scan-build

Build and analyze the project in the current directory

$ scan-build [make]

$ scan-build [command] [command_arguments]

$ scan-build

scan-build [scan-build options] <command> [command options/arguments]

Examples:
scan-build make clean all
scan-build -o analysis_results cmake ..
scan-build gcc -c my_file.c

-o <directory>
    Specifies the output directory for the generated HTML analysis reports. If not provided, a temporary directory is created.

--output <directory>
    Long form alias for -o.

--enable-checker <checker>
    Enables a specific static analysis checker. For example, --enable-checker security.insecureAPI.gets.

--disable-checker <checker>
    Disables a specific static analysis checker that would otherwise be active.

--use-analyzer <analyzer_path>
    Specifies the path to the clang analyzer executable to be used. Useful for custom clang installations.

--view
    Automatically opens the generated HTML analysis report in your default web browser after the analysis completes.

--status-bugs
    Exits with a non-zero status code if any bugs are found during the analysis, useful for CI/CD pipelines.

--analyze-headers
    Instructs the analyzer to process and report issues found within header files as well, not just source files.

--exclude <path>
    Excludes files or directories from being analyzed. Can be specified multiple times for multiple exclusions.

--html-title <title>
    Sets a custom title for the generated HTML analysis report, visible in the browser tab.

--plist
    Outputs results in the XML Property List (plist) format, typically used for integration with Xcode or other tools.

--verbose
    Provides more detailed output during the analysis process, showing internal commands and progress.

--help
    Displays a help message with available scan-build options and exits.

scan-build is a powerful wrapper script for the Clang Static Analyzer, a tool designed to find bugs in C, C++, and Objective-C programs. Instead of requiring modifications to your build system, scan-build intercepts compiler invocations (like gcc or g++) and replaces them with calls to the static analyzer.

During the build process, it transparently runs the analysis, identifying potential issues such as null pointer dereferences, memory leaks, uninitialized variables, and use-after-free errors. Once the build completes, scan-build generates an HTML report, organized to easily navigate and examine the detected bugs, including execution paths leading to the defects. This makes it an invaluable tool for improving code quality and reliability early in the development cycle, integrating seamlessly with various build systems like Make, CMake, and Ninja.

scan-build can significantly increase build times, especially for large projects, due to the intensive static analysis performed.

It may produce false positives, which are reported issues that are not actual bugs, requiring manual review and discernment.

For comprehensive analysis, a 'clean' build is often necessary (e.g., make clean && scan-build make) to ensure all files are recompiled and thus analyzed.

While highly effective, it does not guarantee to find all possible bugs; it only detects issues covered by its available checkers. It relies on clang and its static analyzer being correctly installed and accessible.

scan-build operates by temporarily modifying your system's PATH environment variable to prepend a directory containing symlinks or wrapper scripts for common compilers (like gcc, g++, cc). When your build system (e.g., make) invokes a compiler, it actually calls the scan-build wrapper, which then executes the Clang Static Analyzer on the source file before passing control to the real compiler. This clever interception allows it to analyze your code without any changes to your project's build files.

The Clang Static Analyzer, via scan-build, can detect a wide array of bugs categorized into several checkers. These include:
Memory errors: such as memory leaks, use-after-free, double-free, and uninitialized reads.
Logic errors: like division by zero, null pointer dereferences, and unreachable code.
API misuse: including incorrect API usage, security vulnerabilities (e.g., insecure string functions), and resource leaks (e.g., unclosed files or sockets).
Concurrency issues: for instance, race conditions or deadlocks in multi-threaded code.

scan-build is an integral part of the LLVM project's Clang Static Analyzer. The static analyzer project itself originated at Apple Inc. around 2007, with a primary goal of improving the quality and security of Apple's software.

It was later open-sourced as part of the broader LLVM/Clang initiative, making its powerful capabilities available to the wider development community. scan-build was specifically developed as a user-friendly wrapper script to simplify the integration of the static analyzer into existing build processes, bypassing the need for extensive build system modifications. This approach made static analysis more accessible and practical for everyday development workflows, quickly gaining adoption across various open-source and commercial projects.

clang(1), make(1), cmake(1), ninja(1), valgrind(1), cppcheck(1), splint(1)