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-B4AAEC92-6E18-4115-B5AF-55D4FECAEFCA
Visible to Intel only — GUID: GUID-B4AAEC92-6E18-4115-B5AF-55D4FECAEFCA
Tool Setup and Basic Use
Before You Begin
Install and set up Intel® DPC++ Compatibility Tool.
Refer to Get Started with the Intel® DPC++ Compatibility Tool for installation and setup information.
Basic Use
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>]
If no directory or file is specified for migration, the tool will try to migrate source files found in the current directory. The default output directory is dpct_output. Use the --out-root option to specify an alternate output directory.
You can specify the file path for source files that should be migrated. If using a compilation database, you can find your source code paths in the compilation database file.
The Folder Options sample shows an example of specifying a directory for migration and a specific output folder. For example:
Linux
dpct --in-root=foo --out-root=result/foo foo/main.cu foo/bar/util.cu
Windows
dpct --in-root=foo --out-root=result\foo foo\main.cu foo\bar\util.cu
For detailed instructions on how to use the Folder Options sample, refer to the sample README.
Use Make/CMake* to Migrate a Complete Project on Linux*
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. For example:
dpct --compilation-database=compile_commands.json --in-root=. --out-root=migration
Intel® DPC++ Compatibility Tool parses the compilation database and applies the necessary options when migrating the input sources. Refer to Generate a Compilation Database for detailed information about generating a compilation database.
The Needleman-Wunsch Sample shows an example of migrating a Make/CMake project, using a compilation database to provide project details to the tool.
For detailed instructions on how to use the Needleman-Wunsch sample, refer to the sample README.
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.
Use Microsoft Visual Studio*
You can use Intel® DPC++ Compatibility Tool within the Microsoft Visual Studio IDE to migrate your project to a SYCL project.
Step 1: Select an Existing Project and Start Migration
To select an existing project in Microsoft Visual Studio and start migration:
From the Extensions menu, select Browse Intel® oneAPI Samples
Select Rodinia NW DPCT from the Intel® DPC++ Compatibility Tool category.
Select the Project menu >Migrate Project to DPC++.
In the Select Project to Migrate dialog, click Browse.
Select the directory and the existing project file in the Open dialog.
Select the Configuration and Platform to migrate.
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 can 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
Verify the migration of the source code that uses variables 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 sample README files.
Step 4: Check the Detailed Diagnostic Messages
To learn more 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. Details 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 Intel® DPC++ Compatibility Tool within Microsoft Visual Studio:
To always show warnings after migration:
Select Tools > Options > Intel® DPC++ Compatibility Tool > General.
Select True (the default) for the Always show warnings after migration option.
Click OK.
To enable opening code side-by-side:
Select Tools > Options > Intel® DPC++ Compatibility Tool > General.
Select True (the default) for the Enable opening code side-by-side option.
Click OK.
To select a version of the tool:
If you have multiple versions of Intel® DPC++ Compatibility Tool installed, you can select which version to use.
Select Tools > Options > Intel® DPC++ Compatibility Tool > Tools.
Use the drop-down menu from the step above to select the appropriate version of the tool.
Select the default options (optional).
Click OK.
Code Samples
Use the Intel® DPC++ Compatibility Tool code samples to get familiar with the migration process and tool features.
Each sample README provides detailed instructions for how to migrate the sample code.
Sample Project |
Description |
|---|---|
The Vector Add sample shows how to migrate a simple program from CUDA* to SYCL*. You can use this sample to verify that your development environment is set up correctly to use Intel® DPC++ Compatibility Tool. |
|
The Folder Options sample shows how to migrate more complex projects and use tool options. |
|
The Rodinia Needleman-Wunsch sample demonstrates how to migrate a Make/CMake* project from CUDA to SYCL. |
Explore the complete list of oneAPI code samples in the oneAPI Samples Catalog (GitHub). These samples were designed to help you develop, offload, and optimize multiarchitecture applications targeting CPUs, GPUs, and FPGAs.
To access the samples:
Select a sample from the Intel® DPC++ Compatibility Tool category, using the oneapi-cli utility
Download the sample from GitHub*.
The Intel® oneAPI Base Toolkit Get Started Guides more information on downloading samples. See also: