Example Usage

These steps walk through the actions required to go from a raw .proto file to a C++ library. Other languages will have a similar high-level layout, but you should check the language specific pages too.

The full example workspaces for C++ can be found here, along with the demo proto files here. Example workspaces for all other languages can also be found in that same directory.

Step 1: Load rules_proto_grpc

First, follow the instructions to load the rules_proto_grpc rules in your WORKSPACE file.

Step 2: Write a .proto file

Write a protobuf .proto file, following the specification. In this case, we’ve called the file thing.proto.

syntax = "proto3";

package example;

import "google/protobuf/any.proto";

message Thing {
    string name = 1;
    google.protobuf.Any payload = 2;
}

Step 3: Write a BUILD file

This file should introduce a proto_library target:

proto_library(
    name = "thing_proto",
    srcs = ["thing.proto"],
    deps = ["@com_google_protobuf//:any_proto"],
)

This rule takes no visible action, but is used to group a set of related .proto files and their dependencies. In this example we have a dependency on a well-known type any.proto, hence the proto_library to proto_library dependency ("@com_google_protobuf//:any_proto")

Step 4: Add a cpp_proto_compile target

We now add a target using the cpp_proto_compile rule. This rule converts our .proto file into the C++ specific .h and .cc files.

Note

In this example thing.proto does not include service definitions (gRPC). For protos with services, use the cpp_grpc_compile rule instead.

# BUILD.bazel
load("@rules_proto_grpc//cpp:defs.bzl", "cpp_proto_compile")

cpp_proto_compile(
    name = "cpp_thing_proto",
    protos = [":thing_proto"],
)

Step 5: Load the WORKSPACE macro

But wait, before we can build this, we need to load the dependencies necessary for this rule in our WORKSPACE (see cpp_proto_compile):

# WORKSPACE
load("@rules_proto_grpc//cpp:repositories.bzl", "cpp_repos")

cpp_repos()

Step 6: Build it!

We can now build the cpp_thing_proto target:

$ bazel build //example/proto:cpp_thing_proto
Target //example/proto:cpp_thing_proto up-to-date:
  bazel-genfiles/example/proto/cpp_thing_proto/example/proto/thing.pb.h
  bazel-genfiles/example/proto/cpp_thing_proto/example/proto/thing.pb.cc

You should now see generated .cc and .h files in your bazel-bin output tree.

Step 7: Create a library

If we were only interested in the generated files, the cpp_grpc_compile rule would be fine. However, for convenience we’d rather have the outputs compiled into a C++ library with the necessary dependencies linked. To do that, let’s change the rule from cpp_proto_compile to cpp_proto_library:

# BUILD.bazel
load("@rules_proto_grpc//cpp:defs.bzl", "cpp_proto_library")

cpp_proto_library(
    name = "cpp_thing_proto",
    protos = [":thing_proto"],
)

Now we can build again:

$ bazel build //example/proto:cpp_thing_proto
Target //example/proto:cpp_thing_proto up-to-date:
  bazel-bin/example/proto/libcpp_thing_proto.a
  bazel-bin/example/proto/libcpp_thing_proto.so
  bazel-genfiles/example/proto/cpp_thing_proto/example/proto/thing.pb.h
  bazel-genfiles/example/proto/cpp_thing_proto/example/proto/thing.pb.cc

This time, we also have .a and .so files built. We can now use //example/proto:cpp_thing_proto as a dependency of any other cc_library or cc_binary target as per normal.

Note

The cpp_proto_library target implicitly calls cpp_proto_compile, and we can access that rule’s by adding _pb at the end of the target name, like bazel build //example/proto:cpp_thing_proto_pb