Writing C++ Plug-Ins For CodeSonar

• Overview
• Create Source File(s)
• Compile the Plug-in
• Install
• Implementation Notes
• More on Plug-Ins

Overview

To create and use a CodeSonar C++ plug-in, do the following:

1. Create C++ source file(s) for the plug-in.
2. Compile the plug-in into a library: .dll, .so, or .bundle as appropriate for your platform.
3. Save the plug-in in directory $CSONAR/codesonar/plugins, where $CSONAR is the CodeSonar installation directory.

Create Source File(s)

Suppose you want to define a plug-in called pname_plugin.

#define CS_CPP_IMPL             // must precede #include "csonar_api.hpp"
#include "csonar_api.hpp"       // uses the 'cs' namespace  
// ...
static void cs_plug_main(void){}// must be present but can be empty
CS_DEFINE_PLUGIN(pname_plugin)  // must be final line; built plug-in library must have corresponding name

(Further implementation notes are provided below.)

Compile the Plug-In

Once the plug-in source files are created, compile the plug-in into a library. The library name must meet the file name requirements listed above.

Preliminaries

There are two important requirements for building a C++ plug-in.

• The API header directories must be on the include path.
  • $CSONAR/codesonar/include
  • $CSONAR/csurf/include
• The plug-in must be built with the same pointer width as that of your CodeSonar installation. Otherwise, the plug-in compilation will fail and report errors in cs_basic_types.h.
  • If you are not sure whether you are using 32-bit or 64-bit CodeSonar, look at the "Host Platform" line in $CSONAR/SIGNATURE.txt.
  • Make sure your compiler is configured to the same pointer width. We provide command lines for some common cases below; in other cases you will need to consult your compiler documentation.

Performing the Compilation

Compilation instructions vary slightly depending on your operating system.

• Windows
• All other systems

Troubleshooting

If the build fails and reports errors in cs_basic_types.h, this generally indicates that your build has a different pointer width than that of the CodeSonar installation. If this happens:

1. Double-check the "Host Platform" line in $CSONAR/SIGNATURE.txt to make sure you know the pointer width for your CodeSonar installation
2. Make sure your build command has the same pointer width.
   In particular, make sure you have applied any build flags or other adjustments indicated in Performing the Compilation (above). Depending on your compiler, you may need to perform additional steps: consult your compiler documentation for details.

Install

Save the plug-in in directory $CSONAR/codesonar/plugins, where $CSONAR is the CodeSonar installation directory. The plug-in will be automatically loaded and run when CodeSonar runs.

If you want to save the plug-in in a different location, use the PLUGINS configuration file option to specify its file path so that CodeSonar can load and run it.

Note: you will not be able to modify plug-in .dll files in $CSONAR/codesonar/plugins, or .dll files specified by the PLUGINS option, while a CodeSonar process is running. If you encounter this problem while trying to update an existing plug-in, use the Windows Task Manager (or a similar tool) to end all codesonar.exe processes.

Implementation Notes

• Adding Visitors
• New Warning Classes
• Issuing Warnings
• Retracting Warnings
• Warning Class Information
• New Metric Classes
• Reporting and Retracting Metric Values
• Metric Information

Adding Visitors

The following table lists the available methods for adding visitors.

New Warning Classes

Issuing Warnings

Issue warnings with one of the following.

• warningclass::report() - returns a result indicating whether or not the warning was successfully reported.
• warningclass::report_return warning() - returns the reported warning object (or throws a result).

Both methods are overloaded to account for all warning-issuing cases. See the warningclass class description for details.

Retracting Warnings

Warning Class Information

New Metric Classes

Reporting and Retracting Metric Values

Automatically-reported metrics are computed and reported automatically by the CodeSonar analysis. Manually-reported metrics must be reported explicitly by the plug-in.

Both automatic and manual retraction can take place.

Other Metric Functionality

More on Plug-Ins

General Information:

Specific API Language: