diff options
Diffstat (limited to 'Modules/GenerateExportHeader.cmake')
-rw-r--r-- | Modules/GenerateExportHeader.cmake | 323 |
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() |