diff options
Diffstat (limited to 'Modules')
| -rw-r--r-- | Modules/GenerateExportHeader.cmake | 115 |
1 files changed, 51 insertions, 64 deletions
diff --git a/Modules/GenerateExportHeader.cmake b/Modules/GenerateExportHeader.cmake index 5baf9e0..f83f992 100644 --- a/Modules/GenerateExportHeader.cmake +++ b/Modules/GenerateExportHeader.cmake @@ -6,14 +6,11 @@ # # This module provides the function GENERATE_EXPORT_HEADER(). # -# The GENERATE_EXPORT_HEADER function can be used to generate a file +# 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 -# -# :: +# 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>] @@ -23,20 +20,21 @@ # [NO_DEPRECATED_MACRO_NAME <no_deprecated_macro_name>] # [DEFINE_NO_DEPRECATED] # [PREFIX_NAME <prefix_name>] +# ) # -# ) # -# The target properties CXX_VISIBILITY_PRESET and -# 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 CMAKE_CXX_VISIBILITY_PRESET and -# CMAKE_VISIBILITY_INLINES_HIDDEN. +# 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 +# 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 generate_export_header will be equivalent to: +# simplest case, users of ``GenerateExportHeader`` will be equivalent to: # -# :: +# .. code-block:: cmake # # set(CMAKE_CXX_VISIBILITY_PRESET hidden) # set(CMAKE_VISIBILITY_INLINES_HIDDEN 1) @@ -49,10 +47,9 @@ # ) # # -# # And in the ABI header files: # -# :: +# .. code-block:: c++ # # #include "somelib_export.h" # class SOMELIB_EXPORT SomeClass { @@ -60,17 +57,16 @@ # }; # # -# # 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_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 # 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: # -# :: +# .. code-block:: cmake # # add_library(somelib someclass.cpp) # generate_export_header(somelib @@ -78,14 +74,14 @@ # ) # # +# Generates a file called ``other_name_export.h`` containing the macros +# ``OTHER_NAME_EXPORT``, ``OTHER_NAME_NO_EXPORT`` and ``OTHER_NAME_DEPRECATED`` +# etc. # -# 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 specifiying other options in the +# The ``BASE_NAME`` may be overridden by specifiying other options in the # function. For example: # -# :: +# .. code-block:: cmake # # add_library(somelib someclass.cpp) # generate_export_header(somelib @@ -93,11 +89,10 @@ # ) # # +# creates the macro ``OTHER_NAME_EXPORT`` instead of ``SOMELIB_EXPORT``, but +# other macros and the generated file name is as default: # -# 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 @@ -105,17 +100,16 @@ # ) # # +# creates the macro ``KDE_DEPRECATED`` instead of ``SOMELIB_DEPRECATED``. # -# creates the macro KDE_DEPRECATED instead of SOMELIB_DEPRECATED. -# -# If LIBRARY_TARGET is a static library, macros are defined without +# 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 +# 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}) @@ -123,16 +117,14 @@ # 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. +# 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) @@ -141,10 +133,9 @@ # generate_export_header(somelib ${NO_BUILD_DEPRECATED}) # # -# # And then in somelib: # -# :: +# .. code-block:: c++ # # class SOMELIB_EXPORT SomeClass # { @@ -154,42 +145,38 @@ # #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 +# 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. # +# :: # -# Generates the macros VTK_SOMELIB_EXPORT etc. -# -# -# -# ADD_COMPILER_EXPORT_FLAGS( [<output_variable>] ) +# ADD_COMPILER_EXPORT_FLAGS( [<output_variable>] ) # -# 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 +# 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 -# CXX_VISIBILITY_PRESET and VISIBILITY_INLINES_HIDDEN instead. +# :prop_tgt:`CXX_VISIBILITY_PRESET <<LANG>_VISIBILITY_PRESET>` and +# :prop_tgt:`VISIBILITY_INLINES_HIDDEN` instead. #============================================================================= # Copyright 2011 Stephen Kelly <steveire@gmail.com> |