Get Started with the Intel® DPC++ Compatibility Tool (Beta)

Get Started

  • 0.09
  • 09/09/2020
  • Public Content
Contents

Get Started with the Intel® DPC++ Compatibility Tool

The
Intel® DPC++ Compatibility Tool
 assists in the migration of a developer's program that is written in CUDA* to a program written in
Data Parallel C++ (DPC++)
, which is based on modern C++ and incorporates portable industry standards such as SYCL*.
Visit the Intel® DPC++ Compatibility Tool User Guide for additional information about the tool. Visit the Release Notes for known issues and the most up-to-date information.
Migration will result into a project that is not entirely converted. Additional work, as outlined by the output of the Intel® DPC++ Compatibility Tool, is required to complete the conversion

Before You Begin

The
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.
Certain CUDA header files (specific to your project) may need to be accessible to the
Intel® DPC++ Compatibility Tool
. You can make them available to the tool by pointing to them with the
--cuda-include-path=<path/to/cuda/include>
 option in the
Intel® DPC++ Compatibility Tool
 command line.
If this option is not specified, then the
Intel® DPC++ Compatibility Tool
 looks for the CUDA header files in
/usr/local/cuda/include
 and
/usr/local/cuda-x.y/include
, where
x.y
 is one of these values: 8.0, 9.0, 9.1, 9.2, 10.0, 10.1, or 10.2.
Currently, the
Intel® DPC++ Compatibility Tool
 supports the migration of programs implemented with CUDA versions 8.0, 9.0, 9.1, 9.2, 10.0, 10.1, or 10.2. The list of supported languages and versions may be extended in the future.
To setup the
Intel® DPC++ Compatibility Tool
 environment, run:
  • On Linux:
    source /opt/intel/inteloneapi/setvars.sh
  • On Windows:
    Drive:\opt\intel\inteloneapi\setvars.bat

Linux Users

Use the Command Line

Emitted Warnings
The Intel® DPC++ Compatibility Tool notes the places in the code that may require your attention during the migration of the files in order to be DPC++ compliant. Comments are inserted into the generated source files and displayed as warnings in the output. For more details on what a particular warning means, see the Diagnostic Reference. An example is below: 
/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
^
Step 1: Migrate a Simple Test Project
The general invocation syntax from the operating system shell is: 
dpct [options] [<source0>... <sourceN>]
Built-in Usage Information
To see the list of the
Intel® DPC++ Compatibility Tool
 specific options, use the
--help
 option: 
dpct --help
To see the list of the language parser (Clang*) options, pass
-help
 as the Clang option: 
dpct -- -help
Basic Invocation on the Command Line
Use the steps below to migrate a basic program written in CUDA. Download the vector_add.cu zip file to follow along with the example provided.
  1. Create the basic CUDA program.
  2. Run the
    Intel® DPC++ Compatibility Tool
    : 
    dpct vector_add.cu
    The
    vector_add.dp.cpp
     file should appear in the
    dpct_output
     directory. Use: 
    cd dpct_output
    The file is now a
    DPC++
     source file.
  3. Verify the generated source code and fix the code that the
    Intel® DPC++ Compatibility Tool
     was unable to migrate. (The code used in this example is simple. In this instance, manual changes may not be needed.)
    You must add
    -I<dpct_root_folder>/include
     for the compilation of the migrated sample.
    For more complex sample instructions, go to the
    Intel® DPC++ Compatibility Tool
     User Guide's Usage Workflow Overview section.
Step 2: Migrate a Multi-File Project
The
Intel® DPC++ Compatibility Tool
 can be used to transform programs composed of multiple source and header files. These programs include headers from the system libraries and other projects. The
Intel® DPC++ Compatibility Tool
 must know which headers need migration and which should be left alone.
Use the
--in-root
 option to set the location of your program sources. Any source within the directory specified by
--in-root
 (at any nesting level) is migrated. Any header file within the directory specified by
--in-root
 (at any nesting level) that is included by the source or header file within the directory that is specified by
--in-root
 (at any nesting level) is migrated. Files from outside the
--in-root
 directory are considered system files and they will not be migrated even if they are included by any of your program source files.
The
--out-root
 option specifies the directory where the DPC++ code produced by the
