JavaScript is not currently enabled, but is required for full CodeSonar manual search and browse functionality.

If you are viewing this file in your hub's Web GUI, enable JavaScript in your browser: you will also need it for GUI functionality.

If you opened this file directly from disk, your browser may be directly suppressing JavaScript functionality: certain browsers perform this suppression on local files (but not files delivered by web servers) for security reasons.

CodeSonar® 9.2p0 CONFIDENTIAL CodeSecure Inc
C and C++

Source File Patching

CodeSonar provides source file patching functionality in addition to command- and regular-expression-based source modifications. This section describes the functionality and its typical applications, outlines the patches shipped with CodeSonar, and explains how to create new patches and ensure they are applied correctly.

Source File Patching Example uses a template header example to illustrate the process of creating and incorporating a new source file patch.

CodeSonar applies specified source file patches during the source modification step of the CodeSonar project build phase. As with command- and regular-expression-based source modifications, source file patching is generally applied in order to improve analysis results by removing code that cannot be analyzed, adding code that makes important relationships explicit, or both.

C++ Template Header Patches

Source file patching is particularly beneficial for C++ template library headers, which have several properties distinguising them from other libraries.

CodeSonar ships with a number of C++ template header patches in $CSONAR/codesonar/libmodels/header_patches/. These patches are applied automatically when default configuration settings are used. The shipped patches are as follows.

STL STL header patches for use with gcc 3.x, gcc 4.x, and Visual Studio 6-10.
Boost Patches for some Boost headers. (These headers, and thus their corresponding patches, are compiler-independent.)

Requirements and Terminology

Every patch file patchname for source file fname.fext must be stored within a directory structure of the form dir/fname.fext/patchname. We call dir/ the source patch directory, and fname.fext/ the source patch subdirectory.

source patch directory A directory whose subdirectories contain source patches. A source patch directory must be specified with SOURCE_PATCH_DIRECTORIES in order to enable patching from its subdirectories.
source patch subdirectory CodeSonar imposes the following requirements on every source patch subdirectory.
  • The subdirectory name must match the name of the file for which the patches in the subdirectory are intended.
  • It must be a direct subdirectory of a source patch directory - it cannot be more deeply nested.
CodeSonar does not restrict the number of patch files a source patch directory may contain.

For example, suppose we have source patch directory patchdir, and file patchdir/f.c/fpatch. Then:

  • fpatch is a patch to be applied to source file f.c.
  • patchdir/f.c/ is a source patch subdirectory.
applicability Given source patch directory dir, source patch subdirectory dir/fname.ext/, and patch file dir/fname.ext/patchname, we say that patchname is applicable to source file fname.ext if all hunks of patchname can be successfully applied to fname.ext.

For example, given patchdir/header.hpp/mypatch, mypatch is applicable to source file header.hpp if all hunks of mypatch can be successfully applied to header.hpp.

  • If mypatch is not applicable to header.hpp, no part of mypatch is applied.
  • patchdir/header.hpp/ may contain more than one file, in which case all applicable patch files are applied to header.hpp in arbitrary order.
  • If multiple source patch directories are enabled, and source patch directory D1 was enabled before source patch directory D2, patches from D1/header.hpp/ are applied before patches from D2/header.hpp/.

Other Requirements and Guidelines

Enabling and Disabling

To enable patching from a particular source patch directory mydir, use configuration file parameter SOURCE_PATCH_DIRECTORIES to instruct CodeSonar to apply patches from the source patch subdirectories of mydir as appropriate.

 SOURCE_PATCH_DIRECTORIES += mydir

To disable patching from mydir, edit the appropriate configuration file to delete (or comment out) the corresponding SOURCE_PATCH_DIRECTORIES rule.

# SOURCE_PATCH_DIRECTORIES += mydir

To disable all source patching, edit all applicable configuration files to delete (or comment out) all SOURCE_PATCH_DIRECTORIES rules.

Note: In general, we do not recommend disabling template header patching. Doing so will typically result in a large number of false positive warning reports.

Adding New Patches

Suppose you want to create a patch for file myheader.hpp. The process is as follows.

A. Establish a directory. Make sure you have a source patch directory and subdirectory suitable for use with this functionality.
  1. If you don't already have a directory for storing header patches in, create one. In this example, we will call it patchdir.
    mkdir path/to/patchdir
  2. If patchdir doesn't have a subdirectory called myheader.hpp/, create one.
    mkdir path/to/patchdir/myheader.hpp/
B. Create the patch. Create a patch file that CodeSonar can use to insert your modeling code into myheader.hpp before analyzing it.
  1. If you don't have a suitable working directory, create one.
    mkdir tmp
  2. Save a copy of the header file in your working directory.
    cp /library/path/myheader.hpp tmp/
  3. Change to your working directory.
    cd tmp
  4. Edit the working copy of myheader.hpp to incorporate the necessary modeling code.
  5. Use your normal diff tools to create a patch, storing it in the directory you established in step A. For example, using GNU diffutils:
    diff -u5 /library/path/myheader.hpp myheader.hpp
    > path/to/patchdir/myheader.hpp/mypatch
    The patch file itself can have any name; we have called this one mypatch.
C. Inform CodeSonar Once you have created a patch for myheader.hpp and saved it as path/to/patchdir/myheader.hpp/mypatch, inform CodeSonar that patchdir contains header patches (if it isn't already informed).
  1. Open the appropriate configuration file for editing.
  2. Add a new SOURCE_PATCH_DIRECTORIES rule: 
    SOURCE_PATCH_DIRECTORIES += path/to/patchdir
  3. Save and close the configuration file.
D. Build/Analyze and check Run the build/analysis and check that the patch was applied correctly.
  1. If you have already performed one or more CodeSonar analyses of the project, use your build system's functionality to indicate that /library/path/myheader.hpp has changed and all parts of the project that depend on myheader.hpp should be rebuilt. (If you haven't done something like this before, you may need to consult your build system documentation.)

    Note: If you skip this step, project code that depends on myheader.hpp will only be re-analyzed if one of the following occurs:

    • The dependent code is itself modified.
      • Or something else causes it to be rebuilt. For example, it might also depend on a third file, and that third file may have been modified.
    • Your CodeSonar build is based on a full, clean build of the underlying software project.
  2. Run the build/analysis.
  3. In the Web GUI, examine the Source Listing for myheader.hpp to ensure that your modifications have been applied.

Identifying Applied Patches

To determine which source patches have been incorporated in a particular compilation unit C:

  1. Set VERBOSITY=6 or higher.
  2. Build the CodeSonar project.

    The analysis is likely to be significantly slowed by the high VERBOSITY setting. To avoid this, separate the build and analysis phases: use VERBOSITY=6 with codesonar build to build the project, then reduce the VERBOSITY setting and run the analysis with codesonar analyze. If you only want the patching information and do not care about the analysis results, you can skip the analysis phase entirely.

  3. View the native compilation details log for C.
  4. Examine the CodeSecure Diagnostic output. There are several message types that are relevant to source patches: see the link for details.
 

To report problems with this documentation, please visit https://support.codesecure.com/.