One of the most common use cases for the TICS client is to use it to check whether code contains any violations.
For example, the following command allows you to check Coding Standards violations on /dev/myproject within the context of the TICSQServer project MYPROJECT:
TICS -project MYPROJECT -calc CS /dev/myproject
There are multiple ways to run this command. This can either be done via the command line, or via the IDE integration. For the command line, use the command as given above; for the IDE integration, check for your specific plugin how to do this.
The output in the console should look something like this:
/dev/myproject/sourcefile.c(100): The goto statement shall not be used. C Coding Standard item 6.8.6.1.a (Category: Statements and Blocks, Level: 6) The goto statement shall not be used.
This points out violations in the source code, which is a way to find (and resolve) defects in the local source code before committing it to a SCM repository.
It is possible to pass a (potentially auto-generated) file list to TICS containing the list of files that you wish to analyze. Since this file list might be automatically generated as well, the FILEFILTERS functionality is still used to filter the file list for files that may not be under version control, are automatically generated, or in some other way excluded from TICS analysis.
The contents of the file list need to meet the following requirements:
UTF8
encoding. If this is not the
case, TICS is unable to read the file list.LF
or CRLF
as line separators.
To give an example, these are the contents of the filelist
my-filelist.txt
. Note how the files are separated and that no
quotation marks are necessary.
C:/Working Directory/project/source_code.py C:/Working Directory/project/check_for_violations.py C:/Working Directory/project/coding_standards.py
This file list can then be passed to TICS on the command line. Note the
@
in the argument, marking that TICS needs to look at the contents
of the file to generate its analysis scope:
TICS -project MYPROJECT -calc CS @my-filelist.txt
There are various options available for fine-tuning the set of files that you are analyzing with TICS. You can also use data from the source control management and from your TICS database to better match up to the files that have been changed (and are therefore likely interesting to run a TICS analysis on). Some options you can use are:
-changed
: only analyze the files that are changed
according to the TICS database-checkedoutonly
: only analyze the files that are checked out
according to the SCM tool. In the case the SCM tool doesn't use the
'checked out' concept, then this check is instead done on whether a file has
changed according to the SCM tool.-ignorefilters
: analyze all files passed to TICS
regardless of FILEFILTERS
status, SCM status, or code type.
For instance, if you want to analyze a directory of files, and only want to analyze those that have uncommitted SCM changes, you can use the following command line:
TICS -project MYPROJECT -checkedoutonly -calc CS /dev/myproject
With different arguments to the -calc
argument, it is possible to
run the TICS client for a variety of metrics. See the
list of supported metrics for
all possibilities to pass to the TICS Client.
It is also possible to define a set of fast metrics to run for the
client. Using this option makes it easy for developers to do a quick check on
their code for maximum efficiency. This can be done by using the FAST
option for the command line:
TICS -project MYPROJECT -calc FAST /dev/myproject
See the METRICALIASES
configuration option for how to set a custom set of FAST
metrics.
The recommended way to show changes in your violations is to make use of the
-viewer
option. This will give you a link to the TICS Viewer,
which visualizes your code changes in a delta overview. In this overview you
can easily see changes in your violations. See
this page for a more detailed overview of the
Client Viewer functionality.
-calc GATE
. You don't need to set -viewer
in that case.
There are also various other command line options which allow you more extensive control over which violations TICS will show you. These options can be found at the list of TICS client options for command line usage, or can be set via the TICS Configuration Tool.
A small selection of options that can be used for controlling your output on the command line, or in your IDE:
-shownew
: set extra annotations if the violations are new
compared to the last successful TICSQServer analysis.-showresolved
: set extra annotations on violations that were
resolved compared to the last successful TICSQServer analysis.-deltaonly
: only show violations that are new compared
to the last successful TICSQServer analysis (compare with
-shownew
, which annotates new violations extra, but also shows
unchanged violations).-showsuppressions
: also show violations in the source code that
have been suppressed.
To give an example, if you are running with the -shownew
option,
then TICS will show the following annotation on any violations that are
new compared to the current state of the TICS database:
/dev/myproject/sourcefile.c(100): [***NEW***] The goto statement shall not be used. C Coding Standard item 6.8.6.1.a (Category: Statements and Blocks, Level: 6) The goto statement shall not be used.
Organizations may have a quality gate
in place to make certain that no changes can be made that seriously degrade the
quality of the code. This quality gate will be triggered on any code changes,
either commits or branch merges. Via the Client Viewer
functionality, it is possible to do a local check whether the changes
in the source code meet the quality gate by adding the -calc GATE
option:
TICS -project PROJECT_WITH_QUALITY_GATE -calc GATE ~/branchdir/subdir
This will run the TICS client on the project for the metrics that are contained within the client viewer quality gate.
If a project is passed to TICS for a violation metric, it is possible for TICS to evaluate a delta. For instance, let's take the basic invocation of the TICS Client:
TICS -project MYPROJECT -calc CS /dev/myproject
Since a project is passed, the TICS Client can use database information of previous runs for this project. So then it is possible for TICS to define a predecessor of your source files (if one exists). This predecessor should then match the last version of your source files that has been analyzed by TICS. TICS makes use of the configured source control tool to find which was the last analysis done on the previous version of the source code.
Alternatively, the predecessor to make a delta with can be set by the option
-delta
and an SCM tag from your SCM setup, like this:
TICS -project MYPROJECT -calc CS -delta [SCMTAG] /dev/myproject
Having determined a predecessor, TICS will then run an analysis for the metrics passed via -calc or -recalc options. This analysis can then be compared to the violations that TICS has stored in the database for the predecessor. TICS will then show you the delta with the previous version of your code as well as the violations that have been found in the current version. This allows you to get an easy overview of whether local changes have resolved violations that existed in previous versions, or introduced new violations.
It is possible to suppress individual violations. Suppressing a
violation can be done by using special comments in the code. These
special comments start with //TICS
or
/*TICS
. A space is allowed after the comment marker. Example:// TICS
or /* TICS
.
After the preceding //TICS
or
/*TICS
one can specify
what rules are suppressed by means of a sequence of
-ruleid
statements. E.g.
//TICS -OBJ_16 -DCL_12 // TICS -OBJ_16 -DCL_12
The rules specified in the TICS violation suppression comment are
suppressed for the remainder of the file, starting at the line that
contains the comment. The comment has file scope, i.e., it will not
apply to included files or enclosing files. It is allowed to use
wildcards to specify rules. To switch on a rule again, one can use
"+ruleid
" statements. It is also possible to
suppress a rule of only one specific source line. This is possible with
the option "!ruleid
". Anything past whitespace
or past either one of the special characters : , \
is treated as a comment.
The following example shows how this facility can be used in practice.
//TICS -OBJ_?: TODO still need to be fixed after discussion // MainFrm.cpp : implementation of the CMainFrame class // #include "stdafx.h" #include "test.h" #include "MainFrm.h" #ifdef _DEBUG #define new DEBUG_NEW //TICS !OSD_3: AppWizard generated code #undef THIS_FILE static char THIS_FILE[] = __FILE__; #endif ///////////////////////////////////////////////////////////////////////////// // CMainFrame IMPLEMENT_DYNAMIC(CMainFrame, CMDIFrameWnd) //TICS -*: AppWizard and ClassWizard generated code BEGIN_MESSAGE_MAP(CMainFrame, CMDIFrameWnd) //{{AFX_MSG_MAP(CMainFrame) // NOTE - the ClassWizard will add and remove mapping macros here. // DO NOT EDIT what you see in these blocks of generated code ! ON_WM_CREATE() //}}AFX_MSG_MAP END_MESSAGE_MAP() //TICS +*
IMPORTANT NOTES
The TICS client now also supports running for Abstract Interpretation and Security. Since Abstract Interpretation and Security are metrics which can potentially use more than the input set of the client, this analysis comes with the following limitations:
-project MYPROJECT
argument, or finding the correct project from
your source control management via -project auto
.
This is because the TICS Client will also need to know the
context in which source files reside for deep flow analysis. Finding issues may
need to cross file boundaries, so TICS will also need to know what other files
are in this context.If all the aforementioned requirements are in place, you can run the TICS Client for AI and Security in the same way you would run it for Coding Standards or Compiler Warnings:
TICS -project MYPROJECT -calc AI,SEC /dev/myproject