summaryrefslogtreecommitdiff
path: root/Modules/GenerateExportHeader.cmake
diff options
context:
space:
mode:
Diffstat (limited to 'Modules/GenerateExportHeader.cmake')
-rw-r--r--Modules/GenerateExportHeader.cmake367
1 files changed, 184 insertions, 183 deletions
diff --git a/Modules/GenerateExportHeader.cmake b/Modules/GenerateExportHeader.cmake
index e6dcd00f7a..f2e4527664 100644
--- a/Modules/GenerateExportHeader.cmake
+++ b/Modules/GenerateExportHeader.cmake
@@ -1,189 +1,190 @@
# 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>]
-# [INCLUDE_GUARD_NAME <include_guard_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:
-#
-# .. 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``.
-# 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:
-#
-# .. code-block:: cmake
-#
-# 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
-# )
-#
-#
-# creates the macro ``KDE_DEPRECATED`` instead of ``SOMELIB_DEPRECATED``.
-#
-# If ``LIBRARY_TARGET`` is a static library, macros are defined without
-# values.
-#
-# 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:
-#
-# .. code-block:: cmake
-#
-# 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)
-#
-# This will cause the export macros to expand to nothing when building
-# the static library.
-#
-# 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:
-#
-# .. code-block:: cmake
-#
-# 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:
-#
-# .. code-block:: c++
-#
-# 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
-#
-#
-# If ``PREFIX_NAME`` is specified, the argument will be used as a prefix to
-# all generated macros.
-#
-# For example:
-#
-# .. code-block:: cmake
-#
-# generate_export_header(somelib PREFIX_NAME VTK_)
-#
-# Generates the macros ``VTK_SOMELIB_EXPORT`` etc.
-#
-# ::
-#
-# ADD_COMPILER_EXPORT_FLAGS( [<output_variable>] )
-#
-# 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 function is deprecated. Set the target properties
-# :prop_tgt:`CXX_VISIBILITY_PRESET <<LANG>_VISIBILITY_PRESET>` and
-# :prop_tgt:`VISIBILITY_INLINES_HIDDEN` instead.
+#[=======================================================================[.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>]
+ [INCLUDE_GUARD_NAME <include_guard_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:
+
+.. 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``.
+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:
+
+.. code-block:: cmake
+
+ 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
+ )
+
+
+creates the macro ``KDE_DEPRECATED`` instead of ``SOMELIB_DEPRECATED``.
+
+If ``LIBRARY_TARGET`` is a static library, macros are defined without
+values.
+
+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:
+
+.. code-block:: cmake
+
+ 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)
+
+This will cause the export macros to expand to nothing when building
+the static library.
+
+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:
+
+.. code-block:: cmake
+
+ 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:
+
+.. code-block:: c++
+
+ 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
+
+
+If ``PREFIX_NAME`` is specified, the argument will be used as a prefix to
+all generated macros.
+
+For example:
+
+.. code-block:: cmake
+
+ generate_export_header(somelib PREFIX_NAME VTK_)
+
+Generates the macros ``VTK_SOMELIB_EXPORT`` etc.
+
+::
+
+ ADD_COMPILER_EXPORT_FLAGS( [<output_variable>] )
+
+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 function is deprecated. Set the target properties
+:prop_tgt:`CXX_VISIBILITY_PRESET <<LANG>_VISIBILITY_PRESET>` and
+:prop_tgt:`VISIBILITY_INLINES_HIDDEN` instead.
+#]=======================================================================]
include(CheckCCompilerFlag)
include(CheckCXXCompilerFlag)