C++ and Bazel

This page contains resources that help you use Bazel with C++ projects. It links to a tutorial, build rules, and other information specific to building C++ projects with Bazel.

Working with Bazel

The following resources will help you work with Bazel on C++ projects:

• Tutorial: Building a C++ project
• C++ common use cases
• C/C++ rules
• Essential Libraries
  • Abseil
  • Boost
  • HTTPS Requests: CPR and libcurl
• C++ toolchain configuration
• Tutorial: Configuring C++ toolchains
• Integrating with C++ rules

Best practices

In addition to general Bazel best practices, below are best practices specific to C++ projects.

BUILD files

Follow the guidelines below when creating your BUILD files:

• Each BUILD file should contain one cc_library rule target per compilation unit in the directory.

• You should granularize your C++ libraries as much as possible to maximize incrementality and parallelize the build.

• If there is a single source file in srcs, name the library the same as that C++ file's name. This library should contain C++ file(s), any matching header file(s), and the library's direct dependencies. For example:

  cc_library(
      name = "mylib",
      srcs = ["mylib.cc"],
      hdrs = ["mylib.h"],
      deps = [":lower-level-lib"]
  )
  

• Use one cc_test rule target per cc_library target in the file. Name the target [library-name]_test and the source file [library-name]_test.cc. For example, a test target for the mylib library target shown above would look like this:

  cc_test(
      name = "mylib_test",
      srcs = ["mylib_test.cc"],
      deps = [":mylib"]
  )
  

Include paths

Follow these guidelines for include paths:

• Make all include paths relative to the workspace directory.

• Use quoted includes (#include "foo/bar/baz.h") for non-system headers, not angle-brackets (#include <foo/bar/baz.h>).

• Avoid using UNIX directory shortcuts, such as . (current directory) or .. (parent directory).

• For legacy or third_party code that requires includes pointing outside the project repository, such as external repository includes requiring a prefix, use the include_prefix and strip_include_prefix arguments on the cc_library rule target.

Toolchain features

The following optional features can improve the hygiene of a C++ project. They can be enabled using the --features command-line flag or the features attribute of repo, package or cc_* rules:

• The parse_headers feature makes it so that the C++ compiler is used to parse (but not compile) all header files in the built targets and their dependencies when using the --process_headers_in_dependencies flag. This can help catch issues in header-only libraries and ensure that headers are self-contained and independent of the order in which they are included.
• The layering_check feature enforces that targets only include headers provided by their direct dependencies. The default toolchain supports this feature on Linux with clang as the compiler.