TICS Analyzer Configuration

A TICS Analyzer configuration is a set of files that controls how TiCS analyzes source code. It determines various aspects, such as which metrics are enabled, which source files to include, which coding standards to use, etc. This set of configuration files is located in the directory <section root>/ticsfs/cfg on the web server. It is possible to have multiple TICS configurations. In that case each configuration needs to reside in its own sub-folder and needs to have a unique identification, also called a merge key.

TiCS Environment Variable

In order for the TICS command-line tool to get hold of the configuration, you need to set the TICS environment variable to point at the following URL:

https://HOSTNAME/tiobeweb/TICS/api/cfg?name=CONFIGNAME
Here, the value CONFIGNAME refers to the particular configuration to be used. Configuration default is provided with an initial installation.

In addition to the cfg configuration directory, there are sibling folders containing different types of artifacts that TICS needs to analyze source code:

Each artifact is a uniquely named zip file containing a particular version of the artifact. When TiCS needs an artifact that does not reside in the local cache, it downloads it from the viewer, extracts it locally, and executes it from there.

Note that TiCS Viewer configuration is not part of the TiCS configuration.

Essential Configuration Files

This section describes the essential configuration files that are found in any TiCS configuration.

Config.yaml   (mandatory)

The config.yaml file declares for all tools and other artifacts the versions that should be used. It has different sections for the different types of artifacts. To automatically download an artifact from the TIOBE Artifact Registry, one should provide the version (and the platform if applicable) which can be found on portal.tiobe.com. This is only applicable for tools that are in the TIOBE Artifact Registry. An example config.yaml is as follows:

versions:
  checkers:
    TICScyclox:
      version: 47809  
      platform: linux64
  rules:
    cpptest:
      version: 46945
  ticsbin:
    artifacts:
      - version: 2022.3.1.47846
        platform: ubuntu_16.04
      - version: 2022.3.1.47831
        platform: windows
  jre:
    artifacts:
      - version: 11.0.13+8
        platform: x64_linux
      - version: 11.0.13+8
        platform: x64_windows
  wrapper:
    version: 47278

Platform-specific artifacts

It is possible to serve different artifacts based on the platform of the client requesting these artifacts. In this example you can see that we serve platform-specific artifacts for ticsbin and jre based on platform. Note that for the TiCS wrapper this is not needed because the wrappers are platform independent.

Manual artifact upload

For those artifacts that are not in the TIOBE Artifact Registry, such as Coverity, the location must be provided in artifact. You should make sure that the file that is referenced is present in the viewer-embedded repository, by uploading the file to the respective directory.

versions:
  checkers:
    coverity:
      artifact: /chk/coverity-2021.1.0-win32.x86_64.zip
versions:
  misc:
    git:
      artifact: /misc/portable-git.zip

External Artifact Repositories

By default, artifacts are served from the viewer-embedded repository. You can configure an external artifact repository in Administration Pages → Artifact Repository (see the documentation). Then you need to reference the repository's identifier in a property named repository, as follows:

repository: my-nexus-repo
versions:
  checkers:
    TICScyclox:
      version: 47809  
      platform: linux64

Omitting the repository property is the same as specifying repository: embedded, which references the built-in 'embedded' repository. You can serve different artifacts from different repositories by placing the repository at different levels in the document, referencing different identifiers. The closest ancestor determines which repository is picked.

Source Repositories

An advanced feature is to specify the repository from which an artifact should be downloaded by using the source property. Normally this is not needed: when you specify the version property for an artifact, the source repository is implicitly set to the built-in tiobe-registry. However, if you want to download an artifact from a different source because it is not (yet) available in the registry, you can do so by specifying the source and sourcepath properties. You can for instance use the built-in tics-download-site repository. After saving the config.yaml, artifacts are downloaded from the source repository to a local cache on the viewer, and then uploaded to the target repository (if the target repository allows uploading).

lic.dat   (mandatory)

This is the TiCS license file.

PROJECTS.yaml   (mandatory)

The PROJECTS.yaml is the configuration file found next to the SERVER.yaml file that contains all project specific options. For more details on the PROJECTS.yaml configuration options see the PROJECTS.yaml Reference Page.

SERVER.yaml   (mandatory)

The SERVER.yaml is the global configuration file and contains all options related to location of source code, build environments, SCM tooling, analyzers used, language mapping and some miscellaneous options. For more details on the SERVER.yaml configuration options see the SERVER.yaml Reference Page.

Other Configuration Files

This section describes configuration files that are not mandatory, are for advanced usage, or should seldom be changed by the user.

