ECMGenerateHeaders — Extra CMake Modules 6.28.0 documentation

# ECMGenerateHeaders

Generate C/C++ CamelCase forwarding headers.

    ecm_generate_headers(<camelcase_forwarding_headers_var>
        HEADER_NAMES <CamelCaseName> [<CamelCaseName> [...]]
        [ORIGINAL <CAMELCASE|LOWERCASE>]
        [HEADER_EXTENSION <header_extension>]
        [OUTPUT_DIR <output_dir>]
        [PREFIX <prefix>]
        [SHARED_PREFIX <prefix>] # since 6.19
        [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` or, if set, `.<header_extension>` 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.

`HEADER_EXTENSION` specifies what file name extension is used for the header files. The default is “h”. Since 5.48.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.

`SHARED_PREFIX` works similar to `PREFIX`. It though assumes the original headers will be installed in the same subdirectory as the forwarding headers. So the generated files will include the original ones locally without any prefix. And the above mentioned pre-installation convenience forwarding headers based on the original names will be placed in the same subdirectory (e.g. `KParts/part.h`), to allow includes like `"#include <KParts/Part>"` to be used before installation and working properly. Since 6.19.0.

`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` or `SHARED_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 add to the `INCLUDE_DIRECTORIES` property of the library target the output_dir. If `OUTPUT_DIR` is `CMAKE_CURRENT_BINARY_DIR` (the default) and `CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE` is `ON` (as set by `KDECMakeSettings`), this is automatically done. Otherwise you could do (adapt if `OUTPUT_DIR` is something else)

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

Example usage (without `PREFIX` pr `SHARED_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)

Example usage (with `SHARED_PREFIX`):

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

Since pre-1.0.0.