Templight

A C++ Template Metaprogram Debugger and Profiler

Introduction

Welcome to the website of Templight. This is a clang patch which makes the compiler capable of tracing template instantiations.
You may also be interested in Templar and ProfileDataViewer client tools. These GUI applications let you analyse the content of the trace file.
A Youtube video from C++Now 2013, Aspen, Co on debugging and profiling C++ template metaprograms by Zoltán Porkoláb.

News

• 2014 Dec 6: Metashell has been presented by Ábel Sinkovics and András Kucsma in the talk Interactive Metaprogramming Shell Based on Clang at MeetingC++ in Berlin. Link to the abstract and slides. Video on the talk will be available soon.
• 2014 Dec 2: Metashell - a gdb-like interactive template metaprogram debugger from Ábel Sinkovics and András Kucsma is available at https://github.com/sabel83/metashell. Metashell is based on Templight.
• 2014 Mar 12: Mikael Persson refactored Templight for make it more modular and less intrusive on the Sema class. http://comments.gmane.org/gmane.comp.compilers.clang.devel/35656
• 2014 Jan 22: clang 3.5 (trunk 199501) patch is available. This should work on clang 3.4 release.
• 2013 Dec 20: Martin Schulze created a modified Templar version working with Qt4/5 and Graphviz 2.34.0 (using CGraph). https://github.com/schulmar/Templar.

Download

Some repository soon will be available. Until then:

• 2015 Apr 10: clang 3.6 patch templight-20150410.tar.gz This should work on clang 3.6 release.
• 2014 Jan 22: clang 3.5 (trunk 199501) patch templight-20140122.tar.gz This should work on clang 3.4 release.
• 2013 Jul 18: clang 3.3 patch templight-20130718.tar.gz
• 2013 May 06: clang 3.2 patch templight-20130506.tar.gz
• 2013 May 06: client tools templar-20130506.tar.gz

Getting started

First you have to download the templight patch appropriate to the clang version you want to use. Currently we support clang version 3.2 and 3.3.
To download and build clang see Getting Started: Building and Running Clang. Note also that Python is needed for running the test suite. Get it at: http://www.python.org/download

Checkout LLVM:

• Change directory to where you want the llvm directory placed.
• svn co http://llvm.org/svn/llvm-project/llvm/branches/release_32 llvm

• cd llvm/tools
• svn co http://llvm.org/svn/llvm-project/cfe/branches/release_32 clang
• cd ../..

• cd llvm/tools/clang/tools
• svn co http://llvm.org/svn/llvm-project/clang-tools-extra/branches/release_32 extra
• cd ../../../..

• cd llvm/projects
• svn co http://llvm.org/svn/llvm-project/compiler-rt/branches/release_32 compiler-rt
• cd ../..

• cd llvm/tools/clang
• patch -p0 -i /PATH/TO/PATCH/templight_clang32.diff
• cd ../../..

• mkdir build (for building without polluting the source dir)
• cd build
• ../llvm/configure
• make

How to use

Now you can trace the template instantiations and memoizations during compilation. Doing so you have to add the -templight compiler switch to your build command.

Since patch templight-20140122.tar.gz

• -templight

Flag for tracing template instantiations

• -templight-format format

Format of Templight output file (yaml/xml/text, default is yaml)

• -templight-memory

Flag for tracing memory usage during template instantiations

• -templight-output file

Write Templight output to file

• -templight-safe-mode

For flushing Templight trace immediately instead of store the trace in a buffer. This can lead to greater distortion but can be useful when the compiler crashes.

• -templight-stdout

Tracing template instantiations to standard output. You can use templight as a unix filter when use this flag together with -templight-safe-mode.

• -trace-capacity capacity

Set the capacity of internal template trace buffer. The default value is 500.000 events. To minimize distortion Templight does not increase internal buffer during execution.

Command line parameters for earlier patches (clang 3.3 and clang 3.2)

• clang++ -templight foo.cpp

After that you will have a foo.cpp.trace.xml next to foo.cpp. We call this XML file a trace file, and it is not really meant for human readers.

If you are interested in the memory usage of the compiler during template actions, you can use the following command:

• clang++ -templight-memory foo.cpp

Notice that now you will get a foo.cpp.memory.trace.xml file next to foo.cpp. The scheme is the same but this XML contains the number of dynamically allocated bytes of the compiler at each trace entry.

By default, the trace can contain 500.000 trace events. If it is not enough, you can increase this number:

• clang++ -templight -trace-capacity 1000000 templateHeavyCode.cpp

Trace files are not meant for human readers. We also have GUI tools for analysing the contents of a trace file.

Templar

It is our main tool for template debugging. You can analyse the instantiations step-by-step, can set up breakpoints, filter out the irrelevant instantiations, etc.

requirements: Qt 4.6 or newer, Graphviz 2.28.0

It is a Qt-based project. To build it you must enter the directory where the Templar.pro project file is:

• qmake
• make

Templar does not work with newer versions of Graphviz. Martin Schulze created a modified Templar version working with Qt4/5 and Graphviz 2.34.0 (using CGraph). https://github.com/schulmar/Templar.

ProfileDataViewer

It is a proof-of-concept program to view the profiling results. Later it will be integrated in to an other tool. You can analyse the time measurements data with this program.

requirements: Qt 4.6 or newer

It is a Qt-based project. To build it you must enter the directory where the Qt project file is:

• qmake
• make

Third-party tools

The trace generated by templight is an ideal base for implementing your own tools. If you have one, please contact us, we are happy to refer your tool.

• Abel Sinkovics implemented a nice python-based toolset working on Templight trace file. See details at https://github.com/sabel83/templight

Contact

• Zoltán Borók-Nagy: boroknagyz gmail
• Zoltán Porkoláb: gsd at elte dot hu
• József Mihalicza: jmihalicza gmail

Last updated 2013-05-15 11:27:25 CET