Nightly build steps with Jenkins declarative pipeline

Jenkins declarative pipeline is a new(ish) pipeline syntax for Jenkins that allows you to write pipeline-as-code in a Jeninsfile. Unlike a traditional pipeline, instead of writing Groovy code, a declarative pipeline uses a custom DSL. A simple example that builds a C++ application is below:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
pipeline {
    agent any
    stages {
        stage('Clean Old Builds') {
            steps {
                sh 'rm -fr _builds'
            }
        }
 
        stage('Build') {
            sh 'cmake -H. -B_builds/default'
            sh 'cmake --build _builds/default'
        }
 
        stage('Test')
            sh 'cmake --build _builds/default --target test'
        }
    }
}

The above example, will have 3 stages that can run on any build machine.

• Stage 1, Clean Old Builds, will remove any old builds.
• Stage 2, Build, will run cmake and make.
• Stage 3, Test, will run any unit tests.

This can be cleaner and easier to read than the older Groovy based pipeline syntax.

Nightly Builds

In a previous post, I discussed how to run nightly builds using Jenkins Groovy pipelines. I tried to use the same isJobStartedByTimer function with declarative pipeline, as follows,

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
def isTimerBuild = isJobStartedByTimer()
pipeline {
...
    triggers {
        cron(env.BRANCH_NAME == 'master' ? 'H H(0-2) * * *' : '')
    }
    stages {
        ...
        stage('Nightly') {
            when {
                expression {
                    isTimerBuild == true
                }
            }
            steps {
                sh 'cmake --build _builds/default --target cppcheck
            }
        }
    }
}
// define isJobStartedByTimer function as before
@NonCPS
def isStartedByTimer() {
  ....
}

Unfortunately this failed because of an unauthorized error. I was unable to add the required values to the In Process Script Approval as they never appeared in the approval window.

Improved Method

While looking for a solution to the above problem I came across the following feature request in Jenkins. This was added in the pipeline workflow api plugin in v2.22. The core of this change is that it allows access to the build causes via the currentBuild class, instead of the sandboxed currentBuild.rawBuild class.

1
2
currentBuild.getBuildCauses()
currentBuild.getBuildCauses(String superClassName)

When using these functions you do not have to enable any In Script approvals. To get this to work I updated my isJobStartedByTimer as follows:

1
2
3
4
5
6
7
8
9
10
11
12
@NonCPS
def isJobStartedByTimer() {
    try {
        if(currentBuild.getBuildCauses('hudson.triggers.TimerTrigger$TimerTriggerCause').size() > 0) {
            echo "build started by timer"
            return true
        }
    } catch(theError) {
        echo "Error getting build cause: ${theError}"
    }
    return false
}

Using this updated function, and the example pipeline from earlier, allows me to have build steps that only run at night.

Alternative Improved Method

In some cases I found that the above improved method caused a ClassNotFoundException saying that the TimerTrigger class did not exist. An alternative example, that could be used if you have receive this error, is to use the currentBuild.getBuildCauses() version of the function. This works as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
@NonCPS
def isJobStartedByTimer() {
    try {
        for ( buildCause in currentBuild.getBuildCauses() ) {
            if (buildCause != null) {
                if (buildCause.shortDescription.contains("Started by timer")) {
                    echo "build started by timer"
                    return true
                }
            }
        }
    } catch(theError) {
        echo "Error getting build cause: ${theError}"
    }
    return false
}

Cppcheck: More Checks

In my previous posts, I discussed some errors that Cppcheck can help you find. In this post I'm going to look at some more errors that Cppcheck can prevent.

Memory Leak from realloc

When using realloc, a failure to allocate data will return a null pointer. This can lead to a common error where the original data that you tried to reallocate is leaked. For example:

1
2
3
4
5
6
7
void realloc_issue() {
    int* data = (int*)malloc(4 * sizeof(int));
    // do something
    data = (int*)realloc(data, 8*sizeof(int));
    // do something
    free(data);
}

In the above code, the original data variable is leaked if the call to realloc fails. Using Cppcheck you will get the following warning about the code:

1
[realloc.cpp:4]: (error) Common realloc mistake: 'data' nulled but not freed upon failure

To fix this error you should allow a temporary to take the returned result from realloc and only assign it to data if it is valid memory:

1
2
3
int* new_data = (int*)realloc(data, 8*sizeof(int));
if(new_data)
    data = new_data;

Invalidated Iterator

When using stl containers such as std::vector, using methods such as push_back and resize can invalidate iterators. Cppcheck has a check which can help to catch this mistake. For example:

1
2
3
4
5
6
7
8
9
10
11
void pb_it() {
    std::vector<std::string> v;
    v.push_back("first");
 
    std::vector<std::string>::iterator first = v.begin();
    for(int i = 0; i < 100; ++i) {
        v.push_back("loop");
    }
 
    std::cout << *first << "\n";
}

This will result in the following warning:

1
[push_back.cpp:10]: (error) After push_back(), the iterator 'first' may be invalid.

Note: If you use auto for the iterator or a standard algorithm to fill your vector, then Cppcheck will fail to warn about the error. For example, neither of the following will produce a warning:

1
2
3
std::vector<std::string>::iterator first = v.begin();
std::fill_n(std::back_insertor(v), 100, "loop");
std::cout << *first << "\n";

or

auto first = v.begin(); for ... std::cout << *first << "\n";

Invalid Operation on File

Using the C library functions for working on a FILE*, there is no type safe way at compile time to catch code that reads from a write only file, or writes to a read only file. However, Cppcheck has warnings which can catch this error.

1
2
3
4
5
6
7
8
9
10
11
12
13
void read_on_write_only() {
    FILE* f = fopen("xxxw", "w");
    std::array<char, 100> buf;
    fread(buf.data(), 1, 100, f);
    fclose(f);
}   
 
void write_on_read_only() {
    FILE* f = fopen("xxxf", "r");
    int x = 0;
    fwrite(&x, sizeof(int), 1, f);
    fclose(f);
}   

In the above code we use fread on a file that was opened as write only, and fwrite on a file that was opened read only. Cppcheck will output the following warnings:

1
2
[file_ops.cpp:4]: (error) Read operation on a file that was opened only for writing.
[file_ops.cpp:11]: (error) Write operation on a file that was opened only for reading.

Note: This doesn't warn with std::fstream. For example, If you open a file with ios_base::in, and try to write to it then Cppcheck will fail to warn.

Class Checks

Cppcheck has a number of both style and warning checks that can hint at potential problems with your class design. For example, take this poorly designed class:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
#include <string>
 
class Multipler
{
public:
    Multipler(int x) : x_(new int(x))
    {
    }
    ~Multipler() = default;
    Multipler& operator=(const Multipler& rhs) {
        x_ = new int(*rhs.x_);
        return *this;
    }
    int multiply(int y) const { return y * (*x_); }
 
    void name(const std::string& name) { name_ = name; }
private:
    int* x_;
    std::string name_; 
    int vx_;
};

On most compilers this will compile with no warnings. However, Cppcheck will output the following warnings:

1
2
3
4
5
6
7
[class_design.cpp:6]: (warning) Member variable 'Multipler::vx_' is not initialized in the constructor.
[class_design.cpp:10]: (warning) Member variable 'Multipler::vx_' is not assigned a value in 'Multipler::operator='.
[class_design.cpp:10]: (warning) 'operator=' should check for assignment to self to avoid problems with dynamic memory.
[class_design.cpp:6]: (style) Class 'Multipler' does not have a copy constructor which is recommended since it has dynamic memory/resource allocation(s).
[class_design.cpp:6]: (style) Class 'Multipler' has dynamic memory/resource allocation(s). The destructor is explicitly defaulted but the default destructor does not work well. It is recommended to define the destructor.
[class_design.cpp:6]: (style) Class 'Multipler' has a constructor with 1 argument that is not explicit.
[class_design.cpp:11]: (warning) Possible leak in public function. The pointer 'x_' is not deallocated before it is allocated.

These are good checks, however, you need to have style warnings enabled for some of them. If you only use enable=warning, Cppcheck will not warn about the fact that you fail to delete x_ in the destructor.

Conclusions about Cppcheck

Cppcheck is a good tool to help you write more robust and safe code. However, it is not a silver bullet to prevent errors. As noted in some of my examples, a small change to your code can mean that Cppcheck will fail to catch an error.