ARCHIVE.txt   (optional)

The ARCHIVE.txt is used by TICSQServer to determine what files need to be stored in the quality database. It contains boolean expressions that are evaluated against each file encountered on the file system. See the ARCHIVE Reference Page for more information on specifying the contents of ARCHIVE files. Note that the ARCHIVE.txt file doesn't need to have this name, but it is best to use this name or a variant of this such as ARCHIVE-project1.txt or ARCHIVE-project2.txt to better understand what it contains.

CanonicalPath.pm   (optional)

This file contains a redefinition of the default way TiCS calculates paths for files. Usually the TiCS way of calculating unique paths suffices, but in case there are symbolic links or other complex ways of maintaining code archives, this file may be needed.

CFGVERSION.txt   (mandatory)

This is a file that is used by TICS internally to determine whether a configuration update is needed.

TiCS<modulename>.pm   (optional)

These Perl modules overrule the default TICS Perl modules that are part of the official TICS distribution. Try to keep the number of these custom modules as low as possible.

DEFINES.txt   (optional)

For languages that require a preprocessor.

Languages that require preprocessing and have macros that can be used as functions and identifiers in source text may require that expansions of such macros be ignored by the code checker. Potential violations by such macros can be silently suppressed by specifying a line in DEFINES.txt containing the name of the macro and a list of rules that should be suppressed for occurrences of the macro.

The DEFINES.txt file contains entries of the form

macro: wildcard [wildcard]...
where
macro ::= \*?\w+\*? | /\*[^:]+\*/
wildcard ::= rule | * | rule with parts replaced by * or ?
rule ::= one of the rule IDs of the IMPL.txt

Empty lines and lines starting with // are ignored.

For macros with leading or trailing *, a suffix resp, prefix match is performed on identifiers in the source code. E.g., ENUM* matches all identifiers starting with ENUM. And *STRUCT matches all identifiers ending with STRUCT.

A macro of the form /*...*/ is a comment that is to be matched exactly to comments in the source file.

For rules, each * and ? is expanded to all matching rules.

Example
AFX_MANAGE_STATE: *
assert: *
FAILED: *
GetDlgItem: *
MESSAGE_HANDLER: *
S_OK: *
SUCCEEDED: *
USES_CONVERSION: *
WAIT_OBJECT_0: *
ENUM*: *
*STRUCT: *
/*@unused@*/: *

An include directive includes the given DEFINES file (whose path is resolved against the directory of the including DEFINES file). Its effect is the same as if the contents of that file were inserted at the location of the include directive. The file name may be enclosed by quotes (either '' or ""), but this is not required.

Example of using include statements in DEFINES files:

File DEFINES.txt:

AFX_MANAGE_STATE: *
assert: *
FAILED: *
GetDlgItem: *
MESSAGE_HANDLER: *
include DEFINES-SPECIFIC.txt

File DEFINES-SPECIFIC.txt:

S_OK: *
SUCCEEDED: *
USES_CONVERSION: *
WAIT_OBJECT_0: *
ENUM*: *
*STRUCT: *
/*@unused@*/: *

DEFINES-project.txt   (optional)

For languages that require a preprocessor.

The contents of this file has the same format as DEFINES.txt except that the contents is only taken into account for those input files that belong to the associated project. The file need not exist for a project. The project must match one of the projects from the PROJECTS property in the SERVER.yaml.

exclude-rules-<lctool>.yaml   (optional)

This is a file internally used by TiCS to avoid reporting on unconfigured rules that have been intentionally excluded from analysis.

TiCS also checks on rules that are reported to TiCS by tools, but not configured as part of a ruleset. On some occasions, it is possible that a coding rule or compiler warning is intentionally excluded from TiCS analysis. Potential reasons are because the rule is not applicable for the environment or because the rule reports a lot of false positives.

This file has the name exclude-rules-$(lctool).yaml, with $lctool the lowercase name of the tool. Its contents are an item excludedItems with a list of implementation ID's (see documentation on IMPL.txt for more details).

For example, these are the contents of a file exclude-rules-tsc.yaml which will exclude items TS2564 and TS2769 from unconfigured rules reporting:

excludedItems:
- TS2564
- TS2769

The links.yaml file is an optional file that you can place in any sub-directory of the ticsfs directory, such as bin, chk, or in the ticsfs root. Inside this file you can can define symbolic names that link to concrete files or directories inside that same directory in which the links.yaml file is located. Note that the symbolic links defined in this file are independent of the file-system's symbolic link mechanism and are related only by name.

