Developing a Visual Studio Code Project for SSH Development
Using Visual Studio Code* with Intel® oneAPI Toolkits
This guide assumes you are familiar with C/C++ development and the
Visual Studio Code (VS Code) editor. If you are new to Visual Studio
Code, review these VS Code documentation links:
Prerequisites:
If you have not configured your system and built and run a sample
project, please refer to the appropriate toolkit Get Started guide and
complete those steps:
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.
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*.
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.
Log in to your remote Linux target usingsshand install the Intel oneAPI Toolkit onto that target system. 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 fiThe 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 abovewill notexecute the setvars.sh script when yousshinto 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.
Install theRemote - SSHextension by Microsoft. Click theExtensionsicon and search for “Remote-SSH” in the search bar.![]()
Clickinstall. After installation, you seeRemote – SSHin theInstalled Extensionslist.![]()
Connect to Your Remote Linux Target
See the Visual Studio Code Remote Development using SSH documentation for detailed instructions, requirements, and additional information.
Click theremote-sshicon located in the lower left corner of your VS Code window. Aremote-ssh commandspalette appears near the top of the VS Code window. SelectRemote-SSH: Connect to Hostin that command palette.
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. 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 pressEnter. In the image below, the username is ubuntu.![]()
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.
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. Once logged in, add theC/C++ extensionto your remote VS Code instance. This extension is required to debug a remote session using the VS Code debug interface.
Explore Samples Using Visual Studio Code*
Before working with oneAPI samples, it is recommended that you install the VS Code “Sample Browser for Intel oneAPI Toolkits” extension and the VS Code “Environment Configurator for Intel oneAPI Toolkits” extension.Both can be quickly found in the VS Code extensions marketplace by typing “oneapi” into the marketplace search bar.
The steps below describe how to use these extensions to configure the oneAPI development environment for use with VS Code and use the Sample Browser to locate and create sample projects that help you learn how to use oneAPI features.To configure the oneAPI environment in VS Code:
PressCtrl+Shift+P( orView -> Command Palette…) to open the Command Palette. TypeIntel oneAPIto view options of the installed extensions. Click onIntel oneAPI: Initialize environment variables. Locate the setvars file:
Linux: By default,setvars.shis located in/opt/intel/oneapi/for root or sudo installations, or located in~/intel/oneapi/for local user installations. Windows: By default,setvars.batis located inC:\Program Files(x86)\Intel\oneAPI\If you customized the installation folder, setvars is in your custom folder. In the case of multiple folders in workspace, select the appropriate one. All tasks, launches, and terminals created from VS Code will now contain the oneAPI environment.To browse oneAPI samples using VS Code:
Click on the oneAPI button on the left navigation to view samples. If you do not have the extension installed, search the Extensions Marketplace for “Sample Browser for Intel oneAPI”.![]()
A list of available samples will open in the left navigation.![]()
To view the readme for the sample, click thenext to the sample. If you choose to build and run the sample, the readme will also be downloaded with the sample.
To build and run a sample, click theto the right of the sample name.
Create a new folder for the sample. The sample will load in a new window:![]()
Click README.md to view instructions for the sample.Not all oneAPI sample projects use CMake. The README.md file for each sample specifies how to build the sample. We recommend that you check out the CMake extension for VS Code that is maintained by Microsoft.
Try Debugging (CPU and GPU Only) (Preview)
Intel® Distribution for GDB* does not currently support VS Code. You can use upstream gdb to debug. Debugging a local Windows host using VS Code is not supported. Debugging a local Linux host on CPU is supported using VS Code, but debugging on GPU requires a remote host. Debugging a remote Linux target from Windows or Linux host is supported using VS Code.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.
Go toDebug>Open Configurations, and open thelaunch.jsonconfiguration settings.If you are prompted to select a debug environment, chooseC++ (GDB/LLDB).![]()
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 thelaunch.jsonfile’s"program":property. Addgdb-oneapito your launch.json configuration’s"miDebuggerPath":property.Thegdb-oneapiapplication 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 thegdb-oneapiapplication in your launch.json file. 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": [], "externalConsole":false, "MIMode":"gdb", "miDebuggerPath":"gdb-oneapi", "setupCommands":[ { "description":"Enable pretty-printing for gdb", "text":"-enable-pretty-printing", "ignoreFailures":true }, { "description": "Disable target async", "text": "set target-async off", "ignoreFailures": true } ] } ] } Bring up the debug view by selecting theRunicon in theActivity Bar. You can also use the keyboard shortcut (Ctrl+Shift+D).![]()
Start the run and debug session by clicking the greenDEBUG AND RUNicon, or go toRun>Start Debugging(F5).![]()
Disconnect from a Remote Host
You can close the VS Code remote connection by selectingFile>Close Remote Connectionfrom the VS Code menu. Alternatively, click the coloredremote sshnotification in the lower-left corner of the VS Code window and selectClose Remote Connectionfrom the list ofRemote-SSHcommands.
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:
Open the VS Code command palette (View>Command Palette). Enter remote in the command palette dialog box. SelectRemote-SSH: Kill VS Code Server on Host.You will be prompted to provide auser@hostvalue 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.