Configuring include-what-you-use in TICS

include-what-you-use (also referred to as iwyu or Iwyu in other places in this documentation) is an open-source tool which allows you to ensure very strict checks on what you do and do not include in a C/C++ source file.

Prerequisites

For a successful include-what-you-use integration, the following prerequisites must be met:

• A Linux-based operating system.
• A functional installation of the Clang compiler. include-what-you-use is heavily tied to the internals of the Clang compiler, and requires to be using a version of the tool that is built against a specific version of Clang. In the case you are not using the correct version, TICS will throw an error (rethrown from the tool) that shows you are using the wrong Iwyu version for the Clang version that is installed.

Basic configuration

First and foremost, the include-what-you-use artifact must be made available to TICS. To do this, add the include-what-you-use artifact to config.yaml as shown in the example below. Note that different versions may apply to your situation.

versions:
  checkers:
    iwyu:
      artifacts:
      - version: '0.12'
        platform: ubuntu-clang-8

Next, include-what-you-use needs to be configured for the Fan Out and/or Coding Standards metric. Configuration for these metrics is done in SERVER.yaml.

Fan Out

To utilize include-what-you-use for the Fan Out metric, set the FANOUT property of the C and/or C++ Language to Iwyu in SERVER.yaml. Below an example for the C language:

LANGUAGES:
  C:
    FANOUT:
      TOOL: Iwyu

Coding Standard

By default, include-what-you-use is not included in any coding standard. To make use of include-what-you-use for coding standards, include-what-you-use coding standard rules have to be added to the coding standard. The applied coding standard is specified in the RULESET → RULESDIR property of the C and C++ Language in SERVER.yaml.

LANGUAGES:
  C:
    RULESETS:
    - METRIC: CODINGSTANDARD
      RULESDIR: 4.0/codingstandards/C

At this location inside you will find the coding standard configuration files IMPL.txt and RULES.txt. Add the lines depicted below to these files respectively:

IMPL.txt

IWYU-MISSING	Iwyu	IWYU-MISSING
IWYU-REMOVE	Iwyu	IWYU-REMOVE

RULES.txt

IWYU-MISSING	3	Dependency management	Header should be included directly.
IWYU-REMOVE	3	Dependency management	Superflous inclusion of header.

Using Mapping Files

A mapping file can be added in any configuration directory that will be used by TICS. This file must have the name iwyu_mapping.imp and have the specified content format. If no iwyu_mapping.imp file is present in the configuration, TICS will use a default file.

Content of Mapping Files

The contents of mapping files are better explained at include-what-you-use's own documentation. Specifically, an explanation of the contents of a mapping file can be found here: IWYUMappings