diff options
Diffstat (limited to 'Help')
22 files changed, 133 insertions, 19 deletions
diff --git a/Help/command/get_filename_component.rst b/Help/command/get_filename_component.rst index 3e3c9c3..f55499a 100644 --- a/Help/command/get_filename_component.rst +++ b/Help/command/get_filename_component.rst @@ -15,6 +15,8 @@ Sets ``<var>`` to a component of ``<FileName>``, where ``<mode>`` is one of: NAME = File name without directory EXT = File name longest extension (.b.c from d/a.b.c) NAME_WE = File name without directory or longest extension + LAST_EXT = File name last extention (.c from d/a.b.c) + NAME_WLE = File name without directory or last extension PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11) Paths are returned with forward slashes and have no trailing slashes. diff --git a/Help/dev/review.rst b/Help/dev/review.rst index 0c4eded..1d664c4 100644 --- a/Help/dev/review.rst +++ b/Help/dev/review.rst @@ -238,12 +238,10 @@ Referencing Commits in Commit Messages ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The preferred form for references to other commits is -``commit <commit> (<subject>, <date>)``, where: +``commit <shorthash> (<subject>, <date>)``, where: -* ``<commit>``: - If available, a tag-relative name of the commit produced by - ``git describe --contains <commit-ish>``. Otherwise, the first - 8-10 characters of the commit ``<hash>``. +* ``<shorthash>``: + The abbreviated hash of the commit. * ``<subject>``: The first line of the commit message. @@ -252,6 +250,17 @@ The preferred form for references to other commits is The author date of the commit, in its original time zone, formatted as ``CCYY-MM-DD``. ``git-log(1)`` shows the original time zone by default. +This may be generated with +``git show -s --date=short --pretty="format:%h (%s, %ad)" <commit>``. + +If the commit is a fix for the mentioned commit, consider using a ``Fixes:`` +trailer in the commit message with the specified format. This trailer should +not be word-wrapped. Note that if there is also an issue for what is being +fixed, it is preferrable to link to the issue instead. + +If relevant, add the first release tag of CMake containing the commit after +the ``<date>``, i.e., ``commit <shorthash> (<subject>, <date>, <tag>)``. + Alternatively, the full commit ``<hash>`` may be used. Revising Commit Messages diff --git a/Help/generator/VS_TOOLSET_HOST_ARCH.txt b/Help/generator/VS_TOOLSET_HOST_ARCH.txt index 5d13e77..4eb900f 100644 --- a/Help/generator/VS_TOOLSET_HOST_ARCH.txt +++ b/Help/generator/VS_TOOLSET_HOST_ARCH.txt @@ -1,6 +1,7 @@ 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 a ``host=x64`` option to the toolset specification. +(independent of the architecture they target). +|VS_TOOLSET_HOST_ARCH_DEFAULT| +One may explicitly request use of either the 32-bit or 64-bit host tools +by adding either ``host=x86`` or ``host=x64`` to the toolset specification. See the :variable:`CMAKE_GENERATOR_TOOLSET` variable for details. diff --git a/Help/generator/Visual Studio 12 2013.rst b/Help/generator/Visual Studio 12 2013.rst index d342c53..fb8e021 100644 --- a/Help/generator/Visual Studio 12 2013.rst +++ b/Help/generator/Visual Studio 12 2013.rst @@ -42,4 +42,7 @@ 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. +.. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace:: + By default this generator uses the 32-bit variant even on a 64-bit host. + .. 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 106b7c5..7383f7a 100644 --- a/Help/generator/Visual Studio 14 2015.rst +++ b/Help/generator/Visual Studio 14 2015.rst @@ -39,4 +39,7 @@ 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. +.. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace:: + By default this generator uses the 32-bit variant even on a 64-bit host. + .. include:: VS_TOOLSET_HOST_ARCH.txt diff --git a/Help/generator/Visual Studio 15 2017.rst b/Help/generator/Visual Studio 15 2017.rst index 52c1fa0..7e6f0fb 100644 --- a/Help/generator/Visual Studio 15 2017.rst +++ b/Help/generator/Visual Studio 15 2017.rst @@ -56,4 +56,7 @@ The ``v141`` toolset that comes with Visual Studio 15 2017 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. +.. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace:: + By default this generator uses the 32-bit variant even on a 64-bit host. + .. include:: VS_TOOLSET_HOST_ARCH.txt diff --git a/Help/generator/Visual Studio 16 2019.rst b/Help/generator/Visual Studio 16 2019.rst index 6f2bc56..b456554 100644 --- a/Help/generator/Visual Studio 16 2019.rst +++ b/Help/generator/Visual Studio 16 2019.rst @@ -46,4 +46,8 @@ The ``v142`` toolset that comes with Visual Studio 16 2019 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. +.. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace:: + By default this generator uses the 64-bit variant on x64 hosts and + the 32-bit variant otherwise. + .. include:: VS_TOOLSET_HOST_ARCH.txt diff --git a/Help/manual/cmake-gui.1.rst b/Help/manual/cmake-gui.1.rst index 9322e33..856aa2f 100644 --- a/Help/manual/cmake-gui.1.rst +++ b/Help/manual/cmake-gui.1.rst @@ -10,6 +10,7 @@ Synopsis cmake-gui [<options>] cmake-gui [<options>] {<path-to-source> | <path-to-existing-build>} + cmake-gui [<options>] -S <path-to-source> -B <path-to-build> Description =========== @@ -27,6 +28,14 @@ native tool on their platform. Options ======= +``-S <path-to-source>`` + Path to root directory of the CMake project to build. + +``-B <path-to-build>`` + Path to directory which CMake will use as the root of build directory. + + If the directory doesn't already exist CMake will make it. + .. include:: OPTIONS_HELP.txt See Also diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index bd6a58f..de4ce3d 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -190,6 +190,7 @@ Variables that Change Behavior /variable/CMAKE_LIBRARY_PATH /variable/CMAKE_LINK_DIRECTORIES_BEFORE /variable/CMAKE_MFC_FLAG + /variable/CMAKE_MAXIMUM_RECURSION_DEPTH /variable/CMAKE_MODULE_PATH /variable/CMAKE_NOT_USING_CONFIG_FLAGS /variable/CMAKE_POLICY_DEFAULT_CMPNNNN diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 77178b8..f3b81ec 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -381,9 +381,10 @@ Available commands are: ``chdir <dir> <cmd> [<arg>...]`` Change the current working directory and run a command. -``compare_files <file1> <file2>`` +``compare_files [--ignore-eol] <file1> <file2>`` Check if ``<file1>`` is same as ``<file2>``. If files are the same, - then returns 0, if not it returns 1. + then returns 0, if not it returns 1. The ``--ignore-eol`` option + implies line-wise comparison and ignores LF/CRLF differences. ``copy <file>... <destination>`` Copy files to ``<destination>`` (either file or directory). diff --git a/Help/prop_dir/EXCLUDE_FROM_ALL.rst b/Help/prop_dir/EXCLUDE_FROM_ALL.rst index 1aa24e4..9d3192c 100644 --- a/Help/prop_dir/EXCLUDE_FROM_ALL.rst +++ b/Help/prop_dir/EXCLUDE_FROM_ALL.rst @@ -7,3 +7,9 @@ A property on a directory that indicates if its targets are excluded from the default build target. If it is not, then with a Makefile for example typing make will cause the targets to be built. The same concept applies to the default build of other generators. + +Targets inherit the :prop_tgt:`EXCLUDE_FROM_ALL` property from the directory +that they are created in. When a directory is excluded, all of its targets will +have :prop_tgt:`EXCLUDE_FROM_ALL` set to ``TRUE``. After creating such a target +you can change its :prop_tgt:`EXCLUDE_FROM_ALL` property to ``FALSE``. This +will cause the target to be included in the default build target. diff --git a/Help/prop_tgt/EXCLUDE_FROM_ALL.rst b/Help/prop_tgt/EXCLUDE_FROM_ALL.rst index caa5741..e7457e1 100644 --- a/Help/prop_tgt/EXCLUDE_FROM_ALL.rst +++ b/Help/prop_tgt/EXCLUDE_FROM_ALL.rst @@ -8,3 +8,6 @@ the default build target. If it is not, then with a Makefile for example typing make will cause this target to be built. The same concept applies to the default build of other generators. Installing a target with EXCLUDE_FROM_ALL set to true has undefined behavior. + +This property is enabled by default for targets that are created in +directories that have :prop_dir:`EXCLUDE_FROM_ALL` set to ``TRUE``. diff --git a/Help/release/dev/EXCLUDE_FROM_ALL.rst b/Help/release/dev/EXCLUDE_FROM_ALL.rst new file mode 100644 index 0000000..519ac42 --- /dev/null +++ b/Help/release/dev/EXCLUDE_FROM_ALL.rst @@ -0,0 +1,7 @@ +EXCLUDE_FROM_ALL +---------------- + +* A target's :prop_tgt:`EXCLUDE_FROM_ALL` property can now override the + setting of its directory. A target will now be built as part of "all" + if its :prop_tgt:`EXCLUDE_FROM_ALL` property is set to ``OFF``, even if its + containing directory is marked as :prop_dir:`EXCLUDE_FROM_ALL`. diff --git a/Help/release/dev/FindPython-NumPy-component.rst b/Help/release/dev/FindPython-NumPy-component.rst new file mode 100644 index 0000000..5ea6cfb --- /dev/null +++ b/Help/release/dev/FindPython-NumPy-component.rst @@ -0,0 +1,5 @@ +FindPython-NumPy-component +-------------------------- + +* The :module:`FindPython`, :module:`FindPython2`, and :module:`FindPython3` + modules gained support for ``NumPy`` component. diff --git a/Help/release/dev/cmake-gui-s-b.rst b/Help/release/dev/cmake-gui-s-b.rst new file mode 100644 index 0000000..9447eb3 --- /dev/null +++ b/Help/release/dev/cmake-gui-s-b.rst @@ -0,0 +1,5 @@ +cmake-gui-s-b +------------- + +* The :manual:`cmake-gui(1)` dialog gained new ``-S`` and ``-B`` arguments to + explicitly specify source and build directories. diff --git a/Help/release/dev/compare_files-ignore-eol.rst b/Help/release/dev/compare_files-ignore-eol.rst new file mode 100644 index 0000000..bc32921 --- /dev/null +++ b/Help/release/dev/compare_files-ignore-eol.rst @@ -0,0 +1,6 @@ +compare_files-ignore-eol +------------------------ + +* The :manual:`cmake(1)` ``-E compare_files`` command learned a new + ``--ignore-eol`` option to specify that end-of-line differences (e.g. LF vs + CRLF) should be ignored when comparing files. diff --git a/Help/release/dev/get_filename_component_last_ext.rst b/Help/release/dev/get_filename_component_last_ext.rst new file mode 100644 index 0000000..2487dbc --- /dev/null +++ b/Help/release/dev/get_filename_component_last_ext.rst @@ -0,0 +1,6 @@ +get_filename_component_last_ext +------------------------------- + +* The :command:`get_filename_component` command gained new + ``LAST_EXT`` and ``NAME_WLE`` variants to work with the + extension after the last ``.`` in the name. diff --git a/Help/release/dev/max-recursion-depth.rst b/Help/release/dev/max-recursion-depth.rst new file mode 100644 index 0000000..3d9c781 --- /dev/null +++ b/Help/release/dev/max-recursion-depth.rst @@ -0,0 +1,6 @@ +max-recursion-depth +------------------- + +* CMake now imposes a maximum recursion limit to prevent a stack overflow on + scripts that recurse infinitely. The limit can be adjusted at runtime with + :variable:`CMAKE_MAXIMUM_RECURSION_DEPTH`. diff --git a/Help/release/dev/vs2019.rst b/Help/release/dev/vs2019.rst index 1ffdeec..ee9a2f2 100644 --- a/Help/release/dev/vs2019.rst +++ b/Help/release/dev/vs2019.rst @@ -2,7 +2,7 @@ vs2019 ------ * The :generator:`Visual Studio 16 2019` generator was added. This is - experimental and based on "Visual Studio 2019 Preview 1.1" because this + experimental and based on "Visual Studio 2019 Preview 2" because this version of VS has not been released. The VS 2019 generator differs from generators for earlier versions @@ -10,4 +10,5 @@ vs2019 in the generator name. Instead :variable:`CMAKE_GENERATOR_PLATFORM` must be used, e.g. through the ``-A`` command-line option. Furthermore, the default target platform (architecture) is now based on the *host* - platform. + platform. The VS host toolset selection is now based on the host + architecture as well. diff --git a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst index e9bc28b..e77f211 100644 --- a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst +++ b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst @@ -44,8 +44,8 @@ Supported pairs are: and above with the CUDA toolkit VS integration installed. See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_CUDA` variable. -``host=x64`` - Request use of the native ``x64`` toolchain on ``x64`` hosts. +``host=<arch>`` + Specify the host tools architecture as ``x64`` or ``x86``. Supported by VS 2013 and above. See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE` variable. diff --git a/Help/variable/CMAKE_MAXIMUM_RECURSION_DEPTH.rst b/Help/variable/CMAKE_MAXIMUM_RECURSION_DEPTH.rst new file mode 100644 index 0000000..7110b16 --- /dev/null +++ b/Help/variable/CMAKE_MAXIMUM_RECURSION_DEPTH.rst @@ -0,0 +1,33 @@ +CMAKE_MAXIMUM_RECURSION_DEPTH +----------------------------- + +Maximum recursion depth for CMake scripts. It is intended to be set on the +command line with ``-DCMAKE_MAXIMUM_RECURSION_DEPTH=<x>``, or within +``CMakeLists.txt`` by projects that require a large recursion depth. Projects +that set this variable should provide the user with a way to override it. For +example: + +.. code-block:: cmake + + # About to perform deeply recursive actions + if(NOT CMAKE_MAXIMUM_RECURSION_DEPTH) + set(CMAKE_MAXIMUM_RECURSION_DEPTH 2000) + endif() + +If it is not set, or is set to a non-integer value, a sensible default limit is +used. If the recursion limit is reached, the script terminates immediately with +a fatal error. + +Calling any of the following commands increases the recursion depth: + +* :command:`include` +* :command:`find_package` +* :command:`add_subdirectory` +* :command:`try_compile` +* :command:`ctest_read_custom_files` +* :command:`ctest_run_script` (unless ``NEW_PROCESS`` is specified) +* User-defined :command:`function`'s and :command:`macro`'s (note that + :command:`function` and :command:`macro` themselves don't increase recursion + depth) +* Reading or writing variables that are being watched by a + :command:`variable_watch` diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst index 9b59c52..99ac90d 100644 --- a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst @@ -3,8 +3,8 @@ 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=x64`` -value in the :variable:`CMAKE_GENERATOR_TOOLSET` option. CMake provides -the selected toolchain architecture preference in this variable (either -``x64`` or empty). +The :ref:`Visual Studio Generators` for VS 2013 and above support using +either the 32-bit or 64-bit host toolchains by specifying a ``host=x86`` +or ``host=x64`` value in the :variable:`CMAKE_GENERATOR_TOOLSET` option. +CMake provides the selected toolchain architecture preference in this +variable (``x86``, ``x64``, or empty). |