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://192.168.1.1/tiobeweb/TICS/api/cfg?name=-Here, the value
- refers to the particular configuration to be used.
If the merge key was not configured for this configuration, the value - should be used, as is the case here.
When using the legacy TICS architecture,
the configuration files are located on the File Server.
In that case the TICS environment variable does not point to a URL but a directory on the local file system or network share.
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.
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.
lib:
Contains libraries needed by TICS. Only used in some rare cases.
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 determines for each artifact which particular version should be used.
It has sections for the binaries, checkers, and rules.
A very simple example config.yaml:
format: 1
versions:
checkers:
cpptest:
artifact: /chk/cpptest-2021.1.0-win32.x86_64.zip
Roslyn:
artifact: /chk/roslyn-43282-win-x64.zip
rules:
cpptest:
artifact: /rules/cpptest-rules-20211019.zip
ticsbin:
artifact: /bin/ticsbin-2021.3.1.12345.zip
You might also encounter version and platform properties.
These are currently purely for informational purposes and can be omitted;
only the artifact is taken into account.
In an upcoming version, these properties will be used to download artifact automatically.
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.
The links.yaml file is an optional file that you can place in an artifact directory
(e.g. bin, checkers),
and in which you can define symbolic artifact names that link to concrete artifact zip files.
Instead of referring to a concrete artifact zip in the config.yaml,
you can refer to a symbolic artifact, that will then be resolved to the concrete zip file.
This feature is useful if you have multiple configurations (and hence an equal amount of config.yaml files)
and you want to upgrade all of them to a new TICS version at once.
links: artifact name: concrete path to artifact
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"
config.yaml file.
This file contains one line referring to the directory in which the TICS binaries can be found. This may be an absolute or relative path. By changing the contents of this file, a complete TICS installation (client and server) can be upgraded at once. Examples:
../bin
//fileserver-3a/TICS6.0.3/bin
config.yaml file.
This file contains one line referring to the directory in which the TICS checkers can be found. This may be an absolute or relative path. By changing the contents of this file, the code checkers location can be changed to a shared, central location for example. Examples:
../chk
C:/ticschk