SERVER.txt Reference Guide

The principal TICS configuration is stored in the 'SERVER.txt' file. This file must be located in the directory pointed to by the 'TICS' environment variable. By default, on Windows, this is Program Files\TIOBE\TICS\FileServer\cfg.

Syntax of SERVER.txt

The SERVER.txt file contains a hierarchical map of properties. At the top level, the contents of the SERVER.txt file must be delimited by a pair of braces. The body of the SERVER.txt consists of key-value pairs. Keys are ''-enclosed strings. Values can be numerical, string, list or map. Keys and values are separated by =>. Key-value pairs are terminated by a comma (,).

Examples of property definitions

Numerical:
'NROFBACKUPS' => 20
String:
'OWNER' => 'TIOBE'
List:
'EXTENSIONS' => [ 'pl', 'pm' ]
Map:
'SCMTOOL' => { 'NAME' => 'Custom' }

Properties may be mandatory or optional. A complete list of properties is presented below. For each property is indicated whether it is mandatory or optional.

More formally, the format of the SERVER.txt is defined as follows.

SERVERTXT ::= {
  [ PROPDEF, ]...
}

PROPDEF ::=
  PROPKEY => PROPVAL
PROPKEY ::=
  STRING
PROPVAL ::=
  NUMERICAL | STRING | LIST | MAP
STRING ::=
  'character sequence'
NUMERICAL ::=
  number
LIST ::=
  [ [ PROPVAL, ]... ]
MAP ::=
  { [ PROPDEF, ]... }

Notation

User specific data is printed in italic.

Optional properties are enclosed in brackets:

['PROPERTY' => ...,]

It is possible to use end-of-line comments in the SERVER.txt file. These are denoted by a leading '#'. For instance,

# This is a comment

Property precedence

Some properties may be specified in different and even multiple contexts. For example, the 'NOTIFICATIONS' property may be specified both at the project and global level. In such cases, the project specific settings override the global settings. If no project specific settings are available, the global settings are used. If no project specific settings are available and no global settings are available, the property default (if any) is used.

(In general, properties in a nested context override the global properties for that specific context.)

Available properties

This section gives an overview of all available properties in the SERVER.txt.
ALLOWCOMMENTSUPPRESSIONSoptionaldefault = 1
ARCHIVEGENoptional 
AUTHENTICATIONoptional 
BUGTRACKERoptional 
BUILDRELATIONSEARCHDEPTHoptional
BUILDTOOLSoptional 
COLLECTCLIENTSTATSoptionaldefault = 0
COMPILERSoptional 
CONFIGURATIONoptional 
DATABASEoptional 
DOSUBSToptionaldefault = 1
EMAILmandatory 
EXTINCLUDEoptionaldefault = [ 'h', 'hpp' ]
FILEFILTERSoptional 
FOLLOWLINKSoptionaldefault = 1
INCLUDERELATIONCONTINUEOUTSIDEARCHIVEoptionaldefault = 0
LANGUAGESmandatory 
LDAPoptional 
LICDIRoptional 
MAILTOoptionaldefault='mailto:tics@tiobe.com'
METRICSoptional 
METAINFOoptionaldefault = 1
MSBUILDINPLACEoptionaldefault = 0
NOTIFICATIONSmandatory 
ONLYBUILDRELATIONSFROMDBoptionaldefault = 0
ORGANIZATIONoptionalrecommended
OWNERmandatory 
OWNERVERBOSEoptionaldefault = ''
POSTQDBoptional 
PREPAREQDBoptional 
PYTHONVERSIONoptional 
SCHEDULEoptional 
SCMTOOLoptional 
SITEoptionalrecommended
SUPPRESSMACROEXPANSIONVIOLATIONSoptionaldefault = []
TOOLSoptional 
TQIVERSIONoptional 
WEBSERVERmandatory 

Example of SERVER.txt

The non-realistic example below is a showcase of many of the possibilities in the SERVER.txt. It also illustrates the traditional order in which many of the common properties are presented. Such a customary element order aids TICS service engineers in quickly finding the definitions they are looking for.
{
  'OWNER' => 'owner',
  'MAILTO' => 'mailto:tics@tiobe.com',
  'SITE' => 'site',
  'ORGANIZATION' => 'organization',

  'SCMTOOL' => {
    'NAME' => 'CVS | ClearCase | Git | Perforce | RTC | Subversion | Synergy | TFVC',
  },

  'DATABASE' => {
    'SERVER' => 'dbserver.company.com',
    'DBPATH' => 'C:/TICS/databases',
    'DB_BACKUP_DIR' => 'C:/TICS/BuildServer/backups/databases',
    'NROFBACKUPS' => 20,
  },

  'SCHEDULE' => {
    'LOGDIR' => 'C:/TICS/logs',
    'NROFBACKUPS' => 20,
  },

  'CONFIGURATION' => {
    'BACKUP_DIR' => 'C:/TICS/BuildServer/backups/cfg',
  },

  'LANGUAGES' => {
    'CPP' => {
      'EXTENSIONS' => [ 'cpp' ],
      'BUILDTYPE' => [
        { 'name' => 'VCXProj', 'compiler' => [ 'VC' ] },
        { 'name' => 'Make', 'compiler' => [ 'Gcc' ] },
        { 'name' => 'Tornado', 'compiler' => [ 'Gcc' ] },
      ],
      'GENERATED' => [
        {
         'OPEN' => '// {{{USR',
         'CLOSE' => '// }}}USR',
         'GENERATED' => 0,
        },
        {
         'OPEN' => '// {{{RME classAttribute',
         'CLOSE' => '// }}}RME',
         'GENERATED' => 0,
        },
        {
         'OPEN' => '// {{{RME operation',
         'CLOSE' => '// }}}RME',
         'GENERATED' => 0,
        },
        {
         'OPEN' => '// {{{RME',
         'CLOSE' => '// }}}RME',
        },
        {
         'OPEN' => '^\s*//{{',
         'CLOSE' => '^\s*//}}',
        },
        {
         'OPEN' => '^\s*BEGIN_ACCESSOR_MAP',
         'CLOSE' => '^\s*END_ACCESSOR_MAP',
        },
        {
         'OPEN' => '^\s*BEGIN_COM_MAP',
         'CLOSE' => '^\s*END_COM_MAP',
        },
        {
         'OPEN' => '^\s*BEGIN_CONNECTION_POINT_MAP',
         'CLOSE' => '^\s*END_CONNECTION_POINT_MAP',
        },
        {
         'OPEN' => '^\s*BEGIN_MESSAGE_MAP',
         'CLOSE' => '^\s*END_MESSAGE_MAP',
        },
        {
         'OPEN' => '^\s*BEGIN_OBJECT_MAP',
         'CLOSE' => '^\s*END_OBJECT_MAP',
        },
      ],
      'RULESETS' => [
        {
          'NAME' => 'C++ Coding Standard',
          'DOCNAME' => 'http://server.tiobe.com/codingrules/show_rule.php',
          'SEP' => '_',
          'ANCHOR' => '?ID='
        },
      ],
    },
    'C' => {
      'EXTENSIONS' => [ 'c' ],
      'BUILDTYPE' => [
        { 'name' => 'VCXProj', 'compiler' => [ 'VC' ] },
        { 'name' => 'Make', 'compiler' => [ 'Gcc' ] },
        { 'name' => 'Keil', 'compiler' => [ 'Keil' ] },
        { 'name' => 'Rose', 'compiler' => [ 'Keil' ] },
        { 'name' => 'Tasking', 'compiler' => [ 'Tasking' ] },
        { 'name' => 'Tornado', 'compiler' => [ 'Gcc' ] },
      ],
      'GENERATED' => [
        {
         'OPEN' => '/\* {{{USR \*/',
         'CLOSE' => '/\* }}}USR \*/',
         'GENERATED' => 0,
        },
        {
         'OPEN' => '/\* {{{RME classAttribute',
         'CLOSE' => '/\* }}}RME \*/',
         'GENERATED' => 0,
        },
        {
         'OPEN' => '/\* {{{RME operation',
         'CLOSE' => '/\* }}}RME \*/',
         'GENERATED' => 0,
        },
        {
         'OPEN' => '/\* {{{RME',
         'CLOSE' => '/\* }}}RME \*/',
        },
      ],
      'RULESETS' => [
        {
          'NAME' => 'C Coding Standard',
          'DOCNAME' => 'http://server.tiobe.com/codingrules/show_rule.php',
          'SEP' => '_',
          'ANCHOR' => '?ID='
        },
      ],
    },
    'CS' => {
      'EXTENSIONS' => [ 'cs' ],
      'BUILDTYPE' => [
        { 'name' => 'CSProj' },
      ],
      'RULESETS' => [
        {
          'NAME' => 'C# Coding Standard',
          'DOCNAME' => 'http://server.tiobe.com/codingrules/show_rule.php',
          'SEP' => '_',
          'ANCHOR' => '?ID='
        },
      ],
    },
  },

  'METRICS' => {
    'CODINGSTANDARD' => {
      'ENABLED' => 1,
      'TARGETS' => [
        {
          'KIND' => 'RELATIVE',
        },
        {
          'KIND' => 'ABSOLUTE',
          'VALUE => '60',
          'SCOPE' => '/tst/'
        },
      ],
      'BLOCKINGTARGETS' => [
        {
          'KIND' => 'RELATIVE',
          'VALUE' => 3,
        },
        {
          'KIND' => 'ABSOLUTE',
          'VALUE => '3',
          'SCOPE' => '@src/MyProject.vcpoj'
        },
      ],
    },
    'UNITBRANCHCOVERAGE' => {
      'ENABLED' => 1,
    },
    'UNITSTATEMENTCOVERAGE' => {
      'ENABLED' => 1,
    },
    'UNITFUNCTIONCOVERAGE' => {
      'ENABLED' => 1,
    },
    'LOC' => {
      'ENABLED' => 1,
    },
    'ELOC' => {
      'ENABLED' => 1,
    },
    'CYCLOMATICCOMPLEXITY' => {
      'ENABLED' => 1,
    },
  },

  'WEBSERVER' => {
    'PORTALURL' => 'www.company.com:42506/TIOBEPortal',
    'SHOWANNOTATEDSOURCES' => 1,
  },

  'POSTQDB' => 'postana.bat',
  'PREPAREQDB' => 'build.bat',
  'PYTHONVERSION' => '3.6',
  ## By default, TICS resolves substituted drive letters to their referenced
  ## locations when computing canonical file names (as they are stored in the
  ## quality database).
  ## To prevent TICS from expanding the 'subst' drive letters and accept
  ## substituted drive letters as canonical, set the value below to '0'.
  'DOSUBST' => 1,
}

