mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-05 21:31:08 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge topic 'help-syntax-highlighting'

Browse Source 
93f3f65516 Help: Revise docs of modules AddFileDependencies..CheckFunctionExists
fc7ee1ca45 Help: Override pygments CMakeLexer to support <..> and [..]
74b3eacdc7 Help: Use appropriate list types in FindPkgConfig

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !2468
This commit is contained in:
Craig Scott
2018-10-19 10:31:27 +00:00
committed by Kitware Robot
parent 250b8c1662 93f3f65516
commit 7053dd301c
22 changed files with 291 additions and 172 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
Help/command/execute_process.rst
View File

@@ -5,8 +5,8 @@ Execute one or more child processes.
.. code-block:: cmake
execute_process(COMMAND <cmd1> [args1...]]
[COMMAND <cmd2> [args2...] [...]]
execute_process(COMMAND <cmd1> [<arguments>]
[COMMAND <cmd2> [<arguments>]]...
[WORKING_DIRECTORY <directory>]
[TIMEOUT <seconds>]
[RESULT_VARIABLE <variable>]

17
Help/manual/cmake-language.7.rst
View File

@@ -206,9 +206,10 @@ enclosed content, such as `Escape Sequences`_ or `Variable References`_,
is performed. A bracket argument is always given to the command
invocation as exactly one argument.
For example:
.. No code-block syntax highlighting in the following example
(long string literal not supported by our cmake.py)
.. code-block:: cmake
For example::
message([=[
This is the first line in a bracket argument with bracket length 1.
@@ -253,9 +254,10 @@ closing quotes. Both `Escape Sequences`_ and `Variable References`_
are evaluated. A quoted argument is always given to the command
invocation as exactly one argument.
For example:
.. No code-block syntax highlighting in the following example
(escape \" not supported by our cmake.py)
::
For example::
message("This is a quoted argument containing multiple lines.
This is always one argument even though it contains a ; character.
@@ -264,11 +266,12 @@ For example:
It does end in an unescaped double quote.
")
.. No code-block syntax highlighting in the following example
(for conformity with the two above examples)
The final ``\`` on any line ending in an odd number of backslashes
is treated as a line continuation and ignored along with the
immediately following newline character. For example:
.. code-block:: cmake
immediately following newline character. For example::
message("\
This is the first line of a quoted argument. \

8
Help/policy/CMP0049.rst
View File

@@ -3,14 +3,14 @@ CMP0049
Do not expand variables in target source entries.
CMake 2.8.12 and lower performed and extra layer of variable expansion
when evaluating source file names:
.. code-block:: cmake
CMake 2.8.12 and lower performed an extra layer of variable expansion
when evaluating source file names::
set(a_source foo.c)
add_executable(foo \${a_source})
.. note: no cmake highlighting since this syntax is deprecated
This was undocumented behavior.
The OLD behavior for this policy is to expand such variables when processing

8
Modules/AddFileDependencies.cmake
View File

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

2
Modules/AndroidTestUtilities.cmake
View 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>]

34
Modules/BundleUtilities.cmake
View File

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

2
Modules/CheckCCompilerFlag.cmake
View File

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

20
Modules/CheckCSourceCompiles.cmake
View File

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

25
Modules/CheckCSourceRuns.cmake
View File

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

3
Modules/CheckCXXCompilerFlag.cmake
View File

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

20
Modules/CheckCXXSourceCompiles.cmake
View File

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

25
Modules/CheckCXXSourceRuns.cmake
View File

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

25
Modules/CheckCXXSymbolExists.cmake
View File

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

2
Modules/CheckFortranCompilerFlag.cmake
View File

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

20
Modules/CheckFortranFunctionExists.cmake
View File

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

29
Modules/CheckFortranSourceCompiles.cmake
View File

@@ -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.
#]=======================================================================]

25
Modules/CheckFunctionExists.cmake
View File

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

24
Modules/ExternalProject.cmake
View File

@@ -16,7 +16,9 @@ External Project Definition
The ``ExternalProject_Add()`` function creates a custom target to drive
download, update/patch, configure, build, install and test steps of an
external project::
external project:
.. code-block:: cmake
ExternalProject_Add(<name> [<option>...])
@@ -608,7 +610,9 @@ External Project Definition
appended to them by following them with as many ``COMMAND ...`` options
as needed
(:manual:`generator expressions <cmake-generator-expressions(7)>` are
supported). For example::
supported). For example:
.. code-block:: cmake
ExternalProject_Add(example
... # Download options, etc.
@@ -627,7 +631,9 @@ Obtaining Project Properties
.. command:: ExternalProject_Get_Property
The ``ExternalProject_Get_Property()`` function retrieves external project
target properties::
target properties:
.. code-block:: cmake
ExternalProject_Get_Property(<name> <prop1> [<prop2>...])
@@ -655,7 +661,9 @@ control needed to implement such step-level capabilities.
The ``ExternalProject_Add_Step()`` function specifies an additional custom
step for an external project defined by an earlier call to
:command:`ExternalProject_Add`::
:command:`ExternalProject_Add`:
.. code-block:: cmake
ExternalProject_Add_Step(<name> <step> [<option>...])
@@ -722,7 +730,9 @@ control needed to implement such step-level capabilities.
The ``ExternalProject_Add_StepTargets()`` function generates targets for the
steps listed. The name of each created target will be of the form
``<name>-<step>``::
``<name>-<step>``:
.. code-block:: cmake
ExternalProject_Add_StepTargets(<name> [NO_DEPENDS] <step1> [<step2>...])
@@ -773,7 +783,9 @@ control needed to implement such step-level capabilities.
The ``ExternalProject_Add_StepDependencies()`` function can be used to add
dependencies to a step. The dependencies added must be targets CMake already
knows about (these can be ordinary executable or library targets, custom
targets or even step targets of another external project)::
targets or even step targets of another external project):
.. code-block:: cmake
ExternalProject_Add_StepDependencies(<name> <step> <target1> [<target2>...])

87
Modules/FindPkgConfig.cmake
View File

@@ -9,12 +9,14 @@ A ``pkg-config`` module for CMake.
Finds the ``pkg-config`` executable and adds the :command:`pkg_get_variable`,
:command:`pkg_check_modules` and :command:`pkg_search_module` commands. The
following variables will also be set::
following variables will also be set:
PKG_CONFIG_FOUND ... if pkg-config executable was found
PKG_CONFIG_EXECUTABLE ... pathname of the pkg-config program
PKG_CONFIG_VERSION_STRING ... the version of the pkg-config program found
(since CMake 2.8.8)
``PKG_CONFIG_FOUND``
if pkg-config executable was found
``PKG_CONFIG_EXECUTABLE``
pathname of the pkg-config program
``PKG_CONFIG_VERSION_STRING``
version of pkg-config (since CMake 2.8.8)
#]========================================]
@@ -86,7 +88,9 @@ endmacro()
.. command:: pkg_get_variable
Retrieves the value of a pkg-config variable ``varName`` and stores it in the
result variable ``resultVar`` in the calling scope. ::
result variable ``resultVar`` in the calling scope.
.. code-block:: cmake
pkg_get_variable(<resultVar> <moduleName> <varName>)
@@ -512,7 +516,9 @@ endmacro()
.. command:: pkg_check_modules
Checks for all the given modules, setting a variety of result variables in
the calling scope. ::
the calling scope.
.. code-block:: cmake
pkg_check_modules(<prefix>
[REQUIRED] [QUIET]
@@ -543,27 +549,36 @@ endmacro()
Each ``<moduleSpec>`` can be either a bare module name or it can be a
module name with a version constraint (operators ``=``, ``<``, ``>``,
``<=`` and ``>=`` are supported). The following are examples for a module
named ``foo`` with various constraints::
named ``foo`` with various constraints:
foo # Any version matches
foo<2 # Only match versions before 2
foo>=3.1 # Match any version from 3.1 or later
foo=1.2.3 # Foo must be exactly version 1.2.3
- ``foo`` matches any version.
- ``foo<2`` only matches versions before 2.
- ``foo>=3.1`` matches any version from 3.1 or later.
- ``foo=1.2.3`` requires that foo must be exactly version 1.2.3.
The following variables may be set upon return. Two sets of values exist,
one for the common case (``<XXX> = <prefix>``) and another for the
information ``pkg-config`` provides when it is called with the ``--static``
option (``<XXX> = <prefix>_STATIC``)::
The following variables may be set upon return. Two sets of values exist:
One for the common case (``<XXX> = <prefix>``) and another for the
information ``pkg-config`` provides when called with the ``--static``
option (``<XXX> = <prefix>_STATIC``).
<XXX>_FOUND ... set to 1 if module(s) exist
<XXX>_LIBRARIES ... only the libraries (without the '-l')
<XXX>_LINK_LIBRARIES ... the libraries and their absolute paths
<XXX>_LIBRARY_DIRS ... the paths of the libraries (without the '-L')
<XXX>_LDFLAGS ... all required linker flags
<XXX>_LDFLAGS_OTHER ... all other linker flags
<XXX>_INCLUDE_DIRS ... the '-I' preprocessor flags (without the '-I')
<XXX>_CFLAGS ... all required cflags
<XXX>_CFLAGS_OTHER ... the other compiler flags
``<XXX>_FOUND``
set to 1 if module(s) exist
``<XXX>_LIBRARIES``
only the libraries (without the '-l')
``<XXX>_LINK_LIBRARIES``
the libraries and their absolute paths
``<XXX>_LIBRARY_DIRS``
the paths of the libraries (without the '-L')
``<XXX>_LDFLAGS``
all required linker flags
``<XXX>_LDFLAGS_OTHER``
all other linker flags
``<XXX>_INCLUDE_DIRS``
the '-I' preprocessor flags (without the '-I')
``<XXX>_CFLAGS``
all required cflags
``<XXX>_CFLAGS_OTHER``
the other compiler flags
All but ``<XXX>_FOUND`` may be a :ref:`;-list <CMake Language Lists>` if the
associated variable returned from ``pkg-config`` has multiple values.
@@ -571,14 +586,18 @@ endmacro()
There are some special variables whose prefix depends on the number of
``<moduleSpec>`` given. When there is only one ``<moduleSpec>``,
``<YYY>`` will simply be ``<prefix>``, but if two or more ``<moduleSpec>``
items are given, ``<YYY>`` will be ``<prefix>_<moduleName>``::
items are given, ``<YYY>`` will be ``<prefix>_<moduleName>``.
<YYY>_VERSION ... version of the module
<YYY>_PREFIX ... prefix directory of the module
<YYY>_INCLUDEDIR ... include directory of the module
<YYY>_LIBDIR ... lib directory of the module
``<YYY>_VERSION``
version of the module
``<YYY>_PREFIX``
prefix directory of the module
``<YYY>_INCLUDEDIR``
include directory of the module
``<YYY>_LIBDIR``
lib directory of the module
Examples
Examples:
.. code-block:: cmake
@@ -638,7 +657,9 @@ endmacro()
The behavior of this command is the same as :command:`pkg_check_modules`,
except that rather than checking for all the specified modules, it searches
for just the first successful match. ::
for just the first successful match.
.. code-block:: cmake
pkg_search_module(<prefix>
[REQUIRED] [QUIET]
@@ -647,7 +668,7 @@ endmacro()
[IMPORTED_TARGET [GLOBAL]]
<moduleSpec> [<moduleSpec>...])
Examples
Example:
.. code-block:: cmake

53
Utilities/Sphinx/cmake.py
View File

@@ -4,14 +4,55 @@
import os
import re
# Monkey patch for pygments reporting an error when generator expressions are
# used.
# https://bitbucket.org/birkenfeld/pygments-main/issue/942/cmake-generator-expressions-not-handled
# Override much of pygments' CMakeLexer.
# We need to parse CMake syntax definitions, not CMake code.
# For hard test cases that use much of the syntax below, see
# - module/FindPkgConfig.html (with "glib-2.0>=2.10 gtk+-2.0" and similar)
# - module/ExternalProject.html (with http:// https:// git@; also has command options -E --build)
# - manual/cmake-buildsystem.7.html (with nested $<..>; relative and absolute paths, "::")
from pygments.lexers import CMakeLexer
from pygments.token import Name, Operator
from pygments.token import Name, Operator, Punctuation, String, Text, Comment, Generic, Whitespace, Number
from pygments.lexer import bygroups
CMakeLexer.tokens["args"].append(('(\\$<)(.+?)(>)',
bygroups(Operator, Name.Variable, Operator)))
# Notes on regular expressions below:
# - [\.\+-] are needed for string constants like gtk+-2.0
# - Unix paths are recognized by '/'; support for Windows paths may be added if needed
# - (\\.) allows for \-escapes (used in manual/cmake-language.7)
# - $<..$<..$>..> nested occurence in cmake-buildsystem
CMakeLexer.tokens["root"] = [
(r'\b(\w+)([ \t]*)(\()', bygroups(Name.Function, Text, Name.Function), '#push'), # fctn(
(r'\(', Name.Function, '#push'),
(r'\)', Name.Function, '#pop'),
(r'\[', Punctuation, '#push'),
(r'\]', Punctuation, '#pop'),
(r'[|;,.=*\-]', Punctuation),
(r'\\\\', Punctuation), # used in commands/source_group
(r'[:]', Operator),
(r'[<>]=', Punctuation), # used in FindPkgConfig.cmake
(r'\$<', Operator, '#push'), # $<...>
(r'<[^<|]+?>(\w*\.\.\.)?', Name.Variable), # <expr>
(r'(\$\w*\{)(.+?)(\})', bygroups(Operator, Name.Tag, Operator)), # ${..} $ENV{..}
(r'([A-Z]+\{)(.+?)(\})', bygroups(Operator, Name.Tag, Operator)), # DATA{ ...}
(r'[a-z]+(@|(://))((\\.)|[\w.+-:/\\])+', Name.Attribute), # URL, git@, ...
(r'/\w[\w\.\+-/\\]*', Name.Attribute), # absolute path
(r'/', Name.Attribute),
(r'\w[\w\.\+-]*/[\w.+-/\\]*', Name.Attribute), # relative path
(r'[A-Z]((\\.)|[\w.+-])*[a-z]((\\.)|[\w.+-])*', Name.Builtin), # initial A-Z, contains a-z
(r'@?[A-Z][A-Z0-9_]*', Name.Constant),
(r'[a-z_]((\\;)|(\\ )|[\w.+-])*', Name.Builtin),
(r'[0-9][0-9\.]*', Number),
(r'(?s)"(\\"|[^"])*"', String), # "string"
(r'\.\.\.', Name.Variable),
(r'<', Operator, '#push'), # <..|..> is different from <expr>
(r'>', Operator, '#pop'),
(r'\n', Whitespace),
(r'[ \t]+', Whitespace),
(r'#.*\n', Comment),
# (r'[^<>\])\}\|$"# \t\n]+', Name.Exception), # fallback, for debugging only
]
# Monkey patch for sphinx generating invalid content for qcollectiongenerator
# https://bitbucket.org/birkenfeld/sphinx/issue/1435/qthelp-builder-should-htmlescape-keywords

29
Utilities/Sphinx/colors.py Normal file
View File

@@ -0,0 +1,29 @@
# -*- coding: utf-8 -*-
from pygments.style import Style
from pygments.token import Name, Comment, String, Number, Operator, Whitespace
class CMakeTemplateStyle(Style):
"""
for more token names, see pygments/styles.default
"""
background_color = "#f8f8f8"
default_style = ""
styles = {
Whitespace: "#bbbbbb",
Comment: "italic #408080",
Operator: "bold #000000",
String: "#217A21",
Number: "#105030",
Name.Builtin: "#400080", # anything lowercase
Name.Function: "bold #1010A0", # function
Name.Variable: "#1080B0", # <..>
Name.Tag: "#19177C", # ${..}
Name.Constant: "#6020E0", # uppercase only
Name.Entity: "italic #70A020", # @..@
Name.Attribute: "#906060", # paths, URLs
Name.Label: "#A0A000", # anything left over
Name.Exception: "bold #FF0000", # for debugging only
}

1
Utilities/Sphinx/conf.py.in
View File

@@ -15,6 +15,7 @@ project = 'CMake'
copyright = '@conf_copyright@'
version = '@conf_version@' # feature version
release = '@conf_release@' # full version string
pygments_style = 'colors.CMakeTemplateStyle'
primary_domain = 'cmake'
highlight_language = 'none'