From b5fc1bf3e215751ab12ddbf34bb6ba4588c07eeb Mon Sep 17 00:00:00 2001 From: George Barnett Date: Fri, 18 Jul 2025 09:19:07 +0100 Subject: [PATCH 1/3] Add more documentation about code generation Motivation: Users (especially new ones) often have issues with generating code. This package provide a number of ways to do this but doesn't do a good job of explaining the pros and cons of each method or how to use each of them. Modifications: - Split up the generating stubs doc into four parts: one article for each method explaining how to use that approach. For the build plugin and protoc the content was more or less directly moves from the existing doc. - Reprurpose the existing generating stubs doc to explain the pros and cons of each approach to make it easier for users to decide. Result: Better docs --- .../Articles/Code-generation-with-protoc.md | 97 +++++++ .../Code-generation-with-the-build-plugin.md | 127 +++++++++ ...Code-generation-with-the-command-plugin.md | 80 ++++++ .../Articles/Generating-stubs.md | 244 +++++------------- .../Documentation.docc/Documentation.md | 8 +- 5 files changed, 382 insertions(+), 174 deletions(-) create mode 100644 Sources/GRPCProtobuf/Documentation.docc/Articles/Code-generation-with-protoc.md create mode 100644 Sources/GRPCProtobuf/Documentation.docc/Articles/Code-generation-with-the-build-plugin.md create mode 100644 Sources/GRPCProtobuf/Documentation.docc/Articles/Code-generation-with-the-command-plugin.md diff --git a/Sources/GRPCProtobuf/Documentation.docc/Articles/Code-generation-with-protoc.md b/Sources/GRPCProtobuf/Documentation.docc/Articles/Code-generation-with-protoc.md new file mode 100644 index 0000000..b6ecf09 --- /dev/null +++ b/Sources/GRPCProtobuf/Documentation.docc/Articles/Code-generation-with-protoc.md @@ -0,0 +1,97 @@ +# Code generation with protoc + +This article describes how to use the Swift Package Manager build plugin to +generate gRPC Swift and Swift Protobuf code from your Protocol Buffers `.proto` files. + +## Overview + +If you've used Protocol Buffers before then generating gRPC Swift stubs should be simple. If you're +unfamiliar with Protocol Buffers then you should get comfortable with the concepts before +continuing; the [Protocol Buffers website](https://protobuf.dev/) is a great place to start. + +If you haven't installed `protoc` yet refer to for +instructions. + +## Using protoc + +The [`grpc-swift-protobuf`](https://github.com/grpc/grpc-swift-protobuf) package provides +`protoc-gen-grpc-swift-2`, a program which is a plugin for the Protocol Buffers compiler, `protoc`. +To generate gRPC stubs for your `.proto` files directly you must run the `protoc` command with +the `--grpc-swift-2_out=` option: + +```console +protoc --grpc-swift-2_out=. my-service.proto +``` + +> `protoc-gen-grpc-swift-2` only generates gRPC stubs, it doesn't generate messages. You must use +> `protoc-gen-swift` to generate messages in addition to gRPC Stubs. + +The presence of `--grpc-swift-2_out` tells `protoc` to use the `protoc-gen-grpc-swift-2` plugin. By +default it'll look for the plugin in your `PATH`. You can also specify the path to the plugin +explicitly: + +```console +protoc --plugin=/path/to/protoc-gen-grpc-swift-2 --grpc-swift-2_out=. my-service.proto +``` + +You can also specify various option the `protoc-gen-grpc-swift-2` via `protoc` using +the `--grpc-swift-2_opt` argument: + +```console +protoc --grpc-swift-2_opt== --grpc-swift-2_out=. +``` + +You can specify multiple options by passing the `--grpc-swift-2_opt` argument multiple times: + +```console +protoc \ + --grpc-swift-2_opt== \ + --grpc-swift-2_opt== \ + --grpc-swift-2_out=. +``` + +### Generator options + +| Name | Possible Values | Default | Description | +|---------------------------|---------------------------------------------|-----------------|----------------------------------------------------------| +| `Visibility` | `Public`, `Package`, `Internal` | `Internal` | Access level for generated stubs | +| `Server` | `True`, `False` | `True` | Generate server stubs | +| `Client` | `True`, `False` | `True` | Generate client stubs | +| `FileNaming` | `FullPath`, `PathToUnderscores`, `DropPath` | `FullPath` | How generated source files should be named. † | +| `ProtoPathModuleMappings` | | | Path to module map `.asciipb` file. ‡ | +| `UseAccessLevelOnImports` | `True`, `False` | `False` | Whether imports should have explicit access levels. | +| `GRPCModuleName` | | `GRPCCore` | The name of the `GRPCCore` module. | +| `GRPCProtobufModuleName` | | `GRPCProtobuf` | The name of the `GRPCProtobuf` module. | +| `SwiftProtobufModuleName` | | `SwiftProtobuf` | The name of the `SwiftProtobuf` module. | +| `Availability` | String, in the form `OS Version` | | Platform availability to use in generated code. § | + +† The `FileNaming` option has three possible values, for an input of `foo/bar/baz.proto` the following +output file will be generated: +- `FullPath`: `foo/bar/baz.grpc.swift`. +- `PathToUnderscores`: `foo_bar_baz.grpc.swift` +- `DropPath`: `baz.grpc.swift` + +‡ The code generator assumes all inputs are generated into the same module, `ProtoPathModuleMappings` +allows you to specify a mapping from `.proto` files to the Swift module they are generated in. This +allows the code generator to add appropriate imports to your generated stubs. This is described in +more detail in the [SwiftProtobuf documentation](https://github.com/apple/swift-protobuf/blob/main/Documentation/PLUGIN.md). + +§ If unspecified the following availability is used: macOS 15, iOS 18, tvOS 18, +watchOS 11, visionOS 2. The `Availability` option may be specified multiple +times, where each value is a space delimited pair of platform and version, e.g. +`Availability=macOS 15.0`. + +### Building the protoc plugin + +> The version of `protoc-gen-grpc-swift-2` you use mustn't be newer than the version of +> the `grpc-swift-protobuf` you're using. + +If your package depends on `grpc-swift-protobuf` then you can get a copy of `protoc-gen-grpc-swift-2` +by building it directly: + +```console +swift build --product protoc-gen-grpc-swift-2 +``` + +This command will build the plugin into `.build/debug` directory. You can get the full path using +`swift build --show-bin-path`. diff --git a/Sources/GRPCProtobuf/Documentation.docc/Articles/Code-generation-with-the-build-plugin.md b/Sources/GRPCProtobuf/Documentation.docc/Articles/Code-generation-with-the-build-plugin.md new file mode 100644 index 0000000..4ee6a5b --- /dev/null +++ b/Sources/GRPCProtobuf/Documentation.docc/Articles/Code-generation-with-the-build-plugin.md @@ -0,0 +1,127 @@ +# Code generation with the build plugin + +This article describes how to use `protoc` to generate stubs for gRPC Swift and +Swift Protobuf from your Protocol Buffers `.proto` files. + +## Overview + +The build plugin (`GRPCProtobufGenerator`) is a great choice for convenient +dynamic code generation, however it does come with some limitations. Because it +generates the gRPC Swift stubs as part of the build it has the requirement that +`protoc` must be available at compile time. This requirement means it is not a +good fit for library authors who do not have direct control over this. + +To learn more about other options for code generation see . + +The build plugin works by detecting `.proto` files in the source tree and +invokes `protoc` once for each file (caching results and performing the +generation as necessary). + +If you haven't installed `protoc` yet refer to for +instructions. + +### Adoption + +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. + +For example, to make use of the plugin for generating gRPC Swift stubs as part +of the `echo-server` target: + +```swift +targets: [ + .executableTarget( + name: "echo-server", + dependencies: [ + // ... + ], + plugins: [ + .plugin( + name: "GRPCProtobufGenerator", + package: "grpc-swift-protobuf" + ) + ] + ) + ] +``` + +Once this is done you need to ensure that the `.proto` files to be used for +generation are included in the target's source directory and that you have +defined a configuration file. + +## Configuration + +You must provide a configuration file named +`grpc-swift-proto-generator-config.json` in the directory which encloses all +`.proto` files (in the same directory as the files or a parent directory). The +configuration file tells the build plugin about the options used for `protoc` +invocations. + +> Warning: +> The name of the config file is important and must match exactly, the +> plugin won't be > applied if it can't find the config file. + +You can use the following as a starting point for your configuration: + +```json +{ + "generate": { + "clients": true, + "servers": true, + "messages": true + } +} +``` + +By default clients, servers, and messages will be generated with the `internal` +access level. + +The full structure of the config file looks like this: + +```json +{ + "generate": { + "clients": true, + "servers": true, + "messages": true + }, + "generatedSource": { + "accessLevelOnImports": false, + "accessLevel": "internal" + }, + "protoc": { + "executablePath": "/opt/homebrew/bin/protoc", + "importPaths": [ + "../directory_1" + ] + } +} +``` + +Each of the options are described below: + +| Name | Possible Values | Default | Description | +|----------------------------------------|--------------------------------------------|--------------|-----------------------------------------------------| +| `generate.servers` | `true`, `false` | `true` | Generate server 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 | +| `protoc.executablePath` | N/A | `null`† | Path to the `protoc` executable | +| `protoc.importPaths` | N/A | `null`‡ | Import paths passed to `protoc` | + +† The Swift Package Manager build plugin infrastructure will attempt to discover +the executable's location if you don't provide one. + +‡ If you don't provide any import paths then the path to the configuration file +will be used on a per-source-file basis. + +Many of these options map to `protoc-gen-grpc-swift-2` and `protoc-gen-swift` +options. + +If you require greater flexibility you may specify more than one configuration +file. Configuration files apply to all `.proto` files equal to or below it in +the file hierarchy. A configuration file lower in the file hierarchy supersedes +one above it. diff --git a/Sources/GRPCProtobuf/Documentation.docc/Articles/Code-generation-with-the-command-plugin.md b/Sources/GRPCProtobuf/Documentation.docc/Articles/Code-generation-with-the-command-plugin.md new file mode 100644 index 0000000..827efb6 --- /dev/null +++ b/Sources/GRPCProtobuf/Documentation.docc/Articles/Code-generation-with-the-command-plugin.md @@ -0,0 +1,80 @@ +# Code generation with generate-grpc-code-from-protos + +This article describes how to use the `generate-grpc-code-from-protos` Swift +Package Manager command plugin to generate gRPC Swift and Swift Protobuf code +from your Protocol Buffers `.proto` files. + +This plugin is particularly useful for: + +- **Manual, on-demand code generation:** When you prefer to explicitly generate + code rather than relying on a build tool plugin. +- **Libraries:** For Swift packages intended as libraries, where generated + source code should be checked into your repository to avoid external `protoc` + dependencies for your library's consumers. + +If you haven't installed `protoc` yet refer to for +instructions. + +## Adding the Plugin to Your Package + +To use `generate-grpc-code-from-protos` your package needs to depend on +`grpc-swift-protobuf`. You **don't** need to add a dependency on each target +like you would for the build plugin. + +## Basic Usage + +Once your package depends on `grpc-swift-protobuf` you can invoke it using: + +```sh +swift package generate-grpc-code-from-protos path/to/YourService.proto path/to/YourMessages.proto +``` + +If you've organised your protos within a single directory then you can +pass the path of the directory as an argument instead, the plugin will find +all `.proto` files nested within that directory: + +```sh +swift package generate-grpc-code-from-protos Protos +``` + +By default the plugin generates code for gRPC servers, clients, and Protobuf +messages into the current working directory. To change where the code is +generated you can specify the `--output-path` option: + + +```sh +swift package generate-grpc-code-from-protos --output-path Sources/Generated -- Protos +``` + +> Important: The "`--`" separates options and inputs passed to the plugin. +> +> Everything after "`--`" is treated as an input (a `.proto` file or a +> directory), everything before "`--`" is treated as an option with a value or +> a flag. If there is no "`--`" then all arguments are treated as input. + +You should now have a basic understanding of how to use the plugin. You can +configure how the code is generated via a number of options, a few commonly used +ones are: +- `--no-client` disables client code generation, +- `--no-server` disables server code generation, +- `--no-messages` disables message code generation, +- `--access-level ` specifies the access level of the generated code, + (`` must be one of "internal", "package", or "public"). + +You can read about other options by referring to the `--help` text: + +```sh +swift package generate-grpc-code-from-protos --help +``` + +### Permissions + +Swift Package Manager command plugins require permission to create files. You'll +be prompted to give `generate-grpc-code-from-protos` permission when running it. +To avoid being prompted you can grant permissions ahead of time by specifying +`--allow-writing-to-package-directory` to the `swift package` command. For +example: + +```sh +swift package --allow-writing-to-package-directory generate-grpc-code-from-protos Protos +``` diff --git a/Sources/GRPCProtobuf/Documentation.docc/Articles/Generating-stubs.md b/Sources/GRPCProtobuf/Documentation.docc/Articles/Generating-stubs.md index 9f1003b..a80f056 100644 --- a/Sources/GRPCProtobuf/Documentation.docc/Articles/Generating-stubs.md +++ b/Sources/GRPCProtobuf/Documentation.docc/Articles/Generating-stubs.md @@ -1,178 +1,76 @@ # Generating stubs -Learn how to generate stubs for gRPC Swift from a service defined using the Protocol Buffers IDL. +Learn about the different options for generating stubs for gRPC Swift. ## Overview -If you've used Protocol Buffers before then generating gRPC Swift stubs should be simple. If you're -unfamiliar with Protocol Buffers then you should get comfortable with the concepts before -continuing; the [Protocol Buffers website](https://protobuf.dev/) is a great place to start. - -You can use the `protoc` plugin from the command line directly, or you can make use of a - [Swift Package Manager build plugin](https://github.com/swiftlang/swift-package-manager/blob/main/Documentation/Plugins.md) -convenience which adds the stub generation to the Swift build graph. -You may use the build plugin either from the command line or from Xcode. - -## Using the build plugin - -The build plugin (`GRPCProtobufGenerator`) is a great choice for convenient dynamic code generation, however it does come with some limitations. -Because it generates the gRPC Swift stubs as part of the build it has the requirement that `protoc` must be available -at compile time. This requirement means it is not a good fit for library authors who do not have -direct control over this. - -The build plugin detects `.proto` files in the source tree and invokes `protoc` once for each file -(caching results and performing the generation as necessary). - -### Adoption -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. - -For example, to make use of the plugin for generating gRPC Swift stubs as part of the -`echo-server` target: -```swift -targets: [ - .executableTarget( - name: "echo-server", - dependencies: [ - // ... - ], - plugins: [ - .plugin(name: "GRPCProtobufGenerator", package: "grpc-swift-protobuf") - ] - ) - ] -``` -Once this is done you need to ensure that the `.proto` files to be used for generation -are included in the target's source directory and that you have defined at least one configuration file. - -### Configuration - -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: -```json -{ - "generate": { - "clients": true, - "servers": true, - "messages": true - }, - "generatedSource": { - "accessLevelOnImports": false, - "accessLevel": "internal" - }, - "protoc": { - "executablePath": "/opt/homebrew/bin/protoc", - "importPaths": [ - "../directory_1" - ] - } -} -``` - -The options do not need to be specified and each have default values. - -| Name | Possible Values | Default | Description | -|----------------------------------------|--------------------------------------------|--------------|-----------------------------------------------------| -| `generate.servers` | `true`, `false` | `true` | Generate server 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 | -| `protoc.executablePath` | N/A | `null`† | Path to the `protoc` executable | -| `protoc.importPaths` | N/A | `null`‡ | Import paths passed to `protoc` | - -† The Swift Package Manager build plugin infrastructure will attempt to discover the executable's location if you don't provide one. - -‡ If you don't provide any import paths then the path to the configuration file will be used on a per-source-file basis. - -Many of these options map to `protoc-gen-grpc-swift-2` and `protoc-gen-swift` options. - -If you require greater flexibility you may specify more than one configuration file. -Configuration files apply to all `.proto` files equal to or below it in the file hierarchy. A configuration file -lower in the file hierarchy supersedes one above it. - -### Using protoc - -The [`grpc-swift-protobuf`](https://github.com/grpc/grpc-swift-protobuf) package provides -`protoc-gen-grpc-swift-2`, a program which is a plugin for the Protocol Buffers compiler, `protoc`. -To generate gRPC stubs for your `.proto` files directly you must run the `protoc` command with -the `--grpc-swift-2_out=` option: - -```console -protoc --grpc-swift-2_out=. my-service.proto -``` - -> `protoc-gen-grpc-swift-2` only generates gRPC stubs, it doesn't generate messages. You must use -> `protoc-gen-swift` to generate messages in addition to gRPC Stubs. - -The presence of `--grpc-swift-2_out` tells `protoc` to use the `protoc-gen-grpc-swift-2` plugin. By -default it'll look for the plugin in your `PATH`. You can also specify the path to the plugin -explicitly: - -```console -protoc --plugin=/path/to/protoc-gen-grpc-swift-2 --grpc-swift-2_out=. my-service.proto -``` - -You can also specify various option the `protoc-gen-grpc-swift-2` via `protoc` using -the `--grpc-swift-2_opt` argument: - -```console -protoc --grpc-swift-2_opt== --grpc-swift-2_out=. -``` - -You can specify multiple options by passing the `--grpc-swift-2_opt` argument multiple times: - -```console -protoc \ - --grpc-swift-2_opt== \ - --grpc-swift-2_opt== \ - --grpc-swift-2_out=. -``` - -#### Generator options - -| Name | Possible Values | Default | Description | -|---------------------------|---------------------------------------------|-----------------|----------------------------------------------------------| -| `Visibility` | `Public`, `Package`, `Internal` | `Internal` | Access level for generated stubs | -| `Server` | `True`, `False` | `True` | Generate server stubs | -| `Client` | `True`, `False` | `True` | Generate client stubs | -| `FileNaming` | `FullPath`, `PathToUnderscores`, `DropPath` | `FullPath` | How generated source files should be named. † | -| `ProtoPathModuleMappings` | | | Path to module map `.asciipb` file. ‡ | -| `UseAccessLevelOnImports` | `True`, `False` | `False` | Whether imports should have explicit access levels. | -| `GRPCModuleName` | | `GRPCCore` | The name of the `GRPCCore` module. | -| `GRPCProtobufModuleName` | | `GRPCProtobuf` | The name of the `GRPCProtobuf` module. | -| `SwiftProtobufModuleName` | | `SwiftProtobuf` | The name of the `SwiftProtobuf` module. | -| `Availability` | String, in the form `OS Version` | | Platform availability to use in generated code. § | - -† The `FileNaming` option has three possible values, for an input of `foo/bar/baz.proto` the following -output file will be generated: -- `FullPath`: `foo/bar/baz.grpc.swift`. -- `PathToUnderscores`: `foo_bar_baz.grpc.swift` -- `DropPath`: `baz.grpc.swift` - -‡ The code generator assumes all inputs are generated into the same module, `ProtoPathModuleMappings` -allows you to specify a mapping from `.proto` files to the Swift module they are generated in. This -allows the code generator to add appropriate imports to your generated stubs. This is described in -more detail in the [SwiftProtobuf documentation](https://github.com/apple/swift-protobuf/blob/main/Documentation/PLUGIN.md). - -§ If unspecified the following availability is used: macOS 15, iOS 18, tvOS 18, -watchOS 11, visionOS 2. The `Availability` option may be specified multiple -times, where each value is a space delimited pair of platform and version, e.g. -`Availability=macOS 15.0`. - -#### Building the protoc plugin - -> The version of `protoc-gen-grpc-swift-2` you use mustn't be newer than the version of -> the `grpc-swift-protobuf` you're using. - -If your package depends on `grpc-swift-protobuf` then you can get a copy of `protoc-gen-grpc-swift-2` -by building it directly: - -```console -swift build --product protoc-gen-grpc-swift-2 -``` - -This command will build the plugin into `.build/debug` directory. You can get the full path using -`swift build --show-bin-path`. +There are three primary approaches to generate stubs for your gRPC Swift +project: + +1. **Using `protoc` from the command line:** This is a common method for those + familiar with gRPC or Protocol Buffers. It requires directly invoking + `protoc` along with the gRPC Swift and Swift Protobuf plugins. See + also . +2. **Using a helper CLI provided by this package:** This tool, + `generate-grpc-code-from-protos`, simplifies the + process by wrapping protoc. It handles the building and locating of `protoc` + plugins for you, and exposes various generation options as command-line + arguments. +3. **Using a Swift Package Manager build plugin:** This approach integrates stub + generation directly into your project's build graph, generating stubs + automatically at build time. See for + more information. + +## Deciding Which Approach to Take + +Each method has its own trade-offs. This section will help you choose the best +approach for your specific use case. + +### For Applications (self-contained packages) + +If you are building an **application** (meaning no other packages will depend on +yours), you **may** use the Swift Package Manager build plugin. + +- **Pros:** Stubs are generated as part of your package's build process, + eliminating the need for manual generation steps. +- **Cons:** The `protoc` binary must be available in all environments where + you build your package, including continuous integration (CI) systems. + +### For Libraries (dependent packages) + +If you are building a **library** (a package that other packages will depend +on), you **must not** use the build plugin. + +- **Reason:** You cannot guarantee that consumers of your library will have + protoc available in their build environments. +- **Recommended Approach:** Instead, you must generate stubs out-of-band using + either: + - `protoc` directly from the command line, or + - The helper CLI tool offered by this package. +- **Requirement:** The generated code must then be included directly with the + source files of your library package. + +### The CLI Tool + +The `generate-grpc-code-from-protos` tool is designed to be a simpler and more +user-friendly alternative to invoking `protoc` directly. It automates the process +of building the necessary gRPC and Protobuf plugins for `protoc` and provides +a simpler interface for configuring generation options. It is often the most +convenient way to generate code for your gRPC project. + +### Summary and Next Steps + +This table summarizes the three different approaches: + +| | `protoc` | `generate-grpc-code-from-protos` | Build Plugin +|-----------------------------------|----------|----------------------------------|-------------- +| Suitable for libraries | ✓ | ✓ | ✗ +| Suitable for applications | ✗ | ✗ | ✓ +| Builds plugins for you | ✗ | ✓ | ✓ +| Generated at build time | ✗ | ✗ | ✓ +| Generated code must be checked in | ✓ | ✓ | ✗ + +You can learn more about each approach in: +- +- +- diff --git a/Sources/GRPCProtobuf/Documentation.docc/Documentation.md b/Sources/GRPCProtobuf/Documentation.docc/Documentation.md index f3fb528..fa0180c 100644 --- a/Sources/GRPCProtobuf/Documentation.docc/Documentation.md +++ b/Sources/GRPCProtobuf/Documentation.docc/Documentation.md @@ -17,10 +17,16 @@ This package provides three products: ## Topics -### Essentials +### Generating code - - +- +- +- + +### Generated code + - - - From 14a198af368e7162d22a7a66a9a40d90e844dc76 Mon Sep 17 00:00:00 2001 From: George Barnett Date: Fri, 8 Aug 2025 18:04:32 +0100 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Gus Cairo --- .../Articles/Code-generation-with-the-build-plugin.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Sources/GRPCProtobuf/Documentation.docc/Articles/Code-generation-with-the-build-plugin.md b/Sources/GRPCProtobuf/Documentation.docc/Articles/Code-generation-with-the-build-plugin.md index 4ee6a5b..98042a6 100644 --- a/Sources/GRPCProtobuf/Documentation.docc/Articles/Code-generation-with-the-build-plugin.md +++ b/Sources/GRPCProtobuf/Documentation.docc/Articles/Code-generation-with-the-build-plugin.md @@ -61,7 +61,7 @@ invocations. > Warning: > The name of the config file is important and must match exactly, the -> plugin won't be > applied if it can't find the config file. +> plugin won't be applied if it can't find the config file. You can use the following as a starting point for your configuration: From 9943c820343b98ac0f2eb4386f300e67f48e5d9c Mon Sep 17 00:00:00 2001 From: George Barnett Date: Fri, 8 Aug 2025 18:04:58 +0100 Subject: [PATCH 3/3] Apply suggestions from code review --- .../Articles/Code-generation-with-protoc.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Sources/GRPCProtobuf/Documentation.docc/Articles/Code-generation-with-protoc.md b/Sources/GRPCProtobuf/Documentation.docc/Articles/Code-generation-with-protoc.md index b6ecf09..7a7d9dc 100644 --- a/Sources/GRPCProtobuf/Documentation.docc/Articles/Code-generation-with-protoc.md +++ b/Sources/GRPCProtobuf/Documentation.docc/Articles/Code-generation-with-protoc.md @@ -34,14 +34,14 @@ explicitly: protoc --plugin=/path/to/protoc-gen-grpc-swift-2 --grpc-swift-2_out=. my-service.proto ``` -You can also specify various option the `protoc-gen-grpc-swift-2` via `protoc` using +You can specify various options to `protoc-gen-grpc-swift-2` via `protoc` using the `--grpc-swift-2_opt` argument: ```console protoc --grpc-swift-2_opt== --grpc-swift-2_out=. ``` -You can specify multiple options by passing the `--grpc-swift-2_opt` argument multiple times: +You can specify multiple options by repeating the `--grpc-swift-2_opt` argument: ```console protoc \