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.