diff options
Diffstat (limited to 'Help')
113 files changed, 4051 insertions, 179 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index 48a1a71..38c231a 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -62,8 +62,11 @@ added to the search. If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: .. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| replace:: - |prefix_XXX_SUBDIR| for each ``<prefix>`` in ``PackageName_ROOT`` if called - from within a find module + |prefix_XXX_SUBDIR| for each ``<prefix>`` in the + :variable:`<PackageName>_ROOT` CMake variable and the + :envvar:`<PackageName>_ROOT` environment variable if + called from within a find module loaded by + :command:`find_package(<PackageName>)` .. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace:: |prefix_XXX_SUBDIR| for each ``<prefix>`` in :variable:`CMAKE_PREFIX_PATH` @@ -76,13 +79,16 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: |prefix_XXX_SUBDIR| for each ``<prefix>`` in :variable:`CMAKE_SYSTEM_PREFIX_PATH` -1. If called from within a find module, search prefix paths unique to the - current package being found. Specifically look in the ``PackageName_ROOT`` - CMake and environment variables. The package root variables are maintained - as a stack so if called from nested find modules, root paths from the - parent's find module will be searched after paths from the current module, - i.e. ``CurrentPackage_ROOT``, ``ENV{CurrentPackage_ROOT}``, - ``ParentPackage_ROOT``, ``ENV{ParentPackage_ROOT}``, etc. +1. If called from within a find module loaded by + :command:`find_package(<PackageName>)`, search prefixes unique to the + current package being found. Specifically look in the + :variable:`<PackageName>_ROOT` CMake variable and the + :envvar:`<PackageName>_ROOT` environment variable. + The package root variables are maintained as a stack so if called from + nested find modules, root paths from the parent's find module will be + searched after paths from the current module, + i.e. ``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``, + ``<ParentPackage>_ROOT``, ``ENV{<ParentPackage>_ROOT}``, etc. This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed. See policy :policy:`CMP0074`. diff --git a/Help/command/LINK_OPTIONS_LINKER.txt b/Help/command/LINK_OPTIONS_LINKER.txt new file mode 100644 index 0000000..76927be --- /dev/null +++ b/Help/command/LINK_OPTIONS_LINKER.txt @@ -0,0 +1,10 @@ +To pass options to the linker tool, each compiler driver has is own syntax. +The ``LINKER:`` prefix can be used to specify, in a portable way, options +to pass to the linker tool. The ``LINKER:`` prefix is replaced by the required +driver option and the rest of the option string defines linker arguments using +``,`` as separator. These arguments will be formatted according to the +:variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG` and +:variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP` variables. + +For example, ``"LINKER:-z,defs"`` becomes ``-Xlinker -z -Xlinker defs`` for +``Clang`` and ``-Wl,-z,defs`` for ``GNU GCC``. diff --git a/Help/command/COMPILE_OPTIONS_SHELL.txt b/Help/command/OPTIONS_SHELL.txt index a1316c8..530c012 100644 --- a/Help/command/COMPILE_OPTIONS_SHELL.txt +++ b/Help/command/OPTIONS_SHELL.txt @@ -1,4 +1,4 @@ -The final set of compile options used for a target is constructed by +The final set of compile or link options used for a target is constructed by accumulating options from the current target and the usage requirements of it dependencies. The set of options is de-duplicated to avoid repetition. While beneficial for individual options, the de-duplication step can break diff --git a/Help/command/add_compile_options.rst b/Help/command/add_compile_options.rst index c445608..350a1c0 100644 --- a/Help/command/add_compile_options.rst +++ b/Help/command/add_compile_options.rst @@ -22,4 +22,4 @@ the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem properties. -.. include:: COMPILE_OPTIONS_SHELL.txt +.. include:: OPTIONS_SHELL.txt diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index f20b274..b7ba724 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -153,6 +153,7 @@ the interface target using the commands: * :command:`set_property`, * :command:`target_link_libraries(INTERFACE)`, +* :command:`target_link_options(INTERFACE)`, * :command:`target_include_directories(INTERFACE)`, * :command:`target_compile_options(INTERFACE)`, * :command:`target_compile_definitions(INTERFACE)`, and diff --git a/Help/command/add_link_options.rst b/Help/command/add_link_options.rst new file mode 100644 index 0000000..821198d --- /dev/null +++ b/Help/command/add_link_options.rst @@ -0,0 +1,26 @@ +add_link_options +---------------- + +Adds options to the link of targets. + +:: + + add_link_options(<option> ...) + +Adds options to the link step for targets in the current directory and below +that are added after this command is invoked. See documentation of the +:prop_dir:`directory <LINK_OPTIONS>` and +:prop_tgt:`target <LINK_OPTIONS>` ``LINK_OPTIONS`` properties. + +This command can be used to add any options, but alternative commands +exist to add libraries (:command:`target_link_libraries` or +:command:`link_libraries`). + +Arguments to ``add_link_options`` may use "generator expressions" with +the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. See the :manual:`cmake-buildsystem(7)` +manual for more on defining buildsystem properties. + +.. include:: LINK_OPTIONS_LINKER.txt + +.. include:: OPTIONS_SHELL.txt diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 53f3819..a4416ab 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -262,8 +262,10 @@ The set of installation prefixes is constructed using the following steps. If ``NO_DEFAULT_PATH`` is specified all ``NO_*`` options are enabled. -1. Search paths specified in the ``PackageName_ROOT`` CMake and environment - variables. The package root variables are maintained as a stack so if +1. Search paths specified in the :variable:`<PackageName>_ROOT` CMake + variable and the :envvar:`<PackageName>_ROOT` environment variable, + where ``<PackageName>`` is the package to be found. + The package root variables are maintained as a stack so if called from within a find module, root paths from the parent's find module will also be searched after paths for the current package. This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed. diff --git a/Help/command/install.rst b/Help/command/install.rst index 6cea996..8b2a971 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -280,6 +280,14 @@ targets that link to the object libraries in their implementation. Installing a target with the :prop_tgt:`EXCLUDE_FROM_ALL` target property set to ``TRUE`` has undefined behavior. +:command:`install(TARGETS)` can install targets that were created in +other directories. When using such cross-directory install rules, running +``make install`` (or similar) from a subdirectory will not guarantee that +targets from other directories are up-to-date. You can use +:command:`target_link_libraries` or :command:`add_dependencies` +to ensure that such out-of-directory targets are built before the +subdirectory-specific install rules are run. + The install destination given to the target install ``DESTINATION`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. @@ -427,6 +435,10 @@ example, the code will print a message during installation. +The contents of ``SCRIPT`` or ``CODE`` may use "generator expressions" with +the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. + Installing Exports ^^^^^^^^^^^^^^^^^^ diff --git a/Help/command/list.rst b/Help/command/list.rst index 589e572..ad2c428 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -28,7 +28,7 @@ Synopsis `Ordering`_ list(`REVERSE`_ <list>) - list(`SORT`_ <list>) + list(`SORT`_ <list> [...]) Introduction ^^^^^^^^^^^^ @@ -253,7 +253,23 @@ Reverses the contents of the list in-place. :: - list(SORT <list>) - + list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>]) Sorts the list in-place alphabetically. +Use the option ``<compare>`` to select the compare type for sorting. +The ``<compare>`` option may be one of: + +* ``STRING``: Sorts a list of strings alphabetically. +* ``FILE_BASENAME``: Sort a list of pathnames of files by their basenames. + +Use the option ``<case>`` to select a case sensitive or case insensitive sort mode. +The ``<case>`` option may be one of: + +* ``SENSITIVE``: Sorts the list alphabetically. +* ``INSENSITIVE``: Sorts the list alphabetically in descending order. + +Use the option ``<order>`` to select a case sensitive or case insensitive sort mode. +The ``<order>`` option may be one of: + +* ``ASCENDING``: Sorts the list in ascending order. +* ``DESCENDING``: Sorts the list in descending order. diff --git a/Help/command/math.rst b/Help/command/math.rst index f99dc3d..63af931 100644 --- a/Help/command/math.rst +++ b/Help/command/math.rst @@ -5,10 +5,26 @@ Mathematical expressions. :: - math(EXPR <output-variable> <math-expression>) + math(EXPR <output-variable> <math-expression> [OUTPUT_FORMAT <format>]) ``EXPR`` evaluates mathematical expression and returns result in the output variable. Example mathematical expression is ``5 * (10 + 13)``. Supported operators are ``+``, ``-``, ``*``, ``/``, ``%``, ``|``, ``&``, ``^``, ``~``, ``<<``, ``>>``, and ``(...)``. They have the same meaning as they do in C code. + +Numeric constants are evaluated in decimal or hexadecimal representation. + +The result is formatted according to the option "OUTPUT_FORMAT" , +where ``<format>`` is one of: +:: + + HEXADECIMAL = Result in output variable will be formatted in C code + Hexadecimal notation. + DECIMAL = Result in output variable will be formatted in decimal notation. + + +For example:: + + math(EXPR value "100 * 0xA" DECIMAL) results in value is set to "1000" + math(EXPR value "100 * 0xA" HEXADECIMAL) results in value is set to "0x3e8" diff --git a/Help/command/option.rst b/Help/command/option.rst index 91cd0a7..4fabb87 100644 --- a/Help/command/option.rst +++ b/Help/command/option.rst @@ -9,7 +9,9 @@ Provides an option that the user can optionally select. [initial value]) Provide an option for the user to select as ``ON`` or ``OFF``. If no -initial value is provided, ``OFF`` is used. +initial value is provided, ``OFF`` is used. If the option is already +set as a normal variable then the command does nothing +(see policy :policy:`CMP0077`). If you have options that depend on the values of other options, see the module help for :module:`CMakeDependentOption`. diff --git a/Help/command/string.rst b/Help/command/string.rst index efa923b..29a153a 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -151,6 +151,20 @@ has lower precedence than concatenation. This means that the regular expression ``^ab+d$`` matches ``abbd`` but not ``ababd``, and the regular expression ``^(ab|cd)$`` matches ``ab`` but not ``abd``. +Backslash (``\``) characters in regular expressions are interpreted +literally and do not escape anything or represent placeholders. +However, CMake language :ref:`Escape Sequences` such as ``\t``, +``\r``, ``\n``, and ``\\`` may be used to construct literal tabs, +carriage returns, newlines, and backslashes (respectively) to pass +in a regex. For example: + +* The quoted argument ``"[ \t\r\n]"`` specifies a regex that matches + any single whitespace character. +* The quoted argument ``"[/\\]"`` specifies a regex that matches + a single forward slash ``/`` or backslash ``\``. +* The quoted argument ``"[A-Za-z0-9_]"`` specifies a regex that matches + any single "word" character in the C locale. + Manipulation ^^^^^^^^^^^^ diff --git a/Help/command/target_compile_options.rst b/Help/command/target_compile_options.rst index 194d008..88b7f15 100644 --- a/Help/command/target_compile_options.rst +++ b/Help/command/target_compile_options.rst @@ -39,4 +39,4 @@ with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem properties. -.. include:: COMPILE_OPTIONS_SHELL.txt +.. include:: OPTIONS_SHELL.txt diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index fcc2c07..1f0d69e 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -70,7 +70,8 @@ Each ``<item>`` may be: Link flags specified here are inserted into the link command in the same place as the link libraries. This might not be correct, depending on - the linker. Use the :prop_tgt:`LINK_FLAGS` target property to add link + the linker. Use the :prop_tgt:`LINK_OPTIONS` target property or + :command:`target_link_options` command to add link flags explicitly. The flags will then be placed at the toolchain-defined flag position in the link command. diff --git a/Help/command/target_link_options.rst b/Help/command/target_link_options.rst new file mode 100644 index 0000000..8f47180 --- /dev/null +++ b/Help/command/target_link_options.rst @@ -0,0 +1,42 @@ +target_link_options +------------------- + +Add link options to a target. + +:: + + target_link_options(<target> [BEFORE] + <INTERFACE|PUBLIC|PRIVATE> [items1...] + [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) + +Specify link options to use when linking a given target. The +named ``<target>`` must have been created by a command such as +:command:`add_executable` or :command:`add_library` and must not be an +:ref:`ALIAS target <Alias Targets>`. + +If ``BEFORE`` is specified, the content will be prepended to the property +instead of being appended. + +This command can be used to add any options, but +alternative commands exist to add libraries +(:command:`target_link_libraries` and :command:`link_libraries`). +See documentation of the :prop_dir:`directory <LINK_OPTIONS>` and +:prop_tgt:`target <LINK_OPTIONS>` ``LINK_OPTIONS`` properties. + +The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to +specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` +items will populate the :prop_tgt:`LINK_OPTIONS` property of +``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the +:prop_tgt:`INTERFACE_LINK_OPTIONS` property of ``<target>``. +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.) +The following arguments specify link options. Repeated calls for the same +``<target>`` append items in the order called. + +Arguments to ``target_link_options`` may use "generator expressions" +with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. See the :manual:`cmake-buildsystem(7)` +manual for more on defining buildsystem properties. + +.. include:: LINK_OPTIONS_LINKER.txt + +.. include:: OPTIONS_SHELL.txt diff --git a/Help/command/target_sources.rst b/Help/command/target_sources.rst index a4f5196..5dd8d86 100644 --- a/Help/command/target_sources.rst +++ b/Help/command/target_sources.rst @@ -9,7 +9,9 @@ Add sources to a target. <INTERFACE|PUBLIC|PRIVATE> [items1...] [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) -Specify sources to use when compiling a given target. The +Specify sources to use when compiling a given target. Relative +source file paths are interpreted as being relative to the current +source directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`). The named ``<target>`` must have been created by a command such as :command:`add_executable` or :command:`add_library` and must not be an :ref:`ALIAS target <Alias Targets>`. @@ -27,3 +29,6 @@ Arguments to ``target_sources`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem properties. + +See also the :policy:`CMP0076` policy for older behavior related to the +handling of relative source file paths. diff --git a/Help/cpack_gen/archive.rst b/Help/cpack_gen/archive.rst new file mode 100644 index 0000000..b288aad --- /dev/null +++ b/Help/cpack_gen/archive.rst @@ -0,0 +1,35 @@ +CPack Archive Generator +----------------------- + +Archive CPack generator that supports packaging of sources and binaries in +different formats: + + - 7Z - 7zip - (.7z) + - TBZ2 (.tar.bz2) + - TGZ (.tar.gz) + - TXZ (.tar.xz) + - TZ (.tar.Z) + - ZIP (.zip) + +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 '-' + +.. 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. diff --git a/Help/cpack_gen/bundle.rst b/Help/cpack_gen/bundle.rst new file mode 100644 index 0000000..4628968 --- /dev/null +++ b/Help/cpack_gen/bundle.rst @@ -0,0 +1,64 @@ +CPack Bundle Generator +---------------------- + +CPack Bundle generator (Mac OS X) specific options + +Variables specific to CPack Bundle generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Installers built on Mac OS X using the Bundle generator use the +aforementioned DragNDrop (CPACK_DMG_xxx) variables, plus the following +Bundle-specific parameters (CPACK_BUNDLE_xxx). + +.. variable:: CPACK_BUNDLE_NAME + + The name of the generated bundle. This appears in the OSX finder as the + bundle name. Required. + +.. variable:: CPACK_BUNDLE_PLIST + + Path to an OSX plist file that will be used for the generated bundle. This + assumes that the caller has generated or specified their own Info.plist + file. Required. + +.. variable:: CPACK_BUNDLE_ICON + + Path to an OSX icon file that will be used as the icon for the generated + bundle. This is the icon that appears in the OSX finder for the bundle, and + in the OSX dock when the bundle is opened. Required. + +.. variable:: CPACK_BUNDLE_STARTUP_COMMAND + + Path to a startup script. This is a path to an executable or script that + will be run whenever an end-user double-clicks the generated bundle in the + OSX Finder. Optional. + +.. variable:: CPACK_BUNDLE_APPLE_CERT_APP + + The name of your Apple supplied code signing certificate for the application. + The name usually takes the form "Developer ID Application: [Name]" or + "3rd Party Mac Developer Application: [Name]". If this variable is not set + the application will not be signed. + +.. variable:: CPACK_BUNDLE_APPLE_ENTITLEMENTS + + The name of the plist file that contains your apple entitlements for sandboxing + your application. This file is required for submission to the Mac App Store. + +.. variable:: CPACK_BUNDLE_APPLE_CODESIGN_FILES + + A list of additional files that you wish to be signed. You do not need to + list the main application folder, or the main executable. You should + list any frameworks and plugins that are included in your app bundle. + +.. variable:: CPACK_BUNDLE_APPLE_CODESIGN_PARAMETER + + Additional parameter that will passed to codesign. + Default value: "--deep -f" + +.. variable:: CPACK_COMMAND_CODESIGN + + Path to the codesign(1) command used to sign applications with an + Apple cert. This variable can be used to override the automatically + detected command (or specify its location if the auto-detection fails + to find it.) diff --git a/Help/cpack_gen/cygwin.rst b/Help/cpack_gen/cygwin.rst new file mode 100644 index 0000000..1c5f7af --- /dev/null +++ b/Help/cpack_gen/cygwin.rst @@ -0,0 +1,23 @@ +CPack Cygwin Generator +---------------------- + +Cygwin CPack generator (Cygwin). + +Variables specific to CPack Cygwin generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The +following variable is specific to installers build on and/or for +Cygwin: + +.. variable:: CPACK_CYGWIN_PATCH_NUMBER + + The Cygwin patch number. FIXME: This documentation is incomplete. + +.. variable:: CPACK_CYGWIN_PATCH_FILE + + The Cygwin patch file. FIXME: This documentation is incomplete. + +.. variable:: CPACK_CYGWIN_BUILD_SCRIPT + + The Cygwin build script. FIXME: This documentation is incomplete. diff --git a/Help/cpack_gen/deb.rst b/Help/cpack_gen/deb.rst new file mode 100644 index 0000000..37d750d --- /dev/null +++ b/Help/cpack_gen/deb.rst @@ -0,0 +1,537 @@ +CPack Deb Generator +------------------- + +The built in (binary) CPack Deb generator (Unix only) + +Variables specific to CPack Debian (DEB) generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The CPack Deb generator may be used to create Deb package using :module:`CPack`. +The CPack Deb generator is a :module:`CPack` generator thus it uses the +``CPACK_XXX`` variables used by :module:`CPack`. + +The CPack Deb generator should work on any Linux host but it will produce +better deb package when Debian specific tools ``dpkg-xxx`` are usable on +the build system. + +The CPack Deb generator has specific features which are controlled by the +specifics :code:`CPACK_DEBIAN_XXX` variables. + +:code:`CPACK_DEBIAN_<COMPONENT>_XXXX` variables may be used in order to have +**component** specific values. Note however that ``<COMPONENT>`` refers to +the **grouping name** written in upper case. It may be either a component name +or a component GROUP name. + +Here are some CPack Deb generator wiki resources that are here for historic +reasons and are no longer maintained but may still prove useful: + + - https://gitlab.kitware.com/cmake/community/wikis/doc/cpack/Configuration + - https://gitlab.kitware.com/cmake/community/wikis/doc/cpack/PackageGenerators#deb-unix-only + +List of CPack Deb generator specific variables: + +.. variable:: CPACK_DEB_COMPONENT_INSTALL + + Enable component packaging for CPackDEB + + * Mandatory : NO + * Default : OFF + + If enabled (ON) multiple packages are generated. By default a single package + containing files of all components is generated. + +.. variable:: CPACK_DEBIAN_PACKAGE_NAME + CPACK_DEBIAN_<COMPONENT>_PACKAGE_NAME + + Set Package control field (variable is automatically transformed to lower + case). + + * Mandatory : YES + * Default : + + - :variable:`CPACK_PACKAGE_NAME` for non-component based + installations + - :variable:`CPACK_DEBIAN_PACKAGE_NAME` suffixed with -<COMPONENT> + for component-based installations. + + See https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Source + +.. variable:: CPACK_DEBIAN_FILE_NAME + CPACK_DEBIAN_<COMPONENT>_FILE_NAME + + Package file name. + + * Mandatory : YES + * Default : ``<CPACK_PACKAGE_FILE_NAME>[-<component>].deb`` + + This may be set to ``DEB-DEFAULT`` to allow the CPack Deb generator to generate + package file name by itself in deb format:: + + <PackageName>_<VersionNumber>-<DebianRevisionNumber>_<DebianArchitecture>.deb + + Alternatively provided package file name must end + with either ``.deb`` or ``.ipk`` suffix. + + .. note:: + + Preferred setting of this variable is ``DEB-DEFAULT`` but for backward + compatibility with the CPack Deb generator in CMake prior to version 3.6 this + feature is disabled by default. + + .. note:: + + By using non default filenames duplicate names may occur. Duplicate files + get overwritten and it is up to the packager to set the variables in a + manner that will prevent such errors. + +.. variable:: CPACK_DEBIAN_PACKAGE_EPOCH + + The Debian package epoch + + * Mandatory : No + * Default : - + + Optional number that should be incremented when changing versioning schemas + or fixing mistakes in the version numbers of older packages. + +.. variable:: CPACK_DEBIAN_PACKAGE_VERSION + + The Debian package version + + * Mandatory : YES + * Default : :variable:`CPACK_PACKAGE_VERSION` + + This variable may contain only alphanumerics (A-Za-z0-9) and the characters + . + - ~ (full stop, plus, hyphen, tilde) and should start with a digit. If + :variable:`CPACK_DEBIAN_PACKAGE_RELEASE` is not set then hyphens are not + allowed. + + .. note:: + + For backward compatibility with CMake 3.9 and lower a failed test of this + variable's content is not a hard error when both + :variable:`CPACK_DEBIAN_PACKAGE_RELEASE` and + :variable:`CPACK_DEBIAN_PACKAGE_EPOCH` variables are not set. An author + warning is reported instead. + +.. variable:: CPACK_DEBIAN_PACKAGE_RELEASE + + The Debian package release - Debian revision number. + + * Mandatory : No + * Default : - + + This is the numbering of the DEB package itself, i.e. the version of the + packaging and not the version of the content (see + :variable:`CPACK_DEBIAN_PACKAGE_VERSION`). One may change the default value + if the previous packaging was buggy and/or you want to put here a fancy Linux + distro specific numbering. + +.. variable:: CPACK_DEBIAN_PACKAGE_ARCHITECTURE + CPACK_DEBIAN_<COMPONENT>_PACKAGE_ARCHITECTURE + + The Debian package architecture + + * Mandatory : YES + * Default : Output of :code:`dpkg --print-architecture` (or :code:`i386` + if :code:`dpkg` is not found) + +.. variable:: CPACK_DEBIAN_PACKAGE_DEPENDS + CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS + + Sets the Debian dependencies of this package. + + * Mandatory : NO + * Default : + + - An empty string for non-component based installations + - :variable:`CPACK_DEBIAN_PACKAGE_DEPENDS` for component-based + installations. + + .. note:: + + If :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS` or + more specifically :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS` + is set for this component, the discovered dependencies will be appended + to :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS` instead of + :variable:`CPACK_DEBIAN_PACKAGE_DEPENDS`. If + :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS` is an empty string, + only the automatically discovered dependencies will be set for this + component. + + Example:: + + set(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libc6 (< 2.4)") + +.. variable:: CPACK_DEBIAN_ENABLE_COMPONENT_DEPENDS + + Sets inter component dependencies if listed with + :variable:`CPACK_COMPONENT_<compName>_DEPENDS` variables. + + * Mandatory : NO + * Default : - + +.. variable:: CPACK_DEBIAN_PACKAGE_MAINTAINER + + The Debian package maintainer + + * Mandatory : YES + * Default : :code:`CPACK_PACKAGE_CONTACT` + +.. variable:: CPACK_DEBIAN_PACKAGE_DESCRIPTION + CPACK_COMPONENT_<COMPONENT>_DESCRIPTION + + The Debian package description + + * Mandatory : YES + * Default : + + - :variable:`CPACK_DEBIAN_PACKAGE_DESCRIPTION` if set or + - :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` + + +.. variable:: CPACK_DEBIAN_PACKAGE_SECTION + CPACK_DEBIAN_<COMPONENT>_PACKAGE_SECTION + + Set Section control field e.g. admin, devel, doc, ... + + * Mandatory : YES + * Default : "devel" + + See https://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections + +.. variable:: CPACK_DEBIAN_ARCHIVE_TYPE + + The archive format used for creating the Debian package. + + * Mandatory : YES + * Default : "paxr" + + Possible values are: + + - paxr + - gnutar + + .. note:: + + Default pax archive format is the most portable format and generates + packages that do not treat sparse files specially. + GNU tar format on the other hand supports longer filenames. + +.. variable:: CPACK_DEBIAN_COMPRESSION_TYPE + + The compression used for creating the Debian package. + + * Mandatory : YES + * Default : "gzip" + + Possible values are: + + - lzma + - xz + - bzip2 + - gzip + +.. variable:: CPACK_DEBIAN_PACKAGE_PRIORITY + CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY + + Set Priority control field e.g. required, important, standard, optional, + extra + + * Mandatory : YES + * Default : "optional" + + See https://www.debian.org/doc/debian-policy/ch-archive.html#s-priorities + +.. variable:: CPACK_DEBIAN_PACKAGE_HOMEPAGE + + The URL of the web site for this package, preferably (when applicable) the + site from which the original source can be obtained and any additional + upstream documentation or information may be found. + + * Mandatory : NO + * Default : :variable:`CMAKE_PROJECT_HOMEPAGE_URL` + + .. note:: + + The content of this field is a simple URL without any surrounding + characters such as <>. + +.. variable:: CPACK_DEBIAN_PACKAGE_SHLIBDEPS + CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS + + May be set to ON in order to use :code:`dpkg-shlibdeps` to generate + better package dependency list. + + * Mandatory : NO + * Default : + + - :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS` if set or + - OFF + + .. note:: + + You may need set :variable:`CMAKE_INSTALL_RPATH` to an appropriate value + if you use this feature, because if you don't :code:`dpkg-shlibdeps` + may fail to find your own shared libs. + See https://gitlab.kitware.com/cmake/community/wikis/doc/cmake/RPATH-handling + +.. variable:: CPACK_DEBIAN_PACKAGE_DEBUG + + May be set when invoking cpack in order to trace debug information + during the CPack Deb generator run. + + * Mandatory : NO + * Default : - + +.. variable:: CPACK_DEBIAN_PACKAGE_PREDEPENDS + CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS + + Sets the `Pre-Depends` field of the Debian package. + Like :variable:`Depends <CPACK_DEBIAN_PACKAGE_DEPENDS>`, except that it + also forces :code:`dpkg` to complete installation of the packages named + before even starting the installation of the package which declares the + pre-dependency. + + * Mandatory : NO + * Default : + + - An empty string for non-component based installations + - :variable:`CPACK_DEBIAN_PACKAGE_PREDEPENDS` for component-based + installations. + + See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps + +.. variable:: CPACK_DEBIAN_PACKAGE_ENHANCES + CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES + + Sets the `Enhances` field of the Debian package. + Similar to :variable:`Suggests <CPACK_DEBIAN_PACKAGE_SUGGESTS>` but works + in the opposite direction: declares that a package can enhance the + functionality of another package. + + * Mandatory : NO + * Default : + + - An empty string for non-component based installations + - :variable:`CPACK_DEBIAN_PACKAGE_ENHANCES` for component-based + installations. + + See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps + +.. variable:: CPACK_DEBIAN_PACKAGE_BREAKS + CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS + + Sets the `Breaks` field of the Debian package. + When a binary package (P) declares that it breaks other packages (B), + :code:`dpkg` will not allow the package (P) which declares `Breaks` be + **unpacked** unless the packages that will be broken (B) are deconfigured + first. + As long as the package (P) is configured, the previously deconfigured + packages (B) cannot be reconfigured again. + + * Mandatory : NO + * Default : + + - An empty string for non-component based installations + - :variable:`CPACK_DEBIAN_PACKAGE_BREAKS` for component-based + installations. + + See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-breaks + +.. variable:: CPACK_DEBIAN_PACKAGE_CONFLICTS + CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONFLICTS + + Sets the `Conflicts` field of the Debian package. + When one binary package declares a conflict with another using a `Conflicts` + field, :code:`dpkg` will not allow them to be unpacked on the system at + the same time. + + * Mandatory : NO + * Default : + + - An empty string for non-component based installations + - :variable:`CPACK_DEBIAN_PACKAGE_CONFLICTS` for component-based + installations. + + See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-conflicts + + .. note:: + + This is a stronger restriction than + :variable:`Breaks <CPACK_DEBIAN_PACKAGE_BREAKS>`, which prevents the + broken package from being configured while the breaking package is in + the "Unpacked" state but allows both packages to be unpacked at the same + time. + +.. variable:: CPACK_DEBIAN_PACKAGE_PROVIDES + CPACK_DEBIAN_<COMPONENT>_PACKAGE_PROVIDES + + Sets the `Provides` field of the Debian package. + A virtual package is one which appears in the `Provides` control field of + another package. + + * Mandatory : NO + * Default : + + - An empty string for non-component based installations + - :variable:`CPACK_DEBIAN_PACKAGE_PROVIDES` for component-based + installations. + + See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-virtual + +.. variable:: CPACK_DEBIAN_PACKAGE_REPLACES + CPACK_DEBIAN_<COMPONENT>_PACKAGE_REPLACES + + Sets the `Replaces` field of the Debian package. + Packages can declare in their control file that they should overwrite + files in certain other packages, or completely replace other packages. + + * Mandatory : NO + * Default : + + - An empty string for non-component based installations + - :variable:`CPACK_DEBIAN_PACKAGE_REPLACES` for component-based + installations. + + See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps + +.. variable:: CPACK_DEBIAN_PACKAGE_RECOMMENDS + CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS + + Sets the `Recommends` field of the Debian package. + Allows packages to declare a strong, but not absolute, dependency on other + packages. + + * Mandatory : NO + * Default : + + - An empty string for non-component based installations + - :variable:`CPACK_DEBIAN_PACKAGE_RECOMMENDS` for component-based + installations. + + See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps + +.. variable:: CPACK_DEBIAN_PACKAGE_SUGGESTS + CPACK_DEBIAN_<COMPONENT>_PACKAGE_SUGGESTS + + Sets the `Suggests` field of the Debian package. + Allows packages to declare a suggested package install grouping. + + * Mandatory : NO + * Default : + + - An empty string for non-component based installations + - :variable:`CPACK_DEBIAN_PACKAGE_SUGGESTS` for component-based + installations. + + See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps + +.. variable:: CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS + + * Mandatory : NO + * Default : OFF + + Allows to generate shlibs control file automatically. Compatibility is defined by + :variable:`CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS_POLICY` variable value. + + .. note:: + + Libraries are only considered if they have both library name and version + set. This can be done by setting SOVERSION property with + :command:`set_target_properties` command. + +.. variable:: CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS_POLICY + + Compatibility policy for auto-generated shlibs control file. + + * Mandatory : NO + * Default : "=" + + Defines compatibility policy for auto-generated shlibs control file. + Possible values: "=", ">=" + + See https://www.debian.org/doc/debian-policy/ch-sharedlibs.html#s-sharedlibs-shlibdeps + +.. variable:: CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA + CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_EXTRA + + This variable allow advanced user to add custom script to the + control.tar.gz. + Typical usage is for conffiles, postinst, postrm, prerm. + + * Mandatory : NO + * Default : - + + Usage:: + + set(CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA + "${CMAKE_CURRENT_SOURCE_DIR}/prerm;${CMAKE_CURRENT_SOURCE_DIR}/postrm") + + .. note:: + + The original permissions of the files will be used in the final + package unless the variable + :variable:`CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION` is set. + In particular, the scripts should have the proper executable + flag prior to the generation of the package. + +.. variable:: CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION + CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_STRICT_PERMISSION + + This variable indicates if the Debian policy on control files should be + strictly followed. + + * Mandatory : NO + * Default : FALSE + + Usage:: + + set(CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION TRUE) + + .. note:: + + This overrides the permissions on the original files, following the rules + set by Debian policy + https://www.debian.org/doc/debian-policy/ch-files.html#s-permissions-owners + +.. variable:: CPACK_DEBIAN_PACKAGE_SOURCE + CPACK_DEBIAN_<COMPONENT>_PACKAGE_SOURCE + + Sets the ``Source`` field of the binary Debian package. + When the binary package name is not the same as the source package name + (in particular when several components/binaries are generated from one + source) the source from which the binary has been generated should be + indicated with the field ``Source``. + + * Mandatory : NO + * Default : + + - An empty string for non-component based installations + - :variable:`CPACK_DEBIAN_PACKAGE_SOURCE` for component-based + installations. + + See https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Source + + .. note:: + + This value is not interpreted. It is possible to pass an optional + revision number of the referenced source package as well. + +Building Debian packages on Windows +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To communicate UNIX file permissions from the install stage +to the CPack DEB generator the "cmake_mode_t" NTFS +alternate data stream (ADT) is used. + +When a filesystem without ADT support is used only owner read/write +permissions can be preserved. + +Reproducible packages +^^^^^^^^^^^^^^^^^^^^^ + +The environment variable ``SOURCE_DATE_EPOCH`` may be set to a UNIX +timestamp, defined as the number of seconds, excluding leap seconds, +since 01 Jan 1970 00:00:00 UTC. If set, the CPack Deb generator will +use its value for timestamps in the package. diff --git a/Help/cpack_gen/dmg.rst b/Help/cpack_gen/dmg.rst new file mode 100644 index 0000000..e4482ef --- /dev/null +++ b/Help/cpack_gen/dmg.rst @@ -0,0 +1,101 @@ +CPack DMG Generator +------------------- + +DragNDrop CPack generator (Mac OS X). + +Variables specific to CPack DragNDrop generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following variables are specific to the DragNDrop installers built +on Mac OS X: + +.. variable:: CPACK_DMG_VOLUME_NAME + + The volume name of the generated disk image. Defaults to + CPACK_PACKAGE_FILE_NAME. + +.. variable:: CPACK_DMG_FORMAT + + The disk image format. Common values are UDRO (UDIF read-only), UDZO (UDIF + zlib-compressed) or UDBZ (UDIF bzip2-compressed). Refer to hdiutil(1) for + more information on other available formats. Defaults to UDZO. + +.. variable:: CPACK_DMG_DS_STORE + + Path to a custom DS_Store file. This .DS_Store file e.g. can be used to + specify the Finder window position/geometry and layout (such as hidden + toolbars, placement of the icons etc.). This file has to be generated by + the Finder (either manually or through AppleScript) using a normal folder + from which the .DS_Store file can then be extracted. + +.. variable:: CPACK_DMG_DS_STORE_SETUP_SCRIPT + + Path to a custom AppleScript file. This AppleScript is used to generate + a .DS_Store file which specifies the Finder window position/geometry and + layout (such as hidden toolbars, placement of the icons etc.). + By specifying a custom AppleScript there is no need to use + CPACK_DMG_DS_STORE, as the .DS_Store that is generated by the AppleScript + will be packaged. + +.. variable:: CPACK_DMG_BACKGROUND_IMAGE + + Path to an image file to be used as the background. This file will be + copied to .background/background.<ext>, where ext is the original image file + extension. The background image is installed into the image before + CPACK_DMG_DS_STORE_SETUP_SCRIPT is executed or CPACK_DMG_DS_STORE is + installed. By default no background image is set. + +.. variable:: CPACK_DMG_DISABLE_APPLICATIONS_SYMLINK + + Default behaviour is to include a symlink to ``/Applications`` in the DMG. + Set this option to ``ON`` to avoid adding the symlink. + +.. variable:: CPACK_DMG_SLA_DIR + + Directory where license and menu files for different languages are stored. + Setting this causes CPack to look for a ``<language>.menu.txt`` and + ``<language>.license.txt`` file for every language defined in + ``CPACK_DMG_SLA_LANGUAGES``. If both this variable and + ``CPACK_RESOURCE_FILE_LICENSE`` are set, CPack will only look for the menu + files and use the same license file for all languages. + +.. variable:: CPACK_DMG_SLA_LANGUAGES + + Languages for which a license agreement is provided when mounting the + generated DMG. A menu file consists of 9 lines of text. The first line is + is the name of the language itself, uppercase, in English (e.g. German). + The other lines are translations of the following strings: + + - Agree + - Disagree + - Print + - Save... + - You agree to the terms of the License Agreement when you click the + "Agree" button. + - Software License Agreement + - This text cannot be saved. The disk may be full or locked, or the file + may be locked. + - Unable to print. Make sure you have selected a printer. + + For every language in this list, CPack will try to find files + ``<language>.menu.txt`` and ``<language>.license.txt`` in the directory + specified by the :variable:`CPACK_DMG_SLA_DIR` variable. + +.. variable:: CPACK_COMMAND_HDIUTIL + + Path to the hdiutil(1) command used to operate on disk image files on Mac + OS X. This variable can be used to override the automatically detected + command (or specify its location if the auto-detection fails to find it.) + +.. variable:: CPACK_COMMAND_SETFILE + + Path to the SetFile(1) command used to set extended attributes on files and + directories on Mac OS X. This variable can be used to override the + automatically detected command (or specify its location if the + auto-detection fails to find it.) + +.. variable:: CPACK_COMMAND_REZ + + Path to the Rez(1) command used to compile resources on Mac OS X. This + variable can be used to override the automatically detected command (or + specify its location if the auto-detection fails to find it.) diff --git a/Help/cpack_gen/external.rst b/Help/cpack_gen/external.rst new file mode 100644 index 0000000..a69866d --- /dev/null +++ b/Help/cpack_gen/external.rst @@ -0,0 +1,249 @@ +CPack External Generator +------------------------ + +CPack provides many generators to create packages for a variety of platforms +and packaging systems. The intention is for CMake/CPack to be a complete +end-to-end solution for building and packaging a software project. However, it +may not always be possible to use CPack for the entire packaging process, due +to either technical limitations or policies that require the use of certain +tools. For this reason, CPack provides the "External" generator, which allows +external packaging software to take advantage of some of the functionality +provided by CPack, such as component installation and the dependency graph. + +The CPack External generator doesn't actually package any files. Instead, it +generates a .json file containing the CPack internal metadata, which gives +external software information on how to package the software. This metadata +file contains a list of CPack components and component groups, the various +options passed to :command:`cpack_add_component` and +:command:`cpack_add_component_group`, the dependencies between the components +and component groups, and various other options passed to CPack. + +Format +^^^^^^ + +The file produced by the CPack External generator is a .json file with an +object as its root. This root object will always provide two fields: +``formatVersionMajor`` and ``formatVersionMinor``, which are always integers +that describe the output format of the generator. Backwards-compatible changes +to the output format (for example, adding a new field that didn't exist before) +cause the minor version to be incremented, and backwards-incompatible changes +(for example, deleting a field or changing its meaning) cause the major version +to be incremented and the minor version reset to 0. The format version is +always of the format ``major.minor``. In other words, it always has exactly two +parts, separated by a period. + +You can request one or more specific versions of the output format as described +below with :variable:`CPACK_EXT_REQUESTED_VERSIONS`. The output format will +have a major version that exactly matches the requested major version, and a +minor version that is greater than or equal to the requested minor version. If +no version is requested with :variable:`CPACK_EXT_REQUESTED_VERSIONS`, the +latest known major version is used by default. Currently, the only supported +format is 1.0, which is described below. + +Version 1.0 +*********** + +In addition to the standard format fields, format version 1.0 provides the +following fields in the root: + +``components`` + The ``components`` field is an object with component names as the keys and + objects describing the components as the values. The component objects have + the following fields: + + ``name`` + The name of the component. This is always the same as the key in the + ``components`` object. + + ``displayName`` + The value of the ``DISPLAY_NAME`` field passed to + :command:`cpack_add_component`. + + ``description`` + The value of the ``DESCRIPTION`` field passed to + :command:`cpack_add_component`. + + ``isHidden`` + True if ``HIDDEN`` was passed to :command:`cpack_add_component`, false if + it was not. + + ``isRequired`` + True if ``REQUIRED`` was passed to :command:`cpack_add_component`, false if + it was not. + + ``isDisabledByDefault`` + True if ``DISABLED`` was passed to :command:`cpack_add_component`, false if + it was not. + + ``group`` + Only present if ``GROUP`` was passed to :command:`cpack_add_component`. If + so, this field is a string value containing the component's group. + + ``dependencies`` + An array of components the component depends on. This contains the values + in the ``DEPENDS`` argument passed to :command:`cpack_add_component`. If no + ``DEPENDS`` argument was passed, this is an empty list. + + ``installationTypes`` + An array of installation types the component is part of. This contains the + values in the ``INSTALL_TYPES`` argument passed to + :command:`cpack_add_component`. If no ``INSTALL_TYPES`` argument was + passed, this is an empty list. + + ``isDownloaded`` + True if ``DOWNLOADED`` was passed to :command:`cpack_add_component`, false + if it was not. + + ``archiveFile`` + The name of the archive file passed with the ``ARCHIVE_FILE`` argument to + :command:`cpack_add_component`. If no ``ARCHIVE_FILE`` argument was passed, + this is an empty string. + +``componentGroups`` + The ``componentGroups`` field is an object with component group names as the + keys and objects describing the component groups as the values. The component + group objects have the following fields: + + ``name`` + The name of the component group. This is always the same as the key in the + ``componentGroups`` object. + + ``displayName`` + The value of the ``DISPLAY_NAME`` field passed to + :command:`cpack_add_component_group`. + + ``description`` + The value of the ``DESCRIPTION`` field passed to + :command:`cpack_add_component_group`. + + ``parentGroup`` + Only present if ``PARENT_GROUP`` was passed to + :command:`cpack_add_component_group`. If so, this field is a string value + containing the component group's parent group. + + ``isExpandedByDefault`` + True if ``EXPANDED`` was passed to :command:`cpack_add_component_group`, + false if it was not. + + ``isBold`` + True if ``BOLD_TITLE`` was passed to :command:`cpack_add_component_group`, + false if it was not. + + ``components`` + An array of names of components that are direct members of the group + (components that have this group as their ``GROUP``). Components of + subgroups are not included. + + ``subgroups`` + An array of names of component groups that are subgroups of the group + (groups that have this group as their ``PARENT_GROUP``). + +``installationTypes`` + The ``installationTypes`` field is an object with installation type names as + the keys and objects describing the installation types as the values. The + installation type objects have the following fields: + + ``name`` + The name of the installation type. This is always the same as the key in + the ``installationTypes`` object. + + ``displayName`` + The value of the ``DISPLAY_NAME`` field passed to + :command:`cpack_add_install_type`. + + ``index`` + The integer index of the installation type in the list. + +``projects`` + The ``projects`` field is an array of objects describing CMake projects which + comprise the CPack project. The values in this field are derived from + :variable:`CPACK_INSTALL_CMAKE_PROJECTS`. In most cases, this will be only a + single project. The project objects have the following fields: + + ``projectName`` + The project name passed to :variable:`CPACK_INSTALL_CMAKE_PROJECTS`. + + ``component`` + The name of the component or component set which comprises the project. + + ``directory`` + The build directory of the CMake project. This is the directory which + contains the ``cmake_install.cmake`` script. + + ``subDirectory`` + The subdirectory to install the project into inside the CPack package. + +``packageName`` + The package name given in :variable:`CPACK_PACKAGE_NAME`. Only present if + this option is set. + +``packageVersion`` + The package version given in :variable:`CPACK_PACKAGE_VERSION`. Only present + if this option is set. + +``packageDescriptionFile`` + The package description file given in + :variable:`CPACK_PACKAGE_DESCRIPTION_FILE`. Only present if this option is + set. + +``packageDescriptionSummary`` + The package description summary given in + :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`. Only present if this option is + set. + +``buildConfig`` + The build configuration given to CPack with the ``-C`` option. Only present + if this option is set. + +``defaultDirectoryPermissions`` + The default directory permissions given in + :variable:`CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS`. Only present if this + option is set. + +``setDestdir`` + True if :variable:`CPACK_SET_DESTDIR` is true, false if it is not. + +``packagingInstallPrefix`` + The install prefix given in :variable:`CPACK_PACKAGING_INSTALL_PREFIX`. Only + present if :variable:`CPACK_SET_DESTDIR` is true. + +``stripFiles`` + True if :variable:`CPACK_STRIP_FILES` is true, false if it is not. + +``warnOnAbsoluteInstallDestination`` + True if :variable:`CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION` is true, false + if it is not. + +``errorOnAbsoluteInstallDestination`` + True if :variable:`CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION` is true, + false if it is not. + +Variables specific to CPack External generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. variable:: CPACK_EXT_REQUESTED_VERSIONS + + This variable is used to request a specific version of the CPack External + generator. It is a list of ``major.minor`` values, separated by semicolons. + + If this variable is set to a non-empty value, the CPack External generator + will iterate through each item in the list to search for a version that it + knows how to generate. Requested versions should be listed in order of + descending preference by the client software, as the first matching version + in the list will be generated. + + The generator knows how to generate the version if it has a versioned + generator whose major version exactly matches the requested major version, + and whose minor version is greater than or equal to the requested minor + version. For example, if ``CPACK_EXT_REQUESTED_VERSIONS`` contains 1.0, and + the CPack External generator knows how to generate 1.1, it will generate 1.1. + If the generator doesn't know how to generate a version in the list, it skips + the version and looks at the next one. If it doesn't know how to generate any + of the requested versions, an error is thrown. + + If this variable is not set, or is empty, the CPack External generator will + generate the highest major and minor version that it knows how to generate. + + If an invalid version is encountered in ``CPACK_EXT_REQUESTED_VERSIONS`` (one + that doesn't match ``major.minor``, where ``major`` and ``minor`` are + integers), it is ignored. diff --git a/Help/cpack_gen/freebsd.rst b/Help/cpack_gen/freebsd.rst new file mode 100644 index 0000000..2419057 --- /dev/null +++ b/Help/cpack_gen/freebsd.rst @@ -0,0 +1,138 @@ +CPack FreeBSD Generator +----------------------- + +The built in (binary) CPack FreeBSD (pkg) generator (Unix only) + +Variables specific to CPack FreeBSD (pkg) generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The CPack FreeBSD generator may be used to create pkg(8) packages -- these may +be used on FreeBSD, DragonflyBSD, NetBSD, OpenBSD, but also on Linux or OSX, +depending on the installed package-management tools -- using :module:`CPack`. + +The CPack FreeBSD generator is a :module:`CPack` generator and uses the +``CPACK_XXX`` variables used by :module:`CPack`. It tries to re-use packaging +information that may already be specified for Debian packages for the +:cpack_gen:`CPack Deb Generator`. It also tries to re-use RPM packaging +information when Debian does not specify. + +The CPack FreeBSD generator should work on any host with libpkg installed. The +packages it produces are specific to the host architecture and ABI. + +The CPack FreeBSD generator sets package-metadata through +:code:`CPACK_FREEBSD_XXX` variables. The CPack FreeBSD generator, unlike the +CPack Deb generator, does not specially support componentized packages; a +single package is created from all the software artifacts created through +CMake. + +All of the variables can be set specifically for FreeBSD packaging in +the CPackConfig file or in CMakeLists.txt, but most of them have defaults +that use general settings (e.g. CMAKE_PROJECT_NAME) or Debian-specific +variables when those make sense (e.g. the homepage of an upstream project +is usually unchanged by the flavor of packaging). When there is no Debian +information to fall back on, but the RPM packaging has it, fall back to +the RPM information (e.g. package license). + +.. variable:: CPACK_FREEBSD_PACKAGE_NAME + + Sets the package name (in the package manifest, but also affects the + output filename). + + * Mandatory: YES + * Default: + + - :variable:`CPACK_PACKAGE_NAME` (this is always set by CPack itself, + based on CMAKE_PROJECT_NAME). + +.. variable:: CPACK_FREEBSD_PACKAGE_COMMENT + + Sets the package comment. This is the short description displayed by + pkg(8) in standard "pkg info" output. + + * Mandatory: YES + * Default: + + - :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` (this is always set + by CPack itself, if nothing else sets it explicitly). + - :variable:`PROJECT_DESCRIPTION` (this can be set with the DESCRIPTION + parameter for :command:`project`). + +.. variable:: CPACK_FREEBSD_PACKAGE_DESCRIPTION + + Sets the package description. This is the long description of the package, + given by "pkg info" with a specific package as argument. + + * Mandatory: YES + * Default: + + - :variable:`CPACK_DEBIAN_PACKAGE_DESCRIPTION` (this may be set already + for Debian packaging, so we may as well re-use it). + +.. variable:: CPACK_FREEBSD_PACKAGE_WWW + + The URL of the web site for this package, preferably (when applicable) the + site from which the original source can be obtained and any additional + upstream documentation or information may be found. + + * Mandatory: YES + * Default: + + - :variable:`CMAKE_PROJECT_HOMEPAGE_URL`, or if that is not set, + :variable:`CPACK_DEBIAN_PACKAGE_HOMEPAGE` (this may be set already + for Debian packaging, so we may as well re-use it). + +.. variable:: CPACK_FREEBSD_PACKAGE_LICENSE + + The license, or licenses, which apply to this software package. This must + be one or more license-identifiers that pkg recognizes as acceptable license + identifiers (e.g. "GPLv2"). + + * Mandatory: YES + * Default: + + - :variable:`CPACK_RPM_PACKAGE_LICENSE` + +.. variable:: CPACK_FREEBSD_PACKAGE_LICENSE_LOGIC + + This variable is only of importance if there is more than one license. + The default is "single", which is only applicable to a single license. + Other acceptable values are determined by pkg -- those are "dual" or "multi" -- + meaning choice (OR) or simultaneous (AND) application of the licenses. + + * Mandatory: NO + * Default: single + +.. variable:: CPACK_FREEBSD_PACKAGE_MAINTAINER + + The FreeBSD maintainer (e.g. kde@freebsd.org) of this package. + + * Mandatory: YES + * Default: none + +.. variable:: CPACK_FREEBSD_PACKAGE_ORIGIN + + The origin (ports label) of this package; for packages built by CPack + outside of the ports system this is of less importance. The default + puts the package somewhere under misc/, as a stopgap. + + * Mandatory: YES + * Default: misc/<package name> + +.. variable:: CPACK_FREEBSD_PACKAGE_CATEGORIES + + The ports categories where this package lives (if it were to be built + from ports). If none is set a single category is determined based on + the package origin. + + * Mandatory: YES + * Default: derived from ORIGIN + +.. variable:: CPACK_FREEBSD_PACKAGE_DEPS + + A list of package origins that should be added as package dependencies. + These are in the form <category>/<packagename>, e.g. x11/libkonq. + No version information needs to be provided (this is not included + in the manifest). + + * Mandatory: NO + * Default: empty diff --git a/Help/cpack_gen/ifw.rst b/Help/cpack_gen/ifw.rst new file mode 100644 index 0000000..68776e1 --- /dev/null +++ b/Help/cpack_gen/ifw.rst @@ -0,0 +1,335 @@ +CPack IFW Generator +------------------- + +See :module:`CPackIFW` for details on the CPackIFW module. + +.. _QtIFW: http://doc.qt.io/qtinstallerframework/index.html + + +Overview +^^^^^^^^ + +CPack ``IFW`` generator helps you to create online and offline +binary cross-platform installers with a graphical user interface. + +CPack IFW generator prepares project installation and generates configuration +and meta information for QtIFW_ tools. + +The QtIFW_ provides a set of tools and utilities to create +installers for the supported desktop Qt platforms: Linux, Microsoft Windows, +and Mac OS X. + +You should also install QtIFW_ to use CPack ``IFW`` generator. + +Hints +^^^^^ + +Generally, the CPack ``IFW`` generator automatically finds QtIFW_ tools, +but if you don't use a default path for installation of the QtIFW_ tools, +the path may be specified in either a CMake or an environment variable: + +.. variable:: CPACK_IFW_ROOT + + An CMake variable which specifies the location of the QtIFW_ tool suite. + + The variable will be cached in the ``CPackConfig.cmake`` file and used at + CPack runtime. + +.. variable:: QTIFWDIR + + An environment variable which specifies the location of the QtIFW_ tool + suite. + +.. note:: + The specified path should not contain "bin" at the end + (for example: "D:\\DevTools\\QtIFW2.0.5"). + +The :variable:`CPACK_IFW_ROOT` variable has a higher priority and overrides +the value of the :variable:`QTIFWDIR` variable. + +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" + ) + +Variables +^^^^^^^^^ + +You can use the following variables to change behavior of CPack ``IFW`` +generator. + +Debug +""""" + +.. variable:: CPACK_IFW_VERBOSE + + Set to ``ON`` to enable addition debug output. + By default is ``OFF``. + +Package +""""""" + +.. variable:: CPACK_IFW_PACKAGE_TITLE + + Name of the installer as displayed on the title bar. + By default used :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`. + +.. variable:: CPACK_IFW_PACKAGE_PUBLISHER + + Publisher of the software (as shown in the Windows Control Panel). + By default used :variable:`CPACK_PACKAGE_VENDOR`. + +.. variable:: CPACK_IFW_PRODUCT_URL + + URL to a page that contains product information on your web site. + +.. variable:: CPACK_IFW_PACKAGE_ICON + + Filename for a custom installer icon. The actual file is '.icns' (Mac OS X), + '.ico' (Windows). No functionality on Unix. + +.. variable:: CPACK_IFW_PACKAGE_WINDOW_ICON + + Filename for a custom window icon in PNG format for the Installer + application. + +.. variable:: CPACK_IFW_PACKAGE_LOGO + + Filename for a logo is used as QWizard::LogoPixmap. + +.. variable:: CPACK_IFW_PACKAGE_WATERMARK + + Filename for a watermark is used as QWizard::WatermarkPixmap. + +.. variable:: CPACK_IFW_PACKAGE_BANNER + + Filename for a banner is used as QWizard::BannerPixmap. + +.. variable:: CPACK_IFW_PACKAGE_BACKGROUND + + Filename for an image used as QWizard::BackgroundPixmap (only used by MacStyle). + +.. variable:: CPACK_IFW_PACKAGE_WIZARD_STYLE + + Wizard style to be used ("Modern", "Mac", "Aero" or "Classic"). + +.. variable:: CPACK_IFW_PACKAGE_WIZARD_DEFAULT_WIDTH + + Default width of the wizard in pixels. Setting a banner image will override this. + +.. variable:: CPACK_IFW_PACKAGE_WIZARD_DEFAULT_HEIGHT + + Default height of the wizard in pixels. Setting a watermark image will override this. + +.. variable:: CPACK_IFW_PACKAGE_TITLE_COLOR + + Color of the titles and subtitles (takes an HTML color code, such as "#88FF33"). + +.. variable:: CPACK_IFW_PACKAGE_START_MENU_DIRECTORY + + Name of the default program group for the product in the Windows Start menu. + + By default used :variable:`CPACK_IFW_PACKAGE_NAME`. + +.. variable:: CPACK_IFW_TARGET_DIRECTORY + + Default target directory for installation. + By default used + "@ApplicationsDir@/:variable:`CPACK_PACKAGE_INSTALL_DIRECTORY`" + + You can use predefined variables. + +.. variable:: CPACK_IFW_ADMIN_TARGET_DIRECTORY + + Default target directory for installation with administrator rights. + + You can use predefined variables. + +.. variable:: CPACK_IFW_PACKAGE_GROUP + + The group, which will be used to configure the root package + +.. variable:: CPACK_IFW_PACKAGE_NAME + + The root package name, which will be used if configuration group is not + specified + +.. variable:: CPACK_IFW_PACKAGE_MAINTENANCE_TOOL_NAME + + Filename of the generated maintenance tool. + The platform-specific executable file extension is appended. + + By default used QtIFW_ defaults (``maintenancetool``). + +.. variable:: CPACK_IFW_PACKAGE_REMOVE_TARGET_DIR + + Set to ``OFF`` if the target directory should not be deleted when uninstalling. + + Is ``ON`` by default + +.. variable:: CPACK_IFW_PACKAGE_MAINTENANCE_TOOL_INI_FILE + + Filename for the configuration of the generated maintenance tool. + + By default used QtIFW_ defaults (``maintenancetool.ini``). + +.. variable:: CPACK_IFW_PACKAGE_ALLOW_NON_ASCII_CHARACTERS + + Set to ``ON`` if the installation path can contain non-ASCII characters. + + Is ``ON`` for QtIFW_ less 2.0 tools. + +.. variable:: CPACK_IFW_PACKAGE_ALLOW_SPACE_IN_PATH + + Set to ``OFF`` if the installation path cannot contain space characters. + + Is ``ON`` for QtIFW_ less 2.0 tools. + +.. variable:: CPACK_IFW_PACKAGE_CONTROL_SCRIPT + + Filename for a custom installer control script. + +.. variable:: CPACK_IFW_PACKAGE_RESOURCES + + List of additional resources ('.qrc' files) to include in the installer + binary. + + You can use :command:`cpack_ifw_add_package_resources` command to resolve + relative paths. + +.. variable:: CPACK_IFW_PACKAGE_FILE_EXTENSION + + The target binary extension. + + On Linux, the name of the target binary is automatically extended with + '.run', if you do not specify the extension. + + On Windows, the target is created as an application with the extension + '.exe', which is automatically added, if not supplied. + + On Mac, the target is created as an DMG disk image with the extension + '.dmg', which is automatically added, if not supplied. + +.. variable:: CPACK_IFW_REPOSITORIES_ALL + + The list of remote repositories. + + The default value of this variable is computed by CPack and contains + all repositories added with command :command:`cpack_ifw_add_repository` + or updated with command :command:`cpack_ifw_update_repository`. + +.. variable:: CPACK_IFW_DOWNLOAD_ALL + + If this is ``ON`` all components will be downloaded. + By default is ``OFF`` or used value + from ``CPACK_DOWNLOAD_ALL`` if set + +Components +"""""""""" + +.. variable:: CPACK_IFW_RESOLVE_DUPLICATE_NAMES + + Resolve duplicate names when installing components with groups. + +.. variable:: CPACK_IFW_PACKAGES_DIRECTORIES + + Additional prepared packages dirs that will be used to resolve + dependent components. + +.. variable:: CPACK_IFW_REPOSITORIES_DIRECTORIES + + Additional prepared repository dirs that will be used to resolve and + repack dependent components. This feature available only + since QtIFW_ 3.1. + +Tools +""""" + +.. variable:: CPACK_IFW_FRAMEWORK_VERSION + + The version of used QtIFW_ tools. + +.. variable:: CPACK_IFW_BINARYCREATOR_EXECUTABLE + + The path to "binarycreator" command line client. + + This variable is cached and may be configured if needed. + +.. variable:: CPACK_IFW_REPOGEN_EXECUTABLE + + The path to "repogen" command line client. + + This variable is cached and may be configured if needed. + +.. variable:: CPACK_IFW_INSTALLERBASE_EXECUTABLE + + The path to "installerbase" installer executable base. + + This variable is cached and may be configured if needed. + +.. variable:: CPACK_IFW_DEVTOOL_EXECUTABLE + + The path to "devtool" command line client. + + This variable is cached and may be configured if needed. + + +Online installer +^^^^^^^^^^^^^^^^ + +By default CPack IFW generator makes offline installer. This means that all +components will be packaged into a binary file. + +To make a component downloaded, you must set the ``DOWNLOADED`` option in +:command:`cpack_add_component`. + +Then you would use the command :command:`cpack_configure_downloads`. +If you set ``ALL`` option all components will be downloaded. + +You also can use command :command:`cpack_ifw_add_repository` and +variable :variable:`CPACK_IFW_DOWNLOAD_ALL` 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``). + +See Also +^^^^^^^^ + +Qt Installer Framework Manual: + +* Index page: + http://doc.qt.io/qtinstallerframework/index.html + +* Component Scripting: + http://doc.qt.io/qtinstallerframework/scripting.html + +* Predefined Variables: + http://doc.qt.io/qtinstallerframework/scripting.html#predefined-variables + +* Promoting Updates: + http://doc.qt.io/qtinstallerframework/ifw-updates.html + +Download Qt Installer Framework for you platform from Qt site: + http://download.qt.io/official_releases/qt-installer-framework diff --git a/Help/cpack_gen/nsis.rst b/Help/cpack_gen/nsis.rst new file mode 100644 index 0000000..9f82a04 --- /dev/null +++ b/Help/cpack_gen/nsis.rst @@ -0,0 +1,130 @@ +CPack NSIS Generator +-------------------- + +CPack NSIS generator specific options + +Variables specific to CPack NSIS generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following variables are specific to the graphical installers built +on Windows using the Nullsoft Installation System. + +.. variable:: CPACK_NSIS_INSTALL_ROOT + + The default installation directory presented to the end user by the NSIS + installer is under this root dir. The full directory presented to the end + user is: ${CPACK_NSIS_INSTALL_ROOT}/${CPACK_PACKAGE_INSTALL_DIRECTORY} + +.. variable:: CPACK_NSIS_MUI_ICON + + An icon filename. The name of a ``*.ico`` file used as the main icon for the + generated install program. + +.. variable:: CPACK_NSIS_MUI_UNIICON + + An icon filename. The name of a ``*.ico`` file used as the main icon for the + generated uninstall program. + +.. variable:: CPACK_NSIS_INSTALLER_MUI_ICON_CODE + + undocumented. + +.. variable:: CPACK_NSIS_MUI_WELCOMEFINISHPAGE_BITMAP + + The filename of a bitmap to use as the NSIS MUI_WELCOMEFINISHPAGE_BITMAP. + +.. variable:: CPACK_NSIS_MUI_UNWELCOMEFINISHPAGE_BITMAP + + The filename of a bitmap to use as the NSIS MUI_UNWELCOMEFINISHPAGE_BITMAP. + +.. variable:: CPACK_NSIS_EXTRA_PREINSTALL_COMMANDS + + Extra NSIS commands that will be added to the beginning of the install + Section, before your install tree is available on the target system. + +.. variable:: CPACK_NSIS_EXTRA_INSTALL_COMMANDS + + Extra NSIS commands that will be added to the end of the install Section, + after your install tree is available on the target system. + +.. variable:: CPACK_NSIS_EXTRA_UNINSTALL_COMMANDS + + Extra NSIS commands that will be added to the uninstall Section, before + your install tree is removed from the target system. + +.. variable:: CPACK_NSIS_COMPRESSOR + + The arguments that will be passed to the NSIS SetCompressor command. + +.. variable:: CPACK_NSIS_ENABLE_UNINSTALL_BEFORE_INSTALL + + Ask about uninstalling previous versions first. If this is set to "ON", + then an installer will look for previous installed versions and if one is + found, ask the user whether to uninstall it before proceeding with the + install. + +.. variable:: CPACK_NSIS_MODIFY_PATH + + Modify PATH toggle. If this is set to "ON", then an extra page will appear + in the installer that will allow the user to choose whether the program + directory should be added to the system PATH variable. + +.. variable:: CPACK_NSIS_DISPLAY_NAME + + The display name string that appears in the Windows Add/Remove Program + control panel + +.. variable:: CPACK_NSIS_PACKAGE_NAME + + The title displayed at the top of the installer. + +.. variable:: CPACK_NSIS_INSTALLED_ICON_NAME + + A path to the executable that contains the installer icon. + +.. variable:: CPACK_NSIS_HELP_LINK + + URL to a web site providing assistance in installing your application. + +.. variable:: CPACK_NSIS_URL_INFO_ABOUT + + URL to a web site providing more information about your application. + +.. variable:: CPACK_NSIS_CONTACT + + Contact information for questions and comments about the installation + process. + +.. variable:: CPACK_NSIS_<compName>_INSTALL_DIRECTORY + + Custom install directory for the specified component <compName> instead + of $INSTDIR. + +.. variable:: CPACK_NSIS_CREATE_ICONS_EXTRA + + Additional NSIS commands for creating start menu shortcuts. + +.. variable:: CPACK_NSIS_DELETE_ICONS_EXTRA + + Additional NSIS commands to uninstall start menu shortcuts. + +.. variable:: CPACK_NSIS_EXECUTABLES_DIRECTORY + + Creating NSIS start menu links assumes that they are in 'bin' unless this + variable is set. For example, you would set this to 'exec' if your + executables are in an exec directory. + +.. variable:: CPACK_NSIS_MUI_FINISHPAGE_RUN + + Specify an executable to add an option to run on the finish page of the + NSIS installer. + +.. variable:: CPACK_NSIS_MENU_LINKS + + Specify links in [application] menu. This should contain a list of pair + "link" "link name". The link may be a URL or a path relative to + installation prefix. Like:: + + set(CPACK_NSIS_MENU_LINKS + "doc/cmake-@CMake_VERSION_MAJOR@.@CMake_VERSION_MINOR@/cmake.html" + "CMake Help" "https://cmake.org" "CMake Web Site") diff --git a/Help/cpack_gen/nuget.rst b/Help/cpack_gen/nuget.rst new file mode 100644 index 0000000..c8c481f --- /dev/null +++ b/Help/cpack_gen/nuget.rst @@ -0,0 +1,189 @@ +CPack NuGet Generator +--------------------- + +When build a NuGet package there is no direct way to control an output +filename due a lack of the corresponding CLI option of NuGet, so there +is no ``CPACK_NUGET_PACKAGE_FILENAME`` variable. To form the output filename +NuGet uses the package name and the version according to its built-in rules. + +Also, be aware that including a top level directory +(``CPACK_INCLUDE_TOPLEVEL_DIRECTORY``) is ignored by this generator. + + +Variables specific to CPack NuGet generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The CPack NuGet generator may be used to create NuGet packages using +:module:`CPack`. The CPack NuGet generator is a :module:`CPack` generator thus +it uses the ``CPACK_XXX`` variables used by :module:`CPack`. + +The CPack NuGet generator has specific features which are controlled by the +specifics :code:`CPACK_NUGET_XXX` variables. In the "one per group" mode +(see :variable:`CPACK_COMPONENTS_GROUPING`), ``<compName>`` placeholder +in the variables below would contain a group name (uppercased and turned into +a "C" identifier). + +List of CPack NuGet generator specific variables: + +.. variable:: CPACK_NUGET_COMPONENT_INSTALL + + Enable component packaging for CPack NuGet generator + + * Mandatory : NO + * Default : OFF + +.. variable:: CPACK_NUGET_PACKAGE_NAME + CPACK_NUGET_<compName>_PACKAGE_NAME + + The NUGET package name. + + * Mandatory : YES + * Default : :variable:`CPACK_PACKAGE_NAME` + +.. variable:: CPACK_NUGET_PACKAGE_VERSION + CPACK_NUGET_<compName>_PACKAGE_VERSION + + The NuGet package version. + + * Mandatory : YES + * Default : :variable:`CPACK_PACKAGE_VERSION` + +.. variable:: CPACK_NUGET_PACKAGE_DESCRIPTION + CPACK_NUGET_<compName>_PACKAGE_DESCRIPTION + + A long description of the package for UI display. + + * Mandatory : YES + * Default : + - :variable:`CPACK_COMPONENT_<compName>_DESCRIPTION`, + - ``CPACK_COMPONENT_GROUP_<groupName>_DESCRIPTION``, + - :variable:`CPACK_PACKAGE_DESCRIPTION` + +.. variable:: CPACK_NUGET_PACKAGE_AUTHORS + CPACK_NUGET_<compName>_PACKAGE_AUTHORS + + A comma-separated list of packages authors, matching the profile names + on nuget.org_. These are displayed in the NuGet Gallery on + nuget.org_ and are used to cross-reference packages by the same + authors. + + * Mandatory : YES + * Default : :variable:`CPACK_PACKAGE_VENDOR` + +.. variable:: CPACK_NUGET_PACKAGE_TITLE + CPACK_NUGET_<compName>_PACKAGE_TITLE + + A human-friendly title of the package, typically used in UI displays + as on nuget.org_ and the Package Manager in Visual Studio. If not + specified, the package ID is used. + + * Mandatory : NO + * Default : + - :variable:`CPACK_COMPONENT_<compName>_DISPLAY_NAME`, + - ``CPACK_COMPONENT_GROUP_<groupName>_DISPLAY_NAME`` + +.. variable:: CPACK_NUGET_PACKAGE_OWNERS + CPACK_NUGET_<compName>_PACKAGE_OWNERS + + A comma-separated list of the package creators using profile names + on nuget.org_. This is often the same list as in authors, + and is ignored when uploading the package to nuget.org_. + + * Mandatory : NO + * Default : - + +.. variable:: CPACK_NUGET_PACKAGE_HOMEPAGE_URL + CPACK_NUGET_<compName>_PACKAGE_HOMEPAGE_URL + + A URL for the package's home page, often shown in UI displays as well + as nuget.org_. + + * Mandatory : NO + * Default : :variable:`CPACK_PACKAGE_HOMEPAGE_URL` + +.. variable:: CPACK_NUGET_PACKAGE_LICENSEURL + CPACK_NUGET_<compName>_PACKAGE_LICENSEURL + + A URL for the package's license, often shown in UI displays as well + as nuget.org_. + + * Mandatory : NO + * Default : - + +.. variable:: CPACK_NUGET_PACKAGE_ICONURL + CPACK_NUGET_<compName>_PACKAGE_ICONURL + + A URL for a 64x64 image with transparency background to use as the + icon for the package in UI display. + + * Mandatory : NO + * Default : - + +.. variable:: CPACK_NUGET_PACKAGE_DESCRIPTION_SUMMARY + CPACK_NUGET_<compName>_PACKAGE_DESCRIPTION_SUMMARY + + A short description of the package for UI display. If omitted, a + truncated version of description is used. + + * Mandatory : NO + * Default : :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` + +.. variable:: CPACK_NUGET_PACKAGE_RELEASE_NOTES + CPACK_NUGET_<compName>_PACKAGE_RELEASE_NOTES + + A description of the changes made in this release of the package, + often used in UI like the Updates tab of the Visual Studio Package + Manager in place of the package description. + + * Mandatory : NO + * Default : - + +.. variable:: CPACK_NUGET_PACKAGE_COPYRIGHT + CPACK_NUGET_<compName>_PACKAGE_COPYRIGHT + + Copyright details for the package. + + * Mandatory : NO + * Default : - + +.. variable:: CPACK_NUGET_PACKAGE_TAGS + CPACK_NUGET_<compName>_PACKAGE_TAGS + + A space-delimited list of tags and keywords that describe the + package and aid discoverability of packages through search and + filtering. + + * Mandatory : NO + * Default : - + +.. variable:: CPACK_NUGET_PACKAGE_DEPENDENCIES + CPACK_NUGET_<compName>_PACKAGE_DEPENDENCIES + + A list of package dependencies. + + * Mandatory : NO + * Default : - + +.. variable:: CPACK_NUGET_PACKAGE_DEPENDENCIES_<dependency>_VERSION + CPACK_NUGET_<compName>_PACKAGE_DEPENDENCIES_<dependency>_VERSION + + A `version specification`_ for the particular dependency, where + ``<dependency>`` is an item of the dependency list (see above) + transformed with ``MAKE_C_IDENTIFIER`` function of :command:`string` + command. + + * Mandatory : NO + * Default : - + +.. variable:: CPACK_NUGET_PACKAGE_DEBUG + + Enable debug messages while executing CPack NuGet generator. + + * Mandatory : NO + * Default : OFF + + +.. _nuget.org: http://nuget.org +.. _version specification: https://docs.microsoft.com/en-us/nuget/reference/package-versioning#version-ranges-and-wildcards + +.. NuGet spec docs https://docs.microsoft.com/en-us/nuget/reference/nuspec diff --git a/Help/cpack_gen/packagemaker.rst b/Help/cpack_gen/packagemaker.rst new file mode 100644 index 0000000..f9abdd8 --- /dev/null +++ b/Help/cpack_gen/packagemaker.rst @@ -0,0 +1,23 @@ +CPack PackageMaker Generator +---------------------------- + +PackageMaker CPack generator (Mac OS X). + +Variables specific to CPack PackageMaker generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following variable is specific to installers built on Mac +OS X using PackageMaker: + +.. variable:: CPACK_OSX_PACKAGE_VERSION + + The version of Mac OS X that the resulting PackageMaker archive should be + compatible with. Different versions of Mac OS X support different + features. For example, CPack can only build component-based installers for + Mac OS X 10.4 or newer, and can only build installers that download + component son-the-fly for Mac OS X 10.5 or newer. If left blank, this value + will be set to the minimum version of Mac OS X that supports the requested + features. Set this variable to some value (e.g., 10.4) only if you want to + guarantee that your installer will work on that version of Mac OS X, and + don't mind missing extra features available in the installer shipping with + later versions of Mac OS X. diff --git a/Help/cpack_gen/productbuild.rst b/Help/cpack_gen/productbuild.rst new file mode 100644 index 0000000..1a6e0f8 --- /dev/null +++ b/Help/cpack_gen/productbuild.rst @@ -0,0 +1,68 @@ +CPack productbuild Generator +---------------------------- + +productbuild CPack generator (Mac OS X). + +Variables specific to CPack productbuild generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following variable is specific to installers built on Mac +OS X using ProductBuild: + +.. variable:: CPACK_COMMAND_PRODUCTBUILD + + Path to the productbuild(1) command used to generate a product archive for + the OS X Installer or Mac App Store. This variable can be used to override + the automatically detected command (or specify its location if the + auto-detection fails to find it.) + +.. variable:: CPACK_PRODUCTBUILD_IDENTITY_NAME + + Adds a digital signature to the resulting package. + + +.. variable:: CPACK_PRODUCTBUILD_KEYCHAIN_PATH + + Specify a specific keychain to search for the signing identity. + + +.. variable:: CPACK_COMMAND_PKGBUILD + + Path to the pkgbuild(1) command used to generate an OS X component package + on OS X. This variable can be used to override the automatically detected + command (or specify its location if the auto-detection fails to find it.) + + +.. variable:: CPACK_PKGBUILD_IDENTITY_NAME + + Adds a digital signature to the resulting package. + + +.. variable:: CPACK_PKGBUILD_KEYCHAIN_PATH + + Specify a specific keychain to search for the signing identity. + + +.. variable:: CPACK_PREFLIGHT_<COMP>_SCRIPT + + Full path to a file that will be used as the ``preinstall`` script for the + named ``<COMP>`` component's package, where ``<COMP>`` is the uppercased + component name. No ``preinstall`` script is added if this variable is not + defined for a given component. + + +.. variable:: CPACK_POSTFLIGHT_<COMP>_SCRIPT + + Full path to a file that will be used as the ``postinstall`` script for the + named ``<COMP>`` component's package, where ``<COMP>`` is the uppercased + component name. No ``postinstall`` script is added if this variable is not + defined for a given component. + + +.. variable:: CPACK_PRODUCTBUILD_RESOURCES_DIR + + If specified the productbuild generator copies files from this directory + (including subdirectories) to the ``Resources`` directory. This is done + before the :variable:`CPACK_RESOURCE_FILE_WELCOME`, + :variable:`CPACK_RESOURCE_FILE_README`, and + :variable:`CPACK_RESOURCE_FILE_LICENSE` files are copied. diff --git a/Help/cpack_gen/rpm.rst b/Help/cpack_gen/rpm.rst new file mode 100644 index 0000000..0214766 --- /dev/null +++ b/Help/cpack_gen/rpm.rst @@ -0,0 +1,955 @@ +CPack RPM Generator +------------------- + +The built in (binary) CPack RPM generator (Unix only) + +Variables specific to CPack RPM generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The CPack RPM generator may be used to create RPM packages using :module:`CPack`. +The CPack RPM generator is a :module:`CPack` generator thus it uses the +``CPACK_XXX`` variables used by :module:`CPack`. + +The CPack RPM generator has specific features which are controlled by the specifics +:code:`CPACK_RPM_XXX` variables. + +:code:`CPACK_RPM_<COMPONENT>_XXXX` variables may be used in order to have +**component** specific values. Note however that ``<COMPONENT>`` refers to the +**grouping name** written in upper case. It may be either a component name or +a component GROUP name. Usually those variables correspond to RPM spec file +entities. One may find information about spec files here +http://www.rpm.org/wiki/Docs + +.. note:: + + `<COMPONENT>` part of variables is preferred to be in upper case (for e.g. if + component is named `foo` then use `CPACK_RPM_FOO_XXXX` variable name format) + as is with other `CPACK_<COMPONENT>_XXXX` variables. + For the purposes of back compatibility (CMake/CPack version 3.5 and lower) + support for same cased component (e.g. `fOo` would be used as + `CPACK_RPM_fOo_XXXX`) is still supported for variables defined in older + versions of CMake/CPack but is not guaranteed for variables that + will be added in the future. For the sake of back compatibility same cased + component variables also override upper cased versions where both are + present. + +Here are some CPack RPM generator wiki resources that are here for historic reasons and +are no longer maintained but may still prove useful: + + - https://gitlab.kitware.com/cmake/community/wikis/doc/cpack/Configuration + - https://gitlab.kitware.com/cmake/community/wikis/doc/cpack/PackageGenerators#rpm-unix-only + +List of CPack RPM generator specific variables: + +.. variable:: CPACK_RPM_COMPONENT_INSTALL + + Enable component packaging for CPack RPM generator + + * Mandatory : NO + * Default : OFF + + If enabled (ON) multiple packages are generated. By default a single package + containing files of all components is generated. + +.. variable:: CPACK_RPM_PACKAGE_SUMMARY + CPACK_RPM_<component>_PACKAGE_SUMMARY + + The RPM package summary. + + * Mandatory : YES + * Default : :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` + +.. variable:: CPACK_RPM_PACKAGE_NAME + CPACK_RPM_<component>_PACKAGE_NAME + + The RPM package name. + + * Mandatory : YES + * Default : :variable:`CPACK_PACKAGE_NAME` + +.. variable:: CPACK_RPM_FILE_NAME + CPACK_RPM_<component>_FILE_NAME + + Package file name. + + * Mandatory : YES + * Default : ``<CPACK_PACKAGE_FILE_NAME>[-<component>].rpm`` with spaces + replaced by '-' + + This may be set to ``RPM-DEFAULT`` to allow rpmbuild tool to generate package + file name by itself. + Alternatively provided package file name must end with ``.rpm`` suffix. + + .. note:: + + By using user provided spec file, rpm macro extensions such as for + generating debuginfo packages or by simply using multiple components more + than one rpm file may be generated, either from a single spec file or from + multiple spec files (each component execution produces it's own spec file). + In such cases duplicate file names may occur as a result of this variable + setting or spec file content structure. Duplicate files get overwritten + and it is up to the packager to set the variables in a manner that will + prevent such errors. + +.. variable:: CPACK_RPM_MAIN_COMPONENT + + Main component that is packaged without component suffix. + + * Mandatory : NO + * Default : - + + This variable can be set to any component or group name so that component or + group rpm package is generated without component suffix in filename and + package name. + +.. variable:: CPACK_RPM_PACKAGE_EPOCH + + The RPM package epoch + + * Mandatory : No + * Default : - + + Optional number that should be incremented when changing versioning schemas + or fixing mistakes in the version numbers of older packages. + +.. variable:: CPACK_RPM_PACKAGE_VERSION + + The RPM package version. + + * Mandatory : YES + * Default : :variable:`CPACK_PACKAGE_VERSION` + +.. variable:: CPACK_RPM_PACKAGE_ARCHITECTURE + CPACK_RPM_<component>_PACKAGE_ARCHITECTURE + + The RPM package architecture. + + * Mandatory : YES + * Default : Native architecture output by ``uname -m`` + + This may be set to ``noarch`` if you know you are building a noarch package. + +.. variable:: CPACK_RPM_PACKAGE_RELEASE + + The RPM package release. + + * Mandatory : YES + * Default : 1 + + This is the numbering of the RPM package itself, i.e. the version of the + packaging and not the version of the content (see + :variable:`CPACK_RPM_PACKAGE_VERSION`). One may change the default value if + the previous packaging was buggy and/or you want to put here a fancy Linux + distro specific numbering. + +.. note:: + + This is the string that goes into the RPM ``Release:`` field. Some distros + (e.g. Fedora, CentOS) require ``1%{?dist}`` format and not just a number. + ``%{?dist}`` part can be added by setting :variable:`CPACK_RPM_PACKAGE_RELEASE_DIST`. + +.. variable:: CPACK_RPM_PACKAGE_RELEASE_DIST + + The dist tag that is added RPM ``Release:`` field. + + * Mandatory : NO + * Default : OFF + + This is the reported ``%{dist}`` tag from the current distribution or empty + ``%{dist}`` if RPM macro is not set. If this variable is set then RPM + ``Release:`` field value is set to ``${CPACK_RPM_PACKAGE_RELEASE}%{?dist}``. + +.. variable:: CPACK_RPM_PACKAGE_LICENSE + + The RPM package license policy. + + * Mandatory : YES + * Default : "unknown" + +.. variable:: CPACK_RPM_PACKAGE_GROUP + CPACK_RPM_<component>_PACKAGE_GROUP + + The RPM package group. + + * Mandatory : YES + * Default : "unknown" + +.. variable:: CPACK_RPM_PACKAGE_VENDOR + + The RPM package vendor. + + * Mandatory : YES + * Default : CPACK_PACKAGE_VENDOR if set or "unknown" + +.. variable:: CPACK_RPM_PACKAGE_URL + CPACK_RPM_<component>_PACKAGE_URL + + The projects URL. + + * Mandatory : NO + * Default : :variable:`CMAKE_PROJECT_HOMEPAGE_URL` + +.. variable:: CPACK_RPM_PACKAGE_DESCRIPTION + CPACK_RPM_<component>_PACKAGE_DESCRIPTION + + RPM package description. + + * Mandatory : YES + * Default : :variable:`CPACK_COMPONENT_<compName>_DESCRIPTION` (component + based installers only) if set, :variable:`CPACK_PACKAGE_DESCRIPTION_FILE` + if set or "no package description available" + +.. variable:: CPACK_RPM_COMPRESSION_TYPE + + RPM compression type. + + * Mandatory : NO + * Default : - + + May be used to override RPM compression type to be used to build the + RPM. For example some Linux distribution now default to lzma or xz + compression whereas older cannot use such RPM. Using this one can enforce + compression type to be used. + + Possible values are: + + - lzma + - xz + - bzip2 + - gzip + +.. variable:: CPACK_RPM_PACKAGE_AUTOREQ + CPACK_RPM_<component>_PACKAGE_AUTOREQ + + RPM spec autoreq field. + + * Mandatory : NO + * Default : - + + May be used to enable (1, yes) or disable (0, no) automatic shared libraries + dependency detection. Dependencies are added to requires list. + + .. note:: + + By default automatic dependency detection is enabled by rpm generator. + +.. variable:: CPACK_RPM_PACKAGE_AUTOPROV + CPACK_RPM_<component>_PACKAGE_AUTOPROV + + RPM spec autoprov field. + + * Mandatory : NO + * Default : - + + May be used to enable (1, yes) or disable (0, no) automatic listing of shared + libraries that are provided by the package. Shared libraries are added to + provides list. + + .. note:: + + By default automatic provides detection is enabled by rpm generator. + +.. variable:: CPACK_RPM_PACKAGE_AUTOREQPROV + CPACK_RPM_<component>_PACKAGE_AUTOREQPROV + + RPM spec autoreqprov field. + + * Mandatory : NO + * Default : - + + Variable enables/disables autoreq and autoprov at the same time. + See :variable:`CPACK_RPM_PACKAGE_AUTOREQ` and :variable:`CPACK_RPM_PACKAGE_AUTOPROV` + for more details. + + .. note:: + + By default automatic detection feature is enabled by rpm. + +.. variable:: CPACK_RPM_PACKAGE_REQUIRES + CPACK_RPM_<component>_PACKAGE_REQUIRES + + RPM spec requires field. + + * Mandatory : NO + * Default : - + + May be used to set RPM dependencies (requires). Note that you must enclose + the complete requires string between quotes, for example:: + + set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8") + + The required package list of an RPM file could be printed with:: + + rpm -qp --requires file.rpm + +.. variable:: CPACK_RPM_PACKAGE_CONFLICTS + CPACK_RPM_<component>_PACKAGE_CONFLICTS + + RPM spec conflicts field. + + * Mandatory : NO + * Default : - + + May be used to set negative RPM dependencies (conflicts). Note that you must + enclose the complete requires string between quotes, for example:: + + set(CPACK_RPM_PACKAGE_CONFLICTS "libxml2") + + The conflicting package list of an RPM file could be printed with:: + + rpm -qp --conflicts file.rpm + +.. variable:: CPACK_RPM_PACKAGE_REQUIRES_PRE + CPACK_RPM_<component>_PACKAGE_REQUIRES_PRE + + RPM spec requires(pre) field. + + * Mandatory : NO + * Default : - + + May be used to set RPM preinstall dependencies (requires(pre)). Note that + you must enclose the complete requires string between quotes, for example:: + + set(CPACK_RPM_PACKAGE_REQUIRES_PRE "shadow-utils, initscripts") + +.. variable:: CPACK_RPM_PACKAGE_REQUIRES_POST + CPACK_RPM_<component>_PACKAGE_REQUIRES_POST + + RPM spec requires(post) field. + + * Mandatory : NO + * Default : - + + May be used to set RPM postinstall dependencies (requires(post)). Note that + you must enclose the complete requires string between quotes, for example:: + + set(CPACK_RPM_PACKAGE_REQUIRES_POST "shadow-utils, initscripts") + +.. variable:: CPACK_RPM_PACKAGE_REQUIRES_POSTUN + CPACK_RPM_<component>_PACKAGE_REQUIRES_POSTUN + + RPM spec requires(postun) field. + + * Mandatory : NO + * Default : - + + May be used to set RPM postuninstall dependencies (requires(postun)). Note + that you must enclose the complete requires string between quotes, for + example:: + + set(CPACK_RPM_PACKAGE_REQUIRES_POSTUN "shadow-utils, initscripts") + +.. variable:: CPACK_RPM_PACKAGE_REQUIRES_PREUN + CPACK_RPM_<component>_PACKAGE_REQUIRES_PREUN + + RPM spec requires(preun) field. + + * Mandatory : NO + * Default : - + + May be used to set RPM preuninstall dependencies (requires(preun)). Note that + you must enclose the complete requires string between quotes, for example:: + + set(CPACK_RPM_PACKAGE_REQUIRES_PREUN "shadow-utils, initscripts") + +.. variable:: CPACK_RPM_PACKAGE_SUGGESTS + CPACK_RPM_<component>_PACKAGE_SUGGESTS + + RPM spec suggest field. + + * Mandatory : NO + * Default : - + + May be used to set weak RPM dependencies (suggests). Note that you must + enclose the complete requires string between quotes. + +.. variable:: CPACK_RPM_PACKAGE_PROVIDES + CPACK_RPM_<component>_PACKAGE_PROVIDES + + RPM spec provides field. + + * Mandatory : NO + * Default : - + + May be used to set RPM dependencies (provides). The provided package list + of an RPM file could be printed with:: + + rpm -qp --provides file.rpm + +.. variable:: CPACK_RPM_PACKAGE_OBSOLETES + CPACK_RPM_<component>_PACKAGE_OBSOLETES + + RPM spec obsoletes field. + + * Mandatory : NO + * Default : - + + May be used to set RPM packages that are obsoleted by this one. + +.. variable:: CPACK_RPM_PACKAGE_RELOCATABLE + + build a relocatable RPM. + + * Mandatory : NO + * Default : CPACK_PACKAGE_RELOCATABLE + + If this variable is set to TRUE or ON, the CPack RPM generator will try + to build a relocatable RPM package. A relocatable RPM may + be installed using:: + + rpm --prefix or --relocate + + in order to install it at an alternate place see rpm(8). Note that + currently this may fail if :variable:`CPACK_SET_DESTDIR` is set to ``ON``. If + :variable:`CPACK_SET_DESTDIR` is set then you will get a warning message but + if there is file installed with absolute path you'll get unexpected behavior. + +.. variable:: CPACK_RPM_SPEC_INSTALL_POST + + Deprecated - use :variable:`CPACK_RPM_SPEC_MORE_DEFINE` instead. + + * Mandatory : NO + * Default : - + * Deprecated: YES + + May be used to override the ``__spec_install_post`` section within the + generated spec file. This affects the install step during package creation, + not during package installation. For adding operations to be performed + during package installation, use + :variable:`CPACK_RPM_POST_INSTALL_SCRIPT_FILE` instead. + +.. variable:: CPACK_RPM_SPEC_MORE_DEFINE + + RPM extended spec definitions lines. + + * Mandatory : NO + * Default : - + + May be used to add any ``%define`` lines to the generated spec file. An + example of its use is to prevent stripping of executables (but note that + this may also disable other default post install processing):: + + set(CPACK_RPM_SPEC_MORE_DEFINE "%define __spec_install_post /bin/true") + +.. variable:: CPACK_RPM_PACKAGE_DEBUG + + Toggle CPack RPM generator debug output. + + * Mandatory : NO + * Default : - + + May be set when invoking cpack in order to trace debug information + during CPack RPM run. For example you may launch CPack like this:: + + cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM + +.. variable:: CPACK_RPM_USER_BINARY_SPECFILE + CPACK_RPM_<componentName>_USER_BINARY_SPECFILE + + A user provided spec file. + + * Mandatory : NO + * Default : - + + May be set by the user in order to specify a USER binary spec file + to be used by the CPack RPM generator instead of generating the file. + The specified file will be processed by configure_file( @ONLY). + +.. variable:: CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE + + Spec file template. + + * Mandatory : NO + * Default : - + + If set CPack will generate a template for USER specified binary + spec file and stop with an error. For example launch CPack like this:: + + cpack -D CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE=1 -G RPM + + The user may then use this file in order to hand-craft is own + binary spec file which may be used with + :variable:`CPACK_RPM_USER_BINARY_SPECFILE`. + +.. variable:: CPACK_RPM_PRE_INSTALL_SCRIPT_FILE + CPACK_RPM_PRE_UNINSTALL_SCRIPT_FILE + + Path to file containing pre (un)install script. + + * Mandatory : NO + * Default : - + + May be used to embed a pre (un)installation 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 + script for each component can be overridden with + ``CPACK_RPM_<COMPONENT>_PRE_INSTALL_SCRIPT_FILE`` and + ``CPACK_RPM_<COMPONENT>_PRE_UNINSTALL_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 + + Path to file containing post (un)install script. + + * Mandatory : NO + * Default : - + + May be used to embed a post (un)installation 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 + script for each component can be overridden with + ``CPACK_RPM_<COMPONENT>_POST_INSTALL_SCRIPT_FILE`` and + ``CPACK_RPM_<COMPONENT>_POST_UNINSTALL_SCRIPT_FILE``. + One may verify which scriptlet has been included with:: + + rpm -qp --scripts package.rpm + +.. variable:: CPACK_RPM_USER_FILELIST + CPACK_RPM_<COMPONENT>_USER_FILELIST + + * Mandatory : NO + * Default : - + + May be used to explicitly specify ``%(<directive>)`` file line + in the spec file. Like ``%config(noreplace)`` or any other directive + that be found in the ``%files`` section. You can have multiple directives + per line, as in ``%attr(600,root,root) %config(noreplace)``. Since + the CPack RPM generator is generating the list of files (and directories) the + user specified files of the ``CPACK_RPM_<COMPONENT>_USER_FILELIST`` list will + be removed from the generated list. If referring to directories do + not add a trailing slash. + +.. variable:: CPACK_RPM_CHANGELOG_FILE + + RPM changelog file. + + * Mandatory : NO + * Default : - + + May be used to embed a changelog in the spec file. + The referred file will be read and directly put after the ``%changelog`` + section. + +.. variable:: CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST + + list of path to be excluded. + + * Mandatory : NO + * Default : /etc /etc/init.d /usr /usr/bin /usr/include /usr/lib + /usr/libx32 /usr/lib64 /usr/share /usr/share/aclocal + /usr/share/doc + + May be used to exclude path (directories or files) from the auto-generated + list of paths discovered by CPack RPM. The default value contains a + reasonable set of values if the variable is not defined by the user. If the + variable is defined by the user then the CPack RPM generator will NOT any of + the default path. If you want to add some path to the default list then you + can use :variable:`CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST_ADDITION` variable. + +.. variable:: CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST_ADDITION + + additional list of path to be excluded. + + * Mandatory : NO + * Default : - + + May be used to add more exclude path (directories or files) from the initial + default list of excluded paths. See + :variable:`CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST`. + +.. variable:: CPACK_RPM_RELOCATION_PATHS + + Packages relocation paths list. + + * Mandatory : NO + * Default : - + + May be used to specify more than one relocation path per relocatable RPM. + Variable contains a list of relocation paths that if relative are prefixed + by the value of :variable:`CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX` or by the + value of :variable:`CPACK_PACKAGING_INSTALL_PREFIX` if the component version + is not provided. + Variable is not component based as its content can be used to set a different + path prefix for e.g. binary dir and documentation dir at the same time. + Only prefixes that are required by a certain component are added to that + component - component must contain at least one file/directory/symbolic link + with :variable:`CPACK_RPM_RELOCATION_PATHS` prefix for a certain relocation + path to be added. Package will not contain any relocation paths if there are + no files/directories/symbolic links on any of the provided prefix locations. + Packages that either do not contain any relocation paths or contain + files/directories/symbolic links that are outside relocation paths print + out an ``AUTHOR_WARNING`` that RPM will be partially relocatable. + +.. variable:: CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX + + Per component relocation path install prefix. + + * Mandatory : NO + * Default : CPACK_PACKAGING_INSTALL_PREFIX + + May be used to set per component :variable:`CPACK_PACKAGING_INSTALL_PREFIX` + for relocatable RPM packages. + +.. variable:: CPACK_RPM_NO_INSTALL_PREFIX_RELOCATION + CPACK_RPM_NO_<COMPONENT>_INSTALL_PREFIX_RELOCATION + + Removal of default install prefix from relocation paths list. + + * Mandatory : NO + * Default : CPACK_PACKAGING_INSTALL_PREFIX or CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX + are treated as one of relocation paths + + May be used to remove CPACK_PACKAGING_INSTALL_PREFIX and CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX + from relocatable RPM prefix paths. + +.. variable:: CPACK_RPM_ADDITIONAL_MAN_DIRS + + * Mandatory : NO + * Default : - + + May be used to set additional man dirs that could potentially be compressed + by brp-compress RPM macro. Variable content must be a list of regular + expressions that point to directories containing man files or to man files + directly. Note that in order to compress man pages a path must also be + present in brp-compress RPM script and that brp-compress script must be + added to RPM configuration by the operating system. + + Regular expressions that are added by default were taken from brp-compress + RPM macro: + + - /usr/man/man.* + - /usr/man/.*/man.* + - /usr/info.* + - /usr/share/man/man.* + - /usr/share/man/.*/man.* + - /usr/share/info.* + - /usr/kerberos/man.* + - /usr/X11R6/man/man.* + - /usr/lib/perl5/man/man.* + - /usr/share/doc/.*/man/man.* + - /usr/lib/.*/man/man.* + +.. variable:: CPACK_RPM_DEFAULT_USER + CPACK_RPM_<compName>_DEFAULT_USER + + default user ownership of RPM content + + * Mandatory : NO + * Default : root + + Value should be user name and not UID. + Note that <compName> must be in upper-case. + +.. variable:: CPACK_RPM_DEFAULT_GROUP + CPACK_RPM_<compName>_DEFAULT_GROUP + + default group ownership of RPM content + + * Mandatory : NO + * Default : root + + Value should be group name and not GID. + Note that <compName> must be in upper-case. + +.. variable:: CPACK_RPM_DEFAULT_FILE_PERMISSIONS + CPACK_RPM_<compName>_DEFAULT_FILE_PERMISSIONS + + default permissions used for packaged files + + * Mandatory : NO + * Default : - (system default) + + Accepted values are lists with ``PERMISSIONS``. Valid permissions + are: + + - OWNER_READ + - OWNER_WRITE + - OWNER_EXECUTE + - GROUP_READ + - GROUP_WRITE + - GROUP_EXECUTE + - WORLD_READ + - WORLD_WRITE + - WORLD_EXECUTE + + Note that <compName> must be in upper-case. + +.. variable:: CPACK_RPM_DEFAULT_DIR_PERMISSIONS + CPACK_RPM_<compName>_DEFAULT_DIR_PERMISSIONS + + default permissions used for packaged directories + + * Mandatory : NO + * Default : - (system default) + + Accepted values are lists with PERMISSIONS. Valid permissions + are the same as for :variable:`CPACK_RPM_DEFAULT_FILE_PERMISSIONS`. + Note that <compName> must be in upper-case. + +.. variable:: CPACK_RPM_INSTALL_WITH_EXEC + + force execute permissions on programs and shared libraries + + * Mandatory : NO + * Default : - (system default) + + Force set owner, group and world execute permissions on programs and shared + libraries. This can be used for creating valid rpm packages on systems such + as Debian where shared libraries do not have execute permissions set. + +.. note:: + + Programs and shared libraries without execute permissions are ignored during + separation of debug symbols from the binary for debuginfo packages. + +Packaging of Symbolic Links +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The CPack RPM generator supports packaging of symbolic links:: + + execute_process(COMMAND ${CMAKE_COMMAND} + -E create_symlink <relative_path_location> <symlink_name>) + install(FILES ${CMAKE_CURRENT_BINARY_DIR}/<symlink_name> + DESTINATION <symlink_location> COMPONENT libraries) + +Symbolic links will be optimized (paths will be shortened if possible) +before being added to the package or if multiple relocation paths are +detected, a post install symlink relocation script will be generated. + +Symbolic links may point to locations that are not packaged by the same +package (either a different component or even not packaged at all) but +those locations will be treated as if they were a part of the package +while determining if symlink should be either created or present in a +post install script - depending on relocation paths. + +Symbolic links that point to locations outside packaging path produce a +warning and are treated as non relocatable permanent symbolic links. + +Currently there are a few limitations though: + +* For component based packaging component interdependency is not checked + when processing symbolic links. Symbolic links pointing to content of + a different component are treated the same way as if pointing to location + that will not be packaged. + +* Symbolic links pointing to a location through one or more intermediate + symbolic links will not be handled differently - if the intermediate + symbolic link(s) is also on a relocatable path, relocating it during + package installation may cause initial symbolic link to point to an + invalid location. + +Packaging of debug information +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Debuginfo packages contain debug symbols and sources for debugging packaged +binaries. + +Debuginfo RPM packaging has it's own set of variables: + +.. variable:: CPACK_RPM_DEBUGINFO_PACKAGE + CPACK_RPM_<component>_DEBUGINFO_PACKAGE + + Enable generation of debuginfo RPM package(s). + + * Mandatory : NO + * Default : OFF + +.. note:: + + Binaries must contain debug symbols before packaging so use either ``Debug`` + or ``RelWithDebInfo`` for :variable:`CMAKE_BUILD_TYPE` variable value. + +.. note:: + + Packages generated from packages without binary files, with binary files but + without execute permissions or without debug symbols will cause packaging + termination. + +.. variable:: CPACK_BUILD_SOURCE_DIRS + + Provides locations of root directories of source files from which binaries + were built. + + * Mandatory : YES if :variable:`CPACK_RPM_DEBUGINFO_PACKAGE` is set + * Default : - + +.. note:: + + For CMake project :variable:`CPACK_BUILD_SOURCE_DIRS` is set by default to + point to :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR` paths. + +.. note:: + + Sources with path prefixes that do not fall under any location provided with + :variable:`CPACK_BUILD_SOURCE_DIRS` will not be present in debuginfo package. + +.. variable:: CPACK_RPM_BUILD_SOURCE_DIRS_PREFIX + CPACK_RPM_<component>_BUILD_SOURCE_DIRS_PREFIX + + Prefix of location where sources will be placed during package installation. + + * Mandatory : YES if :variable:`CPACK_RPM_DEBUGINFO_PACKAGE` is set + * Default : "/usr/src/debug/<CPACK_PACKAGE_FILE_NAME>" and + for component packaging "/usr/src/debug/<CPACK_PACKAGE_FILE_NAME>-<component>" + +.. note:: + + Each source path prefix is additionally suffixed by ``src_<index>`` where + index is index of the path used from :variable:`CPACK_BUILD_SOURCE_DIRS` + variable. This produces ``<CPACK_RPM_BUILD_SOURCE_DIRS_PREFIX>/src_<index>`` + replacement path. + Limitation is that replaced path part must be shorter or of equal + length than the length of its replacement. If that is not the case either + :variable:`CPACK_RPM_BUILD_SOURCE_DIRS_PREFIX` variable has to be set to + a shorter path or source directories must be placed on a longer path. + +.. variable:: CPACK_RPM_DEBUGINFO_EXCLUDE_DIRS + + Directories containing sources that should be excluded from debuginfo packages. + + * Mandatory : NO + * Default : "/usr /usr/src /usr/src/debug" + + Listed paths are owned by other RPM packages and should therefore not be + deleted on debuginfo package uninstallation. + +.. variable:: CPACK_RPM_DEBUGINFO_EXCLUDE_DIRS_ADDITION + + Paths that should be appended to :variable:`CPACK_RPM_DEBUGINFO_EXCLUDE_DIRS` + for exclusion. + + * Mandatory : NO + * Default : - + +.. variable:: CPACK_RPM_DEBUGINFO_SINGLE_PACKAGE + + Create a single debuginfo package even if components packaging is set. + + * Mandatory : NO + * Default : OFF + + When this variable is enabled it produces a single debuginfo package even if + component packaging is enabled. + + When using this feature in combination with components packaging and there is + more than one component this variable requires :variable:`CPACK_RPM_MAIN_COMPONENT` + to be set. + +.. note:: + + If none of the :variable:`CPACK_RPM_<component>_DEBUGINFO_PACKAGE` variables + is set then :variable:`CPACK_RPM_DEBUGINFO_PACKAGE` is automatically set to + ``ON`` when :variable:`CPACK_RPM_DEBUGINFO_SINGLE_PACKAGE` is set. + +.. variable:: CPACK_RPM_DEBUGINFO_FILE_NAME + CPACK_RPM_<component>_DEBUGINFO_FILE_NAME + + Debuginfo package file name. + + * Mandatory : NO + * Default : rpmbuild tool generated package file name + + Alternatively provided debuginfo package file name must end with ``.rpm`` + suffix and should differ from file names of other generated packages. + + Variable may contain ``@cpack_component@`` placeholder which will be + replaced by component name if component packaging is enabled otherwise it + deletes the placeholder. + + Setting the variable to ``RPM-DEFAULT`` may be used to explicitly set + filename generation to default. + +.. note:: + + :variable:`CPACK_RPM_FILE_NAME` also supports rpmbuild tool generated package + file name - disabled by default but can be enabled by setting the variable to + ``RPM-DEFAULT``. + +Packaging of sources (SRPM) +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +SRPM packaging is enabled by setting :variable:`CPACK_RPM_PACKAGE_SOURCES` +variable while usually using :variable:`CPACK_INSTALLED_DIRECTORIES` variable +to provide directory containing CMakeLists.txt and source files. + +For CMake projects SRPM package would be produced by executing:: + + cpack -G RPM --config ./CPackSourceConfig.cmake + +.. note:: + + Produced SRPM package is expected to be built with :manual:`cmake(1)` executable + and packaged with :manual:`cpack(1)` executable so CMakeLists.txt has to be + located in root source directory and must be able to generate binary rpm + packages by executing ``cpack -G`` command. The two executables as well as + rpmbuild must also be present when generating binary rpm packages from the + produced SRPM package. + +Once the SRPM package is generated it can be used to generate binary packages +by creating a directory structure for rpm generation and executing rpmbuild +tool:: + + mkdir -p build_dir/{BUILD,BUILDROOT,RPMS,SOURCES,SPECS,SRPMS} + rpmbuild --define "_topdir <path_to_build_dir>" --rebuild <SRPM_file_name> + +Generated packages will be located in build_dir/RPMS directory or its sub +directories. + +.. note:: + + SRPM package internally uses CPack/RPM generator to generate binary packages + so CMakeScripts.txt can decide during the SRPM to binary rpm generation step + what content the package(s) should have as well as how they should be packaged + (monolithic or components). CMake can decide this for e.g. by reading environment + variables set by the package manager before starting the process of generating + binary rpm packages. This way a single SRPM package can be used to produce + different binary rpm packages on different platforms depending on the platform's + packaging rules. + +Source RPM packaging has it's own set of variables: + +.. variable:: CPACK_RPM_PACKAGE_SOURCES + + Should the content be packaged as a source rpm (default is binary rpm). + + * Mandatory : NO + * Default : OFF + +.. note:: + + For cmake projects :variable:`CPACK_RPM_PACKAGE_SOURCES` variable is set + to ``OFF`` in CPackConfig.cmake and ``ON`` in CPackSourceConfig.cmake + generated files. + +.. variable:: CPACK_RPM_SOURCE_PKG_BUILD_PARAMS + + Additional command-line parameters provided to :manual:`cmake(1)` executable. + + * Mandatory : NO + * Default : - + +.. variable:: CPACK_RPM_SOURCE_PKG_PACKAGING_INSTALL_PREFIX + + Packaging install prefix that would be provided in :variable:`CPACK_PACKAGING_INSTALL_PREFIX` + variable for producing binary RPM packages. + + * Mandatory : YES + * Default : "/" + +.. VARIABLE:: CPACK_RPM_BUILDREQUIRES + + List of source rpm build dependencies. + + * Mandatory : NO + * Default : - + + May be used to set source RPM build dependencies (BuildRequires). Note that + you must enclose the complete build requirements string between quotes, for + example:: + + set(CPACK_RPM_BUILDREQUIRES "python >= 2.5.0, cmake >= 2.8") diff --git a/Help/cpack_gen/wix.rst b/Help/cpack_gen/wix.rst new file mode 100644 index 0000000..3822fa0 --- /dev/null +++ b/Help/cpack_gen/wix.rst @@ -0,0 +1,284 @@ +CPack WiX Generator +------------------- + +CPack WiX generator specific options + +Variables specific to CPack WiX generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following variables are specific to the installers built on +Windows using WiX. + +.. variable:: CPACK_WIX_UPGRADE_GUID + + Upgrade GUID (``Product/@UpgradeCode``) + + Will be automatically generated unless explicitly provided. + + It should be explicitly set to a constant generated globally unique + identifier (GUID) to allow your installers to replace existing + installations that use the same GUID. + + You may for example explicitly set this variable in your + CMakeLists.txt to the value that has been generated per default. You + should not use GUIDs that you did not generate yourself or which may + belong to other projects. + + A GUID shall have the following fixed length syntax:: + + XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX + + (each X represents an uppercase hexadecimal digit) + +.. variable:: CPACK_WIX_PRODUCT_GUID + + Product GUID (``Product/@Id``) + + Will be automatically generated unless explicitly provided. + + If explicitly provided this will set the Product Id of your installer. + + The installer will abort if it detects a pre-existing installation that + uses the same GUID. + + The GUID shall use the syntax described for CPACK_WIX_UPGRADE_GUID. + +.. variable:: CPACK_WIX_LICENSE_RTF + + RTF License File + + If CPACK_RESOURCE_FILE_LICENSE has an .rtf extension it is used as-is. + + If CPACK_RESOURCE_FILE_LICENSE has an .txt extension it is implicitly + converted to RTF by the WiX Generator. + The expected encoding of the .txt file is UTF-8. + + With CPACK_WIX_LICENSE_RTF you can override the license file used by the + WiX Generator in case CPACK_RESOURCE_FILE_LICENSE is in an unsupported + format or the .txt -> .rtf conversion does not work as expected. + +.. variable:: CPACK_WIX_PRODUCT_ICON + + The Icon shown next to the program name in Add/Remove programs. + + If set, this icon is used in place of the default icon. + +.. variable:: CPACK_WIX_UI_REF + + This variable allows you to override the Id of the ``<UIRef>`` element + in the WiX template. + + The default is ``WixUI_InstallDir`` in case no CPack components have + been defined and ``WixUI_FeatureTree`` otherwise. + +.. variable:: CPACK_WIX_UI_BANNER + + The bitmap will appear at the top of all installer pages other than the + welcome and completion dialogs. + + If set, this image will replace the default banner image. + + This image must be 493 by 58 pixels. + +.. variable:: CPACK_WIX_UI_DIALOG + + Background bitmap used on the welcome and completion dialogs. + + If this variable is set, the installer will replace the default dialog + image. + + This image must be 493 by 312 pixels. + +.. variable:: CPACK_WIX_PROGRAM_MENU_FOLDER + + Start menu folder name for launcher. + + If this variable is not set, it will be initialized with CPACK_PACKAGE_NAME + +.. variable:: CPACK_WIX_CULTURES + + Language(s) of the installer + + Languages are compiled into the WixUI extension library. To use them, + simply provide the name of the culture. If you specify more than one + culture identifier in a comma or semicolon delimited list, the first one + that is found will be used. You can find a list of supported languages at: + http://wix.sourceforge.net/manual-wix3/WixUI_localization.htm + +.. variable:: CPACK_WIX_TEMPLATE + + Template file for WiX generation + + If this variable is set, the specified template will be used to generate + the WiX wxs file. This should be used if further customization of the + output is required. + + If this variable is not set, the default MSI template included with CMake + will be used. + +.. variable:: CPACK_WIX_PATCH_FILE + + Optional list of XML files with fragments to be inserted into + generated WiX sources + + This optional variable can be used to specify an XML file that the + WiX generator will use to inject fragments into its generated + source files. + + Patch files understood by the CPack WiX generator + roughly follow this RELAX NG compact schema: + + .. code-block:: none + + start = CPackWiXPatch + + CPackWiXPatch = element CPackWiXPatch { CPackWiXFragment* } + + CPackWiXFragment = element CPackWiXFragment + { + attribute Id { string }, + fragmentContent* + } + + fragmentContent = element * - CPackWiXFragment + { + (attribute * { text } | text | fragmentContent)* + } + + Currently fragments can be injected into most + Component, File, Directory and Feature elements. + + The following additional special Ids can be used: + + * ``#PRODUCT`` for the ``<Product>`` element. + * ``#PRODUCTFEATURE`` for the root ``<Feature>`` element. + + The following example illustrates how this works. + + Given that the WiX generator creates the following XML element: + + .. code-block:: xml + + <Component Id="CM_CP_applications.bin.my_libapp.exe" Guid="*"/> + + The following XML patch file may be used to inject an Environment element + into it: + + .. code-block:: xml + + <CPackWiXPatch> + <CPackWiXFragment Id="CM_CP_applications.bin.my_libapp.exe"> + <Environment Id="MyEnvironment" Action="set" + Name="MyVariableName" Value="MyVariableValue"/> + </CPackWiXFragment> + </CPackWiXPatch> + +.. variable:: CPACK_WIX_EXTRA_SOURCES + + Extra WiX source files + + This variable provides an optional list of extra WiX source files (.wxs) + that should be compiled and linked. The full path to source files is + required. + +.. variable:: CPACK_WIX_EXTRA_OBJECTS + + Extra WiX object files or libraries + + This variable provides an optional list of extra WiX object (.wixobj) + and/or WiX library (.wixlib) files. The full path to objects and libraries + is required. + +.. variable:: CPACK_WIX_EXTENSIONS + + This variable provides a list of additional extensions for the WiX + tools light and candle. + +.. variable:: CPACK_WIX_<TOOL>_EXTENSIONS + + This is the tool specific version of CPACK_WIX_EXTENSIONS. + ``<TOOL>`` can be either LIGHT or CANDLE. + +.. variable:: CPACK_WIX_<TOOL>_EXTRA_FLAGS + + This list variable allows you to pass additional + flags to the WiX tool ``<TOOL>``. + + Use it at your own risk. + Future versions of CPack may generate flags which may be in conflict + with your own flags. + + ``<TOOL>`` can be either LIGHT or CANDLE. + +.. variable:: CPACK_WIX_CMAKE_PACKAGE_REGISTRY + + If this variable is set the generated installer will create + an entry in the windows registry key + ``HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<package>`` + The value for ``<package>`` is provided by this variable. + + Assuming you also install a CMake configuration file this will + allow other CMake projects to find your package with + the :command:`find_package` command. + +.. variable:: CPACK_WIX_PROPERTY_<PROPERTY> + + This variable can be used to provide a value for + the Windows Installer property ``<PROPERTY>`` + + The following list contains some example properties that can be used to + customize information under + "Programs and Features" (also known as "Add or Remove Programs") + + * ARPCOMMENTS - Comments + * ARPHELPLINK - Help and support information URL + * ARPURLINFOABOUT - General information URL + * ARPURLUPDATEINFO - Update information URL + * ARPHELPTELEPHONE - Help and support telephone number + * ARPSIZE - Size (in kilobytes) of the application + +.. variable:: CPACK_WIX_ROOT_FEATURE_TITLE + + Sets the name of the root install feature in the WIX installer. Same as + CPACK_COMPONENT_<compName>_DISPLAY_NAME for components. + +.. variable:: CPACK_WIX_ROOT_FEATURE_DESCRIPTION + + Sets the description of the root install feature in the WIX installer. Same as + CPACK_COMPONENT_<compName>_DESCRIPTION for components. + +.. variable:: CPACK_WIX_SKIP_PROGRAM_FOLDER + + If this variable is set to true, the default install location + of the generated package will be CPACK_PACKAGE_INSTALL_DIRECTORY directly. + The install location will not be located relatively below + ProgramFiles or ProgramFiles64. + + .. note:: + Installers created with this feature do not take differences + between the system on which the installer is created + and the system on which the installer might be used into account. + + It is therefore possible that the installer e.g. might try to install + onto a drive that is unavailable or unintended or a path that does not + follow the localization or convention of the system on which the + installation is performed. + +.. variable:: CPACK_WIX_ROOT_FOLDER_ID + + This variable allows specification of a custom root folder ID. + The generator specific ``<64>`` token can be used for + folder IDs that come in 32-bit and 64-bit variants. + In 32-bit builds the token will expand empty while in 64-bit builds + it will expand to ``64``. + + When unset generated installers will default installing to + ``ProgramFiles<64>Folder``. + +.. variable:: CPACK_WIX_ROOT + + This variable can optionally be set to the root directory + of a custom WiX Toolset installation. + + When unspecified CPack will try to locate a WiX Toolset + installation via the ``WIX`` environment variable instead. diff --git a/Help/dev/maint.rst b/Help/dev/maint.rst index ec76479..a8942cd 100644 --- a/Help/dev/maint.rst +++ b/Help/dev/maint.rst @@ -51,15 +51,18 @@ using a local branch named ``release-$ver``, where ``$ver`` is the version number of the current release in the form ``$major.$minor``. It is always merged into ``master`` before publishing. -To merge some ``$topic`` branch into ``release``, first create the local -branch: +Before merging a ``$topic`` branch into ``release``, verify that the +``$topic`` branch has already been merged to ``master`` via the usual +``Do: merge`` process. Then, to merge the ``$topic`` branch into +``release``, start by creating the local branch: .. code-block:: shell git fetch origin git checkout -b release-$ver origin/release -Merge the ``$topic`` branch into the local ``release-$ver`` branch: +Merge the ``$topic`` branch into the local ``release-$ver`` branch, making +sure to include a ``Merge-request: !xxxx`` footer in the commit message: .. code-block:: shell diff --git a/Help/dev/testing.rst b/Help/dev/testing.rst index 1b29acf..23d0ca3 100644 --- a/Help/dev/testing.rst +++ b/Help/dev/testing.rst @@ -26,13 +26,14 @@ commands to set up a new integration testing client: $ git clone https://gitlab.kitware.com/cmake/dashboard-scripts.git CMakeScripts $ cd CMakeScripts -The ``cmake_common.cmake`` script contains comments at the top with +The `cmake_common.cmake`_ script contains comments at the top with instructions to set up a testing client. As it instructs, create a CTest script with local settings and include ``cmake_common.cmake``. .. _`CMake Review Process`: review.rst .. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake .. _`CMake Dashboard Scripts Repository`: https://gitlab.kitware.com/cmake/dashboard-scripts +.. _`cmake_common.cmake`: https://gitlab.kitware.com/cmake/dashboard-scripts/blob/master/cmake_common.cmake Nightly Start Time ------------------ diff --git a/Help/envvar/PackageName_ROOT.rst b/Help/envvar/PackageName_ROOT.rst new file mode 100644 index 0000000..e01009b --- /dev/null +++ b/Help/envvar/PackageName_ROOT.rst @@ -0,0 +1,15 @@ +<PackageName>_ROOT +------------------ + +Calls to :command:`find_package(<PackageName>)` will search in prefixes +specified by the ``<PackageName>_ROOT`` environment variable, where +``<PackageName>`` is the name given to the ``find_package`` call +and ``_ROOT`` is literal. For example, ``find_package(Foo)`` will search +prefixes specified in the ``Foo_ROOT`` environment variable (if set). +See policy :policy:`CMP0074`. + +This variable may hold a single prefix or a list of prefixes separated +by ``:`` on UNIX or ``;`` on Windows (the same as the ``PATH`` environment +variable convention on those platforms). + +See also the :variable:`<PackageName>_ROOT` CMake variable. diff --git a/Help/generator/Green Hills MULTI.rst b/Help/generator/Green Hills MULTI.rst index 4d31690..1b4960d 100644 --- a/Help/generator/Green Hills MULTI.rst +++ b/Help/generator/Green Hills MULTI.rst @@ -3,12 +3,48 @@ Green Hills MULTI Generates Green Hills MULTI project files (experimental, work-in-progress). -Customizations are available through the following cache variables: +Customizations that are used to pick toolset and target system: + +The ``-A <arch>`` can be supplied for setting the target architecture. +``<arch>`` usually is one of "arm", "ppc", "86", etcetera. If the target architecture +is not specified then the default architecture of "arm" will be used. + +The ``-T <toolset>`` can be supplied for setting the toolset to be used. +All toolsets are expected to be located at ``GHS_TOOLSET_ROOT``. +If the toolset is not specified then the latest toolset will be used. + +* ``GHS_TARGET_PLATFORM`` + +Default to ``integrity``. +Usual values are ``integrity``, ``threadx``, ``uvelosity``, +``velosity``, ``vxworks``, ``standalone``. + +* ``GHS_PRIMARY_TARGET`` + +Sets ``primaryTarget`` field in project file. +Defaults to ``<arch>_<GHS_TARGET_PLATFORM>.tgt``. + +* ``GHS_TOOLSET_ROOT`` + +Default to ``C:/ghs``. Root path for ``toolset``. + +* ``GHS_OS_ROOT`` + +Default to ``C:/ghs``. Root path for RTOS searches. + +* ``GHS_OS_DIR`` + +Default to latest platform OS installation at ``GHS_OS_ROOT``. Set this value if +a specific RTOS is to be used. * ``GHS_BSP_NAME`` + +Defaults to ``sim<arch>`` if not set by user. + +Customizations are available through the following cache variables: + * ``GHS_CUSTOMIZATION`` * ``GHS_GPJ_MACROS`` -* ``GHS_OS_DIR`` .. note:: This generator is deemed experimental as of CMake |release| diff --git a/Help/index.rst b/Help/index.rst index fa5273c..fe1b73c 100644 --- a/Help/index.rst +++ b/Help/index.rst @@ -41,6 +41,7 @@ Reference Manuals /manual/cmake-server.7 /manual/cmake-toolchains.7 /manual/cmake-variables.7 + /manual/cpack-generators.7 .. only:: html or text diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 49375e9..dd7934a 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -784,7 +784,7 @@ A *library* output artifact of a buildsystem target may be: with the ``MODULE`` option. * On non-DLL platforms: the shared library file (e.g. ``.so`` or ``.dylib``) - of a shared shared library target created by the :command:`add_library` + of a shared library target created by the :command:`add_library` command with the ``SHARED`` option. The :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY` and :prop_tgt:`LIBRARY_OUTPUT_NAME` diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst index 408a3a0..753647d 100644 --- a/Help/manual/cmake-commands.7.rst +++ b/Help/manual/cmake-commands.7.rst @@ -78,6 +78,7 @@ These commands are available only in CMake projects. /command/add_dependencies /command/add_executable /command/add_library + /command/add_link_options /command/add_subdirectory /command/add_test /command/aux_source_directory @@ -111,6 +112,7 @@ These commands are available only in CMake projects. /command/target_compile_options /command/target_include_directories /command/target_link_libraries + /command/target_link_options /command/target_sources /command/try_compile /command/try_run diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index 2d17bb5..42aeabc 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -20,6 +20,7 @@ Environment Variables that Control the Build /envvar/DESTDIR /envvar/LDFLAGS /envvar/MACOSX_DEPLOYMENT_TARGET + /envvar/PackageName_ROOT Environment Variables for Languages =================================== diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 8ef4d7d..b7276b6 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -54,22 +54,10 @@ All Modules /module/CMakePrintSystemInformation /module/CMakePushCheckState /module/CMakeVerifyManifest - /module/CPackArchive - /module/CPackBundle /module/CPackComponent - /module/CPackCygwin - /module/CPackDeb - /module/CPackDMG - /module/CPackFreeBSD /module/CPackIFW /module/CPackIFWConfigureFile - /module/CPackNSIS - /module/CPackNuGet - /module/CPackPackageMaker - /module/CPackProductBuild - /module/CPackRPM /module/CPack - /module/CPackWIX /module/CSharpUtilities /module/CTest /module/CTestCoverageCollectGCOV @@ -263,3 +251,26 @@ All Modules /module/Use_wxWindows /module/WriteBasicConfigVersionFile /module/WriteCompilerDetectionHeader + +Legacy CPack Modules +==================== + +These modules used to be mistakenly exposed to the user, and have been moved +out of user visibility. They are for CPack internal use, and should never be +used directly. + +.. toctree:: + :maxdepth: 1 + + /module/CPackArchive + /module/CPackBundle + /module/CPackCygwin + /module/CPackDeb + /module/CPackDMG + /module/CPackFreeBSD + /module/CPackNSIS + /module/CPackNuGet + /module/CPackPackageMaker + /module/CPackProductBuild + /module/CPackRPM + /module/CPackWIX diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 631f75b..32a0118 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,16 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used to determine whether to report an error on use of deprecated macros or functions. +Policies Introduced by CMake 3.13 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0078: UseSWIG generates standard target names. </policy/CMP0078> + CMP0077: option() honors normal variables. </policy/CMP0077> + CMP0076: target_sources() command converts relative paths to absolute. </policy/CMP0076> + Policies Introduced by CMake 3.12 ================================= diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 9f9c53f..274206f 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -77,6 +77,7 @@ Properties on Directories /prop_dir/INTERPROCEDURAL_OPTIMIZATION /prop_dir/LABELS /prop_dir/LINK_DIRECTORIES + /prop_dir/LINK_OPTIONS /prop_dir/LISTFILE_STACK /prop_dir/MACROS /prop_dir/PARENT_DIRECTORY @@ -172,6 +173,7 @@ Properties on Targets /prop_tgt/DEBUG_POSTFIX /prop_tgt/DEFINE_SYMBOL /prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY + /prop_tgt/DEPLOYMENT_ADDITIONAL_FILES /prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION /prop_tgt/EchoString /prop_tgt/ENABLE_EXPORTS @@ -197,6 +199,7 @@ Properties on Targets /prop_tgt/IMPORTED_LIBNAME_CONFIG /prop_tgt/IMPORTED_LIBNAME /prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES_CONFIG + /prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES_CONFIG /prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES /prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES_CONFIG /prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES @@ -224,7 +227,9 @@ Properties on Targets /prop_tgt/INTERFACE_COMPILE_FEATURES /prop_tgt/INTERFACE_COMPILE_OPTIONS /prop_tgt/INTERFACE_INCLUDE_DIRECTORIES + /prop_tgt/INTERFACE_LINK_DEPENDS /prop_tgt/INTERFACE_LINK_LIBRARIES + /prop_tgt/INTERFACE_LINK_OPTIONS /prop_tgt/INTERFACE_POSITION_INDEPENDENT_CODE /prop_tgt/INTERFACE_SOURCES /prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES @@ -254,6 +259,7 @@ Properties on Targets /prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG /prop_tgt/LINK_INTERFACE_MULTIPLICITY /prop_tgt/LINK_LIBRARIES + /prop_tgt/LINK_OPTIONS /prop_tgt/LINK_SEARCH_END_STATIC /prop_tgt/LINK_SEARCH_START_STATIC /prop_tgt/LINK_WHAT_YOU_USE @@ -300,8 +306,10 @@ Properties on Targets /prop_tgt/VERSION /prop_tgt/VISIBILITY_INLINES_HIDDEN /prop_tgt/VS_CONFIGURATION_TYPE - /prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY /prop_tgt/VS_DEBUGGER_COMMAND + /prop_tgt/VS_DEBUGGER_COMMAND_ARGUMENTS + /prop_tgt/VS_DEBUGGER_ENVIRONMENT + /prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY /prop_tgt/VS_DESKTOP_EXTENSIONS_VERSION /prop_tgt/VS_DOTNET_REFERENCE_refname /prop_tgt/VS_DOTNET_REFERENCEPROP_refname_TAG_tagname diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index edfff6c..48b1f20 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -204,6 +204,7 @@ Variables that Change Behavior /variable/CMAKE_WARN_DEPRECATED /variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION /variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY + /variable/PackageName_ROOT Variables that Describe the System ================================== @@ -290,6 +291,7 @@ Variables that Control the Build /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG /variable/CMAKE_AUTOGEN_PARALLEL + /variable/CMAKE_AUTOGEN_VERBOSE /variable/CMAKE_AUTOMOC /variable/CMAKE_AUTOMOC_COMPILER_PREDEFINES /variable/CMAKE_AUTOMOC_DEPEND_FILTERS @@ -460,6 +462,8 @@ Variables for Languages /variable/CMAKE_LANG_LIBRARY_ARCHITECTURE /variable/CMAKE_LANG_LINKER_PREFERENCE /variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES + /variable/CMAKE_LANG_LINKER_WRAPPER_FLAG + /variable/CMAKE_LANG_LINKER_WRAPPER_FLAG_SEP /variable/CMAKE_LANG_LINK_EXECUTABLE /variable/CMAKE_LANG_OUTPUT_EXTENSION /variable/CMAKE_LANG_PLATFORM_ID diff --git a/Help/manual/cpack-generators.7.rst b/Help/manual/cpack-generators.7.rst new file mode 100644 index 0000000..ade9149 --- /dev/null +++ b/Help/manual/cpack-generators.7.rst @@ -0,0 +1,29 @@ +.. cmake-manual-description: CPack Generator Reference + +cpack-generators(7) +******************* + +.. only:: html + + .. contents:: + +Generators +========== + +.. toctree:: + :maxdepth: 1 + + /cpack_gen/archive + /cpack_gen/bundle + /cpack_gen/cygwin + /cpack_gen/deb + /cpack_gen/dmg + /cpack_gen/external + /cpack_gen/freebsd + /cpack_gen/ifw + /cpack_gen/nsis + /cpack_gen/nuget + /cpack_gen/packagemaker + /cpack_gen/productbuild + /cpack_gen/rpm + /cpack_gen/wix diff --git a/Help/module/CPackArchive.rst b/Help/module/CPackArchive.rst index eb8d9d2..8616098 100644 --- a/Help/module/CPackArchive.rst +++ b/Help/module/CPackArchive.rst @@ -1 +1,4 @@ -.. cmake-module:: ../../Modules/CPackArchive.cmake +CPackArchive +------------ + +The documentation for the CPack Archive generator has moved here: :cpack_gen:`CPack Archive Generator` diff --git a/Help/module/CPackBundle.rst b/Help/module/CPackBundle.rst index 651e874..5134884 100644 --- a/Help/module/CPackBundle.rst +++ b/Help/module/CPackBundle.rst @@ -1 +1,4 @@ -.. cmake-module:: ../../Modules/CPackBundle.cmake +CPackBundle +----------- + +The documentation for the CPack Bundle generator has moved here: :cpack_gen:`CPack Bundle Generator` diff --git a/Help/module/CPackCygwin.rst b/Help/module/CPackCygwin.rst index 21f4473..719dfce 100644 --- a/Help/module/CPackCygwin.rst +++ b/Help/module/CPackCygwin.rst @@ -1 +1,4 @@ -.. cmake-module:: ../../Modules/CPackCygwin.cmake +CPackCygwin +----------- + +The documentation for the CPack Cygwin generator has moved here: :cpack_gen:`CPack Cygwin Generator` diff --git a/Help/module/CPackDMG.rst b/Help/module/CPackDMG.rst index 784262c..a597002 100644 --- a/Help/module/CPackDMG.rst +++ b/Help/module/CPackDMG.rst @@ -1 +1,4 @@ -.. cmake-module:: ../../Modules/CPackDMG.cmake +CPackDMG +-------- + +The documentation for the CPack DMG generator has moved here: :cpack_gen:`CPack DMG Generator` diff --git a/Help/module/CPackDeb.rst b/Help/module/CPackDeb.rst index d1526ee..73e59a2 100644 --- a/Help/module/CPackDeb.rst +++ b/Help/module/CPackDeb.rst @@ -1 +1,4 @@ -.. cmake-module:: ../../Modules/CPackDeb.cmake +CPackDeb +-------- + +The documentation for the CPack Deb generator has moved here: :cpack_gen:`CPack Deb Generator` diff --git a/Help/module/CPackFreeBSD.rst b/Help/module/CPackFreeBSD.rst index 083f0cb..69701b8 100644 --- a/Help/module/CPackFreeBSD.rst +++ b/Help/module/CPackFreeBSD.rst @@ -1 +1,4 @@ -.. cmake-module:: ../../Modules/CPackFreeBSD.cmake +CPackFreeBSD +------------ + +The documentation for the CPack FreeBSD generator has moved here: :cpack_gen:`CPack FreeBSD Generator` diff --git a/Help/module/CPackNSIS.rst b/Help/module/CPackNSIS.rst index bb35ed6..2cb407a 100644 --- a/Help/module/CPackNSIS.rst +++ b/Help/module/CPackNSIS.rst @@ -1 +1,4 @@ -.. cmake-module:: ../../Modules/CPackNSIS.cmake +CPackNSIS +--------- + +The documentation for the CPack NSIS generator has moved here: :cpack_gen:`CPack NSIS Generator` diff --git a/Help/module/CPackNuGet.rst b/Help/module/CPackNuGet.rst index a4cbb59..4f39b3a 100644 --- a/Help/module/CPackNuGet.rst +++ b/Help/module/CPackNuGet.rst @@ -1 +1,4 @@ -.. cmake-module:: ../../Modules/CPackNuGet.cmake +CPackNuGet +---------- + +The documentation for the CPack NuGet generator has moved here: :cpack_gen:`CPack NuGet Generator` diff --git a/Help/module/CPackPackageMaker.rst b/Help/module/CPackPackageMaker.rst index de55448..226b6fd 100644 --- a/Help/module/CPackPackageMaker.rst +++ b/Help/module/CPackPackageMaker.rst @@ -1 +1,4 @@ -.. cmake-module:: ../../Modules/CPackPackageMaker.cmake +CPackPackageMaker +----------------- + +The documentation for the CPack PackageMaker generator has moved here: :cpack_gen:`CPack PackageMaker Generator` diff --git a/Help/module/CPackProductBuild.rst b/Help/module/CPackProductBuild.rst index 6081fe4..8cd9198 100644 --- a/Help/module/CPackProductBuild.rst +++ b/Help/module/CPackProductBuild.rst @@ -1 +1,4 @@ -.. cmake-module:: ../../Modules/CPackProductBuild.cmake +CPackProductBuild +----------------- + +The documentation for the CPack productbuild generator has moved here: :cpack_gen:`CPack productbuild Generator` diff --git a/Help/module/CPackRPM.rst b/Help/module/CPackRPM.rst index 28d0e69..00b7e0a 100644 --- a/Help/module/CPackRPM.rst +++ b/Help/module/CPackRPM.rst @@ -1 +1,4 @@ -.. cmake-module:: ../../Modules/CPackRPM.cmake +CPackRPM +-------- + +The documentation for the CPack RPM generator has moved here: :cpack_gen:`CPack RPM Generator` diff --git a/Help/module/CPackWIX.rst b/Help/module/CPackWIX.rst index 1f5e451..e1d4a03 100644 --- a/Help/module/CPackWIX.rst +++ b/Help/module/CPackWIX.rst @@ -1 +1,4 @@ -.. cmake-module:: ../../Modules/CPackWIX.cmake +CPackWIX +-------- + +The documentation for the CPack WiX generator has moved here: :cpack_gen:`CPack WiX Generator` diff --git a/Help/policy/CMP0074.rst b/Help/policy/CMP0074.rst index ffac4a7..896936b 100644 --- a/Help/policy/CMP0074.rst +++ b/Help/policy/CMP0074.rst @@ -1,18 +1,19 @@ CMP0074 ------- -:command:`find_package` uses ``PackageName_ROOT`` variables. +:command:`find_package` uses ``<PackageName>_ROOT`` variables. -In CMake 3.12 and above the ``find_package(PackageName)`` command now searches -a prefix specified by a ``PackageName_ROOT`` CMake or environment variable. +In CMake 3.12 and above the :command:`find_package(<PackageName>)` command now +searches prefixes specified by the :variable:`<PackageName>_ROOT` CMake +variable and the :envvar:`<PackageName>_ROOT` environment variable. Package roots are maintained as a stack so nested calls to all ``find_*`` commands inside find modules also search the roots as prefixes. This policy provides compatibility with projects that have not been updated to avoid using -``PackageName_ROOT`` variables for other purposes. +``<PackageName>_ROOT`` variables for other purposes. -The ``OLD`` behavior for this policy is to ignore ``PackageName_ROOT`` -variables. The ``NEW`` behavior for this policy is to use ``PackageName_ROOT`` -variables. +The ``OLD`` behavior for this policy is to ignore ``<PackageName>_ROOT`` +variables. The ``NEW`` behavior for this policy is to use +``<PackageName>_ROOT`` variables. This policy was introduced in CMake version 3.12. CMake version |release| warns when the policy is not set and uses ``OLD`` behavior. diff --git a/Help/policy/CMP0076.rst b/Help/policy/CMP0076.rst new file mode 100644 index 0000000..dd25f80 --- /dev/null +++ b/Help/policy/CMP0076.rst @@ -0,0 +1,26 @@ +CMP0076 +------- + +The :command:`target_sources` command converts relative paths to absolute. + +In CMake 3.13 and above, the :command:`target_sources` command now converts +relative source file paths to absolute paths in the following cases: + +* Source files are added to the target's :prop_tgt:`INTERFACE_SOURCES` + property. +* The target's :prop_tgt:`SOURCE_DIR` property differs from + :variable:`CMAKE_CURRENT_SOURCE_DIR`. + +A path that begins with a generator expression is always left unmodified. + +This policy provides compatibility with projects that have not been updated +to expect this behavior. The ``OLD`` behavior for this policy is to leave +all relative source file paths unmodified. The ``NEW`` behavior of this +policy is to convert relative paths to absolute according to above rules. + +This policy was introduced in CMake version 3.13. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0077.rst b/Help/policy/CMP0077.rst new file mode 100644 index 0000000..8efe198 --- /dev/null +++ b/Help/policy/CMP0077.rst @@ -0,0 +1,16 @@ +CMP0077 +------- + +:command:`option` honors normal variables. + +The ``OLD`` behavior for this policy is to clear any existing normal variables +with the same name. The ``NEW`` behavior for this policy is to not create +a cache entry or modify any existing normal variables if a normal variable +with the same name already exists. + +This policy was introduced in CMake version 3.13. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0078.rst b/Help/policy/CMP0078.rst new file mode 100644 index 0000000..54cdc9c --- /dev/null +++ b/Help/policy/CMP0078.rst @@ -0,0 +1,22 @@ +CMP0078 +------- + +Starting with CMake 3.13, :module:`UseSWIG` generates now standard target +names. This policy provides compatibility with projects that expect the legacy +behavior. + +The ``OLD`` behavior for this policy relies on +``UseSWIG_TARGET_NAME_PREFERENCE`` variable that can be used to specify an +explicit preference. The value may be one of: + +* ``LEGACY``: legacy strategy is applied. Variable + ``SWIG_MODULE_<name>_REAL_NAME`` must be used to get real target name. + This is the default if not specified. +* ``STANDARD``: target name matches specified name. + +This policy was introduced in CMake version 3.13. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/prop_dir/LINK_OPTIONS.rst b/Help/prop_dir/LINK_OPTIONS.rst new file mode 100644 index 0000000..04b9e08 --- /dev/null +++ b/Help/prop_dir/LINK_OPTIONS.rst @@ -0,0 +1,16 @@ +LINK_OPTIONS +------------ + +List of options to use for the link step. + +This property holds a :ref:`;-list <CMake Language Lists>` of options +given so far to the :command:`add_link_options` command. + +This property is used to initialize the :prop_tgt:`LINK_OPTIONS` target +property when a target is created, which is used by the generators to set +the options for the compiler. + +Contents of ``LINK_OPTIONS`` may use "generator expressions" with the +syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual +for available expressions. See the :manual:`cmake-buildsystem(7)` manual +for more on defining buildsystem properties. diff --git a/Help/prop_tgt/DEPLOYMENT_ADDITIONAL_FILES.rst b/Help/prop_tgt/DEPLOYMENT_ADDITIONAL_FILES.rst new file mode 100644 index 0000000..5e9c191 --- /dev/null +++ b/Help/prop_tgt/DEPLOYMENT_ADDITIONAL_FILES.rst @@ -0,0 +1,18 @@ +DEPLOYMENT_ADDITIONAL_FILES +--------------------------- + +Set the WinCE project ``AdditionalFiles`` in ``DeploymentTool`` in ``.vcproj`` +files generated by the :generator:`Visual Studio 9 2008` generator. +This is useful when you want to debug on remote WinCE device. +Specify additional files that will be copied to the device. +For example: + +.. code-block:: cmake + + set_property(TARGET ${TARGET} PROPERTY + DEPLOYMENT_ADDITIONAL_FILES "english.lng|local_folder|remote_folder|0" + "german.lng|local_folder|remote_folder|0") + +produces:: + + <DeploymentTool AdditionalFiles="english.lng|local_folder|remote_folder|0;german.lng|local_folder|remote_folder|0" ... /> diff --git a/Help/prop_tgt/INTERFACE_LINK_DEPENDS.rst b/Help/prop_tgt/INTERFACE_LINK_DEPENDS.rst new file mode 100644 index 0000000..d07f8ea --- /dev/null +++ b/Help/prop_tgt/INTERFACE_LINK_DEPENDS.rst @@ -0,0 +1,31 @@ +INTERFACE_LINK_DEPENDS +---------------------- + +Additional public interface files on which a target binary depends for linking. + +This property is supported only by Makefile and Ninja generators. It is +intended to specify dependencies on "linker scripts" for custom Makefile link +rules. + +When target dependencies are specified using :command:`target_link_libraries`, +CMake will read this property from all target dependencies to determine the +build properties of the consumer. + +Contents of ``INTERFACE_LINK_DEPENDS`` may use "generator expressions" +with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. See the :manual:`cmake-buildsystem(7)` +-manual for more on defining buildsystem properties. + +Link dependency files usage requirements commonly differ between the build-tree +and the install-tree. The ``BUILD_INTERFACE`` and ``INSTALL_INTERFACE`` +generator expressions can be used to describe separate usage requirements +based on the usage location. Relative paths are allowed within the +``INSTALL_INTERFACE`` expression and are interpreted relative to the +installation prefix. For example: + +.. code-block:: cmake + + set_property(TARGET mylib PROPERTY INTERFACE_LINK_DEPENDS + $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/mylinkscript> + $<INSTALL_INTERFACE:mylinkscript> # <prefix>/mylinkscript + ) diff --git a/Help/prop_tgt/INTERFACE_LINK_OPTIONS.rst b/Help/prop_tgt/INTERFACE_LINK_OPTIONS.rst new file mode 100644 index 0000000..c293b98 --- /dev/null +++ b/Help/prop_tgt/INTERFACE_LINK_OPTIONS.rst @@ -0,0 +1,9 @@ +INTERFACE_LINK_OPTIONS +---------------------- + +.. |property_name| replace:: link options +.. |command_name| replace:: :command:`target_link_options` +.. |PROPERTY_INTERFACE_NAME| replace:: ``INTERFACE_LINK_OPTIONS`` +.. |PROPERTY_LINK| replace:: :prop_tgt:`LINK_OPTIONS` +.. |PROPERTY_GENEX| replace:: ``$<TARGET_PROPERTY:foo,INTERFACE_LINK_OPTIONS>`` +.. include:: INTERFACE_BUILD_PROPERTY.txt diff --git a/Help/prop_tgt/LINK_DEPENDS.rst b/Help/prop_tgt/LINK_DEPENDS.rst index 5576b85..3ab8658 100644 --- a/Help/prop_tgt/LINK_DEPENDS.rst +++ b/Help/prop_tgt/LINK_DEPENDS.rst @@ -7,6 +7,11 @@ Specifies a semicolon-separated list of full-paths to files on which the link rule for this target depends. The target binary will be linked if any of the named files is newer than it. -This property is ignored by non-Makefile generators. It is intended -to specify dependencies on "linker scripts" for custom Makefile link +This property is supported only by Makefile and Ninja generators. It is +intended to specify dependencies on "linker scripts" for custom Makefile link rules. + +Contents of ``LINK_DEPENDS`` may use "generator expressions" with +the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. See the :manual:`cmake-buildsystem(7)` +manual for more on defining buildsystem properties. diff --git a/Help/prop_tgt/LINK_FLAGS.rst b/Help/prop_tgt/LINK_FLAGS.rst index b09e7c1..e0b72b5 100644 --- a/Help/prop_tgt/LINK_FLAGS.rst +++ b/Help/prop_tgt/LINK_FLAGS.rst @@ -3,7 +3,11 @@ LINK_FLAGS Additional flags to use when linking this target. -The LINK_FLAGS property can be used to add extra flags to the link -step of a target. :prop_tgt:`LINK_FLAGS_<CONFIG>` will add to the +The LINK_FLAGS property, managed as a string, can be used to add extra flags +to the link step of a target. :prop_tgt:`LINK_FLAGS_<CONFIG>` will add to the configuration ``<CONFIG>``, for example, ``DEBUG``, ``RELEASE``, ``MINSIZEREL``, ``RELWITHDEBINFO``, ... + +.. note:: + + This property has been superseded by :prop_tgt:`LINK_OPTIONS` property. diff --git a/Help/prop_tgt/LINK_FLAGS_CONFIG.rst b/Help/prop_tgt/LINK_FLAGS_CONFIG.rst index ba7adc8..1f2910b 100644 --- a/Help/prop_tgt/LINK_FLAGS_CONFIG.rst +++ b/Help/prop_tgt/LINK_FLAGS_CONFIG.rst @@ -4,3 +4,7 @@ LINK_FLAGS_<CONFIG> Per-configuration linker flags for a target. This is the configuration-specific version of LINK_FLAGS. + +.. note:: + + This property has been superseded by :prop_tgt:`LINK_OPTIONS` property. diff --git a/Help/prop_tgt/LINK_OPTIONS.rst b/Help/prop_tgt/LINK_OPTIONS.rst new file mode 100644 index 0000000..c5263a2 --- /dev/null +++ b/Help/prop_tgt/LINK_OPTIONS.rst @@ -0,0 +1,21 @@ +LINK_OPTIONS +------------ + +List of options to use when linking this target. + +This property holds a :ref:`;-list <CMake Language Lists>` of options +specified so far for its target. Use the :command:`target_link_options` +command to append more options. + +This property is initialized by the :prop_dir:`LINK_OPTIONS` directory +property when a target is created, and is used by the generators to set +the options for the compiler. + +Contents of ``LINK_OPTIONS`` may use "generator expressions" with the +syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual +for available expressions. See the :manual:`cmake-buildsystem(7)` manual +for more on defining buildsystem properties. + +.. note:: + + This property must be used in preference to :prop_tgt:`LINK_FLAGS` property. diff --git a/Help/prop_tgt/VS_DEBUGGER_COMMAND.rst b/Help/prop_tgt/VS_DEBUGGER_COMMAND.rst index f898750..ba5fd0a 100644 --- a/Help/prop_tgt/VS_DEBUGGER_COMMAND.rst +++ b/Help/prop_tgt/VS_DEBUGGER_COMMAND.rst @@ -2,6 +2,8 @@ VS_DEBUGGER_COMMAND ------------------- Sets the local debugger command for Visual Studio C++ targets. +The property value may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. This is defined in ``<LocalDebuggerCommand>`` in the Visual Studio project file. diff --git a/Help/prop_tgt/VS_DEBUGGER_COMMAND_ARGUMENTS.rst b/Help/prop_tgt/VS_DEBUGGER_COMMAND_ARGUMENTS.rst new file mode 100644 index 0000000..06ef5d5 --- /dev/null +++ b/Help/prop_tgt/VS_DEBUGGER_COMMAND_ARGUMENTS.rst @@ -0,0 +1,11 @@ +VS_DEBUGGER_COMMAND_ARGUMENTS +----------------------------- + +Sets the local debugger command line arguments for Visual Studio C++ targets. +The property value may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. +This is defined in ``<LocalDebuggerCommandArguments>`` in the Visual Studio +project file. + +This property only works for Visual Studio 2010 and above; +it is ignored on other generators. diff --git a/Help/prop_tgt/VS_DEBUGGER_ENVIRONMENT.rst b/Help/prop_tgt/VS_DEBUGGER_ENVIRONMENT.rst new file mode 100644 index 0000000..f55ac7b --- /dev/null +++ b/Help/prop_tgt/VS_DEBUGGER_ENVIRONMENT.rst @@ -0,0 +1,11 @@ +VS_DEBUGGER_ENVIRONMENT +----------------------- + +Sets the local debugger environment for Visual Studio C++ targets. +The property value may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. +This is defined in ``<LocalDebuggerEnvironment>`` in the Visual Studio +project file. + +This property only works for Visual Studio 2010 and above; +it is ignored on other generators. diff --git a/Help/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY.rst b/Help/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY.rst index fb0389e..008bbf6 100644 --- a/Help/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY.rst +++ b/Help/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY.rst @@ -2,6 +2,8 @@ VS_DEBUGGER_WORKING_DIRECTORY ----------------------------- Sets the local debugger working directory for Visual Studio C++ targets. +The property value may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. This is defined in ``<LocalDebuggerWorkingDirectory>`` in the Visual Studio project file. diff --git a/Help/release/3.1.rst b/Help/release/3.1.rst index dca42cd..8278353 100644 --- a/Help/release/3.1.rst +++ b/Help/release/3.1.rst @@ -289,12 +289,12 @@ CPack ----- * :manual:`cpack(1)` gained an ``IFW`` generator to package using - Qt Framework Installer tools. See the :module:`CPackIFW` module. + Qt Framework Installer tools. See the :cpack_gen:`CPack IFW Generator`. * :manual:`cpack(1)` gained ``7Z`` and ``TXZ`` generators supporting lzma-compressed archives. -* The :module:`CPackDeb` module learned a new +* The :cpack_gen:`CPack Deb Generator` learned a new :variable:`CPACK_DEBIAN_COMPRESSION_TYPE` variable to set the tarball compression type. diff --git a/Help/release/3.10.rst b/Help/release/3.10.rst index 1205b17..66a1d09 100644 --- a/Help/release/3.10.rst +++ b/Help/release/3.10.rst @@ -184,37 +184,35 @@ CTest CPack ----- -* CPack gained a ``FREEBSD`` generator for FreeBSD ``pkg(8)``, configured - by the :module:`CPackFreeBSD` module. +* A :cpack_gen:`CPack FreeBSD Generator` was added for FreeBSD ``pkg(8)``. -* The CPack ``DEB`` generator, configured by the :module:`CPackDeb` module, - was enabled on Windows. While not fully featured (due to the lack of - external UNIX tools) this will allow building basic cross-platform Debian - packages. +* The :cpack_gen:`CPack Deb Generator` was enabled on Windows. While not + fully featured (due to the lack of external UNIX tools) this will allow + building basic cross-platform Debian packages. -* The :module:`CPackDeb` module learned to set package release version in - ``Version`` info property. +* The :cpack_gen:`CPack Deb Generator` learned to set package release + version in ``Version`` info property. See the :variable:`CPACK_DEBIAN_PACKAGE_RELEASE` variable. -* The :module:`CPackDeb` module learned more strict package version checking - that complies with Debian rules. +* The :cpack_gen:`CPack Deb Generator` learned more strict package + version checking that complies with Debian rules. * The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and :command:`cpack_ifw_configure_component_group` commands gained a new ``REPLACES`` and ``CHECKABLE`` options. -* The :module:`CPackIFW` module gained new +* The :cpack_gen:`CPack IFW Generator` gained new :variable:`CPACK_IFW_PACKAGE_FILE_EXTENSION` variable to customize target binary format. -* The :module:`CPackIFW` module gained new +* The :cpack_gen:`CPack IFW Generator` gained new :variable:`CPACK_IFW_REPOSITORIES_DIRECTORIES` variable to specify additional repositories dirs that will be used to resolve and repack dependent components. This feature is only available when using QtIFW 3.1 or later. -* Modules :module:`CPackRPM` and :module:`CPackDeb` learned to set package epoch - version. +* The :cpack_gen:`CPack RPM Generator` and :cpack_gen:`CPack Deb Generator` + learned to set the package epoch version. See :variable:`CPACK_RPM_PACKAGE_EPOCH` and :variable:`CPACK_DEBIAN_PACKAGE_EPOCH` variables. diff --git a/Help/release/3.11.rst b/Help/release/3.11.rst index 214da0d..a80657d 100644 --- a/Help/release/3.11.rst +++ b/Help/release/3.11.rst @@ -200,11 +200,11 @@ CPack * :manual:`cpack(1)` gained ``--trace`` and ``--trace-expand`` options. -* The :module:`CPackIFW` module gained new +* The :cpack_gen:`CPack IFW Generator` gained new :variable:`CPACK_IFW_PACKAGE_REMOVE_TARGET_DIR` variable to control if the target directory should not be deleted when uninstalling. -* The :module:`CPackRPM` module learned to enable enforcing of execute +* The :cpack_gen:`CPack RPM Generator` learned to enable enforcing of execute privileges on programs and shared libraries. See :variable:`CPACK_RPM_INSTALL_WITH_EXEC` variable. diff --git a/Help/release/3.12.rst b/Help/release/3.12.rst index f6fdb5a..481027e 100644 --- a/Help/release/3.12.rst +++ b/Help/release/3.12.rst @@ -46,8 +46,9 @@ Commands were added to expose ``TOUCH`` functionality without having to use CMake's command-line tool mode with :command:`execute_process`. -* The :command:`find_package` command now searches a prefix specified by - a ``PackageName_ROOT`` CMake or environment variable. Package roots are +* The :command:`find_package` command now searches prefixes specified by + the :variable:`<PackageName>_ROOT` CMake variable and the + :envvar:`<PackageName>_ROOT` environment variable. Package roots are maintained as a stack so nested calls to all ``find_*`` commands inside find modules also search the roots as prefixes. See policy :policy:`CMP0074`. @@ -238,8 +239,8 @@ CPack :variable:`CMAKE_PROJECT_VERSION_PATCH` to initialize corresponding CPack variables. -* :manual:`cpack(1)` gained basic support for `NuGet`_. - See the :module:`CPackNuGet` module. +* A :cpack_gen:`CPack NuGet Generator` was was added with basic + support for `NuGet`_. .. _NuGet: https://docs.microsoft.com/en-us/nuget/what-is-nuget diff --git a/Help/release/3.2.rst b/Help/release/3.2.rst index 8abb1ca..992d44b 100644 --- a/Help/release/3.2.rst +++ b/Help/release/3.2.rst @@ -156,27 +156,27 @@ CTest CPack ----- -* The :module:`CPackRPM` module learned options to set per-component +* The :cpack_gen:`CPack RPM Generator` learned options to set per-component descriptions and summaries. See the :variable:`CPACK_RPM_<component>_PACKAGE_DESCRIPTION` and :variable:`CPACK_RPM_<component>_PACKAGE_SUMMARY` variables. -* The :module:`CPackRPM` module learned options to specify +* The :cpack_gen:`CPack RPM Generator` learned options to specify requirements for pre- and post-install scripts. See the :variable:`CPACK_RPM_PACKAGE_REQUIRES_PRE` and :variable:`CPACK_RPM_PACKAGE_REQUIRES_POST` variables. -* The :module:`CPackRPM` module learned options to specify +* The :cpack_gen:`CPack RPM Generator` learned options to specify requirements for pre- and post-uninstall scripts. See the :variable:`CPACK_RPM_PACKAGE_REQUIRES_PREUN` and :variable:`CPACK_RPM_PACKAGE_REQUIRES_POSTUN` variables. -* The :module:`CPackRPM` module learned a new +* The :cpack_gen:`CPack RPM Generator` learned a new :variable:`CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX` variable to specify a component-specific value to use instead of :variable:`CPACK_PACKAGING_INSTALL_PREFIX`. -* The :module:`CPackRPM` module learned a new +* The :cpack_gen:`CPack RPM Generator` learned a new :variable:`CPACK_RPM_RELOCATION_PATHS` variable to specify multiple relocation prefixes for a single rpm package. diff --git a/Help/release/3.3.rst b/Help/release/3.3.rst index 0beb354..11f0c60 100644 --- a/Help/release/3.3.rst +++ b/Help/release/3.3.rst @@ -169,26 +169,26 @@ CTest CPack ----- -* The :manual:`cpack(1)` ``IFW`` generator and the :module:`CPackIFW` - module learned to support Qt Framework Installer 2.0 tools. +* The :cpack_gen:`CPack IFW Generator` learned to support + Qt Framework Installer 2.0 tools. -* The :module:`CPackDeb` module learned a new +* The :cpack_gen:`CPack Deb Generator` learned a new :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS` variable to specify per-component use of ``dpkg-shlibdeps``. -* The :module:`CPackDeb` module learned a new +* The :cpack_gen:`CPack Deb Generator` learned a new :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS` option to specify per-component dependencies. -* The :module:`CPackRPM` module learned to package symbolic links +* The :cpack_gen:`CPack RPM Generator` learned to package symbolic links more cleanly and now supports directory symlinks with recent ``rpmbuild`` versions. -* The :module:`CPackRPM` module learned a new +* The :cpack_gen:`CPack RPM Generator` learned a new :variable:`CPACK_RPM_ADDITIONAL_MAN_DIRS` variable to specify directories containing man pages for the brp-compress RPM macro. -* The :module:`CPackRPM` module learned a new +* The :cpack_gen:`CPack RPM Generator` learned a new :variable:`CPACK_RPM_<component>_PACKAGE_ARCHITECTURE` variable to specify a component-specific package architecture. diff --git a/Help/release/3.4.rst b/Help/release/3.4.rst index 468627e..0a0e6df 100644 --- a/Help/release/3.4.rst +++ b/Help/release/3.4.rst @@ -197,7 +197,7 @@ CTest CPack ----- -* The :module:`CPackDeb` module learned to set package dependencies +* The :cpack_gen:`CPack Deb Generator` learned to set package dependencies per component. See variables: * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS` @@ -249,11 +249,11 @@ Other Changes :module:`CheckSymbolExists`, and :module:`FindThreads` modules learned to work in environments where only CXX is enabled. -* The :module:`CPackDeb` module now correctly excludes symlinks during package - checksum calculation. +* The :cpack_gen:`CPack Deb Generator` now correctly excludes symlinks + during package checksum calculation. -* The :module:`CPackDeb` no longer uses fakeroot and system tar program for - packaging. +* The :cpack_gen:`CPack Deb Generator` no longer uses fakeroot and + system tar program for packaging. * The :module:`CPack` module no longer mangles settings with CMake-special characters when they're used as defaults for other settings. The macro diff --git a/Help/release/3.5.rst b/Help/release/3.5.rst index 009eb3c..f988908 100644 --- a/Help/release/3.5.rst +++ b/Help/release/3.5.rst @@ -120,31 +120,33 @@ Platforms CPack ----- -* The :module:`CPackDMG` module learned new variable to specify AppleScript - file run to customize appearance of ``DragNDrop`` installer folder, - including background image setting using supplied PNG or multi-resolution - TIFF file. See the :variable:`CPACK_DMG_DS_STORE_SETUP_SCRIPT` and +* The :cpack_gen:`CPack DMG Generator` learned new variable to + specify AppleScript file run to customize appearance of ``DragNDrop`` + installer folder, including background image setting using supplied + PNG or multi-resolution TIFF file. + See the :variable:`CPACK_DMG_DS_STORE_SETUP_SCRIPT` and :variable:`CPACK_DMG_BACKGROUND_IMAGE` variables. -* The :module:`CPackDeb` module learned to set the optional config +* The :cpack_gen:`CPack Deb Generator` learned to set the optional config file ``Source`` field using a monolithic or per-component variable. See :variable:`CPACK_DEBIAN_PACKAGE_SOURCE`. -* The :module:`CPackDeb` module learned to set Package, Section +* The :cpack_gen:`CPack Deb Generator` learned to set Package, Section and Priority control fields per-component. See variables :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_SECTION` and :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY`. -* The :module:`CPack DragNDrop generator <CPackDMG>` learned to add +* The :cpack_gen:`CPack DMG Generator` learned to add multi-lingual SLAs to a DMG which is presented to the user when they try to mount the DMG. See the :variable:`CPACK_DMG_SLA_LANGUAGES` and :variable:`CPACK_DMG_SLA_DIR` variables for details. -* The :module:`CPackNSIS` module learned new variables to add bitmaps to the - installer. See the :variable:`CPACK_NSIS_MUI_WELCOMEFINISHPAGE_BITMAP` +* The :cpack_gen:`CPack NSIS Generator` learned new variables to + add bitmaps to the installer. + See the :variable:`CPACK_NSIS_MUI_WELCOMEFINISHPAGE_BITMAP` and :variable:`CPACK_NSIS_MUI_UNWELCOMEFINISHPAGE_BITMAP` variables. -* The :module:`CPackRPM` module learned to set Name and Group +* The :cpack_gen:`CPack RPM Generator` learned to set Name and Group control fields per-component. See :variable:`CPACK_RPM_<component>_PACKAGE_NAME` and :variable:`CPACK_RPM_<component>_PACKAGE_GROUP`. diff --git a/Help/release/3.6.rst b/Help/release/3.6.rst index a542b77..c796d70 100644 --- a/Help/release/3.6.rst +++ b/Help/release/3.6.rst @@ -165,25 +165,25 @@ CTest CPack ----- -* The :module:`CPackDeb` module learned how to handle ``$ORIGIN`` +* The :cpack_gen:`CPack Deb Generator` learned how to handle ``$ORIGIN`` in ``CMAKE_INSTALL_RPATH`` when :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS` is used for dependency auto detection. -* The :module:`CPackDeb` module learned how to generate ``DEBIAN/shlibs`` - contorl file when package contains shared libraries. +* The :cpack_gen:`CPack Deb Generator` learned how to generate + ``DEBIAN/shlibs`` contorl file when package contains shared libraries. -* The :module:`CPackDeb` module learned how to generate ``DEBIAN/postinst`` and - ``DEBIAN/postrm`` files if the package installs libraries in - ldconfig-controlled locations (e.g. ``/lib/``, ``/usr/lib/``). +* The :cpack_gen:`CPack Deb Generator` learned how to generate + ``DEBIAN/postinst`` and ``DEBIAN/postrm`` files if the package installs + libraries in ldconfig-controlled locations (e.g. ``/lib/``, ``/usr/lib/``). -* The :module:`CPackDeb` module learned how to generate dependencies between - Debian packages if multi-component setup is used and +* The :cpack_gen:`CPack Deb Generator` learned how to generate dependencies + between Debian packages if multi-component setup is used and :variable:`CPACK_COMPONENT_<compName>_DEPENDS` variables are set. For backward compatibility this feature is disabled by default. See :variable:`CPACK_DEBIAN_ENABLE_COMPONENT_DEPENDS`. -* The :module:`CPackDeb` module learned how to set custom package file names - including how to generate properly-named Debian packages:: +* The :cpack_gen:`CPack Deb Generator` learned how to set custom package + file names including how to generate properly-named Debian packages:: <PackageName>_<VersionNumber>-<DebianRevisionNumber>_<DebianArchitecture>.deb @@ -191,42 +191,44 @@ CPack :variable:`CPACK_DEBIAN_FILE_NAME` and :variable:`CPACK_DEBIAN_<COMPONENT>_FILE_NAME`. -* The :module:`CPackDeb` module learned how to set the package release number - (``DebianRevisionNumber`` in package file name when used in combination with - ``DEB-DEFAULT`` value set by :variable:`CPACK_DEBIAN_FILE_NAME`). See - :variable:`CPACK_DEBIAN_PACKAGE_RELEASE`. +* The :cpack_gen:`CPack Deb Generator` learned how to set the package + release number (``DebianRevisionNumber`` in package file name when + used in combination with ``DEB-DEFAULT`` value set by + :variable:`CPACK_DEBIAN_FILE_NAME`). + See :variable:`CPACK_DEBIAN_PACKAGE_RELEASE`. -* The :module:`CPackDeb` module learned how to set the package architecture - per-component. See :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_ARCHITECTURE`. +* The :cpack_gen:`CPack Deb Generator` learned how to set the package + architecture per-component. + See :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_ARCHITECTURE`. -* The :module:`CPackDMG` module learned a new option to tell the CPack - ``DragNDrop`` generaor to skip the ``/Applications`` symlink. +* The :cpack_gen:`CPack DMG Generator` learned a new option to skip the + ``/Applications`` symlink. See the :variable:`CPACK_DMG_DISABLE_APPLICATIONS_SYMLINK` variable. * The :module:`CPackIFW` module gained a new :command:`cpack_ifw_update_repository` command to update a QtIFW-specific repository from a remote repository. -* The :module:`CPackRPM` module learned how to set RPM ``dist`` tag as part of - RPM ``Release:`` tag when enabled (mandatory on some Linux distributions for - e.g. on Fedora). +* The :cpack_gen:`CPack RPM Generator` learned how to set RPM ``dist`` tag + as part of RPM ``Release:`` tag when enabled (mandatory on some Linux + distributions for e.g. on Fedora). See :variable:`CPACK_RPM_PACKAGE_RELEASE_DIST`. -* The :module:`CPackRPM` module learned how to set default values for owning - user/group and file/directory permissions of package content. +* The :cpack_gen:`CPack RPM Generator` learned how to set default values + for owning user/group and file/directory permissions of package content. See :variable:`CPACK_RPM_DEFAULT_USER`, :variable:`CPACK_RPM_DEFAULT_GROUP`, :variable:`CPACK_RPM_DEFAULT_FILE_PERMISSIONS`, :variable:`CPACK_RPM_DEFAULT_DIR_PERMISSIONS` and their per component counterparts. -* The :module:`CPackRPM` module learned how to set user defined package file - names, how to specify that rpmbuild should decide on file name format as - well as handling of multiple rpm packages generated by a single user defined - spec file. +* The :cpack_gen:`CPack RPM Generator` learned how to set user defined + package file names, how to specify that rpmbuild should decide on file + name format as well as handling of multiple rpm packages generated by a + single user defined spec file. See :variable:`CPACK_RPM_PACKAGE_NAME` and :variable:`CPACK_RPM_<component>_PACKAGE_NAME`. -* The :module:`CPackRPM` module learned how to correctly handle symlinks +* The :cpack_gen:`CPack RPM Generator` learned how to correctly handle symlinks that are pointing outside generated packages. Other @@ -296,7 +298,7 @@ Other Changes Input variables of the old case will be honored if provided, and output variables of the old case are always provided. -* The :module:`CPackRPM` module now supports upper cased component +* The :cpack_gen:`CPack RPM Generator` now supports upper cased component names in per component CPackRPM specific variables. E.g. component named ``foo`` now expects component specific variable to be ``CPACK_RPM_FOO_PACKAGE_NAME`` while before diff --git a/Help/release/3.7.rst b/Help/release/3.7.rst index d4d374b..fae10f5 100644 --- a/Help/release/3.7.rst +++ b/Help/release/3.7.rst @@ -221,13 +221,12 @@ CTest CPack ----- -* CPack gained a ``productbuild`` generator on OS X, configured by - the :module:`CPackProductBuild` module. +* CPack gained a :cpack_gen:`CPack productbuild Generator` on OS X. * CPack gained a new :variable:`CPACK_PACKAGE_CHECKSUM` variable to enable generation of a checksum file for each package file. -* The :module:`CPackDeb` module learned to support long file names +* The :cpack_gen:`CPack Deb Generator` learned to support long file names when archive format is set to GNU tar. See :variable:`CPACK_DEBIAN_ARCHIVE_TYPE` @@ -240,32 +239,32 @@ CPack ``USER_INTERFACES`` option to add a list of additional pages to the IFW installer. -* The :module:`CPackRPM` module learned to generate debuginfo +* The :cpack_gen:`CPack RPM Generator` learned to generate debuginfo packages on demand. See :variable:`CPACK_RPM_DEBUGINFO_PACKAGE` and its per component version. -* The :module:`CPackRPM` module learned to generate source rpm +* The :cpack_gen:`CPack RPM Generator` learned to generate source rpm (SRPM) packages on demand. See :variable:`CPACK_RPM_PACKAGE_SOURCES`, :variable:`CPACK_RPM_SOURCE_PKG_BUILD_PARAMS` and :variable:`CPACK_RPM_SOURCE_PKG_PACKAGING_INSTALL_PREFIX`. -* The CPack NSIS generator now supports +* The :cpack_gen:`CPack NSIS Generator` now supports :variable:`CPACK_NSIS_<compName>_INSTALL_DIRECTORY`. This can be used to set component specific installation directories. -* The CPack WIX generator now supports +* The :cpack_gen:`CPack WiX Generator` now supports :variable:`CPACK_WIX_SKIP_PROGRAM_FOLDER` to allow specification of a custom absolute installation prefix outside of the ProgramFiles folders. -* The CPack WIX generator now supports +* The :cpack_gen:`CPack WiX Generator` now supports :variable:`CPACK_COMPONENT_<compName>_DISABLED`. This can be used to deselect a component from being installed by default. -* The CPack WIX generator now supports :variable:`CPACK_WIX_PATCH_FILE` - fragments for Feature elements. +* The :cpack_gen:`CPack WiX Generator` now supports + :variable:`CPACK_WIX_PATCH_FILE` fragments for Feature elements. -* The CPack WIX generator now supports +* The :cpack_gen:`CPack WiX Generator` now supports :variable:`CPACK_WIX_ROOT_FEATURE_TITLE` and :variable:`CPACK_WIX_ROOT_FEATURE_DESCRIPTION` to allow the specification of a custom title and description for the root feature element. diff --git a/Help/release/3.8.rst b/Help/release/3.8.rst index efb2aa5..de51a7b 100644 --- a/Help/release/3.8.rst +++ b/Help/release/3.8.rst @@ -307,7 +307,7 @@ CPack option now is deprecated and will be removed in a future version of CMake. Please use new ``SORTING_PRIORITY`` option instead. -* The :module:`CPackIFW` module gained new +* The :cpack_gen:`CPack IFW Generator` gained new :variable:`CPACK_IFW_PACKAGE_WATERMARK`, :variable:`CPACK_IFW_PACKAGE_BANNER`, :variable:`CPACK_IFW_PACKAGE_BACKGROUND`, @@ -317,26 +317,26 @@ CPack :variable:`CPACK_IFW_PACKAGE_TITLE_COLOR` variables to customize a QtIFW installer look. -* The :module:`CPackProductBuild` module gained options to sign packages. +* The :cpack_gen:`CPack productbuild Generator` gained options to sign packages. See the variables :variable:`CPACK_PRODUCTBUILD_IDENTITY_NAME`, :variable:`CPACK_PRODUCTBUILD_KEYCHAIN_PATH`, :variable:`CPACK_PKGBUILD_IDENTITY_NAME`, and :variable:`CPACK_PKGBUILD_KEYCHAIN_PATH`. -* The :module:`CPackRPM` module learned to omit tags that are not supported by - provided ``rpmbuild`` tool. If unsupported tags are set they are ignored - and a developer warning is printed out. +* The :cpack_gen:`CPack RPM Generator` learned to omit tags that are not + supported by provided ``rpmbuild`` tool. If unsupported tags are set they + are ignored and a developer warning is printed out. -* The :module:`CPackRPM` module learned to generate main component package - which forces generation of a rpm for defined component without component - suffix in filename and package name. +* The :cpack_gen:`CPack RPM Generator` learned to generate main component + package which forces generation of a rpm for defined component without + component suffix in filename and package name. See :variable:`CPACK_RPM_MAIN_COMPONENT` variable. -* The :module:`CPackRPM` module learned to generate a single ``debuginfo`` - package on demand even if components packaging is used. +* The :cpack_gen:`CPack RPM Generator` learned to generate a single + ``debuginfo`` package on demand even if components packaging is used. See :variable:`CPACK_RPM_DEBUGINFO_SINGLE_PACKAGE` variable. -* The :module:`CPackRPM` module learned to support +* The :cpack_gen:`CPack RPM Generator` learned to support multiple directives per file when using :variable:`CPACK_RPM_USER_FILELIST` variable. diff --git a/Help/release/3.9.rst b/Help/release/3.9.rst index 897e268..5001e90 100644 --- a/Help/release/3.9.rst +++ b/Help/release/3.9.rst @@ -206,7 +206,7 @@ CTest CPack ----- -* The :module:`CPackArchive` module learned to modify the filename +* The :cpack_gen:`CPack Archive Generator` learned to modify the filename per-component. See the :variable:`CPACK_ARCHIVE_FILE_NAME` variable and its per-component version :variable:`CPACK_ARCHIVE_<component>_FILE_NAME`. @@ -220,23 +220,24 @@ CPack internationalization support for ``DISPLAY_NAME`` and ``DESCRIPTION`` options. -* The :module:`CPackIFW` module learned the new hint :variable:`CPACK_IFW_ROOT` - variable for finding the QtIFW tool suite installed in a non-standard place. +* The :cpack_gen:`CPack IFW Generator` learned the new hint + :variable:`CPACK_IFW_ROOT` variable for finding the QtIFW tool suite + installed in a non-standard place. -* The :module:`CPackProductBuild` module gained a new +* The :cpack_gen:`CPack productbuild Generator` gained a new :variable:`CPACK_PRODUCTBUILD_RESOURCES_DIR` variable to specify resources to be copied into the ``Resources`` directory. -* The :module:`CPackRPM` module learned to modify the ``debuginfo`` package - name. See the :variable:`CPACK_RPM_DEBUGINFO_FILE_NAME` variable. +* The :cpack_gen:`CPack RPM Generator` learned to modify the ``debuginfo`` + package name. See the :variable:`CPACK_RPM_DEBUGINFO_FILE_NAME` variable. -* The :module:`CPackWIX` module patching system now has the ability to set - additional attributes. This can be done by specifying attributes with - the ``CPackWiXFragment`` XML tag after the ``Id`` attribute. +* The :cpack_gen:`CPack WiX Generator` patching system now has the + ability to set additional attributes. This can be done by specifying + attributes with the ``CPackWiXFragment`` XML tag after the ``Id`` attribute. See the :variable:`CPACK_WIX_PATCH_FILE` variable. -* The CPack WIX generator implemented a new +* The :cpack_gen:`CPack WiX Generator` implemented a new :variable:`CPACK_WIX_ROOT_FOLDER_ID` variable which allows using a custom root folder ID instead of the default ``ProgramFilesFolder`` / ``ProgramFiles64Folder``. 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/CMAKE_AUTOGEN_VERBOSE.rst b/Help/release/dev/CMAKE_AUTOGEN_VERBOSE.rst new file mode 100644 index 0000000..da559cc --- /dev/null +++ b/Help/release/dev/CMAKE_AUTOGEN_VERBOSE.rst @@ -0,0 +1,6 @@ +CMAKE_AUTOGEN_VERBOSE +--------------------- + +* The new variable :variable:`CMAKE_AUTOGEN_VERBOSE` allows + to increase the verbosity of :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC` and + :prop_tgt:`AUTORCC` from within CMakeLists.txt. diff --git a/Help/release/dev/FindCURL-per-config.rst b/Help/release/dev/FindCURL-per-config.rst new file mode 100644 index 0000000..5ba1425 --- /dev/null +++ b/Help/release/dev/FindCURL-per-config.rst @@ -0,0 +1,5 @@ +FindCURL-per-config +------------------- + +* The :module:`FindCURL` module learned to find debug and release variants + separately. diff --git a/Help/release/dev/INTERFACE_LINK_DEPENDS-property.rst b/Help/release/dev/INTERFACE_LINK_DEPENDS-property.rst new file mode 100644 index 0000000..9527c97 --- /dev/null +++ b/Help/release/dev/INTERFACE_LINK_DEPENDS-property.rst @@ -0,0 +1,4 @@ +INTERFACE_LINK_DEPENDS-property +------------------------------- + +* Binary targets gained new :prop_tgt:`INTERFACE_LINK_DEPENDS` property. diff --git a/Help/release/dev/LINK_DEPENDS-property.rst b/Help/release/dev/LINK_DEPENDS-property.rst new file mode 100644 index 0000000..83beba8 --- /dev/null +++ b/Help/release/dev/LINK_DEPENDS-property.rst @@ -0,0 +1,5 @@ +LINK_DEPENDS-property +--------------------- + +* The :prop_tgt:`LINK_DEPENDS` target property learned to support + :manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/release/dev/LINK_OPTIONS.rst b/Help/release/dev/LINK_OPTIONS.rst new file mode 100644 index 0000000..e40dab2 --- /dev/null +++ b/Help/release/dev/LINK_OPTIONS.rst @@ -0,0 +1,11 @@ +LINK_OPTIONS +------------ + +* CMake gained new capabilities to manage link step: + + * :prop_dir:`LINK_OPTIONS` directory property. + * :prop_tgt:`LINK_OPTIONS` and :prop_tgt:`INTERFACE_LINK_OPTIONS` target + properties. + * :command:`add_link_options` command to add link options in the current + directory. + * :command:`target_link_options` command to add link options to targets. diff --git a/Help/release/dev/UseSWIG-USE_TARGET_INCLUDE_DIRECTORIES.rst b/Help/release/dev/UseSWIG-USE_TARGET_INCLUDE_DIRECTORIES.rst new file mode 100644 index 0000000..2a2721f --- /dev/null +++ b/Help/release/dev/UseSWIG-USE_TARGET_INCLUDE_DIRECTORIES.rst @@ -0,0 +1,5 @@ +UseSWIG-USE_TARGET_INCLUDE_DIRECTORIES +-------------------------------------- + +* Module ``UseSWIG`` gains capability to manage target property + :prop_tgt:`INCLUDE_DIRECTORIES` for ``SWIG`` compilation. diff --git a/Help/release/dev/UseSWIG-target-name-policy.rst b/Help/release/dev/UseSWIG-target-name-policy.rst new file mode 100644 index 0000000..bb9011d --- /dev/null +++ b/Help/release/dev/UseSWIG-target-name-policy.rst @@ -0,0 +1,5 @@ +UseSWIG-target-name-policy +-------------------------- + +* The :module:`UseSWIG` module has changed strategy for target naming. + See policy :policy:`CMP0078`. diff --git a/Help/release/dev/cpack-deb-source-date-epoch.rst b/Help/release/dev/cpack-deb-source-date-epoch.rst new file mode 100644 index 0000000..b276569 --- /dev/null +++ b/Help/release/dev/cpack-deb-source-date-epoch.rst @@ -0,0 +1,6 @@ +cpack-deb-source-date-epoch +--------------------------- + +* The :cpack_gen:`CPack Deb Generator` learned to honor the ``SOURCE_DATE_EPOCH`` + environment variable when packaging files. This is useful for generating + reproducible packages. diff --git a/Help/release/dev/cpack-external.rst b/Help/release/dev/cpack-external.rst new file mode 100644 index 0000000..fb9a061 --- /dev/null +++ b/Help/release/dev/cpack-external.rst @@ -0,0 +1,8 @@ +cpack-external +-------------- + +* CPack gained a new :cpack_gen:`CPack External Generator` which is used to + export the CPack metadata in a format that other software can understand. The + intention of this generator is to allow external packaging software to take + advantage of CPack's features when it may not be possible to use CPack for + the entire packaging process. diff --git a/Help/release/dev/cpack-generator-documentation.rst b/Help/release/dev/cpack-generator-documentation.rst new file mode 100644 index 0000000..c3c5193 --- /dev/null +++ b/Help/release/dev/cpack-generator-documentation.rst @@ -0,0 +1,9 @@ +cpack-generator-documentation +----------------------------- + +* The CPack generators have been moved into their own separate section in the + documentation, rather than having the documentation in their internal + implementation modules. +* These internal implementation modules are also no longer available to scripts + that may have been incorrectly including them, because they should never have + been available in the first place. diff --git a/Help/release/dev/ghs.rst b/Help/release/dev/ghs.rst new file mode 100644 index 0000000..d3bec95 --- /dev/null +++ b/Help/release/dev/ghs.rst @@ -0,0 +1,20 @@ +ghs +--- + +* The :generator:`Green Hills MULTI` generator is updated: + + - Added support for architecture selection through + :variable:`CMAKE_GENERATOR_PLATFORM`: + e.g. ``arm``, ``ppc``, and ``86``. + + - Added support for toolset selection through + :variable:`CMAKE_GENERATOR_TOOLSET`, + e.g. ``comp_201205``, ``comp_201510``, ``comp_201722_beta``. + + - Added support for platform selection through ``GHS_TARGET_PLATFORM``, + e.g. ``integrity``, ``linux``, ``standalone``, etc. + + - No longer checks that ``arm`` based compilers are installed but ensures + that the correct ``gbuild.exe`` exists. + + - No longer hard-codes ARM files, BSP, toolset, or OS locations. diff --git a/Help/release/dev/install-code-script-genex.rst b/Help/release/dev/install-code-script-genex.rst new file mode 100644 index 0000000..6532e7b --- /dev/null +++ b/Help/release/dev/install-code-script-genex.rst @@ -0,0 +1,5 @@ +install-code-script-genex +------------------------- + +* The :command:`install(CODE)` and :command:`install(SCRIPT)` commands + learned to support generator expressions. diff --git a/Help/release/dev/list_sort.rst b/Help/release/dev/list_sort.rst new file mode 100644 index 0000000..8971b78 --- /dev/null +++ b/Help/release/dev/list_sort.rst @@ -0,0 +1,5 @@ +list_sort +--------- + +* The :command:`list(SORT)` command gained options to control the + comparison operation used to order the entries. diff --git a/Help/release/dev/math-hex.rst b/Help/release/dev/math-hex.rst new file mode 100644 index 0000000..16e21ec --- /dev/null +++ b/Help/release/dev/math-hex.rst @@ -0,0 +1,4 @@ +math-hex +-------- + +* The :command:`math` command gained options for hexadecimal. diff --git a/Help/release/dev/option-normal-variable.rst b/Help/release/dev/option-normal-variable.rst new file mode 100644 index 0000000..19b9a64 --- /dev/null +++ b/Help/release/dev/option-normal-variable.rst @@ -0,0 +1,5 @@ +option-normal-variable +---------------------- + +* The :command:`option` command now honors existing normal variables instead + of replacing them with a cache entry. See policy :policy:`CMP0077`. diff --git a/Help/release/dev/pkgc-global.rst b/Help/release/dev/pkgc-global.rst new file mode 100644 index 0000000..0c07d9e --- /dev/null +++ b/Help/release/dev/pkgc-global.rst @@ -0,0 +1,5 @@ +pkgc-global +----------- + +* Module ``FindPkgConfig`` gains capability to create imported targets in + global scope. diff --git a/Help/release/dev/subdirectory-installing.rst b/Help/release/dev/subdirectory-installing.rst new file mode 100644 index 0000000..04e4676 --- /dev/null +++ b/Help/release/dev/subdirectory-installing.rst @@ -0,0 +1,5 @@ +subdirectory-installing +----------------------- + +* The :command:`install(TARGETS)` command may now be used + to install targets created outside the current directory. diff --git a/Help/release/dev/subdirectory-sources.rst b/Help/release/dev/subdirectory-sources.rst new file mode 100644 index 0000000..880b321 --- /dev/null +++ b/Help/release/dev/subdirectory-sources.rst @@ -0,0 +1,8 @@ +subdirectory-sources +-------------------- + +* The :command:`target_sources` command now interprets relative source file + paths as relative to the current source directory. This simplifies + incrementally building up a target's sources from subdirectories. The + :policy:`CMP0076` policy was added to provide backward compatibility with + the old behavior where required. diff --git a/Help/release/dev/vs-debugger-improvements.rst b/Help/release/dev/vs-debugger-improvements.rst new file mode 100644 index 0000000..f1944bb --- /dev/null +++ b/Help/release/dev/vs-debugger-improvements.rst @@ -0,0 +1,14 @@ +vs-debugger-improvements +------------------------ + +* A :prop_tgt:`VS_DEBUGGER_COMMAND_ARGUMENTS` target property was created to + set the debugging command line arguments with + :ref:`Visual Studio Generators` for VS 2010 and above. +* A :prop_tgt:`VS_DEBUGGER_ENVIRONMENT` target property was created to + set the debugging environment with + :ref:`Visual Studio Generators` for VS 2010 and above. +* :prop_tgt:`VS_DEBUGGER_COMMAND` + :prop_tgt:`VS_DEBUGGER_COMMAND_ARGUMENTS` + :prop_tgt:`VS_DEBUGGER_ENVIRONMENT` + :prop_tgt:`VS_DEBUGGER_WORKING_DIRECTORY` + target properties can use generator expressions. diff --git a/Help/release/dev/vs-deployment-files.rst b/Help/release/dev/vs-deployment-files.rst new file mode 100644 index 0000000..1590ed9 --- /dev/null +++ b/Help/release/dev/vs-deployment-files.rst @@ -0,0 +1,7 @@ +vs-deployment-files +------------------- + +* The :prop_tgt:`DEPLOYMENT_ADDITIONAL_FILES` target property was + added to tell the :generator:`Visual Studio 9 2008` generator + to specify additional files for deployment to WinCE devices + for remote debugging. diff --git a/Help/release/index.rst b/Help/release/index.rst index 4b32eab..4c9e96a 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_AUTOGEN_VERBOSE.rst b/Help/variable/CMAKE_AUTOGEN_VERBOSE.rst new file mode 100644 index 0000000..bad9cf2 --- /dev/null +++ b/Help/variable/CMAKE_AUTOGEN_VERBOSE.rst @@ -0,0 +1,13 @@ +CMAKE_AUTOGEN_VERBOSE +--------------------- + +Sets the verbosity of :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC` and +:prop_tgt:`AUTORCC`. A positive integer value or a true boolean value +lets the ``AUTO*`` generators output additional processing information. + +Setting :variable:`CMAKE_AUTOGEN_VERBOSE` has the same effect +as setting the ``VERBOSE`` environment variable during +generation (e.g. by calling ``make VERBOSE=1``). +The extra verbosity is limited to the ``AUTO*`` generators though. + +By default :variable:`CMAKE_AUTOGEN_VERBOSE` is unset. diff --git a/Help/variable/CMAKE_GENERATOR_PLATFORM.rst b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst index 50412ff..963f0a4 100644 --- a/Help/variable/CMAKE_GENERATOR_PLATFORM.rst +++ b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst @@ -19,6 +19,8 @@ Platform specification is supported only on specific generators: * For :ref:`Visual Studio Generators` with VS 2005 and above this specifies the target architecture. +* For :generator:`Green Hills MULTI` this specifies the target architecture. + See native build system documentation for allowed platform names. Visual Studio Platform Selection diff --git a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst index 3220244..e9bc28b 100644 --- a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst +++ b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst @@ -18,6 +18,7 @@ Toolset specification is supported only on specific generators: * :ref:`Visual Studio Generators` for VS 2010 and above * The :generator:`Xcode` generator for Xcode 3.0 and above +* The :generator:`Green Hills MULTI` generator See native build system documentation for allowed toolset names. diff --git a/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG.rst b/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG.rst new file mode 100644 index 0000000..0e52282 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG.rst @@ -0,0 +1,39 @@ +CMAKE_<LANG>_LINKER_WRAPPER_FLAG +-------------------------------- + +Defines the syntax of compiler driver option to pass options to the linker +tool. It will be used to translate the ``LINKER:`` prefix in the link options +(see :command:`add_link_options` and :command:`target_link_options`). + +This variable holds a :ref:`;-list <CMake Language Lists>` of tokens. +If a space (i.e. " ") is specified as last token, flag and ``LINKER:`` +arguments will be specified as separate arguments to the compiler driver. +The :variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP` variable can be specified +to manage concatenation of arguments. + +For example, for ``Clang`` we have: + +.. code-block:: cmake + + set (CMAKE_C_LINKER_WRAPPER_FLAG "-Xlinker" " ") + +Specifying ``"LINKER:-z defs"`` will be transformed in +``-Xlinker -z -Xlinker defs``. + +For ``GNU GCC``: + +.. code-block:: cmake + + set (CMAKE_C_LINKER_WRAPPER_FLAG "-Wl,") + set (CMAKE_C_LINKER_WRAPPER_FLAG_SEP ",") + +Specifying ``"LINKER:-z defs"`` will be transformed in ``-Wl,-z,defs``. + +And for ``SunPro``: + +.. code-block:: cmake + + set (CMAKE_C_LINKER_WRAPPER_FLAG "-Qoption" "ld" " ") + set (CMAKE_C_LINKER_WRAPPER_FLAG_SEP ",") + +Specifying ``"LINKER:-z defs"`` will be transformed in ``-Qoption ld -z,defs``. diff --git a/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG_SEP.rst b/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG_SEP.rst new file mode 100644 index 0000000..faf1481 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINKER_WRAPPER_FLAG_SEP.rst @@ -0,0 +1,9 @@ +CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP +------------------------------------ + +This variable is used with :variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG` +variable to format ``LINKER:`` prefix in the link options +(see :command:`add_link_options` and :command:`target_link_options`). + +When specified, arguments of the ``LINKER:`` prefix will be concatenated using +this value as separator. diff --git a/Help/variable/CMAKE_MAKE_PROGRAM.rst b/Help/variable/CMAKE_MAKE_PROGRAM.rst index a3b997a..4f5a50f 100644 --- a/Help/variable/CMAKE_MAKE_PROGRAM.rst +++ b/Help/variable/CMAKE_MAKE_PROGRAM.rst @@ -55,9 +55,11 @@ to configure the project: the CMake cache then CMake will use the specified value if possible. -* The :generator:`Green Hills MULTI` generator sets this to ``gbuild``. - If a user or project explicitly adds ``CMAKE_MAKE_PROGRAM`` to - the CMake cache then CMake will use the specified value. +* The :generator:`Green Hills MULTI` generator sets this to the full + path to ``gbuild.exe`` based upon the toolset being used. + + Once the generator has initialized a particular value for this + variable, changing the value has undefined behavior. The ``CMAKE_MAKE_PROGRAM`` variable is set for use by project code. The value is also used by the :manual:`cmake(1)` ``--build`` and diff --git a/Help/variable/CMAKE_SYSTEM_PROCESSOR.rst b/Help/variable/CMAKE_SYSTEM_PROCESSOR.rst index 09280de..8ad89f1 100644 --- a/Help/variable/CMAKE_SYSTEM_PROCESSOR.rst +++ b/Help/variable/CMAKE_SYSTEM_PROCESSOR.rst @@ -6,5 +6,3 @@ The name of the CPU CMake is building for. This variable is the same as :variable:`CMAKE_HOST_SYSTEM_PROCESSOR` if you build for the host system instead of the target system when cross compiling. - -* The :generator:`Green Hills MULTI` generator sets this to ``ARM`` by default. diff --git a/Help/variable/PackageName_ROOT.rst b/Help/variable/PackageName_ROOT.rst new file mode 100644 index 0000000..4f6c25b --- /dev/null +++ b/Help/variable/PackageName_ROOT.rst @@ -0,0 +1,14 @@ +<PackageName>_ROOT +------------------ + +Calls to :command:`find_package(<PackageName>)` will search in prefixes +specified by the ``<PackageName>_ROOT`` CMake variable, where +``<PackageName>`` is the name given to the ``find_package`` call +and ``_ROOT`` is literal. For example, ``find_package(Foo)`` will search +prefixes specified in the ``Foo_ROOT`` CMake variable (if set). +See policy :policy:`CMP0074`. + +This variable may hold a single prefix or a +:ref:`;-list <CMake Language Lists>` of multiple prefixes. + +See also the :envvar:`<PackageName>_ROOT` environment variable. |