TICS Administration Guide

PROJECTS.yaml Reference Guide

The project specific TICS configuration is stored in the PROJECTS.yaml file. For global settings and a description of the YAML syntax, see the SERVER.yaml documentation.

The PROJECTS.yaml file is an essential part of any TICS configuration. For an overview of other files found in the configuration, please see here.

Syntax:

  project:
    VIEWS:
      [branch name:
        [ENV:
          [environment variable: value]+
        ]
        [PREPARE: script in cfg dir]
        [SCMPROJECTNAME: name of project in CM system]
        [UNITTESTCOVERAGE:
          RESULTDIR: dir with test coverage results
        | RESULTURL: url with test coverage results
        | RESULTZIP: zip with test coverage results
        ]
        [INTEGRATIONTESTCOVERAGE:
          RESULTDIR: dir with test coverage results
        | RESULTURL: url with test coverage results
        | RESULTZIP: zip with test coverage results
        ]
        [SYSTEMTESTCOVERAGE:
          RESULTDIR: dir with test coverage results
        | RESULTURL: url with test coverage results
        | RESULTZIP: zip with test coverage results
        ]
        [TOTALTESTCOVERAGE:
          RESULTDIR: dir with test coverage results
        | RESULTURL: url with test coverage results
        | RESULTZIP: zip with test coverage results
        ]
        [TOOLS:
          [Coverity:
            PROJECT: project name
            [BRANCHDIR: The branchdir that is used for the Coverity analysis]
          ]
        ]
      ]+
    ]
    [ARCHIVEGEN: ARCHIVEGEN]
    [AUTHENTICATION: AUTHENTICATION]
    [BUGTRACKER: BUGTRACKER]
    [BUILDTOOLS: BUILDTOOLS]
    [DATABASE: DATABASE]
    [EMAIL: EMAIL]
    [FILEFILTERS:
      [ARCHIVE: ARCHIVE]
      [ARCHIVEFILTERS: [
        [
            TYPE: INCLUDE
            KIND: DIR
            RHS: directory
          ]+
      ]]
      [CONTENT: CONTENT]
      [CODETYPE: CODETYPE]
      [USEGLOBALARCHIVE: [0|1]]
    ]
    [GROUP: project group]
    [INCLUDERELATIONCONTINUEOUTSIDEARCHIVE: INCLUDERELATIONCONTINUEOUTSIDEARCHIVE]
    [LANGUAGES:
      [FANOUT: FANOUT]
      [GENERATED: GENERATED]
      [RULESETS: RULESETS]
    ]
    [METRICS: METRICS]
    [NOTIFICATIONS: NOTIFICATIONS]
    [ORGANIZATION: ORGANIZATION]
    [ORGVIEW:
      NAME: organizational view custom module name
    ]
    [POSTQDB: POSTQDB]
    [PREPARECLIENT: PREPARECLIENT]
    [PREPAREQDB: PREPAREQDB]
    [RECALC: RECALC]
    [SANITY: sanity trigger]
    [SCMTOOL: SCMTOOL]
    [SITE: SITE]
    [SOAKTIME: SOAKTIME]
    [TOOLS: TOOLS]
    [WEBSERVER:
      [SHOWANNOTATEDSOURCES: [0|1]]
      [SHOWEXTERNALSOURCES: [0|1]]
    ]

Description

Properties are specified per project. The project property is the name of the project. This corresponds with the database name.

The PROJECTS.yaml file is mandatory and should contain at least one project with one branch name.

VIEWS

VIEWS contains the branch specific configuration. The branch name corresponds with the logical/symbolic name of a particular branch that is checked by TICS , e.g. trunk. More than one branch name can be specified per project. This makes it possible to check multiple branches of one project. Branches of a project typically have a large common code base with lots of files that are the same for multiple branches. When put into one project, such a file is analyzed only once (when it is not modified) instead of for each branch separately.

The branch name should be a string referring to the name of the branch as communicated within the organization and/or as used in the SCM repository, e.g., trunk, main, version 1.0. This name is the branch name that is shown in the TICS viewer.

The " # % () , : <> ? \\ | characters are considered illegal and should not be part of a branch name.

ENV can be used to set environment variables specific to a branch.

PREPARE is used to run a script each time the environment needs to be set up, e.g., to set network drive mappings or define environment variables. This makes it possible to have multiple branches mapping to the same Windows drive. The script gets the project name as first argument and the branch directory as second argument. The script will be looked up in the TICS configuration directory on the Web Server. The script is only executed by the server application TICSQServer.

In case both ENV and PREPARE are specified for the same branch, variables set in PREPARE override the same variable set in ENV.

RESULTDIR can be set if the testcoverage result files are located in another directory than the branchs workarea. TICS will search for testcoverage result files within the whole tree beginning at the specified RESULTDIR.

The RESULTURL property can be used instead of the RESULTDIR property. The url should point to a zip file containing all test coverage results. Before the test coverage is calculated, the zip file is downloaded and extracted in a temporary directory. When authentication is needed to access the url, a user name and password can be configured with the USERNAME and PASSWORD:PLAIN property.

The RESULTZIP property can be used instead of the RESULTDIR property. The value should point to a zip file containing all test coverage results. Before the test coverage is calculated, the zip file is extracted in a temporary directory.

SCMPROJECTNAME is needed for the automatic SCM update, in case the SCM update requires a custom name that cannot be derived automatically. This option is currently only supported for CMSynergy.

Context

The project configuration is used in the following contexts:

TICS when used with -project: to determine of the argument given is an existing project; to find the file analyzed by TICS in the quality database; for calculating the deltas between violations in the database and the current analysis.
TICSQServer to determine the root of the project, based on the name of the project given as argument.
TICSQServer to determine all projects available and run on each project.

Example

---
project1:
  VIEWS:
    trunk: {}
    branch_1.0: {}
project2:
  VIEWS:
    trunk: {}

FILEFILTERS

Property FILEFILTERS lists zero or more so-called file filters. File filters limit the scope of the archive.

The following file filters are available.

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.
ARCHIVEFILTERS: Archive filters are a less cryptic (but less powerful) way to list those directories that are included in the archive (meaning: anything not listed is not included).
CONTENT: This property refers to so-called content filters relative to the configuration directory. This property can be used to exclude files from the TICS archive based on their copyright statement or other content that is typically present at the start of a file: copyright statement, generator headers, file identification. See FILEFILTERS for more details on content filters.
USEGLOBALARCHIVE: This property specifies whether to use both the archive file at the global level (the one specified in the SERVER.yaml file - for more information see FILEFILTERS) and the project-specific archive file. It can be either 0 or 1, and is set to 1 by default. In case it is set to 0, the global archive file will not be used in calculation of the archive expression for this project.

Beside the file filters listed above, the following defaults apply as well.

Only files that have a source or header file extension specified by the LANGUAGES section in the SERVER.yaml are accepted. Files that are considered to be makefiles are exempt from this rule.
Only files that are under SCM control are accepted, provided that the SCM property has been set.

File filters are applied consecutively. Each additional filter further narrows the result set.

GROUP

GROUP can be used to group projects together in the viewer: projects with the same GROUP value are put in the same project group. When you define at least two different groups, the viewer will open by showing the project groups rather than the projects by default. It is possible to define nested project groups by using forward slashes (/).

ORGVIEW

With the ORGVIEW property it is possible to configure a custom module for the organizational view configuration files. Such a module is called TICSOrgViewCfgXXX and should implement the following functions:

sub GetOrgFile ($) : Protected;
sub GetOrgMapFile ($) : Protected;

This makes it possible to generate an organizational view on the fly. Or read the organizational view from another location than the TICS configuration directory.

SANITY

SANITY is used to set the trigger on the number of files that would have been added/removed during the database update phase. By default this is set to 200. This means that if more than 200 files are added to or removed from the database a fatal sanity check error is raised. The reason for this is that it is very unusual for an archive to add or remove such a large number of files, and this is usually indicative of a (configuration) problem. Note that it is also possible to specify this property in the SERVER.yaml at top level.

WEBSERVER

SHOWANNOTATEDSOURCES enables or disables showing annotated source code in the web viewer for the specific project. See SHOWANNOTATEDSOURCES for more information.

SHOWEXTERNALSOURCES enables or disables showing external source code in the web viewer for the specific project. See SHOWEXTERNALSOURCES for more information.