Differential D23789 Diff 65655 modules/ECMGenerateExportHeader.cmake

Changeset View

Standalone View

View Options

modules/ECMGenerateExportHeader.cmake

  • This file was added.
1​#.rst:
2​# ECMGenerateExportHeaders
3​# ------------------------
4​#
5​# This module provides the ``ecm_generate_export_header`` function for generating
6​# export macros for libraries with version-based control over visibility and
7​# compiler warnings for deprecated API.
8​# For preparing some values useful in the context it also provides a function
9​# ``ecm_export_header_format_version``.
10​#
11​# ::
12​#
13​# ecm_generate_export_header(<target_name>
14​# VERSION <version>
15​# [BASE_NAME <base_name>]
16​# [GROUP_BASE_NAME <group_base_name>]
17​# [EXPORT_MACRO_NAME <export_macro_name>]
18​# [EXPORT_FILE_NAME <export_file_name>]
19​# [DEPRECATED_MACRO_NAME <deprecated_macro_name>]
20​# [NO_EXPORT_MACRO_NAME <no_export_macro_name>]
21​# [INCLUDE_GUARD_NAME <include_guard_name>]
22​# [STATIC_DEFINE <static_define>]
23​# [PREFIX_NAME <prefix_name>]
24​# [DEPRECATED_BASE_VERSION <deprecated_base_version>]
25​# [EXCLUDE_DEPRECATED_BEFORE <exclude_deprecated_before_version>]
26​# [DEPRECATION_VERSIONS <deprecation_version> [<deprecation_version2> [...]]]
27​# [CUSTOM_CONTENT_FROM_VARIABLE <variable>]
28​# )
29​#
30​# ``VERSION`` specifies the version of the library, given in the format
31​# "<major>.<minor>.<patch>".
32​#
33​# ``GROUP_BASE_NAME`` specifies the name to use for the macros defining
34​# library group default values. If set, this will generate code supporting
35​# ``<group_base_name>_NO_DEPRECATED_WARNINGS``,
36​# ``<group_base_name>_DISABLE_DEPRECATED_BEFORE``,
37​# ``<group_base_name>_DEPRECATED_WARNINGS_SINCE`` and
38​# ``<group_base_name>_NO_DEPRECATED`` (see below).
39​# If not set, the generated code will ignore any such macros.
40​#
41​# ``DEPRECATED_BASE_VERSION`` specifies the default version for warnings
42​# about API deprecated before. The default is
43​# "<exclude_deprecated_before_version>" if set, or "<major>.0.0", with <major>
44​# taken from <version>.
45​#
46​# ``DEPRECATION_VERSIONS`` specifies versions in "<major>.<minor>" format in
47​# which API was declared deprecated. Any version used with the generated
48​# macro `` <prefix_name><base_name>_DEPRECATED_VERSION(major, minor)`` needs
49​# to be listed here, otherwise the macro will fail to work.
50​#
51​# ``EXCLUDE_DEPRECATED_BEFORE`` specifies the version in the format
52​# "<major>.<minor>.<patch>", for which all API deprecated before should be
53​# excluded from the build completely.
54​#
55​# Possible values are "0", "CURRENT" and a version string in the format
56​# "<major>.<minor>.<patch>".
57​#
58​# The macro generates code in the export header, some for use in the sources
59​# of the library the header is generated for, other for use by projects
60​# linking agsinst the library.
61​#
62​# The macros for use in the library C++ sources are these, next to those also
63​# defined by `GenerateExportHeader
64​# <https://cmake.org/cmake/help/latest/module/GenerateExportHeader.html>`_:
65​#
66​# ``<prefix_name><uppercase_base_name>_DEPRECATED_VERSION(major, minor)`` - to
67​# use to conditionally set a ``<prefix_name><uppercase_base_name>_DEPRECATED``
68​# macro for a class, struct or function (pther elements to be supported in
69​# future versions), depending on the visibility macro flags set (see below)
70​#
71​# ``<prefix_name><uppercase_base_name>_ENABLE_DEPRECATED_SINCE(major, minor)``
72​# - evaluates to ``TRUE`` or ``FALSE`` depending on the visibility macro flags
73​# set (see below). To be used mainly with ``#if``/``#endif`` to mark sections
74​# of code which should be included depending on the visibility requested.
75​#
76​# ``<prefix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor)``
dfaureUnsubmitted
Done

