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.
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 (,).
'NROFBACKUPS' => 20String:
'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, ]... }
User specific data is printed in italic.
Optional properties are enclosed in brackets:
It is possible to use end-of-line comments in the SERVER.txt file. These are denoted by a leading '#'. For instance,
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.)
ALLOWCOMMENTSUPPRESSIONS optional default = 1 ARCHIVEGEN optional AUTHENTICATION optional BUGTRACKER optional BUILDRELATIONSEARCHDEPTH optional COLLECTCLIENTSTATS optional default = 0 COMPILERS optional CONFIGURATION optional DATABASE optional DOSUBST optional default = 1 mandatory EXTINCLUDE optional default = [ 'h', 'hpp' ] 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 PREPAREQDB optional PYTHONVERSION optional SCHEDULE optional SCMTOOL optional SITE optional recommended SUPPRESSMACROEXPANSIONVIOLATIONS optional default = [] TOOLS optional TQIVERSION optional VSBUILDRELATIONSSLNROOT optional default = 1 WEBSERVER mandatory
{
'OWNER' => 'owner',
'MAILTO' => 'mailto:tics@tiobe.com',
'SITE' => 'site',
'ORGANIZATION' => 'organization',
'SCMTOOL' => {
'NAME' => 'CVS | ClearCase | Git | Perforce | RTC | Subversion | Synergy | TFVC',
},
'DATABASE' => {
'SERVER' => 'dbserver.company.com',
'DBPATH' => 'C:/TICS/databases',
'DB_BACKUP_DIR' => 'C:/TICS/BuildServer/backups/databases',
'NROFBACKUPS' => 20,
},
'SCHEDULE' => {
'LOGDIR' => 'C:/TICS/logs',
'NROFBACKUPS' => 20,
},
'CONFIGURATION' => {
'BACKUP_DIR' => 'C:/TICS/BuildServer/backups/cfg',
},
'LANGUAGES' => {
'CPP' => {
'EXTENSIONS' => [ 'cpp' ],
'BUILDTYPE' => [
{ 'name' => 'VCXProj', 'compiler' => [ 'VC' ] },
{ 'name' => 'Make', 'compiler' => [ 'Gcc' ] },
{ 'name' => 'Tornado', 'compiler' => [ 'Gcc' ] },
],
'GENERATED' => [
{
'OPEN' => '// {{{USR',
'CLOSE' => '// }}}USR',
'GENERATED' => 0,
},
{
'OPEN' => '// {{{RME classAttribute',
'CLOSE' => '// }}}RME',
'GENERATED' => 0,
},
{
'OPEN' => '// {{{RME operation',
'CLOSE' => '// }}}RME',
'GENERATED' => 0,
},
{
'OPEN' => '// {{{RME',
'CLOSE' => '// }}}RME',
},
{
'OPEN' => '^\s*//{{',
'CLOSE' => '^\s*//}}',
},
{
'OPEN' => '^\s*BEGIN_ACCESSOR_MAP',
'CLOSE' => '^\s*END_ACCESSOR_MAP',
},
{
'OPEN' => '^\s*BEGIN_COM_MAP',
'CLOSE' => '^\s*END_COM_MAP',
},
{
'OPEN' => '^\s*BEGIN_CONNECTION_POINT_MAP',
'CLOSE' => '^\s*END_CONNECTION_POINT_MAP',
},
{
'OPEN' => '^\s*BEGIN_MESSAGE_MAP',
'CLOSE' => '^\s*END_MESSAGE_MAP',
},
{
'OPEN' => '^\s*BEGIN_OBJECT_MAP',
'CLOSE' => '^\s*END_OBJECT_MAP',
},
],
'RULESETS' => [
{
'NAME' => 'C++ Coding Standard',
'DOCNAME' => 'http://server.tiobe.com/codingrules/show_rule.php',
'SEP' => '_',
'ANCHOR' => '?ID='
},
],
},
'C' => {
'EXTENSIONS' => [ 'c' ],
'BUILDTYPE' => [
{ 'name' => 'VCXProj', 'compiler' => [ 'VC' ] },
{ 'name' => 'Make', 'compiler' => [ 'Gcc' ] },
{ 'name' => 'Keil', 'compiler' => [ 'Keil' ] },
{ 'name' => 'Rose', 'compiler' => [ 'Keil' ] },
{ 'name' => 'Tasking', 'compiler' => [ 'Tasking' ] },
{ 'name' => 'Tornado', 'compiler' => [ 'Gcc' ] },
],
'GENERATED' => [
{
'OPEN' => '/\* {{{USR \*/',
'CLOSE' => '/\* }}}USR \*/',
'GENERATED' => 0,
},
{
'OPEN' => '/\* {{{RME classAttribute',
'CLOSE' => '/\* }}}RME \*/',
'GENERATED' => 0,
},
{
'OPEN' => '/\* {{{RME operation',
'CLOSE' => '/\* }}}RME \*/',
'GENERATED' => 0,
},
{
'OPEN' => '/\* {{{RME',
'CLOSE' => '/\* }}}RME \*/',
},
],
'RULESETS' => [
{
'NAME' => 'C Coding Standard',
'DOCNAME' => 'http://server.tiobe.com/codingrules/show_rule.php',
'SEP' => '_',
'ANCHOR' => '?ID='
},
],
},
'CS' => {
'EXTENSIONS' => [ 'cs' ],
'BUILDTYPE' => [
{ 'name' => 'CSProj' },
],
'RULESETS' => [
{
'NAME' => 'C# Coding Standard',
'DOCNAME' => 'http://server.tiobe.com/codingrules/show_rule.php',
'SEP' => '_',
'ANCHOR' => '?ID='
},
],
},
},
'METRICS' => {
'CODINGSTANDARD' => {
'ENABLED' => 1,
'TARGETS' => [
{
'KIND' => 'RELATIVE',
},
{
'KIND' => 'ABSOLUTE',
'VALUE => '60',
'SCOPE' => '/tst/'
},
],
'BLOCKINGTARGETS' => [
{
'KIND' => 'RELATIVE',
'VALUE' => 3,
},
{
'KIND' => 'ABSOLUTE',
'VALUE => '3',
'SCOPE' => '@src/MyProject.vcpoj'
},
],
},
'UNITBRANCHCOVERAGE' => {
'ENABLED' => 1,
},
'UNITSTATEMENTCOVERAGE' => {
'ENABLED' => 1,
},
'UNITFUNCTIONCOVERAGE' => {
'ENABLED' => 1,
},
'LOC' => {
'ENABLED' => 1,
},
'ELOC' => {
'ENABLED' => 1,
},
'CYCLOMATICCOMPLEXITY' => {
'ENABLED' => 1,
},
},
'WEBSERVER' => {
'PORTALURL' => 'www.company.com:42506/TIOBEPortal',
'SHOWANNOTATEDSOURCES' => 1,
},
'POSTQDB' => 'postana.bat',
'PREPAREQDB' => 'build.bat',
'PYTHONVERSION' => '3.6',
## By default, TICS resolves substituted drive letters to their referenced
## locations when computing canonical file names (as they are stored in the
## quality database).
## To prevent TICS from expanding the 'subst' drive letters and accept
## substituted drive letters as canonical, set the value below to '0'.
'DOSUBST' => 1,
}
'ALLOWCOMMENTSUPPRESSIONS' => 0 | 1This setting is optional; the default is 1.
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.
The ALLOWCOMMENTSUPPRESSIONS property is used in the following contexts:
'ARCHIVEGEN' => 'custom archive generator'
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 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' => {
'NAME' => 'bugtracker name'
}
This setting is optional.
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.
'BUGTRACKER' => { 'NAME' => 'Jira' }
'BUILDRELATIONSEARCHDEPTH' => max-depthThis 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.
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.
The BUILDRELATIONSEARCHDEPTH property is used in the
following contexts:
'BUILDRELATIONSEARCHDEPTH' => 3
'COLLECTCLIENTSTATS' => 0|1This setting is optional, the default is 0.
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.
The COLLECTCLIENTSTATS property is used by the TICS client to
decide whether or not to store certain run properties in the database.
'COLLECTCLIENTSTATS' => 1
'COMPILERS' => {
['compiler' => {
'BINNAMES' => [ [executable name],... ],
'COMMENTPRESERVATION' => {language => [0 | 1]},
'WARNINGFLAGS' => [ [flag],... ],
}],...
},
This setting is optional.
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.
The BINNAMES property is used in the following contexts:
'COMPILERS' => {
'Gcc' => {
'BINNAMES' => [ 'gcc', 'gcc960', 'cc386', 'ccarm', 'dplus' ],
}
}
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.
'COMPILERS' => {
'Gcc' => {
'COMMENTPRESERVATION' => {
'C' => '1',
'CPP' => '0',
}
}
}
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.
'COMPILERS' => {
'Gcc' => {
'WARNINGFLAGS' => [ '-Wextra' ],
}
}
'COMPILERS' => {
'cc386' => {
'WARNINGFLAGS' => [ '-Wno-missing-field-initializers', '-Wno-missing-braces' ],
}
}
The WARNINGFLAGS property is used in the following contexts:
-calc COMPILERWARNING).
'CONFIGURATION' => {
['BACKUP_DIR' => 'configuration backup directory',]
['NROFBACKUPS' => number of backups to keep,]
},
This setting is optional.
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.
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.
'CONFIGURATION' => {
'BACKUP_DIR' => 'C:/TICS/BuildServer/backups/cfg',
'NROFBACKUPS' => 20,
},
'DATABASE' => {
'DBPATH' => 'full path to database path',
'SERVER' => 'name/ip-address of the database server',
['PASSWORD:PLAIN' => 'password',]
['DB_BACKUP_DIR' => 'full path to backup directory',]
['DB_BACKUP_TIMEOUT' => maximum time a backup may take (in minutes),]
['DB_BIN => 'full path to the database executable in case not in default path',]
['NROFBACKUPS' => number of backups maintained,]
['PORT => port number of the database server,]
['QUERYFAILURERETRYATTEMPTS' => number of times a query is retried after sql failure,]
['QUERYFAILURERETRYTIMEOUT' => timeout after sql failure (in seconds; default is 60),]
['USERNAME' => 'username',]
},
The optional DATABASE section sets the database connection
information. The only mandatory properties are the domain name or the IP
address of the SERVER that hosts the database and the
DBPATH that contains the location of the Firebird database files.
The DATABASE section can also be set per project in the
PROJECTS.txt.
DBPATH:
The directory containing the Firebird database files.
SERVER:
The domain name or IP address of the server that hosts the database.
DB_BACKUP_DIR:
A location to store database backups in.
DB_BACKUP_TIMEOUT:
Maximum time a backup may take in minutes. Default is 120 minutes / 2 hours.
DB_BIN:
The directory containing the Firebird executables (such as gbak).
NROFBACKUPS:
The number of backups to keep.
USERNAME:
The name of the user to authenticate as.
PASSWORD:
The password belonging to the account above.
QUERYFAILURERETRYATTEMPTS:
The number of times a query is retried when a SQL failure occurs. For example
when the connection to the database is lost. By default, 3 attempts are made to
execute a query successfully.
QUERYFAILURERETRYTIMEOUT:
Sometimes the connection to the database is lost, due to among other things,
network problems. In that case it would be possible to proceed by reconnecting
to the database. With this option, the timeout in seconds is given, after which
a new connection is established. By default, the timeout is 60 seconds. The
reconnection feature is only supported for a handful of SQL problems.
The DATABASE property is used in the following contexts:
-project option.'DOSUBST' => 0|1This setting is optional; the default is 1.
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.
The DOSUBST property is used in the following contexts:
'DOSUBST' => 0
'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.
Basic outgoing mail configuration. TICS can send a number of email notifications: error messages, status reports (a.o., to the TED), and SQA reports.
The basic mail configuration covers the 'From' address to be used as sender of TICS mails and the SMTP host to use for sending mails.
See LDAP and NOTIFICATIONS for further mail configuration properties.
The MAILER property can be used to specify the mail method used to
send e-mail. Two mail methods are shipped with TICS as built-ins:
Http and Smtp.
The Http method requires USERNAME and
PASSWORD to authenticate to the mail relay.
The Smtp method requires SMTPHOST to be set to a
(local) SMTP host that is capable of sending unauthenticated e-mail.
The SMTPHOST property is mandatory in the case of method 'Smtp' and
should point to a valid SMTP mail server that allows the TICSQserver
process to send e-mails. Currently, authenticating SMTP hosts are not
supported. The 'FROM' property can be used to easily identify the
e-mails sent by TICS.
In PROXYSETTINGS, URL can be used to specify
the proxy server that TICS should use when sending email notifications
in case your intranet settings require a proxy to communicate with the
internet. It should be of the format host:port. If the port
number is omitted, 8080 will be used. USERNAME and
PASSWORD can be used to connect through an authenticated proxy.
The PACFILE is an alternative and more advanced way to
configure a proxy server. It can be used to used if you have a so-called
proxy auto-config (PAC) file that contains proxy server information
for your intranet. The PAC-file can be a local file or a URL.
You should not set PACFILE if PROXYSETTINGS => URL has
been set, as it will be ignored.
PROXYAUTOCONFIG => 'file:///c:/proxy.pac',
The EMAIL property is used in the following contexts:
'EMAIL' => {
'FROM' => 'ticsqserver@company.com',
'SMTPHOST' => 'smtp.company.com'
}
'WEBSERVER' => {
'ERRORSUPPRESSION' => 0 or 1 (optional; default=1),
},
This setting is optional.
When TICS fails to analyze a file, for instance because of a tool error, it cannot produce a sensible metric value for that file and instead stores the error in the database. Error Suppression, which is enabled by default, is a feature of the viewer that replaces erroneous measurements by an earlier successful measurement for that file, if available. Without error suppression, such errors would negatively impact the TQI scores, because they decrease the metric coverage.
The advantage of error suppression (also called "spike management") is that trend lines for TQI metrics will be more stable and will have less improper drops that are caused by external factors such as tool failures. The disadvantage is that you might be looking at data that is out-of-date as long as the tool keeps failing. The Annotated Source will give a warning in such cases, because you might observe a mismatch between the source code and the reported violations. Other parts of the viewer will not warn you about this.
The error suppression feature can be disabled per project by setting ERRORSUPPRESSION of
the WEBSERVER to 0. When changing this setting, it is needed to invoke a
generate viewer cache event
afterwards.
'EXTINCLUDE' => [ [ext,]... ]This setting is optional (default=[ 'h', 'hpp' ]).
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!
The EXTINCLUDE property is used in the following
contexts:
'EXTINCLUDE' => [ 'h', 'hh', 'inc' ]
'FILEFILTERS' => {
['ARCHIVE' => 'ARCHIVE',]
['CONTENT' => [
[ {
['ARCHIVE' => 'ARCHIVE',]
'MARKERS' => {
['ALL' => 'marker file',]
['ANY' => 'marker file',]
['NONE' => 'marker file',]
}
'CONTAINS' => {
['ALL' => 'contains file',]
['ANY' => 'contains file',]
['NONE' => 'contains file',]
}
} ]+
], ]
}
This setting is optional.
Property FILEFILTERS lists zero or more so-called file
filters. File filters limit the scope of the archive.
The following file filters are available at top level or project level.
ARCHIVE: This property refers to a so-called archive file
relative to the configuration directory. See the ARCHIVE Reference Guide for more
information on the contents of ARCHIVE files.
Note that for the ARCHIVE expressions on top level, only the
so-called legacy mode is available (see ARCHIVE Reference Guide). This is
because, without a project, the branch directory cannot be determined (which
is needed to determine the root directory of the branch).
CONTENT: This property allows inclusion/exclusion of files based
on their contents. It consists of two mandatory parts and an optional third
part: the MARKERS part (mandatory) that defines what the
interesting parts of input files look like; the CONTAINS part
(mandatory) that describes what these markers should or should not contain;
and the ARCHIVE part (optional) that optionally restricts the
content filter to files that match the archive expression.
Both MARKERS and CONTAINS contain one or more (up to
three) subkeys to fine tune the search. The keys are called ALL,
ANY and NONE. Each of these keys take a file name
(in the configuration directory) as a value.
ALL indicates that all entries in the specified file must be
satisfied. ANY indicates that at least one of the entries must be
satisfied. NONE means that none of the entries must match.
Matches are case insensitive.
It works as follows. First, the input file is scanned for the occurrence of
strings from any of the MARKERS in comment tokens. Any
matching comments are returned and subsequently scanned for strings specified
by CONTAINS.
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.
'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 */
'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 */
'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 */
'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 */
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.
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).
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' => 0|1This setting is optional; the default is 1.
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.
The FOLLOWLINKS property is used in the following contexts:
'INCLUDERELATIONCONTINUEOUTSIDEARCHIVE' => 0|1This setting is optional; the default is 0.
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.
The INCLUDERELATIONCONTINUEOUTSIDEARCHIVE property is used in the following contexts:
TICSQServer -calc
INCLUDERELATIONS).
'LANGUAGES' => {
[ 'language' => {
'EXTENSIONS' => [ ['file extension',]+ ],
[ 'RULESETS' => [
[ {
'NAME' => 'ruleset name',
'METRIC' => 'corresponding metric',
'RULESDIR' => 'directory for configuration files',
['DYNAMICRULESET' => [0|1]]
['ANCHOR' => 'coding standard anchor',]
['DOCNAME' => 'url or related path to document',]
['DOCSUF' => 'rule property to use as URL path suffix',]
['SEP' => 'rule separator',]
}, ]+
], ]
[ 'BUILDTYPE' => [
[ {
'name' => 'buildtype',
['compiler' => [ ['compiler']+ ],]
['make' => 'path to GNU make 3.80 executable',]
}, ]+
], ]
[ 'GENERATED' => [
[ {
'OPEN' => '<reg expression>',
'CLOSE' => '<reg expression>',
'GENERATED' => [0 | 1],
}, ]+
], ]
[ 'CYCLOMATICCOMPLEXITY' => {
'TOOL' => 'cyclomatic complexity measuring tool',
}, ]
[ 'DEADCODE' => {
'TOOL' => 'deadcode measuring tool'
}, ]
[ 'DUPLICATEDCODE' => {
'TOOL' => 'code duplication measuring tool'
}, ]
[ 'FANOUT' => {
'EXTERNALNAMESPACE' => ['list of namespaces external to the software system'],
'INTERNALNAMESPACE' => ['list of namespaces internal to the software system'],
'TOOL' => 'fanout measuring tool',
'CUSTOMIMPORTS' => ['list of custom import keywords'],
}, ]
[ 'TESTCOVERAGE' => {
'TOOLS' => ['test coverage measuring tools']
}, ]
}, ]+
},
The 'LANGUAGES' property is mandatory. It specifies a set of properties
for each language. Languages are identified by their logical name.
Built-in language identifiers include:
'C',
'CPP' (C++),
'CS' (C#),
'JAVA',
'JAVASCRIPT',
'KOTLIN',
'LUA',
'MATLAB',
'OBJECTIVEC',
'PYTHON',
'SCALA',
'SQL',
'TYPESCRIPT',
'VB' (Visual Basic .NET),
'XAML'.
Source files are associated with a language via their file extensions.
This is configured via the 'EXTENSIONS' property. For example, use
'EXTENSIONS' => [ 'c' ] for C source files,
'EXTENSIONS' => [ 'cpp' ] for C++ source files, or
'EXTENSIONS' => [ 'cs' ] for C# source files.
Some metrics (e.g., 'COMPILERWARNING') require compiler options. To obtain
these options from the (build) environment, one or more so-called build types
must be specified via 'BUILDTYPE'.
A build type has a 'name' and optionally a list of supported
compilers. The build type is used to read associated build/makefiles/project
files to extract file lists and options for the preprocessor. A matching
compiler of the list of candidates is used to extract compiler options from
the build and perform preprocessing (if required). It is even possible to
specify some additional (non-standard) preprocessing flags to the compiler.
For C and C++ using Microsoft Visual Studio, the following build type
definition can be used:
'BUILDTYPE' => [
{ 'name' => 'VCXProj', 'compiler' => [ 'VC' ] },
],
A ruleset (in 'RULESETS') must be configured for metrics 'CODINGSTANDARD', 'COMPILERWARNING', 'ABSTRACTINTERPRETATION' and 'SECURITY'. A ruleset must have a unique name, a corresponding metric and a unique rule directory. A metric may be associated with more than one ruleset.
A ruleset 'NAME' must be (globally) unique. This is just a string identifying
the ruleset. Usually, something of the form owner language
metric; e.g., Acme C Coding Standard, Acme C++
Compiler Warnings.
A ruleset metric name must be one of CODINGSTANDARD,
COMPILERWARNING, ABSTRACTINTERPRETATION,
SECURITY.
'RULESDIR' specifies the location of the coding standard configuration files
RULES.txt and IMPL.txt. Each ruleset must specify
its rule configuration in a separate directory.
The property 'DYNAMICRULESET' defines whether a given ruleset is internally an aggregate of multiple different rulesets. For each file separately a choice is made on this ruleset dependent on the compiler version.
The properties 'DOCNAME', 'DOCSUF', 'SEP' and 'ANCHOR' may be set to configure the coding standard viewer for the corresponding language. In case the TICS coding standard viewer is used, setting 'DOCNAME' to the coding standard viewer location for the language is sufficient. In case 'DOCNAME' points to (static) HTML pages, 'SEP' and 'ANCHOR' may also have to be set (to be able to point to individual rules).
The SEI CERT Secure Coding Rules are supported as follows.
'RULESETS' => [
{ 'NAME' => 'SEI CERT C++ Coding Standard',
'METRIC' => 'SECURITY',
...
'DOCNAME' => 'https://wiki.sei.cmu.edu/confluence/display/',
'DOCSUF' => 'SYNOPSIS',
'ANCHOR' => '/',
},
],
So, by setting 'DOCNAME', 'DOCSUF' and 'ANCHOR' (to the values above).
'DOCNAME' points to the TICS coding standard viewer or another document
located on a web server, e.g.,
http://outserver/codingstandard.html.
'ANCHOR' is the static part that redirects to the specific rule within a
coding standard document. For example, if the document contains anchors named
<a name="Rule100">, where 100 is the ID of the
rule, then the 'ANCHOR' should be '#Rule'. For TICS coding
standard viewers, this option can be omitted.
'SEP' overrides unencoded HTML entities in the coding standard document. In
some cases, symbols that are not allowed in URLs, but that are part of the
name of a coding standard rule, such as '#', are replaced by
another character in the coding standard document. For example, a rule
C#100 might be defined as anchor in the coding standard document
as follows: <a name="RuleC_100"> (i.e., the
'#' has been replaced by '_'). In this case, 'SEP'
must be specified as '_'. An alternative (better) approach would
be to use the URL-encoded character in the document; in this case: <a
name="RuleC%23100"> (since '%23' is the URL-encoding of
'#'), and avoid having to specify 'SEP' altogether. For TICS
coding standard viewers, this option can be omitted.
The 'CYCLOMATICCOMPLEXITY' property specifies which cyclomatic complexity
measurement tool to run for files of this language during the calculating
metrics stage. Built-in supported cyclomatic complexity tools include:
CMT,
SourceMonitor,
TICSpp,
TICSsql,
cccc,
mlint.
Not all tools are available for all languages or all platforms (Linux,
Windows, macOS).
It is possible to provide your own custom module and use that. If the
language/cyclomatic complexity measuring tool combination does not fit (e.g.,
the cyclomatic complexity measuring tool does not work for files of the
specified language), a warning is given at the start of the process, and an
error during the calculating metrics stage. In case the
'CYCLOMATICCOMPLEXITY' property is not specified,
'TICSpp' is used.
The 'DEADCODE' property specifies the tool used to calculate dead code.
Supported tools are:
BuiltIn,
Cppcheck
The 'DUPLICATEDCODE' property specifies the tool used to calculate code
duplication. Supported tools are:
CPD
The 'FANOUT' property specifies the tool used to calculate the fan-out metric.
Supported tools are the following:
C,
Cpp,
Go,
Java,
Javascript,
Jsp,
Kotlin,
Lua,
mlint,
Objectivec,
Perl,
Python,
Scala,
Simulink,
Swift,
TICSCil,
TICSsql,
Typescript,
Vb,
None.
TICSCil, TICSsql and mlint are tools used for C#, SQL and Matlab respectively.
For header files, the C fan-out calculator is used.
The TICSCil tool computes fan-out based on information in the
associated assemblies. Note that Cs requires that the (Visual Studio)
projects must have been built so the assemblies are present and the
language 'BUILDTYPE' must be set so the build information can be obtained by
TICS (to determine the assembly location).
For some languages, it is necessary to provide a way to identify whether the calculated fan-out is internal (ie. coming from the same software system) or external (from system or external libraries).
The 'EXTERNALNAMESPACE' property can be used to define a list of namespaces which are known to be from libraries external to the software system, and as such should be counted as external fan-out.
The 'INTERNALNAMESPACE' property can be used to define a list of namespaces which are a part of the software system being analyzed, and as such should be counted as internal fan-out.
Note that 'EXTERNALNAMESPACE' and 'INTERNALNAMESPACE' are mutually exclusive for the same language due to the way these properties are used. In the case an 'INTERNALNAMESPACE' is configured then everything outside of these namespaces will be counted as external, and vice versa. In cases both of these would be configured, then it would also be possible for a namespace to be neither of these, which is not allowed.
Sometimes, libraries and files are imported with a custom function. In such cases, the 'CUSTOMIMPORTS' property can be used. Currently, this is only used for Lua.
'LANGUAGES' => {
'CS' => {
'FANOUT' => {
'INTERNALNAMESPACE' => ['Tiobe.Roslyn'],
'TOOL' => 'TICSCil',
}
},
'JAVA' => {
'FANOUT' => {
'INTERNALNAMESPACE' => ['com.company', 'com.other-company-namespace'],
'TOOL' => 'Java',
}
},
'JAVASCRIPT' => {
'FANOUT' => {
'EXTERNALNAMESPACE' => ['dojo', 'dijit'],
'TOOL' => 'Javascript',
}
},
'LUA' => {
'FANOUT' => {
'TOOL' => 'Lua',
'CUSTOMIMPORTS' => ['custom_import_function'],
}
},
'TYPESCRIPT' => {
'FANOUT' => {
'TOOL' => 'Typescript',
}
}
}
An example of how a Java source file with these settings in SERVER.txt will be scored on Internal and External Fan Out:
// marked as external fan-out import java.io.File; import java.io.IOException; // marked as internal fan-out import com.company.FileUtils; import com.company.package.Runner;
This is not necessary for languages where it is possible to distinguish internal and external imports by the type of import that is being used. In the case of (C, C++, ObjC), internal and external fan-out can be distinguished by the type of include used, as shown in the following example:
#include <cmath> // standard include, will be marked as external fan-out #include "includes.h" // user include, will be marked as internal fan-out
The 'TESTCOVERAGE' property specifies to collect code coverage data
generated by any one of the specified tools. In the case multiple code coverage
tools are configured, TICS will check the result file to determine which code
coverage tool was used to generate it. See the special
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:
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'.
The LANGUAGES property is used in the following contexts:
'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' => {
['SERVER' => 'LDAP server',]
['BASE' => 'LDAP base property',]
['FILTER' => 'LDAP filter property',]
['ATTRIBUTE' => 'LDAP attributes',]
['PASSWORD:PLAIN' => 'LDAP password'),]
}
This setting is optional.
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.
The LDAP property is used in the following contexts:
This setting is only used by TICSQServer. The TICS Viewer can also connect to an LDAP server, which is configured in the Administration Pages.
'LDAP' => {
'SERVER' => 'ldapserver',
'BASE' => 'OU=USERS,OU=aserver,OU=CODE,DC=LDAP,DC=TIOBE,DC=COM',
'FILTER' => 'CN=%s',
'ATTRIBUTE' => 'mail',
'PASSWORD:PLAIN' => 'apassword',
}
'LICDIR' => 'dir'This setting is optional.
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.
TICSQServer, etc are looking for the TICS license file.
'LICDIR' => '../../common'
'MAILTO' => 'support email address'This setting is optional (default='
mailto:tics@tiobe.com').
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'.
The MAILTO property is used in the following contexts:
'MAILTO' => 'mailto:support@company.com'
'METRICS' => {
['metric name' => {
'ENABLED' => 0 | 1,
['MINIMUMTOKENCOUNT' => 50,]
['TARGETS' => [
{
'KIND' => 'ABSOLUTE | RELATIVE',
['VALUE' => value,]
['SCOPE' => 'archive path expression'|@projectfile,]
['AGGREGATED' => 0 | 1,]
},...
],]
['BLOCKINGTARGETS' => [
{
'KIND' => 'ABSOLUTE | RELATIVE',
'VALUE' => value,
['SCOPE' => 'archive path expression'|@projectfile,]
['AGGREGATED' => 0 | 1,]
},...
],]
},]...
},
This setting is optional.
The METRICS section specifies properties for the following metrics.
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 'BLOCKINGTARGETS' subproperty is also used to formulate targets for the metric 'CODINGSTANDARD'. The 'VALUE' of a TARGET reflects the so-called blocking level, which defines a threshold for (new) violations. If a violation is found that violates the BLOCKINGTARGET, a message that indicates the violation is given. This message is shown in the violation overviews. The 'KIND' subproperty specifies an absolute or relative target. For each blocking target 'SCOPE' and 'LANGUAGE' can be defined to specify which files to match. 'SCOPE' matches in the same way as it does in the 'TARGETS' subproperty. 'LANGUAGE' is used to filter files by language before matching with 'SCOPE'. If no 'LANGUAGE' is specified, it means that files in any language, except in languages specified in other BLOCKINGTARGETS, should meet this blocking target.
The 'TARGETS' and 'BLOCKINGTARGETS' properties are used to formulate a so-called QA statement with regard to the metric. If a metric's value meets the specified target value, the measured metric value is said to be accepted by QA. Otherwise, the file or project is not accepted by QA.
'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,
},
],
},
},
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.
'METRICS' => {
'DUPLICATEDCODECUSTOM' => {
'ENABLED' => 1,
'MINIMUMTOKENCOUNT' => 50,
},
},
'METAINFO' => 0 | 1This setting is optional; the default is 1.
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.
The METAINFO property can be used in the following contexts:
'MSBUILDINPLACE' => 0 | 1This setting is optional; the default is 0.
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.
The MSBUILDINPLACE property is used in the following contexts:
'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.
The NOTIFICATIONS section is used to configure the different notification e-mails TICS can send. These are:
NOTIFICATIONS require the EMAIL properties to be correctly set.
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.
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.
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'.
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.
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'.
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.
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.
The NOTIFICATIONS property is used in the following contexts:
'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' => 0|1This setting is optional; the default is 0.
The ONLYBUILDRELATIONSFROMDB property can be used to disable searching the
file system when a project file cannot be found in the database.
The ONLYBUILDRELATIONSFROMDB property is used in the following contexts:
'ONLYBUILDRELATIONSFROMDB' => 1
'ORGANIZATION' => 'organization name'This setting is optional, but recommended.
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 ('/').
The ORGANIZATION property is used in the following contexts:
'ORGANIZATION' => 'Research & Development'
'OWNER' => 'customer name'
In the mandatory OWNER property the name of the customer needs to be specified.
The OWNER property is used in the following contexts:
logo-<owner>.gif (located in web cfg
directory).
'OWNER' => 'TIOBE'
'OWNERVERBOSE' => 'long customer name'This setting is optional.
In the OWNERVERBOSE property the longer name of the customer can be specified.
The OWNERVERBOSE property is used in the following contexts:
'OWNERVERBOSE' => 'TIOBE Software B.V.'
'POSTQDB' => 'executable file or perl module'This setting is optional.
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.
The POSTQDB property is used in the following contexts:
'POSTQDB' => 'post.bat'or
'POSTQDB' => 'POSTQDB.pm'
'PREPAREQDB' => 'executable file or perl module'This setting is optional.
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.
The PREPAREQDB property is used in the following contexts:
'PREPAREQDB' => 'build.bat'or
'PREPAREQDB' => 'PREPAREQDB.pm'
'PYTHONVERSION' => 'Python version'This setting is optional.
To support different versions of python, 'PYTHONVERSION' is introduced since Python 2 and 3 are not compatible.
The PYTHONVERSION property is used in the following context:
'PYTHONVERSION' => '2.7'or
'PYTHONVERSION' => '3.6'
'SCHEDULE' => {
['LOGDIR' => 'directory for logging files',]
['NROFBACKUPS' => number,]
}
This setting is optional.
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.
'SCHEDULE' => {
'LOGDIR' => 'C:/Program Files/TIOBE/TICS/log',
'NROFBACKUPS' => 3,
}
'SCMTOOL' => {
'NAME' => 'CVS | ClearCase | Git | Perforce | RTC | Subversion | Synergy | TFVC',
['AUTOUPDATE' => 0 | 1,]
['CVSMODULES' => [ ['CVS module',]+ ],]
['DB' => 'SCM database name',]
['HOSTNAME' => 'SCM hostname',]
['PASSWORD:PLAIN' => 'SCM db password',]
['PREPARE' => 'script to run before SCM start. Script gets project name as argument',]
['SHOWSCMID' => 0 | 1,]
['SNAPSHOT' => 0 | 1,]
['TEMPDIR' => 'SCM temporary directory',]
['UCM' => 0 | 1,]
['USECHANGEDFILES' => 0 | 1,]
['USERNAME' => 'SCM username',]
['USESUBST' => 0 | 1,]
['VERSION' => 'version',]
['XARGS' => [ ['additional SCM argument',]+ ],]
}
This setting is optional.
The SCMTOOL property determines the Software Configuration Management system that is being used to control the customer's source repository. The following systems are supported:
If none of the above is applicable, the property should be omitted. TICS will
proceed without software configuration management support. For TICS client runs
to work with -project the path to the sources must be the same for
the client and the server.
'USECHANGEDFILES' determines whether the SCM tool's "changed files"
feature is used to determine the set of files that has changed between
the previous TICSQServer run and the current run. By default, this
feature is used if supported by the SCM tool. Currently, this is
supported for Git, Perforce, RTC and Subversion. This means that the SCM
tool is queried for the set of files that has changed since the last
run. This is usually more efficient than doing a compare of the archive
as checked out on the file system and the data stored in the quality
database. The latter method is costly since the file system must be
traversed and data on each file must be gathered individually. However,
there may be cases where the "changed files" feature does not work. For
example, in the case of Subversion, if a work area consists of
check-outs from distinct locations in the repository, the "changed
files" mechanism does not work. In that case, set
'USECHANGEDFILES' => 0.
'AUTOUPDATE' indicates whether TICSQServer should automatically update the archive with the latest available versions from the SCM tool. Depending on the SCM tool used, this is also referred to as rebasing, reconfiguring or synchronizing.
'DB' specifies the name of the SCM repository associated with this
project. TICS uses this value to resolve the name of the current project
for clients that use the project 'auto' setting.
The 'SHOWSCMID' property is used to determine whether the SCM identifiers should be shown by TICS when running the TICS client. There are cases, such as when computing a delta metric, where TICS will show the identifier of the version of the file that was last analyzed by TICS. In contexts where this is not meaningful, these messages can be suppressed by setting 'SHOWSCMID' to 0.
The 'SNAPSHOT' and 'UCM' are used in the case of ClearCase to indicate whether one has a dynamic or a snapshot view and whether UCM is used.
Set 'USESUBST' in cases where the Synergy workarea path is set to
a subst drive, e.g., I:/... => C:/ccm_wa/project. If
'DOSUBST' is set, for each path that is passed to a Synergy
ccm system call, the subst drive (if it was removed by TICS) is
restored. This property must be used, since Synergy does not return
the correct file version number in case an incorrect workarea path is
used (i.e., any path name that differs from Synergy's workarea
administration).
The 'VERSION' property is used for Synergy to specify which
version of Synergy to use (useful if multiple versions are used and/or
installed on a system). Example values of version:
6.4, 6.3, 6.2, 5.1
CS.
All other 'SCMTOOL' properties are currently CMSynergy specific. 'HOSTNAME' specifies the server on which the SCM repository runs. The 'HOSTNAME' property implicitly adds CMSynergy option '-rc'. 'PASSWORD:PLAIN' allows one to specify a password directly in the SERVER.txt file. 'TEMPDIR' specifies the temporary directory to be used by the SCM tool. 'USERNAME' allows one to log into the SCM tool with a certain login name. 'XARGS' allows one to specify additional (unforeseen) arguments to the SCM tool.
The SCMTOOL property is used in the following contexts:
'SCMTOOL' => { 'NAME' => 'Subversion' }
'SITE' => 'site name'This setting is optional, but recommended.
In the 'SITE' property, the name of the site may be specified.
The 'SITE' property is used in the following contexts:
'SITE' => 'Eindhoven'
'SUPPRESSMACROEXPANSIONVIOLATIONS' => [['ruleid',]...]This setting is optional.
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.)
The 'SUPPRESSMACROEXPANSIONVIOLATIONS' property is used in the following contexts:
TICSc and
C++test on lines that contain macro expansions (C/C++ code).
'SUPPRESSMACROEXPANSIONVIOLATIONS' => ['6.7.a', '6.8.3.b']
'TOOLS' => {
['Coverity' => COVERITY,]
['eslint' => ESLINT,]
['flake8' => FLAKE8,]
['gradlew' => GRADLEW,]
['Javac' => JAVAC,]
['luacheck' => LUACHECK,]
['luac' => LUAC,]
['pylint' => PYLINT,]
['Qac' => QAC,]
['ReSharper' => ReSharper,]
['Roslyn' => ROSLYN,]
['ScanBuild' => SCANBUILD,]
['Simulink' => SIMULINK,]
}
Some tools require additional configuration. This can be added to a
tool-specific subsection of the TOOLS section.
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).
See the tool-specific sections for examples.
'TQIVERSION' => 'version'
This setting is optional. The default TQI version is TICS version specific.
TICS controls which TQI version should be used by the viewer to compute the TQI. Each time an analysis is performed, TICS puts the TQI version that should be used for that analysis in the database.
The TQIVERSION setting was introduced to control which TQI
version is put in the database each time a new analysis is performed. The
setting was introduced in TICS 9.0, which is the first version to support the
Security base metric, as used by the TQI 4.0 definition. In the
standard configuration, TICS is capable of measuring the Security metric, but
this is not part of the TQI yet. If you want to configure the Security
metric, you can use this setting to see Security in your TQI score by setting
the value to 4.0.
This setting can be applied on global or project level. Admissable values are
3.11 and 4.0.
The 'TQIVERSION' is used by TICS and stored with the run in the database. The viewer uses this value to determine which TQI formulas to use when computing the (aggregated) TQI values.
'TQIVERSION' => '4.0'
'VSBUILDRELATIONSSLNROOT' => 0|1This setting is optional; the default is 1.
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.
The VSBUILDRELATIONSSLNROOT property is used in the following contexts:
'WEBSERVER' => {
'MERGEKEY' => 'unique name to use when synchronizing files (optional)'
'PORTALURL' => 'URL of the TICS viewer, including section',
'SHOWANNOTATEDSOURCES' => 0 or 1,
'TICSENV' => location of the TICS configuration on the build server (automatic),
'TIMEOUT' => maximal time in seconds to wait for web server responses (optional; default=120),
},
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.
'WEBSERVER' => {
'PORTALURL' => 'http://www.company.com:42506/tiobeweb/TICS',
'SHOWANNOTATEDSOURCES' => 1,
}
This property is mandatory and lets the TICS tools know where the TICS Viewer is hosted.
It should point to the public URL on which the viewer can be reached, including the section name,
e.g.: 'PORTALURL' => 'http://www.company.com:42506/tiobeweb/TICS'.
It is used in the following contexts:
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.
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.
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:
TICSServer-MERGEKEY.cfg file, located in the
TIOBEPortalData/settings directory on the web server.
TICSServer-MERGEKEY.cfg file.
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".
'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.