C and C++

Build and Analysis for C/C++ Projects

To build a project based on C or C++ source code, CodeSonar monitors a normal build of your application, observes the compilations performed during this normal build, and builds the CodeSonar project accordingly. We refer to this mechanism as build hooking, or simply hooking.

Once the project is built, the CodeSonar analysis phase can run. The analysis results are sent to a hub database, from which they can be viewed with an ordinary web browser.

An overview and further links about building and analyzing CodeSonar projects from software in other languages are provided in section Building.

See also: CodeSonar and the Clang Static Analyzer.

How The C/C++ Build Works

The following diagram shows the CodeSonar build and analysis process for C and C++ projects.

Diagram: build hooking

The steps of the build and analysis process are described in Building: Overview. For C and C++ source files, the steps manifest as follows.

1. Observe
The user instructs CodeSonar to observe the execution of a specified operation or sequence of operations. There are two ways to set this up:
  • Command line: as part of the CodeSonar command line, the user specifies a normal software build command, which CodeSonar executes and observes until execution is completed.
  • Windows build wizard: the user specifies applications to observe, executes the normal software build using the appropriate applications, then informs CodeSonar when the normal build has completed.
2. Execute The normal software build process executes. It will compile one or more source files, using one or more compilers available on the local system.

Important: Because CodeSonar is observing the normal software build and basing the CodeSonar project on observed compilations, only source files compiled during the observed build will be represented in the project. Therefore, it is important to make sure that the build recompiles every source file. For example:

  • If you are using make for your normal software build, do a make clean before starting the CodeSonar project build.
  • If you are using Microsoft Visual Studio, start your normal software build with Rebuild All.
3. Recognize Compiler Calls
  • Command line: CodeSonar recognizes relevant calls within the normal build command as it executes.
  • Windows build wizard: CodeSonar recognizes relevant calls made by any of the applications that were selected for observation.
CodeSonar can recognize calls to any compilers on its internal compiler list, plus any compilers specified with the COMPILER_MODELS configuration file parameter.

Important: Calls to compilers that are not on the list and are not specified by the user will not be recognized, and those compilations will not be accounted for in the project.
4. Update Project Each time it recognizes a compiler call, CodeSonar updates the project definition to incorporate source files associated with that call. As part of the incorporation process, each source file F.x undergoes a set of source modifications before any preprocessing occurs.
Finish Building
  • Command line: Once the normal build command terminates, CodeSonar finishes building the project.
  • Windows build wizard: CodeSonar waits until the user indicates that the observation period has concluded by clicking Finalize, then finishes building the project.

All the source files compiled during the normal build are collected into a single project, even if the build is creating more than one executable.

Once it has finished building the project, CodeSonar can run the analysis. If you work through the Windows build wizard to screen 4 or build from the command line with analyze, the analysis will run (and send its results to the hub) after the build has finished. The degree of parallelism in the analysis will depend on the setting of ANALYSIS_SLAVES.

Mixed Builds

When CodeSonar for Binaries is installed, the C/C++ build can be expanded into a mixed build.

Command Line vs Windows Build Wizard

CodeSonar offers two mechanisms for building and analyzing projects: a command line and a Windows build wizard.

For Windows-based projects, the choice between building from the command line and using the Windows build wizard depends partly on personal preference and partly on the slight differences between the two build mechanisms. The following table shows the pros and cons of each mechanism.

  PRO CON
Windows build wizard
  • Is able to observe software builds that make use of Windows IDEs.
  • Some users may prefer a GUI-based project build.
  • Must wait for user instruction before finalizing project and running analysis.
  • All compiler invocations performed during the recording period by processes on the Watch list will be incorporated into the CodeSonar project, whether or not they were intended for inclusion.
command line build
  • Can automatically run the analysis when building finishes.
  • Automatically restricts hooking to the subprocess tree of the normal software build command, so unrelated compilations on the machine are ignored.
  • If the normal software build command reuses processes that don't belong to the command's process subtree, or relies on processes launched by a daemon, any compilations taking place under those processes will not be hooked.

    In particular, this can happen if the build invokes 16-bit Windows executables such as the default cygwin cc.exe and awk.exe.

The build mechanism you choose will be determined partly by the nature of the normal software build, as shown in the following table, and partly on the pros and cons of each approach.

Normal Software Build System Command Line Build Windows Build Wizard
Non-Windows Command Line Use normal build command as argument. not available
Non-Windows IDE GUI Export or manually determine a command line equivalent to the IDE build invocation, and use as argument. not available
Windows Command Line Use normal build command as argument. Make sure the command line and any other necessary processes are in the Watch list; run the normal build command from the command line during the Record phase.
Windows IDE GUI Export or manually determine a command line equivalent to the IDE build invocation, and use as argument. Make sure the IDE and any other necessary processes are in the Watch list; run the normal build command from the IDE during the Record phase.

Command Line Build

As described in Command Line Build/Analysis: Command, the general form of the usual CodeSonar build/analysis command is

codesonar analyze /path/to/pfiles-name
[-project[/[ancestors/]]proj-name] [-no-services] [-foreground] [-wait] [-clean] [-clean-backend] \
[-force-base-hub-analysis] [-name analysis-name] [-preset preset-name] [-no-default-presets] [-conf-file extra-conf-path] \
[-property propkey propval] [-launchd-group ldgroup] [-launchd-key ldkey] \
[-watch-pid pid] [-watch-all-pids] \
[-auth authtype] [-hubuser username] [-hubpwfile pwfile] [-hubbearerfile bearerfile] [-hubcert certfile] [-hubkey privatekeyfile] \
[-remote analysis-launchd] [-remote-archive daemonmode-launchd] [-srcroot basedir] [[protocol://]host:port] [command]

The command element is described below; the other parts of the command line are discussed in Command Line Build/Analysis: Elements.

command The command you usually use to build your software project. In many cases no changes to existing settings are necessary, and in most remaining cases only one or two CodeSonar build options are required.

CodeSonar will execute this command, identify all the compilations that ensue, and build the CodeSonar project accordingly.

Important: Only compilations resulting from executing this command will be represented in the CodeSonar project. Make sure that old object files and executables are removed (for example, with make clean) if necessary to make sure that all source files are compiled.

Some example build commands are listed below.

If command is missing, no building takes place and the analysis starts with the pre-existing contents of pfiles-name.prj_files (which will be a child of the project directory). If pfiles-name.prj_files is empty or missing, an error is raised.

If you usually invoke your build with a list of commands, you will need to quote the list and include an invocation command: generally cmd /c on Windows and sh -c on other systems. For example:

Usual command list tool_invocation_command
Windows Other systems
gcc a.c; gcc b.c cmd /c "gcc a.c; gcc b.c" sh -c "gcc a.c; gcc b.c"
cmake . && make cmd /c "cmake . && make" sh -c "cmake . && make"

command Examples

(Additional command line examples are provided on the following pages: Command Line Build/Analysis, Build and Analysis for Java Projects.

Any build command (or build system) that can be invoked from the command line can be used as the basis for a project. Simply pass the command line build invocation as the command argument to analyze. For example:

codesonar analyze cs-myproj cc myproj.c
codesonar analyze cs-myproj cc -o myproj myproj.c
codesonar analyze cs-myproj make
codesonar analyze cs-myproj make all
codesonar analyze cs-myproj make myproj

The project build and analysis steps can be run separately, as in the following example. The first command instructs CodeSonar to observe the compilation gcc -c myfile.c and update the myproj project accordingly. The second command instructs CodeSonar to analyze myproj and send the results to the default hub.

codesonar build myproj gcc -c myfile.c
codesonar analyze myproj

Note: If your build command is not based on a .exe file, you will need to specify "cmd /c" as part of command. For example:

codesonar analyze cs-myproj cmd /c build.bat

Note: If you are building your software project with CodeWarrior, see the additional information in section Using CodeSonar With CodeWarrior.

Windows Build Wizard

Instructions for using the Windows Build Wizard are provided in Windows Build Wizard Build/Analysis.

Other Build/Analysis Documentation

Building An overview and further links about building and analyzing CodeSonar projects.
Command Line Build/Analysis Information about invoking the CodeSonar build/analysis from the command line.
The Build/Analyze Commands Detailed documentation for codesonar build and codesonar analyze.
Windows Build Wizard Build/Analysis Instructions for using the Windows build wizard.
The Windows Build Wizard Detailed documentation for the Windows build wizard.
Build and Analysis for Java Projects Specific information for build/analysis of projects built (in whole or in part) from Java bytecode.
Troubleshooting the Build Solutions for problems you may encounter during the CodeSonar build/analysis process
CodeSonar and the Clang Static Analyzer Performing a CodeSonar analysis that also includes results from Clang Static Analyzer.