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

comma followed by uppercase letter is unusual grammar

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