ECMGenerateHeaders — Extra CMake Modules 5.21.0 documentation

# ECMGenerateHeaders

Generate C/C++ CamelCase forwarding headers.

    ecm_generate_headers(<camelcase_forwarding_headers_var>
        HEADER_NAMES <CamelCaseName> [<CamelCaseName> [...]]
        [ORIGINAL <CAMELCASE|LOWERCASE>]
        [OUTPUT_DIR <output_dir>]
        [PREFIX <prefix>]
        [REQUIRED_HEADERS <variable>]
        [COMMON_HEADER <HeaderName>]
        [RELATIVE <relative_path>])

For each CamelCase header name passed to HEADER_NAMES, a file of that name will be generated that will include a version with `.h` appended. For example, the generated header `ClassA` will include `classa.h` (or `ClassA.h`, see ORIGINAL). If a CamelCaseName consists of multiple comma-separated files, e.g. `ClassA,ClassB,ClassC`, then multiple camelcase header files will be generated which are redirects to the first header file. The file locations of these generated headers will be stored in <camelcase_forwarding_headers_var>.

ORIGINAL specifies how the name of the original header is written: lowercased or also camelcased. The default is LOWERCASE. Since 1.8.0.

PREFIX places the generated headers in subdirectories. This should be a CamelCase name like `KParts`, which will cause the CamelCase forwarding headers to be placed in the `KParts` directory (e.g. `KParts/Part`). It will also, for the convenience of code in the source distribution, generate forwarding headers based on the original names (e.g. `kparts/part.h`). This allows includes like `"#include <kparts/part.h>"` to be used before installation, as long as the include_directories are set appropriately.

OUTPUT_DIR specifies where the files will be generated; this should be within the build directory. By default, `${CMAKE_CURRENT_BINARY_DIR}` will be used. This option can be used to avoid file conflicts.

REQUIRED_HEADERS specifies an output variable name where all the required headers will be appended so that they can be installed together with the generated ones. This is mostly intended as a convenience so that adding a new header to a project only requires specifying the CamelCase variant in the CMakeLists.txt file; the original variant will then be added to this variable.

COMMON_HEADER generates an additional convenience header which includes all other header files.

The RELATIVE argument indicates where the original headers can be found relative to CMAKE_CURRENT_SOURCE_DIR. It does not affect the generated CamelCase forwarding files, but ecm_generate_headers() uses it when checking that the original header exists, and to generate originally named forwarding headers when PREFIX is set.

To allow other parts of the source distribution (eg: tests) to use the generated headers before installation, it may be desirable to set the INCLUDE_DIRECTORIES property for the library target to output_dir. For example, if OUTPUT_DIR is CMAKE_CURRENT_BINARY_DIR (the default), you could do

    target_include_directories(MyLib PUBLIC "$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>")

Example usage (without PREFIX):

    ecm_generate_headers(
        MyLib_FORWARDING_HEADERS
        HEADERS
            MLFoo
            MLBar
            # etc
        REQUIRED_HEADERS MyLib_HEADERS
        COMMON_HEADER MLGeneral
    )
    install(FILES ${MyLib_FORWARDING_HEADERS} ${MyLib_HEADERS}
            DESTINATION ${CMAKE_INSTALL_PREFIX}/include
            COMPONENT Devel)

Example usage (with PREFIX):

    ecm_generate_headers(
        MyLib_FORWARDING_HEADERS
        HEADERS
            Foo
            # several classes are contained in bar.h, so generate
            # additional files
            Bar,BarList
            # etc
        PREFIX MyLib
        REQUIRED_HEADERS MyLib_HEADERS
    )
    install(FILES ${MyLib_FORWARDING_HEADERS}
            DESTINATION ${CMAKE_INSTALL_PREFIX}/include/MyLib
            COMPONENT Devel)
    install(FILES ${MyLib_HEADERS}
            DESTINATION ${CMAKE_INSTALL_PREFIX}/include/mylib
            COMPONENT Devel)

Since pre-1.0.0.