diff options
Diffstat (limited to 'Help')
26 files changed, 213 insertions, 30 deletions
diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index b42fe42..7274e44 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -94,6 +94,12 @@ The most important properties are: See documentation of the ``IMPORTED_*`` and ``INTERFACE_*`` properties for more information. +An ``UNKNOWN`` library type is typically only used in the implementation of +:ref:`Find Modules`. It allows the path to an imported library (often found +using the :command:`find_library` command) to be used without having to know +what type of library it is. This is especially useful on Windows where a +static library and a DLL's import library both have the same file extension. + Object Libraries ^^^^^^^^^^^^^^^^ diff --git a/Help/command/install.rst b/Help/command/install.rst index 7571aae..ab6fef6 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -660,9 +660,9 @@ 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) + install(EXPORT_ANDROID_MK myproj DESTINATION share/ndk-modules) -will install the executable myexe to ``<prefix>/bin`` and code to import +will install the executable ``myexe`` to ``<prefix>/bin`` and code to import it in the file ``<prefix>/lib/myproj/myproj.cmake`` and ``<prefix>/share/ndk-modules/Android.mk``. An outside project may load this file with the include command and reference the ``myexe`` diff --git a/Help/dev/maint.rst b/Help/dev/maint.rst index a8942cd..1153a09 100644 --- a/Help/dev/maint.rst +++ b/Help/dev/maint.rst @@ -188,12 +188,6 @@ Update ``Source/CMakeVersion.cmake`` to set the version to set(CMake_VERSION_PATCH 0) set(CMake_VERSION_RC 1) -Update ``Utilities/Release/upload_release.cmake``: - -.. code-block:: cmake - - set(VERSION $ver) - Update uses of ``DEVEL_CMAKE_VERSION`` in the source tree to mention the actual version number: diff --git a/Help/dev/review.rst b/Help/dev/review.rst index 1d664c4..cbde6fe 100644 --- a/Help/dev/review.rst +++ b/Help/dev/review.rst @@ -377,7 +377,15 @@ command is needed to stage it again. Resolve ======= -A MR may be resolved in one of the following ways. +The workflow used by the CMake project supports a number of different +ways in which a MR can be moved to a resolved state. In addition to +the conventional practices of merging or closing a MR without merging it, +a MR can also be moved to a quasi-resolved state pending some action. +This may involve moving discussion to an issue or it may be the result of +an extended period of inactivity. These quasi-resolved states are used +to help manage the relatively large number of MRs the project receives +and are not an indication of the changes being rejected. The following +sections explain the different resolutions a MR may be given. Merge ----- @@ -433,15 +441,68 @@ Close ----- If review has concluded that the MR should not be integrated then it -may be closed through GitLab. +may be closed through GitLab. This would normally be a final state +with no expectation that the MR would be re-opened in the future. +It is also used when a MR is being superseded by another separate one, +in which case a reference to the new MR should be added to the MR being +closed. Expire ------ If progress on a MR has stalled for a while, it may be closed with a ``workflow:expired`` label and a comment indicating that the MR has -been closed due to inactivity. - -Contributors are welcome to re-open an expired MR when they are ready -to continue work. Please re-open *before* pushing an update to the -MR topic branch to ensure GitLab will still act on the association. +been closed due to inactivity (it may also be done where the MR is blocked +for an extended period by work in a different MR). This is not an +indication that there is a problem with the MR's content, it is only a +practical measure to allow the reviewers to focus attention on MRs that +are actively being worked on. As a guide, the average period of inactivity +before transitioning a MR to the expired state would be around 2 weeks, +but this may decrease to 1 week or less when there is a high number of +open merge requests. + +Reviewers would usually provide a message similar to the following when +resolving a MR as expired:: + + Closing for now. @<MR-author> please re-open when ready to continue work. + +This is to make it clear to contributors that they are welcome to re-open +the expired MR when they are ready to return to working on it and moving +it forward. In the meantime, the MR will appear as ``Closed`` in GitLab, +but it can be differentiated from permanently closed MRs by the presence +of the ``workflow:expired`` label. + +**NOTE:** Please re-open *before* pushing an update to the MR topic branch +to ensure GitLab will still act on the association. If changes are pushed +before re-opening the MR, the reviewer should initiate a ``Do: check`` to +force GitLab to act on the updates. + +External Discussion +------------------- + +In some situations, a series of comments on a MR may develop into a more +involved discussion, or it may become apparent that there are broader +discussions that need to take place before the MR can move forward in an +agreed direction. Such discussions are better suited to GitLab issues +rather than in a MR because MRs may be superseded by a different MR, or +the set of changes may evolve to look quite different to the context in +which the discussions began. When this occurs, reviewers may ask the +MR author to open an issue to discuss things there and they will transition +the MR to a resolved state with the label ``workflow:external-discussion``. +The MR will appear in GitLab as closed, but it can be differentiated from +permanently closed MRs by the presence of the ``workflow:external-discussion`` +label. Reviewers should leave a message clearly explaining the action +so that the MR author understands that the MR closure is temporary and +it is clear what actions need to happen next. The following is an example +of such a message, but it will usually be necessary to tailor the message +to the individual situation:: + + The desired behavior here looks to be more involved than first thought. + Please open an issue so we can discuss the relevant details there. + Once the path forward is clear, we can re-open this MR and continue work. + +When the discussion in the associated issue runs its course and the way +forward is clear, the MR can be re-opened again and the +``workflow:external-discussion`` label removed. Reviewers should ensure +that the issue created contains a reference to the MR so that GitLab +provides a cross-reference to link the two. diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 8d35b86..1d023cb 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -57,6 +57,7 @@ Policies Introduced by CMake 3.15 .. toctree:: :maxdepth: 1 + CMP0094: FindPython3, FindPython2 and FindPython use LOCATION for lookup strategy. </policy/CMP0094> CMP0093: FindBoost reports Boost_VERSION in x.y.z format. </policy/CMP0093> CMP0092: MSVC warning flags are not in CMAKE_{C,CXX}_FLAGS by default. </policy/CMP0092> CMP0091: MSVC runtime library flags are selected by an abstraction. </policy/CMP0091> diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 9d2ad90..25aab8d 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -342,6 +342,7 @@ Properties on Targets /prop_tgt/VS_KEYWORD /prop_tgt/VS_MOBILE_EXTENSIONS_VERSION /prop_tgt/VS_NO_SOLUTION_DEPLOY + /prop_tgt/VS_PACKAGE_REFERENCES /prop_tgt/VS_PROJECT_IMPORT /prop_tgt/VS_SCC_AUXPATH /prop_tgt/VS_SCC_LOCALPATH diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 1011ed2..75ddd5d 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -351,6 +351,7 @@ Variables that Control the Build /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT /variable/CMAKE_EXE_LINKER_FLAGS_INIT /variable/CMAKE_FOLDER + /variable/CMAKE_FRAMEWORK /variable/CMAKE_Fortran_FORMAT /variable/CMAKE_Fortran_MODULE_DIRECTORY /variable/CMAKE_GHS_NO_SOURCE_GROUP_FILE diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index df0d4c5..107c2cb 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -528,16 +528,22 @@ Available commands are: ``sleep <number>...`` Sleep for given number of seconds. -``tar [cxt][vf][zjJ] file.tar [<options>] [--] [<file>...]`` +``tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...]`` Create or extract a tar or zip archive. Options are: ``c`` Create a new archive containing the specified files. - If used, the <file> argument is mandatory. + If used, the ``<pathname>...`` argument is mandatory. ``x`` Extract to disk from the archive. + The ``<pathname>...`` argument could be used to extract only selected files + or directories. + When extracting selected files or directories, you must provide their exact + names including the path, as printed by list (``-t``). ``t`` - List archive contents to stdout. + List archive contents. + The ``<pathname>...`` argument could be used to list only selected files + or directories. ``v`` Produce verbose output. ``z`` @@ -546,20 +552,23 @@ Available commands are: Compress the resulting archive with bzip2. ``J`` Compress the resulting archive with XZ. - ``--`` - Stop interpreting options and treat all remaining arguments - as file names even if they start in ``-``. + ``--zstd`` + Compress the resulting archive with Zstandard. ``--files-from=<file>`` Read file names from the given file, one per line. Blank lines are ignored. Lines may not start in ``-`` except for ``--add-file=<name>`` to add files whose names start in ``-``. - ``--mtime=<date>`` - Specify modification time recorded in tarball entries. ``--format=<format>`` Specify the format of the archive to be created. Supported formats are: ``7zip``, ``gnutar``, ``pax``, ``paxr`` (restricted pax, default), and ``zip``. + ``--mtime=<date>`` + Specify modification time recorded in tarball entries. + ``--`` + Stop interpreting options and treat all remaining arguments + as file names, even if they start with ``-``. + ``time <command> [<args>...]`` Run command and display elapsed time. diff --git a/Help/policy/CMP0094.rst b/Help/policy/CMP0094.rst new file mode 100644 index 0000000..836f30f --- /dev/null +++ b/Help/policy/CMP0094.rst @@ -0,0 +1,22 @@ +CMP0094 +------- + +Modules :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython` +use ``LOCATION`` for lookup strategy. + +Starting with CMake 3.15, Modules :module:`FindPython3`, :module:`FindPython2` +and :module:`FindPython` set value ``LOCATION`` for, respectively, variables +``Python3_FIND_STRATEGY``, ``Python2_FIND_STRATEGY`` and +``Python_FIND_STRATEGY``. This policy provides compatibility with projects that +expect the legacy behavior. + +The ``OLD`` behavior for this policy set value ``VERSION`` for variables +``Python3_FIND_STRATEGY``, ``Python2_FIND_STRATEGY`` and +``Python_FIND_STRATEGY``. + +This policy was introduced in CMake version 3.15. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike many policies, CMake version |release| does *not* warn +when this policy is not set and simply uses the ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/prop_test/COST.rst b/Help/prop_test/COST.rst index 0c0fca7..9300d7b 100644 --- a/Help/prop_test/COST.rst +++ b/Help/prop_test/COST.rst @@ -1,8 +1,14 @@ COST ---- -Set this to a floating point value. Tests in a test set will be run -in descending order of cost. +This property describes the cost of a test. When parallel testing is +enabled, tests in the test set will be run in descending order of cost. +Projects can explicitly define the cost of a test by setting this property +to a floating point value. -This property describes the cost of a test. You can explicitly set -this value; tests with higher ``COST`` values will run first. +When the cost of a test is not defined by the project, +:manual:`ctest <ctest(1)>` will initially use a default cost of ``0``. +It computes a weighted average of the cost each time a test is run and +uses that as an improved estimate of the cost for the next run. The more +a test is re-run in the same build directory, the more representative the +cost should become. diff --git a/Help/prop_tgt/VS_PACKAGE_REFERENCES.rst b/Help/prop_tgt/VS_PACKAGE_REFERENCES.rst new file mode 100644 index 0000000..5a0465b --- /dev/null +++ b/Help/prop_tgt/VS_PACKAGE_REFERENCES.rst @@ -0,0 +1,13 @@ +VS_PACKAGE_REFERENCES +--------------------- + +Visual Studio package references for nuget. + +Adds one or more semicolon-delimited package references to a generated +Visual Studio project. The version of the package will be +underscore delimited. For example, ``boost_1.7.0;nunit_3.12.*``. + +.. code-block:: cmake + + set_property(TARGET ${TARGET_NAME} PROPERTY + VS_PACKAGE_REFERENCES "boost_1.7.0") diff --git a/Help/release/3.14.rst b/Help/release/3.14.rst index 8a251bd..e3a7a62 100644 --- a/Help/release/3.14.rst +++ b/Help/release/3.14.rst @@ -412,3 +412,11 @@ Changes made since CMake 3.14.0 include the following. incorrectly propagate usage requirements of those dependencies to dependents that link the static library. This has been fixed. The bug also existed in 3.13.0 through 3.13.4 and is fixed in 3.13.5. + +3.14.5 +------ + +* Entries of the ``CPATH`` environment variable are no longer excluded + from explicit use via :command:`include_directories` and + :command:`target_include_directories` as they were in CMake 3.14.0 + through 3.14.4. diff --git a/Help/release/dev/CMAKE_FRAMEWORK.rst b/Help/release/dev/CMAKE_FRAMEWORK.rst new file mode 100644 index 0000000..0253e04 --- /dev/null +++ b/Help/release/dev/CMAKE_FRAMEWORK.rst @@ -0,0 +1,6 @@ +CMAKE_FRAMEWORK +--------------- + +* A :variable:`CMAKE_FRAMEWORK` variable was added to + initialize the :prop_tgt:`FRAMEWORK` property on all + targets. diff --git a/Help/release/dev/FindPython-CMP0094.rst b/Help/release/dev/FindPython-CMP0094.rst new file mode 100644 index 0000000..43442fc --- /dev/null +++ b/Help/release/dev/FindPython-CMP0094.rst @@ -0,0 +1,5 @@ +FindPython-CMP0094 +------------------ + +* Modules :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython` + have changed default strategy for lookup. See policy :policy:`CMP0094`. diff --git a/Help/release/dev/FindPython-FIND_FRAMEWORK.rst b/Help/release/dev/FindPython-FIND_FRAMEWORK.rst new file mode 100644 index 0000000..f390460 --- /dev/null +++ b/Help/release/dev/FindPython-FIND_FRAMEWORK.rst @@ -0,0 +1,5 @@ +FindPython-FIND_FRAMEWORK +------------------------- + +* Modules :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython` + gain a new variable to control frameworks lookup on macOS. diff --git a/Help/release/dev/FindPython-FIND_STRATEGY.rst b/Help/release/dev/FindPython-FIND_STRATEGY.rst new file mode 100644 index 0000000..1d06e04 --- /dev/null +++ b/Help/release/dev/FindPython-FIND_STRATEGY.rst @@ -0,0 +1,5 @@ +FindPython-FIND_STRATEGY +------------------------ + +* Modules :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython` + gain a new way to control lookup strategy. diff --git a/Help/release/dev/clang-gnulike-support.rst b/Help/release/dev/clang-gnulike-support.rst new file mode 100644 index 0000000..87715d7 --- /dev/null +++ b/Help/release/dev/clang-gnulike-support.rst @@ -0,0 +1,5 @@ +clang-gnulike-support +--------------------- + +* The ``Clang`` compiler variant on Windows that targets the MSVC ABI + but has a GNU-like command line is now supported. diff --git a/Help/release/dev/cmake-e-tar-extract-specific-files.rst b/Help/release/dev/cmake-e-tar-extract-specific-files.rst new file mode 100644 index 0000000..4ab3eab --- /dev/null +++ b/Help/release/dev/cmake-e-tar-extract-specific-files.rst @@ -0,0 +1,8 @@ +cmake-e-tar-extract-specific-files +---------------------------------- + +* The :manual:`cmake(1)` ``-E tar`` tool allow for extract (``-x``) or list + (``-t``) only specific files or directories. To select pathnames append + a space-separated list of file names or directories. + When extracting selected files or directories, you must provide their exact + pathname, as printed by list (``-t``) diff --git a/Help/release/dev/cmake-e-tar-zstd-support.rst b/Help/release/dev/cmake-e-tar-zstd-support.rst new file mode 100644 index 0000000..e3488b5 --- /dev/null +++ b/Help/release/dev/cmake-e-tar-zstd-support.rst @@ -0,0 +1,7 @@ +Help/release/dev/cmake-e-tar-zstd-support +----------------------------------------- + +* The :manual:`cmake(1)` ``-E tar`` tool now support Zstandard compression + algorithm with ``--zstd`` option. Zstandard was designed to give + a compression ratio comparable to that of the DEFLATE (zip) algorithm, + but faster, especially for decompression. diff --git a/Help/release/dev/cmake_automoc_relaxed_mode.rst b/Help/release/dev/cmake_automoc_relaxed_mode.rst new file mode 100644 index 0000000..aa4772a --- /dev/null +++ b/Help/release/dev/cmake_automoc_relaxed_mode.rst @@ -0,0 +1,5 @@ +cmake_automoc_relaxed_mode +-------------------------- + +* The variable :variable:`CMAKE_AUTOMOC_RELAXED_MODE` is considered + deprecated. Support still exists but will be removed in future versions. diff --git a/Help/release/dev/vs-add-package-references.rst b/Help/release/dev/vs-add-package-references.rst new file mode 100644 index 0000000..2d260dc --- /dev/null +++ b/Help/release/dev/vs-add-package-references.rst @@ -0,0 +1,6 @@ +vs-add-package-references +------------------------- + +* A :prop_tgt:`VS_PACKAGE_REFERENCES` target property was added to + tell :ref:`Visual Studio Generators` to add references to nuget + packages. diff --git a/Help/variable/CMAKE_AUTOMOC_RELAXED_MODE.rst b/Help/variable/CMAKE_AUTOMOC_RELAXED_MODE.rst index addc62d..6c0c61b 100644 --- a/Help/variable/CMAKE_AUTOMOC_RELAXED_MODE.rst +++ b/Help/variable/CMAKE_AUTOMOC_RELAXED_MODE.rst @@ -1,6 +1,8 @@ CMAKE_AUTOMOC_RELAXED_MODE -------------------------- +.. deprecated:: 3.15 + Switch between strict and relaxed automoc mode. By default, :prop_tgt:`AUTOMOC` behaves exactly as described in the diff --git a/Help/variable/CMAKE_FRAMEWORK.rst b/Help/variable/CMAKE_FRAMEWORK.rst new file mode 100644 index 0000000..591041c --- /dev/null +++ b/Help/variable/CMAKE_FRAMEWORK.rst @@ -0,0 +1,7 @@ +CMAKE_FRAMEWORK +--------------- + +Default value for :prop_tgt:`FRAMEWORK` of targets. + +This variable is used to initialize the :prop_tgt:`FRAMEWORK` property on +all the targets. See that target property for additional information. diff --git a/Help/variable/CMAKE_JOB_POOL_LINK.rst b/Help/variable/CMAKE_JOB_POOL_LINK.rst index 338f771..eeee6e0 100644 --- a/Help/variable/CMAKE_JOB_POOL_LINK.rst +++ b/Help/variable/CMAKE_JOB_POOL_LINK.rst @@ -1,5 +1,5 @@ CMAKE_JOB_POOL_LINK ----------------------- +------------------- This variable is used to initialize the :prop_tgt:`JOB_POOL_LINK` property on all the targets. See :prop_tgt:`JOB_POOL_LINK` diff --git a/Help/variable/CTEST_CUSTOM_WARNING_EXCEPTION.rst b/Help/variable/CTEST_CUSTOM_WARNING_EXCEPTION.rst index 36fa37d..a03d473 100644 --- a/Help/variable/CTEST_CUSTOM_WARNING_EXCEPTION.rst +++ b/Help/variable/CTEST_CUSTOM_WARNING_EXCEPTION.rst @@ -2,6 +2,6 @@ CTEST_CUSTOM_WARNING_EXCEPTION ------------------------------ A list of regular expressions which will be used to exclude when detecting -warning messages in build outputs by the :command:`ctest_test` command. +warning messages in build outputs by the :command:`ctest_build` command. .. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_CUSTOM_WARNING_MATCH.rst b/Help/variable/CTEST_CUSTOM_WARNING_MATCH.rst index a35be96..18aa6b3 100644 --- a/Help/variable/CTEST_CUSTOM_WARNING_MATCH.rst +++ b/Help/variable/CTEST_CUSTOM_WARNING_MATCH.rst @@ -2,6 +2,6 @@ CTEST_CUSTOM_WARNING_MATCH -------------------------- A list of regular expressions which will be used to detect warning messages in -build outputs by the :command:`ctest_test` command. +build outputs by the :command:`ctest_build` command. .. include:: CTEST_CUSTOM_XXX.txt |