Differential D23789 Diff 66670 modules/ECMGenerateExportHeader.cmake

Changeset View

Standalone View

View Options

modules/ECMGenerateExportHeader.cmake

  • This file was added.
1​#.rst:
2​# ECMGenerateExportHeader
3​# -----------------------
4​#
5​# This module provides the ``ecm_generate_export_header`` function for
6​# generating export macros for libraries with version-based control over
7​# visibility and compiler warnings for deprecated API for the library user,
8​# as well as over excluding deprecated API and their implementation when
9​# building the library itself.
10​#
11​# For preparing some values useful in the context it also provides a function
12​# ``ecm_export_header_format_version``.
13​#
14​# ::
15​#
16​# ecm_generate_export_header(<library_target_name>
17​# VERSION <version>
18​# [BASE_NAME <base_name>]
19​# [GROUP_BASE_NAME <group_base_name>]
20​# [EXPORT_MACRO_NAME <export_macro_name>]
21​# [EXPORT_FILE_NAME <export_file_name>]
22​# [DEPRECATED_MACRO_NAME <deprecated_macro_name>]
23​# [NO_EXPORT_MACRO_NAME <no_export_macro_name>]
24​# [INCLUDE_GUARD_NAME <include_guard_name>]
25​# [STATIC_DEFINE <static_define>]
26​# [PREFIX_NAME <prefix_name>]
27​# [DEPRECATED_BASE_VERSION <deprecated_base_version>]
28​# [DEPRECATION_VERSIONS <deprecation_version> [<deprecation_version2> [...]]]
29​# [EXCLUDE_DEPRECATED_BEFORE_AND_AT <exclude_deprecated_before_and_at_version>]
30​# [NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE]
31​# [CUSTOM_CONTENT_FROM_VARIABLE <variable>]
32​# )
33​#
34​# ``VERSION`` specifies the version of the library, given in the format
35​# "<major>.<minor>.<patch>".
36​#
37​# ``GROUP_BASE_NAME`` specifies the name to use for the macros defining
38​# library group default values. If set, this will generate code supporting
39​# ``<group_base_name>_NO_DEPRECATED_WARNINGS``,
40​# ``<group_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT``,
41​# ``<group_base_name>_DEPRECATED_WARNINGS_SINCE`` and
42​# ``<group_base_name>_NO_DEPRECATED`` (see below).
43​# If not set, the generated code will ignore any such macros.
44​#
45​# ``DEPRECATED_BASE_VERSION`` specifies the default version for warnings
46​# about API deprecated before. The default is the next minor version after
47​# "<exclude_deprecated_before_and_at_version>" if set, or "<major>.0.0", with
48​# <major> taken from <version>.
49​#
50​# ``DEPRECATION_VERSIONS`` specifies versions in "<major>.<minor>" format in
51​# which API was declared deprecated. Any version used with the generated
52​# macro `` <prefix_name><base_name>_DEPRECATED_VERSION(major, minor)`` needs
53​# to be listed here, otherwise the macro will fail to work.
54​#
55​# ``EXCLUDE_DEPRECATED_BEFORE_AND_AT`` specifies the version for which all API
56​# deprecated before and at should be excluded from the build completely.
57​# Possible values are "0" (default), "CURRENT" (which resolves to <version>)
58​# and a version string in the format "<major>.<minor>.<patch>".
59​#
60​# ``NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE`` specifies that the definition
61​# ``<prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT`` will
62​# not be set in the public interface of the library inside the build.
63​# The default is that it is set and to the version specified by
64​# ``EXCLUDE_DEPRECATED_BEFORE_AND_AT``, so e.g. test and examples part of the
65​# project automatically build against the full API included in the build.
66​#
67​#
68​# The function ``ecm_generate_export_header`` defines C++ preprocessor macros
69​# in the generated export header, some for use in the sources of the library
70​# the header is generated for, other for use by projects linking agsinst the
71​# library.
72​#
73​# The macros for use in the library C++ sources are these, next to those also
74​# defined by `GenerateExportHeader
75​# <https://cmake.org/cmake/help/latest/module/GenerateExportHeader.html>`_:
76​#
dfaureUnsubmitted
Done

typo: pther -> other

