Commit 93f3f655 authored by Joachim Wuttke's avatar Joachim Wuttke Committed by Craig Scott

Help: Revise docs of modules AddFileDependencies..CheckFunctionExists

* Replace '::' by '.. code-block:: cmake' wherever it makes sense.
* Convert to definition list where appropriate.
* Prefer '<placeholder>' over 'placeholder'.
parent fc7ee1ca
......@@ -5,9 +5,13 @@
# AddFileDependencies
# -------------------
#
# ADD_FILE_DEPENDENCIES(source_file depend_files...)
# Add dependencies to a source file.
#
# Adds the given files as dependencies to source_file
# .. code-block:: cmake
#
# ADD_FILE_DEPENDENCIES(<source> <files>)
#
# Adds the given ``<files>`` to the dependencies of file ``<source>``.
macro(ADD_FILE_DEPENDENCIES _file)
......
......@@ -40,7 +40,7 @@ Module Functions
.. command:: android_add_test_data
::
.. code-block:: cmake
android_add_test_data(<test-name>
[FILES <files>...] [FILES_DEST <device-dir>]
......
......@@ -12,7 +12,7 @@ bundles on the Mac and bundle-like directories on any OS.
The following functions are provided by this module:
::
.. code-block:: cmake
fixup_bundle
copy_and_fixup_bundle
......@@ -39,7 +39,7 @@ DO NOT USE THESE FUNCTIONS AT CONFIGURE TIME (from ``CMakeLists.txt``)!
Instead, invoke them from an :command:`install(CODE)` or
:command:`install(SCRIPT)` rule.
::
.. code-block:: cmake
FIXUP_BUNDLE(<app> <libs> <dirs>)
......@@ -62,14 +62,14 @@ ensure that it is truly standalone.
As an optional parameter (IGNORE_ITEM) a list of file names can be passed,
which are then ignored (e.g. IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe")
::
.. code-block:: cmake
COPY_AND_FIXUP_BUNDLE(<src> <dst> <libs> <dirs>)
Makes a copy of the bundle <src> at location <dst> and then fixes up
the new copied bundle in-place at <dst>...
::
.. code-block:: cmake
VERIFY_APP(<app>)
......@@ -80,14 +80,14 @@ is not verified.
As an optional parameter (IGNORE_ITEM) a list of file names can be passed,
which are then ignored (e.g. IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe")
::
.. code-block:: cmake
GET_BUNDLE_MAIN_EXECUTABLE(<bundle> <result_var>)
The result will be the full path name of the bundle's main executable
file or an "error:" prefixed string if it could not be determined.
::
.. code-block:: cmake
GET_DOTAPP_DIR(<exe> <dotapp_dir_var>)
......@@ -97,7 +97,7 @@ simply return the dir containing the executable.
The returned directory may or may not exist.
::
.. code-block:: cmake
GET_BUNDLE_AND_EXECUTABLE(<app> <bundle_var> <executable_var> <valid_var>)
......@@ -106,14 +106,14 @@ nested inside a ".app" directory and returns the path to the ".app"
directory in <bundle_var> and the path to its main executable in
<executable_var>
::
.. code-block:: cmake
GET_BUNDLE_ALL_EXECUTABLES(<bundle> <exes_var>)
Scans the given bundle recursively for all executable files and
accumulates them into a variable.
::
.. code-block:: cmake
GET_ITEM_KEY(<item> <key_var>)
......@@ -125,7 +125,7 @@ extension with "." replaced by "_"
This key is used as a prefix for CMake variables so that we can
associate a set of variables with a given item based on its key.
::
.. code-block:: cmake
CLEAR_BUNDLE_KEYS(<keys_var>)
......@@ -135,7 +135,7 @@ each key. After the loop, clear the list of keys itself.
Caller of get_bundle_keys should call clear_bundle_keys when done with
list of keys.
::
.. code-block:: cmake
SET_BUNDLE_KEY_VALUES(<keys_var> <context> <item> <exepath> <dirs>
<copyflag> [<rpaths>])
......@@ -143,7 +143,7 @@ list of keys.
Add a key to the list (if necessary) for the given item. If added,
also set all the variables associated with that key.
::
.. code-block:: cmake
GET_BUNDLE_KEYS(<app> <libs> <dirs> <keys_var>)
......@@ -156,7 +156,7 @@ appropriate install_name_tool fixups.
As an optional parameter (IGNORE_ITEM) a list of file names can be passed,
which are then ignored (e.g. IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe")
::
.. code-block:: cmake
COPY_RESOLVED_ITEM_INTO_BUNDLE(<resolved_item> <resolved_embedded_item>)
......@@ -164,7 +164,7 @@ Copy a resolved item into the bundle if necessary. Copy is not
necessary if the resolved_item is "the same as" the
resolved_embedded_item.
::
.. code-block:: cmake
COPY_RESOLVED_FRAMEWORK_INTO_BUNDLE(<resolved_item> <resolved_embedded_item>)
......@@ -178,7 +178,7 @@ BU_COPY_FULL_FRAMEWORK_CONTENTS to ON before calling fixup_bundle. By
default, COPY_RESOLVED_FRAMEWORK_INTO_BUNDLE copies the framework
dylib itself plus the framework Resources directory.
::
.. code-block:: cmake
FIXUP_BUNDLE_ITEM(<resolved_embedded_item> <exepath> <dirs>)
......@@ -204,7 +204,7 @@ once.
If the BU_CHMOD_BUNDLE_ITEMS variable is set then bundle items will be
marked writable before install_name_tool tries to change them.
::
.. code-block:: cmake
VERIFY_BUNDLE_PREREQUISITES(<bundle> <result_var> <info_var>)
......@@ -215,7 +215,7 @@ presumed to exist everywhere.
As an optional parameter (IGNORE_ITEM) a list of file names can be passed,
which are then ignored (e.g. IGNORE_ITEM "vcredist_x86.exe;vcredist_x64.exe")
::
.. code-block:: cmake
VERIFY_BUNDLE_SYMLINKS(<bundle> <result_var> <info_var>)
......
......@@ -9,7 +9,7 @@ Check whether the C compiler supports a given flag.
.. command:: check_c_compiler_flag
::
.. code-block:: cmake
check_c_compiler_flag(<flag> <var>)
......
......@@ -9,15 +9,16 @@ Check if given C source compiles and links into an executable.
.. command:: check_c_source_compiles
::
.. code-block:: cmake
check_c_source_compiles(code resultVar [FAIL_REGEX regex1 [regex2...]])
check_c_source_compiles(<code> <resultVar>
[FAIL_REGEX <regex1> [<regex2>...]])
Check that the source supplied in ``code`` can be compiled as a C source
Check that the source supplied in ``<code>`` can be compiled as a C source
file and linked as an executable (so it must contain at least a ``main()``
function). The result will be stored in the internal cache variable specified
by ``resultVar``, with a boolean true value for success and boolean false for
failure. If ``FAIL_REGEX`` is provided, then failure is determined by
by ``<resultVar>``, with a boolean true value for success and boolean false
for failure. If ``FAIL_REGEX`` is provided, then failure is determined by
checking if anything in the output matches any of the specified regular
expressions.
......@@ -34,7 +35,7 @@ Check if given C source compiles and links into an executable.
``CMAKE_REQUIRED_DEFINITIONS``
A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form
``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by
``resultVar`` will also be added automatically.
``<resultVar>`` will also be added automatically.
``CMAKE_REQUIRED_INCLUDES``
A :ref:`;-list <CMake Language Lists>` of header search paths to pass to
......@@ -53,10 +54,10 @@ Check if given C source compiles and links into an executable.
associated with the check will be suppressed.
The check is only performed once, with the result cached in the variable
named by ``resultVar``. Every subsequent CMake run will re-use this cached
value rather than performing the check again, even if the ``code`` changes.
named by ``<resultVar>``. Every subsequent CMake run will re-use this cached
value rather than performing the check again, even if the ``<code>`` changes.
In order to force the check to be re-evaluated, the variable named by
``resultVar`` must be manually removed from the cache.
``<resultVar>`` must be manually removed from the cache.
#]=======================================================================]
......@@ -131,4 +132,3 @@ macro(CHECK_C_SOURCE_COMPILES SOURCE VAR)
endif()
endif()
endmacro()
......@@ -10,16 +10,16 @@ subsequently be run.
.. command:: check_c_source_runs
::
.. code-block:: cmake
check_c_source_runs(code resultVar)
check_c_source_runs(<code> <resultVar>)
Check that the source supplied in ``code`` can be compiled as a C source
file, linked as an executable and then run. The ``code`` must contain at
least a ``main()`` function. If the code could be built and run successfully,
the internal cache variable specified by ``resultVar`` will be set to 1,
otherwise it will be set to an value that evaluates to boolean false (e.g.
an empty string or an error message).
Check that the source supplied in ``<code>`` can be compiled as a C source
file, linked as an executable and then run. The ``<code>`` must contain at
least a ``main()`` function. If the ``<code>`` could be built and run
successfully, the internal cache variable specified by ``<resultVar>`` will
be set to 1, otherwise it will be set to an value that evaluates to boolean
false (e.g. an empty string or an error message).
The underlying check is performed by the :command:`try_run` command. The
compile and link commands can be influenced by setting any of the following
......@@ -34,7 +34,7 @@ subsequently be run.
``CMAKE_REQUIRED_DEFINITIONS``
A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form
``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by
``resultVar`` will also be added automatically.
``<resultVar>`` will also be added automatically.
``CMAKE_REQUIRED_INCLUDES``
A :ref:`;-list <CMake Language Lists>` of header search paths to pass to
......@@ -53,10 +53,10 @@ subsequently be run.
associated with the check will be suppressed.
The check is only performed once, with the result cached in the variable
named by ``resultVar``. Every subsequent CMake run will re-use this cached
value rather than performing the check again, even if the ``code`` changes.
named by ``<resultVar>``. Every subsequent CMake run will re-use this cached
value rather than performing the check again, even if the ``<code>`` changes.
In order to force the check to be re-evaluated, the variable named by
``resultVar`` must be manually removed from the cache.
``<resultVar>`` must be manually removed from the cache.
#]=======================================================================]
......@@ -132,4 +132,3 @@ macro(CHECK_C_SOURCE_RUNS SOURCE VAR)
endif()
endif()
endmacro()
......@@ -9,7 +9,7 @@ Check whether the CXX compiler supports a given flag.
.. command:: check_cxx_compiler_flag
::
.. code-block:: cmake
check_cxx_compiler_flag(<flag> <var>)
......@@ -61,4 +61,3 @@ macro (CHECK_CXX_COMPILER_FLAG _FLAG _RESULT)
set (CMAKE_REQUIRED_DEFINITIONS "${SAFE_CMAKE_REQUIRED_DEFINITIONS}")
endmacro ()
......@@ -9,15 +9,16 @@ Check if given C++ source compiles and links into an executable.
.. command:: check_cxx_source_compiles
::
.. code-block:: cmake
check_cxx_source_compiles(code resultVar [FAIL_REGEX regex1 [regex2...]])
check_cxx_source_compiles(<code> <resultVar>
[FAIL_REGEX <regex1> [<regex2>...]])
Check that the source supplied in ``code`` can be compiled as a C++ source
Check that the source supplied in ``<code>`` can be compiled as a C++ source
file and linked as an executable (so it must contain at least a ``main()``
function). The result will be stored in the internal cache variable specified
by ``resultVar``, with a boolean true value for success and boolean false for
failure. If ``FAIL_REGEX`` is provided, then failure is determined by
by ``<resultVar>``, with a boolean true value for success and boolean false
for failure. If ``FAIL_REGEX`` is provided, then failure is determined by
checking if anything in the output matches any of the specified regular
expressions.
......@@ -34,7 +35,7 @@ Check if given C++ source compiles and links into an executable.
``CMAKE_REQUIRED_DEFINITIONS``
A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form
``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by
``resultVar`` will also be added automatically.
``<resultVar>`` will also be added automatically.
``CMAKE_REQUIRED_INCLUDES``
A :ref:`;-list <CMake Language Lists>` of header search paths to pass to
......@@ -53,10 +54,10 @@ Check if given C++ source compiles and links into an executable.
associated with the check will be suppressed.
The check is only performed once, with the result cached in the variable
named by ``resultVar``. Every subsequent CMake run will re-use this cached
value rather than performing the check again, even if the ``code`` changes.
named by ``<resultVar>``. Every subsequent CMake run will re-use this cached
value rather than performing the check again, even if the ``<code>`` changes.
In order to force the check to be re-evaluated, the variable named by
``resultVar`` must be manually removed from the cache.
``<resultVar>`` must be manually removed from the cache.
#]=======================================================================]
......@@ -132,4 +133,3 @@ macro(CHECK_CXX_SOURCE_COMPILES SOURCE VAR)
endif()
endif()
endmacro()
......@@ -10,16 +10,16 @@ subsequently be run.
.. command:: check_cxx_source_runs
::
.. code-block:: cmake
check_cxx_source_runs(code resultVar)
check_cxx_source_runs(<code> <resultVar>)
Check that the source supplied in ``code`` can be compiled as a C++ source
file, linked as an executable and then run. The ``code`` must contain at
least a ``main()`` function. If the code could be built and run successfully,
the internal cache variable specified by ``resultVar`` will be set to 1,
otherwise it will be set to an value that evaluates to boolean false (e.g.
an empty string or an error message).
Check that the source supplied in ``<code>`` can be compiled as a C++ source
file, linked as an executable and then run. The ``<code>`` must contain at
least a ``main()`` function. If the ``<code>`` could be built and run
successfully, the internal cache variable specified by ``<resultVar>`` will
be set to 1, otherwise it will be set to an value that evaluates to boolean
false (e.g. an empty string or an error message).
The underlying check is performed by the :command:`try_run` command. The
compile and link commands can be influenced by setting any of the following
......@@ -34,7 +34,7 @@ subsequently be run.
``CMAKE_REQUIRED_DEFINITIONS``
A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form
``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by
``resultVar`` will also be added automatically.
``<resultVar>`` will also be added automatically.
``CMAKE_REQUIRED_INCLUDES``
A :ref:`;-list <CMake Language Lists>` of header search paths to pass to
......@@ -53,10 +53,10 @@ subsequently be run.
associated with the check will be suppressed.
The check is only performed once, with the result cached in the variable
named by ``resultVar``. Every subsequent CMake run will re-use this cached
value rather than performing the check again, even if the ``code`` changes.
named by ``<resultVar>``. Every subsequent CMake run will re-use this cached
value rather than performing the check again, even if the ``<code>`` changes.
In order to force the check to be re-evaluated, the variable named by
``resultVar`` must be manually removed from the cache.
``<resultVar>`` must be manually removed from the cache.
#]=======================================================================]
......@@ -127,4 +127,3 @@ macro(CHECK_CXX_SOURCE_RUNS SOURCE VAR)
endif()
endif()
endmacro()
......@@ -7,10 +7,12 @@
#
# Check if a symbol exists as a function, variable, or macro in C++
#
# CHECK_CXX_SYMBOL_EXISTS(<symbol> <files> <variable>)
# .. code-block:: cmake
#
# Check that the <symbol> is available after including given header
# <files> and store the result in a <variable>. Specify the list of
# CHECK_CXX_SYMBOL_EXISTS(<symbol> <files> <variable>)
#
# Check that the ``<symbol>`` is available after including given header
# ``<files>`` and store the result in a ``<variable>``. Specify the list of
# files in one argument as a semicolon-separated list.
# CHECK_CXX_SYMBOL_EXISTS() can be used to check in C++ files, as
# opposed to CHECK_SYMBOL_EXISTS(), which works only for C.
......@@ -24,13 +26,16 @@
# The following variables may be set before calling this macro to modify
# the way the check is run:
#
# ::
#
# CMAKE_REQUIRED_FLAGS = string of compile command line flags
# CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
# CMAKE_REQUIRED_INCLUDES = list of include directories
# CMAKE_REQUIRED_LIBRARIES = list of libraries to link
# CMAKE_REQUIRED_QUIET = execute quietly without messages
# ``CMAKE_REQUIRED_FLAGS``
# string of compile command line flags
# ``CMAKE_REQUIRED_DEFINITIONS``
# list of macros to define (-DFOO=bar)
# ``CMAKE_REQUIRED_INCLUDES``
# list of include directories
# ``CMAKE_REQUIRED_LIBRARIES``
# list of libraries to link
# ``CMAKE_REQUIRED_QUIET``
# execute quietly without messages
include_guard(GLOBAL)
include(CheckSymbolExists)
......
......@@ -9,7 +9,7 @@ Check whether the Fortran compiler supports a given flag.
.. command:: check_fortran_compiler_flag
::
.. code-block:: cmake
check_fortran_compiler_flag(<flag> <var>)
......
......@@ -5,24 +5,24 @@
# CheckFortranFunctionExists
# --------------------------
#
# macro which checks if the Fortran function exists
# :command:`Macro <macro>` which checks if a Fortran function exists.
#
# CHECK_FORTRAN_FUNCTION_EXISTS(FUNCTION VARIABLE)
# .. code-block:: cmake
#
# ::
#
# FUNCTION - the name of the Fortran function
# VARIABLE - variable to store the result
# Will be created as an internal cache variable.
# CHECK_FORTRAN_FUNCTION_EXISTS(<function> <result>)
#
# where
#
# ``<function>``
# the name of the Fortran function
# ``<result>``
# variable to store the result; will be created as an internal cache variable.
#
# The following variables may be set before calling this macro to modify
# the way the check is run:
#
# ::
#
# CMAKE_REQUIRED_LIBRARIES = list of libraries to link
# ``CMAKE_REQUIRED_LIBRARIES``
# list of libraries to link
include_guard(GLOBAL)
......
......@@ -9,23 +9,24 @@ Check if given Fortran source compiles and links into an executable.
.. command:: check_fortran_source_compiles
::
.. code-block:: cmake
check_fortran_source_compiles(code resultVar
[FAIL_REGEX regex1 [regex2...]]
[SRC_EXT ext]
check_fortran_source_compiles(<code> <resultVar>
[FAIL_REGEX <regex>...]
[SRC_EXT <extension>]
)
Check that the source supplied in ``code`` can be compiled as a Fortran
Checks that the source supplied in ``<code>`` can be compiled as a Fortran
source file and linked as an executable (so it must contain at least a
``PROGRAM`` entry point). The result will be stored in the internal cache
variable specified by ``resultVar``, with a boolean true value for success
and boolean false for failure. If ``FAIL_REGEX`` is provided, then failure is
determined by checking if anything in the output matches any of the specified
regular expressions.
variable ``<resultVar>``, with a boolean true value for success and boolean
false for failure.
If ``FAIL_REGEX`` is provided, then failure is determined by checking
if anything in the output matches any of the specified regular expressions.
By default, the test source file will be given a ``.F`` file extension. The
``SRC_EXT`` option can be used to override this with ``.ext`` instead.
``SRC_EXT`` option can be used to override this with ``.<extension>`` instead.
The underlying check is performed by the :command:`try_compile` command. The
compile and link commands can be influenced by setting any of the following
......@@ -40,7 +41,7 @@ Check if given Fortran source compiles and links into an executable.
``CMAKE_REQUIRED_DEFINITIONS``
A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form
``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by
``resultVar`` will also be added automatically.
``<resultVar>`` will also be added automatically.
``CMAKE_REQUIRED_INCLUDES``
A :ref:`;-list <CMake Language Lists>` of header search paths to pass to
......@@ -59,10 +60,10 @@ Check if given Fortran source compiles and links into an executable.
associated with the check will be suppressed.
The check is only performed once, with the result cached in the variable
named by ``resultVar``. Every subsequent CMake run will re-use this cached
value rather than performing the check again, even if the ``code`` changes.
named by ``<resultVar>``. Every subsequent CMake run will re-use this cached
value rather than performing the check again, even if the ``<code>`` changes.
In order to force the check to be re-evaluated, the variable named by
``resultVar`` must be manually removed from the cache.
``<resultVar>`` must be manually removed from the cache.
#]=======================================================================]
......
......@@ -5,24 +5,29 @@
# CheckFunctionExists
# -------------------
#
# Check if a C function can be linked::
# Check if a C function can be linked
#
# .. code-block:: cmake
#
# check_function_exists(<function> <variable>)
#
# Check that the ``<function>`` is provided by libraries on the system and store
# the result in a ``<variable>``. ``<variable>`` will be created as an internal
# Checks that the ``<function>`` is provided by libraries on the system and store
# the result in a ``<variable>``, which will be created as an internal
# cache variable.
#
# The following variables may be set before calling this macro to modify the
# way the check is run:
#
# ::
#
# CMAKE_REQUIRED_FLAGS = string of compile command line flags
# CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
# CMAKE_REQUIRED_INCLUDES = list of include directories
# CMAKE_REQUIRED_LIBRARIES = list of libraries to link
# CMAKE_REQUIRED_QUIET = execute quietly without messages
# ``CMAKE_REQUIRED_FLAGS``
# string of compile command line flags
# ``CMAKE_REQUIRED_DEFINITIONS``
# list of macros to define (-DFOO=bar)
# ``CMAKE_REQUIRED_INCLUDES``
# list of include directories
# ``CMAKE_REQUIRED_LIBRARIES``
# list of libraries to link
# ``CMAKE_REQUIRED_QUIET``
# execute quietly without messages
#
# .. note::
#
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment