diff --git a/gui/help/ch01.html b/gui/help/ch01.html deleted file mode 100644 index 76ab08bb7..000000000 --- a/gui/help/ch01.html +++ /dev/null @@ -1,13 +0,0 @@ -
Cppcheck is an analysis tool for C/C++ code. Unlike C/C++ compilers - and many other analysis tools, it doesn't detect syntax errors. Cppcheck - only detects the types of bugs that the compilers normally fail to detect. - The goal is no false positives.
Supported code and platforms:
You can check non-standard code that includes various compiler - extensions, inline assembly code, etc.
Cppcheck should be compilable by any C++ compiler that handles - the latest C++ standard.
Cppcheck should work on any platform that has sufficient cpu and - memory.
Accuracy
Please understand that there are limits of Cppcheck. Cppcheck is - rarely wrong about reported errors. But there are many bugs that it - doesn't detect.
You will find more bugs in your software by testing your software - carefully, than by using Cppcheck. You will find more bugs in your - software by instrumenting your software, than by using Cppcheck. But - Cppcheck can still detect some of the bugs that you miss when testing and - instrumenting your software.
Table of Contents
Normally a program has many sourcefiles. And you want to check - them all. Cppcheck can check all sourcefiles in a directory:
cppcheck path
If "path" is a folder then cppcheck will check all sourcefiles in - this folder.
Checking path/file1.cpp... -1/2 files checked 50% done -Checking path/file2.cpp... -2/2 files checked 100% done
There is no command to exclude a file or folder from checking. But - you can exclude a file or folder by being more careful when including - files and folders in the checking.
Imagine for example that the folder "src" contain the folders "a", - "b" and "c". To exclude "c" this command can be used:
cppcheck src/a src/b
All files under "src/a" and "src/b" are then checked.
The flag --file-list
might also be
- useful.
By default Cppcheck will only check for bugs. There are also a few - checks for stylistic issues.
Here is a simple code example:
void f(int x) -{ - int i; - if (x == 0) - { - i = 0; - } -}
To enable stylistic checks, use the --style flag:
cppcheck --enable=style file1.c
The reported error is:
[file3.c:3]: (style) The scope of the variable i can be limited
Many times you will want to save the results in a file. You can - use the normal shell redirection for piping error output to a - file.
cppcheck file1.c 2> err.txt
This check will try to find unused functions. It is best to use - this when the whole program is checked, so that all usages is seen by - cppcheck.
cppcheck --enable=unusedFunctions path
To enable all checks your can use the
- --enable=all
flag:
cppcheck --enable=all path
By default Cppcheck will check all preprocessor configurations - (except those that has #error in them). This is the recommended - behaviour.
But if you want to manually limit the checking you can do so with
- -D
.
Beware that only the macros, which are given here and the macros - defined in source files and known header files are considered. That - excludes all the macros defined in some system header files, which are by - default not examined by cppcheck.
The usage: if you, for example, want to limit the checking so the - only configuration to check should be "DEBUG=1;__cplusplus" then something - like this can be used:
cppcheck -DDEBUG=1 -D__cplusplus path
An alternative for -D is to use #error.
#if LIB_VERSION <= 3 -#error "lib version must be greater than 3" -#endif
Using #error instead of -D have some advantages:
the compiler will not be able to compile the code when invalid - defines are given. So #error makes your source code - safer/better.
Cppcheck will check all valid configurations instead of a single - configuration.
This information is added to the source code which means you - don't need to provide this information to Cppcheck (makes it simpler - to use Cppcheck)
Cppcheck can generate the output in XML format.
Use the --xml flag when you execute cppcheck:
cppcheck --xml file1.cpp
The xml format is:
<?xml version="1.0"?> -<results> - <error file="file1.cpp" line="123" id="someError" - severity="error" msg="some error text"/> -</results>
Attributes:
filename. Both relative and absolute paths are possible
a number
id of error. These are always valid symbolnames.
either error or style
the error message
If you want to reformat the output so it looks different you can use - templates.
To get Visual Studio compatible output you can use "--template - vs":
cppcheck --template vs gui/test.cpp
This output will look like this:
Checking gui/test.cpp... -gui/test.cpp(31): error: Memory leak: b -gui/test.cpp(16): error: Mismatching allocation and deallocation: k
To get gcc compatible output you can use "--template gcc":
cppcheck --template gcc gui/test.cpp
The output will look like this:
Checking gui/test.cpp... -gui/test.cpp:31: error: Memory leak: b -gui/test.cpp:16: error: Mismatching allocation and deallocation: k
You can write your own pattern (for example a comma-separated - format):
cppcheck --template "{file},{line},{severity},{id},{message}" gui/test.cpp
The output will look like this:
Checking gui/test.cpp... -gui/test.cpp,31,error,memleak,Memory leak: b -gui/test.cpp,16,error,mismatchAllocDealloc,Mismatching allocation and deallocation: k
If you want to filter out certain errors you can suppress these. - First you need to create a suppressions file. The format is:
[error id]:[filename]:[line] -[error id]:[filename2] -[error id]
The error id
is the id that you want to suppress.
- The easiest way to get it is to use the --xml
command
- line flag. Copy and paste the id
string from the xml
- output.
Here is an example:
memleak:file1.cpp -exceptNew:file1.cpp -uninitvar
You can then use the suppressions file:
cppcheck --suppressions suppressions.txt src/
Table of Contents
Looking for memory leaks and resource leaks is a key feature of - Cppcheck. Cppcheck can detect many common mistakes by default. But through - some tweaking you can improve the checking.
Cppcheck
understands many common allocation and
- deallocation functions. But not all.
Here is example code that might leak memory or resources:
void foo(int x) -{ - void *f = CreateFred(); - if (x == 1) - return; - DestroyFred(f); -}
If you analyse that with Cppcheck it won't find any leaks:
cppcheck --enable=possibleError fred1.cpp
You can add some custom leaks checking by providing simple - implementations for the allocation and deallocation functions. Write - this in a separate file:
void *CreateFred() -{ - return malloc(100); -} - -void DestroyFred(void *p) -{ - free(p); -}
When Cppcheck see this it understands that CreateFred will return - allocated memory and that DestroyFred will deallocate memory.
Now, execute Cppcheck
this way:
cppcheck --append=fred.cpp fred1.cpp
The output from cppcheck is:
Checking fred1.cpp... -[fred1.cpp:5]: (error) Memory leak: f
Cppcheck has a few checks that ensure that you don't break the basic - guarantee of exception safety. It doesn't have any checks for the strong - guarantee yet.
Example:
Fred::Fred() : a(new int[20]), b(new int[20]) -{ -}
By default cppcheck will not detect any problems in that - code.
To enable the exception safety checking you can use
- --enable
:
cppcheck --enable=exceptNew --enable=exceptRealloc fred.cpp
The output will be:
[fred.cpp:3]: (style) Upon exception there is memory leak: a
If an exception occurs when b
is allocated,
- a
will leak.
Here is another example:
int *p; - -int a(int sz) -{ - delete [] p; - if (sz <= 0) - throw std::runtime_error("size <= 0"); - p = new int[sz]; -}
Check that with Cppcheck:
cppcheck --enable=exceptNew --enable=exceptRealloc except2.cpp
The output from Cppcheck is:
[except2.cpp:7]: (error) Throwing exception in invalid state, p points at deallocated memory
You can convert the xml output from cppcheck into a html report.
- You'll need python and the pygments module
- (http://pygments.org/
) for this to work. In the Cppcheck source
- tree there is a folder "htmlreport" that contains a script that transforms
- a Cppcheck xml file into html output.
This command generates the help screen:
htmlreport/cppcheck-htmlreport -h
The output screen says:
Usage: cppcheck-htmlreport [options] - -Options: - -h, --help show this help message and exit - --file=FILE The cppcheck xml output file to read defects from. - Default is reading from stdin. - --report-dir=REPORT_DIR - The directory where the html report content is written. - --source-dir=SOURCE_DIR - Base directory where source code files can be found.
An example usage:
./cppcheck gui/test.cpp --xml 2> err.xml -htmlreport/cppcheck-htmlreport --file=err.xml --report-dir=test1 --source-dir=.
Table of Contents
The results are shown in a list.
You can show/hide certain types of messages through the
- View
menu.
Results can be saved to an xml file that can later be opened. See
- Save results to file
and Open
- XML
.
The language can be changed at any time by using the
- Language
menu.
More settings are available in
- Edit
>Preferences
.
The project files are used to store project specific settings. - These settings are:
include folders
preprocessor defines
It isn't recommended to provide the paths to the standard C/C++ - headers - Cppcheck has internal knowledge about ANSI C/C++ and it isn't - recommended that this known functionality is redefined. But feel free to - try it.
As you can read in chapter 3 in this manual the default is that - Cppcheck checks all configurations. So only provide preprocessor defines - if you want to limit the checking.
Cppcheck is an analysis tool for C/C++ code. Unlike C/C++ compilers + and many other analysis tools, it doesn't detect syntax errors. Cppcheck + only detects the types of bugs that the compilers normally fail to detect. + The goal is no false positives.
Supported code and platforms:
You can check non-standard code that includes various compiler + extensions, inline assembly code, etc.
Cppcheck should be compilable by any C++ compiler that handles + the latest C++ standard.
Cppcheck should work on any platform that has sufficient cpu and + memory.
Accuracy
Please understand that there are limits of Cppcheck. Cppcheck is + rarely wrong about reported errors. But there are many bugs that it + doesn't detect.
You will find more bugs in your software by testing your software + carefully, than by using Cppcheck. You will find more bugs in your + software by instrumenting your software, than by using Cppcheck. But + Cppcheck can still detect some of the bugs that you miss when testing and + instrumenting your software.
Here is a simple code
int main() +{ + char a[10]; + a[10] = 0; + return 0; +}
If you save that into file1.c and + execute:
cppcheck file1.c
The output from cppcheck will then be:
Checking file1.c... +[file1.c:4]: (error) Array 'a[10]' index 10 out of bounds
Normally a program has many sourcefiles. And you want to check + them all. Cppcheck can check all sourcefiles in a directory:
cppcheck path
If "path" is a folder then cppcheck will check all sourcefiles in + this folder.
Checking path/file1.cpp... +1/2 files checked 50% done +Checking path/file2.cpp... +2/2 files checked 100% done
There is no command to exclude a file or folder from checking. But + you can exclude a file or folder by being more careful when including + files and folders in the checking.
Imagine for example that the folder "src" contain the folders "a", + "b" and "c". To exclude "c" this command can be used:
cppcheck src/a src/b
All files under "src/a" and "src/b" are then checked.
The flag --file-list might also be + useful.
The possible severities for messages are:
used when bugs are found
suggestions about defensive programming to prevent + bugs
stylistic issues related to code cleanup (unused functions, + redundant code, constness, and such)
suggestions for making the code faster
By default only error messages are shown. + Through the --enable command more checks can be + enabled.
With --enable=style you enable most + warning, style and + performance messages.
Here is a simple code example:
void f(int x) +{ + int i; + if (x == 0) + { + i = 0; + } +}
There are no bugs in that code so Cppcheck won't report anything + by default. To enable the stylistic messages, use the --enable=style + command:
cppcheck --enable=style file3.c
The output from Cppcheck is now:
Checking file3.c... +[file3.c:3]: (style) Variable 'i' is assigned a value that is never used +[file3.c:3]: (style) The scope of the variable i can be reduced
This check will try to find unused functions. It is best to use + this when the whole program is checked, so that all usages is seen by + cppcheck.
cppcheck --enable=unusedFunction path
To enable all checks your can use the + --enable=all flag:
cppcheck --enable=all path
Many times you will want to save the results in a file. You can + use the normal shell redirection for piping error output to a + file.
cppcheck file1.c 2> err.txt
By default Cppcheck will check all preprocessor configurations + (except those that has #error in them). This is the recommended + behaviour.
But if you want to manually limit the checking you can do so with + -D.
Beware that only the macros, which are given here and the macros + defined in source files and known header files are considered. That + excludes all the macros defined in some system header files, which are by + default not examined by cppcheck.
The usage: if you, for example, want to limit the checking so the + only configuration to check should be "DEBUG=1;__cplusplus" then something + like this can be used:
cppcheck -DDEBUG=1 -D__cplusplus path
Cppcheck can generate the output in XML format.
Use the --xml flag when you execute cppcheck:
cppcheck --xml file1.cpp
The xml format is:
<?xml version="1.0"?> +<results> + <error file="file1.cpp" line="123" id="someError" + severity="error" msg="some error text"/> +</results>
Attributes:
filename. Both relative and absolute paths are possible
a number
id of error. These are always valid symbolnames.
either error or style. + warning and performance are + saved as style.
the error message
If you want to reformat the output so it looks different you can use + templates.
To get Visual Studio compatible output you can use "--template + vs":
cppcheck --template vs gui/test.cpp
This output will look like this:
Checking gui/test.cpp... +gui/test.cpp(31): error: Memory leak: b +gui/test.cpp(16): error: Mismatching allocation and deallocation: k
To get gcc compatible output you can use "--template gcc":
cppcheck --template gcc gui/test.cpp
The output will look like this:
Checking gui/test.cpp... +gui/test.cpp:31: error: Memory leak: b +gui/test.cpp:16: error: Mismatching allocation and deallocation: k
You can write your own pattern (for example a comma-separated + format):
cppcheck --template "{file},{line},{severity},{id},{message}" gui/test.cpp
The output will look like this:
Checking gui/test.cpp... +gui/test.cpp,31,error,memleak,Memory leak: b +gui/test.cpp,16,error,mismatchAllocDealloc,Mismatching allocation and deallocation: k
If you want to filter out certain errors you can suppress these. + First you need to create a suppressions file. The format is:
[error id]:[filename]:[line] +[error id]:[filename2] +[error id]
The error id is the id that you want to suppress. + The easiest way to get it is to use the --xml command + line flag. Copy and paste the id string from the xml + output.
Here is an example:
memleak:file1.cpp +exceptNew:file1.cpp +uninitvar
You can then use the suppressions file:
cppcheck --suppressions suppressions.txt src/
Looking for memory leaks and resource leaks is a key feature of + Cppcheck. Cppcheck can detect many common mistakes by default. But through + some tweaking you can improve the checking.
Cppcheck understands many common allocation and + deallocation functions. But not all.
Here is example code that might leak memory or resources:
void foo(int x) +{ + void *f = CreateFred(); + if (x == 1) + return; + DestroyFred(f); +}
If you analyse that with Cppcheck it won't find any leaks:
cppcheck --enable=possibleError fred1.cpp
You can add some custom leaks checking by providing simple + implementations for the allocation and deallocation functions. Write + this in a separate file:
void *CreateFred() +{ + return malloc(100); +} + +void DestroyFred(void *p) +{ + free(p); +}
When Cppcheck see this it understands that CreateFred will return + allocated memory and that DestroyFred will deallocate memory.
Now, execute Cppcheck this way:
cppcheck --append=fred.cpp fred1.cpp
The output from cppcheck is:
Checking fred1.cpp... +[fred1.cpp:5]: (error) Memory leak: f
Cppcheck has a few checks that ensure that you don't break the basic + guarantee of exception safety. It doesn't have any checks for the strong + guarantee yet.
Example:
Fred::Fred() : a(new int[20]), b(new int[20]) +{ +}
By default cppcheck will not detect any problems in that + code.
To enable the exception safety checking you can use + --enable:
cppcheck --enable=exceptNew --enable=exceptRealloc fred.cpp
The output will be:
[fred.cpp:3]: (style) Upon exception there is memory leak: a
If an exception occurs when b is allocated, + a will leak.
Here is another example:
int *p; + +int a(int sz) +{ + delete [] p; + if (sz <= 0) + throw std::runtime_error("size <= 0"); + p = new int[sz]; +}
Check that with Cppcheck:
cppcheck --enable=exceptNew --enable=exceptRealloc except2.cpp
The output from Cppcheck is:
[except2.cpp:7]: (error) Throwing exception in invalid state, p points at deallocated memory
You can convert the xml output from cppcheck into a html report. + You'll need python and the pygments module + (http://pygments.org/) for this to work. In the Cppcheck source + tree there is a folder "htmlreport" that contains a script that transforms + a Cppcheck xml file into html output.
This command generates the help screen:
htmlreport/cppcheck-htmlreport -h
The output screen says:
Usage: cppcheck-htmlreport [options] + +Options: + -h, --help show this help message and exit + --file=FILE The cppcheck xml output file to read defects from. + Default is reading from stdin. + --report-dir=REPORT_DIR + The directory where the html report content is written. + --source-dir=SOURCE_DIR + Base directory where source code files can be found.
An example usage:
./cppcheck gui/test.cpp --xml 2> err.xml +htmlreport/cppcheck-htmlreport --file=err.xml --report-dir=test1 --source-dir=.
A Cppcheck GUI is available.
The main screen is shown immediately when the GUI is + started.
The results are shown in a list.
You can show/hide certain types of messages through the + View menu.
Results can be saved to an xml file that can later be opened. See + Save results to file and Open + XML.
The language can be changed at any time by using the + Language menu.
More settings are available in + Edit>Preferences.
The project files are used to store project specific settings. + These settings are:
include folders
preprocessor defines
It isn't recommended to provide the paths to the standard C/C++ + headers - Cppcheck has internal knowledge about ANSI C/C++ and it isn't + recommended that this known functionality is redefined. But feel free to + try it.
As you can read in chapter 3 in this manual the default is that + Cppcheck checks all configurations. So only provide preprocessor defines + if you want to limit the checking.