PROJECTS.txt Reference Guide

The project specific TICS configuration is stored in the PROJECTS.txt file. This file must be located in the directory pointed to by the 'TICS' environment variable. By default, on Windows, this is Program Files\TIOBE\TICS\FileServer\cfg.

The PROJECTS.txt file contains a hierarchical map of properties. Example:

{
  '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'
        },]
        ['INTEGRATIONTESTCOVERAGE' => {
          'RESULTDIR' => 'dir with test coverage results'
        | 'RESULTURL' => 'url with test coverage results'
        },]
        ['SYSTEMTESTCOVERAGE' => {
          'RESULTDIR' => 'dir with test coverage results'
        | 'RESULTURL' => 'url with test coverage results'
        },]
        ['TOTALTESTCOVERAGE' => {
          'RESULTDIR' => 'dir with test coverage results'
        | 'RESULTURL' => 'url 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,]
    ['COLLECTCLIENTSTATS' => COLLECTCLIENTSTATS,]
    ['DATABASE' => DATABASE,]
    ['EMAIL' => EMAIL,]
    ['FILEFILTERS' => {
      ['ARCHIVE' => ARCHIVE,]
      ['ARCHIVEFILTERS' => [
        [ {
            'TYPE' => 'INCLUDE',
            'KIND' => 'DIR',
            'RHS' => 'directory',
          },]+
      ],]
      ['CONTENT' => CONTENT,]
      ['EXCLUDEMANAGEDEXTENSIONS' => [0|1],]
    },]
    ['GROUP' => 'group',]
    ['LANGUAGES' => {
      ['RULESETS' => RULESETS,]
    },]
    ['METRICS' => METRICS,]
    ['NOTIFICATIONS' => NOTIFICATIONS,]
    ['ORGANIZATION' => ORGANIZATION,]
    ['SANITY' => 'sanity trigger',]
    ['SCMTOOL' => SCMTOOL,]
    ['SITE' => SITE,]
    ['TOOLS' => {
      ['Coverity' => COVERITY,]
      ['Javac' => JAVAC,]
    },]
    ['WEBSERVER' => {
      ['SHOWANNOTATEDSOURCES' => [0|1],]
    },]
  }
}

Description

Properties are specified per project. The project property is the name of the project. This corresponds with the database name. 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 PROJECTS.txt file is mandatory and should contain at least one project with one branch name.

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.
EXCLUDEMANAGEDEXTENSIONS
If enabled, exclude source/header files that require so-called Managed Extensions when considering build relations.

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

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

'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 (TICS install dir/cfg). 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 branch's 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.

'GROUP' can be used to add one level of hierarchy on top of the list of projects in the viewer. The project is added to the named group. Projects without a 'GROUP' property are put in the 'Ungrouped Projects' group. Additionally, an 'All Projects' group is created that lists all available projects.

'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.txt at top level.

'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.

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

Context

The project configuration is used in the following contexts:

Example

{
  project1 => {
    'VIEWS' => {
      'trunk' => {},
      'branch_1.0' => {},
    }
  }
  
  'project2' => {
    'VIEWS' => {
      'trunk' => {},
    }
  }
}