SERVER.txt Reference Guide

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

Syntax of SERVER.txt

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

Examples of property definitions

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

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

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

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

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

Notation

User specific data is printed in italic.

Optional properties are enclosed in brackets:

['PROPERTY' => ...,]

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

# This is a comment

Property precedence

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

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

Available properties

This section gives an overview of all available properties in the SERVER.txt.
ALLOWCOMMENTSUPPRESSIONSoptionaldefault = 1
ARCHIVEGENoptional 
AUTHENTICATIONoptional 
BUGTRACKERoptional 
CFG_BACKUP_DIRoptional 
COLLECTCLIENTSTATSoptionaldefault = 0
COMPILERSoptional 
DATABASEmandatory 
DOSUBSToptionaldefault = 1
EMAILoptional 
EXTINCLUDEoptionaldefault = [ 'h', 'hpp' ]
FILEFILTERSoptional 
FOLLOWLINKSoptionaldefault = 1
LANGUAGESmandatory 
LDAPoptional 
MAILTOoptionaldefault='mailto:tics@tiobe.com'
METRICSoptional 
NOTIFICATIONSoptional 
ONLYBUILDRELATIONSFROMDBoptionaldefault = 0
ORGANIZATIONoptionalrecommended
OWNERmandatory 
OWNERVERBOSEoptionaldefault = ''
PREPAREQDBoptional 
SCHEDULEoptional 
SCMTOOLoptional 
SITEoptionalrecommended
SUPPRESSMACROEXPANSIONVIOLATIONSoptionaldefault = []
TOOLS => COVERITYoptional 
TOOLS => JAVACoptional 
VSBUILDRELATIONSSLNROOToptionaldefault = 1
WEBSERVERmandatory 

Example of SERVER.txt

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

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

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

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

  'CFG_BACKUP_DIR' => 'C:/TICS/BuildServer/backups/cfg',

  'LANGUAGES' => {
    'CPP' => {
      'EXTENSIONS' => [ 'cpp' ],
      'BUILDTYPE' => [
        { 'name' => 'VCProj', 'compiler' => [ 'VC' ] },
        { 'name' => 'DSP', 'compiler' => [ 'VC' ] },
        { 'name' => 'DDK', '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' => 'VCProj', 'compiler' => [ 'VC' ] },
        { 'name' => 'DSP', '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/'
        },
      ],
      'ALARMTARGETS' => [
        {
          'KIND' => 'RELATIVE',
          'VALUE' => 3,
        },
        {
          'KIND' => 'ABSOLUTE',
          'VALUE => '3',
          'SCOPE' => '@src/MyProject.vcpoj'
        },
      ],
    },
    'UNITBRANCHCOVERAGE' => {
      'ENABLED' => 1,
    },
    'UNITSTATEMENTCOVERAGE' => {
      'ENABLED' => 1,
    },
    'UNITFUNCTIONCOVERAGE' => {
      'ENABLED' => 1,
    },
    'LOC' => {
      'ENABLED' => 1,
    },
    'ELOC' => {
      'ENABLED' => 1,
    },
    'CYCLOMATICCOMPLEXITY' => {
      'ENABLED' => 1,
    },
  },

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

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

ALLOWCOMMENTSUPPRESSIONS

Syntax

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

Description

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

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

Context

The ALLOWCOMMENTSUPPRESSIONS property is used in the following contexts:


ARCHIVEGEN

Syntax

'ARCHIVEGEN' => 'custom archive generator'

Description

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

This setting is optional.

AUTHENTICATION

Syntax

'AUTHENTICATION' => {
  'TYPE' => 'LDAP|NONE',
  ['SERVER' => 'name/ip-address of the authentication server. Mandatory for LDAP',]
  ['CREDENTIALS' => array of {USERNAME, PASSWORD} objects,]
  ['BINDDN' => 'LDAP bind. Mandatory for LDAP',]
  ['SEARCHNAME' => 'LDAP search name',]
  ['SEARCHFILTER' => 'LDAP search filter',]
  ['SEARCHLOGIN' => {'USERNAME'=>'login name for LDAP search', 'PASSWORD'=>'password for LDAP search'},]
  ['TRUSTSTORE' => 'file system location of a .truststore file when an LDAP SSL connection is required',]
  ['PERMISSIONS' => 'the permission configuration to assign privileges to users',]
},
This setting is optional.

Description

