User Guide

  • 2021.2
  • 04/12/2021
  • Public Content

Developing a Visual Studio Code Project in a Docker Container

The Intel® oneAPI Toolkits support these compilers:
  • Intel® oneAPI DPC++ Compiler
  • Intel® Fortran Compiler
  • Intel® C++ Compiler
Containers allow you to set up and configure environments for building, running and profiling oneAPI applications and distribute them using images:
  • You can install an image containing an environment pre-configured with all the tools you need, then develop within that environment.
  • You can save an environment and use the image to move that environment to another machine without additional setup.
  • You can prepare containers with different sets of languages and runtimes, analysis tools, or other tools, as needed.

Download Docker* Image

You can download a Docker* image from the Containers Repository.
The Docker image is ~5 GB and can take ~15 minutes to download. It will require 25 GB of disk space.
image=intel/oneapi-basekit docker pull "$image"

Singularity Containers

Build a Singularity image using a Singularity file.

Create the Container

  1. Inside the Intel oneAPI project you just created, create a new file named
    Dockerfile
    with the following contents.
    FROM intel/oneapi-basekit
    This Dockerfile will create a local Docker image on your system based on a pre-configured oneAPI Docker container stored in Docker Hub.
    A complete list of preconfigured Docker containers for Intel oneAPI can be found here: https://hub.docker.com/r/intel/oneapi.
  2. Open the Command Palette (Ctrl-Shift-P) and run
    Remote-Containers: Open Folder in Remote Container
    .
  3. A folder selection window will appear. Choose the folder containing your Intel oneAPI project.
  4. When prompted, choose
    From 'Dockerfile'
    .
  5. VS Code will automatically use the Dockerfile you just created to download the image, create the container, and open the project inside of the container.
    The duration of this step depends on the time it takes to download the image and create the container. Refer to the Using Containers documentation for more details.
  6. VS Code will now show that it is connected to the container.

Configure the Container

In order to debug inside of the container, you must enable debugging flags and configure the Intel oneAPI development environment variables within the container. This can be done by editing the
.devcontainer/devcontainer.json
file.
Debugging is only available for CPU applications. Debugging Intel oneAPI GPU applications in VS Code is not supported at this time.
  1. An extension is required to debug Intel oneAPI projects inside of a container. The Microsoft VS Code C/C++ Extension is required to configure the GDB debugger. This can installed automatically by adding it to the container configuration file. Edit the "extensions" line in
    .devcontainer/devcontainer.json:
  2. // Add the IDs of extensions you want installed when the container is created. "extensions": ["ms-VS Code.cpptools"],
    The Intel extension is not POR and it is not available in the Marketplace.
  3. If you will be using a ptrace-based debugger for programming languages such as C++, Go, and Rust, you will need to enable debugging within the container. Uncomment the "runArgs" line in
    .devcontainer/devcontainer.json:
    // Uncomment when using a ptrace-based debugger like C++, Go, and Rust "runArgs": [ "--cap-add=SYS_PTRACE", "--security-opt", "seccomp=unconfined" ],
  4. In order to apply these changes to the container, it must be rebuilt. Open the Command Palette and run
    Remote-Containers: Rebuild Container
    .
  5. The container will be rebuilt and show that the extensions have been installed.

Build the Project

To build the project, follow the instructions in README.md. Note that when you open a Terminal in VS Code (Ctrl-Shift-`) while connected to a container, it opens a login terminal inside of the container.

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 the Container

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

Product and Performance Information

1

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