Get Started with SYCLomatic#

SYCLomatic assists in the migration of your existing CUDA* code to SYCL* code. The tool ports CUDA language kernels and library API calls, migrating 90%-95% of CUDA code to SYCL code. The tool additionally inserts inline warnings to help you complete the migration and tune your code.

SYCLomatic supports migrating programs implemented with CUDA versions 8.0, 9.x, 10.x, 11.x, 12.0-12.3. The list of supported languages and versions may be extended in the future.

For additional information about the tool, refer to the SYCLomatic Developer Guide and Reference.

For detailed information about migration workflow, refer to Migration Workflow Guidelines.

Before You Begin#

Install the tool.

SYCLomatic is available in the SYCLomatic GitHub repo. Review the README for detailed instructions to set up and build the tool.
Make sure CUDA headers are accessible to the tool.

Certain CUDA header files (specific to your project) may need to be accessible to SYCLomatic. The tool looks for these CUDA header files in the following default locations:
- /usr/local/cuda/include
- /usr/local/cuda-x.y/include, where x.y is one of these values: 8.0, 9.x, 10.x, 11.x, 12.0-12.3.
Note

If your CUDA installation is from a source other than NVIDIA, your header files may be in a different location. Locate your header files and use the --cuda-include-path=<path/to/cuda/include> option to specify the location when you run the tool.

The CUDA include path should not be the same as, or a child path of, the directory where the source code (that needs to be migrated) is located.
Install a compiler that supports the DPC++ -specific extensions used in code migrated by SYCLomatic.
- Intel® oneAPI DPC++/C++ Compiler
- oneAPI DPC++ Compiler

Configure environment variables.

To configure the SYCLomatic environment, set the following environment variables:

Linux

export PATH=$PATH_TO_C2S_INSTALL_FOLDER/bin:$PATH
export CPATH=$PATH_TO_C2S_INSTALL_FOLDER/include:$CPATH

Windows (64-bit)

SET PATH=%PATH_TO_C2S_INSTALL_FOLDER%\bin;%PATH%
SET INCLUDE=%PATH_TO_C2S_INSTALL_FOLDER%\include;%INCLUDE%
SET CPATH=%PATH_TO_C2S_INSTALL_FOLDER%\include;%CPATH%

If you use the Intel® oneAPI DPC++/C++ Compiler, make sure to set environment variables using the setvars script.

Optional: If your program targets GPUs, install the appropriate GPU drivers or plug-ins to compile your program to run on Intel, AMD*, or NVIDIA* GPUs.
- To use an Intel GPU, install the latest Intel GPU drivers.
- To use an AMD GPU, install the oneAPI for AMD GPUs plugin.
- To use an NVIDIA GPU, install the oneAPI for NVIDIA GPUs plugin.

Run the Tool#

You can run SYCLomatic 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.

To see the list of the language parser (Clang*) options, pass -help as the Clang option:

dpct -- -help

For a complete list of command-line options, refer to the Command Line Options Reference.

Specify Files to Migrate#

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

You can optionally provide file paths for source files that should be migrated. The paths can be found in the compilation database. The following examples show ways to specify a file or directory for migration.

Migrate a single source file:
```
dpct source.cpp
```

Migrate all files available in the compilation database:

dpct -p=<path to the location of compilation database file>

Migrate one file in the compilation database:

dpct -p=<path to the location of compilation database file> source.cpp

Migrate source files in the directory specified by the --in-root option and place generated files in the directory specified by the --out-root option:
```
dpct --in-root=foo --out-root=bar
```

Understand Emitted Warnings#

During file migration, SYCLomatic identifies the places in the code that may require your attention to make the code SYCL-compliant or correct.

Warnings are inserted into the generated source files and displayed as warnings in the output. For example:

/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
^

For more details on what a specific message means, refer to the Diagnostics Reference.

Get Code Samples#

Use the SYCLomatic code samples to get familiar with the migration process and tool features.

All samples are available on GitHub*.

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

Migrate the Vector Add Sample#

The Vector Add sample shows how to migrate a simple CUDA program to SYCL-compliant code. The simple program adds two vectors of [1..N] and prints the result. The program is intended for CPU.

The following steps show how to migrate the Vector Add sample using SYCLomatic:

Download the Vector Add sample.
Navigate to the root of the Vector Add sample. The sample contains a single CUDA file, vector_add.cu, located in the src folder.
From the root folder of the sample project, run SYCLomatic:
```
dpct --in-root=. src/vector_add.cu
```
The --in-root option specifies the root location of the program sources that should be migrated. Only files and folders within the --in-root directory will be considered for migration by the tool. Files outside the --in-root directory will not be migrated, even if they are included by a source file within the --in-root directory. By default, the migrated files are created in a new folder named dpct_output.

As a result of the migration command, you should see the new SYCL source file in the output folder:
```
dpct_output
└── src
    └── vector_add.dp.cpp
```
The relative paths of the migrated files are maintained.
Inspect the migrated source code and address any DPCT warnings generated by the too.

This sample should generate the following warning:
```
warning: DPCT1003:0: Migrated API does not return error code. (*, 0) is inserted. You may need to rewrite this code.
```
Look up the DPCT1003 warning in the Diagnostic Reference.

The reference explains that SYCL uses exceptions to report errors instead of error codes. In this instance, the tool removed the conditional statement to exit on failure and instead wrapped the code in a try block. The tool retained the error status variable from the original code and changed the source to always assign an error code of 0 to the variable.

The reference provides suggestions for how to fix this warning. In this sample, manually resolve the issue by removing the variable status, since it is not needed.
Compile the migrated code:
```
icpx -fsycl -I<install_dir>/include src/vector_add.dp.cpp
```
where <install_dir> is the SYCLomatic installation directory.
Run the migrated program:
Note

The Vector Add sample is for CPU. Make sure to target your CPU by using the ONEAPI_DEVICE_SELECTOR environment variable:
```
ONEAPI_DEVICE_SELECTOR=*:cpu
```
```
./vector_add
```
You should see a block of even numbers, indicating the result of adding two vectors: [1..N] + [1..N].