In the C++ world, there's no universally accepted standard for managing project dependencies. You need to build and install gRPC before building and running this quick start's Hello World example.

The steps in the section explain how to build and locally install gRPC and Protocol Buffers using cmake. If you'd rather use bazel, see Building from source.

Choose a directory to hold locally installed packages. This page assumes that the environment variable MY_INSTALL_DIR holds this directory path. For example:

• Linux / macOS

export MY_INSTALL_DIR=$HOME/.local

Ensure that the directory exists:

mkdir -p $MY_INSTALL_DIR

Add the local bin folder to your path variable, for example:

export PATH="$MY_INSTALL_DIR/bin:$PATH"

• Windows

set MY_INSTALL_DIR=%USERPROFILE%\cmake

Ensure that the directory exists:

mkdir %MY_INSTALL_DIR%

Add the local bin folder to your path variable, for example:

set PATH=%PATH%;$MY_INSTALL_DIR\bin

You need version {{< param cmake-min-version >}} or later of cmake. Install it by following these instructions if you don't have it:

• Linux

  sudo apt install -y cmake

• macOS:

  brew install cmake

• Windows:

  choco install cmake

• For general cmake installation instructions, see [Installing CMake][].

Check the version of cmake:

cmake --version
cmake version {{< param cmake-version >}}

Under Linux, the version of the system-wide cmake can often be too old. You can install a more recent version into your local installation directory as follows:

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

Install the basic tools required to build gRPC:

• Linux

  sudo apt install -y build-essential autoconf libtool pkg-config

• macOS:

  brew install autoconf automake libtool pkg-config

Clone the grpc repo and its submodules:

git clone --recurse-submodules -b {{< param grpc_vers.core >}} --depth 1 --shallow-submodules https://github.com/grpc/grpc

While not mandatory, gRPC applications usually leverage [Protocol Buffers][pb] for service definitions and data serialization, and the example code uses [proto3][].

The following commands build and locally install gRPC and Protocol Buffers:

• Linux & macOS

  cd grpc
  mkdir -p cmake/build
  pushd cmake/build
  cmake -DgRPC_INSTALL=ON \
        -DgRPC_BUILD_TESTS=OFF \
        -DCMAKE_CXX_STANDARD=17 \
        -DCMAKE_INSTALL_PREFIX=$MY_INSTALL_DIR \
        ../..
  make -j 4
  make install
  popd

• Windows

  mkdir "cmake\build"
  pushd "cmake\build"
  cmake -DgRPC_INSTALL=ON -DgRPC_BUILD_TESTS=OFF -DCMAKE_CXX_STANDARD=17 -DCMAKE_INSTALL_PREFIX=%MY_INSTALL_DIR% ..\..
  cmake --build . --config Release --target install -j 4
  popd

{{% alert title="Important" color="warning" %}} We strongly encourage you to install gRPC locally — using an appropriately set CMAKE_INSTALL_PREFIX — because there is no easy way to uninstall gRPC after you've installed it globally. {{% /alert %}}

More information:

• You can find a complete set of instructions for building gRPC C++ in Building from source.
• For general instructions on how to add gRPC as a dependency to your C++ project, see [Start using gRPC C++][using-grpc].

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:

   cd examples/cpp/helloworld

2. Build the example using cmake:

   • Linux & macOS

     mkdir -p cmake/build
     pushd cmake/build
     cmake -DCMAKE_PREFIX_PATH=$MY_INSTALL_DIR ../..
     make -j 4

   • Windows

     mkdir "cmake\build"
     pushd "cmake\build"
     cmake -DCMAKE_INSTALL_PREFIX=%MY_INSTALL_DIR% ..\..
     cmake --build . --config Release -j 4
     popd

   {{% alert title="Note" color="info" %}} Getting build failures? Most issues, at this point, are the result of a faulty installation. Make sure you have the right version of cmake, and carefully recheck your installation. {{% /alert %}}

