ROCMHeaderWrapper

Contents

ROCMHeaderWrapper#

Applies to Linux and Windows

2024-02-21

6 min read time

Commands#

rocm_wrap_header_file#
rocm_wrap_header_file(
    [HEADERS] <header-file> [<header-file>...]
    [HEADER_LOCATION <header-location>]
    [INCLUDE_LOCATION <include-location>]
    [GUARDS <guard>...]
    [WRAPPER_LOCATIONS <wrapper-location>...]
    [OUTPUT_LOCATIONS <output-location>...]
    [ORIGINAL_FILES <original-file>...]
)

Create a C/C++ wrapper file for each specified header file. The wrapper is simply a C/C++ header that emits a deprecation warning before including its corresponding header. The warning can be turned off by defining ROCM_NO_WRAPPER_HEADER_WARNING when using the wrapper header files. There is an additional configure-time CMake variable ROCM_HEADER_WRAPPER_WERROR, which is used to set the default value for the compile-time C macro of the same name (with CMake truthy values setting a default of true/1). If the compile-time macro is true, then deprecation errors will be emitted instead of warnings.

Any relative header or wrapper locations are relative to ${CPACK_PACKAGING_INSTALL_PREFIX} if it is set, or to ${CMAKE_INSTALL_PREFIX} otherwise (i.e. the install directory). Any relative output locations are relative to ${PROJECT_BINARY_DIR} (i.e. the build directory)

Each <header-file> is presumed to be installed to ${CMAKE_INSTALL_PREFIX}/<header-location>/<header-file>. If it is not specified, <header-location> defaults to include/${CMAKE_PROJECT_NAME} (e.g. include/rocblas).

The <include-location> parameter specifies the presumed compiler include directory, to correctly calculate suggested include directives.

Guards#

A guard item consists of the guard string <guard>, a wrapper location <wrapper-location>, and an output location <output-location>. You may specify any number of guard strings, wrapper locations and output locations. Guard items will be created from the arguments, and if necessary the following defaults will be used: * Default <guard>: WRAPPER * Default <wrapper-location>: ${CMAKE_PROJECT_NAME}/include * Default <output-location>: The associated <wrapper-location> If no guard items are specified, one will be created using all of the default values. Each guard item will create a wrapper file at ${PROJECT_BINARY_DIR}/<output-location>/<header-file> for each header file. This wrapper file will have the include guard ROCM_<guard>_<item-path>, where <item-path> is <header-file> with each / and . replaced with _. It assumes that it will be installed to ${CMAKE_INSTALL_PREFIX}/<wrapper-location>/<header-file>, and will include a relative path that is correct if it is installed to that location.

For example, suppose the project name is rocexample and consider the following:

rocm_wrap_header_file(
    foo/bar.h
    HEADER_LOCATION include/rocexample
    GUARDS
        EXAMPLE
        EXAMPLE_INC
    WRAPPER_LOCATIONS
        rocexample # EXAMPLE
    OUTPUT_LOCATIONS
        wrapper/rocexample # EXAMPLE
)

This will create two wrapper files.

The first wrapper file will be created at ${PROJECT_BINARY_DIR}/wrapper/rocexample/foo/bar.h. Its include guard will be ROCM_EXAMPLE_FOO_BAR_H, and it will include the file ../../include/rocexample/foo/bar.h (which is the correct file when this wrapper is installed at ${CMAKE_INSTALL_PREFIX}/rocexample/foo/bar.h).

The second wrapper file uses the default locations, so it will be created at ${PROJECT_BINARY_DIR}/rocexample/include/foo/bar.h. Its include guard will be ROCM_EXAMPLE_INC_FOO_BAR_H, and it will include the file ../../../include/rocexample/foo/bar.h (which is the correct file when this wrapper is installed at ${CMAKE_INSTALL_PREFIX}/rocexample/include/foo/bar.h)

If the name of the wrapper file being generated is the same as the name of any <original-file>, the contents of that <original-file> will be added to the wrapper file inside a #if 0 block. This has no effect on the code of the header, but it does allow projects which search for specific strings inside a header file to function correctly.

rocm_wrap_header_dir#
rocm_wrap_header_dir(
    <include-directory>
    [HEADER_LOCATION <header-location>]
    [GUARDS <guard>...]
    [WRAPPER_LOCATIONS <wrapper-location>...]
    [OUTPUT_LOCATIONS <output-location>...]
    [PATTERNS <pattern>...]
    [ORIGINAL_FILES <original-file>...]
)

Create a C/C++ wrapper file for each header file in the given directory (or any subdirectory) matching at least one pattern.

Each file in the specified directory which matches a pattern will have a wrapper file created for it. The <header-file> used in each call to rocm_wrap_header_file is the path to the header file relative to <include-directory>.

Contents