diff options
Diffstat (limited to 'Help')
50 files changed, 505 insertions, 72 deletions
diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst index 89787d1..4e5484f 100644 --- a/Help/command/ctest_test.rst +++ b/Help/command/ctest_test.rst @@ -190,29 +190,33 @@ Check the `CDash test measurement documentation <https://github.com/Kitware/CDash/blob/master/docs/test_measurements.md>`_ for more information on the types of test measurements that CDash recognizes. +Starting in version 3.22, CTest can parse custom measurements from tags named +``<CTestMeasurement>`` or ``<CTestMeasurementFile>``. The older names +``<DartMeasurement>`` and ``<DartMeasurementFile>`` are still supported. + The following example demonstrates how to output a variety of custom test measurements. .. code-block:: c++ std::cout << - "<DartMeasurement type=\"numeric/double\" name=\"score\">28.3</DartMeasurement>" + "<CTestMeasurement type=\"numeric/double\" name=\"score\">28.3</CTestMeasurement>" << std::endl; std::cout << - "<DartMeasurement type=\"text/string\" name=\"color\">red</DartMeasurement>" + "<CTestMeasurement type=\"text/string\" name=\"color\">red</CTestMeasurement>" << std::endl; std::cout << - "<DartMeasurement type=\"text/link\" name=\"CMake URL\">https://cmake.org</DartMeasurement>" + "<CTestMeasurement type=\"text/link\" name=\"CMake URL\">https://cmake.org</CTestMeasurement>" << std::endl; std::cout << - "<DartMeasurement type=\"text/preformatted\" name=\"Console Output\">" << + "<CTestMeasurement type=\"text/preformatted\" name=\"Console Output\">" << "line 1.\n" << " \033[31;1m line 2. Bold red, and indented!\033[0;0ml\n" << "line 3. Not bold or indented...\n" << - "</DartMeasurement>" << std::endl; + "</CTestMeasurement>" << std::endl; Image Measurements """""""""""""""""" @@ -222,16 +226,16 @@ The following example demonstrates how to upload test images to CDash. .. code-block:: c++ std::cout << - "<DartMeasurementFile type=\"image/jpg\" name=\"TestImage\">" << - "/dir/to/test_img.jpg</DartMeasurementFile>" << std::endl; + "<CTestMeasurementFile type=\"image/jpg\" name=\"TestImage\">" << + "/dir/to/test_img.jpg</CTestMeasurementFile>" << std::endl; std::cout << - "<DartMeasurementFile type=\"image/gif\" name=\"ValidImage\">" << - "/dir/to/valid_img.gif</DartMeasurementFile>" << std::endl; + "<CTestMeasurementFile type=\"image/gif\" name=\"ValidImage\">" << + "/dir/to/valid_img.gif</CTestMeasurementFile>" << std::endl; std::cout << - "<DartMeasurementFile type=\"image/png\" name=\"AlgoResult\"> << - "/dir/to/img.png</DartMeasurementFile>" + "<CTestMeasurementFile type=\"image/png\" name=\"AlgoResult\"> << + "/dir/to/img.png</CTestMeasurementFile>" << std::endl; Images will be displayed together in an interactive comparison mode on CDash @@ -257,8 +261,10 @@ The following example demonstrates how to upload non-image files to CDash. .. code-block:: c++ std::cout << - "<DartMeasurementFile type=\"file\" name=\"MyTestInputData\">" << - "/dir/to/data.csv</DartMeasurementFile>" << std::endl; + "<CTestMeasurementFile type=\"file\" name=\"TestInputData1\">" << + "/dir/to/data1.csv</CTestMeasurementFile>\n" << + "<CTestMeasurementFile type=\"file\" name=\"TestInputData2\">" << + "/dir/to/data2.csv</CTestMeasurementFile>" << std::endl; If the name of the file to upload is known at configure time, you can use the :prop_test:`ATTACHED_FILES` or :prop_test:`ATTACHED_FILES_ON_FAIL` test @@ -274,3 +280,18 @@ The following example demonstrates how to specify a custom value for the std::cout << "<CTestDetails>My Custom Details Value</CTestDetails>" << std::endl; + +Additional Labels +""""""""""""""""" + +The following example demonstrates how to add additional labels to a test +at runtime. + +.. code-block:: c++ + + std::cout << + "<CTestLabel>Custom Label 1</CTestLabel>\n" << + "<CTestLabel>Custom Label 2</CTestLabel>" << std::endl; + +Use the :prop_test:`LABELS` test property instead for labels that can be +determined at configure time. diff --git a/Help/command/file.rst b/Help/command/file.rst index f038871..96a55ee 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -843,6 +843,11 @@ and ``NO_SOURCE_PERMISSIONS`` is default. Installation scripts generated by the :command:`install` command use this signature (with some undocumented options for internal use). +.. versionchanged:: 3.22 + + The environment variable :envvar:`CMAKE_INSTALL_MODE` can override the + default copying behavior of :command:`file(INSTALL)`. + .. _SIZE: .. code-block:: cmake diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 3dfd62f..bd26010 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -28,11 +28,26 @@ that the package cannot be found if it is not ``REQUIRED``. The ``REQUIRED`` option stops processing with an error message if the package cannot be found. A package-specific list of required components may be listed after the -``COMPONENTS`` option (or after the ``REQUIRED`` option if present). +``COMPONENTS`` keyword. If any of these components are not able to be +satisfied, the package overall is considered to be not found. If the +``REQUIRED`` option is also present, this is treated as a fatal error, +otherwise execution still continues. As a form of shorthand, if the +``REQUIRED`` option is present, the ``COMPONENTS`` keyword can be omitted +and the required components can be listed directly after ``REQUIRED``. + Additional optional components may be listed after -``OPTIONAL_COMPONENTS``. Available components and their influence on -whether a package is considered to be found are defined by the target -package. +``OPTIONAL_COMPONENTS``. If these cannot be satisfied, the package overall +can still be considered found, as long as all required components are +satisfied. + +The set of available components and their meaning are defined by the +target package. Formally, it is up to the target package how to +interpret the component information given to it, but it should follow +the expectations stated above. For calls where no components are specified, +there is no single expected behavior and target packages should clearly +define what occurs in such cases. Common arrangements include assuming it +should find all components, no components or some well-defined subset of the +available components. .. _FIND_PACKAGE_VERSION_FORMAT: @@ -448,8 +463,15 @@ which the file is found. The :variable:`CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS` variable may be set to ``TRUE`` before calling ``find_package`` in order to resolve symbolic links and store the real path to the file. -Every non-REQUIRED ``find_package`` call can be disabled by setting the -:variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to ``TRUE``. +Every non-REQUIRED ``find_package`` call can be disabled or made REQUIRED: + +* Setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable + to ``TRUE`` disables the package. + +* Setting the :variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` variable + to ``TRUE`` makes the package REQUIRED. + +Setting both variables to ``TRUE`` simultaneously is an error. Package File Interface Variables ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -479,7 +501,7 @@ restores their original state before returning): ``<PackageName>_FIND_VERSION_EXACT`` True if ``EXACT`` option was given ``<PackageName>_FIND_COMPONENTS`` - List of requested components + List of specified components (required and optional) ``<PackageName>_FIND_REQUIRED_<c>`` True if component ``<c>`` is required, false if component ``<c>`` is optional diff --git a/Help/command/get_property.rst b/Help/command/get_property.rst index f77d8af..46da285 100644 --- a/Help/command/get_property.rst +++ b/Help/command/get_property.rst @@ -9,7 +9,7 @@ Get a property. <GLOBAL | DIRECTORY [<dir>] | TARGET <target> | - SOURCE <source> | + SOURCE <source> [DIRECTORY <dir> | TARGET_DIRECTORY <target>] | INSTALL <file> | TEST <test> | diff --git a/Help/command/install.rst b/Help/command/install.rst index c6af489..1236f1d 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -30,6 +30,10 @@ are executed in order during installation. with those in the parent directory to run in the order declared (see policy :policy:`CMP0082`). +.. versionchanged:: 3.22 + The environment variable :envvar:`CMAKE_INSTALL_MODE` can override the + default copying behavior of :command:`install()`. + There are multiple signatures for this command. Some of them define installation options for files and targets. Options common to multiple signatures are covered here but they are valid only for diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst index bf437b4..555520d 100644 --- a/Help/command/set_property.rst +++ b/Help/command/set_property.rst @@ -9,8 +9,8 @@ Set a named property in a given scope. DIRECTORY [<dir>] | TARGET [<target1> ...] | SOURCE [<src1> ...] - [DIRECTORY <dirs> ...] | - [TARGET_DIRECTORY <targets> ...] + [DIRECTORY <dirs> ...] + [TARGET_DIRECTORY <targets> ...] | INSTALL [<file1> ...] | TEST [<test1> ...] | CACHE [<entry1> ...] > diff --git a/Help/command/source_group.rst b/Help/command/source_group.rst index a4b5bf1..83ae286 100644 --- a/Help/command/source_group.rst +++ b/Help/command/source_group.rst @@ -22,7 +22,8 @@ The options are: CMake will automatically detect, from ``<src>`` files paths, source groups it needs to create, to keep structure of source groups analogically to the actual files and directories structure in the project. Paths of ``<src>`` - files will be cut to be relative to ``<root>``. + files will be cut to be relative to ``<root>``. The command fails if the + paths within ``src`` do not start with ``root``. ``PREFIX`` .. versionadded:: 3.8 diff --git a/Help/command/string.rst b/Help/command/string.rst index 8ad0089..29ad082 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -449,38 +449,73 @@ be in Coordinated Universal Time (UTC) rather than local time. The optional ``<format_string>`` may contain the following format specifiers: -:: +``%%`` + .. versionadded:: 3.8 - %% A literal percent sign (%). - %d The day of the current month (01-31). - %H The hour on a 24-hour clock (00-23). - %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). - %B Full month name (e.g. October). - %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). - %A Full weekday name (e.g. Friday). - %y The last two digits of the current year (00-99) - %Y The current year. - -.. versionadded:: 3.6 - ``%s`` format specifier (UNIX time). + A literal percent sign (%). -.. versionadded:: 3.7 - ``%a`` and ``%b`` format specifiers (abbreviated month and weekday names). +``%d`` + The day of the current month (01-31). -.. versionadded:: 3.8 - ``%%`` specifier (literal ``%``). +``%H`` + The hour on a 24-hour clock (00-23). -.. versionadded:: 3.7 - ``%A`` and ``%B`` format specifiers (full month and weekday names). +``%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`` + .. versionadded:: 3.7 + + Abbreviated month name (e.g. Oct). + +``%B`` + .. versionadded:: 3.10 + + Full month name (e.g. October). + +``%M`` + The minute of the current hour (00-59). + +``%s`` + .. versionadded:: 3.6 + + 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). + +``%V`` + .. versionadded:: 3.22 + + The ISO 8601 week number of the current year (01-53). + +``%w`` + The day of the current week. 0 is Sunday. (0-6) + +``%a`` + .. versionadded:: 3.7 + + Abbreviated weekday name (e.g. Fri). + +``%A`` + .. versionadded:: 3.10 + + Full weekday name (e.g. Friday). + +``%y`` + The last two digits of the current year (00-99). + +``%Y`` + The current year. Unknown format specifiers will be ignored and copied to the output as-is. diff --git a/Help/cpack_gen/deb.rst b/Help/cpack_gen/deb.rst index d8d53ec..f96ca32 100644 --- a/Help/cpack_gen/deb.rst +++ b/Help/cpack_gen/deb.rst @@ -274,10 +274,23 @@ List of CPack DEB generator specific variables: Possible values are: - - lzma - - xz - - bzip2 - - gzip + ``lzma`` + Lempel–Ziv–Markov chain algorithm + + ``xz`` + XZ Utils compression + + ``bzip2`` + bzip2 Burrows–Wheeler algorithm + + ``gzip`` + GNU Gzip compression + + ``zstd`` + .. versionadded:: 3.22 + + Zstandard compression + .. variable:: CPACK_DEBIAN_PACKAGE_PRIORITY CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY @@ -652,9 +665,18 @@ Dbgsym packaging has its own set of variables: .. note:: + Setting this also strips the ELF files in the generated non-dbgsym package, + which results in debuginfo only being available in the dbgsym package. + +.. note:: + Binaries must contain debug symbols before packaging so use either ``Debug`` or ``RelWithDebInfo`` for :variable:`CMAKE_BUILD_TYPE` variable value. + Additionally, if :variable:`CPACK_STRIP_FILES` is set, the files will be stripped before + they get to the DEB generator, so will not contain debug symbols and + a dbgsym package will not get built. Do not use with :variable:`CPACK_STRIP_FILES`. + Building Debian packages on Windows ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/cpack_gen/nsis.rst b/Help/cpack_gen/nsis.rst index 02e33ba..299cfec 100644 --- a/Help/cpack_gen/nsis.rst +++ b/Help/cpack_gen/nsis.rst @@ -3,8 +3,8 @@ CPack NSIS Generator CPack Nullsoft Scriptable Install System (NSIS) generator specific options. -.. versionchanged:: 3.17 - The NSIS generator requires NSIS 3.0 or newer. +.. versionchanged:: 3.22 + The NSIS generator requires NSIS 3.03 or newer. Variables specific to CPack NSIS generator ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -201,3 +201,9 @@ on Windows Nullsoft Scriptable Install System. .. versionadded:: 3.21 If set, specify the name of the NSIS executable. Default is ``makensis``. + +.. variable:: CPACK_NSIS_IGNORE_LICENSE_PAGE + + .. versionadded:: 3.22 + + If set, do not display the page containing the license during installation. diff --git a/Help/cpack_gen/rpm.rst b/Help/cpack_gen/rpm.rst index 322ab68..823594a 100644 --- a/Help/cpack_gen/rpm.rst +++ b/Help/cpack_gen/rpm.rst @@ -840,6 +840,10 @@ Debuginfo RPM packaging has its own set of variables: Binaries must contain debug symbols before packaging so use either ``Debug`` or ``RelWithDebInfo`` for :variable:`CMAKE_BUILD_TYPE` variable value. + Additionally, if :variable:`CPACK_STRIP_FILES` is set, the files will be stripped before + they get to the RPM generator, so will not contain debug symbols and + a debuginfo package will not get built. Do not use with :variable:`CPACK_STRIP_FILES`. + .. note:: Packages generated from packages without binary files, with binary files but @@ -1035,3 +1039,14 @@ Source RPM packaging has its own set of variables: example:: set(CPACK_RPM_BUILDREQUIRES "python >= 2.5.0, cmake >= 2.8") + +.. VARIABLE:: CPACK_RPM_REQUIRES_EXCLUDE_FROM + + * Mandatory : NO + * Default : - + + May be used to keep the dependency generator from scanning specific files + or directories for dependencies. Note that you can use a regular + expression that matches all of the directories or files, for example:: + + set(CPACK_RPM_REQUIRES_EXCLUDE_FROM "bin/libqsqloci.*\\.so.*") diff --git a/Help/envvar/CMAKE_BUILD_TYPE.rst b/Help/envvar/CMAKE_BUILD_TYPE.rst new file mode 100644 index 0000000..f798aff --- /dev/null +++ b/Help/envvar/CMAKE_BUILD_TYPE.rst @@ -0,0 +1,10 @@ +CMAKE_BUILD_TYPE +---------------- + +.. versionadded:: 3.22 + +.. include:: ENV_VAR.txt + +The ``CMAKE_BUILD_TYPE`` environment variable specifies a default value +for the :variable:`CMAKE_BUILD_TYPE` variable when there is no explicit +configuration given on the first run while creating a new build tree. diff --git a/Help/envvar/CMAKE_CONFIGURATION_TYPES.rst b/Help/envvar/CMAKE_CONFIGURATION_TYPES.rst new file mode 100644 index 0000000..833aa4a --- /dev/null +++ b/Help/envvar/CMAKE_CONFIGURATION_TYPES.rst @@ -0,0 +1,11 @@ +CMAKE_CONFIGURATION_TYPES +------------------------- + +.. versionadded:: 3.22 + +.. include:: ENV_VAR.txt + +The ``CMAKE_CONFIGURATION_TYPES`` environment variable specifies a +default value for the :variable:`CMAKE_CONFIGURATION_TYPES` variable +when there is no explicit configuration given on the first run while +creating a new build tree. diff --git a/Help/envvar/CMAKE_INSTALL_MODE.rst b/Help/envvar/CMAKE_INSTALL_MODE.rst new file mode 100644 index 0000000..37db0d7 --- /dev/null +++ b/Help/envvar/CMAKE_INSTALL_MODE.rst @@ -0,0 +1,37 @@ +CMAKE_INSTALL_MODE +------------------ + +.. versionadded:: 3.22 + +.. include:: ENV_VAR.txt + +The ``CMAKE_INSTALL_MODE`` environment variable allows users to operate +CMake in an alternate mode of :command:`file(INSTALL)` and :command:`install()`. + +The default behavior for an installation is to copy a source file from a +source directory into a destination directory. This environment variable +however allows the user to override this behavior, causing CMake to create +symbolic links instead. + +.. note:: + A symbolic link consists of a reference file path rather than contents of its own, + hence there are two ways to express the relation, either by a relative or an absolute path. + +The following values are allowed for ``CMAKE_INSTALL_MODE``: + +* empty, unset or ``COPY``: default behavior, duplicate the file at its destination +* ``ABS_SYMLINK``: create an *absolute* symbolic link to the source file at the destination *or fail* +* ``ABS_SYMLINK_OR_COPY``: like ``ABS_SYMLINK`` but silently copy on error +* ``REL_SYMLINK``: create an *relative* symbolic link to the source file at the destination *or fail* +* ``REL_SYMLINK_OR_COPY``: like ``REL_SYMLINK`` but silently copy on error +* ``SYMLINK``: try as if through ``REL_SYMLINK`` and fall back to ``ABS_SYMLINK`` if the referenced + file cannot be expressed using a relative path. Fail on error. +* ``SYMLINK_OR_COPY``: like ``SYMLINK`` but silently copy on error + +Installing symbolic links rather than copying files can help conserve storage space because files do +not have to be duplicated on disk. However, modifications applied to the source immediately affects +the symbolic link and vice versa. *Use with caution*. + +.. note:: ``CMAKE_INSTALL_MODE`` only affects files, *not* directories. + +.. note:: Symbolic links are not available on all platforms. diff --git a/Help/generator/Visual Studio 10 2010.rst b/Help/generator/Visual Studio 10 2010.rst index c065550..9ec33c3 100644 --- a/Help/generator/Visual Studio 10 2010.rst +++ b/Help/generator/Visual Studio 10 2010.rst @@ -1,7 +1,14 @@ Visual Studio 10 2010 --------------------- -Generates Visual Studio 10 (VS 2010) project files. +Deprecated. Generates Visual Studio 10 (VS 2010) project files. + +.. note:: + This generator is deprecated and will be removed in a future version + of CMake. It will still be possible to build with VS 10 2010 tools + using the :generator:`Visual Studio 11 2012` (or above) generator + with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v100``, or by + using the :generator:`NMake Makefiles` generator. For compatibility with CMake versions prior to 3.0, one may specify this generator using the name ``Visual Studio 10`` without the year component. diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index fa38588..0799fdd 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -30,12 +30,15 @@ Environment Variables that Control the Build /envvar/CMAKE_APPLE_SILICON_PROCESSOR /envvar/CMAKE_BUILD_PARALLEL_LEVEL + /envvar/CMAKE_BUILD_TYPE + /envvar/CMAKE_CONFIGURATION_TYPES /envvar/CMAKE_CONFIG_TYPE /envvar/CMAKE_EXPORT_COMPILE_COMMANDS /envvar/CMAKE_GENERATOR /envvar/CMAKE_GENERATOR_INSTANCE /envvar/CMAKE_GENERATOR_PLATFORM /envvar/CMAKE_GENERATOR_TOOLSET + /envvar/CMAKE_INSTALL_MODE /envvar/CMAKE_LANG_COMPILER_LAUNCHER /envvar/CMAKE_LANG_LINKER_LAUNCHER /envvar/CMAKE_MSVCIDE_RUN_PATH diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst index 4b2934a..5262105 100644 --- a/Help/manual/cmake-packages.7.rst +++ b/Help/manual/cmake-packages.7.rst @@ -74,7 +74,9 @@ package. By setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to ``TRUE``, the ``<PackageName>`` package will not be searched, and will always -be ``NOTFOUND``. +be ``NOTFOUND``. Likewise, setting the +:variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` to ``TRUE`` will make the +package REQUIRED. .. _`Config File Packages`: diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 5f18a82..c71e8ff 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -202,6 +202,7 @@ Properties on Targets /prop_tgt/EXPORT_NAME /prop_tgt/EXPORT_PROPERTIES /prop_tgt/FOLDER + /prop_tgt/Fortran_BUILDING_INSTRINSIC_MODULES /prop_tgt/Fortran_FORMAT /prop_tgt/Fortran_MODULE_DIRECTORY /prop_tgt/Fortran_PREPROCESS @@ -450,6 +451,7 @@ Properties on Tests /prop_test/DEPENDS /prop_test/DISABLED /prop_test/ENVIRONMENT + /prop_test/ENVIRONMENT_MODIFICATION /prop_test/FAIL_REGULAR_EXPRESSION /prop_test/FIXTURES_CLEANUP /prop_test/FIXTURES_REQUIRED diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 9cea0fb..7cfa0c8 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -231,6 +231,7 @@ Variables that Change Behavior /variable/CMAKE_PROJECT_INCLUDE_BEFORE /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE + /variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName /variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY /variable/CMAKE_STAGING_PREFIX /variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS @@ -428,6 +429,7 @@ Variables that Control the Build /variable/CMAKE_LANG_LINKER_LAUNCHER /variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG /variable/CMAKE_LANG_LINK_LIBRARY_FLAG + /variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG /variable/CMAKE_LANG_VISIBILITY_PRESET /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG @@ -438,6 +440,7 @@ Variables that Control the Build /variable/CMAKE_LINK_LIBRARY_FILE_FLAG /variable/CMAKE_LINK_LIBRARY_FLAG /variable/CMAKE_LINK_WHAT_YOU_USE + /variable/CMAKE_LINK_WHAT_YOU_USE_CHECK /variable/CMAKE_MACOSX_BUNDLE /variable/CMAKE_MACOSX_RPATH /variable/CMAKE_MAP_IMPORTED_CONFIG_CONFIG diff --git a/Help/prop_test/ENVIRONMENT.rst b/Help/prop_test/ENVIRONMENT.rst index 102c792..43bcdbe 100644 --- a/Help/prop_test/ENVIRONMENT.rst +++ b/Help/prop_test/ENVIRONMENT.rst @@ -5,5 +5,5 @@ Specify environment variables that should be defined for running a test. If set to a list of environment variables and values of the form ``MYVAR=value`` those environment variables will be defined while running -the test. The environment is restored to its previous state after the -test is done. +the test. The environment changes from this property do not affect other +tests. diff --git a/Help/prop_test/ENVIRONMENT_MODIFICATION.rst b/Help/prop_test/ENVIRONMENT_MODIFICATION.rst new file mode 100644 index 0000000..ffd5de4 --- /dev/null +++ b/Help/prop_test/ENVIRONMENT_MODIFICATION.rst @@ -0,0 +1,33 @@ +ENVIRONMENT_MODIFICATION +------------------------ + +Specify environment variables that should be modified for running a test. Note +that the operations performed by this property are performed after the +:prop_test:`ENVIRONMENT` property is already applied. + +If set to a list of environment variables and values of the form +``MYVAR=OP:VALUE``. Entries are considered in the order specified in the +property's value. The ``OP`` may be one of: + + - ``reset``: Reset to the unmodified value, ignoring all modifications to + ``MYVAR`` prior to this entry. Note that this will reset the variable to + the value set by :prop_test:`ENVIRONMENT`, if it was set, and otherwise + to its state from the rest of the CTest execution. + - ``set``: Replaces the current value of ``MYVAR`` with ``VALUE``. + - ``unset``: Unsets the current value of ``MYVAR``. + - ``string_append``: Appends ``VALUE`` to the current value of ``MYVAR``. + - ``string_prepend``: Prepends ``VALUE`` to the current value of ``MYVAR``. + - ``path_list_append``: Appends ``VALUE`` to the current value of ``MYVAR`` + using the platform-specific list separator. + - ``path_list_prepend``: Prepends ``VALUE`` to the current value of + ``MYVAR`` using the platform-specific list separator. + - ``cmake_list_append``: Appends ``VALUE`` to the current value of ``MYVAR`` + using ``;`` as the separator. + - ``cmake_list_prepend``: Prepends ``VALUE`` to the current value of + ``MYVAR`` using ``;`` as the separator. + +Unrecognized ``OP`` values will result in the test failing before it is +executed. This is so that future operations may be added without changing +valid behavior of existing tests. + +The environment changes from this property do not affect other tests. diff --git a/Help/prop_tgt/Fortran_BUILDING_INSTRINSIC_MODULES.rst b/Help/prop_tgt/Fortran_BUILDING_INSTRINSIC_MODULES.rst new file mode 100644 index 0000000..518bca7 --- /dev/null +++ b/Help/prop_tgt/Fortran_BUILDING_INSTRINSIC_MODULES.rst @@ -0,0 +1,14 @@ +Fortran_BUILDING_INSTRINSIC_MODULES +----------------------------------- + +Instructs the CMake Fortran preprocessor that the target is building +Fortran intrinsics for building a Fortran compiler. + +This property is off by default and should be turned only on projects +that build a Fortran compiler. It should not be turned on for projects +that use a Fortran compiler. + +Turning this property on will correctly add dependencies for building +Fortran intrinsic modules whereas turning the property off will ignore +Fortran intrinsic modules in the dependency graph as they are supplied +by the compiler itself. diff --git a/Help/prop_tgt/LINK_WHAT_YOU_USE.rst b/Help/prop_tgt/LINK_WHAT_YOU_USE.rst index 2ed93ad..d6de0d4 100644 --- a/Help/prop_tgt/LINK_WHAT_YOU_USE.rst +++ b/Help/prop_tgt/LINK_WHAT_YOU_USE.rst @@ -1,16 +1,22 @@ LINK_WHAT_YOU_USE ---------------------------- +----------------- .. versionadded:: 3.7 -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 is a boolean option that, when set to ``TRUE``, will automatically run +contents of variable :variable:`CMAKE_LINK_WHAT_YOU_USE_CHECK` on the target +after it is linked. In addition, the linker flag specified by variable +:variable:`CMAKE_<LANG>_LINK_WHAT_YOU_USE_FLAG` 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. + +.. note:: + + For now, it is only supported for ``ELF`` platforms and is only applicable to + executable and shared or module library targets. This property will be + ignored for any other targets and configurations. This property is initialized by the value of the :variable:`CMAKE_LINK_WHAT_YOU_USE` variable if it is set 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/FindPkgConfig-PKG_CONFIG-args.rst b/Help/release/dev/FindPkgConfig-PKG_CONFIG-args.rst new file mode 100644 index 0000000..44c26b5 --- /dev/null +++ b/Help/release/dev/FindPkgConfig-PKG_CONFIG-args.rst @@ -0,0 +1,5 @@ +FindPkgConfig-PKG_CONFIG-args +----------------------------- + +* The :module:`FindPkgConfig` module gained a :variable:`PKG_CONFIG_ARGN` + variable to specify arguments to ``pkg-config`` calls. diff --git a/Help/release/dev/GoogleTest-gtest-filter.rst b/Help/release/dev/GoogleTest-gtest-filter.rst new file mode 100644 index 0000000..48b97a7 --- /dev/null +++ b/Help/release/dev/GoogleTest-gtest-filter.rst @@ -0,0 +1,6 @@ +GoogleTest-gtest-filter +----------------------- + +* The :module:`GoogleTest` module :command:`gtest_discover_tests` + function gained a ``TEST_FILTER`` option to filter tests using + ``--gtest_filter`` during test discovery. diff --git a/Help/release/dev/LINK_WHAT_USE_USE-configuration.rst b/Help/release/dev/LINK_WHAT_USE_USE-configuration.rst new file mode 100644 index 0000000..990ed36 --- /dev/null +++ b/Help/release/dev/LINK_WHAT_USE_USE-configuration.rst @@ -0,0 +1,5 @@ +LINK_WHAT_YOU_USE-configuration +------------------------------- + +* Configuration for :prop_tgt:`LINK_WHAT_YOU_USE` feature is now controlled by + ``CMake`` variables and only active for ``ELF`` platforms. diff --git a/Help/release/dev/UseSWIG-dependencies.rst b/Help/release/dev/UseSWIG-dependencies.rst new file mode 100644 index 0000000..a3ec29e --- /dev/null +++ b/Help/release/dev/UseSWIG-dependencies.rst @@ -0,0 +1,6 @@ +UseSWIG-dependencies +-------------------- + +* :module:`UseSWIG` module gained the capability, for + :ref:`Visual Studio Generators` to use `swig` tool to generate implicit + dependencies. diff --git a/Help/release/dev/cmake-install-mode-symlink.rst b/Help/release/dev/cmake-install-mode-symlink.rst new file mode 100644 index 0000000..a5f75ca --- /dev/null +++ b/Help/release/dev/cmake-install-mode-symlink.rst @@ -0,0 +1,16 @@ +cmake-install-mode-symlink +-------------------------- + +* The :envvar:`CMAKE_INSTALL_MODE` environment variable was added to + allow users to override the default file-copying behavior of + :command:`install` and :command:`file(INSTALL)` into creating + symbolic links. This can aid in lowering storage space requirements + and avoiding redundancy. + +* The :command:`file(INSTALL)` can now be affected / modified by the + :envvar:`CMAKE_INSTALL_MODE` environment variable causing installation + of symbolic links instead of copying of files. + +* The :command:`install` can now be affected / modified by the + :envvar:`CMAKE_INSTALL_MODE` environment variable causing installation + of symbolic links instead of copying of files. diff --git a/Help/release/dev/cpack-deb-add-zstd-compression.rst b/Help/release/dev/cpack-deb-add-zstd-compression.rst new file mode 100644 index 0000000..a138455 --- /dev/null +++ b/Help/release/dev/cpack-deb-add-zstd-compression.rst @@ -0,0 +1,6 @@ +cpack-deb-add-zstd-compression +------------------------------ + +* The :cpack_gen:`CPack DEB Generator` gained the + option to set :variable:`CPACK_DEBIAN_COMPRESSION_TYPE` to zstd, + which enables Zstandard compression for deb packages. diff --git a/Help/release/dev/cpack-rpm-requires-exclude-from.rst b/Help/release/dev/cpack-rpm-requires-exclude-from.rst new file mode 100644 index 0000000..7125901 --- /dev/null +++ b/Help/release/dev/cpack-rpm-requires-exclude-from.rst @@ -0,0 +1,6 @@ +cpack-rpm-requires-exclude-from +------------------------------- + +* The :cpack_gen:`CPack RPM Generator` gained the + :variable:`CPACK_RPM_REQUIRES_EXCLUDE_FROM` option avoid scanning + specific paths for dependencies. diff --git a/Help/release/dev/ctest-environment-modifications.rst b/Help/release/dev/ctest-environment-modifications.rst new file mode 100644 index 0000000..64265f0 --- /dev/null +++ b/Help/release/dev/ctest-environment-modifications.rst @@ -0,0 +1,7 @@ +ctest-environment-modifications +------------------------------- + +* :manual:`ctest(1)` learned to be able to modify the environment for a test + through the :prop_test:`ENVIRONMENT_MODIFICATION` property. This is allows + for updates to environment variables based on the environment present at + test time. diff --git a/Help/release/dev/ctest-runtime-labels.rst b/Help/release/dev/ctest-runtime-labels.rst new file mode 100644 index 0000000..7ce0b64 --- /dev/null +++ b/Help/release/dev/ctest-runtime-labels.rst @@ -0,0 +1,7 @@ +ctest-runtime-labels +-------------------- + +* :manual:`ctest(1)` learned to recognize labels attached to a test at run time. + Previously it was only possible to attach labels to tests at configure time + by using the :prop_test:`LABELS` test property. + See :ref:`Additional Test Measurements` for more information. diff --git a/Help/release/dev/env-init-configs.rst b/Help/release/dev/env-init-configs.rst new file mode 100644 index 0000000..5c9892d --- /dev/null +++ b/Help/release/dev/env-init-configs.rst @@ -0,0 +1,9 @@ +env-init-configs +---------------- + +* The :envvar:`CMAKE_BUILD_TYPE` environment variable was added to + provide a default value for the :variable:`CMAKE_BUILD_TYPE` variable. + +* The :envvar:`CMAKE_CONFIGURATION_TYPES` environment variable was added to + provide a default value for the :variable:`CMAKE_CONFIGURATION_TYPES` + variable. diff --git a/Help/release/dev/find_package-required-var.rst b/Help/release/dev/find_package-required-var.rst new file mode 100644 index 0000000..36935ef --- /dev/null +++ b/Help/release/dev/find_package-required-var.rst @@ -0,0 +1,5 @@ +find_package-required-var +------------------------- + +* The :variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` variable was added + to turn a non-REQUIRED :command:`find_package` call into a REQUIRED one. diff --git a/Help/release/dev/msvc-isystem.rst b/Help/release/dev/msvc-isystem.rst new file mode 100644 index 0000000..4a5d79f --- /dev/null +++ b/Help/release/dev/msvc-isystem.rst @@ -0,0 +1,7 @@ +msvc-isystem +------------ + +* The MSVC compilers learned to pass the ``-external:I`` flag for system + includes when using the :generator:`Ninja` and :generator:`NMake Makefiles` + generators. This became available as of Visual Studio 16.10 (toolchain + version 14.29.30037). diff --git a/Help/release/dev/ninja-edit_cache.rst b/Help/release/dev/ninja-edit_cache.rst new file mode 100644 index 0000000..9083f56 --- /dev/null +++ b/Help/release/dev/ninja-edit_cache.rst @@ -0,0 +1,5 @@ +ninja-edit_cache +---------------- + +* The :ref:`Ninja Generators` now implement the ``edit_cache`` target + using :manual:`ccmake(1)` if available. diff --git a/Help/release/dev/nsis-minimal-version.rst b/Help/release/dev/nsis-minimal-version.rst new file mode 100644 index 0000000..b19597a --- /dev/null +++ b/Help/release/dev/nsis-minimal-version.rst @@ -0,0 +1,4 @@ +nsis-minimal-version.rst +------------------------ + +* The :cpack_gen:`CPack NSIS Generator` now requires NSIS 3.03 or later. diff --git a/Help/release/dev/nsis_ignore_install_page.rst b/Help/release/dev/nsis_ignore_install_page.rst new file mode 100644 index 0000000..2d8a8d0 --- /dev/null +++ b/Help/release/dev/nsis_ignore_install_page.rst @@ -0,0 +1,6 @@ +nsis_ignore_install_page +------------------------ + +* The :cpack_gen:`CPack NSIS Generator` gained a new variable + :variable:`CPACK_NSIS_IGNORE_LICENSE_PAGE` to ignore the + license page in the installer. diff --git a/Help/release/dev/string-TIMESTAMP-specifier-V.rst b/Help/release/dev/string-TIMESTAMP-specifier-V.rst new file mode 100644 index 0000000..afd3f03 --- /dev/null +++ b/Help/release/dev/string-TIMESTAMP-specifier-V.rst @@ -0,0 +1,5 @@ +string-TIMESTAMP-specifier-V +---------------------------- + +* The :command:`string(TIMESTAMP)` command now supports the ``%V`` + specifier for ISO 8601 week numbers. diff --git a/Help/release/dev/target_compile_features-ignore-disabled-langs.rst b/Help/release/dev/target_compile_features-ignore-disabled-langs.rst new file mode 100644 index 0000000..0eba125 --- /dev/null +++ b/Help/release/dev/target_compile_features-ignore-disabled-langs.rst @@ -0,0 +1,5 @@ +target_compile_features-ignore-disabled-langs +--------------------------------------------- + +* :command:`target_compile_features` learned to ignored features for languages that + aren't enabled. diff --git a/Help/release/dev/vs10-deprecate.rst b/Help/release/dev/vs10-deprecate.rst new file mode 100644 index 0000000..7bec391 --- /dev/null +++ b/Help/release/dev/vs10-deprecate.rst @@ -0,0 +1,5 @@ +vs10-deprecate +-------------- + +* The :generator:`Visual Studio 10 2010` generator is now deprecated + and will be removed in a future version of CMake. diff --git a/Help/release/index.rst b/Help/release/index.rst index 75667e5..5938878 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -7,6 +7,8 @@ CMake Release Notes This file should include the adjacent "dev.txt" file in development versions but not in release versions. +.. include:: dev.txt + Releases ======== diff --git a/Help/variable/CMAKE_BUILD_TYPE.rst b/Help/variable/CMAKE_BUILD_TYPE.rst index 405f7d5..9ad1481 100644 --- a/Help/variable/CMAKE_BUILD_TYPE.rst +++ b/Help/variable/CMAKE_BUILD_TYPE.rst @@ -23,3 +23,12 @@ Note that configuration names are case-insensitive. The value of this variable will be the same as it is specified when invoking CMake. For instance, if ``-DCMAKE_BUILD_TYPE=ReLeAsE`` is specified, then the value of ``CMAKE_BUILD_TYPE`` will be ``ReLeAsE``. + +This variable is initialized by the first :command:`project` or +:command:`enable_language` command called in a project when a new build +tree is first created. If the :envvar:`CMAKE_BUILD_TYPE` environment +variable is set, its value is used. Otherwise, a toolchain-specific +default is chosen when a language is enabled. + +See :variable:`CMAKE_CONFIGURATION_TYPES` for specifying the configuration +with multi-config generators. diff --git a/Help/variable/CMAKE_CONFIGURATION_TYPES.rst b/Help/variable/CMAKE_CONFIGURATION_TYPES.rst index 8fcc798..5298a72 100644 --- a/Help/variable/CMAKE_CONFIGURATION_TYPES.rst +++ b/Help/variable/CMAKE_CONFIGURATION_TYPES.rst @@ -8,5 +8,11 @@ such as ``Debug``, ``Release``, ``RelWithDebInfo`` etc. This has reasonable defaults on most platforms, but can be extended to provide other build types. +This variable is initialized by the first :command:`project` or +:command:`enable_language` command called in a project when a new build +tree is first created. If the :envvar:`CMAKE_CONFIGURATION_TYPES` +environment variable is set, its value is used. Otherwise, the default +value is generator-specific. + See :variable:`CMAKE_BUILD_TYPE` for specifying the configuration with single-config generators. diff --git a/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst b/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst index ed60020..f77e939 100644 --- a/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst +++ b/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst @@ -14,3 +14,5 @@ the package has already been found in a previous CMake run, the variables which have been stored in the cache will still be there. In that case it is recommended to remove the cache variables for this package from the cache using the cache editor or :manual:`cmake(1)` ``-U`` + +See also the :variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` variable. diff --git a/Help/variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG.rst b/Help/variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG.rst new file mode 100644 index 0000000..5004530 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG.rst @@ -0,0 +1,9 @@ +CMAKE_<LANG>_LINK_WHAT_YOU_USE_FLAG +----------------------------------- + +.. versionadded:: 3.22 + +Linker flag to be used to configure linker so that all specified libraries on +the command line will be linked into the target. + +See also variable :variable:`CMAKE_LINK_WHAT_YOU_USE_CHECK`. diff --git a/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst b/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst index 06b3aa8..bca4519 100644 --- a/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst +++ b/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst @@ -1,5 +1,5 @@ CMAKE_LINK_WHAT_YOU_USE ---------------------------------- +----------------------- .. versionadded:: 3.7 diff --git a/Help/variable/CMAKE_LINK_WHAT_YOU_USE_CHECK.rst b/Help/variable/CMAKE_LINK_WHAT_YOU_USE_CHECK.rst new file mode 100644 index 0000000..e626641 --- /dev/null +++ b/Help/variable/CMAKE_LINK_WHAT_YOU_USE_CHECK.rst @@ -0,0 +1,10 @@ +CMAKE_LINK_WHAT_YOU_USE_CHECK +----------------------------- + +.. versionadded:: 3.22 + +Defines the command executed after the link step to check libraries usage. +This check is currently only defined on ``ELF`` platforms with value +``ldd -u -r``. + +See also :variable:`CMAKE_<LANG>_LINK_WHAT_YOU_USE_FLAG` variables. diff --git a/Help/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.rst b/Help/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.rst new file mode 100644 index 0000000..893f1ae --- /dev/null +++ b/Help/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.rst @@ -0,0 +1,14 @@ +CMAKE_REQUIRE_FIND_PACKAGE_<PackageName> +---------------------------------------- + +.. versionadded:: 3.22 + +Variable for making :command:`find_package` call ``REQUIRED``. + +Every non-``REQUIRED`` :command:`find_package` call in a project can be +turned into ``REQUIRED`` by setting the variable +``CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>`` to ``TRUE``. +This can be used to assert assumptions about build environment and to +ensure the build will fail early if they do not hold. + +See also the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable. |