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.
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=CONFIGNAMEHere, 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:
bin:
Contains the TiCS framework binaries.
chk:
Contains code checkers used by the TiCS framework.
Which particular code checker artifacts are located here depend on the programming languages you use.
lib:
Contains libraries needed by TiCS. Only used in some rare cases.
jre:
Contains Java Runtime Environment needed to run the TiCS wrappers.
misc:
Contains auxiliary artifacts used by the TiCS framework.
This folder is optional and can be used if certain tools needs to be installed automatically
during a TiCS run in case they are not yet available on the machine. For instance, in the case that you are not
certain that Git will always be installed and available on the machine where you run TiCS,
then you can put the Git binaries here.
rules:
This directory contains rule implementations, for code checkers where these are not built-in but distributed separately.
For example all rules of C++test are usually stored here as .rule files.
wrapper:
Contains TiCS wrappers.
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.
This section describes the essential configuration files that are found in any TiCS configuration.
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
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.
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
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.
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).
This is the TiCS license file.
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.
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.
This section describes configuration files that are not mandatory, are for advanced usage, or should seldom be changed by the user.
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.
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.
This is a file that is used by TICS internally to determine whether a configuration update is needed.
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.
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.
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.
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@*/: *
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.
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.zipThe
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.
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:
links.yaml file in the ticsfs root with the following contents:
links: shared: <section:TICS>Here,
<section:TICS> is a section reference to the primary section that you want to reuse from, in this case the section named TICS.
The name shared can be chosen as desired.
/shared,
which will link to the ticsfs directory inside the primary section.
For instance, in order to share the lic.dat file and custom modules that are located in the /cfg/common directory of the primary section,
you would specify the following in the SERVER.yaml of the secondary section(s):
LICDIR: /shared/cfg/common/licdir CONFIGURATION: INCDIRS: ['/shared/cfg/common/modules'] ...
This is a file to configure so called organizational views in the TiCS viewer. More details can be found here.
This is a file to configure so called organizational views in the TICS viewer. More details can be found here.
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.
#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).
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:
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).
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:
RULES.txt
TOOLS property in the SERVER.yaml file.
= followed by a filename.
This file is resolved against the directory in which the IMPL.txt file resides.
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"