The symbolic links feature is useful if you have multiple configurations (and hence an equal number of config.yaml files), and you want to upgrade the version of the TiCS binaries or the version of a particular checker for all configurations at the same time. To make this possible, you would create a links.yaml file inside the bin directory, with the following contents:

links:
  windows-latest: ticsbin-2021.4.1.45678-windows.zip
The config.yaml files in the respective configurations could then point to the symbolic name windows-latest instead of the concrete artifact, as follows:
versions:
  ticsbin:
    artifact: /bin/windows-latest
In order to upgrade all configurations at once, you would only have to change the value of windows-latest in the links.yaml file.

Sharing artifacts

Another feature of the links.yaml file is to share artifacts and configuration items across sections. The idea here is that you designate one primary section that will host all artifacts (TiCS binaries, checkers) and common configuration items such as a license file, rule set configurations, and custom modules. The secondary sections can then refer to the primary section to reuse these artifacts and configuration items. All maintenance on shared artifacts, such as changing custom modules, uploading a new license file, etc., must be done through the Analyzer Configuration Editor of the primary section.

To use this feature, take these steps:

ORGANIZATION_<project>.txt   (optional)

This is a file to configure so called organizational views in the TiCS viewer. More details can be found here.

ORGMAPPING_<project>.txt   (optional)

This is a file to configure so called organizational views in the TICS viewer. More details can be found here.

PREDEFINES-compiler.txt   (mandatory)

For languages that require a preprocessor.

This file contains preprocessor directives for the associated compiler. Usually, the file contains non-ANSI constructs that must be defined away, or macros, identifiers and functions that must be redefined. The compiler must be one of the compilers mentioned in one of the BUILDTYPE properties of the SERVER.yaml.

Example
#define _INTEGRAL_MAX_BITS 64
#define __ptr32
#define __ptr64
#define __w64

If the input is known to be strict standards conforming, this file may remain empty (although it must exist).

RULES/IMPL.txt (rule set definition)   (mandatory)

A RULES.txt file defines a rule set for a specific language and metric. Rule sets can be defined for the metrics Coding Standards, Compiler Warnings, Abstract Interpretation, and Security. Each RULES.txt file is accompanied by an IMPL.txt file that is put next to it in the same directory. It specifies how the particular rule set is implemented, i.e., it defines for each rule by which tool (or compiler) it is checked. In a typical configuration directory you will find multiple directories, each one containing a RULES/IMPL.txt file pair, and optionally some additional tool-specific parameterization files. The mapping of a language and metric pair to a particular rule set is controlled via the RULESDIR in the SERVER.yaml file.

Normally you do not have to change the RULES.txt or IMPL.txt files; TIOBE provides out-of-the-box rule set definitions that should suffice in most cases. In case you do need to make changes, the contents of the files are described below.

The RULES.txt file contains the rule set definition. The file format is line-based. Each line contains four fields, separated by tabs. Empty lines and lines starting with a // (a comment) are ignored. Each line specifies the following fields:

rule ID
Identifier or name of the rule.
level
Level that indicates the severity of the rule. Here 1 has the highest severity. Higher levels indicate lower severity. As many levels as desired can be distinguished (i.e., there is no hard upper limit).
category
The category to which the coding rule belongs. As many categories as desired may be defined.
synopsis
The rule's synopsis.

The RULES.txt file must at least have an entry for each rule ID occurring in the IMPL.txt file.

The IMPL.txt file map rules to a particular implementation. The file format is line-based. Each line contains three fields, separated by tabs. Empty lines and lines starting with a // (a comment) are ignored. Each line specifies the following fields:

rule ID
Name of the rule as used in the coding standard. This name must have a matching name in the RULES.txt
tool ID
The identifier of the tool (static code checker or compiler) that is used to check this rule. The name must match one of the tool names in the TOOLS property in the SERVER.yaml file.
implementation ID
The tool-specific identifier for the check that should be used to check this rule. If the rule implementation requires further parameterization, this can be specified by suffixing the field with = followed by a filename. This file is resolved against the directory in which the IMPL.txt file resides.
Note that multiple lines can refer to the same rule id, when a single rule needs to be checked by multiple tools.

Additionally, include directives are supported. An include directive includes the given IMPL file (whose path is resolved against the directory of the including IMPL file). Its effect is the same as if the contents of that file were inserted at the location of the include directive. The file name may be enclosed by quotes (either '' or ""), but this is not required. Example:

// Include the Java rules
include "../java/IMPL.txt"