Intel® DPC++ Compatibility Tool
 is written. The relative paths are maintained and the extension is changed to
.dp.cpp
.
For example:
  1. Download and unzip the
    foo.zip
     files to a temporary folder. This zip contains a CUDA program with three files in two folders.
  2. From the parent folder of the unzipped foo folder, run the
    Intel® DPC++ Compatibility Tool
    : 
    dpct --in-root=./foo --out-root=./result ./foo/main.cu ./foo/bar/util.cu --extra-arg="-I./foo/bar/"
    If the
    --in-root
     or
    --out-root
     option is not specified, the current working directory ('.') is implied.
  3. As a result, you should see the following files:
    • ./result/main.dp.cpp
    • ./result/bar/util.dp.cpp
    • ./result/bar/util.h
    For more complex sample instructions, go to the
    Intel® DPC++ Compatibility Tool
     User Guide's Usage Workflow Overview section. For more information on command line capabilities, review the Command Line Options Reference.
Step 3: Use make/cmake to Migrate a Complete Project
If your project uses Make or CMake, you can utilize compilation database support to provide compilation options, settings, macro definitions, and include paths to the
Intel® DPC++ Compatibility Tool
. The compilations database is a JSON* file containing the commands required to build a particular project. A compilations database can be generated by running the intercept-build script, which is provided as part of the
Intel® DPC++ Compatibility Tool
. The
Intel® DPC++ Compatibility Tool
 parses the compilation database and applies the necessary options when migrating the input sources.
Step 1: Create the Compilation Database
To create the compilation database, you need to configure your project and make sure it is cleaned. Then invoke the build command, prepending it with
intercept-build
.
For example: 
intercept-build make
The
intercept-build
 script runs your project's build command without building the original program. It also records all the compiler invocations and stores the names of the input files and the compiler options in the compilation database file:
compile_commands.json
.
Step 2: Use the Compilation Database with the
Intel® DPC++ Compatibility Tool
By default, the
Intel® DPC++ Compatibility Tool
 looks for the
compile_commands.json
 file in the current directory and uses the compiler options from it for each input file. The location of compilation database file can be changed using the
-p
 option, similar to the syntax below: 
dpct -p=<path to location of compilation database file> --in-root=../.. --out-root=dpct_output <some_file.cu>
For example: 
dpct -p=compile_commands.json --in-root=../.. --out-root=dpct_output *.cu
See the Usage Workflow Overview article in the
Intel® DPC++ Compatibility Tool
 User Guide for a Make/CMake project migration walk-through that is based on the open source code.

Use Eclipse*

Step 1. Install the Eclipse Plugins
The Eclipse plugins are installed automatically when you specify an instance of Eclipse during the installation of the
Intel® oneAPI Base Toolkit
.
Step 2: Migrate The Project
The following instructions assume you have set up the environment with the vars script.
  1. Run Eclipse within this environment.
  2. Open a CUDA project.
  3. Select this new project in
    Project Explorer
    .
  4. Run
    Project
    Migrate Project to DPC++
     from the top menu.
  5. The new project with the
    <project>_dpcpp
     name is created in your workspace.
Find More

Windows Users

Use the Command Line

Emitted Warnings
The Intel® DPC++ Compatibility Tool notes the places in the code that may require your attention during the migration of the files in order to be DPC++ compliant. Comments are inserted into the generated source files and displayed as warnings in the output. For more details on what a particular warning means, see the Diagnostic Reference . An example is below: 
/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
^
Migrate a vcxproj Project on Windows*
If your project uses Microsoft Visual Studio, you can use the
--vcxprojfile
 option to point to the project that requires migration. The
Intel® DPC++ Compatibility Tool
 will migrate the files you provided as an input files. For example: 
dpct --vcxprojfile=my_project.vcxproj --in-root=./ --out-root=output_proj my_main.cpp my_kernel.cu
The command specified above migrates
my_main.cpp
 and
my_kernel.cu
, if they are part of
my_project.vcxproj
. The result of the migration is sent to the
output_proj
 folder.
-OR- 
dpct --vcxprojfile=my_project.vcxproj --in-root=./ --out-root=output_proj
The command specified above migrates all relevant files the tool found in
my_project.vcxproj
. The result of the migration is sent to the
output_proj
 folder.

