Intel® DPC++ Compatibility Tool Developer Guide and Reference
A newer version of this document is available. Customers should click here to go to the newest version.
Visible to Intel only — GUID: GUID-47DCC8D9-FBB8-45B1-83BF-6B037758192F
Visible to Intel only — GUID: GUID-47DCC8D9-FBB8-45B1-83BF-6B037758192F
Migrate a Project on Linux*
Use the Command Line
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 Intel® DPC++ Compatibility Tool–specific options, use --help:
dpct --helpIf 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.
Migrate the Folder Options Sample
The following steps show how to migrate the Folder Options sample using Intel® DPC++ Compatibility Tool:
Get the Folder Options sample:
Select a sample from the Intel® DPC++ Compatibility Tool category, using the oneapi-cli utility
Download the sample from GitHub*.
Navigate to the root of the sample project.
The Folder Options sample project contains a simple CUDA* program with three files (main.cu, util.cu, and util.h) located in two folders (foo and bar):
foo ├── bar │ ├── util.cu │ └── util.h └── main.cuFrom the root folder of the sample project, run Intel® DPC++ Compatibility Tool:
dpct --in-root=foo --out-root=result/foo foo/main.cu foo/bar/util.cu --extra-arg="-Ifoo/bar/"The --in-root option specifies the location of the CUDA files that need migration. The --out-root option specifies the location for the migrated files.
As a result of the migration command, you should see the following files:
result/foo ├── bar │ ├── util.dp.cpp │ └── util.h └── main.dp.cppInspect the migrated source code, address any generated DPCT warnings, and verify correctness of the new program.
Review Understand Emitted Warnings for additional information about inserted warnings and comments.
For details on addressing warnings generated when migrating code samples, refer to the Addressing Warnings in the Migrated Code section of the sample README files.
For more information on command line capabilities, review the Command Line Options Reference.
Use Make/CMake* to Migrate a Complete Project
If your project uses Make or CMake, you can use a compilation database to provide compilation options, settings, macro definitions, and include paths to Intel® DPC++ Compatibility Tool. Refer to Generate a Compilation Database for detailed information about generating a compilation database.
Intel® DPC++ Compatibility Tool parses the compilation database and applies the necessary options when migrating the input sources.
This example uses the Rodinia needleman-wunsch sample to demonstrate the use of a compilation database, following three high-level steps:
Step 1: Create the Compilation Database
Get the Rodinia needleman-wunsch sample:
Select a sample from the Intel® DPC++ Compatibility Tool category, using the oneapi-cli utility
Download the sample from GitHub*.
When using CMake: Before running intercept-build, configure and generate your Makefile out of CMakeLists.txt. An example of a typical command is cmake ....
Invoke the build command, prepending it with intercept-build.
$ make clean $ intercept-build makeThis creates the file compile_commands.json in the working directory.
The intercept-build script runs your project’s build command without building the original program. It 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.
NOTE:This example assumes the CUDA headers are available at /usr/local/cuda/include. Replace this path according to where they reside on your system.Once intercept build is run, review the output in the compile_commands.json file. The content of this file should look like this example:
[{ "command" : "nvcc -c -o needle -I/usr/local/cuda/include -D__CUDA_ARCH__=400 " "-D__CUDACC__=1 needle.cu", "directory" : "/home/user/projects/DPCPP_CT/rodinia_3.1/cuda/nw", "file" : "/home/user/projects/DPCPP_CT/rodinia_3.1/cuda/nw/needle.cu" }]
Step 2: Use the Compilation Database with the Migration Tool
By default, 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.
Use the following command to migrate the CUDA code in the Rodinia needleman-wunsch sample, using the compilation database generated in the previous step:
dpct -p=compile_commands.json --in-root=. --out-root=migrationThe --in-root option sets the root location of the CUDA files that need migration. Only files and folders located within the --in-root directory will be considered for migration by the tool.
The --out-root option specifies the location for the migrated files. The new project will be created in the migration directory.
The -p option specifies the path for the compilation database.
After running the migration command, you should see the following files in the migration output folder:
migration
└── src
├── needle.h
├── needle_kernel.dp.cpp
└── needle.dp.cppStep 3: Verify the Migrated Source
Verify the migration of the source code that uses variables declared using preprocessor directives.
Inspect the migrated source code and address any generated DPCT warnings.
Verify correctness of the new program.
Review Understand Emitted Warnings for additional information about inserted warnings and comments.
For details on addressing warnings generated when migrating code samples, refer to the Addressing Warnings in the Migrated Code section of the samples README files.
Use Eclipse*
The Eclipse plugins are installed automatically when you specify an instance of Eclipse during the installation of the Intel® oneAPI Base Toolkit.
To access and use the samples within Eclipse:
Open Eclipse*
Select the Intel® menu, then Browse Intel® oneAPI Samples, and browse to the preferred sample
With the new project open, select Migrate Project to DPC++
The migration creates a new project and warnings are displayed directly in the Eclipse* window
Verify the source for correctness and fix anything Intel® DPC++ Compatibility Tool could not migrate.