Migrate a Project on Linux*¶
Use the Command Line¶
Programs may 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) may be migrated. Any header file within the directory specified by
--in-root
(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 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:
Open the Folder Options sample in one of the following ways:
Use the oneapi-cli utility to select a sample from the Intel® DPC++ Compatibility Tool category.
Download 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
).Use the tool’s
--in-root
option and provide input files to specify where to locate the CUDA files that need migration. Use the--out-root
option designate where to generate the resulting files. From the parent folder of the unzipped foo folder, run the Intel® DPC++ Compatibility Tool:1
dpct --in-root=foo --out-root=result/foo foo/main.cu foo/bar/util.cu --extra-arg="-Ifoo/bar/"
If the
--in-root
option is not specified, the directory of the first input source file is implied. If the--out-root
option is not specified,./dpct_output
is implied.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 DPCT warnings generated, and verify correctness of the new program. 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.
Open the Rodinia NW DPCT sample in one of the following ways:
Use the oneapi-cli utility to select a sample from the Intel® DPC++ Compatibility Tool category.
Download from GitHub*: https://github.com/oneapi-src/oneAPI-samples/tree/master/Tools/Migration
Clean the application:
1
make clean
Step 1: Create the Compilation Database
When using CMake: Before running intercept-build, configure and generate your
Makefile out of CMakeLists.txt
. An example of a typical command is cmake...
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:
1 | 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
.
Note
The example below assumes the CUDA headers are available at /usr/local/cuda/include
.
Replace this path according to where they reside on your system.
Once the intercept build is run, review the output in the compile_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, similar to the syntax below:
1 | dpct -p=<path to location of compilation database file> --in-root=../.. --out-root=dpct_output <some_file.cu>
|
The command above will migrate <some_file.cu>
if the information about it can
be found in compiler_commands.json
by <path to location of compilation database file>
.
To migrate all relevant files recorded inside the compilation database, use
the command similar to below:
1 | 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
Note
The Intel® DPC++ Compatibility Tool will attempt to migrate the sources. For the code
that could not be migrated, it inserts comments with additional insights into
the generated source files. Use grep
in the generated source files for
DPCT10
. This will show you if any comments have been inserted by the
Intel® DPC++ Compatibility Tool.
Note
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 make the code DPC++ compliant or correct. 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 Diagnostics Reference. An example is below:
1 2 3 | /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 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 that are declared using preprocessor directives. Inspect the migrated source code, address any DPCT warnings generated, and verify correctness of the new program. 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