Migrate a Project on Linux*¶
Use the Command Line¶
You can invoke the Intel® DPC++ Compatibility Tool at the command line.
Use the dpct
tool’s --in-root
option to specify the location of the
source that should be migrated:
Any source within the
--in-root
directory (at any nesting level) may be migrated.Any header file within the
--in-root
directory (at any nesting level) that is included by the source or header file, which is being migrated, is also migrated.Files from outside the
--in-root
directory are considered system files and will not be migrated even if they are included by any of your program source files.If the
--in-root
option is not specified, the directory of the first input source file is implied.
Use the dpct
tool’s --out-root
option to specify the directory where the
DPC++ code produced by the Intel® DPC++ Compatibility Tool is written:
Relative paths of the migrated files are maintained.
Extensions are changed to
.dp.cpp
.If the
--out-root
option is not specified,./dpct_output
is implied.
The following steps show migration of the Folder Options sample using the
dpct
tool:
Open the Folder Options sample in one of the following ways:
Use the oneapi-cli utility to select the Folder Options sample from the Intel® DPC++ Compatibility Tool category.
Download the Folder Options sample from GitHub*: https://github.com/oneapi-src/oneAPI-samples/tree/master/Tools/Migration
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
, andutil.h
) located in two folders (foo
andbar
).From the parent folder of the unzipped foo folder, run the Intel® DPC++ Compatibility Tool:
dpct --in-root=foo --out-root=result/foo foo/main.cu foo/bar/util.cu --extra-arg="-Ifoo/bar/"
Use the
--in-root
option to specify the location of the CUDA files that need migration. Use the--out-root
option to specify the location for the migrated files.As a result, you should see the following files:
./result/foo/main.dp.cpp
./result/foo/bar/util.dp.cpp
./result/foo/bar/util.h
Inspect the migrated source code, address any generated DPCT warnings, and verify correctness of the new program.
Review Emitted Warnings for additional information about inserted warnings and comments.
For the most accurate and detailed instructions of addressing warnings, see 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 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 compilation database can be generated by running
the intercept-build
script, which is provided as part of the
Intel® DPC++ Compatibility Tool. intercept-build
supports the capture of compilation
command lines for files with the following extensions: .c
, .C
, .cc
,
.CC
, .cp
, .cpp
, .cxx
, .c++
, .C++
, .txx
, and .cu
.
The Intel® DPC++ Compatibility Tool parses the compilation database and applies the necessary options when migrating the input sources.
This example uses the Rodinia NW DPCT sample to demonstrate the use of a compilation database.
Step 1: Create the Compilation Database
Open the Rodinia NW DPCT sample in one of the following ways:
- Use the oneapi-cli utility to select the Rodinia NW DPCT sample from the
Intel® DPC++ Compatibility Tool category.
- Download the Rodinia NW DPCT sample from GitHub*:
https://github.com/oneapi-src/oneAPI-samples/tree/master/Tools/Migration
When using CMake: Before running
intercept-build
, configure and generate your Makefile out ofCMakeLists.txt
. An example of a typical command iscmake ...
.Clean the application:
make clean
Invoke the build command, prepending it with
intercept-build
:intercept-build make
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 thecompile_commands.json
file. The content of this file should look like this example:1 2 3 4 5 6
[{ "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 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 the compilation database file can be changed using the -p
option.
For example, the following command will migrate some_file.cu
if the
information about it can be found in compiler_commands.json
, located at
<some_path>
.
dpct -p=some_path --in-root=../.. --out-root=dpct_output some_file.cu
To migrate all relevant files recorded inside the compilation database, use a command similar to:
dpct -p compile_commands.json --in-root=. --out-root=migration
If you run the command above with the Rodinia NW DPCT sample, you
should see the following files in the migration
out folder:
needle.h
needle_kernel.dp.cpp
needle.dp.cpp
Step 3: Verify the Source for Correctness and Fix Anything the Intel® DPC++ Compatibility Tool was Unable to Migrate
Verify the migration of the source code that uses variables declared using preprocessor directives. Inspect the migrated source code, address any generated DPCT warnings, and verify correctness of the new program.
Review Emitted Warnings for additional information about inserted warnings and comments.
For the most accurate and detailed instructions on addressing warnings, see 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 the Intel® DPC++ Compatibility Tool could not migrate.