Commit 3bb707f0 authored by James Johnston's avatar James Johnston Committed by Brad King
Browse files

Help: Improve formatting of variable documentation

Improve formatting, primarily by:

* Adding links to relevant commands, properties, generators, and so on.
* Converting code, symbols, paths, and so on to fixed-width fonts.
* Hard wrapping lines to 80 characters or less.
parent 404d16e7
......@@ -27,6 +27,8 @@ in each directory of a source tree with the name CMakeLists.txt.
Users build a project by using CMake to generate a build system for a
native tool on their platform.
.. _`CMake Options`:
Options
=======
......
APPLE
-----
True if running on Mac OS X.
``True`` if running on Mac OS X.
Set to true on Mac OS X.
Set to ``true`` on Mac OS X.
BORLAND
-------
True if the Borland compiler is being used.
``True`` if the Borland compiler is being used.
This is set to true if the Borland compiler is being used.
This is set to ``true`` if the Borland compiler is being used.
BUILD_SHARED_LIBS
-----------------
Global flag to cause add_library to create shared libraries if on.
Global flag to cause :command:`add_library` to create shared libraries if on.
If present and true, this will cause all libraries to be built shared
unless the library was explicitly added as a static library. This
variable is often added to projects as an OPTION so that each user of
a project can decide if they want to build the project using shared or
variable is often added to projects as an :command:`option` so that each user
of a project can decide if they want to build the project using shared or
static libraries.
CMAKE_ABSOLUTE_DESTINATION_FILES
--------------------------------
List of files which have been installed using an ABSOLUTE DESTINATION path.
List of files which have been installed using an ``ABSOLUTE DESTINATION`` path.
This variable is defined by CMake-generated cmake_install.cmake
This variable is defined by CMake-generated ``cmake_install.cmake``
scripts. It can be used (read-only) by programs or scripts that
source those install scripts. This is used by some CPack generators
(e.g. RPM).
CMAKE_ANDROID_NATIVE_LIB_DEPENDENCIES
-------------------------------------
Default value for the :prop_tgt:`ANDROID_NATIVE_LIB_DEPENDENCIES` target property.
See that target property for additional information.
Default value for the :prop_tgt:`ANDROID_NATIVE_LIB_DEPENDENCIES` target
property. See that target property for additional information.
CMAKE_ANDROID_NATIVE_LIB_DIRECTORIES
------------------------------------
Default value for the :prop_tgt:`ANDROID_NATIVE_LIB_DIRECTORIES` target property.
See that target property for additional information.
Default value for the :prop_tgt:`ANDROID_NATIVE_LIB_DIRECTORIES` target
property. See that target property for additional information.
......@@ -3,5 +3,6 @@ CMAKE_ARGC
Number of command line arguments passed to CMake in script mode.
When run in -P script mode, CMake sets this variable to the number of
command line arguments. See also CMAKE_ARGV0, 1, 2 ...
When run in :ref:`-P <CMake Options>` script mode, CMake sets this variable to
the number of command line arguments. See also :variable:`CMAKE_ARGV0`,
``1``, ``2`` ...
......@@ -3,7 +3,7 @@ CMAKE_ARGV0
Command line argument passed to CMake in script mode.
When run in -P script mode, CMake sets this variable to the first
command line argument. It then also sets CMAKE_ARGV1, CMAKE_ARGV2,
... and so on, up to the number of command line arguments given. See
also CMAKE_ARGC.
When run in :ref:`-P <CMake Options>` script mode, CMake sets this variable to
the first command line argument. It then also sets ``CMAKE_ARGV1``,
``CMAKE_ARGV2``, ... and so on, up to the number of command line arguments
given. See also :variable:`CMAKE_ARGC`.
......@@ -3,11 +3,11 @@ CMAKE_AUTOMOC_RELAXED_MODE
Switch between strict and relaxed automoc mode.
By default, :prop_tgt:`AUTOMOC` behaves exactly as described in the documentation
of the :prop_tgt:`AUTOMOC` target property. When set to ``TRUE``, it accepts more
input and tries to find the correct input file for ``moc`` even if it
differs from the documented behaviour. In this mode it e.g. also
checks whether a header file is intended to be processed by moc when a
``"foo.moc"`` file has been included.
By default, :prop_tgt:`AUTOMOC` behaves exactly as described in the
documentation of the :prop_tgt:`AUTOMOC` target property. When set to
``TRUE``, it accepts more input and tries to find the correct input file for
``moc`` even if it differs from the documented behaviour. In this mode it
e.g. also checks whether a header file is intended to be processed by moc
when a ``"foo.moc"`` file has been included.
Relaxed mode has to be enabled for KDE4 compatibility.
......@@ -3,5 +3,5 @@ CMAKE_AUTORCC
Whether to handle ``rcc`` automatically for Qt targets.
This variable is used to initialize the :prop_tgt:`AUTORCC` property on all the targets.
See that target property for additional information.
This variable is used to initialize the :prop_tgt:`AUTORCC` property on all
the targets. See that target property for additional information.
......@@ -3,5 +3,5 @@ CMAKE_AUTOUIC
Whether to handle ``uic`` automatically for Qt targets.
This variable is used to initialize the :prop_tgt:`AUTOUIC` property on all the targets.
See that target property for additional information.
This variable is used to initialize the :prop_tgt:`AUTOUIC` property on all
the targets. See that target property for additional information.
......@@ -5,4 +5,4 @@ The path to the top level of the build tree.
This is the full path to the top level of the current CMake build
tree. For an in-source build, this would be the same as
CMAKE_SOURCE_DIR.
:variable:`CMAKE_SOURCE_DIR`.
......@@ -4,16 +4,17 @@ CMAKE_BUILD_TYPE
Specifies the build type on single-configuration generators.
This statically specifies what build type (configuration) will be
built in this build tree. Possible values are empty, Debug, Release,
RelWithDebInfo and MinSizeRel. This variable is only meaningful to
single-configuration generators (such as make and Ninja) i.e. those
which choose a single configuration when CMake runs to generate a
build tree as opposed to multi-configuration generators which offer
selection of the build configuration within the generated build
built in this build tree. Possible values are empty, ``Debug``, ``Release``,
``RelWithDebInfo`` and ``MinSizeRel``. This variable is only meaningful to
single-configuration generators (such as :ref:`Makefile Generators` and
:generator:`Ninja`) i.e. those which choose a single configuration when CMake
runs to generate a build tree as opposed to multi-configuration generators
which offer selection of the build configuration within the generated build
environment. There are many per-config properties and variables
(usually following clean SOME_VAR_<CONFIG> order conventions), such as
CMAKE_C_FLAGS_<CONFIG>, specified as uppercase:
CMAKE_C_FLAGS_[DEBUG|RELEASE|RELWITHDEBINFO|MINSIZEREL]. For example,
in a build tree configured to build type Debug, CMake will see to
having CMAKE_C_FLAGS_DEBUG settings get added to the CMAKE_C_FLAGS
settings. See also CMAKE_CONFIGURATION_TYPES.
(usually following clean ``SOME_VAR_<CONFIG>`` order conventions), such as
``CMAKE_C_FLAGS_<CONFIG>``, specified as uppercase:
``CMAKE_C_FLAGS_[DEBUG|RELEASE|RELWITHDEBINFO|MINSIZEREL]``. For example,
in a build tree configured to build type ``Debug``, CMake will see to
having :variable:`CMAKE_C_FLAGS_DEBUG <CMAKE_<LANG>_FLAGS_DEBUG>` settings get
added to the :variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>` settings. See
also :variable:`CMAKE_CONFIGURATION_TYPES`.
CMAKE_BUILD_WITH_INSTALL_RPATH
------------------------------
Use the install path for the RPATH
Use the install path for the ``RPATH``.
Normally CMake uses the build tree for the RPATH when building
executables etc on systems that use RPATH. When the software is
Normally CMake uses the build tree for the ``RPATH`` when building
executables etc on systems that use ``RPATH``. When the software is
installed the executables etc are relinked by CMake to have the
install RPATH. If this variable is set to true then the software is
always built with the install path for the RPATH and does not need to
install ``RPATH``. If this variable is set to true then the software is
always built with the install path for the ``RPATH`` and does not need to
be relinked when installed.
CMAKE_CACHEFILE_DIR
-------------------
The directory with the CMakeCache.txt file.
The directory with the ``CMakeCache.txt`` file.
This is the full path to the directory that has the CMakeCache.txt
file in it. This is the same as CMAKE_BINARY_DIR.
This is the full path to the directory that has the ``CMakeCache.txt``
file in it. This is the same as :variable:`CMAKE_BINARY_DIR`.
CMAKE_CACHE_MAJOR_VERSION
-------------------------
Major version of CMake used to create the CMakeCache.txt file
Major version of CMake used to create the ``CMakeCache.txt`` file
This stores the major version of CMake used to write a CMake cache
file. It is only different when a different version of CMake is run
......
CMAKE_CACHE_MINOR_VERSION
-------------------------
Minor version of CMake used to create the CMakeCache.txt file
Minor version of CMake used to create the ``CMakeCache.txt`` file
This stores the minor version of CMake used to write a CMake cache
file. It is only different when a different version of CMake is run
......
CMAKE_CACHE_PATCH_VERSION
-------------------------
Patch version of CMake used to create the CMakeCache.txt file
Patch version of CMake used to create the ``CMakeCache.txt`` file
This stores the patch version of CMake used to write a CMake cache
file. It is only different when a different version of CMake is run
......
......@@ -4,11 +4,11 @@ CMAKE_CFG_INTDIR
Build-time reference to per-configuration output subdirectory.
For native build systems supporting multiple configurations in the
build tree (such as Visual Studio and Xcode), the value is a reference
to a build-time variable specifying the name of the per-configuration
output subdirectory. On Makefile generators this evaluates to "."
because there is only one configuration in a build tree. Example
values:
build tree (such as :ref:`Visual Studio Generators` and :generator:`Xcode`),
the value is a reference to a build-time variable specifying the name
of the per-configuration output subdirectory. On :ref:`Makefile Generators`
this evaluates to `.` because there is only one configuration in a build tree.
Example values:
::
......@@ -33,13 +33,14 @@ evaluated at build time. Example of intended usage:
)
add_custom_target(drive ALL DEPENDS out.txt)
Note that CMAKE_CFG_INTDIR is no longer necessary for this purpose but
Note that ``CMAKE_CFG_INTDIR`` is no longer necessary for this purpose but
has been left for compatibility with existing projects. Instead
add_custom_command() recognizes executable target names in its COMMAND
option, so "${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_CFG_INTDIR}/mytool"
can be replaced by just "mytool".
:command:`add_custom_command` recognizes executable target names in its
``COMMAND`` option, so
``${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_CFG_INTDIR}/mytool`` can be replaced
by just ``mytool``.
This variable is read-only. Setting it is undefined behavior. In
multi-configuration build systems the value of this variable is passed
as the value of preprocessor symbol "CMAKE_INTDIR" to the compilation
as the value of preprocessor symbol ``CMAKE_INTDIR`` to the compilation
of all source files.
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