Incremental Migration¶
The Intel® DPC++ Compatibility Tool 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 2 3 4 5 6 7 | #ifndef MACRO_A
... code path 1 ...
#elif MACRO_A == 1
... code path 2 ...
#else
... code path 3 ...
#endif
|
Incrementally migrate sample1.cu
by executing the dpct
command
in the same working directory as the file:
Generate
sample1.dp.cpp
, which contains migrated code for code path 1:dpct sample1.cu --out-root=out
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”
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 2 3 4 5 | #ifdef MACRO_A
... code path 1...
#else
... code path 2...
#endif
|
Content of source file sample2.cu
:
1 2 3 | #define MACRO_A
#include “sample_inc.h”
#undef MACRO_A
|
Content of source file sample3.cu
:
1 | #include “sample_inc.h”
|
Incrementally migrate the files by executing the dpct
command in the same
working directory as the files:
Generate
sample2.dp.cpp
andsample_inc.h
, which contains migrated code for code path 1:1
dpct sample2.cu --out-root=out
Generate
sample3.dp.cpp
andsample_inc.h
, which contains migrated code for code path 1 and code path 2:1
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:
Intel® DPC++ Compatibility Tool option
--no-incremental-migration
is specified.Different versions of the Intel® DPC++ Compatibility Tool are used across multiple migration invocations.
Different options of the Intel® DPC++ Compatibility Tool are used across multiple migration invocations. If the Intel® DPC++ Compatibility Tool detects that a previous migration used a different option-set, the Intel® DPC++ Compatibility Tool will stop migration and exit.
The following options direct the Intel® DPC++ Compatibility Tool 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