From 9ec5ae2929dcded279c3c9d73330c201fc90d031 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Marjam=C3=A4ki?= Date: Sat, 18 Jul 2020 15:27:25 +0200 Subject: [PATCH] GUI: Started writing a manual --- man/gui-manual.md | 183 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 183 insertions(+) create mode 100644 man/gui-manual.md diff --git a/man/gui-manual.md b/man/gui-manual.md new file mode 100644 index 000000000..d4ccee5ac --- /dev/null +++ b/man/gui-manual.md @@ -0,0 +1,183 @@ +--- +title: Cppcheck GUI manual +subtitle: Version 2.1.99 +author: Cppcheck team +lang: en +documentclass: report +--- + + +# Standalone analysis + +It is possible to quickly analyze files. Open the `Analyze` menu and click on either `Files...` or `Directory...`. + +It is recommended that you create a project for analysis. A properly configured project will give you better analysis. + +# Project + +## Creating project + +Open the `File` menu and click on `New project...`. + +## Project options + +The `Project file` dialog contains 4 tabs: + - Paths and defines; paths to check and basic preprocessor settings. + - Types and Functions; configuration of platform and 3rd party libraries + - Analysis; analysis options + - Warning options; formatting warnings, suppressing warnings, etc + - Addons; extra analysis with addons + +### Paths and defines + +It is recommended to import a project file. + +#### Import project + +Project to import. Cppcheck will get: + * what files to check + * preprocessor defines + * preprocessor include paths + * language standard if set + +#### Paths (If you do not import project) + +What paths to check. + +#### Defines (If you do not import project) + +Cppcheck automatically checks the code with different preprocessor configurations. + + #ifdef A + code1 + #endif + #ifdef B + code2 + #endif + +Cppcheck will automatically perform analysis both when A is defined and B is defined. So any bugs in both code1 and code2 will be detected. + +If you want to configure that A will always be defined in Cppcheck analysis you can do that here. + +Defines are separated by semicolon. So you can for instance write: + + A;B=3;C + +#### Undefines (If you do not import project) + + +Cppcheck automatically checks the code with different preprocessor configurations. + + #ifdef A + code1 + #endif + #ifdef B + code2 + #endif + +Cppcheck will automatically perform analysis both when A is defined and B is defined. So any bugs in both code1 and code2 will be detected. + +If you want to configure that A is never defined in Cppcheck analysis you can do that here. + +Undefines are separated by semicolon. So you can for instance write: + + A;C + +#### Include paths (If you do not import project) + +Specify include paths. + +### Types and Functions + +Cppcheck uses `Platform` setting to determine size of short/int/long/pointer/etc. + +Check the libraries that you use in the `Libraries` listbox. + +### Analysis + +#### Cppcheck build dir + +This is a work-folder that Cppcheck uses. Each Cppcheck project should have a separate build dir. It is used for: + * whole program analysis + * debug output + * faster analysis (if a source file has changed check it, if source file is not changed then reuse old results) + * statistics + +#### Parser + +It is in general recommended to use Cppcheck parser. However you can choose to use Clang parser; Clang will be executed with a command line flag that tells it to dump its AST and Cppcheck will read that AST and convert it into a corresponding Cppcheck AST and use that. + +#### Analysis + +Configure what kind of analysis you want. + +The `Normal analysis` is recommended for most use cases. Especially if you use Cppcheck in CI. + +The `Bug hunting` can be used if you really want to find a bug in your code and can invest time looking at bad results and providing extra configuration. + +#### Limit analysis + +You can turn off checking of headers. That could be interesting if Cppcheck is very slow. But normally, you should check the code in headers. + +It is possible to check the code in unused templates. However the Cppcheck AST will be incomplete/wrong. The recommendation is that you do not check unused templates to avoid wrong warnings. The templates will be checked properly when you do use them. + +Max CTU depth: How deep should the whole program analysis be. The risk with a "too high" value is that Cppcheck will be slow. + +Max recursion in template instantiation: Max recursion when Cppcheck instantiates templates. The risk with a "too high" value is that Cppcheck will be slow and can require much memory. + + +### Warning options + +#### Root path + +The root path for warnings. Cppcheck will strip away this part of the path from warnings. For instance if there is a warning in `../myproject/foo/bar/file.cpp` and the root path is `../myproject/foo` then the path for the warning will be `bar/file.cpp`. + +#### Warning Tags + +Tags allow you to manually categorize warnings. + +#### Exclude source files + +Excluded source files will not be analyzed by Cppcheck + +#### Suppressions + +List of suppressions. These warnings will not be shown. + +### Addons + +Y2038 - 32-bit timers that count number of seconds since 1970 will overflow in year 2038. Check that the code does not use such timers. + +Thread safety - Check that the code is thread safe + +Cert - Ensure that the Cert coding standard is followed + +Misra - Ensure that the Misra coding standard is followed. Please note you need to have a textfile with the misra rule texts to get proper warning messages. Cppcheck is not legally allowed to distribute the misra rule texts. + +Clang-tidy - Run Clang-tidy + + +# Preferences + +TODO + + +# Looking at results + +When you have run the analysis it is time to look at the results. + +If you click on a warning then the corresponding code will be shown in the "Warning details" at the bottom. + +You can right click warnings to get options. The difference of "hiding" a warning and "suppressing" a warning is that the suppression is permanent and hiding the warning is only temporary. + + +# Tagging warnings + +You can manually categorize warnings. + +You choose the names of the categories yourself in the project file dialog. + +If tag names are configured then when you look at results you can right click on a warning and tag it. + + +