Migrate a CMake Build Script#

SYCLomatic 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

Note

View a demo example of CMake-based apps in Velocity-Bench.

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

Note

dpct_helper_compile_sycl_code() is provided by the tool. It is located in dpct.cmake in the cmake folder on the install path, during the CMake script migration, dpct.cmake will be copied to the root folder of the migrated project and as a part of the migrated project.

- 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:

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

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

  3. Abstract the CMake syntax mapping between CUDA and SYCL into a pattern-based description in a yaml-based rule.

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

  5. Use the new rule(s) to migrate your project.