diff options
| -rw-r--r-- | Help/command/install.rst | 41 | ||||
| -rw-r--r-- | Help/cpack_gen/ifw.rst | 58 | ||||
| -rw-r--r-- | Modules/CPackComponent.cmake | 83 | ||||
| -rw-r--r-- | Modules/ExternalProject.cmake | 9 | ||||
| -rw-r--r-- | Modules/FetchContent.cmake | 7 |
5 files changed, 116 insertions, 82 deletions
diff --git a/Help/command/install.rst b/Help/command/install.rst index a3c64a4..abf6b17 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -126,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/cpack_gen/ifw.rst b/Help/cpack_gen/ifw.rst index 1d1a55b..d7c71b4 100644 --- a/Help/cpack_gen/ifw.rst +++ b/Help/cpack_gen/ifw.rst @@ -3,6 +3,10 @@ CPack IFW Generator Configure and run the Qt Installer Framework to generate a Qt installer. +.. only:: html + + .. contents:: + Overview ^^^^^^^^ @@ -20,32 +24,6 @@ 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. -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 ^^^^^^^^^^^^^^^^^^^^ @@ -161,6 +139,8 @@ Package Default target directory for installation. By default used "@ApplicationsDir@/:variable:`CPACK_PACKAGE_INSTALL_DIRECTORY`" + (variables embedded in '@' are expanded by the + `QtIFW scripting engine <https://doc.qt.io/qtinstallerframework/scripting.html>`_). You can use predefined variables. @@ -294,6 +274,32 @@ These variables are cached, and may be configured if needed. The path to ``devtool``. +Hints for Finding QtIFW +""""""""""""""""""""""" + +Generally, the CPack ``IFW`` generator automatically finds QtIFW tools, +but if you don't use a default path for installation of the QtIFW tools, +the path may be specified in either a CMake or an environment variable: + +.. variable:: CPACK_IFW_ROOT + + An CMake variable which specifies the location of the QtIFW tool suite. + + The variable will be cached in the ``CPackConfig.cmake`` file and used at + CPack runtime. + +.. variable:: QTIFWDIR + + An environment variable which specifies the location of the QtIFW tool + suite. + +.. note:: + The specified path should not contain "bin" at the end + (for example: "D:\\DevTools\\QtIFW2.0.5"). + +The :variable:`CPACK_IFW_ROOT` variable has a higher priority and overrides +the value of the :variable:`QTIFWDIR` variable. + Online installer ^^^^^^^^^^^^^^^^ diff --git a/Modules/CPackComponent.cmake b/Modules/CPackComponent.cmake index 22fa6bb..1f8c38c 100644 --- a/Modules/CPackComponent.cmake +++ b/Modules/CPackComponent.cmake @@ -7,25 +7,32 @@ CPackComponent Configure components for binary installers and source packages. -Variables concerning CPack Components -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. only:: html -This module handles the component part of :module:`CPack`. + .. contents:: -For certain kinds of binary installers (especially the graphical installers), -CPack generates installers that allow users to select individual application -components to install. -The contents of each of the components are identified by the ``COMPONENT`` -argument of CMake's :command:`install` command. These components can be +Introduction +^^^^^^^^^^^^ + +This module is automatically included by :module:`CPack`. + +Certain binary installers (especially the graphical installers) generated +by CPack allow users to select individual application *components* to install. +This module allows developers to configure the packaging of such components. + +Contents is assigned to components by the ``COMPONENT`` +argument of CMake's :command:`install` command. Components can be annotated with user-friendly names and descriptions, inter-component dependencies, etc., and grouped in various ways to customize the -resulting installer. See the cpack_add_* commands, described below, -for more information about component-specific installations. +resulting installer, using the commands described below. + +To specify different groupings for different CPack generators use +a CPACK_PROJECT_CONFIG_FILE. -Component-specific installation allows users to select specific sets -of components to install during the install process. Installation -components are identified by the ``COMPONENT`` argument of :command:`install`, -and should be further described by the following CPack commands: +Variables +^^^^^^^^^ + +The following variables influence the component-specific packaging: .. variable:: CPACK_COMPONENTS_ALL @@ -59,16 +66,14 @@ and should be further described by the following CPack commands: Specify how components are grouped for multi-package component-aware CPack generators. - Some generators like RPM or ARCHIVE family (TGZ, ZIP, ...) generates - several packages files when asked for component packaging. They group - the component differently depending on the value of this variable: - - * ONE_PER_GROUP (default): creates one package file per component group - * ALL_COMPONENTS_IN_ONE : creates a single package with all (requested) components - * IGNORE : creates one package per component, i.e. IGNORE component group + Some generators like RPM or ARCHIVE (TGZ, ZIP, ...) may generate + several packages files when there are components, depending + on the value of this variable: - One can specify different grouping for different CPack generator by - using a CPACK_PROJECT_CONFIG_FILE. + * ONE_PER_GROUP (default): create one package per component group + * IGNORE : create one package per component (ignore the groups) + * ALL_COMPONENTS_IN_ONE : create a single package with all requested + components .. variable:: CPACK_COMPONENT_<compName>_DISPLAY_NAME @@ -98,10 +103,15 @@ and should be further described by the following CPack commands: True if this component is not selected to be installed by default. +Commands +^^^^^^^^ + +Add component +""""""""""""" + .. command:: cpack_add_component -Describes a CPack installation -component named by the COMPONENT argument to a CMake INSTALL command. +Describe an installation component. :: @@ -116,13 +126,11 @@ component named by the COMPONENT argument to a CMake INSTALL command. [ARCHIVE_FILE filename] [PLIST filename]) - - -The cmake_add_component command describes an installation component, -which the user can opt to install or remove as part of the graphical -installation process. compname is the name of the component, as -provided to the COMPONENT argument of one or more CMake INSTALL -commands. +``compname`` is the name of an installation component, as defined by the +``COMPONENT`` argument of one or more CMake :command:`install` commands. +With the ``cpack_add_component`` command one can set a name, a description, +and other attributes of an installation component. +One can also assign a component to a component group. DISPLAY_NAME is the displayed name of the component, used in graphical installers to display the component name. This value can be any @@ -175,6 +183,9 @@ the component. See cpack_configure_downloads for more information. PLIST gives a filename that is passed to pkgbuild with the ``--component-plist`` argument when using the productbuild generator. +Add component group +""""""""""""""""""" + .. command:: cpack_add_component_group Describes a group of related CPack installation components. @@ -223,6 +234,9 @@ single entry. BOLD_TITLE indicates that the group title should appear in bold, to call the user's attention to the group. +Add installation type +""""""""""""""""""""" + .. command:: cpack_add_install_type Add a new installation type containing @@ -247,6 +261,9 @@ DISPLAY_NAME is the displayed name of the install type, which will typically show up in a drop-down box within a graphical installer. This value can be any string. +Configure downloads +""""""""""""""""""" + .. command:: cpack_configure_downloads Configure CPack to download @@ -279,8 +296,6 @@ requires the ZipDLL plug-in for NSIS, available at: http://nsis.sourceforge.net/ZipDLL_plug-in - - On macOS, installers that download components on-the-fly can only be built and installed on system using macOS 10.5 or later. diff --git a/Modules/ExternalProject.cmake b/Modules/ExternalProject.cmake index 5bac0d8..326ee06 100644 --- a/Modules/ExternalProject.cmake +++ b/Modules/ExternalProject.cmake @@ -9,8 +9,11 @@ ExternalProject .. contents:: +Commands +^^^^^^^^ + External Project Definition -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +""""""""""""""""""""""""""" .. command:: ExternalProject_Add @@ -665,7 +668,7 @@ External Project Definition automatic substitutions that are supported for some options. Obtaining Project Properties -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""""""" .. command:: ExternalProject_Get_Property @@ -686,7 +689,7 @@ Obtaining Project Properties message("Source dir of myExtProj = ${SOURCE_DIR}") Explicit Step Management -^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""" The ``ExternalProject_Add()`` function on its own is often sufficient for incorporating an external project into the main build. Certain scenarios diff --git a/Modules/FetchContent.cmake b/Modules/FetchContent.cmake index f3e1b51..0e98f49 100644 --- a/Modules/FetchContent.cmake +++ b/Modules/FetchContent.cmake @@ -76,8 +76,11 @@ sometimes useful as part of implementing some higher level feature or to populate some content in CMake's script mode. +Commands +^^^^^^^^ + Declaring Content Details -^^^^^^^^^^^^^^^^^^^^^^^^^ +""""""""""""""""""""""""" .. command:: FetchContent_Declare @@ -130,7 +133,7 @@ Declaring Content Details ) Populating The Content -^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""" For most common scenarios, population means making content available to the main build according to previously declared details for that dependency. |