diff options
Diffstat (limited to 'Help/manual')
| -rw-r--r-- | Help/manual/cmake-commands.7.rst | 5 | ||||
| -rw-r--r-- | Help/manual/cmake-developer.7.rst | 3 | ||||
| -rw-r--r-- | Help/manual/cmake-env-variables.7.rst | 8 | ||||
| -rw-r--r-- | Help/manual/cmake-generator-expressions.7.rst | 409 | ||||
| -rw-r--r-- | Help/manual/cmake-language.7.rst | 81 | ||||
| -rw-r--r-- | Help/manual/cmake-modules.7.rst | 105 | ||||
| -rw-r--r-- | Help/manual/cmake-policies.7.rst | 8 | ||||
| -rw-r--r-- | Help/manual/cmake-properties.7.rst | 2 | ||||
| -rw-r--r-- | Help/manual/cmake-qt.7.rst | 38 | ||||
| -rw-r--r-- | Help/manual/cmake-variables.7.rst | 21 |
10 files changed, 457 insertions, 223 deletions
diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst index 0cc5fca..aec9ba5 100644 --- a/Help/manual/cmake-commands.7.rst +++ b/Help/manual/cmake-commands.7.rst @@ -145,8 +145,9 @@ These commands are available only in CTest scripts. Deprecated Commands =================== -These commands are available only for compatibility with older -versions of CMake. Do not use them in new code. +These commands are deprecated since CMake version 3.0. +They are available only for backward compatibility. +Do not use them in new code. .. toctree:: :maxdepth: 1 diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index f05c4b1..c3bbf28 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -13,6 +13,9 @@ Introduction This manual is intended for reference by developers modifying the CMake source tree itself, and by those authoring externally-maintained modules. +See https://cmake.org/get-involved/ to get involved in development of +CMake upstream. + Adding Compile Features ======================= diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index 31aa723..edf80f4 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -7,6 +7,14 @@ cmake-env-variables(7) .. contents:: +This page lists environment variables that have special +meaning to CMake. + +For general information on environment variables, see the +:ref:`Environment Variables <CMake Language Environment Variables>` +section in the cmake-language manual. + + Environment Variables that Control the Build ============================================ diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 76fd3d9..63e43e1 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -20,61 +20,74 @@ commands to populate those properties, such as :command:`target_link_libraries`, :command:`target_include_directories`, :command:`target_compile_definitions` and others. -This means that they enable conditional linking, conditional -definitions used when compiling, and conditional include directories and -more. The conditions may be based on the build configuration, target -properties, platform information or any other queryable information. +They enable conditional linking, conditional definitions used when compiling, +conditional include directories, and more. The conditions may be based on +the build configuration, target properties, platform information or any other +queryable information. -Logical Expressions -=================== +Generator expressions have the form ``$<...>``. To avoid confusion, this page +deviates from most of the CMake documentation in that it omits angular brackets +``<...>`` around placeholders like ``condition``, ``string``, ``target``, +among others. -Logical expressions are used to create conditional output. The basic -expressions are the ``0`` and ``1`` expressions. Because other logical -expressions evaluate to either ``0`` or ``1``, they can be composed to -create conditional output:: +Generator expressions can be nested, as shown in most of the examples below. - $<$<CONFIG:Debug>:DEBUG_MODE> +.. _`Boolean Generator Expressions`: -expands to ``DEBUG_MODE`` when the ``Debug`` configuration is used, and -otherwise expands to nothing. - -Available logical expressions are: - -``$<BOOL:...>`` - ``1`` if the ``...`` is true, else ``0`` -``$<AND:?[,?]...>`` - ``1`` if all ``?`` are ``1``, else ``0`` - - The ``?`` must always be either ``0`` or ``1`` in boolean expressions. - -``$<OR:?[,?]...>`` - ``0`` if all ``?`` are ``0``, else ``1`` -``$<NOT:?>`` - ``0`` if ``?`` is ``1``, else ``1`` -``$<IF:?,true-value...,false-value...>`` - ``true-value...`` if ``?`` is ``1``, ``false-value...`` if ``?`` is ``0`` -``$<STREQUAL:a,b>`` - ``1`` if ``a`` is STREQUAL ``b``, else ``0`` -``$<EQUAL:a,b>`` - ``1`` if ``a`` is EQUAL ``b`` in a numeric comparison, else ``0`` -``$<IN_LIST:a,b>`` - ``1`` if ``a`` is IN_LIST ``b``, else ``0`` -``$<TARGET_EXISTS:tgt>`` - ``1`` if ``tgt`` is an existed target name, else ``0``. -``$<CONFIG:cfg>`` - ``1`` if config is ``cfg``, else ``0``. This is a case-insensitive comparison. - The mapping in :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is also considered by - this expression when it is evaluated on a property on an :prop_tgt:`IMPORTED` - target. -``$<PLATFORM_ID:comp>`` - ``1`` if the CMake-id of the platform matches ``comp``, otherwise ``0``. - See also the :variable:`CMAKE_SYSTEM_NAME` variable. -``$<C_COMPILER_ID:comp>`` - ``1`` if the CMake-id of the C compiler matches ``comp``, otherwise ``0``. - See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. -``$<CXX_COMPILER_ID:comp>`` - ``1`` if the CMake-id of the CXX compiler matches ``comp``, otherwise ``0``. - See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +Boolean Generator Expressions +============================= + +Boolean expressions evaluate to either ``0`` or ``1``. +They are typically used to construct the condition in a :ref:`conditional +generator expression<Conditional Generator Expressions>`. + +Available boolean expressions are: + +Logical Operators +----------------- + +``$<BOOL:string>`` + Converts ``string`` to ``0`` or ``1`` according to the rules of the + :command:`if()` command. Evaluates to ``0`` if any of the following is true: + + * ``string`` is empty, + * ``string`` is a case-insensitive equal of + ``0``, ``FALSE``, ``OFF``, ``N``, ``NO``, ``IGNORE``, or ``NOTFOUND``, or + * ``string`` ends in the suffix ``-NOTFOUND`` (case-sensitive). + + Otherwise evaluates to ``1``. + +``$<AND:conditions>`` + where ``conditions`` is a comma-separated list of boolean expressions. + Evaluates to ``1`` if all conditions are ``1``. + Otherwise evaluates to ``0``. + +``$<OR:conditions>`` + where ``conditions`` is a comma-separated list of boolean expressions. + Evaluates to ``1`` if at least one of the conditions is ``1``. + Otherwise evaluates to ``0``. + +``$<NOT:condition>`` + ``0`` if ``condition`` is ``1``, else ``1``. + +String Comparisons +------------------ + +``$<STREQUAL:string1,string2>`` + ``1`` if ``string1`` and ``string2`` are equal, else ``0``. + The comparison is case-sensitive. For a case-insensitive comparison, + combine with a :ref:`string transforming generator expression + <String Transforming Generator Expressions>`, + + .. code-block:: cmake + + $<STREQUAL:$<UPPER_CASE:${foo}>,"BAR"> # "1" if ${foo} is any of "BAR", "Bar", "bar", ... + +``$<EQUAL:value1,value2>`` + ``1`` if ``value1`` and ``value2`` are numerically equal, else ``0``. +``$<IN_LIST:string,list>`` + ``1`` if ``string`` is member of the comma-separated ``list``, else ``0``. + Uses case-sensitive comparisons. ``$<VERSION_LESS:v1,v2>`` ``1`` if ``v1`` is a version less than ``v2``, else ``0``. ``$<VERSION_GREATER:v1,v2>`` @@ -85,27 +98,55 @@ Available logical expressions are: ``1`` if ``v1`` is a version less than or equal to ``v2``, else ``0``. ``$<VERSION_GREATER_EQUAL:v1,v2>`` ``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``. -``$<C_COMPILER_VERSION:ver>`` - ``1`` if the version of the C compiler matches ``ver``, otherwise ``0``. + + +Variable Queries +---------------- + +``$<TARGET_EXISTS:target>`` + ``1`` if ``target`` exists, else ``0``. +``$<CONFIG:cfg>`` + ``1`` if config is ``cfg``, else ``0``. This is a case-insensitive comparison. + The mapping in :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is also considered by + this expression when it is evaluated on a property on an :prop_tgt:`IMPORTED` + target. +``$<PLATFORM_ID:platform_id>`` + ``1`` if the CMake-id of the platform matches ``platform_id`` + otherwise ``0``. + See also the :variable:`CMAKE_SYSTEM_NAME` variable. +``$<C_COMPILER_ID:compiler_id>`` + ``1`` if the CMake-id of the C compiler matches ``compiler_id``, + otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<CXX_COMPILER_ID:compiler_id>`` + ``1`` if the CMake-id of the CXX compiler matches ``compiler_id``, + otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<C_COMPILER_VERSION:version>`` + ``1`` if the version of the C compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. -``$<CXX_COMPILER_VERSION:ver>`` - ``1`` if the version of the CXX compiler matches ``ver``, otherwise ``0``. +``$<CXX_COMPILER_VERSION:version>`` + ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. -``$<TARGET_POLICY:pol>`` - ``1`` if the policy ``pol`` was NEW when the 'head' target was created, - else ``0``. If the policy was not set, the warning message for the policy +``$<TARGET_POLICY:policy>`` + ``1`` if the ``policy`` was NEW when the 'head' target was created, + else ``0``. If the ``policy`` was not set, the warning message for the policy will be emitted. This generator expression only works for a subset of policies. -``$<COMPILE_FEATURES:feature[,feature]...>`` - ``1`` if all of the ``feature`` features are available for the 'head' +``$<COMPILE_FEATURES:features>`` + where ``features`` is a comma-spearated list. + Evaluates to ``1`` if all of the ``features`` are available for the 'head' target, and ``0`` otherwise. If this expression is used while evaluating the link implementation of a target and if any dependency transitively increases the required :prop_tgt:`C_STANDARD` or :prop_tgt:`CXX_STANDARD` for the 'head' target, an error is reported. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. -``$<COMPILE_LANGUAGE:lang>`` - ``1`` when the language used for compilation unit matches ``lang``, + +.. _`Boolean COMPILE_LANGUAGE Generator Expression`: + +``$<COMPILE_LANGUAGE:language>`` + ``1`` when the language used for compilation unit matches ``language``, otherwise ``0``. This expression may be used to specify compile options, compile definitions, and include directories for source files of a particular language in a target. For example: @@ -147,18 +188,24 @@ Available logical expressions are: add_executable(myapp main.cpp) target_link_libraries(myapp myapp_c myapp_cxx) -Informational Expressions -========================= +String-Valued Generator Expressions +=================================== + +These expressions expand to some string. +For example, -These expressions expand to some information. The information may be used -directly, eg:: +.. code-block:: cmake include_directories(/usr/include/$<CXX_COMPILER_ID>/) expands to ``/usr/include/GNU/`` or ``/usr/include/Clang/`` etc, depending on -the Id of the compiler. +the compiler identifier. + +String-valued expressions may also be combined with other expressions. +Here an example for a string-valued expression within a boolean expressions +within a conditional expression: -These expressions may also may be combined with logical expressions:: +.. code-block:: cmake $<$<VERSION_LESS:$<CXX_COMPILER_VERSION>,4.2.0>:OLD_COMPILER> @@ -166,12 +213,123 @@ expands to ``OLD_COMPILER`` if the :variable:`CMAKE_CXX_COMPILER_VERSION <CMAKE_<LANG>_COMPILER_VERSION>` is less than 4.2.0. -Available informational expressions are: +And here two nested string-valued expressions: + +.. code-block:: cmake + + -I$<JOIN:$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>, -I> + +generates a string of the entries in the :prop_tgt:`INCLUDE_DIRECTORIES` target +property with each entry preceded by ``-I``. + +Expanding on the previous example, if one first wants to check if the +``INCLUDE_DIRECTORIES`` property is non-empty, then it is advisable to +introduce a helper variable to keep the code readable: + +.. code-block:: cmake + + set(prop "$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>") # helper variable + $<$<BOOL:${prop}>:-I$<JOIN:${prop}, -I>> + +The following string-valued generator expressions are available: + +Escaped Characters +------------------ + +String literals to escape the special meaning a character would otherwise have: + +``$<ANGLE-R>`` + A literal ``>``. Used for example to compare strings that contain a ``>``. +``$<COMMA>`` + A literal ``,``. Used for example to compare strings which contain a ``,``. +``$<SEMICOLON>`` + A literal ``;``. Used to prevent list expansion on an argument with ``;``. + +.. _`Conditional Generator Expressions`: + +Conditional Expressions +----------------------- + +Conditional generator expressions depend on a boolean condition +that must be ``0`` or ``1``. + +``$<condition:true_string>`` + Evaluates to ``true_string`` if ``condition`` is ``1``. + Otherwise evaluates to the empty string. + +``$<IF:condition,true_string,false_string>`` + Evaluates to ``true_string`` if ``condition`` is ``1``. + Otherwise evaluates to ``false_string``. + +Typically, the ``condition`` is a :ref:`boolean generator expression +<Boolean Generator Expressions>`. For instance, + +.. code-block:: cmake + + $<$<CONFIG:Debug>:DEBUG_MODE> + +expands to ``DEBUG_MODE`` when the ``Debug`` configuration is used, and +otherwise expands to the empty string. + +.. _`String Transforming Generator Expressions`: + +String Transformations +---------------------- + +``$<JOIN:list,string>`` + Joins the list with the content of ``string``. +``$<LOWER_CASE:string>`` + Content of ``string`` converted to lower case. +``$<UPPER_CASE:string>`` + Content of ``string`` converted to upper case. + +``$<GENEX_EVAL:expr>`` + Content of ``expr`` evaluated as a generator expression in the current + context. This enables consumption of generator expressions whose + evaluation results itself in generator expressions. +``$<TARGET_GENEX_EVAL:tgt,expr>`` + Content of ``expr`` evaluated as a generator expression in the context of + ``tgt`` target. This enables consumption of custom target properties that + themselves contain generator expressions. + + Having the capability to evaluate generator expressions is very useful when + you want to manage custom properties supporting generator expressions. + For example: + + .. code-block:: cmake + + add_library(foo ...) + + set_property(TARGET foo PROPERTY + CUSTOM_KEYS $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS> + ) + + add_custom_target(printFooKeys + COMMAND ${CMAKE_COMMAND} -E echo $<TARGET_PROPERTY:foo,CUSTOM_KEYS> + ) + + This naive implementation of the ``printFooKeys`` custom command is wrong + because ``CUSTOM_KEYS`` target property is not evaluated and the content + is passed as is (i.e. ``$<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>``). + + To have the expected result (i.e. ``FOO_EXTRA_THINGS`` if config is + ``Debug``), it is required to evaluate the output of + ``$<TARGET_PROPERTY:foo,CUSTOM_KEYS>``: + + .. code-block:: cmake + + add_custom_target(printFooKeys + COMMAND ${CMAKE_COMMAND} -E + echo $<TARGET_GENEX_EVAL:foo,$<TARGET_PROPERTY:foo,CUSTOM_KEYS>> + ) + +Variable Queries +---------------- -``$<CONFIGURATION>`` - Configuration name. Deprecated. Use ``CONFIG`` instead. ``$<CONFIG>`` - Configuration name + Configuration name. +``$<CONFIGURATION>`` + Configuration name. Deprecated since CMake 3.0. Use ``CONFIG`` instead. ``$<PLATFORM_ID>`` The CMake-id of the platform. See also the :variable:`CMAKE_SYSTEM_NAME` variable. @@ -187,6 +345,19 @@ Available informational expressions are: ``$<CXX_COMPILER_VERSION>`` The version of the CXX compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<COMPILE_LANGUAGE>`` + The compile language of source files when evaluating compile options. + See :ref:`the related boolean expression + <Boolean COMPILE_LANGUAGE Generator Expression>` + ``$<COMPILE_LANGUAGE:language>`` + for notes about the portability of this generator expression. + +Target-Dependent Queries +------------------------ + +``$<TARGET_NAME_IF_EXISTS:tgt>`` + Expands to the ``tgt`` if the given target exists, an empty string + otherwise. ``$<TARGET_FILE:tgt>`` Full path to main file (.exe, .so.1.2, .a) where ``tgt`` is the name of a target. ``$<TARGET_FILE_NAME:tgt>`` @@ -232,56 +403,21 @@ Available informational expressions are: expression is evaluated on. ``$<TARGET_PROPERTY:prop>`` Value of the property ``prop`` on the target on which the generator - expression is evaluated. + expression is evaluated. Note that for generator expressions in + :ref:`Target Usage Requirements` this is the value of the property + on the consuming target rather than the target specifying the + requirement. ``$<INSTALL_PREFIX>`` Content of the install prefix when the target is exported via :command:`install(EXPORT)` and empty otherwise. -``$<COMPILE_LANGUAGE>`` - The compile language of source files when evaluating compile options. See - the unary version for notes about portability of this generator - expression. - -Output Expressions -================== - -These expressions generate output, in some cases depending on an input. These -expressions may be combined with other expressions for information or logical -comparison:: - -I$<JOIN:$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>, -I> - -generates a string of the entries in the :prop_tgt:`INCLUDE_DIRECTORIES` target -property with each entry preceded by ``-I``. Note that a more-complete use -in this situation would require first checking if the INCLUDE_DIRECTORIES -property is non-empty:: - - $<$<BOOL:${prop}>:-I$<JOIN:${prop}, -I>> +Output-Related Expressions +-------------------------- -where ``${prop}`` refers to a helper variable:: - - set(prop "$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>") - -Available output expressions are: - -``$<0:...>`` - Empty string (ignores ``...``) -``$<1:...>`` - Content of ``...`` -``$<JOIN:list,...>`` - Joins the list with the content of ``...`` -``$<ANGLE-R>`` - A literal ``>``. Used to compare strings which contain a ``>`` for example. -``$<COMMA>`` - A literal ``,``. Used to compare strings which contain a ``,`` for example. -``$<SEMICOLON>`` - A literal ``;``. Used to prevent list expansion on an argument with ``;``. ``$<TARGET_NAME:...>`` Marks ``...`` as being the name of a target. This is required if exporting targets to multiple dependent export sets. The ``...`` must be a literal name of a target- it may not contain generator expressions. -``$<TARGET_NAME_IF_EXISTS:...>`` - Expands to the ``...`` if the given target exists, an empty string - otherwise. ``$<LINK_ONLY:...>`` Content of ``...`` except when evaluated in a link interface while propagating :ref:`Target Usage Requirements`, in which case it is the @@ -296,10 +432,6 @@ Available output expressions are: Content of ``...`` when the property is exported using :command:`export`, or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise. -``$<LOWER_CASE:...>`` - Content of ``...`` converted to lower case. -``$<UPPER_CASE:...>`` - Content of ``...`` converted to upper case. ``$<MAKE_C_IDENTIFIER:...>`` Content of ``...`` converted to a C identifier. The conversion follows the same behavior as :command:`string(MAKE_C_IDENTIFIER)`. @@ -310,42 +442,25 @@ Available output expressions are: Content of ``...`` converted to shell path style. For example, slashes are converted to backslashes in Windows shells and drive letters are converted to posix paths in MSYS shells. The ``...`` must be an absolute path. -``$<GENEX_EVAL:...>`` - Content of ``...`` evaluated as a generator expression in the current - context. This enables consumption of generator expressions - whose evaluation results itself in generator expressions. -``$<TARGET_GENEX_EVAL:tgt,...>`` - Content of ``...`` evaluated as a generator expression in the context of - ``tgt`` target. This enables consumption of custom target properties that - themselves contain generator expressions. - Having the capability to evaluate generator expressions is very useful when - you want to manage custom properties supporting generator expressions. - For example: +Debugging +========= - .. code-block:: cmake +Since generator expressions are evaluated during generation of the buildsystem, +and not during processing of ``CMakeLists.txt`` files, it is not possible to +inspect their result with the :command:`message()` command. - add_library(foo ...) +One possible way to generate debug messages is to add a custom target, - set_property(TARGET foo PROPERTY - CUSTOM_KEYS $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS> - ) +.. code-block:: cmake - add_custom_target(printFooKeys - COMMAND ${CMAKE_COMMAND} -E echo $<TARGET_PROPERTY:foo,CUSTOM_KEYS> - ) + add_custom_target(genexdebug COMMAND ${CMAKE_COMMAND} -E echo "$<...>") - This naive implementation of the ``printFooKeys`` custom command is wrong - because ``CUSTOM_KEYS`` target property is not evaluated and the content - is passed as is (i.e. ``$<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>``). +The shell command ``make genexdebug`` (invoked after execution of ``cmake``) +would then print the result of ``$<...>``. - To have the expected result (i.e. ``FOO_EXTRA_THINGS`` if config is - ``Debug``), it is required to evaluate the output of - ``$<TARGET_PROPERTY:foo,CUSTOM_KEYS>``: +Another way is to write debug messages to a file: - .. code-block:: cmake +.. code-block:: cmake - add_custom_target(printFooKeys - COMMAND ${CMAKE_COMMAND} -E - echo $<TARGET_GENEX_EVAL:foo,$<TARGET_PROPERTY:foo,CUSTOM_KEYS>> - ) + file(GENERATE OUTPUT filename CONTENT "$<...>") diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index 71649ba..5e5cfff 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst @@ -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,16 +254,22 @@ closing quotes. Both `Escape Sequences`_ and `Variable References`_ are evaluated. A quoted argument is always given to the command invocation as exactly one argument. +.. No code-block syntax highlighting in the following example + (escape \" not supported by our cmake.py) + For example: -:: +.. code-block:: cmake - message("This is a quoted argument containing multiple lines. - This is always one argument even though it contains a ; character. - Both \\-escape sequences and ${variable} references are evaluated. - The text does not end on an escaped double-quote like \". - It does end in an unescaped double quote. - ") + message("This is a quoted argument containing multiple lines. + This is always one argument even though it contains a ; character. + Both \\-escape sequences and ${variable} references are evaluated. + The text does not end on an escaped double-quote like \". + 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 @@ -270,11 +277,11 @@ immediately following newline character. For example: .. code-block:: cmake - message("\ - This is the first line of a quoted argument. \ - In fact it is the only line but since it is long \ - the source code uses line continuation.\ - ") + message("\ + This is the first line of a quoted argument. \ + In fact it is the only line but since it is long \ + the source code uses line continuation.\ + ") .. note:: CMake versions prior to 3.0 do not support continuation with ``\``. @@ -382,7 +389,7 @@ historical considerations.) Variable References ------------------- -A *variable reference* has the form ``${variable_name}`` and is +A *variable reference* has the form ``${<variable>}`` and is evaluated inside a `Quoted Argument`_ or an `Unquoted Argument`_. A variable reference is replaced by the value of the variable, or by the empty string if the variable is not set. @@ -398,14 +405,18 @@ the ``$`` is also technically permitted but is discouraged. The `Variables`_ section documents the scope of variable names and how their values are set. -An *environment variable reference* has the form ``$ENV{VAR}`` and -is evaluated in the same contexts as a normal variable reference. -See :variable:`ENV` for more information. +An *environment variable reference* has the form ``$ENV{<variable>}``. +See the `Environment Variables`_ section for more information. -A *cache variable reference* has the form ``$CACHE{VAR}`` and -is evaluated in the same contexts as a normal variable reference. +A *cache variable reference* has the form ``$CACHE{<variable>}``. See :variable:`CACHE` for more information. +The :command:`if` command has a special condition syntax that +allows for variable references in the short form ``<variable>`` +instead of ``${<variable>}``. +However, environment and cache variables always need to be +referenced as ``$ENV{<variable>}`` or ``$CACHE{<variable>}``. + Comments -------- @@ -552,10 +563,38 @@ Otherwise, the variable reference evaluates to an empty string. The ``$CACHE{VAR}`` syntax can be used to do direct cache entry lookups. -The :manual:`cmake-variables(7)` manual documents many variables +The :manual:`cmake-variables(7)` manual documents the many variables that are provided by CMake or have meaning to CMake when set by project code. +.. _`CMake Language Environment Variables`: + +Environment Variables +===================== + +Environment Variables are like ordinary `Variables`_, with the +following differences: + +Scope + Environment variables have global scope in a CMake process. + They are never cached. + +References + `Variable References`_ have the form ``$ENV{<variable>}``. + +Initialization + Initial values of the CMake environment variables are those of + the calling process. + Values can be changed using the :command:`set` and :command:`unset` + commands. + These commands only affect the running CMake process, + not the system environment at large. + Changed values are not written back to the calling process, + and they are not seen by subsequent build or test processes. + +The :manual:`cmake-env-variables(7)` manual documents environment +variables that have special meaning to CMake. + .. _`CMake Language Lists`: Lists diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index b7276b6..95744df 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -3,12 +3,14 @@ cmake-modules(7) **************** -.. only:: html +The modules listed here are part of the CMake distribution. +Projects may provide further modules; their location(s) +can be specified in the :variable:`CMAKE_MODULE_PATH` variable. - .. contents:: +Utility Modules +^^^^^^^^^^^^^^^ -All Modules -=========== +These modules are loaded using the :command:`include` command. .. toctree:: :maxdepth: 1 @@ -41,12 +43,9 @@ All Modules /module/CMakeAddFortranSubdirectory /module/CMakeBackwardCompatibilityCXX /module/CMakeDependentOption - /module/CMakeDetermineVSServicePack - /module/CMakeExpandImportedTargets /module/CMakeFindDependencyMacro /module/CMakeFindFrameworks /module/CMakeFindPackageMode - /module/CMakeForceCompiler /module/CMakeGraphVizOptions /module/CMakePackageConfigHelpers /module/CMakeParseArguments @@ -70,6 +69,42 @@ All Modules /module/ExternalProject /module/FeatureSummary /module/FetchContent + /module/FindPackageHandleStandardArgs + /module/FindPackageMessage + /module/FortranCInterface + /module/GenerateExportHeader + /module/GetPrerequisites + /module/GNUInstallDirs + /module/GoogleTest + /module/InstallRequiredSystemLibraries + /module/MacroAddFileDependencies + /module/ProcessorCount + /module/SelectLibraryConfigurations + /module/SquishTestScript + /module/TestBigEndian + /module/TestForANSIForScope + /module/TestForANSIStreamHeaders + /module/TestForSSTREAM + /module/TestForSTDNamespace + /module/UseEcos + /module/UseJavaClassFilelist + /module/UseJava + /module/UseJavaSymlinks + /module/UsePkgConfig + /module/UseSWIG + /module/UsewxWidgets + /module/Use_wxWindows + /module/WriteCompilerDetectionHeader + +Find Modules +^^^^^^^^^^^^ + +These modules search for third-party software. +They are normally called through the :command:`find_package` command. + +.. toctree:: + :maxdepth: 1 + /module/FindALSA /module/FindArmadillo /module/FindASPELL @@ -82,7 +117,6 @@ All Modules /module/FindBZip2 /module/FindCABLE /module/FindCoin3D - /module/FindCUDA /module/FindCups /module/FindCURL /module/FindCurses @@ -97,6 +131,7 @@ All Modules /module/FindFLEX /module/FindFLTK2 /module/FindFLTK + /module/FindFontconfig /module/FindFreetype /module/FindGCCXML /module/FindGDAL @@ -131,6 +166,7 @@ All Modules /module/FindLAPACK /module/FindLATEX /module/FindLibArchive + /module/FindLibinput /module/FindLibLZMA /module/FindLibXml2 /module/FindLibXslt @@ -173,8 +209,6 @@ All Modules /module/FindosgViewer /module/FindosgVolume /module/FindosgWidget - /module/FindPackageHandleStandardArgs - /module/FindPackageMessage /module/FindPatch /module/FindPerlLibs /module/FindPerl @@ -189,8 +223,6 @@ All Modules /module/FindPython /module/FindPython2 /module/FindPython3 - /module/FindPythonInterp - /module/FindPythonLibs /module/FindQt3 /module/FindQt4 /module/FindQt @@ -205,6 +237,7 @@ All Modules /module/FindSDL_ttf /module/FindSelfPackers /module/FindSquish + /module/FindSQLite3 /module/FindSubversion /module/FindSWIG /module/FindTCL @@ -218,39 +251,39 @@ All Modules /module/FindWget /module/FindWish /module/FindwxWidgets - /module/FindwxWindows /module/FindXCTest /module/FindXalanC /module/FindXercesC /module/FindX11 /module/FindXMLRPC /module/FindZLIB - /module/FortranCInterface - /module/GenerateExportHeader - /module/GetPrerequisites - /module/GNUInstallDirs - /module/GoogleTest - /module/InstallRequiredSystemLibraries - /module/MacroAddFileDependencies - /module/ProcessorCount - /module/SelectLibraryConfigurations - /module/SquishTestScript - /module/TestBigEndian + +Deprecated Modules +^^^^^^^^^^^^^^^^^^^ + +Deprecated Utility Modules +========================== + +.. toctree:: + :maxdepth: 1 + + /module/CMakeDetermineVSServicePack + /module/CMakeExpandImportedTargets + /module/CMakeForceCompiler /module/TestCXXAcceptsFlag - /module/TestForANSIForScope - /module/TestForANSIStreamHeaders - /module/TestForSSTREAM - /module/TestForSTDNamespace - /module/UseEcos - /module/UseJavaClassFilelist - /module/UseJava - /module/UseJavaSymlinks - /module/UsePkgConfig - /module/UseSWIG - /module/UsewxWidgets /module/Use_wxWindows /module/WriteBasicConfigVersionFile - /module/WriteCompilerDetectionHeader + +Deprecated Find Modules +======================= + +.. toctree:: + :maxdepth: 1 + + /module/FindCUDA + /module/FindPythonInterp + /module/FindPythonLibs + /module/FindwxWindows Legacy CPack Modules ==================== diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 2cc52fe..0587429 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,14 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used to determine whether to report an error on use of deprecated macros or functions. +Policies Introduced by CMake 3.14 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0082: Install rules from add_subdirectory() are interleaved with those in caller. </policy/CMP0082> + Policies Introduced by CMake 3.13 ================================= diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 5c3eb81..047859d 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -124,6 +124,7 @@ Properties on Targets /prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG /prop_tgt/ARCHIVE_OUTPUT_NAME /prop_tgt/AUTOGEN_BUILD_DIR + /prop_tgt/AUTOGEN_ORIGIN_DEPENDS /prop_tgt/AUTOGEN_PARALLEL /prop_tgt/AUTOGEN_TARGET_DEPENDS /prop_tgt/AUTOMOC_COMPILER_PREDEFINES @@ -138,6 +139,7 @@ Properties on Targets /prop_tgt/AUTORCC_OPTIONS /prop_tgt/BINARY_DIR /prop_tgt/BUILD_RPATH + /prop_tgt/BUILD_RPATH_USE_ORIGIN /prop_tgt/BUILD_WITH_INSTALL_NAME_DIR /prop_tgt/BUILD_WITH_INSTALL_RPATH /prop_tgt/BUNDLE_EXTENSION diff --git a/Help/manual/cmake-qt.7.rst b/Help/manual/cmake-qt.7.rst index 724d8ec..0382794 100644 --- a/Help/manual/cmake-qt.7.rst +++ b/Help/manual/cmake-qt.7.rst @@ -44,14 +44,10 @@ Qt Build Tools Qt relies on some bundled tools for code generation, such as ``moc`` for meta-object code generation, ``uic`` for widget layout and population, -and ``rcc`` for virtual filesystem content generation. These tools may be +and ``rcc`` for virtual file system content generation. These tools may be automatically invoked by :manual:`cmake(1)` if the appropriate conditions are met. The automatic tool invocation may be used with both Qt 4 and Qt 5. -The tools are executed as part of a synthesized custom target generated by -CMake. Target dependencies may be added to that custom target by adding them -to the :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property. - AUTOMOC ^^^^^^^ @@ -214,19 +210,31 @@ overrides options from the :prop_tgt:`AUTORCC_OPTIONS` target property. Source files can be excluded from :prop_tgt:`AUTORCC` processing by enabling :prop_sf:`SKIP_AUTORCC` or the broader :prop_sf:`SKIP_AUTOGEN`. +The ``<ORIGIN>_autogen`` target +=============================== + +The ``moc`` and ``uic`` tools are executed as part of a synthesized +``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>` generated by +CMake. By default that ``<ORIGIN>_autogen`` target inherits the dependencies +of the ``<ORIGIN>`` target (see :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`). +Target dependencies may be added to the ``<ORIGIN>_autogen`` target by adding +them to the :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property. + Visual Studio Generators ======================== -When using the :manual:`Visual Studio generators <cmake-generators(7)>`, -CMake uses a ``PRE_BUILD`` :command:`custom command <add_custom_command>` for -:prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. -If the :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` processing depends on files, -a :command:`custom target <add_custom_target>` is used instead. -This happens when - -- The origin target depends on :prop_sf:`GENERATED` files which aren't excluded - from :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` by :prop_sf:`SKIP_AUTOMOC`, - :prop_sf:`SKIP_AUTOUIC`, :prop_sf:`SKIP_AUTOGEN` or :policy:`CMP0071` +When using the :manual:`Visual Studio generators <cmake-generators(7)>`, CMake +generates a ``PRE_BUILD`` :command:`custom command <add_custom_command>` +instead of the ``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>` +(for :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`). +This isn't always possible though and +an ``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>` is used, +when either + +- the ``<ORIGIN>`` target depends on :prop_sf:`GENERATED` files which aren't + excluded from :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` by + :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC`, :prop_sf:`SKIP_AUTOGEN` + or :policy:`CMP0071` - :prop_tgt:`AUTOGEN_TARGET_DEPENDS` lists a source file qtmain.lib on Windows diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 9dd36ed..7a7f0b8 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -7,6 +7,14 @@ cmake-variables(7) .. contents:: +This page documents variables that are provided by CMake +or have meaning to CMake when set by project code. + +For general information on variables, see the +:ref:`Variables <CMake Language Variables>` +section in the cmake-language manual. + + Variables that Provide Information ================================== @@ -233,7 +241,6 @@ Variables that Describe the System /variable/ANDROID /variable/APPLE /variable/BORLAND - /variable/CACHE /variable/CMAKE_CL_64 /variable/CMAKE_COMPILER_2005 /variable/CMAKE_HOST_APPLE @@ -252,7 +259,6 @@ Variables that Describe the System /variable/CMAKE_SYSTEM_PROCESSOR /variable/CMAKE_SYSTEM_VERSION /variable/CYGWIN - /variable/ENV /variable/GHS-MULTI /variable/MINGW /variable/MSVC @@ -309,6 +315,7 @@ Variables that Control the Build /variable/CMAKE_ANDROID_STL_TYPE /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG + /variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS /variable/CMAKE_AUTOGEN_PARALLEL /variable/CMAKE_AUTOGEN_VERBOSE /variable/CMAKE_AUTOMOC @@ -322,6 +329,7 @@ Variables that Control the Build /variable/CMAKE_AUTOUIC_OPTIONS /variable/CMAKE_AUTOUIC_SEARCH_PATHS /variable/CMAKE_BUILD_RPATH + /variable/CMAKE_BUILD_RPATH_USE_ORIGIN /variable/CMAKE_BUILD_WITH_INSTALL_NAME_DIR /variable/CMAKE_BUILD_WITH_INSTALL_RPATH /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY @@ -589,3 +597,12 @@ Variables for CPack /variable/CPACK_PACKAGING_INSTALL_PREFIX /variable/CPACK_SET_DESTDIR /variable/CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION + +Variable Expansion Operators +============================ + +.. toctree:: + :maxdepth: 1 + + /variable/CACHE + /variable/ENV |