diff options
Diffstat (limited to 'Help')
144 files changed, 2679 insertions, 261 deletions
diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index d421364..4ab4298 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -20,6 +20,7 @@ The first signature is for adding a custom command to produce an output:: [<lang2> depend2] ...] [WORKING_DIRECTORY dir] [COMMENT comment] + [DEPFILE depfile] [VERBATIM] [APPEND] [USES_TERMINAL]) This defines a command to generate specified ``OUTPUT`` file(s). @@ -170,6 +171,12 @@ The options are: If it is a relative path it will be interpreted relative to the build tree directory corresponding to the current source directory. +``DEPFILE`` + Specify a ``.d`` depfile for the :generator:`Ninja` generator. + A ``.d`` file holds dependencies usually emitted by the custom + command itself. + Using ``DEPFILE`` with other generators than Ninja is an error. + Build Events ^^^^^^^^^^^^ diff --git a/Help/command/cmake_parse_arguments.rst b/Help/command/cmake_parse_arguments.rst index 6206611..ec4ffed 100644 --- a/Help/command/cmake_parse_arguments.rst +++ b/Help/command/cmake_parse_arguments.rst @@ -11,6 +11,17 @@ respective options. cmake_parse_arguments(<prefix> <options> <one_value_keywords> <multi_value_keywords> args...) + cmake_parse_arguments(PARSE_ARGV N <prefix> <options> <one_value_keywords> + <multi_value_keywords>) + +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 values to have special characters like ``;`` in them. The ``<options>`` argument contains all options for the respective macro, i.e. keywords which can be used when calling the macro without any value diff --git a/Help/command/ctest_build.rst b/Help/command/ctest_build.rst index e1b7793..55bb4a3 100644 --- a/Help/command/ctest_build.rst +++ b/Help/command/ctest_build.rst @@ -13,6 +13,7 @@ Perform the :ref:`CTest Build Step` as a :ref:`Dashboard Client`. [NUMBER_ERRORS <num-err-var>] [NUMBER_WARNINGS <num-warn-var>] [RETURN_VALUE <result-var>] + [CAPTURE_CMAKE_ERROR <result-var>] ) Build the project and store results in ``Build.xml`` @@ -29,9 +30,11 @@ The options are: :variable:`CTEST_BINARY_DIRECTORY` variable is used. ``APPEND`` - Mark results for append to those previously submitted to a + Mark ``Build.xml`` for append to results previously submitted to a dashboard server since the last :command:`ctest_start` call. Append semantics are defined by the dashboard server in use. + This does *not* cause results to be appended to a ``.xml`` file + produced by a previous call to this command. ``CONFIGURATION <config>`` Specify the build configuration (e.g. ``Debug``). If not @@ -66,6 +69,10 @@ The options are: ``RETURN_VALUE <result-var>`` Store the return value of the native build tool in the given variable. +``CAPTURE_CMAKE_ERROR <result-var>`` + Store in the ``<result-var>`` variable -1 if there are any errors running + the command and prevent ctest from returning non-zero if an error occurs. + ``QUIET`` Suppress any CTest-specific non-error output that would have been printed to the console otherwise. The summary of warnings / errors, diff --git a/Help/command/ctest_configure.rst b/Help/command/ctest_configure.rst index 851c292..2dea07b 100644 --- a/Help/command/ctest_configure.rst +++ b/Help/command/ctest_configure.rst @@ -6,7 +6,8 @@ Perform the :ref:`CTest Configure Step` as a :ref:`Dashboard Client`. :: ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND] - [OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET]) + [OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET] + [CAPTURE_CMAKE_ERROR <result-var>]) Configure the project build tree and record results in ``Configure.xml`` for submission with the :command:`ctest_submit` command. @@ -22,9 +23,11 @@ The options are: :variable:`CTEST_SOURCE_DIRECTORY` variable is used. ``APPEND`` - Mark results for append to those previously submitted to a + Mark ``Configure.xml`` for append to results previously submitted to a dashboard server since the last :command:`ctest_start` call. Append semantics are defined by the dashboard server in use. + This does *not* cause results to be appended to a ``.xml`` file + produced by a previous call to this command. ``OPTIONS <options>`` Specify command-line arguments to pass to the configuration tool. @@ -33,6 +36,10 @@ The options are: Store in the ``<result-var>`` variable the return value of the native configuration tool. +``CAPTURE_CMAKE_ERROR <result-var>`` + Store in the ``<result-var>`` variable -1 if there are any errors running + the command and prevent ctest from returning non-zero if an error occurs. + ``QUIET`` Suppress any CTest-specific non-error messages that would have otherwise been printed to the console. Output from the underlying diff --git a/Help/command/ctest_coverage.rst b/Help/command/ctest_coverage.rst index 12429b9..8d27b9c 100644 --- a/Help/command/ctest_coverage.rst +++ b/Help/command/ctest_coverage.rst @@ -8,6 +8,7 @@ Perform the :ref:`CTest Coverage Step` as a :ref:`Dashboard Client`. ctest_coverage([BUILD <build-dir>] [APPEND] [LABELS <label>...] [RETURN_VALUE <result-var>] + [CAPTURE_CMAKE_ERROR <result-var] [QUIET] ) @@ -21,9 +22,11 @@ The options are: :variable:`CTEST_BINARY_DIRECTORY` variable is used. ``APPEND`` - Mark results for append to those previously submitted to a + Mark ``Coverage.xml`` for append to results previously submitted to a dashboard server since the last :command:`ctest_start` call. Append semantics are defined by the dashboard server in use. + This does *not* cause results to be appended to a ``.xml`` file + produced by a previous call to this command. ``LABELS`` Filter the coverage report to include only source files labeled @@ -33,6 +36,10 @@ The options are: Store in the ``<result-var>`` variable ``0`` if coverage tools ran without error and non-zero otherwise. +``CAPTURE_CMAKE_ERROR <result-var>`` + Store in the ``<result-var>`` variable -1 if there are any errors running + the command and prevent ctest from returning non-zero if an error occurs. + ``QUIET`` Suppress any CTest-specific non-error output that would have been printed to the console otherwise. The summary indicating how many diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst index 412e323..ce50d42 100644 --- a/Help/command/ctest_test.rst +++ b/Help/command/ctest_test.rst @@ -18,6 +18,7 @@ Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`. [SCHEDULE_RANDOM <ON|OFF>] [STOP_TIME <time-of-day>] [RETURN_VALUE <result-var>] + [CAPTURE_CMAKE_ERROR <result-var>] [QUIET] ) @@ -31,9 +32,11 @@ The options are: :variable:`CTEST_BINARY_DIRECTORY` variable is used. ``APPEND`` - Mark results for append to those previously submitted to a + Mark ``Test.xml`` for append to results previously submitted to a dashboard server since the last :command:`ctest_start` call. Append semantics are defined by the dashboard server in use. + This does *not* cause results to be appended to a ``.xml`` file + produced by a previous call to this command. ``START <start-number>`` Specify the beginning of a range of test numbers. @@ -80,6 +83,10 @@ The options are: Store in the ``<result-var>`` variable ``0`` if all tests passed. Store non-zero if anything went wrong. +``CAPTURE_CMAKE_ERROR <result-var>`` + Store in the ``<result-var>`` variable -1 if there are any errors running + the command and prevent ctest from returning non-zero if an error occurs. + ``QUIET`` Suppress any CTest-specific non-error messages that would have otherwise been printed to the console. Output from the underlying test command is not diff --git a/Help/command/ctest_upload.rst b/Help/command/ctest_upload.rst index d9630d2..39d9de1 100644 --- a/Help/command/ctest_upload.rst +++ b/Help/command/ctest_upload.rst @@ -5,7 +5,7 @@ Upload files to a dashboard server as a :ref:`Dashboard Client`. :: - ctest_upload(FILES <file>... [QUIET]) + ctest_upload(FILES <file>... [QUIET] [CAPTURE_CMAKE_ERROR <result-var>]) The options are: @@ -16,3 +16,7 @@ The options are: ``QUIET`` Suppress any CTest-specific non-error output that would have been printed to the console otherwise. + +``CAPTURE_CMAKE_ERROR <result-var>`` + Store in the ``<result-var>`` variable -1 if there are any errors running + the command and prevent ctest from returning non-zero if an error occurs. diff --git a/Help/command/execute_process.rst b/Help/command/execute_process.rst index ca44b53..e9a5eb0 100644 --- a/Help/command/execute_process.rst +++ b/Help/command/execute_process.rst @@ -20,7 +20,7 @@ Execute one or more child processes. [OUTPUT_STRIP_TRAILING_WHITESPACE] [ERROR_STRIP_TRAILING_WHITESPACE]) -Runs the given sequence of one or more commands with the standard +Runs the given sequence of one or more commands in parallel with the standard output of each process piped to the standard input of the next. A single standard error pipe is used for all processes. @@ -36,6 +36,9 @@ Options: (Use the ``INPUT_*``, ``OUTPUT_*``, and ``ERROR_*`` options to redirect stdin, stdout, and stderr.) + If a sequential execution of multiple commands is required, use multiple + :command:`execute_process` calls with a single ``COMMAND`` argument. + ``WORKING_DIRECTORY`` The named directory will be set as the current working directory of the child processes. diff --git a/Help/command/export.rst b/Help/command/export.rst index 4419dc1..53675a7 100644 --- a/Help/command/export.rst +++ b/Help/command/export.rst @@ -55,3 +55,18 @@ build tree. In some cases, for example for packaging and for system 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. + +:: + + export(TARGETS [target1 [target2 [...]]] [ANDROID_MK <filename>]) + +This signature exports cmake built targets to the android ndk build system +by creating an Android.mk file that references the prebuilt targets. The +Android NDK supports the use of prebuilt libraries, both static and shared. +This allows cmake to build the libraries of a project and make them available +to an ndk build system complete with transitive dependencies, include flags +and defines required to use the libraries. The signature takes a list of +targets and puts them in the Android.mk file specified by the ``<filename>`` +given. This signature can only be used if policy CMP0022 is NEW for all +targets given. A error will be issued if that policy is set to OLD for one +of the targets. diff --git a/Help/command/file.rst b/Help/command/file.rst index 256d16d..8da46cb 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -153,7 +153,8 @@ Move a file or directory within a filesystem from ``<oldname>`` to file(REMOVE_RECURSE [<files>...]) Remove the given files. The ``REMOVE_RECURSE`` mode will remove the given -files and directories, also non-empty directories +files and directories, also non-empty directories. No error is emitted if a +given file does not exist. ------------------------------------------------------------------------------ @@ -222,6 +223,12 @@ Options to both ``DOWNLOAD`` and ``UPLOAD`` are: ``TIMEOUT <seconds>`` Terminate the operation after a given total time has elapsed. +``USERPWD <username>:<password>`` + Set username and password for operation. + +``HTTPHEADER <HTTP-header>`` + HTTP header for operation. Suboption can be repeated several times. + Additional options to ``DOWNLOAD`` are: ``EXPECTED_HASH ALGO=<value>`` diff --git a/Help/command/find_library.rst b/Help/command/find_library.rst index 31e6ec0..1eb50f7 100644 --- a/Help/command/find_library.rst +++ b/Help/command/find_library.rst @@ -49,6 +49,13 @@ path to the framework ``<fullPath>/A.framework``. When a full path to a framework is used as a library, CMake will use a ``-framework A``, and a ``-F<fullPath>`` to link the framework to the target. +If the :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` global property is set +all search paths will be tested as normal, with ``32/`` appended, and +with all matches of ``lib/`` replaced with ``lib32/``. This property is +automatically set for the platforms that are known to need it if at +least one of the languages supported by the :command:`project` command +is enabled. + If the :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` global property is set all search paths will be tested as normal, with ``64/`` appended, and with all matches of ``lib/`` replaced with ``lib64/``. This property is diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 58dff9d..2cb1e5f 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -170,11 +170,21 @@ is acceptable the following variables are set: ``<package>_VERSION_COUNT`` number of version components, 0 to 4 -and the corresponding package configuration file is loaded. When -multiple package configuration files are available whose version files +and the corresponding package configuration file is loaded. +When multiple package configuration files are available whose version files claim compatibility with the version requested it is unspecified which -one is chosen. No attempt is made to choose a highest or closest -version number. +one is chosen: unless the variable :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` +is set no attempt is made to choose a highest or closest version number. + +To control the order in which ``find_package`` checks for compatibiliy 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:: + + SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL) + SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC) + +before calling ``find_package``. Config mode provides an elaborate interface and search procedure. Much of the interface is provided for completeness and for use @@ -194,13 +204,16 @@ configuration file. The tables below show the directories searched. Each entry is meant for installation trees following Windows (W), UNIX (U), or Apple (A) conventions:: - <prefix>/ (W) - <prefix>/(cmake|CMake)/ (W) - <prefix>/<name>*/ (W) - <prefix>/<name>*/(cmake|CMake)/ (W) - <prefix>/(lib/<arch>|lib|share)/cmake/<name>*/ (U) - <prefix>/(lib/<arch>|lib|share)/<name>*/ (U) - <prefix>/(lib/<arch>|lib|share)/<name>*/(cmake|CMake)/ (U) + <prefix>/ (W) + <prefix>/(cmake|CMake)/ (W) + <prefix>/<name>*/ (W) + <prefix>/<name>*/(cmake|CMake)/ (W) + <prefix>/(lib/<arch>|lib|share)/cmake/<name>*/ (U) + <prefix>/(lib/<arch>|lib|share)/<name>*/ (U) + <prefix>/(lib/<arch>|lib|share)/<name>*/(cmake|CMake)/ (U) + <prefix>/<name>*/(lib/<arch>|lib|share)/cmake/<name>*/ (W/U) + <prefix>/<name>*/(lib/<arch>|lib|share)/<name>*/ (W/U) + <prefix>/<name>*/(lib/<arch>|lib|share)/<name>*/(cmake|CMake)/ (W/U) On systems supporting OS X Frameworks and Application Bundles the following directories are searched for frameworks or bundles diff --git a/Help/command/get_cmake_property.rst b/Help/command/get_cmake_property.rst index 3a6fb41..497ab4e 100644 --- a/Help/command/get_cmake_property.rst +++ b/Help/command/get_cmake_property.rst @@ -1,15 +1,20 @@ get_cmake_property ------------------ -Get a property of the CMake instance. +Get a global property of the CMake instance. :: get_cmake_property(VAR property) -Get a property from the CMake instance. The value of the property is +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. -See also the more general :command:`get_property` command. +See also the :command:`get_property` command ``GLOBAL`` option. + +In addition to global properties, this command (for historical reasons) +also supports the :prop_dir:`VARIABLES` and :prop_dir:`MACROS` directory +properties. It also supports a special ``COMPONENTS`` global property that +lists the components given to the :command:`install` command. diff --git a/Help/command/if.rst b/Help/command/if.rst index 56e618c..0941029 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -30,10 +30,12 @@ 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 -``EQUAL``, ``LESS``, ``GREATER``, ``STRLESS``, ``STRGREATER``, -``STREQUAL``, and ``MATCHES`` will be evaluated. Then boolean ``NOT`` -operators and finally boolean ``AND`` and then ``OR`` operators will -be evaluated. +``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. Possible expressions are: @@ -115,6 +117,14 @@ Possible expressions are: True if the given string or variable's value is a valid number and equal to that on the right. +``if(<variable|string> LESS_EQUAL <variable|string>)`` + True if the given string or variable's value is a valid number and less + than or equal to that on the right. + +``if(<variable|string> GREATER_EQUAL <variable|string>)`` + True if the given string or variable's value is a valid number and greater + than or equal to that on the right. + ``if(<variable|string> STRLESS <variable|string>)`` True if the given string or variable's value is lexicographically less than the string or variable on the right. @@ -127,15 +137,31 @@ Possible expressions are: True if the given string or variable's value is lexicographically equal to the string or variable on the right. +``if(<variable|string> STRLESS_EQUAL <variable|string>)`` + True if the given string or variable's value is lexicographically less + than or equal to the string or variable on the right. + +``if(<variable|string> STRGREATER_EQUAL <variable|string>)`` + True if the given string or variable's value is lexicographically greater + than or equal to the string or variable on the right. + ``if(<variable|string> VERSION_LESS <variable|string>)`` Component-wise integer version number comparison (version format is ``major[.minor[.patch[.tweak]]]``). +``if(<variable|string> VERSION_GREATER <variable|string>)`` + Component-wise integer version number comparison (version format is + ``major[.minor[.patch[.tweak]]]``). + ``if(<variable|string> VERSION_EQUAL <variable|string>)`` Component-wise integer version number comparison (version format is ``major[.minor[.patch[.tweak]]]``). -``if(<variable|string> VERSION_GREATER <variable|string>)`` +``if(<variable|string> VERSION_LESS_EQUAL <variable|string>)`` + Component-wise integer version number comparison (version format is + ``major[.minor[.patch[.tweak]]]``). + +``if(<variable|string> VERSION_GREATER_EQUAL <variable|string>)`` Component-wise integer version number comparison (version format is ``major[.minor[.patch[.tweak]]]``). @@ -186,20 +212,21 @@ above-documented signature accepts ``<variable|string>``: * If the left hand argument to ``MATCHES`` is missing it returns false without error -* Both left and right hand arguments to ``LESS``, ``GREATER``, and - ``EQUAL`` are independently tested to see if they are defined - variables, if so their defined values are used otherwise the original - value is used. +* Both left and right hand arguments to ``LESS``, ``GREATER``, ``EQUAL``, + ``LESS_EQUAL``, and ``GREATER_EQUAL``, are independently tested to see if + they are defined variables, if so their defined values are used otherwise + the original value is used. -* Both left and right hand arguments to ``STRLESS``, ``STREQUAL``, and - ``STRGREATER`` are independently tested to see if they are defined - variables, if so their defined values are used otherwise the original - value is used. +* Both left and right hand arguments to ``STRLESS``, ``STRGREATER``, + ``STREQUAL``, ``STRLESS_EQUAL``, and ``STRGREATER_EQUAL`` are independently + tested to see if they are defined variables, if so their defined values are + used otherwise the original value is used. * Both left and right hand arguments to ``VERSION_LESS``, - ``VERSION_EQUAL``, and ``VERSION_GREATER`` are independently tested - to see if they are defined variables, if so their defined values are - used otherwise the original value is used. + ``VERSION_GREATER``, ``VERSION_EQUAL``, ``VERSION_LESS_EQUAL``, and + ``VERSION_GREATER_EQUAL`` are independently tested to see if they are defined + variables, if so their defined values are used otherwise the original value + is used. * The right hand argument to ``NOT`` is tested to see if it is a boolean constant, if so the value is used, otherwise it is assumed to be a diff --git a/Help/command/include.rst b/Help/command/include.rst index c391561..eeca4c6 100644 --- a/Help/command/include.rst +++ b/Help/command/include.rst @@ -15,10 +15,10 @@ is present, then no error is raised if the file does not exist. If 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`, +``<modulename>.cmake`` is searched first in :variable:`CMAKE_MODULE_PATH`, then in the CMake module directory. There is one exception to this: if -the file which calls ``include()`` is located itself in the CMake module -directory, then first the CMake module directory is searched and +the file which calls ``include()`` is located itself in the CMake builtin +module directory, then first the CMake builtin module directory is searched and :variable:`CMAKE_MODULE_PATH` afterwards. See also policy :policy:`CMP0017`. See the :command:`cmake_policy` command documentation for discussion of the diff --git a/Help/command/install.rst b/Help/command/install.rst index aaf12cc..d57dd75 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -314,7 +314,8 @@ Installing Exports :: install(EXPORT <export-name> DESTINATION <dir> - [NAMESPACE <namespace>] [FILE <name>.cmake] + [NAMESPACE <namespace>] [[FILE <name>.cmake]| + [EXPORT_ANDROID_MK <name>.mk]] [PERMISSIONS permissions...] [CONFIGURATIONS [Debug|Release|...]] [EXPORT_LINK_INTERFACE_LIBRARIES] @@ -342,6 +343,13 @@ specified that does not match that given to the targets associated with included in the export but a target to which it links is not included the behavior is unspecified. +In additon to cmake language files, the ``EXPORT_ANDROID_MK`` option maybe +used to specifiy an export to the android ndk build system. The Android +NDK supports the use of prebuilt libraries, both static and shared. This +allows cmake to build the libraries of a project and make them available +to an ndk build system complete with transitive dependencies, include flags +and defines required to use the libraries. + The ``EXPORT`` form is useful to help outside projects use targets built and installed by the current project. For example, the code @@ -349,9 +357,11 @@ and installed by the current project. For example, the code install(TARGETS myexe EXPORT myproj DESTINATION bin) install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj) + install(EXPORT_ANDROID_MK myexp DESTINATION share/ndk-modules) will install the executable myexe to ``<prefix>/bin`` and code to import -it in the file ``<prefix>/lib/myproj/myproj.cmake``. An outside project +it in the file ``<prefix>/lib/myproj/myproj.cmake`` and +``<prefix>/lib/share/ndk-modules/Android.mk``. An outside project may load this file with the include command and reference the ``myexe`` executable from the installation tree using the imported target name ``mp_myexe`` as if the target were built in its own tree. diff --git a/Help/command/math.rst b/Help/command/math.rst index d4deb16..f99dc3d 100644 --- a/Help/command/math.rst +++ b/Help/command/math.rst @@ -5,9 +5,10 @@ Mathematical expressions. :: - math(EXPR <output variable> <math expression>) + math(EXPR <output-variable> <math-expression>) ``EXPR`` evaluates mathematical expression and returns result in the -output variable. Example mathematical expression is '5 * ( 10 + 13 -)'. Supported operators are + - * / % | & ^ ~ << >> * / %. They have -the same meaning as they do in C code. +output variable. Example mathematical expression is ``5 * (10 + 13)``. +Supported operators are ``+``, ``-``, ``*``, ``/``, ``%``, ``|``, ``&``, +``^``, ``~``, ``<<``, ``>>``, and ``(...)``. They have the same meaning +as they do in C code. diff --git a/Help/command/separate_arguments.rst b/Help/command/separate_arguments.rst index 0e3e5a5..1fd3cd1 100644 --- a/Help/command/separate_arguments.rst +++ b/Help/command/separate_arguments.rst @@ -13,19 +13,21 @@ entire command line must be given in one "<args>" argument. 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). +escapes the next literal character (``\"`` is ``"``); there are no special +escapes (``\n`` is just ``n``). 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. +MSDN article `Parsing C Command-Line Arguments`_ for details. + +.. _`Parsing C Command-Line Arguments`: https://msdn.microsoft.com/library/a1y7w461.aspx :: - separate_arguments(VARIABLE) + separate_arguments(<var>) -Convert the value of ``VARIABLE`` to a semi-colon separated list. All +Convert the value of ``<var>`` to a semi-colon separated list. All spaces are replaced with ';'. This helps with generating command lines. diff --git a/Help/command/set.rst b/Help/command/set.rst index d04b880..b24ebef 100644 --- a/Help/command/set.rst +++ b/Help/command/set.rst @@ -25,7 +25,9 @@ If the ``PARENT_SCOPE`` option is given the variable will be set in the scope above the current scope. Each new directory or function creates a new scope. This command will set the value of a variable into the parent directory or calling function (whichever is applicable -to the case at hand). +to the case at hand). The previous state of the variable's value stays the +same in the current scope (e.g., if it was undefined before, it is still +undefined and if it had a value, it is still that value). Set Cache Entry ^^^^^^^^^^^^^^^ diff --git a/Help/command/string.rst b/Help/command/string.rst index 3f4050e..8028333 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -197,10 +197,12 @@ Comparison :: - string(COMPARE EQUAL <string1> <string2> <output variable>) - string(COMPARE NOTEQUAL <string1> <string2> <output variable>) string(COMPARE LESS <string1> <string2> <output variable>) string(COMPARE GREATER <string1> <string2> <output variable>) + string(COMPARE EQUAL <string1> <string2> <output variable>) + string(COMPARE NOTEQUAL <string1> <string2> <output variable>) + string(COMPARE LESS_EQUAL <string1> <string2> <output variable>) + string(COMPARE GREATER_EQUAL <string1> <string2> <output variable>) Compare the strings and store true or false in the output variable. @@ -276,12 +278,14 @@ specifiers: %I The hour on a 12-hour clock (01-12). %j The day of the current year (001-366). %m The month of the current year (01-12). + %b Abbreviated month name (e.g. Oct). %M The minute of the current hour (00-59). %s Seconds since midnight (UTC) 1-Jan-1970 (UNIX time). %S The second of the current minute. 60 represents a leap second. (00-60) %U The week number of the current year (00-53). %w The day of the current week. 0 is Sunday. (0-6) + %a Abbreviated weekday name (e.g. Fri). %y The last two digits of the current year (00-99) %Y The current year. diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index d903d05..90b6575 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -62,6 +62,12 @@ Each ``<item>`` may be: dependencies, so they are generally safe to specify only as private link items that will not propagate to dependents. + Link flags specified here are inserted into the link command in the same + place as the link libraries. This might not be correct, depending on + the linker. Use the :prop_tgt:`LINK_FLAGS` target property to add link + flags explicitly. The flags will then be placed at the toolchain-defined + flag position in the link command. + * A ``debug``, ``optimized``, or ``general`` keyword immediately followed by another ``<item>``. The item following such a keyword will be used only for the corresponding build configuration. The ``debug`` keyword diff --git a/Help/generator/CodeLite.rst b/Help/generator/CodeLite.rst index dbc46d7..3e60aa6 100644 --- a/Help/generator/CodeLite.rst +++ b/Help/generator/CodeLite.rst @@ -5,7 +5,11 @@ Generates CodeLite project files. Project files for CodeLite will be created in the top directory and in every subdirectory which features a CMakeLists.txt file containing -a PROJECT() call. The appropriate make program can build the +a :command:`project` call. +The :variable:`CMAKE_CODELITE_USE_TARGETS` variable may be set to ``ON`` +to change the default behaviour from projects to targets as the basis +for project files. +The appropriate make program can build the project through the default make target. A "make install" target is also provided. diff --git a/Help/generator/Ninja.rst b/Help/generator/Ninja.rst index d94e5f6..3bbd9dc 100644 --- a/Help/generator/Ninja.rst +++ b/Help/generator/Ninja.rst @@ -7,6 +7,27 @@ A build.ninja file is generated into the build tree. Recent versions of the ninja program can build the project through the "all" target. An "install" target is also provided. -For each subdirectory ``sub/dir`` of the project an additional target -named ``sub/dir/all`` is generated that depends on all targets required -by that subdirectory. +For each subdirectory ``sub/dir`` of the project, additional targets +are generated: + +``sub/dir/all`` + Depends on all targets required by the subdirectory. + +``sub/dir/install`` + Runs the install step in the subdirectory, if any. + +``sub/dir/test`` + Runs the test step in the subdirectory, if any. + +``sub/dir/package`` + Runs the package step in the subdirectory, if any. + +Fortran Support +^^^^^^^^^^^^^^^ + +The ``Ninja`` generator conditionally supports Fortran when the ``ninja`` +tool has the required features. As of this version of CMake the needed +features have not been integrated into upstream Ninja. Kitware maintains +a branch of Ninja with the required features on `github.com/Kitware/ninja`_. + +.. _`github.com/Kitware/ninja`: https://github.com/Kitware/ninja/tree/features-for-fortran#readme diff --git a/Help/generator/VS_TOOLSET_HOST_ARCH.txt b/Help/generator/VS_TOOLSET_HOST_ARCH.txt new file mode 100644 index 0000000..58e9223 --- /dev/null +++ b/Help/generator/VS_TOOLSET_HOST_ARCH.txt @@ -0,0 +1,10 @@ +For each toolset that comes with this version of Visual Studio, there are +variants that are themselves compiled for 32-bit (x86) and 64-bit (x64) hosts +(independent of the architecture they target). By default Visual Studio +chooses the 32-bit variant even on a 64-bit host. One may request use of the +64-bit host tools by adding ``host=x64`` to the toolset specification: + +``host=x64`` + Select the 64-bit variant of the default toolset. +``<toolset>,host=x64`` + Select the 64-bit variant of the ``<toolset>`` toolset. diff --git a/Help/generator/Visual Studio 10 2010.rst b/Help/generator/Visual Studio 10 2010.rst index 77ea9df..04eef10 100644 --- a/Help/generator/Visual Studio 10 2010.rst +++ b/Help/generator/Visual Studio 10 2010.rst @@ -4,7 +4,7 @@ Visual Studio 10 2010 Generates Visual Studio 10 (VS 2010) project files. The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set -to specify a target platform name. +to specify a target platform name (architecture). For compatibility with CMake versions prior to 3.1, one may specify a target platform name optionally at the end of this generator name: @@ -17,3 +17,10 @@ a target platform name optionally at the end of this generator name: For compatibility with CMake versions prior to 3.0, one may specify this generator using the name ``Visual Studio 10`` without the year component. + +Toolset Selection +^^^^^^^^^^^^^^^^^ + +The ``v100`` toolset that comes with Visual Studio 10 2010 is selected by +default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps +via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. diff --git a/Help/generator/Visual Studio 11 2012.rst b/Help/generator/Visual Studio 11 2012.rst index 5fa7f2c..347a153 100644 --- a/Help/generator/Visual Studio 11 2012.rst +++ b/Help/generator/Visual Studio 11 2012.rst @@ -4,7 +4,7 @@ Visual Studio 11 2012 Generates Visual Studio 11 (VS 2012) project files. The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set -to specify a target platform name. +to specify a target platform name (architecture). For compatibility with CMake versions prior to 3.1, one may specify a target platform name optionally at the end of this generator name: @@ -20,3 +20,10 @@ a target platform name optionally at the end of this generator name: For compatibility with CMake versions prior to 3.0, one may specify this generator using the name "Visual Studio 11" without the year component. + +Toolset Selection +^^^^^^^^^^^^^^^^^ + +The ``v110`` toolset that comes with Visual Studio 11 2012 is selected by +default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps +via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. diff --git a/Help/generator/Visual Studio 12 2013.rst b/Help/generator/Visual Studio 12 2013.rst index 2c3b119..5071b20 100644 --- a/Help/generator/Visual Studio 12 2013.rst +++ b/Help/generator/Visual Studio 12 2013.rst @@ -4,7 +4,7 @@ Visual Studio 12 2013 Generates Visual Studio 12 (VS 2013) project files. The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set -to specify a target platform name. +to specify a target platform name (architecture). For compatibility with CMake versions prior to 3.1, one may specify a target platform name optionally at the end of this generator name: @@ -17,3 +17,12 @@ a target platform name optionally at the end of this generator name: For compatibility with CMake versions prior to 3.0, one may specify this generator using the name "Visual Studio 12" without the year component. + +Toolset Selection +^^^^^^^^^^^^^^^^^ + +The ``v120`` toolset that comes with Visual Studio 12 2013 is selected by +default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps +via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. + +.. include:: VS_TOOLSET_HOST_ARCH.txt diff --git a/Help/generator/Visual Studio 14 2015.rst b/Help/generator/Visual Studio 14 2015.rst index b35997a..64254b5 100644 --- a/Help/generator/Visual Studio 14 2015.rst +++ b/Help/generator/Visual Studio 14 2015.rst @@ -4,7 +4,7 @@ Visual Studio 14 2015 Generates Visual Studio 14 (VS 2015) project files. The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set -to specify a target platform name. +to specify a target platform name (architecture). For compatibility with CMake versions prior to 3.1, one may specify a target platform name optionally at the end of this generator name: @@ -14,3 +14,12 @@ a target platform name optionally at the end of this generator name: ``Visual Studio 14 2015 ARM`` Specify target platform ``ARM``. + +Toolset Selection +^^^^^^^^^^^^^^^^^ + +The ``v140`` toolset that comes with Visual Studio 14 2015 is selected by +default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps +via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. + +.. include:: VS_TOOLSET_HOST_ARCH.txt diff --git a/Help/generator/Visual Studio 15.rst b/Help/generator/Visual Studio 15.rst new file mode 100644 index 0000000..2eb9052 --- /dev/null +++ b/Help/generator/Visual Studio 15.rst @@ -0,0 +1,25 @@ +Visual Studio 15 +---------------- + +Generates Visual Studio 15 project files. + +The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set +to specify a target platform name (architecture). + +For compatibility with CMake versions prior to 3.1, one may specify +a target platform name optionally at the end of this generator name: + +``Visual Studio 15 Win64`` + Specify target platform ``x64``. + +``Visual Studio 15 ARM`` + Specify target platform ``ARM``. + +Toolset Selection +^^^^^^^^^^^^^^^^^ + +The ``v141`` toolset that comes with Visual Studio 15 is selected by +default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps +via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. + +.. include:: VS_TOOLSET_HOST_ARCH.txt diff --git a/Help/generator/Xcode.rst b/Help/generator/Xcode.rst index d8a6790..25ff4c7 100644 --- a/Help/generator/Xcode.rst +++ b/Help/generator/Xcode.rst @@ -2,3 +2,10 @@ Xcode ----- Generate Xcode project files. + +Toolset Selection +^^^^^^^^^^^^^^^^^ + +By default Xcode is allowed to select its own default toolchain. +The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps +via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. diff --git a/Help/index.rst b/Help/index.rst index 2d3f156..97cd107 100644 --- a/Help/index.rst +++ b/Help/index.rst @@ -32,6 +32,7 @@ Reference Manuals /manual/cmake-generator-expressions.7 /manual/cmake-generators.7 /manual/cmake-language.7 + /manual/cmake-server.7 /manual/cmake-modules.7 /manual/cmake-packages.7 /manual/cmake-policies.7 diff --git a/Help/manual/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt index b428a74..9b3f717 100644 --- a/Help/manual/OPTIONS_BUILD.txt +++ b/Help/manual/OPTIONS_BUILD.txt @@ -52,13 +52,12 @@ Specify toolset name if supported by generator. Some CMake generators support a toolset name to be given to the - native build system to choose a compiler. This is supported only on - specific generators: + native build system to choose a compiler. + See the :variable:`CMAKE_GENERATOR_TOOLSET` variable. + This is supported only on specific generators: - :: - - Visual Studio >= 10 - Xcode >= 3.0 + * :ref:`Visual Studio Generators` for VS 2010 and above + * The :generator:`Xcode` generator for Xcode 3.0 and above See native build system documentation for allowed toolset names. @@ -66,10 +65,12 @@ Specify platform name if supported by generator. Some CMake generators support a platform name to be given to the - native build system to choose a compiler or SDK. This is supported only on - specific generators:: + native build system to choose a compiler or SDK. See the + :variable:`CMAKE_GENERATOR_PLATFORM` variable. + This is supported only on specific generators: - Visual Studio >= 8 + * For :ref:`Visual Studio Generators` with VS 2005 and above this + specifies the target architecture. See native build system documentation for allowed platform names. diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 07bf33f..4950fee 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -860,7 +860,7 @@ with :prop_tgt:`IMPORTED` targets. Alias Targets ------------- -An ``ALIAS`` target is a name which may be used interchangably with +An ``ALIAS`` target is a name which may be used interchangeably with a binary target name in read-only contexts. A primary use-case for ``ALIAS`` targets is for example or unit test executables accompanying a library, which may be part of the same buildsystem or built separately based on user diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst index 7289e61..13f7d16 100644 --- a/Help/manual/cmake-compile-features.7.rst +++ b/Help/manual/cmake-compile-features.7.rst @@ -84,6 +84,33 @@ Feature requirements are evaluated transitively by consuming the link implementation. See :manual:`cmake-buildsystem(7)` for more on transitive behavior of build properties and usage requirements. +Requiring Language Standards +---------------------------- + +In projects that use a large number of commonly available features from +a particular language standard (e.g. C++ 11) one may specify a +meta-feature (e.g. ``cxx_std_11``) that requires use of a compiler mode +aware of that standard. This is simpler than specifying all the +features individually, but does not guarantee the existence of any +particular feature. Diagnosis of use of unsupported features will be +delayed until compile time. + +For example, if C++ 11 features are used extensively in a project's +header files, then clients must use a compiler mode aware of C++ 11 +or above. This can be requested with the code: + +.. code-block:: cmake + + target_compile_features(mylib PUBLIC cxx_std_11) + +In this example, CMake will ensure the compiler is invoked in a mode +that is aware of C++ 11 (or above), adding flags such as +``-std=gnu++11`` if necessary. This applies to sources within ``mylib`` +as well as any dependents (that may include headers from ``mylib``). + +Availability of Compiler Extensions +----------------------------------- + Because the :prop_tgt:`CXX_EXTENSIONS` target property is ``ON`` by default, CMake uses extended variants of language dialects by default, such as ``-std=gnu++11`` instead of ``-std=c++11``. That target property may be @@ -309,4 +336,4 @@ versions specified for each: * ``GNU``: GNU compiler versions 4.4 through 5.0. * ``MSVC``: Microsoft Visual Studio versions 2010 through 2015. * ``SunPro``: Oracle SolarisStudio version 12.4. -* ``Intel``: Intel compiler versions 12.1 through 16.0 on UNIX platforms. +* ``Intel``: Intel compiler versions 12.1 through 17.0. diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index 7bfdcad..6557686 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -24,9 +24,10 @@ to build with such toolchains. std::auto_ptr ------------- -Some implementations have a ``std::auto_ptr`` which can not be used as a -return value from a function. ``std::auto_ptr`` may not be used. Use -``cmsys::auto_ptr`` instead. +The ``std::auto_ptr`` template is deprecated in C++11. We want to use it +so we can build on C++98 compilers but we do not want to turn off compiler +warnings about deprecated interfaces in general. Use the ``CM_AUTO_PTR`` +macro instead. size_t ------ @@ -518,8 +519,16 @@ containing just the line:: The ``cmake-module`` directive will scan the module file to extract reStructuredText markup from comment blocks that start in ``.rst:``. -Add to the top of ``Modules/<module-name>.cmake`` a -:ref:`Line Comment` block of the form: +At the top of ``Modules/<module-name>.cmake``, begin with the following +license notice: + +.. code-block:: cmake + + # Distributed under the OSI-approved BSD 3-Clause License. See accompanying + # file Copyright.txt or https://cmake.org/licensing for details. + +After this notice, add a *BLANK* line. Then, add documentation using +a :ref:`Line Comment` block of the form: .. code-block:: cmake @@ -551,6 +560,9 @@ For example, a ``Modules/Findxxx.cmake`` module may contain: .. code-block:: cmake + # Distributed under the OSI-approved BSD 3-Clause License. See accompanying + # file Copyright.txt or https://cmake.org/licensing for details. + #.rst: # FindXxx # ------- @@ -578,25 +590,6 @@ For example, a ``Modules/Findxxx.cmake`` module may contain: <code> endmacro() -After the top documentation block, leave a *BLANK* line, and then add a -copyright and licence notice block like this one (change only the year -range and name) - -.. code-block:: cmake - - #============================================================================= - # Copyright 2009-2011 Your Name - # - # Distributed under the OSI-approved BSD License (the "License"); - # see accompanying file Copyright.txt for details. - # - # This software is distributed WITHOUT ANY WARRANTY; without even the - # implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - # See the License for more information. - #============================================================================= - # (To distribute this file outside of CMake, substitute the full - # License text for the above reference.) - Test the documentation formatting by running ``cmake --help-module <module-name>``, and also by enabling the ``SPHINX_HTML`` and ``SPHINX_MAN`` options to build the documentation. @@ -790,10 +783,17 @@ A Sample Find Module We will describe how to create a simple find module for a library ``Foo``. -The first thing that is needed is documentation. CMake's documentation -system requires you to start the file with a documentation marker and -the name of the module. You should follow this with a simple statement -of what the module does. +The first thing that is needed is a license notice. + +.. code-block:: cmake + + # Distributed under the OSI-approved BSD 3-Clause License. See accompanying + # file Copyright.txt or https://cmake.org/licensing for details. + +Next we need module documentation. CMake's documentation system requires you +to follow the license notice with a blank line and then with a documentation +marker and the name of the module. You should follow this with a simple +statement of what the module does. .. code-block:: cmake @@ -824,24 +824,6 @@ If the package provides any macros, they should be listed here, but can be documented where they are defined. See the `Module Documentation`_ section above for more details. -After the documentation, leave a blank line, and then add a copyright and -licence notice block - -.. code-block:: cmake - - #============================================================================= - # Copyright 2009-2011 Your Name - # - # Distributed under the OSI-approved BSD License (the "License"); - # see accompanying file Copyright.txt for details. - # - # This software is distributed WITHOUT ANY WARRANTY; without even the - # implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - # See the License for more information. - #============================================================================= - # (To distribute this file outside of CMake, substitute the full - # License text for the above reference.) - Now the actual libraries and so on have to be found. The code here will obviously vary from module to module (dealing with that, after all, is the point of find modules), but there tends to be a common pattern for libraries. diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index d4f47dd..64d15a9 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -66,12 +66,16 @@ Available logical expressions are: ``1`` if the CMake-id of the C compiler matches ``comp``, otherwise ``0``. ``$<CXX_COMPILER_ID:comp>`` ``1`` if the CMake-id of the CXX compiler matches ``comp``, otherwise ``0``. -``$<VERSION_GREATER:v1,v2>`` - ``1`` if ``v1`` is a version greater than ``v2``, else ``0``. ``$<VERSION_LESS:v1,v2>`` ``1`` if ``v1`` is a version less than ``v2``, else ``0``. +``$<VERSION_GREATER:v1,v2>`` + ``1`` if ``v1`` is a version greater than ``v2``, else ``0``. ``$<VERSION_EQUAL:v1,v2>`` ``1`` if ``v1`` is the same version as ``v2``, else ``0``. +``$<VERSION_LESS_EQUAL:v1,v2>`` + ``1`` if ``v1`` is a version less than or equal to ``v2``, else ``0``. +``$<VERSION_GREATER_EQUAL:v1,v2>`` + ``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``. ``$<C_COMPILER_VERSION:ver>`` ``1`` if the version of the C compiler matches ``ver``, otherwise ``0``. ``$<CXX_COMPILER_VERSION:ver>`` diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst index cde8de8..3df3a81 100644 --- a/Help/manual/cmake-generators.7.rst +++ b/Help/manual/cmake-generators.7.rst @@ -82,6 +82,7 @@ Visual Studio Generators /generator/Visual Studio 11 2012 /generator/Visual Studio 12 2013 /generator/Visual Studio 14 2015 + /generator/Visual Studio 15 Other Generators ^^^^^^^^^^^^^^^^ diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 62910cf..015e36e 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -14,6 +14,7 @@ All Modules :maxdepth: 1 /module/AddFileDependencies + /module/AndroidTestUtilities /module/BundleUtilities /module/CheckCCompilerFlag /module/CheckCSourceCompiles @@ -60,6 +61,7 @@ All Modules /module/CPackIFW /module/CPackNSIS /module/CPackPackageMaker + /module/CPackProductBuild /module/CPackRPM /module/CPack /module/CPackWIX @@ -120,6 +122,7 @@ All Modules /module/FindHTMLHelp /module/FindIce /module/FindIcotool + /module/FindICU /module/FindImageMagick /module/FindIntl /module/FindITK @@ -209,6 +212,7 @@ All Modules /module/FindTIFF /module/FindUnixCommands /module/FindVTK + /module/FindVulkan /module/FindWget /module/FindWish /module/FindwxWidgets diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 43f4637..0cfe983 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.7 +================================ + +.. toctree:: + :maxdepth: 1 + + CMP0066: Honor per-config flags in try_compile() source-file signature. </policy/CMP0066> + Policies Introduced by CMake 3.4 ================================ diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 3403dcd..fa21a1f 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -24,6 +24,7 @@ Properties of Global Scope /prop_gbl/DISABLED_FEATURES /prop_gbl/ENABLED_FEATURES /prop_gbl/ENABLED_LANGUAGES + /prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS /prop_gbl/FIND_LIBRARY_USE_LIB64_PATHS /prop_gbl/FIND_LIBRARY_USE_OPENBSD_VERSIONING /prop_gbl/GLOBAL_DEPENDS_DEBUG_MODE @@ -53,6 +54,8 @@ Properties on Directories :maxdepth: 1 /prop_dir/ADDITIONAL_MAKE_CLEAN_FILES + /prop_dir/BINARY_DIR + /prop_dir/BUILDSYSTEM_TARGETS /prop_dir/CACHE_VARIABLES /prop_dir/CLEAN_NO_CUSTOM /prop_dir/CMAKE_CONFIGURE_DEPENDS @@ -72,6 +75,8 @@ Properties on Directories /prop_dir/RULE_LAUNCH_COMPILE /prop_dir/RULE_LAUNCH_CUSTOM /prop_dir/RULE_LAUNCH_LINK + /prop_dir/SOURCE_DIR + /prop_dir/SUBDIRECTORIES /prop_dir/TEST_INCLUDE_FILE /prop_dir/VARIABLES /prop_dir/VS_GLOBAL_SECTION_POST_section @@ -116,6 +121,7 @@ Properties on Targets /prop_tgt/AUTORCC /prop_tgt/AUTORCC_OPTIONS /prop_tgt/BINARY_DIR + /prop_tgt/BUILD_RPATH /prop_tgt/BUILD_WITH_INSTALL_RPATH /prop_tgt/BUNDLE_EXTENSION /prop_tgt/BUNDLE @@ -217,6 +223,7 @@ Properties on Targets /prop_tgt/LINK_LIBRARIES /prop_tgt/LINK_SEARCH_END_STATIC /prop_tgt/LINK_SEARCH_START_STATIC + /prop_tgt/LINK_WHAT_YOU_USE /prop_tgt/LOCATION_CONFIG /prop_tgt/LOCATION /prop_tgt/MACOSX_BUNDLE_INFO_PLIST @@ -274,6 +281,7 @@ Properties on Targets /prop_tgt/VS_SCC_LOCALPATH /prop_tgt/VS_SCC_PROJECTNAME /prop_tgt/VS_SCC_PROVIDER + /prop_tgt/VS_SDK_REFERENCES /prop_tgt/VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION /prop_tgt/VS_WINRT_COMPONENT /prop_tgt/VS_WINRT_EXTENSIONS @@ -297,6 +305,9 @@ Properties on Tests /prop_test/DEPENDS /prop_test/ENVIRONMENT /prop_test/FAIL_REGULAR_EXPRESSION + /prop_test/FIXTURES_CLEANUP + /prop_test/FIXTURES_REQUIRED + /prop_test/FIXTURES_SETUP /prop_test/LABELS /prop_test/MEASUREMENT /prop_test/PASS_REGULAR_EXPRESSION @@ -341,9 +352,11 @@ Properties on Source Files /prop_sf/VS_SHADER_FLAGS /prop_sf/VS_SHADER_MODEL /prop_sf/VS_SHADER_TYPE + /prop_sf/VS_TOOL_OVERRIDE.rst /prop_sf/VS_XAML_TYPE /prop_sf/WRAP_EXCLUDE /prop_sf/XCODE_EXPLICIT_FILE_TYPE + /prop_sf/XCODE_FILE_ATTRIBUTES /prop_sf/XCODE_LAST_KNOWN_FILE_TYPE .. _`Cache Entry Properties`: diff --git a/Help/manual/cmake-qt.7.rst b/Help/manual/cmake-qt.7.rst index e8a2c1e..7827065 100644 --- a/Help/manual/cmake-qt.7.rst +++ b/Help/manual/cmake-qt.7.rst @@ -29,7 +29,7 @@ Qt 4 and Qt 5 may be used together in the same set(CMAKE_AUTOMOC ON) set(CMAKE_INCLUDE_CURRENT_DIR ON) - find_package(Qt5Widgets REQUIRED) + find_package(Qt5 COMPONENTS Widgets DBus REQUIRED) add_executable(publisher publisher.cpp) target_link_libraries(publisher Qt5::Widgets Qt5::DBus) diff --git a/Help/manual/cmake-server.7.rst b/Help/manual/cmake-server.7.rst new file mode 100644 index 0000000..9520cc1 --- /dev/null +++ b/Help/manual/cmake-server.7.rst @@ -0,0 +1,672 @@ +.. cmake-manual-description: CMake Server + +cmake-server(7) +*************** + +.. only:: html + + .. contents:: + +Introduction +============ + +:manual:`cmake(1)` is capable of providing semantic information about +CMake code it executes to generate a buildsystem. If executed with +the ``-E server`` command line options, it starts in a long running mode +and allows a client to request the available information via a JSON protocol. + +The protocol is designed to be useful to IDEs, refactoring tools, and +other tools which have a need to understand the buildsystem in entirety. + +A single :manual:`cmake-buildsystem(7)` may describe buildsystem contents +and build properties which differ based on +:manual:`generation-time context <cmake-generator-expressions(7)>` +including: + +* The Platform (eg, Windows, APPLE, Linux). +* The build configuration (eg, Debug, Release, Coverage). +* The Compiler (eg, MSVC, GCC, Clang) and compiler version. +* The language of the source files compiled. +* Available compile features (eg CXX variadic templates). +* CMake policies. + +The protocol aims to provide information to tooling to satisfy several +needs: + +#. Provide a complete and easily parsed source of all information relevant + to the tooling as it relates to the source code. There should be no need + for tooling to parse generated buildsystems to access include directories + or compile definitions for example. +#. Semantic information about the CMake buildsystem itself. +#. Provide a stable interface for reading the information in the CMake cache. +#. Information for determining when cmake needs to be re-run as a result of + file changes. + + +Operation +========= + +Start :manual:`cmake(1)` in the server command mode, supplying the path to +the build directory to process:: + + cmake -E server (--debug|--pipe <NAMED_PIPE>) + +The server will communicate using stdin/stdout (with the ``--debug`` parameter) +or using a named pipe (with the ``--pipe <NAMED_PIPE>`` parameter). + +When connecting to the server (via named pipe or by starting it in ``--debug`` +mode), the server will reply with a hello message:: + + [== "CMake Server" ==[ + {"supportedProtocolVersions":[{"major":1,"minor":0}],"type":"hello"} + ]== "CMake Server" ==] + +Messages sent to and from the process are wrapped in magic strings:: + + [== "CMake Server" ==[ + { + ... some JSON message ... + } + ]== "CMake Server" ==] + +The server is now ready to accept further requests via the named pipe +or stdin. + + +Debugging +========= + +CMake server mode can be asked to provide statistics on execution times, etc. +or to dump a copy of the response into a file. This is done passing a "debug" +JSON object as a child of the request. + +The debug object supports the "showStats" key, which takes a boolean and makes +the server mode return a "zzzDebug" object with stats as part of its response. +"dumpToFile" takes a string value and will cause the cmake server to copy +the response into the given filename. + +This is a response from the cmake server with "showStats" set to true:: + + [== "CMake Server" ==[ + { + "cookie":"", + "errorMessage":"Waiting for type \"handshake\".", + "inReplyTo":"unknown", + "type":"error", + "zzzDebug": { + "dumpFile":"/tmp/error.txt", + "jsonSerialization":0.011016, + "size":111, + "totalTime":0.025995 + } + } + ]== "CMake Server" ==] + +The server has made a copy of this response into the file /tmp/error.txt and +took 0.011 seconds to turn the JSON response into a string, and it took 0.025 +seconds to process the request in total. The reply has a size of 111 bytes. + + +Protocol API +============ + + +General Message Layout +---------------------- + +All messages need to have a "type" value, which identifies the type of +message that is passed back or forth. E.g. the initial message sent by the +server is of type "hello". Messages without a type will generate an response +of type "error". + +All requests sent to the server may contain a "cookie" value. This value +will he handed back unchanged in all responses triggered by the request. + +All responses will contain a value "inReplyTo", which may be empty in +case of parse errors, but will contain the type of the request message +in all other cases. + + +Type "reply" +^^^^^^^^^^^^ + +This type is used by the server to reply to requests. + +The message may -- depending on the type of the original request -- +contain values. + +Example:: + + [== "CMake Server" ==[ + {"cookie":"zimtstern","inReplyTo":"handshake","type":"reply"} + ]== "CMake Server" ==] + + +Type "error" +^^^^^^^^^^^^ + +This type is used to return an error condition to the client. It will +contain an "errorMessage". + +Example:: + + [== "CMake Server" ==[ + {"cookie":"","errorMessage":"Protocol version not supported.","inReplyTo":"handshake","type":"error"} + ]== "CMake Server" ==] + + +Type "progress" +^^^^^^^^^^^^^^^ + +When the server is busy for a long time, it is polite to send back replies of +type "progress" to the client. These will contain a "progressMessage" with a +string describing the action currently taking place as well as +"progressMinimum", "progressMaximum" and "progressCurrent" with integer values +describing the range of progess. + +Messages of type "progress" will be followed by more "progress" messages or with +a message of type "reply" or "error" that complete the request. + +"progress" messages may not be emitted after the "reply" or "error" message for +the request that triggered the responses was delivered. + + +Type "message" +^^^^^^^^^^^^^^ + +A message is triggered when the server processes a request and produces some +form of output that should be displayed to the user. A Message has a "message" +with the actual text to display as well as a "title" with a suggested dialog +box title. + +Example:: + + [== "CMake Server" ==[ + {"cookie":"","message":"Something happened.","title":"Title Text","inReplyTo":"handshake","type":"message"} + ]== "CMake Server" ==] + + +Type "signal" +^^^^^^^^^^^^^ + +The server can send signals when it detects changes in the system state. Signals +are of type "signal", have an empty "cookie" and "inReplyTo" field and always +have a "name" set to show which signal was sent. + + +Specific Signals +---------------- + +The cmake server may sent signals with the following names: + +"dirty" Signal +^^^^^^^^^^^^^^ + +The "dirty" signal is sent whenever the server determines that the configuration +of the project is no longer up-to-date. This happens when any of the files that have +an influence on the build system is changed. + +The "dirty" signal may look like this:: + + [== "CMake Server" ==[ + { + "cookie":"", + "inReplyTo":"", + "name":"dirty", + "type":"signal"} + ]== "CMake Server" ==] + + +"fileChange" Signal +^^^^^^^^^^^^^^^^^^^ + +The "fileChange" signal is sent whenever a watched file is changed. It contains +the "path" that has changed and a list of "properties" with the kind of change +that was detected. Possible changes are "change" and "rename". + +The "fileChange" signal looks like this:: + + [== "CMake Server" ==[ + { + "cookie":"", + "inReplyTo":"", + "name":"fileChange", + "path":"/absolute/CMakeLists.txt", + "properties":["change"], + "type":"signal"} + ]== "CMake Server" ==] + + +Specific Message Types +---------------------- + + +Type "hello" +^^^^^^^^^^^^ + +The initial message send by the cmake server on startup is of type "hello". +This is the only message ever sent by the server that is not of type "reply", +"progress" or "error". + +It will contain "supportedProtocolVersions" with an array of server protocol +versions supported by the cmake server. These are JSON objects with "major" and +"minor" keys containing non-negative integer values. Some versions may be marked +as experimental. These will contain the "isExperimental" key set to true. Enabling +these requires a special command line argument when starting the cmake server mode. + +Example:: + + [== "CMake Server" ==[ + {"supportedProtocolVersions":[{"major":0,"minor":1}],"type":"hello"} + ]== "CMake Server" ==] + + +Type "handshake" +^^^^^^^^^^^^^^^^ + +The first request that the client may send to the server is of type "handshake". + +This request needs to pass one of the "supportedProtocolVersions" of the "hello" +type response received earlier back to the server in the "protocolVersion" field. + +Each protocol version may request additional attributes to be present. + +Protocol version 1.0 requires the following attributes to be set: + + * "sourceDirectory" with a path to the sources + * "buildDirectory" with a path to the build directory + * "generator" with the generator name + * "extraGenerator" (optional!) with the extra generator to be used + * "platform" with the generator platform (if supported by the generator) + * "toolset" with the generator toolset (if supported by the generator) + +Example:: + + [== "CMake Server" ==[ + {"cookie":"zimtstern","type":"handshake","protocolVersion":{"major":0}, + "sourceDirectory":"/home/code/cmake", "buildDirectory":"/tmp/testbuild", + "generator":"Ninja"} + ]== "CMake Server" ==] + +which will result in a response type "reply":: + + [== "CMake Server" ==[ + {"cookie":"zimtstern","inReplyTo":"handshake","type":"reply"} + ]== "CMake Server" ==] + +indicating that the server is ready for action. + + +Type "globalSettings" +^^^^^^^^^^^^^^^^^^^^^ + +This request can be sent after the initial handshake. It will return a +JSON structure with information on cmake state. + +Example:: + + [== "CMake Server" ==[ + {"type":"globalSettings"} + ]== "CMake Server" ==] + +which will result in a response type "reply":: + + [== "CMake Server" ==[ + { + "buildDirectory": "/tmp/test-build", + "capabilities": { + "generators": [ + { + "extraGenerators": [], + "name": "Watcom WMake", + "platformSupport": false, + "toolsetSupport": false + }, + <...> + ], + "serverMode": false, + "version": { + "isDirty": false, + "major": 3, + "minor": 6, + "patch": 20160830, + "string": "3.6.20160830-gd6abad", + "suffix": "gd6abad" + } + }, + "checkSystemVars": false, + "cookie": "", + "extraGenerator": "", + "generator": "Ninja", + "debugOutput": false, + "inReplyTo": "globalSettings", + "sourceDirectory": "/home/code/cmake", + "trace": false, + "traceExpand": false, + "type": "reply", + "warnUninitialized": false, + "warnUnused": false, + "warnUnusedCli": true + } + ]== "CMake Server" ==] + + +Type "setGlobalSettings" +^^^^^^^^^^^^^^^^^^^^^^^^ + +This request can be sent to change the global settings attributes. Unknown +attributes are going to be ignored. Read-only attributes reported by +"globalSettings" are all capabilities, buildDirectory, generator, +extraGenerator and sourceDirectory. Any attempt to set these will be ignored, +too. + +All other settings will be changed. + +The server will respond with an empty reply message or an error. + +Example:: + + [== "CMake Server" ==[ + {"type":"setGlobalSettings","debugOutput":true} + ]== "CMake Server" ==] + +CMake will reply to this with:: + + [== "CMake Server" ==[ + {"inReplyTo":"setGlobalSettings","type":"reply"} + ]== "CMake Server" ==] + + +Type "configure" +^^^^^^^^^^^^^^^^ + +This request will configure a project for build. + +To configure a build directory already containing cmake files, it is enough to +set "buildDirectory" via "setGlobalSettings". To create a fresh build directory +you also need to set "currentGenerator" and "sourceDirectory" via "setGlobalSettings" +in addition to "buildDirectory". + +You may a list of strings to "configure" via the "cacheArguments" key. These +strings will be interpreted similar to command line arguments related to +cache handling that are passed to the cmake command line client. + +Example:: + + [== "CMake Server" ==[ + {"type":"configure", "cacheArguments":["-Dsomething=else"]} + ]== "CMake Server" ==] + +CMake will reply like this (after reporting progress for some time):: + + [== "CMake Server" ==[ + {"cookie":"","inReplyTo":"configure","type":"reply"} + ]== "CMake Server" ==] + + +Type "compute" +^^^^^^^^^^^^^^ + +This request will generate build system files in the build directory and +is only available after a project was successfully "configure"d. + +Example:: + + [== "CMake Server" ==[ + {"type":"compute"} + ]== "CMake Server" ==] + +CMake will reply (after reporting progress information):: + + [== "CMake Server" ==[ + {"cookie":"","inReplyTo":"compute","type":"reply"} + ]== "CMake Server" ==] + + +Type "codemodel" +^^^^^^^^^^^^^^^^ + +The "codemodel" request can be used after a project was "compute"d successfully. + +It will list the complete project structure as it is known to cmake. + +The reply will contain a key "configurations", which will contain a list of +configuration objects. Configuration objects are used to destinquish between +different configurations the build directory might have enabled. While most +generators only support one configuration, others might support several. + +Each configuration object can have the following keys: + +"name" + contains the name of the configuration. The name may be empty. +"projects" + contains a list of project objects, one for each build project. + +Project objects define one (sub-)project defined in the cmake build system. + +Each project object can have the following keys: + +"name" + contains the (sub-)projects name. +"sourceDirectory" + contains the current source directory +"buildDirectory" + contains the current build directory. +"targets" + contains a list of build system target objects. + +Target objects define individual build targets for a certain configuration. + +Each target object can have the following keys: + +"name" + contains the name of the target. +"type" + defines the type of build of the target. Possible values are + "STATIC_LIBRARY", "MODULE_LIBRARY", "SHARED_LIBRARY", "OBJECT_LIBRARY", + "EXECUTABLE", "UTILITY" and "INTERFACE_LIBRARY". +"fullName" + contains the full name of the build result (incl. extensions, etc.). +"sourceDirectory" + contains the current source directory. +"buildDirectory" + contains the current build directory. +"artifacts" + with a list of build artifacts. The list is sorted with the most + important artifacts first (e.g. a .DLL file is listed before a + .PDB file on windows). +"linkerLanguage" + contains the language of the linker used to produce the artifact. +"linkLibraries" + with a list of libraries to link to. This value is encoded in the + system's native shell format. +"linkFlags" + with a list of flags to pass to the linker. This value is encoded in + the system's native shell format. +"linkLanguageFlags" + with the flags for a compiler using the linkerLanguage. This value is + encoded in the system's native shell format. +"frameworkPath" + with the framework path (on Apple computers). This value is encoded + in the system's native shell format. +"linkPath" + with the link path. This value is encoded in the system's native shell + format. +"sysroot" + with the sysroot path. +"fileGroups" + contains the source files making up the target. + +FileGroups are used to group sources using similar settings together. + +Each fileGroup object may contain the following keys: + +"language" + contains the programming language used by all files in the group. +"compileFlags" + with a string containing all the flags passed to the compiler + when building any of the files in this group. This value is encoded in + the system's native shell format. +"includePath" + with a list of include paths. Each include path is an object + containing a "path" with the actual include path and "isSystem" with a bool + value informing whether this is a normal include or a system include. This + value is encoded in the system's native shell format. +"defines" + with a list of defines in the form "SOMEVALUE" or "SOMEVALUE=42". This + value is encoded in the system's native shell format. +"sources" + with a list of source files. + +All file paths in the fileGroup are either absolute or relative to the +sourceDirectory of the target. + +Example:: + + [== "CMake Server" ==[ + {"type":"codemodel"} + ]== "CMake Server" ==] + +CMake will reply:: + + [== "CMake Server" ==[ + { + "configurations": [ + { + "name": "", + "projects": [ + { + "buildDirectory": "/tmp/build/Source/CursesDialog/form", + "name": "CMAKE_FORM", + "sourceDirectory": "/home/code/src/cmake/Source/CursesDialog/form", + "targets": [ + { + "artifacts": [ "/tmp/build/Source/CursesDialog/form/libcmForm.a" ], + "buildDirectory": "/tmp/build/Source/CursesDialog/form", + "fileGroups": [ + { + "compileFlags": " -std=gnu11", + "defines": [ "CURL_STATICLIB", "LIBARCHIVE_STATIC" ], + "includePath": [ { "path": "/tmp/build/Utilities" }, <...> ], + "isGenerated": false, + "language": "C", + "sources": [ "fld_arg.c", <...> ] + } + ], + "fullName": "libcmForm.a", + "linkerLanguage": "C", + "name": "cmForm", + "sourceDirectory": "/home/code/src/cmake/Source/CursesDialog/form", + "type": "STATIC_LIBRARY" + } + ] + }, + <...> + ] + } + ], + "cookie": "", + "inReplyTo": "codemodel", + "type": "reply" + } + ]== "CMake Server" ==] + + +Type "cmakeInputs" +^^^^^^^^^^^^^^^^^^ + +The "cmakeInputs" requests will report files used by CMake as part +of the build system itself. + +This request is only available after a project was successfully +"configure"d. + +Example:: + + [== "CMake Server" ==[ + {"type":"cmakeInputs"} + ]== "CMake Server" ==] + +CMake will reply with the following information:: + + [== "CMake Server" ==[ + {"buildFiles": + [ + {"isCMake":true,"isTemporary":false,"sources":["/usr/lib/cmake/...", ... ]}, + {"isCMake":false,"isTemporary":false,"sources":["CMakeLists.txt", ...]}, + {"isCMake":false,"isTemporary":true,"sources":["/tmp/build/CMakeFiles/...", ...]} + ], + "cmakeRootDirectory":"/usr/lib/cmake", + "sourceDirectory":"/home/code/src/cmake", + "cookie":"", + "inReplyTo":"cmakeInputs", + "type":"reply" + } + ]== "CMake Server" ==] + +All file names are either relative to the top level source directory or +absolute. + +The list of files which "isCMake" set to true are part of the cmake installation. + +The list of files witch "isTemporary" set to true are part of the build directory +and will not survive the build directory getting cleaned out. + + +Type "cache" +^^^^^^^^^^^^ + +The "cache" request can be used once a project is configured and will +list the cached configuration values. + +Example:: + + [== "CMake Server" ==[ + {"type":"cache"} + ]== "CMake Server" ==] + +CMake will respond with the following output:: + + [== "CMake Server" ==[ + { + "cookie":"","inReplyTo":"cache","type":"reply", + "cache": + [ + { + "key":"SOMEVALUE", + "properties": + { + "ADVANCED":"1", + "HELPSTRING":"This is not helpful" + } + "type":"STRING", + "value":"TEST"} + ] + } + ]== "CMake Server" ==] + +The output can be limited to a list of keys by passing an array of key names +to the "keys" optional field of the "cache" request. + + +Type "fileSystemWatchers" +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The server can watch the filesystem for changes. The "fileSystemWatchers" +command will report on the files and directories watched. + +Example:: + + [== "CMake Server" ==[ + {"type":"fileSystemWatchers"} + ]== "CMake Server" ==] + +CMake will respond with the following output:: + + [== "CMake Server" ==[ + { + "cookie":"","inReplyTo":"fileSystemWatchers","type":"reply", + "watchedFiles": [ "/absolute/path" ], + "watchedDirectories": [ "/absolute" ] + } + ]== "CMake Server" ==] diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst index 390220c..74eab2d 100644 --- a/Help/manual/cmake-toolchains.7.rst +++ b/Help/manual/cmake-toolchains.7.rst @@ -290,12 +290,206 @@ Windows Store may look like this: set(CMAKE_SYSTEM_NAME WindowsStore) set(CMAKE_SYSTEM_VERSION 8.1) -Cross Compiling using NVIDIA Nsight Tegra ------------------------------------------ +.. _`Cross Compiling for Android`: -A toolchain file to configure a Visual Studio generator to -build using NVIDIA Nsight Tegra targeting Android may look -like this: +Cross Compiling for Android +--------------------------- + +A toolchain file may configure cross-compiling for Android by setting the +:variable:`CMAKE_SYSTEM_NAME` variable to ``Android``. Further configuration +is specific to the Android development environment to be used. + +For :ref:`Visual Studio Generators`, CMake expects :ref:`NVIDIA Nsight Tegra +Visual Studio Edition <Cross Compiling for Android with NVIDIA Nsight Tegra +Visual Studio Edition>` to be installed. See that section for further +configuration details. + +For :ref:`Makefile Generators` and the :generator:`Ninja` generator, +CMake expects one of these environments: + +* :ref:`NDK <Cross Compiling for Android with the NDK>` +* :ref:`Standalone Toolchain <Cross Compiling for Android with a Standalone Toolchain>` + +CMake uses the following steps to select one of the environments: + +* If the :variable:`CMAKE_ANDROID_NDK` variable is set, the NDK at the + specified location will be used. + +* Else, if the :variable:`CMAKE_ANDROID_STANDALONE_TOOLCHAIN` variable + is set, the Standalone Toolchain at the specified location will be used. + +* Else, if the :variable:`CMAKE_SYSROOT` variable is set to a directory + of the form ``<ndk>/platforms/android-<api>/arch-<arch>``, the ``<ndk>`` + part will be used as the value of :variable:`CMAKE_ANDROID_NDK` and the + NDK will be used. + +* Else, if the :variable:`CMAKE_SYSROOT` variable is set to a directory of the + form ``<standalone-toolchain>/sysroot``, the ``<standalone-toolchain>`` part + will be used as the value of :variable:`CMAKE_ANDROID_STANDALONE_TOOLCHAIN` + and the Standalone Toolchain will be used. + +* Else, if a cmake variable ``ANDROID_NDK`` is set it will be used + as the value of :variable:`CMAKE_ANDROID_NDK`, and the NDK will be used. + +* Else, if a cmake variable ``ANDROID_STANDALONE_TOOLCHAIN`` is set, it will be + used as the value of :variable:`CMAKE_ANDROID_STANDALONE_TOOLCHAIN`, and the + Standalone Toolchain will be used. + +* Else, if an environment variable ``ANDROID_NDK_ROOT`` or + ``ANDROID_NDK`` is set, it will be used as the value of + :variable:`CMAKE_ANDROID_NDK`, and the NDK will be used. + +* Else, if an environment variable ``ANDROID_STANDALONE_TOOLCHAIN`` is + set then it will be used as the value of + :variable:`CMAKE_ANDROID_STANDALONE_TOOLCHAIN`, and the Standalone + Toolchain will be used. + +* Else, an error diagnostic will be issued that neither the NDK or + Standalone Toolchain can be found. + +.. _`Cross Compiling for Android with the NDK`: + +Cross Compiling for Android with the NDK +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A toolchain file may configure :ref:`Makefile Generators` or the +:generator:`Ninja` generator to target Android for cross-compiling. + +Configure use of an Android NDK with the following variables: + +:variable:`CMAKE_SYSTEM_NAME` + Set to ``Android``. Must be specified to enable cross compiling + for Android. + +:variable:`CMAKE_SYSTEM_VERSION` + Set to the Android API level. If not specified, the value is + determined as follows: + + * If the :variable:`CMAKE_ANDROID_API` variable is set, its value + is used as the API level. + * If the :variable:`CMAKE_SYSROOT` variable is set, the API level is + detected from the NDK directory structure containing the sysroot. + * Otherwise, the latest API level available in the NDK is used. + +:variable:`CMAKE_ANDROID_ARCH_ABI` + Set to the Android ABI (architecture). If not specified, this + variable will default to ``armeabi``. + The :variable:`CMAKE_ANDROID_ARCH` variable will be computed + from ``CMAKE_ANDROID_ARCH_ABI`` automatically. + Also see the :variable:`CMAKE_ANDROID_ARM_MODE` and + :variable:`CMAKE_ANDROID_ARM_NEON` variables. + +:variable:`CMAKE_ANDROID_NDK` + Set to the absolute path to the Android NDK root directory. + A ``${CMAKE_ANDROID_NDK}/platforms`` directory must exist. + If not specified, a default for this variable will be chosen + as specified :ref:`above <Cross Compiling for Android>`. + +:variable:`CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION` + Set to the version of the NDK toolchain to be selected as the compiler. + If not specified, the latest available GCC toolchain will be used. + +:variable:`CMAKE_ANDROID_STL_TYPE` + Set to specify which C++ standard library to use. If not specified, + a default will be selected as described in the variable documentation. + +The following variables will be computed and provided automatically: + +:variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX` + The absolute path prefix to the binutils in the NDK toolchain. + +:variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX` + The host platform suffix of the binutils in the NDK toolchain. + + +For example, a toolchain file might contain: + +.. code-block:: cmake + + set(CMAKE_SYSTEM_NAME Android) + set(CMAKE_SYSTEM_VERSION 21) # API level + set(CMAKE_ANDROID_ARCH_ABI arm64-v8a) + set(CMAKE_ANDROID_NDK /path/to/android-ndk) + set(CMAKE_ANDROID_STL_TYPE gnustl_static) + +Alternatively one may specify the values without a toolchain file: + +.. code-block:: console + + $ cmake ../src \ + -DCMAKE_SYSTEM_NAME=Android \ + -DCMAKE_SYSTEM_VERSION=21 \ + -DCMAKE_ANDROID_ARCH_ABI=arm64-v8a \ + -DCMAKE_ANDROID_NDK=/path/to/android-ndk \ + -DCMAKE_ANDROID_STL_TYPE=gnustl_static + +.. _`Cross Compiling for Android with a Standalone Toolchain`: + +Cross Compiling for Android with a Standalone Toolchain +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A toolchain file may configure :ref:`Makefile Generators` or the +:generator:`Ninja` generator to target Android for cross-compiling +using a standalone toolchain. + +Configure use of an Android standalone toolchain with the following variables: + +:variable:`CMAKE_SYSTEM_NAME` + Set to ``Android``. Must be specified to enable cross compiling + for Android. + +:variable:`CMAKE_ANDROID_STANDALONE_TOOLCHAIN` + Set to the absolute path to the standalone toolchain root directory. + A ``${CMAKE_ANDROID_STANDALONE_TOOLCHAIN}/sysroot`` directory + must exist. + If not specified, a default for this variable will be chosen + as specified :ref:`above <Cross Compiling for Android>`. + +:variable:`CMAKE_ANDROID_ARM_MODE` + When the standalone toolchain targets ARM, optionally set this to ``ON`` + to target 32-bit ARM instead of 16-bit Thumb. + See variable documentation for details. + +:variable:`CMAKE_ANDROID_ARM_NEON` + When the standalone toolchain targets ARM v7, optionally set thisto ``ON`` + to target ARM NEON devices. See variable documentation for details. + +The following variables will be computed and provided automatically: + +:variable:`CMAKE_SYSTEM_VERSION` + The Android API level detected from the standalone toolchain. + +:variable:`CMAKE_ANDROID_ARCH_ABI` + The Android ABI detected from the standalone toolchain. + +:variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX` + The absolute path prefix to the binutils in the standalone toolchain. + +:variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX` + The host platform suffix of the binutils in the standalone toolchain. + +For example, a toolchain file might contain: + +.. code-block:: cmake + + set(CMAKE_SYSTEM_NAME Android) + set(CMAKE_ANDROID_STANDALONE_TOOLCHAIN /path/to/android-toolchain) + +Alternatively one may specify the values without a toolchain file: + +.. code-block:: console + + $ cmake ../src \ + -DCMAKE_SYSTEM_NAME=Android \ + -DCMAKE_ANDROID_STANDALONE_TOOLCHAIN=/path/to/android-toolchain + +.. _`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio Edition`: + +Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio Edition +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A toolchain file to configure one of the :ref:`Visual Studio Generators` +to build using NVIDIA Nsight Tegra targeting Android may look like this: .. code-block:: cmake diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 85b8eae..93e809a 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -38,6 +38,8 @@ Variables that Provide Information /variable/CMAKE_EXTRA_GENERATOR /variable/CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES /variable/CMAKE_FIND_PACKAGE_NAME + /variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION + /variable/CMAKE_FIND_PACKAGE_SORT_ORDER /variable/CMAKE_GENERATOR /variable/CMAKE_GENERATOR_PLATFORM /variable/CMAKE_GENERATOR_TOOLSET @@ -80,6 +82,7 @@ Variables that Provide Information /variable/CMAKE_VS_NsightTegra_VERSION /variable/CMAKE_VS_PLATFORM_NAME /variable/CMAKE_VS_PLATFORM_TOOLSET + /variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION /variable/CMAKE_XCODE_PLATFORM_TOOLSET /variable/PROJECT_BINARY_DIR @@ -110,6 +113,7 @@ Variables that Change Behavior /variable/CMAKE_AUTOMOC_RELAXED_MODE /variable/CMAKE_BACKWARDS_COMPATIBILITY /variable/CMAKE_BUILD_TYPE + /variable/CMAKE_CODELITE_USE_TARGETS /variable/CMAKE_COLOR_MAKEFILE /variable/CMAKE_CONFIGURATION_TYPES /variable/CMAKE_DEBUG_TARGET_PROPERTIES @@ -156,6 +160,8 @@ Variables that Change Behavior /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE /variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY /variable/CMAKE_STAGING_PREFIX + /variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS + /variable/CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE /variable/CMAKE_SYSTEM_APPBUNDLE_PATH /variable/CMAKE_SYSTEM_FRAMEWORK_PATH /variable/CMAKE_SYSTEM_IGNORE_PATH @@ -173,6 +179,7 @@ Variables that Describe the System .. toctree:: :maxdepth: 1 + /variable/ANDROID /variable/APPLE /variable/BORLAND /variable/CMAKE_CL_64 @@ -213,6 +220,7 @@ Variables that Describe the System /variable/WINCE /variable/WINDOWS_PHONE /variable/WINDOWS_STORE + /variable/XCODE /variable/XCODE_VERSION Variables that Control the Build @@ -225,6 +233,9 @@ Variables that Control the Build /variable/CMAKE_ANDROID_API /variable/CMAKE_ANDROID_API_MIN /variable/CMAKE_ANDROID_ARCH + /variable/CMAKE_ANDROID_ARCH_ABI + /variable/CMAKE_ANDROID_ARM_MODE + /variable/CMAKE_ANDROID_ARM_NEON /variable/CMAKE_ANDROID_ASSETS_DIRECTORIES /variable/CMAKE_ANDROID_GUI /variable/CMAKE_ANDROID_JAR_DEPENDENCIES @@ -232,11 +243,14 @@ Variables that Control the Build /variable/CMAKE_ANDROID_JAVA_SOURCE_DIR /variable/CMAKE_ANDROID_NATIVE_LIB_DEPENDENCIES /variable/CMAKE_ANDROID_NATIVE_LIB_DIRECTORIES + /variable/CMAKE_ANDROID_NDK + /variable/CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION /variable/CMAKE_ANDROID_PROCESS_MAX /variable/CMAKE_ANDROID_PROGUARD /variable/CMAKE_ANDROID_PROGUARD_CONFIG_PATH /variable/CMAKE_ANDROID_SECURE_PROPS_PATH /variable/CMAKE_ANDROID_SKIP_ANT_STEP + /variable/CMAKE_ANDROID_STANDALONE_TOOLCHAIN /variable/CMAKE_ANDROID_STL_TYPE /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG @@ -246,6 +260,7 @@ Variables that Control the Build /variable/CMAKE_AUTORCC_OPTIONS /variable/CMAKE_AUTOUIC /variable/CMAKE_AUTOUIC_OPTIONS + /variable/CMAKE_BUILD_RPATH /variable/CMAKE_BUILD_WITH_INSTALL_RPATH /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG @@ -253,7 +268,9 @@ Variables that Control the Build /variable/CMAKE_DEBUG_POSTFIX /variable/CMAKE_ENABLE_EXPORTS /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG + /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT /variable/CMAKE_EXE_LINKER_FLAGS + /variable/CMAKE_EXE_LINKER_FLAGS_INIT /variable/CMAKE_Fortran_FORMAT /variable/CMAKE_Fortran_MODULE_DIRECTORY /variable/CMAKE_GNUtoMS @@ -275,11 +292,14 @@ Variables that Control the Build /variable/CMAKE_LINK_INTERFACE_LIBRARIES /variable/CMAKE_LINK_LIBRARY_FILE_FLAG /variable/CMAKE_LINK_LIBRARY_FLAG + /variable/CMAKE_LINK_WHAT_YOU_USE /variable/CMAKE_MACOSX_BUNDLE /variable/CMAKE_MACOSX_RPATH /variable/CMAKE_MAP_IMPORTED_CONFIG_CONFIG /variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG + /variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT /variable/CMAKE_MODULE_LINKER_FLAGS + /variable/CMAKE_MODULE_LINKER_FLAGS_INIT /variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX /variable/CMAKE_NO_BUILTIN_CHRPATH /variable/CMAKE_NO_SYSTEM_FROM_IMPORTED @@ -292,11 +312,15 @@ Variables that Control the Build /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG /variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG + /variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG_INIT /variable/CMAKE_SHARED_LINKER_FLAGS + /variable/CMAKE_SHARED_LINKER_FLAGS_INIT /variable/CMAKE_SKIP_BUILD_RPATH /variable/CMAKE_SKIP_INSTALL_RPATH /variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG + /variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT /variable/CMAKE_STATIC_LINKER_FLAGS + /variable/CMAKE_STATIC_LINKER_FLAGS_INIT /variable/CMAKE_TRY_COMPILE_CONFIGURATION /variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES /variable/CMAKE_TRY_COMPILE_TARGET_TYPE @@ -315,7 +339,9 @@ Variables for Languages .. toctree:: :maxdepth: 1 - /variable/CMAKE_COMPILER_IS_GNULANG + /variable/CMAKE_COMPILER_IS_GNUCC + /variable/CMAKE_COMPILER_IS_GNUCXX + /variable/CMAKE_COMPILER_IS_GNUG77 /variable/CMAKE_C_COMPILE_FEATURES /variable/CMAKE_C_EXTENSIONS /variable/CMAKE_C_STANDARD @@ -328,6 +354,8 @@ Variables for Languages /variable/CMAKE_Fortran_MODDIR_FLAG /variable/CMAKE_Fortran_MODOUT_FLAG /variable/CMAKE_INTERNAL_PLATFORM_ABI + /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_PREFIX + /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_SUFFIX /variable/CMAKE_LANG_ARCHIVE_APPEND /variable/CMAKE_LANG_ARCHIVE_CREATE /variable/CMAKE_LANG_ARCHIVE_FINISH @@ -343,10 +371,15 @@ Variables for Languages /variable/CMAKE_LANG_CREATE_SHARED_MODULE /variable/CMAKE_LANG_CREATE_STATIC_LIBRARY /variable/CMAKE_LANG_FLAGS_DEBUG + /variable/CMAKE_LANG_FLAGS_DEBUG_INIT /variable/CMAKE_LANG_FLAGS_MINSIZEREL + /variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT /variable/CMAKE_LANG_FLAGS_RELEASE + /variable/CMAKE_LANG_FLAGS_RELEASE_INIT /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO + /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT /variable/CMAKE_LANG_FLAGS + /variable/CMAKE_LANG_FLAGS_INIT /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE @@ -368,6 +401,7 @@ Variables for Languages /variable/CMAKE_LANG_SOURCE_FILE_EXTENSIONS /variable/CMAKE_LANG_STANDARD_INCLUDE_DIRECTORIES /variable/CMAKE_LANG_STANDARD_LIBRARIES + /variable/CMAKE_Swift_LANGUAGE_VERSION /variable/CMAKE_USER_MAKE_RULES_OVERRIDE_LANG Variables for CTest diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 65153af..063aea1 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -108,6 +108,11 @@ Options Like ``--trace``, but with variables expanded. +``--trace-source=<file>`` + Put cmake in trace mode, but output only lines of a specified file. + + Multiple options are allowed. + ``--warn-uninitialized`` Warn about uninitialized values. @@ -175,6 +180,43 @@ CMake provides builtin command-line tools through the signature:: Run ``cmake -E`` or ``cmake -E help`` for a summary of commands. Available commands are: +``capabilities`` + Report cmake capabilities in JSON format. The output is a JSON object + with the following keys: + + ``version`` + A JSON object with version information. Keys are: + + ``string`` + The full version string as displayed by cmake ``--version``. + ``major`` + The major version number in integer form. + ``minor`` + The minor version number in integer form. + ``patch`` + The patch level in integer form. + ``suffix`` + The cmake version suffix string. + ``isDirty`` + A bool that is set if the cmake build is from a dirty tree. + + ``generators`` + A list available generators. Each generator is a JSON object with the + following keys: + + ``name`` + A string containing the name of the generator. + ``toolsetSupport`` + ``true`` if the generator supports toolsets and ``false`` otherwise. + ``platformSupport`` + ``true`` if the generator supports platforms and ``false`` otherwise. + ``extraGenerators`` + A list of strings with all the extra generators compatible with + the generator. + + ``serverMode`` + ``true`` if cmake supports server-mode and ``false`` otherwise. + ``chdir <dir> <cmd> [<arg>...]`` Change the current working directory and run a command. @@ -231,6 +273,9 @@ Available commands are: ``rename <oldname> <newname>`` Rename a file or directory (on one volume). +``server`` + Launch :manual:`cmake-server(7)` mode. + ``sleep <number>...`` Sleep for given number of seconds. diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index e797333..ce81578 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -56,7 +56,7 @@ Options Enable failover. This option allows ctest to resume a test set execution that was - previously interrupted. If no interruption occurred, the -F option + previously interrupted. If no interruption occurred, the ``-F`` option will have no effect. ``-j <jobs>, --parallel <jobs>`` @@ -77,12 +77,12 @@ Options Make ctest quiet. This option will suppress all the output. The output log file will - still be generated if the --output-log is specified. Options such - as --verbose, --extra-verbose, and --debug are ignored if --quiet is - specified. + still be generated if the ``--output-log`` is specified. Options such + as ``--verbose``, ``--extra-verbose``, and ``--debug`` are ignored + if ``--quiet`` is specified. ``-O <file>, --output-log <file>`` - Output to log file + Output to log file. This option tells ctest to write all its output to a log file. @@ -90,7 +90,7 @@ Options Disable actual execution of tests. This option tells ctest to list the tests that would be run but not - actually run them. Useful in conjunction with the -R and -E + actually run them. Useful in conjunction with the ``-R`` and ``-E`` options. ``-L <regex>, --label-regex <regex>`` @@ -118,7 +118,7 @@ Options given regular expression. ``-D <dashboard>, --dashboard <dashboard>`` - Execute dashboard test + Execute dashboard test. This option tells ctest to act as a CDash client and perform a dashboard test. All tests are <Mode><Test>, where Mode can be @@ -126,26 +126,27 @@ Options Update, Configure, Build, Test, Coverage, and Submit. ``-D <var>:<type>=<value>`` - Define a variable for script mode + Define a variable for script mode. Pass in variable values on the command line. Use in conjunction - with -S to pass variable values to a dashboard script. Parsing -D + with ``-S`` to pass variable values to a dashboard script. Parsing ``-D`` arguments as variable values is only attempted if the value - following -D does not match any of the known dashboard types. + following ``-D`` does not match any of the known dashboard types. ``-M <model>, --test-model <model>`` - Sets the model for a dashboard + Sets the model for a dashboard. - This option tells ctest to act as a CDash client where the TestModel - can be Experimental, Nightly, and Continuous. Combining -M and -T - is similar to -D + This option tells ctest to act as a CDash client where the ``<model>`` + can be ``Experimental``, ``Nightly``, and ``Continuous``. + Combining ``-M`` and ``-T`` is similar to ``-D``. ``-T <action>, --test-action <action>`` - Sets the dashboard action to perform + Sets the dashboard action to perform. This option tells ctest to act as a CDash client and perform some - action such as start, build, test etc. Combining -M and -T is - similar to -D + action such as ``start``, ``build``, ``test`` etc. See + `Dashboard Client Steps`_ for the full list of actions. + Combining ``-M`` and ``-T`` is similar to ``-D``. ``--track <track>`` Specify the track to submit dashboard to @@ -156,24 +157,24 @@ Options arbitrary. ``-S <script>, --script <script>`` - Execute a dashboard for a configuration + Execute a dashboard for a configuration. This option tells ctest to load in a configuration script which sets a number of parameters such as the binary and source directories. Then ctest will do what is required to create and run a dashboard. - This option basically sets up a dashboard and then runs ctest -D + This option basically sets up a dashboard and then runs ``ctest -D`` with the appropriate options. ``-SP <script>, --script-new-process <script>`` - Execute a dashboard for a configuration + Execute a dashboard for a configuration. - This option does the same operations as -S but it will do them in a + This option does the same operations as ``-S`` but it will do them in a separate process. This is primarily useful in cases where the script may modify the environment and you do not want the modified - environment to impact other -S scripts. + environment to impact other ``-S`` scripts. ``-A <file>, --add-notes <file>`` - Add a notes file with submission + Add a notes file with submission. This option tells ctest to include a notes file when submitting dashboard. @@ -188,19 +189,19 @@ Options contains the same syntax as the command line. ``-U, --union`` - Take the Union of -I and -R + Take the Union of ``-I`` and ``-R``. - When both -R and -I are specified by default the intersection of - tests are run. By specifying -U the union of tests is run instead. + When both ``-R`` and ``-I`` are specified by default the intersection of + tests are run. By specifying ``-U`` the union of tests is run instead. ``--rerun-failed`` - Run only the tests that failed previously + Run only the tests that failed previously. This option tells ctest to perform only the tests that failed during its previous run. When this option is specified, ctest ignores all - other options intended to modify the list of tests to run (-L, -R, - -E, -LE, -I, etc). In the event that CTest runs and no tests fail, - subsequent calls to ctest with the --rerun-failed option will run + other options intended to modify the list of tests to run (``-L``, ``-R``, + ``-E``, ``-LE``, ``-I``, etc). In the event that CTest runs and no tests + fail, subsequent calls to ctest with the ``--rerun-failed`` option will run the set of tests that most recently failed (if any). ``--repeat-until-fail <n>`` @@ -209,7 +210,7 @@ Options This is useful in finding sporadic failures in test cases. ``--max-width <width>`` - Set the max width for a test name to output + Set the max width for a test name to output. Set the maximum width for each test name to show in the output. This allows the user to widen the output to avoid clipping the test @@ -232,26 +233,25 @@ Options label associated with the tests run. If there are no labels on the tests, nothing extra is printed. -``--build-and-test`` +``--build-and-test <path-to-source> <path-to-build>`` Configure, build and run a test. This option tells ctest to configure (i.e. run cmake on), build, and or execute a test. The configure and test steps are optional. The arguments to this command line are the source and binary - directories. By default this will run CMake on the Source/Bin - directories specified unless --build-nocmake is specified. - The --build-generator option *must* be provided to use - --build-and-test. If --test-command is specified then that will be + directories. + The ``--build-generator`` option *must* be provided to use + ``--build-and-test``. If ``--test-command`` is specified then that will be run after the build is complete. Other options that affect this - mode are --build-target --build-nocmake, --build-run-dir, - --build-two-config, --build-exe-dir, - --build-project,--build-noclean, --build-options + mode are ``--build-target``, ``--build-nocmake``, ``--build-run-dir``, + ``--build-two-config``, ``--build-exe-dir``, + ``--build-project``, ``--build-noclean`` and ``--build-options``. ``--build-target`` Specify a specific target to build. - This option goes with the --build-and-test option, if left out the - all target is built. + This option goes with the ``--build-and-test`` option, if left out the + ``all`` target is built. ``--build-nocmake`` Run the build without running cmake first. @@ -264,13 +264,13 @@ Options Directory where programs will be after it has been compiled. ``--build-two-config`` - Run CMake twice + Run CMake twice. ``--build-exe-dir`` Specify the directory for the executable. ``--build-generator`` - Specify the generator to use. + Specify the generator to use. See the :manual:`cmake-generators(7)` manual. ``--build-generator-platform`` Specify the generator-specific platform. @@ -288,25 +288,23 @@ Options Skip the make clean step. ``--build-config-sample`` - A sample executable to use to determine the configuration - A sample executable to use to determine the configuration that - should be used. e.g. Debug/Release/etc + should be used. e.g. Debug/Release/etc. ``--build-options`` Add extra options to the build step. This option must be the last option with the exception of - --test-command + ``--test-command`` ``--test-command`` - The test to run with the --build-and-test option. + The test to run with the ``--build-and-test`` option. ``--test-output-size-passed <size>`` - Limit the output for passed tests to <size> bytes. + Limit the output for passed tests to ``<size>`` bytes. ``--test-output-size-failed <size>`` - Limit the output for failed tests to <size> bytes. + Limit the output for failed tests to ``<size>`` bytes. ``--test-timeout`` The time limit in seconds, internal use only. @@ -335,14 +333,14 @@ Options This option will submit extra files to the dashboard. ``--force-new-ctest-process`` - Run child CTest instances as new processes + Run child CTest instances as new processes. By default CTest will run child CTest instances within the same process. If this behavior is not desired, this argument will enforce new processes for child CTest processes. ``--schedule-random`` - Use a random order for scheduling tests + Use a random order for scheduling tests. This option will run the tests in a random order. It is commonly used to detect implicit dependencies in a test suite. @@ -361,7 +359,7 @@ Options Set a time at which all tests should stop running. Set a real time of day at which all tests should timeout. Example: - 7:00:00 -0400. Any time format understood by the curl date parser + ``7:00:00 -0400``. Any time format understood by the curl date parser is accepted. Local time is assumed if no timezone is specified. ``--http1.0`` diff --git a/Help/module/AndroidTestUtilities.rst b/Help/module/AndroidTestUtilities.rst new file mode 100644 index 0000000..e7ec864 --- /dev/null +++ b/Help/module/AndroidTestUtilities.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/AndroidTestUtilities.cmake diff --git a/Help/module/CPackProductBuild.rst b/Help/module/CPackProductBuild.rst new file mode 100644 index 0000000..6081fe4 --- /dev/null +++ b/Help/module/CPackProductBuild.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CPackProductBuild.cmake diff --git a/Help/module/FindICU.rst b/Help/module/FindICU.rst new file mode 100644 index 0000000..ee3f4a9 --- /dev/null +++ b/Help/module/FindICU.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindICU.cmake diff --git a/Help/module/FindVulkan.rst b/Help/module/FindVulkan.rst new file mode 100644 index 0000000..adf824e --- /dev/null +++ b/Help/module/FindVulkan.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindVulkan.cmake diff --git a/Help/policy/CMP0066.rst b/Help/policy/CMP0066.rst new file mode 100644 index 0000000..d1dcb0e --- /dev/null +++ b/Help/policy/CMP0066.rst @@ -0,0 +1,27 @@ +CMP0066 +------- + +Honor per-config flags in :command:`try_compile` source-file signature. + +The source file signature of the :command:`try_compile` command uses the value +of the :variable:`CMAKE_<LANG>_FLAGS` variable in the test project so that the +test compilation works as it would in the main project. However, CMake 3.6 and +below do not also honor config-specific compiler flags such as those in the +:variable:`CMAKE_<LANG>_FLAGS_DEBUG` variable. CMake 3.7 and above prefer to +honor config-specific compiler flags too. This policy provides compatibility +for projects that do not expect config-specific compiler flags to be used. + +The ``OLD`` behavior of this policy is to ignore config-specific flag +variables like :variable:`CMAKE_<LANG>_FLAGS_DEBUG` and only use CMake's +built-in defaults for the current compiler and platform. + +The ``NEW`` behavior of this policy is to honor config-specific flag +variabldes like :variable:`CMAKE_<LANG>_FLAGS_DEBUG`. + +This policy was introduced in CMake version 3.7. 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_CMP0066 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/prop_dir/BINARY_DIR.rst b/Help/prop_dir/BINARY_DIR.rst new file mode 100644 index 0000000..597c79a --- /dev/null +++ b/Help/prop_dir/BINARY_DIR.rst @@ -0,0 +1,5 @@ +BINARY_DIR +---------- + +This read-only directory property reports absolute path to the binary +directory corresponding to the source on which it is read. diff --git a/Help/prop_dir/BUILDSYSTEM_TARGETS.rst b/Help/prop_dir/BUILDSYSTEM_TARGETS.rst new file mode 100644 index 0000000..da907cb --- /dev/null +++ b/Help/prop_dir/BUILDSYSTEM_TARGETS.rst @@ -0,0 +1,11 @@ +BUILDSYSTEM_TARGETS +------------------- + +This read-only directory property contains a +:ref:`;-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 +:ref:`Interface Libraries`. Each entry in the list is the logical name +of a target, suitable to pass to the :command:`get_property` command +``TARGET`` option. diff --git a/Help/prop_dir/SOURCE_DIR.rst b/Help/prop_dir/SOURCE_DIR.rst new file mode 100644 index 0000000..ac98c3b --- /dev/null +++ b/Help/prop_dir/SOURCE_DIR.rst @@ -0,0 +1,5 @@ +SOURCE_DIR +---------- + +This read-only directory property reports absolute path to the source +directory on which it is read. diff --git a/Help/prop_dir/SUBDIRECTORIES.rst b/Help/prop_dir/SUBDIRECTORIES.rst new file mode 100644 index 0000000..2c2ea77 --- /dev/null +++ b/Help/prop_dir/SUBDIRECTORIES.rst @@ -0,0 +1,15 @@ +SUBDIRECTORIES +-------------- + +This read-only directory property contains a +:ref:`;-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 +``DIRECTORY`` option. + +.. note:: + + The :command:`subdirs` command does not process its arguments until + after the calling directory is fully processed. Therefore looking + up this property in the current directory will not see them. diff --git a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst index e8f4d2a..00a5104 100644 --- a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst @@ -14,6 +14,15 @@ compile features and a list of supported compilers. The features known to this version of CMake are: +``cxx_std_98`` + Compiler mode is aware of C++ 98. + +``cxx_std_11`` + Compiler mode is aware of C++ 11. + +``cxx_std_14`` + Compiler mode is aware of C++ 14. + ``cxx_aggregate_default_initializers`` Aggregate default initializers, as defined in N3605_. diff --git a/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst index a08af00..3707fef 100644 --- a/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst @@ -13,6 +13,15 @@ compile features and a list of supported compilers. The features known to this version of CMake are: +``c_std_90`` + Compiler mode is aware of C 90. + +``c_std_99`` + Compiler mode is aware of C 99. + +``c_std_11`` + Compiler mode is aware of C 11. + ``c_function_prototypes`` Function prototypes, as defined in ``ISO/IEC 9899:1990``. diff --git a/Help/prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS.rst b/Help/prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS.rst new file mode 100644 index 0000000..ce18b65 --- /dev/null +++ b/Help/prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS.rst @@ -0,0 +1,10 @@ +FIND_LIBRARY_USE_LIB32_PATHS +---------------------------- + +Whether the :command:`find_library` command should automatically search +``lib32`` directories. + +``FIND_LIBRARY_USE_LIB32_PATHS`` is a boolean specifying whether the +:command:`find_library` command should automatically search the ``lib32`` +variant of directories called ``lib`` in the search path when building 32-bit +binaries. diff --git a/Help/prop_sf/COMPILE_FLAGS.rst b/Help/prop_sf/COMPILE_FLAGS.rst index 086a063..1012164 100644 --- a/Help/prop_sf/COMPILE_FLAGS.rst +++ b/Help/prop_sf/COMPILE_FLAGS.rst @@ -6,3 +6,10 @@ Additional flags to be added when compiling this source file. These flags will be added to the list of compile flags when this source file builds. Use :prop_sf:`COMPILE_DEFINITIONS` to pass additional preprocessor definitions. + +Contents of ``COMPILE_FLAGS`` may use "generator expressions" +with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. However, :generator:`Xcode` +does not support per-config per-source settings, so expressions +that depend on the build configuration are not allowed with that +generator. diff --git a/Help/prop_sf/VS_TOOL_OVERRIDE.rst b/Help/prop_sf/VS_TOOL_OVERRIDE.rst new file mode 100644 index 0000000..8bdc5ca --- /dev/null +++ b/Help/prop_sf/VS_TOOL_OVERRIDE.rst @@ -0,0 +1,5 @@ +VS_TOOL_OVERRIDE +---------------- + +Override the default Visual Studio tool that will be applied to the source file +with a new tool not based on the extension of the file. diff --git a/Help/prop_sf/XCODE_FILE_ATTRIBUTES.rst b/Help/prop_sf/XCODE_FILE_ATTRIBUTES.rst new file mode 100644 index 0000000..39e6966 --- /dev/null +++ b/Help/prop_sf/XCODE_FILE_ATTRIBUTES.rst @@ -0,0 +1,11 @@ +XCODE_FILE_ATTRIBUTES +--------------------- + +Add values to the Xcode ``ATTRIBUTES`` setting on its reference to a +source file. Among other things, this can be used to set the role on +a mig file:: + + set_source_files_properties(defs.mig + PROPERTIES + XCODE_FILE_ATTRIBUTES "Client;Server" + ) diff --git a/Help/prop_test/DEPENDS.rst b/Help/prop_test/DEPENDS.rst index ee946d9..89c7553 100644 --- a/Help/prop_test/DEPENDS.rst +++ b/Help/prop_test/DEPENDS.rst @@ -3,4 +3,8 @@ DEPENDS Specifies that this test should only be run after the specified list of tests. -Set this to a list of tests that must finish before this test is run. +Set this to a list of tests that must finish before this test is run. The +results of those tests are not considered, the dependency relationship is +purely for order of execution (i.e. it is really just a *run after* +relationship). Consider using test fixtures with setup tests if a dependency +with successful completion is required (see :prop_test:`FIXTURES_REQUIRED`). diff --git a/Help/prop_test/FIXTURES_CLEANUP.rst b/Help/prop_test/FIXTURES_CLEANUP.rst new file mode 100644 index 0000000..f0a4be0 --- /dev/null +++ b/Help/prop_test/FIXTURES_CLEANUP.rst @@ -0,0 +1,46 @@ +FIXTURES_CLEANUP +---------------- + +Specifies a list of fixtures for which the test is to be treated as a cleanup +test. + +Fixture cleanup tests are ordinary tests with all of the usual test +functionality. Setting the ``FIXTURES_CLEANUP`` property for a test has two +primary effects: + +- CTest will ensure the test executes after all other tests which list any of + the fixtures in its :prop_test:`FIXTURES_REQUIRED` property. + +- If CTest is asked to run only a subset of tests (e.g. using regular + expressions or the ``--rerun-failed`` option) and the cleanup test is not in + the set of tests to run, it will automatically be added if any tests in the + set require any fixture listed in ``FIXTURES_CLEANUP``. + +A cleanup test can have multiple fixtures listed in its ``FIXTURES_CLEANUP`` +property. It will execute only once for the whole CTest run, not once for each +fixture. A fixture can also have more than one cleanup test defined. If there +are multiple cleanup tests for a fixture, projects can control their order with +the usual :prop_test:`DEPENDS` test property if necessary. + +A cleanup test is allowed to require other fixtures, but not any fixture listed +in its ``FIXTURES_CLEANUP`` property. For example: + +.. code-block:: cmake + + # Ok: Dependent fixture is different to cleanup + set_tests_properties(cleanupFoo PROPERTIES + FIXTURES_CLEANUP Foo + FIXTURES_REQUIRED Bar + ) + + # Error: cannot require same fixture as cleanup + set_tests_properties(cleanupFoo PROPERTIES + FIXTURES_CLEANUP Foo + FIXTURES_REQUIRED Foo + ) + +Cleanup tests will execute even if setup or regular tests for that fixture fail +or are skipped. + +See :prop_test:`FIXTURES_REQUIRED` for a more complete discussion of how to use +test fixtures. diff --git a/Help/prop_test/FIXTURES_REQUIRED.rst b/Help/prop_test/FIXTURES_REQUIRED.rst new file mode 100644 index 0000000..e37dfb5 --- /dev/null +++ b/Help/prop_test/FIXTURES_REQUIRED.rst @@ -0,0 +1,94 @@ +FIXTURES_REQUIRED +----------------- + +Specifies a list of fixtures the test requires. Fixture names are case +sensitive. + +Fixtures are a way to attach setup and cleanup tasks to a set of tests. If a +test requires a given fixture, then all tests marked as setup tasks for that +fixture will be executed first (once for the whole set of tests, not once per +test requiring the fixture). After all tests requiring a particular fixture +have completed, CTest will ensure all tests marked as cleanup tasks for that +fixture are then executed. Tests are marked as setup tasks with the +:prop_test:`FIXTURES_SETUP` property and as cleanup tasks with the +:prop_test:`FIXTURES_CLEANUP` property. If any of a fixture's setup tests fail, +all tests listing that fixture in their ``FIXTURES_REQUIRED`` property will not +be executed. The cleanup tests for the fixture will always be executed, even if +some setup tests fail. + +When CTest is asked to execute only a subset of tests (e.g. by the use of +regular expressions or when run with the ``--rerun-failed`` command line +option), it will automatically add any setup or cleanup tests for fixtures +required by any of the tests that are in the execution set. + +Since setup and cleanup tasks are also tests, they can have an ordering +specified by the :prop_test:`DEPENDS` test property just like any other tests. +This can be exploited to implement setup or cleanup using multiple tests for a +single fixture to modularise setup or cleanup logic. + +The concept of a fixture is different to that of a resource specified by +:prop_test:`RESOURCE_LOCK`, but they may be used together. A fixture defines a +set of tests which share setup and cleanup requirements, whereas a resource +lock has the effect of ensuring a particular set of tests do not run in +parallel. Some situations may need both, such as setting up a database, +serialising test access to that database and deleting the database again at the +end. For such cases, tests would populate both ``FIXTURES_REQUIRED`` and +:prop_test:`RESOURCE_LOCK` to combine the two behaviours. Names used for +:prop_test:`RESOURCE_LOCK` have no relationship with names of fixtures, so note +that a resource lock does not imply a fixture and vice versa. + +Consider the following example which represents a database test scenario +similar to that mentioned above: + +.. code-block:: cmake + + add_test(NAME testsDone COMMAND emailResults) + add_test(NAME fooOnly COMMAND testFoo) + add_test(NAME dbOnly COMMAND testDb) + add_test(NAME dbWithFoo COMMAND testDbWithFoo) + add_test(NAME createDB COMMAND initDB) + add_test(NAME setupUsers COMMAND userCreation) + add_test(NAME cleanupDB COMMAND deleteDB) + add_test(NAME cleanupFoo COMMAND removeFoos) + + set_tests_properties(setupUsers PROPERTIES DEPENDS createDB) + + set_tests_properties(createDB PROPERTIES FIXTURES_SETUP DB) + set_tests_properties(setupUsers PROPERTIES FIXTURES_SETUP DB) + set_tests_properties(cleanupDB PROPERTIES FIXTURES_CLEANUP DB) + set_tests_properties(cleanupFoo PROPERTIES FIXTURES_CLEANUP Foo) + set_tests_properties(testsDone PROPERTIES FIXTURES_CLEANUP "DB;Foo") + + set_tests_properties(fooOnly PROPERTIES FIXTURES_REQUIRED Foo) + set_tests_properties(dbOnly PROPERTIES FIXTURES_REQUIRED DB) + set_tests_properties(dbWithFoo PROPERTIES FIXTURES_REQUIRED "DB;Foo") + + set_tests_properties(dbOnly dbWithFoo createDB setupUsers cleanupDB + PROPERTIES RESOURCE_LOCK DbAccess) + +Key points from this example: + +- Two fixtures are defined: ``DB`` and ``Foo``. Tests can require a single + fixture as ``fooOnly`` and ``dbOnly`` do, or they can depend on multiple + fixtures like ``dbWithFoo`` does. + +- A ``DEPENDS`` relationship is set up to ensure ``setupUsers`` happens after + ``createDB``, both of which are setup tests for the ``DB`` fixture and will + therefore be executed before the ``dbOnly`` and ``dbWithFoo`` tests + automatically. + +- No explicit ``DEPENDS`` relationships were needed to make the setup tests run + before or the cleanup tests run after the regular tests. + +- The ``Foo`` fixture has no setup tests defined, only a single cleanup test. + +- ``testsDone`` is a cleanup test for both the ``DB`` and ``Foo`` fixtures. + Therefore, it will only execute once regular tests for both fixtures have + finished (i.e. after ``fooOnly``, ``dbOnly`` and ``dbWithFoo``). No + ``DEPENDS`` relationship was specified for ``testsDone``, so it is free to + run before, after or concurrently with other cleanup tests for either + fixture. + +- The setup and cleanup tests never list the fixtures they are for in their own + ``FIXTURES_REQUIRED`` property, as that would result in a dependency on + themselves and be considered an error. diff --git a/Help/prop_test/FIXTURES_SETUP.rst b/Help/prop_test/FIXTURES_SETUP.rst new file mode 100644 index 0000000..a220215 --- /dev/null +++ b/Help/prop_test/FIXTURES_SETUP.rst @@ -0,0 +1,47 @@ +FIXTURES_SETUP +-------------- + +Specifies a list of fixtures for which the test is to be treated as a setup +test. + +Fixture setup tests are ordinary tests with all of the usual test +functionality. Setting the ``FIXTURES_SETUP`` property for a test has two +primary effects: + +- CTest will ensure the test executes before any other test which lists the + fixture(s) in its :prop_test:`FIXTURES_REQUIRED` property. + +- If CTest is asked to run only a subset of tests (e.g. using regular + expressions or the ``--rerun-failed`` option) and the setup test is not in + the set of tests to run, it will automatically be added if any tests in the + set require any fixture listed in ``FIXTURES_SETUP``. + +A setup test can have multiple fixtures listed in its ``FIXTURES_SETUP`` +property. It will execute only once for the whole CTest run, not once for each +fixture. A fixture can also have more than one setup test defined. If there are +multiple setup tests for a fixture, projects can control their order with the +usual :prop_test:`DEPENDS` test property if necessary. + +A setup test is allowed to require other fixtures, but not any fixture listed +in its ``FIXTURES_SETUP`` property. For example: + +.. code-block:: cmake + + # Ok: dependent fixture is different to setup + set_tests_properties(setupFoo PROPERTIES + FIXTURES_SETUP Foo + FIXTURES_REQUIRED Bar + ) + + # Error: cannot require same fixture as setup + set_tests_properties(setupFoo PROPERTIES + FIXTURES_SETUP Foo + FIXTURES_REQUIRED Foo + ) + +If any of a fixture's setup tests fail, none of the tests listing that fixture +in its :prop_test:`FIXTURES_REQUIRED` property will be run. Cleanup tests will, +however, still be executed. + +See :prop_test:`FIXTURES_REQUIRED` for a more complete discussion of how to use +test fixtures. diff --git a/Help/prop_test/RESOURCE_LOCK.rst b/Help/prop_test/RESOURCE_LOCK.rst index 8c30f01..755e0aa 100644 --- a/Help/prop_test/RESOURCE_LOCK.rst +++ b/Help/prop_test/RESOURCE_LOCK.rst @@ -5,3 +5,6 @@ Specify a list of resources that are locked by this test. If multiple tests specify the same resource lock, they are guaranteed not to run concurrently. + +See also :prop_test:`FIXTURES_REQUIRED` if the resource requires any setup or +cleanup steps. diff --git a/Help/prop_test/TIMEOUT_AFTER_MATCH.rst b/Help/prop_test/TIMEOUT_AFTER_MATCH.rst index a191a9c..d607992 100644 --- a/Help/prop_test/TIMEOUT_AFTER_MATCH.rst +++ b/Help/prop_test/TIMEOUT_AFTER_MATCH.rst @@ -22,7 +22,9 @@ When the test outputs a line that matches ``regex`` its start time is reset to the current time and its timeout duration is changed to ``seconds``. Prior to this, the timeout duration is determined by the :prop_test:`TIMEOUT` property or the :variable:`CTEST_TEST_TIMEOUT` -variable if either of these are set. +variable if either of these are set. Because the test's start time is +reset, its execution time will not include any time that was spent +waiting for the matching output. :prop_test:`TIMEOUT_AFTER_MATCH` is useful for avoiding spurious timeouts when your test must wait for some system resource to become diff --git a/Help/prop_tgt/ANDROID_API.rst b/Help/prop_tgt/ANDROID_API.rst index 714ad58..63464d7 100644 --- a/Help/prop_tgt/ANDROID_API.rst +++ b/Help/prop_tgt/ANDROID_API.rst @@ -1,7 +1,8 @@ ANDROID_API ----------- -Set the Android Target API version (e.g. ``15``). The version number -must be a positive decimal integer. This property is initialized by -the value of the :variable:`CMAKE_ANDROID_API` variable if it is set -when a target is created. +When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio +Edition`, this property sets the Android target API version (e.g. ``15``). +The version number must be a positive decimal integer. This property is +initialized by the value of the :variable:`CMAKE_ANDROID_API` variable if +it is set when a target is created. diff --git a/Help/prop_tgt/ANDROID_ARCH.rst b/Help/prop_tgt/ANDROID_ARCH.rst index 5477fb5..3e07e5a 100644 --- a/Help/prop_tgt/ANDROID_ARCH.rst +++ b/Help/prop_tgt/ANDROID_ARCH.rst @@ -1,7 +1,8 @@ ANDROID_ARCH ------------ -Set the Android target architecture. +When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio +Edition`, this property sets the Android target architecture. This is a string property that could be set to the one of the following values: diff --git a/Help/prop_tgt/ANDROID_GUI.rst b/Help/prop_tgt/ANDROID_GUI.rst index abdba7a..92e2041 100644 --- a/Help/prop_tgt/ANDROID_GUI.rst +++ b/Help/prop_tgt/ANDROID_GUI.rst @@ -1,7 +1,9 @@ ANDROID_GUI ----------- -Build an executable as an application package on Android. +When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio +Edition`, this property specifies whether to build an executable as an +application package on Android. When this property is set to true the executable when built for Android will be created as an application package. This property is initialized diff --git a/Help/prop_tgt/ANDROID_STL_TYPE.rst b/Help/prop_tgt/ANDROID_STL_TYPE.rst index 7256e26..386e96e 100644 --- a/Help/prop_tgt/ANDROID_STL_TYPE.rst +++ b/Help/prop_tgt/ANDROID_STL_TYPE.rst @@ -1,15 +1,27 @@ ANDROID_STL_TYPE ---------------- -Set the Android property that defines the type of STL support for the project. +When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio +Edition`, this property specifies the type of STL support for the project. This is a string property that could set to the one of the following values: -``none`` e.g. "No C++ Support" -``system`` e.g. "Minimal C++ without STL" -``gabi++_static`` e.g. "GAbi++ Static" -``gabi++_shared`` e.g. "GAbi++ Shared" -``gnustl_static`` e.g. "GNU libstdc++ Static" -``gnustl_shared`` e.g. "GNU libstdc++ Shared" -``stlport_static`` e.g. "STLport Static" -``stlport_shared`` e.g. "STLport Shared" + +``none`` + No C++ Support +``system`` + Minimal C++ without STL +``gabi++_static`` + GAbi++ Static +``gabi++_shared`` + GAbi++ Shared +``gnustl_static`` + GNU libstdc++ Static +``gnustl_shared`` + GNU libstdc++ Shared +``stlport_static`` + STLport Static +``stlport_shared`` + STLport Shared + This property is initialized by the value of the -variable:`CMAKE_ANDROID_STL_TYPE` variable if it is set when a target is created. +:variable:`CMAKE_ANDROID_STL_TYPE` variable if it is set when a target is +created. diff --git a/Help/prop_tgt/AUTORCC.rst b/Help/prop_tgt/AUTORCC.rst index 8dce6b1..158fdf8 100644 --- a/Help/prop_tgt/AUTORCC.rst +++ b/Help/prop_tgt/AUTORCC.rst @@ -19,5 +19,10 @@ Additional command line options for rcc can be set via the The global property :prop_gbl:`AUTOGEN_TARGETS_FOLDER` can be used to group the autorcc targets together in an IDE, e.g. in MSVS. +When there are multiple ``.qrc`` files with the same name, CMake will +generate unspecified unique names for ``rcc``. Therefore if +``Q_INIT_RESOURCE()`` or ``Q_CLEANUP_RESOURCE()`` need to be used the +``.qrc`` file name must be unique. + See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. diff --git a/Help/prop_tgt/BUILD_RPATH.rst b/Help/prop_tgt/BUILD_RPATH.rst new file mode 100644 index 0000000..27393f5 --- /dev/null +++ b/Help/prop_tgt/BUILD_RPATH.rst @@ -0,0 +1,10 @@ +BUILD_RPATH +----------- + +A :ref:`;-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. + +This property is initialized by the value of the variable +:variable:`CMAKE_BUILD_RPATH` if it is set when a target is created. diff --git a/Help/prop_tgt/BUNDLE_EXTENSION.rst b/Help/prop_tgt/BUNDLE_EXTENSION.rst index ea265b3..6b3d580 100644 --- a/Help/prop_tgt/BUNDLE_EXTENSION.rst +++ b/Help/prop_tgt/BUNDLE_EXTENSION.rst @@ -1,7 +1,8 @@ BUNDLE_EXTENSION ---------------- -The file extension used to name a :prop_tgt:`BUNDLE` target on the OS X and iOS. +The file extension used to name a :prop_tgt:`BUNDLE`, a :prop_tgt:`FRAMEWORK`, +or a :prop_tgt:`MACOSX_BUNDLE` target on the OS X and iOS. -The default value is ``bundle`` - you can also use ``plugin`` or whatever -file extension is required by the host app for your bundle. +The default value is ``bundle``, ``framework``, or ``app`` for the respective +target types. diff --git a/Help/prop_tgt/LINK_WHAT_YOU_USE.rst b/Help/prop_tgt/LINK_WHAT_YOU_USE.rst new file mode 100644 index 0000000..32d6edb --- /dev/null +++ b/Help/prop_tgt/LINK_WHAT_YOU_USE.rst @@ -0,0 +1,15 @@ +LINK_WHAT_YOU_USE +--------------------------- + +This is a boolean option that when set to ``TRUE`` will automatically run +``ldd -r -u`` on the target after it is linked. In addition, the linker flag +``-Wl,--no-as-needed`` will be passed to the target with the link command so +that all libraries specified on the command line will be linked into the +target. This will result in the link producing a list of libraries that +provide no symbols used by this target but are being linked to it. +This is only applicable to executable and shared library targets and +will only work when ld and ldd accept the flags used. + +This property is initialized by the value of +the :variable:`CMAKE_LINK_WHAT_YOU_USE` variable if it is set +when a target is created. diff --git a/Help/prop_tgt/MAP_IMPORTED_CONFIG_CONFIG.rst b/Help/prop_tgt/MAP_IMPORTED_CONFIG_CONFIG.rst index 09ff0ce..4da855b 100644 --- a/Help/prop_tgt/MAP_IMPORTED_CONFIG_CONFIG.rst +++ b/Help/prop_tgt/MAP_IMPORTED_CONFIG_CONFIG.rst @@ -1,19 +1,25 @@ MAP_IMPORTED_CONFIG_<CONFIG> ---------------------------- -Map from project configuration to IMPORTED target's configuration. +Map from project configuration to +:ref:`imported target <IMPORTED targets>`'s configuration. Set this to the list of configurations of an imported target that may -be used for the current project's <CONFIG> configuration. Targets +be used for the current project's ``<CONFIG>`` configuration. Targets imported from another project may not provide the same set of configuration names available in the current project. Setting this property tells CMake what imported configurations are suitable for use -when building the <CONFIG> configuration. The first configuration in -the list found to be provided by the imported target is selected. If -this property is set and no matching configurations are available, +when building the ``<CONFIG>`` configuration. The first configuration in +the list found to be provided by the imported target (i.e. via +:prop_tgt:`IMPORTED_LOCATION_<CONFIG>` for the mapped-to ``<CONFIG>``) +is selected. As a special case, an empty list element refers to the +configuration-less imported target location +(i.e. :prop_tgt:`IMPORTED_LOCATION`). + +If this property is set and no matching configurations are available, then the imported target is considered to be not found. This property is ignored for non-imported targets. -This property is initialized by the value of the variable -CMAKE_MAP_IMPORTED_CONFIG_<CONFIG> if it is set when a target is -created. +This property is initialized by the value of the +:variable:`CMAKE_MAP_IMPORTED_CONFIG_<CONFIG>` variable if it is set when a +target is created. diff --git a/Help/prop_tgt/VS_SDK_REFERENCES.rst b/Help/prop_tgt/VS_SDK_REFERENCES.rst new file mode 100644 index 0000000..769a0d1 --- /dev/null +++ b/Help/prop_tgt/VS_SDK_REFERENCES.rst @@ -0,0 +1,7 @@ +VS_SDK_REFERENCES +----------------- + +Visual Studio project SDK references. +Specify a :ref:`;-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/prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS.rst b/Help/prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS.rst index 3f48af8..06c3e6d 100644 --- a/Help/prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS.rst +++ b/Help/prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS.rst @@ -5,8 +5,9 @@ This property is implemented only for MS-compatible tools on Windows. Enable this boolean property to automatically create a module definition (``.def``) file with all global symbols found in the input ``.obj`` files -for a ``SHARED`` library on Windows. The module definition file will be -passed to the linker causing all symbols to be exported from the ``.dll``. +for a ``SHARED`` library (or executable with :prop_tgt:`ENABLE_EXPORTS`) +on Windows. The module definition file will be passed to the linker +causing all symbols to be exported from the ``.dll``. For global *data* symbols, ``__declspec(dllimport)`` must still be used when compiling against the code in the ``.dll``. All other function symbols will be automatically exported and imported by callers. This simplifies porting diff --git a/Help/release/3.7.rst b/Help/release/3.7.rst new file mode 100644 index 0000000..3b8ade6 --- /dev/null +++ b/Help/release/3.7.rst @@ -0,0 +1,320 @@ +CMake 3.7 Release Notes +*********************** + +.. only:: html + + .. contents:: + +Changes made since CMake 3.6 include the following. + +New Features +============ + +Platforms +--------- + +* CMake now supports :ref:`Cross Compiling for Android` with simple + toolchain files. + +* The Clang compiler is now supported on AIX. + +Generators +---------- + +* The :generator:`Ninja` generator learned to conditionally support + Fortran when using a ``ninja`` tool that has the necessary features. + See generator documentation for details. + +* The :generator:`Ninja` generator learned to produce phony targets + of the form ``sub/dir/{test,install,package}`` to drive the build + of a subdirectory installation, test or packaging target. + This is equivalent to ``cd sub/dir; make {test,install,package}`` + with :ref:`Makefile Generators`. + +* The :generator:`Visual Studio 15` generator was added. This is + experimental and based on Preview 5 because this version of VS + has not been released. + +* :ref:`Visual Studio Generators` for VS 2010 and above learned to + place ``.natvis`` source files into VS project files properly. + +* The :generator:`Xcode` generator's rudimentary Swift language support + learned to honor a new :variable:`CMAKE_Swift_LANGUAGE_VERSION` variable + to tell Xcode what version of Swift is used by the source. + +* The :generator:`CodeLite` generator gained a new + :variable:`CMAKE_CODELITE_USE_TARGETS` option + to change project creation from projects to targets. + +Commands +-------- + +* The :command:`add_custom_command` command gained a new ``DEPFILE`` + option that works with the :generator:`Ninja` generator to provide + implicit dependency information to the build tool. + +* The :command:`cmake_parse_arguments` command gained a new ``PARSE_ARGV`` + mode to read arguments directly from ``ARGC`` and ``ARGV#`` + variables inside a :command:`function` body. + +* The :command:`export` command gained an ``ANDROID_MK`` option + to generate ``Android.mk`` files referencing CMake-built + libraries as prebuilts for the Android NDK build system. + +* The :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands gained + ``HTTPHEADER <HTTP-header>`` and ``USERPWD <username>:<password>`` options. + +* The :command:`find_library` and :command:`find_package` commands learned + to search in ``lib32/`` directories when the build targets a 32-bit + architecture. See the :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` global + property. + +* The :command:`find_package` command gained the possibility of + sorting compatible libraries by ``NAME`` or by ``NATURAL`` sorting by + setting the two new variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` + and :variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`. + +* The :command:`if` command gained new boolean comparison operations + ``LESS_EQUAL``, ``GREATER_EQUAL``, ``STRLESS_EQUAL``, ``STRGREATER_EQUAL``, + ``VERSION_LESS_EQUAL``, and ``VERSION_GREATER_EQUAL``. + +* The :command:`install` command gained an ``EXPORT_ANDROID_MK`` + subcommand to install ``Android.mk`` files referencing installed + libraries as prebuilts for the Android NDK build system. + +* The :command:`string(TIMESTAMP)` and :command:`file(TIMESTAMP)` + commands gained support for the ``%a`` and ``%b`` placeholders. + These are the abbreviated weekday and month names. + +* The :command:`try_compile` command source file signature now honors + configuration-specific flags (e.g. :variable:`CMAKE_<LANG>_FLAGS_DEBUG`) + in the generated test project. Previously only the default such flags + for the current toolchain were used. See policy :policy:`CMP0066`. + +Variables +--------- + +* Variable :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` was added to control + the sorting mode of the :command:`find_package` command. + +* Variable :variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION` was added to control + the sorting direction the :command:`find_package` command. + +* :variable:`Toolchain files <CMAKE_TOOLCHAIN_FILE>` may now set a + :variable:`CMAKE_<LANG>_FLAGS_INIT` variable to initialize the + :variable:`CMAKE_<LANG>_FLAGS` cache entry the first time a language is + enabled in a build tree. + +* :variable:`Toolchain files <CMAKE_TOOLCHAIN_FILE>` may now set + :variable:`CMAKE_EXE_LINKER_FLAGS_INIT`, + :variable:`CMAKE_SHARED_LINKER_FLAGS_INIT`, and + :variable:`CMAKE_MODULE_LINKER_FLAGS_INIT` variables to initialize the + :variable:`CMAKE_EXE_LINKER_FLAGS`, + :variable:`CMAKE_SHARED_LINKER_FLAGS`, and + :variable:`CMAKE_MODULE_LINKER_FLAGS` cache entries the first time + a language is enabled in a build tree. + +Properties +---------- + +* On Apple platforms the :prop_tgt:`BUNDLE_EXTENSION` target property + now also applies to Frameworks and App Bundles. + +* A :prop_dir:`BINARY_DIR` directory property was added to get the + absolute path to the binary directory corresponding to the source + directory on which the property is read. + +* A :prop_dir:`BUILDSYSTEM_TARGETS` directory property was added to + get the list of logical buildsystem target names added by the + project in a directory. + +* A :prop_tgt:`LINK_WHAT_YOU_USE` target property and supporting + :variable:`CMAKE_LINK_WHAT_YOU_USE` variable were introduced + to detect (on UNIX) shared libraries that are linked but not + needed by running ``ldd -r -u``. + +* A :prop_dir:`SOURCE_DIR` directory property was added to get the + absolute path to the source directory associated with a directory. + +* A :prop_dir:`SUBDIRECTORIES` directory property was added to + get the list of subdirectories added by a project in a directory. + +* A :prop_tgt:`VS_SDK_REFERENCES` target property was added to tell + :ref:`Visual Studio Generators` to reference the named SDKs. + +* A :prop_sf:`VS_TOOL_OVERRIDE` source file property was created to tell + :ref:`Visual Studio Generators` what tool to use for a source file. + +* The :prop_tgt:`WINDOWS_EXPORT_ALL_SYMBOLS` target property now applies + to executable targets with the :prop_tgt:`ENABLE_EXPORTS` property set. + +* A :prop_sf:`XCODE_FILE_ATTRIBUTES` source file property was + added to tell the :generator:`Xcode` generator to generate + custom content in the Xcode project attributes for the file. + +Modules +------- + +* An :module:`AndroidTestUtilities` module was added to manage transfer + of test data to an Android device. + +* The :module:`CheckFortranSourceCompiles` module macro + ``CHECK_Fortran_SOURCE_COMPILES`` gained a ``SRC_EXT`` option + to specify a custom test Fortran source file extension. + +* The :module:`ExternalProject` module gained ``HTTP_USERNAME`` and + ``HTTP_PASSWORD`` options to set http download credentials. + +* The :module:`ExternalProject` module gained a ``HTTP_HEADER`` + option to add http download headers. + +* The :module:`FindBISON` module ``BISON_TARGET`` macro learned a new + ``REPORT_FILE`` option to specify the bison ``--report-file=`` option. + +* The :module:`FindBZip2` module now provides imported targets. + +* A :module:`FindICU` module was introduced to find the International + Components for Unicode (ICU) libraries and programs. + +* The :module:`FindMatlab` module learned to find the SIMULINK and MAT + components. + +* The :module:`FindMatlab` module :command:`matlab_add_mex` command learned + to add executables and modules. + +* The :module:`FindMatlab` module :command:`matlab_add_unit_test` command + learned to support inline Matlab test code. + +* The :module:`FindOpenCL` module now provides imported targets. + +* The :module:`FindOpenMP` module learned to detect the OpenMP + version (specification date) from the compiler. + +* A :module:`FindVulkan` module was added. + +* The :module:`GenerateExportHeader` module learned a new + ``CUSTOM_CONTENT_FROM_VARIABLE`` option to specify a variable + containing custom content for inclusion in the generated header. + +* The :module:`GNUInstallDirs` module gained a new + :command:`GNUInstallDirs_get_absolute_install_dir` command. + +* The :module:`UseJava` module gained APIs to "export" jar targets + for use by external CMake projects. See the ``install_jar_exports`` + and ``export_jars`` functions. + +CTest +----- + +* CTest now supports test fixtures through the new :prop_test:`FIXTURES_SETUP`, + :prop_test:`FIXTURES_CLEANUP` and :prop_test:`FIXTURES_REQUIRED` test + properties. When using regular expressions or ``--rerun-failed`` to limit + the tests to be run, a fixture's setup and cleanup tests will automatically + be added to the execution set if any test requires that fixture. + +* The :command:`ctest_configure`, :command:`ctest_build`, + :command:`ctest_test`, :command:`ctest_coverage`, and :command:`ctest_upload` + commands gained a new ``CAPTURE_CMAKE_ERROR`` option to capture any errors + that occur as the commands run into a variable and avoid affecting the return + code of the :manual:`ctest(1)` process. + +CPack +----- + +* CPack gained a ``productbuild`` generator on OS X, configured by + the :module:`CPackProductBuild` module. + +* CPack gained a new :variable:`CPACK_PACKAGE_CHECKSUM` variable to + enable generation of a checksum file for each package file. + +* The :module:`CPackDeb` module learned to support long file names + when archive format is set to GNU tar. + See :variable:`CPACK_DEBIAN_ARCHIVE_TYPE` + +* The :module:`CPackIFW` module gained a new + :command:`cpack_ifw_add_package_resources` command to include additional + resources in the installer binary. + +* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and + :command:`cpack_ifw_configure_component_group` commands gained a new + ``USER_INTERFACES`` option to add a list of additonal pages to the IFW + installer. + +* The :module:`CPackRPM` module learned to generate debuginfo + packages on demand. See :variable:`CPACK_RPM_DEBUGINFO_PACKAGE` + and its per component version. + +* The :module:`CPackRPM` module learned to generate source rpm + (SRPM) packages on demand. See :variable:`CPACK_RPM_PACKAGE_SOURCES`, + :variable:`CPACK_RPM_SOURCE_PKG_BUILD_PARAMS` and + :variable:`CPACK_RPM_SOURCE_PKG_PACKAGING_INSTALL_PREFIX`. + +* The CPack NSIS generator now supports + :variable:`CPACK_NSIS_<compName>_INSTALL_DIRECTORY`. + This can be used to set component specific installation directories. + +* The CPack WIX generator now supports + :variable:`CPACK_WIX_SKIP_PROGRAM_FOLDER` to allow specification + of a custom absolute installation prefix outside + of the ProgramFiles folders. + +* The CPack WIX generator now supports + :variable:`CPACK_COMPONENT_<compName>_DISABLED`. + This can be used to deselect a component from being installed by default. + +* The CPack WIX generator now supports :variable:`CPACK_WIX_PATCH_FILE` + fragments for Feature elements. + +* The CPack WIX generator now supports + :variable:`CPACK_WIX_ROOT_FEATURE_TITLE` and + :variable:`CPACK_WIX_ROOT_FEATURE_DESCRIPTION` to allow the specification + of a custom title and description for the root feature element. + +Other +----- + +* :manual:`cmake(1)` gained a ``-E capabilities`` option to provide a + machine-readable (JSON) description of the capabilities of the + cmake tool (available generators, etc.). + +* A new :manual:`cmake-server(7)` mode was added to provide semantic + information about a CMake-generated buildsystem to clients through + a JSON protocol. Currently all protocols are experimental and subject + to change. + +* The :manual:`cmake(1)` command learned a ``--trace-source=<file>`` option. + +* :manual:`ccmake(1)` learned to support vim-like navigation bindings. + +* :manual:`cmake-gui(1)` gained a button to open the generated project file + for :ref:`Visual Studio Generators` and the :generator:`Xcode` generator. + +Deprecated and Removed Features +=============================== + +* We no longer provide Linux i386 binaries for download from ``cmake.org`` + for new versions of CMake. + +* Vim support files ``cmake-indent.vim``, ``cmake-syntax.vim``, and + ``cmake-help.vim`` have been removed in favor of the files now provided + from the `vim-cmake-syntax`_ project. + +* Support for building CMake itself with some compilers was dropped: + + * Visual Studio 7.1 and 2005 -- superseded by VS 2008 and above + * MinGW.org mingw32 -- superseded by MSYS2 mingw32 and mingw64 + + CMake still supports generating build systems for other projects using + these compilers. + +Other Changes +============= + +* The Fortran dependency scanner learned to support the syntax of + `Fortran Submodules`_. + +* Vim support files ``indent/cmake.vim`` and ``syntax/cmake.vim`` + from the `vim-cmake-syntax`_ project are now distributed with CMake. + +.. _`Fortran Submodules`: http://fortranwiki.org/fortran/show/Submodules +.. _`vim-cmake-syntax`: https://github.com/pboettch/vim-cmake-syntax 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/ExternalData-multiple-hashes.rst b/Help/release/dev/ExternalData-multiple-hashes.rst new file mode 100644 index 0000000..608a277 --- /dev/null +++ b/Help/release/dev/ExternalData-multiple-hashes.rst @@ -0,0 +1,7 @@ +ExternalData-multiple-hashes +---------------------------- + +* The :module:`ExternalData` module learned to support multiple + content links for one data file using different hashes, e.g. + ``img.png.sha256`` and ``img.png.sha1``. This allows objects + to be fetched from sources indexed by different hash algorithms. diff --git a/Help/release/dev/UseSWIG-SWIG_OUTFILE_DIR.rst b/Help/release/dev/UseSWIG-SWIG_OUTFILE_DIR.rst new file mode 100644 index 0000000..c001a88 --- /dev/null +++ b/Help/release/dev/UseSWIG-SWIG_OUTFILE_DIR.rst @@ -0,0 +1,6 @@ +UseSWIG-SWIG_OUTFILE_DIR +------------------------ + +* The :module:`UseSWIG` module ``swig_add_source_to_module`` command + learned a new ``SWIG_OUTFILE_DIR`` option to control the output + file location (``swig -o``). diff --git a/Help/release/dev/add-BUILD_RPATH.rst b/Help/release/dev/add-BUILD_RPATH.rst new file mode 100644 index 0000000..0d69e45 --- /dev/null +++ b/Help/release/dev/add-BUILD_RPATH.rst @@ -0,0 +1,6 @@ +add-BUILD_RPATH +--------------- + +* A :variable:`CMAKE_BUILD_RPATH` variable and corresponding + :prop_tgt:`BUILD_RPATH` target property were added to support custom + ``RPATH`` locations to be added to binaries in the build tree. diff --git a/Help/release/dev/allow-fallback-config-mapping.rst b/Help/release/dev/allow-fallback-config-mapping.rst new file mode 100644 index 0000000..2522e10 --- /dev/null +++ b/Help/release/dev/allow-fallback-config-mapping.rst @@ -0,0 +1,6 @@ +allow-fallback-config-mapping +----------------------------- + +* The :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` target property learned + to interpret empty list elements as referring to the configuration-less + imported location specified by :prop_tgt:`IMPORTED_LOCATION`. diff --git a/Help/release/dev/compile-features-for-language-standards.rst b/Help/release/dev/compile-features-for-language-standards.rst new file mode 100644 index 0000000..20473b7 --- /dev/null +++ b/Help/release/dev/compile-features-for-language-standards.rst @@ -0,0 +1,7 @@ +compile-features-for-language-standards +--------------------------------------- + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + now offers meta-features that request compiler modes for specific language + standard levels. See :prop_gbl:`CMAKE_C_KNOWN_FEATURES` and + :prop_gbl:`CMAKE_CXX_KNOWN_FEATURES`. diff --git a/Help/release/dev/cpack-rpm-single-debuginfo.rst b/Help/release/dev/cpack-rpm-single-debuginfo.rst new file mode 100644 index 0000000..34a710d --- /dev/null +++ b/Help/release/dev/cpack-rpm-single-debuginfo.rst @@ -0,0 +1,11 @@ +cpack-rpm-single-debuginfo +-------------------------- + +* The :module:`CPackRPM` module learned to generate main component package + which forces generation of a rpm for defined component without component + suffix in filename and package name. + See :variable:`CPACK_RPM_MAIN_COMPONENT` variable. + +* The :module:`CPackRPM` module learned to generate a single debuginfo package + on demand even if components packagin is used. + See :variable:`CPACK_RPM_DEBUGINFO_SINGLE_PACKAGE` variable. diff --git a/Help/release/dev/external-project-clone-progress.rst b/Help/release/dev/external-project-clone-progress.rst new file mode 100644 index 0000000..766a1a3 --- /dev/null +++ b/Help/release/dev/external-project-clone-progress.rst @@ -0,0 +1,5 @@ +external-project-clone-progress +------------------------------- + +* The :module:`ExternalProject` module gained the ``GIT_PROGRESS`` option to + force Git to show progress when cloning repositories. diff --git a/Help/release/dev/intel-compile-features-windows.rst b/Help/release/dev/intel-compile-features-windows.rst new file mode 100644 index 0000000..6a2cdfe --- /dev/null +++ b/Help/release/dev/intel-compile-features-windows.rst @@ -0,0 +1,6 @@ +intel-compile-features-windows +------------------------------ + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + is now aware of features supported by Intel C++ compilers versions 12.1 + through 17.0 on UNIX and Windows platforms. diff --git a/Help/release/dev/math-EXPR-unary.rst b/Help/release/dev/math-EXPR-unary.rst new file mode 100644 index 0000000..d4af15b --- /dev/null +++ b/Help/release/dev/math-EXPR-unary.rst @@ -0,0 +1,5 @@ +math-EXPR-unary +--------------- + +* The :command:`math(EXPR)` command gained support for unary + ``+`` and ``-`` expressions. diff --git a/Help/release/dev/src-COMPILE_FLAGS-genex.rst b/Help/release/dev/src-COMPILE_FLAGS-genex.rst new file mode 100644 index 0000000..26cd3ef --- /dev/null +++ b/Help/release/dev/src-COMPILE_FLAGS-genex.rst @@ -0,0 +1,5 @@ +src-COMPILE_FLAGS-genex +----------------------- + +* The :prop_sf:`COMPILE_FLAGS` source file property learned to support + :manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/release/dev/st2-env-settings.rst b/Help/release/dev/st2-env-settings.rst new file mode 100644 index 0000000..7b36347 --- /dev/null +++ b/Help/release/dev/st2-env-settings.rst @@ -0,0 +1,6 @@ +st2-env-settings +---------------- + +* The :generator:`Sublime Text 2` extra generator learned to place + environment variables in the generated ``.sublime-project``. + See the :variable:`CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS` variable. diff --git a/Help/release/dev/st2-exclude-patterns-variable.rst b/Help/release/dev/st2-exclude-patterns-variable.rst new file mode 100644 index 0000000..8706c1f --- /dev/null +++ b/Help/release/dev/st2-exclude-patterns-variable.rst @@ -0,0 +1,7 @@ +st2-exclude-patterns-variable +----------------------------- + +* The :generator:`Sublime Text 2` extra generator no longer excludes the + build tree from the ``.sublime-project`` when it is inside the source tree. + The :variable:`CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE` variable + was added to control the behavior explicitly. diff --git a/Help/release/dev/vs-host-x64-tools.rst b/Help/release/dev/vs-host-x64-tools.rst new file mode 100644 index 0000000..e42881a --- /dev/null +++ b/Help/release/dev/vs-host-x64-tools.rst @@ -0,0 +1,7 @@ +vs-host-x64-tools +----------------- + +* The :ref:`Visual Studio Generators` for VS 2013 and above learned to + support a ``host=x64`` option in the :variable:`CMAKE_GENERATOR_TOOLSET` + value (e.g. via the :manual:`cmake(1)` ``-T`` option) to request use + of a VS 64-bit toolchain on 64-bit hosts. diff --git a/Help/release/index.rst b/Help/release/index.rst index 92c3b63..30decd5 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -5,12 +5,15 @@ CMake Release Notes This file should include the adjacent "dev.txt" file in development versions but not in release versions. +.. include:: dev.txt + Releases ======== .. toctree:: :maxdepth: 1 + 3.7 <3.7> 3.6 <3.6> 3.5 <3.5> 3.4 <3.4> diff --git a/Help/variable/ANDROID.rst b/Help/variable/ANDROID.rst new file mode 100644 index 0000000..fede4ca --- /dev/null +++ b/Help/variable/ANDROID.rst @@ -0,0 +1,5 @@ +ANDROID +------- + +Set to ``1`` when the target system (:variable:`CMAKE_SYSTEM_NAME`) is +``Android``. diff --git a/Help/variable/CMAKE_ANDROID_API.rst b/Help/variable/CMAKE_ANDROID_API.rst index c8264e0..c07a05a 100644 --- a/Help/variable/CMAKE_ANDROID_API.rst +++ b/Help/variable/CMAKE_ANDROID_API.rst @@ -1,5 +1,11 @@ CMAKE_ANDROID_API ----------------- -Default value for the :prop_tgt:`ANDROID_API` target property. -See that target property for additional information. +When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio +Edition`, this variable may be set to specify the default value for the +:prop_tgt:`ANDROID_API` target property. See that target property for +additional information. + +Otherwise, when :ref:`Cross Compiling for Android`, this variable provides +the Android API version number targeted. This will be the same value as +the :variable:`CMAKE_SYSTEM_VERSION` variable for ``Android`` platforms. diff --git a/Help/variable/CMAKE_ANDROID_ARCH.rst b/Help/variable/CMAKE_ANDROID_ARCH.rst index 8fbb46d..b91ca57 100644 --- a/Help/variable/CMAKE_ANDROID_ARCH.rst +++ b/Help/variable/CMAKE_ANDROID_ARCH.rst @@ -1,5 +1,19 @@ CMAKE_ANDROID_ARCH ------------------ -Default value for the :prop_tgt:`ANDROID_ARCH` target property. -See that target property for additional information. +When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio +Edition`, this variable may be set to specify the default value for the +:prop_tgt:`ANDROID_ARCH` target property. See that target property for +additional information. + +Otherwise, when :ref:`Cross Compiling for Android`, this variable provides +the name of the Android architecture corresponding to the value of the +:variable:`CMAKE_ANDROID_ARCH_ABI` variable. The architecture name +may be one of: + +* ``arm`` +* ``arm64`` +* ``mips`` +* ``mips64`` +* ``x86`` +* ``x86_64`` diff --git a/Help/variable/CMAKE_ANDROID_ARCH_ABI.rst b/Help/variable/CMAKE_ANDROID_ARCH_ABI.rst new file mode 100644 index 0000000..0a3ed3c --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_ARCH_ABI.rst @@ -0,0 +1,17 @@ +CMAKE_ANDROID_ARCH_ABI +---------------------- + +When :ref:`Cross Compiling for Android`, this variable specifies the +target architecture and ABI to be used. Valid values are: + +* ``arm64-v8a`` +* ``armeabi-v7a`` +* ``armeabi-v6`` +* ``armeabi`` +* ``mips`` +* ``mips64`` +* ``x86`` +* ``x86_64`` + +See also the :variable:`CMAKE_ANDROID_ARM_MODE` and +:variable:`CMAKE_ANDROID_ARM_NEON` variables. diff --git a/Help/variable/CMAKE_ANDROID_ARM_MODE.rst b/Help/variable/CMAKE_ANDROID_ARM_MODE.rst new file mode 100644 index 0000000..ad3c37c --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_ARM_MODE.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_ARM_MODE +---------------------- + +When :ref:`Cross Compiling for Android` and :variable:`CMAKE_ANDROID_ARCH_ABI` +is set to one of the ``armeabi`` architectures, set ``CMAKE_ANDROID_ARM_MODE`` +to ``ON`` to target 32-bit ARM processors (``-marm``). Otherwise, the +default is to target the 16-bit Thumb processors (``-mthumb``). diff --git a/Help/variable/CMAKE_ANDROID_ARM_NEON.rst b/Help/variable/CMAKE_ANDROID_ARM_NEON.rst new file mode 100644 index 0000000..4b7ae03 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_ARM_NEON.rst @@ -0,0 +1,6 @@ +CMAKE_ANDROID_ARM_NEON +---------------------- + +When :ref:`Cross Compiling for Android` and :variable:`CMAKE_ANDROID_ARCH_ABI` +is set to ``armeabi-v7a`` set ``CMAKE_ANDROID_ARM_NEON`` to ``ON`` to target +ARM NEON devices. diff --git a/Help/variable/CMAKE_ANDROID_NDK.rst b/Help/variable/CMAKE_ANDROID_NDK.rst new file mode 100644 index 0000000..d241dd0 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_NDK.rst @@ -0,0 +1,7 @@ +CMAKE_ANDROID_NDK +----------------- + +When :ref:`Cross Compiling for Android with the NDK`, this variable holds +the absolute path to the root directory of the NDK. The directory must +contain a ``platforms`` subdirectory holding the ``android-<api>`` +directories. diff --git a/Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION.rst b/Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION.rst new file mode 100644 index 0000000..dff7d64 --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION.rst @@ -0,0 +1,13 @@ +CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION +----------------------------------- + +When :ref:`Cross Compiling for Android with the NDK`, this variable +may be set to specify the version of the toolchain to be used +as the compiler. The variable must be set to one of these forms: + +* ``<major>.<minor>``: GCC of specified version +* ``clang<major>.<minor>``: Clang of specified version +* ``clang``: Clang of most recent available version + +A toolchain of the requested version will be selected automatically to +match the ABI named in the :variable:`CMAKE_ANDROID_ARCH_ABI` variable. diff --git a/Help/variable/CMAKE_ANDROID_STANDALONE_TOOLCHAIN.rst b/Help/variable/CMAKE_ANDROID_STANDALONE_TOOLCHAIN.rst new file mode 100644 index 0000000..ea62cab --- /dev/null +++ b/Help/variable/CMAKE_ANDROID_STANDALONE_TOOLCHAIN.rst @@ -0,0 +1,6 @@ +CMAKE_ANDROID_STANDALONE_TOOLCHAIN +---------------------------------- + +When :ref:`Cross Compiling for Android with a Standalone Toolchain`, this +variable holds the absolute path to the root directory of the toolchain. +The specified directory must contain a ``sysroot`` subdirectory. diff --git a/Help/variable/CMAKE_ANDROID_STL_TYPE.rst b/Help/variable/CMAKE_ANDROID_STL_TYPE.rst index 766b2c8..cfb76aa 100644 --- a/Help/variable/CMAKE_ANDROID_STL_TYPE.rst +++ b/Help/variable/CMAKE_ANDROID_STL_TYPE.rst @@ -1,5 +1,36 @@ CMAKE_ANDROID_STL_TYPE ---------------------- -Default value for the :prop_tgt:`ANDROID_STL_TYPE` target property. -See that target property for additional information. +When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio +Edition`, this variable may be set to specify the default value for the +:prop_tgt:`ANDROID_STL_TYPE` target property. See that target property +for additional information. + +When :ref:`Cross Compiling for Android with the NDK`, this variable may be +set to specify the STL variant to be used. The value may be one of: + +``none`` + No C++ Support +``system`` + Minimal C++ without STL +``gabi++_static`` + GAbi++ Static +``gabi++_shared`` + GAbi++ Shared +``gnustl_static`` + GNU libstdc++ Static +``gnustl_shared`` + GNU libstdc++ Shared +``c++_static`` + LLVM libc++ Static +``c++_shared`` + LLVM libc++ Shared +``stlport_static`` + STLport Static +``stlport_shared`` + STLport Shared + +The default value is ``gnustl_static``. Note that this default differs from +the native NDK build system because CMake may be used to build projects for +Android that are not natively implemented for it and use the C++ standard +library. diff --git a/Help/variable/CMAKE_BUILD_RPATH.rst b/Help/variable/CMAKE_BUILD_RPATH.rst new file mode 100644 index 0000000..f20eb41 --- /dev/null +++ b/Help/variable/CMAKE_BUILD_RPATH.rst @@ -0,0 +1,10 @@ +CMAKE_BUILD_RPATH +----------------- + +A :ref:`;-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. + +This is used to initialize the :prop_tgt:`BUILD_RPATH` target property +for all targets. diff --git a/Help/variable/CMAKE_CODELITE_USE_TARGETS.rst b/Help/variable/CMAKE_CODELITE_USE_TARGETS.rst new file mode 100644 index 0000000..33cdf6c --- /dev/null +++ b/Help/variable/CMAKE_CODELITE_USE_TARGETS.rst @@ -0,0 +1,8 @@ +CMAKE_CODELITE_USE_TARGETS +-------------------------- + +Change the way the CodeLite generator creates projectfiles. + +If this variable evaluates to ``ON`` at the end of the top-level +``CMakeLists.txt`` file, the generator creates projectfiles based on targets +rather than projects. diff --git a/Help/variable/CMAKE_COMPILER_IS_GNUCC.rst b/Help/variable/CMAKE_COMPILER_IS_GNUCC.rst new file mode 100644 index 0000000..a40667e --- /dev/null +++ b/Help/variable/CMAKE_COMPILER_IS_GNUCC.rst @@ -0,0 +1,5 @@ +CMAKE_COMPILER_IS_GNUCC +----------------------- + +True if the ``C`` compiler is GNU. +Use :variable:`CMAKE_C_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` instead. diff --git a/Help/variable/CMAKE_COMPILER_IS_GNUCXX.rst b/Help/variable/CMAKE_COMPILER_IS_GNUCXX.rst new file mode 100644 index 0000000..f1f5cf7 --- /dev/null +++ b/Help/variable/CMAKE_COMPILER_IS_GNUCXX.rst @@ -0,0 +1,5 @@ +CMAKE_COMPILER_IS_GNUCXX +------------------------ + +True if the C++ (``CXX``) compiler is GNU. +Use :variable:`CMAKE_CXX_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` instead. diff --git a/Help/variable/CMAKE_COMPILER_IS_GNUG77.rst b/Help/variable/CMAKE_COMPILER_IS_GNUG77.rst new file mode 100644 index 0000000..3d6dab4 --- /dev/null +++ b/Help/variable/CMAKE_COMPILER_IS_GNUG77.rst @@ -0,0 +1,5 @@ +CMAKE_COMPILER_IS_GNUG77 +------------------------ + +True if the ``Fortran`` compiler is GNU. +Use :variable:`CMAKE_Fortran_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` instead. diff --git a/Help/variable/CMAKE_COMPILER_IS_GNULANG.rst b/Help/variable/CMAKE_COMPILER_IS_GNULANG.rst deleted file mode 100644 index 4b652c0..0000000 --- a/Help/variable/CMAKE_COMPILER_IS_GNULANG.rst +++ /dev/null @@ -1,15 +0,0 @@ -CMAKE_COMPILER_IS_GNU<LANG> ---------------------------- - -True if the compiler is GNU. - -If the selected ``<LANG>`` compiler is the GNU compiler then this is ``TRUE``, -if not it is ``FALSE``. Unlike the other per-language variables, this -uses the GNU syntax for identifying languages instead of the CMake -syntax. Recognized values of the ``<LANG>`` suffix are: - -:: - - CC = C compiler - CXX = C++ compiler - G77 = Fortran compiler diff --git a/Help/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT.rst b/Help/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT.rst new file mode 100644 index 0000000..592a369 --- /dev/null +++ b/Help/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT.rst @@ -0,0 +1,10 @@ +CMAKE_EXE_LINKER_FLAGS_<CONFIG>_INIT +------------------------------------ + +Value used to initialize the :variable:`CMAKE_EXE_LINKER_FLAGS_<CONFIG>` +cache entry the first time a build tree is configured. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also :variable:`CMAKE_EXE_LINKER_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_EXE_LINKER_FLAGS_INIT.rst b/Help/variable/CMAKE_EXE_LINKER_FLAGS_INIT.rst new file mode 100644 index 0000000..0b8afe4 --- /dev/null +++ b/Help/variable/CMAKE_EXE_LINKER_FLAGS_INIT.rst @@ -0,0 +1,11 @@ +CMAKE_EXE_LINKER_FLAGS_INIT +--------------------------- + +Value used to initialize the :variable:`CMAKE_EXE_LINKER_FLAGS` +cache entry the first time a build tree is configured. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also the configuration-specific variable +:variable:`CMAKE_EXE_LINKER_FLAGS_<CONFIG>_INIT`. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION.rst b/Help/variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION.rst new file mode 100644 index 0000000..99e4ec1 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION.rst @@ -0,0 +1,16 @@ +CMAKE_FIND_PACKAGE_SORT_DIRECTION +--------------------------------- + +The sorting direction used by :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER`. +It can assume one of the following values: + +``DEC`` + Default. Ordering is done in descending mode. + The highest folder found will be tested first. + +``ASC`` + Ordering is done in ascending mode. + The lowest folder found will be tested first. + +If :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` is not set or is set to ``NONE`` +this variable has no effect. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_SORT_ORDER.rst b/Help/variable/CMAKE_FIND_PACKAGE_SORT_ORDER.rst new file mode 100644 index 0000000..ba5f3a8 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_SORT_ORDER.rst @@ -0,0 +1,36 @@ +CMAKE_FIND_PACKAGE_SORT_ORDER +----------------------------- + +The default order for sorting packages found using :command:`find_package`. +It can assume one of the following values: + +``NONE`` + Default. No attempt is done to sort packages. + The first valid package found will be selected. + +``NAME`` + Sort packages lexicographically before selecting one. + +``NATURAL`` + Sort packages using natural order (see ``strverscmp(3)`` manual), + i.e. such that contiguous digits are compared as whole numbers. + +Natural sorting can be employed to return the highest version when multiple +versions of the same library are found by :command:`find_package`. For +example suppose that the following libraries have been found: + +* libX-1.1.0 +* libX-1.2.9 +* libX-1.2.10 + +By setting ``NATURAL`` order we can select the one with the highest +version number ``libX-1.2.10``. + +.. code-block:: cmake + + set(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL) + find_package(libX CONFIG) + +The sort direction can be controlled using the +:variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION` variable +(by default decrescent, e.g. lib-B will be tested before lib-A). diff --git a/Help/variable/CMAKE_INSTALL_PREFIX.rst b/Help/variable/CMAKE_INSTALL_PREFIX.rst index 3f3347f..86f1944 100644 --- a/Help/variable/CMAKE_INSTALL_PREFIX.rst +++ b/Help/variable/CMAKE_INSTALL_PREFIX.rst @@ -5,7 +5,7 @@ Install directory used by :command:`install`. If ``make install`` is invoked or ``INSTALL`` is built, this directory is prepended onto all install directories. This variable defaults to -``/usr/local`` on UNIX and ``c:/Program Files`` on Windows. +``/usr/local`` on UNIX and ``c:/Program Files/${PROJECT_NAME}`` on Windows. On UNIX one can use the ``DESTDIR`` mechanism in order to relocate the whole installation. ``DESTDIR`` means DESTination DIRectory. It is diff --git a/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_PREFIX.rst b/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_PREFIX.rst new file mode 100644 index 0000000..b51422f --- /dev/null +++ b/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_PREFIX.rst @@ -0,0 +1,11 @@ +CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX +------------------------------------- + +When :ref:`Cross Compiling for Android` this variable contains the absolute +path prefixing the toolchain GNU compiler and its binutils. + +See also :variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX`. + +For example, the path to the linker is:: + + ${CMAKE_CXX_ANDROID_TOOLCHAIN_PREFIX}ld${CMAKE_CXX_ANDROID_TOOLCHAIN_SUFFIX} diff --git a/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_SUFFIX.rst b/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_SUFFIX.rst new file mode 100644 index 0000000..a4af640 --- /dev/null +++ b/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_SUFFIX.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX +------------------------------------- + +When :ref:`Cross Compiling for Android` this variable contains the +host platform suffix of the toolchain GNU compiler and its binutils. + +See also :variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX`. diff --git a/Help/variable/CMAKE_LANG_FLAGS_DEBUG_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_DEBUG_INIT.rst new file mode 100644 index 0000000..dcddb2e --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_DEBUG_INIT.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_FLAGS_DEBUG_INIT +----------------------------- + +Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_DEBUG` cache +entry the first time a build tree is configured for language ``<LANG>``. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also :variable:`CMAKE_<LANG>_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_LANG_FLAGS_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_INIT.rst new file mode 100644 index 0000000..1d32cc3 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_INIT.rst @@ -0,0 +1,15 @@ +CMAKE_<LANG>_FLAGS_INIT +----------------------- + +Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS` cache entry +the first time a build tree is configured for language ``<LANG>``. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also the configuration-specific variables: + +* :variable:`CMAKE_<LANG>_FLAGS_DEBUG_INIT` +* :variable:`CMAKE_<LANG>_FLAGS_RELEASE_INIT` +* :variable:`CMAKE_<LANG>_FLAGS_MINSIZEREL_INIT` +* :variable:`CMAKE_<LANG>_FLAGS_RELWITHDEBINFO_INIT` diff --git a/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT.rst new file mode 100644 index 0000000..c0aedf4 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_FLAGS_MINSIZEREL_INIT +---------------------------------- + +Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_MINSIZEREL` +cache entry the first time a build tree is configured for language ``<LANG>``. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also :variable:`CMAKE_<LANG>_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_LANG_FLAGS_RELEASE_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_RELEASE_INIT.rst new file mode 100644 index 0000000..59f92ff --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_RELEASE_INIT.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_FLAGS_RELEASE_INIT +------------------------------- + +Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_RELEASE` +cache entry the first time a build tree is configured for language ``<LANG>``. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also :variable:`CMAKE_<LANG>_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT.rst new file mode 100644 index 0000000..915f023 --- /dev/null +++ b/Help/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_FLAGS_RELWITHDEBINFO_INIT +-------------------------------------- + +Value used to initialize the :variable:`CMAKE_<LANG>_FLAGS_RELWITHDEBINFO` +cache entry the first time a build tree is configured for language ``<LANG>``. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also :variable:`CMAKE_<LANG>_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst b/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst new file mode 100644 index 0000000..90c4d3f --- /dev/null +++ b/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst @@ -0,0 +1,6 @@ +CMAKE_LINK_WHAT_YOU_USE +--------------------------------- + +Default value for :prop_tgt:`LINK_WHAT_YOU_USE` target property. +This variable is used to initialize the property on each target as it is +created. diff --git a/Help/variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT.rst b/Help/variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT.rst new file mode 100644 index 0000000..3279014 --- /dev/null +++ b/Help/variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT.rst @@ -0,0 +1,10 @@ +CMAKE_MODULE_LINKER_FLAGS_<CONFIG>_INIT +--------------------------------------- + +Value used to initialize the :variable:`CMAKE_MODULE_LINKER_FLAGS_<CONFIG>` +cache entry the first time a build tree is configured. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also :variable:`CMAKE_MODULE_LINKER_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_MODULE_LINKER_FLAGS_INIT.rst b/Help/variable/CMAKE_MODULE_LINKER_FLAGS_INIT.rst new file mode 100644 index 0000000..91b39f6 --- /dev/null +++ b/Help/variable/CMAKE_MODULE_LINKER_FLAGS_INIT.rst @@ -0,0 +1,11 @@ +CMAKE_MODULE_LINKER_FLAGS_INIT +------------------------------ + +Value used to initialize the :variable:`CMAKE_MODULE_LINKER_FLAGS` +cache entry the first time a build tree is configured. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also the configuration-specific variable +:variable:`CMAKE_MODULE_LINKER_FLAGS_<CONFIG>_INIT`. diff --git a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst index 582f9e4..36cf75f 100644 --- a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst +++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst @@ -15,6 +15,8 @@ warn by default: policy :policy:`CMP0060`. * ``CMAKE_POLICY_WARNING_CMP0065`` controls the warning for policy :policy:`CMP0065`. +* ``CMAKE_POLICY_WARNING_CMP0066`` controls the warning for + policy :policy:`CMP0066`. 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_SHARED_LINKER_FLAGS_CONFIG_INIT.rst b/Help/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG_INIT.rst new file mode 100644 index 0000000..185df38 --- /dev/null +++ b/Help/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG_INIT.rst @@ -0,0 +1,10 @@ +CMAKE_SHARED_LINKER_FLAGS_<CONFIG>_INIT +--------------------------------------- + +Value used to initialize the :variable:`CMAKE_SHARED_LINKER_FLAGS_<CONFIG>` +cache entry the first time a build tree is configured. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also :variable:`CMAKE_SHARED_LINKER_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_SHARED_LINKER_FLAGS_INIT.rst b/Help/variable/CMAKE_SHARED_LINKER_FLAGS_INIT.rst new file mode 100644 index 0000000..cb819a7 --- /dev/null +++ b/Help/variable/CMAKE_SHARED_LINKER_FLAGS_INIT.rst @@ -0,0 +1,11 @@ +CMAKE_SHARED_LINKER_FLAGS_INIT +------------------------------ + +Value used to initialize the :variable:`CMAKE_SHARED_LINKER_FLAGS` +cache entry the first time a build tree is configured. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also the configuration-specific variable +:variable:`CMAKE_SHARED_LINKER_FLAGS_<CONFIG>_INIT`. diff --git a/Help/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT.rst b/Help/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT.rst new file mode 100644 index 0000000..a49d1cb --- /dev/null +++ b/Help/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT.rst @@ -0,0 +1,10 @@ +CMAKE_STATIC_LINKER_FLAGS_<CONFIG>_INIT +--------------------------------------- + +Value used to initialize the :variable:`CMAKE_STATIC_LINKER_FLAGS_<CONFIG>` +cache entry the first time a build tree is configured. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also :variable:`CMAKE_STATIC_LINKER_FLAGS_INIT`. diff --git a/Help/variable/CMAKE_STATIC_LINKER_FLAGS_INIT.rst b/Help/variable/CMAKE_STATIC_LINKER_FLAGS_INIT.rst new file mode 100644 index 0000000..113ca71 --- /dev/null +++ b/Help/variable/CMAKE_STATIC_LINKER_FLAGS_INIT.rst @@ -0,0 +1,11 @@ +CMAKE_STATIC_LINKER_FLAGS_INIT +------------------------------ + +Value used to initialize the :variable:`CMAKE_STATIC_LINKER_FLAGS` +cache entry the first time a build tree is configured. +This variable is meant to be set by a :variable:`toolchain file +<CMAKE_TOOLCHAIN_FILE>`. CMake may prepend or append content to +the value based on the environment and target platform. + +See also the configuration-specific variable +:variable:`CMAKE_STATIC_LINKER_FLAGS_<CONFIG>_INIT`. diff --git a/Help/variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS.rst b/Help/variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS.rst new file mode 100644 index 0000000..02c8663 --- /dev/null +++ b/Help/variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS.rst @@ -0,0 +1,25 @@ +CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS +--------------------------------- + +This variable contains a list of env vars as a list of tokens with the +syntax ``var=value``. + +Example: + +.. code-block:: cmake + + set(CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS + "FOO=FOO1\;FOO2\;FOON" + "BAR=BAR1\;BAR2\;BARN" + "BAZ=BAZ1\;BAZ2\;BAZN" + "FOOBAR=FOOBAR1\;FOOBAR2\;FOOBARN" + "VALID=" + ) + +In case of malformed variables CMake will fail: + +.. code-block:: cmake + + set(CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS + "THIS_IS_NOT_VALID" + ) diff --git a/Help/variable/CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE.rst b/Help/variable/CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE.rst new file mode 100644 index 0000000..d654425 --- /dev/null +++ b/Help/variable/CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE.rst @@ -0,0 +1,7 @@ +CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE +--------------------------------------- + +If this variable evaluates to ``ON`` at the end of the top-level +``CMakeLists.txt`` file, the :generator:`Sublime Text 2` extra generator +excludes the build tree from the ``.sublime-project`` if it is inside the +source tree. diff --git a/Help/variable/CMAKE_Swift_LANGUAGE_VERSION.rst b/Help/variable/CMAKE_Swift_LANGUAGE_VERSION.rst new file mode 100644 index 0000000..50121e2 --- /dev/null +++ b/Help/variable/CMAKE_Swift_LANGUAGE_VERSION.rst @@ -0,0 +1,5 @@ +CMAKE_Swift_LANGUAGE_VERSION +---------------------------- + +Set to the Swift language version number. If not set, the legacy "2.3" +version is assumed. diff --git a/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE.rst b/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE.rst index 9af0d97..622278e 100644 --- a/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE.rst +++ b/Help/variable/CMAKE_USER_MAKE_RULES_OVERRIDE.rst @@ -14,8 +14,10 @@ variables that must be set before CMake builds its first test project to check that the compiler for a language works. It should not be used to load a file in cases that a normal :command:`include` will work. Use it only as a last resort for behavior that cannot be achieved any -other way. For example, one may set ``CMAKE_C_FLAGS_INIT`` to change the -default value used to initialize :variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>` +other way. For example, one may set the +:variable:`CMAKE_C_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>` variable +to change the default value used to initialize the +:variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>` variable before it is cached. The override file should NOT be used to set anything that could be set after languages are enabled, such as variables like :variable:`CMAKE_RUNTIME_OUTPUT_DIRECTORY` that affect the placement of diff --git a/Help/variable/CMAKE_VERSION.rst b/Help/variable/CMAKE_VERSION.rst index bbb1d91..872e2fa 100644 --- a/Help/variable/CMAKE_VERSION.rst +++ b/Help/variable/CMAKE_VERSION.rst @@ -26,11 +26,11 @@ Individual component values are also available in variables: * :variable:`CMAKE_PATCH_VERSION` * :variable:`CMAKE_TWEAK_VERSION` -Use the :command:`if` command ``VERSION_LESS``, ``VERSION_EQUAL``, or -``VERSION_GREATER`` operators to compare version string values against -``CMAKE_VERSION`` using a component-wise test. Version component -values may be 10 or larger so do not attempt to compare version -strings as floating-point numbers. +Use the :command:`if` command ``VERSION_LESS``, ``VERSION_GREATER``, +``VERSION_EQUAL``, ``VERSION_LESS_EQUAL``, or ``VERSION_GREATER_EQUAL`` +operators to compare version string values against ``CMAKE_VERSION`` using a +component-wise test. Version component values may be 10 or larger so do not +attempt to compare version strings as floating-point numbers. .. note:: diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst new file mode 100644 index 0000000..4c04e97 --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst @@ -0,0 +1,10 @@ +CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE +------------------------------------------- + +Visual Studio preferred tool architecture. + +The :ref:`Visual Studio Generators` for VS 2013 and above support optional +selection of a 64-bit toolchain on 64-bit hosts by specifying a ``host=64`` +value in the :variable:`CMAKE_GENERATOR_TOOLSET` option. CMake provides +the selected toolchain architecture preference in this variable (either +``x64`` or empty). diff --git a/Help/variable/MSVC10.rst b/Help/variable/MSVC10.rst index 33692ad..98e0493 100644 --- a/Help/variable/MSVC10.rst +++ b/Help/variable/MSVC10.rst @@ -1,6 +1,5 @@ MSVC10 ------ -``True`` when using Microsoft Visual C++ 10.0 - -Set to ``true`` when the compiler is version 10.0 of Microsoft Visual C++. +``True`` when using the Microsoft Visual Studio ``v100`` toolset +(``cl`` version 16) or another compiler that simulates it. diff --git a/Help/variable/MSVC11.rst b/Help/variable/MSVC11.rst index 3ab606d..42b7b86 100644 --- a/Help/variable/MSVC11.rst +++ b/Help/variable/MSVC11.rst @@ -1,6 +1,5 @@ MSVC11 ------ -``True`` when using Microsoft Visual C++ 11.0 - -Set to ``true`` when the compiler is version 11.0 of Microsoft Visual C++. +``True`` when using the Microsoft Visual Studio ``v110`` toolset +(``cl`` version 17) or another compiler that simulates it. diff --git a/Help/variable/MSVC12.rst b/Help/variable/MSVC12.rst index 15fa64b..0648f35 100644 --- a/Help/variable/MSVC12.rst +++ b/Help/variable/MSVC12.rst @@ -1,6 +1,5 @@ MSVC12 ------ -``True`` when using Microsoft Visual C++ 12.0. - -Set to ``true`` when the compiler is version 12.0 of Microsoft Visual C++. +``True`` when using the Microsoft Visual Studio ``v120`` toolset +(``cl`` version 18) or another compiler that simulates it. diff --git a/Help/variable/MSVC14.rst b/Help/variable/MSVC14.rst index 0b9125d..f67ebc7 100644 --- a/Help/variable/MSVC14.rst +++ b/Help/variable/MSVC14.rst @@ -1,6 +1,5 @@ MSVC14 ------ -``True`` when using Microsoft Visual C++ 14.0. - -Set to ``true`` when the compiler is version 14.0 of Microsoft Visual C++. +``True`` when using the Microsoft Visual Studio ``v140`` toolset +(``cl`` version 19) or another compiler that simulates it. diff --git a/Help/variable/MSVC80.rst b/Help/variable/MSVC80.rst index b17777c..0d33e82 100644 --- a/Help/variable/MSVC80.rst +++ b/Help/variable/MSVC80.rst @@ -1,6 +1,5 @@ MSVC80 ------ -``True`` when using Microsoft Visual C++ 8.0. - -Set to ``true`` when the compiler is version 8.0 of Microsoft Visual C++. +``True`` when using the Microsoft Visual Studio ``v80`` toolset +(``cl`` version 14) or another compiler that simulates it. diff --git a/Help/variable/MSVC90.rst b/Help/variable/MSVC90.rst index 7162d6c..1716e6f 100644 --- a/Help/variable/MSVC90.rst +++ b/Help/variable/MSVC90.rst @@ -1,6 +1,5 @@ MSVC90 ------ -``True`` when using Microsoft Visual C++ 9.0. - -Set to ``true`` when the compiler is version 9.0 of Microsoft Visual C++. +``True`` when using the Microsoft Visual Studio ``v90`` toolset +(``cl`` version 15) or another compiler that simulates it. diff --git a/Help/variable/MSVC_VERSION.rst b/Help/variable/MSVC_VERSION.rst index ef3b0b5..e2aff3c9 100644 --- a/Help/variable/MSVC_VERSION.rst +++ b/Help/variable/MSVC_VERSION.rst @@ -13,4 +13,4 @@ Known version numbers are:: 1600 = VS 10.0 1700 = VS 11.0 1800 = VS 12.0 - 1900 = VS 14.0 + 1900 = VS 14.0, 15.0 diff --git a/Help/variable/XCODE.rst b/Help/variable/XCODE.rst new file mode 100644 index 0000000..99f20fb --- /dev/null +++ b/Help/variable/XCODE.rst @@ -0,0 +1,4 @@ +XCODE +----- + +``True`` when using :generator:`Xcode` generator. |