Migrate a Project on Linux*

Intel® DPC++ Compatibility Tool Developer Guide and Reference

Download PDF

ID 768918

Date 3/31/2023

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-0FACBFF3-C1FD-488C-B336-390021A975D7

View Details

Migrate a Project on Linux*

Use the Command Line

You can invoke Intel® DPC++ Compatibility Tool at the command line.

Use the 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 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 tool’s --out-root option to specify the directory where the SYCL* code produced by 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 how to migrate the Folder Options sample using Intel® DPC++ Compatibility Tool:

Get the Folder Options sample:
- Use the oneapi-cli utility to select the sample from the Intel® DPC++ Compatibility Tool category.
- 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.cu
```
From 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.cpp

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 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 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.

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.

Step 1: Create the Compilation Database

Get the Rodinia needleman-wunsch sample:
- Use the oneapi-cli utility to select the sample from the Intel® DPC++ Compatibility Tool category.
- 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 make
```
This 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=migration

The --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.cpp

Step 3: Verify the Source for Correctness and Fix Anything the 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 Intel® DPC++ Compatibility Tool could not migrate.

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Intel® DPC++ Compatibility Tool Developer Guide and Reference

Migrate a Project on Linux*

Use the Command Line

Use Make/CMake* to Migrate a Complete Project

Use Eclipse*