I have found that Cppcheck can be very helpful when taking over an old codebase that uses an older style of C++. After enabling Cppcheck, you can often catch errors that have existed in the code for years and the developers have been lucky not to hit (e.g. mistakes in error handlers). If you are using more modern C++ style, Cppcheck might not be up to date with all changes and may miss some warnings. However, I would still recommend to have it running in your CI system to prevent errors from reaching your production code.

Cppcheck: Basic Checks

In my previous posts, I've given an intro to Cppcheck and also described how to integrate it with CMake.

In this post I'm going to start looking at some of the errors that Cppcheck can help you find in your code.

Memory Leaks

Every C++ developer will have at some point written code which includes a memory leak. With modern C++ we have tools such as std::unique_ptr and std::shared_ptr to help with resource allocation, however, when using raw pointers (e.g. in legacy code), using a tool such as Cppcheck can help catch errors. For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
#include <string>
#include <iostream>
 
std::string* my_to_string(int x) {
    return new std::string(to_string(x));
}
 
void print_ints() {
    for(int i = 0; i < 10; ++i) {
        std::string* tmp = my_to_string(i);
        std::cout << tmp << "\n";
    }
}

When run against a compiler, this code doesn't produce any warnings or errors, even with the all warnings enabled. However, when run against cppcheck, we can see:

1
2
3
$ cppcheck --enable=warning  leak.cpp
Checking leak.cpp ...
[leak.cpp:12]: (error) Memory leak: tmp

Out of Bounds

Out of bounds memory access can cause issues such as a seg fault or leaking of sensitive data. Using C++ check can help to prevent OOB errors from reaching your final release. For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
#include <array>
#include <iostream>
 
const int SZ = 5;
 
std::array<int, SZ> array_oob() {
    std::array<int, SZ> arr;
    for(int i = 0; i <= SZ; ++i) {
        arr[i] = i;
    }
    return arr;
}
 
void carray_oob() {
    int arr[5];
    for(int i = 0; i <= SZ; ++i) {
        arr[i] = i;
    }
}
 
int from_outside(int c) { 
    std::array<int, SZ> arr;
    return arr[c];
}
 
void use_from_ouside() { 
    from_outside(100); 
} 

Will produce the following errors when run with Cppcheck:

1
2
3
4
5
$ cppcheck --enable=warning oob.cpp 
Checking oob.cpp ...
[oob.cpp:9]: (error) Array 'arr[5]' accessed at index 5, which is out of bounds.
[oob.cpp:17]: (error) Array 'arr[5]' accessed at index 5, which is out of bounds.
[oob.cpp:23]: (error) Array 'arr[5]' accessed at index 100, which is out of bounds.

Interestingly using Cppcheck v1.85 the following code does not produce any error:

1
2
3
4
5
6
7
std::vector<int> vector_oob() {
    std::vector<int> arr;
    for(int i = 0; i <= SZ; ++i) {
        arr[i] = i;
    }
    return arr;
}

Use After Move

Cppcheck will detect the incorrect usage of a moved from variable in the following code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
#include <string>
#include <iostream>
 
void print(std::string&& to_print) {
    std::string moved(std::move(to_print));
    std::cout << moved << "\n";
}
 
void use_after_move() {
    std::string hello = "Hello";
    print(std::move(hello));
    hello[0] = 'h';
    std::cout << hello << "\n";
}

With the following error:

1
2
3
4
$ cppcheck --enable=warning uam.cpp 
Checking uam.cpp ...
[uam.cpp:13]: (warning) Access of moved variable 'hello'.
[uam.cpp:14]: (warning) Access of moved variable 'hello'.

Integrating Cppcheck and CMake

In my previous post, I gave an introduction to the static analysis tool Cppcheck. In this post, I'm going to show how to integrate Cppcheck into the CMake build system to generate a cppcheck-analysis target for the make / ninja build systems.

CMake

CMake is a meta build system that can be used to generate files for various build systems, including make and ninja. I would recommend to have a basic knowledge of how CMake works before reading this post. For an introduction to CMake, you can read my CMake tutorial.

FindCppcheck

In CMake you can find dependencies using a find(ModuleName) command. This commands looks for a file FindModuleName.cmake and will parse this file to find the dependency and add it's requirements. For Cppcheck, you can add a FindCppcheck.cmake in a folder cmake/modules off the root of your project.