dfaure: typo: pther -> other
77​# ``<prefix_name><uppercase_base_name>_DEPRECATED_VERSION(major, minor)`` - to
78​# use to conditionally set a ``<prefix_name><uppercase_base_name>_DEPRECATED``
79​# macro for a class, struct or function (other elements to be supported in
80​# future versions), depending on the visibility macro flags set (see below)
81​#
82​# ``<prefix_name><uppercase_base_name>_ENABLE_DEPRECATED_SINCE(major, minor)``
83​# - evaluates to ``TRUE`` or ``FALSE`` depending on the visibility macro flags
84​# set (see below). To be used mainly with ``#if``/``#endif`` to mark sections
85​# of code which should be included depending on the visibility requested.
86​#
dfaureUnsubmitted
Done

(minor) small inconsistency, here you use '&' as separator between #if and #endif, while on line 80 you use '/'.

dfaure: (minor) small inconsistency, here you use '&' as separator between #if and #endif, while on…
87​# ``<prefix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor)``
88​# - evaluates to ``TRUE`` or ``FALSE`` depending on the value of
dfaureUnsubmitted
Done

I'm having trouble parsing the "only" in this sentence.

deprecated API only... that seems redundant, it's only API that gets deprecated :-)

Maybe you mean "to disable only at build time"?
Or "declaration-only code" ?

and it's always about build time... the choice is between building the library and building the users of the library, isn't it? It's all "build time" of someone...

dfaure: I'm having trouble parsing the "only" in this sentence. `deprecated API only`... that seems…
kossebauAuthorUnsubmitted
Not Done

I tried to reword things a bit, also changed all other places talking about build time to be explicit.

kossebau: I tried to reword things a bit, also changed all other places talking about build time to be…
89​# ``EXCLUDE_DEPRECATED_BEFORE_AND_AT`. To be used mainly with
90​# ``#if``/``#endif`` to mark sections of 2 types of code: implementation code
91​# for deprecated API and declaration code of deprecated API which only may be
92​# disabled at build time of the library for BC reasons (e.g. virtual methods,
93​# see notes below).
94​#
95​# ``<prefix_name><uppercase_base_name>_EXCLUDE_DEPRECATED_BEFORE_AND_AT`` -
96​# holds the version used to exclude deprecated API at build time of the
97​# library.
98​#
99​# The macros used to control visibility when building against the library are:
100​#
101​# ``<prefix_name><uppercase_base_name>_NO_DEPRECATED_WARNINGS`` - flag to
102​# define to disable all deprecation warnings
103​#
104​# ``<prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE_AND_AT`` -
105​# definition to set to a value in single hex number version notation
106​# (``0x<major><minor><patch>``).
107​#
108​# ``<prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE``
dfaureUnsubmitted
Done

"The tricks [....] does not work" is invalid grammar: either "The trick" (singular) or "do not work" (plural).

