Instrumenting only the relevant things saves time and resources. Here is a little intro which should help you to select the files you want to instrument.
Backlisting and Whitelisting
Before diving into the topic, there is one important question to ask yourself: Are there more files that you want to include than exclude or the other way around? When you have more files to exclude you should tend to whitelisting; if it is the other way around you should tend to blacklisting. Blacklisting is a method to specify which files you don’t want to be instrumented. This is especially useful when you have just a few files that should not be instrumented. Whitelisting is a method to specify only those files you want to be instrumented. This is a good option if you have many files that you want to instrument.
If all the files you want to include or exclude are in the same path, you can include or exclude specific absolute paths. A common example might be your project directory which contains only the source and the corresponding header files. In this configuration, you may want to exclude the library headers located outside of the folder, so you just include the path to your project.
The following is a whitelisting example which includes your source folder:
Similarly, for blacklisting, the following excludes your library folder:
If the files you want to include or exclude have the same extension, wildcards may be an easy and quick way to specify the files you want to include or exclude. This method uses an “*” character to denote an infinite amount of characters.
The following is a whitelisting example which includes only the “.cpp” files:
Similarly, for blacklisting, the following excludes the “.h”. Files
Regular Expressions (RegEx)
If the files you want to include or exclude have similar names, you may want to use Regular Expressions. This is the hardest method for beginners because it takes some time to get used to the syntax. There are a few tutorials where you can learn how to use RegEx.
The following example includes every file which is in a directory named „src“.
The following example excludes all the files which starts with the „test“ pattern, like test_lib.cpp or test.h
For further information about Regular Expressions, visit our documentation.
Note: If you use the RegEx and Wildcard arguments without „-abs“, they only handle relative paths. This is not recommended, however. Read more about this in our Coco Documentation.