You should then add the following to your root CMakeLists.txt to tell it where to search for modules:

1
2
# Add a custom CMake Modules directory
set(CMAKE_MODULE_PATH ${CMAKE_SOURCE_DIR}/cmake/modules ${CMAKE_MODULE_PATH})

The code for the FindCppcheck.cmake is below

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
# Locate cppcheck and add a cppcheck-analysis target
#
# This module defines
#  CPPCHECK_BIN, where to find cppcheck
#
# To help find the binary you can set CPPCHECK_ROOT_DIR to search a custom path
# Exported argumets include
#   CPPCHECK_FOUND, if false, do not try to link to cppcheck --- if (CPPCHECK_FOUND)
#   
#   CPPCHECK_THREADS_ARG - Number of threads to use (default -j4)
#   CPPCHECK_PROJECT_ARG - The project to use (compile_comands.json)
#   CPPCHECK_BUILD_DIR_ARG - The build output directory (default - ${PROJECT_BINARY_DIR}/analysis/cppcheck)
#   CPPCHECK_ERROR_EXITCODE_ARG - The exit code if an error is found (default --error-exitcode=1)
#   CPPCHECK_SUPPRESSIONS - A suppressiosn file to use (defaults to .cppcheck_suppressions)
#   CPPCHECK_EXITCODE_SUPPRESSIONS - An exitcode suppressions file to use (defaults to .cppcheck_exitcode_suppressions)
#   CPPCHECK_CHECKS_ARGS - The checks to run (defaults to --enable=warning)
#   CPPCHECK_OTHER_ARGS - Any other arguments
#   CPPCHECK_COMMAND - The full command to run the default cppcheck configuration
#   CPPCHECK_EXCLUDES - A list of files or folders to exclude from the scan. Must be the full path
#   
# if CPPCHECK_XML_OUTPUT is set to an output file name before calling this. CppCheck will create an xml file with that name
# find the cppcheck binary
 
# if custom path check there first
if(CPPCHECK_ROOT_DIR)
    find_program(CPPCHECK_BIN 
        NAMES
        cppcheck
        PATHS
        "${CPPCHECK_ROOT_DIR}"
        NO_DEFAULT_PATH)
endif()
 
find_program(CPPCHECK_BIN NAMES cppcheck)
 
if(CPPCHECK_BIN)
    execute_process(COMMAND ${CPPCHECK_BIN} --version
                  OUTPUT_VARIABLE CPPCHECK_VERSION
                  ERROR_QUIET
                  OUTPUT_STRIP_TRAILING_WHITESPACE)
 
    set(CPPCHECK_THREADS_ARG "-j4" CACHE STRING "The number of threads to use")
    set(CPPCHECK_PROJECT_ARG "--project=${PROJECT_BINARY_DIR}/compile_commands.json")
    set(CPPCHECK_BUILD_DIR_ARG "--cppcheck-build-dir=${PROJECT_BINARY_DIR}/analysis/cppcheck" CACHE STRING "The build directory to use")
    # Don't show thise errors
    if(EXISTS "${CMAKE_SOURCE_DIR}/.cppcheck_suppressions")
        set(CPPCHECK_SUPPRESSIONS "--suppressions-list=${CMAKE_SOURCE_DIR}/.cppcheck_suppressions" CACHE STRING "The suppressions file to use")
    else()
        set(CPPCHECK_SUPPRESSIONS "" CACHE STRING "The suppressions file to use")
    endif()
 
    # Show these errors but don't fail the build
    # These are mainly going to be from the "warning" category that is enabled by default later
    if(EXISTS "${CMAKE_SOURCE_DIR}/.cppcheck_exitcode_suppressions")
        set(CPPCHECK_EXITCODE_SUPPRESSIONS "--exitcode-suppressions=${CMAKE_SOURCE_DIR}/.cppcheck_exitcode_suppressions" CACHE STRING "The exitcode suppressions file to use")
    else()
        set(CPPCHECK_EXITCODE_SUPPRESSIONS "" CACHE STRING "The exitcode suppressions file to use")
    endif()
 
    set(CPPCHECK_ERROR_EXITCODE_ARG "--error-exitcode=1" CACHE STRING "The exitcode to use if an error is found")
    set(CPPCHECK_CHECKS_ARGS "--enable=warning" CACHE STRING "Arguments for the checks to run")
    set(CPPCHECK_OTHER_ARGS "" CACHE STRING "Other arguments")
    set(_CPPCHECK_EXCLUDES)
 
    ## set exclude files and folders
    foreach(ex ${CPPCHECK_EXCLUDES})
        list(APPEND _CPPCHECK_EXCLUDES "-i${ex}")
    endforeach(ex)
 
    set(CPPCHECK_ALL_ARGS 
        ${CPPCHECK_THREADS_ARG} 
        ${CPPCHECK_PROJECT_ARG} 
        ${CPPCHECK_BUILD_DIR_ARG} 
        ${CPPCHECK_ERROR_EXITCODE_ARG} 
        ${CPPCHECK_SUPPRESSIONS} 
        ${CPPCHECK_EXITCODE_SUPPRESSIONS}
        ${CPPCHECK_CHECKS_ARGS} 
        ${CPPCHECK_OTHER_ARGS}
        ${_CPPCHECK_EXCLUDES}
    )
 
    # run cppcheck command with optional xml output for CI system
    if(NOT CPPCHECK_XML_OUTPUT)
        set(CPPCHECK_COMMAND 
            ${CPPCHECK_BIN}
            ${CPPCHECK_ALL_ARGS}
        )
    else()
        set(CPPCHECK_COMMAND
            ${CPPCHECK_BIN}
            ${CPPCHECK_ALL_ARGS}
            --xml 
            --xml-version=2
            2> ${CPPCHECK_XML_OUTPUT})
    endif()
 
