diff options
Diffstat (limited to 'Help')
28 files changed, 520 insertions, 166 deletions
diff --git a/Help/command/cmake_command.rst b/Help/command/cmake_command.rst new file mode 100644 index 0000000..9281647 --- /dev/null +++ b/Help/command/cmake_command.rst @@ -0,0 +1,40 @@ +cmake_command +------------- + +Call meta-operations on CMake commands. + +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + cmake_command(`INVOKE`_ <command> [<args>...]) + +Introduction +^^^^^^^^^^^^ + +This command will call meta-operations on built-in CMake commands or +those created via the :command:`macro` or :command:`function` commands. + +Invoking +^^^^^^^^ + +.. _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!") 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..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: 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/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 fb84378..37f8678 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -375,6 +375,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/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/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..ebe75b1 --- /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. 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/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/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/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 ======== |