As part of work funded by OpenSFS, a plugin for Clang has been developed. This plugin can be used  to identify code in the Lustre source tree that is never called. In addition, structures that are read and never written, and unused variables can also be identified. The purpose of this document is to enable a developer to begin working with these tools.

Setting up the environment

1. Setup a RHEL 6.3 (or 6.4, or 6.5) image capable of building the kernel and Lustre source code. Use a disk image with at least 24 GB.
   
   1. gcc (GCC) 4.4.6 20120305 (Red Hat 4.4.6-4). gcc that is packaged with EL 6.5 also works.
   2. install git
2. Install Clang and LLVM. RPMs are available from elrepo. Clang/LLVM version 3.0 has good parity with gcc-4.4. Parity with gcc-4.4 is important as gcc is used during the analysis.
   

   • llvm-devel-3.0-5.el6.elrepo.x86_64

   • llvm-libs-3.0-5.el6.elrepo.x86_64
   • llvm-doc-3.0-5.el6.elrepo.noarch
   • llvm-3.0-5.el6.elrepo.x86_64
   • clang-devel-3.0-5.el6.elrepo.x86_64
   • clang-3.0-5.el6.elrepo.x86_64
   • clang-analyzer-3.0-5.el6.elrepo.x86_64

   • clang-doc-3.0-5.el6.elrepo.noarch

     Once elrepo is available as a repo, only the main channel is available by default. To install llvm and clang you need the elrepo-extras repo. This can be enabled by including      --enablerepo=elrepo-extras in your yum command.

3. Download lustre-static-analysis Clang plugin: 
        git clone http://git.whamcloud.com/tools/lustre-static-analysis.git
4. Make the contents of Endian, DeclUse and Utils directories.

Building Lustre for static analysis

1. Build a Lustre patched kernel with GCC. This document assumes a Lustre patched kernel version: 2.6.32-279.19.1.el6_lustre_gcov.x86_64.
2. Build SPL and ZFS if necessary.

3. Build Lustre software using a script included in lustre-static-analysis for assistance:

   # cd lustre-release # git clean -fxd # sh autogen.sh && ./configure # ~/lustre-static-analysis/DeclUse/decl_use_make

   For each .c to .o compilation performed by GCC, decl_use_make will also run Clang with the lustre-static-analysis plugin. When compiling file.c the output file.o is produced by GCC and should be identical to a normal Lustre build. Simultaneously decl_use_make instructs Clang to read file.c and produce corresponding file.o._Ref and file.o._Err. Note: Clang does not compile file.c to an object file. Clang parses file.c and produces an AST in memory. The file.o._Err file records the errors Clang discovered during processing file.c.

   In practice, file.o is first build as .tmp_file.o then renamed to file.o. This happens in the Makefile so GCC and Clang are unaware of the file.o.

Useful products from Clang static analysis produced by decl_use_make

For the purposes of static analysis provided by the Clang plugin, the file.o._Ref are intermediate file and not of general interest. The files of interest are contained in the directory DeclUse-2.5.60-40-g*/ . Useful file include:

Gotchas

• The static usage tracker is confused by disconnected declarations.