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.