TICS Administration Guide

SERVER.yaml Reference Guide

The principal TICS configuration is stored in the SERVER.yaml file. It contains global configuration options that hold for all projects. Project-specific configuration overrides can be found in the PROJECTS.yaml file.

The SERVER.yaml file is an essential part of any TICS configuration. For an overview of other files found in the configuration, see here.

Syntax of SERVER.yaml

The SERVER.yaml file uses YAML syntax. A YAML file contains a hierarchical map of key-value properties. Keys are strings. A value can be a number, string, list or map. Keys-value pairs are separated by :, and terminated by a newline. Some examples:

Numerical property:
```
NROFBACKUPS: 20
```
String property, can optionally surrounded by quotes:
```
OWNER: TIOBE
ORGANIZATION: 'Development'
```

List property:

EXTENSIONS:
  - pl
  - pm

Or in an abbreviated form:

EXTENSIONS: ['pl', 'pm']

Map:
```
SCMTOOL:
  NAME: Custom
```

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

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.yaml.

ALLOWCOMMENTSUPPRESSIONS optional default = 1

ARCHIVEGEN optional

AUTHENTICATION optional

BUGTRACKER optional

BUILDRELATIONSEARCHDEPTH optional

BUILDTOOLS optional

COMPILERS optional

CONFIGURATION optional

DATABASE optional

DOSUBST optional default = 1

EMAIL mandatory

FILEFILTERS optional

FOLLOWLINKS optional default = 1

INCLUDERELATIONCONTINUEOUTSIDEARCHIVE optional default = 0

LANGUAGES mandatory

LDAP optional

LICDIR optional

MAILTO optional default='mailto:tics@tiobe.com'

METRICS optional

METAINFO optional default = 1

MSBUILDINPLACE optional default = 0

NOTIFICATIONS mandatory

ONLYBUILDRELATIONSFROMDB optional default = 0

ORGANIZATION optional recommended

OWNER mandatory

OWNERVERBOSE optional default = ''

POSTQDB optional

PREPARECLIENT optional

PREPAREQDB optional

PYTHONVERSION optional

RECALC optional

LOG optional

SCMTOOL optional

SITE optional recommended

SOAKTIME optional

SUPPRESSMACROEXPANSIONVIOLATIONS optional default = []

TOOLS optional

WEBSERVER mandatory

Notation

For all the examples below, the following rules apply:

User specific data is printed in italic.
Optional properties are enclosed in brackets:
[PROPERTY: ...]
Zero or more occurrences of properties' values are enclosed in brackets followed by a plus:
[PROPERTY: []+...]
It is possible to use comments in the SERVER.yaml file. These are denoted by a leading '#'. However, adding comments is not very useful as they are not preserved when the file is changed programmatically.

Example of SERVER.yaml

The non-realistic example below is a showcase of many of the possibilities in the SERVER.yaml. 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'
  NROFBACKUPS: 20

LOG:
  DIR: C:/TICS/logs
  MAXBACKUPS: 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: http://www.company.com:42506/TIOBEPortal
  SHOWANNOTATEDSOURCES: 1

POSTQDB: postana.bat
PREPARECLIENT: client.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:

After running the static analysis tools during the filtering stage.

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:

To determine the project file for source files during the TICS client run.

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.

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:

To find the compiler options for a source file, TICS uses the compiler executable name to find these options, in makefile-like build files.
TICS uses the compiler to preprocess source files.

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:

