diff options
Diffstat (limited to 'Help')
176 files changed, 1082 insertions, 657 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index 73dbd57..dde4dbb 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -96,7 +96,7 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: 2. Search paths specified in cmake-specific cache variables. These are intended to be used on the command line with a ``-DVAR=value``. - The values are interpreted as :ref:`;-lists <CMake Language Lists>`. + The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`. This can be skipped if ``NO_CMAKE_PATH`` is passed. * |CMAKE_PREFIX_PATH_XXX| diff --git a/Help/command/LINK_OPTIONS_LINKER.txt b/Help/command/LINK_OPTIONS_LINKER.txt index 76927be..a723375 100644 --- a/Help/command/LINK_OPTIONS_LINKER.txt +++ b/Help/command/LINK_OPTIONS_LINKER.txt @@ -8,3 +8,15 @@ driver option and the rest of the option string defines linker arguments using For example, ``"LINKER:-z,defs"`` becomes ``-Xlinker -z -Xlinker defs`` for ``Clang`` and ``-Wl,-z,defs`` for ``GNU GCC``. + +The ``LINKER:`` prefix can be specified as part of a ``SHELL:`` prefix +expression. + +The ``LINKER:`` prefix supports, as alternate syntax, specification of +arguments using ``SHELL:`` prefix and space as separator. Previous example +becomes ``"LINKER:SHELL:-z defs"``. + +.. note:: + + Specifying ``SHELL:`` prefix elsewhere than at the beginning of the + ``LINKER:`` prefix is not supported. diff --git a/Help/command/add_compile_definitions.rst b/Help/command/add_compile_definitions.rst index 48815d4..8225da7 100644 --- a/Help/command/add_compile_definitions.rst +++ b/Help/command/add_compile_definitions.rst @@ -1,9 +1,9 @@ add_compile_definitions ----------------------- -Adds preprocessor definitions to the compilation of source files. +Add preprocessor definitions to the compilation of source files. -:: +.. code-block:: cmake add_compile_definitions(<definition> ...) diff --git a/Help/command/add_compile_options.rst b/Help/command/add_compile_options.rst index 350a1c0..fcdcfd4 100644 --- a/Help/command/add_compile_options.rst +++ b/Help/command/add_compile_options.rst @@ -1,9 +1,9 @@ add_compile_options ------------------- -Adds options to the compilation of source files. +Add options to the compilation of source files. -:: +.. code-block:: cmake add_compile_options(<option> ...) diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index 71fe494..9bf0d87 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -8,7 +8,9 @@ There are two main signatures for ``add_custom_command``. Generating Files ^^^^^^^^^^^^^^^^ -The first signature is for adding a custom command to produce an output:: +The first signature is for adding a custom command to produce an output: + +.. code-block:: cmake add_custom_command(OUTPUT output1 [output2 ...] COMMAND command1 [ARGS] [args1...] @@ -200,7 +202,7 @@ before or after building the target. The command becomes part of the target and will only execute when the target itself is built. If the target is already built, the command will not execute. -:: +.. code-block:: cmake add_custom_command(TARGET <target> PRE_BUILD | PRE_LINK | POST_BUILD diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst index a6b2f77..c63dd23 100644 --- a/Help/command/add_custom_target.rst +++ b/Help/command/add_custom_target.rst @@ -3,7 +3,7 @@ add_custom_target Add a target with no output so it will always be built. -:: +.. code-block:: cmake add_custom_target(Name [ALL] [command1 [args1...]] [COMMAND command2 [args2...] ...] diff --git a/Help/command/add_definitions.rst b/Help/command/add_definitions.rst index 1da15a6..39a43f4 100644 --- a/Help/command/add_definitions.rst +++ b/Help/command/add_definitions.rst @@ -1,9 +1,9 @@ add_definitions --------------- -Adds -D define flags to the compilation of source files. +Add -D define flags to the compilation of source files. -:: +.. code-block:: cmake add_definitions(-DFOO -DBAR ...) diff --git a/Help/command/add_dependencies.rst b/Help/command/add_dependencies.rst index 7a66143..de219a5 100644 --- a/Help/command/add_dependencies.rst +++ b/Help/command/add_dependencies.rst @@ -3,11 +3,11 @@ add_dependencies Add a dependency between top-level targets. -:: +.. code-block:: cmake add_dependencies(<target> [<target-dependency>]...) -Make a top-level ``<target>`` depend on other top-level targets to +Makes a top-level ``<target>`` depend on other top-level targets to ensure that they build before ``<target>`` does. A top-level target is one created by one of the :command:`add_executable`, :command:`add_library`, or :command:`add_custom_target` commands diff --git a/Help/command/add_executable.rst b/Help/command/add_executable.rst index c7a30d7..0a7d7e1 100644 --- a/Help/command/add_executable.rst +++ b/Help/command/add_executable.rst @@ -3,7 +3,7 @@ add_executable Add an executable to the project using the specified source files. -:: +.. code-block:: cmake add_executable(<name> [WIN32] [MACOSX_BUNDLE] [EXCLUDE_FROM_ALL] @@ -47,7 +47,7 @@ within IDE. -------------------------------------------------------------------------- -:: +.. code-block:: cmake add_executable(<name> IMPORTED [GLOBAL]) @@ -67,7 +67,7 @@ properties for more information. -------------------------------------------------------------------------- -:: +.. code-block:: cmake add_executable(<name> ALIAS <target>) diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index c4c512c..ec6cb9d 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -10,7 +10,7 @@ Add a library to the project using the specified source files. Normal Libraries ^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake add_library(<name> [STATIC | SHARED | MODULE] [EXCLUDE_FROM_ALL] @@ -67,7 +67,7 @@ within IDE. Imported Libraries ^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake add_library(<name> <SHARED|STATIC|MODULE|OBJECT|UNKNOWN> IMPORTED [GLOBAL]) @@ -92,7 +92,7 @@ for more information. Object Libraries ^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake add_library(<name> OBJECT <src>...) @@ -121,7 +121,7 @@ consider adding at least one real source file to any target that references Alias Libraries ^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake add_library(<name> ALIAS <target>) @@ -141,7 +141,7 @@ installed or exported. Interface Libraries ^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake add_library(<name> INTERFACE [IMPORTED [GLOBAL]]) diff --git a/Help/command/add_link_options.rst b/Help/command/add_link_options.rst index 551d440..1b02bee 100644 --- a/Help/command/add_link_options.rst +++ b/Help/command/add_link_options.rst @@ -1,9 +1,9 @@ add_link_options ---------------- -Adds options to the link of shared library, module and executable targets. +Add options to the link of shared library, module and executable targets. -:: +.. code-block:: cmake add_link_options(<option> ...) @@ -21,6 +21,6 @@ the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem properties. -.. include:: LINK_OPTIONS_LINKER.txt - .. include:: OPTIONS_SHELL.txt + +.. include:: LINK_OPTIONS_LINKER.txt diff --git a/Help/command/add_subdirectory.rst b/Help/command/add_subdirectory.rst index 012ded4..8dba986 100644 --- a/Help/command/add_subdirectory.rst +++ b/Help/command/add_subdirectory.rst @@ -3,12 +3,11 @@ add_subdirectory Add a subdirectory to the build. -:: +.. code-block:: cmake - add_subdirectory(source_dir [binary_dir] - [EXCLUDE_FROM_ALL]) + add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL]) -Add a subdirectory to the build. The source_dir specifies the +Adds a subdirectory to the build. The source_dir specifies the directory in which the source CMakeLists.txt and code files are located. If it is a relative path it will be evaluated with respect to the current directory (the typical usage), but it may also be an diff --git a/Help/command/add_test.rst b/Help/command/add_test.rst index d8a96e9..a8c257d 100644 --- a/Help/command/add_test.rst +++ b/Help/command/add_test.rst @@ -3,13 +3,13 @@ add_test Add a test to the project to be run by :manual:`ctest(1)`. -:: +.. code-block:: cmake add_test(NAME <name> COMMAND <command> [<arg>...] [CONFIGURATIONS <config>...] [WORKING_DIRECTORY <dir>]) -Add a test called ``<name>``. The test name may not contain spaces, +Adds a test called ``<name>``. The test name may not contain spaces, quotes, or other characters special in CMake syntax. The options are: ``COMMAND`` @@ -39,7 +39,9 @@ The ``COMMAND`` and ``WORKING_DIRECTORY`` options may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. -Example usage:: +Example usage: + +.. code-block:: cmake add_test(NAME mytest COMMAND testDriver --config $<CONFIGURATION> @@ -57,7 +59,7 @@ file produced by target ``myexe``. --------------------------------------------------------------------- -:: +.. code-block:: cmake add_test(<name> <command> [<arg>...]) diff --git a/Help/command/aux_source_directory.rst b/Help/command/aux_source_directory.rst index dcd1cdf..e0af665 100644 --- a/Help/command/aux_source_directory.rst +++ b/Help/command/aux_source_directory.rst @@ -3,7 +3,7 @@ aux_source_directory Find all source files in a directory. -:: +.. code-block:: cmake aux_source_directory(<dir> <variable>) diff --git a/Help/command/break.rst b/Help/command/break.rst index fc2cd3c..4875a2b 100644 --- a/Help/command/break.rst +++ b/Help/command/break.rst @@ -3,10 +3,10 @@ break Break from an enclosing foreach or while loop. -:: +.. code-block:: cmake break() -Breaks from an enclosing foreach loop or while loop +Breaks from an enclosing :command:`foreach` or :command:`while` loop. See also the :command:`continue` command. diff --git a/Help/command/build_name.rst b/Help/command/build_name.rst index f717db1..2a1fbae 100644 --- a/Help/command/build_name.rst +++ b/Help/command/build_name.rst @@ -1,7 +1,7 @@ build_name ---------- -Disallowed. See CMake Policy :policy:`CMP0036`. +Disallowed since version 3.0. See CMake Policy :policy:`CMP0036`. Use ``${CMAKE_SYSTEM}`` and ``${CMAKE_CXX_COMPILER}`` instead. diff --git a/Help/command/cmake_host_system_information.rst b/Help/command/cmake_host_system_information.rst index 2dee93a..2e9563a 100644 --- a/Help/command/cmake_host_system_information.rst +++ b/Help/command/cmake_host_system_information.rst @@ -3,7 +3,7 @@ cmake_host_system_information Query host system specific information. -:: +.. code-block:: cmake cmake_host_system_information(RESULT <variable> QUERY <key> ...) diff --git a/Help/command/cmake_minimum_required.rst b/Help/command/cmake_minimum_required.rst index 2f1ab60..e6ebcf0 100644 --- a/Help/command/cmake_minimum_required.rst +++ b/Help/command/cmake_minimum_required.rst @@ -1,11 +1,15 @@ cmake_minimum_required ---------------------- -Set the minimum required version of cmake for a project and -update `Policy Settings`_ to match the version given:: +Require a minimum version of cmake. + +.. code-block:: cmake cmake_minimum_required(VERSION <min>[...<max>] [FATAL_ERROR]) +Sets the minimum required version of cmake for a project. +Also updates the policy settings as explained below. + ``<min>`` and the optional ``<max>`` are each CMake versions of the form ``major.minor[.patch[.tweak]]``, and the ``...`` is literal. @@ -47,13 +51,17 @@ as of a given CMake version and tells newer CMake versions to warn about their new policies. When a ``<min>`` version higher than 2.4 is specified the command -implicitly invokes:: +implicitly invokes + +.. code-block:: cmake cmake_policy(VERSION <min>[...<max>]) which sets CMake policies based on the range of versions specified. When a ``<min>`` version 2.4 or lower is given the command implicitly -invokes:: +invokes + +.. code-block:: cmake cmake_policy(VERSION 2.4[...<max>]) diff --git a/Help/command/cmake_parse_arguments.rst b/Help/command/cmake_parse_arguments.rst index efbef54..c8327e2 100644 --- a/Help/command/cmake_parse_arguments.rst +++ b/Help/command/cmake_parse_arguments.rst @@ -1,26 +1,28 @@ cmake_parse_arguments --------------------- -``cmake_parse_arguments`` is intended to be used in macros or functions for -parsing the arguments given to that macro or function. It processes the -arguments and defines a set of variables which hold the values of the -respective options. +Parse function or macro arguments. -:: +.. code-block:: cmake cmake_parse_arguments(<prefix> <options> <one_value_keywords> - <multi_value_keywords> args...) + <multi_value_keywords> <args>...) - cmake_parse_arguments(PARSE_ARGV N <prefix> <options> <one_value_keywords> - <multi_value_keywords>) + cmake_parse_arguments(PARSE_ARGV <N> <prefix> <options> + <one_value_keywords> <multi_value_keywords>) + +This command is for use in macros or functions. +It processes the arguments given to that macro or function, +and defines a set of variables which hold the values of the +respective options. -The first signature reads processes arguments passed in the ``args...``. +The first signature reads processes arguments passed in the ``<args>...``. This may be used in either a :command:`macro` or a :command:`function`. The ``PARSE_ARGV`` signature is only for use in a :command:`function` body. In this case the arguments that are parsed come from the ``ARGV#`` variables of the calling function. The parsing starts with -the Nth argument, where ``N`` is an unsigned integer. This allows for +the ``<N>``-th argument, where ``<N>`` is an unsigned integer. This allows for the values to have special characters like ``;`` in them. The ``<options>`` argument contains all options for the respective macro, diff --git a/Help/command/cmake_policy.rst b/Help/command/cmake_policy.rst index c3f7cfb..a80f982 100644 --- a/Help/command/cmake_policy.rst +++ b/Help/command/cmake_policy.rst @@ -22,7 +22,9 @@ Setting Policies by CMake Version The ``cmake_policy`` command is used to set policies to ``OLD`` or ``NEW`` behavior. While setting policies individually is supported, we -encourage projects to set policies based on CMake versions:: +encourage projects to set policies based on CMake versions: + +.. code-block:: cmake cmake_policy(VERSION <min>[...<max>]) @@ -50,7 +52,7 @@ command implicitly calls ``cmake_policy(VERSION)`` too. Setting Policies Explicitly ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake cmake_policy(SET CMP<NNNN> NEW) cmake_policy(SET CMP<NNNN> OLD) @@ -66,7 +68,7 @@ policy state to ``NEW``. Checking Policy Settings ^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake cmake_policy(GET CMP<NNNN> <variable>) @@ -85,7 +87,9 @@ scripts loaded by :command:`include` and :command:`find_package` commands except when invoked with the ``NO_POLICY_SCOPE`` option (see also policy :policy:`CMP0011`). The ``cmake_policy`` command provides an interface to manage custom -entries on the policy stack:: +entries on the policy stack: + +.. code-block:: cmake cmake_policy(PUSH) cmake_policy(POP) diff --git a/Help/command/configure_file.rst b/Help/command/configure_file.rst index e08c573..29e85bd 100644 --- a/Help/command/configure_file.rst +++ b/Help/command/configure_file.rst @@ -3,7 +3,7 @@ configure_file Copy a file to another location and modify its contents. -:: +.. code-block:: cmake configure_file(<input> <output> [COPYONLY] [ESCAPE_QUOTES] [@ONLY] @@ -13,15 +13,21 @@ Copies an ``<input>`` file to an ``<output>`` file and substitutes variable values referenced as ``@VAR@`` or ``${VAR}`` in the input file content. Each variable reference will be replaced with the current value of the variable, or the empty string if the variable -is not defined. Furthermore, input lines of the form:: +is not defined. Furthermore, input lines of the form + +.. code-block:: c #cmakedefine VAR ... -will be replaced with either:: +will be replaced with either + +.. code-block:: c #define VAR ... -or:: +or + +.. code-block:: c /* #undef VAR */ @@ -33,12 +39,16 @@ either ``#define VAR 1`` or ``#define VAR 0`` similarly. The result lines (with the exception of the ``#undef`` comments) can be indented using spaces and/or tabs between the ``#`` character and the ``cmakedefine`` or ``cmakedefine01`` words. This whitespace -indentation will be preserved in the output lines:: +indentation will be preserved in the output lines: + +.. code-block:: c # cmakedefine VAR # cmakedefine01 VAR -will be replaced, if ``VAR`` is defined, with:: +will be replaced, if ``VAR`` is defined, with + +.. code-block:: c # define VAR # define VAR 1 diff --git a/Help/command/continue.rst b/Help/command/continue.rst index 1c7d673..31c7089 100644 --- a/Help/command/continue.rst +++ b/Help/command/continue.rst @@ -3,10 +3,12 @@ continue Continue to the top of enclosing foreach or while loop. -:: +.. code-block:: cmake continue() The ``continue`` command allows a cmake script to abort the rest of a block in a :command:`foreach` or :command:`while` loop, and start at the top of -the next iteration. See also the :command:`break` command. +the next iteration. + +See also the :command:`break` command. diff --git a/Help/command/create_test_sourcelist.rst b/Help/command/create_test_sourcelist.rst index dde6812..77e37c5 100644 --- a/Help/command/create_test_sourcelist.rst +++ b/Help/command/create_test_sourcelist.rst @@ -3,7 +3,7 @@ create_test_sourcelist Create a test driver and source list for building test programs. -:: +.. code-block:: cmake create_test_sourcelist(sourceListName driverName test1 test2 test3 diff --git a/Help/command/ctest_submit.rst b/Help/command/ctest_submit.rst index 2ba6bef..426475c 100644 --- a/Help/command/ctest_submit.rst +++ b/Help/command/ctest_submit.rst @@ -33,6 +33,7 @@ The options are: ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES Upload = Files prepared for upload by ctest_upload(), in Upload.xml Submit = nothing + Done = Build is complete, in Done.xml ``FILES <file>...`` Specify an explicit list of specific files to be submitted. diff --git a/Help/command/define_property.rst b/Help/command/define_property.rst index da2631c..8f7439b 100644 --- a/Help/command/define_property.rst +++ b/Help/command/define_property.rst @@ -3,7 +3,7 @@ define_property Define and document custom properties. -:: +.. code-block:: cmake define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE | TEST | VARIABLE | CACHED_VARIABLE> @@ -11,7 +11,7 @@ Define and document custom properties. BRIEF_DOCS <brief-doc> [docs...] FULL_DOCS <full-doc> [docs...]) -Define one property in a scope for use with the :command:`set_property` and +Defines one property in a scope for use with the :command:`set_property` and :command:`get_property` commands. This is primarily useful to associate documentation with property names that may be retrieved with the :command:`get_property` command. The first argument determines the kind of diff --git a/Help/command/else.rst b/Help/command/else.rst index 0e5a198..a98fcd8 100644 --- a/Help/command/else.rst +++ b/Help/command/else.rst @@ -3,8 +3,8 @@ else Starts the else portion of an if block. -:: +.. code-block:: cmake - else(expression) + else([<condition>]) See the :command:`if` command. diff --git a/Help/command/elseif.rst b/Help/command/elseif.rst index 9a8dfed..6bf8646 100644 --- a/Help/command/elseif.rst +++ b/Help/command/elseif.rst @@ -1,10 +1,11 @@ elseif ------ -Starts the elseif portion of an if block. +Starts an elseif portion of an if block. -:: +.. code-block:: cmake - elseif(expression) + elseif(<condition>) -See the :command:`if` command. +See the :command:`if` command, especially for the syntax and logic +of the ``<condition>``. diff --git a/Help/command/enable_language.rst b/Help/command/enable_language.rst index 61dfc03..fb49b44 100644 --- a/Help/command/enable_language.rst +++ b/Help/command/enable_language.rst @@ -3,12 +3,12 @@ enable_language Enable a language (CXX/C/Fortran/etc) -:: +.. code-block:: cmake enable_language(<lang> [OPTIONAL] ) -This command enables support for the named language in CMake. This is -the same as the project command but does not create any of the extra +Enables support for the named language in CMake. This is +the same as the :command:`project` command but does not create any of the extra variables that are created by the project command. Example languages are ``CXX``, ``C``, ``CUDA``, ``Fortran``, and ``ASM``. diff --git a/Help/command/enable_testing.rst b/Help/command/enable_testing.rst index 1e3e279..e2028d2 100644 --- a/Help/command/enable_testing.rst +++ b/Help/command/enable_testing.rst @@ -3,7 +3,7 @@ enable_testing Enable testing for current directory and below. -:: +.. code-block:: cmake enable_testing() diff --git a/Help/command/endforeach.rst b/Help/command/endforeach.rst index 9af972b..fd923d5 100644 --- a/Help/command/endforeach.rst +++ b/Help/command/endforeach.rst @@ -3,8 +3,12 @@ endforeach Ends a list of commands in a foreach block. -:: +.. code-block:: cmake - endforeach(expression) + endforeach([<loop_var>]) See the :command:`foreach` command. + +The optional ``<loop_var>`` argument is supported for backward compatibility +only. If used it must be a verbatim repeat of the ``<loop_var>`` argument of +the opening ``foreach`` clause. diff --git a/Help/command/endfunction.rst b/Help/command/endfunction.rst index 6cc196c..e27129d 100644 --- a/Help/command/endfunction.rst +++ b/Help/command/endfunction.rst @@ -3,8 +3,12 @@ endfunction Ends a list of commands in a function block. -:: +.. code-block:: cmake - endfunction(expression) + endfunction([<name>]) See the :command:`function` command. + +The optional ``<name>`` argument is supported for backward compatibility +only. If used it must be a verbatim repeat of the ``<name>`` argument +of the opening ``function`` command. diff --git a/Help/command/endif.rst b/Help/command/endif.rst index a0163bf..fc4f038 100644 --- a/Help/command/endif.rst +++ b/Help/command/endif.rst @@ -3,8 +3,12 @@ endif Ends a list of commands in an if block. -:: +.. code-block:: cmake - endif(expression) + endif([<condition>]) See the :command:`if` command. + +The optional ``<condition>`` argument is supported for backward compatibility +only. If used it must be a verbatim repeat of the argument of the opening +``if`` clause. diff --git a/Help/command/endmacro.rst b/Help/command/endmacro.rst index 47327a7..4290ba7 100644 --- a/Help/command/endmacro.rst +++ b/Help/command/endmacro.rst @@ -3,8 +3,12 @@ endmacro Ends a list of commands in a macro block. -:: +.. code-block:: cmake - endmacro(expression) + endmacro([<name>]) See the :command:`macro` command. + +The optional ``<name>`` argument is supported for backward compatibility +only. If used it must be a verbatim repeat of the ``<name>`` argument +of the opening ``macro`` command. diff --git a/Help/command/endwhile.rst b/Help/command/endwhile.rst index 798c20e..5ef585b 100644 --- a/Help/command/endwhile.rst +++ b/Help/command/endwhile.rst @@ -3,8 +3,12 @@ endwhile Ends a list of commands in a while block. -:: +.. code-block:: cmake - endwhile(expression) + endwhile([<condition>]) See the :command:`while` command. + +The optional ``<condition>`` argument is supported for backward compatibility +only. If used it must be a verbatim repeat of the argument of the opening +``while`` clause. diff --git a/Help/command/exec_program.rst b/Help/command/exec_program.rst index 6dfdad3..bc9b069 100644 --- a/Help/command/exec_program.rst +++ b/Help/command/exec_program.rst @@ -1,7 +1,9 @@ exec_program ------------ -Deprecated. Use the :command:`execute_process` command instead. +.. deprecated:: 3.0 + + Use the :command:`execute_process` command instead. Run an executable program during the processing of the CMakeList.txt file. diff --git a/Help/command/execute_process.rst b/Help/command/execute_process.rst index 716f457..3a56dce 100644 --- a/Help/command/execute_process.rst +++ b/Help/command/execute_process.rst @@ -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>] @@ -56,7 +56,7 @@ Options: ``RESULTS_VARIABLE <variable>`` The variable will be set to contain the result of all processes as a - :ref:`;-list <CMake Language Lists>`, in order of the given ``COMMAND`` + :ref:`semicolon-separated list <CMake Language Lists>`, in order of the given ``COMMAND`` arguments. Each entry will be an integer return code from the corresponding child or a string describing an error condition. diff --git a/Help/command/export.rst b/Help/command/export.rst index 8c49328..b255ee8 100644 --- a/Help/command/export.rst +++ b/Help/command/export.rst @@ -3,11 +3,11 @@ export Export targets from the build tree for use by outside projects. -:: +.. code-block:: cmake export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>]) -Create a file ``<filename>`` that may be included by outside projects to +Creates a file ``<filename>`` that may be included by outside projects to import targets from the current project's build tree. This is useful during cross-compiling to build utility executables that can run on the host platform in one project and then import them into another @@ -25,7 +25,7 @@ export targets from an installation tree. The properties set on the generated IMPORTED targets will have the same values as the final values of the input TARGETS. -:: +.. code-block:: cmake export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>] [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES]) @@ -49,7 +49,7 @@ unspecified. transitive usage requirements of other targets that link to the object libraries in their implementation. -:: +.. code-block:: cmake export(PACKAGE <PackageName>) @@ -65,7 +65,7 @@ wide installations, it is not desirable to write the user package registry. If the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable is enabled, the ``export(PACKAGE)`` command will do nothing. -:: +.. code-block:: cmake export(TARGETS [target1 [target2 [...]]] [ANDROID_MK <filename>]) diff --git a/Help/command/export_library_dependencies.rst b/Help/command/export_library_dependencies.rst index 2cb437e..9753abf 100644 --- a/Help/command/export_library_dependencies.rst +++ b/Help/command/export_library_dependencies.rst @@ -1,7 +1,7 @@ export_library_dependencies --------------------------- -Disallowed. See CMake Policy :policy:`CMP0033`. +Disallowed since version 3.0. See CMake Policy :policy:`CMP0033`. Use :command:`install(EXPORT)` or :command:`export` command. diff --git a/Help/command/file.rst b/Help/command/file.rst index d4a6006..f5279c0 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -42,7 +42,7 @@ Reading .. _READ: -:: +.. code-block:: cmake file(READ <filename> <variable> [OFFSET <offset>] [LIMIT <max-in>] [HEX]) @@ -54,7 +54,7 @@ be converted to a hexadecimal representation (useful for binary data). .. _STRINGS: -:: +.. code-block:: cmake file(STRINGS <filename> <variable> [<options>...]) @@ -105,7 +105,7 @@ from the input file. .. _HASH: -:: +.. code-block:: cmake file(<HASH> <filename> <variable>) @@ -116,7 +116,7 @@ command. .. _TIMESTAMP: -:: +.. code-block:: cmake file(TIMESTAMP <filename> <variable> [<format>] [UTC]) @@ -133,7 +133,7 @@ Writing .. _WRITE: .. _APPEND: -:: +.. code-block:: cmake file(WRITE <filename> <content>...) file(APPEND <filename> <content>...) @@ -150,7 +150,7 @@ to update the file only when its content changes. .. _TOUCH: .. _TOUCH_NOCREATE: -:: +.. code-block:: cmake file(TOUCH [<files>...]) file(TOUCH_NOCREATE [<files>...]) @@ -167,7 +167,7 @@ modified. .. _GENERATE: -:: +.. code-block:: cmake file(GENERATE OUTPUT output-file <INPUT input-file|CONTENT content> @@ -217,7 +217,7 @@ Filesystem .. _GLOB: .. _GLOB_RECURSE: -:: +.. code-block:: cmake file(GLOB <variable> [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS] @@ -272,7 +272,7 @@ Examples of recursive globbing include:: .. _RENAME: -:: +.. code-block:: cmake file(RENAME <oldname> <newname>) @@ -282,7 +282,7 @@ Move a file or directory within a filesystem from ``<oldname>`` to .. _REMOVE: .. _REMOVE_RECURSE: -:: +.. code-block:: cmake file(REMOVE [<files>...]) file(REMOVE_RECURSE [<files>...]) @@ -293,7 +293,7 @@ given file does not exist. .. _MAKE_DIRECTORY: -:: +.. code-block:: cmake file(MAKE_DIRECTORY [<directories>...]) @@ -302,7 +302,7 @@ Create the given directories and their parents as needed. .. _COPY: .. _INSTALL: -:: +.. code-block:: cmake file(<COPY|INSTALL> <files>... DESTINATION <dir> [FILE_PERMISSIONS <permissions>...] @@ -338,7 +338,7 @@ Path Conversion .. _RELATIVE_PATH: -:: +.. code-block:: cmake file(RELATIVE_PATH <variable> <directory> <file>) @@ -348,7 +348,7 @@ store it in the ``<variable>``. .. _TO_CMAKE_PATH: .. _TO_NATIVE_PATH: -:: +.. code-block:: cmake file(TO_CMAKE_PATH "<path>" <variable>) file(TO_NATIVE_PATH "<path>" <variable>) @@ -370,7 +370,7 @@ Transfer .. _DOWNLOAD: .. _UPLOAD: -:: +.. code-block:: cmake file(DOWNLOAD <url> <file> [<options>...]) file(UPLOAD <file> <url> [<options>...]) @@ -460,7 +460,7 @@ Locking .. _LOCK: -:: +.. code-block:: cmake file(LOCK <path> [DIRECTORY] [RELEASE] [GUARD <FUNCTION|FILE|PROCESS>] diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 3ad571c..937a930 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -12,7 +12,7 @@ Find an external project, and load its settings. Basic Signature and Module Mode ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE] [REQUIRED] [[COMPONENTS] [components...]] @@ -51,8 +51,9 @@ mode and "Config" mode. The above signature selects Module mode. If no module is found the command falls back to Config mode, described below. This fall back is disabled if the ``MODULE`` option is given. -In Module mode, CMake searches for a file called ``Find<PackageName>.cmake`` -in the :variable:`CMAKE_MODULE_PATH` followed by the CMake installation. +In Module mode, CMake searches for a file called ``Find<PackageName>.cmake``. +The file is first searched in the :variable:`CMAKE_MODULE_PATH`, +then among the :ref:`Find Modules` provided by the CMake installation. If the file is found, it is read and processed by CMake. It is responsible for finding the package, checking the version, and producing any needed messages. Some find-modules provide limited or no support for versioning; @@ -67,7 +68,9 @@ full command signature and details of the search process. Project maintainers wishing to provide a package to be found by this command are encouraged to read on. -The complete Config mode command signature is:: +The complete Config mode command signature is + +.. code-block:: cmake find_package(<PackageName> [version] [EXACT] [QUIET] [REQUIRED] [[COMPONENTS] [components...]] @@ -202,7 +205,9 @@ is set no attempt is made to choose a highest or closest version number. To control the order in which ``find_package`` checks for compatibility use the two variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and :variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`. -For instance in order to select the highest version one can set:: +For instance in order to select the highest version one can set + +.. code-block:: cmake SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL) SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC) @@ -286,7 +291,7 @@ enabled. 2. Search paths specified in cmake-specific cache variables. These are intended to be used on the command line with a ``-DVAR=value``. - The values are interpreted as :ref:`;-lists <CMake Language Lists>`. + The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`. This can be skipped if ``NO_CMAKE_PATH`` is passed:: CMAKE_PREFIX_PATH diff --git a/Help/command/fltk_wrap_ui.rst b/Help/command/fltk_wrap_ui.rst index 041e5a7..6675272 100644 --- a/Help/command/fltk_wrap_ui.rst +++ b/Help/command/fltk_wrap_ui.rst @@ -3,7 +3,7 @@ fltk_wrap_ui Create FLTK user interfaces Wrappers. -:: +.. code-block:: cmake fltk_wrap_ui(resultingLibraryName source1 source2 ... sourceN ) diff --git a/Help/command/foreach.rst b/Help/command/foreach.rst index 106ba73..ae2afb2 100644 --- a/Help/command/foreach.rst +++ b/Help/command/foreach.rst @@ -3,45 +3,82 @@ foreach Evaluate a group of commands for each value in a list. -:: +.. code-block:: cmake - foreach(loop_var arg1 arg2 ...) - COMMAND1(ARGS ...) - COMMAND2(ARGS ...) - ... - endforeach(loop_var) + foreach(<loop_var> <items>) + <commands> + endforeach() -All commands between foreach and the matching endforeach are recorded -without being invoked. Once the endforeach is evaluated, the recorded -list of commands is invoked once for each argument listed in the -original foreach command. Before each iteration of the loop -``${loop_var}`` will be set as a variable with the current value in the -list. +where ``<items>`` is a list of items that are separated by +semicolon or whitespace. +All commands between ``foreach`` and the matching ``endforeach`` are recorded +without being invoked. Once the ``endforeach`` is evaluated, the recorded +list of commands is invoked once for each item in ``<items>``. +At the beginning of each iteration the variable ``loop_var`` will be set +to the value of the current item. -:: +The commands :command:`break` and :command:`continue` provide means to +escape from the normal control flow. - foreach(loop_var RANGE total) - foreach(loop_var RANGE start stop [step]) +Per legacy, the :command:`endforeach` command admits +an optional ``<loop_var>`` argument. +If used, it must be a verbatim +repeat of the argument of the opening +``foreach`` command. -Foreach can also iterate over a generated range of numbers. There are -three types of this iteration: +.. code-block:: cmake -* When specifying single number, the range will have elements [0, ... to - "total"] (inclusive). + foreach(<loop_var> RANGE <stop>) -* When specifying two numbers, the range will have elements from the - first number to the second number (inclusive). +In this variant, ``foreach`` iterates over the numbers +0, 1, ... up to (and including) the nonnegative integer ``<stop>``. -* The third optional number is the increment used to iterate from the - first number to the second number (inclusive). +.. code-block:: cmake -:: + foreach(<loop_var> RANGE <start> <stop> [<step>]) + +In this variant, ``foreach`` iterates over the numbers from +``<start>`` up to at most ``<stop>`` in steps of ``<step>``. +If ``<step>`` is not specified, then the step size is 1. +The three arguments ``<start>`` ``<stop>`` ``<step>`` must +all be nonnegative integers, and ``<stop>`` must not be +smaller than ``<start>``; otherwise you enter the danger zone +of undocumented behavior that may change in future releases. + +.. code-block:: cmake + + foreach(loop_var IN [LISTS [<lists>]] [ITEMS [<items>]]) - foreach(loop_var IN [LISTS [list1 [...]]] - [ITEMS [item1 [...]]]) +In this variant, ``<lists>`` is a whitespace or semicolon +separated list of list-valued variables. The ``foreach`` +command iterates over each item in each given list. +The ``<items>`` following the ``ITEMS`` keyword are processed +as in the first variant of the ``foreach`` command. +The forms ``LISTS A`` and ``ITEMS ${A}`` are +equivalent. + +The following example shows how the ``LISTS`` option is +processed: + +.. code-block:: cmake + + set(A 0;1) + set(B 2 3) + set(C "4 5") + set(D 6;7 8) + set(E "") + foreach(X IN LISTS A B C D E) + message(STATUS "X=${X}") + endforeach() + +yields +:: -Iterates over a precise list of items. The ``LISTS`` option names -list-valued variables to be traversed, including empty elements (an -empty string is a zero-length list). (Note macro -arguments are not variables.) The ``ITEMS`` option ends argument -parsing and includes all arguments following it in the iteration. + -- X=0 + -- X=1 + -- X=2 + -- X=3 + -- X=4 5 + -- X=6 + -- X=7 + -- X=8 diff --git a/Help/command/function.rst b/Help/command/function.rst index 7ffdfee..4a223b4 100644 --- a/Help/command/function.rst +++ b/Help/command/function.rst @@ -1,27 +1,29 @@ function -------- -Start recording a function for later invocation as a command:: - - function(<name> [arg1 [arg2 [arg3 ...]]]) - COMMAND1(ARGS ...) - COMMAND2(ARGS ...) - ... - endfunction(<name>) - -Define a function named ``<name>`` that takes arguments named ``arg1``, -``arg2``, ``arg3``, (...). -Commands listed after function, but before the matching -:command:`endfunction()`, are not invoked until the function is invoked. -When it is invoked, the commands recorded in the function are first -modified by replacing formal parameters (``${arg1}``) with the arguments -passed, and then invoked as normal commands. +Start recording a function for later invocation as a command. + +.. code-block:: cmake + + function(<name> [<arg1> ...]) + <commands> + endfunction() + +Defines a function named ``<name>`` that takes arguments +named ``<arg1>``, ... +The ``<commands>`` in the function definition are recorded; +they are not invoked until the function is invoked. When +the function is invoked, the recorded ``<commands>`` are first +modified by replacing formal parameters (``${arg1}``, ...) +with the arguments passed, and then invoked as normal commands. + In addition to referencing the formal parameters you can reference the ``ARGC`` variable which will be set to the number of arguments passed into the function as well as ``ARGV0``, ``ARGV1``, ``ARGV2``, ... which will have the actual values of the arguments passed in. This facilitates creating functions with optional arguments. -Additionally ``ARGV`` holds the list of all arguments given to the + +Furthermore, ``ARGV`` holds the list of all arguments given to the function and ``ARGN`` holds the list of arguments past the last expected argument. Referencing to ``ARGV#`` arguments beyond ``ARGC`` have undefined @@ -29,6 +31,10 @@ behavior. Checking that ``ARGC`` is greater than ``#`` is the only way to ensure that ``ARGV#`` was passed to the function as an extra argument. +Per legacy, the :command:`endfunction` command admits an optional +``<name>`` argument. If used, it must be a verbatim repeat of the +argument of the opening ``function`` command. + A function opens a new scope: see :command:`set(var PARENT_SCOPE)` for details. diff --git a/Help/command/get_cmake_property.rst b/Help/command/get_cmake_property.rst index 497ab4e..58bf741 100644 --- a/Help/command/get_cmake_property.rst +++ b/Help/command/get_cmake_property.rst @@ -3,14 +3,14 @@ get_cmake_property Get a global property of the CMake instance. -:: +.. code-block:: cmake - get_cmake_property(VAR property) + get_cmake_property(<var> <property>) -Get a global property from the CMake instance. The value of the property is -stored in the variable ``VAR``. If the property is not found, ``VAR`` -will be set to "NOTFOUND". See the :manual:`cmake-properties(7)` manual -for available properties. +Gets a global property from the CMake instance. The value of +the ``<property>`` is stored in the variable ``<var>``. +If the property is not found, ``<var>`` will be set to ``"NOTFOUND"``. +See the :manual:`cmake-properties(7)` manual for available properties. See also the :command:`get_property` command ``GLOBAL`` option. diff --git a/Help/command/get_directory_property.rst b/Help/command/get_directory_property.rst index bf8349c..218efa9 100644 --- a/Help/command/get_directory_property.rst +++ b/Help/command/get_directory_property.rst @@ -3,11 +3,11 @@ get_directory_property Get a property of ``DIRECTORY`` scope. -:: +.. code-block:: cmake get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>) -Store a property of directory scope in the named ``<variable>``. +Stores a property of directory scope in the named ``<variable>``. The ``DIRECTORY`` argument specifies another directory from which to retrieve the property value instead of the current directory. The specified directory must have already been traversed by CMake. @@ -18,7 +18,7 @@ if the property is not found for the nominated directory scope, the search will chain to a parent scope as described for the :command:`define_property` command. -:: +.. code-block:: cmake get_directory_property(<variable> [DIRECTORY <dir>] DEFINITION <var-name>) diff --git a/Help/command/get_filename_component.rst b/Help/command/get_filename_component.rst index f11c0fc..3e3c9c3 100644 --- a/Help/command/get_filename_component.rst +++ b/Help/command/get_filename_component.rst @@ -3,13 +3,11 @@ get_filename_component Get a specific component of a full filename. ------------------------------------------------------------------------------- +.. code-block:: cmake -:: - - get_filename_component(<VAR> <FileName> <COMP> [CACHE]) + get_filename_component(<var> <FileName> <mode> [CACHE]) -Set ``<VAR>`` to a component of ``<FileName>``, where ``<COMP>`` is one of: +Sets ``<var>`` to a component of ``<FileName>``, where ``<mode>`` is one of: :: @@ -24,15 +22,11 @@ The longest file extension is always considered. If the optional ``CACHE`` argument is specified, the result variable is added to the cache. ------------------------------------------------------------------------------- - -:: +.. code-block:: cmake - get_filename_component(<VAR> <FileName> - <COMP> [BASE_DIR <BASE_DIR>] - [CACHE]) + get_filename_component(<var> <FileName> <mode> [BASE_DIR <dir>] [CACHE]) -Set ``<VAR>`` to the absolute path of ``<FileName>``, where ``<COMP>`` is one +Sets ``<var>`` to the absolute path of ``<FileName>``, where ``<mode>`` is one of: :: @@ -41,7 +35,7 @@ of: REALPATH = Full path to existing file with symlinks resolved If the provided ``<FileName>`` is a relative path, it is evaluated relative -to the given base directory ``<BASE_DIR>``. If no base directory is +to the given base directory ``<dir>``. If no base directory is provided, the default base directory will be :variable:`CMAKE_CURRENT_SOURCE_DIR`. @@ -49,16 +43,12 @@ Paths are returned with forward slashes and have no trailing slashes. If the optional ``CACHE`` argument is specified, the result variable is added to the cache. ------------------------------------------------------------------------------- - -:: +.. code-block:: cmake - get_filename_component(<VAR> <FileName> - PROGRAM [PROGRAM_ARGS <ARG_VAR>] - [CACHE]) + get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE]) The program in ``<FileName>`` will be found in the system search path or left as a full path. If ``PROGRAM_ARGS`` is present with ``PROGRAM``, then any command-line arguments present in the ``<FileName>`` string are split -from the program name and stored in ``<ARG_VAR>``. This is used to +from the program name and stored in ``<arg_var>``. This is used to separate a program name from its arguments in a command line string. diff --git a/Help/command/get_property.rst b/Help/command/get_property.rst index 8b85f7d..c0f9b46 100644 --- a/Help/command/get_property.rst +++ b/Help/command/get_property.rst @@ -3,32 +3,33 @@ get_property Get a property. -:: +.. code-block:: cmake get_property(<variable> <GLOBAL | - DIRECTORY [dir] | + DIRECTORY [<dir>] | TARGET <target> | SOURCE <source> | INSTALL <file> | TEST <test> | CACHE <entry> | - VARIABLE> + VARIABLE > PROPERTY <name> [SET | DEFINED | BRIEF_DOCS | FULL_DOCS]) -Get one property from one object in a scope. The first argument -specifies the variable in which to store the result. The second -argument determines the scope from which to get the property. It must -be one of the following: +Gets one property from one object in a scope. + +The first argument specifies the variable in which to store the result. +The second argument determines the scope from which to get the property. +It must be one of the following: ``GLOBAL`` Scope is unique and does not accept a name. ``DIRECTORY`` Scope defaults to the current directory but another - directory (already processed by CMake) may be named by full or - relative path. + directory (already processed by CMake) may be named by the + full or relative path ``<dir>``. ``TARGET`` Scope must name one existing target. @@ -58,6 +59,7 @@ value indicating whether the property has been set. If the ``DEFINED`` option is given the variable is set to a boolean value indicating whether the property has been defined such as with the :command:`define_property` command. + If ``BRIEF_DOCS`` or ``FULL_DOCS`` is given then the variable is set to a string containing documentation for the requested property. If documentation is requested for a property that has not been defined diff --git a/Help/command/get_source_file_property.rst b/Help/command/get_source_file_property.rst index 51fbd33..decec19 100644 --- a/Help/command/get_source_file_property.rst +++ b/Help/command/get_source_file_property.rst @@ -3,11 +3,11 @@ get_source_file_property Get a property for a source file. -:: +.. code-block:: cmake get_source_file_property(VAR file property) -Get a property from a source file. The value of the property is +Gets a property from a source file. The value of the property is stored in the variable ``VAR``. If the source property is not found, the behavior depends on whether it has been defined to be an ``INHERITED`` property or not (see :command:`define_property`). Non-inherited properties will set diff --git a/Help/command/get_target_property.rst b/Help/command/get_target_property.rst index 98e9db3..cbf4721 100644 --- a/Help/command/get_target_property.rst +++ b/Help/command/get_target_property.rst @@ -3,7 +3,7 @@ get_target_property Get a property from a target. -:: +.. code-block:: cmake get_target_property(VAR target property) diff --git a/Help/command/get_test_property.rst b/Help/command/get_test_property.rst index 555c3b2..e02b9bc 100644 --- a/Help/command/get_test_property.rst +++ b/Help/command/get_test_property.rst @@ -3,7 +3,7 @@ get_test_property Get a property of the test. -:: +.. code-block:: cmake get_test_property(test property VAR) diff --git a/Help/command/if.rst b/Help/command/if.rst index 5294ce8..4781f35 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -3,41 +3,49 @@ if Conditionally execute a group of commands. +Synopsis +^^^^^^^^ + .. code-block:: cmake - if(expression) - # then section. - COMMAND1(ARGS ...) - COMMAND2(ARGS ...) - #... - elseif(expression2) - # elseif section. - COMMAND1(ARGS ...) - COMMAND2(ARGS ...) - #... - else(expression) - # else section. - COMMAND1(ARGS ...) - COMMAND2(ARGS ...) - #... - endif(expression) - -Evaluates the given expression. If the result is true, the commands -in the THEN section are invoked. Otherwise, the commands in the else -section are invoked. The elseif and else sections are optional. You -may have multiple elseif clauses. Note that the expression in the -else and endif clause is optional. Long expressions can be used and -there is a traditional order of precedence. Parenthetical expressions -are evaluated first followed by unary tests such as ``EXISTS``, -``COMMAND``, and ``DEFINED``. Then any binary tests such as + if(<condition>) + <commands> + elseif(<condition>) # optional block, can be repeated + <commands> + else() # optional block + <commands> + endif() + +Evaluates the ``condition`` argument of the ``if`` clause according to the +`Condition syntax`_ described below. If the result is true, then the +``commands`` in the ``if`` block are executed. +Otherwise, optional ``elseif`` blocks are processed in the same way. +Finally, if no ``condition`` is true, ``commands`` in the optional ``else`` +block are executed. + +Per legacy, the :command:`else` and :command:`elseif` commands admit +an optional ``<condition>`` argument. +If used, it must be a verbatim +repeat of the argument of the opening +``if`` command. + +Condition Syntax +^^^^^^^^^^^^^^^^ + +The following syntax applies to the ``condition`` argument of +the ``if``, ``elseif`` and :command:`while` clauses. + +Compound conditions are evaluated in the following order of precedence: +Innermost parentheses are evaluated first. Next come unary tests such +as ``EXISTS``, ``COMMAND``, and ``DEFINED``. Then binary tests such as ``EQUAL``, ``LESS``, ``LESS_EQUAL``, ``GREATER``, ``GREATER_EQUAL``, ``STREQUAL``, ``STRLESS``, ``STRLESS_EQUAL``, ``STRGREATER``, ``STRGREATER_EQUAL``, ``VERSION_EQUAL``, ``VERSION_LESS``, ``VERSION_LESS_EQUAL``, ``VERSION_GREATER``, ``VERSION_GREATER_EQUAL``, -and ``MATCHES`` will be evaluated. Then boolean ``NOT`` operators and -finally boolean ``AND`` and then ``OR`` operators will be evaluated. +and ``MATCHES``. Then the boolean operators in the order ``NOT``, ``AND``, +and finally ``OR``. -Possible expressions are: +Possible conditions are: ``if(<constant>)`` True if the constant is ``1``, ``ON``, ``YES``, ``TRUE``, ``Y``, @@ -52,14 +60,14 @@ Possible expressions are: True if given a variable that is defined to a value that is not a false constant. False otherwise. (Note macro arguments are not variables.) -``if(NOT <expression>)`` - True if the expression is not true. +``if(NOT <condition>)`` + True if the condition is not true. -``if(<expr1> AND <expr2>)`` - True if both expressions would be considered true individually. +``if(<cond1> AND <cond2>)`` + True if both conditions would be considered true individually. -``if(<expr1> OR <expr2>)`` - True if either expression would be considered true individually. +``if(<cond1> OR <cond2>)`` + True if either condition would be considered true individually. ``if(COMMAND command-name)`` True if the given name is a command, macro or function that can be @@ -103,7 +111,7 @@ Possible expressions are: ``if(<variable|string> MATCHES regex)`` True if the given string or variable's value matches the given regular - expression. See :ref:`Regex Specification` for regex format. + condition. See :ref:`Regex Specification` for regex format. ``()`` groups are captured in :variable:`CMAKE_MATCH_<n>` variables. ``if(<variable|string> LESS <variable|string>)`` @@ -184,31 +192,40 @@ Possible expressions are: variable is true or false just if it has been set. (Note macro arguments are not variables.) -``if((expression) AND (expression OR (expression)))`` - The expressions inside the parenthesis are evaluated first and then - the remaining expression is evaluated as in the previous examples. +``if((condition) AND (condition OR (condition)))`` + The conditions inside the parenthesis are evaluated first and then + the remaining condition is evaluated as in the previous examples. Where there are nested parenthesis the innermost are evaluated as part - of evaluating the expression that contains them. + of evaluating the condition that contains them. + +Variable Expansion +^^^^^^^^^^^^^^^^^^ The if command was written very early in CMake's history, predating the ``${}`` variable evaluation syntax, and for convenience evaluates variables named by its arguments as shown in the above signatures. Note that normal variable evaluation with ``${}`` applies before the if -command even receives the arguments. Therefore code like:: +command even receives the arguments. Therefore code like + +.. code-block:: cmake set(var1 OFF) set(var2 "var1") if(${var2}) -appears to the if command as:: +appears to the if command as - if(var1) +.. code-block:: cmake + + if(var1) and is evaluated according to the ``if(<variable>)`` case documented above. The result is ``OFF`` which is false. However, if we remove the -``${}`` from the example then the command sees:: +``${}`` from the example then the command sees + +.. code-block:: cmake - if(var2) + if(var2) which is true because ``var2`` is defined to "var1" which is not a false constant. diff --git a/Help/command/include.rst b/Help/command/include.rst index eeca4c6..80968da 100644 --- a/Help/command/include.rst +++ b/Help/command/include.rst @@ -3,16 +3,16 @@ include Load and run CMake code from a file or module. -:: +.. code-block:: cmake - include(<file|module> [OPTIONAL] [RESULT_VARIABLE <VAR>] + include(<file|module> [OPTIONAL] [RESULT_VARIABLE <var>] [NO_POLICY_SCOPE]) -Load and run CMake code from the file given. Variable reads and +Loads and runs CMake code from the file given. Variable reads and writes access the scope of the caller (dynamic scoping). If ``OPTIONAL`` is present, then no error is raised if the file does not exist. If -``RESULT_VARIABLE`` is given the variable will be set to the full filename -which has been included or NOTFOUND if it failed. +``RESULT_VARIABLE`` is given the variable ``<var>`` will be set to the +full filename which has been included or ``NOTFOUND`` if it failed. If a module is specified instead of a file, the file with name ``<modulename>.cmake`` is searched first in :variable:`CMAKE_MODULE_PATH`, diff --git a/Help/command/include_directories.rst b/Help/command/include_directories.rst index e797b5d..fe281c3 100644 --- a/Help/command/include_directories.rst +++ b/Help/command/include_directories.rst @@ -3,7 +3,7 @@ include_directories Add include directories to the build. -:: +.. code-block:: cmake include_directories([AFTER|BEFORE] [SYSTEM] dir1 [dir2 ...]) diff --git a/Help/command/include_external_msproject.rst b/Help/command/include_external_msproject.rst index 335282a..375baf2 100644 --- a/Help/command/include_external_msproject.rst +++ b/Help/command/include_external_msproject.rst @@ -3,7 +3,7 @@ include_external_msproject Include an external Microsoft project file in a workspace. -:: +.. code-block:: cmake include_external_msproject(projectname location [TYPE projectTypeGUID] diff --git a/Help/command/include_guard.rst b/Help/command/include_guard.rst index 62cce22..877aa86 100644 --- a/Help/command/include_guard.rst +++ b/Help/command/include_guard.rst @@ -3,7 +3,7 @@ include_guard Provides an include guard for the file currently being processed by CMake. -:: +.. code-block:: cmake include_guard([DIRECTORY|GLOBAL]) diff --git a/Help/command/include_regular_expression.rst b/Help/command/include_regular_expression.rst index ab5a563..dde8378 100644 --- a/Help/command/include_regular_expression.rst +++ b/Help/command/include_regular_expression.rst @@ -3,11 +3,11 @@ include_regular_expression Set the regular expression used for dependency checking. -:: +.. code-block:: cmake include_regular_expression(regex_match [regex_complain]) -Set the regular expressions used in dependency checking. Only files +Sets the regular expressions used in dependency checking. Only files matching ``regex_match`` will be traced as dependencies. Only files matching ``regex_complain`` will generate warnings if they cannot be found (standard header paths are not searched). The defaults are: diff --git a/Help/command/install.rst b/Help/command/install.rst index 98074d0..4966df4 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -101,7 +101,7 @@ Installing Targets .. _TARGETS: -:: +.. code-block:: cmake install(TARGETS targets... [EXPORT <export-name>] [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE| @@ -305,7 +305,7 @@ Installing Files .. _FILES: .. _PROGRAMS: -:: +.. code-block:: cmake install(<FILES|PROGRAMS> files... DESTINATION <dir> [PERMISSIONS permissions...] @@ -340,7 +340,7 @@ Installing Directories .. _DIRECTORY: -:: +.. code-block:: cmake install(DIRECTORY dirs... DESTINATION <dir> [FILE_PERMISSIONS permissions...] @@ -424,7 +424,7 @@ Custom Installation Logic .. _CODE: .. _SCRIPT: -:: +.. code-block:: cmake install([[SCRIPT <file>] [CODE <code>]] [COMPONENT <component>] [EXCLUDE_FROM_ALL] [...]) @@ -447,7 +447,7 @@ Installing Exports .. _EXPORT: -:: +.. code-block:: cmake install(EXPORT <export-name> DESTINATION <dir> [NAMESPACE <namespace>] [[FILE <name>.cmake]| diff --git a/Help/command/install_files.rst b/Help/command/install_files.rst index 1850be6..f5fb46d 100644 --- a/Help/command/install_files.rst +++ b/Help/command/install_files.rst @@ -1,7 +1,9 @@ install_files ------------- -Deprecated. Use the :command:`install(FILES)` command instead. +.. deprecated:: 3.0 + + Use the :command:`install(FILES)` command instead. This command has been superceded by the :command:`install` command. It is provided for compatibility with older CMake code. The ``FILES`` form is diff --git a/Help/command/install_programs.rst b/Help/command/install_programs.rst index 79aa486..fab6482 100644 --- a/Help/command/install_programs.rst +++ b/Help/command/install_programs.rst @@ -1,7 +1,9 @@ install_programs ---------------- -Deprecated. Use the :command:`install(PROGRAMS)` command instead. +.. deprecated:: 3.0 + + Use the :command:`install(PROGRAMS)` command instead. This command has been superceded by the :command:`install` command. It is provided for compatibility with older CMake code. The ``FILES`` form is diff --git a/Help/command/install_targets.rst b/Help/command/install_targets.rst index 49ca696..c9efdce 100644 --- a/Help/command/install_targets.rst +++ b/Help/command/install_targets.rst @@ -1,7 +1,9 @@ install_targets --------------- -Deprecated. Use the :command:`install(TARGETS)` command instead. +.. deprecated:: 3.0 + + Use the :command:`install(TARGETS)` command instead. This command has been superceded by the :command:`install` command. It is provided for compatibility with older CMake code. diff --git a/Help/command/link_directories.rst b/Help/command/link_directories.rst index 1dce9a0..9cb8faa 100644 --- a/Help/command/link_directories.rst +++ b/Help/command/link_directories.rst @@ -3,11 +3,11 @@ link_directories Add directories in which the linker will look for libraries. -:: +.. code-block:: cmake link_directories([AFTER|BEFORE] directory1 [directory2 ...]) -Add the paths in which the linker should search for libraries. +Adds the paths in which the linker should search for libraries. Relative paths given to this command are interpreted as relative to the current source directory, see :policy:`CMP0015`. diff --git a/Help/command/link_libraries.rst b/Help/command/link_libraries.rst index fd5dc37..8665cb7 100644 --- a/Help/command/link_libraries.rst +++ b/Help/command/link_libraries.rst @@ -3,7 +3,7 @@ link_libraries Link libraries to all targets added later. -:: +.. code-block:: cmake link_libraries([item1 [item2 [...]]] [[debug|optimized|general] <item>] ...) diff --git a/Help/command/list.rst b/Help/command/list.rst index 2357a9b..bfcdf34 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -64,7 +64,7 @@ Reading .. _LENGTH: -:: +.. code-block:: cmake list(LENGTH <list> <output variable>) @@ -72,7 +72,7 @@ Returns the list's length. .. _GET: -:: +.. code-block:: cmake list(GET <list> <element index> [<element index> ...] <output variable>) @@ -80,7 +80,7 @@ Returns the list of elements specified by indices from the list. .. _JOIN: -:: +.. code-block:: cmake list(JOIN <list> <glue> <output variable>) @@ -90,7 +90,7 @@ from :command:`string` command. .. _SUBLIST: -:: +.. code-block:: cmake list(SUBLIST <list> <begin> <length> <output variable>) @@ -104,7 +104,7 @@ Search .. _FIND: -:: +.. code-block:: cmake list(FIND <list> <value> <output variable>) @@ -116,7 +116,7 @@ Modification .. _APPEND: -:: +.. code-block:: cmake list(APPEND <list> [<element> ...]) @@ -124,7 +124,7 @@ Appends elements to the list. .. _FILTER: -:: +.. code-block:: cmake list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>) @@ -136,7 +136,7 @@ For more information on regular expressions see also the .. _INSERT: -:: +.. code-block:: cmake list(INSERT <list> <element_index> <element> [<element> ...]) @@ -144,7 +144,7 @@ Inserts elements to the list to the specified location. .. _REMOVE_ITEM: -:: +.. code-block:: cmake list(REMOVE_ITEM <list> <value> [<value> ...]) @@ -152,7 +152,7 @@ Removes the given items from the list. .. _REMOVE_AT: -:: +.. code-block:: cmake list(REMOVE_AT <list> <index> [<index> ...]) @@ -160,7 +160,7 @@ Removes items at given indices from the list. .. _REMOVE_DUPLICATES: -:: +.. code-block:: cmake list(REMOVE_DUPLICATES <list>) @@ -168,7 +168,7 @@ Removes duplicated items in the list. .. _TRANSFORM: -:: +.. code-block:: cmake list(TRANSFORM <list> <ACTION> [<SELECTOR>] [OUTPUT_VARIABLE <output variable>]) @@ -190,30 +190,40 @@ The actions have exactly the same semantics as sub-commands of The ``<ACTION>`` may be one of: ``APPEND``, ``PREPEND``: Append, prepend specified value to each element of -the list. :: +the list. + +.. code-block:: cmake list(TRANSFORM <list> <APPEND|PREPEND> <value> ...) ``TOUPPER``, ``TOLOWER``: Convert each element of the list to upper, lower -characters. :: +characters. + +.. code-block:: cmake list(TRANSFORM <list> <TOLOWER|TOUPPER> ...) ``STRIP``: Remove leading and trailing spaces from each element of the -list. :: +list. + +.. code-block:: cmake list(TRANSFORM <list> STRIP ...) ``GENEX_STRIP``: Strip any :manual:`generator expressions <cmake-generator-expressions(7)>` from each -element of the list. :: +element of the list. + +.. code-block:: cmake list(TRANSFORM <list> GENEX_STRIP ...) ``REPLACE``: Match the regular expression as many times as possible and substitute the replacement expression for the match for each element of the list -(Same semantic as ``REGEX REPLACE`` from :command:`string` command). :: +(Same semantic as ``REGEX REPLACE`` from :command:`string` command). + +.. code-block:: cmake list(TRANSFORM <list> REPLACE <regular_expression> <replace_expression> ...) @@ -223,17 +233,23 @@ type of selector can be specified at a time. The ``<SELECTOR>`` may be one of: -``AT``: Specify a list of indexes. :: +``AT``: Specify a list of indexes. + +.. code-block:: cmake list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...) ``FOR``: Specify a range with, optionally, an increment used to iterate over -the range. :: +the range. + +.. code-block:: cmake list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...) ``REGEX``: Specify a regular expression. Only elements matching the regular -expression will be transformed. :: +expression will be transformed. + +.. code-block:: cmake list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...) @@ -243,7 +259,7 @@ Ordering .. _REVERSE: -:: +.. code-block:: cmake list(REVERSE <list>) @@ -251,7 +267,7 @@ Reverses the contents of the list in-place. .. _SORT: -:: +.. code-block:: cmake list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>]) diff --git a/Help/command/load_cache.rst b/Help/command/load_cache.rst index f113447..33625c4 100644 --- a/Help/command/load_cache.rst +++ b/Help/command/load_cache.rst @@ -3,21 +3,20 @@ load_cache Load in the values from another project's CMake cache. -:: +.. code-block:: cmake - load_cache(pathToCacheFile READ_WITH_PREFIX - prefix entry1...) + load_cache(pathToCacheFile READ_WITH_PREFIX prefix entry1...) -Read the cache and store the requested entries in variables with their +Reads the cache and store the requested entries in variables with their name prefixed with the given prefix. This only reads the values, and does not create entries in the local project's cache. -:: +.. code-block:: cmake load_cache(pathToCacheFile [EXCLUDE entry1...] [INCLUDE_INTERNALS entry1...]) -Load in the values from another cache and store them in the local +Loads in the values from another cache and store them in the local project's cache as internal entries. This is useful for a project that depends on another project built in a different tree. ``EXCLUDE`` option can be used to provide a list of entries to be excluded. diff --git a/Help/command/load_command.rst b/Help/command/load_command.rst index a1576e8..dc23599 100644 --- a/Help/command/load_command.rst +++ b/Help/command/load_command.rst @@ -1,7 +1,7 @@ load_command ------------ -Disallowed. See CMake Policy :policy:`CMP0031`. +Disallowed since version 3.0. See CMake Policy :policy:`CMP0031`. Load a command into a running CMake. diff --git a/Help/command/macro.rst b/Help/command/macro.rst index 6bee69c..2746b1b 100644 --- a/Help/command/macro.rst +++ b/Help/command/macro.rst @@ -1,27 +1,29 @@ macro ----- -Start recording a macro for later invocation as a command:: +Start recording a macro for later invocation as a command - macro(<name> [arg1 [arg2 [arg3 ...]]]) - COMMAND1(ARGS ...) - COMMAND2(ARGS ...) - ... +.. code-block:: cmake + + macro(<name> [<arg1> ...]) + <commands> endmacro(<name>) -Define a macro named ``<name>`` that takes arguments named ``arg1``, -``arg2``, ``arg3``, (...). +Defines a macro named ``<name>`` that takes arguments +named ``<arg1>``, ... Commands listed after macro, but before the matching :command:`endmacro()`, are not invoked until the macro is invoked. When it is invoked, the commands recorded in the macro are first -modified by replacing formal parameters (``${arg1}``) with the arguments -passed, and then invoked as normal commands. +modified by replacing formal parameters (``${arg1}``, ...) +with the arguments passed, and then invoked as normal commands. + In addition to referencing the formal parameters you can reference the values ``${ARGC}`` which will be set to the number of arguments passed into the function as well as ``${ARGV0}``, ``${ARGV1}``, ``${ARGV2}``, ... which will have the actual values of the arguments passed in. This facilitates creating macros with optional arguments. -Additionally ``${ARGV}`` holds the list of all arguments given to the + +Furthermore, ``${ARGV}`` holds the list of all arguments given to the macro and ``${ARGN}`` holds the list of arguments past the last expected argument. Referencing to ``${ARGV#}`` arguments beyond ``${ARGC}`` have undefined @@ -38,7 +40,9 @@ Macro Argument Caveats Note that the parameters to a macro and values such as ``ARGN`` are not variables in the usual CMake sense. They are string replacements much like the C preprocessor would do with a macro. -Therefore you will NOT be able to use commands like:: +Therefore you will NOT be able to use commands like + +.. code-block:: cmake if(ARGV1) # ARGV1 is not a variable if(DEFINED ARGV2) # ARGV2 is not a variable @@ -50,18 +54,22 @@ In the second and third case, the proper way to check if an optional variable was passed to the macro is to use ``if(${ARGC} GREATER 2)``. In the last case, you can use ``foreach(loop_var ${ARGN})`` but this will skip empty arguments. -If you need to include them, you can use:: +If you need to include them, you can use + +.. code-block:: cmake set(list_var "${ARGN}") foreach(loop_var IN LISTS list_var) Note that if you have a variable with the same name in the scope from which the macro is called, using unreferenced names will use the -existing variable instead of the arguments. For example:: +existing variable instead of the arguments. For example: + +.. code-block:: cmake macro(_BAR) foreach(arg IN LISTS ARGN) - [...] + <commands> endforeach() endmacro() diff --git a/Help/command/make_directory.rst b/Help/command/make_directory.rst index 27ecf51..8469b0a 100644 --- a/Help/command/make_directory.rst +++ b/Help/command/make_directory.rst @@ -1,7 +1,9 @@ make_directory -------------- -Deprecated. Use the :command:`file(MAKE_DIRECTORY)` command instead. +.. deprecated:: 3.0 + + Use the :command:`file(MAKE_DIRECTORY)` command instead. :: diff --git a/Help/command/mark_as_advanced.rst b/Help/command/mark_as_advanced.rst index c3f94fc..5712fb4 100644 --- a/Help/command/mark_as_advanced.rst +++ b/Help/command/mark_as_advanced.rst @@ -3,17 +3,22 @@ mark_as_advanced Mark cmake cached variables as advanced. -:: +.. code-block:: cmake - mark_as_advanced([CLEAR|FORCE] VAR [VAR2 ...]) + mark_as_advanced([CLEAR|FORCE] <var1> ...) -Mark the named cached variables as advanced. An advanced variable -will not be displayed in any of the cmake GUIs unless the show -advanced option is on. If ``CLEAR`` is the first argument advanced -variables are changed back to unadvanced. If ``FORCE`` is the first -argument, then the variable is made advanced. If neither ``FORCE`` nor -``CLEAR`` is specified, new values will be marked as advanced, but if the -variable already has an advanced/non-advanced state, it will not be -changed. +Sets the advanced/non-advanced state of the named +cached variables. -It does nothing in script mode. +An advanced variable will not be displayed in any +of the cmake GUIs unless the ``show advanced`` option is on. +In script mode, the advanced/non-advanced state has no effect. + +If the keyword ``CLEAR`` is given +then advanced variables are changed back to unadvanced. +If the keyword ``FORCE`` is given +then the variables are made advanced. +If neither ``FORCE`` nor ``CLEAR`` is specified, +new values will be marked as advanced, but if a +variable already has an advanced/non-advanced state, +it will not be changed. diff --git a/Help/command/math.rst b/Help/command/math.rst index 63af931..4fa55f6 100644 --- a/Help/command/math.rst +++ b/Help/command/math.rst @@ -1,30 +1,36 @@ math ---- -Mathematical expressions. +Evaluate a mathematical expression. -:: +.. code-block:: cmake - math(EXPR <output-variable> <math-expression> [OUTPUT_FORMAT <format>]) + math(EXPR <variable> "<expression>" [OUTPUT_FORMAT <format>]) -``EXPR`` evaluates mathematical expression and returns result in the -output variable. Example mathematical expression is ``5 * (10 + 13)``. +Evaluates a mathematical ``<expression>`` and sets ``<variable>`` to the +resulting value. + +The mathematical expression must be given as a string (i.e. enclosed in +double quotation marks). An example is ``"5 * (10 + 13)"``. Supported operators are ``+``, ``-``, ``*``, ``/``, ``%``, ``|``, ``&``, -``^``, ``~``, ``<<``, ``>>``, and ``(...)``. They have the same meaning -as they do in C code. +``^``, ``~``, ``<<``, ``>>``, and ``(...)``; they have the same meaning +as in C code. + +Hexadecimal numbers are recognized when prefixed with "0x", as in C code. -Numeric constants are evaluated in decimal or hexadecimal representation. +The result is formatted according to the option ``OUTPUT_FORMAT``, +where ``<format>`` is one of -The result is formatted according to the option "OUTPUT_FORMAT" , -where ``<format>`` is one of: -:: +``HEXADECIMAL`` + Hexadecimal notation as in C code, i. e. starting with "0x". +``DECIMAL`` + Decimal notation. Which is also used if no ``OUTPUT_FORMAT`` option + is specified. - HEXADECIMAL = Result in output variable will be formatted in C code - Hexadecimal notation. - DECIMAL = Result in output variable will be formatted in decimal notation. +For example -For example:: +.. code-block:: cmake - math(EXPR value "100 * 0xA" DECIMAL) results in value is set to "1000" - math(EXPR value "100 * 0xA" HEXADECIMAL) results in value is set to "0x3e8" + math(EXPR value "100 * 0xA" OUTPUT_FORMAT DECIMAL) # value is set to "1000" + math(EXPR value "100 * 0xA" OUTPUT_FORMAT HEXADECIMAL) # value is set to "0x3e8" diff --git a/Help/command/message.rst b/Help/command/message.rst index 04c62fd..2b4b1aa 100644 --- a/Help/command/message.rst +++ b/Help/command/message.rst @@ -3,7 +3,7 @@ message Display a message to the user. -:: +.. code-block:: cmake message([<mode>] "message to display" ...) diff --git a/Help/command/option.rst b/Help/command/option.rst index 4fabb87..8956307 100644 --- a/Help/command/option.rst +++ b/Help/command/option.rst @@ -1,17 +1,16 @@ option ------ -Provides an option that the user can optionally select. +Provide an option that the user can optionally select. -:: +.. code-block:: cmake - option(<option_variable> "help string describing option" - [initial value]) + option(<variable> "<help_text>" [value]) -Provide an option for the user to select as ``ON`` or ``OFF``. If no -initial value is provided, ``OFF`` is used. If the option is already -set as a normal variable then the command does nothing -(see policy :policy:`CMP0077`). +Provides an option for the user to select as ``ON`` or ``OFF``. +If no initial ``<value>`` is provided, ``OFF`` is used. +If ``<variable>`` is already set as a normal variable +then the command does nothing (see policy :policy:`CMP0077`). If you have options that depend on the values of other options, see the module help for :module:`CMakeDependentOption`. diff --git a/Help/command/output_required_files.rst b/Help/command/output_required_files.rst index 5e13557..8bc6a73 100644 --- a/Help/command/output_required_files.rst +++ b/Help/command/output_required_files.rst @@ -1,7 +1,7 @@ output_required_files --------------------- -Disallowed. See CMake Policy :policy:`CMP0032`. +Disallowed since version 3.0. See CMake Policy :policy:`CMP0032`. Approximate C preprocessor dependency scanning. diff --git a/Help/command/project.rst b/Help/command/project.rst index bd8b4ef..688e56c 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -1,90 +1,119 @@ project ------- -Sets project details such as name, version, etc. and enables languages. +Set the name of the project. + +Synopsis +^^^^^^^^ .. code-block:: cmake - project(<PROJECT-NAME> [LANGUAGES] [<language-name>...]) + project(<PROJECT-NAME> [<language-name>...]) project(<PROJECT-NAME> [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]] [DESCRIPTION <project-description-string>] [HOMEPAGE_URL <url-string>] [LANGUAGES <language-name>...]) -Sets the name of the project and stores the name in the -:variable:`PROJECT_NAME` variable. Additionally this sets variables +Sets the name of the project, and stores it in the variable +:variable:`PROJECT_NAME`. When called from the top-level +``CMakeLists.txt`` also stores the project name in the +variable :variable:`CMAKE_PROJECT_NAME`. + +Also sets the variables * :variable:`PROJECT_SOURCE_DIR`, :variable:`<PROJECT-NAME>_SOURCE_DIR` * :variable:`PROJECT_BINARY_DIR`, :variable:`<PROJECT-NAME>_BINARY_DIR` -If ``VERSION`` is specified, given components must be non-negative integers. -If ``VERSION`` is not specified, the default version is the empty string. -The ``VERSION`` option may not be used unless policy :policy:`CMP0048` is -set to ``NEW``. - -The :command:`project()` command stores the version number and its components -in variables - -* :variable:`PROJECT_VERSION`, - :variable:`<PROJECT-NAME>_VERSION` -* :variable:`PROJECT_VERSION_MAJOR`, - :variable:`<PROJECT-NAME>_VERSION_MAJOR` -* :variable:`PROJECT_VERSION_MINOR`, - :variable:`<PROJECT-NAME>_VERSION_MINOR` -* :variable:`PROJECT_VERSION_PATCH`, - :variable:`<PROJECT-NAME>_VERSION_PATCH` -* :variable:`PROJECT_VERSION_TWEAK`, - :variable:`<PROJECT-NAME>_VERSION_TWEAK` - -Variables corresponding to unspecified versions are set to the empty string -(if policy :policy:`CMP0048` is set to ``NEW``). - -If the optional ``DESCRIPTION`` is given, then :variable:`PROJECT_DESCRIPTION` -and :variable:`<PROJECT-NAME>_DESCRIPTION` will be set to its argument. -These variables will be cleared if ``DESCRIPTION`` is not given. -The description is expected to be a relatively short string, usually no more -than a few words. - -The optional ``HOMEPAGE_URL`` sets the analogous variables -:variable:`PROJECT_HOMEPAGE_URL` and :variable:`<PROJECT-NAME>_HOMEPAGE_URL`. -When this option is given, the URL provided should be the canonical home for -the project. -These variables will be cleared if ``HOMEPAGE_URL`` is not given. - -Note that the description and homepage URL may be used as defaults for -things like packaging meta-data, documentation, etc. - -Optionally you can specify which languages your project supports. -Example languages include ``C``, ``CXX`` (i.e. C++), ``CUDA``, -``Fortran``, and ``ASM``. -By default ``C`` and ``CXX`` are enabled if no language options are -given. Specify language ``NONE``, or use the ``LANGUAGES`` keyword -and list no languages, to skip enabling any languages. - -If enabling ``ASM``, list it last so that CMake can check whether -compilers for other languages like ``C`` work for assembly too. - -If a variable exists called :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, +Further variables are set by the optional arguments described in the following. +If any of these arguments is not used, then the corresponding variables are +set to the empty string. + +If the variable :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` exists, the file pointed to by that variable will be included as the last step of the project command. +Options +^^^^^^^ + +The options are: + +``VERSION <version>`` + Optional; may not be used unless policy :policy:`CMP0048` is + set to ``NEW``. + + Takes a ``<version>`` argument composed of non-negative integer components, + i.e. ``<major>[.<minor>[.<patch>[.<tweak>]]]``, + and sets the variables + + * :variable:`PROJECT_VERSION`, + :variable:`<PROJECT-NAME>_VERSION` + * :variable:`PROJECT_VERSION_MAJOR`, + :variable:`<PROJECT-NAME>_VERSION_MAJOR` + * :variable:`PROJECT_VERSION_MINOR`, + :variable:`<PROJECT-NAME>_VERSION_MINOR` + * :variable:`PROJECT_VERSION_PATCH`, + :variable:`<PROJECT-NAME>_VERSION_PATCH` + * :variable:`PROJECT_VERSION_TWEAK`, + :variable:`<PROJECT-NAME>_VERSION_TWEAK`. + + When the :command:`project()` command is called from the top-level ``CMakeLists.txt``, + then the version is also stored in the variable :variable:`CMAKE_PROJECT_VERSION`. + +``DESCRIPTION <project-description-string>`` + Optional. + Sets the variables + + * :variable:`PROJECT_DESCRIPTION`, :variable:`<PROJECT-NAME>_DESCRIPTION` + + to ``<project-description-string>``. + It is recommended that this description is a relatively short string, + usually no more than a few words. + + When the :command:`project()` command is called from the top-level ``CMakeLists.txt``, + then the description is also stored in the variable :variable:`CMAKE_PROJECT_DESCRIPTION`. + +``HOMEPAGE_URL <url-string>`` + Optional. + Sets the variables + + * :variable:`PROJECT_HOMEPAGE_URL`, :variable:`<PROJECT-NAME>_HOMEPAGE_URL` + + to ``<url-string>``, which should be the canonical home URL for the project. + + When the :command:`project()` command is called from the top-level ``CMakeLists.txt``, + then the URL also is stored in the variable :variable:`CMAKE_PROJECT_HOMEPAGE_URL`. + +``LANGUAGES <language-name>...`` + Optional. + Can also be specified without ``LANGUAGES`` keyword per the first, short signature. + + Selects which programming languages are needed to build the project. + Supported languages include ``C``, ``CXX`` (i.e. C++), ``CUDA``, ``Fortran``, and ``ASM``. + By default ``C`` and ``CXX`` are enabled if no language options are given. + Specify language ``NONE``, or use the ``LANGUAGES`` keyword and list no languages, + to skip enabling any languages. + + If enabling ``ASM``, list it last so that CMake can check whether + compilers for other languages like ``C`` work for assembly too. + +The variables set through the ``VERSION``, ``DESCRIPTION`` and ``HOMEPAGE_URL`` +options are intended for use as default values in package metadata and documentation. + +Usage +^^^^^ + The top-level ``CMakeLists.txt`` file for a project must contain a literal, direct call to the :command:`project` command; loading one through the :command:`include` command is not sufficient. If no such call exists CMake will implicitly add one to the top that enables the -default languages (``C`` and ``CXX``). The name of the project set in -the top level ``CMakeLists.txt`` file is available from the -:variable:`CMAKE_PROJECT_NAME` variable, its description from -:variable:`CMAKE_PROJECT_DESCRIPTION`, its homepage URL from -:variable:`CMAKE_PROJECT_HOMEPAGE_URL` and its version from -:variable:`CMAKE_PROJECT_VERSION`. +default languages (``C`` and ``CXX``). .. note:: Call the :command:`cmake_minimum_required` command at the beginning of the top-level ``CMakeLists.txt`` file even before calling the - ``project()`` command. It is important to establish version and + :command:`project()` command. It is important to establish version and policy settings before invoking other commands whose behavior they may affect. See also policy :policy:`CMP0000`. diff --git a/Help/command/qt_wrap_cpp.rst b/Help/command/qt_wrap_cpp.rst index 3843bf5..c04c7a6 100644 --- a/Help/command/qt_wrap_cpp.rst +++ b/Help/command/qt_wrap_cpp.rst @@ -3,10 +3,9 @@ qt_wrap_cpp Create Qt Wrappers. -:: +.. code-block:: cmake - qt_wrap_cpp(resultingLibraryName DestName - SourceLists ...) + qt_wrap_cpp(resultingLibraryName DestName SourceLists ...) -Produce moc files for all the .h files listed in the SourceLists. The +Produces moc files for all the .h files listed in the SourceLists. The moc files will be added to the library using the ``DestName`` source list. diff --git a/Help/command/qt_wrap_ui.rst b/Help/command/qt_wrap_ui.rst index f731ed9..9a8863d 100644 --- a/Help/command/qt_wrap_ui.rst +++ b/Help/command/qt_wrap_ui.rst @@ -3,12 +3,12 @@ qt_wrap_ui Create Qt user interfaces Wrappers. -:: +.. code-block:: cmake qt_wrap_ui(resultingLibraryName HeadersDestName SourcesDestName SourceLists ...) -Produce .h and .cxx files for all the .ui files listed in the +Produces .h and .cxx files for all the .ui files listed in the ``SourceLists``. The .h files will be added to the library using the ``HeadersDestNamesource`` list. The .cxx files will be added to the library using the ``SourcesDestNamesource`` list. diff --git a/Help/command/remove.rst b/Help/command/remove.rst index 4628277..543d016 100644 --- a/Help/command/remove.rst +++ b/Help/command/remove.rst @@ -1,7 +1,9 @@ remove ------ -Deprecated. Use the :command:`list(REMOVE_ITEM)` command instead. +.. deprecated:: 3.0 + + Use the :command:`list(REMOVE_ITEM)` command instead. :: diff --git a/Help/command/remove_definitions.rst b/Help/command/remove_definitions.rst index ea18918..faad16d 100644 --- a/Help/command/remove_definitions.rst +++ b/Help/command/remove_definitions.rst @@ -1,9 +1,9 @@ remove_definitions ------------------ -Removes -D define flags added by :command:`add_definitions`. +Remove -D define flags added by :command:`add_definitions`. -:: +.. code-block:: cmake remove_definitions(-DFOO -DBAR ...) diff --git a/Help/command/return.rst b/Help/command/return.rst index e49fb3c..830992c 100644 --- a/Help/command/return.rst +++ b/Help/command/return.rst @@ -3,7 +3,7 @@ return Return from a file, directory or function. -:: +.. code-block:: cmake return() @@ -14,5 +14,6 @@ and control is returned to the including file. If it is encountered in a file which is not included by another file, e.g. a ``CMakeLists.txt``, control is returned to the parent directory if there is one. If return is called in a function, control is returned to the caller of the function. -Note that a macro is not a function and does not handle return like a -function does. + +Note that a :command:`macro <macro>`, unlike a :command:`function <function>`, +is expanded in place and therefore cannot handle ``return()``. diff --git a/Help/command/separate_arguments.rst b/Help/command/separate_arguments.rst index 47982a5..fbca859 100644 --- a/Help/command/separate_arguments.rst +++ b/Help/command/separate_arguments.rst @@ -1,33 +1,43 @@ separate_arguments ------------------ -Parse space-separated arguments into a semicolon-separated list. +Parse command-line arguments into a semicolon-separated list. -:: +.. code-block:: cmake - separate_arguments(<var> <NATIVE|UNIX|WINDOWS>_COMMAND "<args>") + separate_arguments(<variable> <mode> <args>) -Parses a UNIX- or Windows-style command-line string "<args>" and -stores a semicolon-separated list of the arguments in ``<var>``. The -entire command line must be given in one "<args>" argument. +Parses a space-separated string ``<args>`` into a list of items, +and stores this list in semicolon-separated standard form in ``<variable>``. -The ``UNIX_COMMAND`` mode separates arguments by unquoted whitespace. It -recognizes both single-quote and double-quote pairs. A backslash -escapes the next literal character (``\"`` is ``"``); there are no special -escapes (``\n`` is just ``n``). +This function is intended for parsing command-line arguments. +The entire command line must be passed as one string in the +argument ``<args>``. -The ``WINDOWS_COMMAND`` mode parses a Windows command-line using the same -syntax the runtime library uses to construct argv at startup. It -separates arguments by whitespace that is not double-quoted. -Backslashes are literal unless they precede double-quotes. See the -MSDN article `Parsing C Command-Line Arguments`_ for details. +The exact parsing rules depend on the operating system. +They are specified by the ``<mode>`` argument which must +be one of the following keywords: -The ``NATIVE_COMMAND`` mode parses a Windows command-line if the host -system is Windows, and a UNIX command-line otherwise. +``UNIX_COMMAND`` + Arguments are separated by by unquoted whitespace. + Both single-quote and double-quote pairs are respected. + A backslash escapes the next literal character (``\"`` is ``"``); + there are no special escapes (``\n`` is just ``n``). + +``WINDOWS_COMMAND`` + A Windows command-line is parsed using the same + syntax the runtime library uses to construct argv at startup. It + separates arguments by whitespace that is not double-quoted. + Backslashes are literal unless they precede double-quotes. See the + MSDN article `Parsing C Command-Line Arguments`_ for details. + +``NATIVE_COMMAND`` + Proceeds as in ``WINDOWS_COMMAND`` mode if the host system is Windows. + Otherwise proceeds as in ``UNIX_COMMAND`` mode. .. _`Parsing C Command-Line Arguments`: https://msdn.microsoft.com/library/a1y7w461.aspx -:: +.. code-block:: cmake separate_arguments(<var>) diff --git a/Help/command/set.rst b/Help/command/set.rst index b24ebef..e37e693 100644 --- a/Help/command/set.rst +++ b/Help/command/set.rst @@ -8,18 +8,18 @@ and cache entries. Signatures of this command that specify a ``<value>...`` placeholder expect zero or more arguments. Multiple arguments will be joined as -a :ref:`;-list <CMake Language Lists>` to form the actual variable +a :ref:`semicolon-separated list <CMake Language Lists>` to form the actual variable value to be set. Zero arguments will cause normal variables to be unset. See the :command:`unset` command to unset variables explicitly. Set Normal Variable ^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake set(<variable> <value>... [PARENT_SCOPE]) -Set the given ``<variable>`` in the current function or directory scope. +Sets the given ``<variable>`` in the current function or directory scope. If the ``PARENT_SCOPE`` option is given the variable will be set in the scope above the current scope. Each new directory or function @@ -32,11 +32,11 @@ undefined and if it had a value, it is still that value). Set Cache Entry ^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake set(<variable> <value>... CACHE <type> <docstring> [FORCE]) -Set the given cache ``<variable>`` (cache entry). Since cache entries +Sets the given cache ``<variable>`` (cache entry). Since cache entries are meant to provide user-settable values this does not overwrite existing cache entries by default. Use the ``FORCE`` option to overwrite existing entries. @@ -84,8 +84,8 @@ current working directory and convert it to an absolute path. Set Environment Variable ^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake set(ENV{<variable>} <value>...) -Set the current process environment ``<variable>`` to the given value. +Sets the current process environment ``<variable>`` to the given value. diff --git a/Help/command/set_directory_properties.rst b/Help/command/set_directory_properties.rst index 42e7fd7..cc71522 100644 --- a/Help/command/set_directory_properties.rst +++ b/Help/command/set_directory_properties.rst @@ -1,11 +1,13 @@ set_directory_properties ------------------------ -Set properties of the current directory and subdirectories in key-value pairs. +Set properties of the current directory and subdirectories. -:: +.. code-block:: cmake - set_directory_properties(PROPERTIES prop1 value1 prop2 value2) + set_directory_properties(PROPERTIES prop1 value1 [prop2 value2] ...) + +Sets properties of the current directory and its subdirectories in key-value pairs. See :ref:`Directory Properties` for the list of properties known to CMake and their individual documentation for the behavior of each property. diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst index c89e1ce..2d270ec 100644 --- a/Help/command/set_property.rst +++ b/Help/command/set_property.rst @@ -3,21 +3,22 @@ set_property Set a named property in a given scope. -:: - - set_property(<GLOBAL | - DIRECTORY [dir] | - TARGET [target1 [target2 ...]] | - SOURCE [src1 [src2 ...]] | - INSTALL [file1 [file2 ...]] | - TEST [test1 [test2 ...]] | - CACHE [entry1 [entry2 ...]]> +.. code-block:: cmake + + set_property(<GLOBAL | + DIRECTORY [<dir>] | + TARGET [<target1> ...] | + SOURCE [<src1> ...] | + INSTALL [<file1> ...] | + TEST [<test1> ...] | + CACHE [<entry1> ...] > [APPEND] [APPEND_STRING] - PROPERTY <name> [value1 [value2 ...]]) + PROPERTY <name> [value1 ...]) -Set one property on zero or more objects of a scope. The first -argument determines the scope in which the property is set. It must -be one of the following: +Sets one property on zero or more objects of a scope. + +The first argument determines the scope in which the property is set. +It must be one of the following: ``GLOBAL`` Scope is unique and does not accept a name. diff --git a/Help/command/set_source_files_properties.rst b/Help/command/set_source_files_properties.rst index b4904e8..8538a1e 100644 --- a/Help/command/set_source_files_properties.rst +++ b/Help/command/set_source_files_properties.rst @@ -3,13 +3,13 @@ set_source_files_properties Source files can have properties that affect how they are built. -:: +.. code-block:: cmake set_source_files_properties([file1 [file2 [...]]] PROPERTIES prop1 value1 [prop2 value2 [...]]) -Set properties associated with source files using a key/value paired +Sets properties associated with source files using a key/value paired list. See :ref:`Source File Properties` for the list of properties known to CMake. Source file properties are visible only to targets added in the same directory (CMakeLists.txt). diff --git a/Help/command/set_target_properties.rst b/Help/command/set_target_properties.rst index 7db952d..597be23 100644 --- a/Help/command/set_target_properties.rst +++ b/Help/command/set_target_properties.rst @@ -3,13 +3,13 @@ set_target_properties Targets can have properties that affect how they are built. -:: +.. code-block:: cmake set_target_properties(target1 target2 ... PROPERTIES prop1 value1 prop2 value2 ...) -Set properties on targets. The syntax for the command is to list all +Sets properties on targets. The syntax for the command is to list all the targets you want to change, and then provide the values you want to set next. You can use any prop value pair you want and extract it later with the :command:`get_property` or :command:`get_target_property` diff --git a/Help/command/set_tests_properties.rst b/Help/command/set_tests_properties.rst index 3efb165..55fd635 100644 --- a/Help/command/set_tests_properties.rst +++ b/Help/command/set_tests_properties.rst @@ -3,11 +3,11 @@ set_tests_properties Set a property of the tests. -:: +.. code-block:: cmake set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2) -Set a property for the tests. If the test is not found, CMake +Sets a property for the tests. If the test is not found, CMake will report an error. :manual:`Generator expressions <cmake-generator-expressions(7)>` will be expanded the same as supported by the test's :command:`add_test` call. See diff --git a/Help/command/site_name.rst b/Help/command/site_name.rst index e17c1ee..1bcaead 100644 --- a/Help/command/site_name.rst +++ b/Help/command/site_name.rst @@ -3,6 +3,6 @@ site_name Set the given variable to the name of the computer. -:: +.. code-block:: cmake site_name(variable) diff --git a/Help/command/source_group.rst b/Help/command/source_group.rst index 938ca40..6623c98 100644 --- a/Help/command/source_group.rst +++ b/Help/command/source_group.rst @@ -4,7 +4,7 @@ source_group Define a grouping for source files in IDE project generation. There are two different signatures to create source groups. -:: +.. code-block:: cmake source_group(<name> [FILES <src>...] [REGULAR_EXPRESSION <regex>]) source_group(TREE <root> [PREFIX <prefix>] [FILES <src>...]) diff --git a/Help/command/string.rst b/Help/command/string.rst index cc18069..893fb43 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -48,7 +48,7 @@ Search and Replace .. _FIND: -:: +.. code-block:: cmake string(FIND <string> <substring> <output variable> [REVERSE]) @@ -59,7 +59,7 @@ substring. If the substring is not found, a position of -1 is returned. .. _REPLACE: -:: +.. code-block:: cmake string(REPLACE <match_string> <replace_string> <output variable> @@ -73,7 +73,7 @@ Regular Expressions .. _`REGEX MATCH`: -:: +.. code-block:: cmake string(REGEX MATCH <regular_expression> <output variable> <input> [<input>...]) @@ -83,7 +83,7 @@ All ``<input>`` arguments are concatenated before matching. .. _`REGEX MATCHALL`: -:: +.. code-block:: cmake string(REGEX MATCHALL <regular_expression> <output variable> <input> [<input>...]) @@ -94,7 +94,7 @@ All ``<input>`` arguments are concatenated before matching. .. _`REGEX REPLACE`: -:: +.. code-block:: cmake string(REGEX REPLACE <regular_expression> <replace_expression> <output variable> @@ -177,7 +177,7 @@ Manipulation .. _APPEND: -:: +.. code-block:: cmake string(APPEND <string variable> [<input>...]) @@ -185,7 +185,7 @@ Append all the input arguments to the string. .. _PREPEND: -:: +.. code-block:: cmake string(PREPEND <string variable> [<input>...]) @@ -193,7 +193,7 @@ Prepend all the input arguments to the string. .. _CONCAT: -:: +.. code-block:: cmake string(CONCAT <output variable> [<input>...]) @@ -202,7 +202,7 @@ the result in the named output variable. .. _JOIN: -:: +.. code-block:: cmake string(JOIN <glue> <output variable> [<input>...]) @@ -215,7 +215,7 @@ special characters like ``;`` in them. .. _TOLOWER: -:: +.. code-block:: cmake string(TOLOWER <string1> <output variable>) @@ -223,7 +223,7 @@ Convert string to lower characters. .. _TOUPPER: -:: +.. code-block:: cmake string(TOUPPER <string1> <output variable>) @@ -231,7 +231,7 @@ Convert string to upper characters. .. _LENGTH: -:: +.. code-block:: cmake string(LENGTH <string> <output variable>) @@ -239,7 +239,7 @@ Store in an output variable a given string's length. .. _SUBSTRING: -:: +.. code-block:: cmake string(SUBSTRING <string> <begin> <length> <output variable>) @@ -253,7 +253,7 @@ If string is shorter than length then end of string is used instead. .. _STRIP: -:: +.. code-block:: cmake string(STRIP <string> <output variable>) @@ -262,7 +262,7 @@ trailing spaces removed. .. _GENEX_STRIP: -:: +.. code-block:: cmake string(GENEX_STRIP <input string> <output variable>) @@ -274,7 +274,7 @@ Comparison .. _COMPARE: -:: +.. code-block:: cmake string(COMPARE LESS <string1> <string2> <output variable>) string(COMPARE GREATER <string1> <string2> <output variable>) @@ -292,7 +292,7 @@ Hashing .. _`HASH`: -:: +.. code-block:: cmake string(<HASH> <output variable> <input>) @@ -325,7 +325,7 @@ Generation .. _ASCII: -:: +.. code-block:: cmake string(ASCII <number> [<number> ...] <output variable>) @@ -333,7 +333,7 @@ Convert all numbers into corresponding ASCII characters. .. _CONFIGURE: -:: +.. code-block:: cmake string(CONFIGURE <string1> <output variable> [@ONLY] [ESCAPE_QUOTES]) @@ -342,7 +342,7 @@ Transform a string like :command:`configure_file` transforms a file. .. _MAKE_C_IDENTIFIER: -:: +.. code-block:: cmake string(MAKE_C_IDENTIFIER <input string> <output variable>) @@ -353,7 +353,7 @@ the result. .. _RANDOM: -:: +.. code-block:: cmake string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>] [RANDOM_SEED <seed>] <output variable>) @@ -366,7 +366,7 @@ random number generator. .. _TIMESTAMP: -:: +.. code-block:: cmake string(TIMESTAMP <output variable> [<format string>] [UTC]) @@ -421,7 +421,7 @@ If no explicit ``<format string>`` is given it will default to: .. _UUID: -:: +.. code-block:: cmake string(UUID <output variable> NAMESPACE <namespace> NAME <name> TYPE <MD5|SHA1> [UPPER]) diff --git a/Help/command/subdir_depends.rst b/Help/command/subdir_depends.rst index 5676c8f..0c1b3c1 100644 --- a/Help/command/subdir_depends.rst +++ b/Help/command/subdir_depends.rst @@ -1,7 +1,7 @@ subdir_depends -------------- -Disallowed. See CMake Policy :policy:`CMP0029`. +Disallowed since version 3.0. See CMake Policy :policy:`CMP0029`. Does nothing. diff --git a/Help/command/subdirs.rst b/Help/command/subdirs.rst index 43b87d4..530951b 100644 --- a/Help/command/subdirs.rst +++ b/Help/command/subdirs.rst @@ -1,7 +1,9 @@ subdirs ------- -Deprecated. Use the :command:`add_subdirectory` command instead. +.. deprecated:: 3.0 + + Use the :command:`add_subdirectory` command instead. Add a list of subdirectories to the build. diff --git a/Help/command/target_compile_definitions.rst b/Help/command/target_compile_definitions.rst index a740117..9e9c690 100644 --- a/Help/command/target_compile_definitions.rst +++ b/Help/command/target_compile_definitions.rst @@ -3,13 +3,13 @@ target_compile_definitions Add compile definitions to a target. -:: +.. code-block:: cmake target_compile_definitions(<target> <INTERFACE|PUBLIC|PRIVATE> [items1...] [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) -Specify compile definitions to use when compiling a given ``<target>``. The +Specifies compile definitions to use when compiling a given ``<target>``. The named ``<target>`` must have been created by a command such as :command:`add_executable` or :command:`add_library` and must not be an :ref:`ALIAS target <Alias Targets>`. diff --git a/Help/command/target_compile_features.rst b/Help/command/target_compile_features.rst index bf413bf..9271cd5 100644 --- a/Help/command/target_compile_features.rst +++ b/Help/command/target_compile_features.rst @@ -3,11 +3,11 @@ target_compile_features Add expected compiler features to a target. -:: +.. code-block:: cmake target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...]) -Specify compiler features required when compiling a given target. If the +Specifies compiler features required when compiling a given target. If the feature is not listed in the :variable:`CMAKE_C_COMPILE_FEATURES` variable or :variable:`CMAKE_CXX_COMPILE_FEATURES` variable, then an error will be reported by CMake. If the use of the feature requires diff --git a/Help/command/target_compile_options.rst b/Help/command/target_compile_options.rst index 88b7f15..c26c926 100644 --- a/Help/command/target_compile_options.rst +++ b/Help/command/target_compile_options.rst @@ -3,13 +3,13 @@ target_compile_options Add compile options to a target. -:: +.. code-block:: cmake target_compile_options(<target> [BEFORE] <INTERFACE|PUBLIC|PRIVATE> [items1...] [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) -Specify compile options to use when compiling a given target. The +Specifies compile options to use when compiling a given target. The named ``<target>`` must have been created by a command such as :command:`add_executable` or :command:`add_library` and must not be an :ref:`ALIAS target <Alias Targets>`. diff --git a/Help/command/target_include_directories.rst b/Help/command/target_include_directories.rst index e71be64..660e15c 100644 --- a/Help/command/target_include_directories.rst +++ b/Help/command/target_include_directories.rst @@ -3,13 +3,13 @@ target_include_directories Add include directories to a target. -:: +.. code-block:: cmake target_include_directories(<target> [SYSTEM] [BEFORE] <INTERFACE|PUBLIC|PRIVATE> [items1...] [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) -Specify include directories to use when compiling a given target. +Specifies include directories to use when compiling a given target. The named ``<target>`` must have been created by a command such as :command:`add_executable` or :command:`add_library` and must not be an :ref:`ALIAS target <Alias Targets>`. diff --git a/Help/command/target_link_directories.rst b/Help/command/target_link_directories.rst index b46aac0..76da94d 100644 --- a/Help/command/target_link_directories.rst +++ b/Help/command/target_link_directories.rst @@ -3,13 +3,13 @@ target_link_directories Add link directories to a target. -:: +.. code-block:: cmake target_link_directories(<target> [BEFORE] <INTERFACE|PUBLIC|PRIVATE> [items1...] [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) -Specify the paths in which the linker should search for libraries when +Specifies the paths in which the linker should search for libraries when linking a given target. Each item can be an absolute or relative path, with the latter being interpreted as relative to the current source directory. These items will be added to the link command. diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index 58f312e..c5e4f9f 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -14,7 +14,9 @@ Overview ^^^^^^^^ This command has several signatures as detailed in subsections below. -All of them have the general form:: +All of them have the general form + +.. code-block:: cmake target_link_libraries(<target> ... <item>... ...) @@ -92,7 +94,7 @@ Each ``<item>`` may be: * **A generator expression**: A ``$<...>`` :manual:`generator expression <cmake-generator-expressions(7)>` may evaluate to any of the above - items or to a :ref:`;-list <CMake Language Lists>` of them. + items or to a :ref:`semicolon-separated list <CMake Language Lists>` of them. If the ``...`` contains any ``;`` characters, e.g. after evaluation of a ``${list}`` variable, be sure to use an explicitly quoted argument ``"$<...>"`` so that this command receives it as a @@ -128,7 +130,7 @@ buildsystem properties. Libraries for a Target and/or its Dependents ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake target_link_libraries(<target> <PRIVATE|PUBLIC|INTERFACE> <item>... @@ -145,7 +147,7 @@ used for linking ``<target>``. Libraries for both a Target and its Dependents ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake target_link_libraries(<target> <item>...) @@ -163,7 +165,7 @@ exclusively by this signature private. Libraries for a Target and/or its Dependents (Legacy) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake target_link_libraries(<target> <LINK_PRIVATE|LINK_PUBLIC> <lib>... @@ -185,7 +187,7 @@ made part of the :prop_tgt:`INTERFACE_LINK_LIBRARIES`. If policy Libraries for Dependents Only (Legacy) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...) diff --git a/Help/command/target_link_options.rst b/Help/command/target_link_options.rst index 8f47180..285455a 100644 --- a/Help/command/target_link_options.rst +++ b/Help/command/target_link_options.rst @@ -3,13 +3,13 @@ target_link_options Add link options to a target. -:: +.. code-block:: cmake target_link_options(<target> [BEFORE] <INTERFACE|PUBLIC|PRIVATE> [items1...] [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) -Specify link options to use when linking a given target. The +Specifies link options to use when linking a given target. The named ``<target>`` must have been created by a command such as :command:`add_executable` or :command:`add_library` and must not be an :ref:`ALIAS target <Alias Targets>`. @@ -37,6 +37,6 @@ with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem properties. -.. include:: LINK_OPTIONS_LINKER.txt - .. include:: OPTIONS_SHELL.txt + +.. include:: LINK_OPTIONS_LINKER.txt diff --git a/Help/command/target_sources.rst b/Help/command/target_sources.rst index 5dd8d86..27e737b 100644 --- a/Help/command/target_sources.rst +++ b/Help/command/target_sources.rst @@ -3,13 +3,13 @@ target_sources Add sources to a target. -:: +.. code-block:: cmake target_sources(<target> <INTERFACE|PUBLIC|PRIVATE> [items1...] [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) -Specify sources to use when compiling a given target. Relative +Specifies sources to use when compiling a given target. Relative source file paths are interpreted as being relative to the current source directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`). The named ``<target>`` must have been created by a command such as diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index 66ea3d7..28caa7c 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -10,7 +10,7 @@ Try building some code. Try Compiling Whole Projects ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake try_compile(RESULT_VAR <bindir> <srcdir> <projectName> [<targetName>] [CMAKE_FLAGS <flags>...] @@ -28,7 +28,7 @@ below for the meaning of other options. Try Compiling Source Files ^^^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake try_compile(RESULT_VAR <bindir> <srcfile|SOURCES srcfile...> [CMAKE_FLAGS <flags>...] @@ -47,7 +47,9 @@ returned in ``RESULT_VAR``. In this form the user need only supply one or more source files that include a definition for ``main``. CMake will create a ``CMakeLists.txt`` file to build -the source(s) as an executable that looks something like this:: +the source(s) as an executable that looks something like this: + +.. code-block:: cmake add_definitions(<expanded COMPILE_DEFINITIONS from caller>) include_directories(${INCLUDE_DIRECTORIES}) diff --git a/Help/command/try_run.rst b/Help/command/try_run.rst index e3bd57d..dfa0bf9 100644 --- a/Help/command/try_run.rst +++ b/Help/command/try_run.rst @@ -10,7 +10,7 @@ Try compiling and then running some code. Try Compiling and Running Source Files ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake try_run(RUN_RESULT_VAR COMPILE_RESULT_VAR bindir srcfile [CMAKE_FLAGS <flags>...] diff --git a/Help/command/unset.rst b/Help/command/unset.rst index c19dd31..1a5e49f 100644 --- a/Help/command/unset.rst +++ b/Help/command/unset.rst @@ -3,7 +3,7 @@ unset Unset a variable, cache variable, or environment variable. -:: +.. code-block:: cmake unset(<variable> [CACHE | PARENT_SCOPE]) @@ -24,7 +24,7 @@ for further details. ``<variable>`` can be an environment variable such as: -:: +.. code-block:: cmake unset(ENV{LD_LIBRARY_PATH}) diff --git a/Help/command/use_mangled_mesa.rst b/Help/command/use_mangled_mesa.rst index 6f4d7ac..4d9e12b 100644 --- a/Help/command/use_mangled_mesa.rst +++ b/Help/command/use_mangled_mesa.rst @@ -1,7 +1,7 @@ use_mangled_mesa ---------------- -Disallowed. See CMake Policy :policy:`CMP0030`. +Disallowed since version 3.0. See CMake Policy :policy:`CMP0030`. Copy mesa headers for use in combination with system GL. diff --git a/Help/command/utility_source.rst b/Help/command/utility_source.rst index ee34492..94d6a4e 100644 --- a/Help/command/utility_source.rst +++ b/Help/command/utility_source.rst @@ -1,7 +1,7 @@ utility_source -------------- -Disallowed. See CMake Policy :policy:`CMP0034`. +Disallowed since version 3.0. See CMake Policy :policy:`CMP0034`. Specify the source tree of a third-party utility. diff --git a/Help/command/variable_requires.rst b/Help/command/variable_requires.rst index 9cf9f3f..b4742a5 100644 --- a/Help/command/variable_requires.rst +++ b/Help/command/variable_requires.rst @@ -1,7 +1,7 @@ variable_requires ----------------- -Disallowed. See CMake Policy :policy:`CMP0035`. +Disallowed since version 3.0. See CMake Policy :policy:`CMP0035`. Use the :command:`if` command instead. diff --git a/Help/command/variable_watch.rst b/Help/command/variable_watch.rst index a2df058..ce69bcf 100644 --- a/Help/command/variable_watch.rst +++ b/Help/command/variable_watch.rst @@ -3,11 +3,13 @@ variable_watch Watch the CMake variable for change. -:: +.. code-block:: cmake - variable_watch(<variable name> [<command to execute>]) + variable_watch(<variable> [<command>]) -If the specified variable changes, the message will be printed about -the variable being changed. If the command is specified, the command -will be executed. The command will receive the following arguments: -COMMAND(<variable> <access> <value> <current list file> <stack>) +If the specified ``<variable>`` changes, a message will be printed +to inform about the change. + +Additionally, if ``<command>`` is given, this command will be executed. +The command will receive the following arguments: +``COMMAND(<variable> <access> <value> <current_list_file> <stack>)`` diff --git a/Help/command/while.rst b/Help/command/while.rst index 7509da3..a4957c1 100644 --- a/Help/command/while.rst +++ b/Help/command/while.rst @@ -3,15 +3,23 @@ while Evaluate a group of commands while a condition is true -:: +.. code-block:: cmake - while(condition) - COMMAND1(ARGS ...) - COMMAND2(ARGS ...) - ... - endwhile(condition) + while(<condition>) + <commands> + endwhile() All commands between while and the matching :command:`endwhile` are recorded without being invoked. Once the :command:`endwhile` is evaluated, the -recorded list of commands is invoked as long as the condition is true. The -condition is evaluated using the same logic as the :command:`if` command. +recorded list of commands is invoked as long as the ``<condition>`` is true. + +The ``<condition>`` has the same syntax and is evaluated using the same logic +as described at length for the :command:`if` command. + +The commands :command:`break` and :command:`continue` provide means to +escape from the normal control flow. + +Per legacy, the :command:`endwhile` command admits +an optional ``<condition>`` argument. +If used, it must be a verbatim repeat of the argument of the opening +``while`` command. diff --git a/Help/command/write_file.rst b/Help/command/write_file.rst index 40e7557..4d476bd 100644 --- a/Help/command/write_file.rst +++ b/Help/command/write_file.rst @@ -1,7 +1,9 @@ write_file ---------- -Deprecated. Use the :command:`file(WRITE)` command instead. +.. deprecated:: 3.0 + + Use the :command:`file(WRITE)` command instead. :: 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-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 76fd3d9..bddf827 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -31,7 +31,9 @@ Logical Expressions 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:: +create conditional output: + +.. code-block:: cmake $<$<CONFIG:Debug>:DEBUG_MODE> @@ -151,14 +153,18 @@ Informational Expressions ========================= These expressions expand to some information. The information may be used -directly, eg:: +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. -These expressions may also may be combined with logical expressions:: +These expressions may also may be combined with logical expressions: + +.. code-block:: cmake $<$<VERSION_LESS:$<CXX_COMPILER_VERSION>,4.2.0>:OLD_COMPILER> @@ -232,7 +238,10 @@ 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. @@ -246,18 +255,24 @@ 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:: +comparison: + +.. 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``. Note that a more-complete use in this situation would require first checking if the INCLUDE_DIRECTORIES -property is non-empty:: +property is non-empty: + +.. code-block:: cmake $<$<BOOL:${prop}>:-I$<JOIN:${prop}, -I>> -where ``${prop}`` refers to a helper variable:: +where ``${prop}`` refers to a helper variable: + +.. code-block:: cmake set(prop "$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>") diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index 71649ba..630a86b 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 ``\``. diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index b7276b6..c0bef08 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 @@ -218,39 +250,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..1651114 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -138,6 +138,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-variables.7.rst b/Help/manual/cmake-variables.7.rst index 9dd36ed..b88c661 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -322,6 +322,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 diff --git a/Help/manual/cpack.1.rst b/Help/manual/cpack.1.rst index 87aa38d..6159d7b 100644 --- a/Help/manual/cpack.1.rst +++ b/Help/manual/cpack.1.rst @@ -29,9 +29,10 @@ Options package(s) in that generator's format according to the details provided in the ``CPackConfig.cmake`` configuration file. A generator is responsible for generating the required inputs for a particular package system and invoking - that system's package creation tools. Possible generator names are specified - in the :manual:`Generators <cmake-generators(7)>` section of the manual and + that system's package creation tools. All supported generators are specified + in the :manual:`Generators <cpack-generators(7)>` section of the manual and the ``--help`` option lists the generators supported for the target platform. + If this option is not given, the :variable:`CPACK_GENERATOR` variable determines the default set of generators that will be used. diff --git a/Help/module/FindFontconfig.rst b/Help/module/FindFontconfig.rst new file mode 100644 index 0000000..449fe09 --- /dev/null +++ b/Help/module/FindFontconfig.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindFontconfig.cmake diff --git a/Help/module/FindLibinput.rst b/Help/module/FindLibinput.rst new file mode 100644 index 0000000..a8ca0b0 --- /dev/null +++ b/Help/module/FindLibinput.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindLibinput.cmake diff --git a/Help/policy/CMP0049.rst b/Help/policy/CMP0049.rst index a3ce4b1..291bf57 100644 --- a/Help/policy/CMP0049.rst +++ b/Help/policy/CMP0049.rst @@ -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 diff --git a/Help/policy/CMP0082.rst b/Help/policy/CMP0082.rst new file mode 100644 index 0000000..7b2ef04 --- /dev/null +++ b/Help/policy/CMP0082.rst @@ -0,0 +1,24 @@ +CMP0082 +------- + +Install rules from :command:`add_subdirectory` calls are interleaved with +those in caller. + +CMake 3.13 and lower ran the install rules from :command:`add_subdirectory` +after all other install rules, even if :command:`add_subdirectory` was called +before the other install rules. CMake 3.14 and later interleaves these +:command:`add_subdirectory` install rules with the others so that they are +run in the order they are declared. + +The ``OLD`` behavior for this policy is to run the install rules from +:command:`add_subdirectory` after the other install rules. The ``NEW`` +behavior for this policy is to run all install rules in the order they are +declared. + +This policy was introduced in CMake version 3.14. Unlike most policies, +CMake version |release| does *not* warn by default when this policy +is not set and simply uses OLD behavior. See documentation of the +:variable:`CMAKE_POLICY_WARNING_CMP0082 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/prop_dir/BUILDSYSTEM_TARGETS.rst b/Help/prop_dir/BUILDSYSTEM_TARGETS.rst index da907cb..04bb56e 100644 --- a/Help/prop_dir/BUILDSYSTEM_TARGETS.rst +++ b/Help/prop_dir/BUILDSYSTEM_TARGETS.rst @@ -2,7 +2,7 @@ BUILDSYSTEM_TARGETS ------------------- This read-only directory property contains a -:ref:`;-list <CMake Language Lists>` of buildsystem targets added in the +:ref:`semicolon-separated list <CMake Language Lists>` of buildsystem targets added in the directory by calls to the :command:`add_library`, :command:`add_executable`, and :command:`add_custom_target` commands. The list does not include any :ref:`Imported Targets` or :ref:`Alias Targets`, but does include diff --git a/Help/prop_dir/COMPILE_OPTIONS.rst b/Help/prop_dir/COMPILE_OPTIONS.rst index 877deb0..48e8b9b 100644 --- a/Help/prop_dir/COMPILE_OPTIONS.rst +++ b/Help/prop_dir/COMPILE_OPTIONS.rst @@ -3,7 +3,7 @@ COMPILE_OPTIONS List of options to pass to the compiler. -This property holds a :ref:`;-list <CMake Language Lists>` of options +This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of options given so far to the :command:`add_compile_options` command. This property is used to initialize the :prop_tgt:`COMPILE_OPTIONS` target diff --git a/Help/prop_dir/LINK_DIRECTORIES.rst b/Help/prop_dir/LINK_DIRECTORIES.rst index f9fb815..44dc230 100644 --- a/Help/prop_dir/LINK_DIRECTORIES.rst +++ b/Help/prop_dir/LINK_DIRECTORIES.rst @@ -3,7 +3,7 @@ LINK_DIRECTORIES List of linker search directories. -This property holds a :ref:`;-list <CMake Language Lists>` of directories +This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of directories and is typically populated using the :command:`link_directories` command. It gets its initial value from its parent directory, if it has one. diff --git a/Help/prop_dir/LINK_OPTIONS.rst b/Help/prop_dir/LINK_OPTIONS.rst index 15c555f..54ac6dd 100644 --- a/Help/prop_dir/LINK_OPTIONS.rst +++ b/Help/prop_dir/LINK_OPTIONS.rst @@ -4,7 +4,7 @@ LINK_OPTIONS List of options to use for the link step of shared library, module and executable targets. -This property holds a :ref:`;-list <CMake Language Lists>` of options +This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of options given so far to the :command:`add_link_options` command. This property is used to initialize the :prop_tgt:`LINK_OPTIONS` target diff --git a/Help/prop_dir/SUBDIRECTORIES.rst b/Help/prop_dir/SUBDIRECTORIES.rst index 2c2ea77..6a0ac80 100644 --- a/Help/prop_dir/SUBDIRECTORIES.rst +++ b/Help/prop_dir/SUBDIRECTORIES.rst @@ -2,7 +2,7 @@ SUBDIRECTORIES -------------- This read-only directory property contains a -:ref:`;-list <CMake Language Lists>` of subdirectories processed so far by +:ref:`semicolon-separated list <CMake Language Lists>` of subdirectories processed so far by the :command:`add_subdirectory` or :command:`subdirs` commands. Each entry is the absolute path to the source directory (containing the ``CMakeLists.txt`` file). This is suitable to pass to the :command:`get_property` command diff --git a/Help/prop_dir/TESTS.rst b/Help/prop_dir/TESTS.rst index 91acd3e..56e230e 100644 --- a/Help/prop_dir/TESTS.rst +++ b/Help/prop_dir/TESTS.rst @@ -3,5 +3,5 @@ TESTS List of tests. -This read-only property holds a :ref:`;-list <CMake Language Lists>` of tests +This read-only property holds a :ref:`semicolon-separated list <CMake Language Lists>` of tests defined so far, in the current directory, by the :command:`add_test` command. diff --git a/Help/prop_sf/COMPILE_OPTIONS.rst b/Help/prop_sf/COMPILE_OPTIONS.rst index 3b2bc8d..7e48271 100644 --- a/Help/prop_sf/COMPILE_OPTIONS.rst +++ b/Help/prop_sf/COMPILE_OPTIONS.rst @@ -3,7 +3,7 @@ COMPILE_OPTIONS List of additional options to pass to the compiler. -This property holds a :ref:`;-list <CMake Language Lists>` of options +This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of options and will be added to the list of compile flags when this source file builds. Use :prop_sf:`COMPILE_DEFINITIONS` to pass additional preprocessor definitions and :prop_sf:`INCLUDE_DIRECTORIES` to pass diff --git a/Help/prop_sf/INCLUDE_DIRECTORIES.rst b/Help/prop_sf/INCLUDE_DIRECTORIES.rst index 55780e5..23de70e 100644 --- a/Help/prop_sf/INCLUDE_DIRECTORIES.rst +++ b/Help/prop_sf/INCLUDE_DIRECTORIES.rst @@ -3,7 +3,7 @@ INCLUDE_DIRECTORIES List of preprocessor include file search directories. -This property holds a :ref:`;-list <CMake Language Lists>` of paths +This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of paths and will be added to the list of include directories when this source file builds. These directories will take precedence over directories defined at target level except for :generator:`Xcode` generator due to technical diff --git a/Help/prop_sf/OBJECT_DEPENDS.rst b/Help/prop_sf/OBJECT_DEPENDS.rst index 1d24960..aaff956 100644 --- a/Help/prop_sf/OBJECT_DEPENDS.rst +++ b/Help/prop_sf/OBJECT_DEPENDS.rst @@ -3,7 +3,7 @@ OBJECT_DEPENDS Additional files on which a compiled object file depends. -Specifies a :ref:`;-list <CMake Language Lists>` of full-paths to +Specifies a :ref:`semicolon-separated list <CMake Language Lists>` of full-paths to files on which any object files compiled from this source file depend. On :ref:`Makefile Generators` and the :generator:`Ninja` generator an object file will be recompiled if any of the named files is newer than it. diff --git a/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst b/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst index a9a0ecf..5329bba 100644 --- a/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst +++ b/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst @@ -1,7 +1,7 @@ AUTOMOC_MACRO_NAMES ------------------- -A :ref:`;-list <CMake Language Lists>` list of macro names used by +A :ref:`semicolon-separated list <CMake Language Lists>` list of macro names used by :prop_tgt:`AUTOMOC` to determine if a C++ file needs to be processed by ``moc``. This property is only used if the :prop_tgt:`AUTOMOC` property is ``ON`` diff --git a/Help/prop_tgt/BUILD_RPATH.rst b/Help/prop_tgt/BUILD_RPATH.rst index 27393f5..13c9c1d 100644 --- a/Help/prop_tgt/BUILD_RPATH.rst +++ b/Help/prop_tgt/BUILD_RPATH.rst @@ -1,7 +1,7 @@ BUILD_RPATH ----------- -A :ref:`;-list <CMake Language Lists>` specifying runtime path (``RPATH``) +A :ref:`semicolon-separated list <CMake Language Lists>` specifying runtime path (``RPATH``) entries to add to binaries linked in the build tree (for platforms that support it). The entries will *not* be used for binaries in the install tree. See also the :prop_tgt:`INSTALL_RPATH` target property. diff --git a/Help/prop_tgt/BUILD_RPATH_USE_ORIGIN.rst b/Help/prop_tgt/BUILD_RPATH_USE_ORIGIN.rst new file mode 100644 index 0000000..511de7a --- /dev/null +++ b/Help/prop_tgt/BUILD_RPATH_USE_ORIGIN.rst @@ -0,0 +1,24 @@ +BUILD_RPATH_USE_ORIGIN +---------------------- + +Whether to use relative paths for the build ``RPATH``. + +This property is initialized by the value of the variable +:variable:`CMAKE_BUILD_RPATH_USE_ORIGIN`. + +On platforms that support runtime paths (``RPATH``) with the +``$ORIGIN`` token, setting this property to ``TRUE`` enables relative +paths in the build ``RPATH`` for executables that point to shared +libraries in the same build tree. + +Normally the build ``RPATH`` of an executable contains absolute paths +to the directory of shared libraries. Directories contained within the +build tree can be made relative to enable relocatable builds and to +help achieving reproducible builds by omitting the build directory +from the build environment. + +This property has no effect on platforms that do not support the +``$ORIGIN`` token in ``RPATH``, or when the :variable:`CMAKE_SKIP_RPATH` +variable is set. The runtime path set through the +:prop_tgt:`BUILD_RPATH` target property is also unaffected by this +property. diff --git a/Help/prop_tgt/COMPILE_OPTIONS.rst b/Help/prop_tgt/COMPILE_OPTIONS.rst index 892ac23..0cd6836 100644 --- a/Help/prop_tgt/COMPILE_OPTIONS.rst +++ b/Help/prop_tgt/COMPILE_OPTIONS.rst @@ -3,7 +3,7 @@ COMPILE_OPTIONS List of options to pass to the compiler. -This property holds a :ref:`;-list <CMake Language Lists>` of options +This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of options specified so far for its target. Use the :command:`target_compile_options` command to append more options. diff --git a/Help/prop_tgt/IMPORTED_OBJECTS.rst b/Help/prop_tgt/IMPORTED_OBJECTS.rst index 222e6cc..50a329f 100644 --- a/Help/prop_tgt/IMPORTED_OBJECTS.rst +++ b/Help/prop_tgt/IMPORTED_OBJECTS.rst @@ -1,7 +1,7 @@ IMPORTED_OBJECTS ---------------- -:ref:`;-list <CMake Language Lists>` of absolute paths to the object +A :ref:`semicolon-separated list <CMake Language Lists>` of absolute paths to the object files on disk for an :ref:`imported <Imported targets>` :ref:`object library <object libraries>`. diff --git a/Help/prop_tgt/LANG_CLANG_TIDY.rst b/Help/prop_tgt/LANG_CLANG_TIDY.rst index 2887e23..2bfef66 100644 --- a/Help/prop_tgt/LANG_CLANG_TIDY.rst +++ b/Help/prop_tgt/LANG_CLANG_TIDY.rst @@ -3,7 +3,7 @@ This property is implemented only when ``<LANG>`` is ``C`` or ``CXX``. -Specify a :ref:`;-list <CMake Language Lists>` containing a command +Specify a :ref:`semicolon-separated list <CMake Language Lists>` containing a command line for the ``clang-tidy`` tool. The :ref:`Makefile Generators` and the :generator:`Ninja` generator will run this tool along with the compiler and report a warning if the tool reports any problems. diff --git a/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst b/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst index b63d6d7..23af503 100644 --- a/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst +++ b/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst @@ -4,7 +4,7 @@ This property is implemented only when ``<LANG>`` is ``C``, ``CXX``, ``Fortran``, or ``CUDA``. -Specify a :ref:`;-list <CMake Language Lists>` containing a command line +Specify a :ref:`semicolon-separated list <CMake Language Lists>` containing a command line for a compiler launching tool. The :ref:`Makefile Generators` and the :generator:`Ninja` generator will run this tool and pass the compiler and its arguments to the tool. Some example tools are distcc and ccache. diff --git a/Help/prop_tgt/LANG_CPPCHECK.rst b/Help/prop_tgt/LANG_CPPCHECK.rst index 5f8be00..60785d0 100644 --- a/Help/prop_tgt/LANG_CPPCHECK.rst +++ b/Help/prop_tgt/LANG_CPPCHECK.rst @@ -3,10 +3,12 @@ This property is supported only when ``<LANG>`` is ``C`` or ``CXX``. -Specify a :ref:`;-list <CMake Language Lists>` containing a command line +Specify a :ref:`semicolon-separated list <CMake Language Lists>` containing a command line for the ``cppcheck`` static analysis tool. The :ref:`Makefile Generators` and the :generator:`Ninja` generator will run ``cppcheck`` along with the -compiler and report any problems. +compiler and report any problems. If the command-line specifies the +exit code options to ``cppcheck`` then the build will fail if the +tool returns non-zero. This property is initialized by the value of the :variable:`CMAKE_<LANG>_CPPCHECK` variable if it is set when a target is diff --git a/Help/prop_tgt/LANG_CPPLINT.rst b/Help/prop_tgt/LANG_CPPLINT.rst index 14f47d4..9944c88 100644 --- a/Help/prop_tgt/LANG_CPPLINT.rst +++ b/Help/prop_tgt/LANG_CPPLINT.rst @@ -3,7 +3,7 @@ This property is supported only when ``<LANG>`` is ``C`` or ``CXX``. -Specify a :ref:`;-list <CMake Language Lists>` containing a command line +Specify a :ref:`semicolon-separated list <CMake Language Lists>` containing a command line for the ``cpplint`` style checker. The :ref:`Makefile Generators` and the :generator:`Ninja` generator will run ``cpplint`` along with the compiler and report any problems. diff --git a/Help/prop_tgt/LANG_INCLUDE_WHAT_YOU_USE.rst b/Help/prop_tgt/LANG_INCLUDE_WHAT_YOU_USE.rst index 26f6d16..35220e4 100644 --- a/Help/prop_tgt/LANG_INCLUDE_WHAT_YOU_USE.rst +++ b/Help/prop_tgt/LANG_INCLUDE_WHAT_YOU_USE.rst @@ -3,7 +3,7 @@ This property is implemented only when ``<LANG>`` is ``C`` or ``CXX``. -Specify a :ref:`;-list <CMake Language Lists>` containing a command +Specify a :ref:`semicolon-separated list <CMake Language Lists>` containing a command line for the ``include-what-you-use`` tool. The :ref:`Makefile Generators` and the :generator:`Ninja` generator will run this tool along with the compiler and report a warning if the tool reports any problems. diff --git a/Help/prop_tgt/LINK_DIRECTORIES.rst b/Help/prop_tgt/LINK_DIRECTORIES.rst index 085a701..c2905b3 100644 --- a/Help/prop_tgt/LINK_DIRECTORIES.rst +++ b/Help/prop_tgt/LINK_DIRECTORIES.rst @@ -4,7 +4,7 @@ LINK_DIRECTORIES List of directories to use for the link step of shared library, module and executable targets. -This property holds a :ref:`;-list <CMake Language Lists>` of directories +This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of directories specified so far for its target. Use the :command:`target_link_directories` command to append more search directories. diff --git a/Help/prop_tgt/LINK_OPTIONS.rst b/Help/prop_tgt/LINK_OPTIONS.rst index bd5e937..2a05ea7 100644 --- a/Help/prop_tgt/LINK_OPTIONS.rst +++ b/Help/prop_tgt/LINK_OPTIONS.rst @@ -6,7 +6,7 @@ and executable targets. Targets that are static libraries need to use the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property. -This property holds a :ref:`;-list <CMake Language Lists>` of options +This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of options specified so far for its target. Use the :command:`target_link_options` command to append more options. diff --git a/Help/prop_tgt/STATIC_LIBRARY_OPTIONS.rst b/Help/prop_tgt/STATIC_LIBRARY_OPTIONS.rst index 6e03185..d05fda4 100644 --- a/Help/prop_tgt/STATIC_LIBRARY_OPTIONS.rst +++ b/Help/prop_tgt/STATIC_LIBRARY_OPTIONS.rst @@ -5,7 +5,7 @@ Archiver (or MSVC librarian) flags for a static library target. Targets that are shared libraries, modules, or executables need to use the :prop_tgt:`LINK_OPTIONS` target property. -This property holds a :ref:`;-list <CMake Language Lists>` of options +This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of options specified so far for its target. Use :command:`set_target_properties` or :command:`set_property` commands to set its content. diff --git a/Help/prop_tgt/VS_SDK_REFERENCES.rst b/Help/prop_tgt/VS_SDK_REFERENCES.rst index 769a0d1..99987f5 100644 --- a/Help/prop_tgt/VS_SDK_REFERENCES.rst +++ b/Help/prop_tgt/VS_SDK_REFERENCES.rst @@ -2,6 +2,6 @@ VS_SDK_REFERENCES ----------------- Visual Studio project SDK references. -Specify a :ref:`;-list <CMake Language Lists>` of SDK references +Specify a :ref:`semicolon-separated list <CMake Language Lists>` of SDK references to be added to a generated Visual Studio project, e.g. ``Microsoft.AdMediatorWindows81, Version=1.0``. diff --git a/Help/release/3.6.rst b/Help/release/3.6.rst index c796d70..b2403cf 100644 --- a/Help/release/3.6.rst +++ b/Help/release/3.6.rst @@ -251,7 +251,7 @@ Deprecated and Removed Features Users that keep some ``<prefix>/bin`` directories in the ``PATH`` just for their tools do not necessarily want any supporting ``<prefix>/lib`` directories searched. One may set the ``CMAKE_PREFIX_PATH`` environment - variable with a :ref:`;-list <CMake Language Lists>` of prefixes that are + variable with a :ref:`semicolon-separated list <CMake Language Lists>` of prefixes that are to be searched. * The :generator:`Visual Studio 7 .NET 2003` generator is now diff --git a/Help/release/dev/0-sample-topic.rst b/Help/release/dev/0-sample-topic.rst new file mode 100644 index 0000000..e4cc01e --- /dev/null +++ b/Help/release/dev/0-sample-topic.rst @@ -0,0 +1,7 @@ +0-sample-topic +-------------- + +* This is a sample release note for the change in a topic. + Developers should add similar notes for each topic branch + making a noteworthy change. Each document should be named + and titled to match the topic name to avoid merge conflicts. diff --git a/Help/release/dev/ExternalProject-log-options.rst b/Help/release/dev/ExternalProject-log-options.rst new file mode 100644 index 0000000..88bc799 --- /dev/null +++ b/Help/release/dev/ExternalProject-log-options.rst @@ -0,0 +1,8 @@ +ExternalProject-log-options +--------------------------- + +* The :module:`ExternalProject` module :command:`ExternalProject_Add` command + gained ``LOG_DIR`` and ``LOG_MERGED_STDOUTERR`` options to control logging. + +* The :module:`ExternalProject` module :command:`ExternalProject_Add` command + gained ``LOG_PATCH`` to optionally log the patch step. diff --git a/Help/release/dev/FindGDAL-target.rst b/Help/release/dev/FindGDAL-target.rst new file mode 100644 index 0000000..b121a72 --- /dev/null +++ b/Help/release/dev/FindGDAL-target.rst @@ -0,0 +1,4 @@ +FindGDAL-target +--------------- + +* The :module:`FindGDAL` module now provides an imported target. diff --git a/Help/release/dev/FindMatlab-2018a-API.rst b/Help/release/dev/FindMatlab-2018a-API.rst new file mode 100644 index 0000000..1063411 --- /dev/null +++ b/Help/release/dev/FindMatlab-2018a-API.rst @@ -0,0 +1,7 @@ +FindMatlab-2018a-API +-------------------- + +* The :module:`FindMatlab` module gained new options ``R2017b`` and + ``R2018a`` to specify the MEX API version to use; these options + mirror the new options to the ``mex`` command in MATLAB R2018a. + The option ``MX_LIBRARY`` is no longer needed. diff --git a/Help/release/dev/better-empty-list-behavior.rst b/Help/release/dev/better-empty-list-behavior.rst new file mode 100644 index 0000000..cd864f4 --- /dev/null +++ b/Help/release/dev/better-empty-list-behavior.rst @@ -0,0 +1,9 @@ +better-empty-list-behavior +-------------------------- + +* The :command:`list` operations ``REMOVE_ITEM``, ``REMOVE_DUPLICATES``, + ``SORT``, ``REVERSE``, and ``FILTER`` all now accept a non-existent variable + as the list since these operations on empty lists is also the empty list. + +* The :command:`list` operation ``REMOVE_AT`` now indicates that the given + indices are invalid for a non-existent variable or empty list. diff --git a/Help/release/dev/cppcheck-exit-code.rst b/Help/release/dev/cppcheck-exit-code.rst new file mode 100644 index 0000000..d66c762 --- /dev/null +++ b/Help/release/dev/cppcheck-exit-code.rst @@ -0,0 +1,6 @@ +cppcheck-exit-code +------------------ + +* When using cppcheck via the :variable:`CMAKE_<LANG>_CPPCHECK` variable + or :prop_tgt:`<LANG>_CPPCHECK` property, the build will now fail if + ``cppcheck`` returns non-zero as configured by its command-line options. diff --git a/Help/release/dev/ctest-done.rst b/Help/release/dev/ctest-done.rst new file mode 100644 index 0000000..9ec0e24 --- /dev/null +++ b/Help/release/dev/ctest-done.rst @@ -0,0 +1,5 @@ +ctest-done +---------- + +* The :command:`ctest_submit` command learned a new ``Done`` part that can be used + to inform CDash that a build is complete and that no more parts will be uploaded. diff --git a/Help/release/dev/find_fontconfig.rst b/Help/release/dev/find_fontconfig.rst new file mode 100644 index 0000000..4ae18c9 --- /dev/null +++ b/Help/release/dev/find_fontconfig.rst @@ -0,0 +1,6 @@ +find_fontconfig +--------------- + +* The :module:`FindFontconfig` module was added to find `fontconfig`_. + +.. _`fontconfig`: https://www.freedesktop.org/wiki/Software/fontconfig/ diff --git a/Help/release/dev/find_libinput.rst b/Help/release/dev/find_libinput.rst new file mode 100644 index 0000000..ebb9e7a --- /dev/null +++ b/Help/release/dev/find_libinput.rst @@ -0,0 +1,6 @@ +find_libinput +------------- + +* The :module:`FindLibinput` module was added to find `libinput`_. + +.. _`libinput`: https://www.freedesktop.org/wiki/Software/libinput/ diff --git a/Help/release/dev/install-subdirectory-order.rst b/Help/release/dev/install-subdirectory-order.rst new file mode 100644 index 0000000..c52e617 --- /dev/null +++ b/Help/release/dev/install-subdirectory-order.rst @@ -0,0 +1,5 @@ +install-subdirectory-order +-------------------------- + +* Install rules under :command:`add_subdirectory` now interleave with those in + the calling directory. See policy :policy:`CMP0082` for details. diff --git a/Help/release/dev/relative-rpath.rst b/Help/release/dev/relative-rpath.rst new file mode 100644 index 0000000..5c62b10 --- /dev/null +++ b/Help/release/dev/relative-rpath.rst @@ -0,0 +1,8 @@ +relative-rpath +-------------- + +* A :variable:`CMAKE_BUILD_RPATH_USE_ORIGIN` variable and corresponding + :prop_tgt:`BUILD_RPATH_USE_ORIGIN` target property were added to + enable use of relative runtime paths (RPATHs). This helps achieving + relocatable and reproducible builds that are invariant of the build + directory. diff --git a/Help/release/index.rst b/Help/release/index.rst index fbe4cf6..7ef3a8e 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -7,6 +7,8 @@ CMake Release Notes This file should include the adjacent "dev.txt" file in development versions but not in release versions. +.. include:: dev.txt + Releases ======== diff --git a/Help/variable/CMAKE_APPBUNDLE_PATH.rst b/Help/variable/CMAKE_APPBUNDLE_PATH.rst index c1f0951..1c7ca51 100644 --- a/Help/variable/CMAKE_APPBUNDLE_PATH.rst +++ b/Help/variable/CMAKE_APPBUNDLE_PATH.rst @@ -1,6 +1,6 @@ CMAKE_APPBUNDLE_PATH -------------------- -:ref:`;-list <CMake Language Lists>` of directories specifying a search path +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path for macOS application bundles used by the :command:`find_program`, and :command:`find_package` commands. diff --git a/Help/variable/CMAKE_AUTOMOC_MACRO_NAMES.rst b/Help/variable/CMAKE_AUTOMOC_MACRO_NAMES.rst index 2c8997b..ba1b9d2 100644 --- a/Help/variable/CMAKE_AUTOMOC_MACRO_NAMES.rst +++ b/Help/variable/CMAKE_AUTOMOC_MACRO_NAMES.rst @@ -1,7 +1,7 @@ CMAKE_AUTOMOC_MACRO_NAMES ---------------------------- -A :ref:`;-list <CMake Language Lists>` list of macro names used by +:ref:`Semicolon-separated list <CMake Language Lists>` list of macro names used by :variable:`CMAKE_AUTOMOC` to determine if a C++ file needs to be processed by ``moc``. diff --git a/Help/variable/CMAKE_BUILD_RPATH.rst b/Help/variable/CMAKE_BUILD_RPATH.rst index f20eb41..f5d53b8 100644 --- a/Help/variable/CMAKE_BUILD_RPATH.rst +++ b/Help/variable/CMAKE_BUILD_RPATH.rst @@ -1,7 +1,7 @@ CMAKE_BUILD_RPATH ----------------- -A :ref:`;-list <CMake Language Lists>` specifying runtime path (``RPATH``) +:ref:`Semicolon-separated list <CMake Language Lists>` specifying runtime path (``RPATH``) entries to add to binaries linked in the build tree (for platforms that support it). The entries will *not* be used for binaries in the install tree. See also the :variable:`CMAKE_INSTALL_RPATH` variable. diff --git a/Help/variable/CMAKE_BUILD_RPATH_USE_ORIGIN.rst b/Help/variable/CMAKE_BUILD_RPATH_USE_ORIGIN.rst new file mode 100644 index 0000000..e34ede6 --- /dev/null +++ b/Help/variable/CMAKE_BUILD_RPATH_USE_ORIGIN.rst @@ -0,0 +1,7 @@ +CMAKE_BUILD_RPATH_USE_ORIGIN +---------------------------- + +Whether to use relative paths for the build ``RPATH``. + +This is used to initialize the :prop_tgt:`BUILD_RPATH_USE_ORIGIN` target +property for all targets, see that property for more details. diff --git a/Help/variable/CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES.rst b/Help/variable/CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES.rst index 768f571..7de50a5 100644 --- a/Help/variable/CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES.rst +++ b/Help/variable/CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES.rst @@ -2,6 +2,6 @@ CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES -------------------------------------- When the ``CUDA`` language has been enabled, this provides a -:ref:`;-list <CMake Language Lists>` of include directories provided +:ref:`semicolon-separated list <CMake Language Lists>` of include directories provided by the CUDA Toolkit. The value may be useful for C++ source files to include CUDA headers. diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH.rst b/Help/variable/CMAKE_FIND_ROOT_PATH.rst index ba2cf31..6172c56 100644 --- a/Help/variable/CMAKE_FIND_ROOT_PATH.rst +++ b/Help/variable/CMAKE_FIND_ROOT_PATH.rst @@ -1,7 +1,7 @@ CMAKE_FIND_ROOT_PATH -------------------- -:ref:`;-list <CMake Language Lists>` of root paths to search on the filesystem. +:ref:`Semicolon-separated list <CMake Language Lists>` of root paths to search on the filesystem. This variable is most useful when cross-compiling. CMake uses the paths in this list as alternative roots to find filesystem items with diff --git a/Help/variable/CMAKE_FRAMEWORK_PATH.rst b/Help/variable/CMAKE_FRAMEWORK_PATH.rst index 04751f8..13ade4e 100644 --- a/Help/variable/CMAKE_FRAMEWORK_PATH.rst +++ b/Help/variable/CMAKE_FRAMEWORK_PATH.rst @@ -1,7 +1,7 @@ CMAKE_FRAMEWORK_PATH -------------------- -:ref:`;-list <CMake Language Lists>` of directories specifying a search path +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path for macOS frameworks used by the :command:`find_library`, :command:`find_package`, :command:`find_path`, and :command:`find_file` commands. diff --git a/Help/variable/CMAKE_IGNORE_PATH.rst b/Help/variable/CMAKE_IGNORE_PATH.rst index 92f3770..4bca34b 100644 --- a/Help/variable/CMAKE_IGNORE_PATH.rst +++ b/Help/variable/CMAKE_IGNORE_PATH.rst @@ -1,7 +1,7 @@ CMAKE_IGNORE_PATH ----------------- -:ref:`;-list <CMake Language Lists>` of directories to be *ignored* by +:ref:`Semicolon-separated list <CMake Language Lists>` of directories to be *ignored* by the :command:`find_program`, :command:`find_library`, :command:`find_file`, and :command:`find_path` commands. This is useful in cross-compiling environments where some system directories contain incompatible but diff --git a/Help/variable/CMAKE_INCLUDE_PATH.rst b/Help/variable/CMAKE_INCLUDE_PATH.rst index e4e7f2c..4918e99 100644 --- a/Help/variable/CMAKE_INCLUDE_PATH.rst +++ b/Help/variable/CMAKE_INCLUDE_PATH.rst @@ -1,7 +1,7 @@ CMAKE_INCLUDE_PATH ------------------ -:ref:`;-list <CMake Language Lists>` of directories specifying a search path +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path for the :command:`find_file` and :command:`find_path` commands. By default it is empty, it is intended to be set by the project. See also :variable:`CMAKE_SYSTEM_INCLUDE_PATH` and :variable:`CMAKE_PREFIX_PATH`. diff --git a/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG.rst b/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG.rst index 0e52282..df51407 100644 --- a/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG.rst +++ b/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG.rst @@ -5,7 +5,7 @@ Defines the syntax of compiler driver option to pass options to the linker tool. It will be used to translate the ``LINKER:`` prefix in the link options (see :command:`add_link_options` and :command:`target_link_options`). -This variable holds a :ref:`;-list <CMake Language Lists>` of tokens. +This variable holds a :ref:`semicolon-separated list <CMake Language Lists>` of tokens. If a space (i.e. " ") is specified as last token, flag and ``LINKER:`` arguments will be specified as separate arguments to the compiler driver. The :variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP` variable can be specified @@ -17,7 +17,7 @@ For example, for ``Clang`` we have: set (CMAKE_C_LINKER_WRAPPER_FLAG "-Xlinker" " ") -Specifying ``"LINKER:-z defs"`` will be transformed in +Specifying ``"LINKER:-z,defs"`` will be transformed in ``-Xlinker -z -Xlinker defs``. For ``GNU GCC``: @@ -27,7 +27,7 @@ For ``GNU GCC``: set (CMAKE_C_LINKER_WRAPPER_FLAG "-Wl,") set (CMAKE_C_LINKER_WRAPPER_FLAG_SEP ",") -Specifying ``"LINKER:-z defs"`` will be transformed in ``-Wl,-z,defs``. +Specifying ``"LINKER:-z,defs"`` will be transformed in ``-Wl,-z,defs``. And for ``SunPro``: @@ -36,4 +36,4 @@ And for ``SunPro``: set (CMAKE_C_LINKER_WRAPPER_FLAG "-Qoption" "ld" " ") set (CMAKE_C_LINKER_WRAPPER_FLAG_SEP ",") -Specifying ``"LINKER:-z defs"`` will be transformed in ``-Qoption ld -z,defs``. +Specifying ``"LINKER:-z,defs"`` will be transformed in ``-Qoption ld -z,defs``. diff --git a/Help/variable/CMAKE_LIBRARY_PATH.rst b/Help/variable/CMAKE_LIBRARY_PATH.rst index b1770dc..8135b65 100644 --- a/Help/variable/CMAKE_LIBRARY_PATH.rst +++ b/Help/variable/CMAKE_LIBRARY_PATH.rst @@ -1,7 +1,7 @@ CMAKE_LIBRARY_PATH ------------------ -:ref:`;-list <CMake Language Lists>` of directories specifying a search path +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path for the :command:`find_library` command. By default it is empty, it is intended to be set by the project. See also :variable:`CMAKE_SYSTEM_LIBRARY_PATH` and :variable:`CMAKE_PREFIX_PATH`. diff --git a/Help/variable/CMAKE_MODULE_PATH.rst b/Help/variable/CMAKE_MODULE_PATH.rst index 6490054..4dcf6b5 100644 --- a/Help/variable/CMAKE_MODULE_PATH.rst +++ b/Help/variable/CMAKE_MODULE_PATH.rst @@ -1,7 +1,7 @@ CMAKE_MODULE_PATH ----------------- -:ref:`;-list <CMake Language Lists>` of directories specifying a search path +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path for CMake modules to be loaded by the :command:`include` or :command:`find_package` commands before checking the default modules that come with CMake. By default it is empty, it is intended to be set by the project. diff --git a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst index aa23b65..d179728 100644 --- a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst +++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst @@ -19,6 +19,8 @@ warn by default: policy :policy:`CMP0066`. * ``CMAKE_POLICY_WARNING_CMP0067`` controls the warning for policy :policy:`CMP0067`. +* ``CMAKE_POLICY_WARNING_CMP0082`` controls the warning for + policy :policy:`CMP0082`. This variable should not be set by a project in CMake code. Project developers running CMake may set this variable in their cache to diff --git a/Help/variable/CMAKE_PREFIX_PATH.rst b/Help/variable/CMAKE_PREFIX_PATH.rst index c2a4a60..1d4fd0b 100644 --- a/Help/variable/CMAKE_PREFIX_PATH.rst +++ b/Help/variable/CMAKE_PREFIX_PATH.rst @@ -1,7 +1,7 @@ CMAKE_PREFIX_PATH ----------------- -:ref:`;-list <CMake Language Lists>` of directories specifying installation +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying installation *prefixes* to be searched by the :command:`find_package`, :command:`find_program`, :command:`find_library`, :command:`find_file`, and :command:`find_path` commands. Each command will add appropriate diff --git a/Help/variable/CMAKE_PROGRAM_PATH.rst b/Help/variable/CMAKE_PROGRAM_PATH.rst index 799e119..2d0c090 100644 --- a/Help/variable/CMAKE_PROGRAM_PATH.rst +++ b/Help/variable/CMAKE_PROGRAM_PATH.rst @@ -1,7 +1,7 @@ CMAKE_PROGRAM_PATH ------------------ -:ref:`;-list <CMake Language Lists>` of directories specifying a search path +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path for the :command:`find_program` command. By default it is empty, it is intended to be set by the project. See also :variable:`CMAKE_SYSTEM_PROGRAM_PATH` and :variable:`CMAKE_PREFIX_PATH`. diff --git a/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst b/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst index 4ad7e33..6afbd33 100644 --- a/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst +++ b/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst @@ -1,7 +1,7 @@ CMAKE_SYSTEM_IGNORE_PATH ------------------------ -:ref:`;-list <CMake Language Lists>` of directories to be *ignored* by +:ref:`Semicolon-separated list <CMake Language Lists>` of directories to be *ignored* by the :command:`find_program`, :command:`find_library`, :command:`find_file`, and :command:`find_path` commands. This is useful in cross-compiling environments where some system directories contain incompatible but diff --git a/Help/variable/CMAKE_SYSTEM_INCLUDE_PATH.rst b/Help/variable/CMAKE_SYSTEM_INCLUDE_PATH.rst index 2c14345..680404e 100644 --- a/Help/variable/CMAKE_SYSTEM_INCLUDE_PATH.rst +++ b/Help/variable/CMAKE_SYSTEM_INCLUDE_PATH.rst @@ -1,7 +1,7 @@ CMAKE_SYSTEM_INCLUDE_PATH ------------------------- -:ref:`;-list <CMake Language Lists>` of directories specifying a search path +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path for the :command:`find_file` and :command:`find_path` commands. By default this contains the standard directories for the current system. It is *not* intended to be modified by the project; use :variable:`CMAKE_INCLUDE_PATH` for diff --git a/Help/variable/CMAKE_SYSTEM_LIBRARY_PATH.rst b/Help/variable/CMAKE_SYSTEM_LIBRARY_PATH.rst index 3969cb9..116832b 100644 --- a/Help/variable/CMAKE_SYSTEM_LIBRARY_PATH.rst +++ b/Help/variable/CMAKE_SYSTEM_LIBRARY_PATH.rst @@ -1,7 +1,7 @@ CMAKE_SYSTEM_LIBRARY_PATH ------------------------- -:ref:`;-list <CMake Language Lists>` of directories specifying a search path +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path for the :command:`find_library` command. By default this contains the standard directories for the current system. It is *not* intended to be modified by the project; use :variable:`CMAKE_LIBRARY_PATH` for this. diff --git a/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst index 38b2f8d..87a9d06 100644 --- a/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst +++ b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst @@ -1,7 +1,7 @@ CMAKE_SYSTEM_PREFIX_PATH ------------------------ -:ref:`;-list <CMake Language Lists>` of directories specifying installation +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying installation *prefixes* to be searched by the :command:`find_package`, :command:`find_program`, :command:`find_library`, :command:`find_file`, and :command:`find_path` commands. Each command will add appropriate diff --git a/Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst b/Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst index cf1b83e..9b70361 100644 --- a/Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst +++ b/Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst @@ -1,7 +1,7 @@ CMAKE_SYSTEM_PROGRAM_PATH ------------------------- -:ref:`;-list <CMake Language Lists>` of directories specifying a search path +:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path for the :command:`find_program` command. By default this contains the standard directories for the current system. It is *not* intended to be modified by the project; use :variable:`CMAKE_PROGRAM_PATH` for this. diff --git a/Help/variable/PackageName_ROOT.rst b/Help/variable/PackageName_ROOT.rst index 4f6c25b..c5b07ae 100644 --- a/Help/variable/PackageName_ROOT.rst +++ b/Help/variable/PackageName_ROOT.rst @@ -9,6 +9,6 @@ prefixes specified in the ``Foo_ROOT`` CMake variable (if set). See policy :policy:`CMP0074`. This variable may hold a single prefix or a -:ref:`;-list <CMake Language Lists>` of multiple prefixes. +:ref:`semicolon-separated list <CMake Language Lists>` of multiple prefixes. See also the :envvar:`<PackageName>_ROOT` environment variable. |