endif()
 
 
 
# handle the QUIETLY and REQUIRED arguments and set YAMLCPP_FOUND to TRUE if all listed variables are TRUE
include(FindPackageHandleStandardArgs)
FIND_PACKAGE_HANDLE_STANDARD_ARGS(
    CPPCHECK 
    DEFAULT_MSG 
    CPPCHECK_BIN)
 
mark_as_advanced(
    CPPCHECK_BIN  
    CPPCHECK_THREADS_ARG
    CPPCHECK_PROJECT_ARG
    CPPCHECK_BUILD_DIR_ARG
    CPPCHECK_ERROR_EXITCODE_ARG
    CPPCHECK_SUPPRESSIONS
    CPPCHECK_EXITCODE_SUPPRESSIONS
    CPPCHECK_CHECKS_ARGS
    CPPCHECK_EXCLUDES
    CPPCHECK_OTHER_ARGS)
 
# If found add a cppcheck-analysis target
if(CPPCHECK_FOUND)
    file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/analysis/cppcheck)
    add_custom_target(cppcheck-analysis 
        COMMAND ${CPPCHECK_COMMAND})
    message("cppcheck found. Use cppccheck-analysis targets to run it")
else()
    message("cppcheck not found. No cppccheck-analysis targets")
endif()

This file includes comments to describe the various sections, however, I'll include some common settings that you may wish to override before calling it.

Checks to enable

To change the level of enabled checks you can use the CPPCHECK_CHECKS_ARGS variable. By default this is set to --enable=warning. You can override it to any of the supported check levels in Cppcheck.

Suppression

As discussed in my previous post you can suppress some warnings in Cppcheck using a suppression file. By default the above script will look for a suppressions file in .cppcheck_suppressions. If it exists it will add this to the command when calling cppcheck. To override this file you can change the CPPCHECK_SUPPRESSIONS argument.