Compiler Warning analysis (-calc COMPILERWARNING).

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.yaml 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.yaml
[...]
|-- 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_TIMEOUT: maximum time a backup may take (in minutes) ]
  [ DB_BIN: full path to the database executable in case not in default path]
  [ DB_MIGRATE_TIMEOUT: maximum time a database migration may take (in minutes) ]
  [ ENCODING: the database connection encoding to use ]
  [ NROFBACKUPS: number of backups maintained ]
  [ PORT: port number of the database server ]
  [ QUERYFAILURERETRYATTEMPTS: number of times a query is retried after a connection failure (default is 10) ]
  [ QUERYFAILURERETRYTIMEOUT: waiting time after a connection 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.

Database backups will be placed on the webserver in the directory <section root>/backups/qdb (see Configuring Sections for configuring the 'section root').

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

DBPATH: The directory containing the Firebird database files. Use DBPATH: <default> to inherit the value set in the Administration Pages → System.

SERVER: The domain name or IP address of the server that hosts the database. Use SERVER: <default> to inherit the value set in the Administration Pages → System.

DB_BACKUP_TIMEOUT: Maximum time a backup may take in minutes. Default is 120 minutes / 2 hours. When the timeout is reached, TICS will continue with the next action, but will not abort the backup.

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

DB_MIGRATE_TIMEOUT: Maximum time a database migration may take in minutes. Default is 120 minutes / 2 hours. When the timeout is reached, TICS will continue with the next action, but will not abort the migration.

ENCODING: The character encoding to use for the database connection. Should be one of UTF8, ISO8859_1, ASCII, GB_2312, BIG_5. It is recommended to omit this setting or use ENCODING: <default> to inherit the value set in the Administration Pages → System. Only use this setting if you want to override the encoding for one or more projects.

NROFBACKUPS: The number of backups to keep per project (default is 20).

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 it is not possible to execute a query on the database, when for example the connection to the database is lost. By default, 10 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. Retries are only done in the case of connection issues.

Context

The DATABASE property is used in the following contexts:

Database connection for TICSQServer.
Database connection for TICS viewer.
Database connection for TICS client when running with the -project option.

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:

All places in the TICS executables where the canonical path of a file is calculated. This includes at least all database transactions and SCM tool interactions.

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 is mandatory when Smtp method of sending e-mails is used.

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:

TICSQServer status reports.
TICSQServer error reports.
TICSQServer alarms (when target thresholds are exceeded).
TED communication.
Viewer SQA reports.

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.

FILEFILTERS

Syntax

FILEFILTERS:
  [ ARCHIVE: 'ARCHIVE' ]
  [ CONTENT: [
  [
      [ ARCHIVE: 'ARCHIVE' ]
      [ CODETYPE: 'CODETYPE' ]
      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.

Additionally, you can also add the CODETYPE parameter to a CONTENT file filter. This will make it so that the content check will result in a given code type being set rather than a file being included or excluded from analysis. See the page on code types for more information.

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.

FOLLOWLINKS

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:

All places in the TICS executables where the canonical path of a file is calculated. This includes at least all database transactions and SCM tool interactions.

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:

During include relation calculation (TICSQServer -calc INCLUDERELATIONS).

Example

INCLUDERELATIONCONTINUEOUTSIDEARCHIVE: 1

LANGUAGES

Syntax

LANGUAGES:
[ language:
    EXTENSIONS: [ [ 'extensions of source files' ]+ ]
    [ INCEXTENSIONS: [ [ 'extensions of header/include files']+ ]]
    [ 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.

Header/include files are associated with a language via their file extensions. This is configured via the INCEXTENSIONS property. For example, you may want to configure the C language to use both .h and .hh extensions to be treated as header files for the C language.

Note that this is a property that can be different per language. For instance, you may want to configure for .hpp files that they are only taken into account for C++. To give an example where both source and header files are configured by extensions:

LANGUAGES:
  C:
    EXTENSIONS:
    - c
    INCEXTENSIONS:
    - h
    - hh
  CPP:
    EXTENSIONS:
    - cpp
    INCEXTENSIONS:
    - h
    - hh
    - hpp

If no INCEXTENSIONS property is configured for languages, the following defaults are used for C, C++ and ObjC:

C: .h files
C++: .h, .hpp files
ObjC: .h 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: TICSpp, TICSsql, 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, 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.yaml 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.

Configuring Generated Code Regions

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.

To give an easy example, let's consider the following C file with some C (pseudo)code:

void some_handwritten_function(void)
{
  ...
}

// Start of generated section
void some_generated_function(void)
{
  ...
}
// End of generated section

We want to include the function some_handwritten_function, but exclude the function some_generated_function. Then, we configure the following start and end markers, and add GENERATED:1 to signify that this region should be detected as generated:

LANGUAGES:
  C:
    GENERATED:
    - OPEN: Start of generated section
      CLOSE: End of generated section
      GENERATED: 1

Now, let's assume we have the opposite situation, which takes some more effort to configure. We have a file that is completely generated, apart from a small part with user additions. Let's first consider the pseudocode of this file:

// FILE WAS GENERATED BY YOUR_FILE_GENERATOR
void first_generated_function(void)
{
  ...
}

// Start of user section
void user_function(void)
{
  ...
}
// End of user section

void second_generated_function(void)
{
  ...
}

We now first want to detect that by default this entire file should be marked as generated. So we look at the first line and a clear remark is found that can serve as an opening marker. To ensure it still ends at the end of the file, we use the \Z special regular expression character.

Next up, we now need to detect the non-generated section instead. So, we set the Start/End of user sections as open-close markers, and set the GENERATED property to 0 to mark that this section should not be considered generated.

LANGUAGES:
  C:
    GENERATED:
    - OPEN: FILE WAS GENERATED BY
      CLOSE: \Z
      GENERATED: 1
    - OPEN: Start of user section
      CLOSE: End of user section
      GENERATED: 0

See the default SERVER.yaml file that is included in the TICS installation for further examples of how GENERATED is used in various configurations.

Context

The LANGUAGES property is used in the following contexts:

All source file/programming/coding standard language related contexts.
All violation analysis/metrics calculation/test coverage data collection related 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:

TICSQServer alarms (when target thresholds are exceeded).

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=USERSOU=aserverOU=CODEDC=LDAPDC=TIOBEDC=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: protocol specifier, e.g., MAILTO: 'tics@tiobe.com'.

Context

The MAILTO property is used in the following contexts:

To display the support address in -version information of TICS and TICSQServer.

Example

MAILTO: 'mailto:support@company.com'

METRICALIASES

Syntax

METRICALIASES:
  FAST:
  - metric names

Description

It is possible to configure a set of metrics to run via the FAST option. This can contain any metric that is supported by the TICS Client, and is meant to contain a set of metrics for a fast check with the TICS Client. Note that the TICS Client will still run them in its default ordering, so that is not changed.

Example:

METRICALIASES:
  FAST:
  - CODINGSTANDARD
  - COMPILERWARNING
  - FANOUT

Note that by default the FAST metric will contain a large set of metrics. In the case that some of these metrics are not fast to run for your setup, then it is possible to disable these for FAST by adding a list for FAST to the configuration that does not contain these metrics.

The default metrics for FAST are:

LOC
CODINGSTANDARD
COMPILERWARNING
AVGCYCLOMATICCOMPLEXITY
MAXCYCLOMATICCOMPLEXITY
FANOUT

METRICS

Syntax

METRICS:
  [ metric name:
    ENABLED: 0 | 1
    [ MINIMUMTOKENCOUNT: 50]
    [ SPLITCODETYPES:
        EXTERNAL: 0 | 1
        GENERATED: 0 | 1
        TESTCODE: 0 | 1
    ]
    [ 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
COMPILERWARNING: 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. These targets are specified as follows:

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 any violation metric (these are CODINGSTANDARD, COMPILERWARNING, ABSTRACTINTERPRETATION, SECURITY) is interpreted against the confidence factor.

Example configuring a TARGET for a single metric

METRICS:
  UNITBRANCHCOVERAGE:
    ENABLED: 1
    TARGETS:
    - KIND: ABSOLUTE
      VALUE: 80

Configuring Blocking Targets

The BLOCKINGTARGETS subproperty is also used to formulate targets for violation metrics.

The VALUE of a BLOCKINGTARGETS reflects the so-called blocking level, which defines a threshold for (new) violations. If a violation is found that violates the BLOCKINGTARGETS, a message that indicates the violation is given. This message is shown in the violation overviews. So, if you set the VALUE property to 3, then all violations on the levels 1, 2, and 3 will be considered BLOCKING.
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 configuring a `BLOCKINGTARGETS` for a single metric

METRICS:
  CODINGSTANDARD:
    ENABLED: 1
    BLOCKINGTARGETS:
    - KIND: RELATIVE
      VALUE: 3
    - KIND: ABSOLUTE
      VALUE: 3
      SCOPE: ^component1/
      LANGUAGE: CPP

Example for all metrics (with various TARGETS and BLOCKINGTARGETS)

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

Configuring Code Type Splits in Code Duplication

The SPLITCODETYPES property is used to configure whether duplicated code analysis should take duplications between different code types into account. It can be unwanted to check for duplications across these borders, since this tends to cross responsibilities in the source code. By default, the splits on code type are enabled, so TICS does not check for duplication between different types.

The following splits are possible:

production and test code (TESTCODE)
internal and external code (EXTERNAL)
handwritten and generated code (GENERATED)

See this page for more detailed information on code types.

Example

METRICS:
  DUPLICATEDCODE:
    ENABLED: 1
    SPLITCODETYPES:
      TESTCODE: 1
      GENERATED: 0
      EXTERNAL: 0

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:

TICS reports incompatibilities that are incorrect
A checker no longer works correctly after upgrading

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:

The MSBuild command fails in the temporary directory. The possible causes of failing are:
- The dependency to the referenced projects and the external resources is not configured properly
- The project has not been built for the given target configuration or for any configuration.

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:

TICSQServer status reports.
TICSQServer error reports.
TICSQServer alarms (when target thresholds are exceeded).
TED communication.
Viewer SQA reports.

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:

To determine the project file for source files during the TICS client run.

Example

ONLYBUILDRELATIONSFROMDB: 1

ORGANIZATION

Syntax

ORGANIZATION: organization name

This setting is optional, but recommended. Use ORGANIZATION: <default> to inherit the value set in the Administration Pages → Preferences.

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:

To display the organization name in status notification mails of TICSQServer.
The Organization filter becomes available in the breadcrumb in the viewer when more than one organization is defined.

Example

ORGANIZATION: Research & Development

OWNER

Syntax

OWNER: customer name

Description

In the mandatory OWNER property the name of the customer needs to be specified. Use OWNER: <default> to inherit the value set in the Administration Pages → Preferences.

Context

The OWNER property is used in the following contexts:

To display the customer's name in -version information of TICS and TICSQServer.
To display the customer's name in Visual Studio 6 and .NET help information dialogs.
To display the customer's name in the web based TICS viewer.
The Owner filter becomes available in the breadcrumb in the viewer when more than one owner is defined.

Example

OWNER: TIOBE

OWNERVERBOSE

Syntax

OWNERVERBOSE: long customer name

This setting is optional. Use OWNERVERBOSE: <default> to inherit the value set in the Administration Pages → Preferences.

Description

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

Context

The OWNERVERBOSE property is used in the following contexts:

For the generation of the SQA report title page (by the viewer).

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:

In case some actions need to be performed after finishing the actual TICS database process. This could be for instance generating custom reports.

Example

POSTQDB: post.bat

POSTQDB: POSTQDB.pm

PREPARECLIENT

Syntax

PREPARECLIENT: executable file or perl module

This setting is optional.

Description

The executable file or perl module is started by the TICS Client before starting file analysis. This property can be used in the case that it is necessary to set up the TICS Client analysis, for instance to run test coverage of the files that are being analyzed. The executable/perl module is called for each project that is being analyzed as a part of this set (so in the case of multiproject analysis, it may invoke multiple scripts). 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 PREPARECLIENT property is used in the following contexts:

In case some actions need to be performed by the TICS Client before starting analysis. For example, if it is necessary to generate code coverage before running the code coverage analysis in TICS.

Example

PREPARECLIENT: run_code_coverage.bat

PREPARECLIENT: PREPARECLIENT.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:

In case some actions need to be performed before starting the actual TICS database process. This could be for instance running a build or setting some environment variables.

Example

PREPAREQDB: build.bat

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:

To run Coding Standard and Compiler Warning for Python

Example

PYTHONVERSION: 2.7

PYTHONVERSION: 3.6

RECALC

Syntax

RECALC:
  [DEFINES: 1|0]

This setting is optional. By default, this option is 1.

Description

TICSQServer is able to automatically detect several conditions which may change analysis results. One of those is the contents of the DEFINES.txt. file, which contains a list of macros and a list of rules for which this macro should not be checked. Each change in this file could affect TICS results, however to trigger on each change may lead to a lot of recalculations being triggered, which may be unwanted.

Context

The RECALC: DEFINES property is used in the following context:

When determining the necessity to recalculate a violation metric from the DEFINES.txt file.

Example

RECALC:
  DEFINES: 1

RECALC:
  DEFINES: 0

LOG

Syntax

The following optional setting can be configured on a global level in the SERVER.yaml to apply them for all projects or in PROJECTS.yaml to a specific project. If the property is configured in SERVER.yaml and also in PROJECTS.yaml, the project specific property will overwrite the global one.

LOG:
  [ DIR: location for logging files ]
  [ MAXBACKUPS: max number of logs to keep in the DIR ]

Description

The LOG section allows setting certain properties that are convenient when running TICS.

If DIR is specified, the output of each TICS executable is logged to its own log file in the DIR 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 MAXBACKUPS is set, the specified number of backups is used to remove any excess log files in the LOG->DIR directory.

Example

The LOG setting can be configured in SERVER.yaml as:

LOG:
  DIR: C:/Program Files/TIOBE/TICS/log
  MAXBACKUPS: 3

And in PROJECTS.yaml

projectName:
  LOG:
    DIR: C:/Program Files/TIOBE/TICS/log2
    MAXBACKUPS: 3
  VIEWS:
    branchName: {}

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 ]
  [ 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:

CVS
ClearCase
Git
Perforce
RTC
Subversion
Synergy
TFVC

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.

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.yaml 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:

All translations from a file on the file system (workarea) to a file in the quality database (and vice versa).

Example

SCMTOOL:
  NAME: Subversion

SITE

Syntax

SITE: site name

This setting is optional, but recommended. Use SITE: <default> to inherit the value set in the Administration Pages → Preferences.

Description

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

Context

The SITE property is used in the following contexts:

To display the site name in status notification mails of TICSQServer.
The Site filter becomes available in the breadcrumb in the viewer when more than one site is defined.

Example

SITE: Eindhoven

SOAKTIME

Syntax

SOAKTIME: natural number

This setting is optional. By default this property is disabled. SOAKTIME is given in days.

Description

SOAKTIME allows new rules being added at blocking levels without immediately becoming blocking. This allows for a grace period in which the organization can get familiar with the new rule and fix any issues. When the soak time has expired (the configured number of days since the rule's introduction have passed), any new violations of that rule become blocking issues.

If SOAKTIME is not set or set to zero (0), SOAKTIME is disabled and any new rules at blocking levels lead to blocking violations immediately.

It is an error to set SOAKTIME to a negative value, to a floating point value, or to a non-numeric value.

Context

The SOAKTIME property is used in the following contexts:

When running TICS client or TICSQServer in case BLOCKINGTARGETS are configured and new rules are added at a blocking level.

Note that TICS client may report BLOCKING AFTER TBD in case TICSQServer has not yet run after rule configuration changes.

Example Output

With soak time expiration date

/sw/components/java/Deimos/src/deimos/config/Config.java(855):
    [***BLOCKING AFTER 2021-05-12***] Don't modify control variables within a for block.
    Java Coding Standard item Basic103 (Category: Basic, Level: 2)
    Dont modify control variables within a for block.

 Basic103               |     2 |     1 |    +1 | BLOCKING AFTER 2021-05-12 | Don't modify control variables within a for block.

     2 |     1 |    +1 | BLOCKING AFTER 2021-05-12

*** NOTE the following BLOCKING AFTER issues (SOAKTIME) ***
*** Reason: Coding Standard Violations of file 'Config.java' on BLOCKING AFTER SOAKTIME levels: 1 at level 2 ***
*** Reason: Coding Standard Violations of file 'ConfigUtil.java' on BLOCKING AFTER SOAKTIME levels: 1 at level 2, 1 at level 3 ***

With soak time expiration date To Be Determined

    [***NEW BLOCKING AFTER TBD***] Don't modify control variables within a for block.

 Basic103           |     2 |     1 |    +1 | BLOCKING AFTER TBD        | Don't modify control variables within a for block.

     2 |     1 |    +1 | BLOCKING AFTER TBD

Example Configuration

SOAKTIME: 100

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:

When suppressing violations for TICSc and C++test on lines that contain macro expansions (C/C++ code).

Example

SUPPRESSMACROEXPANSIONVIOLATIONS: ['6.7.a', '6.8.3.b']

TOOLS

Syntax

TOOLS:
  [bandit: BANDIT]
  [BlackDuck: BLACKDUCK]
  [Coverity: COVERITY]
  [eslint: ESLINT]
  [flake8: FLAKE8]
  [Javac: JAVAC]
  [luacheck: LUACHECK]
  [luac: LUAC]
  [pylint: PYLINT]
  [Qac: QAC]
  [ReSharper: ReSharper]
  [Roslyn: ROSLYN]

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.

WEBSERVER

Syntax

WEBSERVER:
  CLIENTVIEWER: indicates whether all TICS clients should upload results to the webserver for the purpose of the client viewer functionality (optional boolean; default=0).
  MERGEKEY: unique name to use when synchronizing files (optional)
  POLLTIMEOUT: time in seconds after which TICS should switch to a polling strategy for the job result (optional; default=30)
  PORTALURL: URL of the TICS viewer including section
  SHOWANNOTATEDSOURCES: 0 or 1
  SHOWEXTERNALSOURCES: 0 or 1 (optional; default=0)
  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)
  HEARTBEAT: 
    INTERVAL: time in seconds between heartbeats sent by TICS to the viewer (optional; default=60)
    TIMEOUT: time in seconds to wait without receiving a heartbeat from TICS before closing (detaching) the associated run (optional; default=180)

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, SHOWANNOTATEDSOURCES properties are mandatory. Other properties are optional. An authentication token can be obtained through the Administration Pages → Authentication Tokens panel.

Example

WEBSERVER:
  PORTALURL: http://www.company.com:42506/tiobeweb/TICS
  SHOWANNOTATEDSOURCES: 1

POLLTIMEOUT (optional)

This property is optional, and has a default of 30 seconds. By setting this property, you can set the maximum time that TICS keeps a request to the webserver alive. After this poll timeout is reached, TICS will instead make a new request to check for the results.

To avoid encountering gateway timeouts for requests that can take a long time, TICS waits a number of seconds configured in POLLTIMEOUT for a request to finish. After that, TICS switches to a long polling strategy. This entails that after the number of seconds configured in POLLTIMEOUT a new request is made to check whether the job at the webserver has completed.

As such, if you are using a proxy gateway with a low timeout, make certain that this property is below the timeout of your gateway. Otherwise, TICS requests may fail unexpectedly with an [ERROR 5404].

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. Use PORTALURL: <default> to inherit the value set in the Administration Pages → System. It is used in the following contexts:

Running TICSQServer or TICSMaintenance while synchronizing projects or files.
Running TICSQServer or TICSMaintenance for SQA report generation.
Running TICS or TICSQServer with option -version will display the location of the user documentation on the webserver.
The global viewer uses it to link to the local viewer containing the project.

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. By disabling this option in the SERVER.yaml, any files present on the web server will be removed by the next TICSQServer run.

SHOWEXTERNALSOURCES (optional; default = 0)

Enable or disable showing source files labeled as External Code in the TICS viewer (see Code Types for a further explanation of the different code types supported by TICS). This configuration option has a default of 0 and is optional. When enabled, TICSQServer will upload external source files as well as internal source files to the web server. By disabling this option in SERVER/PROJECTS.yaml, no external source code will be uploaded to the web server.

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 branch 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.yaml and SERVER.yaml, 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.yaml to a unique name. For example, if you have a Windows and Linux build machine, use MERGEKEY: Windows in the first SERVER.yaml and MERGEKEY: Linux in the second.

Limitations:

The MERGEKEY is used as a filename suffix in the TICSServer-MERGEKEY.cfg file, located in the TIOBEPortalData/settings directory on the web server.
Only alpha-numeric characters, underscores (_) and hypens (-) are allowed in the MERGEKEY. Spaces are not allowed.
If you change the MERGEKEY, you have to manually delete the old TICSServer-MERGEKEY.cfg file.
Project names should be unique among build servers. The viewer shows an error when a duplicate project name is encountered.

HEARTBEAT

During a TiCS run, the client sends intermittent heartbeat signals to the viewer, to enable detection of runs that have stopped unexpectedly. When a heartbeat has not been received for a certain amount of time, the run is detached automatically.

INTERVAL (optional; default=60)

Time in seconds between heartbeat messages sent to the viewer.

TIMEOUT (optional; default=180)

After not receiving a heartbeat for a number of seconds specified by the TIMEOUT option, the viewer will consider the corresponding run closed. This means that if a run is killed, another run for the same project can start after the specified amount of time has elapsed.

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.yaml (or PROJECTS.yaml for project overrides). However passwords should never be stored in plain text.

The mechanism used to encrypt passwords in the SERVER.yaml is as follows. The plaintext password is saved in the SERVER.yaml 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.yaml will lead to errors when an attempt is made by TICS to use the password. So all passwords in the SERVER.yaml must be encrypted when used.

ALLOWCOMMENTSUPPRESSIONS	optional	default = 1
ARCHIVEGEN	optional
AUTHENTICATION	optional
BUGTRACKER	optional
BUILDRELATIONSEARCHDEPTH	optional
BUILDTOOLS	optional
COMPILERS	optional
CONFIGURATION	optional
DATABASE	optional
DOSUBST	optional	default = 1
EMAIL	mandatory
FILEFILTERS	optional
FOLLOWLINKS	optional	default = 1
INCLUDERELATIONCONTINUEOUTSIDEARCHIVE	optional	default = 0
LANGUAGES	mandatory
LDAP	optional
LICDIR	optional
MAILTO	optional	default='mailto:tics@tiobe.com'
METRICS	optional
METAINFO	optional	default = 1
MSBUILDINPLACE	optional	default = 0
NOTIFICATIONS	mandatory
ONLYBUILDRELATIONSFROMDB	optional	default = 0
ORGANIZATION	optional	recommended
OWNER	mandatory
OWNERVERBOSE	optional	default = ''
POSTQDB	optional
PREPARECLIENT	optional
PREPAREQDB	optional
PYTHONVERSION	optional
RECALC	optional
LOG	optional
SCMTOOL	optional
SITE	optional	recommended
SOAKTIME	optional
SUPPRESSMACROEXPANSIONVIOLATIONS	optional	default = []
TOOLS	optional
WEBSERVER	mandatory