diff options
Diffstat (limited to 'Help')
43 files changed, 926 insertions, 172 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index 42bf52b..cebe051 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -15,6 +15,7 @@ The general signature is: [PATHS path1 [path2 ... ENV var]] [PATH_SUFFIXES suffix1 [suffix2 ...]] [DOC "cache documentation string"] + [REQUIRED] [NO_DEFAULT_PATH] [NO_PACKAGE_ROOT_PATH] [NO_CMAKE_PATH] @@ -31,8 +32,9 @@ A cache entry named by ``<VAR>`` is created to store the result of this command. If the |SEARCH_XXX| is found the result is stored in the variable and the search will not be repeated unless the variable is cleared. -If nothing is found, the result will be -``<VAR>-NOTFOUND``, and the search will be attempted again the +If nothing is found, the result will be ``<VAR>-NOTFOUND``. +The ``REQUIRED`` option stops processing with an error message if nothing +is found, otherwise the search will be attempted again the next time |FIND_XXX| is invoked with the same variable. Options include: @@ -57,6 +59,9 @@ Options include: ``DOC`` Specify the documentation string for the ``<VAR>`` cache entry. +``REQUIRED`` + Stop processing with an error message if nothing is found. + If ``NO_DEFAULT_PATH`` is specified, then no additional paths are added to the search. If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: diff --git a/Help/command/cmake_command.rst b/Help/command/cmake_command.rst new file mode 100644 index 0000000..08b7832 --- /dev/null +++ b/Help/command/cmake_command.rst @@ -0,0 +1,90 @@ +cmake_command +------------- + +Call meta-operations on CMake commands. + +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + cmake_command(`INVOKE`_ <command> [<args>...]) + cmake_command(`EVAL`_ CODE <code>...) + +Introduction +^^^^^^^^^^^^ + +This command will call meta-operations on built-in CMake commands or +those created via the :command:`macro` or :command:`function` commands. + +``cmake_command`` does not introduce a new variable or policy scope. + +Invoking Commands +^^^^^^^^^^^^^^^^^ + +.. _INVOKE: + +.. code-block:: cmake + + cmake_command(INVOKE <command> [<args>...]) + +Invokes the named ``<command>`` with the given arguments (if any). +For example, the code: + +.. code-block:: cmake + + set(message_command "message") + cmake_command(INVOKE ${message_command} STATUS "Hello World!") + +is equivalent to + +.. code-block:: cmake + + message(STATUS "Hello World!") + +Evaluating Code +^^^^^^^^^^^^^^^ + +.. _EVAL: + +.. code-block:: cmake + + cmake_command(EVAL CODE <code>...) + +Evaluates the ``<code>...`` as CMake code. + +For example, the code: + +.. code-block:: cmake + + set(A TRUE) + set(B TRUE) + set(C TRUE) + set(condition "(A AND B) OR C") + + cmake_command(EVAL CODE " + if (${condition}) + message(STATUS TRUE) + else() + message(STATUS FALSE) + endif()" + ) + +is equivalent to + +.. code-block:: cmake + + set(A TRUE) + set(B TRUE) + set(C TRUE) + set(condition "(A AND B) OR C") + + file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake " + if (${condition}) + message(STATUS TRUE) + else() + message(STATUS FALSE) + endif()" + ) + + include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake) diff --git a/Help/command/execute_process.rst b/Help/command/execute_process.rst index 14f879d..b32025f 100644 --- a/Help/command/execute_process.rst +++ b/Help/command/execute_process.rst @@ -21,7 +21,9 @@ Execute one or more child processes. [COMMAND_ECHO <where>] [OUTPUT_STRIP_TRAILING_WHITESPACE] [ERROR_STRIP_TRAILING_WHITESPACE] - [ENCODING <name>]) + [ENCODING <name>] + [ECHO_OUTPUT_VARIABLE] + [ECHO_ERROR_VARIABLE]) Runs the given sequence of one or more commands. @@ -105,6 +107,15 @@ Options: for this encoding. In CMake 3.11.0, ``UTF-8`` was added for consistency with the `UTF-8 RFC <https://www.ietf.org/rfc/rfc3629>`_ naming convention. +``ECHO_OUTPUT_VARIABLE``, ``ECHO_ERROR_VARIABLE`` + The standard output or standard error will not be exclusively redirected to + the configured variables. + + The output will be duplicated, it will be sent into the configured variables + and also on standard output or standard error. + + This is analogous to the ``tee`` Unix command. + If more than one ``OUTPUT_*`` or ``ERROR_*`` option is given for the same pipe the precedence is not specified. If no ``OUTPUT_*`` or ``ERROR_*`` options are given the output will diff --git a/Help/command/file.rst b/Help/command/file.rst index df7d8ba..92cb2ed 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -19,6 +19,7 @@ Synopsis file({`WRITE`_ | `APPEND`_} <filename> <content>...) file({`TOUCH`_ | `TOUCH_NOCREATE`_} [<file>...]) file(`GENERATE`_ OUTPUT <output-file> [...]) + file(`CONFIGURE`_ OUTPUT <output-file> CONTENT <content> [...]) `Filesystem`_ file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] [<globbing-expr>...]) @@ -41,6 +42,10 @@ Synopsis `Locking`_ file(`LOCK`_ <path> [...]) + `Archiving`_ + file(`ARCHIVE_CREATE`_ OUTPUT <archive> FILES <files> [...]) + file(`ARCHIVE_EXTRACT`_ INPUT <archive> DESTINATION <dir> [...]) + Reading ^^^^^^^ @@ -54,7 +59,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: @@ -482,6 +489,45 @@ generation phase. The output file will not yet have been written when the ``file(GENERATE)`` command returns, it is written only after processing all of a project's ``CMakeLists.txt`` files. +.. _CONFIGURE: + +.. code-block:: cmake + + file(CONFIGURE OUTPUT output-file + CONTENT content + [ESCAPE_QUOTES] [@ONLY] + [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ]) + +Generate an output file using the input given by ``CONTENT`` and substitute +variable values referenced as ``@VAR@`` or ``${VAR}`` contained therein. The +substitution rules behave the same as the :command:`configure_file` command. +In order to match :command:`configure_file`'s behavior, generator expressions +are not supported for both ``OUTPUT`` and ``CONTENT``. + +The arguments are: + +``OUTPUT <output-file>`` + Specify the output file name to generate. A relative path is treated with + respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. See policy + :policy:`CMP0070`. + ``<output-file>`` does not support generator expressions. + +``CONTENT <content>`` + Use the content given explicitly as input. + ``<content>`` does not support generator expressions. + +``ESCAPE_QUOTES`` + Escape any substituted quotes with backslashes (C-style). + +``@ONLY`` + Restrict variable replacement to references of the form ``@VAR@``. + This is useful for configuring scripts that use ``${VAR}`` syntax. + +``NEWLINE_STYLE <style>`` + Specify the newline style for the output file. Specify + ``UNIX`` or ``LF`` for ``\n`` newlines, or specify + ``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines. + Filesystem ^^^^^^^^^^ @@ -846,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/command/function.rst b/Help/command/function.rst index 53ba754..30938b3 100644 --- a/Help/command/function.rst +++ b/Help/command/function.rst @@ -44,11 +44,15 @@ can be invoked through any of foo() Foo() FOO() + cmake_command(INVOKE foo) and so on. However, it is strongly recommended to stay with the case chosen in the function definition. Typically functions use all-lowercase names. +The :command:`cmake_command(INVOKE ...)` command can also be used to invoke the +function. + Arguments ^^^^^^^^^ 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/macro.rst b/Help/command/macro.rst index 3f6f2f9..ee955cb 100644 --- a/Help/command/macro.rst +++ b/Help/command/macro.rst @@ -42,11 +42,15 @@ can be invoked through any of foo() Foo() FOO() + cmake_command(INVOKE foo) and so on. However, it is strongly recommended to stay with the case chosen in the macro definition. Typically macros use all-lowercase names. +The :command:`cmake_command(INVOKE ...)` command can also be used to invoke the +macro. + Arguments ^^^^^^^^^ 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 4a9ab99..776bb46 100644 --- a/Help/cpack_gen/ifw.rst +++ b/Help/cpack_gen/ifw.rst @@ -1,73 +1,28 @@ CPack IFW Generator ------------------- +Configure and run the Qt Installer Framework to generate a Qt installer. + +.. only:: html + + .. contents:: + Overview ^^^^^^^^ 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). +<http://doc.qt.io/qtinstallerframework/index.html>`_ (QtIFW), +and runs QtIFW tools to generate a Qt installer. QtIFW provides tools and utilities to create installers for the platforms supported by `Qt <https://www.qt.io>`_: Linux, Microsoft Windows, and macOS. -To make use of this generator, QtIFW should also be installed. -The module :module:`CPackIFW` looks for the location of the -QtIFW command-line utilities. - -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. - -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 -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. - -Localization of the description of your components and groups is useful for -users of your installers. - -A localized variable or argument can contain a single default value, and a -set of pairs the name of the locale and the localized value. - -For example: - -.. code-block:: cmake - - set(LOCALIZABLE_VARIABLE "Default value" - en "English value" - en_US "American value" - en_GB "Great Britain value" - ) +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. Variables ^^^^^^^^^ @@ -157,6 +112,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. @@ -263,55 +220,111 @@ Components repack dependent components. This feature available only since QtIFW 3.1. -Tools -""""" +QtIFW Tools +""""""""""" .. variable:: CPACK_IFW_FRAMEWORK_VERSION 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 - This variable is cached and may be configured if needed. + 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. +Other Settings +^^^^^^^^^^^^^^ Online installer -^^^^^^^^^^^^^^^^ +"""""""""""""""" -By default CPack IFW generator makes offline installer. This means that all -components will be packaged into a binary file. +By default, this generator generates an *offline installer*. This means that +that all packaged files are fully contained in the installer executable. -To make a component downloaded, you must set the ``DOWNLOADED`` option in -:command:`cpack_add_component`. +In contrast, an *online installer* will download some or all components from +a remote server. -Then you would use the command :command:`cpack_configure_downloads`. -If you set ``ALL`` option all components will be downloaded. +The ``DOWNLOADED`` option in the :command:`cpack_add_component` command +specifies that a component is to be downloaded. Alternatively, the ``ALL`` +option in the :command:`cpack_configure_downloads` command specifies that +`all` components are to be be downloaded. -You also can use command :command:`cpack_ifw_add_repository` and -variable :variable:`CPACK_IFW_DOWNLOAD_ALL` for more specific configuration. +The :command:`cpack_ifw_add_repository` command and the +:variable:`CPACK_IFW_DOWNLOAD_ALL` variable allow for more specific +configuration. -CPack IFW generator creates "repository" dir in current binary dir. You -would copy content of this dir to specified ``site`` (``url``). +When there are online components, CPack will write them to archive files. +The help page of the :module:`CPackComponent` module, especially the section +on the :command:`cpack_configure_downloads` function, explains how to make +these files accessible from a download URL. + +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 +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. + +Localization of the description of your components and groups is useful for +users of your installers. + +A localized variable or argument can contain a single default value, and a +set of pairs the name of the locale and the localized value. + +For example: + +.. code-block:: cmake + + set(LOCALIZABLE_VARIABLE "Default value" + en "English value" + en_US "American value" + en_GB "Great Britain value" + ) See Also ^^^^^^^^ @@ -330,5 +343,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/cpack_gen/rpm.rst b/Help/cpack_gen/rpm.rst index 2693c7b..66d5464 100644 --- a/Help/cpack_gen/rpm.rst +++ b/Help/cpack_gen/rpm.rst @@ -473,38 +473,42 @@ List of CPack RPM generator specific variables: .. variable:: CPACK_RPM_PRE_INSTALL_SCRIPT_FILE CPACK_RPM_PRE_UNINSTALL_SCRIPT_FILE + CPACK_RPM_PRE_TRANS_SCRIPT_FILE - Path to file containing pre (un)install script. + Path to file containing pre install/uninstall/transaction script. * Mandatory : NO * Default : - - May be used to embed a pre (un)installation script in the spec file. + May be used to embed a pre installation/uninstallation/transaction script in the spec file. The referred script file (or both) will be read and directly put after the ``%pre`` or ``%preun`` section - If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the (un)install + If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the install/uninstall/transaction script for each component can be overridden with - ``CPACK_RPM_<COMPONENT>_PRE_INSTALL_SCRIPT_FILE`` and - ``CPACK_RPM_<COMPONENT>_PRE_UNINSTALL_SCRIPT_FILE``. + ``CPACK_RPM_<COMPONENT>_PRE_INSTALL_SCRIPT_FILE``, + ``CPACK_RPM_<COMPONENT>_PRE_UNINSTALL_SCRIPT_FILE``, and + ``CPACK_RPM_<COMPONENT>_PRE_TRANS_SCRIPT_FILE`` One may verify which scriptlet has been included with:: rpm -qp --scripts package.rpm .. variable:: CPACK_RPM_POST_INSTALL_SCRIPT_FILE CPACK_RPM_POST_UNINSTALL_SCRIPT_FILE + CPACK_RPM_POST_TRANS_SCRIPT_FILE - Path to file containing post (un)install script. + Path to file containing post install/uninstall/transaction script. * Mandatory : NO * Default : - - May be used to embed a post (un)installation script in the spec file. + May be used to embed a post installation/uninstallation/transaction script in the spec file. The referred script file (or both) will be read and directly put after the ``%post`` or ``%postun`` section. - If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the (un)install + If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the install/uninstall/transaction script for each component can be overridden with - ``CPACK_RPM_<COMPONENT>_POST_INSTALL_SCRIPT_FILE`` and - ``CPACK_RPM_<COMPONENT>_POST_UNINSTALL_SCRIPT_FILE``. + ``CPACK_RPM_<COMPONENT>_POST_INSTALL_SCRIPT_FILE``, + ``CPACK_RPM_<COMPONENT>_POST_UNINSTALL_SCRIPT_FILE``, and + ``CPACK_RPM_<COMPONENT>_POST_TRANS_SCRIPT_FILE`` One may verify which scriptlet has been included with:: rpm -qp --scripts package.rpm 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/guide/tutorial/Step6/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt index 4bf6024..f64c6ac 100644 --- a/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt @@ -8,10 +8,20 @@ target_include_directories(MathFunctions # does this system provide the log and exp functions? include(CheckSymbolExists) -set(CMAKE_REQUIRED_LIBRARIES "m") check_symbol_exists(log "math.h" HAVE_LOG) check_symbol_exists(exp "math.h" HAVE_EXP) +if(NOT (HAVE_LOG AND HAVE_EXP)) + unset(HAVE_LOG CACHE) + unset(HAVE_EXP CACHE) + set(CMAKE_REQUIRED_LIBRARIES "m") + check_symbol_exists(log "math.h" HAVE_LOG) + check_symbol_exists(exp "math.h" HAVE_EXP) + if(HAVE_LOG AND HAVE_EXP) + target_link_libraries(MathFunctions PRIVATE m) + endif() +endif() +# add compile definitions if(HAVE_LOG AND HAVE_EXP) target_compile_definitions(MathFunctions PRIVATE "HAVE_LOG" "HAVE_EXP") diff --git a/Help/guide/tutorial/index.rst b/Help/guide/tutorial/index.rst index a844cbf..4fbcd4c 100644 --- a/Help/guide/tutorial/index.rst +++ b/Help/guide/tutorial/index.rst @@ -386,7 +386,7 @@ these functions using the :module:`CheckSymbolExists` module in the top-level .. literalinclude:: Step6/MathFunctions/CMakeLists.txt :language: cmake :start-after: # does this system provide the log and exp functions? - :end-before: if(HAVE_LOG AND HAVE_EXP) + :end-before: # add compile definitions Now let's add these defines to ``TutorialConfig.h.in`` so that we can use them from ``mysqrt.cxx``: diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst index 59ba897..87743b4 100644 --- a/Help/manual/cmake-commands.7.rst +++ b/Help/manual/cmake-commands.7.rst @@ -16,6 +16,7 @@ These commands are always available. :maxdepth: 1 /command/break + /command/cmake_command /command/cmake_host_system_information /command/cmake_minimum_required /command/cmake_parse_arguments diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 691481b..72de4ac 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -259,6 +259,109 @@ Variable Queries add_executable(myapp main.cpp) target_link_libraries(myapp myapp_c myapp_cxx) +.. _`Boolean LINK_LANGUAGE Generator Expression`: + +``$<LINK_LANG_AND_ID:language,compiler_ids>`` + ``1`` when the language used for link step matches ``language`` and the + CMake's compiler id of the language linker matches any one of the entries + in ``compiler_ids``, otherwise ``0``. This expression is a short form for the + combination of ``$<LINK_LANGUAGE:language>`` and + ``$<LANG_COMPILER_ID:compiler_ids>``. This expression may be used to specify + link libraries, link options, link directories and link dependencies of a + particular language and linker combination in a target. For example: + + .. code-block:: cmake + + add_library(libC_Clang ...) + add_library(libCXX_Clang ...) + add_library(libC_Intel ...) + add_library(libCXX_Intel ...) + + add_executable(myapp main.c) + if (CXX_CONFIG) + target_sources(myapp PRIVATE file.cxx) + endif() + target_link_libraries(myapp + PRIVATE $<$<LINK_LANG_AND_ID:CXX,Clang,AppleClang>:libCXX_Clang> + $<$<LINK_LANG_AND_ID:C,Clang,AppleClang>:libC_Clang> + $<$<LINK_LANG_AND_ID:CXX,Intel>:libCXX_Intel> + $<$<LINK_LANG_AND_ID:C,Intel>:libC_Intel>) + + This specifies the use of different link libraries based on both the + compiler id and link language. This example will have target ``libCXX_Clang`` + as link dependency when ``Clang`` or ``AppleClang`` is the ``CXX`` + linker, and ``libCXX_Intel`` when ``Intel`` is the ``CXX`` linker. + Likewise when the ``C`` linker is ``Clang`` or ``AppleClang``, target + ``libC_Clang`` will be added as link dependency and ``libC_Intel`` when + ``Intel`` is the ``C`` linker. + + See :ref:`the note related to + <Constraints LINK_LANGUAGE Generator Expression>` + ``$<LINK_LANGUAGE:language>`` for constraints about the usage of this + generator expression. + +``$<LINK_LANGUAGE:languages>`` + ``1`` when the language used for link step matches any of the entries + in ``languages``, otherwise ``0``. This expression may be used to specify + link libraries, link options, link directories and link dependencies of a + particular language in a target. For example: + + .. code-block:: cmake + + add_library(api_C ...) + add_library(api_CXX ...) + add_library(api INTERFACE) + target_link_options(api INTERFACE $<$<LINK_LANGUAGE:C>:-opt_c> + $<$<LINK_LANGUAGE:CXX>:-opt_cxx>) + target_link_libraries(api INTERFACE $<$<LINK_LANGUAGE:C>:api_C> + $<$<LINK_LANGUAGE:CXX>:api_CXX>) + + add_executable(myapp1 main.c) + target_link_options(myapp1 PRIVATE api) + + add_executable(myapp2 main.cpp) + target_link_options(myapp2 PRIVATE api) + + This specifies to use the ``api`` target for linking targets ``myapp1`` and + ``myapp2``. In practice, ``myapp1`` will link with target ``api_C`` and + option ``-opt_c`` because it will use ``C`` as link language. And ``myapp2`` + will link with ``api_CXX`` and option ``-opt_cxx`` because ``CXX`` will be + the link language. + + .. _`Constraints LINK_LANGUAGE Generator Expression`: + + .. note:: + + To determine the link language of a target, it is required to collect, + transitively, all the targets which will be linked to it. So, for link + libraries properties, a double evaluation will be done. During the first + evaluation, ``$<LINK_LANGUAGE:..>`` expressions will always return ``0``. + The link language computed after this first pass will be used to do the + second pass. To avoid inconsistency, it is required that the second pass + do not change the link language. Moreover, to avoid unexpected + side-effects, it is required to specify complete entities as part of the + ``$<LINK_LANGUAGE:..>`` expression. For example: + + .. code-block:: cmake + + add_library(lib STATIC file.cxx) + add_library(libother STATIC file.c) + + # bad usage + add_executable(myapp1 main.c) + target_link_libraries(myapp1 PRIVATE lib$<$<LINK_LANGUAGE:C>:other>) + + # correct usage + add_executable(myapp2 main.c) + target_link_libraries(myapp2 PRIVATE $<$<LINK_LANGUAGE:C>:libother>) + + In this example, for ``myapp1``, the first pass will, unexpectedly, + determine that the link language is ``CXX`` because the evaluation of the + generator expression will be an empty string so ``myapp1`` will depends on + target ``lib`` which is ``C++``. On the contrary, for ``myapp2``, the first + evaluation will give ``C`` as link language, so the second pass will + correctly add target ``libother`` as link dependency. + String-Valued Generator Expressions =================================== @@ -450,22 +553,41 @@ Variable Queries <Boolean COMPILE_LANGUAGE Generator Expression>` ``$<COMPILE_LANGUAGE:language>`` for notes about the portability of this generator expression. +``$<LINK_LANGUAGE>`` + The link language of target when evaluating link options. + See :ref:`the related boolean expression + <Boolean LINK_LANGUAGE Generator Expression>` ``$<LINK_LANGUAGE:language>`` + for notes about the portability of this generator expression. + + .. note:: + + This generator expression is not supported by the link libraries + properties to avoid side-effects due to the double evaluation of + these properties. Target-Dependent Queries ------------------------ +These queries refer to a target ``tgt``. This can be any runtime artifact, +namely: + +* an executable target created by :command:`add_executable` +* a shared library target (``.so``, ``.dll`` but not their ``.lib`` import library) + created by :command:`add_library` +* a static library target created by :command:`add_library` + +In the following, "the ``tgt`` filename" means the name of the ``tgt`` +binary file. This has to be distinguished from "the target name", +which is just the string ``tgt``. + ``$<TARGET_NAME_IF_EXISTS:tgt>`` - Expands to the ``tgt`` if the given target exists, an empty string - otherwise. + The target name ``tgt`` if the target exists, an empty string otherwise. ``$<TARGET_FILE:tgt>`` - Full path to main file (.exe, .so.1.2, .a) where ``tgt`` is the name of a - target. + Full path to the ``tgt`` binary file. ``$<TARGET_FILE_BASE_NAME:tgt>`` - Base name of main file where ``tgt`` is the name of a target. - - The base name corresponds to the target file name (see - ``$<TARGET_FILE_NAME:tgt>``) without prefix and suffix. For example, if - target file name is ``libbase.so``, the base name is ``base``. + Base name of ``tgt``, i.e. ``$<TARGET_FILE_NAME:tgt>`` without prefix and + suffix. + For example, if the ``tgt`` filename is ``libbase.so``, the base name is ``base``. See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, :prop_tgt:`LIBRARY_OUTPUT_NAME` and :prop_tgt:`RUNTIME_OUTPUT_NAME` @@ -480,32 +602,31 @@ Target-Dependent Queries Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. ``$<TARGET_FILE_PREFIX:tgt>`` - Prefix of main file where ``tgt`` is the name of a target. + Prefix of the ``tgt`` filename (such as ``lib``). See also the :prop_tgt:`PREFIX` target property. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. ``$<TARGET_FILE_SUFFIX:tgt>`` - Suffix of main file where ``tgt`` is the name of a target. - - The suffix corresponds to the file extension (such as ".so" or ".exe"). + Suffix of the ``tgt`` filename (extension such as ``.so`` or ``.exe``). See also the :prop_tgt:`SUFFIX` target property. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. ``$<TARGET_FILE_NAME:tgt>`` - Name of main file (.exe, .so.1.2, .a). + The ``tgt`` filename. ``$<TARGET_FILE_DIR:tgt>`` - Directory of main file (.exe, .so.1.2, .a). + Directory of the ``tgt`` binary file. ``$<TARGET_LINKER_FILE:tgt>`` - File used to link (.a, .lib, .so) where ``tgt`` is the name of a target. + File used when linking to the ``tgt`` target. This will usually + be the library that ``tgt`` represents (``.a``, ``.lib``, ``.so``), + but for a shared library on DLL platforms, it would be the ``.lib`` + import library associated with the DLL. ``$<TARGET_LINKER_FILE_BASE_NAME:tgt>`` - Base name of file used to link where ``tgt`` is the name of a target. - - The base name corresponds to the target linker file name (see - ``$<TARGET_LINKER_FILE_NAME:tgt>``) without prefix and suffix. For example, + Base name of file used to link the target ``tgt``, i.e. + ``$<TARGET_LINKER_FILE_NAME:tgt>`` without prefix and suffix. For example, if target file name is ``libbase.a``, the base name is ``base``. See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, @@ -520,7 +641,7 @@ Target-Dependent Queries Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. ``$<TARGET_LINKER_FILE_PREFIX:tgt>`` - Prefix of file used to link where ``tgt`` is the name of a target. + Prefix of file used to link target ``tgt``. See also the :prop_tgt:`PREFIX` and :prop_tgt:`IMPORT_PREFIX` target properties. @@ -538,15 +659,15 @@ Target-Dependent Queries Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. ``$<TARGET_LINKER_FILE_NAME:tgt>`` - Name of file used to link (.a, .lib, .so). + Name of file used to link target ``tgt``. ``$<TARGET_LINKER_FILE_DIR:tgt>`` - Directory of file used to link (.a, .lib, .so). + Directory of file used to link target ``tgt``. ``$<TARGET_SONAME_FILE:tgt>`` - File with soname (.so.3) where ``tgt`` is the name of a target. + File with soname (``.so.3``) where ``tgt`` is the name of a target. ``$<TARGET_SONAME_FILE_NAME:tgt>`` - Name of file with soname (.so.3). + Name of file with soname (``.so.3``). ``$<TARGET_SONAME_FILE_DIR:tgt>`` - Directory of with soname (.so.3). + Directory of with soname (``.so.3``). ``$<TARGET_PDB_FILE:tgt>`` Full path to the linker generated program database file (.pdb) where ``tgt`` is the name of a target. @@ -589,11 +710,10 @@ Target-Dependent Queries Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. ``$<TARGET_PROPERTY:prop>`` - Value of the property ``prop`` on the target on which the generator - expression is evaluated. Note that for generator expressions in - :ref:`Target Usage Requirements` this is the value of the property - on the consuming target rather than the target specifying the - requirement. + Value of the property ``prop`` on the target for which the expression + is being evaluated. Note that for generator expressions in + :ref:`Target Usage Requirements` this is the consuming target rather + than the target specifying the requirement. ``$<INSTALL_PREFIX>`` Content of the install prefix when the target is exported via :command:`install(EXPORT)`, or when evaluated in diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 060a072..e552377 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -200,6 +200,7 @@ Properties on Targets /prop_tgt/Fortran_FORMAT /prop_tgt/Fortran_MODULE_DIRECTORY /prop_tgt/FRAMEWORK + /prop_tgt/FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG /prop_tgt/FRAMEWORK_VERSION /prop_tgt/GENERATOR_FILE_NAME /prop_tgt/GHS_INTEGRITY_APP @@ -375,6 +376,7 @@ Properties on Targets /prop_tgt/VS_SCC_PROJECTNAME /prop_tgt/VS_SCC_PROVIDER /prop_tgt/VS_SDK_REFERENCES + /prop_tgt/VS_SOLUTION_DEPLOY /prop_tgt/VS_USER_PROPS /prop_tgt/VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION /prop_tgt/VS_WINRT_COMPONENT diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index fc27739..c271024 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -388,6 +388,7 @@ Variables that Control the Build /variable/CMAKE_EXE_LINKER_FLAGS_INIT /variable/CMAKE_FOLDER /variable/CMAKE_FRAMEWORK + /variable/CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG /variable/CMAKE_Fortran_FORMAT /variable/CMAKE_Fortran_MODULE_DIRECTORY /variable/CMAKE_GHS_NO_SOURCE_GROUP_FILE diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 28a081f..e497890 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_tgt/CONFIG_POSTFIX.rst b/Help/prop_tgt/CONFIG_POSTFIX.rst index 11b50b9..5c2fbd7 100644 --- a/Help/prop_tgt/CONFIG_POSTFIX.rst +++ b/Help/prop_tgt/CONFIG_POSTFIX.rst @@ -8,3 +8,6 @@ is appended to the target file name built on disk. For non-executable targets, this property is initialized by the value of the variable CMAKE_<CONFIG>_POSTFIX if it is set when a target is created. This property is ignored on the Mac for Frameworks and App Bundles. + +For macOS see also the :prop_tgt:`FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>` +target property. diff --git a/Help/prop_tgt/FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG.rst b/Help/prop_tgt/FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG.rst new file mode 100644 index 0000000..2b20bf9 --- /dev/null +++ b/Help/prop_tgt/FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG.rst @@ -0,0 +1,25 @@ +FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG> +--------------------------------------- + +Postfix to append to the framework file name for configuration <CONFIG>, +when using a multi-config generator (like Xcode and Ninja Multi-Config). + +When building with configuration <CONFIG> the value of this property +is appended to the framework file name built on disk. + +For example given a framework called ``my_fw``, a value of ``_debug`` +for the :prop_tgt:`FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>` property, and +``Debug;Release`` in `CMAKE_CONFIGURATION_TYPES`, the following relevant +files would be created for the ``Debug`` and ``Release`` configurations: + +- Release/my_fw.framework/my_fw +- Release/my_fw.framework/Versions/A/my_fw +- Debug/my_fw.framework/my_fw_debug +- Debug/my_fw.framework/Versions/A/my_fw_debug + +For framework targets, this property is initialized by the value of the +variable :variable:`CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>` if it +is set when a target is created. + +This property is ignored for non-framework targets, and when using single +config generators. diff --git a/Help/prop_tgt/VS_SOLUTION_DEPLOY.rst b/Help/prop_tgt/VS_SOLUTION_DEPLOY.rst new file mode 100644 index 0000000..7906d75 --- /dev/null +++ b/Help/prop_tgt/VS_SOLUTION_DEPLOY.rst @@ -0,0 +1,29 @@ +VS_SOLUTION_DEPLOY +------------------ + +Specify that the target should be marked for deployment when not targeting +Windows CE, Windows Phone or a Windows Store application. + +If the target platform doesn't support deployment, this property won't have any effect. + +Generator expressions are supported. + +Example 1 +^^^^^^^^^ + +This shows setting the variable for the target foo. + +.. code-block:: cmake + + add_executable(foo SHARED foo.cpp) + set_property(TARGET foo PROPERTY VS_SOLUTION_DEPLOY ON) + +Example 2 +^^^^^^^^^ + +This shows setting the variable for the Release configuration only. + +.. code-block:: cmake + + add_executable(foo SHARED foo.cpp) + set_property(TARGET foo PROPERTY VS_SOLUTION_DEPLOY "$<NOT:$<CONFIG:Release>>") 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/CPackRPM-trans-scripts.rst b/Help/release/dev/CPackRPM-trans-scripts.rst new file mode 100644 index 0000000..57fc099 --- /dev/null +++ b/Help/release/dev/CPackRPM-trans-scripts.rst @@ -0,0 +1,7 @@ +CPackRPM-trans-scripts +---------------------- + +* The :cpack_gen:`CPack RPM Generator` gained + :variable:`CPACK_RPM_PRE_TRANS_SCRIPT_FILE` + :variable:`CPACK_RPM_POST_TRANS_SCRIPT_FILE` + variables to specify pre- and post-trans scripts. diff --git a/Help/release/dev/FindPython-artifacts-interactive.rst b/Help/release/dev/FindPython-artifacts-interactive.rst new file mode 100644 index 0000000..1aa4b3e --- /dev/null +++ b/Help/release/dev/FindPython-artifacts-interactive.rst @@ -0,0 +1,6 @@ +FindPython-artifacts-interactive +-------------------------------- + +* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython` + modules gained the possibility to create artifacts cache variables for + interactive edition. 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/cmake-gui-env-platform-defaults.rst b/Help/release/dev/cmake-gui-env-platform-defaults.rst new file mode 100644 index 0000000..0960ef1 --- /dev/null +++ b/Help/release/dev/cmake-gui-env-platform-defaults.rst @@ -0,0 +1,8 @@ +cmake-gui-env-platform-defaults +------------------------------- + +* :manual:`cmake-gui(1)` now populates its generator selection + widget default value from the :envvar:`CMAKE_GENERATOR` environment + variable. Additionally, environment variables + :envvar:`CMAKE_GENERATOR_PLATFORM` and :envvar:`CMAKE_GENERATOR_TOOLSET` + are used to populate their respective widget defaults. diff --git a/Help/release/dev/cmake_command-command.rst b/Help/release/dev/cmake_command-command.rst new file mode 100644 index 0000000..6200ae2 --- /dev/null +++ b/Help/release/dev/cmake_command-command.rst @@ -0,0 +1,6 @@ +cmake_command +------------- + +* The :command:`cmake_command()` command was added for meta-operations on + scripted or built-in commands, starting with a mode to ``INVOKE`` other + commands, and ``EVAL CODE`` to inplace evaluate a CMake script. 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/execute_process.rst b/Help/release/dev/execute_process.rst new file mode 100644 index 0000000..02e813b --- /dev/null +++ b/Help/release/dev/execute_process.rst @@ -0,0 +1,5 @@ +execute_process +--------------- + +* The :command:`execute_process` command gained the ``ECHO_OUTPUT_VARIABLE`` + and ``ECHO_ERROR_VARIABLE`` options. 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/file_configure.rst b/Help/release/dev/file_configure.rst new file mode 100644 index 0000000..35e99c4 --- /dev/null +++ b/Help/release/dev/file_configure.rst @@ -0,0 +1,6 @@ +file_configure +-------------- + +* The :command:`file(CONFIGURE)` subcommand was created in order replicate the + :command:`configure_file` functionality without resorting to a pre-existing + file on disk as input. The content is instead passed as a string. diff --git a/Help/release/dev/findswig-components.rst b/Help/release/dev/findswig-components.rst new file mode 100644 index 0000000..ce569be --- /dev/null +++ b/Help/release/dev/findswig-components.rst @@ -0,0 +1,5 @@ +findswig-components +------------------- + +* The :module:`FindSWIG` module now accepts target languages as ``COMPONENTS`` + and ``OPTIONAL_COMPONENTS`` arguments to ``find_package``. diff --git a/Help/release/dev/framework-multi-config-postfix.rst b/Help/release/dev/framework-multi-config-postfix.rst new file mode 100644 index 0000000..50cf9ce --- /dev/null +++ b/Help/release/dev/framework-multi-config-postfix.rst @@ -0,0 +1,7 @@ +framework-multi-config-postfix +------------------------------ + +* The :prop_tgt:`FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>` target property + and associated :variable:`CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>` + variable were created to allow adding a postfix to the name of a + framework file name when using a multi-config generator. diff --git a/Help/release/dev/genex-LINK_LANGUAGE.rst b/Help/release/dev/genex-LINK_LANGUAGE.rst new file mode 100644 index 0000000..05894d6 --- /dev/null +++ b/Help/release/dev/genex-LINK_LANGUAGE.rst @@ -0,0 +1,5 @@ +genex-LINK_LANGUAGE +=================== + +* The ``$<LINK_LANGUAGE:...>`` and ``$<LINK_LANG_AND_ID:...>`` + :manual:`generator expressions <cmake-generator-expressions(7)>` were added. 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. diff --git a/Help/release/dev/required_find_commands.rst b/Help/release/dev/required_find_commands.rst new file mode 100644 index 0000000..cc2bf02 --- /dev/null +++ b/Help/release/dev/required_find_commands.rst @@ -0,0 +1,6 @@ +required_find_commands +---------------------- + +* The :command:`find_program`, :command:`find_library`, :command:`find_path` + and :command:`find_file` commands gained a new ``REQUIRED`` option that will + stop processing with an error message if nothing is found. 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. diff --git a/Help/release/dev/useswig-fortran.rst b/Help/release/dev/useswig-fortran.rst new file mode 100644 index 0000000..17baf96 --- /dev/null +++ b/Help/release/dev/useswig-fortran.rst @@ -0,0 +1,7 @@ +useswig-fortran +--------------- + +* The :module:`UseSWIG` module now supports Fortran as a target language if + the ``SWIG_EXECUTABLE`` is SWIG-Fortran_. + +.. _`SWIG-Fortran`: https://github.com/swig-fortran/swig diff --git a/Help/release/dev/vs-sln-deploy.rst b/Help/release/dev/vs-sln-deploy.rst new file mode 100644 index 0000000..2e83e52 --- /dev/null +++ b/Help/release/dev/vs-sln-deploy.rst @@ -0,0 +1,6 @@ +vs-sln-deploy +------------- + +* The :prop_tgt:`VS_SOLUTION_DEPLOY` target property was added to tell + :ref:`Visual Studio Generators` for VS 2010 and above to mark a + target for deployment even when not building for Windows Phone/Store/CE. diff --git a/Help/release/index.rst b/Help/release/index.rst index 5d1f8a2..22b1a09 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_FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG.rst b/Help/variable/CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG.rst new file mode 100644 index 0000000..5c7cd23 --- /dev/null +++ b/Help/variable/CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG.rst @@ -0,0 +1,8 @@ +CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG> +--------------------------------------------- + +Default framework filename postfix under configuration ``<CONFIG>`` when +using a multi-config generator. + +When a framework target is created its :prop_tgt:`FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>` +target property is initialized with the value of this variable if it is set. |