Envoy Clang Libtooling developer tools

Overview

A number of tools live in this directory that are intended for use by Envoy developers (and potentially CI). These are host tools and should not be linked into the Envoy target. They are based around Clang's libtooling libraries, a C++ framework for writing Clang tools in the style of clang-format and clang-check.

Building and running

To build tools in this tree, a Clang binary install must be available. If you are building Envoy with clang, this should already be true of your system. You can find prebuilt binary releases of Clang at https://releases.llvm.org. You will need the Clang version used by Envoy in CI (currently clang-10.0).

To build a tool, set the following environment variable:

export LLVM_CONFIG=<path to clang installation>/bin/llvm-config

Assuming that CC and CXX already point at Clang, you should be able to build with:

bazel build @envoy_dev//clang_tools/syntax_only

To run libtooling based tools against Envoy, you will need to first generate a compilation database, which tells the tool how to take a source file and locate its various dependencies. The tools/gen_compilation_database.py script generates this and also does setup of the Bazel cache paths to allow external dependencies to be located:

tools/gen_compilation_database.py --include_headers

Finally, the tool can be run against source files in the Envoy tree:

bazel-bin/external/envoy_dev/clang_tools/syntax_only/syntax_only \
  source/common/common/logger.cc

Adding a new Envoy libtooling based tool

Follow the example at tools/clang_tools/syntax_only, based on the tutorial example at https://clang.llvm.org/docs/LibTooling.html. Please use the envoy_clang_tools_cc_binary Bazel macro for the tool, this disables use of RTTI/exceptions and allows developer tools to be structurally excluded from the build as needed.