Starting with Eclipse Che 7.3, Visual Studio Code (VS Code) extensions can be installed to extend the functionality of a Che workspace. VS Code extensions can run in the Che-Theia editor container, or they can be packaged in their own isolated and pre-configured containers with their prerequisites.
This document describes:
Use of a VS Code extension in Che with workspaces
Che Plug-ins panel
How to publish a VS Code extension in the Che plug-in registry (to share the extension with other Che users)
The extension-hosting sidecar container and the use of the extension in a devfile are optional for this.
How to review the compatibility of the VS Code extensions to be informed whether a specific API is supported or has not been implemented yet.
Publishing a VS Code extension into the Che plug-in registry
Writing a meta.yaml file and adding it to a plug-in registry
The plug-in meta information is required to publish a VS Code extension in an Eclipse Che plug-in registry. This meta information is provided as a
meta.yaml file. This section describes how to create a
meta.yaml file for an extension.
meta.yamlfile in the following plug-in registry directory:
meta.yamlfile and provide the necessary information. The configuration file must adhere to the following structure:
apiVersion: v2 (1) publisher: myorg (2) name: my-vscode-ext (3) version: 1.7.2 (4) type: value (5) displayName: (6) title: (7) description: (8) icon: https://www.eclipse.org/che/images/logo-eclipseche.svg (9) repository: (10) category: (11) spec: containers: (12) - image: (13) memoryLimit: (14) memoryRequest: (15) cpuLimit: (16) cpuRequest: (17) extensions: (18) - https://github.com/redhat-developer/vscode-yaml/releases/download/0.4.0/redhat.vscode-yaml-0.4.0.vsix - vscode:extension/SonarSource.sonarlint-vscode
1 Version of the file structure. 2 Name of the plug-in publisher. Must be the same as the publisher in the path. 3 Name of the plug-in. Must be the same as in path. 4 Version of the plug-in. Must be the same as in path. 5 Type of the plug-in. Possible values:
VS Code extension.
6 A short name of the plug-in. 7 Title of the plug-in. 8 A brief explanation of the plug-in and what it does. 9 The link to the plug-in logo. 10 Optional. The link to the source-code repository of the plug-in. 11 Defines the category that this plug-in belongs to. Should be one of the following:
12 If this section is omitted, the VS Code extension is added into the Che-Theia IDE container. 13 The Docker image from which the sidecar container will be started. Example:
14 The maximum RAM which is available for the sidecar container. Example: "512Mi". This value might be overridden by the user in the component configuration. 15 The RAM which is given for the sidecar container by default. Example: "256Mi". This value might be overridden by the user in the component configuration. 16 The maximum CPU amount in cores or millicores (suffixed with "m") which is available for the sidecar container. Examples: "500m", "2". This value might be overridden by the user in the component configuration. 17 The CPU amount in cores or millicores (suffixed with "m") which is given for the sidecar container by default. Example: "125m". This value might be overridden by the user in the component configuration. 18 A list of VS Code extensions that should be run in this sidecar container.
Adding a plug-in registry VS Code extension to a workspace
When the required VS Code extension is added into a Che plug-in registry, the user can add it into the workspace through the Che Plugins panel or through the workspace configuration.
Adding a VS Code extension using the Che Plugins panel
A running instance of Eclipse Che. To install an instance of Eclipse Che, see Che quick-starts
To add a VS Code extension using the Che Plugins panel:
Open the Che Plugins panel by hiting
CTRL+SHIFT+Jor navigate to View/Plugins.
Change the current registry to the registry in which the VS Code extension was added.
In the search bar, click the Menu button and then click Change Registry to choose the registry from the list. If the required registry is not in the list, add it using the Add Registry menu option. The registry link should point to the
pluginssegment of the registry. For example:
Search for the required plug-in using the filter, and then click the Install button.
Restart the workspace for the changes to take effect.
Adding a VS Code extension using the workspace configuration
To add a VS Code extension using the workspace configuration:
Click the Workspaces tab on the Dashboard and select the workspace in which you want to add the plug-in. The Workspace <workspace-name> window is opened showing the details of the workspace.
Click the devfile tab.
Locate the components section, and add a new entry with the following structure:
- type: chePlugin id: (1)
1 Link to the
meta.yamlfile in your registry, for example,
Che automatically adds the other fields to the new component.
Alternatively, you can link to a
meta.yamlfile hosted on GitHub, via the reference field.
- type: chePlugin reference: (1)
Restart the workspace for the changes to take effect.
Choosing the sidecar image
Che plug-ins are special services that extend the Che workspace capabilities. Che plug-ins are packaged as containers. The containers that the plug-ins are packaged into run as sidecars of the Che workspace editor and augment its capabilities.
A running instance of Eclipse Che. To install an instance of Eclipse Che, see Che 'quick-starts'.
To choose a sidecar image:
If the VS code extension does not have any external dependencies, use
eclipse/che-theia-endpoint-runtime: nextas a sidecar container image for the extension.
In addition to the
eclipse/che-theia-endpoint-runtime:nextbase image, the following ready-to-use sidecar images that include language-specific dependencies are available:
If a VS Code extension has external dependencies that are not found in one of the ready-to-use images, use a container image that contains the needed dependencies for the extension and is based on the
FROMdirective should be similar to
FROM eclipse/che-theia-endpoint-runtime:next. This is required because this base image contains tools for running the remote VS Code extension and communications between the sidecar and the Che-Theia editor, so that the VS Code extension does not have to know that it is a remote one.
Verifying the VS Code extension API compatibility level
Che-Theia does not fully support the VS Code extensions API. The vscode-theia-comparator is used to analyze the compatibility between the Che-Theia plug-in API and the VS Code extension API. This tool runs in a nightly cycle, and the results are published on the vscode-theia-comparator GitHub page.
Personal GitHub access token. For information on creating a personal access token for the command line see Creating a personal access token for the command line. A GitHub access token is required to increase the GitHub download limit for your IP address.
To run the vscode-theia comparator manually:
Clone the vscode-theia-comparator repository, and build it using the
GITHUB_TOKENenvironment variable to your token.
yarn run generatecommand to generate a report.
out/status.htmlfile to view the report.