nsumner / clang-plugins-demo

A simple example of defining custom plugins for clang and the clang static analyzer.

These plugins and programs are demonstrations of how to create and use the plugin infrastructure of clang for analyzing ASTs or integrating with the clang static analyzer.

The AST plugin prints out the names of functions found when parsing a file. The static analyzer plugin is the SimpleStreamChecker from the clang code base (as well as How to write a checker in 24 hours by Anna Zaks and Jordan Rose). It identifies issues in handling FILEs in C program. Neither plugin is a contribution here. This project just provides an example of how to integrate such plugins into a standalone project.

Building with CMake

1. Clone the demo repository.

    git clone https://github.com/nsumner/clang-plugins-demo.git
   

2. Create a new directory for building.

    mkdir build
   

3. Change into the new directory.

    cd build
   

4. Run CMake with the path to the LLVM source.

    cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=True \
        -DLLVM_DIR=</path/to/LLVM/build>/lib/cmake/llvm/ \
        ../clang-plugins-demo
   

5. Run make inside the build directory:

    make
   

This produces standalone tools called bin/print-functions and bin/runstreamchecker. Loadable plugin variants of the analyses are also produced inside lib/.

Note, building with a tool like ninja can be done by adding -G Ninja to the cmake invocation and running ninja instead of make.

Running

Both the AST plugins and clang static analyzer plugins can be run via standalone programs or via extra command line arguments to clang. The provided standalone variants can operate on individual files or on compilation databases, but compilation databases are somewhat easier to work with.

AST Plugins

To load and run AST plugins dynamically in clang, you can use:

    clang -fplugin=lib/libfunction-printer-plugin.so -c ../test/functions.c

To run the plugin via the standalone program:

    bin/print-functions -- clang -c ../test/functions.c

Note that this will require you to put the paths to all headers in the command line (using -I) or they will not be found. It can be simpler to instead use a compilation database:

    bin/print-functions -p compile_commands.json

Clang Static Analyzer Plugins

To load and run a static analyzer plugin dynamically in clang, use:

    clang -fsyntax-only -fplugin=lib/libstreamchecker.so \
      -Xclang -analyze -Xclang -analyzer-checker=demo.streamchecker \
      ../clang-plugins-demo/test/files.c

To run the plugin via the standalone program:

    bin/runstreamchecker -- clang -c ../clang-plugins-demo/test/files.c

Again, missing headers are likely, and using a compilation database is the preferred and simplest way to work around this issue. Note that clang comes with scripts that can build a compilation database for an existing project.

Licenses

The code for this project is released under an MIT License (included in the LICENSE file in the root directory of the project).

The code in SimpleStreamChecker.cpp comes from the clang project and is released under the University of Illinois/NCSA Open Source License.

clang-plugins-demo's Issues

cmake failed

Hello, thank you for your code. But when I do as what you said, I got error， I don't know why.
This is the log.
➜ build cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=True -DLLVM_DIR=~/code/llvm_xcode/lib/cmake/llvm ..
-- Found LLVM 10.0.0svn
-- Using LLVMConfig.cmake in: ~/code/llvm_xcode/lib/cmake/llvm
-- Linker detection: ld64
LLVM STATUS:
Definitions -D__STDC_CONSTANT_MACROS -D__STDC_FORMAT_MACROS -D__STDC_LIMIT_MACROS
Includes /Users/wangao/code/llvm-project/llvm/include;/Users/wangao/code/llvm_xcode/include
STATIC_INCLUDES-NOTFOUND;/Users/wangao/code/llvm_xcode/tools/clang/include
Libraries /Users/wangao/code/llvm_xcode/$(CONFIGURATION)$(EFFECTIVE_PLATFORM_NAME)/lib
CMake Error: The following variables are used in this project, but they are set to NOTFOUND.
Please set them or make sure they are set and tested correctly in the CMake files:
STATIC_INCLUDES
used as include directory in directory /Users/wangao/Desktop/clang-plugins-demo-master
used as include directory in directory /Users/wangao/Desktop/clang-plugins-demo-master
used as include directory in directory /Users/wangao/Desktop/clang-plugins-demo-master/lib
used as include directory in directory /Users/wangao/Desktop/clang-plugins-demo-master/lib/function-printer
used as include directory in directory /Users/wangao/Desktop/clang-plugins-demo-master/lib/function-printer
used as include directory in directory /Users/wangao/Desktop/clang-plugins-demo-master/lib/function-printer
used as include directory in directory /Users/wangao/Desktop/clang-plugins-demo-master/lib/streamchecker
used as include directory in directory /Users/wangao/Desktop/clang-plugins-demo-master/lib/streamchecker
used as include directory in directory /Users/wangao/Desktop/clang-plugins-demo-master/tools
used as include directory in directory /Users/wangao/Desktop/clang-plugins-demo-master/tools/print-functions
used as include directory in directory /Users/wangao/Desktop/clang-plugins-demo-master/tools/print-functions
used as include directory in directory /Users/wangao/Desktop/clang-plugins-demo-master/tools/runstreamchecker
used as include directory in directory /Users/wangao/Desktop/clang-plugins-demo-master/tools/runstreamchecker

-- Configuring incomplete, errors occurred!
See also "/Users/wangao/Desktop/clang-plugins-demo-master/build/CMakeFiles/CMakeOutput.log".