Incremental Migration#

SYCLomatic provides incremental migration, which automatically merges the results from multiple migrations into a single migrated project.

Incremental migration can be used to

  • migrate a CUDA* project incrementally, for example 10 files at a time

  • migrate new CUDA files into an already migrated project

  • migrate multiple code paths

Incremental migration is enabled by default. Disable incremental migration using the --no-incremental-migration option.

Example 1: Migrate a File with Conditional Compilation Code#

This example shows incremental migration for a file sample1.cu that contains conditional compilation code. Content of sample1.cu:

1  #ifndef MACRO_A
2  ... code path 1 ...
3  #elif MACRO_A == 1
4  ... code path 2 ...
5  #else
6  ... code path 3 ...
7  #endif

Use the following steps to incrementally migrate sample1.cu.

  1. Generate sample1.dp.cpp, which contains migrated code for code path 1. From the same working directory as the file, run:

    dpct sample1.cu --out-root=out

  2. Generate sample1.dp.cpp, which contains migrated code for code path 1 and code path 2:

    dpct sample1.cu --out-root=out --extra-arg=”-DMACRO_A=1”

  3. Generate sample1.dp.cpp, which contains migrated code for code path 1, code path 2, and code path 3:

    dpct sample1.cu --out-root=out --extra-arg=”-DMACRO_A=2”

The result contains migrated code for each code path.

Example 2: Migrate a Header File Used by Multiple Source Files#

This example shows the use of incremental migration for a header file that is included in several source files, each with a different macro definition.

Content of header file sample_inc.h:

1  #ifdef MACRO_A
2  ... code path 1...
3  #else
4  ... code path 2...
5  #endif

Content of source file sample2.cu:

1  #define MACRO_A
2  #include "sample_inc.h"
3  #undef MACRO_A

Content of source file sample3.cu:

#include "sample_inc.h"

Use the following steps to incrementally migrate the files.

  1. Generate sample2.dp.cpp and sample_inc.h, which contains migrated code for code path 1.

    From the same working directory as the file, run:

    dpct sample2.cu --out-root=out

  2. Generate sample3.dp.cpp and sample_inc.h, which contains migrated code for code path 1 and code path 2:

    dpct sample3.cu --out-root=out

The result contains migrated code for each code path.

Limitations#

Incremental migration will not be triggered in the following conditions:

  1. SYCLomatic option --no-incremental-migration is specified.

  2. Different versions of SYCLomatic are used across multiple migration invocations.

  3. Different options of SYCLomatic are used across multiple migration invocations. If SYCLomatic detects that a previous migration used a different option-set, SYCLomatic will stop migration and exit.

The following options direct SYCLomatic to generate different migrated code and may break incremental migration. Use the same values for these options across migration invocations to keep incremental migration working.

  • --always-use-async-handler

  • --assume-nd-range-dim

  • --comments

  • --custom-helper-name

  • --enable-ctad

  • --keep-original-code

  • --no-cl-namespace-inline

  • --no-dpcpp-extensions

  • --no-dry-pattern

  • --optimize-migration

  • -p

  • --process-all

  • --sycl-named-lambda

  • --use-experimental-features

  • --use-explicit-namespace

  • --usm-level

  • --vcxprojfile