Starting with Eclipse Che 7, 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.

Importing a VS Code extension in the Che-Theia editor

This section describes how to install a Visual Studio Code (VS Code) extension from the VS Code marketplace in a Che workspace when using Che-Theia as the Che editor component.

This method of installing VS Code extensions is for extensions that do not have runtime dependencies. To install extensions that require particular dependencies (tools, environment variables, runtime servers), see section Publishing a VS Code extension into the Che plug-in registry.

Prerequisites

  • A running instance of Eclipse Che. To install an instance of Eclipse Che, see Che 'quick-starts'.

  • Configure the Che-Theia memory limit with 512 MB RAM or more to run the Che-Theia editor. In addition, reserve sufficient memory for the VS code extensions. The specific amount of memory required depends on the extensions used.

Procedure

To import a VS Code extension in the Che Theia editor:

  1. Navigate to the VS Code marketplace, locate the required extension, and copy the VS Code Quick Open code to the clipboard.

  2. Open the Che Plugins panel in the Che-Theia IDE. If the panel is not shown, use the View → Che Plugins menu options from the main menu.

    For macOS users, paste the install command or the install button into the Che Plugins panel.

    vs code extension installation

  3. In the Install extension dialog box, click Install to start the installation. The VS Code plugin has been installed message indicates successful installation of the plug-in.

  4. In the top-left corner of the window, click Click here to apply changes and restart your workspace to restart the workspace and apply the changes.

    vs code extension apply restart

  5. In the Restart Workspace dialog box, click Restart to confirm the action.

    vs code extension restart workspace

After the workspace restarts, the added VS Code extensions are launched.

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.

Procedure

  1. Create a meta.yaml file in the following plug-in registry directory: <apiVersion>/plugins/<publisher>/<plug-inName>/<plug-inVersion>/.

  2. Edit the meta.yaml file 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)
  extensions:                                                   (15)
    - 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 Plug-in name. Must be the same as in path.
    4 The Che plug-in version. Must be the same as in path.
    5 Type of the Che plug-in. For VS Code extensions, it must be VS Code extension.
    6 A short name of the plug-in.
    7 Plug-in title.
    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: Editor, Debugger, Formatter, Language, Linter, Snippet, Theme, or Other.
    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: eclipse/che-theia-endpoint-runtime:next.
    14 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.
    15 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 the VS Code extension using the Che Plugins panel

Prerequisites

  • A running instance of Eclipse Che. To install an instance of Eclipse Che, see Che quick-starts

Procedure

To add the VS Code extension using the Che Plugins panel:

  1. Open the Che Plugin panel.

  2. Change the current registry to the registry in which the VS Code extension was added.

  3. 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 plugins segment of the registry. For example: https://my-registry.com/v3/plugins/index.json.

    vs code extension change registry

  4. Search for the required plug-in using the filter, and then click the Install button.

  5. Restart the workspace for the changes to take effect.

Adding the VS Code extension using the workspace configuration

Prerequisites
Procedure

To add the VS Code extension using the workspace configuration:

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

  2. Click the devfile tab.

  3. Locate the components section, and add a new entry with the following structure:

     - type: chePlugin
   id:              (1)
    1 Link to the meta.yaml file in your registry, for example, https://my-plugin-registry/v3/plugins/<publisher>/<plug-inName>/<plug-inVersion>/meta.yaml

    Che automatically adds the other fields to the new component.

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

Prerequisites

  • A running instance of Eclipse Che. To install an instance of Eclipse Che, see Che 'quick-starts'.

Procedure

To choose a sidecar image:

  1. If the VS code extension does not have any external dependencies, use eclipse/che-theia-endpoint-runtime: next as a sidecar container image for the extension.

    In addition to the eclipse/che-theia-endpoint-runtime:next base image, the following ready-to-use sidecar images that include language-specific dependencies are available:

    • eclipse/che-remote-plugin-runner-java8

    • eclipse/che-remote-plugin-runner-java11

    • eclipse/che-remote-plugin-go-1.10.7

    • eclipse/che-remote-plugin-python-3.7.3

    • eclipse/che-remote-plugin-dotnet-2.2.105

    • eclipse/che-remote-plugin-php7

    • eclipse/che-remote-plugin-kubernetes-tooling-1.0.0

    • eclipse/che-remote-plugin-kubernetes-tooling-0.1.17

    • eclipse/che-remote-plugin-openshift-connector-0.0.17

    • eclipse/che-remote-plugin-openshift-connector-0.0.21

  2. 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 eclipse/che-theia-endpoint-runtime:next image.

    Example: The FROM directive 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.

Prerequisites
Procedure

To run the vscode-theia comparator manually:

  1. Clone the vscode-theia-comparator repository, and build it using the yarn command.

  2. Set the GITHUB_TOKEN environment variable to your token.

  3. Execute the yarn run generate command to generate a report.

  4. Open the out/status.html file to view the report.

Tags: