Defining custom commands for Che-Theia

The Che-Theia IDE allows users to define custom commands in a devfile that are then available when working in a workspace.

This is useful, for example, for:

Simplifying building, running, and debugging projects.
Allowing lead developers to customize workspaces based on team requirements.
Reducing time needed to onboard new team members.

Che-Theia task types

The following is an example of the commands section of a devfile.

commands:

  - name: Package Native App
    actions:
      - type: exec
        component: centos-quarkus-maven
        command: "mvn package -Dnative -Dmaven.test.skip"
        workdir: ${CHE_PROJECTS_ROOT}/quarkus-quickstarts/getting-started

  - name: Start Native App
    actions:
      - type: exec
        component: ubi-minimal
        command: ./getting-started-1.0-SNAPSHOT-runner
        workdir: ${CHE_PROJECTS_ROOT}/quarkus-quickstarts/getting-started/target

  - name: Attach remote debugger
    actions:
    - type: vscode-launch
      referenceContent: |
        {
          "version": "0.2.0",
          "configurations": [
            {
              "type": "java",
              "request": "attach",
              "name": "Attach to Remote Quarkus App",
              "hostName": "localhost",
              "port": 5005
            }
          ]
        }

Che commands

Package Native App and Start Native App

The Che commands are to be used to define tasks that will be executed in the workspace container.

The exec type implies that the Che runner is used for command execution. The user can specify the component in whose container the command is executed.
The command field contains the command line for execution.
The workdir is the working directory in which the command is executed.
The component field refers to the container where the command will be executed. The field contains the component alias where the container is defined.

VS Code launch configurations

Attach remote debugger

VS Code launch configurations are usually used to define debugging configuration. To trigger these configurations, press F5 or choose Start Debugging from the Debug menu. The configurations provide information to the debugger, such as the port to connect to for debugging or the type of the application to debug (Node.js, Java, and others.).

The type is vscode-launch.
It contains the launch configurations in the VS Code format.
For more information about VS Code launch configurations, see the Debugging section on the Visual Studio documentation page.

Tasks of type che, also known as exec commands, can be executed from the Terminal→Run Task menu or by selecting them in the My Workspace panel. Other tasks are only available from Terminal→Run Task. Launch configurations are available in the Che-Theia debugger.

Examples

Running and debugging

Che-Theia supports the Debug Adapter Protocol. This protocol defines a generic way for how a development tool can communicate with a debugger. It means Che-Theia works with all implementations.

Prerequisites

A running instance of Eclipse Che. To install an instance of Eclipse Che, see Installing Che.

Procedure

To debug an application:

Click Debug → Add Configuration to add debugging or launch configuration to the project.
From the pop-up menu, select the appropriate configuration for the application that you want to debug.
Update the configuration by modifying or adding attributes.
Breakpoints can be toggled by clicking the editor margin.
After opening a context menu, use the Edit Breakpoint command to add conditions.

The IDE then displays the Expresion input field.
To start debugging, click View→Debug.
In the Debug view, select the configuration and press F5 to debug the application. Or, start the application without debugging by pressing Ctrl+F5.

Editing a task and launch configuration

Procedure

To customize the configuration file:

Edit the tasks.json or launch.json configuration files.
Add new definitions to the configuration file or modify the existing ones.

The changes are stored in the configuration file.
To customize the task configuration provided by plug-ins, select the Terminal → Configure Tasks menu option, and choose the task to configure. The configuration is then copied to the tasks.json file and is available for editing.