Document use of the build plugin #2176
Conversation
Motivation: To ease use of the `grpc-swift-protobuf` Swift Package Manager build plugin. Modifications: Documentation added. Result: Greater understanding?
| The protoc plugin can be used from the command line directly, passed to `protoc`, or | ||
| you can make use of a convenience which adds the stub generation to the Swift build graph. | ||
| The automatic gRPC Swift stub generation makes use of a [Swift Package Manager build plugin]( | ||
| https://github.com/swiftlang/swift-package-manager/blob/main/Documentation/Plugins.md) to use the | ||
| `.proto` files as inputs to the build graph, input them into `protoc` using `protoc-gen-grpc-swift` | ||
| and `protoc-gen-swift` as needed, and make the resulting gRPC Swift stubs available to code | ||
| against without committing them as source. The build plugin may be invoked either from the command line or from Xcode. |
There was a problem hiding this comment.
I think we should pull this further up (so that it's the second paragraph) and make it more concise. We can then expand in each section. I'd like it so that the overview is like a landing page; you're giving the reader a brief introduction and then giving them a choice (manual generation with protoc vs. automated with build plugin.)
To that end it might be worth swapping the two around and having the build plugin first (progressive disclosure?).
| to be available at compile time. Also because of a limitation of Swift Package Manager build plugins, the plugin | ||
| will only be invoked when applied to the source contained in a leaf package, so it is not useful for generating code for | ||
| library authors. |
There was a problem hiding this comment.
This isn't actually true. The reason you can't use this build plugin in non-leaf packages is that it forces an implicit build time dependency on protoc which might not always be available.
There was a problem hiding this comment.
Ah, thanks for pointing that out! I'll have to refresh my knowledge of the docs.
| Because it generates the gRPC Swift stubs as part of the build it has the requirement that `protoc` must be guaranteed | ||
| to be available at compile time. Also because of a limitation of Swift Package Manager build plugins, the plugin |
There was a problem hiding this comment.
"must" and "guaranteed" are both requirements, let's get rid of one
| Because it generates the gRPC Swift stubs as part of the build it has the requirement that `protoc` must be guaranteed | |
| to be available at compile time. Also because of a limitation of Swift Package Manager build plugins, the plugin | |
| Because it generates the gRPC Swift stubs as part of the build it has the requirement that `protoc` must be available at compile time. Also because of a limitation of Swift Package Manager build plugins, the plugin |
| The build plugin will detect `.proto` files in the source tree and perform one invocation of `protoc` for each file | ||
| (caching results and performing the generation as necessary). |
There was a problem hiding this comment.
Try to write in the active voice, e.g. "The build plugin detects .proto files in the source tree and invokes protoc once for each file."
| Swift Package Manager build plugins must be adopted on a per-target basis, you can do this by modifying your | ||
| package manifest (`Package.swift` file). You will need to declare the `grpc-swift-protobuf` package as a package | ||
| dependency and then add the plugin to any desired targets. |
There was a problem hiding this comment.
nit: active voice
"You must adopt Swift Package Manager build plugins on a per-target basis by modifying your package manifest (Package.swift file). To do this, declare the grpc-swift-protobuf package as a dependency and add the plugin to your desired targets.
| "messages": true, | ||
| }, | ||
| "generatedSource": { | ||
| "accessLevelOnImports": false, |
There was a problem hiding this comment.
Forgot to mention that this change never actually got made, the config is still using useAccessLevelOnImports. I can fix that up though.
There was a problem hiding this comment.
| | `generate.servers` | `true`, `false` | `True` | Generate server stubs | | ||
| | `generate.clients` | `true`, `false` | `True` | Generate client stubs | | ||
| | `generate.messages` | `true`, `false` | `True` | Generate message stubs | |
There was a problem hiding this comment.
| | `generate.servers` | `true`, `false` | `True` | Generate server stubs | | |
| | `generate.clients` | `true`, `false` | `True` | Generate client stubs | | |
| | `generate.messages` | `true`, `false` | `True` | Generate message stubs | | |
| | `generate.servers` | `true`, `false` | `true` | Generate server stubs | | |
| | `generate.clients` | `true`, `false` | `true` | Generate client stubs | | |
| | `generate.messages` | `true`, `false` | `true` | Generate message stubs | |
| | `generate.clients` | `true`, `false` | `True` | Generate client stubs | | ||
| | `generate.messages` | `true`, `false` | `True` | Generate message stubs | | ||
| | `generatedSource.accessLevelOnImports` | `true`, `false` | `false` | Whether imports should have explicit access levels | | ||
| | `generatedSource.accessLevel` | `public`, `package`, `internal` | `internal` | Access level for generated stubs | |
There was a problem hiding this comment.
Because we're describing JSON, these should be strings
| | `generatedSource.accessLevel` | `public`, `package`, `internal` | `internal` | Access level for generated stubs | | |
| | `generatedSource.accessLevel` | `"public"`, `"package"`, `"internal"` | `"internal"` | Access level for generated stubs | |
| | `generate.messages` | `true`, `false` | `True` | Generate message stubs | | ||
| | `generatedSource.accessLevelOnImports` | `true`, `false` | `false` | Whether imports should have explicit access levels | | ||
| | `generatedSource.accessLevel` | `public`, `package`, `internal` | `internal` | Access level for generated stubs | | ||
| | `protoc.executablePath` | N/A | N/A (attempted discovery) | Path to the `protoc` executable | |
There was a problem hiding this comment.
Because it's JSON the default is null, but that has meaning which we should describe
| | `protoc.executablePath` | N/A | N/A (attempted discovery) | Path to the `protoc` executable | | |
| | `protoc.executablePath` | N/A | null | |
| | Path to the `protoc` executable. Autodetected if the `null`. | |
| | `generatedSource.accessLevelOnImports` | `true`, `false` | `false` | Whether imports should have explicit access levels | | ||
| | `generatedSource.accessLevel` | `public`, `package`, `internal` | `internal` | Access level for generated stubs | | ||
| | `protoc.executablePath` | N/A | N/A (attempted discovery) | Path to the `protoc` executable | | ||
| | `protoc.importPaths` | N/A | Directory containing the config file | Access level for generated stubs | |
There was a problem hiding this comment.
The description is wrong here. Also like above we put the default as null and explain that the directory of the config file is used if null.
rnro
force-pushed
the
grpc-swift-protobuf_plugin_docs
branch
from
1356950 to
9e70d5c
Compare
| The [`grpc-swift-protobuf`](https://github.com/grpc/grpc-swift-protobuf) package provides | ||
| `protoc-gen-grpc-swift`, a program which is a plugin for the Protocol Buffers compiler, `protoc`. |
There was a problem hiding this comment.
I think this should be in the first paragraph in ### Using protoc section
|
|
||
| > `protoc-gen-grpc-swift` only generates gRPC stubs, it doesn't generate messages. You must use | ||
| > `protoc-gen-swift` to generate messages in addition to gRPC Stubs. |
There was a problem hiding this comment.
I think this should be in the second paragraph in ### Using protoc section
Sources/GRPCCore/Documentation.docc/Articles/Generating-stubs.md
Outdated
Show resolved
Hide resolved
Sources/GRPCCore/Documentation.docc/Articles/Generating-stubs.md
Outdated
Show resolved
Hide resolved
|
|
||
| You must provide a configuration file in the directory which encloses all .proto files (in the same directory or a parent). | ||
| Configuration files, written in JSON, tell the build plugin about the options used for protoc invocations. | ||
| You must name the file grpc-swift-proto-generator-config.json and structure it in the following format: |
There was a problem hiding this comment.
| You must name the file grpc-swift-proto-generator-config.json and structure it in the following format: | |
| You must name the file `grpc-swift-proto-generator-config.json` and structure it in the following format: |
Sources/GRPCCore/Documentation.docc/Articles/Generating-stubs.md
Outdated
Show resolved
Hide resolved
Co-authored-by: George Barnett <gbarnett@apple.com>
Co-authored-by: George Barnett <gbarnett@apple.com>
Co-authored-by: George Barnett <gbarnett@apple.com>
Sources/GRPCCore/Documentation.docc/Articles/Generating-stubs.md
Outdated
Show resolved
Hide resolved
Sources/GRPCCore/Documentation.docc/Articles/Generating-stubs.md
Outdated
Show resolved
Hide resolved
Sources/GRPCCore/Documentation.docc/Articles/Generating-stubs.md
Outdated
Show resolved
Hide resolved
Motivation:
To ease use of the
grpc-swift-protobufSwift Package Manager build plugin.Modifications:
Documentation added.
Result:
Greater understanding?