templight

Templight 2.0 - Template Instantiation Profiler and Debugger

Templight is a Clang-based tool to profile the time and memory consumption of template instantiations and to perform interactive debugging sessions to gain introspection into the template instantiation process.

Disclaimer: Templight is still at a very preliminary state. We hope to get as much early adoption and testing as we can get, but be aware that we are still experimenting with the output formats and some of the behaviors.

Table of Contents

• Templight Profiler
• Templight Debugger
• Getting Started
• Getting and Compiling Templight
• Invoking Templight
• Using the Templight Profiler
• Default Output Location
• Using the Templight Debugger
• Using Blacklists
• Inspecting the profiles
• Credits

Templight Profiler

The templight profiler is intended to be used as a drop-in substitute for the clang compiler (or one of its variants, like clang-cl) and it performs a full compilation, honoring all the clang compiler options, but records a trace (or history) of the template instantiations performed by the compiler for each translation unit.

The profiler will record a time-stamp when a template instantiation is entered and when it is exited, which is what forms the compilation-time profile of the template instantiations of a translation unit. The total memory consumption can also be recorded at these points, which will skew the time profiles, but provide a profile of the memory consumed by the compiler during the template instantiations.

The profiler is enabled by the templight option -profiler, and it supports the following additional templight options:

• -stdout - Output template instantiation traces to standard output (mainly for piping / redirecting purposes). Warning: you need to make sure the source files compile cleanly, otherwise, the output will be corrupted by warning or error messages.
• -memory - Profile the memory usage during template instantiations.
• -safe-mode - Output Templight traces without buffering, not to lose them at failure (note: this will distort the timing profiles due to file I/O latency).
• -ignore-system - Ignore any template instantiation located in system-includes (-isystem), such as from the STL.
• -output= - Write Templight profiling traces to . By default, it outputs to "current_source.cpp.trace.pbf" or "current_source.cpp.memory.trace.pbf" (if -memory is used).
• -blacklist= - Specify a blacklist file that lists declaration contexts (e.g., namespaces) and identifiers (e.g., std::basic_string) as regular expressions to be filtered out of the trace (not appear in the profiler trace files). Every line of the blacklist file should contain either "context" or "identifier", followed by a single space character and then, a valid regular expression.

Templight Debugger

The templight interactive debugger is also a drop-in substitute for the clang compiler, honoring all its options, but it will interrupt the compilation with a console prompt (stdin). The operations of the templight debugger are modeled after the GDB debugger and essentially works the same, with most commands being the same, but instead of stepping through the execution of the code (in GDB), it steps through the instantiation of the templates.

In short, the templight debugger is to template meta-programming what GDB is to regular code.

The debugger is enabled by the templight option -debugger, and it supports the following additional templight options:

• -ignore-system - Ignore any template instantiation located in system-includes (-isystem), such as from the STL.
• -blacklist= - Specify a blacklist file that lists declaration contexts (e.g., namespaces) and identifiers (e.g., std::basic_string) as regular expressions to be ignored by the debugger. Every line of the blacklist file should contain either "context" or "identifier", followed by a single space character and then, a valid regular expression.

NOTE: Both the debugger and the profiler can be used together. Obviously, if compilation is constantly interrupted by the interactive debugger, the time traces recorded by the profiler will be meaningless. Nevertheless, running the profiler during debugging will have the benefit of recording the history of the template instantiations, for later review, and can also record, with reasonably accuracy, the memory consumption profiles.

Getting Started

Getting and Compiling Templight

Templight must be compiled from source, alongside the Clang source code.

1. Follow the instructions from LLVM/Clang to get a local copy of the Clang source code.

2. Clone the templight repository into the clang directories, as follows:

  (from top-level folder)
  $ cd clang/tools
  $ mkdir templight
  $ git clone  templight

1. Add the templight subdirectory to CMake:

  (from top-level folder)
  $ cd clang/tools
  $ echo "add_clang_subdirectory(templight)" >> CMakeLists.txt

1. (Re-)Compile LLVM / Clang: (same as the corresponding step in LLVM/Clang instructions)

  (from top-level folder)
  $ mkdir build
  $ cd build
  $ cmake -DLLVM_ENABLE_PROJECTS=clang ../llvm/
  $ make

1. If successful, there should be a templight and a templight++ executable in the build/bin folder.

NOTE: You do not need to apply the patch templight_clang_patch.diff and you can ignore the corresponding version numbers in templight_clang_version.txt. Those are meant for other uses case (testing some hooks within clang).

Invoking Templight