1
`set(CPPCHECK_SUPPRESSIONS ${PROJECT_ROOT_DIR}/my_suppressions)

exitcode

When Cppcheck finds errors you can tell it what error code to use when exiting the program. With the above script the default exitcode is 1. To override this you can use the CPPCHECK_ERROR_EXITCODE_ARG. To set it to use the cppcheck default

1
set(CPPCHECK_ERROR_EXITCODE_ARG "")

XML output

Cppcheck supports outputting the results via XML. This can be helpful for CI systems to read the output and add a report. To enable XML output you can set the CPPCHECK_XML_OUTPUT variable to the file you want to use:

1
set(CPPCHECK_XML_OUTPUT "${PROJECT_BINARY_DIR}/analysis/cppcheck/cppcheck_analysis.xml")

Excluding files

If you have vendored third party code in your repository then you may not want to include that in your Cppcheck analysis. To exclude a file or folder you can create a list CPPCHECK_EXCLUDES

1
2
3
4
set(CPPCHECK_EXCLUDES
    ${CMAKE_SOURCE_DIR}/3rd_party
    ${CMAKE_BINARY_DIR}/
)

Calling FindCppcheck

To call cppcheck you might add something similar to the below snipped to your root CMakeLists.txt:

1
2
3
4
5
6
7
8
set(CPPCHECK_XML_OUTPUT "${PROJECT_BINARY_DIR}/analysis/cppcheck/cppcheck_analysis.xml")
 
set(CPPCHECK_EXCLUDES
    ${CMAKE_SOURCE_DIR}/3rd_party
    ${CMAKE_BINARY_DIR}/
)
 
find(Cppcheck)

This will then add the target make cppcheck-analysis to your build system. By default this target will fail your build if there are any static analysis errors.

Conclusion

In this post, I've described how you can integrated Cppcheck into your build system using CMake. This allows you to provide a simplified interface for all developers and your CI system to easily call Cppcheck as they would any other build target.

The new cppcheck-analysis target will allow for new developers to quickly call Cppcheck and also supports incremental static-analysis to encourage calling it on larger projects.

Intro to CppCheck

Cppcheck is an open-source static analysis tool for C++. In this post I'm going to describe how to install and run Cppcheck over your C++ code base.

Static Analysis

Static analysis is the analysis of code without executing it. It can be used to find common programming errors and enforce coding guidelines. Some common benefits of static analysis include:

• Prevent unexpected / undefined behaviour.
• Find security vulnerabilities and make code more secure.
• Make code more maintainable by enforcing coding standards.

The very first static analysis tool that programmers use is their compiler. In my previous blog posts, I've discussed how using multiple compilers can help catch errors and prevent undefined behaviour. Using multiple compilers is a great first step in detecting issues, however, dedicated static analysis tools can help to prevent more errors as they can look at more detailed and complex code paths to analyse issues.

Cppcheck

Cppcheck is a standalone static analysis tool that can perform the following checks:

• Undefined Behaviour
  • Dead pointers
  • Integer Overflow
  • Null pointer dereferences
  • Out of bounds checking
• Security checking including some common CVE errors
• Coding Standards

It is integrated into may common CI systems, IDEs and programming environments to allow it to be easily run over different code bases.

Installing

On Linux, most common package managers include a version of Cppcheck, however, this version is often older and out of date. As a result I recommended to install the latest version which can be found from the Cppcheck website.

For windows a binary installer is available.

For other platforms, it is easy to build the latest version from source. The only requirements are CMake and a C++11 compatible compiler. To build and install v1.85 (the latest at time or writing), you can run:

1
2
3
4
5
6
7
8
$ wget https://github.com/danmar/cppcheck/archive/1.85.tar.gz
$ tar xvf 1.85.tar.gz
$ cd cppcheck-1.85
$ mkdir build
$ cd build
$ cmake ..
$ make
$ sudo make install

You should then have cppcheck available in your path:

1
2
$ cppcheck --version
Cppcheck 1.85

Basic Usage

Single File

To run Cppcheck against a single cpp file you can run cppcheck filename.cpp. For a simple example, take the following file.

1
2
3
4
5
6
7
8
#include <array>
 
int main() {
  const int ex_sz = 5;
  std::array<int, ex_sz> ex;
  ex[ex_sz] = 1;
  return 1;
}

Under GCC and Clang this compiles without any warnings using -Wall. However, with Cppcheck I see:

1
2
3
$ cppcheck test.cpp 
Checking test.cpp ...
[test.cpp:6]: (error) Array 'ex[5]' accessed at index 5, which is out of bounds.

This simple tests shows us how using Cppcheck as a static analysis tool can save us from an out of bounds error.

Header Files

If you have header files, you can use the -I flag to tell cppcheck where to search for them.

1
cppcheck -I inc/ with_header.cpp

Recursive Checks

To recursively check all cpp files in a folder you can pass the folder name to Cppcheck.

1
cppcheck -I inc/ src/

Enabling Checks

As mentioned, Cppcheck has a number of different checks available. You can enable or disable checks by using the --enable flag.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
--enable=<id>        Enable additional checks. The available ids are:
                      * all
                              Enable all checks. It is recommended to only
                              use --enable=all when the whole program is
                              scanned, because this enables unusedFunction.
                      * warning
                              Enable warning messages
                      * style
                              Enable all coding style checks. All messages
                              with the severities 'style', 'performance' and
                              'portability' are enabled.
                      * performance
                              Enable performance messages
                      * portability
                              Enable portability messages
                      * information
                              Enable information messages
                      * unusedFunction
                              Check for unused functions. It is recommend
                              to only enable this when the whole program is
                              scanned.
                      * missingInclude
                              Warn if there are missing includes. For
                              detailed information, use '--check-config'.
                     Several ids can be given if you separate them with
                     commas. See also --std

Usage for an existing project

As you can see from the above you have to pass details about your source code to Cppcheck in order for it to understand what files to analyse, how to find dependencies, and what compiler flags to use. The easiest way to do this is to use a compilation database.

If you are using CMake you can create a compilation database using the -DCMAKE_EXPORT_COMPILE_COMMANDS=ON flag, or by adding the following to your root CMakeLists.txt.

1
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

After running CMake with this enabled a file compile_commands.json will be created. This will look like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
[
  {
    "directory": "/home/user/development/project",
    "command": "/usr/bin/c++ -Iinc -std=c+11 ... -c ../foo/foo.cc",
    "file": "../foo/foo.cc"
  },
 
  ...
 
  {
    "directory": "/home/user/development/project",
    "command": "/usr/bin/c++ -Iinc -std=c+11 ... -c ../foo/bar.cc",
    "file": "../foo/bar.cc"
  }
]

Once you have the compilation database available, you can then run Cppcheck as:

1
cppcheck --enable=all --project=compile_commands.json

Conclusions

This post showed how to install and run Cppcheck over your project. It also showed a simple example of how using static analysis can help you to detect errors. In future posts, I hope to show more advanced features of Cppcheck and also some common errors that it can help detect.

Warnings Series - Unused Result

In this series of posts I'm discussing how compiling with multiple compilers and warnings enabled can help to catch errors at development time. In the last post I discussed how to catch format errors and use compiler specific methods to annotate your code. In this post, I'm going to look at a standards compliant way to annotate your code to help the compiler identify potential errors.

Background

Starting with C++11, it is possible to add attribute specifiers to your code. These can give both your users and the compiler hints on how to treat your code. An example of such an attribute is the deprecated attribute to warn that some code (e.g. class, namespace, or function) should no longer be used and may be removed in the future.

Unused Result

The unused-result warning is issued when a function that uses the [[nodiscard]] attribute specifier is called and the returned value is not used. This attribute specifier was added to the language in C++17. It can be used to annotate functions, classes and enums.

nodiscard functions

The [[nodiscard]] attribute will encourage the compiler to issue a warning if a function declared nodiscard has it's returned value not captured. For example, the following code will issue an unused result warning.

1
2
3
4
5
6
7
8
[[nodiscard]] int* allocate_int() 
{
    return new int(1);
}
 
void test() {
    allocate_int();
}

In this code, the return value of allocate_int is a raw pointer and should always be deleted. By adding the [[nodiscard]] attribute, we are telling the compiler to warn users of the function if they ignore the value. An example of such a warning from Clang is:

1
2
3
warning: ignoring return value of function declared with 'nodiscard' attribute [-Wunused-result]
    allocate_int();
    ^

Note: This only checks that the returned value is captured and not that it is used correctly.

nodiscard classes

The [[nodiscard]] attribute can also be added to classes (and enums) to warn when they are returned by value and ignored. For example:

1
2
3
4
5
6
7
8
9
struct [[nodiscard]] use_me { };
 
use_me do_stuff() {
    return use_me{};
}
 
void test_use_me() {
    do_stuff();
}

This will issue a warning that the use of do_stuff in test_use_me is not using the returned value from that function. This is only applicable when you return the class by value. For example, the following code will not issue a warning:

1
2
3
4
5
6
7
8
9
use_me USE_ME{};
 
use_me& do_more_stuff() {
    return USE_ME;
}
 
void test_use_me_ref() {
    do_more_stuff();
}

Ignoring nodiscard

If a function is marked [[nodiscard]] but for some reason you know you can safely ignore the result, you can use a void cast to ignore the value. In the case of our do_stuff function above, we could call it as below to safely ignore the warning:

1
static_cast<void>(do_stuff());

While C style casts are often discouraged in new code, for a case such as this it can make for easier to read code.

1
(void)do_stuff();

Catching the error

Clang

With newer versions of Clang, you will receive the unused-result warning when compiling with C++11, 14 or 17 on all warning levels. With older versions prior to v3.9, you may receive a warning that the nodiscard attribute is not known.

GCC

Similar to Clang, with newer versions of GCC you will receive the unused-result warning when compiling with the C++11, 14 or 17 standards on all warning levels. For GCC versions earlier than GCC 7, you will receive a the unknown-attribute warning.

MSVC

On MSVC 2018, you will receive the warning C4834 when compiling with the /std:c++latest flag. For example:

1
2
<source>(12): warning C4834: discarding return value of function with 'nodiscard' attribute
<source>(25): warning C4834: discarding return value of function with 'nodiscard' attribute

Earlier versions of MSVC, do not appear to display any related warnings, however, they do ignore the unknown attribute and allow the code to compile.

Comparing the errors

To view the errors from each compiler you can use godbolt to compare the output.

Warnings Series - Format

In this series of posts I'm discussing how compiling with multiple compilers and warnings enabled can help to catch errors. In the last post I discussed how to turn return type warnings into errors. In this post, I'm going to look at another warning that I often promote to an errors.

Background

As discussed in my previous posts, you can turn specific warnings into error using the -Werror=warning-name command line flag on GCC and Clang. In some cases you can also annotate code in order enable checking it for a warning type.

Format

The format warning lets you know when you have used the incorrect format specifier for the printf family of functions. For example:

1
2
long i = 4294967295;
printf("%d\n", i);

In the above example, using %d instead of %ld may print the value -1 instead of the expected value 4294967295. For a simple cause of a log statement, the incorrect value might not matter, however, if you are serializing a value to a file it may cause issues for your users.

In another example:

1
2
long i = 1;
printf("%s\n", i);

You are attempting to print a number using the string format specifier. This specifier expects a null terminated string and as a result it will cause undefined behaviour which could create security and stability issues.

Catching the error

Clang

When compiling with Clang this is a warning by default when using no compiler flags. To promote the warning to an error you can use -Werror=format. Below is an example of the warning from Clang:

1
2
3
4
5
6
7
8
9
<source>:23:18: warning: format specifies type 'int' but the argument has type 'int64_t' (aka 'long') [-Wformat]
  printf("%d\n", i);
          ~~     ^
          %ld
<source>:24:18: warning: format specifies type 'char *' but the argument has type 'int64_t' (aka 'long') [-Wformat]
  printf("%s\n", i);
          ~~     ^
          %ld
2 warnings generated.

GCC

For GCC the warning is not enabled by default. It is included as part of the -Wall flag or can be enabled individually using -Wformat. To promote it to an error you can use -Werror=format.

Note: From v8.0 of GCC you will receive a warning with no additional compiler flags.

MSVC

With MSVC the warning for standard printf functions is enabled by default.

Attributing your own functions

It can sometimes be the case that you want to make your own function which takes a format specifier (e.g. a logging function):

1
2
3
4
5
6
7
8
9
void my_logger(int level, const char* format, ...)
{
    if(level >= LOGGING_LEVEL) {
        va_list(args);
        va_start(args, format);
        vfprintf(stderr, format, args);
        va_end(args);
    }
}

Which you can call as:

1
my_logger(WARN,"%s\n", i);

In this case the normal format warning won't appear in you code to warn you of errors. If using GCC and Clang, you can add a non-standard function attribute to tell the compiler that a function takes a format argument.

1
void my_logger(int level, const char* format, ...) __attribute__ ((format (printf, 2, 3)));

After adding this you can will receive the following warning warning:

1
2
3
4
<source>:26:27: warning: format specifies type 'char *' but the argument has type 'int64_t' (aka 'long') [-Wformat]
  my_logger(WARN, "%s\n", i);
                   ~~     ^
                   %ld

Note: This is not available on MSVC, so the addition of this attribute should be hidden behind a conditional compiler flag.

Comparing the errors

To view the errors from each compiler you can use godbolt to compare the output.