kolan
/
CMake
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

GenerateExportHeader: Reformat docs.

This commit is contained in:
Stephen Kelly 2013-12-20 14:12:48 +01:00
parent 272a20f8e5
commit ea78935f62
1 changed files with 51 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

115
Modules/GenerateExportHeader.cmake
View File

@ -6,14 +6,11 @@
# #
# This module provides the function GENERATE_EXPORT_HEADER(). # 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 # suitable for preprocessor inclusion which contains EXPORT macros to be
# used in library classes. # used in library classes::
#
# GENERATE_EXPORT_HEADER( LIBRARY_TARGET
#
# ::
# #
# GENERATE_EXPORT_HEADER( LIBRARY_TARGET
# [BASE_NAME <base_name>] # [BASE_NAME <base_name>]
# [EXPORT_MACRO_NAME <export_macro_name>] # [EXPORT_MACRO_NAME <export_macro_name>]
# [EXPORT_FILE_NAME <export_file_name>] # [EXPORT_FILE_NAME <export_file_name>]
@ -23,20 +20,21 @@
# [NO_DEPRECATED_MACRO_NAME <no_deprecated_macro_name>] # [NO_DEPRECATED_MACRO_NAME <no_deprecated_macro_name>]
# [DEFINE_NO_DEPRECATED] # [DEFINE_NO_DEPRECATED]
# [PREFIX_NAME <prefix_name>] # [PREFIX_NAME <prefix_name>]
# )
# #
# )
# #
# The target properties CXX_VISIBILITY_PRESET and # The target properties :prop_tgt:`CXX_VISIBILITY_PRESET <<LANG>_VISIBILITY_PRESET>`
# VISIBILITY_INLINES_HIDDEN can be used to add the appropriate compile # and :prop_tgt:`VISIBILITY_INLINES_HIDDEN` can be used to add the appropriate
# flags for targets. See the documentation of those target properties, # compile flags for targets. See the documentation of those target properties,
# and the convenience variables CMAKE_CXX_VISIBILITY_PRESET and # and the convenience variables
# CMAKE_VISIBILITY_INLINES_HIDDEN. # :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 # 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_CXX_VISIBILITY_PRESET hidden)
# set(CMAKE_VISIBILITY_INLINES_HIDDEN 1) # set(CMAKE_VISIBILITY_INLINES_HIDDEN 1)
@ -49,10 +47,9 @@
# ) # )
# #
# #
#
# And in the ABI header files: # And in the ABI header files:
# #
# :: # .. code-block:: c++
# #
# #include "somelib_export.h" # #include "somelib_export.h"
# class SOMELIB_EXPORT SomeClass { # class SOMELIB_EXPORT SomeClass {
@ -60,17 +57,16 @@
# }; # };
# #
# #
#
# The CMake fragment will generate a file in the # The CMake fragment will generate a file in the
# ${CMAKE_CURRENT_BINARY_DIR} called somelib_export.h containing the # ``${CMAKE_CURRENT_BINARY_DIR}`` called ``somelib_export.h`` containing the
# macros SOMELIB_EXPORT, SOMELIB_NO_EXPORT, SOMELIB_DEPRECATED, # macros ``SOMELIB_EXPORT``, ``SOMELIB_NO_EXPORT``, ``SOMELIB_DEPRECATED``,
# SOMELIB_DEPRECATED_EXPORT and SOMELIB_DEPRECATED_NO_EXPORT. The # ``SOMELIB_DEPRECATED_EXPORT`` and ``SOMELIB_DEPRECATED_NO_EXPORT``. The
# resulting file should be installed with other headers in the library. # 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 # The ``BASE_NAME`` argument can be used to override the file name and the
# names used for the macros # names used for the macros:
# #
# :: # .. code-block:: cmake
# #
# add_library(somelib someclass.cpp) # add_library(somelib someclass.cpp)
# generate_export_header(somelib # 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 # The ``BASE_NAME`` may be overridden by specifiying other options in the
# OTHER_NAME_EXPORT, OTHER_NAME_NO_EXPORT and OTHER_NAME_DEPRECATED etc.
#
# The BASE_NAME may be overridden by specifiying other options in the
# function. For example: # function. For example:
# #
# :: # .. code-block:: cmake
# #
# add_library(somelib someclass.cpp) # add_library(somelib someclass.cpp)
# generate_export_header(somelib # 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 # .. code-block:: cmake
# other macros and the generated file name is as default.
#
# ::
# #
# add_library(somelib someclass.cpp) # add_library(somelib someclass.cpp)
# generate_export_header(somelib # 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. # values.
# #
# If the same sources are used to create both a shared and a static # If the same sources are used to create both a shared and a static
# library, the uppercased symbol ${BASE_NAME}_STATIC_DEFINE should be # library, the uppercased symbol ``${BASE_NAME}_STATIC_DEFINE`` should be
# used when building the static library # used when building the static library:
# #
# :: # .. code-block:: cmake
# #
# add_library(shared_variant SHARED ${lib_SRCS}) # add_library(shared_variant SHARED ${lib_SRCS})
# add_library(static_variant ${lib_SRCS}) # add_library(static_variant ${lib_SRCS})
@ -123,16 +117,14 @@
# set_target_properties(static_variant PROPERTIES # set_target_properties(static_variant PROPERTIES
# COMPILE_FLAGS -DLIBSHARED_AND_STATIC_STATIC_DEFINE) # COMPILE_FLAGS -DLIBSHARED_AND_STATIC_STATIC_DEFINE)
# #
#
#
# This will cause the export macros to expand to nothing when building # This will cause the export macros to expand to nothing when building
# the static library. # the static library.
# #
# If DEFINE_NO_DEPRECATED is specified, then a macro # If ``DEFINE_NO_DEPRECATED`` is specified, then a macro
# ${BASE_NAME}_NO_DEPRECATED will be defined This macro can be used to # ``${BASE_NAME}_NO_DEPRECATED`` will be defined This macro can be used to
# remove deprecated code from preprocessor output. # remove deprecated code from preprocessor output:
# #
# :: # .. code-block:: cmake
# #
# option(EXCLUDE_DEPRECATED "Exclude deprecated parts of the library" FALSE) # option(EXCLUDE_DEPRECATED "Exclude deprecated parts of the library" FALSE)
# if (EXCLUDE_DEPRECATED) # if (EXCLUDE_DEPRECATED)
@ -141,10 +133,9 @@
# generate_export_header(somelib ${NO_BUILD_DEPRECATED}) # generate_export_header(somelib ${NO_BUILD_DEPRECATED})
# #
# #
#
# And then in somelib: # And then in somelib:
# #
# :: # .. code-block:: c++
# #
# class SOMELIB_EXPORT SomeClass # class SOMELIB_EXPORT SomeClass
# { # {
@ -154,42 +145,38 @@
# #endif # #endif
# }; # };
# #
# # .. code-block:: c++
#
# ::
# #
# #ifndef SOMELIB_NO_DEPRECATED # #ifndef SOMELIB_NO_DEPRECATED
# void SomeClass::oldMethod() { } # void SomeClass::oldMethod() { }
# #endif # #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. # all generated macros.
# #
# For example: # For example:
# #
# :: # .. code-block:: cmake
# #
# generate_export_header(somelib PREFIX_NAME VTK_) # 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>] )
# #
# # The ``ADD_COMPILER_EXPORT_FLAGS`` function adds ``-fvisibility=hidden`` to
# # :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` if supported, and is a no-op
# ADD_COMPILER_EXPORT_FLAGS( [<output_variable>] ) # on Windows which does not need extra compiler flags for exporting support.
# # You may optionally pass a single argument to ``ADD_COMPILER_EXPORT_FLAGS``
# The ADD_COMPILER_EXPORT_FLAGS function adds -fvisibility=hidden to # that will be populated with the ``CXX_FLAGS`` required to enable visibility
# 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. # support for the compiler/architecture in use.
# #
# This function is deprecated. Set the target properties # 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> # Copyright 2011 Stephen Kelly <steveire@gmail.com>