# How to Set Up External Tools & Formats
# Clang Static Analyzer
The Open Source LLVM clang compiler includes a static analyzer (opens new window) that performs dataflow analysis on C/C++ code. Analysis is started using the scan-build script, which wraps the make process.
To enable output in plist format (which we require), the option -plist must be passed to the scan-build command.
Additionally, you might want to enable additional checkers using the -enable-checker command.
To obtain a list of all available checkers, run the following command:
clang -cc1 -analyzer-checker-help
Note that it is sufficient to provide a package/category to the analyzer to enable more checks. A typical invocation of the static analyzer might look like this:
scan-build -plist
-enable-checker alpha
-enable-checker core
-enable-checker cplusplus
-enable-checker deadcode
-enable-checker security
-enable-checker unix
make
To upload analysis results, you should use the external-report service as described in our article on external uploads.
# Clang-Tidy
While Clang-Tidy is integrated as an internal analysis tool, the Clang-Tidy binaries are generally not shipped with Teamscale. Our docker-image distributions contain the correct clang-tidy version, but distributions based on zip-files do not contain clang-tidy. Instead, you will need to install clang-tidy 15.0.7 (opens new window) on your machine. More details are described here.
# Cppcheck
While Cppcheck is integrated as an internal analysis tool, the Cppcheck binaries are generally not shipped with Teamscale. Our docker-image distributions contain the correct Cppcheck version, but distributions based on zip-files do not contain Cppcheck. Instead, you will need to install cppcheck-2.7 (opens new window) on your machine.
You will need to have the python 3 on the PATH to execute the MISRA checks of Cppcheck.
This is included in our docker-image distributions as well.
More details are described here.
# FindBugs and SpotBugs
FindBugs (opens new window) is an Open Source bug pattern search tool working on the byte code of Java programs. This means that in order to use FindBugs, you have to first compile the code.
SpotBugs (opens new window) is the successor of FindBugs, which is no longer maintained.
Since SpotBugs reports are compatible with the FindBugs report format, they can be uploaded with the same analysis-tool name (FINDBUGS).
To upload analysis results, you should use the external-report service as described here.
# JaCoCo
JaCoCo (opens new window) is an Open Source code coverage tool for Java. Teamscale allows to upload XML coverage reports produced by JaCoCo. Please refer to our Java test coverage guide for instructions on how to set up JaCoCo for your tests.
To upload JaCoCo coverage data, you should use the external-report service as described here.
# Cobertura
Cobertura (opens new window) is an Open Source code coverage tool for Java. Teamscale allows to upload XML coverage reports produced by Cobertura. You can generate an XML report with the Cobertura Ant task cobertura-report by setting the parameter format to xml as follows:
<cobertura-report format="xml"
destdir="${coveragereport.dir}"
srcdir="${src.dir}" />
For further details on the usage of the Cobertura Ant tasks, please refer to the Cobertura user manual.
To upload Cobertura coverage data, you should use the external-report service as described here.
# gcov
The tool gcov (opens new window) measures line coverage for C/C++ code compiled with the GCC compiler.
To determine the code coverage, the code must be compiled using the switch --coverage.
This creates files with the extension gcno during compilation.
During execution of the code, the coverage data is stored into files with ending gcda.
The program gcov is then used to convert the coverage data into readable files with the extension gcov as follows:
gcov -o <OBJ_DIR> -l -p <SOURCE_FILES>
Here the <OBJ_DIR> is the directory containing the object files.
For projects with many subdirectories it should be noted that the parameter must point directly to the directory containing the matching object.
The relative path of the source files is not used. The paramters -l and -p are used to ensure that files with the same name but different directories do not collide.
Alternatively, the python script gcovr (opens new window) can be used to execute gcov for complex project layouts.
To preserve the gcov files, the parameter --keep must be used.
Please note that gcovr does not support merging of coverage files (see gcovr FAQ (opens new window) and this StackOverflow question (opens new window), which is needed when code is executed in more than one test run.
If you have to merge coverage files consider using lcov (opens new window) (also see this StackOverflow question (opens new window)).
To upload coverage results to Teamscale, you should use the external-report service as described here.
# ESLint
While ESLint binaries are shipped with Teamscale, you will need to install the necessary NodeJS (opens new window) runtime on your machine.
You will need to have the NodeJS binaries on the PATH and restart Teamscale before you can enable ESLint for your project.
The bundled ESLint distribution includes:
- eslint@8.20.0
- @typescript-eslint/parser@5.30.7
- @typescript-eslint/eslint-plugin@5.30.7
- eslint-plugin-react@7.30.1
- typescript@4.7.4
Teamscale comes with an ESLint configuration that defaults to ESLint's default values. You can still provide a custom ESLint config file in the analysis profile to adjust the rule's settings to your needs.
Configuration file security
For security reasons, Teamscale only allows json, yml and yaml as valid ESLint configuration file extension by default. To enable JavaScript configuration files (e.g., .eslintrc.js), you can set -Dcom.teamscale.allow-executable-lint-config-file=true in the jvm.properties file.
This is discouraged because it can potentially lead to code execution on the Teamscale server via the configuration file.
# TSLint
Removed
TSLint support has been removed with Teamscale 8.2. Most of the TSLint checks are available via ESLint now. See the TSLint deprecation blog (opens new window) for an overview of ESLint checks that replace TSLint checks.
# abaplint
AbapLint binaries (version @abaplint/cli@2.89.15) are now shipped and dedicated to being used with Teamscale.
The bundled binaries include basic ABAP dependencies (opens new window) as well as a default JSON configuration
file. You can provide a different configuration file using the option ABAPLint configuration file in the analysis profile.
Except you have a compelling reason, consider removing the url property in the dependencies object. This property points to a public
git repository containing required ABAP dependencies for ABAPLint. If present, it causes ABAPLint to
git-clone (opens new window) the
repository during the analysis of every commit and this impacts the performance of the analysis. In addition, the analysis might fail if
the server has no local git installed, or no internet connection is present.
It is possible in the configuration file to link to ABAP dependencies different from what is bundled in Teamscale.
Do this by providing in the folder property, the absolute path to the dependencies folder. For Windows users, ensure that the path string uses
forward slashes in place of Windows backward slashes. Also, if the path to the dependencies is on a root drive (e.g. D:) different from where Teamscale is
installed (e.g. C:), create a directory junction on the root drive for Teamscale that points to the location of the ABAP dependencies. Then use the path to
the directory junction inside the folder property:
mklink /J C:\path\to\directory_junction_link D:\path\to\abap\dependencies\folder
AbapLint is able to analyze ABAP files according to the version of the ABAP language. This corresponds to some
Abaplint version (opens new window), which is specified in the AbapLint
configuration file, in the version field of the syntax section. As Teamscale communicates with SAP systems, it is now able to lint ABAP files providing the
appropriate language version. If you desire to use a different language version, locate its corresponding version type from the
file (opens new window) and save into your configuration file. Teamscale will use the appropriate
version from the SAP system if the version field is left blank or omitted.
NodeJS
ABAPLint requires that NodeJS version 16 or higher (opens new window) is deployed on your system and globally available by putting it to the PATH variable.
# PC-lint/FlexeLint
PC-lint (opens new window) is a static analysis tool for C/C++ that covers a wide range of checks. To import PC-lint analysis results in Teamscale, you need to generate an XML report using the +xml parameter from PC-lint. For details, please refer to the documentation of PC-lint.
The check descriptions in Teamscale are up-to-date with PC-lint version 9.00L (i.e., Teamscale can import and display findings from a report generated by this PC-lint version).
# Pylint
Pylint (opens new window) is an Open Source code analysis tool for Python working directly on the source code.
The check descriptions in Teamscale are up-to-date with pylint 2.16.0-dev (i.e., Teamscale can import and display findings from a report generated by this version). To import Pylint analysis results into Teamscale, you need to create the generated report using a special format. This can be achieved by using the following command line call:
pylint --score=no --reports=no --msg-template='line: {line}, messageId: {msg_id}, message: {msg}, absolutePath: {abspath}, messageName: {symbol}' /path/to/python/files > report.json
This command generates a plain text format which can be uploaded to Teamscale, for example with the Teamscale Python client’s upload_report method, manually via the external uploads view for your project or simply using curl via the REST interface.
Please ensure to use the above message template without any changes.
Please note that while Pylint is capable of generating a JSON report, this cannot be used for Teamscale as does not contain all information necessary to seamlessly integrate the report into Teamscale.
# Parasoft C/C++test
The reports from Parasoft C/C++test are fully self-contained. The content and structure, however, depend completely on the configuration of the tool. Hence, before the first import of such a report, the findings need to be made known to Teamscale using the following steps:
- Create a new analysis profile (e.g., called
CppWithParasoft) with Parasoft C/C++test enabled in the tools section - Call the following service to upload the report and update the analysis profile:
curl -X POST -F report=@parasoft.xml 'http://<teamscale-url>/api/external-findings/descriptions/from-parasoft-report?analysis-profile=CppWithParasoft'
- The analysis profile should now be updated with rules and can be adjusted if needed
- Create a project with the updated analysis profile
# XCode Test Coverage
Test coverage for XCode projects is recorded in an XCResult bundle in a binary format. Teamscale supports importing
the contained line-based test coverage by exporting it in a textual format using the xccov command line tool. For
XCode 13.3 and above the coverage can be exported in a textual format using the following command:
xcrun xccov view --archive path/to/some.xcresult
For XCode 13.2 and below the XCode tooling cannot produce a comprehensive report with line coverage information for all files in a project, the following shell script must be used to obtain a coverage report that can be imported into Teamscale:
#!/bin/bash
if [ $# -eq 0 ]
then
echo "Please provide path to xccovarchive directory"
exit 1
fi
archive="$1"
coverage=""
files=$(xcrun xccov view --archive --file-list "$archive")
while read -r file; do
coverage+="$file"
coverage+=$'\n'
coverage+="$(xcrun xccov view --archive "$archive" --file "$file"):"
coverage+=$'\n'
done <<< "$files"
echo "${coverage}"
In both cases the command will output the coverage report to standard out. You can pipe the output into a file which can then be uploaded via the REST API as described here.
Note that the Teamscale Upload (opens new window) tool provides an easy to use automatic
conversion of the XCResult bundle. Any *.xcresult, *.xcresult.tar, *.xcresult.tar.gz or *.xcresult.tgz file can
be passed as a report with format XCODE to the tool and it will perform automatic conversion to the right format
before upload.
# XCode XCTest test execution data
Besides coverage, XCTest result files (*.xcresult) also contain test execution data.
To import this data to Teamscale, the following command can be used to generate a report in JSON format:
xcrun xcresulttool get --path <xcresult-file> --format json
The generated *.json file should contain an explicit testsRef ID, e.g. 0~pYxLsSwT2harDbBkwHOemYmrig4tejMoZIDzYaRhN1_YDV6VNk01K24YhzwGOQTd5yIr4raTPhFhE3DPlKwG_Q==.
This ID should be used in the following script to obtain the final report file:
xcrun xcresulttool get --path <xcresult-file> --format json --id "<id>"
This resulting *.json file can then be uploaded to Teamscale as a XCode JSON test execution report.
This can be done analogously to test execution reports as described here (opens new window).
# BullseyeCoverage
See our detailled guide on C/C++ test coverage.
# SwiftLint
SwiftLint is a tool to check Swift code for adherence to style guide and conventions.
While SwiftLint is executed directly by Teamscale, the binaries are not shipped with the Teamscale distribution.
To enable SwiftLint, you need to install SwiftLint on the Teamscale analysis server and ensure that the swiftlint executable is on the path.