Teamscale Documentation

Appearance

Teamscale Integration for Other IDEs and Editors ​

By using a small command-line client for developers (teamscale-dev) Teamscale can be integrated into other IDEs or editors for which no dedicated plug-in exists. This makes it possible to use Teamscale, for example, from within Visual Studio Code or Sublime Text.

Installing teamscale-dev ​

The CQSE website offers both the latest version and older versions of the teamscale-dev client for download. Moreover, you can choose between platform-specific (for Windows, Linux, macOS) and platform-independent downloads. While the former downloads are self-contained, the latter requires a Java runtime environment to be installed on your machine.

Once you have downloaded the appropriate .zip archive, perform the following installation steps depending on your operating system (Windows, macOS, Linux).

Linux/macOS ​

For macOS and Linux, it's recommended to install teamscale-dev to the /opt directory and then linking the executable to your /usr/local/bin directory.

  1. Extract the archive: sudo unzip teamscale-dev-*.zip -d /opt/
  2. Link executable: sudo ln -s /opt/teamscale-dev/bin/teamscale-dev /usr/local/bin/
  3. Add the following line to your ~/.bashrc or ~/.zshrc to enable auto-completion:
    shell
    source <( teamscale-dev generate-completion )

macOS Security

Note that the startup of teamscale-dev may be blocked on macOS upon the first execution. To allow execution of the executable go to System Settings > Privacy & Security and check the Security section for an application that was blocked from running.

Windows ​

On Windows, it's recommended to install teamscale-dev to the C:\Program Files directory and adding the contained bin directory to your PATH environment variable.

  1. Extract the archive to C:\Program Files.
  2. Add C:\Program Files\teamscale-dev\bin to your PATH via Control Panel > Advanced System Settings > Environment Variables > System Variables.

Configuring Your Projects Using .teamscale.toml Files ​

Before you can use teamscale-dev, your local projects needs to be configured to map to projects on the Teamscale server. This is done using one or more .teamscale.toml configuration files in a simple, uniform file format (.teamscale.toml).

In the simplest case, place a file like the following in the root directory of your project:

toml
root = true

[project]
id = "example"

[server]
url = "https://example.com/teamscale/"

For more advanced cases, please refer to the documentation of the file format.

Invoking teamscale-dev from Different IDEs or Editors ​

Sublime Text ​

To use teamscale-dev conveniently from within Sublime Text, perform the following steps:

  1. Add a new build system (Tools > Build System > New Build System...).

  2. Copy (or download) and paste the following snippet in Sublime Text's build-system format:

    json
    {
  "cmd": [
    "teamscale-dev/bin/teamscale-dev",
    "pre-commit",
    "--user",
    "TODO Your username",
    "--accesskey",
    "TODO Your access key",
    "$file"
  ],
  "keyfiles": [
    ".teamscale.toml"
  ],
  "file_regex": "^(.*):(\\d+):(\\d+):\\s+(?:error|warning):\\s+(.*)$"
}

  3. Adapt the cmd property to point to your teamscale-dev executable (bin/teamscale-dev.bat on Windows, bin/teamscale-dev on Linux and macOS).

  4. Adapt the cmd property so that the --user and --accesskey options use your credentials, i.e., your username and access key. (See the documentation of the command-line client for further ways to supply your credentials.)

Executing a build with the pre-commit build system will now show any findings for the current file.

Vim/NeoVim ​

To use teamscale-dev conveniently from within Vim or NeoVim, we provide integration via a compiler plug-in.

  1. Copy compiler/teamscale.vim to your $VIMRUNTIME/compiler folder, e.g. ~/.config/nvim/compiler for NeoVim.

  2. In your .vimrc, you must at least define the variables mentioned in vimrc.vim to let the plug-in know your Teamscale credentials and where teamscale-dev is installed. Optionally, you can use the remaining commands in that file to define a convenient command :Precommit to run pre-commit for the current file and a keyboard mapping. Internally, this command selects Teamscale as the compiler, calls :make %, and then reverts to your previously set compiler to not interrupt your existing compiler/make workflow. Any findings are then shown in the quickfix window (:cw).

If you want pre-commit on-save, you can define a BufWritePost autocommand to call :Precommit whenever the current buffer is written.

XCode ​

To use teamscale-dev conveniently from within XCode, perform the following steps:

  1. Configure credentials (This step only needs to be performed once for all your XCode projects.):
    1. Create a file called .teamscale-dev.args in your home directory (i.e., /Users/<username>/.teamscale-dev.args).
    2. Configure an args file for supplying credentials.
  2. Configure XCode project:
    1. Open your project in XCode.
    2. Select project in the Project navigator.
    3. Add new target called Teamscale Pre-Commit:
      1. In the TARGETS panel, click the + icon.
      2. Select Other > Aggregate and go to Next.
      3. Set the name Product Name to Teamscale Pre-Commit.
    4. Add a new Run Script phase to the build of the new target:
      1. Go to the Build Phases tab of the Teamscale Pre-Commit target.
      2. Add a New Run Script Phase via the + icon in the top left corner.
      3. Set the Shell command to:
        shell
        teamscale-dev pre-commit @"${HOME}/.teamscale-dev.args" --only-uncommitted-changes "${SRCROOT}"

Once this is configured you can select the Teamscale Pre-Commit target at the top and then run pre-commit by executing the active scheme via the play button at the top. This will execute pre-commit analysis on new or changed files that have not been committed yet.