C++ quick start: fix instructions (#172)

* C++ quick start: fix instructions

Closes #95
Closes #97

* Post-review edits

* Reworked, and tested, instructions

* Updates based on Jan's feedback

* Updates following more feedback from Jan

Author: chalin

content/docs/quickstart/cpp.md

@@ -3,69 +3,168 @@ layout: quickstart
 title: C++ Quick Start
 short: C++
 description: This guide gets you started with gRPC in C++ with a simple working example.
+cmake-version: 3.17.0
 ---
 
-### Prerequisites
+In the C++ world, there's no universally accepted standard for managing project
+dependencies. In this quick start, you'll follow steps to build and locally
+install gRPC before building and running this quick start's Hello World example.
+
+### Setup
 
-#### gRPC
+Choose a directory to hold locally installed packages. This page assumes that
+the environment variable `MY_INSTALL_DIR` holds this directory path. For
+example:
 
-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).
+```sh
+$ export MY_INSTALL_DIR=$HOME/local
+```
 
-To run the example code, please ensure `pkg-config` is installed on your
-machine before you build and install gRPC in the previous step, since the
-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
-`sudo apt-get install pkg-config`.
+Ensure that the directory exists:
 
-#### Protocol Buffers v3
+```sh
+$ mkdir -p $MY_INSTALL_DIR
+```
 
-While not mandatory to use gRPC, gRPC applications usually leverage Protocol
-Buffers v3 for service definitions and data serialization, and our example code
-uses Protocol Buffers as well as gRPC. If you don't already have it installed on
-your system, you can install the version cloned alongside gRPC. First ensure
-that you are running these commands in the gRPC tree you just built in the from
-the previous step.
+Add the local `bin` folder to your path variable, for example:
 
 ```sh
-$ cd third_party/protobuf
-$ make && sudo make install
+$ export PATH="$PATH:$MY_INSTALL_DIR/bin"
 ```
 
-###  Build the example
+### Prerequisites
 
-Always assuming you have gRPC properly installed, go into the example's
-directory:
+#### cmake
+
+Version 3.13 or later of `cmake` is required to install gRPC locally.
+
+- Linux
+
+  ```sh
+  $ sudo apt install -y cmake
+  ```
+
+- macOS:
+
+  ```sh
+  $ brew install cmake
+  ```
+
+- For general `cmake` installation instructions, see [Installing CMake][].
+
+Check the version of `cmake`:
 
 ```sh
-$ cd examples/cpp/helloworld/
+$ cmake --version
 ```
 
-Let's build the example client and server:
+Under Linux, the version of the system-wide `cmake` can be too low. You can
+install a more recent version into your local installation directory as follows:
+
 ```sh
-$ make
+$ wget -q -O cmake-linux.sh https://github.com/Kitware/CMake/releases/download/v{{< param cmake-version >}}/cmake-{{< param cmake-version >}}-Linux-x86_64.sh
+$ sh cmake-linux.sh -- --skip-license --prefix=$MY_INSTALL_DIR
+$ rm cmake-linux.sh
 ```
 