Use Microsoft Visual Studio*

You can use the
Intel® DPC++ Compatibility Tool
 within the Microsoft Visual Studio IDE to migrate your project to a
DPC++
 project. You must use a CUDA file to create a Windows* project prior to following the steps below.
Step 1: Select an Existing Project
To select an existing project in Microsoft Visual Studio:
  1. Select
    Project
    Migrate Project to DPC++
    .
  2. In the
    Select Project to Migrate
     dialog, click
    Browse
    .
  3. Select the directory and the existing project file in the
    Open
     dialog.
  4. Select the
    Configuration
     and
    Platform
     to migrate.
  5. Click
    OK
    .
Step 2: Specify the Migration Configuration
After selecting an existing project, you will see the
Migration Configuration
 dialog. These configurations have default values. You are able to specify the configurations, including the new project file name and directory, the
--in-root
 argument, and the additional options for the migration. The command line area is read-only and shows the command line that will be used to migrate the project. The migration starts once you click
OK
.
Step 3: Verify the Source for Correctness
Intel® DPC++ Compatibility Tool
 generates diagnostic messages during the migration. You may check the diagnostic messages in the
Intel® DPC++ Compatibility Tool
 view of Visual Studio. The view shows all the diagnostic messages in a table. The
Migrated Source File Location
 column shows the hyperlinks that send you to the line of
DPC++
 source files. The
Source File Location
 column shows the corresponding hyperlinks to the line of original source files. By default, the migrated source code and original source code are shown in side by side editors.
Step 4: Check the Detailed Diagnostic Messages
To learn more details about a diagnostic message, click the
Help
 hyperlink in the
Actions
 column, which is located in the table in the
Intel® DPC++ Compatibility Tool
 view. The detail about why the diagnostic message is generated and information on how to fix the issue are shown.
Specifying Options
You can set your preferences for using the
Intel® DPC++ Compatibility Tool
 within Microsoft Visual Studio:
  • To always show warnings after migration:
    1. Select
      Tools
      Options
      Intel DPC++ Compatibility Tool
      General
      .
    2. Select
      True
       (the default) for the
      Always show warnings after migration
       option.
    3. Click
      OK
      .
  • To enable opening code side-by-side:
    1. Select
      Tools
      Options
      Intel DPC++ Compatibility Tool
      General
      .
    2. Select
      True
       (the default) for the
      Enable opening code side-by-side
       option.
    3. Click
      OK
      .
  • To select a version of the tool:
    If you have multiple versions of the
    Intel® DPC++ Compatibility Tool
     installed, you can select which version to use.
    1. Select
      Tools
      Options
      Intel DPC++ Compatibility Tool
      Tools
      .
    2. Use the drop-down menu from the step above to select the appropriate version of the tool.
    3. Select the default options (optional).
    4. Click
      OK
      .

Find More

Content
Description and Links
On-Demand Webinar: Migrating Your Existing CUDA Code to DPC++ Code
Intel® DPC++ Compatibility Tool
 User Guide
Provides details on migrating CUDA* applications to Data Parallel C++ (DPC++): https://software.intel.com/en-us/intel-dpcpp-compatibility-tool-user-guide
Installation Guides for Intel® oneAPI Toolkits
SYCL specification version 1.2.1 PDF
The SYCL Specification PDF, explains how SYCL integrates OpenCL™ devices with modern C++: https://www.khronos.org/registry/SYCL/specs/sycl-1.2.1.pdf
Khronos* SYCL overview site
An overview of SYCL: https://www.khronos.org/sycl/
CUDA support in Clang
Proposed extensions to the SYCL specification

Notices and Disclaimers

Intel technologies may require enabled hardware, software or service activation.
No product or component can be absolutely secure.
Your costs and results may vary.
© Intel Corporation. Intel, the Intel logo, and other Intel marks are trademarks of Intel Corporation or its subsidiaries. Other names and brands may be claimed as the property of others.
No license (express or implied, by estoppel or otherwise) to any intellectual property rights is granted by this document.
The products described may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request.
Intel disclaims all express and implied warranties, including without limitation, the implied warranties of merchantability, fitness for a particular purpose, and non-infringement, as well as any warranty arising from course of performance, course of dealing, or usage in trade.

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