Templight is designed to be a drop-in replacement for the clang compiler. This is because in order to correctly profile the compilation, it must run as the compiler would, honoring all compilation options specified by the user.

Because of this particular situation, the options for templight must be specially marked with -Xtemplight to distinguish them from other Clang options. The general usage goes like this:

  $ templight++ [[-Xtemplight [templight-option]]|[clang-option]] 

Or, for the MSVC-compatible version of templight (analoguous to clang-cl) use as follows:

  $ templight-cl [[-Xtemplight [templight-option]]|[clang-option]] 
(OR)
  > templight-cl.exe [[-Xtemplight [templight-option]]|[clang-option]] 

For example, if we have this simple command-line invocation of clang:

  $ clang++ -Wall -c some_source.cpp -o some_source.o

The corresponding templight profiler invocation, with options -memory and -ignore-system would look like this:

  $ templight++ -Xtemplight -profiler -Xtemplight -memory -Xtemplight -ignore-system -Wall -c some_source.cpp -o some_source.o

Note that the order in which the templight-options appear is not important, and that clang options can be interleaved with templight-options. However, every single templight-option must be immediately preceeded with -Xtemplight.

As can be seen from that simple example, one can easily substitude the clang command (e.g., clang++) with a compound templight invocation (e.g., templight++ -Xtemplight -profiler -Xtemplight -memory) and thus, leave the remainder of the command-line intact. That is how templight can be used as a drop-in replacement for clang in any given project, build script or an IDE's build configuration.

If you use CMake and Clang with the following common trick:

  $ export CC=/path/to/llvm/build/bin/clang
  $ export CXX=/path/to/llvm/build/bin/clang++
  $ cmake 

Then, templight could be swapped in by the same trick:

  $ export CC="/path/to/llvm/build/bin/templight -Xtemplight -profiler -Xtemplight -memory"
  $ export CXX="/path/to/llvm/build/bin/templight++ -Xtemplight -profiler -Xtemplight -memory"
  $ cmake 

But be warned that the cmake scripts will not fully recognize this compiler, and therefore, you might have to make small changes in the CMake files to be able to handle it. Up to now, experience with building complete cmake projects with templight has been very successful as cmake essentially recognizes templight as a "Clang" compiler and applies the appropriate configuration. There were, however, a few minor issues found that were easily circumvented on a case-by-case basis, and so, be warned that this might not work perfectly on the first try. If anyone is interested in creating some CMake modules to deal with templight specifically, please contact the maintainer, such modules would be more than welcomed. Also, any feedback on your experience working with templight on a large project would be much appreciated.

Using the Templight Profiler

The templight profiler is invoked by specifying the templight-option -profiler. By default, if no other templight-option is specified, the templight profiler will output only time profiling data and will output to one file per input source file and will append the extension .trace.pbf to the output filename (object file output).

For example, running the following:

  $ templight++ -Xtemplight -profiler -c some_source.cpp

will produce a file called some_source.o.trace.pbf in the same directory as some_source.cpp.

It is, in general, highly recommended to use the -ignore-system option for the profiler (and debugger too) because instantiations from standard or third-party libraries can cause significant noise and dramatically increase the size of the trace files produced. If libraries like the STL or most of Boost libraries are used, it is likely that most of the traces produced relate to those libraries and not to your own. Therefore, it is recommended to use -isystem when specifying the include directories for those libraries and then use the -ignore-system templight-option when producing the traces.

Warning: Trace files produced by the profiler can be very large, especially in template-heavy code. So, use this tool with caution. It is not recommended to blindly generate templight trace files for all the source files of a particular project (e.g., using templight profiler in place of clang in a CMake build tree). You should first identify specific parts of your project that you suspect (or know) lead to template instantiation problems (e.g., compile-time performance issues, or actual bugs or failures), and then create a small source file that exercises those specific parts and produce a templight trace for that source file.

Default Output Location

The location and names of the output files for the templight traces needs some explanation, because it might not always be straight-forward. The main problem here is that templight is meant to be used as a drop-in replacement for the compiler (and it actually compiles the code, exactly as the vanilla Clang compiler does it). The problem is that you can invoke a compiler in many different ways. On typical small tests, you would simply invoke the compiler on a single source file and produce either an executable or an object file. In other case, you might invoke it with a list of source files to produce either an executable or a library. And for "real" projects, a build system will generally invoke the compiler for each source file, producing an object file each time, and later invoking the linker separately.

Templight must find a reasonable place to output its traces in all those cases, and often, specifying an output location with -output does not really solve the problem (like this problem: multiple source files, one output location?). The only really straight-forward case is with the -stdout option, where the traces are simply printed out to the standard output (presumably to be pipe