The AUTHENTICATION section is added to provide an authentication/authorization mechanism in the TICS viewer. This way all projects or specific projects can be viewed only when the correct username/password is provided. When AUTHENTICATION is configured, the viewer will show a login panel when authentication is required or the provided username/password combination does not give rights to view the project's data. When authentication and authorization is successful the username and password will be saved (encrypted) in a browser cookie so the next time authentication is automatic.

The AUTHENTICATION section can be specified at global level in the SERVER.txt file and/or in the scope of a project in the PROJECTS.txt file. The settings for a project in the PROJECTS.txt file override the global settings.

Context

The AUTHENTICATION property is used when opening a viewer for determining what projects should need authentication/authorization.

Example

'AUTHENTICATION' => {
  'TYPE' => 'LDAP',
  'SERVER' => 'some.server.com:389',
  'BINDDN' => '%user%@intra.local',
  'SEARCHNAME' => 'dc=intra,dc=local',
  'SEARCHFILTER' => '(&(objectClass=user)(memberOf=cn=Engineer,ou=Research))',
  'PERMISSIONS' => {
    'BUILDCONFIGADMIN' => {
      'ALLOWEDUSERS' => [
        'user1'
      ]
    }, 
    'VIEWER' => {
      'ALLOWEDUSERS' => [
        'admin_username',
        'user1',
        'user2'
      ]
    } 
  }
}

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' }

CFG_BACKUP_DIR

Syntax

'CFG_BACKUP_DIR' => 'configuration backup directory'
This setting is optional.

Description

If the CFG_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 CFG_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 CFG_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 CFG_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 CFG_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 CFG_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

'CFG_BACKUP_DIR' => 'C:/TICS/BuildServer/backups/cfg'

COLLECTCLIENTSTATS

Syntax

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

Description

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

Context

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

Example

'COLLECTCLIENTSTATS' => 1

COMPILERS

Syntax

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

Description

The BINNAMES property

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

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

Context

The BINNAMES property is used in the following contexts:

Example

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

The COMMENTPRESERVATION property

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

Example

'COMPILERS' => {
  'Gcc' => {
    'COMMENTPRESERVATION' => '1',
  }
}

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:


DATABASE

Syntax

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

Description

The mandatory DATABASE property sets the database connection information. The only mandatory property is the domain name or the IP address of the SERVER that hosts the database.

'SERVER'
The domain name or IP address of the server that hosts the database.
'DB_BACKUP_DIR'
A location to store database backups in.
'DB_BACKUP_TIMEOUT'
Maximum time a backup may take in minutes. Default is 120 minutes / 2 hours.
'NROFBACKUPS'
The number of backups to keep.
'DBPATH'
The directory containing the Firebird database files.
'DB_BIN'
The directory containing the Firebird executables (such as gbak).
'USERNAME'
The name of the user to authenticate as.
'PASSWORD'
The password belonging to the account above.
'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. To avoid endless trying, a reconnection is tried 2 times. By default, the timeout is 60 seconds. The reconnection feature is only supported for a handful of SQL problems.

Context

The DATABASE property is used in the following contexts:


DOSUBST

Syntax

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

Description

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

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

Context

The DOSUBST property is used in the following contexts:

Example

'DOSUBST' => 0

EMAIL

Syntax

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

Description

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

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

See LDAP and NOTIFICATIONS for further mail configuration properties.

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

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

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

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

The 'PROXYURL' 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.

The 'PROXYAUTOCONFIG' 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 PROXYAUTOCONFIG if PROXYURL has been set, as it will be ignored.

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

Context

The EMAIL property is used in the following contexts:

Example

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

EXTINCLUDE

Syntax

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

Description

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

The EXTINCLUDE property overrides the default settings!

Context

The EXTINCLUDE property is used in the following contexts:

Example

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

FILEFILTERS

Syntax

