Tartan: a Clang analysis plugin for GLib and GNOME

Tartan is a plugin for the Clang static analyser and C compiler which adds tighter support for GLib and GNOME, introducing extra checks and warnings when compiling C code which uses GLib. It was formerly known as ‘gnome-clang’, but renamed to be less GNOME-centric.

If you want to get started using Tartan with JHBuild:

  1. Download and install the plugin.
  2. Set it up with JHBuild.

The plugin works by loading gobject-introspection metadata for all functions it encounters (both functions exported by the code being compiled, if it is a library; and functions called by it). This metadata is then used to add compiler attributes to the code, such as non-NULL attributes, which the compiler can then use for static analysis and emitting extra compiler warnings.

The plugin also detects common coding practices for code which uses GLib, such as the use of g_return_if_fail() to describe function preconditions, and uses this to add extra compiler attributes.

Tartan is licenced under the GPLv3+.

Download and installation

Tarballs for released versions of Tartan are on the releases page. All have been signed with key 4B2EAFA0 (Philip Withnall). Versions 0.2.0 and older were released under the name ‘gnome-clang’.

Compilation follows the standard automake process:

tar -xJf ./tartan-$VERSION.tar.xz
cd ./tartan-$VERSION
./configure --prefix=$PREFIX
make
make install

Alternatively, JHBuild may be used directly (e.g. after cloning the git repository):

cd ./tartan
jhbuild make

To enable debug output from the plugin itself, pass --enable-debug to the configure script.

This will install the Tartan plugin, a dynamically loadable library, in $PREFIX/lib/tartan/$LLVM_VERSION/libtartan.so.

Usage

Tartan can be used as a standalone plugin with the Clang static analyser, or can be integrated with JHBuild to be automatically run on all C source code compiled using JHBuild (this is the recommended method of using Tartan).

In both cases, all GIR typelibs installed on the system will be loaded automatically.

Usage with JHBuild

JHBuild has in-built support for compiling with the scan-build wrapper, a script which comes with Clang to allow projects to be statically analysed in parallel with compilation (and without requiring Clang to be used for compilation itself). To enable this using Tartan, add the following lines to ~/.jhbuildrc:

static_analyzer = True
static_analyzer_template = 'tartan-build -v -o %(outputdir)s/%(module)s

where tartan-build is a wrapper script for Clang which loads and enables the Tartan plugin. It can be used both installed ($JHBUILD_PREFIX/bin/tartan) or uninstalled (/path/to/tartan/source/scripts/tartan).

The scan-build wrapper can be used instead to use the Clang static analyzer without Tartan:

static_analyzer = True
static_analyzer_template = 'scan-build -v -o %(outputdir)s/%(module)s

This will enable static analysis of C code compiled with JHBuild, but will not enable GLib-specific warnings.

Standalone usage

Automatic wrapper script

The easiest way to use Tartan standalone is with the scan-build script which comes with Clang. Tartan provides a wrapper script, tartan-build, which passes the right arguments to scan-build:

tartan-build -v ./autogen.sh
tartan-build -v make

where ./autogen.sh is the command to configure your project and make builds it.

You can think of tartan-build as setting the CC environment variable to use the static analyser, so that autogen.sh picks that up.

The tartan script can be used installed or uninstalled, straight from the Tartan source directory.

Directly with Clang

To use Tartan with the Clang static analyser directly, use the tartan wrapper script by itself. The old command

clang -cc1 -analyze -std=c89 $system_includes my-project/*.c

becomes:

tartan -cc1 -analyze -std=c89 $system_includes my-project/*.c

which wraps the normal Clang compiler and automatically loads the correct plugin. The system includes should be set using:

system_includes=`echo | cpp -Wp,-v 2>&1 | \
grep '^[[:space:]]' | sed -e 's/^[[:space:]]*/-isystem/' | \
tr "\n" ' '`

You should also specify your project’s include flags, for example using pkg-config:

tartan -cc1 -analyze -std=c89 $system_includes `pkg-config --cflags glib-2.0` my-project/*.c

You can think of the tartan script as equivalent to clang or gcc — it acts as a compiler.

The tartan script looks for the clang binary in the same directory as itself, and then looks for libtartan.so in the same prefix. If either of these are installed in non-standard locations, set the TARTAN_CLANG_CC and TARTAN_CLANG_PLUGIN environment variables to the absolute paths of the clang binary and the libtartan.so library, respectively.

The TARTAN_CLANG_CFLAGS environment variable may optionally be set to pass extra options to the compiler after the Tartan options. Similarly, TARTAN_CLANG_OPTIONS may optionally be set to pass extra options to the Tartan plugin (only).

Raw Clang plugin

Finally, Tartan may be used without the wrapper script by passing the -load, -add-plugin and -analyzer-checker arguments directly to the compiler:

clang -cc1 -load $PREFIX/lib/tartan/$LLVM_VERSION/libtartan.so -add-plugin tartan -analyzer-checker tartan -analyze -std=c89 my-project/*.c

Again, Tartan can be used both while installed or uninstalled.

Troubleshooting

If it seems like Tartan is not successfully being configured with use when building your project, there are a couple of things you can try to debug the situation.

Source code and bugs

Git repository

The source code for Tartan is stored in git, which can be viewed online or cloned:

git clone git://anongit.freedesktop.org/tartan

Bugs

Tartan uses Phabricator on freedesktop.org for bug tracking and feature requests.

To file a bug, please file a task on Phabricator.

Contact

Tartan is written by Philip Withnall, as part of R&D work by Collabora.

If you have any bug reports, questions, suggestions or criticism of the project, please e-mail me (philip tecnocode co uk).

Mailing list

Tartan has a mailing list on freedesktop.org for development discussion and support questions.