Oink: a Collaboration of C++ Static Analysis Tools

Maintainer: Daniel S. Wilkerson
Developer: Karl Chen
Developer: Scott McPeak

Introduction

Welcome to Oink! Oink is a collaboration of C++ static analysis tools. The C++ front-end for Oink is Elsa by Scott McPeak. Currently the main tool provided by Oink is Cqual++, a polymorphic whole-program dataflow analysis for C++. Cqual++ was inspired by Jeff Foster's and Cqual tool and shares the backend solver with it.

Companion projects

• Delta assists you in minimizing "interesting" files subject to a test of their interestingness. A common such situation is when attempting to isolate a small failure-inducing substring of a large input that causes your program to exhibit a bug.
• Build Interceptor captures the .i files of any project while it is built from source using the gcc tool-chain.

Directory contents

• Oink Main Documentation [this document] Introduction to Oink.
• Cqual++ Documentation Documentation on the main Oink tool.
• Oink Manifest A top-down view of the aspects of Oink, which files participate in each aspect, and documentation on each file.
• Oink Coding Style The Oink coding guidelines; also provided is some elisp for putting emacs into the mode I use when editing it.
• Features of Elsa The elsa documentation is extensive; I simply point out a few useful features that users of Oink/Cqual++ should know about.

Page contents

• Dependencies: Dependencies on other tools that I could think of.
• Licensing: The licensing under which Oink and its sub-projects are released.
• Tools: List of tools that come with Oink.
• Acknowledgments: Thanks the many people who supported and contributed to the project.

Oink has been tested successfully on recent versions of Linux, Apple OSX, and Cygwin/Windows.

Here are some dependencies (with versions) that I know about and that occurred to me to mention.

• gcc: 2.95.3, 3.2-7, 3.4.0 known to work; 2.96-110 doesn't work. I've had problems with gcc 4.x so I don't use it yet and I can't recommend it.
• flex: 2.5.4 known to work.
• dot: 1.8.10 known to work; Get dot from here: http://www.graphviz.org/. You do not need dot for the base functionality of the system. If we have an internal graph to print out, such as the output of -fq-print-quals-graph, it will be rendered out in dot format and you will need dot to convert that to postscript.
• libzipios++ and zlib (optional): Enable loading and saving .qz archive files, in addition to .qdir archive directories.

See License.txt for the the copyright and terms of use of the software in the oink repository and its subdirectories.

Tools

To make Oink easy to learn and build-upon, I have written some small example tools. Each sample tool is a stand-alone executable and does not share infrastructure with other unrelated tools, making it smaller and easier to understand. Oink also provides the Cqual++ tool, a polymorphic whole-program dataflow analysis for C++.

Oink tool

The Oink tool, oink/oink, is the empty analysis: it does nothing. Its features and command-line flags are shared by all other tools. For an exhaustive list of the oink/oink flags and a short description of each, just type: ./oink --help

StaticPrint tool

The StaticPrint tool, oink/staticprint, is intended to print out various facts about a program that can be obtained statically. Currently it prints the inheritance tree and a histogram of AST nodes. Run 'make staticprint-check-print' and then view Test/staticprint1.cc.ihg.dot.ps in a postscript viewer and compare with the source code in Test/staticprint1.cc. See the staticprint_test.incl.mk makefile for other examples. Note that currently this tree is translation-unit-local since staticprint has no linker imitator.

DfgPrint tool

The Dfgprint tool, oink/dfgprint, prints the data flow graph of a C++ program. It is purposefully small and simple so it is easy to see the essentials of writing a dataflow tool. It should be easy to get started on a dataflow analysis by simply copying dfgprint and hacking it. Run 'make dfgprint-check-print' and then view Test/dfgprint1.c.dfg.dot.ps in a postscript viewer and compare with the source code in Test/dfgprint1.c . Note that the graph generation requires that you have the graph layout program 'dot'.

Note that dfgprint prints 'expression-level' dataflow. The dataflow used by the Cqual++ analysis (described below) is the more detailed 'type-level' flow; you can get a graph of that flow by running Cqual++ with the flag -fprint-quals-graph and then running 'dot' on the resulting quals.dot file.

CfgPrint tool

The Cfgprint tool, oink/cfgprint, prints the intra-procedural control flow graph of a C++ program (by delegating to that functionality in Elsa). Similarly to dfgprint it also is purposefully small and simple. Run 'make cfgprint-check-print' and then view Test/cfgprint1.c.cfg.dot.ps in a postscript viewer and compare with the source code in Test/cfgprint1.c .

Note that cfgprint prints a statement-level control flow graph; a more precise expression-level graph could be implemented as (mostly) a refinement of the statement-level flow, but this is not done yet. (It would not be a strict refinement due to the possibility of using a goto to jump out of a gnu expression statement; Yes there is an example of this in the Red Hat 9 source tree.) We don't compute the (inter-procedural) call graph as to do that properly really requires including also a points-to analysis and a dataflow analysis.

Cqual++ tool [further documentation]

The major tool of the current Oink distribution is Cqual++, oink/qual, which checks static assertions about C++ programs that can be expressed as a polymorphic dataflow of type qualifiers. Cqual++ uses libqual to do the inference. Please see the Cqual++ Documentation for more information.

The old acknowledgments section was quite out of date. A new section is forthcoming.

Enjoy.

        --- Daniel

© 2002-2006 Daniel S. Wilkerson