Skip to content

Commit 1356950

Browse files
rnrornro
committed
review comments
1 parent 6cb362c commit 1356950

File tree

1 file changed

+87
-87
lines changed

1 file changed

+87
-87
lines changed

‎Sources/GRPCCore/Documentation.docc/Articles/Generating-stubs.md

Lines changed: 87 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -11,16 +11,96 @@ continuing; the [Protocol Buffers website](https://protobuf.dev/) is a great pla
1111
The [`grpc-swift-protobuf`](https://github.com/grpc/grpc-swift-protobuf) package provides
1212
`protoc-gen-grpc-swift`, a program which is a plugin for the Protocol Buffers compiler, `protoc`.
1313

14+
You can use the protoc plugin from the command line directly, or you can make use of a
15+
[Swift Package Manager build plugin](https://github.com/swiftlang/swift-package-manager/blob/main/Documentation/Plugins.md)
16+
convenience which adds the stub generation to the Swift build graph.
17+
You may use the build plugin either from the command line or from Xcode.
18+
19+
1420
> `protoc-gen-grpc-swift` only generates gRPC stubs, it doesn't generate messages. You must use
1521
> `protoc-gen-swift` to generate messages in addition to gRPC Stubs.
1622
17-
The protoc plugin can be used from the command line directly, passed to `protoc`, or
18-
you can make use of a convenience which adds the stub generation to the Swift build graph.
19-
The automatic gRPC Swift stub generation makes use of a [Swift Package Manager build plugin](
20-
https://github.com/swiftlang/swift-package-manager/blob/main/Documentation/Plugins.md) to use the
21-
`.proto` files as inputs to the build graph, input them into `protoc` using `protoc-gen-grpc-swift`
22-
and `protoc-gen-swift` as needed, and make the resulting gRPC Swift stubs available to code
23-
against without committing them as source. The build plugin may be invoked either from the command line or from Xcode.
23+
24+
25+
## Using the build plugin
26+
27+
The build plugin (`GRPCProtobufGenerator`) is a great choice for convenient dynamic code generation, however it does come with some limitations.
28+
Because it generates the gRPC Swift stubs as part of the build it has the requirement that `protoc` must be available
29+
at compile time. This requirements means it is not a good fit for library authors who do not have
30+
direct control over this.
31+
32+
The build plugin detects `.proto` files in the source tree and invokes `protoc` once for each file
33+
(caching results and performing the generation as necessary).
34+
35+
### Adoption
36+
You must adopt Swift Package Manager build plugins on a per-target basis by modifying your package manifest
37+
(`Package.swift` file). To do this, declare the grpc-swift-protobuf package as a dependency and add the plugin
38+
to your desired targets.
39+
40+
For example, to make use of the plugin for generating gRPC Swift stubs as part of the
41+
`echo-server` target:
42+
```swift
43+
targets: [
44+
.executableTarget(
45+
name: "echo-server",
46+
dependencies: [
47+
// ...
48+
],
49+
plugins: [
50+
.plugin(name: "GRPCProtobufGenerator", package: "grpc-swift-protobuf")
51+
]
52+
)
53+
]
54+
```
55+
Once this is done you need to ensure that that the `.proto` files to be used for generation
56+
are included in the target's source directory and that you have defined at least one configuration file.
57+
58+
### Configuration
59+
60+
You must provide a configuration file in the directory which encloses all .proto files (in the same directory or a parent).
61+
Configuration files, written in JSON, tell the build plugin about the options used for protoc invocations.
62+
You must name the file grpc-swift-proto-generator-config.json and structure it in the following format:
63+
```json
64+
{
65+
"generate": {
66+
"clients": true,
67+
"servers": true,
68+
"messages": true,
69+
},
70+
"generatedSource": {
71+
"accessLevelOnImports": false,
72+
"accessLevel": "internal",
73+
}
74+
"protoc": {
75+
"executablePath": "/opt/homebrew/bin/protoc"
76+
"importPaths": [
77+
"../directory_1",
78+
],
79+
},
80+
}
81+
```
82+
83+
The options do not need to be specified and each have default values.
84+
85+
| Name | Possible Values | Default | Description |
86+
|----------------------------------------|--------------------------------------------|--------------|-----------------------------------------------------|
87+
| `generate.servers` | `true`, `false` | `true` | Generate server stubs |
88+
| `generate.clients` | `true`, `false` | `true` | Generate client stubs |
89+
| `generate.messages` | `true`, `false` | `true` | Generate message stubs |
90+
| `generatedSource.accessLevelOnImports` | `true`, `false` | `false` | Whether imports should have explicit access levels |
91+
| `generatedSource.accessLevel` | `"public"`, `"package"`, `"internal"` | `"internal"` | Access level for generated stubs |
92+
| `protoc.executablePath` | N/A | null† | Path to the `protoc` executable |
93+
| `protoc.importPaths` | N/A | null‡ | Access level for generated stubs |
94+
95+
† The Swift Package Manager build plugin infrastructure will attempt to discover the executable's location if you don't provide one.
96+
97+
‡ If you don't provide any import paths then the path to the configuration file will be used on a per-source-file basis.
98+
99+
Many of these map to `protoc-gen-grpc-swift` and `protoc-gen-swift` options.
100+
101+
If you require greater flexibility you may specify more than one configuration file.
102+
Configuration files apply to all `.proto` files equal to or below it in the file hierarchy. A configuration file
103+
lower in the file hierarchy supersedes one above it.
24104

25105
### Using protoc
26106

@@ -91,83 +171,3 @@ swift build --product protoc-gen-grpc-swift
91171

92172
This command will build the plugin into `.build/debug` directory. You can get the full path using
93173
`swift build --show-bin-path`.
94-
95-
## Using the build plugin
96-
97-
The build plugin (`GRPCProtobufGenerator`) is a great choice for convenient dynamic code generation, however it does come with some limitations.
98-
Because it generates the gRPC Swift stubs as part of the build it has the requirement that `protoc` must be guaranteed
99-
to be available at compile time. Also because of a limitation of Swift Package Manager build plugins, the plugin
100-
will only be invoked when applied to the source contained in a leaf package, so it is not useful for generating code for
101-
library authors.
102-
103-
The build plugin will detect `.proto` files in the source tree and perform one invocation of `protoc` for each file
104-
(caching results and performing the generation as necessary).
105-
106-
### Adoption
107-
Swift Package Manager build plugins must be adopted on a per-target basis, you can do this by modifying your
108-
package manifest (`Package.swift` file). You will need to declare the `grpc-swift-protobuf` package as a package
109-
dependency and then add the plugin to any desired targets.
110-
111-
For example, to make use of the plugin for generating gRPC Swift stubs as part of the
112-
`plugin-adopter` target:
113-
```swift
114-
targets: [
115-
.executableTarget(
116-
name: "plugin-adopter",
117-
dependencies: [
118-
// ...
119-
],
120-
plugins: [
121-
.plugin(name: "GRPCProtobufGenerator", package: "grpc-swift-protobuf")
122-
]
123-
)
124-
]
125-
```
126-
Once this is done you need to ensure that that the `.proto` files to be used for generation
127-
are included in the target's source directory (below relevant the `Source` directory) and that you have
128-
defined at least one configuration file.
129-
130-
### Configuration
131-
132-
The build plugin requires a configuration file to be present in a directory which encloses all `.proto` files
133-
(in the same directory or a parent).
134-
Configuration files are JSON which tells the build plugin about the options which will be used in the
135-
invocations of `protoc`. Configuration files must be named `grpc-swift-proto-generator-config.json`
136-
and have the following format:
137-
```json
138-
{
139-
"generate": {
140-
"clients": true,
141-
"servers": true,
142-
"messages": true,
143-
},
144-
"generatedSource": {
145-
"accessLevelOnImports": false,
146-
"accessLevel": "internal",
147-
}
148-
"protoc": {
149-
"executablePath": "/opt/homebrew/bin/protoc"
150-
"importPaths": [
151-
"../directory_1",
152-
],
153-
},
154-
}
155-
```
156-
157-
The options do not need to be specified and each have default values.
158-
159-
| Name | Possible Values | Default | Description |
160-
|----------------------------------------|--------------------------------------------|--------------------------------------|----------------------------------------------------------|
161-
| `generate.servers` | `true`, `false` | `True` | Generate server stubs |
162-
| `generate.clients` | `true`, `false` | `True` | Generate client stubs |
163-
| `generate.messages` | `true`, `false` | `True` | Generate message stubs |
164-
| `generatedSource.accessLevelOnImports` | `true`, `false` | `false` | Whether imports should have explicit access levels |
165-
| `generatedSource.accessLevel` | `public`, `package`, `internal` | `internal` | Access level for generated stubs |
166-
| `protoc.executablePath` | N/A | N/A (attempted discovery) | Path to the `protoc` executable |
167-
| `protoc.importPaths` | N/A | Directory containing the config file | Access level for generated stubs |
168-
169-
Many of these map to `protoc-gen-grpc-swift` and `protoc-gen-swift` options.
170-
171-
If you require greater flexibility you may specify more than one configuration file.
172-
Configuration files apply to all `.proto` files equal to or below it in the file hierarchy. A configuration file
173-
lower in the file hierarchy supersedes one above it.

0 commit comments

Comments
 (0)