From a36c464a86a5e80cfb8f51c43976bc7b3a6909aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Marjam=C3=A4ki?= Date: Thu, 13 Nov 2025 14:52:25 +0100 Subject: [PATCH 1/7] Fixed #14266 (documentation: clarify how -i works) --- cli/cmdlineparser.cpp | 7 ++++--- man/manual.md | 8 ++++---- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/cli/cmdlineparser.cpp b/cli/cmdlineparser.cpp index cb70269c380..88c034c49e9 100644 --- a/cli/cmdlineparser.cpp +++ b/cli/cmdlineparser.cpp @@ -1837,9 +1837,10 @@ void CmdLineParser::printHelp(bool premium) const " this is not needed.\n" " --include=\n" " Force inclusion of a file before the checked file.\n" - " -i Exclude source files or directories matching str from\n" - " the check. This applies only to source files so header\n" - " files included by source files are not matched.\n" + " -i Skip translation units whose *source filename* matches\n" + " ''. '' can be a filename or directory.\n" + " Note: If you want to prevent warnings in some headers,\n" + " use suppressions instead.\n" " --inconclusive Allow that Cppcheck reports even though the analysis is\n" " inconclusive.\n" " There are false positives with this option. Each result\n" diff --git a/man/manual.md b/man/manual.md index 3ce784de298..a26ffae79a8 100644 --- a/man/manual.md +++ b/man/manual.md @@ -126,13 +126,13 @@ Typically a `compile_commands.json` contains absolute paths. However no matter i * a file with relative path `src/test2.c` can be checked. * a file with relative path `src/test3.cpp` is not checked. -### Excluding a file or folder from checking +### Exclude files matching a given pattern -The option `-i` specifies a pattern to files/folders to exclude. With this command no files in `src/c` are checked: +With `-i ` you can configure filename/directory patterns that should be excluded from checking. - cppcheck -isrc/c src +> *Note*: If you want to filter out warnings for a header file then `-i` will not work. The option `--suppress` should be used instead. -The `-i` option is not used during preprocessing, it can't be used to exclude headers that are included. +Translation units are skipped if their *source filename* matches the exclusion pattern. This filtering happens *before* preprocessing, and the exclusion patterns are not applied during preprocessing or analysis. You can use `**`, `*` and `?` in the pattern to specify excluded folders/files. `**`: matches zero or more characters, including path separators From 581a9c481e1070e9cccd6285e6724b81675c7546 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Marjam=C3=A4ki?= Date: Thu, 13 Nov 2025 16:35:16 +0100 Subject: [PATCH 2/7] review --- man/manual.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/man/manual.md b/man/manual.md index a26ffae79a8..e2a48b8326e 100644 --- a/man/manual.md +++ b/man/manual.md @@ -130,7 +130,7 @@ Typically a `compile_commands.json` contains absolute paths. However no matter i With `-i ` you can configure filename/directory patterns that should be excluded from checking. -> *Note*: If you want to filter out warnings for a header file then `-i` will not work. The option `--suppress` should be used instead. +> *Note*: If you want to filter out warnings for a header file then `-i` will not work. The option `--suppress` should be used instead. Any header included in a source file which is not excluded would be processed regardless the `-i` option applied to that header. Translation units are skipped if their *source filename* matches the exclusion pattern. This filtering happens *before* preprocessing, and the exclusion patterns are not applied during preprocessing or analysis. From dccbb887ce829473e5ee36fa5647623f2faf25d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Marjam=C3=A4ki?= Date: Thu, 13 Nov 2025 16:47:25 +0100 Subject: [PATCH 3/7] exclude=>ignore --- man/manual.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/man/manual.md b/man/manual.md index e2a48b8326e..3b52dbbeda8 100644 --- a/man/manual.md +++ b/man/manual.md @@ -126,11 +126,11 @@ Typically a `compile_commands.json` contains absolute paths. However no matter i * a file with relative path `src/test2.c` can be checked. * a file with relative path `src/test3.cpp` is not checked. -### Exclude files matching a given pattern +### Ignore/skip files matching a given pattern -With `-i ` you can configure filename/directory patterns that should be excluded from checking. +With `-i ` you can configure filename/directory patterns that should be ignored/skipped. -> *Note*: If you want to filter out warnings for a header file then `-i` will not work. The option `--suppress` should be used instead. Any header included in a source file which is not excluded would be processed regardless the `-i` option applied to that header. +> *Note*: If you want to filter out warnings for a header file then `-i` will not work. The option `--suppress` should be used instead. Any header included in a source file which is not ignored would be processed regardless the `-i` option applied to that header. Translation units are skipped if their *source filename* matches the exclusion pattern. This filtering happens *before* preprocessing, and the exclusion patterns are not applied during preprocessing or analysis. From 98011b53e42cafe762553289adbc628005806209 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Marjam=C3=A4ki?= Date: Fri, 14 Nov 2025 08:28:35 +0100 Subject: [PATCH 4/7] Update cli/cmdlineparser.cpp Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- cli/cmdlineparser.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cli/cmdlineparser.cpp b/cli/cmdlineparser.cpp index 88c034c49e9..168e8f67721 100644 --- a/cli/cmdlineparser.cpp +++ b/cli/cmdlineparser.cpp @@ -1838,7 +1838,7 @@ void CmdLineParser::printHelp(bool premium) const " --include=\n" " Force inclusion of a file before the checked file.\n" " -i Skip translation units whose *source filename* matches\n" - " ''. '' can be a filename or directory.\n" + " . can be a filename or directory.\n" " Note: If you want to prevent warnings in some headers,\n" " use suppressions instead.\n" " --inconclusive Allow that Cppcheck reports even though the analysis is\n" From 79bdf0581d38ffdfada0ef7a1946c0a70a5dc5b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Marjam=C3=A4ki?= Date: Fri, 14 Nov 2025 09:08:54 +0100 Subject: [PATCH 5/7] rephrazing --- cli/cmdlineparser.cpp | 7 +++++-- man/manual.md | 8 ++++---- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/cli/cmdlineparser.cpp b/cli/cmdlineparser.cpp index 168e8f67721..86130ddc977 100644 --- a/cli/cmdlineparser.cpp +++ b/cli/cmdlineparser.cpp @@ -1837,8 +1837,11 @@ void CmdLineParser::printHelp(bool premium) const " this is not needed.\n" " --include=\n" " Force inclusion of a file before the checked file.\n" - " -i Skip translation units whose *source filename* matches\n" - " . can be a filename or directory.\n" + " -i Ignore files that match . can be a filename\n" + " or directory and can contain *,**,?. A file that is\n" + " ignored will not be checked directly (the whole\n" + " translation unit is skipped completely). Header files\n" + " are checked indirectly when they are #include'd.\n" " Note: If you want to prevent warnings in some headers,\n" " use suppressions instead.\n" " --inconclusive Allow that Cppcheck reports even though the analysis is\n" diff --git a/man/manual.md b/man/manual.md index 3b52dbbeda8..163374035a2 100644 --- a/man/manual.md +++ b/man/manual.md @@ -126,13 +126,13 @@ Typically a `compile_commands.json` contains absolute paths. However no matter i * a file with relative path `src/test2.c` can be checked. * a file with relative path `src/test3.cpp` is not checked. -### Ignore/skip files matching a given pattern +### Ignore files matching a given pattern -With `-i ` you can configure filename/directory patterns that should be ignored/skipped. +With `-i ` you can configure filename/directory patterns that should be ignored. -> *Note*: If you want to filter out warnings for a header file then `-i` will not work. The option `--suppress` should be used instead. Any header included in a source file which is not ignored would be processed regardless the `-i` option applied to that header. +A file that is ignored will not be checked directly (the complete translation unit is skipped). Any header #include'd from a source file which is not ignored is checked indirectly, regardless if the header is ignored. -Translation units are skipped if their *source filename* matches the exclusion pattern. This filtering happens *before* preprocessing, and the exclusion patterns are not applied during preprocessing or analysis. +> *Note*: If you want to filter out warnings for a header file then `-i` will not work. Use suppressions instead. You can use `**`, `*` and `?` in the pattern to specify excluded folders/files. `**`: matches zero or more characters, including path separators From 5b9e4ef11672242c9bcb5f85d38fd1d5459165c0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Marjam=C3=A4ki?= Date: Fri, 14 Nov 2025 10:34:58 +0100 Subject: [PATCH 6/7] update manual-premium.md --- man/manual-premium.md | 49 ++++++++++++++++++++++++------------------- 1 file changed, 28 insertions(+), 21 deletions(-) diff --git a/man/manual-premium.md b/man/manual-premium.md index 47cc3c61afb..6ae337a9fb0 100644 --- a/man/manual-premium.md +++ b/man/manual-premium.md @@ -104,15 +104,18 @@ need to use both approaches. Later chapters will describe this in more detail. With `--file-filter=` you can configure file filter(s) and then only those files matching the filter will be checked. -For example, this command below means that `src/test1.cpp` and `src/test/file1.cpp` could be checked, but `src/file2.cpp` will not be checked: - - cppcheck src/ --file-filter=src/test* - You can use `**`, `*` and `?` in the file filter pattern. `**`: matches zero or more characters, including path separators `*`: matches zero or more characters, excluding path separators `?`: matches any single character except path separators +For example, this command below means that `src/test1.cpp` could be checked, but `src/file2.cpp` and `src/test/file1.cpp` will not be checked: + + cppcheck src/ --file-filter=src/test* + +Cppcheck first collects all files in the specified directory, then applies the filter. Therefore, the filter pattern +must include the directory path you specified. + A common use case for `--file-filter` is to check a project, but only check certain files: cppcheck --project=compile_commands.json --file-filter=src/*.c @@ -122,13 +125,13 @@ Typically a `compile_commands.json` contains absolute paths. However no matter i * a file with relative path `src/test2.c` can be checked. * a file with relative path `src/test3.cpp` is not checked. -### Excluding a file or folder from checking +### Ignore files matching a given pattern -The option `-i` specifies a pattern to files/folders to exclude. With this command no files in `src/c` are checked: +With `-i ` you can configure filename/directory patterns that should be ignored. - cppcheck -isrc/c src +A file that is ignored will not be checked directly (the complete translation unit is skipped). Any header #include'd from a source file which is not ignored is checked indirectly, regardless if the header is ignored. -The `-i` option is not used during preprocessing, it can't be used to exclude headers that are included. +> *Note*: If you want to filter out warnings for a header file then `-i` will not work. Use suppressions instead. You can use `**`, `*` and `?` in the pattern to specify excluded folders/files. `**`: matches zero or more characters, including path separators @@ -149,8 +152,8 @@ By default Cppcheck uses an internal C/C++ parser. However there is an experimen Install `clang`. Then use Cppcheck option `--clang`. -Technically, Cppcheck will execute `clang` with its `-ast-dump` option. The Clang output is then imported and converted into -the normal Cppcheck format. And then normal Cppcheck analysis is performed on that. +Cppcheck executes clang with the -ast-dump option, imports the output, converts it to Cppcheck's internal format, and then +performs standard analysis. You can also pass a custom Clang executable to the option by using for example `--clang=clang-10`. You can also pass it with a path. On Windows it will append the `.exe` extension unless you use a path. @@ -190,9 +193,8 @@ be improved. Cppcheck instantiates the templates in your code. -If your templates are recursive this can lead to slow analysis that uses a lot -of memory. Cppcheck will write information messages when there are potential -problems. +If your templates are recursive, this can lead to slow analysis and high memory usage. Cppcheck will write information +messages when there are potential problems. Example code: @@ -249,7 +251,7 @@ Using a Cppcheck build folder is not mandatory but it is recommended. Cppcheck save analyzer information in that folder. -The advantages are; +The advantages are: - It speeds up the analysis as it makes incremental analysis possible. Only changed files are analyzed when you recheck. - Whole program analysis also when multiple threads are used. @@ -285,7 +287,7 @@ To ignore certain folders in the project you can use `-i`. This will skip the an ## CMake -Generate a compile database: +Generate a compile database (a JSON file containing compilation commands for each source file): cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON . @@ -368,9 +370,12 @@ Here is a file that has 3 bugs (when x,y,z are assigned). #error C must be defined #endif +The flag `-D` tells Cppcheck that a name is defined. Cppcheck will only analyze configurations that +contain this define. + +The flag `-U` tells Cppcheck that a name is not defined. Cppcheck will only analyze configurations +that does not contain this define. -The flag `-D` tells Cppcheck that a name is defined. There will be no Cppcheck analysis without this define. -The flag `-U` tells Cppcheck that a name is not defined. There will be no Cppcheck analysis with this define. The flag `--force` and `--max-configs` is used to control how many combinations are checked. When `-D` is used, Cppcheck will only check 1 configuration unless these are used. @@ -476,7 +481,8 @@ build dir. For instance, the unusedFunction warnings require whole program analy If you want to filter out certain errors from being generated, then it is possible to suppress these. -If you encounter a false positive, then please report it to the Cppcheck team so that it can be fixed. +If you encounter a false positive, please report it to the Cppcheck team so that the issue can be +fixed. ## Plain text suppressions @@ -1034,7 +1040,7 @@ Example configuration of naming conventions: ### y2038.py -[y2038.py](https://github.com/danmar/cppcheck/blob/main/addons/y2038.py) checks Linux systems for [year 2038 problem](https://en.wikipedia.org/wiki/Year_2038_problem) safety. This required [modified environment](https://github.com/3adev/y2038). See complete description [here](https://github.com/danmar/cppcheck/blob/main/addons/doc/y2038.txt). +[y2038.py](https://github.com/danmar/cppcheck/blob/main/addons/y2038.py) checks source code for [year 2038 problem](https://en.wikipedia.org/wiki/Year_2038_problem) safety. ## Running Addons @@ -1073,6 +1079,7 @@ Cppcheck already contains configurations for several libraries. They can be load ## Using a .cfg file To use a .cfg file shipped with cppcheck, pass the `--library=` option. The table below shows the currently existing libraries: + | .cfg file | Library | Comment | | ----------------- | ------------- | ------------- | | avr.cfg | | | @@ -1082,7 +1089,7 @@ To use a .cfg file shipped with cppcheck, pass the `--library=` option. The | cairo.cfg | [cairo](https://www.cairographics.org/) | | | cppcheck-lib.cfg | [Cppcheck](http://cppcheck.net/) | Used in selfcheck of | | | |the Cppcheck code base | -| cppunit.cfg | [CppUnit](https://sourceforge.net/projects/cppunit/) | +| cppunit.cfg | [CppUnit](https://sourceforge.net/projects/cppunit/) | | | dpdk.cfg | | | | embedded_sql.cfg | | | | emscripten.cfg | | | @@ -1115,7 +1122,7 @@ To use a .cfg file shipped with cppcheck, pass the `--library=` option. The | sdl.cfg | | | | sfml.cfg | | | | sqlite3.cfg | [SQLite](https://www.sqlite.org/) | | -| std.cfg | C/C++ standard library | Loaded by default +| std.cfg | C/C++ standard library | Loaded by default | | tinyxml2.cfg | [TinyXML-2](https://github.com/leethomason/tinyxml2) | | | vcl.cfg | | | | windows.cfg | [Win32 API](https://learn.microsoft.com/en-us/windows/win32/) | | From 2c18207553e05e2e6e2367e4362126c145df2589 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Marjam=C3=A4ki?= Date: Fri, 14 Nov 2025 13:10:10 +0100 Subject: [PATCH 7/7] formatting list --- man/manual.md | 1 + 1 file changed, 1 insertion(+) diff --git a/man/manual.md b/man/manual.md index 163374035a2..cc1182ab9ab 100644 --- a/man/manual.md +++ b/man/manual.md @@ -144,6 +144,7 @@ A use case for `-i` is to check a project, but exclude certain files/folders: cppcheck --project=compile_commands.json -itest Typically a `compile_commands.json` contains absolute paths. However no matter if `compile_commands.json` contains absolute paths or relative paths, the option `-itest` would mean that: + * a file with relative path `test1.cpp` can be checked. * a file with relative path `test/somefile.cpp` is not checked