A semantic syntax highlighting and code hyper-linking tool for C and C++. It is written in C++ and based on libclang, Clang's C-Interface.
An example of what it generates is its output when run on itself (note that the
directory listing was not generated with synth itself but with the
dir2html.py script run on the output):
synth is a commandline-tool with the following usage syntax:
synth <OPTIONS> (<inroot> [-o <outroot>])... (--db <dbdir>|--cmd <cmd>)
synth has two usage modes: In
--db mode it expects a directory with a Clang
compilation database (
http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html for how to create
such a file for your project (it's trivial if you already use CMake with Clang).
--cmd mode a full clang command line is passed e.g.
--cmd /usr/bin/clang++ myfile.cpp -I ~/my/include/dir. It is important that
the clang path is correct because certain include files are searched relative to
synth will execute all given commands (except in
--db mode it only executes
commands without filename or with a filename that is under some
For each file encountered (including all
#included files) it produces an
output file only if the file is in some
<inroot>. The output file will then
be written as
<outroot> is the one given
next to the matching
<relpath> is the path of the file
relative to the matched
<inroot> (if multiple
<inroot>s match, the first
one is used).
These options are allowed:
-j <n>: Use
<n>threads. If the option is omitted, the number of CPU cores is used (same when
<n>is zero). Ignored in
-t <templatefile>: Use the
<templatefile>as output-template. All outputs will be formatted according to this file. The following replacements are made:
@@code@@: The highlighted code (without any surrounding
@@filename@@: The name of the input file, relative to the matched
@@rootdir@@: A relative path to the output root. If multiple
<outroot>s are given and their common prefix is under the current working directory, that common prefix is used as output root for all files. Otherwise each file simply has the
<outroot>of the matched
<inroot>as its output root. This is useful e.g. to link to a CSS-file. By default, synth will use a minimal HTML5 template with the filename as
<title>and referencing a
-e <arg>: Can be given multiple times.
<arg>will be appended to the arguments passed to clang. E.g. to specify an additional include directory use
-e -I -e ~/my/include/dir. Useful in
--doxytags <doxytagfile> <baseurl>: Can be given multiple times. Reads in the Doxygen tag file
<doxytagfile>and tries to link tokens to their Doxygen documentation. synth will only try to link tokens to their documentation if they would not be otherwise linked directly to their declaration/definition in source. Additionally, synth will add documentation links to definitions (those would not normally be linked to source code because they don't refer to anything).
An interesting example Doxygen tagfile is the one for the C++ standard library available at http://en.cppreference.com/w/Cppreference:Archives#Doxygen_tag_file.
--max-id-sz <n>: By default, synth will try to link entities by name instead of by line number if possible. However, this makes the HTML files bigger and synth itself slower and more memory hungry. Especially for C++ functions with many parameters the IDs can get ridiculously long. With this option you can control the maximum size (in bytes) of the IDs used. If you specify
0, no IDs will be generated and everything will be linked by line number. The default maximum size is 128 bytes.
synth my-repo/ -o my-repo-html/ /usr/include/ -o my-repo-html/include \ --db my-repo-builddir/
Process all commands of the compilation-database under
generating output for files under
my-repo-html/ and for
my-repo-html/include. E.g. a file
my-repo/src/main.cpp will be processed to
/usr/include/math.h will be processed to
my-repo-html/include/math.h. If e.g. a file
/usr/local/include/boost/filesystem.hpp was also included, it would not be
processed by synth (it will still be parsed though as this is necessary for
highlighting files that use it).
The highlighting classes are the same ones that
Pygments uses. Additionally the CSS classes
def are given to declarations and definitions respectively (tokens that are
both get both classes). Note that most Pygments styles seem to assume that
classes such as
Name.Function) are only emitted for function
declarations/definitions but synth also highlights usages. This is the reason
for the included
code.css style which is a version of the
where only declarations and definitions are bold.
- Clone or download the repository
- Set up dependencies (Boost 1.60 and libclang 3.7+ (tested with 3.8), a C++14 compiler (tested with clang).
- Create a build directory and from there run
cmake <path to repo root>.
- Run your build tool on the generated build files e.g.
msbuild synth.sln. If you have a not too ancient CMake you can just use
cmake --build ..
This project is licensed under the MIT license. See LICENSE.txt