'FILEFILTERS' => {
  ['ARCHIVE' => 'ARCHIVE',]
  ['CONTENT' => [
  [ {
      '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.

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 parts: the 'MARKERS' part that defines what the interesting parts of input files look like; and the 'CONTAINS' part that describes what these markers should or should not contain.

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

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

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

Example Matching Markers in a Source File

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

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

Running the content filter on MySourceFile.c gives

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

and

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

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

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

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

This would reject both

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

and

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

This would accept

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

and reject

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

This would accept both

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

and

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

This would reject both

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

and

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

Example (white list)

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

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

Here, 'COPYRIGHT.txt' contains the following.

(C)
Copyright

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

'COMPANY.txt' contains the following.

Acme Legal Corp
Acme Taxes Corp

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

Example (black list)

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

<autogenerated>
<auto-generated>

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

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

Here, 'AUTOGEN.txt' contains the following.

<autogenerated>
<auto-generated>

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

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

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

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


Syntax

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

Description

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

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

Context

The FOLLOWLINKS property is used in the following contexts:

Example

'FOLLOWLINKS' => 0

LANGUAGES

Syntax

'LANGUAGES' => {
[ 'language' => {
    'EXTENSIONS' => [ ['file extension',]+ ],
    [ 'RULESETS' => [
      [ {
        'NAME' => 'ruleset name',
        'METRIC' => 'corresponding metric',
        'RULESDIR' => 'directory for configuration files',
        ['ANCHOR' => 'coding standard anchor',]
        ['DOCNAME' => 'url or related path to document',]
        ['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' => 'duplicated code measuring tool'
    }, ]
    [ 'FANOUT' => {
      'TOOL' => 'fanout measuring tool'
    }, ]
    [ 'TESTCOVERAGE' => {
      'TOOL' => 'test coverage measuring tool'
    }, ]
  }, ]+
},

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: 'ADA', 'C', 'COBOL', 'CPP' (C++), 'CS' (C#), 'JAVA', 'JAVASCRIPT', 'OBJECTIVEC', 'PERL', 'PYTHON', 'SCALA', 'SQL', 'VB' (Visual Basic .NET), 'XAML'.

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

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

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

A ruleset (in 'RULESETS') must be configured for metrics 'CODINGSTANDARD', 'COMPILERWARNING' and 'ABSTRACTINTERPRETATION'. 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.

'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 properties 'DOCNAME', 'SEP' and 'ANCHOR' must 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 CS 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).

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

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

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

The 'CYCLOMATICCOMPLEXITY' property specifies which cyclomatic complexity measurement tool to run for files of this language during the calculating metrics stage. Built-in supported cyclomatic complexity tools include: CMT, RainCode, SourceMonitor, TICSpp, TICSsql, cccc, gnatmetric, mlint, perlcritic, pygenie. Not all tools are available for all languages or all platforms (Linux, Windows). 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 duplicated code. Supported tools are: CPD

The 'FANOUT' property specifies the tool used to calculate the fan-out metric. Supported tools are: BuiltIn, None, TICSCil, TICSsql, mlint. By default, the built-in calculator is used. For .NET, it is possible to specify 'TICSCil' as the fan-out calculator. The TICSCil tool computes the fan-out based on information in the associated assemblies. Note that this 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).

The 'TESTCOVERAGE' property specifies to collect code coverage data generated by the specified tool. See the special Test Coverage chapter for more information on configuring test coverage data collection and its behavior.

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

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

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

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

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

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

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

Context

The LANGUAGES property is used in the following contexts:

Example

'LANGUAGES' => {
  'CPP' => {
    'EXTENSIONS' => [ 'cpp' ],
    'RULESETS' => [
      { 'NAME' => 'C++ Coding Standard',
        'METRIC' => 'CODINGSTANDARD',
        'RULESDIR' => 'codingstandard/cpp',
        'DOCNAME' => 'codingstandard.html',
        'SEP' => '#',
      },
    ],
    'BUILDTYPE' => [
      { 'name' => 'VCXProj', 'compiler' => [ 'VC' ] },
    ],
    'CYCLOMATICCOMPLEXITY' => {
      'TOOL' => 'TICSpp'
    },
    'DEADCODE' => {
      'TOOL' => 'Cppcheck'
    },
    'FANOUT' => {
      'TOOL' => 'BuiltIn'
    },
    'TESTCOVERAGE' => {
      'TOOL' => '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:

Example

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

MAILTO

Syntax

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

Description

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

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

Context

The MAILTO property is used in the following contexts:

Example

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

METRICS

Syntax

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

Description

The METRICS section specifies properties for the following metrics.

CODINGSTANDARD
Coding standard violations
COMPILERWARNINGS
Compiler warnings
ABSTRACTINTERPRETATION
Abstract interpretation
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)
REACHABLEFILES
The number of reachable (buildable) files (relative to the total number of files)
DUPLICATEDCODE
The number of duplicated lines of code (relative to the total lines of code) in a file
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.

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

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

The 'ALARMTARGETS' property is also used to formulate targets for the metric 'CODINGSTANDARD'. The 'VALUE' of a TARGET reflects the so-called alarm level, which defines a threshold for (new) violations. If a violation is found that violates the ALARMTARGET, a so-called ALARM! is given. This alarm is shown in the violation overviews. The 'KIND' subproperty specifies an absolute or relative target.

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

Example

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

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',]
    },]
  },
This setting is optional.

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.

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

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 TIOBE Enterprise Dashboard (TED). This dashboard is accessible to customers and is valuable in monitoring multiple projects over time. It is therefore recommended to specify this address in the 'TO' or 'CC' properties.

TEMPLATE

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

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

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

Thanks,

The SQA manager

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

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

Dear TICS user,


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

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


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


Regards,

The TICS deployment team

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

Context

The NOTIFICATIONS property is used in the following contexts:

Example

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

ONLYBUILDRELATIONSFROMDB

Syntax

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

Description

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

Context

The ONLYBUILDRELATIONSFROMDB property is used in the following contexts:

Example

'ONLYBUILDRELATIONSFROMDB' => 1

ORGANIZATION

Syntax

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

Description

In the ORGANIZATION property the name of the organization may be specified.

Context

The ORGANIZATION property is used in the following contexts:

Example

'ORGANIZATION' => 'Research & Development'

OWNER

Syntax

'OWNER' => 'customer name'

Description

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

Context

The OWNER property is used in the following contexts:

Example

'OWNER' => 'TIOBE'

OWNERVERBOSE

Syntax

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

Description

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

Context

The OWNERVERBOSE property is used in the following contexts:

Example

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

PREPAREQDB

Syntax

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

Description

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

Context

The PREPAREQDB property is used in the following contexts:

Example

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

SCHEDULE

Syntax

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

Description

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

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

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

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

Example

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

SCMTOOL

Syntax

'SCMTOOL' => {
  'NAME' => 'CVS | ClearCase | Git | Perforce | RTC | Subversion | Synergy',
  ['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',]
  ['SNAPSHOT' => 0 | 1,]
  ['TEMPDIR' => 'SCM temporary directory',]
  ['UCM' => 0 | 1,]
  ['USECHANGEDFILES' => 0 | 1,]
  ['USERNAME' => 'SCM username',]
  ['USESUBST' => 0 | 1,]
  ['VERSION' => 'version',]
  ['XARGS' => [ ['additional SCM argument',]+ ],]
}
This setting is optional.

Description

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

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

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

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

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

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

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

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

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

Context

The SCMTOOL property is used in the following contexts:

Example

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

SITE

Syntax

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

Description

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

Context

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

Example

'SITE' => 'Eindhoven'

SUPPRESSMACROEXPANSIONVIOLATIONS

Syntax

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

Description

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

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

Context

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

Example

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

VSBUILDRELATIONSSLNROOT

Syntax

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

Description

The VSBUILDRELATIONSSLNROOT property can be used to allow C/C++/C# files from Visual Studio projects not to be treated as unbuildable in case the archive does not contain solution files for them.

By default, any C/C++/C# files not covered by a solution file are considered dead code. To suppress this behavior, set VSBUILDRELATIONSSLNROOT => 0.

Context

The VSBUILDRELATIONSSLNROOT property is used in the following contexts:

Example

'VSBUILDRELATIONSSLNROOT' => 1

WEBSERVER

Syntax

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

Description

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

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

Context

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

Example

This example configures the location of the TICS viewer, files are copied via the file system (instead of HTTP requests), files are viewable via the viewer's annotated source functionality and the configuration is not automatically synchronized with the TICS configuration on the file server.

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

In this case, the QDB viewer can be reached at http://www.company.com/viewer, the documentation root at http://www.company.com/viewer/docs/index.php, and the administrator documentation at http://www.company.com/viewer/docs/admin/index.php.


PORTALURL (mandatory)

By default, the portal runs on the same host as the viewer. Use this property to specify the base URL to the portal. E.g., 'PORTALURL' => '192.168.1.93:8090/TIOBEPortal'.


SHOWANNOTATEDSOURCES (mandatory)

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


TIMEOUT (optional; default = 120)

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

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

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


LOG (optional; default = 0)

Enable or disable generation of logging information on the web server. This is useful when debugging. By default, logging is disabled. Note that logging always appends to the same log file and that logging produces a lot of data. Therefore, do not forget to turn off logging again after debugging.


MERGEKEY (optional)

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

Limitations:


Appendix

Passwords

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

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

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

After running TICSQServer or TICSMaintenance -checkconfig:

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

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