Update Example READMEs (#2179)

Motivation: The examples now use the Swift PM build plugin but the READMEs weren't updated to include the PROTOC_PATH. Modifications: - update READMEs Result: Better examples
grpc · Jan 24, 2025 · bfe033f · bfe033f
1 parent 4c6357d
commit bfe033f
Show file tree

Hide file tree

Showing 5 changed files with 70 additions and 10 deletions.
diff --git a/Examples/echo/README.md b/Examples/echo/README.md
@@ -12,27 +12,36 @@ the four RPC types.
 The tool uses the [SwiftNIO](https://github.com/grpc/grpc-swift-nio-transport)
 HTTP/2 transport.
 
+## Prerequisites
+
+You must have the Protocol Buffers compiler (`protoc`) installed. You can find
+the instructions for doing this in the [gRPC Swift Protobuf documentation][0].
+The `swift` commands below are all prefixed with `PROTOC_PATH=$(which protoc)`,
+this is to let the build system know where `protoc` is located so that it can
+generate stubs for you. You can read more about it in the [gRPC Swift Protobuf
+documentation][1].
+
 ## Usage
 
 Build and run the server using the CLI:
 
 ```console
-$ swift run echo serve
+$ PROTOC_PATH=$(which protoc) swift run echo serve
 Echo listening on [ipv4]127.0.0.1:1234
 ```
 
 Use the CLI to make a unary 'Get' request against it:
 
 ```console
-$ swift run echo get --message "Hello"
+$ PROTOC_PATH=$(which protoc) swift run echo get --message "Hello"
 get → Hello
 get ← Hello
 ```
 
 Use the CLI to make a bidirectional streaming 'Update' request:
 
 ```console
-$ swift run echo update --message "Hello World"
+$ PROTOC_PATH=$(which protoc) swift run echo update --message "Hello World"
 update → Hello
 update → World
 update ← Hello
@@ -42,5 +51,8 @@ update ← World
 Get help with the CLI by running:
 
 ```console
-$ swift run echo --help
+$ PROTOC_PATH=$(which protoc) swift run echo --help
 ```
+
+[0]: https://swiftpackageindex.com/grpc/grpc-swift-protobuf/documentation/grpcprotobuf/installing-protoc
+[1]: https://swiftpackageindex.com/grpc/grpc-swift-protobuf/documentation/grpcprotobuf/generating-stubs
diff --git a/Examples/error-details/README.md b/Examples/error-details/README.md
@@ -10,12 +10,21 @@ described in more detailed in the [gRPC Error
 Guide](https://grpc.io/docs/guides/error/) and is made available via the
 [grpc-swift-protobuf](https://github.com/grpc-swift-protobuf) package.
 
+## Prerequisites
+
+You must have the Protocol Buffers compiler (`protoc`) installed. You can find
+the instructions for doing this in the [gRPC Swift Protobuf documentation][0].
+The `swift` commands below are all prefixed with `PROTOC_PATH=$(which protoc)`,
+this is to let the build system know where `protoc` is located so that it can
+generate stubs for you. You can read more about it in the [gRPC Swift Protobuf
+documentation][1].
+
 ## Usage
 
 Build and run the example using the CLI:
 
 ```console
-$ swift run
+$ PROTOC_PATH=$(which protoc) swift run
 Error code: resourceExhausted
 Error message: The greeter has temporarily run out of greetings.
 Error details:
@@ -24,3 +33,6 @@ Error details:
 - Help links:
    - https://en.wikipedia.org/wiki/Caffeine (A Wikipedia page about caffeine including its properties and effects.)
 ```
+
+[0]: https://swiftpackageindex.com/grpc/grpc-swift-protobuf/documentation/grpcprotobuf/installing-protoc
+[1]: https://swiftpackageindex.com/grpc/grpc-swift-protobuf/documentation/grpcprotobuf/generating-stubs
diff --git a/Examples/hello-world/README.md b/Examples/hello-world/README.md
@@ -10,25 +10,37 @@ service which allows you to start a server and to make requests against it.
 The tool uses the [SwiftNIO](https://github.com/grpc/grpc-swift-nio-transport)
 HTTP/2 transport.
 
+## Prerequisites
+
+You must have the Protocol Buffers compiler (`protoc`) installed. You can find
+the instructions for doing this in the [gRPC Swift Protobuf documentation][0].
+The `swift` commands below are all prefixed with `PROTOC_PATH=$(which protoc)`,
+this is to let the build system know where `protoc` is located so that it can
+generate stubs for you. You can read more about it in the [gRPC Swift Protobuf
+documentation][1].
+
 ## Usage
 
 Build and run the server using the CLI:
 
 ```console
-$ swift run hello-world serve
+$ PROTOC_PATH=$(which protoc) swift run hello-world serve
 Greeter listening on [ipv4]127.0.0.1:31415
 ```
 
 Use the CLI to send a request to the service:
 
 ```console
-$ swift run hello-world greet
+$ PROTOC_PATH=$(which protoc) swift run hello-world greet
 Hello, stranger
 ```
 
 Send the name of the greetee in the request by specifying a `--name`:
 
 ```console
-$ swift run hello-world greet --name "PanCakes 🐶"
+$ PROTOC_PATH=$(which protoc) swift run hello-world greet --name "PanCakes 🐶"
 Hello, PanCakes 🐶
 ```
+
+[0]: https://swiftpackageindex.com/grpc/grpc-swift-protobuf/documentation/grpcprotobuf/installing-protoc
+[1]: https://swiftpackageindex.com/grpc/grpc-swift-protobuf/documentation/grpcprotobuf/generating-stubs
diff --git a/Examples/reflection-server/README.md b/Examples/reflection-server/README.md
@@ -23,6 +23,15 @@ protoc --descriptor_set_out=path/to/output.pb path/to/input.proto \
   --include_imports
 ```
 
+## Prerequisites
+
+You must have the Protocol Buffers compiler (`protoc`) installed. You can find
+the instructions for doing this in the [gRPC Swift Protobuf documentation][0].
+The `swift` commands below are all prefixed with `PROTOC_PATH=$(which protoc)`,
+this is to let the build system know where `protoc` is located so that it can
+generate stubs for you. You can read more about it in the [gRPC Swift Protobuf
+documentation][1].
+
 ## Usage
 
 Build and run the server using the CLI:
@@ -59,3 +68,6 @@ $ grpcurl -plaintext -d '{ "text": "Hello" }' 127.0.0.1:31415 echo.Echo.Get
   "text": "Hello"
 }
 ```
+
+[0]: https://swiftpackageindex.com/grpc/grpc-swift-protobuf/documentation/grpcprotobuf/installing-protoc
+[1]: https://swiftpackageindex.com/grpc/grpc-swift-protobuf/documentation/grpcprotobuf/generating-stubs
diff --git a/Examples/route-guide/README.md b/Examples/route-guide/README.md
@@ -15,19 +15,28 @@ HTTP/2 transport.
 This example has an accompanying tutorial hosted on the [Swift Package
 Index](https://swiftpackageindex.com/grpc/grpc-swift/main/tutorials/grpccore/route-guide).
 
+## Prerequisites
+
+You must have the Protocol Buffers compiler (`protoc`) installed. You can find
+the instructions for doing this in the [gRPC Swift Protobuf documentation][0].
+The `swift` commands below are all prefixed with `PROTOC_PATH=$(which protoc)`,
+this is to let the build system know where `protoc` is located so that it can
+generate stubs for you. You can read more about it in the [gRPC Swift Protobuf
+documentation][1].
+
 ## Usage
 
 Build and run the server using the CLI:
 
 ```console
-$ swift run route-guide serve
+$ PROTOC_PATH=$(which protoc) swift run route-guide serve
 server listening on [ipv4]127.0.0.1:31415
 ```
 
 Use the CLI to interrogate the different RPCs you can call:
 
 ```console
-$ swift run route-guide --help
+$ PROTOC_PATH=$(which protoc) swift run route-guide --help
 USAGE: route-guide <subcommand>
 
 OPTIONS:
@@ -42,3 +51,6 @@ SUBCOMMANDS:
 
   See 'route-guide help <subcommand>' for detailed help.
 ```
+
+[0]: https://swiftpackageindex.com/grpc/grpc-swift-protobuf/documentation/grpcprotobuf/installing-protoc
+[1]: https://swiftpackageindex.com/grpc/grpc-swift-protobuf/documentation/grpcprotobuf/generating-stubs