diff options
Diffstat (limited to 'Help')
24 files changed, 181 insertions, 41 deletions
diff --git a/Help/command/add_test.rst b/Help/command/add_test.rst index 884b2ee..a77ba37 100644 --- a/Help/command/add_test.rst +++ b/Help/command/add_test.rst @@ -38,8 +38,9 @@ The given test command is expected to exit with code ``0`` to pass and non-zero to fail, or vice-versa if the :prop_test:`WILL_FAIL` test property is set. Any output written to stdout or stderr will be captured by :manual:`ctest(1)` but does not affect the pass/fail status -unless the :prop_test:`PASS_REGULAR_EXPRESSION` or -:prop_test:`FAIL_REGULAR_EXPRESSION` test property is used. +unless the :prop_test:`PASS_REGULAR_EXPRESSION`, +:prop_test:`FAIL_REGULAR_EXPRESSION` or +:prop_test:`SKIP_REGULAR_EXPRESSION` test property is used. The ``COMMAND`` and ``WORKING_DIRECTORY`` options may use "generator expressions" with the syntax ``$<...>``. See the diff --git a/Help/command/install.rst b/Help/command/install.rst index ab6fef6..5affc5b 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -126,6 +126,8 @@ project. There are several kinds of target files that may be installed: marked with the ``FRAMEWORK`` property on macOS (see ``FRAMEWORK`` below.) For DLL platforms (all Windows-based systems including Cygwin), the DLL import library is treated as an ``ARCHIVE`` target. + On AIX, the linker import file created for executables with + :prop_tgt:`ENABLE_EXPORTS` is treated as an ``ARCHIVE`` target. ``LIBRARY`` Module libraries are always treated as ``LIBRARY`` targets. For non- diff --git a/Help/command/message.rst b/Help/command/message.rst index 5dca6b4..3002842 100644 --- a/Help/command/message.rst +++ b/Help/command/message.rst @@ -60,6 +60,11 @@ messages one at a time on a status line and other messages in an interactive pop-up box. The ``--loglevel`` command-line option to each of these tools can be used to control which messages will be shown. +Messages of log levels ``NOTICE`` and below will also have each line preceded +by the content of the :variable:`CMAKE_MESSAGE_INDENT` variable (converted to +a single string by concatenating its list items). For ``STATUS`` to ``TRACE`` +messages, this indenting content will be inserted after the hyphens. + CMake Warning and Error message text displays using a simple markup language. Non-indented text is formatted in line-wrapped paragraphs delimited by newlines. Indented text is considered pre-formatted. diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 8cd6e68..d8142a2 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -811,6 +811,10 @@ An *archive* output artifact of a buildsystem target may be: executable target created by the :command:`add_executable` command when its :prop_tgt:`ENABLE_EXPORTS` target property is set. +* On AIX: the linker import file (e.g. ``.imp``) of an executable target + created by the :command:`add_executable` command when its + :prop_tgt:`ENABLE_EXPORTS` target property is set. + The :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY` and :prop_tgt:`ARCHIVE_OUTPUT_NAME` target properties may be used to control archive output artifact locations and names in the build tree. diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index d7207e1..6bdabaf 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -57,6 +57,7 @@ Policies Introduced by CMake 3.16 .. toctree:: :maxdepth: 1 + CMP0096: project() preserves leading zeros in version components. </policy/CMP0096> CMP0095: RPATH entries are properly escaped in the intermediary CMake install script. </policy/CMP0095> Policies Introduced by CMake 3.15 diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 0beca82..ae4be3e 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -407,6 +407,7 @@ Properties on Tests /prop_test/REQUIRED_FILES /prop_test/RESOURCE_LOCK /prop_test/RUN_SERIAL + /prop_test/SKIP_REGULAR_EXPRESSION /prop_test/SKIP_RETURN_CODE /prop_test/TIMEOUT /prop_test/TIMEOUT_AFTER_MATCH diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index e0ce6f7..c3f6f8a 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -69,6 +69,7 @@ Variables that Provide Information /variable/CMAKE_MAKE_PROGRAM /variable/CMAKE_MATCH_COUNT /variable/CMAKE_MATCH_n + /variable/CMAKE_MESSAGE_INDENT /variable/CMAKE_MINIMUM_REQUIRED_VERSION /variable/CMAKE_MINOR_VERSION /variable/CMAKE_NETRC @@ -609,7 +610,6 @@ Variables for CPack /variable/CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION /variable/CPACK_INCLUDE_TOPLEVEL_DIRECTORY /variable/CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS - /variable/CPACK_INSTALL_SCRIPT /variable/CPACK_PACKAGING_INSTALL_PREFIX /variable/CPACK_SET_DESTDIR /variable/CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION diff --git a/Help/policy/CMP0091.rst b/Help/policy/CMP0091.rst index 5b7c4e3..1a5878a 100644 --- a/Help/policy/CMP0091.rst +++ b/Help/policy/CMP0091.rst @@ -20,7 +20,9 @@ CMake 3.15 and above prefer to leave the MSVC runtime library selection flags out of the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` values and instead offer a first-class abstraction. The :variable:`CMAKE_MSVC_RUNTIME_LIBRARY` variable and :prop_tgt:`MSVC_RUNTIME_LIBRARY` target property may be set to -select the MSVC runtime library. +select the MSVC runtime library. If they are not set then CMake uses the +default value ``MultiThreaded$<$<CONFIG:Debug>:Debug>DLL`` which is +equivalent to the original flags. This policy provides compatibility with projects that have not been updated to be aware of the abstraction. The policy setting takes effect as of the diff --git a/Help/policy/CMP0096.rst b/Help/policy/CMP0096.rst new file mode 100644 index 0000000..8eaf0f9 --- /dev/null +++ b/Help/policy/CMP0096.rst @@ -0,0 +1,25 @@ +CMP0096 +------- + +The :command:`project` command preserves leading zeros in version components. + +When a ``VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]`` argument is given +to the :command:`project` command, it stores the version string in the +``PROJECT_VERSION`` variable and stores individual integer version components +in ``PROJECT_VERSION_{MAJOR,MINOR,PATCH,TWEAK}`` variables (see policy +:policy:`CMP0048`). CMake 3.15 and below dropped leading zeros from each +component. CMake 3.16 and higher prefer to preserve leading zeros. This +policy provides compatibility for projects that have not been updated to +expect the new behavior. + +The ``OLD`` behavior of this policy drops leading zeros in all components, +e.g. such that version ``1.07.06`` becomes ``1.7.6``. The ``NEW`` behavior +of this policy preserves the leading zeros in all components, such that +version ``1.07.06`` remains unchanged. + +This policy was introduced in CMake version 3.16. Unlike many policies, CMake +version |release| does *not* warn when this policy is not set and simply uses +the ``OLD`` behavior. Use the :command:`cmake_policy` command to set it to +``OLD`` or ``NEW`` explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/prop_test/SKIP_REGULAR_EXPRESSION.rst b/Help/prop_test/SKIP_REGULAR_EXPRESSION.rst new file mode 100644 index 0000000..2c6d980 --- /dev/null +++ b/Help/prop_test/SKIP_REGULAR_EXPRESSION.rst @@ -0,0 +1,17 @@ +SKIP_REGULAR_EXPRESSION +----------------------- + +If the output matches this regular expression the test will be marked as skipped. + +If set, if the output matches one of specified regular expressions, +the test will be marked as skipped. Example: + +.. code-block:: cmake + + set_property(TEST mytest PROPERTY + SKIP_REGULAR_EXPRESSION "[^a-z]Skip" "SKIP" "Skipped" + ) + +``SKIP_REGULAR_EXPRESSION`` expects a list of regular expressions. + +See also the :prop_test:`SKIP_RETURN_CODE` property. diff --git a/Help/prop_test/SKIP_RETURN_CODE.rst b/Help/prop_test/SKIP_RETURN_CODE.rst index 3d48c2f..23c4c62 100644 --- a/Help/prop_test/SKIP_RETURN_CODE.rst +++ b/Help/prop_test/SKIP_RETURN_CODE.rst @@ -8,3 +8,5 @@ test are met. If such a situation should not be considered a hard failure a return code of the process can be specified that will mark the test as ``Not Run`` if it is encountered. Valid values are in the range of 0 to 255, inclusive. + +See also the :prop_test:`SKIP_REGULAR_EXPRESSION` property. diff --git a/Help/prop_tgt/ENABLE_EXPORTS.rst b/Help/prop_tgt/ENABLE_EXPORTS.rst index 581c2b9..0b1064a 100644 --- a/Help/prop_tgt/ENABLE_EXPORTS.rst +++ b/Help/prop_tgt/ENABLE_EXPORTS.rst @@ -7,16 +7,25 @@ Normally an executable does not export any symbols because it is the final program. It is possible for an executable to export symbols to be used by loadable modules. When this property is set to true CMake will allow other targets to "link" to the executable with the -:command:`TARGET_LINK_LIBRARIES` command. On all platforms a target-level +:command:`target_link_libraries` command. On all platforms a target-level dependency on the executable is created for targets that link to it. -For DLL platforms an import library will be created for the exported -symbols and then used for linking. All Windows-based systems -including Cygwin are DLL platforms. For non-DLL platforms that -require all symbols to be resolved at link time, such as macOS, the -module will "link" to the executable using a flag like -``-bundle_loader``. For other non-DLL platforms the link rule is simply -ignored since the dynamic loader will automatically bind symbols when -the module is loaded. +Handling of the executable on the link lines of the loadable modules +varies by platform: + +* On Windows-based systems (including Cygwin) an "import library" is + created along with the executable to list the exported symbols. + Loadable modules link to the import library to get the symbols. + +* On macOS, loadable modules link to the executable itself using the + ``-bundle_loader`` flag. + +* On AIX, a linker "import file" is created along with the executable + to list the exported symbols for import when linking other targets. + Loadable modules link to the import file to get the symbols. + +* On other platforms, loadable modules are simply linked without + referencing the executable since the dynamic loader will + automatically bind symbols when the module is loaded. This property is initialized by the value of the variable :variable:`CMAKE_ENABLE_EXPORTS` if it is set when a target is created. diff --git a/Help/prop_tgt/IMPORTED_IMPLIB.rst b/Help/prop_tgt/IMPORTED_IMPLIB.rst index 77fb552..c8b6fde 100644 --- a/Help/prop_tgt/IMPORTED_IMPLIB.rst +++ b/Help/prop_tgt/IMPORTED_IMPLIB.rst @@ -3,5 +3,7 @@ IMPORTED_IMPLIB Full path to the import library for an ``IMPORTED`` target. -Set this to the location of the ``.lib`` part of a Windows DLL. Ignored -for non-imported targets. +Set this to the location of the ``.lib`` part of a Windows DLL, or on +AIX set it to an import file created for executables that export symbols +(see the :prop_tgt:`ENABLE_EXPORTS` target property). +Ignored for non-imported targets. diff --git a/Help/prop_tgt/MSVC_RUNTIME_LIBRARY.rst b/Help/prop_tgt/MSVC_RUNTIME_LIBRARY.rst index 1e3f5e9..73792de 100644 --- a/Help/prop_tgt/MSVC_RUNTIME_LIBRARY.rst +++ b/Help/prop_tgt/MSVC_RUNTIME_LIBRARY.rst @@ -19,6 +19,9 @@ support per-configuration specification. For example, the code: selects for the target ``foo`` a multi-threaded statically-linked runtime library with or without debug information depending on the configuration. +If this property is not set then CMake uses the default value +``MultiThreaded$<$<CONFIG:Debug>:Debug>DLL`` to select a MSVC runtime library. + .. note:: This property has effect only when policy :policy:`CMP0091` is set to ``NEW`` diff --git a/Help/release/dev/add_skip_regular_expression_test_property.rst b/Help/release/dev/add_skip_regular_expression_test_property.rst new file mode 100644 index 0000000..20ef214 --- /dev/null +++ b/Help/release/dev/add_skip_regular_expression_test_property.rst @@ -0,0 +1,10 @@ +add_skip_regular_expression_test_property +----------------------------------------- + +* A new test property, :prop_test:`SKIP_REGULAR_EXPRESSION`, has been added. + This property is similar to :prop_test:`FAIL_REGULAR_EXPRESSION` and + :prop_test:`PASS_REGULAR_EXPRESSION`, but with the same meaning as + :prop_test:`SKIP_RETURN_CODE`. This is useful, for example, in cases where + the user has no control over the return code of the test. For example, in + Catch2, the return value is the number of assertion failed, therefore it is + impossible to use it for :prop_test:`SKIP_RETURN_CODE`. diff --git a/Help/release/dev/aix.rst b/Help/release/dev/aix.rst new file mode 100644 index 0000000..6919358 --- /dev/null +++ b/Help/release/dev/aix.rst @@ -0,0 +1,20 @@ +aix +--- + +* On AIX, executables using the :prop_tgt:`ENABLE_EXPORTS` target property + now produce a linker import file with a ``.imp`` extension in addition + to the executable file. Plugins (created via :command:`add_library` with + the ``MODULE`` option) that use :command:`target_link_libraries` to link + to the executable for its symbols are now linked using the import file. + The :command:`install(TARGETS)` command now installs the import file as + an ``ARCHIVE`` artifact. + +* On AIX, runtime linking is no longer enabled by default. CMake provides + the linker enough information to resolve all symbols up front. + One may manually enable runtime linking for shared libraries and/or + loadable modules by adding ``-Wl,-G`` to their link flags + (e.g. in the :variable:`CMAKE_SHARED_LINKER_FLAGS` or + :variable:`CMAKE_MODULE_LINKER_FLAGS` variable). + One may manually enable runtime linking for executables by adding + ``-Wl,-brtl`` to their link flags (e.g. in the + :variable:`CMAKE_EXE_LINKER_FLAGS` variable). diff --git a/Help/release/dev/cmake-qch-no-version-in-filename.rst b/Help/release/dev/cmake-qch-no-version-in-filename.rst new file mode 100644 index 0000000..3c5cb04 --- /dev/null +++ b/Help/release/dev/cmake-qch-no-version-in-filename.rst @@ -0,0 +1,8 @@ +cmake-qch-no-version-in-filename +-------------------------------- + +* The Qt Compressed Help file is now named ``CMake.qch``, which no longer + contains the release version in the file name. When CMake is upgraded + in-place, the name and location of this file will remain constant. + Tools such as IDEs, help viewers, etc. should now be able to refer to this + file at a fixed location that remains valid across CMake upgrades. diff --git a/Help/release/dev/cpack-install-scripts.rst b/Help/release/dev/cpack-install-scripts.rst new file mode 100644 index 0000000..7b80d33 --- /dev/null +++ b/Help/release/dev/cpack-install-scripts.rst @@ -0,0 +1,5 @@ +cpack-install-scripts +--------------------- + +* The ``CPACK_INSTALL_SCRIPT`` variable has been deprecated in favor of the + new, more accurately named :variable:`CPACK_INSTALL_SCRIPTS` variable. diff --git a/Help/release/dev/message-indent.rst b/Help/release/dev/message-indent.rst new file mode 100644 index 0000000..b170708 --- /dev/null +++ b/Help/release/dev/message-indent.rst @@ -0,0 +1,5 @@ +message-indent +-------------- + +* The :command:`message` command learned indentation control with the new + :variable:`CMAKE_MESSAGE_INDENT` variable. diff --git a/Help/release/dev/project-version-0.rst b/Help/release/dev/project-version-0.rst new file mode 100644 index 0000000..6525522 --- /dev/null +++ b/Help/release/dev/project-version-0.rst @@ -0,0 +1,5 @@ +project-version-0 +----------------- + +* The :command:`project` no longer strips leading zeros in version components. + See policy :policy:`CMP0096`. diff --git a/Help/variable/CMAKE_ENABLE_EXPORTS.rst b/Help/variable/CMAKE_ENABLE_EXPORTS.rst index 7ec4d63..8848da1 100644 --- a/Help/variable/CMAKE_ENABLE_EXPORTS.rst +++ b/Help/variable/CMAKE_ENABLE_EXPORTS.rst @@ -1,22 +1,8 @@ CMAKE_ENABLE_EXPORTS -------------------- -Specify whether an executable exports symbols for loadable modules. +Specify whether executables export symbols for loadable modules. -Normally an executable does not export any symbols because it is the -final program. It is possible for an executable to export symbols to -be used by loadable modules. When this property is set to true CMake -will allow other targets to ``link`` to the executable with the -:command:`TARGET_LINK_LIBRARIES` command. On all platforms a target-level -dependency on the executable is created for targets that link to it. -For DLL platforms an import library will be created for the exported -symbols and then used for linking. All Windows-based systems -including Cygwin are DLL platforms. For non-DLL platforms that -require all symbols to be resolved at link time, such as macOS, the -module will ``link`` to the executable using a flag like -``-bundle_loader``. For other non-DLL platforms the link rule is simply -ignored since the dynamic loader will automatically bind symbols when -the module is loaded. - -This variable is used to initialize the target property -:prop_tgt:`ENABLE_EXPORTS` for executable targets. +This variable is used to initialize the :prop_tgt:`ENABLE_EXPORTS` target +property for executable targets when they are created by calls to the +:command:`add_executable` command. See the property documentation for details. diff --git a/Help/variable/CMAKE_MESSAGE_INDENT.rst b/Help/variable/CMAKE_MESSAGE_INDENT.rst new file mode 100644 index 0000000..f7975ab --- /dev/null +++ b/Help/variable/CMAKE_MESSAGE_INDENT.rst @@ -0,0 +1,30 @@ +CMAKE_MESSAGE_INDENT +-------------------- + +The :command:`message` command joins the strings from this list and for +log levels of ``NOTICE`` and below, it prepends the resultant string to +each line of the message. + +Example: + +.. code-block:: cmake + + list(APPEND listVar one two three) + + message(VERBOSE [[Collected items in the "listVar":]]) + list(APPEND CMAKE_MESSAGE_INDENT " ") + + foreach(item IN LISTS listVar) + message(VERBOSE ${item}) + endforeach() + + list(POP_BACK CMAKE_MESSAGE_INDENT) + message(VERBOSE "No more indent") + +Which results in the following output: + + -- Collected items in the "listVar": + -- one + -- two + -- tree + -- No more indent diff --git a/Help/variable/CMAKE_MSVC_RUNTIME_LIBRARY.rst b/Help/variable/CMAKE_MSVC_RUNTIME_LIBRARY.rst index 6ed68c9..8b54e7e 100644 --- a/Help/variable/CMAKE_MSVC_RUNTIME_LIBRARY.rst +++ b/Help/variable/CMAKE_MSVC_RUNTIME_LIBRARY.rst @@ -20,6 +20,11 @@ support per-configuration specification. For example, the code: selects for all following targets a multi-threaded statically-linked runtime library with or without debug information depending on the configuration. +If this variable is not set then the :prop_tgt:`MSVC_RUNTIME_LIBRARY` target +property will not be set automatically. If that property is not set then +CMake uses the default value ``MultiThreaded$<$<CONFIG:Debug>:Debug>DLL`` +to select a MSVC runtime library. + .. note:: This variable has effect only when policy :policy:`CMP0091` is set to ``NEW`` diff --git a/Help/variable/CPACK_INSTALL_SCRIPT.rst b/Help/variable/CPACK_INSTALL_SCRIPT.rst deleted file mode 100644 index 12a48a4..0000000 --- a/Help/variable/CPACK_INSTALL_SCRIPT.rst +++ /dev/null @@ -1,8 +0,0 @@ -CPACK_INSTALL_SCRIPT --------------------- - -Extra CMake script provided by the user. - -If set this CMake script will be executed by CPack during its local -[CPack-private] installation which is done right before packaging the -files. The script is not called by e.g.: ``make install``. |