diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/add_custom_command.rst | 3 | ||||
| -rw-r--r-- | Help/command/add_custom_target.rst | 3 | ||||
| -rw-r--r-- | Help/command/file.rst | 63 | ||||
| -rw-r--r-- | Help/dev/source.rst | 144 | ||||
| -rw-r--r-- | Help/manual/cmake-properties.7.rst | 6 | ||||
| -rw-r--r-- | Help/manual/cmake-variables.7.rst | 2 | ||||
| -rw-r--r-- | Help/manual/cmake.1.rst | 14 | ||||
| -rw-r--r-- | Help/prop_sf/GENERATED.rst | 33 | ||||
| -rw-r--r-- | Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst | 2 | ||||
| -rw-r--r-- | Help/prop_tgt/MACHO_COMPATIBILITY_VERSION.rst | 14 | ||||
| -rw-r--r-- | Help/prop_tgt/MACHO_CURRENT_VERSION.rst | 13 | ||||
| -rw-r--r-- | Help/prop_tgt/OSX_COMPATIBILITY_VERSION.rst | 14 | ||||
| -rw-r--r-- | Help/prop_tgt/OSX_CURRENT_VERSION.rst | 13 | ||||
| -rw-r--r-- | Help/prop_tgt/SOVERSION.rst | 4 | ||||
| -rw-r--r-- | Help/prop_tgt/VERSION.rst | 4 | ||||
| -rw-r--r-- | Help/release/3.17.rst | 45 | ||||
| -rw-r--r-- | Help/release/dev/FindRuby-variable-case.rst | 7 | ||||
| -rw-r--r-- | Help/release/dev/GoogleTest-XML_OUTPUT_DIR.rst | 6 | ||||
| -rw-r--r-- | Help/release/dev/file_archive.rst | 7 | ||||
| -rw-r--r-- | Help/release/dev/profiling.rst | 9 |
20 files changed, 335 insertions, 71 deletions
diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index 69d6e9a..9279748 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -68,6 +68,9 @@ The options are: order-only dependencies to ensure the byproducts will be available before their dependents build. + The :ref:`Makefile Generators` will remove ``BYPRODUCTS`` and other + :prop_sf:`GENERATED` files during ``make clean``. + ``COMMAND`` Specify the command-line(s) to execute at build time. If more than one ``COMMAND`` is specified they will be executed in order, diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst index 2d5f5f0..56ab414 100644 --- a/Help/command/add_custom_target.rst +++ b/Help/command/add_custom_target.rst @@ -49,6 +49,9 @@ The options are: order-only dependencies to ensure the byproducts will be available before their dependents build. + The :ref:`Makefile Generators` will remove ``BYPRODUCTS`` and other + :prop_sf:`GENERATED` files during ``make clean``. + ``COMMAND`` Specify the command-line(s) to execute at build time. If more than one ``COMMAND`` is specified they will be executed in order, diff --git a/Help/command/file.rst b/Help/command/file.rst index 5a479d9..92cb2ed 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -42,6 +42,10 @@ Synopsis `Locking`_ file(`LOCK`_ <path> [...]) + `Archiving`_ + file(`ARCHIVE_CREATE`_ OUTPUT <archive> FILES <files> [...]) + file(`ARCHIVE_EXTRACT`_ INPUT <archive> DESTINATION <dir> [...]) + Reading ^^^^^^^ @@ -888,3 +892,62 @@ child directory or file. Trying to lock file twice is not allowed. Any intermediate directories and file itself will be created if they not exist. ``GUARD`` and ``TIMEOUT`` options ignored on ``RELEASE`` operation. + +Archiving +^^^^^^^^^ + +.. _ARCHIVE_CREATE: + +.. code-block:: cmake + + file(ARCHIVE_CREATE OUTPUT <archive> + [FILES <files>] + [DIRECTORY <dirs>] + [FORMAT <format>] + [TYPE <type>] + [MTIME <mtime>] + [VERBOSE]) + +Creates an archive specifed by ``OUTPUT`` with the content of ``FILES`` and +``DIRECTORY``. + +To specify the format of the archive set the ``FORMAT`` option. +Supported formats are: ``7zip``, ``gnutar``, ``pax``, ``paxr``, ``raw``, +(restricted pax, default), and ``zip``. + +To specify the type of compression set the ``TYPE`` option. +Supported compression types are: ``None``, ``BZip2``, ``GZip``, ``XZ``, +and ``Zstd``. + +.. note:: + With ``FORMAT`` set to ``raw`` only one file will be compressed with the + compression type specified by ``TYPE``. + +With ``VERBOSE`` the command will produce verbose output. + +To specify the modification time recorded in tarball entries use +the ``MTIME`` option. + +.. _ARCHIVE_EXTRACT: + +.. code-block:: cmake + + file(ARCHIVE_EXTRACT INPUT <archive> + [FILES <files>] + [DIRECTORY <dirs>] + [DESTINATION <dir>] + [LIST_ONLY] + [VERBOSE]) + +Extracts or lists the content of an archive specified by ``INPUT``. + +The directory where the content of the archive will be extracted can +be specified via ``DESTINATION``. If the directory does not exit, it +will be created. + +To select which files and directories will be extracted or listed +use ``FILES`` and ``DIRECTORY`` options. + +``LIST_ONLY`` will only list the files in the archive. + +With ``VERBOSE`` the command will produce verbose output. diff --git a/Help/dev/source.rst b/Help/dev/source.rst index 0f7488b..5371353 100644 --- a/Help/dev/source.rst +++ b/Help/dev/source.rst @@ -23,12 +23,142 @@ format only a subset of files, such as those that are locally modified. C++ Subset Permitted ==================== -CMake requires compiling as C++11 or above. However, in order to support -building on older toolchains some constructs need to be handled with care: +CMake requires compiling as C++11 in order to support building on older +toolchains. However, to facilitate development, some standard library +features from more recent C++ standards are supported through a compatibility +layer. These features are defined under the namespace ``cm`` and headers +are accessible under the ``cm/`` directory. The headers under ``cm/`` can +be used in place of the standard ones when extended features are needed. +For example ``<cm/memory>`` can be used in place of ``<memory>``. -* Do not use ``std::auto_ptr``. +Available features are: - The ``std::auto_ptr`` template is deprecated in C++11. Use ``std::unique_ptr``. +* From ``C++14``: + + * ``<cm/iterator>``: + ``cm::make_reverse_iterator``, ``cm::cbegin``, ``cm::cend``, + ``cm::rbegin``, ``cm::rend``, ``cm::crbegin``, ``cm::crend`` + + * ``<cm/memory>``: + ``cm::make_unique`` + + * ``<cm/shared_mutex>``: + ``cm::shared_lock`` + + * ``<cm/type_traits>``: + ``cm::enable_if_t`` + +* From ``C++17``: + + * ``<cm/algorithm>``: + ``cm::clamp`` + + * ``<cm/iterator>``: + ``cm::size``, ``cm::empty``, ``cm::data`` + + * ``<cm/optional>``: + ``cm::nullopt_t``, ``cm::nullopt``, ``cm::optional``, + ``cm::make_optional``, ``cm::bad_optional_access`` + + * ``<cm/shared_mutex>``: + ``cm::shared_mutex`` + + * ``<cm/string_view>``: + ``cm::string_view`` + + * ``<cm/type_traits>``: + ``cm::bool_constant``, ``cm::invoke_result_t``, ``cm::invoke_result``, + ``cm::void_t`` + + * ``<cm/utility>``: + ``cm::in_place_t``, ``cm::in_place`` + +* From ``C++20``: + + * ``<cm/deque>``: + ``cm::erase``, ``cm::erase_if`` + + * ``<cm/list>``: + ``cm::erase``, ``cm::erase_if`` + + * ``<cm/map>`` : + ``cm::erase_if`` + + * ``<cm/set>`` : + ``cm::erase_if`` + + * ``<cm/string>``: + ``cm::erase``, ``cm::erase_if`` + + * ``<cm/unordered_map>``: + ``cm::erase_if`` + + * ``<cm/unordered_set>``: + ``cm::erase_if`` + + * ``<cm/vector>``: + ``cm::erase``, ``cm::erase_if`` + +Additionally, some useful non-standard extensions to the C++ standard library +are available in headers under the directory ``cmext/`` in namespace ``cm``. +These are: + +* ``<cmext/algorithm>``: + + * ``cm::append``: + Append elements to a sequential container. + +* ``<cmext/iterator>``: + + * ``cm::is_terator``: + Checks if a type is an iterator type. + + * ``cm::is_input_iterator``: + Checks if a type is an input iterator type. + + * ``cm::is_range``: + Checks if a type is a range type: must have methods ``begin()`` and + ``end()`` returning an iterator. + + * ``cm::is_input_range``: + Checks if a type is an input range type: must have methods ``begin()`` and + ``end()`` returning an input iterator. + +* ``<cmext/memory>``: + + * ``cm::static_reference_cast``: + Apply a ``static_cast`` to a smart pointer. + + * ``cm::dynamic_reference_cast``: + Apply a ``dynamic_cast`` to a smart pointer. + +* ``<cmext/type_traits>``: + + * ``cm::is_container``: + Checks if a type is a container type. + + * ``cm::is_associative_container``: + Checks if a type is an associative container type. + + * ``cm::is_unordered_associative_container``: + Checks if a type is an unordered associative container type. + + * ``cm::is_sequence_container``: + Checks if a type is a sequence container type. + + * ``cm::is_unique_ptr``: + Checks if a type is a ``std::unique_ptr`` type. + +Dynamic Memory Management +========================= + +To ensure efficient memory management, i.e. no memory leaks, it is required +to use smart pointers. Any dynamic memory allocation must be handled by a +smart pointer such as ``std::unique_ptr`` or ``std::shared_ptr``. + +It is allowed to pass raw pointers between objects to enable objects sharing. +A raw pointer **must** not be deleted. Only the object(s) owning the smart +pointer are allowed to delete dynamically allocated memory. Source Tree Layout ================== @@ -69,6 +199,12 @@ The CMake source tree is organized as follows. * ``Utilities/``: Scripts, third-party source code. + * ``Utilities/std/cm``: + Support files for various C++ standards. + + * ``Utilities/std/cmext``: + Extensions to the C++ STL. + * ``Utilities/Sphinx/``: Sphinx configuration to build CMake user documentation. diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 15f0cfc..e552377 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -286,6 +286,8 @@ Properties on Targets /prop_tgt/LINK_WHAT_YOU_USE /prop_tgt/LOCATION_CONFIG /prop_tgt/LOCATION + /prop_tgt/MACHO_COMPATIBILITY_VERSION + /prop_tgt/MACHO_CURRENT_VERSION /prop_tgt/MACOSX_BUNDLE_INFO_PLIST /prop_tgt/MACOSX_BUNDLE /prop_tgt/MACOSX_FRAMEWORK_INFO_PLIST @@ -304,8 +306,6 @@ Properties on Targets /prop_tgt/OBJCXX_STANDARD_REQUIRED /prop_tgt/OSX_ARCHITECTURES_CONFIG /prop_tgt/OSX_ARCHITECTURES - /prop_tgt/OSX_CURRENT_VERSION - /prop_tgt/OSX_COMPATIBILITY_VERSION /prop_tgt/OUTPUT_NAME_CONFIG /prop_tgt/OUTPUT_NAME /prop_tgt/PDB_NAME_CONFIG @@ -391,7 +391,6 @@ Properties on Targets /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN /prop_tgt/XCODE_SCHEME_ARGUMENTS - /prop_tgt/XCODE_SCHEME_WORKING_DIRECTORY /prop_tgt/XCODE_SCHEME_DEBUG_AS_ROOT /prop_tgt/XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING /prop_tgt/XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER @@ -408,6 +407,7 @@ Properties on Targets /prop_tgt/XCODE_SCHEME_THREAD_SANITIZER_STOP /prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER /prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP + /prop_tgt/XCODE_SCHEME_WORKING_DIRECTORY /prop_tgt/XCODE_SCHEME_ZOMBIE_OBJECTS /prop_tgt/XCTEST diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 7696fd9..c271024 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -247,7 +247,6 @@ Variables that Change Behavior /variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN - /variable/CMAKE_XCODE_SCHEME_WORKING_DIRECTORY /variable/CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING /variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS @@ -262,6 +261,7 @@ Variables that Change Behavior /variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP /variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER /variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP + /variable/CMAKE_XCODE_SCHEME_WORKING_DIRECTORY /variable/CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS /variable/PackageName_ROOT diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 44b1f2f..429cba4 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -356,6 +356,20 @@ Options in :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR`. This flag tells CMake to warn about other files as well. +``--profiling-output=<path>`` + Used in conjuction with ``--profiling-format`` to output to a given path. + +``--profiling-format=<file>`` + Enable the output of profiling data of CMake script in the given format. + + This can aid performance analysis of CMake scripts executed. Third party + applications should be used to process the output into human readable format. + + Currently supported values are: + ``google-trace`` Outputs in Google Trace Format, which can be parsed by the + about:tracing tab of Google Chrome or using a plugin for a tool like Trace + Compass. + .. _`Build Tool Mode`: Build a Project diff --git a/Help/prop_sf/GENERATED.rst b/Help/prop_sf/GENERATED.rst index d430ee2..48ff70c 100644 --- a/Help/prop_sf/GENERATED.rst +++ b/Help/prop_sf/GENERATED.rst @@ -4,16 +4,29 @@ GENERATED Is this source file generated as part of the build or CMake process. Tells the internal CMake engine that a source file is generated by an outside -process such as another build step, or the execution of CMake itself. This -information is then used to exempt the file from any existence or validity -checks. Generated files are created by the execution of commands such as -:command:`add_custom_command` and :command:`file(GENERATE)`. - -When a generated file created by an :command:`add_custom_command` command -is explicitly listed as a source file for any target in the same -directory scope (which usually means the same ``CMakeLists.txt`` file), -CMake will automatically create a dependency to make sure the file is -generated before building that target. +process such as another build step, or the execution of CMake itself. +This information is then used to exempt the file from any existence or +validity checks. + +Any file that is + +- created by the execution of commands such as + :command:`add_custom_command` and :command:`file(GENERATE)` +- listed as one of the ``BYPRODUCTS`` of an :command:`add_custom_command` + or :command:`add_custom_target` command, or +- created by a CMake ``AUTOGEN`` operation such as :prop_tgt:`AUTOMOC`, + :prop_tgt:`AUTORCC`, or :prop_tgt:`AUTOUIC` + +will be marked with the ``GENERATED`` property. + +When a generated file created as the ``OUTPUT`` of an +:command:`add_custom_command` command is explicitly listed as a source file +for any target in the same directory scope (which usually means the same +``CMakeLists.txt`` file), CMake will automatically create a dependency to +make sure the file is generated before building that target. + +The :ref:`Makefile Generators` will remove ``GENERATED`` files during +``make clean``. Generated sources may be hidden in some IDE tools, while in others they might be shown. For the special case of sources generated by CMake's :prop_tgt:`AUTOMOC` diff --git a/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst index d5c5e14..92b52a3 100644 --- a/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst +++ b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst @@ -33,4 +33,4 @@ If :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` depends on a file that is either :prop_sf:`SKIP_AUTOUIC`, :prop_sf:`SKIP_AUTOGEN` or :policy:`CMP0071` or - a file that isn't in the origin target's sources -it must added to :prop_tgt:`AUTOGEN_TARGET_DEPENDS`. +it must be added to :prop_tgt:`AUTOGEN_TARGET_DEPENDS`. diff --git a/Help/prop_tgt/MACHO_COMPATIBILITY_VERSION.rst b/Help/prop_tgt/MACHO_COMPATIBILITY_VERSION.rst new file mode 100644 index 0000000..f3fedba --- /dev/null +++ b/Help/prop_tgt/MACHO_COMPATIBILITY_VERSION.rst @@ -0,0 +1,14 @@ +MACHO_COMPATIBILITY_VERSION +--------------------------- + +What compatibility version number is this target for Mach-O binaries. + +For shared libraries on Mach-O systems (e.g. macOS, iOS) +the ``MACHO_COMPATIBILITY_VERSION`` property correspond to +``compatibility version`` and :prop_tgt:`MACHO_CURRENT_VERSION` to +``current version``. +See the :prop_tgt:`FRAMEWORK` target property for an example. + +Versions of Mach-O binaries may be checked with the ``otool -L <binary>`` +command. If ``MACHO_COMPATIBILITY_VERSION`` is not set, the value of +the :prop_tgt:`SOVERSION` property will be used. diff --git a/Help/prop_tgt/MACHO_CURRENT_VERSION.rst b/Help/prop_tgt/MACHO_CURRENT_VERSION.rst new file mode 100644 index 0000000..4a1d3f0 --- /dev/null +++ b/Help/prop_tgt/MACHO_CURRENT_VERSION.rst @@ -0,0 +1,13 @@ +MACHO_CURRENT_VERSION +--------------------- + +What current version number is this target for Mach-O binaries. + +For shared libraries on Mach-O systems (e.g. macOS, iOS) +the :prop_tgt:`MACHO_COMPATIBILITY_VERSION` property correspond to +``compatibility version`` and ``MACHO_CURRENT_VERSION`` to ``current version``. +See the :prop_tgt:`FRAMEWORK` target property for an example. + +Versions of Mach-O binaries may be checked with the ``otool -L <binary>`` +command. If ``MACHO_CURRENT_VERSION`` is not set, the value of +the :prop_tgt:`VERSION` property will be used. diff --git a/Help/prop_tgt/OSX_COMPATIBILITY_VERSION.rst b/Help/prop_tgt/OSX_COMPATIBILITY_VERSION.rst deleted file mode 100644 index 5432b9a7..0000000 --- a/Help/prop_tgt/OSX_COMPATIBILITY_VERSION.rst +++ /dev/null @@ -1,14 +0,0 @@ -OSX_COMPATIBILITY_VERSION -------------------------- - -What compatibility version number is this target for OSX. - -For shared libraries on Mach-O systems (e.g. macOS, iOS) -the ``OSX_COMPATIBILITY_VERSION`` property correspond to -``compatibility version`` and :prop_tgt:`OSX_CURRENT_VERSION` to -``current version``. -See the :prop_tgt:`FRAMEWORK` target property for an example. - -Versions of Mach-O binaries may be checked with the ``otool -L <binary>`` -command. If ``OSX_COMPATIBILITY_VERSION`` is not set, the value of -the :prop_tgt:``SOVERSION`` property will be used. diff --git a/Help/prop_tgt/OSX_CURRENT_VERSION.rst b/Help/prop_tgt/OSX_CURRENT_VERSION.rst deleted file mode 100644 index 609924d..0000000 --- a/Help/prop_tgt/OSX_CURRENT_VERSION.rst +++ /dev/null @@ -1,13 +0,0 @@ -OSX_CURRENT_VERSION -------------------- - -What current version number is this target for OSX. - -For shared libraries on Mach-O systems (e.g. macOS, iOS) -the :prop_tgt:`OSX_COMPATIBILITY_VERSION` property correspond to -``compatibility version`` and ``OSX_CURRENT_VERSION`` to ``current version``. -See the :prop_tgt:`FRAMEWORK` target property for an example. - -Versions of Mach-O binaries may be checked with the ``otool -L <binary>`` -command. If ``OSX_CURRENT_VERSION`` is not set, the value of -the :prop_tgt:``VERSION`` property will be used. diff --git a/Help/prop_tgt/SOVERSION.rst b/Help/prop_tgt/SOVERSION.rst index 1a66c8f..d6f8a94 100644 --- a/Help/prop_tgt/SOVERSION.rst +++ b/Help/prop_tgt/SOVERSION.rst @@ -22,8 +22,8 @@ Mach-O Versions For shared libraries and executables on Mach-O systems (e.g. macOS, iOS), the ``SOVERSION`` property is a fallback to -:prop_tgt:`OSX_COMPATIBILITY_VERSION` property which corresponds to +:prop_tgt:`MACHO_COMPATIBILITY_VERSION` property which corresponds to *compatiblity version* and :prop_tgt:`VERSION` is a fallback to -:prop_tgt:`OSX_CURRENT_VERSION` which corresponds to *current version*. +:prop_tgt:`MACHO_CURRENT_VERSION` which corresponds to *current version*. See the :prop_tgt:`FRAMEWORK` target property for an example. Versions of Mach-O binaries may be checked with the ``otool -L <binary>`` command. diff --git a/Help/prop_tgt/VERSION.rst b/Help/prop_tgt/VERSION.rst index a24b613..f592f4a 100644 --- a/Help/prop_tgt/VERSION.rst +++ b/Help/prop_tgt/VERSION.rst @@ -23,9 +23,9 @@ Mach-O Versions ^^^^^^^^^^^^^^^ For shared libraries and executables on Mach-O systems (e.g. macOS, iOS), -the ``VERSION`` property is a fallback to :prop_tgt:`OSX_CURRENT_VERSION` +the ``VERSION`` property is a fallback to :prop_tgt:`MACHO_CURRENT_VERSION` property which corresponds to *current version* and :prop_tgt:`SOVERSION` -is a fallback to :prop_tgt:`OSX_COMPATIBILITY_VERSION` which corresponds +is a fallback to :prop_tgt:`MACHO_COMPATIBILITY_VERSION` which corresponds to *compatiblity version*. See the :prop_tgt:`FRAMEWORK` target property for an example. Versions of Mach-O binaries may be checked with the ``otool -L <binary>`` command. diff --git a/Help/release/3.17.rst b/Help/release/3.17.rst index 23dec84..c2cfdf0 100644 --- a/Help/release/3.17.rst +++ b/Help/release/3.17.rst @@ -47,12 +47,12 @@ Command-Line ------------ * :manual:`cmake(1)` gained a ``--debug-find`` command-line option to - enable additional human-readable output on where find commands search. + enable additional human-readable output on where ``find_*`` commands search. * :manual:`cmake(1)` gained a ``--trace-format`` command-line option that can be used to set the ``--trace`` output format. Currently, the old human readable and the new JSON format are supported. The new JSON format - is easier to parse automatically, than the existing format. + is easier to parse automatically than the existing format. * :manual:`cmake(1)` gained a ``-E rm`` command-line tool that can be used to remove directories and files. This supersedes the existing @@ -65,7 +65,7 @@ Commands ``DEPENDS`` arguments that are specified relative to the current binary directory. -* The :command:`foreach` learned a new option ``ZIP_LISTS`` to iterate +* The :command:`foreach` command learned a new ``ZIP_LISTS`` option to iterate over multiple lists simultaneously. * The :command:`load_cache(READ_WITH_PREFIX)` command mode is now allowed @@ -79,7 +79,7 @@ Commands * The :command:`message` command gained new keywords ``CHECK_START``, ``CHECK_PASS`` and ``CHECK_FAIL``. -* :command:`target_compile_options` command now honors the ``BEFORE`` +* The :command:`target_compile_options` command now honors the ``BEFORE`` keyword more consistently. See policy :policy:`CMP0101`. Variables @@ -102,7 +102,7 @@ Variables use CUDA. * The :variable:`CMAKE_FIND_DEBUG_MODE` variable was introduced to - print extra find call information during the cmake run to standard + print extra ``find_*`` call information during the cmake run to standard error. Output is designed for human consumption and not for parsing. * The :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` variable now takes its @@ -117,17 +117,20 @@ Variables to persist a log level between CMake runs, unlike the ``--log-level`` command line option which only applies to that particular run. -* The :variable:`CMAKE_XCODE_SCHEME_ENVIRONMENT` variable and - :prop_tgt:`XCODE_SCHEME_ENVIRONMENT` target property were added to - tell the :generator:`Xcode` generator to set the value of the - ``Custom Working Directory`` schema option. +* The :variable:`CMAKE_XCODE_SCHEME_ENVIRONMENT` variable was added + to initialize the :prop_tgt:`XCODE_SCHEME_ENVIRONMENT` target property. + +* The :variable:`CMAKE_XCODE_SCHEME_WORKING_DIRECTORY` variable and + associated :prop_tgt:`XCODE_SCHEME_WORKING_DIRECTORY` target property + were added to tell the :generator:`Xcode` generator to set the value of + the ``Custom Working Directory`` schema option. Properties ---------- * The :prop_tgt:`AIX_EXPORT_ALL_SYMBOLS` target property and associated :variable:`CMAKE_AIX_EXPORT_ALL_SYMBOLS` variable were created to - optionally explicitly disbale automatic export of symbols from shared + optionally explicitly disable automatic export of symbols from shared libraries on AIX. * The :prop_tgt:`DEPRECATION` target property was added to mark @@ -140,10 +143,10 @@ Properties In particular, the ``$<INSTALL_PREFIX>`` generator expression can be used to set the directory relative to the install-time prefix. -* Target properties :prop_tgt:`OSX_COMPATIBILITY_VERSION` and - :prop_tgt:`OSX_CURRENT_VERSION` were added to set the - ``compatibility_version`` and ``curent_version`` respectively - on macOS. For backwards compatibility, if these properties +* Target properties :prop_tgt:`MACHO_COMPATIBILITY_VERSION` and + :prop_tgt:`MACHO_CURRENT_VERSION` were added to set the + ``compatibility_version`` and ``curent_version``, respectively, + for Mach-O binaries. For backwards compatibility, if these properties are not set, :prop_tgt:`SOVERSION` and :prop_tgt:`VERSION` are used respectively as fallbacks. @@ -180,11 +183,11 @@ Modules * The :module:`FindPython3` and :module:`FindPython` modules gained, respectively, variable ``Python3_SOABI`` and ``Python_SOABI`` giving the standard extension suffix for modules. Moreover, commands - ``Python3_add_library`` and ``Python_add_library`` gained the option + ``Python3_add_library()`` and ``Python_add_library()`` gained the option ``WITH_SOABI`` to prefix the library suffix with the value of ``SOABI``. * The :module:`FindLibXml2` module now provides an imported target for the - ``xmllint`` executable + ``xmllint`` executable. Autogen ------- @@ -198,7 +201,7 @@ CTest * The :variable:`CTEST_CONFIGURATION_TYPE` variable is now set from the command line when :manual:`ctest(1)` is invoked with ``-C <cfg>``. -* The :manual:`ctest(1)` gained support for Dr. Memory to run +* The :manual:`ctest(1)` tool gained support for Dr. Memory to run memcheck runs. * The :manual:`ctest(1)` tool gained a ``--no-tests=<[error|ignore]>`` option @@ -246,9 +249,9 @@ CPack :variable:`CPACK_NSIS_FINISH_TITLE_3LINES`. These can be used to specify the finish page title and display it in 3 lines. -* The :cpack_gen:`CPack productbuild Generator` gained option - :variable:`CPACK_PRODUCTBUILD_BACKGROUND` to specify a background image - for the macOS installer. +* The :cpack_gen:`CPack productbuild Generator` gained support for a + :variable:`CPACK_PRODUCTBUILD_BACKGROUND` variable to specify a background + image for the macOS installer. Other ----- @@ -293,7 +296,7 @@ Other Changes See policy :policy:`CMP0099`. * When using MinGW tools, the :command:`find_library` command no longer - finds ``.dll`` files by default. Instead it expects ``.dll.a`` import + finds ``.dll`` files by default. Instead, it expects ``.dll.a`` import libraries to be available. * The :generator:`MinGW Makefiles` generator no longer issues an error if diff --git a/Help/release/dev/FindRuby-variable-case.rst b/Help/release/dev/FindRuby-variable-case.rst new file mode 100644 index 0000000..bd4a2f1 --- /dev/null +++ b/Help/release/dev/FindRuby-variable-case.rst @@ -0,0 +1,7 @@ +FindRuby-variable-case +---------------------- + +* The :module:`FindRuby` module input and output variables were all renamed + from ``RUBY_`` to ``Ruby_`` for consistency with other find modules. + Input variables of the old case will be honored if provided, and output + variables of the old case are always provided. diff --git a/Help/release/dev/GoogleTest-XML_OUTPUT_DIR.rst b/Help/release/dev/GoogleTest-XML_OUTPUT_DIR.rst new file mode 100644 index 0000000..ee29e60 --- /dev/null +++ b/Help/release/dev/GoogleTest-XML_OUTPUT_DIR.rst @@ -0,0 +1,6 @@ +GoogleTest-XML_OUTPUT_DIR +------------------------- + +* The :module:`GoogleTest` module ``gtest_discover_test`` command + gained a new optional parameter ``XML_OUTPUT_DIR``. When set the JUnit XML + test results are stored in that directory. diff --git a/Help/release/dev/file_archive.rst b/Help/release/dev/file_archive.rst new file mode 100644 index 0000000..e79529c --- /dev/null +++ b/Help/release/dev/file_archive.rst @@ -0,0 +1,7 @@ +file_archive +------------ + +* The :command:`file` command gained the ``ARCHIVE_{CREATE|EXTRACT}`` subcommands. + + These subcommands will replicate the :manual:`cmake(1)` ``-E tar`` functionality in + CMake scripting code. diff --git a/Help/release/dev/profiling.rst b/Help/release/dev/profiling.rst new file mode 100644 index 0000000..ab180f0 --- /dev/null +++ b/Help/release/dev/profiling.rst @@ -0,0 +1,9 @@ +cmake-profiling +--------------- + +* Add support for profiling of CMake scripts through the parameters + ``--profiling-output`` and ``--profiling-format``. These options can + be used by users to gain insight into the performance of their scripts. + + The first supported output format is ``google-trace`` which is a format + supported by Google Chrome's ``about:tracing`` tab. |