User Guide

  • 2021.2
  • 04/12/2021
  • Public Content

Developing a Visual Studio Code Project for SSH Development

The following procedure will use a Remote Host connection enabling you to edit and debug your code remotely. For instructions on how to develop locally, see Local Usage of Visual Studio Code with Intel® oneAPI Toolkits on Linux*.

Prerequisites

It is not necessary to install VS Code on your remote Linux system; it is needed only on your local system. This means that your remote Linux target can be a "headless" or CLI-only system; your remote Linux system does not require a GUI in order to be used for remote development.

Set oneAPI Environment Variables on the Remote Host

In order to perform development on your remote Linux target, you must install an Intel oneAPI Toolkit and configure the oneAPI development environment variables on the remote Linux target.
  1. Log in to your remote Linux target using
    ssh
    and install the Intel oneAPI Toolkit onto that target system.
  2. Configure your remote Linux target so that the oneAPI development environment script (
    setvars.sh
    ) runs when VS Code initiates a remote connection.
    Visual Studio Code does not currently provide a mechanism to automatically run scripts on your remote Linux target when it "remotes into" your target system (for example, running
    setvars.sh
    remotely). There are a variety of ways to get around this issue, only one of which is presented here. See the Bash Startup Files man page for more options.
    Add the following shell script lines to your remote Linux system's
    /etc/profile
    script. This location (or in an
    /etc/profile.d/
    script) will ensure that all users of your remote Linux target development system will run the
    setvars.sh
    environment script when they connect remotely using Visual Studio Code:
    if [ -z "$SSH_TTY" ] && [ -n "$SSH_CLIENT" ]; then . /opt/intel/oneapi/setvars.sh &>/dev/null fi
    The above assumes that you have installed your oneAPI toolkits on your remote Linux target in the default "root/sudo" installation location (
    /opt/intel/oneapi/
    ). If you have installed the oneAPI tools in a different location on your remote Linux system, you will have to adjust the path to
    setvars.sh
    .
    The script shown above
    will not
    execute the
    setvars.sh
    script when you
    ssh
    into your remote Linux system or if you are using it directly with a terminal session. Remove the first and third lines if you want it to execute for such interactive terminal sessions. See Configure Your CPU or GPU System for more details regarding configuration of the oneAPI environment on a Linux system.

Configure Visual Studio Code on Your Local Host

You must install the VS Code "remote ssh" extension into your local copy of VS Code. This extension facilitates development on your remote Linux target.
  1. Install the
    Remote - SSH
    extension by Microsoft. Click the
    Extensions
    icon and search for "Remote-SSH" in the search bar.
    Screenshot showing extensions search
  2. Click
    install
    . After installation, you see
    Remote – SSH
    in the
    Installed Extensions
    list.
    Screenshot showing extensions installed

Connect to Your Remote Linux Target

See the Visual Studio Code Remote Development using SSH documentation for detailed instructions, requirements, and additional information.
  1. Click the
    remote-ssh
    icon located in the lower left corner of your VS Code window. A
    remote-ssh commands
    palette appears near the top of the VS Code window. Select
    Remote-SSH: Connect to Host
    in that command palette.
    Screenshot showing VS Code remote connect icon
    The first connection to your remote Linux target may require a minute or longer to download and install the necessary VS Code backend tools to your remote system. Subsequent connections to the remote system are generally faster. VS Code will indicate the installation process in the lower-right corner of your VS Code window.
  2. Enter the username and an IP address or valid hostname for your remote Linux target, using the same format you would use for an SSH connection into that system, and then press
    Enter
    . In the image below, the username is
    ubuntu
    .
    Screenshot showing VS Code remote connect icon
  3. A new VS Code window opens and is connected to the remote host. If you do not have an SSH key-pair set up for this connection, you will be prompted to enter a password for your remote Linux target.
    Screenshot showing VS Code remote connect icon
    If you see errors about bad SSH file permissions when connecting, see fixing SSH file permission errors. If your connection is hanging, you may need to enable TCP forwarding or respond to a server prompt. See Tips and Tricks for details.
  4. Once logged in, add the
    C/C++ extension
    to your remote VS Code instance. This extension is required to debug a remote session using the VS Code debug interface.

