Remote Visual Studio Code* Development with Intel® oneAPI on Linux*

Technical Article

  • XX.XX
  • 09/28/2020
  • Public Content
Contents

Remote Visual Studio Code Development with Intel® oneAPI Toolkits on Linux*

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 VSCode 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 the Base Kit 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 oneAPI Base Toolkit onto that target system.
    To get started, you need to install only the oneAPI Base Toolkit on your remote Linux target; you can install additional oneAPI toolkits either now or at a later time.
  2. Configure your remote Linux target so that the oneAPI development environment script (
    setvars.sh
    ) runs when VSCode 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 VSCode "remote ssh" extension into your local copy of VSCode. 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 VSCode window. A
    remote-ssh commands
     palette appears near the top of the VSCode window. Select
    Remote-SSH: Connect to Host
     in that command palette.
    Screenshot showing VSCode remote connect icon
    The first connection to your remote Linux target may require a minute or longer to download and install the necessary VSCode backend tools to your remote system. Subsequent connections to the remote system are generally faster. VSCode will indicate the installation process in the lower-right corner of your VSCode 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 VSCode remote connect icon
  3. A new VSCode 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 VSCode 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 VSCode instance. This extension is required to debug a remote session using the VSCode debug interface.

Create a New oneAPI Project

Follow the instructions in Basic Usage of Visual Studio Code with oneAPI on Linux, and refer to the section titled "Explore oneAPI Samples with VS Code".
Once you have created a oneAPI sample on your remote Linux system, you can build, run, and debug it on the remote host, from within your local VS Code window.

Disconnect from a Remote Host

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

Kill Remote VSCode Server

If you need to kill the remote VSCode SSH server on your remote Linux target, perform the following steps:
  1. Open the VSCode 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 VSCode connection; VSCode will kill only the VSCode remote server instances that match that user.
VSCode 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

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804