Learn How to Compile and Debug Data Parallel C++ Programs Using Eclipse*

Published: 12/31/2019  

Last Updated: 12/30/2019

By Loc Q Nguyen

This guide describes how to use the Eclipse* Integrated Development Environment (IDE) to compile and debug Data Parallel C++ (DPC++) programs on a Linux* OS host. For the current Intel® oneAPI Base Toolkit (Base Kit) beta release, debugging with Eclipse supports only CPU kernel offload. To compile and debug in CLI mode, refer to Get Started with Debugging Data Parallel C++ for Linux* OS Host (Beta).

In this article, you will learn how to:

  • Install Eclipse
  • Integrate Eclipse with the DPC++ compiler
  • Compile and run a DPC++ sample program
  • Configure Eclipse to debug a DPC++ sample program

Step 1: Install Eclipse*

To get started, you need Eclipse v4.9 or above and Eclipse C/C++ Development Tools (CDT) 9.3 or above.

  1. Download the latest Eclipse Installer eclipse-inst-linux64.tar.gz.
  2. Extract the files.
  3. Start the installer executable file and select Eclipse IDE for C/C++ Developers. Select a folder for the Eclipse installation.

Step 2: Integrate Eclipse with the DPC++ Compiler

If you haven’t yet installed the Base Kit, follow these steps:

  1. Go to the Intel® oneAPI Toolkits website.
  2. Download and install the oneAPI toolkit by clicking Get the Base Kit.
  3. During installation, you are asked if you want to set up your IDE. Click Select Eclipse* IDE Configuration, and browse to select the Eclipse installation path.

Intel oneAPI base toolkit installation dialog screen capture

File selection dialog screenshot

If the Base kit is already installed, you can install Eclipse as described in Step 1. In addition, you need to complete the following steps.

  1. Search for the Eclipse Plugins in the Base Kit:
cd <oneAPI install dir>/inteloneapi
find . -type f -regextype awk -regex ".*(com.intel|org.eclipse).*[.]zip"
./compiler/2021.1-beta03/linux/ide_support/com.intel.compiler.p2.oneapi-19.1.0SNAPSHOT.zip
./compiler/2021.1-beta03/linux/ide_support/com.intel.dpcpp.compiler.p2-2021.1.0-SNAPSHOT.zip
./advisor/2021.1-beta03/ide-support/com.intel.launchers.update-advisor-1.0.0-SNAPSHOT.zip
./dpcpp-ct/2021.1-beta03/ide_support/com.intel.dpct.p2-2021.1.0-SNAPSHOT.zip
./dev-utilities/2021.1-beta03/ide-support/eclipse/com.intel.samples.update-1.0.0-SNAPSHOT.zip
./vtune/2021.1-beta03/ide-support/com.intel.launchers.update-amplifier-1.0.0-SNAPSHOT.zip
  1. In Eclipse, select Help -> Install New Software... The Install wizard opens.
  2. Click Add to open a dialog box.
  3. In the Add Repository box, click Archive… to open a file browser.
  4. In the file browser, go to the /opt/intel/inteloneapi/compiler/2021-1-beta03/linux/ide-support directory (found in the previous step).
  5. Double-click the com.intel.compiler.p2.oneapi-19.1.0-SNAPSHOT.zip plugin, then click Add.

Eclipse plugin installation dialog

  1. Click Select All, and then click Next.
  2. Restart Eclipse.

Eclipse plugin installation configuration dialog

Step 3: Compile and Run a DPC++ Sample Program

This step describes how to compile and run a Data Parallel C++ program with Eclipse. It uses a DPC++ sample program as an example.

  1. Set up the proper environment variables for the oneAPI toolkit in a terminal:
source <oneAPI install dir>/setvars.sh
  1. Start Eclipse:
<eclipse_install_dir>/cpp-2019-09/eclipse/eclipse
  1. Click Launch to display the Eclipse IDE for C/C++ Developers. Click on Create a new C/C++ project.
  2. To create a new project:
    1. Go to File -> Choose New Project.
    2. Under C/C++ Choose C/C++ Project, click Next.
    3. Choose C++ Managed Build, then click Next.
    4. Name the project, for example “array-transform”.
    5. Choose the Hello World DPC++ Project, then click Finish. (Note that in the Toolchain field, Intel® oneAPI DPC++ Compiler is selected.)
    6. Click Finish to create a new project. This will create the <eclipse-workspace>/array-transform workspace directory. In this example, we work with a sample program called array-transform.cpp, which is available in the intel/BaseKit-code-samples GitHub repository.

Eclipse project creation dialog

  1. Copy the sample array-transform.cpp program from the Intel oneAPI Base Toolkit code sample package to the working folder:
cp <BaseKit-code-samples_install_dir>/Debugger/array-transform/src/array-transform.cpp <eclipse-workspace>/array-transform/.
  1. Delete the main.cpp file from the project: right-click on main.cpp and select Delete.
  2. Refresh the project: right-click on array-transform and select Refresh. You should see the array-transform.cpp file appearing in the project.

Eclipse application screenshot showing project file context menu

Eclipse application screenshot showing project context menu

  1. To compile the program, select Project -> Build Project.

Eclipse application screenshot showing project menu

  1. To run the executable file, select Run -> Run.

Eclipse application screenshot showing run menu

Step 4: Configure Eclipse to Debug a DPC++ Program

In the current oneAPI toolkit beta release, debugging with Eclipse only supports debugging the CPU kernel offload. Debugging the GPU kernel offload is not yet supported.

To configure the Eclipse debugger:

  1. In Eclipse, select Run -> Debug Configurations to create a Debug Configuration window.
  2. In the Debugger tab, set the GDB debugger to use the gdb-oneapi debugger:
<oneAPI install dir>/debugger/latest/gdb/intel64/bin/gdb-oneapi

Debug configurations dialog with debugger tab selected

  1. In the Environment tab, set:
    1. DISABLE_AUTO_ATTACH=1 to turn off auto-attach, which conflicts with Eclipse
    2. SYCL_DEVICE_TYPE=CPU to enforce kernel running in CPU
  2. Click Apply.

Debug configuration dialog with environment tab selected

  1. To start debugging in Eclipse, select Run -> Debug.
  2. In the Debugger windows, create a breakpoint at line 49 of the array-transform.cpp file, then type continue. You will see multiple threads hit this breakpoint:
(gdb) break 49
(gdb) continue

Eclipse application screenshot demonstrating debugging session

7. You can now use the usual GDB* commands:

  • F5 key to step into
  • F6 key to step over
  • F7 key  for step return
  • F8 key for resume

For example, to print the local variable index and the value of acc_in[index]:

(gdb) print index
(gdb) print acc_in[index]

To examine four word-size items in decimal format:

(gdb) x /4dw acc_in

To go to another thread:

(gdb) continue

To examine a current thread in a multi-thread program:

(gdb) set scheduler-locking on
(gdb) next

You can also examine the values of local variables and registers:

(gdb)info locals
(gdb)info registers
(gdb)info registers all

Finally, to terminate the GDB:

(gdb) quit

Summary

You are now ready to get started using DPC++ in the Eclipse IDE. Use the references below to learn more about programming with DPC++, and visit the site Intel® oneAPI Toolkits to learn how oneAPI products deliver the tools you need to develop and deploy your applications and solutions across multiple architectures.

References

Product and Performance Information

1

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