Create a Blank Project

  1. Click
    File
    New File
    to open a blank file in Visual Studio Code (VS Code).
  2. Once you have completed writing code, you can save it as a file or save it as a workspace. For more information on workspaces, see the Visual Studio Code Get Started Guide.
  3. To run the code, click
    Run
    Run without Debugging
    .
  4. Select C++ as the language. The code will run.

Import an Existing Project

  1. Click
    File
    Open File
    or
    File
    Open Workspace
    to open an existing project in Visual Studio Code (VS Code).
  2. Once you have completed writing code, you can save it as a file or save it as a workspace. For more information on workspaces, see the Visual Studio Code Get Started Guide.
  3. To run the code, click
    Run
    Run without Debugging
    .
  4. Select C++ as the language. The code will run.

Try Debugging (CPU Only) (Preview)

Intel® Distribution for GDB* does not currently support VS Code. You can use upstream gdb to debug.
This section assumes that you can build your sample and have installed the Microsoft VS Code C/C++ Extension. The C/C++ extension is required to configure the oneAPI C/C++ debugger.
The Intel
®
oneAPI Base Toolkit
includes a special version of GNU* GDB (
gdb-oneapi
) designed to support oneAPI C/C++ applications. To debug your DPC++ application using this special debugger, you will need to make changes to the
.vscode/launch.json
configuration file.
  1. Go to
    Debug
    Open Configurations
    , and open the
    launch.json
    configuration settings.
    If you are prompted to select a debug environment, choose
    C++ (GDB/LLDB)
    .
    Screenshot showing command pallet prompting for debugger
  2. Copy the code shown below into your
    launch.json
    file, and replace the
    "program":
    property's value with the path to your project's executable (that is, the application that you are going to debug).
    If VS Code doesn't recognize the application name, you may have to insert the full path and file name into the
    launch.json
    file's
    "program":
    property.
  3. Add
    gdb-oneapi
    to your
    launch.json
    configuration's
    "miDebuggerPath":
    property.
    The
    gdb-oneapi
    application should have been added to your path when you ran
    setvars.sh
    to configure the oneAPI development environment, prior to starting VS Code. If you prefer, you can specify the full path and filename to the
    gdb-oneapi
    application in your
    launch.json
    file.
  4. In some configurations, GDB may not be compatible with VS Code. If this happens, add the environment variable to disable `gdb-oneapi` support for GPU autolaunch. This can either be done in the environment prior to launching VS Code, or within the launch.json:
    export INTELGT_AUTO_ATTACH_DISABLE=1
    { "version":"0.2.0", "configurations":[ { "name":"(gdb) Launch", "type":"cppdbg", "request":"launch", "program":"${workspaceFolder}/build/array-transform", "args":[ "cpu" ], "stopAtEntry":false, "cwd":"${workspaceFolder}", "environment":[ { "name":"INTELGT_AUTO_ATTACH_DISABLE", "value":"1" } ], "externalConsole":false, "MIMode":"gdb", "miDebuggerPath":"gdb-oneapi", "setupCommands":[ { "description":"Enable pretty-printing for gdb", "text":"-enable-pretty-printing", "ignoreFailures":true } ] } ] }
  5. Bring up the debug view by selecting the
    Run
    icon in the
    Activity Bar
    . You can also use the keyboard shortcut (
    Ctrl+Shift+D
    ).
  6. Start the run and debug session by clicking the green
    DEBUG AND RUN
    icon, or go to
    Run
    Start Debugging
    (
    F5
    ).
    Screenshot showing VS Code recommended extension installation popup

Disconnect from a Remote Host

You can close the VS Code remote connection by selecting
File
Close Remote Connection
from the VS Code menu. Alternatively, click the colored
remote ssh
notification in the lower-left corner of the VS Code window and select
Close Remote Connection
from the list of
Remote-SSH
commands.

Kill Remote VS Code Server

If you need to kill the remote VS Code SSH server on your remote Linux target, perform the following steps:
  1. Open the VS Code command palette (
    View
    Command Palette
    ).
  2. Enter
    remote
    in the command palette dialog box.
  3. Select
    Remote-SSH: Kill VS Code Server on Host
    .
You will be prompted to provide a
user@host
value or choose from a list of preconfigured SSH hosts in your
.ssh/config
file. Use the same credentials that you used to make your remote VS Code connection; VS Code will kill only the VS Code remote server instances that match that user.
VS Code provides no indication that completion of the
kill
command was successful. If you initiated a remote session with more than one remote user, you must perform the kill for each one.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.