Clang scan-build: a great C++ Static Analyzer

Clang has a command line utility that is very easy to use, and adds a static code analysis step to gcc or clang. It is trivial to install (less than 5 minutes – really! ) and works with almost any build system ( makefiles, xcode etc. )

The Clang Static Analyzer ( aka “scan-build” is a script that will intercept all calls that your existing build system makes to clang/gcc, and replaces them with an instrumented version of clang that does static analysis of your code before compiling.

Think of it as adding a set of extra deep code warnings to your C++ compiler.
The static analysis is significantly slower – so you don’t want to run this all the time.

An Example Error

The easiest way to understand what scan-build can do is to look at an example error report. Scan build will write error reports to the shell along with the rest of the compiler output, but it really shines when you run it in a mode where it send the error reports to a web browser.

Here is an example:

You can see from this a little bit about how it works. scan-build compiles the code down to some intermediate form, like the machine independent pseudo code that compilers use before instruction generation.

Then it simulates executing the functions with different arguments, simulating different logic paths through the functions. Considering options like what if numbers are zero or negative, what if pointers are null etc.

And then it reports on paths that produce errors – like null pointer dereferences, or reading uninitialized data. You can see that in this case at step 15 it detects that we’re reading a garbage value.

It is this multi-path simulation that allows it to generate errors that the normal compiler can’t and also why this tool is much slower than a normal compile step.

scan-build limits the paths it explores by looking at your assertions. So if you assert that a certain condition should be impossible it will not simulate that path.

It does come up with occasional false positives. Usually this is when it passes into functions values that you know are not possible given the way the function is used. To avoid this, just assert at the start of that function that certain arguments can’t take on certain values. It’s good documentation in these cases anyway.

It also isn’t good at detecting conditions that are technically wrong, but that you know in practice are harmless. In the example above its true that the decoder will read some invalid bytes when the input string is short. But we never use such bytes in the final output – so its harmless, and saves us some conditionals.

Installation and Running

Installation on Os X is really easy – just download a gzip file with the binaries. Inside the bin directory is a script called scan-build. Just prefix that to your build command:

scan-build -V make

The -V option is what causes it to send errors to your browser and is really recommended. Once you see this technique you wonder why more programs don’t do this.

Resources