Add ECMGenerateExportHeader, for improved handling of deprecated API

Summary:
Generates additional macros in the export header which can be used for
fine-grained disabling of warnings & visibility as well as excluding from
the build.

Reviewers: #frameworks, #build_system

Subscribers: chehrlic, dfaure, cgiboudeaux, kde-frameworks-devel, kde-buildsystem

Tags: #frameworks, #build_system

Differential Revision: https://phabricator.kde.org/D23789

14 files changed, 1192 insertions, 0 deletions

diff --git a/docs/module/ECMGenerateExportHeader.rst b/docs/module/ECMGenerateExportHeader.rst
new file mode 100644
index 00000000..d0ab9411
--- /dev/null
+++ b/docs/module/ECMGenerateExportHeader.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../modules/ECMGenerateExportHeader.cmake
diff --git a/modules/ECMGenerateExportHeader.cmake b/modules/ECMGenerateExportHeader.cmake
new file mode 100644
index 00000000..dfecb3a6
--- /dev/null
+++ b/modules/ECMGenerateExportHeader.cmake
@@ -0,0 +1,729 @@
+#.rst:
+# 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_DEFINITION_EXPORT_TO_BUILD_INTERFACE]
+#       [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 for warnings
+# about API deprecated before and at. 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)``
+# 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_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.
+# The default is that it is 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.
+#
+#
+# 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
+# <https://cmake.org/cmake/help/latest/module/GenerateExportHeader.html>`_:
+#
+# ``<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>_ENABLE_DEPRECATED_SINCE(major, minor)``
+#   evaluates to ``TRUE`` or ``FALSE`` 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`` or ``FALSE`` depending on the value of
+#   ``EXCLUDE_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 explicitely set.
+#
+# Note: 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:
+#
+# .. code-block:: cmake
+#
+#   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``:
+#
+# .. code-block:: cpp
+#
+#   #include <foo_export.h>
+#
+#   #if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
+#   /**
+#     * @deprecated Since 5.0
+#     */
+#   FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()")
+#   FOO_EXPORT void doFoo();
+#   #endif
+#
+#   #if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
+#   /**
+#     * @deprecated Since 5.12
+#     */
+#   FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()")
+#   FOO_EXPORT 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):
+#
+# .. code-block:: cmake
+#
+#   add_definitions(-DFOO_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000)
+#
+# Or using the macro variable of the group:
+#
+# .. code-block:: cmake
+#
+#   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.
+#
+# .. code-block:: cmake
+#
+#   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:
+#
+# .. code-block:: cpp
+#
+#   #include <foo_export.h>
+#
+#   enum Bars {
+#       One,
+#   #if FOO_BUILD_DEPRECATED_SINCE(5, 0)
+#       Two,
+#   #endif
+#       Three,
+#   };
+#
+#   #if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
+#   /**
+#     * @deprecated Since 5.0
+#     */
+#   FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()")
+#   FOO_EXPORT void doFoo();
+#   #endif
+#
+#   #if FOO_ENABLE_DEPRECATED_SINCE(5, 12)
+#   /**
+#     * @deprecated Since 5.12
+#     */
+#   FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()")
+#   FOO_EXPORT 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
+#   };
+#
+# .. code-block:: cpp
+#
+#   #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
+# explicitely 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:
+#
+# .. code-block:: cmake
+#
+#   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.
+
+#=============================================================================
+# Copyright 2019 Friedrich W. H. Kossebau <kossebau@kde.org>
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+#
+# 1. Redistributions of source code must retain the copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+# 3. The name of the author may not be used to endorse or promote products
+#    derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+# IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+# THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+include(GenerateExportHeader)
+include(CMakeParseArguments)
+
+# helper method
+function(_ecm_geh_generate_hex_number _var_name _version)
+    set(_hexnumber 0)
+
+    set(version_regex "^([0-9]+)\\.([0-9]+)\\.([0-9]+)$")
+    string(REGEX REPLACE ${version_regex} "\\1" _version_major "${_version}")
+    string(REGEX REPLACE ${version_regex} "\\2" _version_minor "${_version}")
+    string(REGEX REPLACE ${version_regex} "\\3" _version_patch "${_version}")
+    set(_outputformat)
+    if (NOT CMAKE_VERSION VERSION_LESS 3.13)
+        set(_outputformat OUTPUT_FORMAT HEXADECIMAL)
+    endif()
+    math(EXPR _hexnumber "${_version_major}*65536 + ${_version_minor}*256 + ${_version_patch}" ${_outputformat})
+    set(${_var_name} ${_hexnumber} PARENT_SCOPE)
+endfunction()
+
+function(ecm_export_header_format_version _version)
+    set(options
+    )
+    set(oneValueArgs
+        CURRENT_VERSION
+        STRING_VAR
+        HEXNUMBER_VAR
+    )
+    set(multiValueArgs
+    )
+    cmake_parse_arguments(ARGS "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
+
+    if (NOT ARGS_CURRENT_VERSION)
+        message(FATAL_ERROR "No CURRENT_VERSION passed when calling ecm_export_header_format_version().")
+    endif()
+    if (NOT ARGS_STRING_VAR AND NOT ARGS_HEXNUMBER_VAR)
+        message(FATAL_ERROR "No STRING_VAR or HEXNUMBER_VAR passed when calling ecm_export_header_format_version().")
+    endif()
+
+    if(_version STREQUAL "CURRENT")
+        set(_version ${ARGS_CURRENT_VERSION})
+    endif()
+
+    if (ARGS_STRING_VAR)
+        set(${ARGS_STRING_VAR} ${_version} PARENT_SCOPE)
+    endif()
+
+    if (ARGS_HEXNUMBER_VAR)
+        set(_hexnumber 0) # by default build all deprecated API
+        if(_version)
+            _ecm_geh_generate_hex_number(_hexnumber ${_version})
+        endif()
+        set(${ARGS_HEXNUMBER_VAR} ${_hexnumber} PARENT_SCOPE)
+    endif()
+endfunction()
+
+
+function(ecm_generate_export_header target)
+    set(options
+        NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE
+    )
+    set(oneValueArgs
+        BASE_NAME
+        GROUP_BASE_NAME
+        EXPORT_FILE_NAME
+        DEPRECATED_BASE_VERSION
+        VERSION
+        EXCLUDE_DEPRECATED_BEFORE_AND_AT
+        EXPORT_MACRO_NAME
+        DEPRECATED_MACRO_NAME
+        NO_EXPORT_MACRO_NAME
+        INCLUDE_GUARD_NAME
+        STATIC_DEFINE
+        PREFIX_NAME
+        CUSTOM_CONTENT_FROM_VARIABLE
+    )
+    set(multiValueArgs
+        DEPRECATION_VERSIONS
+    )
+    cmake_parse_arguments(ARGS "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
+
+    # args sanity check
+    if (NOT ARGS_VERSION)
+        message(FATAL_ERROR "No VERSION passed when calling ecm_generate_export_header().")
+    endif()
+    if (ARGS_INCLUDE_GUARD_NAME AND CMAKE_VERSION VERSION_LESS 3.11)
+        message(FATAL_ERROR "Argument INCLUDE_GUARD_NAME needs at least CMake 3.11 when calling ecm_generate_export_header().")
+    endif()
+    if (NOT ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT)
+        set(ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT 0)
+    elseif(ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT STREQUAL "CURRENT")
+        set(ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT ${ARGS_VERSION})
+    endif()
+    if (NOT ARGS_DEPRECATED_BASE_VERSION)
+        if (ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT)
+            set(ARGS_DEPRECATED_BASE_VERSION "${ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT}")
+        else()
+            string(REGEX REPLACE "^([0-9]+)\\.([0-9]+)\\.([0-9]+)$" "\\1"
+ _version_major "${ARGS_VERSION}")
+            set(ARGS_DEPRECATED_BASE_VERSION "${_version_major}.0.0")
+        endif()
+    else()
+        if (ARGS_DEPRECATED_BASE_VERSION VERSION_LESS ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT)
+            message(FATAL_ERROR "DEPRECATED_BASE_VERSION cannot be lower than EXCLUDE_DEPRECATED_BEFORE_AND_AT when calling ecm_generate_export_header().")
+        endif()
+    endif()
+    if(NOT ARGS_BASE_NAME)
+        set(ARGS_BASE_NAME "${target}")
+    endif()
+    string(TOUPPER "${ARGS_BASE_NAME}" _upper_base_name)
+    string(TOLOWER "${ARGS_BASE_NAME}" _lower_base_name)
+
+    if(NOT ARGS_EXPORT_FILE_NAME)
+        set(ARGS_EXPORT_FILE_NAME "${_lower_base_name}_export.h")
+    endif()
+    string(REPLACE "." ", " _commaed_version "${ARGS_VERSION}")
+    string(REPLACE "." ", " _commaed_deprecatedbaseversion "${ARGS_DEPRECATED_BASE_VERSION}")
+
+    set(_macro_base_name "${ARGS_PREFIX_NAME}${_upper_base_name}")
+    if (ARGS_EXPORT_MACRO_NAME)
+        set(_export_macro_name "${ARGS_EXPORT_MACRO_NAME}")
+    else()
+        set(_export_macro_name "${_macro_base_name}_EXPORT")
+    endif()
+    if (ARGS_NO_EXPORT_MACRO_NAME)
+        set(_no_export_macro_name "${ARGS_NO_EXPORT_MACRO_NAME}")
+    else()
+        set(_no_export_macro_name "${_macro_base_name}_NO_EXPORT")
+    endif()
+    if (ARGS_DEPRECATED_MACRO_NAME)
+        set(_deprecated_macro_name "${ARGS_DEPRECATED_MACRO_NAME}")
+    else()
+        set(_deprecated_macro_name "${_macro_base_name}_DEPRECATED")
+    endif()
+
+    if(NOT IS_ABSOLUTE ${ARGS_EXPORT_FILE_NAME})
+        set(ARGS_EXPORT_FILE_NAME "${CMAKE_CURRENT_BINARY_DIR}/${ARGS_EXPORT_FILE_NAME}")
+    endif()
+
+    set_property(TARGET ${target} APPEND PROPERTY AUTOGEN_TARGET_DEPENDS "${ARGS_EXPORT_FILE_NAME}")
+    # build with all the API not excluded, ensure all deprecated API is visible in the build itselt
+    _ecm_geh_generate_hex_number(_hexnumber ${ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT})
+    set(_disabling_definition "${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT=${_hexnumber}")
+    target_compile_definitions(${target} PRIVATE "${_disabling_definition}")
+    if (NOT ARGS_NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE)
+        target_compile_definitions(${target} INTERFACE "$<BUILD_INTERFACE:${_disabling_definition}>")
+    endif()
+
+    # for the set of compiler versions supported by ECM/KF we can assume those attributes supported
+    # KF6: with C++14 support expected, switch to always use [[deprecated(text)]]
+    if (CMAKE_C_COMPILER_ID STREQUAL "GNU" OR CMAKE_C_COMPILER_ID MATCHES "Clang")
+        set(_decl_deprecated_text_definition "__attribute__ ((__deprecated__(text)))")
+    elseif(MSVC)
+        set(_decl_deprecated_text_definition "__declspec(deprecated(text))")
+    else()
+        set(_decl_deprecated_text_definition "${_macro_base_name}_DECL_DEPRECATED")
+    endif()
+
+    # generate header file
+    set(_output "
+#define ${_macro_base_name}_DECL_DEPRECATED_TEXT(text) ${_decl_deprecated_text_definition}
+
+#define ECM_GENERATEEXPORTHEADER_VERSION_VALUE(major, minor, patch) ((major<<16)|(minor<<8)|(patch))
+"
+    )
+    if (ARGS_GROUP_BASE_NAME)
+        string(TOUPPER "${ARGS_GROUP_BASE_NAME}" _upper_group_name)
+        string(APPEND _output "
+// Take any defaults from group settings
+#if !defined(${_macro_base_name}_NO_DEPRECATED) && !defined(${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT)
+#  ifdef ${_upper_group_name}_NO_DEPRECATED
+#    define ${_macro_base_name}_NO_DEPRECATED
+#  elif defined(${_upper_group_name}_DISABLE_DEPRECATED_BEFORE_AND_AT)
+#    define ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT ${_upper_group_name}_DISABLE_DEPRECATED_BEFORE_AND_AT
+#  endif
+#endif
+#if !defined(${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT) && defined(${_upper_group_name}_DISABLE_DEPRECATED_BEFORE_AND_AT)
+#  define ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT ${_upper_group_name}_DISABLE_DEPRECATED_BEFORE_AND_AT
+#endif
+
+#if !defined(${_macro_base_name}_NO_DEPRECATED_WARNINGS) && !defined(${_macro_base_name}_DEPRECATED_WARNINGS_SINCE)
+#  ifdef ${_upper_group_name}_NO_DEPRECATED_WARNINGS
+#    define ${_macro_base_name}_NO_DEPRECATED_WARNINGS
+#  elif defined(${_upper_group_name}_DEPRECATED_WARNINGS_SINCE)
+#    define ${_macro_base_name}_DEPRECATED_WARNINGS_SINCE ${_upper_group_name}_DEPRECATED_WARNINGS_SINCE
+#  endif
+#endif
+#if !defined(${_macro_base_name}_DEPRECATED_WARNINGS_SINCE) && defined(${_upper_group_name}_DEPRECATED_WARNINGS_SINCE)
+#  define ${_macro_base_name}_DEPRECATED_WARNINGS_SINCE ${_upper_group_name}_DEPRECATED_WARNINGS_SINCE
+#endif
+"
+        )
+    endif()
+    string(APPEND _output "
+#if defined(${_macro_base_name}_NO_DEPRECATED)
+#  undef ${_deprecated_macro_name}
+#  define ${_deprecated_macro_name}_EXPORT ${_export_macro_name}
+#  define ${_deprecated_macro_name}_NO_EXPORT ${_no_export_macro_name}
+#elif defined(${_macro_base_name}_NO_DEPRECATED_WARNINGS)
+#  define ${_deprecated_macro_name}
+#  define ${_deprecated_macro_name}_EXPORT ${_export_macro_name}
+#  define ${_deprecated_macro_name}_NO_EXPORT ${_no_export_macro_name}
+#else
+#  define ${_deprecated_macro_name} ${_macro_base_name}_DECL_DEPRECATED
+#  define ${_deprecated_macro_name}_EXPORT ${_macro_base_name}_DECL_DEPRECATED_EXPORT
+#  define ${_deprecated_macro_name}_NO_EXPORT ${_macro_base_name}_DECL_DEPRECATED_NO_EXPORT
+#endif
+"
+    )
+    if (ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT)
+        message(STATUS "Excluding from build all API deprecated before and at: ${ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT}")
+        # TODO: the generated code ideally would emit a warning if some consumer used a value
+        # smaller then what the the build was done with
+        string(REPLACE "." ", " _commaed_excluded_before_version "${ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT}")
+        string(APPEND _output "
+// Build was done with the API removed deprecated before: ${ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT}
+#define ${_macro_base_name}_EXCLUDE_DEPRECATED_BEFORE_AND_AT ECM_GENERATEEXPORTHEADER_VERSION_VALUE(${_commaed_excluded_before_version})
+
+#ifdef ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT
+#  if ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT < ${_macro_base_name}_EXCLUDE_DEPRECATED_BEFORE_AND_AT
+#    undef ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT
+#    define ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT ${_macro_base_name}_EXCLUDE_DEPRECATED_BEFORE_AND_AT
+#  endif
+#endif
+
+#define ${_macro_base_name}_BUILD_DEPRECATED_SINCE(major, minor) (ECM_GENERATEEXPORTHEADER_VERSION_VALUE(major, minor, 0) > ${_macro_base_name}_EXCLUDE_DEPRECATED_BEFORE_AND_AT)
+"
+        )
+    else()
+        string(APPEND _output "
+// No deprecated API had been removed from build
+#define ${_macro_base_name}_EXCLUDE_DEPRECATED_BEFORE_AND_AT 0
+
+#define ${_macro_base_name}_BUILD_DEPRECATED_SINCE(major, minor) 1
+"
+        )
+    endif()
+    string(APPEND _output "
+#ifdef ${_macro_base_name}_NO_DEPRECATED
+#  define ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT ECM_GENERATEEXPORTHEADER_VERSION_VALUE(${_commaed_version})
+#endif
+#ifdef ${_macro_base_name}_NO_DEPRECATED_WARNINGS
+#  define ${_macro_base_name}_DEPRECATED_WARNINGS_SINCE 0
+#endif
+
+#ifndef ${_macro_base_name}_DEPRECATED_WARNINGS_SINCE
+#  ifdef ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT
+#    define ${_macro_base_name}_DEPRECATED_WARNINGS_SINCE ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT
+#  else
+#    define ${_macro_base_name}_DEPRECATED_WARNINGS_SINCE ECM_GENERATEEXPORTHEADER_VERSION_VALUE(${_commaed_version})
+#  endif
+#endif
+
+#ifndef ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT
+#  define ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT ECM_GENERATEEXPORTHEADER_VERSION_VALUE(${_commaed_deprecatedbaseversion})
+#endif
+
+#ifdef ${_deprecated_macro_name}
+#  define ${_macro_base_name}_ENABLE_DEPRECATED_SINCE(major, minor) (ECM_GENERATEEXPORTHEADER_VERSION_VALUE(major, minor, 0) > ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT)
+#else
+#  define ${_macro_base_name}_ENABLE_DEPRECATED_SINCE(major, minor) 0
+#endif
+"
+    )
+    if (DEFINED ARGS_DEPRECATION_VERSIONS)
+        set(_major_versions)
+        foreach(_version ${ARGS_DEPRECATION_VERSIONS})
+            string(REPLACE "." ", " _commaed_version "${_version}")
+            string(REPLACE "." "_" _underscored_version "${_version}")
+            string(REGEX REPLACE "^([0-9]+)\\.([0-9]+)$" "\\1"
+ _version_major "${_version}")
+            # IN_LIST only since cmake 3.3
+            set(_in_list FALSE)
+            foreach(_v ${_major_versions})
+                if (_v STREQUAL _version_major)
+                    set(_in_list TRUE)
+                    break()
+                endif()
+            endforeach()
+            if(NOT _in_list)
+                list(APPEND _major_versions ${_version_major})
+            endif()
+
+            string(APPEND _output "
+#if ${_macro_base_name}_DEPRECATED_WARNINGS_SINCE >= ECM_GENERATEEXPORTHEADER_VERSION_VALUE(${_commaed_version}, 0)
+#  define ${_macro_base_name}_DEPRECATED_VERSION_${_underscored_version}(text) ${_macro_base_name}_DECL_DEPRECATED_TEXT(text)
+#else
+#  define ${_macro_base_name}_DEPRECATED_VERSION_${_underscored_version}(text)
+#endif
+"
+            )
+        endforeach()
+        foreach(_major_version ${_major_versions})
+            string(APPEND _output
+"#define ${_macro_base_name}_DEPRECATED_VERSION_${_major_version}(minor, text)      ${_macro_base_name}_DEPRECATED_VERSION_${_major_version}_##minor(text)
+"
+            )
+        endforeach()
+
+        # TODO: any way to prefix "Since major.minor. " to text without getting text context wrapped with ""?
+        string(APPEND _output
+"#define ${_macro_base_name}_DEPRECATED_VERSION(major, minor, text) ${_macro_base_name}_DEPRECATED_VERSION_##major(minor, \"Since \"#major\".\"#minor\". \"#text)
+"
+        )
+    endif()
+    if (ARGS_CUSTOM_CONTENT_FROM_VARIABLE)
+        string(APPEND _output "${ARGS_CUSTOM_CONTENT_FROM_VARIABLE}\n")
+    endif()
+
+    set(_header_file "${ARGS_EXPORT_FILE_NAME}")
+    set(_header_work_file "${_header_file}.work")
+
+    # prepare optional arguments to pass through to generate_export_header
+    set(_include_guard_name_args)
+    if (ARGS_INCLUDE_GUARD_NAME)
+        set(_include_guard_name_args INCLUDE_GUARD_NAME "${ARGS_INCLUDE_GUARD_NAME}")
+    endif()
+    set(_export_macro_name_args)
+    if (ARGS_EXPORT_MACRO_NAME)
+        set(_export_macro_name_args EXPORT_MACRO_NAME "${ARGS_EXPORT_MACRO_NAME}")
+    endif()
+    set(_no_export_macro_name_args)
+    if (ARGS_NO_EXPORT_MACRO_NAME)
+        set(_no_export_macro_name_args ARGS_NO_EXPORT_MACRO_NAME "${ARGS_NO_EXPORT_MACRO_NAME}")
+    endif()
+    set(_prefix_name_args)
+    if (ARGS_PREFIX_NAME)
+        set(_prefix_name_args PREFIX_NAME "${ARGS_PREFIX_NAME}")
+    endif()
+    set(_static_define_args)
+    if (ARGS_STATIC_DEFINE)
+        set(_static_define_args STATIC_DEFINE "${ARGS_STATIC_DEFINE}")
+    endif()
+    # for older cmake verions we have to manually append our generated content
+    # for newer we use CUSTOM_CONTENT_FROM_VARIABLE
+    set(_custom_content_args)
+    if (NOT CMAKE_VERSION VERSION_LESS 3.7)
+        set(_custom_content_args CUSTOM_CONTENT_FROM_VARIABLE _output)
+    endif()
+    generate_export_header(${target}
+        BASE_NAME ${ARGS_BASE_NAME}
+        DEPRECATED_MACRO_NAME "${_macro_base_name}_DECL_DEPRECATED"
+        ${_prefix_name_args}
+        ${_export_macro_name_args}
+        ${_no_export_macro_name_args}
+        ${_static_define_args}
+        EXPORT_FILE_NAME "${_header_work_file}"
+        ${_include_guard_name_args}
+        ${_custom_content_args}
+    )
+
+    if (CMAKE_VERSION VERSION_LESS 3.7)
+        if (ARGS_INCLUDE_GUARD_NAME)
+            set(_include_guard "ECM_GENERATEEXPORTHEADER_${ARGS_INCLUDE_GUARD_NAME}")
+        else()
+            set(_include_guard "ECM_GENERATEEXPORTHEADER_${_upper_base_name}_EXPORT_H")
+        endif()
+
+        file(APPEND ${_header_work_file} "
+
+#ifndef ${_include_guard}
+#define ${_include_guard}
+
+${_output}
+
+#endif // ${_include_guard}
+"
+        )
+    endif()
+
+    # avoid rebuilding if there was no change
+    execute_process(
+        COMMAND ${CMAKE_COMMAND} -E copy_if_different "${_header_work_file}" "${_header_file}"
+    )
+    file(REMOVE "${_header_work_file}")
+endfunction()
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index 9df03eb9..72ae57dc 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -53,6 +53,7 @@ set_package_properties(
 )
 
 add_subdirectory(ECMAddTests)
+add_subdirectory(ECMGenerateExportHeaderTest)
 add_subdirectory(ECMGenerateHeadersTest)
 add_subdirectory(ECMSetupVersionTest)
 add_subdirectory(ECMGeneratePkgConfigFile)
diff --git a/tests/ECMGenerateExportHeaderTest/CMakeLists.txt b/tests/ECMGenerateExportHeaderTest/CMakeLists.txt
new file mode 100644
index 00000000..5b25a7df
--- /dev/null
+++ b/tests/ECMGenerateExportHeaderTest/CMakeLists.txt
@@ -0,0 +1,120 @@
+set(installation_path "${CMAKE_CURRENT_BINARY_DIR}/installation/")
+
+macro(add_generate_export_header_library_test _exclude_deprecated_before_and_at)
+    if("${ARGV1}" STREQUAL "WITH_GROUP")
+        set(_set_group_option "-DSET_GROUP=TRUE")
+        set(_library_buildname "library-${_exclude_deprecated_before_and_at}-group")
+    else()
+        set(_library_buildname "library-${_exclude_deprecated_before_and_at}")
+    endif()
+    add_test(NAME ecm_generate_export_header-build-${_library_buildname}
+        COMMAND ${CMAKE_CTEST_COMMAND}
+            --build-and-test
+            "${CMAKE_CURRENT_SOURCE_DIR}/library"
+            "${CMAKE_CURRENT_BINARY_DIR}/${_library_buildname}"
+            --build-two-config
+            --build-generator "${CMAKE_GENERATOR}"
+            --build-makeprogram ${CMAKE_MAKE_PROGRAM}
+            --build-project library
+            --build-target install
+            --build-options
+                "-DEXCLUDE_DEPRECATED_BEFORE_AND_AT=${_exclude_deprecated_before_and_at}"
+                "-DCMAKE_INSTALL_PREFIX:PATH=${installation_path}/${_library_buildname}"
+                ${_set_group_option}
+            --test-command dummy
+    )
+endmacro()
+
+macro(add_generate_export_header_consumer_test _test_variant _exclude_deprecated_before_and_at _group_test_mode _consumer_build)
+    set(_extra_build_options ${ARGN})
+    if(_group_test_mode STREQUAL "GROUPLESS")
+        set(_library "library-${_exclude_deprecated_before_and_at}")
+    else()
+        set(_library "library-${_exclude_deprecated_before_and_at}-group")
+    endif()
+    add_test(NAME ecm_generate_export_header-${_consumer_build}
+        COMMAND ${CMAKE_CTEST_COMMAND}
+            --build-and-test
+            "${CMAKE_CURRENT_SOURCE_DIR}/consumer"
+            "${CMAKE_CURRENT_BINARY_DIR}/${_consumer_build}"
+            --build-two-config
+            --build-generator "${CMAKE_GENERATOR}"
+            --build-makeprogram ${CMAKE_MAKE_PROGRAM}
+            --build-project consumer
+            --build-options
+                "-DTEST_VARIANT:STRING=${_test_variant}"
+                "-DDEPRECATED_EXCLUDED_BEFORE_AND_AT:STRING=${_exclude_deprecated_before_and_at}"
+                "-DLIBRARY:STRING=${_library}"
+                "-DGROUP_MODE:STRING=${_group_test_mode}"
+                ${_extra_build_options}
+            --test-command dummy
+    )
+endmacro()
+
+macro(add_generate_export_header_consumer_disable_deprecated_before_and_at_test
+    _disable_deprecated_before_and_at
+    _exclude_deprecated_before_and_at
+    _group_test_mode
+    )
+    set(_consumer_build "consumer-${_disable_deprecated_before_and_at}-${_exclude_deprecated_before_and_at}-${_group_test_mode}")
+    set(_extra_build_options
+        "-DLIBRARY_DISABLE_DEPRECATED_BEFORE_AND_AT:STRING=${_disable_deprecated_before_and_at}"
+    )
+    add_generate_export_header_consumer_test(DISABLE_DEPRECATED_BEFORE_AND_AT
+        ${_exclude_deprecated_before_and_at}
+        ${_group_test_mode}
+        ${_consumer_build}
+        ${_extra_build_options}
+    )
+endmacro()
+
+macro(add_generate_export_header_consumer_no_deprecated_test _exclude_deprecated_before_and_at _group_test_mode)
+    set(_consumer_build "consumer-NO-DEPRECATED-${_exclude_deprecated_before_and_at}-${_group_test_mode}")
+    add_generate_export_header_consumer_test(NO_DEPRECATED
+        ${_exclude_deprecated_before_and_at}
+        ${_group_test_mode}
+        ${_consumer_build}
+    )
+endmacro()
+
+# prepare list of versions
+set(library_versions 0 2.0.0 CURRENT)
+list(LENGTH library_versions library_versions_count)
+math(EXPR _last_index ${library_versions_count}-1)
+
+# test generating the library with different EXCLUDE_DEPRECATED_BEFORE_AND_AT values
+# als install the generated libraries together incl. exported cmake targets, for use in tests below
+# TODO: wariant with DEPRECATED_BASE_VERSION
+foreach(_group_arg "" "WITH_GROUP")
+    foreach(_index RANGE ${_last_index})
+        list(GET library_versions ${_index} _exclude_deprecated_before_and_at)
+        add_generate_export_header_library_test(${_exclude_deprecated_before_and_at} ${_group_arg})
+    endforeach()
+endforeach()
+
+
+set(group_test_modes "GROUPLESS" "GROUP_USE_DIRECT" "GROUP_USE_GROUP")
+
+# test using the library, built with different EXCLUDE_DEPRECATED_BEFORE_AND_AT values,
+# while using different DISABLE_DEPRECATED_BEFORE_AND_AT values
+# TODO: test DEPRECATED_WARNINGS_SINCE
+foreach(_group_test_mode ${group_test_modes})
+    foreach(_exclude_index RANGE ${_last_index})
+        list(GET library_versions ${_exclude_index} _exclude_deprecated_before_and_at)
+        # using disabled API limit below the excluded API limit is not supported and
+        # catched by the code generated from the ecm_generate_export_header,
+        # so testing those combination will not work, so start from the excluded API limit
+        foreach(_disable_index RANGE ${_exclude_index} ${_last_index})
+            list(GET library_versions ${_disable_index} _disable_deprecated_before_and_at)
+            add_generate_export_header_consumer_disable_deprecated_before_and_at_test(${_disable_deprecated_before_and_at} ${_exclude_deprecated_before_and_at} ${_group_test_mode})
+        endforeach()
+    endforeach()
+endforeach()
+
+# test with NO_DEPRECATED
+foreach(_group_test_mode ${group_test_modes})
+    foreach(_exclude_index RANGE ${_last_index})
+        list(GET library_versions ${_exclude_index} _exclude_deprecated_before_and_at)
+        add_generate_export_header_consumer_no_deprecated_test(${_exclude_deprecated_before_and_at} ${_group_test_mode})
+    endforeach()
+endforeach()
diff --git a/tests/ECMGenerateExportHeaderTest/consumer/CMakeLists.txt b/tests/ECMGenerateExportHeaderTest/consumer/CMakeLists.txt
new file mode 100644
index 00000000..ba5940cd
--- /dev/null
+++ b/tests/ECMGenerateExportHeaderTest/consumer/CMakeLists.txt
@@ -0,0 +1,50 @@
+cmake_minimum_required(VERSION 3.0.0)
+
+project(consumer)
+
+include(CheckCXXSourceCompiles)
+include(CMakeParseArguments)
+
+include(../../test_helpers.cmake)
+
+include("${CMAKE_CURRENT_BINARY_DIR}/../installation/${LIBRARY}/lib/library/LibraryTargets.cmake")
+
+# map any "CURRENT" value to library version string
+# keep version in sync with the one used in library/CMakeLists.txt
+set(library_version 2.40.0)
+if(LIBRARY_DISABLE_DEPRECATED_BEFORE_AND_AT STREQUAL "CURRENT")
+    set(LIBRARY_DISABLE_DEPRECATED_BEFORE_AND_AT ${library_version})
+endif()
+if(DEPRECATED_EXCLUDED_BEFORE_AND_AT STREQUAL "CURRENT")
+    set(DEPRECATED_EXCLUDED_BEFORE_AND_AT ${library_version})
+endif()
+
+# load the test variant specific testAPI method
+include(testAPI_${TEST_VARIANT}.cmake)
+
+# for each API element test their visibility to the compiler and if a warning is emitted
+set(_code "Enum enumerator = Enumerator_deprecatedAt2_0;")
+testAPI(_code DEPRECATED_AT 2.0 BUILD_TIME_ONLY_DISABLABLE NO_WARNING)
+
+set(_code "Enum enumerator = Enumerator_not_deprecated;")
+testAPI(_code)
+
+set(_code "function_deprecatedAt2_0();")
+testAPI(_code DEPRECATED_AT 2.0)
+
+set(_code "function_deprecatedAt2_12();")
+testAPI(_code DEPRECATED_AT 2.12)
+
+set(_code "function_not_deprecated();")
+testAPI(_code)
+
+set(_code "Class().method_deprecatedAt2_0();")
+testAPI(_code DEPRECATED_AT 2.0 BUILD_TIME_ONLY_DISABLABLE)
+
+set(_code "Class().method_deprecatedAt2_12();")
+testAPI(_code DEPRECATED_AT 2.12 BUILD_TIME_ONLY_DISABLABLE)
+
+set(_code "Class().method_not_deprecated();")
+testAPI(_code)
+
+add_executable(dummy main.cpp)
diff --git a/tests/ECMGenerateExportHeaderTest/consumer/main.cpp b/tests/ECMGenerateExportHeaderTest/consumer/main.cpp
new file mode 100644
index 00000000..0f45ea60
--- /dev/null
+++ b/tests/ECMGenerateExportHeaderTest/consumer/main.cpp
@@ -0,0 +1,4 @@
+int main(int, char**)
+{
+    return 0;
+}
diff --git a/tests/ECMGenerateExportHeaderTest/consumer/testAPI_DISABLE_DEPRECATED_BEFORE_AND_AT.cmake b/tests/ECMGenerateExportHeaderTest/consumer/testAPI_DISABLE_DEPRECATED_BEFORE_AND_AT.cmake
new file mode 100644
index 00000000..fac51d53
--- /dev/null
+++ b/tests/ECMGenerateExportHeaderTest/consumer/testAPI_DISABLE_DEPRECATED_BEFORE_AND_AT.cmake
@@ -0,0 +1,71 @@
+function(generate_hex_number _var_name _version)
+    set(_hexnumber 0)
+
+    set(version_regex "^([0-9]+)\\.([0-9]+)\\.([0-9]+)$")
+    string(REGEX REPLACE ${version_regex} "\\1" _version_major "${_version}")
+    string(REGEX REPLACE ${version_regex} "\\2" _version_minor "${_version}")
+    string(REGEX REPLACE ${version_regex} "\\3" _version_patch "${_version}")
+    set(_outputformat)
+    if (NOT CMAKE_VERSION VERSION_LESS 3.13)
+        set(_outputformat OUTPUT_FORMAT HEXADECIMAL)
+    endif()
+    math(EXPR _hexnumber "${_version_major}*65536 + ${_version_minor}*256 + ${_version_patch}" ${_outputformat})
+    set(${_var_name} ${_hexnumber} PARENT_SCOPE)
+endfunction()
+
+
+generate_hex_number(disable_deprecated_before_and_at_hexnumber ${LIBRARY_DISABLE_DEPRECATED_BEFORE_AND_AT})
+
+if(GROUP_MODE STREQUAL "GROUP_USE_GROUP")
+    set(_deprecation_macros_base_name "LIBGROUP")
+else()
+    set(_deprecation_macros_base_name "LIBRARY")
+endif()
+
+function(testAPI code_var_name)
+    set(options BUILD_TIME_ONLY_DISABLABLE NO_WARNING)
+    set(oneValueArgs DEPRECATED_AT)
+    set(multiValueArgs)
+    cmake_parse_arguments(ARGS "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
+
+    if((NOT ARGS_DEPRECATED_AT) OR
+       (ARGS_BUILD_TIME_ONLY_DISABLABLE AND ARGS_DEPRECATED_AT VERSION_GREATER DEPRECATED_EXCLUDED_BEFORE_AND_AT) OR
+       (ARGS_DEPRECATED_AT VERSION_GREATER LIBRARY_DISABLE_DEPRECATED_BEFORE_AND_AT))
+       set(_build_result_expected TRUE)
+    else()
+       set(_build_result_expected FALSE)
+    endif()
+
+    set(CMAKE_REQUIRED_LIBRARIES library)
+    set(CMAKE_REQUIRED_DEFINITIONS "-D${_deprecation_macros_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT=${disable_deprecated_before_and_at_hexnumber}")
+
+    set(_code "
+#include <library.hpp>
+int main(int, char**)
+{
+    ${${code_var_name}}
+}
+")
+
+    unset(_result CACHE) # clear out as check_cxx_source_compiles caches the result
+    check_cxx_source_compiles("${_code}" _result)
+
+    assert_var_bool_value(_result ${_build_result_expected})
+
+    # check warning 
+    if(_build_result_expected)
+        if((ARGS_BUILD_TIME_ONLY_DISABLABLE AND NOT ARGS_NO_WARNING) OR
+           (NOT ARGS_BUILD_TIME_ONLY_DISABLABLE AND ARGS_DEPRECATED_AT AND
+            ARGS_DEPRECATED_AT VERSION_GREATER LIBRARY_DISABLE_DEPRECATED_BEFORE_AND_AT))
+            set(_dep_warning_result_expected FALSE)
+        else()
+            set(_dep_warning_result_expected TRUE)
+        endif()
+
+        set(CMAKE_REQUIRED_FLAGS "-Werror=deprecated-declarations")
+        set(CMAKE_REQUIRED_DEFINITIONS) # unset LIBRARY_DISABLE_DEPRECATED_BEFORE_AND_AT, as LIBRARY_DEPRECATED_WARNINGS_SINCE defaults to it
+        unset(_dep_warning_result CACHE) # clear out as check_cxx_source_compiles caches the result
+        check_cxx_source_compiles("${_code}" _dep_warning_result)
+        assert_var_bool_value(_dep_warning_result ${_dep_warning_result_expected})
+    endif()
+endfunction()
diff --git a/tests/ECMGenerateExportHeaderTest/consumer/testAPI_NO_DEPRECATED.cmake b/tests/ECMGenerateExportHeaderTest/consumer/testAPI_NO_DEPRECATED.cmake
new file mode 100644
index 00000000..190ccecc
--- /dev/null
+++ b/tests/ECMGenerateExportHeaderTest/consumer/testAPI_NO_DEPRECATED.cmake
@@ -0,0 +1,50 @@
+if(GROUP_MODE STREQUAL "GROUP_USE_GROUP")
+    set(_deprecation_macros_base_name "LIBGROUP")
+else()
+    set(_deprecation_macros_base_name "LIBRARY")
+endif()
+
+function(testAPI code_var_name)
+    set(options BUILD_TIME_ONLY_DISABLABLE NO_WARNING)
+    set(oneValueArgs DEPRECATED_AT)
+    set(multiValueArgs)
+    cmake_parse_arguments(ARGS "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
+
+    if((NOT ARGS_DEPRECATED_AT) OR
+       (ARGS_BUILD_TIME_ONLY_DISABLABLE AND ARGS_DEPRECATED_AT VERSION_GREATER DEPRECATED_EXCLUDED_BEFORE_AND_AT))
+       set(_build_result_expected TRUE)
+    else()
+       set(_build_result_expected FALSE)
+    endif()
+
+    set(CMAKE_REQUIRED_LIBRARIES library)
+    set(CMAKE_REQUIRED_DEFINITIONS "-D${_deprecation_macros_base_name}_NO_DEPRECATED")
+
+    set(_code "
+#include <library.hpp>
+int main(int, char**)
+{
+    ${${code_var_name}}
+}
+")
+
+    unset(_result CACHE) # clear out as check_cxx_source_compiles caches the result
+    check_cxx_source_compiles("${_code}" _result)
+
+    assert_var_bool_value(_result ${_build_result_expected})
+
+    # check warning
+    if(_build_result_expected)
+        if(ARGS_BUILD_TIME_ONLY_DISABLABLE AND NOT ARGS_NO_WARNING)
+            set(_dep_warning_result_expected FALSE)
+        else()
+            set(_dep_warning_result_expected TRUE)
+        endif()
+
+        set(CMAKE_REQUIRED_FLAGS "-Werror=deprecated-declarations")
+        set(CMAKE_REQUIRED_DEFINITIONS) # unset LIBRARY_DISABLE_DEPRECATED_BEFORE_AND_AT, as LIBRARY_DEPRECATED_WARNINGS_SINCE defaults to it
+        unset(_dep_warning_result CACHE) # clear out as check_cxx_source_compiles caches the result
+        check_cxx_source_compiles("${_code}" _dep_warning_result)
+        assert_var_bool_value(_dep_warning_result ${_dep_warning_result_expected})
+    endif()
+endfunction()
diff --git a/tests/ECMGenerateExportHeaderTest/format_version/CMakeLists.txt b/tests/ECMGenerateExportHeaderTest/format_version/CMakeLists.txt
new file mode 100644
index 00000000..b46719c2
--- /dev/null
+++ b/tests/ECMGenerateExportHeaderTest/format_version/CMakeLists.txt
@@ -0,0 +1,50 @@
+cmake_minimum_required(VERSION 3.0.0)
+
+project(format_version)
+
+set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/../../../modules)
+include(ECMGenerateExportHeader)
+
+include(../../test_helpers.cmake)
+
+set(_current_version "4.5.6")
+
+# check 0
+ecm_export_header_format_version(0
+    CURRENT_VERSION ${_current_version}
+    STRING_VAR _versionstring
+    HEXNUMBER_VAR _hexnumber
+)
+
+assert_var_str_value(_versionstring "0")
+assert_var_str_value(_hexnumber "0")
+
+# check other
+ecm_export_header_format_version(1.2.3
+    CURRENT_VERSION ${_current_version}
+    STRING_VAR _versionstring
+    HEXNUMBER_VAR _hexnumber
+)
+
+assert_var_str_value(_versionstring "1.2.3")
+if (NOT CMAKE_VERSION VERSION_LESS 3.13)
+    assert_var_str_value(_hexnumber "0x10203")
+else()
+    assert_var_str_value(_hexnumber "66051")
+endif()
+
+# check CURRENT
+ecm_export_header_format_version(CURRENT
+    CURRENT_VERSION ${_current_version}
+    STRING_VAR _versionstring
+    HEXNUMBER_VAR _hexnumber
+)
+
+assert_var_str_value(_versionstring "4.5.6")
+if (NOT CMAKE_VERSION VERSION_LESS 3.13)
+    assert_var_str_value(_hexnumber "0x40506")
+else()
+    assert_var_str_value(_hexnumber "263430")
+endif()
+
+add_executable(dummy main.cpp)
diff --git a/tests/ECMGenerateExportHeaderTest/format_version/main.cpp b/tests/ECMGenerateExportHeaderTest/format_version/main.cpp
new file mode 100644
index 00000000..0f45ea60
--- /dev/null
+++ b/tests/ECMGenerateExportHeaderTest/format_version/main.cpp
@@ -0,0 +1,4 @@
+int main(int, char**)
+{
+    return 0;
+}
diff --git a/tests/ECMGenerateExportHeaderTest/library/CMakeLists.txt b/tests/ECMGenerateExportHeaderTest/library/CMakeLists.txt
new file mode 100644
index 00000000..eb925c9b
--- /dev/null
+++ b/tests/ECMGenerateExportHeaderTest/library/CMakeLists.txt
@@ -0,0 +1,40 @@
+cmake_minimum_required(VERSION 3.0.0)
+
+# keep version in sync with the one used in consumer/CMakeLists.txt for the library
+# ideally would be send over by an exported target property,
+# but exporting custom properties via EXPORT_PROPERTIES only was added in CMake 3.12
+project(library VERSION 2.40.0)
+
+set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/../../../modules)
+include(ECMGenerateExportHeader)
+
+set(_public_includedir "include/library")
+
+add_library(library library.cpp)
+target_include_directories(library
+    PUBLIC
+        "$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>"
+        "$<INSTALL_INTERFACE:${_public_includedir}>"
+)
+
+if(SET_GROUP)
+    set(_group_args GROUP_BASE_NAME LIBGROUP)
+endif()
+
+ecm_generate_export_header(library
+    ${_group_args}
+    VERSION ${library_VERSION}
+    DEPRECATION_VERSIONS 2.0 2.12
+    EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT}
+)
+
+install(TARGETS library DESTINATION lib EXPORT library_targets)
+
+install(EXPORT library_targets FILE LibraryTargets.cmake DESTINATION lib/library)
+install(FILES
+    library.hpp
+    "${CMAKE_CURRENT_BINARY_DIR}/library_export.h"
+    DESTINATION ${_public_includedir}
+)
+
+add_executable(dummy main.cpp)
diff --git a/tests/ECMGenerateExportHeaderTest/library/library.cpp b/tests/ECMGenerateExportHeaderTest/library/library.cpp
new file mode 100644
index 00000000..9d08838c
--- /dev/null
+++ b/tests/ECMGenerateExportHeaderTest/library/library.cpp
@@ -0,0 +1,33 @@
+#include "library.hpp"
+
+#if LIBRARY_BUILD_DEPRECATED_SINCE(2, 0)
+void function_deprecatedAt2_0()
+{
+}
+#endif
+
+#if LIBRARY_BUILD_DEPRECATED_SINCE(2, 12)
+void function_deprecatedAt2_12()
+{
+}
+#endif
+
+void function_not_deprecated()
+{
+}
+
+#if LIBRARY_BUILD_DEPRECATED_SINCE(2, 0)
+void Class::method_deprecatedAt2_0()
+{
+}
+#endif
+
+#if LIBRARY_BUILD_DEPRECATED_SINCE(2, 12)
+void Class::method_deprecatedAt2_12()
+{
+}
+#endif
+
+void Class::method_not_deprecated()
+{
+}
diff --git a/tests/ECMGenerateExportHeaderTest/library/library.hpp b/tests/ECMGenerateExportHeaderTest/library/library.hpp
new file mode 100644
index 00000000..2124bf8a
--- /dev/null
+++ b/tests/ECMGenerateExportHeaderTest/library/library.hpp
@@ -0,0 +1,35 @@
+#include <library_export.h>
+
+enum Enum {
+#if LIBRARY_BUILD_DEPRECATED_SINCE(2, 0)
+    Enumerator_deprecatedAt2_0,
+#endif
+    Enumerator_not_deprecated,
+};
+
+#if LIBRARY_ENABLE_DEPRECATED_SINCE(2, 0)
+LIBRARY_DEPRECATED_VERSION(2, 0, "Deprecated at 2.0")
+LIBRARY_EXPORT void function_deprecatedAt2_0();
+#endif
+
+#if LIBRARY_ENABLE_DEPRECATED_SINCE(2, 12)
+LIBRARY_DEPRECATED_VERSION(2, 12, "Deprecated at 2.12")
+LIBRARY_EXPORT void function_deprecatedAt2_12();
+#endif
+
+LIBRARY_EXPORT void function_not_deprecated();
+
+class LIBRARY_EXPORT Class {
+public:
+#if LIBRARY_BUILD_DEPRECATED_SINCE(2, 0)
+    LIBRARY_DEPRECATED_VERSION(2, 0, "Deprecated at 2.0")
+    virtual void method_deprecatedAt2_0();
+#endif
+
+#if LIBRARY_BUILD_DEPRECATED_SINCE(2, 12)
+    LIBRARY_DEPRECATED_VERSION(2, 12, "Deprecated at 2.12")
+    virtual void method_deprecatedAt2_12();
+#endif
+
+    virtual void method_not_deprecated();
+};
diff --git a/tests/ECMGenerateExportHeaderTest/library/main.cpp b/tests/ECMGenerateExportHeaderTest/library/main.cpp
new file mode 100644
index 00000000..0f45ea60
--- /dev/null
+++ b/tests/ECMGenerateExportHeaderTest/library/main.cpp
@@ -0,0 +1,4 @@
+int main(int, char**)
+{
+    return 0;
+}