typo: pther -> other

dfaure: typo: pther -> other
77​# - evaluates to ``TRUE`` or ``FALSE`` depending on the value of
78​# ``EXCLUDE_DEPRECATED_BEFORE`. To be used mainly with ``#if``/``#endif`` to
79​# mark sections of implementation code for deprecated API, as well as
80​# declaration code of deprecated API only to disable at build time (e.g.
81​# virtual methods, see notes below).
82​#
83​# ``<prefix_name><uppercase_base_name>_EXCLUDE_DEPRECATED_BEFORE`` - holds the
84​# version used to exclude deprecated API at build time.
85​#
86​# The macros used to control visibility when building against the library are:
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​#
88​# ``<prefix_name><uppercase_base_name>_NO_DEPRECATED_WARNINGS`` - flag to
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​# define to disable all deprecation warnings
90​#
91​# ``<prefix_name><uppercase_base_name>_DISABLE_DEPRECATED_BEFORE`` -
92​# definition to set to a value in single hex number version notation
93​# (``0x<major><minor><patch>``).
94​#
95​# ``<prefix_name><uppercase_base_name>_DEPRECATED_WARNINGS_SINCE``
96​#
97​# ``<prefix_name><uppercase_base_name>_NO_DEPRECATED`` - flag to define to disable all deprecated API
98​#
99​#
100​# Note: The tricks applied here for hiding deprecated API to the compiler
101​# when building against a library does not work for all deprecated API:
102​#
103​# * virtual methods need to stay visible to the compiler to build proper
104​# virtual method tables for subclasses
105​# * enumerators from enums cannot be simply removed, as this changes
106​# auto values of following enumerators, also can poke holes in enumerator
107​# series used as index into tables
108​#
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​# In such cases the API can be only "hidden" at build time of the library,
110​# itself, by generated hard coded macro settings, using
111​# ``<prefix_name><uppercase_base_name>_BUILD_DEPRECATED_SINCE(major, minor)``.
112​#
113​# Examples:
114​#
115​# Preparing a library "Foo" created by target "foo", which is part of a group
116​# of libraries "Bar", where some API of "Foo" got deprecated at versions
117​# 5.0 & 5.12:
118​#
119​# .. code-block:: cmake
120​#
121​# ecm_generate_export_header(foo
122​# GROUP_BASE_NAME BAR
123​# VERSION ${FOO_VERSION}
124​# DEPRECATION_VERSIONS 5.0 5.12
125​# )
126​#
127​# In the library "Foo" sources in the headers the API would be prepared like
128​# this, using the generated macros ``FOO_ENABLE_DEPRECATED_SINCE`` and
129​# ``FOO_DEPRECATED_VERSION``:
130​#
131​# .. code-block:: cpp
132​#
133​# #include <foo_export.h>
134​#
135​# #if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
136​# /**
137​# * @deprecated Since 5.0
138​# */
139​# FOO_DEPRECATED_VERSION(5, 0)
140​# void doFoo();
141​# #endif
142​#
143​# #if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
144​# /**
145​# * @deprecated Since 5.12
146​# */
147​# FOO_DEPRECATED_VERSION(5, 12)
148​# FOO_EXPORT void doBar();
149​# #endif
150​#
151​# Projects linking against the "Foo" library can control which part of its
152​# deprecated API should be hidden to the compiler by adding a definition
153​# using the ``FOO_DISABLE_DEPRECATED_BEFORE`` macro variable set to the
154​# desired value (in version hex number notation):
155​#
156​# .. code-block:: cmake
157​#
158​# add_definitions(-DFOO_DISABLE_DEPRECATED_BEFORE=0x050000)
159​#
160​# Or using the macro variable of the group:
161​#
162​# .. code-block:: cmake
163​#
164​# add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE=0x050000)
165​#
166​# If both are specified, ``FOO_DISABLE_DEPRECATED_BEFORE`` will take
167​# precedence.
168​#
169​# To build a variant of a library with some deprecated API completely left
170​# out from the build, not only optionally invisible to consumers, one uses the
171​# ``EXCLUDE_DEPRECATED_BEFORE`` parameter. This is best combined with a cached
172​# CMake variable.
173​#
174​# .. code-block:: cmake
175​#
176​# set(EXCLUDE_DEPRECATED_BEFORE 0 CACHE STRING "Control what part of deprecated API is excluded from build [default=0].")
177​#
178​# ecm_generate_export_header(foo
179​# VERSION ${FOO_VERSION}
180​# EXCLUDE_DEPRECATED_BEFORE ${EXCLUDE_DEPRECATED_BEFORE}
181​# DEPRECATION_VERSIONS 5.0 5.12
182​# )
183​#
184​# The macros used in the headers for library consumers are reused for
185​# disabling the API excluded in the build. For disabling their implementation
186​# as well as deprecated API which only can be disabled at build time, one
187​# uses the generated macro ``FOO_BUILD_DEPRECATED_SINCE``, like this:
188​#
189​# .. code-block:: cpp
190​#
191​# #include <foo_export.h>
192​#
193​# enum Bars {
194​# One,
195​# #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
196​# Two,
197​# #endif
198​# Three,
199​# };
200​#
201​# #if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
202​# /**
203​# * @deprecated Since 5.0
204​# */
205​# FOO_DEPRECATED_VERSION(5, 0)
206​# void doFoo();
207​# #endif
208​#
209​# #if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
210​# /**
211​# * @deprecated Since 5.12
212​# */
213​# FOO_DEPRECATED_VERSION(5, 12)
214​# FOO_EXPORT void doBar();
215​# #endif
216​#
217​# class Foo {
218​# #if FOO_BUILD_DEPRECATED_SINCE(5, 12)
219​# /**
220​# * @deprecated Since 5.12
221​# */
222​# FOO_DEPRECATED_VERSION(5, 12)
223​# virtual void doFoo();
224​# #endif
225​#
226​# .. code-block:: cpp
227​#
228​# #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
229​# void doFoo()
230​# {
231​# // [...]
232​# }
233​# #endif
234​#
235​# #if FOO_BUILD_DEPRECATED_SINCE(5, 12)
236​# void doBar()
237​# {
238​# // [...]
239​# }
240​# #endif
241​#
242​# #if FOO_BUILD_DEPRECATED_SINCE(5, 12)
243​# void Foo::doFoo()
244​# {
245​# // [...]
246​# }
247​# #endif
248​#
249​# If the project containing the "Foo" library includes code for tests and
250​# examples, also builds against other libraries from the same group "Bar", and
251​# one wants to disable some deprecated API of the other libraries using the
252​# group macro ``BAR_DISABLE_DEPRECATED_BEFORE``, one should explicitely set
253​# ``FOO_DISABLE_DEPRECATED_BEFORE`` at least for the tests again to the
254​# version before which all deprecated API has been excluded from the build,
255​# That way the test can still test all API that is part of the actual build.
256​# To get the hex number style value the helper macro
257​# ``ecm_export_header_format_version()`` will be used:
258​#
259​# .. code-block:: cmake
260​#
261​# set(EXCLUDE_DEPRECATED_BEFORE 0 CACHE STRING "Control what part of deprecated API is excluded from build [default=0].")
262​#
263​# ecm_generate_export_header(foo
264​# VERSION ${FOO_VERSION}
265​# GROUP_BASE_NAME BAR
266​# EXCLUDE_DEPRECATED_BEFORE ${EXCLUDE_DEPRECATED_BEFORE}
267​# DEPRECATION_VERSIONS 5.0 5.12
268​# )
269​#
270​# ecm_export_header_format_version(${EXCLUDE_DEPRECATED_BEFORE}
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​# CURRENT_VERSION ${KFOO_VERSION}
272​# HEXNUMBER_VAR FOO_EXCLUDE_DEPRECATED_BEFORE_HEXNUMBER
273​# )
274​#
275​# add_definitions(
276​# -DBAR_DISABLE_DEPRECATED_BEFORE=0x053E00
277​# -DFOO_DISABLE_DEPRECATED_BEFORE=${FOO_EXCLUDE_DEPRECATED_BEFORE_HEXNUMBER}
dfaureUnsubmitted
Done

comma followed by uppercase letter is unusual grammar

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