You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+61Lines changed: 61 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,6 +13,67 @@ External plugins are separate processes and use
13
13
14
14
KMS communicates with plugins over gRPC. As such, the various interfaces are defined via gRPC service definitions.
15
15
16
+
## Pre-requisites
17
+
18
+
Several tools are required to generate the code:
19
+
20
+
1.**`protoc compiler`**: see the instruction on the official [web site](https://protobuf.dev/installation) or install using homebrew `brew install protobuf`.
21
+
2.**`protoc-gen-go`**: install via `go install google.golang.org/protobuf/cmd/protoc-gen-go@latest`.
22
+
3.**`protoc-gen-go-grpc`**: install via `go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest`.
23
+
4.**`protoc-gen-grpc-gateway`**: install via `go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway`.
24
+
5.**`protoc-gen-openapiv2`**: install via `go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2`.
25
+
6.**`protofetch`**: download from the [releases page](https://github.com/coralogix/protofetch/releases/latest) of [the GitHub repository](https://github.com/coralogix/protofetch) or install via `cargo install protofetch` or `npm install -g @coralogix/protofetch`, or using any similar tool compatible with the npm registry.
26
+
27
+
## Optional tools
28
+
29
+
Optionally, the [`buf` CLI](https://github.com/bufbuild/buf) tool can be used to validate, detect breaking changes, and format `.proto` files:
30
+
31
+
-**`buf breaking --against https://github.com/openkcm/api-sdk.git#branch=main`**: detect breaking changes against the main branch of the remote repository.
32
+
-**`buf format -w`**: format `.proto` files.
33
+
-**`buf lint`**: lint `.proto` files.
34
+
35
+
## Makefile
36
+
37
+
There are several `make` targets defined in the `Makefile`:
38
+
39
+
-**`fetch-protos`**: download `.proto` dependencies using `protofetch`.
40
+
-**`generate`**: fetches `.proto` dependencies, formats `.proto` files, and generates Go code.
41
+
-**`install-proto-tools`**: installs the tools (including optional) from the following sources: Homebrew, Go registry (via `go install`), NPM registry (via `npm install -g`). See the target definition for the details.
42
+
-**`validate-proto`**: formats and lints `.proto` files, detects breaking changes.
43
+
44
+
For the rest `make` targets see `Makefile`.
45
+
46
+
## Dependencies
47
+
48
+
`.proto` dependencies are managed with the [`protofetch`](https://github.com/coralogix/protofetch) tool. This tool downloads `.proto` files from a specified location of a git repository and places them into the `vendor-proto` directory. The dependencies are specified in the `protofetch.toml` file.
49
+
50
+
For instance, a dependency on the [`protovalidate`](https://github.com/bufbuild/protovalidate) proto definitions can be specified as follow:
51
+
52
+
```toml
53
+
name = "github.com/openkcm/plugin-sdk"
54
+
description = "Plugins SDK of the OpenKCM project"
55
+
56
+
[protovalidate]
57
+
url = "github.com/bufbuild/protovalidate"
58
+
revision = "v1.1.1"
59
+
content_roots = ["/proto/protovalidate"]
60
+
allow_policies = ["buf/validate/*"]
61
+
```
62
+
63
+
In order to fetch dependencies, execute:
64
+
65
+
```sh
66
+
$ protofetch -o vendor-proto fetch
67
+
```
68
+
69
+
## Generate Go code from the .proto definitions
70
+
71
+
The code can be generated with executing the following Make target
72
+
73
+
```sh
74
+
$ make generate
75
+
```
76
+
16
77
## Support, Feedback, Contributing
17
78
18
79
This project is open to feature requests/suggestions, bug reports etc. via [GitHub issues](https://github.com/openkcm/plugin-sdk/issues). Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our [Contribution Guidelines](CONTRIBUTING.md).
0 commit comments