TeamCity Cloud 2024.03 Help

Inspections

The Inspections (IntelliJ IDEA) build runner is intended to run code analysis based on IntelliJ IDEA inspections for your project. In addition to the version that TeamCity automatically downloads and installs on its first startup, it is possible to install another version of JetBrains IntelliJ Inspections and Duplicates Engine.

IntelliJ IDEA's code analysis engine is capable of inspecting your Java, JavaScript, HTML, XML and other code and allows you to

  • find probable bugs;

  • locate "dead" code;

  • detect performance issues;

  • improve the code structure and maintainability;

  • ensure the code conforms to guidelines, standards, and specifications.

Refer to IntelliJ IDEA documentation for more details.

This page contains reference information about the Inspections (IntelliJ IDEA) build runner fields.

IntelliJ IDEA Project Settings

Option

Description

Project file type

To be able to run IntelliJ IDEA inspections on your code, TeamCity requires either an IntelliJ IDEA project file/directory, Maven pom.xml or Gradle build.gradle to be specified here.

Path to the project

Depending on the type of project selected in the Project file type, specify here:

  • For IntelliJ IDEA project: the path to the project file (.ipr) or the path to the project directory the root directory of the project containing the .idea directory).

  • For Maven project: the path to the pom.xml file.

  • For Gradle project: the path to the .gradle or .gradle.kts file.
    This information is required by this build runner to understand the structure of the project.

Detect global libraries and module-based JDK in the *.iml files

This option is available if you use an IntelliJ IDEA project to run the inspections. In IntelliJ IDEA, the module settings are stored in *.iml files, thus, if this option is checked, all the module files will be automatically scanned for references to the global libraries and module JDKs when saved. This helps ensure that all references will be properly resolved.

Check/Reparse Project

This option is available if you use an IntelliJ IDEA project to run the inspections. Click this button to reparse your IntelliJ IDEA project and import the build settings right from the project, for example the list of JDKs.

Working directory

Enter a path to a Build Working Directory if it differs from the Build Checkout Directory.

Optional, specify if differs from the checkout directory.

Unresolved Project Modules and Path Variables

This section is displayed when an IntelliJ IDEA module file (.iml) referenced from an IntelliJ IDEA project file:

  • cannot be found

  • allows you to enter the values of path variables used in the IPR-file.

To refresh the values in this section, click Check/Reparse Project.

Option

Description

<path_variable_name>

This field appears if the project file contains path macros, defined in the Path Variables dialog of the IntelliJ IDEA settings. In Set value to field, specify a path to the project resources to be used on different build agents.

Project SDKs

This section provides the list of SDKs detected in the project.

Option

Description

JDK Home

Use this field to specify the JDK home for the project.

JDK Jar File Patterns

Click this link to open a text area where you can define templates for the jar files of the project JDK. Use Ant rules to define the jar file patterns. The default value is used for Linux and Windows operating systems:

jre/lib/*.jar

For macOS, use the following lines:

lib/*.jar ../Classes/*.jar

IDEA Home

If your project uses the IDEA JDK, specify the location of the IDEA home directory

IDEA Jar Files Patterns

Click this link to open a text area, where you can define templates for the jar files of the IDEA JDK.

Java Parameters

Option

Description

JDK

Select a JDK. This section details the available options. The default is JAVA_HOME environment variable or the agent's own Java.

JDK home path

The option is available when <Custom> is selected above. Use this field to specify the path to your custom JDK used to run the build. If the field is left blank, the path to JDK Home is read either from the JAVA_HOME environment variable on the agent machine, or from the env.JAVA_HOME property specified in the build agent configuration file (buildAgent.properties). If these values are not specified, TeamCity uses the Java home of the build agent process itself.

JVM command line parameters

Additional JVM command line parameters allow you to set initial and maximum heap sizes, enable additional logging, select the required bytecode verifier mode, and more.

You can specify both standard (begin with -, for instance -verbose:[class|module|gc|jni] or --dry-run) and non-standard (begin with -X, for instance -Xmx<size> or -XstartOnFirstThread) JVM options.

To specify multiple command line parameters, use space as a separator. For example:

-verbose:gc -Xdiag -Xcomp -Xmx512m -Xms256m

Inspection Parameters

In IntelliJ IDEA-based IDEs, the code inspections reported are configured by an inspection profile.
When running the inspections in TeamCity, you can specify the inspection profile to use: first you need to configure the inspection profile in IntelliJ IDEA-based IDE and then specify it in TeamCity.

Follow these rules when preparing inspection profiles:

  • if your inspection profile uses scopes, make sure the scopes are shared;

  • lock the profile (this ensures that inspections present in TeamCity but not enabled in your IDEA installation will not be run by TeamCity);

  • ensure the profile does not have inspections provided by plugins not included into the default IntelliJ IDEA Ultimate distribution (otherwise they will just be ignored by TeamCity);

  • for best results, edit the inspection profile in the IntelliJ IDEA of the same version as used by TeamCity (can be looked up in the inspection build log).

The logic of selecting an inspection profile is as follows:

  • if the path to the inspection profile is specified, then the profile will be loaded from the file. If the loading fails, the inspection runner will fail too.

  • if the name of the inspection profile is specified, the profile is searched for in the project's shared profiles. If there is no such profile, the inspection runner will fail.

  • if neither the name nor path is specified, the default profile of the project is used.

Option

Description

Inspections profile path

Use this text field to specify the path to inspections profiles file relative to the project root directory. Use this field only if you do not want to use the shared project profile specified in "Inspections profile name".

Inspections profile name

Enter the name of the desired shared project profile. If the field is left blank and no profile path is specified, the default project profile will be used.

Include / exclude patterns:

Optional, specify to restrict the sources scope to run Inspections on.

Include/exclude patterns are newline-delimited set of rules of the form:

[+:|-:]pattern

where the pattern must satisfy the following rules:

  • must end with either ** or * (this effectively limits the patterns to only the directories level, they do not support file-level patterns);

  • references to modules can be included as [<IDEA_module_name>]/<path_within_module>. If you have a Maven project configured, you can use Maven module's artifactId as <IDEA_module_name>;

  • the configured paths are treated as relative paths within content roots of the IDEA project modules. That is, the paths should be relative to the module's roots.

Some notes on patterns processing:

  • excludes have precedence over includes

  • if include patterns are specified, only directories matching these patterns will be included, all other directories will be excluded

  • the include pattern has a special behavior (due to underlying limitations): it includes the directory specified and all the files residing directly in the directories above the one specified.

Example:

+:testData/tables/** -:testData/** -:testdata/** -:[testData]/**

For Maven inspections run, to ensure correct Java is used for the project JDK, define env.JAVA_HOME configuration parameter pointing to the JDK to be used as the project JDK.

Getting the same results in IntelliJ IDEA and TeamCity Inspections Build

The code inspections reported by IntelliJ IDEA and TeamCity Java Code Inspections build depend on a number of factors. You would need to ensure equal settings in IntelliJ IDEA and the build to get the same reports. The relevant settings include:

  • inspections profile used in IntelliJ IDEA and TeamCity build;

  • environment-specific project dependencies (files not in version control, and so on);

  • IDE-level settings, like defined SDKs, path variables, and so on;

  • generated files: should be present in the TeamCity agent if they are present when working with the project in IntelliJ IDEA;

  • IntelliJ IDEA version. It is recommended to use the same IntelliJ IDEA version that is used in the TeamCity build. The version is written in the Inspections build log;

  • the set and versions of the IntelliJ IDEA plugins that the project relies on.

Last modified: 15 December 2023