dfaure: "The tricks [....] does not work" is invalid grammar: either "The trick" (singular) or "do not…
109​#
110​# ``<prefix_name><uppercase_base_name>_NO_DEPRECATED`` - flag to define to disable all deprecated API
111​#
112​# Note: The tricks applied here for hiding deprecated API to the compiler
113​# when building against a library do not work for all deprecated API:
114​#
115​# * virtual methods need to stay visible to the compiler to build proper
116​# virtual method tables for subclasses
117​# * enumerators from enums cannot be simply removed, as this changes
118​# auto values of following enumerators, also can poke holes in enumerator
119​# series used as index into tables
120​#
121​# In such cases the API can be only "hidden" at build time of the library,
122​# itself, by generated hard coded macro settings, using
123​# ``<prefix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor)``.
124​#
125​# Examples:
126​#
127​# Preparing a library "Foo" created by target "foo", which is part of a group
128​# of libraries "Bar", where some API of "Foo" got deprecated at versions
129​# 5.0 & 5.12:
130​#
131​# .. code-block:: cmake
132​#
133​# ecm_generate_export_header(foo
134​# GROUP_BASE_NAME BAR
135​# VERSION ${FOO_VERSION}
136​# DEPRECATION_VERSIONS 5.0 5.12
137​# )
138​#
139​# In the library "Foo" sources in the headers the API would be prepared like
140​# this, using the generated macros ``FOO_ENABLE_DEPRECATED_SINCE`` and
141​# ``FOO_DEPRECATED_VERSION``:
142​#
143​# .. code-block:: cpp
144​#
145​# #include <foo_export.h>
146​#
147​# #if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
148​# /**
149​# * @deprecated Since 5.0
150​# */
151​# FOO_DEPRECATED_VERSION(5, 0)
152​# FOO_EXPORT void doFoo();
153​# #endif
154​#
155​# #if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
156​# /**
157​# * @deprecated Since 5.12
158​# */
159​# FOO_DEPRECATED_VERSION(5, 12)
160​# FOO_EXPORT void doBar();
161​# #endif
162​#
163​# Projects linking against the "Foo" library can control which part of its
164​# deprecated API should be hidden to the compiler by adding a definition
165​# using the ``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT`` macro variable set to the
166​# desired value (in version hex number notation):
167​#
168​# .. code-block:: cmake
169​#
170​# add_definitions(-DFOO_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000)
171​#
172​# Or using the macro variable of the group:
173​#
174​# .. code-block:: cmake
175​#
176​# add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000)
177​#
178​# If both are specified, ``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT`` will take
179​# precedence.
180​#
181​# To build a variant of a library with some deprecated API completely left
182​# out from the build, not only optionally invisible to consumers, one uses the
183​# ``EXCLUDE_DEPRECATED_BEFORE_AND_AT`` parameter. This is best combined with a
184​# cached CMake variable.
185​#
186​# .. code-block:: cmake
187​#
188​# set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control the range of deprecated API excluded from the build [default=0].")
189​#
190​# ecm_generate_export_header(foo
191​# VERSION ${FOO_VERSION}
192​# EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
193​# DEPRECATION_VERSIONS 5.0 5.12
194​# )
195​#
196​# The macros used in the headers for library consumers are reused for
197​# disabling the API excluded in the build of the library. For disabling the
198​# implementation of that API as well as for disabling deprecated API which
199​# only can be disabled at build time of the library for BC reasons, one
200​# uses the generated macro ``FOO_BUILD_DEPRECATED_SINCE``, like this:
201​#
202​# .. code-block:: cpp
203​#
204​# #include <foo_export.h>
205​#
206​# enum Bars {
207​# One,
208​# #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
209​# Two,
210​# #endif
211​# Three,
212​# };
213​#
214​# #if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
215​# /**
216​# * @deprecated Since 5.0
217​# */
218​# FOO_DEPRECATED_VERSION(5, 0)
219​# FOO_EXPORT void doFoo();
220​# #endif
221​#
222​# #if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
223​# /**
224​# * @deprecated Since 5.12
225​# */
226​# FOO_DEPRECATED_VERSION(5, 12)
227​# FOO_EXPORT void doBar();
228​# #endif
229​#
230​# class FOO_EXPORT Foo {
231​# public:
232​# #if FOO_BUILD_DEPRECATED_SINCE(5, 12)
233​# /**
234​# * @deprecated Since 5.12
235​# */
236​# FOO_DEPRECATED_VERSION(5, 12)
237​# virtual void doWhat();
238​# #endif
239​# };
240​#
241​# .. code-block:: cpp
242​#
243​# #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
244​# void doFoo()
245​# {
246​# // [...]
247​# }
248​# #endif
249​#
250​# #if FOO_BUILD_DEPRECATED_SINCE(5, 12)
251​# void doBar()
252​# {
253​# // [...]
254​# }
255​# #endif
256​#
257​# #if FOO_BUILD_DEPRECATED_SINCE(5, 12)
258​# void Foo::doWhat()
259​# {
260​# // [...]
261​# }
262​# #endif
263​#
264​# So e.g. if ``EXCLUDE_DEPRECATED_BEFORE_AND_AT`` is set to "5.0.0", the
265​# enumerator ``Two`` and the method ``::doFoo()`` will be effectively not
266​# available to library consumers, ``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT``
267​# cannot be used to reactivate the declaration, and ``Foo::doWhat`` will not
268​# have been built into the library binary.
269​#
270​# When using the ``NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE`` and the project
dfaureUnsubmitted
Done

Really? Isn't doWhat excluded only if EXCLUDE_DEPRECATED_BEFORE_AND_AT is set to 5.12.0?
With 5.0.0 it's still available, no?

I'm also surprised this paragraph talks about doWhat but not doBar, they both get disabled together, right?

