ECMGenerateExportHeader¶
This module provides the ecm_generate_export_header
function for
generating export macros for libraries with version-based control over
visibility of and compiler warnings for deprecated API for the library user,
as well as over excluding deprecated API and their implementation when
building the library itself.
For preparing some values useful in the context it also provides a function
ecm_export_header_format_version
.
ecm_generate_export_header(<library_target_name>
VERSION <version>
[BASE_NAME <base_name>]
[GROUP_BASE_NAME <group_base_name>]
[EXPORT_MACRO_NAME <export_macro_name>]
[EXPORT_FILE_NAME <export_file_name>]
[DEPRECATED_MACRO_NAME <deprecated_macro_name>]
[NO_EXPORT_MACRO_NAME <no_export_macro_name>]
[INCLUDE_GUARD_NAME <include_guard_name>]
[STATIC_DEFINE <static_define>]
[PREFIX_NAME <prefix_name>]
[DEPRECATED_BASE_VERSION <deprecated_base_version>]
[DEPRECATION_VERSIONS <deprecation_version> [<deprecation_version2> [...]]]
[EXCLUDE_DEPRECATED_BEFORE_AND_AT <exclude_deprecated_before_and_at_version>]
[NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE]
[NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE]
[USE_VERSION_HEADER [<version_file_name>]] # Since 5.106
[VERSION_BASE_NAME <version_base_name>] # Since 5.106
[VERSION_MACRO_NAME <version_macro_name>] # Since 5.106
[CUSTOM_CONTENT_FROM_VARIABLE <variable>]
)
VERSION
specifies the version of the library, given in the format
“<major>.<minor>.<patchlevel>”.
GROUP_BASE_NAME
specifies the name to use for the macros defining
library group default values. If set, this will generate code supporting
<group_base_name>_NO_DEPRECATED_WARNINGS
,
<group_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT
,
<group_base_name>_DEPRECATED_WARNINGS_SINCE
and
<group_base_name>_NO_DEPRECATED
(see below).
If not set, the generated code will ignore any such macros.
DEPRECATED_BASE_VERSION
specifies the default version before and at which
deprecated API is disabled. Possible values are “0”, “CURRENT” (which
resolves to <version>) and a version string in the format
“<major>.<minor>.<patchlevel>”. The default is the value of
“<exclude_deprecated_before_and_at_version>” if set, or “<major>.0.0”, with
<major> taken from <version>.
DEPRECATION_VERSIONS
specifies versions in “<major>.<minor>” format in
which API was declared deprecated. Any version used with the generated
macro <prefix_name><base_name>_DEPRECATED_VERSION(major, minor, text)
or <prefix_name><base_name>_DEPRECATED_VERSION_BELATED(major, minor, textmajor, textminor, text)
needs to be listed here, otherwise the macro will fail to work.
EXCLUDE_DEPRECATED_BEFORE_AND_AT
specifies the version for which all API
deprecated before and at should be excluded from the build completely.
Possible values are “0” (default), “CURRENT” (which resolves to <version>)
and a version string in the format “<major>.<minor>.<patchlevel>”.
NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE
specifies that the definition
<prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE
will
not be set for the library inside its own build, and thus will be defined
by either explicit definition in the build system configuration or by the
default value mechanism (see below).
The default is that it is set for the build, to the version specified by
EXCLUDE_DEPRECATED_BEFORE_AND_AT
, so no deprecation warnings are
done for any own deprecated API used in the library implementation itself.
NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE
specifies that the definition
<prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT
will
not be set in the public interface of the library inside its own build, and
the same for the definition
<prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE
(if not
disabled by NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE
already).
The default is that they are set, to the version specified by
EXCLUDE_DEPRECATED_BEFORE_AND_AT
, so e.g. test and examples part of the
project automatically build against the full API included in the build and
without any deprecation warnings for it.
USE_VERSION_HEADER
defines whether a given header file
<version_file_name>
providing macros specifying the library version should
be included in the generated header file. By default angle-brackets are used
for the include statement. To generate includes with double quotes, add
double quotes to the argument string (needs escaping), e.g. \"version.h\"
.
The macro from the included version header holding the library version is
given as <version_macro_name>
by the argument VERSION_MACRO_NAME
and
used in the generated code for calculating defaults. If not specified, the
defaults for the version file name and the version macro are derived from
<version_base_name>
as passed with VERSION_BASE_NAME
, which again
defaults to <base_name>
or otherwise <library_target_name>
.
The macro name defaults to <uppercase_version_base_name>_VERSION
,
the version file name to <lowercase_version_base_name>_version.h
.
Since 5.106.
CUSTOM_CONTENT_FROM_VARIABLE
specifies the name of a variable whose
content will be appended at the end of the generated file, before any
final inclusion guard closing. Note that before 5.98 this was broken and
would only append the string passed as argument value.
The function ecm_generate_export_header
defines C++ preprocessor macros
in the generated export header, some for use in the sources of the library
the header is generated for, other for use by projects linking agsinst the
library.
The macros for use in the library C++ sources are these, next to those also defined by GenerateExportHeader:
<prefix_name><uppercase_base_name>_DEPRECATED_VERSION(major, minor, text)
to use to conditionally set a
<prefix_name><uppercase_base_name>_DEPRECATED
macro for a class, struct or function (other elements to be supported in future versions), depending on the visibility macro flags set (see below)<prefix_name><uppercase_base_name>_DEPRECATED_VERSION_BELATED(major, minor, textmajor, textminor, text)
to use to conditionally set a
<prefix_name><uppercase_base_name>_DEPRECATED
macro for a class, struct or function (other elements to be supported in future versions), depending on the visibility macro flags set (see below), withmajor
&minor
applied for the logic andtextmajor
&textminor
for the warnings message. Useful for retroactive tagging of API for the compiler without injecting the API into the compiler warning conditions of already released versions. Since 5.71.<prefix_name><uppercase_base_name>_ENUMERATOR_DEPRECATED_VERSION(major, minor, text)
to use to conditionally set a
<prefix_name><uppercase_base_name>_DEPRECATED
macro for an enumerator, depending on the warnings macro flags set (see below). In builds using C++14 standard or earlier, where enumerator attributes are not yet supported, the macro will always yield an empty string. With MSVC it is also always an empty string for now. Since 5.82.<prefix_name><uppercase_base_name>_ENUMERATOR_DEPRECATED_VERSION_BELATED(major, minor, textmajor, textminor, text)
to use to conditionally set a
<prefix_name><uppercase_base_name>_DEPRECATED
macro for an enumerator, depending on the warnings macro flags set (see below), withmajor
&minor
applied for the logic andtextmajor
&textminor
for the warnings message. In builds using C++14 standard or earlier, where enumerator attributes are not yet supported, the macro will always yield an empty string. Useful for retroactive tagging of API for the compiler without injecting the API into the compiler warning conditions of already released versions. With MSVC it is also always an empty string for now. Since 5.82.<prefix_name><uppercase_base_name>_ENABLE_DEPRECATED_SINCE(major, minor)
evaluates to
TRUE
orFALSE
depending on the visibility macro flags set (see below). To be used mainly with#if
/#endif
to mark sections of code which should be included depending on the visibility requested.<prefix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor)
evaluates to
TRUE
orFALSE
depending on the value ofEXCLUDE_DEPRECATED_BEFORE_AND_AT
. To be used mainly with#if
/#endif
to mark sections of two types of code: implementation code for deprecated API and declaration code of deprecated API which only may be disabled at build time of the library for BC reasons (e.g. virtual methods, see notes below).<prefix_name><uppercase_base_name>_EXCLUDE_DEPRECATED_BEFORE_AND_AT
holds the version used to exclude deprecated API at build time of the library.
The macros used to control visibility when building against the library are:
<prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT
definition to set to a value in single hex number version notation (
0x<major><minor><patchlevel>
).<prefix_name><uppercase_base_name>_NO_DEPRECATED
flag to define to disable all deprecated API, being a shortcut for settings
<prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT
to the current version. If both are set, this flag overrules.<prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE
definition to set to a value in single hex number version notation (
0x<major><minor><patchlevel>
). Warnings will be only activated for API deprecated up to and including the version. If<prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT
is set (directly or via the group default), it will default to that version, resulting in no warnings. Otherwise the default is the current version, resulting in warnings for all deprecated API.<prefix_name><uppercase_base_name>_NO_DEPRECATED_WARNINGS
flag to define to disable all deprecation warnings, being a shortcut for setting
<prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE
to “0”. If both are set, this flag overrules.
When the GROUP_BASE_NAME
has been used, the same macros but with the
given <group_base_name>
prefix are available to define the defaults of
these macros, if not explicitly set.
Warning
The tricks applied here for hiding deprecated API to the compiler when building against a library do not work for all deprecated API:
virtual methods need to stay visible to the compiler to build proper virtual method tables for subclasses
enumerators from enums cannot be simply removed, as this changes auto values of following enumerators, also can poke holes in enumerator series used as index into tables
In such cases the API can be only “hidden” at build time of the library,
itself, by generated hard coded macro settings, using
<prefix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor)
.
Examples:
Preparing a library “Foo” created by target “foo”, which is part of a group of libraries “Bar”, where some API of “Foo” got deprecated at versions 5.0 & 5.12:
ecm_generate_export_header(foo
GROUP_BASE_NAME BAR
VERSION ${FOO_VERSION}
DEPRECATION_VERSIONS 5.0 5.12
)
In the library “Foo” sources in the headers the API would be prepared like
this, using the generated macros FOO_ENABLE_DEPRECATED_SINCE
and
FOO_DEPRECATED_VERSION
:
#include <foo_export.h>
#if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
/**
* @deprecated Since 5.0
*/
FOO_EXPORT
FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()")
void doFoo();
#endif
#if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
/**
* @deprecated Since 5.12
*/
FOO_EXPORT
FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()")
void doBar();
#endif
Projects linking against the “Foo” library can control which part of its
deprecated API should be hidden to the compiler by adding a definition
using the FOO_DISABLE_DEPRECATED_BEFORE_AND_AT
macro variable set to the
desired value (in version hex number notation):
add_definitions(-DFOO_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000)
Or using the macro variable of the group:
add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000)
If both are specified, FOO_DISABLE_DEPRECATED_BEFORE_AND_AT
will take
precedence.
To build a variant of a library with some deprecated API completely left
out from the build, not only optionally invisible to consumers, one uses the
EXCLUDE_DEPRECATED_BEFORE_AND_AT
parameter. This is best combined with a
cached CMake variable.
set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control the range of deprecated API excluded from the build [default=0].")
ecm_generate_export_header(foo
VERSION ${FOO_VERSION}
EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
DEPRECATION_VERSIONS 5.0 5.12
)
The macros used in the headers for library consumers are reused for
disabling the API excluded in the build of the library. For disabling the
implementation of that API as well as for disabling deprecated API which
only can be disabled at build time of the library for BC reasons, one
uses the generated macro FOO_BUILD_DEPRECATED_SINCE
, like this:
#include <foo_export.h>
enum Bars {
One,
#if FOO_BUILD_DEPRECATED_SINCE(5, 0)
Two FOO_ENUMERATOR_DEPRECATED_VERSION(5, 0, "Use Three"), // macro available since 5.82
#endif
Three,
};
#if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
/**
* @deprecated Since 5.0
*/
FOO_EXPORT
FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()")
void doFoo();
#endif
#if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
/**
* @deprecated Since 5.12
*/
FOO_EXPORT
FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()")
void doBar();
#endif
class FOO_EXPORT Foo {
public:
#if FOO_BUILD_DEPRECATED_SINCE(5, 0)
/**
* @deprecated Since 5.0
*/
FOO_DEPRECATED_VERSION(5, 0, "Feature removed")
virtual void doWhat();
#endif
};
#if FOO_BUILD_DEPRECATED_SINCE(5, 0)
void doFoo()
{
// [...]
}
#endif
#if FOO_BUILD_DEPRECATED_SINCE(5, 12)
void doBar()
{
// [...]
}
#endif
#if FOO_BUILD_DEPRECATED_SINCE(5, 0)
void Foo::doWhat()
{
// [...]
}
#endif
So e.g. if EXCLUDE_DEPRECATED_BEFORE_AND_AT
is set to “5.0.0”, the
enumerator Two
as well as the methods ::doFoo()
and Foo::doWhat()
will be not available to library consumers. The methods will not have been
compiled into the library binary, and the declarations will be hidden to the
compiler, FOO_DISABLE_DEPRECATED_BEFORE_AND_AT
also cannot be used to
reactivate them.
When using the NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE
and the project
for the “Foo” library includes also tests and examples linking against the
library and using deprecated API (like tests covering it), one better
explicitly sets FOO_DISABLE_DEPRECATED_BEFORE_AND_AT
for those targets
to the version before and at which all deprecated API has been excluded from
the build.
Even more when building against other libraries from the same group “Bar” and
disabling some deprecated API of those libraries using the group macro
BAR_DISABLE_DEPRECATED_BEFORE_AND_AT
, which also works as default for
FOO_DISABLE_DEPRECATED_BEFORE_AND_AT
.
To get the hex number style value the helper macro
ecm_export_header_format_version()
will be used:
set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control what part of deprecated API is excluded from build [default=0].")
ecm_generate_export_header(foo
VERSION ${FOO_VERSION}
GROUP_BASE_NAME BAR
EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE
DEPRECATION_VERSIONS 5.0 5.12
)
ecm_export_header_format_version(${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
CURRENT_VERSION ${FOO_VERSION}
HEXNUMBER_VAR foo_no_deprecated_before_and_at
)
# disable all deprecated API up to 5.9.0 from all other libs of group "BAR" that we use ourselves
add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050900)
add_executable(app app.cpp)
target_link_libraries(app foo)
target_compile_definitions(app
PRIVATE "FOO_DISABLE_DEPRECATED_BEFORE_AND_AT=${foo_no_deprecated_before_and_at}")
Since 5.64.0.