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

View File

@ -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>