dfaure: Really? Isn't doWhat excluded only if EXCLUDE_DEPRECATED_BEFORE_AND_AT is set to 5.12.0? With 5.
kossebauAuthorUnsubmitted
Not Done

Hm, indeed that text is bogus. Guess that was in draft mode still when I shuffled a lot with code snippets for the examples, but then I forgot to finish it up and missed the bits when skimming the doc text for completeness. Brushed over text coming in.

And going to give the whole documentation another calm concentrated read tonight myself again, seeing such things still in.

kossebau: Hm, indeed that text is bogus. Guess that was in draft mode still when I shuffled a lot with…
271​# for the "Foo" library includes also tests and examples linking against the
272​# library and using deprecated API (like tests covering it), one better
273​# explicitely sets ``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT`` for those targets
274​# to the version before and at which all deprecated API has been excluded from
275​# the build,
276​# Even more when building against other libraries from the same group "Bar" and
277​# disabling some deprecated API of those libraries using the group macro
dfaureUnsubmitted
Done

comma followed by uppercase letter is unusual grammar

dfaure: comma followed by uppercase letter is unusual grammar
278​# ``BAR_DISABLE_DEPRECATED_BEFORE_AND_AT``, which also works as default for
279​# ``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT``.
280​#
281​# To get the hex number style value the helper macro
282​# ``ecm_export_header_format_version()`` will be used:
283​#
284​# .. code-block:: cmake
285​#
286​# set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control what part of deprecated API is excluded from build [default=0].")
287​#
288​# ecm_generate_export_header(foo
289​# VERSION ${FOO_VERSION}
290​# GROUP_BASE_NAME BAR
291​# EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
292​# NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE
293​# DEPRECATION_VERSIONS 5.0 5.12
294​# )
295​#
296​# ecm_export_header_format_version(${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
297​# CURRENT_VERSION ${FOO_VERSION}
298​# HEXNUMBER_VAR foo_no_deprecated_before_and_at
299​# )
300​#
301​# # disable all deprecated API up to 5.9.0 from all other libs of group "BAR" that we use ourselves
302​# add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050900)
303​#
304​# add_executable(app app.cpp)
305​# target_link_libraries(app foo)
306​# target_compile_definitions(app
307​# PRIVATE "FOO_DISABLE_DEPRECATED_BEFORE_AND_AT=${foo_no_deprecated_before_and_at}")
308​#
309​# Since 5.64.0.
310​
311​#=============================================================================
312​# Copyright 2019 Friedrich W. H. Kossebau <kossebau@kde.org>
313​#
314​# Redistribution and use in source and binary forms, with or without
315​# modification, are permitted provided that the following conditions
316​# are met:
317​#
318​# 1. Redistributions of source code must retain the copyright
319​# notice, this list of conditions and the following disclaimer.
320​# 2. Redistributions in binary form must reproduce the copyright
321​# notice, this list of conditions and the following disclaimer in the
322​# documentation and/or other materials provided with the distribution.
323​# 3. The name of the author may not be used to endorse or promote products
324​# derived from this software without specific prior written permission.
325​#
326​# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
327​# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
328​# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
329​# IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
330​# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
331​# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
332​# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
333​# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
334​# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
335​# THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
336​
337​include(GenerateExportHeader)
338​include(CMakeParseArguments)
339​
340​# helper method
341​function(_ecm_geh_generate_hex_number _var_name _version)
342​ set(_hexnumber 0)
343​
344​ set(version_regex "^([0-9]+)\\.([0-9]+)\\.([0-9]+)$")
345​ string(REGEX REPLACE ${version_regex} "\\1" _version_major "${_version}")
346​ string(REGEX REPLACE ${version_regex} "\\2" _version_minor "${_version}")
347​ string(REGEX REPLACE ${version_regex} "\\3" _version_patch "${_version}")
348​ set(_outputformat)
349​ if (NOT CMAKE_VERSION VERSION_LESS 3.13)
350​ set(_outputformat OUTPUT_FORMAT HEXADECIMAL)
351​ endif()
352​ math(EXPR _hexnumber "${_version_major}*65536 + ${_version_minor}*256 + ${_version_patch}" ${_outputformat})
353​ set(${_var_name} ${_hexnumber} PARENT_SCOPE)
354​endfunction()
355​
356​function(ecm_export_header_format_version _version)
357​ set(options
358​ )
359​ set(oneValueArgs
360​ CURRENT_VERSION
361​ STRING_VAR
362​ HEXNUMBER_VAR
363​ )
364​ set(multiValueArgs
365​ )
366​ cmake_parse_arguments(ARGS "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
367​
368​ if (NOT ARGS_CURRENT_VERSION)
369​ message(FATAL_ERROR "No CURRENT_VERSION passed when calling ecm_export_header_format_version().")
370​ endif()
371​ if (NOT ARGS_STRING_VAR AND NOT ARGS_HEXNUMBER_VAR)
372​ message(FATAL_ERROR "No STRING_VAR or HEXNUMBER_VAR passed when calling ecm_export_header_format_version().")
373​ endif()
374​
375​ if(_version STREQUAL "CURRENT")
376​ set(_version ${ARGS_CURRENT_VERSION})
377​ endif()
378​
379​ if (ARGS_STRING_VAR)
380​ set(${ARGS_STRING_VAR} ${_version} PARENT_SCOPE)
381​ endif()
382​
383​ if (ARGS_HEXNUMBER_VAR)
384​ set(_hexnumber 0) # by default build all deprecated API
385​ if(_version)
386​ _ecm_geh_generate_hex_number(_hexnumber ${_version})
387​ endif()
388​ set(${ARGS_HEXNUMBER_VAR} ${_hexnumber} PARENT_SCOPE)
389​ endif()
390​endfunction()
391​
392​
393​function(ecm_generate_export_header target)
394​ set(options
395​ NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE
396​ )
397​ set(oneValueArgs
398​ BASE_NAME
399​ GROUP_BASE_NAME
400​ EXPORT_FILE_NAME
401​ DEPRECATED_BASE_VERSION
402​ VERSION
403​ EXCLUDE_DEPRECATED_BEFORE_AND_AT
404​ EXPORT_MACRO_NAME
405​ DEPRECATED_MACRO_NAME
406​ NO_EXPORT_MACRO_NAME
407​ INCLUDE_GUARD_NAME
408​ STATIC_DEFINE
409​ PREFIX_NAME
410​ CUSTOM_CONTENT_FROM_VARIABLE
411​ )
412​ set(multiValueArgs
413​ DEPRECATION_VERSIONS
414​ )
415​ cmake_parse_arguments(ARGS "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
416​
417​ # args sanity check
418​ if (NOT ARGS_VERSION)
419​ message(FATAL_ERROR "No VERSION passed when calling ecm_generate_export_header().")
420​ endif()
421​ if (ARGS_INCLUDE_GUARD_NAME AND CMAKE_VERSION VERSION_LESS 3.11)
422​ message(FATAL_ERROR "Argument INCLUDE_GUARD_NAME needs at least CMake 3.11 when calling ecm_generate_export_header().")
423​ endif()
424​ if (NOT ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT)
425​ set(ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT 0)
426​ elseif(ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT STREQUAL "CURRENT")
427​ set(ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT ${ARGS_VERSION})
428​ endif()
429​ if (NOT ARGS_DEPRECATED_BASE_VERSION)
430​ if (ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT)
431​ set(ARGS_DEPRECATED_BASE_VERSION "${ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT}")
432​ else()
433​ string(REGEX REPLACE "^([0-9]+)\\.([0-9]+)\\.([0-9]+)$" "\\1"
434​ _version_major "${ARGS_VERSION}")
435​ set(ARGS_DEPRECATED_BASE_VERSION "${_version_major}.0.0")
436​ endif()
437​ else()
438​ if (ARGS_DEPRECATED_BASE_VERSION VERSION_LESS ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT)
439​ message(FATAL_ERROR "DEPRECATED_BASE_VERSION cannot be lower than EXCLUDE_DEPRECATED_BEFORE_AND_AT when calling ecm_generate_export_header().")
440​ endif()
441​ endif()
442​ if(NOT ARGS_BASE_NAME)
443​ set(ARGS_BASE_NAME "${target}")
444​ endif()
445​ string(TOUPPER "${ARGS_BASE_NAME}" _upper_base_name)
446​ string(TOLOWER "${ARGS_BASE_NAME}" _lower_base_name)
447​
448​ if(NOT ARGS_EXPORT_FILE_NAME)
449​ set(ARGS_EXPORT_FILE_NAME "${_lower_base_name}_export.h")
450​ endif()
451​ string(REPLACE "." ", " _commaed_version "${ARGS_VERSION}")
452​ string(REPLACE "." ", " _commaed_deprecatedbaseversion "${ARGS_DEPRECATED_BASE_VERSION}")
453​
454​ set(_macro_base_name "${ARGS_PREFIX_NAME}${_upper_base_name}")
455​ if (ARGS_EXPORT_MACRO_NAME)
456​ set(_export_macro_name "${ARGS_EXPORT_MACRO_NAME}")
457​ else()
458​ set(_export_macro_name "${_macro_base_name}_EXPORT")
459​ endif()
460​ if (ARGS_NO_EXPORT_MACRO_NAME)
461​ set(_no_export_macro_name "${ARGS_NO_EXPORT_MACRO_NAME}")
462​ else()
463​ set(_no_export_macro_name "${_macro_base_name}_NO_EXPORT")
464​ endif()
465​ if (ARGS_DEPRECATED_MACRO_NAME)
466​ set(_deprecated_macro_name "${ARGS_DEPRECATED_MACRO_NAME}")
467​ else()
468​ set(_deprecated_macro_name "${_macro_base_name}_DEPRECATED")
469​ endif()
470​
471​ if(NOT IS_ABSOLUTE ${ARGS_EXPORT_FILE_NAME})
472​ set(ARGS_EXPORT_FILE_NAME "${CMAKE_CURRENT_BINARY_DIR}/${ARGS_EXPORT_FILE_NAME}")
473​ endif()
474​
475​ set_property(TARGET ${target} APPEND PROPERTY AUTOGEN_TARGET_DEPENDS "${ARGS_EXPORT_FILE_NAME}")
476​ # build with all the API not excluded, ensure all deprecated API is visible in the build itselt
477​ _ecm_geh_generate_hex_number(_hexnumber ${ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT})
478​ set(_disabling_definition "${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT=${_hexnumber}")
479​ target_compile_definitions(${target} PRIVATE "${_disabling_definition}")
480​ if (NOT ARGS_NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE)
481​ target_compile_definitions(${target} INTERFACE "$<BUILD_INTERFACE:${_disabling_definition}>")
482​ endif()
483​
484​ # generate header file
485​ set(_output "
486​#define ECM_GENERATEEXPORTHEADER_VERSION_VALUE(major, minor, patch) ((major<<16)|(minor<<8)|(patch))
487​"
488​ )
489​ if (ARGS_GROUP_BASE_NAME)
490​ string(TOUPPER "${ARGS_GROUP_BASE_NAME}" _upper_group_name)
491​ string(APPEND _output "
492​// Take any defaults from group settings
493​#if !defined(${_macro_base_name}_NO_DEPRECATED) && defined(${_upper_group_name}_NO_DEPRECATED)
494​# define ${_macro_base_name}_NO_DEPRECATED
495​#endif
496​#if !defined(${_macro_base_name}_NO_DEPRECATED_WARNINGS) && defined(${_upper_group_name}_NO_DEPRECATED_WARNINGS)
497​# define ${_macro_base_name}_NO_DEPRECATED_WARNINGS
498​#endif
499​#if !defined(${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT) && defined(${_upper_group_name}_DISABLE_DEPRECATED_BEFORE_AND_AT)
500​# define ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT ${_upper_group_name}_DISABLE_DEPRECATED_BEFORE_AND_AT
501​#endif
502​#if !defined(${_macro_base_name}_DEPRECATED_WARNINGS_SINCE) && defined(${_upper_group_name}_DEPRECATED_WARNINGS_SINCE)
503​# define ${_macro_base_name}_DEPRECATED_WARNINGS_SINCE ${_upper_group_name}_DEPRECATED_WARNINGS_SINCE
504​#endif
505​"
506​ )
507​ endif()
508​ string(APPEND _output "
509​#if defined(${_macro_base_name}_NO_DEPRECATED)
510​# undef ${_deprecated_macro_name}
511​# undef ${_deprecated_macro_name}_EXPORT
512​# undef ${_deprecated_macro_name}_NO_EXPORT
513​#elif defined(${_macro_base_name}_NO_DEPRECATED_WARNINGS)
514​# define ${_deprecated_macro_name}
515​# define ${_deprecated_macro_name}_EXPORT ${_export_macro_name}
516​# define ${_deprecated_macro_name}_NO_EXPORT ${_no_export_macro_name}
517​#else
518​# define ${_deprecated_macro_name} ${_macro_base_name}_DECL_DEPRECATED
519​# define ${_deprecated_macro_name}_EXPORT ${_macro_base_name}_DECL_DEPRECATED_EXPORT
520​# define ${_deprecated_macro_name}_NO_EXPORT ${_macro_base_name}_DECL_DEPRECATED_NO_EXPORT
521​#endif
522​"
523​ )
524​ if (ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT)
525​ message(STATUS "Excluding from build all API deprecated before and at: ${ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT}")
526​ # TODO: the generated code ideally would emit a warning if some consumer used a value
527​ # smaller then what the the build was done with
528​ string(REPLACE "." ", " _commaed_excluded_before_version "${ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT}")
529​ string(APPEND _output "
530​// Build was done with the API removed deprecated before: ${ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT}
531​#define ${_macro_base_name}_EXCLUDE_DEPRECATED_BEFORE_AND_AT ECM_GENERATEEXPORTHEADER_VERSION_VALUE(${_commaed_excluded_before_version})
532​
533​#ifdef ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT
534​# if ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT < ${_macro_base_name}_EXCLUDE_DEPRECATED_BEFORE_AND_AT
535​# undef ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT
536​# define ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT ${_macro_base_name}_EXCLUDE_DEPRECATED_BEFORE_AND_AT
537​# endif
538​#endif
539​
540​#define ${_macro_base_name}_BUILD_DEPRECATED_SINCE(major, minor) (ECM_GENERATEEXPORTHEADER_VERSION_VALUE(major, minor, 0) > ${_macro_base_name}_EXCLUDE_DEPRECATED_BEFORE_AND_AT)
541​"
542​ )
543​ else()
544​ string(APPEND _output "
545​// No deprecated API had been removed from build
546​#define ${_macro_base_name}_EXCLUDE_DEPRECATED_BEFORE_AND_AT 0
547​
548​#define ${_macro_base_name}_BUILD_DEPRECATED_SINCE(major, minor) 1
549​"
550​ )
551​ endif()
552​ string(APPEND _output "
553​#ifndef ${_macro_base_name}_DEPRECATED_WARNINGS_SINCE
554​# ifdef ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT
555​# define ${_macro_base_name}_DEPRECATED_WARNINGS_SINCE (${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT)
556​# else
557​# define ${_macro_base_name}_DEPRECATED_WARNINGS_SINCE ECM_GENERATEEXPORTHEADER_VERSION_VALUE(${_commaed_version})
558​# endif
559​#endif
560​
561​#ifndef ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT
562​# define ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT ECM_GENERATEEXPORTHEADER_VERSION_VALUE(${_commaed_deprecatedbaseversion})
563​#endif
564​
565​#ifdef ${_deprecated_macro_name}
566​# define ${_macro_base_name}_ENABLE_DEPRECATED_SINCE(major, minor) (ECM_GENERATEEXPORTHEADER_VERSION_VALUE(major, minor, 0) > ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT)
567​#else
568​# define ${_macro_base_name}_ENABLE_DEPRECATED_SINCE(major, minor) 0
569​#endif
570​"
571​ )
572​ if (DEFINED ARGS_DEPRECATION_VERSIONS)
573​ set(_major_versions)
574​ foreach(_version ${ARGS_DEPRECATION_VERSIONS})
575​ string(REPLACE "." ", " _commaed_version "${_version}")
576​ string(REPLACE "." "_" _underscored_version "${_version}")
577​ string(REGEX REPLACE "^([0-9]+)\\.([0-9]+)$" "\\1"
578​ _version_major "${_version}")
579​ # IN_LIST only since cmake 3.3
580​ set(_in_list FALSE)
581​ foreach(_v ${_major_versions})
582​ if (_v STREQUAL _version_major)
583​ set(_in_list TRUE)
584​ break()
585​ endif()
586​ endforeach()
587​ if(NOT _in_list)
588​ list(APPEND _major_versions ${_version_major})
589​ endif()
590​
591​ string(APPEND _output "
592​#if ${_macro_base_name}_DEPRECATED_WARNINGS_SINCE >= ECM_GENERATEEXPORTHEADER_VERSION_VALUE(${_commaed_version}, 0)
593​# define ${_macro_base_name}_DEPRECATED_VERSION_${_underscored_version} ${_deprecated_macro_name}
594​#else
595​# define ${_macro_base_name}_DEPRECATED_VERSION_${_underscored_version}
596​#endif
597​"
598​ )
599​ endforeach()
600​ foreach(_major_version ${_major_versions})
601​ string(APPEND _output
602​"#define ${_macro_base_name}_DEPRECATED_VERSION_${_major_version}(minor) ${_macro_base_name}_DEPRECATED_VERSION_${_major_version}_##minor
603​"
604​ )
605​ endforeach()
606​
607​ string(APPEND _output
608​"#define ${_macro_base_name}_DEPRECATED_VERSION(major, minor) ${_macro_base_name}_DEPRECATED_VERSION_##major(minor)
609​"
610​ )
611​ endif()
612​ if (ARGS_CUSTOM_CONTENT_FROM_VARIABLE)
613​ string(APPEND _output "${ARGS_CUSTOM_CONTENT_FROM_VARIABLE}\n")
614​ endif()
615​
616​ set(_header_file "${ARGS_EXPORT_FILE_NAME}")
617​ set(_header_work_file "${_header_file}.work")
618​
619​ # prepare optional arguments to pass through to generate_export_header
620​ set(_include_guard_name_args)
621​ if (ARGS_INCLUDE_GUARD_NAME)
622​ set(_include_guard_name_args INCLUDE_GUARD_NAME "${ARGS_INCLUDE_GUARD_NAME}")
623​ endif()
624​ set(_export_macro_name_args)
625​ if (ARGS_EXPORT_MACRO_NAME)
626​ set(_export_macro_name_args EXPORT_MACRO_NAME "${ARGS_EXPORT_MACRO_NAME}")
627​ endif()
628​ set(_no_export_macro_name_args)
629​ if (ARGS_NO_EXPORT_MACRO_NAME)
630​ set(_no_export_macro_name_args ARGS_NO_EXPORT_MACRO_NAME "${ARGS_NO_EXPORT_MACRO_NAME}")
631​ endif()
632​ set(_prefix_name_args)
633​ if (ARGS_PREFIX_NAME)
634​ set(_prefix_name_args PREFIX_NAME "${ARGS_PREFIX_NAME}")
635​ endif()
636​ set(_static_define_args)
637​ if (ARGS_STATIC_DEFINE)
638​ set(_static_define_args STATIC_DEFINE "${ARGS_STATIC_DEFINE}")
639​ endif()
640​ # for older cmake verions we have to manually append our generated content
641​ # for newer we use CUSTOM_CONTENT_FROM_VARIABLE
642​ set(_custom_content_args)
643​ if (NOT CMAKE_VERSION VERSION_LESS 3.7)
644​ set(_custom_content_args CUSTOM_CONTENT_FROM_VARIABLE _output)
645​ endif()
646​ generate_export_header(${target}
647​ BASE_NAME ${ARGS_BASE_NAME}
648​ DEPRECATED_MACRO_NAME "${_macro_base_name}_DECL_DEPRECATED"
649​ ${_prefix_name_args}
650​ ${_export_macro_name_args}
651​ ${_no_export_macro_name_args}
652​ ${_static_define_args}
653​ EXPORT_FILE_NAME "${_header_work_file}"
654​ ${_include_guard_name_args}
655​ ${_custom_content_args}
656​ )
657​
658​ if (CMAKE_VERSION VERSION_LESS 3.7)
659​ if (ARGS_INCLUDE_GUARD_NAME)
660​ set(_include_guard "ECM_GENERATEEXPORTHEADER_${ARGS_INCLUDE_GUARD_NAME}")
661​ else()
662​ set(_include_guard "ECM_GENERATEEXPORTHEADER_${_upper_base_name}_EXPORT_H")
663​ endif()
664​
665​ file(APPEND ${_header_work_file} "
666​
667​#ifndef ${_include_guard}
668​#define ${_include_guard}
669​
670​${_output}
671​
672​#endif // ${_include_guard}
673​"
674​ )
675​ endif()
676​
677​ # avoid rebuilding if there was no change
678​ execute_process(
679​ COMMAND ${CMAKE_COMMAND} -E copy_if_different "${_header_work_file}" "${_header_file}"
680​ )
681​ file(REMOVE "${_header_work_file}")
682​endfunction()