Tool Setup and Basic Use

Intel® DPC++ Compatibility Tool Developer Guide and Reference

Download PDF

ID 768918

Date 10/31/2024

Version

Public

Visible to Intel only — GUID: GUID-9A931A9E-CD71-42A9-AEC6-395DB8F724D2

View Details

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

NOTE:

c2s is an alias to the dpct command and may be used in its place.

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:
1. Select Tools > Options > Intel® DPC++ Compatibility Tool > General.
2. Select True (the default) for the Always show warnings after migration option.
3. Click OK.
To enable opening code side-by-side:
1. Select Tools > Options > Intel® DPC++ Compatibility Tool > General.
2. Select True (the default) for the Enable opening code side-by-side option.
3. 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.
1. Select Tools > Options > Intel® DPC++ Compatibility Tool > Tools.
2. Use the drop-down menu from the step above to select the appropriate version of the tool.
3. Select the default options (optional).
4. 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
Vector Add	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.
Folder Options	The Folder Options sample shows how to migrate more complex projects and use tool options.
Rodinia Needleman-Wunsch	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:

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Intel® DPC++ Compatibility Tool Developer Guide and Reference

Tool Setup and Basic Use

Before You Begin

Basic Use

Use Make/CMake* to Migrate a Complete Project on Linux*

Use Eclipse*

Use Microsoft Visual Studio*

Code Samples