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 steps:

  1. Extract the archive.
  2. Move the resulting teamscale-dev directory to the desired location. Common locations are %ProgramFiles% (Windows, typically C:\Program Files), /opt (Linux), or /Applications (macOS).
  3. Verify that the installation works by executing teamscale-dev\bin\teamscale-dev.bat (Windows) or teamscale-dev/bin/teamscale-dev (Linux, macOS) from your shell.
  4. (Optional) Add the bin directory to your shell's path.

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/"
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 ​

Visual Studio Code ​

To use Teamscale from within Visual Studio Code (VS Code), perform the following steps:

  1. Add a new task (Terminal > Configure Tasks... > Create tasks.json file from template > Others).

  2. Copy (or download) and paste the following snippet in VS Code's tasks.json format:

    json5
    {
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Upload for Pre-Commit Analysis",
      "detail": "Upload the current file to Teamscale for pre-commit analysis.",
      "type": "process",
      // TODO Point to your teamscale-dev(.bat) executable.
      "command": "teamscale-dev/bin/teamscale-dev",
      "args": [
        "pre-commit",
        // TODO Change to your credentials (username and IDE access key).
        "--user",
        "Your Username",
        "--accesskey",
        "Your IDE Access Key",
        "--show-links-to-findings",
        "${file}"
      ],
      "group": {
        "kind": "build",
        "isDefault": true
      },
      "presentation": {
        "panel": "dedicated",
        "reveal": "never",
        "revealProblems": "onProblem"
      },
      "problemMatcher": {
        "fileLocation": "absolute",
        "source": "Teamscale",
        "owner": "teamscale-dev",
        "pattern": {
          "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$",
          "file": 1,
          "line": 2,
          "column": 3,
          "severity": 4,
          "message": 5
        }
      }
    }
  ]
}
    {
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Upload for Pre-Commit Analysis",
      "detail": "Upload the current file to Teamscale for pre-commit analysis.",
      "type": "process",
      // TODO Point to your teamscale-dev(.bat) executable.
      "command": "teamscale-dev/bin/teamscale-dev",
      "args": [
        "pre-commit",
        // TODO Change to your credentials (username and IDE access key).
        "--user",
        "Your Username",
        "--accesskey",
        "Your IDE Access Key",
        "--show-links-to-findings",
        "${file}"
      ],
      "group": {
        "kind": "build",
        "isDefault": true
      },
      "presentation": {
        "panel": "dedicated",
        "reveal": "never",
        "revealProblems": "onProblem"
      },
      "problemMatcher": {
        "fileLocation": "absolute",
        "source": "Teamscale",
        "owner": "teamscale-dev",
        "pattern": {
          "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$",
          "file": 1,
          "line": 2,
          "column": 3,
          "severity": 4,
          "message": 5
        }
      }
    }
  ]
}

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

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

Running the task from within VS Code via Terminal > Run Task... > Upload File to Teamscale for Pre-Commit Analysis now opens the Problems panel whenever the file being currently edited contains any findings. To keep the Problems view focussed on the findings from pre-commit analysis, we recommend enabling the Show Active File Only filter.

You can also assign a keyboard shortcut to this task.

  1. Open the Keyboard Shortcuts preferences (File > Preferences > Keyboard Shortcuts).

  2. Click the Open Keyboard Shortcuts (JSON) button in the upper-right corner.

  3. Copy (or download) and paste the following snippet in VS Code's keybindings.json format:

    json
    {
  "key": "ctrl+alt+shift+p",
  "command": "workbench.action.tasks.runTask",
  "args": "Upload for Pre-Commit Analysis"
}
    {
  "key": "ctrl+alt+shift+p",
  "command": "workbench.action.tasks.runTask",
  "args": "Upload for Pre-Commit Analysis"
}

  4. Adapt the key property as necessary using any combination of accepted keys.

Sublime Text ​

To use Teamscale 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:

    Invalid code snippet option
    Invalid code snippet option

  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 IDE 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.