Understanding the workflow

Creating a custom function is a simple process after you get used to the workflow and the tools provided by the kwcreatechecker utility. Before you start, you need to decide:

• what to call your checker (also known as issue code)
• what to call the library in which your custom function or functions will be linked

For the purposes of this article, we'll use 'TUTORIAL' as the code of the checker, and 'tutorial' as the name of the library that will contain the custom functions we create. Library names don't need extensions, as they are automatically generated specific to the platform in use (DLL for Windows, SO for Linux, DYLIB for Mac, and so on).

Creating the checker stub files

The kwcreatechecker utility is used to create the stub files for the checker:

$ kwcreatechecker --code TUTORIAL --type kast --language cxx --kast-library tutorial

This command creates a working directory, called TUTORIAL, a set of stub files in that directory, and a sub-directory specific to your OS for the custom function files. The content of the TUTORIAL directory is:

• Makefile, the overall build script
• Makefile.plugin, the specific build script for the custom function
• PluginSource.cpp, the template source for the custom function
• checkers.xml, the template definition for the checker
• help.xml, the template definition for the checker help
• ix86-apple-macosx/, the working folder in which custom function will be linked
• testcase.cc, the template source for a test case

The example is created on a Mac, but the only difference for other platforms is the name of the subfolder used to link the custom function library. With these files, you've got everything you need to start creating a custom function or set of functions and testing them.

Using the basic workflow

After you generate the stub files with kwcreatechecker, the initial workflow is:

1. Create a local project in the working directory (TUTORIAL in the example) with kwcheck create.
2. Edit checkers.xml (potentially using Checker Studio for prototyping) to define the KAST expression that will exercise your custom function.
3. Edit testcase.cc with positive and negative examples showing the defect pattern you want the checker to find.
4. Execute the build script to generate a build specification for your test case with 'make buildspec', and import it into your local project with kwcheck import kwinject.out.
5. Edit PluginSource.cpp to create or update one or more custom functions.
6. Generate the checker with 'make install' to build an installable checker deployment package.
7. Install your checker locally on your desktop by unzipping the checker deployment package into the ~/.klocwork/plugins directory. For example:

   unzip -o TUTORIAL.zip -d ~/.klocwork/plugins

8. Check your checker with kwcheck run to see if it does what you want.
9. If it doesn't succeed, repeat the process from step 5 until it's successful.

Customizing the workflow

You can follow that template workflow, or automate it a little by modifying the generated build script for your own purposes. For example, to specialize the Makefile for our purposes, we could modify it to complete the installation of the checker (not just prepare it for installation), and automate testing the checker against the test case.

For example, we can:

• add a new default target to the makefile:

 all: install run

• include an unzip command in the install target (e.g. unzip -o TUTORIAL.zip -d ~/.klocwork/plugins)
• add a target similar to this one for testing:

 run: buildspec
        rm -rf .kwlp
        rm -rf .kwps
        "$(KW_INSTALL_DIR)/bin/kwcheck"-? create -b kwinject.out
        "$(KW_INSTALL_DIR)/bin/kwcheck"-? run

Our example is based on a Unix platform, and on other platforms the Makefile modifications would be different, but the purpose is the same. With the changes we've made, the workflow is simplified to:

1. Edit checkers.xml to define the KAST expression that will exercise your function.
2. Edit testcase.cc to appropriately exercise your checker.
3. Edit PluginSource.cpp to create or update your custom function.
4. Test your custom function with 'make' (this will run the 'install' and 'run' targets if you've modified Makefile according to the description above).
5. Repeat the process from step 3, or even step 1 or 2, until you're happy with the checker.

There are also further steps that you might find useful for customizing the workflow, such as:

• changing the names of the default local project folders to make finding them easier
• changing the name of the license host to which the project is connected
• splitting the test case code into its own build script