synth
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):
Usage
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 (compilation_commands.json
) in <dbdir>
. See
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).
In --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
it.
synth will execute all given commands (except in --db
mode it only executes
commands without filename or with a filename that is under some <inroot>
).
For each file encountered (including all #include
d files) it produces an
output file only if the file is in some <inroot>
. The output file will then
be written as <outroot>/<relpath>.html
where <outroot>
is the one given
next to the matching <inroot>
and <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--cmd
mode. -
-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<code>
or<pre>
tags.@@filename@@
: The name of the input file, relative to the matched<inroot>
.@@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@@rotdir@@/code.css
stylesheet.
-
-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--db
mode. -
--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 specify0
, no IDs will be generated and everything will be linked by line number. The default maximum size is 128 bytes.
Example
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 my-repo-builddir/
,
generating output for files under my-repo/
to my-repo-html/
and for
files under /usr/include/
to my-repo-html/include
. E.g. a file
my-repo/src/main.cpp
will be processed to my-repo-html/src/main.cpp
and /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).
Highlighting
The highlighting classes are the same ones that
Pygments uses. Additionally the CSS classes decl
and
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 nf
(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 colorful
style
where only declarations and definitions are bold.
Building
- 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.
make
ormsbuild synth.sln
. If you have a not too ancient CMake you can just usecmake --build .
.
License
This project is licensed under the MIT license. See LICENSE.txt