-Most failures at this point are a result of a faulty installation (or having
-installed gRPC to a non-standard location. Check out [the installation
-instructions for details](https://github.com/grpc/grpc/blob/master/src/cpp/README.md#make)).
+
+#### gRPC and Protocol Buffers
+
+While not mandatory, gRPC applications usually leverage [Protocol Buffers][pb]
+for service definitions and data serialization, and the example code uses
+[proto3][].
+
+The following instructions will locally install gRPC and Protocol Buffers.
+
+ 1. Install the basic tools required to build gRPC:
+
+    - Linux
+
+      ```sh
+      $ sudo apt install -y build-essential autoconf libtool pkg-config
+      ```
+
+    - macOS:
+
+      ```sh
+      $ brew install autoconf automake libtool pkg-config
+      ```
+
+ 2. Clone the `grpc` repo and its submodules:
+
+    ```sh
+    $ git clone --recurse-submodules -b {{< param grpc_release_tag >}} https://github.com/grpc/grpc
+    $ cd grpc
+    ```
+
+ 3. Build and locally install gRPC and all requisite tools:
+
+    ```sh
+    $ mkdir -p cmake/build
+    $ pushd cmake/build
+    $ cmake -DgRPC_INSTALL=ON \
+          -DgRPC_BUILD_TESTS=OFF \
+          -DCMAKE_INSTALL_PREFIX=$MY_INSTALL_DIR \
+          ../..
+    $ make -j
+    $ make install
+    $ popd
+    ```
+
+More information:
+
+- You can find a complete set of instructions for building gRPC C++ in [Building
+  from source][from-source].
+- For general instructions on how to add gRPC as a dependency to your C++
+  project, see [Start using gRPC C++][using-grpc].
+
+[from-source]: https://github.com/grpc/grpc/blob/master/BUILDING.md
+[using-grpc]: https://github.com/grpc/grpc/tree/master/src/cpp#to-start-using-grpc-c
+
+###  Build the example
+
+The example code is part of the `grpc` repo source, which you cloned as part of
+the steps of the previous section.
+
+ 1. Change to the example's directory:
+
+    ```sh
+    $ cd examples/cpp/helloworld
+    ```
+
+ 2. Build the example using `cmake`:
+
+    ```sh
+    $ mkdir -p cmake/build
+    $ pushd cmake/build
+    $ cmake -DCMAKE_PREFIX_PATH=$MY_INSTALL_DIR ../..
+    $ make -j
+    ```
+
+    {{< note >}}
+  **Getting build failures?** Most issues, at this point, are a result of a
+  faulty installation. Ensure that the have the right versions of `cmake`, and
+  carefully recheck your installation.
+    {{< /note >}}
+
 
 ### Try it!
 
-From the `examples/cpp/helloworld` directory, run the server, which will listen
-on port 50051:
+Run the example from the example **build** directory
+`examples/cpp/helloworld/cmake/build`:
 
-```sh
-$ ./greeter_server
-```
+ 1. Run the server:
 
-From a different terminal, run the client:
+    ```sh
+    $ ./greeter_server
+    ```
 
-```sh
-$ ./greeter_client
-```
+ 1. From a different terminal, run the client and see the client output:
 
-If things go smoothly, you will see the `Greeter received: Hello world` in the
-client side output.
+    ```sh
+    $ ./greeter_client
+    Greeter received: Hello world
+    ```
 
 Congratulations! You've just run a client-server application with gRPC.
 
@@ -74,11 +173,11 @@ Congratulations! You've just run a client-server application with gRPC.
 Now let's look at how to update the application with an extra method on the
 server for the client to call. Our gRPC service is defined using protocol
 buffers; you can find out lots more about how to define a service in a `.proto`
-file in [What is gRPC?](/docs/guides/) and [gRPC Basics:
-C++](/docs/tutorials/basic/cpp/). For now all you 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 `HelloResponse` from the server, and that this method
-is defined like this:
+file in [What is gRPC?](/docs/guides) and [gRPC Basics:
+C++](/docs/tutorials/basic/cpp). For now all you 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 `HelloResponse` from the
+server, and that this method is defined like this:
 
 ```protobuf
 // The greeting service definition.
@@ -98,10 +197,8 @@ message HelloReply {
 }
 ```
 
-Let's update this so that the `Greeter` service has two methods. Edit
-`examples/protos/helloworld.proto` (from the root of the cloned repository) and
-update it with a new `SayHelloAgain` method, with the same request and response
-types:
+Edit [examples/protos/helloworld.proto][] and add a new `SayHelloAgain()` method, with the
+same request and response types:
 
 ```protobuf
 // The greeting service definition.
@@ -125,34 +222,36 @@ message HelloReply {
 
 Remember to save the file!
 
-### Generate gRPC code
+### Regenerate gRPC code
+
+Before you can use the new service method, you need to recompile the updated
+proto file.
 
-Next we need to update the gRPC code used by our application to use the new
-service definition. From the `examples/cpp/helloworld` directory:
+From the example **build** directory `examples/cpp/helloworld/cmake/build`, run:
 
 ```sh
-$ make
+$ make -j
 ```
 
 This regenerates `helloworld.pb.{h,cc}` and `helloworld.grpc.pb.{h,cc}`, which
-contains our generated client and server classes, as well as classes for
+contains the generated client and server classes, as well as classes for
 populating, serializing, and retrieving our request and response types.
 
 ### Update and run the application
 
-We now have new generated server and client code, but we still need to implement
+You have new generated server and client code, but you still need to implement
 and call the new method in the human-written parts of our example application.
 
 #### Update the server
 
-In the same directory, open `greeter_server.cc`. Implement the new method like
-this:
+Open `greeter_server.cc` from the example's root directory. Implement the new
+method like this:
 
 ```c++
 class GreeterServiceImpl final : public Greeter::Service {
   Status SayHello(ServerContext* context, const HelloRequest* request,
                   HelloReply* reply) override {
-     // ... (pre-existing code)
+     // ...
   }
 
   Status SayHelloAgain(ServerContext* context, const HelloRequest* request,
@@ -167,9 +266,9 @@ class GreeterServiceImpl final : public Greeter::Service {
 
 #### Update the client
 
-A new `SayHelloAgain` method is now available in the stub. We'll follow the same
-pattern as for the already present `SayHello` and add a new `SayHelloAgain`
-method to `GreeterClient`:
+A new `SayHelloAgain()` method is now available in the stub. We'll follow the
+same pattern as for the already present `SayHello()` and add a new
+`SayHelloAgain()` method to `GreeterClient`:
 
 ```c++
 class GreeterClient {
@@ -196,10 +295,9 @@ class GreeterClient {
       return "RPC failed";
     }
   }
-
 ```
 
-Finally, we exercise this new method in `main`:
+Finally, invoke this new method in `main()`:
 
 ```c++
 int main(int argc, char** argv) {
@@ -212,17 +310,17 @@ int main(int argc, char** argv) {
 
   return 0;
 }
-
 ```
 
 #### Run!
 
-Just like we did before, from the `examples/cpp/helloworld` directory:
+Run the client and server like you did before. Execute the following commands
+from the example **build** directory `examples/cpp/helloworld/cmake/build`:
 
  1. Build the client and server after having made changes:
 
     ```sh
-    $ make
+    $ make -j
     ```
 
  2. Run the server:
@@ -239,15 +337,23 @@ Just like we did before, from the `examples/cpp/helloworld` directory:
 
     You'll see the following output:
 
-    ```sh
+    ```nocode
     Greeter received: Hello world
     Greeter received: Hello again world
     ```
 
 ### What's next
 
-- Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides/)
-  and [gRPC Concepts](/docs/guides/concepts/).
-- Work through a more detailed tutorial in [gRPC Basics: C++](/docs/tutorials/basic/cpp/).
+- Read a full explanation of how gRPC works in [What is gRPC?](/docs/guides)
+  and [gRPC Concepts](/docs/guides/concepts).
+- Work through a more detailed tutorial in [gRPC Basics: C++](/docs/tutorials/basic/cpp).
 - Explore the gRPC C++ core API in its [reference
-  documentation](/grpc/cpp/).
+  documentation](/grpc/cpp).
+
+[examples/protos/helloworld.proto]: https://github.com/grpc/grpc/blob/{{< param grpc_release_tag >}}/examples/protos/helloworld.proto
+[github.com/google/protobuf/releases]: https://github.com/google/protobuf/releases
+[Installing CMake]: https://cmake.org/install
+[pb]: https://developers.google.com/protocol-buffers
+[proto3]: https://developers.google.com/protocol-buffers/docs/proto3
+[repo]: https://github.com/grpc/grpc/tree/{{< param grpc_release_tag >}}
+[using-grpc]: https://github.com/grpc/grpc/tree/master/src/cpp#to-start-using-grpc-c