Before You Begin

1. Install the tool.

   Intel® DPC++ Compatibility Tool is included in the Intel® oneAPI Base Toolkit. If you have not installed the Intel® oneAPI Base Toolkit, follow the instructions in the Installation Guide.

   The Intel® DPC++ Compatibility Tool is also available as a stand-alone download. Download the stand-alone tool.

2. Make sure CUDA headers are accessible to the tool.

   Certain CUDA header files (specific to your project) may need to be accessible to Intel® DPC++ Compatibility Tool. The tool looks for these CUDA header files in the following default locations:

   • /usr/local/cuda/include

   • /usr/local/cuda-x.y/include, where x.y is one of these values: 8.0, 9.x, 10.x, 11.x, 12.0-12.1.

   NOTE:

   If your CUDA installation is from a source other than NVIDIA, your header files may be in a different location. Locate your header files and use the --cuda-include-path=<path/to/cuda/include> option to specify the location when you run the tool.

   The CUDA include path should not be the same as, or a child path of, the directory where the source code (that needs to be migrated) is located.

3. Install a compiler that supports the DPC++ -specific extensions used in code migrated by Intel® DPC++ Compatibility Tool.

   • Intel® oneAPI DPC++/C++ Compiler

   • oneAPI DPC++ Compiler

4. Set environment variables using the setvars script.

5. Optional: If your program targets GPUs, install the appropriate GPU drivers or plug-ins to compile your program to run on Intel, AMD*, or NVIDIA* GPUs.

   • To use an Intel GPU, install the latest Intel GPU drivers.

   • To use an AMD GPU, install the oneAPI for AMD GPUs plugin.

   • To use an NVIDIA GPU, install the oneAPI for NVIDIA GPUs plugin.

Run the Tool

You can run Intel® DPC++ Compatibility Tool from the command line and provide migration instructions using the tool’s command-line options. The general command syntax is:

dpct [options] [<source0>... <sourceN>]

To see the list of the language parser (Clang*) options, pass -help as the Clang option:

dpct -- -help

For a complete list of command-line options, refer to the Command Line Options Reference.

Specify Files to Migrate

If no directory or file is specified for migration, the tool will try to migrate source files found in the current directory. The default output directory is dpct_output. Use the --out-root option to specify an output directory.

You can optionally provide file paths for source files that should be migrated. The paths can be found in the compilation database. The following examples show ways to specify a file or directory for migration.

• Migrate a single source file:

  dpct source.cpp

• Migrate all files available in the compilation database:

  dpct -p=<path to the location of compilation database file>

• Migrate one file in the compilation database:

  dpct -p=<path to the location of compilation database file> source.cpp

• Migrate source files in the directory specified by the --in-root option and place generated files in the directory specified by the --out-root option:

  dpct --in-root=foo --out-root=bar

Understand Emitted Warnings

During file migration, Intel® DPC++ Compatibility Tool identifies the places in the code that may require your attention to make the code SYCL-compliant or correct.

Warnings are inserted into the generated source files and displayed as warnings in the output. For example:

/path/to/file.hpp:26:1: warning: DPCT1003:0: Migrated API does not return error code. (*,0) is inserted. You may need to rewrite this code.
// source code line for which warning was generated
^

For more details on what a specific warning means, refer to the Diagnostic Reference.

Get Code Samples

Use the Intel® DPC++ Compatibility Tool code samples to get familiar with the migration process and tool features.

To access the samples:

• Use the oneAPI CLI Samples Browser to select a sample from the Intel® DPC++ Compatibility Tool category. For detailed information on downloading samples using the oneAPI CLI Samples Browser, as well as using an IDE to run the sample, refer to

  • Get Started Guide with the Intel® oneAPI Base Toolkit for Windows*

  • Get Started with the Intel® oneAPI Base Toolkit for Linux*

• Download the sample from GitHub*.

Each sample README provides detailed instructions for how to migrate the sample code.

Explore the complete list of oneAPI code samples in the oneAPI Samples Catalog (GitHub). These samples were designed to help you develop, offload, and optimize multiarchitecture applications targeting CPUs, GPUs, and FPGAs.

Migrate the Vector Add Sample

The Vector Add sample shows how to migrate a simple CUDA program to SYCL-compliant code. The simple program adds two vectors of [1..N] and prints the result. The program is intended for CPU.

The following steps show how to migrate the Vector Add sample using Intel® DPC++ Compatibility Tool:

1. Download the Vector Add sample.

2. Navigate to the root of the Vector Add sample. The sample contains a single CUDA file, vector_add.cu, located in the src folder.

3. From the root folder of the sample project, run Intel® DPC++ Compatibility Tool:

   dpct --in-root=. src/vector_add.cu

   The --in-root option specifies the root location of the program sources that should be migrated. Only files and folders within the --in-root directory will be considered for migration by the tool. Files outside the --in-root directory will not be migrated, even if they are included by a source file within the --in-root directory. By default, the migrated files are created in a new folder named dpct_output.

   As a result of the migration command, you should see the new SYCL source file in the output folder:

   dpct_output
   └── src
       └── vector_add.dp.cpp

   The relative paths of the migrated files are maintained.

4. Inspect the migrated source code and address any DPCT warnings generated by the too.

   This sample should generate the following warning:

   warning: DPCT1003:0: Migrated API does not return error code. (*, 0) is inserted. You may need to rewrite this code.

   Look up the DPCT1003 warning in the Diagnostic Reference.

   The reference explains that SYCL uses exceptions to report errors instead of error codes. In this instance, the tool removed the conditional statement to exit on failure and instead wrapped the code in a try block. The tool retained the error status variable from the original code and changed the source to always assign an error code of 0 to the variable.

   The reference provides suggestions for how to fix this warning. In this sample, manually resolve the issue by removing the variable status, since it is not needed.

5. Compile the migrated code:

   icpx -fsycl -I<install_dir>/include src/vector_add.dp.cpp

   where <install_dir> is the Intel® DPC++ Compatibility Tool installation directory.

6. Run the migrated program:

   NOTE:

   The Vector Add sample is for CPU. Make sure to target your CPU by using the ONEAPI_DEVICE_SELECTOR environment variable:

   ONEAPI_DEVICE_SELECTOR=*:cpu

   ./vector_add

   You should see a block of even numbers, indicating the result of adding two vectors: [1..N] + [1..N].

For detailed information about migration workflow, refer to Migration Workflow Guidelines.

Find More

* SYCL is a registered trademark of the Kronos Group, Inc.