<?xml version="1.0" encoding="utf-8"?> <!-- Software Index, Copyright 2010, Software Index Project Team Link: http://swi.sourceforge.net This file is part of Software Index Tool. Software Index is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 of the License. Software Index is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with Software Index. If not, see <http://www.gnu.org/licenses/>. --> <!-- Configuration file is formed in XML format. Use this file as a 'configuration file description' and create new configurations using this file as a baseline. Comments below provides with the description for all options. Commented XML sections make patterns for your specific extensions. Some of them demonstrates usage examples. --> <!-- Root node 'swi:configuration' is mandatory. It's name is hardcoded. --> <swi:configuration> <!-- Section 'swi:info' is used for descriptive purposes. --> <swi:info> <!-- Option 'swi:version' should be equal to 1. It is reserved for further extensions. --> <swi:version>1</swi:version> <!-- Option 'swi:project/swi:name' is used in the final report. All objects are references in the following format: YOUR_PROJECT_NAME/YOUR_MODULE_NAME/FILE/FUNCTION_NAME Changes in this sections automatically reflected in the report. --> <swi:project> <!-- Modify this option in order to refer to the actual name of your solution --> <swi:name>YOUR_PROJECT_NAME</swi:name> </swi:project> <!-- This section for tracing purposes. If you workflow assumes history records in project files, this is the place to keep your records The section is optional. --> <swi:history> <!-- Section 'swi:revision' can be repeated several times --> <swi:revision> <swi:name>ALFA</swi:name> <swi:user>USER</swi:user> <swi:comment>Sample configuration with the description created</swi:comment> </swi:revision> <!-- Add here the next 'swi:revision' section, for example: <swi:revision> <swi:name>BETA</swi:name> <swi:user>USER</swi:user> <swi:comment>Description of the next update</swi:comment> </swi:revision> --> </swi:history> </swi:info> <!-- The 'swi:general' section configures global settings for the tool. The section is optional. --> <swi:general> <!-- Filtering of the debug information The section is optional. --> <swi:debug> <!-- The 'swi:enabled' option activates/deativates the tracing: Possible values are 'on' and 'off' By default, the debug is not enabled. --> <swi:enabled>off</swi:enabled> </swi:debug> </swi:general> <!-- Section 'swi:modules' define where to get sources and how to process them. --> <swi:modules> <!-- Section 'swi:module' can be repeated several times --> <swi:module> <!-- Option 'swi:name' is used in the final report. All objects are references in the following format: YOUR_PROJECT_NAME/YOUR_MODULE_NAME/FILE/FUNCTION_NAME Changes in this sections automatically reflected in the report. Modify this option in order to refer to the actual name of your module --> <swi:name>YOUR_MODULE_NAME</swi:name> <!-- This is a full path to the directory where module's source files are stored It can be relative or full path (recommended). If it is relative path, you need to run Software Index tool from the relatively correct folder. Directory is processed recursively. I.e. files in sub-directories are scanned as well. In the report and in 'swi:files' section below, files are referenced relatively to directory configured in 'swi:location'. --> <swi:location>/path/to/my/module</swi:location> <!-- Section 'swi:files' which files to process and which to miss. The section is optional. --> <swi:files> <!-- This option is a regular expression. If file name (in module's location) is mathced by this expression, it is included to the list for processing. Otherwise, it is missed and not touched by Software Index tool. The example below matches files with the following extensions: .c, .h, .cpp, .hpp By default, all files are included. If it is a file in sub-directory, it's name --> <swi:include>^.*[.][chCH]([pP][pP])?$</swi:include> <!-- This option is a regular expression. If file name (in module's location) is mathced by this expression, it is excluded from the list for processing (even if it was previously mathced by the previous option). The example below matches files with the following extensions: .gz.c, .gz.h, .gz.cpp, .gz.hpp By default, no files are excluded. --> <swi:exclude>^.*[.][gG][zZ][.][chCH]([pP][pP])?$</swi:exclude> </swi:files> <!-- The Software Index does not parse 'preprocessor' statements, like a C/C++ compiler. It just removes lines with preprocessor defines, includes, conditions and so on. As a result a code may include unfolded preprocessor strings which are normally replaced/removed by a compiler. For example, the initial code line 1: #define MAXIMUM_NUMBER (100) line 2: #ifdef DEBUG line 3: if (currentNumber < MAXIMUM_NUMBER) { line 4: printf("New overflow detected: %d\n", currentNumber); line 5: count++; line 6: } line 7: #else line 8: if (currentNumber < MAXIMUM_NUMBER) { line 9: count++; line 10: } line 11: #endif is converted to: line 1: line 2: line 3: if (currentNumber < MAXIMUM_NUMBER) { line 4: printf("New overflow detected: %d\n", currentNumber); line 5: count++; line 6: } line 7: line 8: if (currentNumber < MAXIMUM_NUMBER) { line 9: count++; line 10: } line 11: In the last example, the final code is parsable. If all your preprocessor statements are in the similar style and does not corrupt the structure of block start/end delimeters as in the example above, you do not need to bother about preprocessor stuff. However, if the initial code includes lines like these: line 1: #define MAXIMUM_NUMBER (100) line 2: if (currentNumber < MAXIMUM_NUMBER) { line 3: #ifdef DEBUG line 4: printf("New overflow detected: %d\n", currentNumber); line 5: count++; line 6: } line 7: #else line 8: count++; line 9: } line 10: #endif it is not parsable, because brackets mismatch is detected after preprocessing (see lines 6 and 9 below): line 1: line 2: if (currentNumber < MAXIMUM_NUMBER) { line 3: line 4: printf("New overflow detected: %d\n", currentNumber); line 5: count++; line 6: } line 7: line 8: count++; line 9: } line 10: Thus, in order to use Software Index tool it is necessary to refactor places, like in the example above. The section 'swi:preprocessor' is useful in other cases. For example, if the initial code includes the following lines: line 1: #define DECLARE_HANDLER(handlerName) \ line 2: int handlerName(unsigned int stateId, \ line 3: unsigned int eventId, \ line 4: struct EVENT_DATA_TYPE eventData) line 5: line 6: DECLARE_HANDLER(leftButtonClick); line 7: DECLARE_HANDLER(rightButtonClick); line 8: line 9: DECLARE_HANDLER(leftButtonClick) line 10: { line 11: /* This function is called when left mouse button is clicked */ line 12: ... line 13: } line 14: line 15: DECLARE_HANDLER(rightButtonClick) line 16: { line 17: /* This function is called when right mouse button is clicked */ line 18: ... line 19: } line 20: Software Index tool detects function DECLARE_HANDLER twice. As a result, they will be named: 'DECLARE_HANDLER' and 'DECLARE_HANDLER (2)' accordingly. The better solution is to preprocess these strings using the preprocessor feature. For this particular example, it is recommended to define the rule which replaces the string: lines 6,7,9,15: DECLARE_HANDLER(_xxx_) by lines 6,7,9,15: int _xxx_(unsigned int stateId, unsigned int eventId, struct EVENT_DATA_TYPE eventData) where _xxx_ is the actual function name. In other words, the 'swi:preprocessor' section should include the following XML tags: <swi:rule> <swi:filepattern>your_regexp_file_pattern</swi:filepattern> <swi:searchpattern>([^_a-zA-Z0-9])DECLARE_HANDLER\(([^_a-zA-Z0-9])\)</swi:searchpattern> <swi:replacepattern>${1}int ${2}(unsigned int stateId, unsigned int eventId, struct EVENT_DATA_TYPE eventData)</swi:replacepattern> </swi:rule> As a result, the functions will be detected with the correct names: 'leftButtonClick' and 'rightButtonClick' accordingly. 'swi:preprocessor' section is optional. --> <swi:preprocessor> <!-- Section 'swi:rule' is optional or can be repeated several times --> <swi:rule> <!-- This option is a regular expression. If name of file which is under processing is mathced by this expression, it is preprocessed according to the rule definitions. Otherwise, it is missed and not touched by the internal preprocessor tool. The example below matches files with the following extensions: .h, .hpp --> <swi:filepattern>^.*[.][hH]([pP][pP])?$</swi:filepattern> <!-- Options 'swi:searchpattern' and 'swi:replacepattern' are regular expressions. Preprocessor searches the code by the 'swi:searchpattern' pattern. If it is found it is replaced by 'swi:replacepattern' string, which is interpolated before: variables ${1}, ${2}, ... are replaced by actual strings from 'swi:searchpattern' regexp hooks. --> <swi:searchpattern>([^_a-zA-Z0-9])DECLARE_HANDLER\(([_a-zA-Z0-9]+)\)</swi:searchpattern> <swi:replacepattern>${1}int ${2}(unsigned int stateId, unsigned int eventId, struct EVENT_DATA_TYPE eventData)</swi:replacepattern> </swi:rule> <!-- Add here the next 'swi:rule' section, for example: <swi:rule> <swi:filepattern>.*</swi:filepattern> <swi:searchpattern>(\s+)(union\s*)({)</swi:searchpattern> <swi:replacepattern>$1$2 _noname_ $3</swi:replacepattern> </swi:rule> --> </swi:preprocessor> <!-- Scaner tool is used for global searching and violation reporting. If the scaner finds something, it reports the message which is also configured and increases the exit code from the Software Index Tool. For example, if you codding style requires to open the block begging from the new line: line 1: line 2: if (currentNumber < MAXIMUM_NUMBER) line 3: { line 4: count++; line 5: } line 6: it is possible to check it by scaner defining the 'swi:searchpattern' in the following way: [\n][^{][{] This regular expression matches the code which is 'badly' formated: line 1: line 2: if (currentNumber < MAXIMUM_NUMBER) { line 3: count++; line 4: } line 5: More examples. If you codding style does not allow to have noname structures, enums or unions: line 1: line 2: typedef struct _NAME_HERE_IS_MANDATORY_ line 3: { line 4: int a; line 5: } my_type; line 6: it is possible to check it by scaner defining the 'swi:searchpattern' in the following way: (\s+)((union)|(enum)|(struct))(\s*{) This regular expression matches the code which is 'wrongly' written: line 1: line 2: typedef struct // noname here line 3: { line 4: int a; line 5: } my_type; line 6: And if the 'swi:messagepattern' equals to: Noname '$2' detected. the error report looks like this: file.c:2: warning: Noname 'struct' detected. 'swi:scaner' section is optional. --> <swi:scanner> <!-- Section 'swi:rule' can be missed or repeated several times --> <swi:rule> <!-- This option is a regular expression. If name of file which is under processing is mathced by this expression, it is scaned according to the rule definitions. Otherwise, it is missed and not touched by the internal scaner tool. The example below matches all files. --> <swi:filepattern>.*</swi:filepattern> <!-- Options 'swi:searchpattern' and 'swi:messagepattern' are regular expressions. Scaner searches the code by the 'swi:searchpattern' pattern. If it is found the 'swi:messagepattern' string is printed to STDERR, 'swi:messagepattern' string is interpolated: variables ${1}, ${2}, ... are replaced by actual strings from 'swi:searchpattern' regexp hooks. --> <swi:searchpattern>(\s+)((union)|(enum)|(struct))(\s*{)</swi:searchpattern> <swi:messagepattern>Noname '$2' detected.</swi:messagepattern> <!-- The 'swi:codecontent' option defines the content for scanner, it can be: initial - the initial source content code - the initial code (without comments) comments - comments only (no code) nopreprocessor - preprocessor strings excluded (without comments and preprocessor) nostrings - strings excluded (without comments and strings) purified - strings and preprocessor excluded (without comments, strings and preprocessor) commentheader - comments before function's header functionname - name of a function functionhead - purified function's header, no body functionbody - purified function's body, no header By default, the 'purified' code is scanned --> <swi:codecontent>purified</swi:codecontent> </swi:rule> <!-- Add here the next 'swi:rule' section, for example: <swi:rule> <swi:filepattern>.*</swi:filepattern> <swi:searchpattern>#define\s*([_a-zA-Z0-9]+)\s*[\(]?([0-9]+)[\)]?</swi:searchpattern> <swi:messagepattern>Define '${1}' of the number '${2}' should be replaced by 'static const int ${1} = ${2};'</swi:messagepattern> <swi:codecontent>nostrings</swi:codecontent> </swi:rule> --> <!-- If some finding is acceptable and should not be considered as a violation it is possible to define the exception and suppress the notification in the 'swi:suppress' section below. --> <swi:suppress> <!-- The exception should be defined in combination with 'swi:message' option. If a scanner's message is matched by the regular expression 'swi:message' and the object is matched by the regular expression in 'swi:pattern' tag, the finding is ignored and not printed to the log and stderr streams. For example, the following pattern blocks the notification: 'Noname 'enum' detected.' for the object: YOUR_PROJECT_NAME/YOUR_MODULE_NAME/your_file.c/yourFunction --> <swi:pattern swi:message="Noname 'enum' detected.">^YOUR_PROJECT_NAME/YOUR_MODULE_NAME/your_file.c/yourFunction$</swi:pattern> <!-- Add here the next 'swi:pattern' section, for example: <swi:pattern swi:message="Noname 'struct' detected.">^.*/.*/file2.c/function2$</swi:pattern> --> </swi:suppress> </swi:scanner> <!-- Indexer measures common software statistics per functions, files, modules and project. They are: STATICTIC-GROUP / STATISTIC-NAME - DESCRIPTION =============== / ================== - ============================ swi:length / swi:source - total number of symbols swi:length / swi:blank - number of space symbols swi:length / swi:executable - number of executable symbols swi:length / swi:comment - number of symbols inside comments swi:length / swi:function:name - number of symbols in name of a function swi:lines / swi:comment:header - number of lines in a comment before a function/file swi:lines / swi:source - total number of lines swi:lines / swi:blank - number of empty lines swi:lines / swi:executable - number of executable lines swi:lines / swi:comment - number of lines with comments swi:complexity / swi:blocks - number of blocks swi:complexity / swi:cyclomatic - McCabe's (Myer's) Cyclomatic complexity metric swi:complexity / swi:maxdepth - Maximum indent level swi:count / swi:functions - Number of functions swi:count / swi:files - Number of files swi:count / swi:modules - Number of modules swi:checksum / swi:source - Checksum for the source code (compare purposes) Every statistic is reported incombination with the following types: STATICTIC-TYPE - DESCRIPTION =============== - ============================ swi:exact - exact value swi:average - average value within a distribution swi:min - minimum value within a distribution swi:max - maximum value within a distribution swi:total - sum of values within a distribution Cumulative types (swi:average, swi:min, swi:max and swi:total) are reported if they are applicable. 'swi:indexer:common' section is optional. --> <swi:indexer:common> <!-- No settings currently available --> </swi:indexer:common> <!-- Duplication indexer searches for identical code fragments, calculates total number of symbols in continues duplicated fragments per function, file, module and project. Note: blank symbols (spaces, tabulations, newlines) are ignored when strings are compared. The duplciation statistic is reported by reference 'swi:duplication/swi:symbols': STATICTIC-GROUP / STATISTIC-NAME - DESCRIPTION =============== / ================== - ============================ swi:duplication / swi:symbols - Number of duplicated symbols The statistic is reported incombination with the following types: STATICTIC-TYPE - DESCRIPTION =============== - ============================ swi:exact - exact value swi:average - average value within a distribution swi:min - minimum value within a distribution swi:max - maximum value within a distribution swi:total - sum of values within a distribution Cumulative types (swi:average, swi:min, swi:max and swi:total) are reported if they are applicable. This internal tool also collects pointers to duplicated fragments and prints them. Also, they can be easily extracted from the final report for other needs. 'swi:indexer:dup' section is optional. --> <swi:indexer:dup> <!-- The 'swi:codecontent' option defines the content for the duplicatiion searcher, it can be: initial - the initial source content code - the initial code (without comments) comments - comments only (no code) nopreprocessor - preprocessor strings excluded (without comments and preprocessor) nostrings - strings excluded (without comments and strings) purified - strings and preprocessor excluded (without comments, strings and preprocessor) commentheader - comments before function's header functionname - name of a function functionhead - purified function's header, no body functionbody - purified function's body, no header By default, the 'purified' content is used. Recomendation: if Software Index tool detects a log of duplicated fragments which are within function's header (declarations), usually it is the case when where are overloaded functions with a huge list of arguments, it is recommended to set 'swi:codecontent' option to 'functionbody' value. --> <swi:codecontent>purified</swi:codecontent> <!-- The 'swi:enabled' option activates/deativates the calculation of the duplication index: on - the search tool is launched and the statistic is calculated off - the search tool is not started, the statistic is reported by zeros By default, the this feature is enabled --> <swi:enabled>on</swi:enabled> <!-- The 'swi:minlength' option defines the minimal length of the duplicated fragment. In other words, if the duplicated fragment is found it is at least 'swi:minlength' in length Too small value, for example 10, results in excessive growth of the total duplication index Too large value may cause the empty search result. By default, it is equal to 100. --> <swi:minlength>100</swi:minlength> <!-- The 'swi:proximity' option allows to report two code fragments as duplicated even if they are not matched exactly till the end. It helps to search 'almost' duplicated code fragments instead of 'exactly' duplicated. This option is a value from 1 till 100. For example, if there is found group of duplicated code fragments which are 100 symbols in length and 'swi:proximity' is equal to 80, this group will be extended by other found code fragments which have 80 or more the same symbols. By default, it is equal to 100. --> <swi:proximity>100</swi:proximity> <!-- All code fragments are related to some function. Except global defines, declarations, class definitions and so on. Software Index attaches global code to the 'dummy' function with name '>>>GLOBAL<<<'. The 'swi:globalcode' configures whether the global code should be included to the scope of search for duplication. on - global code is scaned for duplication off - global code is missed By default, the this option is 'off'. --> <swi:globalcode>on</swi:globalcode> </swi:indexer:dup> <!-- gcc/g++ compilers in combination with gcov tool are able to report statement and branch coverage information and statistics. Software Index has a bridge to this information which is configured in the 'swi:indexer:gcov' section below. Note: the feature works only if 'gcov' is visible in PATH environment. The short summary about possible coverage metrics: * Function coverage Has each function in the program been executed? * Statement coverage Has each line of the source code been executed? If at least one statement is executed, 'Function coverage' metric is equal to 100% (i.e. a function is executed at least once) * Decision coverage Has each control structure (such as an if statement) evaluated both to true and false? * Condition coverage Has each boolean sub-expression evaluated both to true and false? More 'strict' metric than 'Decision coverage'. * Modified Condition/Decision Coverage (MC/DC) Has every condition in a decision taken on all possible outcomes at least once? Has each condition been shown to affect that decision outcome independently? * Path coverage Has every possible route through a given part of the code been executed? * Entry/exit coverage Has every possible call and return of the function been executed? The coverage statistic is reported by the following indexes: STATICTIC-GROUP / STATISTIC-NAME - DESCRIPTION (*) =============== / ================== - ============================ swi:coverage / swi:gsum:lines - Total number of executable lines/statements (from point of compiler view) swi:coverage / swi:gsum:branches - Total number of branches swi:coverage / swi:gsum:calls - Total number of calls swi:coverage / swi:gcov:lines - Number of executed lines (the same as 'Statement coverage' metric in the list above) swi:coverage / swi:gcov:branches - Number of exected branches (no analogue in the list of coverage metrics above; incremented by 2 for a boolean condition (2 branches) if a condition is evaluated at least once and resulted either in true OR in false) swi:coverage / swi:gcov:takenonce - Number of branches executed at least once (the same as 'Condition coverage' metric in the list above; a boolean condition (2 branches) is totaly covered if a boolean sub-expression evaluated both to true and false at least once) swi:coverage / swi:gcov:calls - Number of exectuted calls (the same as 'Entry/exit coverage' metric in the list above) (*) For more details about reported numbers see the documentation for 'gcov' tool. The statistic is reported incombination with the following types: STATICTIC-TYPE - DESCRIPTION =============== - ============================ swi:exact - exact value swi:average - average value within a distribution swi:min - minimum value within a distribution swi:max - maximum value within a distribution swi:total - sum of values within a distribution Cumulative types (swi:average, swi:min, swi:max and swi:total) are reported if they are applicable. 'swi:indexer:gcov' section is optional. If it is missed coverage statistic is not collected. --> <swi:indexer:gcov> <!-- The 'swi:enabled' option activates/deativates the collection of coverage statistic: on - active off - inactive, coverage statistic is not collected and not reported By default, the this is not enabled --> <swi:enabled>on</swi:enabled> <!-- This option is a regular expression. If name of file which is under processing is mathced by this expression, coverage statistic is retrieved for this file. Otherwise, coverage statistic is not reported. By default, all files are affected. --> <swi:filepattern>^.*[.][cC][pP]?[pP]?$</swi:filepattern> <!-- The coverage statistic is avaialble in 'gcda' files. gcov tool reads these files and reports the information. Every source file, if it is touched by gcov, has corresponding gcda file. For example, if the initial source file is 'file.c' and the compiled binary file is 'file.o', the corresponding 'gcda' file with coverage data is 'file.gcda' Two options below define how to map the initial source file to the file with coverage data. 'swi:sourcefile' is a regular expression. It is applied to name of a file. This operation gives variables ${1}, ${2}, ... according to regexp hooks. 'swi:gcdafile' constructs the corresponding 'gcda' file. The example below demostrates the case of mapping: from 'file.c' to 'file.gcda' from 'otehrfile.c' to 'otherfile.gcda' and so on... If the 'gcda' file is not found, coverage statistic is not collected and not reported. The example below demonstrates the default mapping scheme if options are missed. --> <swi:sourcefile>(.*)[.][cC][pP]?[pP]?</swi:sourcefile> <swi:gcdafile>${1}.gcda</swi:gcdafile> </swi:indexer:gcov> </swi:module> <!-- Add here the next 'swi:module' section. --> </swi:modules> <!-- The 'swi:report' section defines the location for reports and output settings. --> <swi:report> <!-- This is a full path to the directory where report files should be stored It can be relative or full path (recommended). If it is relative path, you need to run Software Index tool from the relatively correct folder. --> <swi:destination>/path/to/the/destination/folder</swi:destination> <!-- The main report is generated to XML format. Other files are created from the XML file by converters. --> <swi:xml> <!-- Name of final XML file in 'swi:destination' directory. --> <swi:name>swi_report_sample.xml</swi:name> <!-- Software Index process software modules independantly from their versions. However, if it is executed with a reference to a report generated by Software Index tool for the baseline versions of your modules (baseline version - previous version of the product, the state of product before the time when changes and updates and/or additions applied) it has additional information and can report the modification status for every statistic (increased/decreased) and for every function, file and module (added, removed, modified, cloned or unmodified). Description of modification statuses: added - there was no object in the baseline version and it was added to the current version removed - there was object in the baseline version and it was removed from the current version modified - there was object in the baseline version and it was changed/updated cloned - there was object in the baseline version, it was not changed/updated in the new version, but duplication index (swi:duplication/swi:executable) was decreased or increased unmodified - the object was now touched In addition to the extra info, it helps to filter the output information. For example, it is possible to print limit overheads for added and modified functions only (missing analogues messages for untouched objects). As a result, Software Index tool can be deployed to the software development process without extra work and remakes in your old sources. You can always start to measure/control the characteristics of objectes (functions) which are affected by your recent updates only, improving the total quality step-by-step (version-by-version). See 'Example 1' in the next section for examples. The 'swi:baseline' option points out to the report for the baseline version. It should be stored in 'swi:destination' directory. If it is not defined, it is considered that all objects (functions, files and so on) were added. --> <swi:baseline>swi_report_sample.xml</swi:baseline> </swi:xml> <!-- Notifications are prinited to file and to stderr stream. They highlight exceeded limitations of indexes/statistics and other notices, warnings and errors. --> <swi:notifications> <!-- Name of log file in 'swi:destination' directory. --> <swi:name>swi_report_sample.log</swi:name> <!-- Flags in XML sub-tags in 'swi:error' section activate/deactivate counter of errors/notifications. If the object with the corresponding modification status has some notification (exceeded limit, for example), the error counter is increased. The final value of the error counter is returned to the operation system as exit code. Thus, if there are no notifications/errors, exit code is zero. Options should be equal to some value from the list below: on - counter is increased (selected by default for all) off - counter is not increased Example 1: 'easy deployment of the tool' added - 'on' removed - 'on' or 'off' modified - 'on' cloned - 'on' or 'off' unmodified - 'off' Example 2: 'global control' added - 'on' removed - 'on' modified - 'on' cloned - 'on' unmodified - 'on' Example 3: 'always success (zero exit code)' added - 'off' removed - 'off' modified - 'off' cloned - 'off' unmodified - 'off' 'swi:error' section is optional. --> <swi:error> <swi:added>on</swi:added> <swi:removed>on</swi:removed> <swi:modified>on</swi:modified> <swi:cloned>on</swi:cloned> <swi:unmodified>on</swi:unmodified> </swi:error> <!-- The 'swi:print' section defines which messages should be printed to the log and to stderr stream. By analogy with the previous configuration section, the flags are defined per modification status. There are 4 types of messages which are configred by 'swi:failures', 'swi:modifications', 'swi:duplications' and 'swi:scanmessages' options. (*) 'swi:failures' - notifications about broken limits (see 'swi:limits' section below) By default, these messages are activated 'swi:modifications' - notes about added/modified/cloned/removed objects (see 'swi:xml/swi:baseline' option above By default, these messages are activated (**) 'swi:duplications' - pointers to the duplicated regions in files (see 'swi:indexer:dup' sections above) (!) By default, these messages are NOT activated (*) 'swi:scanmessages' - messages collected by the internal scaner tool (see 'swi:scaner' sections above) By default, these messages are activated (*) marks types of messages which affect the exit code (see 'swi:error' section above). (**) these messages are always printed for an object if there failures for the index: 'swi:duplication/swi:symbols/swi:exact' 'swi:print' section can be missed or empty. In this case default values are applied. --> <swi:print> <swi:added> <swi:failures>on</swi:failures> <swi:modifications>off</swi:modifications> <swi:duplications>off</swi:duplications> <swi:scanmessages>on</swi:scanmessages> </swi:added> <swi:removed> <swi:failures>on</swi:failures> <swi:modifications>off</swi:modifications> <swi:duplications>off</swi:duplications> <swi:scanmessages>on</swi:scanmessages> </swi:removed> <swi:modified> <swi:failures>on</swi:failures> <swi:modifications>off</swi:modifications> <swi:duplications>off</swi:duplications> <swi:scanmessages>on</swi:scanmessages> </swi:modified> <swi:cloned> <swi:failures>on</swi:failures> <swi:modifications>off</swi:modifications> <swi:duplications>off</swi:duplications> <swi:scanmessages>on</swi:scanmessages> </swi:cloned> <swi:unmodified> <swi:failures>on</swi:failures> <swi:modifications>off</swi:modifications> <swi:duplications>off</swi:duplications> <swi:scanmessages>on</swi:scanmessages> </swi:unmodified> </swi:print> </swi:notifications> </swi:report> <!-- Software Index tool is able to validate that the particular statistic is in the acceptable range. Limits should be defined per: STATISTIC-GROUP / STATISTIC-NAME / STATISTIC-TYPE (See sections 'swi:indexer:common' and 'swi:indexer:dup' above) 'swi:limits' section is optional. --> <swi:limits> <!-- For example, if it is required to have proper (not too short) comment header, it is necessary to limit the statistic: 'swi:lines/swi:comment:header/swi:exact' It is demonstarted in the following section: --> <!-- STATISTIC-GROUP --> <swi:lines> <!-- STATISTIC-NAME --> <swi:comment:header> <!-- STATISTIC-TYPE --> <swi:exact> <!-- After that, actual limits should be defined for three levels: info, notice, warning The common rule is that options should be in order: 'swi:info' < 'swi:notice' < 'swi:warning' OR: 'swi:info' > 'swi:notice' > 'swi:warning' Note: limits can be negative, in this case they do not have any sense. In the example below, no messages are printed for a function if comment header before includes 5 lines at least. If it is so, the 'regular' level is attached to this function. If comment has 3-4 lines, level 'info' is assigned. If comment has 1-2 lines, level 'notice' is assigned. If there are no comments at all (0 lines), level 'warning' is assigned. --> <swi:info>5</swi:info> <swi:notice>3</swi:notice> <swi:warning>1</swi:warning> <!-- The next option is a regular expression. If name of object which is under processing is mathced by this expression, the limit is applied to this object. Otherwise, the object is missed and the level becomes 'undefined' for the object. For example, value '^MY_PROJECT/MY_MODULE$' requires to apply the limit to the module only, missing statistics for the project, files and functions. By default, statistics are validated for all objects. --> <swi:objectpattern>.*</swi:objectpattern> <!-- If some object is evaluated in non-regular level (info/notice/warning) and you consider that it is too excessive to fix it (or just there are no needs/benefits to do it), it is possible to define the exception and suppress the notification in the 'swi:suppress' section below. The exception should be defined in combination with 'swi:level' option. If there is notification for the object: MY_PROJECT/MY_MODULE/my_file.c/myFunction with 'notice' level, the 'swi:level' should be equal to 'notice'. Otherwise, the notification will be still printed. In other words, severity of the message and suppress level should be equal. Also, one rule can suppress several objects. An object is considered as suppressed if it is matched by regular expression in 'swi:pattern' option. For example, the regexp pattern MY_PROJECT/MY_MODULE/my_file.c/.* suppresses all functions in my_file.c in scope of MY_MODULE module in MY_PROJECT project. However, it it NOT recommended to use multiple suppressing, due to possible missmatch in severity of messages: For example, if there are two functions: MY_PROJECT/MY_MODULE/my_file.c/myFunction1 MY_PROJECT/MY_MODULE/my_file.c/myFunction2 and one of them is reported by the message with 'notice' level but the second is evaluated in 'regular' level, the 'swi:pattern' rule: MY_PROJECT/MY_MODULE/my_file.c/.* will always result in the unsuppressable message, either for the first or for the second function. It is better to suppress all objects by their full reference. For example (see the previous example for prehistory) <swi:pattern swi:level="notice">^MY_PROJECT/MY_MODULE/my_file.c/myFunction1$</swi:pattern> Symbols '^' and '$' are special regexp modifiers. They require immidiate borders in the name. --> <swi:suppress> <!-- Section 'swi:pattern' can be repeated several times --> <swi:pattern swi:level="notice">^MY_PROJECT/MY_MODULE/my_file.c/myFunction1$</swi:pattern> <!-- Add here the next 'swi:pattern' section, for example: <swi:pattern swi:level="warning">^.*/.*/file2.c/operator new[]$</swi:pattern> --> </swi:suppress> </swi:exact> </swi:comment:header> <!-- STATISTIC-NAME --> <swi:comment> <!-- This is the next example of a limit for statistic. It demonstrates how to limit the relative values. For example, it is required to have at least 30% of comments per every function. This is defined by the relation: 'swi:lines/swi:comment/swi:exact' / 'swi:lines/swi:executable/swi:exact' * 100%. In this case it is necessary to limit 'swi:lines/swi:comment/swi:exact' (what we do here) in the relation with 'swi:lines/swi:executable/swi:exact'. Note: if statistic in the relation ('swi:lines/swi:executable/swi:exact' in this example) is not defined OR equal to zero, result depends on the sign of the limited statistic ('swi:lines/swi:comment/swi:exact' in this example): if statistic > 0 than relative statistic becomes 'Infinity' if statistic < 0 than relative statistic becomes '-Infinity' if statistic = 0 than relative statistic becomes equals to '1.00' --> <swi:exact swi:relation="swi:lines/swi:executable/swi:exact"> <!-- 0.3 is 30% --> <swi:info>0.3</swi:info> <!-- 0.25 is 25% --> <swi:notice>0.25</swi:notice> <!-- 0.2 is 20% --> <swi:warning>0.2</swi:warning> <!-- Add here suppress section, if it is needed. For example: <swi:suppress> <swi:pattern swi:level="notice">^MY_PROJECT/MY_MODULE/my_file.c/myFunction1$</swi:pattern> <swi:pattern swi:level="info">^MY_PROJECT/MY_MODULE/my_file.c/myFunction2$</swi:pattern> </swi:suppress> --> </swi:exact> </swi:comment> <!-- STATISTIC-NAME --> <swi:executable> <!-- The previous examples require to limit the low bound of exact value. This sample demonstrates the limitation for total upper value. For example, sometimes it is useful to require to have short files, because they are easily maintainable in most cases. The settings in this sections allows to do it: no messages are printed for a file if total number of executable lines less than or equal to 1000. --> <swi:total> <swi:info>1000</swi:info> <swi:notice>1500</swi:notice> <swi:warning>2000</swi:warning> <!-- Most likely that you will need to suppress messages for modules, because total value of lines in a module is a sum of lines in all files. --> <swi:suppress> <!-- Section 'swi:pattern' can be repeated several times --> <swi:pattern swi:level="warning">^MY_PROJECT/MY_MODULE$</swi:pattern> <!-- Add here the next 'swi:pattern' section, for example: <swi:pattern swi:level="warning">^MY_PROJECT/MY_MODULE$</swi:pattern> --> </swi:suppress> </swi:total> </swi:executable> <!-- STATISTIC-NAME --> <swi:source> <!-- This example is an extension for the previous. Here the limitation is applied for total values of files, modules and project at the same time. The settings in this sections allows to do it: a) no messages (info) are printed for a file if total number of source lines less than or equal to 1000. b) no messages (notices) are printed for a module if total number of source lines less than or equal to 10000. c) no messages (notices) are printed for a project if total number of source lines less than or equal to 100000. --> <swi:total> <!-- Limit for files --> <swi:info>1000</swi:info> <!-- Limit for modules --> <swi:notice>10000</swi:notice> <!-- Limit for the project --> <swi:warning>100000</swi:warning> <!-- Most likely that you will need to suppress info messages for modules and notice messages for the project, because total value of lines in a module is a sum of lines in all files, and total value of lines in project is a sum of lines in all modules. --> <swi:suppress> <!-- Section 'swi:pattern' can be repeated several times --> <swi:pattern swi:level="info">^MY_PROJECT/MY_MODULE$</swi:pattern> <swi:pattern swi:level="notice">^MY_PROJECT$</swi:pattern> <!-- Add here the next 'swi:pattern' section, for example: <swi:pattern swi:level="info">^MY_PROJECT/MY_MODULE$</swi:pattern> --> </swi:suppress> </swi:total> </swi:source> </swi:lines> <!-- STATISTIC-GROUP --> <swi:complexity> <!-- STATISTIC-NAME --> <swi:cyclomatic> <!-- STATISTIC-TYPE --> <swi:exact> <!-- In the example below, no messages are printed for a function if cyclomatic complexity index less than or equal to 7. It indicates about proper (low) level of logical branching in a subroutine. Low level of this index more or less grants decreased costs for mainteinability and further development, minimal probability of bad fixes, better and easier understanding of a logical part of SW. --> <swi:info>7</swi:info> <swi:notice>10</swi:notice> <swi:warning>15</swi:warning> <!-- Add here suppress section, if it is needed. For example: <swi:suppress> <swi:pattern swi:level="notice">^MY_PROJECT/MY_MODULE/my_file.c/myFunction1$</swi:pattern> <swi:pattern swi:level="info">^MY_PROJECT/MY_MODULE/my_file.c/myFunction2$</swi:pattern> </swi:suppress> --> </swi:exact> </swi:cyclomatic> </swi:complexity> <!-- The following section defines the limitation for duplication index. In the example, it is required to control exact relative duplication index for functions and total relative duplication index for the whole project. --> <!-- STATISTIC-GROUP --> <swi:duplication> <!-- STATISTIC-NAME --> <swi:symbols> <!-- STATISTIC-TYPE --> <swi:exact swi:relation="swi:length/swi:executable/swi:exact"> <swi:info>0.30</swi:info> <swi:notice>0.40</swi:notice> <swi:warning>0.60</swi:warning> <!-- Add here suppress section, if it is needed. For example: <swi:suppress> <swi:pattern swi:level="notice">^MY_PROJECT/MY_MODULE/my_file.c/myFunction1$</swi:pattern> <swi:pattern swi:level="info">^MY_PROJECT/MY_MODULE/my_file.c/myFunction2$</swi:pattern> </swi:suppress> --> </swi:exact> <!-- STATISTIC-TYPE --> <swi:total swi:relation="swi:length/swi:executable/swi:total"> <swi:info>0.30</swi:info> <swi:notice>0.40</swi:notice> <swi:warning>0.60</swi:warning> <!-- This option explicitly defines the content for validation. It requires to apply the limit to the project and miss modules, files and functions. --> <swi:objectpattern>^MY_PROJECT$</swi:objectpattern> <!-- Add here suppress section, if it is needed. For example: <swi:suppress> <swi:pattern swi:level="warning">^MY_PROJECT/MY_MODULE/my_file.c$</swi:pattern> <swi:pattern swi:level="notice">^MY_PROJECT/MY_MODULE$</swi:pattern> <swi:pattern swi:level="info">^MY_PROJECT$</swi:pattern> </swi:suppress> --> </swi:total> </swi:symbols> </swi:duplication> <!-- Add here more sections with definition of limits if it is needed. --> </swi:limits> </swi:configuration>