Configuration files

A configuration file is analogous to a .travis.yml file. It describes how a C or C++ project should be analyzed with TrustInSoft Analyzer.

It also allows to configure the analysis by defining the list of source files to analyze or by setting any other options of the analyzer (such as the slevel).

It is recommended to use the suffix .config (such as tis.config) for the configuration files in order to be automatically recognized and selected in the GUI. However, any filename can be used for a configuration when using the -tis-config-load <filename> option.

See the section Syntax to know how to write a configuration file.

Analysis configurations

A single configuration file can describe one or several analysis for the same project. These descriptions are called analysis configurations.

By default, the first analysis configuration of the file is used. This behavior can be changed with the option -tis-config-select <n> where <n> is the n-th analysis configuration in the file (starting at 1).

In the GUI, if the selected configuration file has several analysis configuration, a second field will be displayed to allow the user to select another analysis configuration.

Analysis configuration selection in the GUI

Tip

An analysis configuration can also be selected by its name thanks to the -tis-config-select-by-name command line option.

Syntax

The configuration file is written in JSON, according to the ECMA-404 standard, with a syntax extension for comments. The syntax extension allows the following comments syntax:

  • // will ignore the end of the line
  • /* will ignore all characters until the next */

Caution

Conforming to the ECMA-404 standard, objects are lists of name/value pairs and the names are not required to be unique.

Moreover, the ordering of the name/value pairs is significant for configuration files.

A configuration file is a list (i.e. a JSON array) of analysis configurations. An analysis configuration is represented as a JSON object where each option is a pair “name/value” of this JSON object:

[
  // analysis configuration 1
  {
    "option1": <value_of_option1>,
    "option2": <value_of_option2>,
    ...
  },
  // analysis configuration 2
  {
    "option2": <another_value_of_option2>
  },
  ...
]

If your configuration file contains only one analysis configuration, it can also be directly written without the top-level JSON array:

{
  "option1": <value_of_option1>,
  "option2": <value_of_option2>,
  ...
}

Tip

A configuration file included with the special option include must contain only a single analysis configuration.

Loading an analysis configuration

When loading an analysis configuration, the options described in the configuration will be set in the analyzer. The evaluation order is done from left to right and options are set according to this evaluation order.

Some options defined in a configuration file can also be set by the command line or by the GUI. In this case, the following rules are applied:

  • If the option has a simple type (string, boolean, number), then any previous value (set by the command line or the GUI) is overwritten.
  • If the option has a list type, then the value from the analysis configuration is concatenated at the end of the list of any previous value set by the command line or the GUI.
  • If the option has a collection type (set, map, …), then the value from the analysis configuration is merged with any previous value set by the command line or the GUI. This behavior can be disabled by adding the -@all keyword at the beginning of the value (see also Options with set/list type argument and Options with map type argument).

See also the List of options about the type of each option.

Example:

$ cat tis.config
{ "main": "my_main",
  "val-slevel-merge-after-loop": [ "-@all", "f" ],
  "slevel-function": { "f": 10 } }

$ tis-analyzer \
    -main foo \
    -val-slevel-merge-after-loop "main,foo" \
    -slevel-function "main:50" \
    -tis-config-load tis.config

In this example, the analysis is performed with the following options:

  • main: my_main
  • val-slevel-merge-after-loop: f
  • slevel-function: main:50 and f:10

Changing the analysis configuration

When another analysis configuration is loaded, before being loaded, the previous one needs to be reset.

When an analysis configuration is reset, any value set by the configuration is reverted to its previous value as if the analysis configuration was never loaded. However if a value has been changed after loading the analysis configuration by using the GUI or anything else, then this updated value will not be reset.

Then, once the previous analysis configuration is reset, the new one is loaded with the same rules as described in Loading an analysis configuration.

Downloading the current configuration

In the GUI, the current configuration can be downloaded with the button at the right of the Help button (see the above screenshot).

The downloaded configuration file contains the values of all options.

Unset options (or options with their default values) are not saved in the configuration file.

Caution

Some options, such as the list of files, require the Parsing or Value Analysis to be run in order to be correctly synchronized with the current analysis.

It is recommended to download the configuration file when both of the Parsing and Value Analysis buttons of the Overview panel are not notifying that some parameters are out-of-date.

Tip

In the downloaded configuration file, some options values are made explicit. For instance, the files options always contains the explicit list of files instead of the “all” value even if it matches the same list of files.

Path in analysis configurations

Some options in the analysis configurations can contain path to files, such as the options files or cpp-extra-args (when a -I <dir> is given for example).

Every relative path detected in these options is relative to the directory containing the configuration file, except when the analysis configuration has the special option prefix_path.

In that case, if the prefix_path value is an absolute path, then the detected relative paths are relative to the prefix_path. Otherwise, the resolved relative path is relative to <directory of the configuration file>/<prefix_path>

All absolute paths detected are left unchanged.

List of options

Option name

  • Description: This option allows to give a name to the analysis configuration. This name is used in the GUI field to select the analysis configuration if the configuration file contains several ones, which can be more convenient than its number.

    The name can also be used to select an analysis configuration from the command line with the -tis-config-select-by-name option.

    The given name is cosmetic and has no impact on the performed analysis.

  • Type: string

Option files

  • Description: The list of files to analyze. Can also accept the value “all” to select all the source files contained in the directory of the configuration file. If this field is set in a configuration file, all other source files given on the command line will be ignored.

    Examples:

    { "files": "all" }
    
    { "files": [ "src/aes.c", "main.c" ] }
    
    { "files":
      [ { "name": "src/aes.c",
          "cpp-extra-args": "-I include -D ARG=2" },
        "main.c" ] }
    

    Note: Use the compilation_cmd field to add extra arguments to the pre-processor command for every file.

  • Type:

    • string among the following values:

      • “all”
    • list of:

      • strings

      • objects with fields:

        • name (required): The name of the file.

          Type: string

        • cpp-command (optional): The command to use to pre-process the file. See also the -cpp-command-file command line option. Beware: relative paths in this field are kept unchanged (and are relative to the analyzer working directory and not the configuration file directory). The special option prefix_path does not affect paths of this field either. Use the cpp-extra-args field instead for options involving a path.

          Type: string

        • cpp-extra-args (optional): The extra arguments to add to the pre-processor command for the file. See also the -cpp-extra-args-file command line option. however only relevant options for pre-processing are kept. Relative paths are affected by the directory containing the configuration file and the prefix_path field.

          Type: string

Option filesystem

  • Description: The virtual file system and its options to use for the analysis. See also tis-mkfs Manual. If the object of this field does not contain a "files" or "use", and if "enabled" is set to true, then a default empty filesystem is used.

  • Type: object with fields:

    • enabled (optional): If enabled, the virtual file system is used during the analysis. If the feature is disabled, it can still be enabled later from the GUI. Default true

      Type: boolean

    • system_errors (optional): If set, system errors are simulated while accessing the file system. Default: value of the option -fs-error

      Type: boolean

    • files (optional): The list of files in the virtual file system. This list can be empty. This field is not compatible with the "use" one.

      Type: list of:

      • strings

      • objects with fields:

        • name (required): Name of the file (or directory) in the virtual file system. It should exactly match the string given to the filesystem functions in the C code.

          Type: string

        • type (optional): Type of the abstract file. This field is incompatible with "from", "size", "min_val" and "max_val". The supported files are regular files, directories, named pipes and character devices. If this field not given, as well as the "from" or "size" field, the default type of the file is a regular one.

          Type: string among the following values:

          • “chr”
          • “dir”
          • “fifo”
          • “file”
        • from (optional): If given, the content of the file (or directory) in the virtual file system will be the one of the real file located at the given path. If not given, the content of the file (or directory) will be abstracted. See more at File Generation. Note: if given, this filename is relative to the configuration file directory (unless the filename is absolute), and also depends on the special option prefix_path.

          Type: string

        • size (optional): First argument of the -generic option of tis-mkfs. It represents the size of the file. See more at File Generation. This field is not compatible with "from". Fields "min_val" and "max_val" are also required if this one is given.

          Type: integer

        • min_val (optional): Second argument of the -generic option of tis-mkfs. It represents the minimal value of the interval for each character of the file. See more at File Generation. This field is not compatible with "from". Fields "size" and "max_val" are also required if this one is given.

          Type: integer

        • max_val (optional): Third argument of the -generic option of tis-mkfs. It represents the maximal value of the interval for each character of the file. See more at File Generation. This field is not compatible with "from". Fields "size" and "min_val" are also required if this one is given.

          Type: integer

    • nb_max_files (optional): The maximum number of files that can be created by the program during the analysis. This field is relevant only if the "files" is given. Default: 20

      Type: integer

    • nb_max_dirs (optional): The maximum number of directories that can be created by the program during the analysis. This field is relevant only if the "files" is given. Default: 20

      Type: integer

    • generated_filename (optional): The name of the generated C file containing the virtual file system. This field is relevant only if the "files" is given. Note: if given, this filename is relative to the configuration file directory (unless the filename is absolute), and also depends on the special option prefix_path. Default: "tis-mkfs-filesystem.c"

      Type: string

    • use (optional): Name of a tis-mkfs generated C file to use instead of a list of files. This field is not compatible with the "files" one. Note: if given, this filename is relative to the configuration file directory (unless the filename is absolute), and also depends on the special option prefix_path.

      Type: string

Option language

  • Description: The language to use for the analysis.

    Setting a language allows to automatically set a list of options to correctly analyzing the program according to the given language.

    The language is set after any other options of the configuration file, hence the list of options set by this language cannot be overwritten by a field of the configuration file.

    The auto value allows to decide which language to use according to the given list of source files.

    Note: If this field is not given, the behavior is the same as the auto value.

    Note: The automatic detection of the language is only performed if a configuration file is read. Using the analyzer with the command line without a configuration file will not perform the automatic detection of the language.

  • Type: string among the following values:

    • “auto”
    • “c”
    • “c++”

Option prefix_path

  • Description: This option allows to prefix all filenames with the given path.

    { "prefix_path": "path/to/another_directory" }
    
    • If the prefix_path option is not specified in the configuration file, by default, all relative filenames are relative to the directory containing the configuration file.
    • If the prefix_path option is given with an absolute path (which is not recommended), all relative filenames are prefixed by this path.
    • If the prefix_path option is given with a relative path, all relative filenames are prefixed by <directory containing the configuration file>/<prefix_path>

    Tip

    If the value of the option files is all, then only files located in the given prefix_path are selected.

    For instance, the following configuration file:

    {
      "files":
        [
          "src/dir/file1.c",
          "src/dir/file2.c"
        ],
      "cpp-extra-args": "-DFOO=4 -Isrc/dir/headers"
    }
    

    is equivalent to this one:

    {
      "prefix_path": "src/dir",
      "files":
        [
          "file1.c",
          "file2.c"
        ],
      "cpp-extra-args": "-DFOO=4 -Iheaders"
    }
    
  • Type: string

Option include

  • Description: An analysis configuration also allows the usage of the option include in order to load other configuration files, which must contain only a single analysis configuration each.

    { "include": "path/to/another_configuration_file.config" }
    

    For each option in the included configuration:

    • If the option has not been declared before the special option include, it will be added to the main configuration.
    • If the option has already been declared before the special option include:
      • If the option’s type is a list of values, the value of the option in the included configuration will be concatenated to the existing one in the main configuration.
      • Otherwise, the value of the option in the included configuration will replace the value in the main configuration.

    For any option declared after the include option in the main configuration, the value of the option will either be added, be concatenated or will replace the one declared in the included configuration by following the same rules as above.

    The following two analysis configurations:

    {
      "files": [ "test.c" ],
      "slevel": 150,
      "include": "dir/other.config",
      "val-stop-at-nth-alarm": 8
    }
    
    {
      "files": [ "other.c" ],
      "slevel": 10,
      "val-stop-at-nth-alarm": 4
    }
    

    are equivalent to this single analysis configuration:

    {
      "files": [ "test.c", "dir/other.c" ],
      "slevel": 10,
      "val-stop-at-nth-alarm": 8
    }
    

    Several configuration files can be included with a single include option.

    {
      "include":
        [
          "path/to/sub_config1.config",
          "path/to/sub_config2.config",
          "common/common.config"
        ]
    }
    

    In this case, the first configuration file to include is processed according to the above rules. Then the resulting configuration will be considered as the main one for the second configuration file to include, and so on…

  • Type:

    • string
    • list of strings

Command line options

The command line options allowing to tune the analyzer can also be given in the configuration file. The command line option name needs to be written without the leading dash - (such as slevel-function instead of -slevel-function).

Caution

