From 5e4ea5676d77ba5ddf4b50fbcf4482af4d04b029 Mon Sep 17 00:00:00 2001 From: George Barnett Date: Fri, 24 Jan 2025 10:05:48 +0000 Subject: [PATCH 1/2] Update Example READMEs 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 --- Examples/echo/README.md | 15 +++++++++++---- Examples/error-details/README.md | 9 ++++++++- Examples/hello-world/README.md | 13 ++++++++++--- Examples/reflection-server/README.md | 7 +++++++ Examples/route-guide/README.md | 11 +++++++++-- 5 files changed, 45 insertions(+), 10 deletions(-) diff --git a/Examples/echo/README.md b/Examples/echo/README.md index bea921190..7e155459c 100644 --- a/Examples/echo/README.md +++ b/Examples/echo/README.md @@ -12,19 +12,24 @@ 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]. + ## 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 ``` @@ -32,7 +37,7 @@ 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 +47,7 @@ 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 diff --git a/Examples/error-details/README.md b/Examples/error-details/README.md index 6eeaa35e4..a0d70c40c 100644 --- a/Examples/error-details/README.md +++ b/Examples/error-details/README.md @@ -10,12 +10,17 @@ 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]. + ## 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 +29,5 @@ 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 diff --git a/Examples/hello-world/README.md b/Examples/hello-world/README.md index 9a1ff32ce..736689f7c 100644 --- a/Examples/hello-world/README.md +++ b/Examples/hello-world/README.md @@ -10,25 +10,32 @@ 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]. + ## 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 diff --git a/Examples/reflection-server/README.md b/Examples/reflection-server/README.md index 1743a8a08..3b9980f9e 100644 --- a/Examples/reflection-server/README.md +++ b/Examples/reflection-server/README.md @@ -23,6 +23,11 @@ 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]. + ## Usage Build and run the server using the CLI: @@ -59,3 +64,5 @@ $ 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 diff --git a/Examples/route-guide/README.md b/Examples/route-guide/README.md index d19a53c87..b4afe6472 100644 --- a/Examples/route-guide/README.md +++ b/Examples/route-guide/README.md @@ -15,19 +15,24 @@ 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]. + ## 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 OPTIONS: @@ -42,3 +47,5 @@ SUBCOMMANDS: See 'route-guide help ' for detailed help. ``` + +[0]: https://swiftpackageindex.com/grpc/grpc-swift-protobuf/documentation/grpcprotobuf/installing-protoc From c32b7197b781a6018b6302f7b3f5b75370952b8e Mon Sep 17 00:00:00 2001 From: George Barnett Date: Fri, 24 Jan 2025 10:49:32 +0000 Subject: [PATCH 2/2] Add note about PROTOC_PATH --- Examples/echo/README.md | 5 +++++ Examples/error-details/README.md | 5 +++++ Examples/hello-world/README.md | 5 +++++ Examples/reflection-server/README.md | 5 +++++ Examples/route-guide/README.md | 5 +++++ 5 files changed, 25 insertions(+) diff --git a/Examples/echo/README.md b/Examples/echo/README.md index 7e155459c..da5049731 100644 --- a/Examples/echo/README.md +++ b/Examples/echo/README.md @@ -16,6 +16,10 @@ HTTP/2 transport. 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 @@ -51,3 +55,4 @@ $ 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 index a0d70c40c..6dc09059e 100644 --- a/Examples/error-details/README.md +++ b/Examples/error-details/README.md @@ -14,6 +14,10 @@ Guide](https://grpc.io/docs/guides/error/) and is made available via the 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 @@ -31,3 +35,4 @@ Error details: ``` [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 index 736689f7c..32fa4ca5a 100644 --- a/Examples/hello-world/README.md +++ b/Examples/hello-world/README.md @@ -14,6 +14,10 @@ HTTP/2 transport. 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 @@ -39,3 +43,4 @@ 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 index 3b9980f9e..0954d844d 100644 --- a/Examples/reflection-server/README.md +++ b/Examples/reflection-server/README.md @@ -27,6 +27,10 @@ protoc --descriptor_set_out=path/to/output.pb path/to/input.proto \ 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 @@ -66,3 +70,4 @@ $ grpcurl -plaintext -d '{ "text": "Hello" }' 127.0.0.1:31415 echo.Echo.Get ``` [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 index b4afe6472..8a06ed735 100644 --- a/Examples/route-guide/README.md +++ b/Examples/route-guide/README.md @@ -19,6 +19,10 @@ Index](https://swiftpackageindex.com/grpc/grpc-swift/main/tutorials/grpccore/rou 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 @@ -49,3 +53,4 @@ SUBCOMMANDS: ``` [0]: https://swiftpackageindex.com/grpc/grpc-swift-protobuf/documentation/grpcprotobuf/installing-protoc +[1]: https://swiftpackageindex.com/grpc/grpc-swift-protobuf/documentation/grpcprotobuf/generating-stubs