ALLOWCOMMENTSUPPRESSIONS

Syntax

'ALLOWCOMMENTSUPPRESSIONS' => 0 | 1
This setting is optional; the default is 1.

Description

By default, TICS allows developers to suppress rule violations by putting //TICS or /*TICS comments in the source code. The idea is that there may be valid reasons why a rule violation is allowed in certain special cases and the suppressed violations are logged in the database by TICSQServer in any case so they can be inspected later.

However, in client only environments, suppressions are in danger of being overlooked, so it is possible to configure TICS to not honor the special suppression comments in the source code. In that case, violation instances are reported as normal.

Context

The ALLOWCOMMENTSUPPRESSIONS property is used in the following contexts:


ARCHIVEGEN

Syntax

'ARCHIVEGEN' => 'custom archive generator'

Description

Property ARCHIVEGEN can be used to indicate how the archive expression for a project should be generated. Many organizations have a particular directory structure that is used for many of their projects. Instead of having to specify this structure time and again for each new project, this structure can be used to automatically generate an appropriate archive expression upon project creation/configuration.

This setting is optional.

AUTHENTICATION

This setting has been deprecated as of version 8.7 and is from then on configured in the TICS Viewer using the security settings in the Administration Pages. Your existing configuration has been automatically migrated during the upgrade to 8.7. Please verify whether your authentication settings have been successfully migrated by using the Administration Pages and remove the AUTHENTICATION setting from your TICS configuration files. Note that you need to have the proper permissions to access the Administration pages.


BUGTRACKER

Syntax

  'BUGTRACKER' => {
    'NAME' => 'bugtracker name'
  }
This setting is optional.

Description

The BUGTRACKER property is required when calculating the fix rate and/or accumulative fix rate metrics. These metrics relate the changes of a file to defects in a bugtracker. The BUGTRACKER property determines the specific implementation that is used to obtain the defect information from.

Example

'BUGTRACKER' => { 'NAME' => 'Jira' }

BUILDRELATIONSEARCHDEPTH

Syntax

'BUILDRELATIONSEARCHDEPTH' => max-depth
This setting is optional. If the property is unset, the search depth is "infinite". I.e., the search for a makefile continues until the root of the file system is reached.

Description

The BUILDRELATIONSEARCHDEPTH property can be used to limit searching the file system when a project file cannot be found in the database. Normally, a makefile is searched for relative to the source file by searching in the direction of the file system root. On large file systems, this can be costly. With this property, the number of levels searched upwards can be limited.

Context

The BUILDRELATIONSEARCHDEPTH property is used in the following contexts:

Example

'BUILDRELATIONSEARCHDEPTH' => 3

BUILDTOOLS

Syntax

'BUILDTOOLS' => {
  ['gradlew' => GRADLEW,]
  ['Maven' => MAVEN,]
  ['MSBUILD' => MSBuild,]
}

Description

Some build tools require additional configuration. This can be added to a subsection of the BUILDTOOLS section.

Context

Build-specific options can be configure to support build tools such as gradlew, Maven and MSBuild.


COLLECTCLIENTSTATS

Syntax

'COLLECTCLIENTSTATS' => 0|1
This setting is optional, the default is 0.

Description

By default, TICS does not track client usage in the database. Use this property to enable client usage statistics in the database. The following data is stored for each TICS run: start and end time of the run, the username of the account running the process, whether the run succeeded or not and any error message that occurred as well as any files affected by the run and their SCM IDs.

Context

The COLLECTCLIENTSTATS property is used by the TICS client to decide whether or not to store certain run properties in the database.

Example

'COLLECTCLIENTSTATS' => 1

COMPILERS

Syntax

'COMPILERS' => {
  ['compiler' => {
    'BINNAMES' => [ [executable name],... ],
    'COMMENTPRESERVATION' => {language => [0 | 1]},
    'WARNINGFLAGS' => [ [flag],... ],
  }],...
},
This setting is optional.

Description

The BINNAMES property

For each compiler TICS supports, a default set of known executable names is hard-coded in TICS. If for such a compiler an executable is used in your build environment that is not supported by TICS, this name can be configured in this property. Specify only the name of the exectable. If no extension is specified, under Windows, the default extension .exe is appended to the compiler name.

The BINNAMES property is optional. Any compiler names specified by this property are appended to the default (hard-coded) set.

Context

The BINNAMES property is used in the following contexts:

Example

'COMPILERS' => {
  'Gcc' => {
    'BINNAMES' => [ 'gcc', 'gcc960', 'cc386', 'ccarm', 'dplus' ],
  }
}

The COMMENTPRESERVATION property

By default comments are preserved when a file is preprocessed. For some compilers this causes errors when files are preprocessed. When this happens COMMENTSPRESERVATION can be set to 0 to discard all comments during preprocessing. COMMENTSPRESERVATION is specified per language.

Example

'COMPILERS' => {
  'Gcc' => {
    'COMMENTPRESERVATION' => {
      'C' => '1',
      'CPP' => '0',
    }
  }
}

The WARNINGFLAGS property

Since a compiler type can represent multiple specific compiler implementations, the WARNINGFLAGS can be used to distinguish between these specific compiler implementations with respect to supported warning classes for Compiler Warning analysis.

Important: the WARNINGFLAGS property is currently only respected by the Gcc compiler type. I.e., other built-in compiler types ignore this property, but custom implementations can make use of it.

WARNINGFLAGS may be specified per compiler type or compiler name. So, if you have a compiler binname cc386 you can also use this to specify warning flags specific to this compiler. Note that these warning flags are appended to the default set! (So, they do not replace any built-in flags.) In case WARNINGFLAGS are specified for both compiler type and compiler name, the union of these flags is taken.

Example (compiler type)

'COMPILERS' => {
  'Gcc' => {
    'WARNINGFLAGS' => [ '-Wextra' ],
  }
}

Example (compiler name)

'COMPILERS' => {
  'cc386' => {
    'WARNINGFLAGS' => [ '-Wno-missing-field-initializers', '-Wno-missing-braces' ],
  }
}

Context

The WARNINGFLAGS property is used in the following contexts:


CONFIGURATION

Syntax

'CONFIGURATION' => {
  ['INCDIRS' => 'additional configuration directories for custom modules',]
  ['BACKUP_DIR' => 'configuration backup directory',]
  ['NROFBACKUPS' => number of backups to keep,]
},
This setting is optional.

Description

INCDIRS can be used to organize the configuration directory. In case one has many custom modules, perhaps some of them shared with other TICS configurations, then it may be convenient to use INCDIRS.

Example
'CONFIGURATION' => {
  'INCDIRS' => ['../../common'],
}

Note that relative paths are resolved against the directory containing the SERVER.txt file. I.e., the TICS configuration directory ($TICS (Linux) or %TICS% (Windows)).

Caveat Module names in these directories (configuration directory and INCDIRS) should be unique (i.e., no two modules in any of these directories should have the same base name). So, if the configuration directory contains A.pm and ../../common has a A.pm this is a problem.

Example
'CONFIGURATION' => {
  'INCDIRS' => ['custom'],
}
$TICS/
[...]
|-- SERVER.txt
[...]
|-- custom
|   |-- TICSBuildCustom.pm
|   |-- TICSBuildMake.pm
|   `-- TICSSCMToolCustom.pm
[...]
`-- prepare.bat

In this setup, the custom modules from the custom/ directory are also used during the TICS run. E.g., in the example above, modules TICSBuildCustom.pm, TICSBuildMake.pm and TICSSCMToolCustom.pm override any built-in module of the same name (TICSBuildMake.pm) and can be used in the TICS configuration and TICS run: TICSBuildCustom.pm with 'BUILDTYPE' => [{'name' => 'Custom'}], TICSSCMToolCustom.pm with 'SCMTOOL' => {'NAME' => 'Custom'}.

If the BACKUP_DIR property is set, its value is used as a target directory to copy the configuration files to (as determined by the current settings). If the directory does not exist, it is created if possible. No history is preserved, just a single copy is stored.

The BACKUP_DIR property is offered as an alternative when your TICS configuration is not under configuration management or not covered by your local backup policy. It gives you the opportunity to save a copy of the configuration directory to another location.

The BACKUP_DIR property can also be used to synchronize the configuration with another TICS component that cannot directly access the original location. Example Suppose the TICS web server (viewer) cannot access the configuration on the file server, but the build server has access to the file system of the web server, then, by specifying the appropriate location on the web server as the value of the BACKUP_DIR property, TICSQServer can synchronize its configuration with the configuration used by the viewer.

If your TICS configuration is not under version control and not covered by the local backup policy, it is advisable to use the BACKUP_DIR property to save another copy of your configuration. This avoids nasty surprises when you suffer a disk crash or an involuntary deletion of files on the file server.

Context

The INCDIRS property is used at initialization time by TICS client, TICSQServer, TICSMaintenance, TICSMigrate and TICSQuery. When determining the configuration, this property is used to load the relevant modules when they are needed. Note that custom modules are only loaded when first needed.

The BACKUP_DIR property is used at initialization time by TICSQServer. When determining the configuration, this property is used to save relevant files to the specified location.

Example

'CONFIGURATION' => {
  'INCDIRS' => ['prepare', '../../common'],
  'BACKUP_DIR' => 'C:/TICS/BuildServer/backups/cfg',
  'NROFBACKUPS' => 20,
},

DATABASE

Syntax

