summaryrefslogtreecommitdiff
path: root/Modules/GenerateExportHeader.cmake
diff options
context:
space:
mode:
Diffstat (limited to 'Modules/GenerateExportHeader.cmake')
-rw-r--r--Modules/GenerateExportHeader.cmake323
1 files changed, 191 insertions, 132 deletions
diff --git a/Modules/GenerateExportHeader.cmake b/Modules/GenerateExportHeader.cmake
index 4ef14ac28..4573c2e77 100644
--- a/Modules/GenerateExportHeader.cmake
+++ b/Modules/GenerateExportHeader.cmake
@@ -1,148 +1,189 @@
-# - Function for generation of export macros for libraries
-# This module provides the function GENERATE_EXPORT_HEADER() and the
-# accompanying ADD_COMPILER_EXPORT_FLAGS() function.
-#
-# The GENERATE_EXPORT_HEADER function can be used to generate a file suitable
-# for preprocessor inclusion which contains EXPORT macros to be used in
-# library classes.
-#
-# GENERATE_EXPORT_HEADER( LIBRARY_TARGET
-# [BASE_NAME <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>]
-# [STATIC_DEFINE <static_define>]
-# [NO_DEPRECATED_MACRO_NAME <no_deprecated_macro_name>]
-# [DEFINE_NO_DEPRECATED]
-# [PREFIX_NAME <prefix_name>]
-# )
-#
-# ADD_COMPILER_EXPORT_FLAGS( [<output_variable>] )
-#
-# By default GENERATE_EXPORT_HEADER() generates macro names in a file name
-# determined by the name of the library. The ADD_COMPILER_EXPORT_FLAGS function
-# adds -fvisibility=hidden to CMAKE_CXX_FLAGS if supported, and is a no-op on
-# Windows which does not need extra compiler flags for exporting support. You
-# may optionally pass a single argument to ADD_COMPILER_EXPORT_FLAGS that will
-# be populated with the required CXX_FLAGS required to enable visibility support
-# for the compiler/architecture in use.
-#
-# This means that in the simplest case, users of these functions will be
-# equivalent to:
-#
-# add_compiler_export_flags()
-# add_library(somelib someclass.cpp)
-# generate_export_header(somelib)
-# install(TARGETS somelib DESTINATION ${LIBRARY_INSTALL_DIR})
-# install(FILES
-# someclass.h
-# ${PROJECT_BINARY_DIR}/somelib_export.h DESTINATION ${INCLUDE_INSTALL_DIR}
-# )
+# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
+# file Copyright.txt or https://cmake.org/licensing for details.
+
+#.rst:
+# GenerateExportHeader
+# --------------------
+#
+# Function for generation of export macros for libraries
+#
+# This module provides the function GENERATE_EXPORT_HEADER().
+#
+# The ``GENERATE_EXPORT_HEADER`` function can be used to generate a file
+# suitable for preprocessor inclusion which contains EXPORT macros to be
+# used in library classes::
+#
+# GENERATE_EXPORT_HEADER( LIBRARY_TARGET
+# [BASE_NAME <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>]
+# [STATIC_DEFINE <static_define>]
+# [NO_DEPRECATED_MACRO_NAME <no_deprecated_macro_name>]
+# [DEFINE_NO_DEPRECATED]
+# [PREFIX_NAME <prefix_name>]
+# [CUSTOM_CONTENT_FROM_VARIABLE <variable>]
+# )
+#
+#
+# The target properties :prop_tgt:`CXX_VISIBILITY_PRESET <<LANG>_VISIBILITY_PRESET>`
+# and :prop_tgt:`VISIBILITY_INLINES_HIDDEN` can be used to add the appropriate
+# compile flags for targets. See the documentation of those target properties,
+# and the convenience variables
+# :variable:`CMAKE_CXX_VISIBILITY_PRESET <CMAKE_<LANG>_VISIBILITY_PRESET>` and
+# :variable:`CMAKE_VISIBILITY_INLINES_HIDDEN`.
+#
+# By default ``GENERATE_EXPORT_HEADER()`` generates macro names in a file
+# name determined by the name of the library. This means that in the
+# simplest case, users of ``GenerateExportHeader`` will be equivalent to:
+#
+# .. code-block:: cmake
+#
+# set(CMAKE_CXX_VISIBILITY_PRESET hidden)
+# set(CMAKE_VISIBILITY_INLINES_HIDDEN 1)
+# add_library(somelib someclass.cpp)
+# generate_export_header(somelib)
+# install(TARGETS somelib DESTINATION ${LIBRARY_INSTALL_DIR})
+# install(FILES
+# someclass.h
+# ${PROJECT_BINARY_DIR}/somelib_export.h DESTINATION ${INCLUDE_INSTALL_DIR}
+# )
+#
#
# And in the ABI header files:
#
-# #include "somelib_export.h"
-# class SOMELIB_EXPORT SomeClass {
-# ...
-# };
+# .. code-block:: c++
+#
+# #include "somelib_export.h"
+# class SOMELIB_EXPORT SomeClass {
+# ...
+# };
#
-# The CMake fragment will generate a file in the ${CMAKE_CURRENT_BINARY_DIR}
-# called somelib_export.h containing the macros SOMELIB_EXPORT, SOMELIB_NO_EXPORT,
-# SOMELIB_DEPRECATED, SOMELIB_DEPRECATED_EXPORT and SOMELIB_DEPRECATED_NO_EXPORT.
+#
+# The CMake fragment will generate a file in the
+# ``${CMAKE_CURRENT_BINARY_DIR}`` called ``somelib_export.h`` containing the
+# macros ``SOMELIB_EXPORT``, ``SOMELIB_NO_EXPORT``, ``SOMELIB_DEPRECATED``,
+# ``SOMELIB_DEPRECATED_EXPORT`` and ``SOMELIB_DEPRECATED_NO_EXPORT``.
+# They will be followed by content taken from the variable specified by
+# the ``CUSTOM_CONTENT_FROM_VARIABLE`` option, if any.
# The resulting file should be installed with other headers in the library.
#
-# The BASE_NAME argument can be used to override the file name and the names
-# used for the macros
+# The ``BASE_NAME`` argument can be used to override the file name and the
+# names used for the macros:
#
-# add_library(somelib someclass.cpp)
-# generate_export_header(somelib
-# BASE_NAME other_name
-# )
+# .. code-block:: cmake
#
-# Generates a file called other_name_export.h containing the macros
-# OTHER_NAME_EXPORT, OTHER_NAME_NO_EXPORT and OTHER_NAME_DEPRECATED etc.
+# add_library(somelib someclass.cpp)
+# generate_export_header(somelib
+# BASE_NAME other_name
+# )
+#
+#
+# Generates a file called ``other_name_export.h`` containing the macros
+# ``OTHER_NAME_EXPORT``, ``OTHER_NAME_NO_EXPORT`` and ``OTHER_NAME_DEPRECATED``
+# etc.
+#
+# The ``BASE_NAME`` may be overridden by specifying other options in the
+# function. For example:
+#
+# .. code-block:: cmake
+#
+# add_library(somelib someclass.cpp)
+# generate_export_header(somelib
+# EXPORT_MACRO_NAME OTHER_NAME_EXPORT
+# )
+#
+#
+# creates the macro ``OTHER_NAME_EXPORT`` instead of ``SOMELIB_EXPORT``, but
+# other macros and the generated file name is as default:
+#
+# .. code-block:: cmake
+#
+# add_library(somelib someclass.cpp)
+# generate_export_header(somelib
+# DEPRECATED_MACRO_NAME KDE_DEPRECATED
+# )
#
-# The BASE_NAME may be overridden by specifiying other options in the function.
-# For example:
#
-# add_library(somelib someclass.cpp)
-# generate_export_header(somelib
-# EXPORT_MACRO_NAME OTHER_NAME_EXPORT
-# )
+# creates the macro ``KDE_DEPRECATED`` instead of ``SOMELIB_DEPRECATED``.
#
-# creates the macro OTHER_NAME_EXPORT instead of SOMELIB_EXPORT, but other macros
-# and the generated file name is as default.
+# If ``LIBRARY_TARGET`` is a static library, macros are defined without
+# values.
#
-# add_library(somelib someclass.cpp)
-# generate_export_header(somelib
-# DEPRECATED_MACRO_NAME KDE_DEPRECATED
-# )
+# If the same sources are used to create both a shared and a static
+# library, the uppercased symbol ``${BASE_NAME}_STATIC_DEFINE`` should be
+# used when building the static library:
#
-# creates the macro KDE_DEPRECATED instead of SOMELIB_DEPRECATED.
+# .. code-block:: cmake
#
-# If LIBRARY_TARGET is a static library, macros are defined without values.
+# add_library(shared_variant SHARED ${lib_SRCS})
+# add_library(static_variant ${lib_SRCS})
+# generate_export_header(shared_variant BASE_NAME libshared_and_static)
+# set_target_properties(static_variant PROPERTIES
+# COMPILE_FLAGS -DLIBSHARED_AND_STATIC_STATIC_DEFINE)
#
-# If the same sources are used to create both a shared and a static library, the
-# uppercased symbol ${BASE_NAME}_STATIC_DEFINE should be used when building the
-# static library
+# This will cause the export macros to expand to nothing when building
+# the static library.
#
-# add_library(shared_variant SHARED ${lib_SRCS})
-# add_library(static_variant ${lib_SRCS})
-# generate_export_header(shared_variant BASE_NAME libshared_and_static)
-# set_target_properties(static_variant PROPERTIES
-# COMPILE_FLAGS -DLIBSHARED_AND_STATIC_STATIC_DEFINE)
+# If ``DEFINE_NO_DEPRECATED`` is specified, then a macro
+# ``${BASE_NAME}_NO_DEPRECATED`` will be defined This macro can be used to
+# remove deprecated code from preprocessor output:
#
-# This will cause the export macros to expand to nothing when building the
-# static library.
+# .. code-block:: cmake
#
-# If DEFINE_NO_DEPRECATED is specified, then a macro ${BASE_NAME}_NO_DEPRECATED
-# will be defined
-# This macro can be used to remove deprecated code from preprocessor output.
+# option(EXCLUDE_DEPRECATED "Exclude deprecated parts of the library" FALSE)
+# if (EXCLUDE_DEPRECATED)
+# set(NO_BUILD_DEPRECATED DEFINE_NO_DEPRECATED)
+# endif()
+# generate_export_header(somelib ${NO_BUILD_DEPRECATED})
#
-# option(EXCLUDE_DEPRECATED "Exclude deprecated parts of the library" FALSE)
-# if (EXCLUDE_DEPRECATED)
-# set(NO_BUILD_DEPRECATED DEFINE_NO_DEPRECATED)
-# endif()
-# generate_export_header(somelib ${NO_BUILD_DEPRECATED})
#
# And then in somelib:
#
-# class SOMELIB_EXPORT SomeClass
-# {
-# public:
-# #ifndef SOMELIB_NO_DEPRECATED
-# SOMELIB_DEPRECATED void oldMethod();
-# #endif
-# };
+# .. code-block:: c++
#
-# #ifndef SOMELIB_NO_DEPRECATED
-# void SomeClass::oldMethod() { }
-# #endif
+# class SOMELIB_EXPORT SomeClass
+# {
+# public:
+# #ifndef SOMELIB_NO_DEPRECATED
+# SOMELIB_DEPRECATED void oldMethod();
+# #endif
+# };
#
-# If PREFIX_NAME is specified, the argument will be used as a prefix to all
-# generated macros.
+# .. code-block:: c++
+#
+# #ifndef SOMELIB_NO_DEPRECATED
+# void SomeClass::oldMethod() { }
+# #endif
+#
+#
+# If ``PREFIX_NAME`` is specified, the argument will be used as a prefix to
+# all generated macros.
#
# For example:
#
-# generate_export_header(somelib PREFIX_NAME VTK_)
+# .. code-block:: cmake
#
-# Generates the macros VTK_SOMELIB_EXPORT etc.
-
-#=============================================================================
-# Copyright 2011 Stephen Kelly <steveire@gmail.com>
+# generate_export_header(somelib PREFIX_NAME VTK_)
+#
+# Generates the macros ``VTK_SOMELIB_EXPORT`` etc.
+#
+# ::
+#
+# ADD_COMPILER_EXPORT_FLAGS( [<output_variable>] )
#
-# Distributed under the OSI-approved BSD License (the "License");
-# see accompanying file Copyright.txt for details.
+# The ``ADD_COMPILER_EXPORT_FLAGS`` function adds ``-fvisibility=hidden`` to
+# :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` if supported, and is a no-op
+# on Windows which does not need extra compiler flags for exporting support.
+# You may optionally pass a single argument to ``ADD_COMPILER_EXPORT_FLAGS``
+# that will be populated with the ``CXX_FLAGS`` required to enable visibility
+# support for the compiler/architecture in use.
#
-# This software is distributed WITHOUT ANY WARRANTY; without even the
-# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-# See the License for more information.
-#=============================================================================
-# (To distribute this file outside of CMake, substitute the full
-# License text for the above reference.)
+# This function is deprecated. Set the target properties
+# :prop_tgt:`CXX_VISIBILITY_PRESET <<LANG>_VISIBILITY_PRESET>` and
+# :prop_tgt:`VISIBILITY_INLINES_HIDDEN` instead.
-include(CMakeParseArguments)
include(CheckCXXCompilerFlag)
# TODO: Install this macro separately?
@@ -156,7 +197,7 @@ macro(_test_compiler_hidden_visibility)
if(CMAKE_COMPILER_IS_GNUCXX AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS "4.2")
set(GCC_TOO_OLD TRUE)
- elseif(CMAKE_COMPILER_IS_GNUC AND CMAKE_C_COMPILER_VERSION VERSION_LESS "4.2")
+ elseif(CMAKE_COMPILER_IS_GNUCC AND CMAKE_C_COMPILER_VERSION VERSION_LESS "4.2")
set(GCC_TOO_OLD TRUE)
elseif(CMAKE_CXX_COMPILER_ID MATCHES Intel AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS "12.0")
set(_INTEL_TOO_OLD TRUE)
@@ -164,29 +205,29 @@ macro(_test_compiler_hidden_visibility)
# Exclude XL here because it misinterprets -fvisibility=hidden even though
# the check_cxx_compiler_flag passes
- # http://www.cdash.org/CDash/testDetails.php?test=109109951&build=1419259
if(NOT GCC_TOO_OLD
AND NOT _INTEL_TOO_OLD
AND NOT WIN32
AND NOT CYGWIN
- AND NOT "${CMAKE_CXX_COMPILER_ID}" MATCHES XL
- AND NOT "${CMAKE_CXX_COMPILER_ID}" MATCHES PGI
- AND NOT "${CMAKE_CXX_COMPILER_ID}" MATCHES Watcom)
+ AND NOT CMAKE_CXX_COMPILER_ID MATCHES XL
+ AND NOT CMAKE_CXX_COMPILER_ID MATCHES PGI
+ AND NOT CMAKE_CXX_COMPILER_ID MATCHES Watcom)
check_cxx_compiler_flag(-fvisibility=hidden COMPILER_HAS_HIDDEN_VISIBILITY)
check_cxx_compiler_flag(-fvisibility-inlines-hidden
COMPILER_HAS_HIDDEN_INLINE_VISIBILITY)
- option(USE_COMPILER_HIDDEN_VISIBILITY
- "Use HIDDEN visibility support if available." ON)
- mark_as_advanced(USE_COMPILER_HIDDEN_VISIBILITY)
endif()
endmacro()
macro(_test_compiler_has_deprecated)
- if("${CMAKE_CXX_COMPILER_ID}" MATCHES Borland
- OR "${CMAKE_CXX_COMPILER_ID}" MATCHES HP
+ # NOTE: Some Embarcadero compilers silently compile __declspec(deprecated)
+ # without error, but this is not a documented feature and the attribute does
+ # not actually generate any warnings.
+ if(CMAKE_CXX_COMPILER_ID MATCHES Borland
+ OR CMAKE_CXX_COMPILER_ID MATCHES Embarcadero
+ OR CMAKE_CXX_COMPILER_ID MATCHES HP
OR GCC_TOO_OLD
- OR "${CMAKE_CXX_COMPILER_ID}" MATCHES PGI
- OR "${CMAKE_CXX_COMPILER_ID}" MATCHES Watcom)
+ OR CMAKE_CXX_COMPILER_ID MATCHES PGI
+ OR CMAKE_CXX_COMPILER_ID MATCHES Watcom)
set(COMPILER_HAS_DEPRECATED "" CACHE INTERNAL
"Compiler support for a deprecated attribute")
else()
@@ -220,10 +261,10 @@ macro(_DO_SET_MACRO_VALUES TARGET_LIBRARY)
get_property(type TARGET ${TARGET_LIBRARY} PROPERTY TYPE)
if(NOT ${type} STREQUAL "STATIC_LIBRARY")
- if(WIN32)
+ if(WIN32 OR CYGWIN)
set(DEFINE_EXPORT "__declspec(dllexport)")
set(DEFINE_IMPORT "__declspec(dllimport)")
- elseif(COMPILER_HAS_HIDDEN_VISIBILITY AND USE_COMPILER_HIDDEN_VISIBILITY)
+ elseif(COMPILER_HAS_HIDDEN_VISIBILITY)
set(DEFINE_EXPORT "__attribute__((visibility(\"default\")))")
set(DEFINE_IMPORT "__attribute__((visibility(\"default\")))")
set(DEFINE_NO_EXPORT "__attribute__((visibility(\"hidden\")))")
@@ -236,7 +277,7 @@ macro(_DO_GENERATE_EXPORT_HEADER TARGET_LIBRARY)
set(options DEFINE_NO_DEPRECATED)
set(oneValueArgs PREFIX_NAME BASE_NAME EXPORT_MACRO_NAME EXPORT_FILE_NAME
DEPRECATED_MACRO_NAME NO_EXPORT_MACRO_NAME STATIC_DEFINE
- NO_DEPRECATED_MACRO_NAME)
+ NO_DEPRECATED_MACRO_NAME CUSTOM_CONTENT_FROM_VARIABLE)
set(multiValueArgs)
cmake_parse_arguments(_GEH "${options}" "${oneValueArgs}" "${multiValueArgs}"
@@ -289,7 +330,9 @@ macro(_DO_GENERATE_EXPORT_HEADER TARGET_LIBRARY)
string(MAKE_C_IDENTIFIER ${STATIC_DEFINE} STATIC_DEFINE)
if(_GEH_DEFINE_NO_DEPRECATED)
- set(DEFINE_NO_DEPRECATED TRUE)
+ set(DEFINE_NO_DEPRECATED 1)
+ else()
+ set(DEFINE_NO_DEPRECATED 0)
endif()
if(_GEH_NO_DEPRECATED_MACRO_NAME)
@@ -307,6 +350,14 @@ macro(_DO_GENERATE_EXPORT_HEADER TARGET_LIBRARY)
endif()
string(MAKE_C_IDENTIFIER ${EXPORT_IMPORT_CONDITION} EXPORT_IMPORT_CONDITION)
+ if(_GEH_CUSTOM_CONTENT_FROM_VARIABLE)
+ if(DEFINED "${_GEH_CUSTOM_CONTENT_FROM_VARIABLE}")
+ set(CUSTOM_CONTENT "${${_GEH_CUSTOM_CONTENT_FROM_VARIABLE}}")
+ else()
+ set(CUSTOM_CONTENT "")
+ endif()
+ endif()
+
configure_file("${_GENERATE_EXPORT_HEADER_MODULE_DIR}/exportheader.cmake.in"
"${EXPORT_FILE_NAME}" @ONLY)
endmacro()
@@ -315,6 +366,7 @@ function(GENERATE_EXPORT_HEADER TARGET_LIBRARY)
get_property(type TARGET ${TARGET_LIBRARY} PROPERTY TYPE)
if(NOT ${type} STREQUAL "STATIC_LIBRARY"
AND NOT ${type} STREQUAL "SHARED_LIBRARY"
+ AND NOT ${type} STREQUAL "OBJECT_LIBRARY"
AND NOT ${type} STREQUAL "MODULE_LIBRARY")
message(WARNING "This macro can only be used with libraries")
return()
@@ -326,10 +378,16 @@ function(GENERATE_EXPORT_HEADER TARGET_LIBRARY)
endfunction()
function(add_compiler_export_flags)
+ if(NOT CMAKE_MINIMUM_REQUIRED_VERSION VERSION_LESS 2.8.12)
+ message(DEPRECATION "The add_compiler_export_flags function is obsolete. Use the CXX_VISIBILITY_PRESET and VISIBILITY_INLINES_HIDDEN target properties instead.")
+ endif()
_test_compiler_hidden_visibility()
_test_compiler_has_deprecated()
+ option(USE_COMPILER_HIDDEN_VISIBILITY
+ "Use HIDDEN visibility support if available." ON)
+ mark_as_advanced(USE_COMPILER_HIDDEN_VISIBILITY)
if(NOT (USE_COMPILER_HIDDEN_VISIBILITY AND COMPILER_HAS_HIDDEN_VISIBILITY))
# Just return if there are no flags to add.
return()
@@ -343,9 +401,10 @@ function(add_compiler_export_flags)
# Either return the extra flags needed in the supplied argument, or to the
# CMAKE_CXX_FLAGS if no argument is supplied.
- if(ARGV0)
+ if(ARGC GREATER 0)
set(${ARGV0} "${EXTRA_FLAGS}" PARENT_SCOPE)
else()
- set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${EXTRA_FLAGS}" PARENT_SCOPE)
+ string(APPEND CMAKE_CXX_FLAGS " ${EXTRA_FLAGS}")
+ set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS}" PARENT_SCOPE)
endif()
endfunction()