1Command Line Usage: scan-build and CodeChecker 2============================================== 3 4This document provides guidelines for running the static analyzer from the command line on whole projects. 5CodeChecker and scan-build are two CLI tools for using CSA on multiple files (translation units). 6Both provide a way of driving the analyzer, detecting compilation flags, and generating reports. 7CodeChecker is more actively maintained, provides heuristics for working with multiple versions of popular compilers and it also comes with a web-based GUI for viewing, filtering, categorizing and suppressing the results. 8Therefore CodeChecker is recommended in case you need any of the above features or just more customizability in general. 9 10Comparison of CodeChecker and scan-build 11---------------------------------------- 12 13The static analyzer is by design a GUI tool originally intended to be consumed by the XCode IDE. 14Its purpose is to find buggy execution paths in the program, and such paths are very hard to comprehend by looking at a non-interactive standard output. 15It is possible, however, to invoke the static analyzer from the command line in order to obtain analysis results, and then later view them interactively in a graphical interface. 16The following tools are used commonly to run the analyzer from the command line. 17Both tools are wrapper scripts to drive the analysis and the underlying invocations of the Clang compiler: 18 191. scan-build_ is an old and simple command line tool that emits static analyzer warnings as HTML files while compiling your project. You can view the analysis results in your web browser. 20 - Useful for individual developers who simply want to view static analysis results at their desk, or in a very simple collaborative environment. 21 - Works on all major platforms (Windows, Linux, macOS) and is available as a package in many Linux distributions. 22 - Does not include support for cross-translation-unit analysis. 23 242. CodeChecker_ is a driver and web server that runs the static analyzer on your projects on demand and maintains a database of issues. 25 - Perfect for managing large amounts of thee static analyzer warnings in a collaborative environment. 26 - Generally much more feature-rich than scan-build. 27 - Supports incremental analysis: Results can be stored in a database, subsequent analysis runs can be compared to list the newly added defects. 28 - :doc:`CrossTranslationUnit` is supported fully on Linux via CodeChecker. 29 - Can run clang-tidy checkers too. 30 - Open source, but out-of-tree, i.e. not part of the LLVM project. 31 32scan-build 33---------- 34 35**scan-build** is a command line utility that enables a user to run the static analyzer over their codebase as part of performing a regular build (from the command line). 36 37How does it work? 38~~~~~~~~~~~~~~~~~ 39 40During a project build, as source files are compiled they are also analyzed in tandem by the static analyzer. 41 42Upon completion of the build, results are then presented to the user within a web browser. 43 44Will it work with any build system? 45~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 46 47**scan-build** has little or no knowledge about how you build your code. It works by overriding the ``CC`` and ``CXX`` environment variables to (hopefully) change your build to use a "fake" compiler instead of the one that would normally build your project. This fake compiler executes either ``clang`` or ``gcc`` (depending on the platform) to compile your code and then executes the static analyzer to analyze your code. 48 49This "poor man's interposition" works amazingly well in many cases and falls down in others. Please consult the information on this page on making the best use of **scan-build**, which includes getting it to work when the aforementioned hack fails to work. 50 51.. image:: ../images/scan_build_cmd.png 52 53.. image:: ../images/analyzer_html.png 54 55**Viewing static analyzer results in a web browser** 56 57Basic Usage 58~~~~~~~~~~~ 59 60Basic usage of ``scan-build`` is designed to be simple: just place the word "scan-build" in front of your build command:: 61 62 $ scan-build make 63 $ scan-build xcodebuild 64 65In the first case ``scan-build`` analyzes the code of a project built with ``make`` and in the second case ``scan-build`` analyzes a project built using ``xcodebuild``. 66 67Here is the general format for invoking ``scan-build``:: 68 69 $ scan-build [scan-build options] <command> [command options] 70 71Operationally, ``scan-build`` literally runs <command> with all of the subsequent options passed to it. For example, one can pass ``-j4`` to ``make`` get a parallel build over 4 cores:: 72 73 $ scan-build make -j4 74 75In almost all cases, ``scan-build`` makes no effort to interpret the options after the build command; it simply passes them through. In general, ``scan-build`` should support parallel builds, but **not distributed builds**. 76 77It is also possible to use ``scan-build`` to analyze specific files:: 78 79 $ scan-build gcc -c t1.c t2.c 80 81This example causes the files ``t1.c`` and ``t2.c`` to be analyzed. 82 83For Windows Users 84~~~~~~~~~~~~~~~~~ 85 86Windows users must have Perl installed to use scan-build. 87 88``scan-build.bat`` script allows you to launch scan-build in the same way as it described in the Basic Usage section above. To invoke scan-build from an arbitrary location, add the path to the folder containing scan-build.bat to your PATH environment variable. 89 90If you have unexpected compilation/make problems when running scan-build with MinGW/MSYS the following information may be helpful: 91 92- If getting unexpected ``"fatal error: no input files"`` while building with MSYS make from the Windows cmd, try one of these solutions: 93 - Use MinGW ``mingw32-make`` instead of MSYS ``make`` and exclude the path to MSYS from PATH to prevent ``mingw32-make`` from using MSYS utils. MSYS utils are dependent on the MSYS runtime and they are not intended for being run from the Windows cmd. Specifically, makefile commands with backslashed quotes may be heavily corrupted when passed for execution. 94 - Run ``make`` from the sh shell:: 95 96 $ scan-build [scan-build options] sh -c "make [make options]" 97 98- If getting ``"Error : *** target pattern contains no `%'"`` while using GNU Make 3.81, try to use another version of make. 99 100Other Options 101~~~~~~~~~~~~~ 102 103As mentioned above, extra options can be passed to ``scan-build``. These options prefix the build command. For example:: 104 105 $ scan-build -k -V make 106 $ scan-build -k -V xcodebuild 107 108Here is a subset of useful options: 109 110- **-o**: Target directory for HTML report files. Subdirectories will be created as needed to represent separate "runs" of the analyzer. If this option is not specified, a directory is created in ``/tmp`` to store the reports. 111- **-h** *(or no arguments)*: Display all ``scan-build`` options. 112- **-k**, **--keep-going**: Add a "keep on going" option to the specified build command. This option currently supports ``make`` and ``xcodebuild``. This is a convenience option; one can specify this behavior directly using build options. 113- **-v**: Verbose output from scan-build and the analyzer. **A second and third "-v" increases verbosity**, and is useful for filing bug reports against the analyzer. 114- **-V**: View analysis results in a web browser when the build command completes. 115- **--use-analyzer Xcode** *(or)* **--use-analyzer [path to clang]**: ``scan-build`` uses the 'clang' executable relative to itself for static analysis. One can override this behavior with this option by using the 'clang' packaged with Xcode (on OS X) or from the PATH. 116 117A complete list of options can be obtained by running ``scan-build`` with no arguments. 118 119Output of scan-build 120~~~~~~~~~~~~~~~~~~~~ 121 122The output of scan-build is a set of HTML files, each one which represents a separate bug report. A single ``index.html`` file is generated for surveying all of the bugs. You can then just open ``index.html`` in a web browser to view the bug reports. 123 124Where the HTML files are generated is specified with a **-o** option to ``scan-build``. If **-o** isn't specified, a directory in ``/tmp`` is created to store the files (``scan-build`` will print a message telling you where they are). If you want to view the reports immediately after the build completes, pass **-V** to ``scan-build``. 125 126Recommended Usage Guidelines 127~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 128 129This section describes a few recommendations with running the analyzer. 130 131Always Analyze a Project in its "Debug" Configuration 132~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 133 134Most projects can be built in a "debug" mode that enables assertions. Assertions are picked up by the static analyzer to prune infeasible paths, which in some cases can greatly reduce the number of false positives (bogus error reports) emitted by the tool. 135 136Another option is to use ``--force-analyze-debug-code`` flag of **scan-build** tool which would enable assertions automatically. 137 138Use Verbose Output when Debugging scan-build 139~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 140 141``scan-build`` takes a **-v** option to emit verbose output about what it's doing; two **-v** options emit more information. Redirecting the output of ``scan-build`` to a text file (make sure to redirect standard error) is useful for filing bug reports against ``scan-build`` or the analyzer, as we can see the exact options (and files) passed to the analyzer. For more comprehensible logs, don't perform a parallel build. 142 143Run './configure' through scan-build 144~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 145 146If an analyzed project uses an autoconf generated ``configure`` script, you will probably need to run ``configure`` script through ``scan-build`` in order to analyze the project. 147 148**Example**:: 149 150 $ scan-build ./configure 151 $ scan-build --keep-cc make 152 153The reason ``configure`` also needs to be run through ``scan-build`` is because ``scan-build`` scans your source files by *interposing* on the compiler. This interposition is currently done by ``scan-build`` temporarily setting the environment variable ``CC`` to ``ccc-analyzer``. The program ``ccc-analyzer`` acts like a fake compiler, forwarding its command line arguments over to the compiler to perform regular compilation and ``clang`` to perform static analysis. 154 155Running ``configure`` typically generates makefiles that have hardwired paths to the compiler, and by running ``configure`` through ``scan-build`` that path is set to ``ccc-analyzer``. 156 157Analyzing iPhone Projects 158~~~~~~~~~~~~~~~~~~~~~~~~~ 159 160Conceptually Xcode projects for iPhone applications are nearly the same as their cousins for desktop applications. **scan-build** can analyze these projects as well, but users often encounter problems with just building their iPhone projects from the command line because there are a few extra preparative steps they need to take (e.g., setup code signing). 161 162Recommendation: use "Build and Analyze" 163~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 164 165The absolute easiest way to analyze iPhone projects is to use the `Analyze feature in Xcode <https://developer.apple.com/library/ios/recipes/xcode_help-source_editor/chapters/Analyze.html#//apple_ref/doc/uid/TP40009975-CH4-SW1>`_ (which is based on the static analyzer). There a user can analyze their project right from a menu without most of the setup described later. 166 167`Instructions are available <../xcode.html>`_ on this website on how to use open source builds of the analyzer as a replacement for the one bundled with Xcode. 168 169Using scan-build directly 170~~~~~~~~~~~~~~~~~~~~~~~~~ 171 172If you wish to use **scan-build** with your iPhone project, keep the following things in mind: 173 174- Analyze your project in the ``Debug`` configuration, either by setting this as your configuration with Xcode or by passing ``-configuration Debug`` to ``xcodebuild``. 175- Analyze your project using the ``Simulator`` as your base SDK. It is possible to analyze your code when targeting the device, but this is much easier to do when using Xcode's *Build and Analyze* feature. 176- Check that your code signing SDK is set to the simulator SDK as well, and make sure this option is set to ``Don't Code Sign``. 177 178Note that you can most of this without actually modifying your project. For example, if your application targets iPhoneOS 2.2, you could run **scan-build** in the following manner from the command line:: 179 180 $ scan-build xcodebuild -configuration Debug -sdk iphonesimulator2.2 181 182Alternatively, if your application targets iPhoneOS 3.0:: 183 184 $ scan-build xcodebuild -configuration Debug -sdk iphonesimulator3.0 185 186Gotcha: using the right compiler 187~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 188 189Recall that **scan-build** analyzes your project by using a compiler to compile the project and ``clang`` to analyze your project. The script uses simple heuristics to determine which compiler should be used (it defaults to ``clang`` on Darwin and ``gcc`` on other platforms). When analyzing iPhone projects, **scan-build** may pick the wrong compiler than the one Xcode would use to build your project. For example, this could be because multiple versions of a compiler may be installed on your system, especially if you are developing for the iPhone. 190 191When compiling your application to run on the simulator, it is important that **scan-build** finds the correct version of ``gcc/clang``. Otherwise, you may see strange build errors that only happen when you run ``scan-build``. 192 193**scan-build** provides the ``--use-cc`` and ``--use-c++`` options to hardwire which compiler scan-build should use for building your code. Note that although you are chiefly interested in analyzing your project, keep in mind that running the analyzer is intimately tied to the build, and not being able to compile your code means it won't get fully analyzed (if at all). 194 195If you aren't certain which compiler Xcode uses to build your project, try just running ``xcodebuild`` (without **scan-build**). You should see the full path to the compiler that Xcode is using, and use that as an argument to ``--use-cc``. 196 197CodeChecker 198----------- 199 200Basic Usage 201~~~~~~~~~~~ 202 203Install CodeChecker as described here: `CodeChecker Install Guide <https://github.com/Ericsson/codechecker/#Install-guide>`_. 204 205Create a compilation database. If you use cmake then pass the ``-DCMAKE_EXPORT_COMPILE_COMMANDS=1`` parameter to cmake. Cmake will create a ``compile_commands.json`` file. 206If you have a Makefile based or similar build system then you can log the build commands with the help of CodeChecker:: 207 208 make clean 209 CodeChecker log -b "make" -o compile_commands.json 210 211Analyze your project:: 212 213 CodeChecker analyze compile_commands.json -o ./reports 214 215View the analysis results. 216Print the detailed results in the command line:: 217 218 CodeChecker parse --print-steps ./reports 219 220Or view the detailed results in a browser:: 221 222 CodeChecker parse ./reports -e html -o ./reports_html 223 firefox ./reports_html/index.html 224 225Optional: store the analysis results in a DB:: 226 227 mkdir ./ws 228 CodeChecker server -w ./ws -v 8555 & 229 CodeChecker store ./reports --name my-project --url http://localhost:8555/Default 230 231Optional: manage (categorize, suppress) the results in your web browser:: 232 233 firefox http://localhost:8555/Default 234 235Detailed Usage 236~~~~~~~~~~~~~~ 237 238For extended documentation please refer to the `official site of CodeChecker <https://github.com/Ericsson/codechecker/blob/master/docs/usage.md>`_! 239 240
