Visible to Intel only — GUID: GUID-DC4E7AC8-321B-4775-8A20-E8FEF11B6B00
Visible to Intel only — GUID: GUID-DC4E7AC8-321B-4775-8A20-E8FEF11B6B00
Migrate a CMake Build Script
Intel® DPC++ Compatibility Tool supports migration of CMake build scripts by migrating a CUDA* specific CMake syntax to the SYCL* version. The migration capability can be extended and customized with a user-defined migration rule, which can be loaded with option --rule-file. The tool provides two command line options to trigger the migration of the CMake build script:
Option |
Description |
---|---|
--migrate-build-script=CMake |
EXPERIMENTAL. Migrate the CMake file(s). |
--migrate-build-script-only |
EXPERIMENTAL. Only migrate the build script(s). Default: off. |
Examples
Example 1: Migrate the CMake build script of a CUDA project:
dpct -in-root=./ -out-root=out -migrate-build-script-only
Example 2: Migrate the CMake build script of a CUDA project using a user-defined migration rule defined in rule_file.yaml:
dpct -in-root=./ -out-root=out -migrate-build-script-only --rule-file=rule_file.yaml
Example 3: Migrate the CMake build script of a CUDA project together with source code migration:
dpct -p=./ -in-root=./ -out-root=out --migrate-build-script=CMake
Customize Migration of CMake Build Script
To customize migration of a CMake build script, you can use the predefined built-in migration rules, or write a custom user-defined migration rule.
Use Predefined Migration Rules for CMake Build Script
The tool provides a set of predefined migration rules in the extensions/cmake_rules
folder on the install path. These predefined rules may be helpful in migrating your CMake build script.
Use the –rule-file option to specify the use of a predefined migration rule.
Write a Custom User-defined Migration Rule
You can customize the migration of your CMake file by defining a user-defined migration rule. Detailed information about writing your own user-defined migration rule, is provided in the Write User-defined Migration Rules section.
The following example demonstrates a user-defined CMake build script migration rule. The functionality of each field of the rule is detailed in the comment column. The example rule targets the CMake macro cuda_compile_ptx for migration, migrating cuda_compile_ptx(obj_file kernel.cu) to dpct_helper_compile_sycl_code (obj_file kernel.dp.cpp).
- Rule: rule_cuda_compile_ptx # Specify the unique name of the
rule
Kind: CMakeRule # The kind of the rule
Priority: Fallback # The priority of the rule
(Takeover, Default, Fallback)
CmakeSyntax: cuda_compile_ptx # The CMake syntax target to
migrate
In: cuda_compile_ptx(${device} ${value}) # Specify target pattern of
cuda_compile_ptx will be
migrated
Out: dpct_helper_compile_sycl_code(${device} ${value}) # Specify the
content of to migrate the content specified in “In” file
Subrules: # Subrules to further process
the field(s) of pattern
specified in “In” field
value: # Process the value file of
pattern specified in “In” file
MatchMode: Full # Specify the match mode of the
sub rule Full or Partial, default is Partial
In: ${arg}.cu # Replace the file name in *.cu
pattern to *.cp.cpp
Out: ${arg}.dp.cpp
For additional information on defining user-defined migration rules, refer to Migration Rules.
To write a user defined migration rule for CMake syntax:
Identify the CMake CUDA specific syntax that needs to be migrated. It is important to understand the usage case(s) of the CMake CUDA specific syntax.
Figure out the functionally equivalent SYCL-side mapping for CUDA CMake syntax, and test the mapping. If SYCL side functionally equivalent mapping is not available, consider adding a helper function, such as the helper function available in the dpct.cmake file on the tool install path.
Abstract the CMake syntax mapping between CUDA and SYCL into a pattern-based description in a yaml-based rule.
Test the functionality of the rule with lit cases by running the following command to make sure the migration rule is working as expected. If not, you may need to refine the migration rule defined in step 2.
dpct -in-root=./ -out-root out -rule-file=new_rule.yaml test.cmake
Use the new rule(s) to migrate your project.