The command line options involving a special action at the start of the analyzer (-load, -add-path, -save, -tis-config, …), options involving an action which prematurely terminates the analyzer (-dump-cmdline, …), project-related options (-set-project-as-default, …), and sequencing options (-then, -then-on, …) are not supported in configuration files.

Options with simple type argument

Any command line option taking none, an integer or a string as argument can be written with respectively a boolean, an integer or a string JSON value.

Example: The following command line

tis-analyzer -val -slevel 100 -main my_function

is equivalent to the following analysis configuration

{
   "val": true,
   "slevel": 100,
   "main": "my_function"
}

When defining such an option, any previous value bound to this option is overwritten by the new defined one, including the value given on the command line if any.

Tip

The hexadecimal representation for integer options can also be used with the following syntax:

{ "slevel": "0x100" }

Options with set/list type argument

Any command line option taking a set or a list of values as argument, with the support of categories if available, can be written with a list of JSON values.

When defining such a set option, the newly defined value is merged with any previously defined value, including the ones given on the command line.

In the case of a list option, the newly defined value is concatenated at the end of the previous value, including the ones given on the command line too.

Tip

For set options, as specified in documentation of command line options, the keyword "-@all" can be used to remove any previous value of the set.

This keyword is not available for list options.

Example: The following command line

tis-analyzer
  -cpp-extra-args=-Iinclude/
  -cpp-extra-args=-DFN(a\,b)=my_function(a\,b)
  -val-slevel-merge-after-loop "@all,-main"

is equivalent to the following analysis configuration

{
   "cpp-extra-args":
     [
       "-Iinclude/",
       "-DFN(a,b)=my_function(a,b)"
     ],
   "val-slevel-merge-after-loop":
     [
       "@all",
       "-main"
     ]
}

Note: With the command line, any , in the values needs to be escaped to prevent it to be interpreted as a separator for the list/set. Escaping such commas is not required in a configuration file.

Tip

The brackets ([ and ]) can also be omitted if the value of the option contains only one element. Also the same option can be given several times in a same analysis configuration.

Hence, the two following configurations are equivalent:

{ "cpp-extra-args":
    [ "-Iinclude/",
      "-DFN(a,b)=my_function(a,b)" ] }
{ "cpp-extra-args": "-Iinclude/",
  "cpp-extra-args": "-DFN(a,b)=my_function(a,b)" }

Options with map type argument

Any command line option taking a map (also known as dictionary) as argument can be written with a JSON object where:

  • the keys of the map are the field names of the JSON object,
  • and values of these keys are the value of the JSON object (associated to their respective field).

When defining such a map option, the newly bindings defined are merged with any previously defined bindings in the map, including the ones given on the command line.

A binding of the map can be removed from the map by using the value null with the key of the binding as the object field.

If a key is associated to several values, the last defined value overwrites all the previously defined one.

Tip

The binding "-@all": true can be use to remove any binding previously defined in the map.

Example: The following command line

tis-analyzer
  -slevel-function "f:100,g:50,h:56,main:42"
  -slevel-function "f:110,-g"

is equivalent to the following analysis configuration

{
  "slevel-function":
    {
      "f": 100,
      "g": 50,
      "h": 56,
      "main": 42,
      "f": 110,
      "g": null
    }
}

Note: With the command line, any , in the keys or values needs to be escaped to prevent it to be interpreted as a separator for the list/set. Escaping such commas is not required in a configuration file.

Examples

A basic example compliant with a simple C project:

{
  "files": "all",
  "machdep": "gcc_x86_64",
  "val-stop-at-nth-alarm": 1
}

More advanced examples:

{
  "files":
    [
      "util.c",
      "tool/engine.c",
      "main.c"
    ],
  "main": "f",
  "cpp-extra-args":
    [
      "-DFOO",
      "-Itool"
    ],
  "slevel": 1500
}
{
  "files":
    [
      "crypto.c",
      "main.c"
    ],
  "slevel-function":
    {
      "main":  150,
      "encrypt": 30000
    }
 }
{
  "files":
    [
      "crypto.c",
      "main.c"
    ],
  "filesystem":
    {
      "enabled": true,
      "system_errors": false,
      "files":
        [
          {
            "name": "/home/Documents",
            "type": "dir"
          },
          {
            "name": "/home/bob/.bashrc"
          },
          {
            "name": "/usr/share/input_file.txt",
            "from": "main_input_file.txt"
          }
        ]
    }
 }