'DATABASE' => {
  'DBPATH' => 'full path to database path',
  'SERVER' => 'name/ip-address of the database server',
  ['PASSWORD:PLAIN' => 'password',]
  ['DB_BACKUP_DIR' => 'full path to backup directory',]
  ['DB_BACKUP_TIMEOUT' => maximum time a backup may take (in minutes),]
  ['DB_BIN => 'full path to the database executable in case not in default path',]
  ['NROFBACKUPS' => number of backups maintained,]
  ['PORT => port number of the database server,]
  ['QUERYFAILURERETRYATTEMPTS' => number of times a query is retried after sql failure,]
  ['QUERYFAILURERETRYTIMEOUT' => timeout after sql failure (in seconds; default is 60),]
  ['USERNAME' => 'username',]
},

Description

The optional DATABASE section sets the database connection information. The only mandatory properties are the domain name or the IP address of the SERVER that hosts the database and the DBPATH that contains the location of the Firebird database files.

The DATABASE section can also be set per project in the PROJECTS.txt.

DBPATH: The directory containing the Firebird database files.

SERVER: The domain name or IP address of the server that hosts the database.

DB_BACKUP_DIR: A location to store database backups in.

DB_BACKUP_TIMEOUT: Maximum time a backup may take in minutes. Default is 120 minutes / 2 hours.

DB_BIN: The directory containing the Firebird executables (such as gbak).

NROFBACKUPS: The number of backups to keep.

USERNAME: The name of the user to authenticate as.

PASSWORD: The password belonging to the account above.

QUERYFAILURERETRYATTEMPTS: The number of times a query is retried when a SQL failure occurs. For example when the connection to the database is lost. By default, 3 attempts are made to execute a query successfully.

QUERYFAILURERETRYTIMEOUT: Sometimes the connection to the database is lost, due to among other things, network problems. In that case it would be possible to proceed by reconnecting to the database. With this option, the timeout in seconds is given, after which a new connection is established. By default, the timeout is 60 seconds. The reconnection feature is only supported for a handful of SQL problems.

Context

The DATABASE property is used in the following contexts:


DOSUBST

Syntax

'DOSUBST' => 0|1
This setting is optional; the default is 1.

Description

By default, on Windows, TICS uses the original directory for drives created via the shell command SUBST in file names. In some cases this is will lead to problems. For example when absolute paths in source code are used for included files. Or when relative paths are relative to the subst drive. In those cases set the DOSUBST property to 0.

The DOSUBST property is optional and when omitted DOSUBST will be set to the value 1.

Context

The DOSUBST property is used in the following contexts:

Example

'DOSUBST' => 0

EMAIL

Syntax

'EMAIL' => {
  'FROM' => 'e-mail address',
  ['SMTPHOST' => 'send mail host',]
  ['MAILER' => 'mail module to use for sending e-mail',]
  ['USERNAME' => 'user name required to authenticate to the HTTP mail relay',]
  ['PASSWORD:PLAIN' => 'plain password required to authenticate to the HTTP mail relay',]
  ['PROXYSETTINGS' => {
    ['URL' => 'proxy server location',]
    ['USERNAME' => 'user name required to authenticate to the proxy server',]
    ['PASSWORD:PLAIN' => 'plain password required to authenticate to the proxy server',]
    ['PACFILE' => 'URL or path to PAC file',]
  },]
}
This setting is mandatory. See NOTIFICATIONS for mandatory notification mail sub-properties.

Description

Basic outgoing mail configuration. TICS can send a number of email notifications: error messages, status reports (a.o., to the TED), and SQA reports.

The basic mail configuration covers the 'From' address to be used as sender of TICS mails and the SMTP host to use for sending mails.

See LDAP and NOTIFICATIONS for further mail configuration properties.

The MAILER property can be used to specify the mail method used to send e-mail. Two mail methods are shipped with TICS as built-ins: Http and Smtp.

The Http method requires USERNAME and PASSWORD to authenticate to the mail relay.

The Smtp method requires SMTPHOST to be set to a (local) SMTP host that is capable of sending unauthenticated e-mail.

The SMTPHOST property is mandatory in the case of method 'Smtp' and should point to a valid SMTP mail server that allows the TICSQserver process to send e-mails. Currently, authenticating SMTP hosts are not supported. The 'FROM' property can be used to easily identify the e-mails sent by TICS.

In PROXYSETTINGS, URL can be used to specify the proxy server that TICS should use when sending email notifications in case your intranet settings require a proxy to communicate with the internet. It should be of the format host:port. If the port number is omitted, 8080 will be used. USERNAME and PASSWORD can be used to connect through an authenticated proxy.

The PACFILE is an alternative and more advanced way to configure a proxy server. It can be used to used if you have a so-called proxy auto-config (PAC) file that contains proxy server information for your intranet. The PAC-file can be a local file or a URL. You should not set PACFILE if PROXYSETTINGS => URL has been set, as it will be ignored.

Example
  PROXYAUTOCONFIG => 'file:///c:/proxy.pac',

Context

The EMAIL property is used in the following contexts:

Example

'EMAIL' => {
  'FROM' => 'ticsqserver@company.com',
  'SMTPHOST' => 'smtp.company.com'
}

ERRORSUPPRESSION

Syntax

'WEBSERVER' => {
  'ERRORSUPPRESSION' => 0 or 1 (optional; default=1),
},

This setting is optional.

Description

When TICS fails to analyze a file, for instance because of a tool error, it cannot produce a sensible metric value for that file and instead stores the error in the database. Error Suppression, which is enabled by default, is a feature of the viewer that replaces erroneous measurements by an earlier successful measurement for that file, if available. Without error suppression, such errors would negatively impact the TQI scores, because they decrease the metric coverage.

The advantage of error suppression (also called "spike management") is that trend lines for TQI metrics will be more stable and will have less improper drops that are caused by external factors such as tool failures. The disadvantage is that you might be looking at data that is out-of-date as long as the tool keeps failing. The Annotated Source will give a warning in such cases, because you might observe a mismatch between the source code and the reported violations. Other parts of the viewer will not warn you about this.

The error suppression feature can be disabled per project by setting ERRORSUPPRESSION of the WEBSERVER to 0. When changing this setting, it is needed to invoke a generate viewer cache event afterwards.


EXTINCLUDE

Syntax

'EXTINCLUDE' => [ [ext,]... ]
This setting is optional (default=[ 'h', 'hpp' ]).

Description

By default, TICS recognizes the .h and .hpp extensions as include files. On Windows, these extensions are matched case insensitively; on Unix, these are matched case sensitively. Some projects require additional or other extensions for include files. These can be specified by the EXTINCLUDE property.

The EXTINCLUDE property overrides the default settings!

Context

The EXTINCLUDE property is used in the following contexts:

Example

'EXTINCLUDE' => [ 'h', 'hh', 'inc' ]

FILEFILTERS

Syntax

'FILEFILTERS' => {
  ['ARCHIVE' => 'ARCHIVE',]
  ['CONTENT' => [
  [ {
      ['ARCHIVE' => 'ARCHIVE',]
      'MARKERS' => {
          ['ALL' => 'marker file',]
          ['ANY' => 'marker file',]
          ['NONE' => 'marker file',]
      }
      'CONTAINS' => {
          ['ALL' => 'contains file',]
          ['ANY' => 'contains file',]
          ['NONE' => 'contains file',]
      }
    } ]+
  ], ]
}
This setting is optional.

Description

Property FILEFILTERS lists zero or more so-called file filters. File filters limit the scope of the archive.

The following file filters are available at top level or project level.

ARCHIVE: This property refers to a so-called archive file relative to the configuration directory. See the ARCHIVE Reference Guide for more information on the contents of ARCHIVE files.

Note that for the ARCHIVE expressions on top level, only the so-called legacy mode is available (see ARCHIVE Reference Guide). This is because, without a project, the branch directory cannot be determined (which is needed to determine the root directory of the branch).

CONTENT: This property allows inclusion/exclusion of files based on their contents. It consists of two mandatory parts and an optional third part: the MARKERS part (mandatory) that defines what the interesting parts of input files look like; the CONTAINS part (mandatory) that describes what these markers should or should not contain; and the ARCHIVE part (optional) that optionally restricts the content filter to files that match the archive expression.

Both MARKERS and CONTAINS contain one or more (up to three) subkeys to fine tune the search. The keys are called ALL, ANY and NONE. Each of these keys take a file name (in the configuration directory) as a value.

ALL indicates that all entries in the specified file must be satisfied. ANY indicates that at least one of the entries must be satisfied. NONE means that none of the entries must match. Matches are case insensitive.

It works as follows. First, the input file is scanned for the occurrence of strings from any of the MARKERS in comment tokens. Any matching comments are returned and subsequently scanned for strings specified by CONTAINS.

Example Matching Markers in a Source File

An example should clarify how markers from a source file are matched.

MySourceFile.c
/* Pro mundi ponderum ea, ABC duo ei graece luptatum pertinax */
int ABC(void);
/* Eirmod eloquentiam vim te, DEF ornatus vivendo ex mei */
void DEF(int);
/* Ludus eruditi graecis vel ut, pri atqui libris expetenda eu. */
void ABCDEF(void);
Content file filter
'MARKERS' => {
  'ANY' => 'ABCDEF.txt',
}
ABCDEF.txt
ABC
DEF

Running the content filter on MySourceFile.c gives

/* Pro mundi ponderum ea, ABC duo ei graece luptatum pertinax */

and

/* Eirmod eloquentiam vim te, DEF ornatus vivendo ex mei */

So, it only returns comments (and not the other occurrences of ABC or DEF).

Subsequently, these comments are subject to CONTAINS filtering. Let's consider several cases.

Exclude occurrences of ABC and DEF
Use 'NONE' to exclude
'CONTAINS' => {
  'NONE' => 'ABCDEF.txt',
}

This would reject both

/* Pro mundi ponderum ea, ABC duo ei graece luptatum pertinax */

and

/* Eirmod eloquentiam vim te, DEF ornatus vivendo ex mei */
Include occurrences of 'vim'
Use 'ANY' to include
'CONTAINS' => {
  'ANY' => 'VIM.txt',
}
VIM.txt
vim

This would accept

/* Eirmod eloquentiam vim te, DEF ornatus vivendo ex mei */

and reject

/* Pro mundi ponderum ea, ABC duo ei graece luptatum pertinax */
Include occurrences of 'ei'
'CONTAINS' => {
  'ANY' => 'EI.txt',
}
EI.txt
ei

This would accept both

/* Pro mundi ponderum ea, ABC duo ei graece luptatum pertinax */

and

/* Eirmod eloquentiam vim te, DEF ornatus vivendo ex mei */
Exclude occurrences of 'ei'
Note the 'NONE' instead of 'ANY'
'CONTAINS' => {
  'NONE' => 'EI.txt',
}

This would reject both

/* Pro mundi ponderum ea, ABC duo ei graece luptatum pertinax */

and

/* Eirmod eloquentiam vim te, DEF ornatus vivendo ex mei */

Example (white list)

Suppose we want to exclude all files that have a copyright statement containing a company name other than our own. This is a form of white-listing where we only accept those files that satisfy the strings explicitly listed. We would specify the following.

  'FILEFILTERS' => {
    'CONTENT' => [
      {
        'MARKERS' => {
          'ANY' => 'COPYRIGHT.txt',
        },
        'CONTAINS' => {
          'ANY' => 'COMPANY.txt',
        },
      }
    ],
  },

Here, 'COPYRIGHT.txt' contains the following.

(C)
Copyright

This means we are going to scan the input file for comment tokens that contain (C) or (we used 'ANY') Copyright (case insensitively). If no such tokens are found, we accept the file.

'COMPANY.txt' contains the following.

Acme Legal Corp
Acme Taxes Corp

This means we are going to accept the file if any markers from above contain Acme Legal Corp or (again: 'ANY') Acme Taxes Corp. Otherwise, the file is rejected and not included for quality analysis.

Example (black list)

Suppose we want to exclude all auto-generated files. Auto-generated files, in our case, are files containing one of the following remarks:

<autogenerated>
<auto-generated>

Here, we implement a so-called black list where all explicitly listed strings are disallowed. We specify the following.

  'FILEFILTERS' => {
    'CONTENT' => [
      {
        'MARKERS' => {
          'ANY' => 'AUTOGEN.txt',
        },
        'CONTAINS' => {
          'NONE' => 'AUTOGEN.txt',
        },
      }
    ],
  },

Here, 'AUTOGEN.txt' contains the following.

<autogenerated>
<auto-generated>

This means we are going to scan the input file for comment tokens containing <autogenerated> or (we used 'ANY') <auto-generated> (case insensitively). If no such tokens are found, we accept the file.

But, now, in case matching comments are found, we specify that these may not contain <autogenerated> or <auto-generated>. What is this? This is the general pattern for excluding literal text. This is necessary since files, in general, will contain comments that do not match any of the strings in 'AUTOGEN.txt'. This means we cannot use

  'FILEFILTERS' => {
    'CONTENT' => [
      {
        'MARKERS' => {
          'NONE' => 'AUTOGEN.txt',
        },
      }
    ],
  },

since that would include such files (instead of excluding them as desired).

Example (conditional content filter)

Here, we want to conditionally mark files matching a certain location as generated code. Note the 'ARCHIVE' below.

  'FILEFILTERS' => {
    'CONTENT' => [
      {
        'ARCHIVE' => 'ARCHIVE_GENERATED_AADE.txt',
        'MARKERS' => {
          'ANY' => 'GENERATEDFILES_AADE.txt',
        },
        'CONTAINS' => {
          'NONE' => 'GENERATEDFILES_AADE.txt',
        },
      }
    ],
  },

The files above have the following contents.

'ARCHIVE_GENERATED_AADE.txt'

'FILE' => "/BB-025-0017A/AADE/"

'GENERATEDFILES_AADE.txt'

#generated by DriFE#

Consider the following source files in the archive.

src/BB-025-0017A/AADE/file1.c
src/BB-025-0017A/file2.c
src/BB-025-0017A/AADE/file3.c

with the following contents:

src/BB-025-0017A/AADE/file1.c

//#generated by DriFE#

src/BB-025-0017A/file2.c

//#generated by DriFE#

src/BB-025-0017A/AADE/file3.c

//#generated by ASD

file1.c matches 'ARCHIVE', therefore, the content filter is applied and matches. So, file1.c is excluded. file2.c does not match 'ARCHIVE', therefore, the content filter is not applied and file2.c is included. file3.c matches 'ARCHIVE', therefore, the content filter is applied and does not match. So, file3.c is included.


Syntax

'FOLLOWLINKS' => 0|1
This setting is optional; the default is 1.

Description

On Unix (including Linux), files and folders can be symbolic links, pointing to the real file or folder (or even other links). Some projects are set up to create a folder structure that depends on linked files and folders, in which case, the links should be followed by TICS to obtain the actual file or folder. But in other cases, for example, when using CMSynergy under certain conditions, symbolic links point to the CMSynergy database file, and in that case the link should not be followed, but must be treated as if the link were the actual file.

The FOLLOWLINKS property is optional and when omitted FOLLOWLINKS will be set to the value 1, meaning links will be traversed.

Context

The FOLLOWLINKS property is used in the following contexts:

Example

'FOLLOWLINKS' => 0

INCLUDERELATIONCONTINUEOUTSIDEARCHIVE

Syntax

'INCLUDERELATIONCONTINUEOUTSIDEARCHIVE' => 0|1
This setting is optional; the default is 0.

Description

Normally, during include relation calculation, TICS should stop once a file outside the archive is found, since it is unlikely that this should (transitively) include files from inside the archive again.

However, in some cases, it is the case that files from inside the archive are included from files outside the archive. In those cases, 'INCLUDERELATIONCONTINUEOUTSIDEARCHIVE' can be set to 1.

Context

The INCLUDERELATIONCONTINUEOUTSIDEARCHIVE property is used in the following contexts:

Example

'INCLUDERELATIONCONTINUEOUTSIDEARCHIVE' => 1

LANGUAGES

Syntax

'LANGUAGES' => {
[ 'language' => {
    'EXTENSIONS' => [ ['file extension',]+ ],
    [ 'RULESETS' => [
      [ {
        'NAME' => 'ruleset name',
        'METRIC' => 'corresponding metric',
        'RULESDIR' => 'directory for configuration files',
        ['DYNAMICRULESET' => [0|1]]
        ['ANCHOR' => 'coding standard anchor',]
        ['DOCNAME' => 'url or related path to document',]
        ['DOCSUF' => 'rule property to use as URL path suffix',]
        ['SEP' => 'rule separator',]
      }, ]+
    ], ]
    [ 'BUILDTYPE' => [
      [ {
        'name' => 'buildtype',
        ['compiler' => [ ['compiler']+ ],]
        ['make' => 'path to GNU make 3.80 executable',]
      }, ]+
    ], ]
    [ 'GENERATED' => [
      [ {
        'OPEN' => '<reg expression>',
        'CLOSE' => '<reg expression>',
        'GENERATED' => [0 | 1],
      }, ]+
    ], ]
    [ 'CYCLOMATICCOMPLEXITY' => {
      'TOOL' => 'cyclomatic complexity measuring tool',
    }, ]
    [ 'DEADCODE' => {
      'TOOL' => 'deadcode measuring tool'
    }, ]
    [ 'DUPLICATEDCODE' => {
      'TOOL' => 'code duplication measuring tool'
    }, ]
    [ 'FANOUT' => {
      'EXTERNALNAMESPACE' => ['list of namespaces external to the software system'],
      'INTERNALNAMESPACE' => ['list of namespaces internal to the software system'],
      'TOOL' => 'fanout measuring tool',
      'CUSTOMIMPORTS' => ['list of custom import keywords'],
    }, ]
    [ 'TESTCOVERAGE' => {
      'TOOLS' => ['test coverage measuring tools']
    }, ]
  }, ]+
},

Description

The 'LANGUAGES' property is mandatory. It specifies a set of properties for each language. Languages are identified by their logical name. Built-in language identifiers include: 'C', 'CPP' (C++), 'CS' (C#), 'JAVA', 'JAVASCRIPT', 'KOTLIN', 'LUA', 'MATLAB', 'OBJECTIVEC', 'PYTHON', 'SCALA', 'SQL', 'TYPESCRIPT', 'VB' (Visual Basic .NET), 'XAML'.

Source files are associated with a language via their file extensions. This is configured via the 'EXTENSIONS' property. For example, use 'EXTENSIONS' => [ 'c' ] for C source files, 'EXTENSIONS' => [ 'cpp' ] for C++ source files, or 'EXTENSIONS' => [ 'cs' ] for C# source files.

Some metrics (e.g., 'COMPILERWARNING') require compiler options. To obtain these options from the (build) environment, one or more so-called build types must be specified via 'BUILDTYPE'. A build type has a 'name' and optionally a list of supported compilers. The build type is used to read associated build/makefiles/project files to extract file lists and options for the preprocessor. A matching compiler of the list of candidates is used to extract compiler options from the build and perform preprocessing (if required). It is even possible to specify some additional (non-standard) preprocessing flags to the compiler. For C and C++ using Microsoft Visual Studio, the following build type definition can be used:

'BUILDTYPE' => [
  { 'name' => 'VCXProj', 'compiler' => [ 'VC' ] },
],

A ruleset (in 'RULESETS') must be configured for metrics 'CODINGSTANDARD', 'COMPILERWARNING', 'ABSTRACTINTERPRETATION' and 'SECURITY'. A ruleset must have a unique name, a corresponding metric and a unique rule directory. A metric may be associated with more than one ruleset.

A ruleset 'NAME' must be (globally) unique. This is just a string identifying the ruleset. Usually, something of the form owner language metric; e.g., Acme C Coding Standard, Acme C++ Compiler Warnings.

A ruleset metric name must be one of CODINGSTANDARD, COMPILERWARNING, ABSTRACTINTERPRETATION, SECURITY.

'RULESDIR' specifies the location of the coding standard configuration files RULES.txt and IMPL.txt. Each ruleset must specify its rule configuration in a separate directory.

The property 'DYNAMICRULESET' defines whether a given ruleset is internally an aggregate of multiple different rulesets. For each file separately a choice is made on this ruleset dependent on the compiler version.

The properties 'DOCNAME', 'DOCSUF', 'SEP' and 'ANCHOR' may be set to configure the coding standard viewer for the corresponding language. In case the TICS coding standard viewer is used, setting 'DOCNAME' to the coding standard viewer location for the language is sufficient. In case 'DOCNAME' points to (static) HTML pages, 'SEP' and 'ANCHOR' may also have to be set (to be able to point to individual rules).

The SEI CERT Secure Coding Rules are supported as follows.

    'RULESETS' => [
      { 'NAME' => 'SEI CERT C++ Coding Standard',
        'METRIC' => 'SECURITY',
        ...
        'DOCNAME' => 'https://wiki.sei.cmu.edu/confluence/display/',
        'DOCSUF' => 'SYNOPSIS',
        'ANCHOR' => '/',
      },
    ],

So, by setting 'DOCNAME', 'DOCSUF' and 'ANCHOR' (to the values above).

'DOCNAME' points to the TICS coding standard viewer or another document located on a web server, e.g., http://outserver/codingstandard.html.

'ANCHOR' is the static part that redirects to the specific rule within a coding standard document. For example, if the document contains anchors named <a name="Rule100">, where 100 is the ID of the rule, then the 'ANCHOR' should be '#Rule'. For TICS coding standard viewers, this option can be omitted.

'SEP' overrides unencoded HTML entities in the coding standard document. In some cases, symbols that are not allowed in URLs, but that are part of the name of a coding standard rule, such as '#', are replaced by another character in the coding standard document. For example, a rule C#100 might be defined as anchor in the coding standard document as follows: <a name="RuleC_100"> (i.e., the '#' has been replaced by '_'). In this case, 'SEP' must be specified as '_'. An alternative (better) approach would be to use the URL-encoded character in the document; in this case: <a name="RuleC%23100"> (since '%23' is the URL-encoding of '#'), and avoid having to specify 'SEP' altogether. For TICS coding standard viewers, this option can be omitted.

The 'CYCLOMATICCOMPLEXITY' property specifies which cyclomatic complexity measurement tool to run for files of this language during the calculating metrics stage. Built-in supported cyclomatic complexity tools include: CMT, SourceMonitor, TICSpp, TICSsql, cccc, mlint. Not all tools are available for all languages or all platforms (Linux, Windows, macOS). It is possible to provide your own custom module and use that. If the language/cyclomatic complexity measuring tool combination does not fit (e.g., the cyclomatic complexity measuring tool does not work for files of the specified language), a warning is given at the start of the process, and an error during the calculating metrics stage. In case the 'CYCLOMATICCOMPLEXITY' property is not specified, 'TICSpp' is used.

The 'DEADCODE' property specifies the tool used to calculate dead code. Supported tools are: BuiltIn, Cppcheck

The 'DUPLICATEDCODE' property specifies the tool used to calculate code duplication. Supported tools are: CPD

The 'FANOUT' property specifies the tool used to calculate the fan-out metric. Supported tools are the following: C, Cpp, Go, Java, Javascript, Jsp, Kotlin, Lua, mlint, Objectivec, Perl, Python, Scala, Simulink, Swift, TICSCil, TICSsql, Typescript, Vb, None. TICSCil, TICSsql and mlint are tools used for C#, SQL and Matlab respectively. For header files, the C fan-out calculator is used. The TICSCil tool computes fan-out based on information in the associated assemblies. Note that Cs requires that the (Visual Studio) projects must have been built so the assemblies are present and the language 'BUILDTYPE' must be set so the build information can be obtained by TICS (to determine the assembly location).

For some languages, it is necessary to provide a way to identify whether the calculated fan-out is internal (ie. coming from the same software system) or external (from system or external libraries).

The 'EXTERNALNAMESPACE' property can be used to define a list of namespaces which are known to be from libraries external to the software system, and as such should be counted as external fan-out.

The 'INTERNALNAMESPACE' property can be used to define a list of namespaces which are a part of the software system being analyzed, and as such should be counted as internal fan-out.

Note that 'EXTERNALNAMESPACE' and 'INTERNALNAMESPACE' are mutually exclusive for the same language due to the way these properties are used. In the case an 'INTERNALNAMESPACE' is configured then everything outside of these namespaces will be counted as external, and vice versa. In cases both of these would be configured, then it would also be possible for a namespace to be neither of these, which is not allowed.

Sometimes, libraries and files are imported with a custom function. In such cases, the 'CUSTOMIMPORTS' property can be used. Currently, this is only used for Lua.

  'LANGUAGES' => {
    'CS' => {
      'FANOUT' => {
        'INTERNALNAMESPACE' => ['Tiobe.Roslyn'],
        'TOOL' => 'TICSCil',
      }
    },
    'JAVA' => {
      'FANOUT' => {
        'INTERNALNAMESPACE' => ['com.company', 'com.other-company-namespace'],
        'TOOL' => 'Java',
      }
    },
    'JAVASCRIPT' => {
      'FANOUT' => {
        'EXTERNALNAMESPACE' => ['dojo', 'dijit'],
        'TOOL' => 'Javascript',
      }
    },
    'LUA' => {
      'FANOUT' => {
        'TOOL' => 'Lua',
        'CUSTOMIMPORTS' => ['custom_import_function'],
      }
    },
    'TYPESCRIPT' => {
      'FANOUT' => {
        'TOOL' => 'Typescript',
      }
    }
  }

An example of how a Java source file with these settings in SERVER.txt will be scored on Internal and External Fan Out:

  // marked as external fan-out
  import java.io.File;
  import java.io.IOException;

  // marked as internal fan-out
  import com.company.FileUtils;
  import com.company.package.Runner;

This is not necessary for languages where it is possible to distinguish internal and external imports by the type of import that is being used. In the case of (C, C++, ObjC), internal and external fan-out can be distinguished by the type of include used, as shown in the following example:

  #include <cmath>      // standard include, will be marked as external fan-out
  #include "includes.h" // user include, will be marked as internal fan-out

The 'TESTCOVERAGE' property specifies to collect code coverage data generated by any one of the specified tools. In the case multiple code coverage tools are configured, TICS will check the result file to determine which code coverage tool was used to generate it. See the special Test Coverage chapter for more information on configuring test coverage data collection and its behavior.

Source files may contain generated regions. Usually, these regions are generated by some tool or an IDE wizard. These are outside the control of a developer and, therefore, must not produce violations that the developer is unable to solve. To avoid violations on generated code, the property 'GENERATED' can be used to define the generated regions by means of regular expressions.

The 'OPEN' property defines the pattern for the start marker of a region. The 'CLOSE' property defines the pattern for the end marker of that region. The 'GENERATED' property indicates whether the matched region is generated (value 1; this is the default) or user code (value 0).

Pattern values defined by 'OPEN' and 'CLOSE' are interpreted as follows:

.
Matches all characters, including newlines
^
Matches the start of a line (useful for preprocessor directives)
$
Matches the end of a line (useful for preprocessor directives)
\A
Matches the start of the file
\Z
Matches the end of the file
\b
Matches a word boundary (i.e., the transition between a word character and a non-word character)

Do not forget to escape regular expression meta characters that must be matched literally (such as *, ( and )). Furthermore, when matching arbitrary text between two fixed texts, be sure to take the shortest match by suffixing a + or * with ?, to make these operators non-greedy. Otherwise, the longest match is taken which is usually undesired. E.g., 'OPEN' => 'BEGIN.*?END'. In general, it is better to avoid using . altogether and be more specific about acceptable characters. E.g., 'OPEN' => '\bDependencyProperty\b[^;]*='. This matches anything except ; between DependencyProperty and =.

Matched regions should occur sequentially (linearly) or properly nested in a file. Regions should not partially overlap.

See the default SERVER.txt file that is included in the TICS installation for examples of 'GENERATED'.

Context

The LANGUAGES property is used in the following contexts:

Example

'LANGUAGES' => {
  'CPP' => {
    'EXTENSIONS' => [ 'cpp' ],
    'RULESETS' => [
      { 'NAME' => 'C++ Coding Standard',
        'METRIC' => 'CODINGSTANDARD',
        'RULESDIR' => 'codingstandard/cpp',
        'DOCNAME' => 'codingstandard.html',
        'SEP' => '#',
      },
    ],
    'BUILDTYPE' => [
      { 'name' => 'VCXProj', 'compiler' => [ 'VC' ] },
    ],
    'CYCLOMATICCOMPLEXITY' => {
      'TOOL' => 'TICSpp'
    },
    'DEADCODE' => {
      'TOOL' => 'Cppcheck'
    },
    'FANOUT' => {
      'TOOL' => 'Cpp'
    },
    'TESTCOVERAGE' => {
      'TOOLS' => ['Bullseye']
    },
  },
}

LDAP

Syntax

'LDAP' => {
  ['SERVER' => 'LDAP server',]
  ['BASE' => 'LDAP base property',]
  ['FILTER' => 'LDAP filter property',]
  ['ATTRIBUTE' => 'LDAP attributes',]
  ['PASSWORD:PLAIN' => 'LDAP password'),]
}
This setting is optional.

Description

The LDAP properties are used to couple user names to e-mail addresses via an LDAP server. This is used for sending so-called target e-mails when a file checked in by a certain user exceeds the target's threshold.

Context

The LDAP property is used in the following contexts:

This setting is only used by TICSQServer. The TICS Viewer can also connect to an LDAP server, which is configured in the Administration Pages.

Example

'LDAP' => {
  'SERVER' => 'ldapserver',
  'BASE' => 'OU=USERS,OU=aserver,OU=CODE,DC=LDAP,DC=TIOBE,DC=COM',
  'FILTER' => 'CN=%s',
  'ATTRIBUTE' => 'mail',
  'PASSWORD:PLAIN' => 'apassword',
}

LICDIR

Syntax

'LICDIR' => 'dir'
This setting is optional.

Description

'LICDIR' may be used to override the default location of the 'lic.dat' license file.

In case the 'LICDIR' property is not set, the default configuration directory is used. In case the 'LICDIR' property has a relative value, it is resolved against the configuration directory. In case the resulting path does not exist, an error is given.

Context

This is used when TICSQServer, etc are looking for the TICS license file.

Example

'LICDIR' => '../../common'

MAILTO

Syntax

'MAILTO' => 'support email address'
This setting is optional (default='mailto:tics@tiobe.com').

Description

In the MAILTO property the email address of the support team can be specified. Here, the support team is the team responsible for fixing problems in the TICS components and implementing new ideas. The support team may be a first line help desk at a customer site that acts as a proxy for the actual development team. It may also be a consultant that acts as an intermediate. Or, it can refer to TIOBE directly (this is the default).

If you do not expect any confusion, you can omit the mailto: protocal specifier, e.g., 'MAILTO' => 'tics@tiobe.com'.

Context

The MAILTO property is used in the following contexts:

Example

'MAILTO' => 'mailto:support@company.com'

METRICS

Syntax

'METRICS' => {
  ['metric name' => {
    'ENABLED' => 0 | 1,
    ['MINIMUMTOKENCOUNT' => 50,]
    ['TARGETS' => [
      {
        'KIND' => 'ABSOLUTE | RELATIVE',
        ['VALUE' => value,]
        ['SCOPE' => 'archive path expression'|@projectfile,]
        ['AGGREGATED' => 0 | 1,]
      },...
    ],]
    ['BLOCKINGTARGETS' => [
      {
        'KIND' => 'ABSOLUTE | RELATIVE',
        'VALUE' => value,
        ['SCOPE' => 'archive path expression'|@projectfile,]
        ['AGGREGATED' => 0 | 1,]
      },...
    ],]
  },]...
},
This setting is optional.

Description

The METRICS section specifies properties for the following metrics.

CODINGSTANDARD
Coding standard violations
COMPILERWARNINGS
Compiler warnings
ABSTRACTINTERPRETATION
Abstract interpretation
SECURITY
Security
UNITBRANCHCOVERAGE
Unit test/code branch coverage
UNITSTATEMENTCOVERAGE
Unit test/code statement coverage
UNITFUNCTIONCOVERAGE
Unit test/code function coverage
UNITDECISIONCOVERAGE
Unit test/code decision coverage
INTEGRATIONBRANCHCOVERAGE
Integration test/code branch coverage
INTEGRATIONSTATEMENTCOVERAGE
Integration test/code cstatement overage
INTEGRATIONFUNCTIONCOVERAGE
Integration test/code function coverage
INTEGRATIONDECISIONCOVERAGE
Integration test/code decision coverage
SYSTEMBRANCHCOVERAGE
System test/code branch coverage
SYSTEMSTATEMENTCOVERAGE
System test/code statement coverage
SYSTEMFUNCTIONCOVERAGE
System test/code function coverage
SYSTEMDECISIONCOVERAGE
System test/code decision coverage
TOTALBRANCHCOVERAGE
Total test/code branch coverage
TOTALSTATEMENTCOVERAGE
Total test/code statement coverage
TOTALFUNCTIONCOVERAGE
Total test/code function coverage
TOTALDECISIONCOVERAGE
Total test/code decision coverage
LOC
Lines of code (physical)
ELOC
Effective lines of code (logical)
GLOC
Lines of code including generated code
AVGCYCLOMATICCOMPLEXITY
Mc Cabe's average cyclomatic complexity (per function)
MAXCYCLOMATICCOMPLEXITY
Mc Cabe's maximum cyclomatic complexity (for a function in a file)
CHANGERATE
The change rate (churn) in lines of code
ACCUCHANGERATE
The accumulative change rate (churn) in lines of code
LINESADDED
The number of lines added (inserted)
LINESDELETED
The number of lines deleted
LINESCHANGED
The number of lines changed (edited)
ACCULINESADDED
The accumulative number of lines added (inserted)
ACCULINESDELETED
The accumulative number of lines deleted
ACCULINESCHANGED
The accumulative number of lines changed (edited)
FANOUT
The number of other modules a module depends upon (averaged per file), separated by whether these modules are from outside the software system (external fanout) or from inside the software system (internal fanout). In the case there is no support yet for a language to detect the difference between the two types of files, it will report a single unseparated number.
DEADCODE
The number of unreachable (unbuildable) lines of code (relative to the total lines of code)
DUPLICATEDCODE
The number of duplicated lines of code (relative to the total lines of code) in a file
DUPLICATEDCODECUSTOM
A variant of the duplicated code metric for which a custom number of tokens can be specified through the MINIMUMTOKENCOUNT property
FIXRATE
The number of defects associated with a file.
ACCUFIXRATE
The accumulative number of defects associated with a file.

The 'METRICS' property can be specified at global and project level. When a specific metric is configured at both project level and global level, the project level configuration is used for that specific metric.

The 'ENABLED' subproperty indicates whether the specified metric is being computed by TICS.

Configuring Targets

The 'TARGETS' subproperty contains the target values for the metric. The 'KIND' subproperty specifies an absolute or relative target. The 'VALUE' property specifies the threshold for the metric in case the 'KIND' is 'ABSOLUTE'. A 'RELATIVE' target means that the metric value may not decrease with respect to the last known metric value. For each target a 'SCOPE' can be defined. This can be either a filename, a directory or a projectfile. All files that match the scope (i.e. it is located in the directory or is part of the projectfile) should meet the target. If no 'SCOPE' is specified for a target, it means that all files in the project should meet this target. If a file matches multiple scopes, then the first one is used. The 'AGGREGATED' subproperty can be set to 1 to specify that not all files in the scope should match the target, but that the total/aggregated value of all files in the scope should match the target. The default value of 'AGGREGATED' is 0.

Specifying a target for metric 'CODINGSTANDARD' is interpreted against the confidence factor.

The 'BLOCKINGTARGETS' subproperty is also used to formulate targets for the metric 'CODINGSTANDARD'. The 'VALUE' of a TARGET reflects the so-called blocking level, which defines a threshold for (new) violations. If a violation is found that violates the BLOCKINGTARGET, a message that indicates the violation is given. This message is shown in the violation overviews. The 'KIND' subproperty specifies an absolute or relative target. For each blocking target 'SCOPE' and 'LANGUAGE' can be defined to specify which files to match. 'SCOPE' matches in the same way as it does in the 'TARGETS' subproperty. 'LANGUAGE' is used to filter files by language before matching with 'SCOPE'. If no 'LANGUAGE' is specified, it means that files in any language, except in languages specified in other BLOCKINGTARGETS, should meet this blocking target.

The 'TARGETS' and 'BLOCKINGTARGETS' properties are used to formulate a so-called QA statement with regard to the metric. If a metric's value meets the specified target value, the measured metric value is said to be accepted by QA. Otherwise, the file or project is not accepted by QA.

Example
'METRICS' => {
  'UNITBRANCHCOVERAGE' => {
    'ENABLED' => 1,
    'TARGETS' => [
      {
        'KIND' => 'ABSOLUTE',
        'VALUE' => 80,
      },
    ],
  },
  'CODINGSTANDARD' => {
    'ENABLED' => 1,
    'TARGETS' => [
      {
        'KIND' => 'ABSOLUTE',
        'VALUE' => 70,
      },
      {
        'KIND' => 'ABSOLUTE',
        'VALUE' => 40,
        'SCOPE' => '/test/'
      },
      {
        'KIND' => 'ABSOLUTE',
        'VALUE' => 90,
        'SCOPE' => '@components/comp1/build/project.vcxproj'
      },
    ],
    'BLOCKINGTARGETS' => [
      {
        'KIND' => 'RELATIVE',
        'VALUE' => 3,
      },
      {
        'KIND' => 'ABSOLUTE',
        'VALUE' => 3,
        'SCOPE' => '^component1/'
        'LANGUAGE' => 'CPP',
      },
    ],
  },
  'CYCLOMATICCOMPLEXITY' => {
    'ENABLED' => 1,
  },
  'ELOC' => {
    'ENABLED' => 1,
  },
  'UNITFUNCTIONCOVERAGE' => {
    'ENABLED' => 0,
  },
  'LOC' => {
    'ENABLED' => 1,
  },
  'UNITSTATEMENTCOVERAGE' => {
    'ENABLED' => 1,
    'TARGETS' => [
      {
        'KIND' => 'ABSOLUTE',
        'VALUE' => 90,
      },
    ],
  },
},

Configuring Custom Code Duplication

The MINIMUMTOKENCOUNT property is used to configure a custom number of tokens to use for the DUPLICATEDCODECUSTOM metric. Lowering this value from the default will result in more duplications being found.

Example
'METRICS' => {
  'DUPLICATEDCODECUSTOM' => {
    'ENABLED' => 1,
    'MINIMUMTOKENCOUNT' => 50,
  },
},

METAINFO

Syntax

'METAINFO' => 0 | 1
This setting is optional; the default is 1.

Description

The METAINFO property can be used to disable meta-information usage. Meta-information is provided by code checkers through the file info.json and is used for various compatibility checks, performance improvements and other improvements.

In general, this option should always be enabled, but in case its usage causes unforeseen issues, this option disables it.

Context

The METAINFO property can be used in the following contexts:


MSBUILDINPLACE

Syntax

'MSBUILDINPLACE' => 0 | 1
This setting is optional; the default is 0.

Description

The MSBUILDINPLACE property can be used to enable performing the MSBuild command in the project directory instead of the temporary directory.

Please be aware that this option calls MSbuild command with the target "Rebuild" so that it will clean and then build the project and the referenced projects.

Context

The MSBUILDINPLACE property is used in the following contexts:


NOTIFICATIONS

Syntax

  'NOTIFICATIONS' => {
    ['TARGETS' => {
      ['TO' => 'Email To address',]
      ['CC' => 'Email Cc address',]
      ['BCC' => 'Email Bcc address',]
      ['NOTIFYUSERS' => 0 | 1,]
      ['TEMPLATE' => 'Template for the message body',]
      ['EMAILMAPPING' => 'Conversion string for mapping user names to email addresses',]
    },]
    'STATUS' => {
      'TO' => 'Email To address',
      ['CC' => 'Email Cc address',]
      ['BCC' => 'Email Bcc address',]
    },
    ['ERROR' => {
      'TO' => 'Email To address',
      ['CC' => 'Email Cc address',]
      ['BCC' => 'Email Bcc address',]
    },]
    ['SQAREPORT' => {
      'TO' => 'Email To address',
      ['CC' => 'Email Cc address',]
      ['BCC' => 'Email Bcc address',]
      ['TEMPLATE' => 'Template for the message body',]
    },]
    'TED' => {
      'TO' => 'Email To address',
      ['CC' => 'Email Cc address',]
    },
  },
This setting is mandatory. The STATUS and TED sub-properties have to be set.

Description

The NOTIFICATIONS section is used to configure the different notification e-mails TICS can send. These are:

ERROR
Messages in case fatal errors occurred during the TICS run.
SQAREPORT
SQA reports as generated at the end of each TICS run.
STATUS
Status summaries for each analyzed project.
TARGETS
Notifications in case target thresholds are exceeded.
TED
Aggregated data that is send to TIOBE for the purpose of the TICS Enterprise Dashboard (TED)

NOTIFICATIONS require the EMAIL properties to be correctly set.

ERROR

In the case of fatal runtime errors, TICS can send a notification, e.g., to the build manager, so corrective action may be taken. Error messages identify the project, branch (if known), TICS version, error message and other identifying data (if available).

Typically, you would also send a copy to the TED, i.e. ticsreports@tiobe.com.

SQAREPORT

When the SQAREPORT property is specified with one or more valid TO (and optionally CC and BCC) e-mail addresses, TICSQServer sends an SQA report in PDF format to the listed recipients once a month.

SQAREPORT requires the WEBSERVER properties to be correctly configured.

STATUS

In case of a successful analysis, TICS can send a summary mail for a project to the supplied e-mail addresses after each completed project. The e-mail contains a number of key characteristics of the project run, such as the number of new, changed and deleted files, the number of successfully analyzed files, the violation coverage per branch, the confidence factor per branch, the violations per level per branch and the lines of code per branch.

Typically, you would also send a copy to the TED, i.e. 'ticsreports@tiobe.com'.

TED

Since version 8.4, the viewer is by default configured to send an email to teddata@tiobe.com in addition to the one that is send to ticsreports@tiobe.com (see above). This allows us to phase out the current Java-based TED client and replace it by a new web-based solution that has the same look and feel as the viewer and shares a large part of the functionality, increasing the usability greatly.

The TED data mail contains more data than the STATUS mail. In particular, it contains more detailed and historical metric data. However, it is important to note that all data is aggregated at project level, meaning that we do not send out data that can be attributed to any particular file or directory. We also do NOT send out file names, directory names, user names, passwords, or any other confidential parts of the configuration. Naturally, we do NOT send out any source code! If you want to be reassured, you can (temporarily) add your email address to the CC field to receive a copy. The mail has an attached Zip, that solely consists of human-readable files, which you can inspect using any text editor.

If you do not agree with the data we send out you can remove the TO setting. Please notify us if you do so.

TARGETS

In case TARGETS are defined for METRICS, TICS can notify listed persons when a file target threshold is exceeded. Per TICSQServer run, these so called ALARM emails are sent to the persons who are described to it (i.e. the email addresses in the TO, CC and/or BCC properties).

When the NOTIFYUSERS property has been set to 1, TICS will retrieve the users responsible for the negative target result from the SCM Tool. These users will receive an ALARM mail containing an overview of all files for which the user is responsible and did not meet the target thresholds.

The 'EMAILMAPPING' property describes how a user name (as extracted from the SCM tool) should be converted for sending e-mail. For example, use 'EMAILMAPPING' => '%s' to simply use the retrieved name unmodified. For user 'john' this would try to send mail to e-mail address 'john'. When specifying 'EMAILMAPPING' => '%s@company.com', mail would be sent to 'john@company.com' for user 'john'.

TO CC BCC

The standard e-mail fields to specify recipients of the notification message. To specify multiple e-mail addresses, use a comma-separated list.

At least one e-mail address should be supplied when sending notification messages.

The 'ticsreports@tiobe.com' e-mail address is used to send status summaries to the so-called TICS Enterprise Dashboard (TED). This dashboard is accessible to customers and is valuable in monitoring multiple projects over time. It is therefore recommended to specify this address in the 'TO' or 'CC' properties.

TEMPLATE

The 'TEMPLATE' property for the TARGETS property can be used to provide a custom text in the body of the alarm email. The template may contain the variables $project and $branch which will be substituted with the corresponding values. For example, specify 'TEMPLATE' => 'alertemail.txt' and place the following contents in the file 'alertemail.txt' (to be placed in the TICS configuration directory -- typically on the file server):

One of your last commits for $project - $branch has caused a metric
target threshold to be exceeded. See the details below.

Please remove/resolve a.s.a.p.

Thanks,

The SQA manager

--------------------------------------------------------------------------

The SQAREPORT property also accepts a TEMPLATE. See the example below.

Dear TICS user,


Please find enclosed the TICS SQA report with the following characteristics.

Project: $project
Branch:  $viewname
Period:  $month $year


For questions or feedback, contact your local TICS administrator or tics@tiobe.com.


Regards,

The TICS deployment team

This template accepts parameters (identified by their leading '$') that are substituted upon message generation. See for example the $project, $viewname, and $month above.

Context

The NOTIFICATIONS property is used in the following contexts:

Example

  'NOTIFICATIONS' => {
    'ERROR' => {
      'TO' => 'buildmgr@company.com',
      'CC' => 'ticsreports@tiobe.com'
    },
    'SQAREPORT' => {
      'TO' => 'sqa@company.com'
    },
    'STATUS' => {
      'TO' => 'ticsreports@tiobe.com'
    },
    'TED' => {
      'TO' => 'teddata@tiobe.com'
    }
  },

ONLYBUILDRELATIONSFROMDB

Syntax

'ONLYBUILDRELATIONSFROMDB' => 0|1
This setting is optional; the default is 0.

Description

The ONLYBUILDRELATIONSFROMDB property can be used to disable searching the file system when a project file cannot be found in the database.

Context

The ONLYBUILDRELATIONSFROMDB property is used in the following contexts:

Example

'ONLYBUILDRELATIONSFROMDB' => 1

ORGANIZATION

Syntax

'ORGANIZATION' => 'organization name'
This setting is optional, but recommended.

Description

In the ORGANIZATION property the name of the organizational structure may be specified. For instance, you can use this field to specify a cluster, business unit, or department. It is possible to define nested organizations by using forward slashes ('/').

Context

The ORGANIZATION property is used in the following contexts:

Example

'ORGANIZATION' => 'Research & Development'

OWNER

Syntax

'OWNER' => 'customer name'

Description

In the mandatory OWNER property the name of the customer needs to be specified.

Context

The OWNER property is used in the following contexts:

Example

'OWNER' => 'TIOBE'

OWNERVERBOSE

Syntax

'OWNERVERBOSE' => 'long customer name'
This setting is optional.

Description

In the OWNERVERBOSE property the longer name of the customer can be specified.

Context

The OWNERVERBOSE property is used in the following contexts:

Example

'OWNERVERBOSE' => 'TIOBE Software B.V.'

POSTQDB

Syntax

'POSTQDB' => 'executable file or perl module'
This setting is optional.

Description

The executable file or perl module is started by TICSQServer after finishing the analysis of the projects. This property can be used for instance to run a post analysis after finishing the normal TICS analysis. The executable/perl module is called for each branch of each project. So if 2 projects with each 3 branches are available, the executable/perl module is called 6 times. In case of an executable file, it is invoked by TICS with 3 arguments. In case of a perl module, the function main is invoked with 3 arguments. These arguments are: the project name, the branch path, and the branch name. This information can be used to discriminate between projects and branches. The executable file or function main in case of a perl module should return 0 on successful completion and a non-zero number or string otherwise.

Context

The POSTQDB property is used in the following contexts:

Example

'POSTQDB' => 'post.bat'
or
'POSTQDB' => 'POSTQDB.pm'

PREPAREQDB

Syntax

'PREPAREQDB' => 'executable file or perl module'
This setting is optional.

Description

The executable file or perl module is started by TICSQServer before starting the analysis of the projects. This property can be used for instance to run a build process before starting the TICS analysis, or to set some necessary environment variables. The executable/perl module is called for each branch of each project. So if 2 projects with each 3 branches are available, the executable/perl module is called 6 times. In case of an executable file, it is invoked by TICS with 3 arguments. In case of a perl module, the function main is invoked with 3 arguments. These arguments are: the project name, the branch path, and the branch name. This information can be used to discriminate between projects and branches. The executable file or function main in case of a perl module should return 0 on successful completion and a non-zero number or string otherwise. In case the run of the executable/perl module was not successful for any branch within a project, no TICSQServer analysis is run for that project. Note that the 'AUTOUPDATE' property is executed before the PREPAREQDB executable/perl module is run.

Context

The PREPAREQDB property is used in the following contexts:

Example

'PREPAREQDB' => 'build.bat'
or
'PREPAREQDB' => 'PREPAREQDB.pm'

PYTHONVERSION

Syntax

'PYTHONVERSION' => 'Python version'
This setting is optional.

Description

To support different versions of python, 'PYTHONVERSION' is introduced since Python 2 and 3 are not compatible.

Context

The PYTHONVERSION property is used in the following context:

Example

'PYTHONVERSION' => '2.7'
or
'PYTHONVERSION' => '3.6'

SCHEDULE

Syntax

'SCHEDULE' => {
  ['LOGDIR' => 'directory for logging files',]
  ['NROFBACKUPS' => number,]
}
This setting is optional.

Description

The SCHEDULE section allows setting certain properties that are convenient when running TICSQServer as a scheduled job.

If LOGDIR is specified, the output of each TICS executable is logged to its own log file in the LOGDIR specified directory.

Each invocation of each TICS tool gets its own log file of the form <project name>-<tool name>_<yyyy-mm-dd>_<HH-MM-SS>.log. E.g., MyProject-TICSQServer_2005-09-06_16-25-11.log.

If NROFBACKUPS is set, the specified number of backups is used to remove any excess log files in the LOGDIR directory.

Example

'SCHEDULE' => {
  'LOGDIR' => 'C:/Program Files/TIOBE/TICS/log',
  'NROFBACKUPS' => 3,
}

SCMTOOL

Syntax

'SCMTOOL' => {
  'NAME' => 'CVS | ClearCase | Git | Perforce | RTC | Subversion | Synergy | TFVC',
  ['AUTOUPDATE' => 0 | 1,]
  ['CVSMODULES' => [ ['CVS module',]+ ],]
  ['DB' => 'SCM database name',]
  ['HOSTNAME' => 'SCM hostname',]
  ['PASSWORD:PLAIN' => 'SCM db password',]
  ['PREPARE' => 'script to run before SCM start. Script gets project name as argument',]
  ['SHOWSCMID' => 0 | 1,]
  ['SNAPSHOT' => 0 | 1,]
  ['TEMPDIR' => 'SCM temporary directory',]
  ['UCM' => 0 | 1,]
  ['USECHANGEDFILES' => 0 | 1,]
  ['USERNAME' => 'SCM username',]
  ['USESUBST' => 0 | 1,]
  ['VERSION' => 'version',]
  ['XARGS' => [ ['additional SCM argument',]+ ],]
}
This setting is optional.

Description

The SCMTOOL property determines the Software Configuration Management system that is being used to control the customer's source repository. The following systems are supported:

If none of the above is applicable, the property should be omitted. TICS will proceed without software configuration management support. For TICS client runs to work with -project the path to the sources must be the same for the client and the server.

'USECHANGEDFILES' determines whether the SCM tool's "changed files" feature is used to determine the set of files that has changed between the previous TICSQServer run and the current run. By default, this feature is used if supported by the SCM tool. Currently, this is supported for Git, Perforce, RTC and Subversion. This means that the SCM tool is queried for the set of files that has changed since the last run. This is usually more efficient than doing a compare of the archive as checked out on the file system and the data stored in the quality database. The latter method is costly since the file system must be traversed and data on each file must be gathered individually. However, there may be cases where the "changed files" feature does not work. For example, in the case of Subversion, if a work area consists of check-outs from distinct locations in the repository, the "changed files" mechanism does not work. In that case, set 'USECHANGEDFILES' => 0.

'AUTOUPDATE' indicates whether TICSQServer should automatically update the archive with the latest available versions from the SCM tool. Depending on the SCM tool used, this is also referred to as rebasing, reconfiguring or synchronizing.

'DB' specifies the name of the SCM repository associated with this project. TICS uses this value to resolve the name of the current project for clients that use the project 'auto' setting.

The 'SHOWSCMID' property is used to determine whether the SCM identifiers should be shown by TICS when running the TICS client. There are cases, such as when computing a delta metric, where TICS will show the identifier of the version of the file that was last analyzed by TICS. In contexts where this is not meaningful, these messages can be suppressed by setting 'SHOWSCMID' to 0.

The 'SNAPSHOT' and 'UCM' are used in the case of ClearCase to indicate whether one has a dynamic or a snapshot view and whether UCM is used.

Set 'USESUBST' in cases where the Synergy workarea path is set to a subst drive, e.g., I:/... => C:/ccm_wa/project. If 'DOSUBST' is set, for each path that is passed to a Synergy ccm system call, the subst drive (if it was removed by TICS) is restored. This property must be used, since Synergy does not return the correct file version number in case an incorrect workarea path is used (i.e., any path name that differs from Synergy's workarea administration).

The 'VERSION' property is used for Synergy to specify which version of Synergy to use (useful if multiple versions are used and/or installed on a system). Example values of version: 6.4, 6.3, 6.2, 5.1 CS.

All other 'SCMTOOL' properties are currently CMSynergy specific. 'HOSTNAME' specifies the server on which the SCM repository runs. The 'HOSTNAME' property implicitly adds CMSynergy option '-rc'. 'PASSWORD:PLAIN' allows one to specify a password directly in the SERVER.txt file. 'TEMPDIR' specifies the temporary directory to be used by the SCM tool. 'USERNAME' allows one to log into the SCM tool with a certain login name. 'XARGS' allows one to specify additional (unforeseen) arguments to the SCM tool.

Context

The SCMTOOL property is used in the following contexts:

Example

'SCMTOOL' => { 'NAME' => 'Subversion' }

SITE

Syntax

'SITE' => 'site name'
This setting is optional, but recommended.

Description

In the 'SITE' property, the name of the site may be specified.

Context

The 'SITE' property is used in the following contexts:

Example

'SITE' => 'Eindhoven'

SUPPRESSMACROEXPANSIONVIOLATIONS

Syntax

'SUPPRESSMACROEXPANSIONVIOLATIONS' => [['ruleid',]...]
This setting is optional.

Description

The 'SUPPRESSMACROEXPANSIONVIOLATIONS' property may be populated with rule IDs to suppress all violations of those rules on C/C++ source lines that contain macro expansions.

By default, this property is disabled. When enabled, all violations on the specified rules reported by TICSc and C++test on source lines that contain macro expansions are suppressed. Use this as a blanket approach to macro suppression. (Compare this to the DEFINES approach that offers finer control.)

Context

The 'SUPPRESSMACROEXPANSIONVIOLATIONS' property is used in the following contexts:

Example

'SUPPRESSMACROEXPANSIONVIOLATIONS' => ['6.7.a', '6.8.3.b']

TOOLS

Syntax

'TOOLS' => {
  ['bandit' => BANDIT,]
  ['Coverity' => COVERITY,]
  ['eslint' => ESLINT,]
  ['flake8' => FLAKE8,]
  ['Javac' => JAVAC,]
  ['luacheck' => LUACHECK,]
  ['luac' => LUAC,]
  ['pylint' => PYLINT,]
  ['Qac' => QAC,]
  ['ReSharper' => ReSharper,]
  ['Roslyn' => ROSLYN,]
  ['ScanBuild' => SCANBUILD,]
  ['Simulink' => SIMULINK,]
}

Description

Some tools require additional configuration. This can be added to a tool-specific subsection of the TOOLS section.

Context

The tool-specific configuration is used whenever the specified tool is used. (Currently, the tools mentioned are for the metrics Abstract Interpretation, Compiler Warnings and Coding Standards).

Example

See the tool-specific sections for examples.


TQIVERSION

Syntax

'TQIVERSION' => 'version'

This setting is optional. The default TQI version is TICS version specific.

Description

TICS controls which TQI version should be used by the viewer to compute the TQI. Each time an analysis is performed, TICS puts the TQI version that should be used for that analysis in the database.

The TQIVERSION setting was introduced to control which TQI version is put in the database each time a new analysis is performed. The setting was introduced in TICS 9.0, which is the first version to support the Security base metric, as used by the TQI 4.0 definition. In the standard configuration, TICS is capable of measuring the Security metric, but this is not part of the TQI yet. If you want to configure the Security metric, you can use this setting to see Security in your TQI score by setting the value to 4.0.

This setting can be applied on global or project level. Admissable values are 3.11 and 4.0.

Context

The 'TQIVERSION' is used by TICS and stored with the run in the database. The viewer uses this value to determine which TQI formulas to use when computing the (aggregated) TQI values.

Example

'TQIVERSION' => '4.0'

WEBSERVER

Syntax

'WEBSERVER' => {
  'MERGEKEY' => 'unique name to use when synchronizing files (optional)'
  'PORTALURL' => 'URL of the TICS viewer, including section',
  'SHOWANNOTATEDSOURCES' => 0 or 1,
  'TICSENV' => location of the TICS configuration on the build server (automatic),
  'TIMEOUT' => maximal time in seconds to wait for web server responses (optional; default=120),
},

Description

The mandatory 'WEBSERVER' section specifies the location of the TICS viewer and associated properties. The viewer is contacted to synchronize added or removed projects, to upload files for annotated source viewing, and for creating and sending SQA reports. In effect, TICSQServer cannot function properly without a well-configured viewer.

The 'PORTALURL' and 'SHOWANNOTATEDSOURCES' properties are mandatory. Other properties are optional, some of which have default values as described below.

Example

'WEBSERVER' => {
  'PORTALURL' => 'http://www.company.com:42506/tiobeweb/TICS',
  'SHOWANNOTATEDSOURCES' => 1,
}

PORTALURL (mandatory)

This property is mandatory and lets the TICS tools know where the TICS Viewer is hosted. It should point to the public URL on which the viewer can be reached, including the section name, e.g.: 'PORTALURL' => 'http://www.company.com:42506/tiobeweb/TICS'. It is used in the following contexts:


SHOWANNOTATEDSOURCES (mandatory)

Enable or disable showing annotated source code in the web viewer. This option is mandatory. TICSQServer will stop if this option is not configured. When enabled, TICSQServer will upload any source files to the web server (The address configured in PORTALURL is used). By disabling this option in the SERVER.txt, any files present on the web server will be removed by the next TICSQServer run.


TIMEOUT (optional; default = 120)

Set the maximum time in seconds that TICSQServer or TICSMaintenance wait for a response from the web server (during file synchronization or SQA report generation).

When configuring TICS and testing the installation it is best to leave this value set to a reasonable amount of time to give the web server the chance to give a proper response (i.e., when testing the web server connection).

However, when the connection has been established to be functional, it is possible to reduce the timeout value considerably, since most of the time, the response of the web server is not very interesting. It is just performing some task in the background. Especially, when generating SQA reports (which may take a lot of time) it is useless to wait for the completion of this task. In that case, one can even set the timeout value as low as 1 second ('TIMEOUT' => 1). This results in TICSQServer not waiting on the completion of the SQA report generation for each branche and therefore being able to process more branches/projects in less time. Note, however, that this places additional load on the web/database servers, since now multiple SQA report generations will be running simultaneously. (Especially, the database server will be processing expensive queries in parallel.) So, check whether the database server can handle the additional load before permanently lowering the TIMEOUT value.


MERGEKEY (optional)

Property to be used in 'hybrid' environments where multiple build servers are used. In this advanced situation, each build server has its own copy of PROJECTS.txt and SERVER.txt, but there is only one viewer instance. Without this property, only one set of projects will be visible in the viewer at a time, namely those of the build server whose configuration files were synchronized last. To prevent overwriting the configuration files, set the MERGEKEY property in each SERVER.txt to a unique name. For example, if you have a Windows and Linux build machine, use MERGEKEY => 'Windows' in the first SERVER.txt and MERGEKEY => 'Linux' in the second.

Limitations:


Appendix

Passwords

Some sections may require authentication, like the database connection settings or the LDAP service configuration. These passwords need to be stored in the SERVER.txt (or PROJECTS.txt for project overrides). However passwords should never be stored in plain text.

The mechanism used to encrypt passwords in the SERVER.txt is as follows. The plaintext password is saved in the SERVER.txt using the "PASSWORD:PLAIN" key. Running TICS will encrypt the value and rename the key to "PASSWORD".

Example
'DATABASE' => {
  'USERNAME' => 'john',
  'PASSWORD:PLAIN' => 'somePassword',
}

After running TICSQServer or TICSMaintenance -checkconfig:

'DATABASE' => {
  'USERNAME' => 'john',
  'PASSWORD' => 'L3CS5I21DOGANR26lOZ5JQ==',
}

Using plain text passwords in the SERVER.txt will lead to errors when an attempt is made by TICS to use the password. So all passwords in the SERVER.txt must be encrypted when used.