grpc
/
grpc.io
mirror of https://github.com/grpc/grpc.io.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Quick start and Tutorial cleanup across all languages (#112) 

- Closes #87
- Closes #88
- Contributes to #111
- Markdown cleanup
- Copyedits in an attempt to bring some uniformity across language Quick Start and Tutorials.
This commit is contained in:
Patrice Chalin 2020-03-05 09:43:02 -05:00 committed by GitHub
parent 1acb8697ab
commit 07b1440ba3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
26 changed files with 707 additions and 688 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
content/docs/quickstart/android.md
View File

@ -7,20 +7,19 @@ description: This guide gets you started with gRPC in Android Java with a simple
<div id="toc"></div> <div id="toc"></div>
### Before you begin ### Prerequisites
#### Prerequisites - JDK version 7 or higher
- Android SDK, API level 14 or higher
- An android device set up for [USB debugging][] or an
[Android Virtual Device][]
* JDK: version 7 or higher [Android Virtual Device]: https://developer.android.com/studio/run/managing-avds.html
* Android SDK: API level 14 or higher [USB debugging]: https://developer.android.com/studio/command-line/adb.html#Enabling
* An android device set up for [USB
debugging](https://developer.android.com/studio/command-line/adb.html#Enabling)
or an [Android Virtual
Device](https://developer.android.com/studio/run/managing-avds.html)
Note: gRPC Java does not support running a server on an Android device. For this > **Note**: gRPC Java does not support running a server on an Android device.
quickstart, the Android client app will connect to a server running on your > For this quick start, the Android client app will connect to a server running
local (non-Android) computer. > on your local (non-Android) computer.
### Download the example ### Download the example
@ -38,19 +37,19 @@ $ cd grpc-java/examples
### Run a gRPC application ### Run a gRPC application
1. Compile the server 1. Compile the server:
```sh ```sh
$ ./gradlew installDist $ ./gradlew installDist
``` ```
2. Run the server 2. Run the server:
```sh ```sh
$ ./build/install/examples/bin/hello-world-server $ ./build/install/examples/bin/hello-world-server
``` ```
3. In another terminal, compile and run the client 3. From another terminal, compile and run the client:
```sh ```sh
$ cd android/helloworld $ cd android/helloworld
@ -111,7 +110,7 @@ message HelloReply {
} }
``` ```
(Don't forget to save the file!) Remember to save the file!
### Update and run the application ### Update and run the application
@ -125,7 +124,7 @@ parts of our example application.
#### Update the server #### Update the server
Check out the Java quickstart [here](/docs/quickstart/java/#update-the-server). See the [Java quick start](/docs/quickstart/java/#update-the-server).
#### Update the client #### Update the client
@ -157,13 +156,13 @@ Just like we did before, from the `examples` directory:
$ ./gradlew installDist $ ./gradlew installDist
``` ```
2. Run the server 2. Run the server:
```sh ```sh
$ ./build/install/examples/bin/hello-world-server $ ./build/install/examples/bin/hello-world-server
``` ```
3. In another terminal, compile and install the client to your device 3. From another terminal, compile and install the client to your device
```sh ```sh
$ cd android/helloworld $ cd android/helloworld

27
content/docs/quickstart/cpp.md
View File

@ -7,9 +7,9 @@ description: This guide gets you started with gRPC in C++ with a simple working
<div id="toc"></div> <div id="toc"></div>
### Before you begin ### Prerequisites
#### Install gRPC #### gRPC
To install gRPC on your system, follow the [instructions to install gRPC C++ via make](https://github.com/grpc/grpc/blob/master/src/cpp/README.md#make). To install gRPC on your system, follow the [instructions to install gRPC C++ via make](https://github.com/grpc/grpc/blob/master/src/cpp/README.md#make).
@ -19,7 +19,7 @@ example `Makefile`s try to look up the installed gRPC path using `pkg-config`.
On Debian-based systems like Ubuntu, this can usually be done via On Debian-based systems like Ubuntu, this can usually be done via
`sudo apt-get install pkg-config`. `sudo apt-get install pkg-config`.
#### Install Protocol Buffers v3 #### Protocol Buffers v3
While not mandatory to use gRPC, gRPC applications usually leverage Protocol While not mandatory to use gRPC, gRPC applications usually leverage Protocol
Buffers v3 for service definitions and data serialization, and our example code Buffers v3 for service definitions and data serialization, and our example code
@ -55,11 +55,13 @@ instructions for details](https://github.com/grpc/grpc/blob/master/src/cpp/READM
From the `examples/cpp/helloworld` directory, run the server, which will listen From the `examples/cpp/helloworld` directory, run the server, which will listen
on port 50051: on port 50051:
```sh ```sh
$ ./greeter_server $ ./greeter_server
``` ```
From a different terminal, run the client: From a different terminal, run the client:
```sh ```sh
$ ./greeter_client $ ./greeter_client
``` ```
@ -69,7 +71,6 @@ client side output.
Congratulations! You've just run a client-server application with gRPC. Congratulations! You've just run a client-server application with gRPC.
### Update a gRPC service ### Update a gRPC service
Now let's look at how to update the application with an extra method on the Now let's look at how to update the application with an extra method on the
@ -81,7 +82,6 @@ C++](/docs/tutorials/basic/cpp/). For now all you need to know is that both the
the client and returns a `HelloResponse` from the server, and that this method the client and returns a `HelloResponse` from the server, and that this method
is defined like this: is defined like this:
```protobuf ```protobuf
// The greeting service definition. // The greeting service definition.
service Greeter { service Greeter {
@ -105,7 +105,6 @@ Let's update this so that the `Greeter` service has two methods. Edit
update it with a new `SayHelloAgain` method, with the same request and response update it with a new `SayHelloAgain` method, with the same request and response
types: types:
```protobuf ```protobuf
// The greeting service definition. // The greeting service definition.
service Greeter { service Greeter {
@ -126,7 +125,7 @@ message HelloReply {
} }
``` ```
(Don't forget to save the file!) Remember to save the file!
### Generate gRPC code ### Generate gRPC code
@ -151,7 +150,6 @@ and call the new method in the human-written parts of our example application.
In the same directory, open `greeter_server.cc`. Implement the new method like In the same directory, open `greeter_server.cc`. Implement the new method like
this: this:
```c++ ```c++
class GreeterServiceImpl final : public Greeter::Service { class GreeterServiceImpl final : public Greeter::Service {
Status SayHello(ServerContext* context, const HelloRequest* request, Status SayHello(ServerContext* context, const HelloRequest* request,
@ -229,22 +227,21 @@ Just like we did before, from the `examples/cpp/helloworld` directory:
$ make $ make
``` ```
2. Run the server 2. Run the server:
```sh ```sh
$ ./greeter_server $ ./greeter_server
``` ```
3. On a different terminal, run the client 3. On a different terminal, run the client:
```sh ```sh
$ ./greeter_client $ ./greeter_client
``` ```
You should see the updated output: You'll see the following output:
```sh ```sh
$ ./greeter_client
Greeter received: Hello world Greeter received: Hello world
Greeter received: Hello again world Greeter received: Hello again world
``` ```
@ -252,7 +249,7 @@ Just like we did before, from the `examples/cpp/helloworld` directory:
### What's next ### What's next
- Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides/) - Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides/)
and [gRPC Concepts](/docs/guides/concepts/) and [gRPC Concepts](/docs/guides/concepts/).
- Work through a more detailed tutorial in [gRPC Basics: C++](/docs/tutorials/basic/cpp/) - Work through a more detailed tutorial in [gRPC Basics: C++](/docs/tutorials/basic/cpp/).
- Explore the gRPC C++ core API in its [reference - Explore the gRPC C++ core API in its [reference
documentation](/grpc/cpp/) documentation](/grpc/cpp/).

5
content/docs/quickstart/csharp-dotnet.md
View File

@ -7,8 +7,9 @@ description: This guide gets you started with gRPC for .NET with a simple workin
<div id="toc"></div> <div id="toc"></div>
NOTE: This is a quick start guide for the "grpc-dotnet" implementation of gRPC C#s. > **Note**: This is a quick start guide for the "grpc-dotnet" implementation of
See [gRPC C# Quick Start](/docs/quickstart/csharp) for how to start with the gRPC C# implementation based on native Core library. > gRPC C#s. See [gRPC C# Quick Start](/docs/quickstart/csharp) for how to start
> with the gRPC C# implementation based on native Core library.
### General project info ### General project info

28
content/docs/quickstart/csharp.md
View File

@ -7,12 +7,12 @@ description: This guide gets you started with gRPC in C# with a simple working e
<div id="toc"></div> <div id="toc"></div>
NOTE: This is a quick start guide for the gRPC C# implementation based on Core native library. > **Note**: This is a quick start guide for the gRPC C# implementation based on
See [gRPC for .NET Quick Start](/docs/quickstart/csharp-dotnet/) for how to start with the "grpc-dotnet" implementation. > Core native library. See [gRPC for .NET Quick
> Start](/docs/quickstart/csharp-dotnet/) for how to start with the
> "grpc-dotnet" implementation.
### Before you begin ### Prerequisites
#### Prerequisites
Whether you're using Windows, OS X, or Linux, you can follow this Whether you're using Windows, OS X, or Linux, you can follow this
example by using either an IDE and its build tools, example by using either an IDE and its build tools,
@ -30,7 +30,7 @@ clones the entire repository, but you just need the examples for this quickstart
and other tutorials): and other tutorials):
```sh ```sh
$ # Clone the repository to get the example code: # Clone the repository to get the example code:
$ git clone -b {{< param grpc_release_tag >}} https://github.com/grpc/grpc $ git clone -b {{< param grpc_release_tag >}} https://github.com/grpc/grpc
$ cd grpc $ cd grpc
``` ```
@ -61,14 +61,14 @@ From the `examples/csharp/Helloworld` directory:
From the `examples/csharp/Helloworld` directory: From the `examples/csharp/Helloworld` directory:
* Run the server * Run the server:
```sh ```sh
> cd GreeterServer > cd GreeterServer
> dotnet run -f netcoreapp2.1 > dotnet run -f netcoreapp2.1
``` ```
* In another terminal, run the client * From another terminal, run the client:
```sh ```sh
> cd GreeterClient > cd GreeterClient
@ -130,7 +130,7 @@ message HelloReply {
} }
``` ```
(Don't forget to save the file!) Remember to save the file!
### Generate gRPC code ### Generate gRPC code
@ -220,14 +220,14 @@ example by running `dotnet build Greeter.sln` or by clicking "Build" in Visual S
Just like we did before, from the `examples/csharp/Helloworld` directory: Just like we did before, from the `examples/csharp/Helloworld` directory:
* Run the server 1. Run the server:
```sh ```sh
> cd GreeterServer > cd GreeterServer
> dotnet run -f netcoreapp2.1 > dotnet run -f netcoreapp2.1
``` ```
* In another terminal, run the client 2. From another terminal, run the client:
```sh ```sh
> cd GreeterClient > cd GreeterClient
@ -237,7 +237,7 @@ Just like we did before, from the `examples/csharp/Helloworld` directory:
### What's next ### What's next
- Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides/) - Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides/)
and [gRPC Concepts](/docs/guides/concepts/) and [gRPC Concepts](/docs/guides/concepts/).
- Work through a more detailed tutorial in [gRPC Basics: C#](/docs/tutorials/basic/csharp/) - Work through a more detailed tutorial in [gRPC Basics: C#](/docs/tutorials/basic/csharp/).
- Explore the gRPC C# core API in its [reference - Explore the gRPC C# core API in its [reference
documentation](/grpc/csharp/api/Grpc.Core.html) documentation](/grpc/csharp/api/Grpc.Core.html).

16
content/docs/quickstart/dart.md
View File

@ -9,12 +9,12 @@ description: This guide gets you started with gRPC in Dart with a simple working
### Prerequisites ### Prerequisites
#### Dart SDK - Dart SDK version 2.0 or higher.
gRPC requires Dart SDK version 2.0 or higher. Dart gRPC supports Flutter and Server platforms.
For installation instructions, see [Install Dart](https://dart.dev/install). For installation instructions, see [Install Dart](https://dart.dev/install).
> Note: Dart gRPC supports the Flutter and Server platforms.
#### Protocol Buffers v3 #### Protocol Buffers v3
While not mandatory to use gRPC, gRPC applications usually leverage Protocol While not mandatory to use gRPC, gRPC applications usually leverage Protocol
@ -66,13 +66,13 @@ From the `example/helloworld` directory:
$ pub get $ pub get
``` ```
2. Run the server 2. Run the server:
```sh ```sh
$ dart bin/server.dart $ dart bin/server.dart
``` ```
3. In another terminal, run the client 3. From another terminal, run the client:
```sh ```sh
$ dart bin/client.dart $ dart bin/client.dart
@ -205,20 +205,20 @@ Future<void> main(List<String> args) async {
Run the client and server like you did before. Execute the following commands Run the client and server like you did before. Execute the following commands
from the `example/helloworld` directory: from the `example/helloworld` directory:
1. Run the server 1. Run the server:
```sh ```sh
$ dart bin/server.dart $ dart bin/server.dart
``` ```
2. In another terminal, run the client. This time, add a name as a command-line 2. From another terminal, run the client. This time, add a name as a command-line
argument: argument:
```sh ```sh
$ dart bin/client.dart Alice $ dart bin/client.dart Alice
``` ```
You should see the following output in the client terminal: You'll see the following output:
```sh ```sh
Greeter client received: Hello, Alice! Greeter client received: Hello, Alice!

55
content/docs/quickstart/go.md
View File

@ -9,17 +9,11 @@ description: This guide gets you started with gRPC in Go with a simple working e
### Prerequisites ### Prerequisites
#### Go version - Go version 1.6 or higher.
gRPC requires Go 1.6 or higher. For installation instructions, see Go's [Getting Started](https://golang.org/doc/install) guide.
```sh #### gRPC
$ go version
```
For installation instructions, follow this guide: [Getting Started - The Go Programming Language](https://golang.org/doc/install)
#### Install gRPC
Use the following command to install gRPC. Use the following command to install gRPC.
@ -27,7 +21,7 @@ Use the following command to install gRPC.
$ go get -u google.golang.org/grpc $ go get -u google.golang.org/grpc
``` ```
#### Install Protocol Buffers v3 #### Protocol Buffers v3
Install the protoc compiler that is used to generate gRPC service code. The simplest way to do this is to download pre-compiled binaries for your platform(`protoc-<version>-<platform>.zip`) from here: [https://github.com/google/protobuf/releases](https://github.com/google/protobuf/releases) Install the protoc compiler that is used to generate gRPC service code. The simplest way to do this is to download pre-compiled binaries for your platform(`protoc-<version>-<platform>.zip`) from here: [https://github.com/google/protobuf/releases](https://github.com/google/protobuf/releases)
@ -40,7 +34,9 @@ Next, install the protoc plugin for Go
$ go get -u github.com/golang/protobuf/protoc-gen-go $ go get -u github.com/golang/protobuf/protoc-gen-go
``` ```
The compiler plugin, protoc-gen-go, will be installed in $GOBIN, defaulting to $GOPATH/bin. It must be in your $PATH for the protocol compiler, protoc, to find it. The compiler plugin, `protoc-gen-go`, will be installed in `$GOBIN`, defaulting
to `$GOPATH/bin`. It must be in your `PATH` for the protocol compiler, protoc,
to find it.
```sh ```sh
$ export PATH=$PATH:$GOPATH/bin $ export PATH=$PATH:$GOPATH/bin
@ -58,14 +54,19 @@ Change to the example directory
$ cd $GOPATH/src/google.golang.org/grpc/examples/helloworld $ cd $GOPATH/src/google.golang.org/grpc/examples/helloworld
``` ```
gRPC services are defined in a `.proto` file, which is used to generate a corresponding `.pb.go` file. The `.pb.go` file is generated by compiling the `.proto` file using the protocol compiler: `protoc`. gRPC services are defined in a `.proto` file, which is used to generate a
corresponding `.pb.go` file. The `.pb.go` file is generated by compiling the
`.proto` file using the protocol compiler: `protoc`.
For the purpose of this example, the `helloworld.pb.go` file has already been generated (by compiling `helloworld.proto`), and can be found in this directory: `$GOPATH/src/google.golang.org/grpc/examples/helloworld/helloworld` For the purpose of this example, the `helloworld.pb.go` file has already been
generated (by compiling `helloworld.proto`), and can be found in this directory:
`$GOPATH/src/google.golang.org/grpc/examples/helloworld/helloworld`
This `helloworld.pb.go` file contains: This `helloworld.pb.go` file contains:
* Generated client and server code. - Generated client and server code.
* Code for populating, serializing, and retrieving our `HelloRequest` and `HelloReply` message types. - Code for populating, serializing, and retrieving our `HelloRequest` and
`HelloReply` message types.
### Try it! ### Try it!
@ -115,10 +116,12 @@ message HelloReply {
} }
``` ```
Let's update this so that the `Greeter` service has two methods. Make sure you are in the same examples dir as above (`$GOPATH/src/google.golang.org/grpc/examples/helloworld`) Let's update this so that the `Greeter` service has two methods. Make sure you
are in the same examples dir as above
(`$GOPATH/src/google.golang.org/grpc/examples/helloworld`).
Edit `helloworld/helloworld.proto` and update it with a new `SayHelloAgain` method, with the same request and response Edit `helloworld/helloworld.proto` and update it with a new `SayHelloAgain`
types: method, with the same request and response types:
```protobuf ```protobuf
// The greeting service definition. // The greeting service definition.
@ -143,7 +146,8 @@ message HelloReply {
### Generate gRPC code ### Generate gRPC code
Next we need to update the gRPC code used by our application to use the new Next we need to update the gRPC code used by our application to use the new
service definition. From the same examples dir as above (`$GOPATH/src/google.golang.org/grpc/examples/helloworld`) service definition. From the same examples dir as above
(`$GOPATH/src/google.golang.org/grpc/examples/helloworld`):
```sh ```sh
$ protoc -I helloworld/ helloworld/helloworld.proto --go_out=plugins=grpc:helloworld $ protoc -I helloworld/ helloworld/helloworld.proto --go_out=plugins=grpc:helloworld
@ -180,22 +184,21 @@ log.Printf("Greeting: %s", r.GetMessage())
#### Run! #### Run!
Run the server 1. Run the server:
```sh ```sh
$ go run greeter_server/main.go $ go run greeter_server/main.go
``` ```
On a different terminal, run the client 2. On a different terminal, run the client:
```sh ```sh
$ go run greeter_client/main.go $ go run greeter_client/main.go
``` ```
You should see the updated output: You'll see the following output:
```sh ```sh
$ go run greeter_client/main.go
Greeting: Hello world Greeting: Hello world
Greeting: Hello again world Greeting: Hello again world
``` ```
@ -203,7 +206,7 @@ Greeting: Hello again world
### What's next ### What's next
- Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides/) - Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides/)
and [gRPC Concepts](/docs/guides/concepts/) and [gRPC Concepts](/docs/guides/concepts/).
- Work through a more detailed tutorial in [gRPC Basics: Go](/docs/tutorials/basic/go/) - Work through a more detailed tutorial in [gRPC Basics: Go](/docs/tutorials/basic/go/).
- Explore the gRPC Go core API in its [reference - Explore the gRPC Go core API in its [reference
documentation](https://godoc.org/google.golang.org/grpc) documentation](https://godoc.org/google.golang.org/grpc).

19
content/docs/quickstart/java.md
View File

@ -7,11 +7,9 @@ description: This guide gets you started with gRPC in Java with a simple working
<div id="toc"></div> <div id="toc"></div>
### Before you begin ### Prerequisites
#### Prerequisites - JDK version 7 or higher
* JDK: version 7 or higher
### Download the example ### Download the example
@ -37,13 +35,13 @@ From the `examples` directory:
$ ./gradlew installDist $ ./gradlew installDist
``` ```
2. Run the server 2. Run the server:
```sh ```sh
$ ./build/install/examples/bin/hello-world-server $ ./build/install/examples/bin/hello-world-server
``` ```
3. In another terminal, run the client 3. From another terminal, run the client:
```sh ```sh
$ ./build/install/examples/bin/hello-world-client $ ./build/install/examples/bin/hello-world-client
@ -103,7 +101,7 @@ message HelloReply {
} }
``` ```
(Don't forget to save the file!) Remember to save the file!
### Update and run the application ### Update and run the application
@ -172,19 +170,19 @@ public void greet(String name) {
Just like we did before, from the `examples` directory: Just like we did before, from the `examples` directory:
1. Compile the client and server 1. Compile the client and server:
```sh ```sh
$ ./gradlew installDist $ ./gradlew installDist
``` ```
2. Run the server 2. Run the server:
```sh ```sh
$ ./build/install/examples/bin/hello-world-server $ ./build/install/examples/bin/hello-world-server
``` ```
3. In another terminal, run the client 3. From another terminal, run the client:
```sh ```sh
$ ./build/install/examples/bin/hello-world-client $ ./build/install/examples/bin/hello-world-client
@ -197,4 +195,3 @@ Just like we did before, from the `examples` directory:
- Work through a more detailed tutorial in [gRPC Basics: Java](/docs/tutorials/basic/java/). - Work through a more detailed tutorial in [gRPC Basics: Java](/docs/tutorials/basic/java/).
- Explore the gRPC Java core API in its [reference - Explore the gRPC Java core API in its [reference
documentation](/grpc-java/javadoc/). documentation](/grpc-java/javadoc/).

29
content/docs/quickstart/node.md
View File

@ -7,11 +7,9 @@ description: This guide gets you started with gRPC in Node with a simple working
<div id="toc"></div> <div id="toc"></div>
### Before you begin ### Prerequisites
#### Prerequisites - Node version 4.0.0 or higher
* `node`: version 4.0.0 or higher
### Download the example ### Download the example
@ -21,11 +19,11 @@ clones the entire repository, but you just need the examples for this quickstart
and other tutorials): and other tutorials):
```sh ```sh
$ # Clone the repository to get the example code # Clone the repository to get the example code
$ git clone -b {{< param grpc_release_tag >}} https://github.com/grpc/grpc $ git clone -b {{< param grpc_release_tag >}} https://github.com/grpc/grpc
$ # Navigate to the dynamic codegen "hello, world" Node example: # Navigate to the dynamic codegen "hello, world" Node example:
$ cd grpc/examples/node/dynamic_codegen $ cd grpc/examples/node/dynamic_codegen
$ # Install the example's dependencies # Install the example's dependencies
$ npm install $ npm install
``` ```
@ -33,13 +31,13 @@ $ npm install
From the `examples/node/dynamic_codegen` directory: From the `examples/node/dynamic_codegen` directory:
1. Run the server 1. Run the server:
```sh ```sh
$ node greeter_server.js $ node greeter_server.js
``` ```
2. In another terminal, run the client 2. From another terminal, run the client:
```sh ```sh
$ node greeter_client.js $ node greeter_client.js
@ -100,7 +98,7 @@ message HelloReply {
} }
``` ```
(Don't forget to save the file!) Remember to save the file!
### Update and run the application ### Update and run the application
@ -128,7 +126,6 @@ function main() {
server.bind('0.0.0.0:50051', grpc.ServerCredentials.createInsecure()); server.bind('0.0.0.0:50051', grpc.ServerCredentials.createInsecure());
server.start(); server.start();
} }
...
``` ```
#### Update the client #### Update the client
@ -152,13 +149,13 @@ function main() {
Just like we did before, from the `examples/node/dynamic_codegen` directory: Just like we did before, from the `examples/node/dynamic_codegen` directory:
1. Run the server 1. Run the server:
```sh ```sh
$ node greeter_server.js $ node greeter_server.js
``` ```
2. In another terminal, run the client 2. From another terminal, run the client:
```sh ```sh
$ node greeter_client.js $ node greeter_client.js
@ -167,8 +164,8 @@ Just like we did before, from the `examples/node/dynamic_codegen` directory:
### What's next ### What's next
- Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides/) - Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides/)
and [gRPC Concepts](/docs/guides/concepts/) and [gRPC Concepts](/docs/guides/concepts/).
- Work through a more detailed tutorial in [gRPC Basics: Node](/docs/tutorials/basic/node/) - Work through a more detailed tutorial in [gRPC Basics: Node](/docs/tutorials/basic/node/).
- Explore the gRPC Node core API in its [reference - Explore the gRPC Node core API in its [reference
documentation](/grpc/node/) documentation](/grpc/node/).
- We do have more than one grpc implementation for nodejs. [Learn about the pros and cons of each here](https://github.com/grpc/grpc-node/blob/master/PACKAGE-COMPARISON.md). - We do have more than one grpc implementation for nodejs. [Learn about the pros and cons of each here](https://github.com/grpc/grpc-node/blob/master/PACKAGE-COMPARISON.md).

119
content/docs/quickstart/objective-c.md
View File

@ -9,42 +9,41 @@ description: This guide gets you started with gRPC on the iOS platform in Object
### Before you begin ### Before you begin
#### System requirement #### System requirements
The minimum deployment iOS version for gRPC is 7.0.
OS X El Capitan (version 10.11) or above is required to build and run this - macOS version 10.11 (El Capitan) or higher
Quickstart. - iOS version 7.0 or higher
#### Prerequisites #### Prerequisites
* `CocoaPods`: version 1.0 or higher - CocoaPods version 1.0 or higher
* Check status and version of CocoaPods on your system with command `pod Check the status and version of CocoaPods on your system:
--version`.
* If CocoaPods is not installed, follow the install instructions on CocoaPods
[website](https://cocoapods.org).
* `Xcode`: version 7.2 or higher
* Check your Xcode version by running Xcode from Lauchpad, then select
"Xcode->About Xcode" in the menu.
* Make sure the command line developer tools are installed:
```sh ```sh
[sudo] xcode-select --install $ pod --version
``` ```
* `Homebrew` If CocoaPods is not installed, follow the [CocoaPods install
* Check status and version of Homebrew on your system with command `brew instructions](https://cocoapods.org).
--version`.
* If Homebrew is not installed, install with: - Xcode version 7.2 or higher
Check your Xcode version by running Xcode from Lauchpad, then select
**Xcode > About Xcode** in the menu.
Make sure the command line developer tools are installed:
```sh ```sh
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" $ xcode-select --install
``` ```
* `autoconf`, `automake`, `libtool`, `pkg-config` - [Homebrew](https://brew.sh/)
* Install with Homebrew
- `autoconf`, `automake`, `libtool`, `pkg-config`
```sh ```sh
brew install autoconf automake libtool pkg-config $ brew install autoconf automake libtool pkg-config
``` ```
### Download the example ### Download the example
@ -58,6 +57,7 @@ $ git clone --recursive -b {{< param grpc_release_tag >}} https://github.com/grp
``` ```
### Install gRPC plugins and libraries ### Install gRPC plugins and libraries
```sh ```sh
$ cd grpc $ cd grpc
$ make $ make
@ -65,12 +65,13 @@ $ [sudo] make install
``` ```
### Install protoc compiler ### Install protoc compiler
```sh ```sh
$ brew tap grpc/grpc $ brew tap grpc/grpc
$ brew install protobuf $ brew install protobuf
``` ```
### Run the server ### Run the server:
For this sample app, we need a gRPC server running on the local machine. gRPC For this sample app, we need a gRPC server running on the local machine. gRPC
Objective-C API supports creating gRPC clients but not gRPC servers. Therefore Objective-C API supports creating gRPC clients but not gRPC servers. Therefore
@ -82,7 +83,7 @@ $ make
$ ./greeter_server & $ ./greeter_server &
``` ```
### Run the client ### Run the client:
#### Generate client libraries and dependencies #### Generate client libraries and dependencies
@ -126,7 +127,7 @@ need to know is that both the server and the client "stub" have a `SayHello`
RPC method that takes a `HelloRequest` parameter from the client and returns a RPC method that takes a `HelloRequest` parameter from the client and returns a
`HelloResponse` from the server, and that this method is defined like this: `HelloResponse` from the server, and that this method is defined like this:
```c ```protobuf
// The greeting service definition. // The greeting service definition.
service Greeter { service Greeter {
// Sends a greeting // Sends a greeting
@ -148,7 +149,7 @@ Let's update this so that the `Greeter` service has two methods. Edit
`examples/protos/helloworld.proto` and update it with a new `SayHelloAgain` `examples/protos/helloworld.proto` and update it with a new `SayHelloAgain`
method, with the same request and response types: method, with the same request and response types:
```c ```protobuf
// The greeting service definition. // The greeting service definition.
service Greeter { service Greeter {
// Sends a greeting // Sends a greeting
@ -168,7 +169,7 @@ message HelloReply {
} }
``` ```
(Don't forget to save the file!) Remember to save the file!
### Update the client and server ### Update the client and server
@ -258,59 +259,63 @@ above. Open the client Xcode project in Xcode:
```sh ```sh
$ open HelloWorld.xcworkspace $ open HelloWorld.xcworkspace
``` ```
and run the client app. If you look at the console messages, you should see two RPC calls,
and run the client app. If you look at the console messages, You'll see two RPC calls,
one to SayHello and one to SayHelloAgain. one to SayHello and one to SayHelloAgain.
### Troubleshooting ### Troubleshooting
**When installing CocoaPods, error prompt `activesupport requires Ruby version >= 2.2.2.`** When installing CocoaPods, error `activesupport requires Ruby version >= 2.2.2`
: Install an older version of `activesupport`, then install CocoaPods:
Install an older version of `activesupport`, then install CocoaPods:
```sh ```sh
[sudo] gem install activesupport -v 4.2.6 $ [sudo] gem install activesupport -v 4.2.6
[sudo] gem install cocoapods $ [sudo] gem install cocoapods
``` ```
**When installing dependencies with CocoaPods, error prompt `Unable to find a specification for !ProtoCompiler-gRPCPlugin`**
Update the local clone of spec repo by running `pod repo update` When installing dependencies with CocoaPods, error `Unable to find a specification for !ProtoCompiler-gRPCPlugin`
**Compiler error when compiling `objective_c_plugin.cc`** : Update the local clone of spec repo by running `pod repo update`
Removing `protobuf` package with Homebrew before building gRPC may solve Compiler error when compiling `objective_c_plugin.cc`
this problem. We are working on a more elegant fix.
**When building HellowWorld, error prompt `ld: unknown option: --no-as-needed`** : Removing `protobuf` package with Homebrew before building gRPC may solve this
problem. We are working on a more elegant fix.
This problem is due to linker `ld` in Apple LLVM not supporting the When building HellowWorld, error `ld: unknown option: --no-as-needed`
--no-as-needed option. We are working on a fix right now and will merge the fix
very soon.
**When building grpc, error prompt `cannot find install-sh install.sh or shtool`** : This problem is due to linker `ld` in Apple LLVM not supporting the
`--no-as-needed` option. We are working on a fix right now and will merge the
fix very soon.
Remove the gRPC directory, clone a new one and try again. It is likely that some When building grpc, error `cannot find install-sh install.sh or shtool`
auto generated files are corrupt; remove and rebuild may solve the problem.
**When building grpc, error prompt `Can't exec "aclocal"`** : Remove the gRPC directory, clone a new one and try again. It is likely that
some auto generated files are corrupt; remove and rebuild may solve the
problem.
The package `automake` is missing. Install `automake` should solve this problem. When building grpc, error `Can't exec "aclocal"`
**When building grpc, error prompt `possibly undefined macro: AC_PROG_LIBTOOL`** : The package `automake` is missing. Install `automake` should solve this problem.
The package `libtool` is missing. Install `libtool` should solve this problem. When building grpc, error `possibly undefined macro: AC_PROG_LIBTOOL`
**When building grpc, error prompt `cannot find install-sh, install.sh, or shtool`** : The package `libtool` is missing. Install `libtool` should solve this problem.
Some of the auto generated files are corrupt. Remove the entire gRPC directory, When building grpc, error `cannot find install-sh, install.sh, or shtool`
clone from GitHub, and build again.
**Cannot find `protoc` when building HelloWorld** : Some of the auto generated files are corrupt. Remove the entire gRPC
directory, clone from GitHub, and build again.
Run `brew install protobuf` to get `protoc` compiler. Cannot find `protoc` when building HelloWorld
: Run `brew install protobuf` to get the `protoc` compiler.
### What's next ### What's next
- Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides/) - Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides/)
and [gRPC Concepts](/docs/guides/concepts/) and [gRPC Concepts](/docs/guides/concepts/).
- Work through a more detailed tutorial in [gRPC Basics: Objective-C](/docs/tutorials/basic/objective-c/) - Work through a more detailed tutorial in [gRPC Basics: Objective-C](/docs/tutorials/basic/objective-c/).
- Explore the Objective-C core API in its [reference - Explore the Objective-C core API in its [reference
documentation](http://cocoadocs.org/docsets/gRPC/) documentation](http://cocoadocs.org/docsets/gRPC/).

57
content/docs/quickstart/php.md
View File

@ -9,10 +9,10 @@ description: This guide gets you started with gRPC in PHP with a simple working
### Prerequisites ### Prerequisites
* `php` 5.5 or above, 7.0 or above - PHP 5.5 or higher, 7.0 or higher
* `pecl` - PECL
* `composer` - Composer
* `phpunit` (optional) - PHPUnit (optional)
**Install PHP and PECL on Ubuntu/Debian:** **Install PHP and PECL on Ubuntu/Debian:**
@ -65,9 +65,10 @@ $ sudo mv phpunit-old.phar /usr/bin/phpunit
### Install the gRPC PHP extension ### Install the gRPC PHP extension
There are two ways to install gRPC PHP extension. There are two ways to install gRPC PHP extension:
* `pecl`
* `build from source` - `pecl`
- `build from source`
#### Using PECL #### Using PECL
@ -150,9 +151,9 @@ need the `composer` and `protoc` binaries. You can find out how to get these bel
### Install other prerequisites for both Mac OS X and Linux ### Install other prerequisites for both Mac OS X and Linux
* `protoc: protobuf compiler` - `protoc: protobuf compiler`
* `protobuf.so: protobuf runtime library` - `protobuf.so: protobuf runtime library`
* `grpc_php_plugin: Generates PHP gRPC service interface out of Protobuf IDL` - `grpc_php_plugin: Generates PHP gRPC service interface out of Protobuf IDL`
#### Install Protobuf compiler #### Install Protobuf compiler
@ -200,7 +201,7 @@ in terms of APIs offered. The C implementation provides better performance,
while the native implementation is easier to install. Make sure the installed while the native implementation is easier to install. Make sure the installed
protobuf version works with grpc version. protobuf version works with grpc version.
##### 1. C implementation (for better performance) ##### C implementation (for better performance)
``` sh ``` sh
$ sudo pecl install protobuf $ sudo pecl install protobuf
@ -220,7 +221,7 @@ depending on where your PHP installation is.
extension=protobuf.so extension=protobuf.so
``` ```
##### 2. PHP implementation (for easier installation) ##### PHP implementation (for easier installation)
Add this to your `composer.json` file: Add this to your `composer.json` file:
@ -265,11 +266,11 @@ you can find out how to create gRPC servers in our other tutorials,
e.g. [Node.js](/docs/tutorials/basic/node/). e.g. [Node.js](/docs/tutorials/basic/node/).
```sh ```sh
$ # Clone the repository to get the example code: # Clone the repository to get the example code:
$ git clone -b {{< param grpc_release_tag >}} https://github.com/grpc/grpc $ git clone -b {{< param grpc_release_tag >}} https://github.com/grpc/grpc
$ # Build grpc_php_plugin to generate proto files if not build before # Build grpc_php_plugin to generate proto files if not build before
$ cd grpc && git submodule update --init && make grpc_php_plugin $ cd grpc && git submodule update --init && make grpc_php_plugin
$ # Navigate to the "hello, world" PHP example: # Navigate to the "hello, world" PHP example:
$ cd examples/php $ cd examples/php
$ ./greeter_proto_gen.sh $ ./greeter_proto_gen.sh
$ composer install $ composer install
@ -279,7 +280,7 @@ $ composer install
From the `examples/node` directory: From the `examples/node` directory:
1. Run the server 1. Run the server:
```sh ```sh
$ npm install $ npm install
@ -287,9 +288,8 @@ From the `examples/node` directory:
$ node greeter_server.js $ node greeter_server.js
``` ```
In another terminal, from the `examples/php` directory: 2. From another terminal, from the `examples/php` directory,
run the client:
1. Run the client
```sh ```sh
$ ./run_greeter_client.sh $ ./run_greeter_client.sh
@ -308,7 +308,7 @@ server and the client "stub" have a `SayHello` RPC method that takes a
the server, and that this method is defined like this: the server, and that this method is defined like this:
```php ```protobuf
// The greeting service definition. // The greeting service definition.
service Greeter { service Greeter {
// Sends a greeting // Sends a greeting
@ -330,7 +330,7 @@ Let's update this so that the `Greeter` service has two methods. Edit
`examples/protos/helloworld.proto` and update it with a new `SayHelloAgain` `examples/protos/helloworld.proto` and update it with a new `SayHelloAgain`
method, with the same request and response types: method, with the same request and response types:
```php ```protobuf
// The greeting service definition. // The greeting service definition.
service Greeter { service Greeter {
// Sends a greeting // Sends a greeting
@ -350,7 +350,7 @@ message HelloReply {
} }
``` ```
(Don't forget to save the file!) Remember to save the file!
### Generate gRPC code ### Generate gRPC code
@ -422,15 +422,14 @@ In the same directory, open `greeter_client.php`. Call the new method like this:
Just like we did before, from the `examples/node/dynamic_codegen` directory: Just like we did before, from the `examples/node/dynamic_codegen` directory:
1. Run the server 1. Run the server:
```sh ```sh
$ node greeter_server.js $ node greeter_server.js
``` ```
In another terminal, from the `examples/php` directory: 2. From another terminal, from the `examples/php` directory,
run the client:
2. Run the client
```sh ```sh
$ ./run_greeter_client.sh $ ./run_greeter_client.sh
@ -439,7 +438,7 @@ In another terminal, from the `examples/php` directory:
### What's next ### What's next
- Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides/) - Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides/)
and [gRPC Concepts](/docs/guides/concepts/) and [gRPC Concepts](/docs/guides/concepts/).
- Work through a more detailed tutorial in [gRPC Basics: PHP](/docs/tutorials/basic/php/) - Work through a more detailed tutorial in [gRPC Basics: PHP](/docs/tutorials/basic/php/).
- Explore the gRPC PHP core API in its [reference - Explore the gRPC PHP core API in its [reference
documentation](/grpc/php/namespace-Grpc.html) documentation](/grpc/php/namespace-Grpc.html).

35
content/docs/quickstart/python.md
View File

@ -7,13 +7,12 @@ description: This guide gets you started with gRPC in Python with a simple worki
<div id="toc"></div> <div id="toc"></div>
### Before you begin ### Prerequisites
#### Prerequisites - Python 2.7, or Python 3.4 or higher
- `pip` version 9.0.1 or higher
gRPC Python is supported for use with Python 2.7 or Python 3.4 or higher. If necessary, upgrade your version of `pip`:
Ensure you have `pip` version 9.0.1 or higher:
```sh ```sh
$ python -m pip install --upgrade pip $ python -m pip install --upgrade pip
@ -29,7 +28,7 @@ $ source venv/bin/activate
$ python -m pip install --upgrade pip $ python -m pip install --upgrade pip
``` ```
#### Install gRPC #### gRPC
Install gRPC: Install gRPC:
@ -55,11 +54,11 @@ You can work around this using:
$ python -m pip install grpcio --ignore-installed $ python -m pip install grpcio --ignore-installed
``` ```
#### Install gRPC tools #### gRPC tools
Python's gRPC tools include the protocol buffer compiler `protoc` and the Python's gRPC tools include the protocol buffer compiler `protoc` and the
special plugin for generating server and client code from `.proto` service special plugin for generating server and client code from `.proto` service
definitions. For the first part of our quickstart example, we've already definitions. For the first part of our quick-start example, we've already
generated the server and client stubs from generated the server and client stubs from
[helloworld.proto](https://github.com/grpc/grpc/tree/{{< param grpc_release_tag >}}/examples/protos/helloworld.proto), [helloworld.proto](https://github.com/grpc/grpc/tree/{{< param grpc_release_tag >}}/examples/protos/helloworld.proto),
but you'll need the tools for the rest of our quick start, as well as later but you'll need the tools for the rest of our quick start, as well as later
@ -79,9 +78,9 @@ clones the entire repository, but you just need the examples for this quickstart
and other tutorials): and other tutorials):
```sh ```sh
$ # Clone the repository to get the example code: # Clone the repository to get the example code:
$ git clone -b {{< param grpc_release_tag >}} https://github.com/grpc/grpc $ git clone -b {{< param grpc_release_tag >}} https://github.com/grpc/grpc
$ # Navigate to the "hello, world" Python example: # Navigate to the "hello, world" Python example:
$ cd grpc/examples/python/helloworld $ cd grpc/examples/python/helloworld
``` ```
@ -89,13 +88,13 @@ $ cd grpc/examples/python/helloworld
From the `examples/python/helloworld` directory: From the `examples/python/helloworld` directory:
1. Run the server 1. Run the server:
```sh ```sh
$ python greeter_server.py $ python greeter_server.py
``` ```
2. In another terminal, run the client 2. From another terminal, run the client:
```sh ```sh
$ python greeter_client.py $ python greeter_client.py
@ -156,7 +155,7 @@ message HelloReply {
} }
``` ```
(Don't forget to save the file!) Remember to save the file!
### Generate gRPC code ### Generate gRPC code
@ -212,13 +211,13 @@ def run():
Just like we did before, from the `examples/python/helloworld` directory: Just like we did before, from the `examples/python/helloworld` directory:
1. Run the server 1. Run the server:
```sh ```sh
$ python greeter_server.py $ python greeter_server.py
``` ```
2. In another terminal, run the client 2. From another terminal, run the client:
```sh ```sh
$ python greeter_client.py $ python greeter_client.py
@ -227,7 +226,7 @@ Just like we did before, from the `examples/python/helloworld` directory:
### What's next ### What's next
- Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides/) - Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides/)
and [gRPC Concepts](/docs/guides/concepts/) and [gRPC Concepts](/docs/guides/concepts/).
- Work through a more detailed tutorial in [gRPC Basics: Python](/docs/tutorials/basic/python/) - Work through a more detailed tutorial in [gRPC Basics: Python](/docs/tutorials/basic/python/).
- Explore the gRPC Python core API in its [reference - Explore the gRPC Python core API in its [reference
documentation](/grpc/python/) documentation](/grpc/python/).

39
content/docs/quickstart/ruby.md
View File

@ -7,32 +7,32 @@ description: This guide gets you started with gRPC in Ruby with a simple working
<div id="toc"></div> <div id="toc"></div>
### Before you begin ### Prerequisites
#### Prerequisites - Ruby version 2 or higher
* `ruby`: version 2 or higher #### gRPC
#### Install gRPC To install gRPC, run the following command:
``` ```sh
$ gem install grpc $ gem install grpc
``` ```
#### Install gRPC tools #### gRPC tools
Ruby's gRPC tools include the protocol buffer compiler `protoc` and the special Ruby's gRPC tools include the protocol buffer compiler `protoc` and the special
plugin for generating server and client code from the `.proto` service plugin for generating server and client code from the `.proto` service
definitions. For the first part of our quickstart example, we've already definitions. For the first part of our quick-start example, we've already
generated the server and client stubs from generated the server and client stubs from
[helloworld.proto](https://github.com/grpc/grpc/tree/{{< param grpc_release_tag >}}/examples/protos/helloworld.proto), [helloworld.proto](https://github.com/grpc/grpc/tree/{{< param grpc_release_tag >}}/examples/protos/helloworld.proto),
but you'll need the tools for the rest of our quick start, as well as later but you'll need the tools for the rest of our quick start, as well as later
tutorials and your own projects. tutorials and your own projects.
To install gRPC tools, run: To install gRPC tools, run the following command:
```sh ```sh
gem install grpc-tools $ gem install grpc-tools
``` ```
### Download the example ### Download the example
@ -43,9 +43,9 @@ clones the entire repository, but you just need the examples for this quickstart
and other tutorials): and other tutorials):
```sh ```sh
$ # Clone the repository to get the example code: # Clone the repository to get the example code:
$ git clone -b {{< param grpc_release_tag >}} https://github.com/grpc/grpc $ git clone -b {{< param grpc_release_tag >}} https://github.com/grpc/grpc
$ # Navigate to the "hello, world" Ruby example: # Navigate to the "hello, world" Ruby example:
$ cd grpc/examples/ruby $ cd grpc/examples/ruby
``` ```
@ -53,13 +53,13 @@ $ cd grpc/examples/ruby
From the `examples/ruby` directory: From the `examples/ruby` directory:
1. Run the server 1. Run the server:
```sh ```sh
$ ruby greeter_server.rb $ ruby greeter_server.rb
``` ```
2. In another terminal, run the client 2. From another terminal, run the client:
```sh ```sh
$ ruby greeter_client.rb $ ruby greeter_client.rb
@ -120,7 +120,7 @@ message HelloReply {
} }
``` ```
(Don't forget to save the file!) Remember to save the file!
### Generate gRPC code ### Generate gRPC code
@ -149,7 +149,6 @@ class GreeterServer < Helloworld::Greeter::Service
Helloworld::HelloReply.new(message: "Hello again, #{hello_req.name}") Helloworld::HelloReply.new(message: "Hello again, #{hello_req.name}")
end end
end end
...
``` ```
#### Update the client #### Update the client
@ -171,13 +170,13 @@ end
Just like we did before, from the `examples/ruby` directory: Just like we did before, from the `examples/ruby` directory:
1. Run the server 1. Run the server:
```sh ```sh
$ ruby greeter_server.rb $ ruby greeter_server.rb
``` ```
2. In another terminal, run the client 2. From another terminal, run the client:
```sh ```sh
$ ruby greeter_client.rb $ ruby greeter_client.rb
@ -186,7 +185,7 @@ Just like we did before, from the `examples/ruby` directory:
### What's next ### What's next
- Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides/) - Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides/)
and [gRPC Concepts](/docs/guides/concepts/) and [gRPC Concepts](/docs/guides/concepts/).
- Work through a more detailed tutorial in [gRPC Basics: Ruby](/docs/tutorials/basic/ruby/) - Work through a more detailed tutorial in [gRPC Basics: Ruby](/docs/tutorials/basic/ruby/).
- Explore the gRPC Ruby core API in its [reference - Explore the gRPC Ruby core API in its [reference
documentation](http://www.rubydoc.info/gems/grpc) documentation](http://www.rubydoc.info/gems/grpc).

32
content/docs/quickstart/web.md
View File

@ -9,13 +9,14 @@ description: This guide gets you started with gRPC-Web with a simple working exa
### Prerequisites ### Prerequisites
* `docker` and `docker-compose` - `docker`
- `docker-compose`
This demo requires Docker Compose file This demo requires Docker Compose file
[version 3](https://docs.docker.com/compose/compose-file/). Please refer to [version 3](https://docs.docker.com/compose/compose-file/). Please refer to
[Docker website](https://docs.docker.com/compose/install/#install-compose) on how to install Docker. [Docker website](https://docs.docker.com/compose/install/#install-compose) on how to install Docker.
### Run an Echo example from the browser! ### Run an Echo example from your browser!
```sh ```sh
$ git clone https://github.com/grpc/grpc-web $ git clone https://github.com/grpc/grpc-web
@ -24,35 +25,30 @@ $ docker-compose pull
$ docker-compose up -d node-server envoy commonjs-client $ docker-compose up -d node-server envoy commonjs-client
``` ```
Open a browser tab, and go to: From your browser visit
[localhost:8081/echotest.html](http://localhost:8081/echotest.html).
```sh
http://localhost:8081/echotest.html
```
To shutdown, run `docker-compose down`. To shutdown, run `docker-compose down`.
### What is Happening? ### What is happening?
In this demo, there are three key components: In this demo, there are three key components:
1. `node-server`: This is a standard gRPC Server, implemented in Node. 1. `node-server`: This is a standard gRPC Server, implemented in Node. This
This server listens at port `:9090` and implements the service's business server listens at port `:9090` and implements the service's business logic.
logic.
2. `envoy`: This is the Envoy proxy. It listens at `:8080` and forwards the 2. `envoy`: This is the Envoy proxy. It listens at `:8080` and forwards the
browser's gRPC-Web requests to port `:9090`. This is done via a config file browser's gRPC-Web requests to port `:9090`. This is done via a config file
`envoy.yaml`. `envoy.yaml`.
3. `commonjs-client`: This component generates the client stub class using 3. `commonjs-client`: This component generates the client stub class using the
the `protoc-gen-grpc-web` protoc plugin, compiles all the JS dependencies `protoc-gen-grpc-web` protoc plugin, compiles all the JS dependencies using
using `webpack`, and hosts the static content `echotest.html` and `webpack`, and hosts the static content `echotest.html` and `dist/main.js`
`dist/main.js` using a simple web server at port `:8081`. Once the user using a simple web server at port `:8081`. Once the user interacts with the
interacts with the webpage, it sends a gRPC-Web request to the Envoy proxy webpage, it sends a gRPC-Web request to the Envoy proxy endpoint at `:8080`.
endpoint at `:8080`.
### What's next ### What's next
- Work through a more detailed tutorial in [gRPC Basics: Web](/docs/tutorials/basic/web/) - Work through a more detailed tutorial in [gRPC Basics: Web](/docs/tutorials/basic/web/).

1
content/docs/tutorials/auth/oauth2-objective-c.md
View File

@ -175,6 +175,7 @@ To use this approach, first create a class in your project that conforms to
``` ```
When creating an RPC object, pass an instance of this class to call option `authTokenProvider`: When creating an RPC object, pass an instance of this class to call option `authTokenProvider`:
```objective-c ```objective-c
GRPCMutableCallOptions *options = [[GRPCMutableCallOptions alloc] init]; GRPCMutableCallOptions *options = [[GRPCMutableCallOptions alloc] init];
options.authTokenProvider = [[TokenProvider alloc] init]; options.authTokenProvider = [[TokenProvider alloc] init];

29
content/docs/tutorials/basic/android.md
View File

@ -63,14 +63,19 @@ service RouteGuide {
Then we define `rpc` methods inside our service definition, specifying their request and response types. gRPC lets you define four kinds of service method, all of which are used in the `RouteGuide` service: Then we define `rpc` methods inside our service definition, specifying their request and response types. gRPC lets you define four kinds of service method, all of which are used in the `RouteGuide` service:
- A *simple RPC* where the client sends a request to the server using the stub and waits for a response to come back, just like a normal function call. - A *simple RPC* where the client sends a request to the server using the stub
and waits for a response to come back, just like a normal function call.
```proto ```proto
// Obtains the feature at a given position. // Obtains the feature at a given position.
rpc GetFeature(Point) returns (Feature) {} rpc GetFeature(Point) returns (Feature) {}
``` ```
- A *server-side streaming RPC* where the client sends a request to the server and gets a stream to read a sequence of messages back. The client reads from the returned stream until there are no more messages. As you can see in our example, you specify a server-side streaming method by placing the `stream` keyword before the *response* type. - A *server-side streaming RPC* where the client sends a request to the server
and gets a stream to read a sequence of messages back. The client reads from
the returned stream until there are no more messages. As you can see in our
example, you specify a server-side streaming method by placing the `stream`
keyword before the *response* type.
```proto ```proto
// Obtains the Features available within the given Rectangle. Results are // Obtains the Features available within the given Rectangle. Results are
@ -80,7 +85,11 @@ rpc GetFeature(Point) returns (Feature) {}
rpc ListFeatures(Rectangle) returns (stream Feature) {} rpc ListFeatures(Rectangle) returns (stream Feature) {}
``` ```
- A *client-side streaming RPC* where the client writes a sequence of messages and sends them to the server, again using a provided stream. Once the client has finished writing the messages, it waits for the server to read them all and return its response. You specify a client-side streaming method by placing the `stream` keyword before the *request* type. - A *client-side streaming RPC* where the client writes a sequence of messages
and sends them to the server, again using a provided stream. Once the client
has finished writing the messages, it waits for the server to read them all
and return its response. You specify a client-side streaming method by placing
the `stream` keyword before the *request* type.
```proto ```proto
// Accepts a stream of Points on a route being traversed, returning a // Accepts a stream of Points on a route being traversed, returning a
@ -88,7 +97,14 @@ rpc ListFeatures(Rectangle) returns (stream Feature) {}
rpc RecordRoute(stream Point) returns (RouteSummary) {} rpc RecordRoute(stream Point) returns (RouteSummary) {}
``` ```
- A *bidirectional streaming RPC* where both sides send a sequence of messages using a read-write stream. The two streams operate independently, so clients and servers can read and write in whatever order they like: for example, the server could wait to receive all the client messages before writing its responses, or it could alternately read a message then write a message, or some other combination of reads and writes. The order of messages in each stream is preserved. You specify this type of method by placing the `stream` keyword before both the request and the response. - A *bidirectional streaming RPC* where both sides send a sequence of messages
using a read-write stream. The two streams operate independently, so clients
and servers can read and write in whatever order they like: for example, the
server could wait to receive all the client messages before writing its
responses, or it could alternately read a message then write a message, or
some other combination of reads and writes. The order of messages in each
stream is preserved. You specify this type of method by placing the `stream`
keyword before both the request and the response.
```proto ```proto
// Accepts a stream of RouteNotes sent while a route is being traversed, // Accepts a stream of RouteNotes sent while a route is being traversed,
@ -96,7 +112,9 @@ rpc RecordRoute(stream Point) returns (RouteSummary) {}
rpc RouteChat(stream RouteNote) returns (stream RouteNote) {} rpc RouteChat(stream RouteNote) returns (stream RouteNote) {}
``` ```
Our .proto file also contains protocol buffer message type definitions for all the request and response types used in our service methods - for example, here's the `Point` message type: Our `.proto` file also contains protocol buffer message type definitions for all
the request and response types used in our service methods - for example, here's
the `Point` message type:
```proto ```proto
// Points are represented as latitude-longitude pairs in the E7 representation // Points are represented as latitude-longitude pairs in the E7 representation
@ -109,7 +127,6 @@ message Point {
} }
``` ```
### Generating client code ### Generating client code
Next we need to generate the gRPC client interfaces from our .proto Next we need to generate the gRPC client interfaces from our .proto

23
content/docs/tutorials/basic/cpp.md
View File

@ -74,7 +74,7 @@ You can see the complete .proto file in
To define a service, you specify a named `service` in your .proto file: To define a service, you specify a named `service` in your .proto file:
```c ```protobuf
service RouteGuide { service RouteGuide {
... ...
} }
@ -87,7 +87,7 @@ all of which are used in the `RouteGuide` service:
- A *simple RPC* where the client sends a request to the server using the stub - A *simple RPC* where the client sends a request to the server using the stub
and waits for a response to come back, just like a normal function call. and waits for a response to come back, just like a normal function call.
```c ```protobuf
// Obtains the feature at a given position. // Obtains the feature at a given position.
rpc GetFeature(Point) returns (Feature) {} rpc GetFeature(Point) returns (Feature) {}
``` ```
@ -98,7 +98,7 @@ rpc GetFeature(Point) returns (Feature) {}
example, you specify a server-side streaming method by placing the `stream` example, you specify a server-side streaming method by placing the `stream`
keyword before the *response* type. keyword before the *response* type.
```c ```protobuf
// Obtains the Features available within the given Rectangle. Results are // Obtains the Features available within the given Rectangle. Results are
// streamed rather than returned at once (e.g. in a response message with a // streamed rather than returned at once (e.g. in a response message with a
// repeated field), as the rectangle may cover a large area and contain a // repeated field), as the rectangle may cover a large area and contain a
@ -112,7 +112,7 @@ rpc ListFeatures(Rectangle) returns (stream Feature) {}
and return its response. You specify a client-side streaming method by placing and return its response. You specify a client-side streaming method by placing
the `stream` keyword before the *request* type. the `stream` keyword before the *request* type.
```c ```protobuf
// Accepts a stream of Points on a route being traversed, returning a // Accepts a stream of Points on a route being traversed, returning a
// RouteSummary when traversal is completed. // RouteSummary when traversal is completed.
rpc RecordRoute(stream Point) returns (RouteSummary) {} rpc RecordRoute(stream Point) returns (RouteSummary) {}
@ -127,17 +127,17 @@ rpc RecordRoute(stream Point) returns (RouteSummary) {}
stream is preserved. You specify this type of method by placing the `stream` stream is preserved. You specify this type of method by placing the `stream`
keyword before both the request and the response. keyword before both the request and the response.
```c ```protobuf
// Accepts a stream of RouteNotes sent while a route is being traversed, // Accepts a stream of RouteNotes sent while a route is being traversed,
// while receiving other RouteNotes (e.g. from other users). // while receiving other RouteNotes (e.g. from other users).
rpc RouteChat(stream RouteNote) returns (stream RouteNote) {} rpc RouteChat(stream RouteNote) returns (stream RouteNote) {}
``` ```
Our .proto file also contains protocol buffer message type definitions for all Our `.proto` file also contains protocol buffer message type definitions for all
the request and response types used in our service methods - for example, here's the request and response types used in our service methods - for example, here's
the `Point` message type: the `Point` message type:
```c ```protobuf
// Points are represented as latitude-longitude pairs in the E7 representation // Points are represented as latitude-longitude pairs in the E7 representation
// (degrees multiplied by 10**7 and rounded to the nearest integer). // (degrees multiplied by 10**7 and rounded to the nearest integer).
// Latitudes should be in the range +/- 90 degrees and longitude should be in // Latitudes should be in the range +/- 90 degrees and longitude should be in
@ -148,7 +148,6 @@ message Point {
} }
``` ```
### Generating client and server code ### Generating client and server code
Next we need to generate the gRPC client and server interfaces from our .proto Next we need to generate the gRPC client and server interfaces from our .proto
@ -520,17 +519,19 @@ independently.
### Try it out! ### Try it out!
Build client and server: Build the client and server:
```sh ```sh
$ make $ make
``` ```
Run the server, which will listen on port 50051:
Run the server:
```sh ```sh
$ ./route_guide_server $ ./route_guide_server
``` ```
Run the client (in a different terminal):
From a different terminal, run the client:
```sh ```sh
$ ./route_guide_client $ ./route_guide_client

25
content/docs/tutorials/basic/csharp.md
View File

@ -128,7 +128,7 @@ rpc RecordRoute(stream Point) returns (RouteSummary) {}
rpc RouteChat(stream RouteNote) returns (stream RouteNote) {} rpc RouteChat(stream RouteNote) returns (stream RouteNote) {}
``` ```
Our .proto file also contains protocol buffer message type definitions for all Our `.proto` file also contains protocol buffer message type definitions for all
the request and response types used in our service methods - for example, here's the request and response types used in our service methods - for example, here's
the `Point` message type: the `Point` message type:
@ -480,28 +480,27 @@ using (var call = client.RouteChat())
### Try it out! ### Try it out!
#### Build the client and server: Build the client and server:
##### Using Visual Studio (or Visual Studio For Mac) Using Visual Studio (or Visual Studio For Mac)
: Open the solution `examples/csharp/RouteGuide/RouteGuide.sln` and select **Build**.
- Open the solution `examples/csharp/RouteGuide/RouteGuide.sln` and select **Build**. Using `dotnet` command line tool
##### Using "dotnet" command line tool : Run `dotnet build RouteGuide.sln` from the `examples/csharp/RouteGuide`
directory. For additional instructions on building the gRPC example with the
`dotnet` command line tool, see [Quick Start](../../quickstart/csharp.html).
- Run `dotnet build RouteGuide.sln` from the `examples/csharp/RouteGuide` directory. Run the server:
See the [quickstart](../../quickstart/csharp.html) for additional instructions on building
the gRPC example with the `dotnet` command line tool.
Run the server, which will listen on port 50052: ```sh
```
> cd RouteGuideServer/bin/Debug/netcoreapp2.1 > cd RouteGuideServer/bin/Debug/netcoreapp2.1
> dotnet exec RouteGuideServer.dll > dotnet exec RouteGuideServer.dll
``` ```
Run the client (in a different terminal): From a different terminal, run the client:
``` ```sh
> cd RouteGuideClient/bin/Debug/netcoreapp2.1 > cd RouteGuideClient/bin/Debug/netcoreapp2.1
> dotnet exec RouteGuideClient.dll > dotnet exec RouteGuideClient.dll
``` ```

17
content/docs/tutorials/basic/dart.md
View File

@ -56,7 +56,6 @@ $ cd grpc-dart/example/route_guide
You also should have the relevant tools installed to generate the server and client interface code - if you don't already, follow the setup instructions in [the Dart quick start guide](/docs/quickstart/dart/). You also should have the relevant tools installed to generate the server and client interface code - if you don't already, follow the setup instructions in [the Dart quick start guide](/docs/quickstart/dart/).
### Defining the service ### Defining the service
Our first step (as you'll know from the [Overview](/docs/)) is to Our first step (as you'll know from the [Overview](/docs/)) is to
@ -126,7 +125,9 @@ rpc RecordRoute(stream Point) returns (RouteSummary) {}
rpc RouteChat(stream RouteNote) returns (stream RouteNote) {} rpc RouteChat(stream RouteNote) returns (stream RouteNote) {}
``` ```
Our .proto file also contains protocol buffer message type definitions for all the request and response types used in our service methods - for example, here's the `Point` message type: Our `.proto` file also contains protocol buffer message type definitions for all
the request and response types used in our service methods - for example, here's
the `Point` message type:
```proto ```proto
// Points are represented as latitude-longitude pairs in the E7 representation // Points are represented as latitude-longitude pairs in the E7 representation
@ -521,21 +522,25 @@ write in any order — the streams operate completely independently.
### Try it out! ### Try it out!
Go to the `examples/route_guide` folder. Work from the example directory:
First, make sure dependencies are downloaded: ```sh
$ cd examples/route_guide
```
Get packages:
```sh ```sh
$ pub get $ pub get
``` ```
To run the server, simply: Run the server:
```sh ```sh
$ dart bin/server.dart $ dart bin/server.dart
``` ```
Likewise, to run the client: From a different terminal, run the client:
```sh ```sh
$ dart bin/client.dart $ dart bin/client.dart

19
content/docs/tutorials/basic/go.md
View File

@ -128,7 +128,9 @@ rpc RecordRoute(stream Point) returns (RouteSummary) {}
rpc RouteChat(stream RouteNote) returns (stream RouteNote) {} rpc RouteChat(stream RouteNote) returns (stream RouteNote) {}
``` ```
Our .proto file also contains protocol buffer message type definitions for all the request and response types used in our service methods - for example, here's the `Point` message type: Our `.proto` file also contains protocol buffer message type definitions for all
the request and response types used in our service methods - for example, here's
the `Point` message type:
```proto ```proto
// Points are represented as latitude-longitude pairs in the E7 representation // Points are represented as latitude-longitude pairs in the E7 representation
@ -154,7 +156,9 @@ From the `route_guide` example directory run :
protoc -I routeguide/ routeguide/route_guide.proto --go_out=plugins=grpc:routeguide protoc -I routeguide/ routeguide/route_guide.proto --go_out=plugins=grpc:routeguide
``` ```
Running this command generates the following file in the `routeguide` directory under the `route_guide` example directory: Running this command generates the following file in the `routeguide` directory
under the `route_guide` example directory:
- `route_guide.pb.go` - `route_guide.pb.go`
This contains: This contains:
@ -573,14 +577,19 @@ any order — the streams operate completely independently.
### Try it out! ### Try it out!
To compile and run the server, assuming you are in the folder Work from the example directory:
`$GOPATH/src/google.golang.org/grpc/examples/route_guide`, simply:
```sh
$ cd $GOPATH/src/google.golang.org/grpc/examples/route_guide
```
Run the server:
```sh ```sh
$ go run server/server.go $ go run server/server.go
``` ```
Likewise, to run the client: From a different terminal, run the client:
```sh ```sh
$ go run client/client.go $ go run client/client.go

5
content/docs/tutorials/basic/java.md
View File

@ -57,7 +57,6 @@ Then change your current directory to `grpc-java/examples`:
$ cd grpc-java/examples $ cd grpc-java/examples
``` ```
### Defining the service ### Defining the service
Our first step (as you'll know from the [Overview](/docs/)) is to Our first step (as you'll know from the [Overview](/docs/)) is to
@ -142,7 +141,7 @@ rpc RecordRoute(stream Point) returns (RouteSummary) {}
rpc RouteChat(stream RouteNote) returns (stream RouteNote) {} rpc RouteChat(stream RouteNote) returns (stream RouteNote) {}
``` ```
Our .proto file also contains protocol buffer message type definitions for all Our `.proto` file also contains protocol buffer message type definitions for all
the request and response types used in our service methods - for example, here's the request and response types used in our service methods - for example, here's
the `Point` message type: the `Point` message type:
@ -157,7 +156,6 @@ message Point {
} }
``` ```
### Generating client and server code ### Generating client and server code
Next we need to generate the gRPC client and server interfaces from our .proto Next we need to generate the gRPC client and server interfaces from our .proto
@ -181,7 +179,6 @@ The following classes are generated from our service definition:
`RouteGuide` service. `RouteGuide` service.
- *stub* classes that clients can use to talk to a `RouteGuide` server. - *stub* classes that clients can use to talk to a `RouteGuide` server.
<a name="server"></a> <a name="server"></a>
### Creating the server ### Creating the server

10
content/docs/tutorials/basic/node.md
View File

@ -145,7 +145,7 @@ rpc RecordRoute(stream Point) returns (RouteSummary) {}
rpc RouteChat(stream RouteNote) returns (stream RouteNote) {} rpc RouteChat(stream RouteNote) returns (stream RouteNote) {}
``` ```
Our .proto file also contains protocol buffer message type definitions for all Our `.proto` file also contains protocol buffer message type definitions for all
the request and response types used in our service methods - for example, here's the request and response types used in our service methods - for example, here's
the `Point` message type: the `Point` message type:
@ -512,17 +512,19 @@ independently.
### Try it out! ### Try it out!
Build client and server: Build the client and server:
```sh ```sh
$ npm install $ npm install
``` ```
Run the server, which will listen on port 50051:
Run the server:
```sh ```sh
$ node ./dynamic_codegen/route_guide/route_guide_server.js --db_path=./dynamic_codegen/route_guide/route_guide_db.json $ node ./dynamic_codegen/route_guide/route_guide_server.js --db_path=./dynamic_codegen/route_guide/route_guide_db.json
``` ```
Run the client (in a different terminal):
From a different terminal, run the client:
```sh ```sh
$ node ./dynamic_codegen/route_guide/route_guide_client.js --db_path=./dynamic_codegen/route_guide/route_guide_db.json $ node ./dynamic_codegen/route_guide/route_guide_client.js --db_path=./dynamic_codegen/route_guide/route_guide_db.json

2
content/docs/tutorials/basic/objective-c.md
View File

@ -178,7 +178,7 @@ rpc RecordRoute(stream Point) returns (RouteSummary) {}
rpc RouteChat(stream RouteNote) returns (stream RouteNote) {} rpc RouteChat(stream RouteNote) returns (stream RouteNote) {}
``` ```
Our .proto file also contains protocol buffer message type definitions for all Our `.proto` file also contains protocol buffer message type definitions for all
the request and response types used in our service methods - for example, here's the request and response types used in our service methods - for example, here's
the `Point` message type: the `Point` message type:

2
content/docs/tutorials/basic/php.md
View File

@ -168,7 +168,7 @@ rpc RecordRoute(stream Point) returns (RouteSummary) {}
rpc RouteChat(stream RouteNote) returns (stream RouteNote) {} rpc RouteChat(stream RouteNote) returns (stream RouteNote) {}
``` ```
Our .proto file also contains protocol buffer message type definitions for all Our `.proto` file also contains protocol buffer message type definitions for all
the request and response types used in our service methods - for example, here's the request and response types used in our service methods - for example, here's
the `Point` message type: the `Point` message type:

6
content/docs/tutorials/basic/python.md
View File

@ -129,7 +129,7 @@ rpc RecordRoute(stream Point) returns (RouteSummary) {}
rpc RouteChat(stream RouteNote) returns (stream RouteNote) {} rpc RouteChat(stream RouteNote) returns (stream RouteNote) {}
``` ```
Your .proto file also contains protocol buffer message type definitions for all Your `.proto` file also contains protocol buffer message type definitions for all
the request and response types used in our service methods - for example, here's the request and response types used in our service methods - for example, here's
the `Point` message type: the `Point` message type:
@ -394,13 +394,13 @@ for received_route_note in stub.RouteChat(sent_route_note_iterator):
### Try it out! ### Try it out!
Run the server, which will listen on port 50051: Run the server:
```sh ```sh
$ python route_guide_server.py $ python route_guide_server.py
``` ```
Run the client (in a different terminal): From a different terminal, run the client:
```sh ```sh
$ python route_guide_client.py $ python route_guide_client.py

23
content/docs/tutorials/basic/ruby.md
View File

@ -129,7 +129,7 @@ rpc RecordRoute(stream Point) returns (RouteSummary) {}
rpc RouteChat(stream RouteNote) returns (stream RouteNote) {} rpc RouteChat(stream RouteNote) returns (stream RouteNote) {}
``` ```
Our .proto file also contains protocol buffer message type definitions for all Our `.proto` file also contains protocol buffer message type definitions for all
the request and response types used in our service methods - for example, here's the request and response types used in our service methods - for example, here's
the `Point` message type: the `Point` message type:
@ -376,23 +376,28 @@ streams operate completely independently.
### Try it out! ### Try it out!
Build client and server: Work from the example directory:
```sh
$ cd examples/ruby
```
Build the client and server:
```sh ```sh
$ # from examples/ruby
$ gem install bundler && bundle install $ gem install bundler && bundle install
``` ```
Run the server, which will listen on port 50051:
Run the server:
```sh ```sh
$ # from examples/ruby
$ bundle exec route_guide/route_guide_server.rb ../python/route_guide/route_guide_db.json $ bundle exec route_guide/route_guide_server.rb ../python/route_guide/route_guide_db.json
$ # (note that the route_guide_db.json file is actually language-agnostic; it's just
$ # located in the python folder).
``` ```
Run the client (in a different terminal):
> Note: The `route_guide_db.json` file is actually language-agnostic, it happens to be located in the `python` folder.
From a different terminal, run the client:
```sh ```sh
$ # from examples/ruby
$ bundle exec route_guide/route_guide_client.rb ../python/route_guide/route_guide_db.json $ bundle exec route_guide/route_guide_client.rb ../python/route_guide/route_guide_db.json
``` ```

9
content/docs/tutorials/basic/web.md
View File

@ -32,7 +32,6 @@ protocol buffers, including efficient serialization, a simple IDL, and easy
interface updating. gRPC-Web lets you access gRPC services built in this manner interface updating. gRPC-Web lets you access gRPC services built in this manner
from browsers using an idiomatic API. from browsers using an idiomatic API.
<a name="setup"></a> <a name="setup"></a>
### Define the Service ### Define the Service
@ -74,7 +73,6 @@ function doEcho(call, callback) {
} }
``` ```
### Configure the Envoy Proxy ### Configure the Envoy Proxy
In this example, we will use the [Envoy](https://www.envoyproxy.io/) In this example, we will use the [Envoy](https://www.envoyproxy.io/)
@ -119,15 +117,11 @@ this:
You may also need to add some CORS setup to make sure the browser can request You may also need to add some CORS setup to make sure the browser can request
cross-origin content. cross-origin content.
In this simple example, the browser makes gRPC requests to port `:8080`. Envoy In this simple example, the browser makes gRPC requests to port `:8080`. Envoy
forwards the request to the backend gRPC server listening on port `:9090`. forwards the request to the backend gRPC server listening on port `:9090`.
### Generate Protobuf Messages and Service Client Stub ### Generate Protobuf Messages and Service Client Stub
To generate the protobuf message classes from our `echo.proto`, run the To generate the protobuf message classes from our `echo.proto`, run the
following command: following command:
@ -163,7 +157,6 @@ In the `--grpc-web_out` param above:
Our command generates the client stub, by default, to the file Our command generates the client stub, by default, to the file
`echo_grpc_web_pb.js`. `echo_grpc_web_pb.js`.
### Write JS Client Code ### Write JS Client Code
Now you are ready to write some JS client code. Put this in a `client.js` file. Now you are ready to write some JS client code. Put this in a `client.js` file.
@ -201,7 +194,6 @@ You will need a `package.json` file
### Compile the JS Library ### Compile the JS Library
Finally, putting all these together, we can compile all the relevant JS files Finally, putting all these together, we can compile all the relevant JS files
into one single JS library that can be used in the browser. into one single JS library that can be used in the browser.
@ -212,6 +204,5 @@ $ npx webpack client.js
Now embed `dist/main.js` into your project and see it in action! Now embed `dist/main.js` into your project and see it in action!
[protobuf documentation]:https://developers.google.com/protocol-buffers/ [protobuf documentation]:https://developers.google.com/protocol-buffers/
[main page]:/docs/ [main page]:/docs/