Run the example from the example build directory examples/cpp/helloworld/cmake/build:

1. Run the server:

   ./greeter_server

2. From a different terminal, run the client and see the client output:

   ./greeter_client
   Greeter received: Hello world

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 Introduction to gRPC and Basics tutorial. 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 HelloReply from the server, and that this method is defined like this:

// The greeting service definition.
service Greeter {
  // Sends a greeting
  rpc SayHello (HelloRequest) returns (HelloReply) {}
}

// The request message containing the user's name.
message HelloRequest {
  string name = 1;
}

// The response message containing the greetings
message HelloReply {
  string message = 1;
}

Open [examples/protos/helloworld.proto][] and add a new SayHelloAgain() method, with the same request and response types:

// The greeting service definition.
service Greeter {
  // Sends a greeting
  rpc SayHello (HelloRequest) returns (HelloReply) {}
  // Sends another greeting
  rpc SayHelloAgain (HelloRequest) returns (HelloReply) {}
}

// The request message containing the user's name.
message HelloRequest {
  string name = 1;
}

// The response message containing the greetings
message HelloReply {
  string message = 1;
}

Remember to save the file!

Before you can use the new service method, you need to recompile the updated proto file.

From the example build directory examples/cpp/helloworld/cmake/build, run:

• Linux & macOS

make -j 4

• Windows

cmake --build . --config Release -j 4

This regenerates helloworld.pb.{h,cc} and helloworld.grpc.pb.{h,cc}, which contains the generated client and server classes, as well as classes for populating, serializing, and retrieving our request and response types.

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.

Open greeter_server.cc from the example's root directory. Implement the new method like this:

class GreeterServiceImpl final : public Greeter::Service {
  Status SayHello(ServerContext* context, const HelloRequest* request,
                  HelloReply* reply) override {
     // ...
  }

  Status SayHelloAgain(ServerContext* context, const HelloRequest* request,
                       HelloReply* reply) override {
    std::string prefix("Hello again ");
    reply->set_message(prefix + request->name());
    return Status::OK;
  }
};

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:

class GreeterClient {
 public:
  // ...
  std::string SayHello(const std::string& user) {
     // ...
  }

  std::string SayHelloAgain(const std::string& user) {
    // Follows the same pattern as SayHello.
    HelloRequest request;
    request.set_name(user);
    HelloReply reply;
    ClientContext context;

    // Here we can use the stub's newly available method we just added.
    Status status = stub_->SayHelloAgain(&context, request, &reply);
    if (status.ok()) {
      return reply.message();
    } else {
      std::cout << status.error_code() << ": " << status.error_message()
                << std::endl;
      return "RPC failed";
    }
  }

Finally, invoke this new method in main():

int main(int argc, char** argv) {
  // ...
  std::string reply = greeter.SayHello(user);
  std::cout << "Greeter received: " << reply << std::endl;

  reply = greeter.SayHelloAgain(user);
  std::cout << "Greeter received: " << reply << std::endl;

  return 0;
}

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:

   • Linux & macOS

   make -j 4

   • Windows

   cmake --build . --config Release -j 4

2. Run the server:

   ./greeter_server

3. On a different terminal, run the client:

   ./greeter_client

   You'll see the following output:

   Greeter received: Hello world
   Greeter received: Hello again world
   

{{% alert title="Note" color="info" %}} Interested in an asynchronous version of the client and server? You'll find the greeter_async_{client,server}.cc files in the example's source directory.

{{% /alert %}}

• Learn how gRPC works in Introduction to gRPC and Core concepts.
• Work through the Basics tutorial.
• Explore the API reference.

[examples/protos/helloworld.proto]: https://github.com/grpc/grpc/blob/{{< param grpc_vers.core >}}/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://protobuf.dev/programming-guides/proto3 [repo]: https://github.com/grpc/grpc/tree/{{< param grpc_vers.core >}} [using-grpc]: https://github.com/grpc/grpc/tree/master/src/cpp#to-start-using-grpc-c