Skip to content

Commit 3af0ce5

Browse files
committed
Update docs
1 parent e31b63b commit 3af0ce5

File tree

1 file changed

+20
-19
lines changed

1 file changed

+20
-19
lines changed

Sources/protoc-gen-grpc-swift/Docs.docc/spm-plugin.md

+20-19
Original file line numberDiff line numberDiff line change
@@ -22,18 +22,8 @@ There are multiple ways to do this. Some of the easiest are:
2222
1. If you are on macOS, installing it via `brew install protobuf`
2323
2. Download the binary from [Google's github repository](https://github.com/protocolbuffers/protobuf).
2424

25-
### Adding the proto files to your target
26-
27-
Next, you need to add the `.proto` files for which you want to generate your Swift types to your target's
28-
source directory. You should also commit these files to your git repository since the generated types
29-
are now generated on demand.
30-
31-
> Note: imports on your `.proto` files will have to include the relative path from the target source to the `.proto` file you wish to import.
32-
> Files **must** be contained within the target source directory.
33-
3425
### Adding the plugin to your manifest
3526

36-
After adding the `.proto` files you can now add the plugin to the target inside your `Package.swift` manifest.
3727
First, you need to add a dependency on `grpc-swift`. Afterwards, you can declare the usage of the plugin
3828
for your target. Here is an example snippet of a `Package.swift` manifest:
3929

@@ -61,23 +51,33 @@ let package = Package(
6151

6252
### Configuring the plugin
6353

64-
Lastly, after you have added the `.proto` files and modified your `Package.swift` manifest, you can now
65-
configure the plugin to invoke the `protoc` compiler. This is done by adding a `grpc-swift-config.json`
66-
to the root of your target's source folder. An example configuration file looks like this:
54+
Configuring the plugin is done by adding a `grpc-swift-config.json` file anywhere in your target's sources. Before you start configuring the plugin, you need to add the `.proto` files to your sources. You should also commit these files to your git repository since the generated types are now generated on demand. It's also important to note that the proto files in your configuration should be in the same directory as the config file. Let's see an example to have a better understanding.
55+
56+
Here's an example file structure that looks like this:
57+
58+
```text
59+
Sources
60+
├── main.swift
61+
├── ProtoBuf
62+
├── grpc-swift-config.json
63+
├── foo.proto
64+
└── Bar
65+
└── Bar.proto
66+
```
6767

6868
```json
6969
{
7070
"invocations": [
7171
{
7272
"protoFiles": [
73-
"Path/To/Foo.proto",
73+
"Foo.proto",
7474
],
7575
"visibility": "internal",
7676
"server": false
7777
},
7878
{
7979
"protoFiles": [
80-
"Bar.proto"
80+
"Bar/Bar.proto"
8181
],
8282
"visibility": "public",
8383
"client": false,
@@ -87,11 +87,12 @@ to the root of your target's source folder. An example configuration file looks
8787
}
8888
```
8989

90-
> Note: paths to your `.proto` files will have to include the relative path from the target source to the `.proto` file location.
91-
> Files **must** be contained within the target source directory.
90+
> Note: paths to your `.proto` files will have to include the relative path from the config file directory to the `.proto` file location.
91+
> Files **must** be contained within the same directory as the config file.
9292
93-
In the above configuration, you declared two invocations to the `protoc` compiler. The first invocation
94-
is generating Swift types for the `Foo.proto` file with `internal` visibility. Notice the relative path to the `.proto` file.
93+
In the above configuration, notice the relative path of the `.proto` file with respect to the configuration file. If you add a file in the `Sources` folder, the plugin would be unable to access it as the path is computed relative to the `grpc-swift-config.json` file. So the `.proto` files have to be added within the `ProtoBuf` folder, with relative paths taken into consideration.
94+
Here, you declared two invocations to the `protoc` compiler. The first invocation
95+
is generating Swift types for the `Foo.proto` file with `internal` visibility.
9596
We have also specified the `server` option and set it to false: this means that server code won't be generated for this proto.
9697
The second invocation is generating Swift types for the `Bar.proto` file with the `public` visibility.
9798
Notice the `client` option: it's been set to false, so no client code will be generated for this proto. We have also set

0 commit comments

Comments
 (0)