diff options
Diffstat (limited to 'Help')
28 files changed, 304 insertions, 13 deletions
diff --git a/Help/command/cmake_host_system_information.rst b/Help/command/cmake_host_system_information.rst index 9402d57..7199874 100644 --- a/Help/command/cmake_host_system_information.rst +++ b/Help/command/cmake_host_system_information.rst @@ -13,13 +13,34 @@ queried. The list of queried values is stored in ``<variable>``. ``<key>`` can be one of the following values: -:: - - NUMBER_OF_LOGICAL_CORES = Number of logical cores. - NUMBER_OF_PHYSICAL_CORES = Number of physical cores. - HOSTNAME = Hostname. - FQDN = Fully qualified domain name. - TOTAL_VIRTUAL_MEMORY = Total virtual memory in megabytes. - AVAILABLE_VIRTUAL_MEMORY = Available virtual memory in megabytes. - TOTAL_PHYSICAL_MEMORY = Total physical memory in megabytes. - AVAILABLE_PHYSICAL_MEMORY = Available physical memory in megabytes. +============================= ================================================ +Key Description +============================= ================================================ +``NUMBER_OF_LOGICAL_CORES`` Number of logical cores +``NUMBER_OF_PHYSICAL_CORES`` Number of physical cores +``HOSTNAME`` Hostname +``FQDN`` Fully qualified domain name +``TOTAL_VIRTUAL_MEMORY`` Total virtual memory in megabytes +``AVAILABLE_VIRTUAL_MEMORY`` Available virtual memory in megabytes +``TOTAL_PHYSICAL_MEMORY`` Total physical memory in megabytes +``AVAILABLE_PHYSICAL_MEMORY`` Available physical memory in megabytes +``IS_64BIT`` One if processor is 64Bit +``HAS_FPU`` One if processor has floating point unit +``HAS_MMX`` One if processor supports MMX instructions +``HAS_MMX_PLUS`` One if porcessor supports Ext. MMX instructions +``HAS_SSE`` One if porcessor supports SSE instructions +``HAS_SSE2`` One if porcessor supports SSE2 instructions +``HAS_SSE_FP`` One if porcessor supports SSE FP instructions +``HAS_SSE_MMX`` One if porcessor supports SSE MMX instructions +``HAS_AMD_3DNOW`` One if porcessor supports 3DNow instructions +``HAS_AMD_3DNOW_PLUS`` One if porcessor supports 3DNow+ instructions +``HAS_IA64`` One if IA64 processor emulating x86 +``HAS_SERIAL_NUMBER`` One if processor has serial number +``PROCESSOR_SERIAL_NUMBER`` Processor serial number +``PROCESSOR_NAME`` Human readable processor name +``PROCESSOR_DESCRIPTION`` Human readable full processor description +``OS_NAME`` See :variable:`CMAKE_HOST_SYSTEM_NAME` +``OS_RELEASE`` The OS sub-type e.g. on Windows ``Professional`` +``OS_VERSION`` The OS build ID +``OS_PLATFORM`` See :variable:`CMAKE_HOST_SYSTEM_PROCESSOR` +============================= ================================================ diff --git a/Help/command/execute_process.rst b/Help/command/execute_process.rst index d617243..799493f 100644 --- a/Help/command/execute_process.rst +++ b/Help/command/execute_process.rst @@ -10,6 +10,7 @@ Execute one or more child processes. [WORKING_DIRECTORY <directory>] [TIMEOUT <seconds>] [RESULT_VARIABLE <variable>] + [RESULTS_VARIABLE <variable>] [OUTPUT_VARIABLE <variable>] [ERROR_VARIABLE <variable>] [INPUT_FILE <file>] @@ -49,10 +50,16 @@ Options: specified number of seconds (fractions are allowed). ``RESULT_VARIABLE`` - The variable will be set to contain the result of running the processes. + The variable will be set to contain the result of last child process. This will be an integer return code from the last child or a string describing an error condition. +``RESULTS_VARIABLE <variable>`` + The variable will be set to contain the result of all processes as a + :ref:`;-list <CMake Language Lists>`, in order of the given ``COMMAND`` + arguments. Each entry will be an integer return code from the + corresponding child or a string describing an error condition. + ``OUTPUT_VARIABLE``, ``ERROR_VARIABLE`` The variable named will be set with the contents of the standard output and standard error pipes, respectively. If the same variable is named diff --git a/Help/command/file.rst b/Help/command/file.rst index b2e4eea..7afb715 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -291,6 +291,8 @@ from the input content to produce the output content. The options are: ``INPUT <input-file>`` Use the content from a given file as input. + A relative path is treated with respect to the value of + :variable:`CMAKE_CURRENT_SOURCE_DIR`. See policy :policy:`CMP0070`. ``OUTPUT <output-file>`` Specify the output file name to generate. Use generator expressions @@ -298,6 +300,9 @@ from the input content to produce the output content. The options are: name. Multiple configurations may generate the same output file only if the generated content is identical. Otherwise, the ``<output-file>`` must evaluate to an unique name for each configuration. + A relative path (after evaluating generator expressions) is treated + with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. + See policy :policy:`CMP0070`. Exactly one ``CONTENT`` or ``INPUT`` option must be given. A specific ``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``. diff --git a/Help/command/include_guard.rst b/Help/command/include_guard.rst new file mode 100644 index 0000000..62cce22 --- /dev/null +++ b/Help/command/include_guard.rst @@ -0,0 +1,46 @@ +include_guard +------------- + +Provides an include guard for the file currently being processed by CMake. + +:: + + include_guard([DIRECTORY|GLOBAL]) + +Sets up an include guard for the current CMake file (see the +:variable:`CMAKE_CURRENT_LIST_FILE` variable documentation). + +CMake will end its processing of the current file at the location of the +:command:`include_guard` command if the current file has already been +processed for the applicable scope (see below). This provides functionality +similar to the include guards commonly used in source headers or to the +``#pragma once`` directive. If the current file has been processed previously +for the applicable scope, the effect is as though :command:`return` had been +called. Do not call this command from inside a function being defined within +the current file. + +An optional argument specifying the scope of the guard may be provided. +Possible values for the option are: + +``DIRECTORY`` + The include guard applies within the current directory and below. The file + will only be included once within this directory scope, but may be included + again by other files outside of this directory (i.e. a parent directory or + another directory not pulled in by :command:`add_subdirectory` or + :command:`include` from the current file or its children). + +``GLOBAL`` + The include guard applies globally to the whole build. The current file + will only be included once regardless of the scope. + +If no arguments given, ``include_guard`` has the same scope as a variable, +meaning that the include guard effect is isolated by the most recent +function scope or current directory if no inner function scopes exist. +In this case the command behavior is the same as: + +.. code-block:: cmake + + if(__CURRENT_FILE_VAR__) + return() + endif() + set(__CURRENT_FILE_VAR__ TRUE) diff --git a/Help/dev/maint.rst b/Help/dev/maint.rst index 78c06df..889e4e3 100644 --- a/Help/dev/maint.rst +++ b/Help/dev/maint.rst @@ -8,6 +8,38 @@ See documentation on `CMake Development`_ for more information. .. contents:: Maintainer Processes: +Review a Merge Request +====================== + +The `CMake Review Process`_ requires a maintainer to issue the ``Do: merge`` +command to integrate a merge request. Please check at least the following: + +* If the MR source branch is not named well for the change it makes + (e.g. it is just ``master`` or the patch changed during review), + add a ``Topic-rename: <topic>`` trailing line to the MR description + to provide a better topic name. + +* If the MR introduces a new feature or a user-facing behavior change, + such as a policy, ensure that a ``Help/release/dev/$topic.rst`` file + is added with a release note. + +* If a commit changes a specific area, such as a module, its commit + message should have an ``area:`` prefix on its first line. + +* If a commit fixes a tracked issue, its commit message should have + a trailing line such as ``Fixes: #00000``. + +* Ensure that the MR adds sufficient documentation and test cases. + +* Ensure that the MR has been tested sufficiently. Typically it should + be staged for nightly testing with ``Do: stage``. Then manually + review the `CMake CDash Page`_ to verify that no regressions were + introduced. (Learn to tolerate spurious failures due to idiosyncrasies + of various nightly builders.) + +.. _`CMake Review Process`: review.rst +.. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake + Branch a New Release ==================== diff --git a/Help/dev/source.rst b/Help/dev/source.rst index 7e44995..16a9252 100644 --- a/Help/dev/source.rst +++ b/Help/dev/source.rst @@ -58,3 +58,50 @@ need to be handled with care: When assigning the result of ``.size()`` on a container for example, the result should be assigned to ``size_t`` not to ``std::size_t``, ``unsigned int`` or similar types. + +Source Tree Layout +================== + +The CMake source tree is organized as follows. + +* ``Auxiliary/``: + Shell and editor integration files. + +* ``Help/``: + Documentation. + + * ``Help/dev/``: + Developer documentation. + + * ``Help/release/dev/``: + Release note snippets for development since last release. + +* ``Licenses/``: + License files for third-party libraries in binary distributions. + +* ``Modules/``: + CMake language modules installed with CMake. + +* ``Packaging/``: + Files used for packaging CMake itself for distribution. + +* ``Source/``: + Source code of CMake itself. + +* ``Templates/``: + Files distributed with CMake as implementation details for generators, + packagers, etc. + +* ``Tests/``: + The test suite. See `Tests/README.rst`_. + +* ``Utilities/``: + Scripts, third-party source code. + + * ``Utilities/Sphinx/``: + Sphinx configuration to build CMake user documentation. + + * ``Utilities/Release/``: + Scripts used to package CMake itself for distribution on ``cmake.org``. + +.. _`Tests/README.rst`: ../../Tests/README.rst diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst index 611c989..f8bfb32 100644 --- a/Help/manual/cmake-commands.7.rst +++ b/Help/manual/cmake-commands.7.rst @@ -44,6 +44,7 @@ These commands are always available. /command/get_property /command/if /command/include + /command/include_guard /command/list /command/macro /command/mark_as_advanced diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 4a03b7a..fa6144c 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -60,6 +60,7 @@ All Modules /module/CPackCygwin /module/CPackDeb /module/CPackDMG + /module/CPackFreeBSD /module/CPackIFW /module/CPackIFWConfigureFile /module/CPackNSIS diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 7b85817..eb9af27 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.10 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0070: Define file(GENERATE) behavior for relative paths. </policy/CMP0070> + Policies Introduced by CMake 3.9 ================================ diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index ec25596..94ab70c 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -291,6 +291,7 @@ Properties on Targets /prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY /prop_tgt/VS_DESKTOP_EXTENSIONS_VERSION /prop_tgt/VS_DOTNET_REFERENCE_refname + /prop_tgt/VS_DOTNET_REFERENCEPROP_refname_TAG_tagname /prop_tgt/VS_DOTNET_REFERENCES /prop_tgt/VS_DOTNET_REFERENCES_COPY_LOCAL /prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION diff --git a/Help/manual/cmake-server.7.rst b/Help/manual/cmake-server.7.rst index 9520cc1..6a68a1c 100644 --- a/Help/manual/cmake-server.7.rst +++ b/Help/manual/cmake-server.7.rst @@ -254,6 +254,11 @@ versions supported by the cmake server. These are JSON objects with "major" and 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. +Within a "major" version all "minor" versions are fully backwards compatible. +New "minor" versions may introduce functionality in such a way that existing +clients of the same "major" version will continue to work, provided they +ignore keys in the output that they do not know about. + Example:: [== "CMake Server" ==[ @@ -268,6 +273,9 @@ 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. +Giving the "major" version of the requested protocol version will make the server +use the latest minor version of that protocol. Use this if you do not explicitly +need to depend on a specific minor version. Each protocol version may request additional attributes to be present. diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 1a2726d..ec8fedf 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -319,6 +319,7 @@ Variables that Control the Build /variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG /variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT /variable/CMAKE_MODULE_LINKER_FLAGS_INIT + /variable/CMAKE_MSVCIDE_RUN_PATH /variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX /variable/CMAKE_NO_BUILTIN_CHRPATH /variable/CMAKE_NO_SYSTEM_FROM_IMPORTED diff --git a/Help/module/CPackFreeBSD.rst b/Help/module/CPackFreeBSD.rst new file mode 100644 index 0000000..083f0cb --- /dev/null +++ b/Help/module/CPackFreeBSD.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CPackFreeBSD.cmake diff --git a/Help/policy/CMP0070.rst b/Help/policy/CMP0070.rst new file mode 100644 index 0000000..0fb3617 --- /dev/null +++ b/Help/policy/CMP0070.rst @@ -0,0 +1,25 @@ +CMP0070 +------- + +Define :command:`file(GENERATE)` behavior for relative paths. + +CMake 3.10 and newer define that relative paths given to ``INPUT`` and +``OUTPUT`` arguments of ``file(GENERATE)`` are interpreted relative to the +current source and binary directories, respectively. CMake 3.9 and lower did +not define any behavior for relative paths but did not diagnose them either +and accidentally treated them relative to the process working directory. +Policy ``CMP0070`` provides compatibility with projects that used the old +undefined behavior. + +This policy affects behavior of relative paths given to ``file(GENERATE)``. +The ``OLD`` behavior for this policy is to treat the paths relative to the +working directory of CMake. The ``NEW`` behavior for this policy is to +interpret relative paths with respect to the current source or binary +directory of the caller. + +This policy was introduced in CMake version 3.10. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst b/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst index 0fe0b31..28925fc 100644 --- a/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst +++ b/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst @@ -1,7 +1,8 @@ <LANG>_COMPILER_LAUNCHER ------------------------ -This property is implemented only when ``<LANG>`` is ``C`` or ``CXX``. +This property is implemented only when ``<LANG>`` is ``C``, ``CXX``, +or ``CUDA``. Specify a :ref:`;-list <CMake Language Lists>` containing a command line for a compiler launching tool. The :ref:`Makefile Generators` and the diff --git a/Help/prop_tgt/VS_DOTNET_REFERENCEPROP_refname_TAG_tagname.rst b/Help/prop_tgt/VS_DOTNET_REFERENCEPROP_refname_TAG_tagname.rst new file mode 100644 index 0000000..ab311ea --- /dev/null +++ b/Help/prop_tgt/VS_DOTNET_REFERENCEPROP_refname_TAG_tagname.rst @@ -0,0 +1,14 @@ +VS_DOTNET_REFERENCEPROP_<refname>_TAG_<tagname> +----------------------------------------------- + +Defines an XML property ``<tagname>`` for a .NET reference +``<refname>``. + +Reference properties can be set for .NET references which are +defined by the target properties :prop_tgt:`VS_DOTNET_REFERENCES`, +:prop_tgt:`VS_DOTNET_REFERENCE_<refname>` +and also for project references to other C# targets which are +established by :command:`target_link_libraries()`. + +This property is only applicable to C# targets and Visual Studio +generators 2010 and later. 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/VS_DOTNET_REFERENCEPROP_refname_TAG_tagname.rst b/Help/release/dev/VS_DOTNET_REFERENCEPROP_refname_TAG_tagname.rst new file mode 100644 index 0000000..0e258fd --- /dev/null +++ b/Help/release/dev/VS_DOTNET_REFERENCEPROP_refname_TAG_tagname.rst @@ -0,0 +1,6 @@ +vs-dotnet-custom-reference-tags +------------------------------- + +* The :prop_tgt:`VS_DOTNET_REFERENCEPROP_<refname>_TAG_<tagname>` + target property was added to support custom XML tags for reference + assemblies in C# targets. diff --git a/Help/release/dev/cmake_host_system_information-extend.rst b/Help/release/dev/cmake_host_system_information-extend.rst new file mode 100644 index 0000000..d1c882d --- /dev/null +++ b/Help/release/dev/cmake_host_system_information-extend.rst @@ -0,0 +1,6 @@ +cmake_host_system_information-extend +------------------------------------ + +* The :command:`cmake_host_system_information` command learned more keys + to get information about the processor capabilities and the host OS + version. diff --git a/Help/release/dev/cpack-freebsd-pkg.rst b/Help/release/dev/cpack-freebsd-pkg.rst new file mode 100644 index 0000000..1732581 --- /dev/null +++ b/Help/release/dev/cpack-freebsd-pkg.rst @@ -0,0 +1,5 @@ +cpack-freebsd-pkg +----------------- + +* CPack gained a ``FREEBSD`` generator for FreeBSD ``pkg(8)``, configured + by the :module:`CPackFreeBSD` module. diff --git a/Help/release/dev/cuda-compiler-launcher.rst b/Help/release/dev/cuda-compiler-launcher.rst new file mode 100644 index 0000000..f217780 --- /dev/null +++ b/Help/release/dev/cuda-compiler-launcher.rst @@ -0,0 +1,8 @@ +cuda-compiler-launcher +---------------------- + +* The :ref:`Makefile Generators` and the :generator:`Ninja` generator learned + to add compiler launcher tools like ccache along with the compiler for the + ``CUDA`` language (``C`` and ``CXX`` were supported previously). See the + :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable and + :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property for details. diff --git a/Help/release/dev/deb-on-windows.rst b/Help/release/dev/deb-on-windows.rst new file mode 100644 index 0000000..b307720 --- /dev/null +++ b/Help/release/dev/deb-on-windows.rst @@ -0,0 +1,7 @@ +deb-on-windows +-------------- + +* The CPack ``DEB`` generator, configured by the :module:`CPackDeb` module, + was enabled on Windows. While not fully featured (due to the lack of + external UNIX tools) this will allow building basic cross-platform Debian + packages. diff --git a/Help/release/dev/execute_process-pipeline-results.rst b/Help/release/dev/execute_process-pipeline-results.rst new file mode 100644 index 0000000..9755ef5 --- /dev/null +++ b/Help/release/dev/execute_process-pipeline-results.rst @@ -0,0 +1,6 @@ +execute_process-pipeline-results +-------------------------------- + +* The :command:`execute_process` command gained a ``RESULTS_VARIABLE`` + option to collect a list of results from all children in a pipeline + of processes when multiple ``COMMAND`` arguments are given. diff --git a/Help/release/dev/file-generate-relative-paths.rst b/Help/release/dev/file-generate-relative-paths.rst new file mode 100644 index 0000000..fdeb9e0e --- /dev/null +++ b/Help/release/dev/file-generate-relative-paths.rst @@ -0,0 +1,7 @@ +file-generate-relative-paths +---------------------------- + +* The :command:`file(GENERATE)` command now interprets relative paths + given to its ``OUTPUT`` and ``INPUT`` arguments with respect to the + caller's current binary and source directories, respectively. + See policy :policy:`CMP0070`. diff --git a/Help/release/dev/include-guard.rst b/Help/release/dev/include-guard.rst new file mode 100644 index 0000000..9b0c64c --- /dev/null +++ b/Help/release/dev/include-guard.rst @@ -0,0 +1,8 @@ +include_guard +------------- + +* The :command:`include_guard` command was introduced to allow guarding + CMake scripts from being included more than once. The command supports + ``DIRECTORY`` and ``GLOBAL`` options to adjust the corresponding include guard + scope. If no options given, include guard is similar to basic variable-based + check. diff --git a/Help/release/index.rst b/Help/release/index.rst index 8222d0c..7f481a3 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -5,6 +5,8 @@ CMake Release Notes This file should include the adjacent "dev.txt" file in development versions but not in release versions. +.. include:: dev.txt + Releases ======== diff --git a/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst b/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst index 7961f60..f4e2ba5 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst @@ -3,4 +3,4 @@ CMAKE_<LANG>_COMPILER_LAUNCHER Default value for :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property. This variable is used to initialize the property on each target as it is -created. This is done only when ``<LANG>`` is ``C`` or ``CXX``. +created. This is done only when ``<LANG>`` is ``C``, ``CXX``, or ``CUDA``. diff --git a/Help/variable/CMAKE_MSVCIDE_RUN_PATH.rst b/Help/variable/CMAKE_MSVCIDE_RUN_PATH.rst new file mode 100644 index 0000000..22e727f --- /dev/null +++ b/Help/variable/CMAKE_MSVCIDE_RUN_PATH.rst @@ -0,0 +1,10 @@ +CMAKE_MSVCIDE_RUN_PATH +---------------------- + +Extra PATH locations that should be used when executing +:command:`add_custom_command` or :command:`add_custom_target` when using the +:generator:`Visual Studio 9 2008` (or above) generator. This allows +for running commands and using dll's that the IDE environment is not aware of. + +If not set explicitly the value is initialized by the ``CMAKE_MSVCIDE_RUN_PATH`` +environment variable, if set, and otherwise left empty. |