diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/file.rst | 6 | ||||
| -rw-r--r-- | Help/command/install.rst | 54 | ||||
| -rw-r--r-- | Help/command/string.rst | 21 | ||||
| -rw-r--r-- | Help/cpack_gen/archive.rst | 47 | ||||
| -rw-r--r-- | Help/cpack_gen/ifw.rst | 117 | ||||
| -rw-r--r-- | Help/guide/tutorial/index.rst | 6 | ||||
| -rw-r--r-- | Help/manual/ctest.1.rst | 9 | ||||
| -rw-r--r-- | Help/release/dev/deprecate-policy-old.rst | 8 | ||||
| -rw-r--r-- | Help/release/dev/string-hex.rst | 5 |
9 files changed, 171 insertions, 102 deletions
diff --git a/Help/command/file.rst b/Help/command/file.rst index b186177..5877d43 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -54,7 +54,9 @@ Reading Read content from a file called ``<filename>`` and store it in a ``<variable>``. Optionally start from the given ``<offset>`` and read at most ``<max-in>`` bytes. The ``HEX`` option causes data to -be converted to a hexadecimal representation (useful for binary data). +be converted to a hexadecimal representation (useful for binary data). If the +``HEX`` option is specified, letters in the output (``a`` through ``f``) are in +lowercase. .. _STRINGS: @@ -540,7 +542,7 @@ are only traversed if ``FOLLOW_SYMLINKS`` is given or policy By default ``GLOB_RECURSE`` omits directories from result list - setting ``LIST_DIRECTORIES`` to true adds directories to result list. If ``FOLLOW_SYMLINKS`` is given or policy :policy:`CMP0009` is not set to -``OLD`` then ``LIST_DIRECTORIES`` treats symlinks as directories. +``NEW`` then ``LIST_DIRECTORIES`` treats symlinks as directories. Examples of recursive globbing include:: diff --git a/Help/command/install.rst b/Help/command/install.rst index 5affc5b..abf6b17 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -30,13 +30,20 @@ signatures that specify them. The common options are: ``DESTINATION`` Specify the directory on disk to which a file will be installed. - If a full path (with a leading slash or drive letter) is given - it is used directly. If a relative path is given it is interpreted - relative to the value of the :variable:`CMAKE_INSTALL_PREFIX` variable. + Arguments can be relative or absolute paths. + + If a relative path is given it is interpreted relative to the value + of the :variable:`CMAKE_INSTALL_PREFIX` variable. The prefix can be relocated at install time using the ``DESTDIR`` mechanism explained in the :variable:`CMAKE_INSTALL_PREFIX` variable documentation. + If an absolute path (with a leading slash or drive letter) is given + it is used verbatim. + + As absolute paths are not supported by :manual:`cpack <cpack(1)>` installer + generators, it is preferable to use relative paths throughout. + ``PERMISSIONS`` Specify permissions for installed files. Valid permissions are ``OWNER_READ``, ``OWNER_WRITE``, ``OWNER_EXECUTE``, ``GROUP_READ``, @@ -119,31 +126,38 @@ Installing Targets ) The ``TARGETS`` form specifies rules for installing targets from a -project. There are several kinds of target files that may be installed: +project. There are several kinds of target :ref:`Output Artifacts` +that may be installed: ``ARCHIVE`` - Static libraries are treated as ``ARCHIVE`` targets, except those - 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. + Target artifacts of this kind include: + + * *Static libraries* + (except on macOS when marked as ``FRAMEWORK``, see below); + * *DLL import libraries* + (on all Windows-based systems including Cygwin; they have extension + ``.lib``, in contrast to the ``.dll`` libraries that go to ``RUNTIME``); + * On AIX, the *linker import file* created for executables with + :prop_tgt:`ENABLE_EXPORTS` enabled. ``LIBRARY`` - Module libraries are always treated as ``LIBRARY`` targets. For non- - DLL platforms shared libraries are treated as ``LIBRARY`` targets, - except those marked with the ``FRAMEWORK`` property on macOS (see - ``FRAMEWORK`` below.) + Target artifacts of this kind include: + + * *Shared libraries*, except + + - DLLs (these go to ``RUNTIME``, see below), + - on macOS when marked as ``FRAMEWORK`` (see below). ``RUNTIME`` - Executables are treated as ``RUNTIME`` objects, except those marked - with the ``MACOSX_BUNDLE`` property on macOS (see ``BUNDLE`` below.) - For DLL platforms (all Windows-based systems including Cygwin), the - DLL part of a shared library is treated as a ``RUNTIME`` target. + Target artifacts of this kind include: + + * *Executables* + (except on macOS when marked as ``MACOSX_BUNDLE``, see ``BUNDLE`` below); + * DLLs (on all Windows-based systems including Cygwin; note that the + accompanying import libraries are of kind ``ARCHIVE``). ``OBJECTS`` - Object libraries (a simple group of object files) are always treated - as ``OBJECTS`` targets. + Object files associated with *object libraries*. ``FRAMEWORK`` Both static and shared libraries marked with the ``FRAMEWORK`` diff --git a/Help/command/string.rst b/Help/command/string.rst index 81a2061..cfcf914 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -11,8 +11,6 @@ Synopsis `Search and Replace`_ string(`FIND`_ <string> <substring> <out-var> [...]) string(`REPLACE`_ <match-string> <replace-string> <out-var> <input>...) - - `Regular Expressions`_ string(`REGEX MATCH`_ <match-regex> <out-var> <input>...) string(`REGEX MATCHALL`_ <match-regex> <out-var> <input>...) string(`REGEX REPLACE`_ <match-regex> <replace-expr> <out-var> <input>...) @@ -38,6 +36,7 @@ Synopsis `Generation`_ string(`ASCII`_ <number>... <out-var>) + string(`HEX`_ <string> <out-var>) string(`CONFIGURE`_ <string> <out-var> [...]) string(`MAKE_C_IDENTIFIER`_ <string> <out-var>) string(`RANDOM`_ [<option>...] <out-var>) @@ -47,6 +46,9 @@ Synopsis Search and Replace ^^^^^^^^^^^^^^^^^^ +Search and Replace With Plain Strings +""""""""""""""""""""""""""""""""""""" + .. _FIND: .. code-block:: cmake @@ -74,8 +76,8 @@ so strings containing multi-byte characters may lead to unexpected results. Replace all occurrences of ``<match_string>`` in the ``<input>`` with ``<replace_string>`` and store the result in the ``<output_variable>``. -Regular Expressions -^^^^^^^^^^^^^^^^^^^ +Search and Replace With Regular Expressions +""""""""""""""""""""""""""""""""""""""""""" .. _`REGEX MATCH`: @@ -87,6 +89,7 @@ Regular Expressions Match the ``<regular_expression>`` once and store the match in the ``<output_variable>``. All ``<input>`` arguments are concatenated before matching. +Regular expressions are specified in the subsection just below. .. _`REGEX MATCHALL`: @@ -353,6 +356,16 @@ Generation Convert all numbers into corresponding ASCII characters. +.. _HEX: + +.. code-block:: cmake + + string(HEX <string> <output_variable>) + +Convert each byte in the input ``<string>`` to its hexadecimal representation +and store the concatenated hex digits in the ``<output_variable>``. Letters in +the output (``a`` through ``f``) are in lowercase. + .. _CONFIGURE: .. code-block:: cmake diff --git a/Help/cpack_gen/archive.rst b/Help/cpack_gen/archive.rst index d455f4b..e9904ae 100644 --- a/Help/cpack_gen/archive.rst +++ b/Help/cpack_gen/archive.rst @@ -1,8 +1,8 @@ CPack Archive Generator ----------------------- -Archive CPack generator that supports packaging of sources and binaries in -different formats: +CPack generator for packaging files into an archive, which can have +any of the following formats: - 7Z - 7zip - (.7z) - TBZ2 (.tar.bz2) @@ -12,25 +12,42 @@ different formats: - TZST (.tar.zst) - ZIP (.zip) +When this generator is called from ``CPackSourceConfig.cmake`` (or through +the ``package_source`` target), then the generated archive will contain all +files in the project directory, except those specified in +:variable:`CPACK_SOURCE_IGNORE_FILES`. The following is one example of +packaging all source files of a project: + +.. code-block:: cmake + + set(CPACK_SOURCE_GENERATOR "TGZ") + set(CPACK_SOURCE_IGNORE_FILES + \\.git/ + build/ + ".*~$" + ) + set(CPACK_VERBATIM_VARIABLES YES) + include(CPack) + +When this generator is called from ``CPackConfig.cmake`` (or through the +``package`` target), then the generated archive will contain all files +that have been installed via CMake's :command:`install` command (and the +deprecated commands :command:`install_files`, :command:`install_programs`, +and :command:`install_targets`). + Variables specific to CPack Archive generator ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. variable:: CPACK_ARCHIVE_FILE_NAME CPACK_ARCHIVE_<component>_FILE_NAME - Package file name without extension which is added automatically depending - on the archive format. - - * Mandatory : YES - * Default : ``<CPACK_PACKAGE_FILE_NAME>[-<component>].<extension>`` with - spaces replaced by '-' + Package file name without extension. The extension is determined from the + archive format (see list above) and automatically appended to the file name. + The default is ``<CPACK_PACKAGE_FILE_NAME>[-<component>]``, with spaces + replaced by '-'. .. variable:: CPACK_ARCHIVE_COMPONENT_INSTALL - Enable component packaging for CPackArchive - - * Mandatory : NO - * Default : OFF - - If enabled (ON) multiple packages are generated. By default a single package - containing files of all components is generated. + Enable component packaging. If enabled (ON), then the archive generator + creates multiple packages. The default is OFF, which means that a single + package containing files of all components is generated. diff --git a/Help/cpack_gen/ifw.rst b/Help/cpack_gen/ifw.rst index feccd3d..d7c71b4 100644 --- a/Help/cpack_gen/ifw.rst +++ b/Help/cpack_gen/ifw.rst @@ -1,51 +1,28 @@ CPack IFW Generator ------------------- -See :module:`CPackIFW` for details on the CPackIFW module. +Configure and run the Qt Installer Framework to generate a Qt installer. -.. _QtIFW: http://doc.qt.io/qtinstallerframework/index.html +.. only:: html + .. contents:: Overview ^^^^^^^^ -CPack ``IFW`` generator helps you to create online and offline -binary cross-platform installers with a graphical user interface. +This :manual:`cpack generator <cpack-generators(7)>` generates +configuration and meta information for the `Qt Installer Framework +<http://doc.qt.io/qtinstallerframework/index.html>`_ (QtIFW), +and runs QtIFW tools to generate a Qt installer. -CPack IFW generator prepares project installation and generates configuration -and meta information for QtIFW_ tools. +QtIFW provides tools and utilities to create installers for +the platforms supported by `Qt <https://www.qt.io>`_: Linux, +Microsoft Windows, and macOS. -The QtIFW_ provides a set of tools and utilities to create -installers for the supported desktop Qt platforms: Linux, Microsoft Windows, -and macOS. - -You should also install QtIFW_ to use CPack ``IFW`` generator. - -Hints -^^^^^ - -Generally, the CPack ``IFW`` generator automatically finds QtIFW_ tools, -but if you don't use a default path for installation of the QtIFW_ tools, -the path may be specified in either a CMake or an environment variable: - -.. variable:: CPACK_IFW_ROOT - - An CMake variable which specifies the location of the QtIFW_ tool suite. - - The variable will be cached in the ``CPackConfig.cmake`` file and used at - CPack runtime. - -.. variable:: QTIFWDIR - - An environment variable which specifies the location of the QtIFW_ tool - suite. - -.. note:: - The specified path should not contain "bin" at the end - (for example: "D:\\DevTools\\QtIFW2.0.5"). - -The :variable:`CPACK_IFW_ROOT` variable has a higher priority and overrides -the value of the :variable:`QTIFWDIR` variable. +To make use of this generator, QtIFW needs to be installed. +The :module:`CPackIFW` module looks for the location of the +QtIFW command-line utilities, and defines several commands to +control the behavior of this generator. Internationalization ^^^^^^^^^^^^^^^^^^^^ @@ -53,7 +30,7 @@ Internationalization Some variables and command arguments support internationalization via CMake script. This is an optional feature. -Installers created by QtIFW_ tools have built-in support for +Installers created by QtIFW tools have built-in support for internationalization and many phrases are localized to many languages, but this does not apply to the description of the your components and groups that will be distributed. @@ -162,6 +139,8 @@ Package Default target directory for installation. By default used "@ApplicationsDir@/:variable:`CPACK_PACKAGE_INSTALL_DIRECTORY`" + (variables embedded in '@' are expanded by the + `QtIFW scripting engine <https://doc.qt.io/qtinstallerframework/scripting.html>`_). You can use predefined variables. @@ -185,7 +164,7 @@ Package Filename of the generated maintenance tool. The platform-specific executable file extension is appended. - By default used QtIFW_ defaults (``maintenancetool``). + By default used QtIFW defaults (``maintenancetool``). .. variable:: CPACK_IFW_PACKAGE_REMOVE_TARGET_DIR @@ -197,19 +176,19 @@ Package Filename for the configuration of the generated maintenance tool. - By default used QtIFW_ defaults (``maintenancetool.ini``). + By default used QtIFW defaults (``maintenancetool.ini``). .. variable:: CPACK_IFW_PACKAGE_ALLOW_NON_ASCII_CHARACTERS Set to ``ON`` if the installation path can contain non-ASCII characters. - Is ``ON`` for QtIFW_ less 2.0 tools. + Is ``ON`` for QtIFW less 2.0 tools. .. variable:: CPACK_IFW_PACKAGE_ALLOW_SPACE_IN_PATH Set to ``OFF`` if the installation path cannot contain space characters. - Is ``ON`` for QtIFW_ less 2.0 tools. + Is ``ON`` for QtIFW less 2.0 tools. .. variable:: CPACK_IFW_PACKAGE_CONTROL_SCRIPT @@ -266,38 +245,60 @@ Components Additional prepared repository dirs that will be used to resolve and repack dependent components. This feature available only - since QtIFW_ 3.1. + since QtIFW 3.1. -Tools -""""" +QtIFW Tools +""""""""""" .. variable:: CPACK_IFW_FRAMEWORK_VERSION - The version of used QtIFW_ tools. + The version of used QtIFW tools. -.. variable:: CPACK_IFW_BINARYCREATOR_EXECUTABLE +The following variables provide the locations of the QtIFW +command-line tools as discovered by the module :module:`CPackIFW`. +These variables are cached, and may be configured if needed. - The path to "binarycreator" command line client. +.. variable:: CPACK_IFW_BINARYCREATOR_EXECUTABLE - This variable is cached and may be configured if needed. + The path to ``binarycreator``. .. variable:: CPACK_IFW_REPOGEN_EXECUTABLE - The path to "repogen" command line client. - - This variable is cached and may be configured if needed. + The path to ``repogen``. .. variable:: CPACK_IFW_INSTALLERBASE_EXECUTABLE - The path to "installerbase" installer executable base. - - This variable is cached and may be configured if needed. + The path to ``installerbase``. .. variable:: CPACK_IFW_DEVTOOL_EXECUTABLE - The path to "devtool" command line client. + The path to ``devtool``. + +Hints for Finding QtIFW +""""""""""""""""""""""" + +Generally, the CPack ``IFW`` generator automatically finds QtIFW tools, +but if you don't use a default path for installation of the QtIFW tools, +the path may be specified in either a CMake or an environment variable: + +.. variable:: CPACK_IFW_ROOT + + An CMake variable which specifies the location of the QtIFW tool suite. + + The variable will be cached in the ``CPackConfig.cmake`` file and used at + CPack runtime. + +.. variable:: QTIFWDIR + + An environment variable which specifies the location of the QtIFW tool + suite. - This variable is cached and may be configured if needed. +.. note:: + The specified path should not contain "bin" at the end + (for example: "D:\\DevTools\\QtIFW2.0.5"). + +The :variable:`CPACK_IFW_ROOT` variable has a higher priority and overrides +the value of the :variable:`QTIFWDIR` variable. Online installer @@ -335,5 +336,5 @@ Qt Installer Framework Manual: * Promoting Updates: http://doc.qt.io/qtinstallerframework/ifw-updates.html -Download Qt Installer Framework for you platform from Qt site: +Download Qt Installer Framework for your platform from Qt site: http://download.qt.io/official_releases/qt-installer-framework diff --git a/Help/guide/tutorial/index.rst b/Help/guide/tutorial/index.rst index 96f0486..a844cbf 100644 --- a/Help/guide/tutorial/index.rst +++ b/Help/guide/tutorial/index.rst @@ -183,7 +183,7 @@ last few lines of the top-level ``CMakeLists.txt`` file should now look like: ) Now let us make the MathFunctions library optional. While for the tutorial -there really isn’t any need to do so, for larger projects this is a common +there really isn't any need to do so, for larger projects this is a common occurrence. The first step is to add an option to the top-level ``CMakeLists.txt`` file. @@ -918,8 +918,8 @@ subbdirectories. The layout will look like: .. code-block:: none - Step12 - └── debug - └── release + - debug + - release Now we need to setup debug and release builds. We can use :variable:`CMAKE_BUILD_TYPE` to set the configuration type: diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 2bfaafe..6503f0e 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -1331,6 +1331,15 @@ the running machine. This allows CTest to internally keep track of which resources are in use and which are free, scheduling tests in a way that prevents them from trying to claim resources that are not available. +When the resource allocation feature is used, CTest will not oversubscribe +resources. For example, if a resource has 8 slots, CTest will not run tests +that collectively use more than 8 slots at a time. This has the effect of +limiting how many tests can run at any given time, even if a high ``-j`` +argument is used, if those tests all use some slots from the same resource. +In addition, it means that a single test that uses more of a resource than is +available on a machine will not run at all (and will be reported as +``Not Run``). + A common use case for this feature is for tests that require the use of a GPU. Multiple tests can simultaneously allocate memory from a GPU, but if too many tests try to do this at once, some of them will fail to allocate, resulting in diff --git a/Help/release/dev/deprecate-policy-old.rst b/Help/release/dev/deprecate-policy-old.rst new file mode 100644 index 0000000..cffd206 --- /dev/null +++ b/Help/release/dev/deprecate-policy-old.rst @@ -0,0 +1,8 @@ +deprecate-policy-old +-------------------- + +* An explicit deprecation diagnostic was added for policy ``CMP0070`` + and policy ``CMP0071`` (``CMP0069`` and below were already deprecated). + The :manual:`cmake-policies(7)` manual explains that the OLD behaviors + of all policies are deprecated and that projects should port to the + NEW behaviors. diff --git a/Help/release/dev/string-hex.rst b/Help/release/dev/string-hex.rst new file mode 100644 index 0000000..f220aca --- /dev/null +++ b/Help/release/dev/string-hex.rst @@ -0,0 +1,5 @@ +string-hex +---------- + +* The :command:`string` command learned a new ``HEX`` sub-command, which + converts strings into their hexadecimal representation. |