diff options
Diffstat (limited to 'Help')
210 files changed, 5529 insertions, 434 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index 38c231a67..73dbd5774 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -137,7 +137,7 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: .. |FIND_ARGS_XXX| replace:: <VAR> NAMES name -On OS X the :variable:`CMAKE_FIND_FRAMEWORK` and +On macOS the :variable:`CMAKE_FIND_FRAMEWORK` and :variable:`CMAKE_FIND_APPBUNDLE` variables determine the order of preference between Apple-style and unix-style package components. diff --git a/Help/command/LINK_OPTIONS_LINKER.txt b/Help/command/LINK_OPTIONS_LINKER.txt new file mode 100644 index 000000000..a72337515 --- /dev/null +++ b/Help/command/LINK_OPTIONS_LINKER.txt @@ -0,0 +1,22 @@ +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``. + +The ``LINKER:`` prefix can be specified as part of a ``SHELL:`` prefix +expression. + +The ``LINKER:`` prefix supports, as alternate syntax, specification of +arguments using ``SHELL:`` prefix and space as separator. Previous example +becomes ``"LINKER:SHELL:-z defs"``. + +.. note:: + + Specifying ``SHELL:`` prefix elsewhere than at the beginning of the + ``LINKER:`` prefix is not supported. diff --git a/Help/command/COMPILE_OPTIONS_SHELL.txt b/Help/command/OPTIONS_SHELL.txt index a1316c871..530c0126f 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 c445608c3..350a1c0bd 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_custom_command.rst b/Help/command/add_custom_command.rst index 5f74c543e..71fe49477 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -182,6 +182,9 @@ The options are: If it is a relative path it will be interpreted relative to the build tree directory corresponding to the current source directory. + Arguments to ``WORKING_DIRECTORY`` may use + :manual:`generator expressions <cmake-generator-expressions(7)>`. + ``DEPFILE`` Specify a ``.d`` depfile for the :generator:`Ninja` generator. A ``.d`` file holds dependencies usually emitted by the custom diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst index bd61c8b96..a6b2f7773 100644 --- a/Help/command/add_custom_target.rst +++ b/Help/command/add_custom_target.rst @@ -121,3 +121,6 @@ The options are: Execute the command with the given current working directory. If it is a relative path it will be interpreted relative to the build tree directory corresponding to the current source directory. + + Arguments to ``WORKING_DIRECTORY`` may use + :manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index f20b2743e..c4c512c0e 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -35,7 +35,7 @@ variable :variable:`BUILD_SHARED_LIBS` is ``ON``. For ``SHARED`` and ``MODULE`` libraries the :prop_tgt:`POSITION_INDEPENDENT_CODE` target property is set to ``ON`` automatically. A ``SHARED`` or ``STATIC`` library may be marked with the :prop_tgt:`FRAMEWORK` -target property to create an OS X Framework. +target property to create an macOS Framework. If a library does not export any symbols, it must not be declared as a ``SHARED`` library. For example, a Windows resource DLL or a managed C++/CLI @@ -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 000000000..e5fb87829 --- /dev/null +++ b/Help/command/add_link_options.rst @@ -0,0 +1,26 @@ +add_link_options +---------------- + +Adds options to the link of shared library, module and executable 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:: OPTIONS_SHELL.txt + +.. include:: LINK_OPTIONS_LINKER.txt diff --git a/Help/command/cmake_host_system_information.rst b/Help/command/cmake_host_system_information.rst index 989315194..2dee93ad5 100644 --- a/Help/command/cmake_host_system_information.rst +++ b/Help/command/cmake_host_system_information.rst @@ -20,10 +20,10 @@ Key Description ``NUMBER_OF_PHYSICAL_CORES`` Number of physical cores ``HOSTNAME`` Hostname ``FQDN`` Fully qualified domain name -``TOTAL_VIRTUAL_MEMORY`` Total virtual memory in megabytes -``AVAILABLE_VIRTUAL_MEMORY`` Available virtual memory in megabytes -``TOTAL_PHYSICAL_MEMORY`` Total physical memory in megabytes -``AVAILABLE_PHYSICAL_MEMORY`` Available physical memory in megabytes +``TOTAL_VIRTUAL_MEMORY`` Total virtual memory in MiB [#mebibytes]_ +``AVAILABLE_VIRTUAL_MEMORY`` Available virtual memory in MiB [#mebibytes]_ +``TOTAL_PHYSICAL_MEMORY`` Total physical memory in MiB [#mebibytes]_ +``AVAILABLE_PHYSICAL_MEMORY`` Available physical memory in MiB [#mebibytes]_ ``IS_64BIT`` One if processor is 64Bit ``HAS_FPU`` One if processor has floating point unit ``HAS_MMX`` One if processor supports MMX instructions @@ -44,3 +44,7 @@ Key Description ``OS_VERSION`` The OS build ID ``OS_PLATFORM`` See :variable:`CMAKE_HOST_SYSTEM_PROCESSOR` ============================= ================================================ + +.. rubric:: Footnotes + +.. [#mebibytes] One MiB (mebibyte) is equal to 1024x1024 bytes. diff --git a/Help/command/ctest_submit.rst b/Help/command/ctest_submit.rst index cc9612bcc..2ba6bef3d 100644 --- a/Help/command/ctest_submit.rst +++ b/Help/command/ctest_submit.rst @@ -10,6 +10,7 @@ Perform the :ref:`CTest Submit Step` as a :ref:`Dashboard Client`. [RETRY_COUNT <count>] [RETRY_DELAY <delay>] [RETURN_VALUE <result-var>] + [CAPTURE_CMAKE_ERROR <result-var>] [QUIET] ) @@ -52,6 +53,10 @@ The options are: Store in the ``<result-var>`` variable ``0`` for success and non-zero on failure. +``CAPTURE_CMAKE_ERROR <result-var>`` + Store in the ``<result-var>`` variable -1 if there are any errors running + the command and prevent ctest from returning non-zero if an error occurs. + ``QUIET`` Suppress all non-error messages that would have otherwise been printed to the console. @@ -65,6 +70,7 @@ Submit to CDash Upload API [HTTPHEADER <header>] [RETRY_COUNT <count>] [RETRY_DELAY <delay>] + [RETURN_VALUE <result-var>] [QUIET]) This second signature is used to upload files to CDash via the CDash @@ -73,5 +79,5 @@ with a content hash of the file. If CDash does not already have the file, then it is uploaded. Along with the file, a CDash type string is specified to tell CDash which handler to use to process the data. -This signature accepts the ``HTTPHEADER``, ``RETRY_COUNT``, ``RETRY_DELAY``, and -``QUIET`` options as described above. +This signature accepts the ``HTTPHEADER``, ``RETRY_COUNT``, ``RETRY_DELAY``, +``RETURN_VALUE`` and ``QUIET`` options as described above. diff --git a/Help/command/ctest_update.rst b/Help/command/ctest_update.rst index b205bca93..df1a4e560 100644 --- a/Help/command/ctest_update.rst +++ b/Help/command/ctest_update.rst @@ -5,7 +5,10 @@ Perform the :ref:`CTest Update Step` as a :ref:`Dashboard Client`. :: - ctest_update([SOURCE <source-dir>] [RETURN_VALUE <result-var>] [QUIET]) + ctest_update([SOURCE <source-dir>] + [RETURN_VALUE <result-var>] + [CAPTURE_CMAKE_ERROR <result-var>] + [QUIET]) Update the source tree from version control and record results in ``Update.xml`` for submission with the :command:`ctest_submit` command. @@ -20,6 +23,10 @@ The options are: Store in the ``<result-var>`` variable the number of files updated or ``-1`` on error. +``CAPTURE_CMAKE_ERROR <result-var>`` + Store in the ``<result-var>`` variable -1 if there are any errors running + the command and prevent ctest from returning non-zero if an error occurs. + ``QUIET`` Tell CTest to suppress most non-error messages that it would have otherwise printed to the console. CTest will still report diff --git a/Help/command/export.rst b/Help/command/export.rst index 0c676c6a7..8c4932848 100644 --- a/Help/command/export.rst +++ b/Help/command/export.rst @@ -51,15 +51,15 @@ unspecified. :: - export(PACKAGE <name>) + export(PACKAGE <PackageName>) Store the current build directory in the CMake user package registry -for package ``<name>``. The find_package command may consider the -directory while searching for package ``<name>``. This helps dependent +for package ``<PackageName>``. The find_package command may consider the +directory while searching for package ``<PackageName>``. This helps dependent projects find and use a package from the current project's build tree without help from the user. Note that the entry in the package registry that this command creates works only in conjunction with a -package configuration file (``<name>Config.cmake``) that works with the +package configuration file (``<PackageName>Config.cmake``) that works with the build tree. In some cases, for example for packaging and for system wide installations, it is not desirable to write the user package registry. If the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index a4416abd3..3ad571cdb 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -1,21 +1,29 @@ find_package ------------ -Load settings for an external project. +.. only:: html + + .. contents:: + +Find an external project, and load its settings. + +.. _`basic signature`: + +Basic Signature and Module Mode +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: - find_package(<package> [version] [EXACT] [QUIET] [MODULE] + find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE] [REQUIRED] [[COMPONENTS] [components...]] [OPTIONAL_COMPONENTS components...] [NO_POLICY_SCOPE]) -Finds and loads settings from an external project. ``<package>_FOUND`` +Finds and loads settings from an external project. ``<PackageName>_FOUND`` will be set to indicate whether the package was found. When the package is found package-specific information is provided through variables and :ref:`Imported Targets` documented by the package itself. The ``QUIET`` option disables messages if the package cannot be found. The -``MODULE`` option disables the second signature documented below. The ``REQUIRED`` option stops processing with an error message if the package cannot be found. @@ -33,28 +41,35 @@ should be compatible (format is ``major[.minor[.patch[.tweak]]]``). The inside a find-module, the corresponding arguments are forwarded automatically from the outer call (including the ``EXACT`` flag for ``[version]``). Version support is currently provided only on a -package-by-package basis (details below). +package-by-package basis (see the `Version Selection`_ section below). -User code should generally look for packages using the above simple -signature. The remainder of this command documentation specifies the +See the :command:`cmake_policy` command documentation for discussion +of the ``NO_POLICY_SCOPE`` option. + +The command has two modes by which it searches for packages: "Module" +mode and "Config" mode. The above signature selects Module mode. +If no module is found the command falls back to Config mode, described +below. This fall back is disabled if the ``MODULE`` option is given. + +In Module mode, CMake searches for a file called ``Find<PackageName>.cmake`` +in the :variable:`CMAKE_MODULE_PATH` followed by the CMake installation. +If the file is found, it is read and processed by CMake. It is responsible +for finding the package, checking the version, and producing any needed +messages. Some find-modules provide limited or no support for versioning; +check the module documentation. + +Full Signature and Config Mode +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +User code should generally look for packages using the above `basic +signature`_. The remainder of this command documentation specifies the full command signature and details of the search process. Project maintainers wishing to provide a package to be found by this command are encouraged to read on. -The command has two modes by which it searches for packages: "Module" -mode and "Config" mode. Module mode is available when the command is -invoked with the above reduced signature. CMake searches for a file -called ``Find<package>.cmake`` in the :variable:`CMAKE_MODULE_PATH` -followed by the CMake installation. If the file is found, it is read -and processed by CMake. It is responsible for finding the package, -checking the version, and producing any needed messages. Many -find-modules provide limited or no support for versioning; check -the module documentation. If no module is found and the ``MODULE`` -option is not given the command proceeds to Config mode. - The complete Config mode command signature is:: - find_package(<package> [version] [EXACT] [QUIET] + find_package(<PackageName> [version] [EXACT] [QUIET] [REQUIRED] [[COMPONENTS] [components...]] [CONFIG|NO_MODULE] [NO_POLICY_SCOPE] @@ -76,37 +91,44 @@ The complete Config mode command signature is:: ONLY_CMAKE_FIND_ROOT_PATH | NO_CMAKE_FIND_ROOT_PATH]) -The ``CONFIG`` option may be used to skip Module mode explicitly and -switch to Config mode. It is synonymous to using ``NO_MODULE``. Config -mode is also implied by use of options not specified in the reduced -signature. +The ``CONFIG`` option, the synonymous ``NO_MODULE`` option, or the use +of options not specified in the `basic signature`_ all enforce pure Config +mode. In pure Config mode, the command skips Module mode search and +proceeds at once with Config mode search. -Config mode attempts to locate a configuration file provided by the -package to be found. A cache entry called ``<package>_DIR`` is created to +Config mode search attempts to locate a configuration file provided by the +package to be found. A cache entry called ``<PackageName>_DIR`` is created to hold the directory containing the file. By default the command -searches for a package with the name ``<package>``. If the ``NAMES`` option -is given the names following it are used instead of ``<package>``. The -command searches for a file called ``<name>Config.cmake`` or -``<lower-case-name>-config.cmake`` for each name specified. A -replacement set of possible configuration file names may be given +searches for a package with the name ``<PackageName>``. If the ``NAMES`` option +is given the names following it are used instead of ``<PackageName>``. +The command searches for a file called ``<PackageName>Config.cmake`` or +``<lower-case-package-name>-config.cmake`` for each name specified. +A replacement set of possible configuration file names may be given using the ``CONFIGS`` option. The search procedure is specified below. Once found, the configuration file is read and processed by CMake. Since the file is provided by the package it already knows the location of package contents. The full path to the configuration file -is stored in the cmake variable ``<package>_CONFIG``. +is stored in the cmake variable ``<PackageName>_CONFIG``. All configuration files which have been considered by CMake while searching for an installation of the package with an appropriate -version are stored in the cmake variable ``<package>_CONSIDERED_CONFIGS``, -the associated versions in ``<package>_CONSIDERED_VERSIONS``. +version are stored in the cmake variable ``<PackageName>_CONSIDERED_CONFIGS``, +the associated versions in ``<PackageName>_CONSIDERED_VERSIONS``. If the package configuration file cannot be found CMake will generate an error describing the problem unless the ``QUIET`` argument is specified. If ``REQUIRED`` is specified and the package is not found a fatal error is generated and the configure step stops executing. If -``<package>_DIR`` has been set to a directory not containing a +``<PackageName>_DIR`` has been set to a directory not containing a configuration file CMake will ignore it and search from scratch. +Package maintainers providing CMake package configuration files are +encouraged to name and install them such that the `Search Procedure`_ +outlined below will find them without requiring use of additional options. + +Version Selection +^^^^^^^^^^^^^^^^^ + When the ``[version]`` argument is given Config mode will only find a version of the package that claims compatibility with the requested version (format is ``major[.minor[.patch[.tweak]]]``). If the ``EXACT`` @@ -127,7 +149,7 @@ version file is loaded in a nested scope in which the following variables have been defined: ``PACKAGE_FIND_NAME`` - the ``<package>`` name + the ``<PackageName>`` ``PACKAGE_FIND_VERSION`` full requested version string ``PACKAGE_FIND_VERSION_MAJOR`` @@ -158,17 +180,17 @@ whether the configuration file provides an acceptable version. They are not available after the find_package call returns. If the version is acceptable the following variables are set: -``<package>_VERSION`` +``<PackageName>_VERSION`` full provided version string -``<package>_VERSION_MAJOR`` +``<PackageName>_VERSION_MAJOR`` major version if provided, else 0 -``<package>_VERSION_MINOR`` +``<PackageName>_VERSION_MINOR`` minor version if provided, else 0 -``<package>_VERSION_PATCH`` +``<PackageName>_VERSION_PATCH`` patch version if provided, else 0 -``<package>_VERSION_TWEAK`` +``<PackageName>_VERSION_TWEAK`` tweak version if provided, else 0 -``<package>_VERSION_COUNT`` +``<PackageName>_VERSION_COUNT`` number of version components, 0 to 4 and the corresponding package configuration file is loaded. @@ -187,17 +209,8 @@ For instance in order to select the highest version one can set:: before calling ``find_package``. -Config mode provides an elaborate interface and search procedure. -Much of the interface is provided for completeness and for use -internally by find-modules loaded by Module mode. Most user code -should simply call:: - - find_package(<package> [major[.minor]] [EXACT] [REQUIRED|QUIET]) - -in order to find a package. Package maintainers providing CMake -package configuration files are encouraged to name and install them -such that the procedure outlined below will find them without -requiring use of additional options. +Search Procedure +^^^^^^^^^^^^^^^^ CMake constructs a set of possible installation prefixes for the package. Under each prefix several directories are searched for a @@ -216,7 +229,7 @@ Each entry is meant for installation trees following Windows (W), UNIX <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/ (W/U) <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (W/U) -On systems supporting OS X Frameworks and Application Bundles the +On systems supporting macOS Frameworks and Application Bundles the following directories are searched for frameworks or bundles containing a configuration file:: @@ -228,7 +241,7 @@ containing a configuration file:: <prefix>/<name>.app/Contents/Resources/CMake/ (A) In all cases the ``<name>`` is treated as case-insensitive and corresponds -to any of the names specified (``<package>`` or names given by ``NAMES``). +to any of the names specified (``<PackageName>`` or names given by ``NAMES``). Paths with ``lib/<arch>`` are enabled if the :variable:`CMAKE_LIBRARY_ARCHITECTURE` variable is set. ``lib*`` includes one @@ -286,7 +299,7 @@ enabled. (``;`` on Windows and ``:`` on UNIX). This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed:: - <package>_DIR + <PackageName>_DIR CMAKE_PREFIX_PATH CMAKE_FRAMEWORK_PATH CMAKE_APPBUNDLE_PATH @@ -329,7 +342,7 @@ enabled. hard-coded guesses. .. |FIND_XXX| replace:: find_package -.. |FIND_ARGS_XXX| replace:: <package> +.. |FIND_ARGS_XXX| replace:: <PackageName> .. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: :variable:`CMAKE_FIND_ROOT_PATH_MODE_PACKAGE` @@ -339,33 +352,36 @@ enabled. Every non-REQUIRED ``find_package`` call can be disabled by setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to ``TRUE``. +Package File Interface Variables +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + When loading a find module or package configuration file ``find_package`` defines variables to provide information about the call arguments (and restores their original state before returning): ``CMAKE_FIND_PACKAGE_NAME`` - the ``<package>`` name which is searched for -``<package>_FIND_REQUIRED`` + the ``<PackageName>`` which is searched for +``<PackageName>_FIND_REQUIRED`` true if ``REQUIRED`` option was given -``<package>_FIND_QUIETLY`` +``<PackageName>_FIND_QUIETLY`` true if ``QUIET`` option was given -``<package>_FIND_VERSION`` +``<PackageName>_FIND_VERSION`` full requested version string -``<package>_FIND_VERSION_MAJOR`` +``<PackageName>_FIND_VERSION_MAJOR`` major version if requested, else 0 -``<package>_FIND_VERSION_MINOR`` +``<PackageName>_FIND_VERSION_MINOR`` minor version if requested, else 0 -``<package>_FIND_VERSION_PATCH`` +``<PackageName>_FIND_VERSION_PATCH`` patch version if requested, else 0 -``<package>_FIND_VERSION_TWEAK`` +``<PackageName>_FIND_VERSION_TWEAK`` tweak version if requested, else 0 -``<package>_FIND_VERSION_COUNT`` +``<PackageName>_FIND_VERSION_COUNT`` number of version components, 0 to 4 -``<package>_FIND_VERSION_EXACT`` +``<PackageName>_FIND_VERSION_EXACT`` true if ``EXACT`` option was given -``<package>_FIND_COMPONENTS`` +``<PackageName>_FIND_COMPONENTS`` list of requested components -``<package>_FIND_REQUIRED_<c>`` +``<PackageName>_FIND_REQUIRED_<c>`` true if component ``<c>`` is required, false if component ``<c>`` is optional @@ -375,8 +391,5 @@ In Config mode ``find_package`` handles ``REQUIRED``, ``QUIET``, and ``[version]`` options automatically but leaves it to the package configuration file to handle components in a way that makes sense for the package. The package configuration file may set -``<package>_FOUND`` to false to tell ``find_package`` that component +``<PackageName>_FOUND`` to false to tell ``find_package`` that component requirements are not satisfied. - -See the :command:`cmake_policy` command documentation for discussion -of the ``NO_POLICY_SCOPE`` option. diff --git a/Help/command/if.rst b/Help/command/if.rst index f04f23321..5294ce8e3 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -148,23 +148,33 @@ Possible expressions are: ``if(<variable|string> VERSION_LESS <variable|string>)`` Component-wise integer version number comparison (version format is - ``major[.minor[.patch[.tweak]]]``). + ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero). + Any non-integer version component or non-integer trailing part of a version + component effectively truncates the string at that point. ``if(<variable|string> VERSION_GREATER <variable|string>)`` Component-wise integer version number comparison (version format is - ``major[.minor[.patch[.tweak]]]``). + ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero). + Any non-integer version component or non-integer trailing part of a version + component effectively truncates the string at that point. ``if(<variable|string> VERSION_EQUAL <variable|string>)`` Component-wise integer version number comparison (version format is - ``major[.minor[.patch[.tweak]]]``). + ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero). + Any non-integer version component or non-integer trailing part of a version + component effectively truncates the string at that point. ``if(<variable|string> VERSION_LESS_EQUAL <variable|string>)`` Component-wise integer version number comparison (version format is - ``major[.minor[.patch[.tweak]]]``). + ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero). + Any non-integer version component or non-integer trailing part of a version + component effectively truncates the string at that point. ``if(<variable|string> VERSION_GREATER_EQUAL <variable|string>)`` Component-wise integer version number comparison (version format is - ``major[.minor[.patch[.tweak]]]``). + ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero). + Any non-integer version component or non-integer trailing part of a version + component effectively truncates the string at that point. ``if(<variable|string> IN_LIST <variable>)`` True if the given element is contained in the named list variable. diff --git a/Help/command/include_directories.rst b/Help/command/include_directories.rst index f69493460..e797b5df1 100644 --- a/Help/command/include_directories.rst +++ b/Help/command/include_directories.rst @@ -33,3 +33,9 @@ Arguments to ``include_directories`` 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:: + + Prefer the :command:`target_include_directories` command to add include + directories to individual targets and optionally propagate/export them + to dependents. diff --git a/Help/command/install.rst b/Help/command/install.rst index 6cea996f0..98074d0b6 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -89,6 +89,13 @@ Command signatures that install files may print messages during installation. Use the :variable:`CMAKE_INSTALL_MESSAGE` variable to control which messages are printed. +Many of the ``install()`` variants implicitly create the directories +containing the installed files. If +:variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` is set, these +directories will be created with the permissions specified. Otherwise, +they will be created according to the uname rules on Unix-like platforms. +Windows platforms are unaffected. + Installing Targets ^^^^^^^^^^^^^^^^^^ @@ -115,19 +122,19 @@ project. There are several kinds of target files that may be installed: ``ARCHIVE`` Static libraries are treated as ``ARCHIVE`` targets, except those - marked with the ``FRAMEWORK`` property on OS X (see ``FRAMEWORK`` + marked with the ``FRAMEWORK`` property on macOS (see ``FRAMEWORK`` below.) For DLL platforms (all Windows-based systems including Cygwin), the DLL import library is treated as an ``ARCHIVE`` target. ``LIBRARY`` Module libraries are always treated as ``LIBRARY`` targets. For non- DLL platforms shared libraries are treated as ``LIBRARY`` targets, - except those marked with the ``FRAMEWORK`` property on OS X (see + except those marked with the ``FRAMEWORK`` property on macOS (see ``FRAMEWORK`` below.) ``RUNTIME`` Executables are treated as ``RUNTIME`` objects, except those marked - with the ``MACOSX_BUNDLE`` property on OS X (see ``BUNDLE`` below.) + with the ``MACOSX_BUNDLE`` property on macOS (see ``BUNDLE`` below.) For DLL platforms (all Windows-based systems including Cygwin), the DLL part of a shared library is treated as a ``RUNTIME`` target. @@ -137,11 +144,11 @@ project. There are several kinds of target files that may be installed: ``FRAMEWORK`` Both static and shared libraries marked with the ``FRAMEWORK`` - property are treated as ``FRAMEWORK`` targets on OS X. + property are treated as ``FRAMEWORK`` targets on macOS. ``BUNDLE`` Executables marked with the ``MACOSX_BUNDLE`` property are treated as - ``BUNDLE`` targets on OS X. + ``BUNDLE`` targets on macOS. ``PUBLIC_HEADER`` Any ``PUBLIC_HEADER`` files associated with a library are installed in @@ -280,6 +287,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. diff --git a/Help/command/link_directories.rst b/Help/command/link_directories.rst index 5c64bc609..1dce9a05a 100644 --- a/Help/command/link_directories.rst +++ b/Help/command/link_directories.rst @@ -1,19 +1,51 @@ link_directories ---------------- -Specify directories in which the linker will look for libraries. +Add directories in which the linker will look for libraries. :: - link_directories(directory1 directory2 ...) + link_directories([AFTER|BEFORE] directory1 [directory2 ...]) -Specify the paths in which the linker should search for libraries. -The command will apply only to targets created after it is called. +Add the paths in which the linker should search for libraries. Relative paths given to this command are interpreted as relative to the current source directory, see :policy:`CMP0015`. -Note that this command is rarely necessary. Library locations -returned by :command:`find_package` and :command:`find_library` are -absolute paths. Pass these absolute library file paths directly to the -:command:`target_link_libraries` command. CMake will ensure the linker finds -them. +The directories are added to the :prop_dir:`LINK_DIRECTORIES` directory +property for the current ``CMakeLists.txt`` file, converting relative +paths to absolute as needed. +The command will apply only to targets created after it is called. + +By default the directories specified are appended onto the current list of +directories. This default behavior can be changed by setting +:variable:`CMAKE_LINK_DIRECTORIES_BEFORE` to ``ON``. By using +``AFTER`` or ``BEFORE`` explicitly, you can select between appending and +prepending, independent of the default. + +Arguments to ``link_directories`` 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 command is rarely necessary and should be avoided where there are + other choices. Prefer to pass full absolute paths to libraries where + possible, since this ensures the correct library will always be linked. + The :command:`find_library` command provides the full path, which can + generally be used directly in calls to :command:`target_link_libraries`. + Situations where a library search path may be needed include: + + - Project generators like Xcode where the user can switch target + architecture at build time, but a full path to a library cannot + be used because it only provides one architecture (i.e. it is not + a universal binary). + - Libraries may themselves have other private library dependencies + that expect to be found via ``RPATH`` mechanisms, but some linkers + are not able to fully decode those paths (e.g. due to the presence + of things like ``$ORIGIN``). + + If a library search path must be provided, prefer to localize the effect + where possible by using the :command:`target_link_directories` command + rather than ``link_directories()``. The target-specific command can also + control how the search directories propagate to other dependent targets. diff --git a/Help/command/list.rst b/Help/command/list.rst index 589e57253..2357a9b8d 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,27 @@ 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 ``COMPARE`` keyword to select the comparison method for sorting. +The ``<compare>`` option should be one of: + +* ``STRING``: Sorts a list of strings alphabetically. This is the + default behavior if the ``COMPARE`` option is not given. +* ``FILE_BASENAME``: Sorts a list of pathnames of files by their basenames. + +Use the ``CASE`` keyword to select a case sensitive or case insensitive +sort mode. The ``<case>`` option should be one of: + +* ``SENSITIVE``: List items are sorted in a case-sensitive manner. This is + the default behavior if the ``CASE`` option is not given. +* ``INSENSITIVE``: List items are sorted case insensitively. The order of + items which differ only by upper/lowercase is not specified. + +To control the sort order, the ``ORDER`` keyword can be given. +The ``<order>`` option should be one of: + +* ``ASCENDING``: Sorts the list in ascending order. This is the default + behavior when the ``ORDER`` option is not given. +* ``DESCENDING``: Sorts the list in descending order. diff --git a/Help/command/math.rst b/Help/command/math.rst index f99dc3db3..63af931d8 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 91cd0a778..4fabb8747 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/project.rst b/Help/command/project.rst index c1de05786..bd8b4ef5c 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -44,6 +44,7 @@ Variables corresponding to unspecified versions are set to the empty string If the optional ``DESCRIPTION`` is given, then :variable:`PROJECT_DESCRIPTION` and :variable:`<PROJECT-NAME>_DESCRIPTION` will be set to its argument. +These variables will be cleared if ``DESCRIPTION`` is not given. The description is expected to be a relatively short string, usually no more than a few words. @@ -51,6 +52,7 @@ The optional ``HOMEPAGE_URL`` sets the analogous variables :variable:`PROJECT_HOMEPAGE_URL` and :variable:`<PROJECT-NAME>_HOMEPAGE_URL`. When this option is given, the URL provided should be the canonical home for the project. +These variables will be cleared if ``HOMEPAGE_URL`` is not given. Note that the description and homepage URL may be used as defaults for things like packaging meta-data, documentation, etc. diff --git a/Help/command/set_directory_properties.rst b/Help/command/set_directory_properties.rst index e485fce0a..42e7fd783 100644 --- a/Help/command/set_directory_properties.rst +++ b/Help/command/set_directory_properties.rst @@ -1,12 +1,11 @@ set_directory_properties ------------------------ -Set a property of the directory. +Set properties of the current directory and subdirectories in key-value pairs. :: set_directory_properties(PROPERTIES prop1 value1 prop2 value2) -Set a property for the current directory and subdirectories. See -:ref:`Directory Properties` for the list of properties known -to CMake. +See :ref:`Directory Properties` for the list of properties known to CMake +and their individual documentation for the behavior of each property. diff --git a/Help/command/string.rst b/Help/command/string.rst index efa923b70..cc18069f4 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -121,6 +121,11 @@ The following characters have special meaning in regular expressions: Matches at end of input ``.`` Matches any single character +``\<char>`` + Matches the single character specified by ``<char>``. Use this to + match special regex characters, e.g. ``\.`` for a literal ``.`` + or ``\\`` for a literal backslash ``\``. Escaping a non-special + character is unnecessary but allowed, e.g. ``\a`` matches ``a``. ``[ ]`` Matches any character(s) inside the brackets ``[^ ]`` @@ -151,6 +156,22 @@ 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``. +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. +* The quoted argument ``"\\(\\a\\+b\\)"`` specifies a regex that matches + the exact string ``(a+b)``. Each ``\\`` is parsed in a quoted argument + as just ``\``, so the regex itself is actually ``\(\a\+\b\)``. This + can alternatively be specified in a :ref:`bracket argument` without + having to escape the backslashes, e.g. ``[[\(\a\+\b\)]]``. + Manipulation ^^^^^^^^^^^^ diff --git a/Help/command/target_compile_options.rst b/Help/command/target_compile_options.rst index 194d0081c..88b7f1542 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_directories.rst b/Help/command/target_link_directories.rst new file mode 100644 index 000000000..b46aac07d --- /dev/null +++ b/Help/command/target_link_directories.rst @@ -0,0 +1,55 @@ +target_link_directories +----------------------- + +Add link directories to a target. + +:: + + target_link_directories(<target> [BEFORE] + <INTERFACE|PUBLIC|PRIVATE> [items1...] + [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) + +Specify the paths in which the linker should search for libraries when +linking a given target. Each item can be an absolute or relative path, +with the latter being interpreted as relative to the current source +directory. These items will be added to the link command. + +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>`. + +The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to +specify the scope of the items that follow them. ``PRIVATE`` and +``PUBLIC`` items will populate the :prop_tgt:`LINK_DIRECTORIES` property +of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the +:prop_tgt:`INTERFACE_LINK_DIRECTORIES` property of ``<target>`` +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items). +Each item specifies a link directory and will be converted to an absolute +path if necessary before adding it to the relevant property. Repeated +calls for the same ``<target>`` append items in the order called. + +If ``BEFORE`` is specified, the content will be prepended to the relevant +property instead of being appended. + +Arguments to ``target_link_directories`` 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 command is rarely necessary and should be avoided where there are + other choices. Prefer to pass full absolute paths to libraries where + possible, since this ensures the correct library will always be linked. + The :command:`find_library` command provides the full path, which can + generally be used directly in calls to :command:`target_link_libraries`. + Situations where a library search path may be needed include: + + - Project generators like Xcode where the user can switch target + architecture at build time, but a full path to a library cannot + be used because it only provides one architecture (i.e. it is not + a universal binary). + - Libraries may themselves have other private library dependencies + that expect to be found via ``RPATH`` mechanisms, but some linkers + are not able to fully decode those paths (e.g. due to the presence + of things like ``$ORIGIN``). diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index fcc2c0745..58f312e1a 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -18,10 +18,13 @@ All of them have the general form:: target_link_libraries(<target> ... <item>... ...) -The named ``<target>`` must have been created in the current directory by -a command such as :command:`add_executable` or :command:`add_library` and -must not be an :ref:`ALIAS target <Alias Targets>`. -Repeated calls for the same ``<target>`` append items in the order called. +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 policy :policy:`CMP0079` is not +set to ``NEW`` then the target must have been created in the current +directory. Repeated calls for the same ``<target>`` append items in +the order called. + Each ``<item>`` may be: * **A library target name**: The generated link line will have the @@ -40,6 +43,9 @@ Each ``<item>`` may be: the library instead of using the full path (e.g. ``/usr/lib/libfoo.so`` becomes ``-lfoo``). + The full path to the target's artifact will be quoted/escaped for + the shell automatically. + * **A full path to a library file**: The generated link line will normally preserve the full path to the file. The buildsystem will have a dependency to re-link ``<target>`` if the library file changes. @@ -59,9 +65,15 @@ Each ``<item>`` may be: imported into generated project files. This is not supported by other generators. + The full path to the library file will be quoted/escaped for + the shell automatically. + * **A plain library name**: The generated link line will ask the linker to search for the library (e.g. ``foo`` becomes ``-lfoo`` or ``foo.lib``). + The library name/flag is treated as a command-line string fragment and + will be used with no extra quoting or escaping. + * **A link flag**: Item names starting with ``-``, but not ``-l`` or ``-framework``, are treated as linker flags. Note that such flags will be treated like any other library link item for purposes of transitive @@ -70,10 +82,28 @@ 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. + The link flag is treated as a command-line string fragment and + will be used with no extra quoting or escaping. + +* **A generator expression**: A ``$<...>`` :manual:`generator expression + <cmake-generator-expressions(7)>` may evaluate to any of the above + items or to a :ref:`;-list <CMake Language Lists>` of them. + If the ``...`` contains any ``;`` characters, e.g. after evaluation + of a ``${list}`` variable, be sure to use an explicitly quoted + argument ``"$<...>"`` so that this command receives it as a + single ``<item>``. + + Additionally, a generator expression may be used as a fragment of + any of the above items, e.g. ``foo$<1:_d>``. + + Note that generator expressions will not be used in OLD handling of + policy :policy:`CMP0003` or policy :policy:`CMP0004`. + * A ``debug``, ``optimized``, or ``general`` keyword immediately followed by another ``<item>``. The item following such a keyword will be used only for the corresponding build configuration. The ``debug`` keyword @@ -84,18 +114,16 @@ Each ``<item>`` may be: optional. Higher granularity may be achieved for per-configuration rules by creating and linking to :ref:`IMPORTED library targets <Imported Targets>`. + These keywords are interpreted immediately by this command and therefore + have no special meaning when produced by a generator expression. Items containing ``::``, such as ``Foo::Bar``, are assumed to be :ref:`IMPORTED <Imported Targets>` or :ref:`ALIAS <Alias Targets>` library target names and will cause an error if no such target exists. See policy :policy:`CMP0028`. -Arguments to ``target_link_libraries`` may use "generator expressions" -with the syntax ``$<...>``. Note however, that generator expressions -will not be used in OLD handling of :policy:`CMP0003` or :policy:`CMP0004`. -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 the :manual:`cmake-buildsystem(7)` manual for more on defining +buildsystem properties. Libraries for a Target and/or its Dependents ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/command/target_link_options.rst b/Help/command/target_link_options.rst new file mode 100644 index 000000000..0b45a8b2c --- /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:: OPTIONS_SHELL.txt + +.. include:: LINK_OPTIONS_LINKER.txt diff --git a/Help/command/target_sources.rst b/Help/command/target_sources.rst index a4f5196e6..5dd8d86cc 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/command/unset.rst b/Help/command/unset.rst index a1fc95cc6..c19dd318a 100644 --- a/Help/command/unset.rst +++ b/Help/command/unset.rst @@ -7,9 +7,16 @@ Unset a variable, cache variable, or environment variable. unset(<variable> [CACHE | PARENT_SCOPE]) -Removes the specified variable causing it to become undefined. If -``CACHE`` is present then the variable is removed from the cache instead -of the current scope. +Removes a normal variable from the current scope, causing it +to become undefined. If ``CACHE`` is present, then a cache variable +is removed instead of a normal variable. Note that when evaluating +:ref:`Variable References` of the form ``${VAR}``, CMake first searches +for a normal variable with that name. If no such normal variable exists, +CMake will then search for a cache entry with that name. Because of this +unsetting a normal variable can expose a cache variable that was previously +hidden. To force a variable reference of the form ``${VAR}`` to return an +empty string, use ``set(<variable> "")``, which clears the normal variable +but leaves it defined. If ``PARENT_SCOPE`` is present then the variable is removed from the scope above the current scope. See the same option in the :command:`set` command diff --git a/Help/cpack_gen/archive.rst b/Help/cpack_gen/archive.rst new file mode 100644 index 000000000..b288aaddc --- /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 000000000..29727e2e9 --- /dev/null +++ b/Help/cpack_gen/bundle.rst @@ -0,0 +1,64 @@ +CPack Bundle Generator +---------------------- + +CPack Bundle generator (macOS) specific options + +Variables specific to CPack Bundle generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Installers built on macOS 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 000000000..1c5f7af91 --- /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 000000000..fdde6544b --- /dev/null +++ b/Help/cpack_gen/deb.rst @@ -0,0 +1,557 @@ +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. + +Packaging of debug information +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Dbgsym packages contain debug symbols for debugging packaged binaries. + +Dbgsym packaging has its own set of variables: + +.. variable:: CPACK_DEBIAN_DEBUGINFO_PACKAGE + CPACK_DEBIAN_<component>_DEBUGINFO_PACKAGE + + Enable generation of dbgsym .ddeb 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. + +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 000000000..1e3788933 --- /dev/null +++ b/Help/cpack_gen/dmg.rst @@ -0,0 +1,101 @@ +CPack DragNDrop Generator +------------------------- + +The DragNDrop CPack generator (macOS) creates a DMG image. + +Variables specific to CPack DragNDrop generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following variables are specific to the DragNDrop installers built +on macOS: + +.. 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 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 + macOS. 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 macOS. 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 macOS. 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 000000000..e4912a462 --- /dev/null +++ b/Help/cpack_gen/external.rst @@ -0,0 +1,283 @@ +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. + +Integration with External Packaging Tools +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The CPack External generator generates a .json file containing the +CPack internal metadata, which gives external software information +on how to package the software. External packaging software may itself +invoke CPack, consume the generated metadata, +install and package files as required. + +Alternatively CPack can invoke an external packaging software +through an optional custom CMake script in +:variable:`CPACK_EXTERNAL_PACKAGE_SCRIPT` instead. + +Staging of installation files may also optionally be +taken care of by the generator when enabled through the +:variable:`CPACK_EXTERNAL_ENABLE_STAGING` variable. + +JSON Format +^^^^^^^^^^^ + +The JSON 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. + +The JSON's 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_EXTERNAL_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_EXTERNAL_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_EXTERNAL_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_EXTERNAL_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_EXTERNAL_REQUESTED_VERSIONS`` (one + that doesn't match ``major.minor``, where ``major`` and ``minor`` are + integers), it is ignored. + +.. variable:: CPACK_EXTERNAL_ENABLE_STAGING + + This variable can be set to true to enable optional installation + into a temporary staging area which can then be picked up + and packaged by an external packaging tool. + The top level directory used by CPack for the current packaging + task is contained in ``CPACK_TOPLEVEL_DIRECTORY``. + It is automatically cleaned up on each run before packaging is initiated + and can be used for custom temporary files required by + the external packaging tool. + It also contains the staging area ``CPACK_TEMPORARY_DIRECTORY`` + into which CPack performs the installation when staging is enabled. + +.. variable:: CPACK_EXTERNAL_PACKAGE_SCRIPT + + This variable can optionally specify the full path to + a CMake script file to be run as part of the CPack invocation. + It is invoked after (optional) staging took place and may + run an external packaging tool. The script has access to + the variables defined by the CPack config file. diff --git a/Help/cpack_gen/freebsd.rst b/Help/cpack_gen/freebsd.rst new file mode 100644 index 000000000..b22ea9a81 --- /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 000000000..e43b1d646 --- /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 macOS. + +You should also install QtIFW_ to use CPack ``IFW`` generator. + +Hints +^^^^^ + +Generally, the CPack ``IFW`` generator automatically finds QtIFW_ tools, +but if you don't use a default path for installation of the QtIFW_ tools, +the path may be specified in either a CMake or an environment variable: + +.. variable:: CPACK_IFW_ROOT + + An CMake variable which specifies the location of the QtIFW_ tool suite. + + The variable will be cached in the ``CPackConfig.cmake`` file and used at + CPack runtime. + +.. variable:: QTIFWDIR + + An environment variable which specifies the location of the QtIFW_ tool + suite. + +.. note:: + The specified path should not contain "bin" at the end + (for example: "D:\\DevTools\\QtIFW2.0.5"). + +The :variable:`CPACK_IFW_ROOT` variable has a higher priority and overrides +the value of the :variable:`QTIFWDIR` variable. + +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' (macOS), + '.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 000000000..9f82a04bd --- /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 000000000..c8c481f8e --- /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 000000000..e9464b749 --- /dev/null +++ b/Help/cpack_gen/packagemaker.rst @@ -0,0 +1,23 @@ +CPack PackageMaker Generator +---------------------------- + +PackageMaker CPack generator (macOS). + +Variables specific to CPack PackageMaker generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following variable is specific to installers built on Mac +macOS using PackageMaker: + +.. variable:: CPACK_OSX_PACKAGE_VERSION + + The version of macOS that the resulting PackageMaker archive should be + compatible with. Different versions of macOS support different + features. For example, CPack can only build component-based installers for + macOS 10.4 or newer, and can only build installers that download + component son-the-fly for macOS 10.5 or newer. If left blank, this value + will be set to the minimum version of macOS 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 macOS, and + don't mind missing extra features available in the installer shipping with + later versions of macOS. diff --git a/Help/cpack_gen/productbuild.rst b/Help/cpack_gen/productbuild.rst new file mode 100644 index 000000000..d22fcd48a --- /dev/null +++ b/Help/cpack_gen/productbuild.rst @@ -0,0 +1,68 @@ +CPack productbuild Generator +---------------------------- + +productbuild CPack generator (macOS). + +Variables specific to CPack productbuild generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following variable is specific to installers built on Mac +macOS using ProductBuild: + +.. variable:: CPACK_COMMAND_PRODUCTBUILD + + Path to the ``productbuild(1)`` command used to generate a product archive for + the macOS 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 macOS component package + on macOS. 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 000000000..5c543ffce --- /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 its 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 its 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 its 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 000000000..dde49438b --- /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\<PackageName>`` + The value for ``<PackageName>`` 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 ec764792c..a8942cd7c 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 1b29acf30..23d0ca3f2 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/CMAKE_OSX_ARCHITECTURES.rst b/Help/envvar/CMAKE_OSX_ARCHITECTURES.rst index 8bbf993bd..5fd6e5223 100644 --- a/Help/envvar/CMAKE_OSX_ARCHITECTURES.rst +++ b/Help/envvar/CMAKE_OSX_ARCHITECTURES.rst @@ -1,7 +1,7 @@ CMAKE_OSX_ARCHITECTURES ----------------------- -Target specific architectures for OS X. +Target specific architectures for macOS. The ``CMAKE_OSX_ARCHITECTURES`` environment variable sets the default value for the :variable:`CMAKE_OSX_ARCHITECTURES` variable. See diff --git a/Help/envvar/CTEST_PROGRESS_OUTPUT.rst b/Help/envvar/CTEST_PROGRESS_OUTPUT.rst new file mode 100644 index 000000000..a8e15bc2f --- /dev/null +++ b/Help/envvar/CTEST_PROGRESS_OUTPUT.rst @@ -0,0 +1,14 @@ +CTEST_PROGRESS_OUTPUT +--------------------- + +Boolean environment variable that affects how :manual:`ctest <ctest(1)>` +command output reports overall progress. When set to 1, TRUE, ON or anything +else that evaluates to boolean true, progress is reported by repeatedly +updating the same line. This greatly reduces the overall verbosity, but is +only supported when output is sent directly to a terminal. If the environment +variable is not set or has a value that evaluates to false, output is reported +normally with each test having its own start and end lines logged to the +output. + +The ``--progress`` option to :manual:`ctest <ctest(1)>` overrides this +environment variable if both are given. diff --git a/Help/envvar/CUDAHOSTCXX.rst b/Help/envvar/CUDAHOSTCXX.rst index f0f94f647..bb786ca83 100644 --- a/Help/envvar/CUDAHOSTCXX.rst +++ b/Help/envvar/CUDAHOSTCXX.rst @@ -7,3 +7,7 @@ determine ``CUDA`` host compiler, after which the value for ``CUDAHOSTCXX`` is stored in the cache as :variable:`CMAKE_CUDA_HOST_COMPILER`. For any configuration run (including the first), the environment variable will be ignored if the :variable:`CMAKE_CUDA_HOST_COMPILER` variable is defined. + +This environment variable is primarily meant for use with projects that +enable ``CUDA`` as a first-class language. The :module:`FindCUDA` +module will also use it to initialize its ``CUDA_HOST_COMPILER`` setting. diff --git a/Help/envvar/MACOSX_DEPLOYMENT_TARGET.rst b/Help/envvar/MACOSX_DEPLOYMENT_TARGET.rst index e6051b44a..9dafa3234 100644 --- a/Help/envvar/MACOSX_DEPLOYMENT_TARGET.rst +++ b/Help/envvar/MACOSX_DEPLOYMENT_TARGET.rst @@ -1,7 +1,7 @@ MACOSX_DEPLOYMENT_TARGET ------------------------ -Specify the minimum version of OS X on which the target binaries are +Specify the minimum version of macOS on which the target binaries are to be deployed. The ``MACOSX_DEPLOYMENT_TARGET`` environment variable sets the default value for diff --git a/Help/generator/Green Hills MULTI.rst b/Help/generator/Green Hills MULTI.rst index 4d3169026..1b4960d89 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/generator/Visual Studio 10 2010.rst b/Help/generator/Visual Studio 10 2010.rst index 04eef1039..0446b8c1a 100644 --- a/Help/generator/Visual Studio 10 2010.rst +++ b/Help/generator/Visual Studio 10 2010.rst @@ -3,11 +3,29 @@ Visual Studio 10 2010 Generates Visual Studio 10 (VS 2010) project files. -The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set -to specify a target platform name (architecture). +For compatibility with CMake versions prior to 3.0, one may specify this +generator using the name ``Visual Studio 10`` without the year component. + +Project Types +^^^^^^^^^^^^^ + +Only Visual C++ and C# projects may be generated. Other types of +projects (Database, Website, etc.) are not supported. + +Platform Selection +^^^^^^^^^^^^^^^^^^ + +The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps +via the :manual:`cmake(1)` ``-A`` option, to specify a target platform +name (architecture). For example: + +* ``cmake -G "Visual Studio 10 2010" -A Win32`` +* ``cmake -G "Visual Studio 10 2010" -A x64`` +* ``cmake -G "Visual Studio 10 2010" -A Itanium`` For compatibility with CMake versions prior to 3.1, one may specify -a target platform name optionally at the end of this generator name: +a target platform name optionally at the end of the generator name. +This is supported only for: ``Visual Studio 10 2010 Win64`` Specify target platform ``x64``. @@ -15,9 +33,6 @@ a target platform name optionally at the end of this generator name: ``Visual Studio 10 2010 IA64`` Specify target platform ``Itanium``. -For compatibility with CMake versions prior to 3.0, one may specify this -generator using the name ``Visual Studio 10`` without the year component. - Toolset Selection ^^^^^^^^^^^^^^^^^ diff --git a/Help/generator/Visual Studio 11 2012.rst b/Help/generator/Visual Studio 11 2012.rst index 347a153b9..8fddbb301 100644 --- a/Help/generator/Visual Studio 11 2012.rst +++ b/Help/generator/Visual Studio 11 2012.rst @@ -3,11 +3,31 @@ Visual Studio 11 2012 Generates Visual Studio 11 (VS 2012) project files. -The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set -to specify a target platform name (architecture). +For compatibility with CMake versions prior to 3.0, one may specify this +generator using the name "Visual Studio 11" without the year component. + +Project Types +^^^^^^^^^^^^^ + +Only Visual C++ and C# projects may be generated. Other types of +projects (JavaScript, Database, Website, etc.) are not supported. + +Platform Selection +^^^^^^^^^^^^^^^^^^ + +The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps +via the :manual:`cmake(1)` ``-A`` option, to specify a target platform +name (architecture). For example: + +* ``cmake -G "Visual Studio 11 2012" -A Win32`` +* ``cmake -G "Visual Studio 11 2012" -A x64`` +* ``cmake -G "Visual Studio 11 2012" -A ARM`` +* ``cmake -G "Visual Studio 11 2012" -A <WinCE-SDK>`` + (Specify a target platform matching a Windows CE SDK name.) For compatibility with CMake versions prior to 3.1, one may specify -a target platform name optionally at the end of this generator name: +a target platform name optionally at the end of the generator name. +This is supported only for: ``Visual Studio 11 2012 Win64`` Specify target platform ``x64``. @@ -18,9 +38,6 @@ a target platform name optionally at the end of this generator name: ``Visual Studio 11 2012 <WinCE-SDK>`` Specify target platform matching a Windows CE SDK name. -For compatibility with CMake versions prior to 3.0, one may specify this -generator using the name "Visual Studio 11" without the year component. - Toolset Selection ^^^^^^^^^^^^^^^^^ diff --git a/Help/generator/Visual Studio 12 2013.rst b/Help/generator/Visual Studio 12 2013.rst index 5071b20ce..8b4c16295 100644 --- a/Help/generator/Visual Studio 12 2013.rst +++ b/Help/generator/Visual Studio 12 2013.rst @@ -3,11 +3,29 @@ Visual Studio 12 2013 Generates Visual Studio 12 (VS 2013) project files. -The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set -to specify a target platform name (architecture). +For compatibility with CMake versions prior to 3.0, one may specify this +generator using the name "Visual Studio 12" without the year component. + +Project Types +^^^^^^^^^^^^^ + +Only Visual C++ and C# projects may be generated. Other types of +projects (JavaScript, Powershell, Python, etc.) are not supported. + +Platform Selection +^^^^^^^^^^^^^^^^^^ + +The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps +via the :manual:`cmake(1)` ``-A`` option, to specify a target platform +name (architecture). For example: + +* ``cmake -G "Visual Studio 12 2013" -A Win32`` +* ``cmake -G "Visual Studio 12 2013" -A x64`` +* ``cmake -G "Visual Studio 12 2013" -A ARM`` For compatibility with CMake versions prior to 3.1, one may specify -a target platform name optionally at the end of this generator name: +a target platform name optionally at the end of the generator name. +This is supported only for: ``Visual Studio 12 2013 Win64`` Specify target platform ``x64``. @@ -15,9 +33,6 @@ a target platform name optionally at the end of this generator name: ``Visual Studio 12 2013 ARM`` Specify target platform ``ARM``. -For compatibility with CMake versions prior to 3.0, one may specify this -generator using the name "Visual Studio 12" without the year component. - Toolset Selection ^^^^^^^^^^^^^^^^^ diff --git a/Help/generator/Visual Studio 14 2015.rst b/Help/generator/Visual Studio 14 2015.rst index 64254b579..917d8e5c4 100644 --- a/Help/generator/Visual Studio 14 2015.rst +++ b/Help/generator/Visual Studio 14 2015.rst @@ -3,11 +3,26 @@ Visual Studio 14 2015 Generates Visual Studio 14 (VS 2015) project files. -The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set -to specify a target platform name (architecture). +Project Types +^^^^^^^^^^^^^ + +Only Visual C++ and C# projects may be generated. Other types of +projects (JavaScript, Powershell, Python, etc.) are not supported. + +Platform Selection +^^^^^^^^^^^^^^^^^^ + +The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps +via the :manual:`cmake(1)` ``-A`` option, to specify a target platform +name (architecture). For example: + +* ``cmake -G "Visual Studio 14 2015" -A Win32`` +* ``cmake -G "Visual Studio 14 2015" -A x64`` +* ``cmake -G "Visual Studio 14 2015" -A ARM`` For compatibility with CMake versions prior to 3.1, one may specify -a target platform name optionally at the end of this generator name: +a target platform name optionally at the end of the generator name. +This is supported only for: ``Visual Studio 14 2015 Win64`` Specify target platform ``x64``. diff --git a/Help/generator/Visual Studio 15 2017.rst b/Help/generator/Visual Studio 15 2017.rst index 2cf1aa013..42a3bb6b3 100644 --- a/Help/generator/Visual Studio 15 2017.rst +++ b/Help/generator/Visual Studio 15 2017.rst @@ -3,17 +3,11 @@ Visual Studio 15 2017 Generates Visual Studio 15 (VS 2017) project files. -The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set -to specify a target platform name (architecture). +Project Types +^^^^^^^^^^^^^ -For compatibility with CMake versions prior to 3.1, one may specify -a target platform name optionally at the end of this generator name: - -``Visual Studio 15 2017 Win64`` - Specify target platform ``x64``. - -``Visual Studio 15 2017 ARM`` - Specify target platform ``ARM``. +Only Visual C++ and C# projects may be generated. Other types of +projects (JavaScript, Powershell, Python, etc.) are not supported. Instance Selection ^^^^^^^^^^^^^^^^^^ @@ -31,6 +25,28 @@ one of the instances, that instance will be used. Otherwise, if more than one instance is installed we do not define which one is chosen by default. +Platform Selection +^^^^^^^^^^^^^^^^^^ + +The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps +via the :manual:`cmake(1)` ``-A`` option, to specify a target platform +name (architecture). For example: + +* ``cmake -G "Visual Studio 15 2017" -A Win32`` +* ``cmake -G "Visual Studio 15 2017" -A x64`` +* ``cmake -G "Visual Studio 15 2017" -A ARM`` +* ``cmake -G "Visual Studio 15 2017" -A ARM64`` + +For compatibility with CMake versions prior to 3.1, one may specify +a target platform name optionally at the end of the generator name. +This is supported only for: + +``Visual Studio 15 2017 Win64`` + Specify target platform ``x64``. + +``Visual Studio 15 2017 ARM`` + Specify target platform ``ARM``. + Toolset Selection ^^^^^^^^^^^^^^^^^ diff --git a/Help/generator/Visual Studio 9 2008.rst b/Help/generator/Visual Studio 9 2008.rst index 40471b92e..a29033f01 100644 --- a/Help/generator/Visual Studio 9 2008.rst +++ b/Help/generator/Visual Studio 9 2008.rst @@ -3,11 +3,22 @@ Visual Studio 9 2008 Generates Visual Studio 9 2008 project files. -The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set -to specify a target platform name. +Platform Selection +^^^^^^^^^^^^^^^^^^ + +The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps +via the :manual:`cmake(1)` ``-A`` option, to specify a target platform +name (architecture). For example: + +* ``cmake -G "Visual Studio 9 2008" -A Win32`` +* ``cmake -G "Visual Studio 9 2008" -A x64`` +* ``cmake -G "Visual Studio 9 2008" -A Itanium`` +* ``cmake -G "Visual Studio 9 2008" -A <WinCE-SDK>`` + (Specify a target platform matching a Windows CE SDK name.) For compatibility with CMake versions prior to 3.1, one may specify -a target platform name optionally at the end of this generator name: +a target platform name optionally at the end of the generator name. +This is supported only for: ``Visual Studio 9 2008 Win64`` Specify target platform ``x64``. diff --git a/Help/index.rst b/Help/index.rst index fa5273c0c..fe1b73c26 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/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt index 33d27af52..baa73d5e1 100644 --- a/Help/manual/OPTIONS_BUILD.txt +++ b/Help/manual/OPTIONS_BUILD.txt @@ -1,3 +1,11 @@ +``-S <path-to-source>`` + Path to root directory of the CMake project to build. + +``-B <path-to-build>`` + Path to directory which CMake will use as the root of build directory. + + If the directory doesn't already exist CMake will make it. + ``-C <initial-cache>`` Pre-load a script to populate the cache. diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 49375e903..4fc484b2d 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -95,7 +95,7 @@ Apple Frameworks """""""""""""""" A ``SHARED`` library may be marked with the :prop_tgt:`FRAMEWORK` -target property to create an OS X or iOS Framework Bundle. +target property to create an macOS or iOS Framework Bundle. The ``MACOSX_FRAMEWORK_IDENTIFIER`` sets ``CFBundleIdentifier`` key and it uniquely identifies the bundle. @@ -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 408a3a0b7..0cc5fca83 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 @@ -110,7 +111,9 @@ These commands are available only in CMake projects. /command/target_compile_features /command/target_compile_options /command/target_include_directories + /command/target_link_directories /command/target_link_libraries + /command/target_link_options /command/target_sources /command/try_compile /command/try_run diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index 32e8cfc2c..f05c4b129 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -579,11 +579,11 @@ file and the ``Help/manual/cmake-modules.7.rst`` toctree entry. Find Modules ------------ -A "find module" is a ``Modules/Find<package>.cmake`` file to be loaded -by the :command:`find_package` command when invoked for ``<package>``. +A "find module" is a ``Modules/Find<PackageName>.cmake`` file to be loaded +by the :command:`find_package` command when invoked for ``<PackageName>``. The primary task of a find module is to determine whether a package -exists on the system, set the ``<package>_FOUND`` variable to reflect +exists on the system, set the ``<PackageName>_FOUND`` variable to reflect this and provide any variables, macros and imported targets required to use the package. A find module is useful in cases where an upstream library does not provide a diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index 42aeabc89..31aa723fe 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -53,5 +53,6 @@ Environment Variables for CTest /envvar/CTEST_INTERACTIVE_DEBUG_MODE /envvar/CTEST_OUTPUT_ON_FAILURE /envvar/CTEST_PARALLEL_LEVEL + /envvar/CTEST_PROGRESS_OUTPUT /envvar/CTEST_USE_LAUNCHERS_DEFAULT /envvar/DASHBOARD_TEST_FROM_CTEST diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 8fd07d776..76fd3d9ed 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -51,7 +51,7 @@ Available logical expressions are: ``0`` if all ``?`` are ``0``, else ``1`` ``$<NOT:?>`` ``0`` if ``?`` is ``1``, else ``1`` -``$<IF:?,true-value...,false-value...>``` +``$<IF:?,true-value...,false-value...>`` ``true-value...`` if ``?`` is ``1``, ``false-value...`` if ``?`` is ``0`` ``$<STREQUAL:a,b>`` ``1`` if ``a`` is STREQUAL ``b``, else ``0`` @@ -68,10 +68,13 @@ Available logical expressions are: target. ``$<PLATFORM_ID:comp>`` ``1`` if the CMake-id of the platform matches ``comp``, otherwise ``0``. + See also the :variable:`CMAKE_SYSTEM_NAME` variable. ``$<C_COMPILER_ID:comp>`` ``1`` if the CMake-id of the C compiler matches ``comp``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. ``$<CXX_COMPILER_ID:comp>`` ``1`` if the CMake-id of the CXX compiler matches ``comp``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. ``$<VERSION_LESS:v1,v2>`` ``1`` if ``v1`` is a version less than ``v2``, else ``0``. ``$<VERSION_GREATER:v1,v2>`` @@ -84,8 +87,10 @@ Available logical expressions are: ``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``. ``$<C_COMPILER_VERSION:ver>`` ``1`` if the version of the C compiler matches ``ver``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. ``$<CXX_COMPILER_VERSION:ver>`` ``1`` if the version of the CXX compiler matches ``ver``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. ``$<TARGET_POLICY:pol>`` ``1`` if the policy ``pol`` was NEW when the 'head' target was created, else ``0``. If the policy was not set, the warning message for the policy diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index 87f8f9dec..71649ba3e 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst @@ -391,14 +391,20 @@ inside out, e.g. ``${outer_${inner_variable}_variable}``. Literal variable references may consist of alphanumeric characters, the characters ``/_.+-``, and `Escape Sequences`_. Nested references -may be used to evaluate variables of any name. (See also policy -:policy:`CMP0053` documentation for historical considerations.) +may be used to evaluate variables of any name. See also policy +:policy:`CMP0053` documentation for historical considerations and reasons why +the ``$`` is also technically permitted but is discouraged. The `Variables`_ section documents the scope of variable names and how their values are set. An *environment variable reference* has the form ``$ENV{VAR}`` and is evaluated in the same contexts as a normal variable reference. +See :variable:`ENV` for more information. + +A *cache variable reference* has the form ``$CACHE{VAR}`` and +is evaluated in the same contexts as a normal variable reference. +See :variable:`CACHE` for more information. Comments -------- @@ -543,6 +549,8 @@ to the binding in the current directory scope, if any. If a is found, or no binding is found, CMake then searches for a cache entry. If a cache entry is found, its value is used. Otherwise, the variable reference evaluates to an empty string. +The ``$CACHE{VAR}`` syntax can be used to do direct cache entry +lookups. The :manual:`cmake-variables(7)` manual documents many variables that are provided by CMake or have meaning to CMake when set diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 8ef4d7dfd..b7276b657 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-packages.7.rst b/Help/manual/cmake-packages.7.rst index c9442bc19..876ca84d9 100644 --- a/Help/manual/cmake-packages.7.rst +++ b/Help/manual/cmake-packages.7.rst @@ -73,7 +73,7 @@ Handling of ``COMPONENTS`` and ``OPTIONAL_COMPONENTS`` is defined by the package. By setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to -``TRUE``, the ``PackageName`` package will not be searched, and will always +``TRUE``, the ``<PackageName>`` package will not be searched, and will always be ``NOTFOUND``. .. _`Config File Packages`: @@ -92,9 +92,9 @@ packages, that is, they belong with the header files and any other files provided to assist downstreams in using the package. A set of variables which provide package status information are also set -automatically when using a config-file package. The ``<Package>_FOUND`` +automatically when using a config-file package. The ``<PackageName>_FOUND`` variable is set to true or false, depending on whether the package was -found. The ``<Package>_DIR`` cache variable is set to the location of the +found. The ``<PackageName>_DIR`` cache variable is set to the location of the package configuration file. Find-module Packages @@ -108,10 +108,10 @@ file, it is not shipped with upstream, but is used by downstream to find the files by guessing locations of files with platform-specific hints. Unlike the case of an upstream-provided package configuration file, no single point -of reference identifies the package as being found, so the ``<Package>_FOUND`` +of reference identifies the package as being found, so the ``<PackageName>_FOUND`` variable is not automatically set by the :command:`find_package` command. It can still be expected to be set by convention however and should be set by -the author of the Find-module. Similarly there is no ``<Package>_DIR`` variable, +the author of the Find-module. Similarly there is no ``<PackageName>_DIR`` variable, but each of the artifacts such as library locations and header file locations provide a separate cache variable. @@ -197,7 +197,7 @@ When the :command:`find_package` command loads a version file it first sets the following variables: ``PACKAGE_FIND_NAME`` - The <package> name + The ``<PackageName>`` ``PACKAGE_FIND_VERSION`` Full requested version string @@ -240,26 +240,26 @@ variables. When the version file claims to be an acceptable match for the requested version the find_package command sets the following variables for use by the project: -``<package>_VERSION`` +``<PackageName>_VERSION`` Full provided version string -``<package>_VERSION_MAJOR`` +``<PackageName>_VERSION_MAJOR`` Major version if provided, else 0 -``<package>_VERSION_MINOR`` +``<PackageName>_VERSION_MINOR`` Minor version if provided, else 0 -``<package>_VERSION_PATCH`` +``<PackageName>_VERSION_PATCH`` Patch version if provided, else 0 -``<package>_VERSION_TWEAK`` +``<PackageName>_VERSION_TWEAK`` Tweak version if provided, else 0 -``<package>_VERSION_COUNT`` +``<PackageName>_VERSION_COUNT`` Number of version components, 0 to 4 The variables report the version of the package that was actually found. -The ``<package>`` part of their name matches the argument given to the +The ``<PackageName>`` part of their name matches the argument given to the :command:`find_package` command. .. _`Creating Packages`: @@ -347,8 +347,8 @@ The :module:`CMakePackageConfigHelpers` module provides a macro for creating a simple ``ConfigVersion.cmake`` file. This file sets the version of the package. It is read by CMake when :command:`find_package` is called to determine the compatibility with the requested version, and to set some -version-specific variables ``<Package>_VERSION``, ``<Package>_VERSION_MAJOR``, -``<Package>_VERSION_MINOR`` etc. The :command:`install(EXPORT)` command is +version-specific variables ``<PackageName>_VERSION``, ``<PackageName>_VERSION_MAJOR``, +``<PackageName>_VERSION_MINOR`` etc. The :command:`install(EXPORT)` command is used to export the targets in the ``ClimbingStatsTargets`` export-set, defined previously by the :command:`install(TARGETS)` command. This command generates the ``ClimbingStatsTargets.cmake`` file to contain :prop_tgt:`IMPORTED` @@ -432,8 +432,8 @@ the dependency is not found, along with a diagnostic that the ``ClimbingStats`` package can not be used without the ``Stats`` package. If ``COMPONENTS`` are specified when the downstream uses :command:`find_package`, -they are listed in the ``<Package>_FIND_COMPONENTS`` variable. If a particular -component is non-optional, then the ``<Package>_FIND_REQUIRED_<comp>`` will +they are listed in the ``<PackageName>_FIND_COMPONENTS`` variable. If a particular +component is non-optional, then the ``<PackageName>_FIND_REQUIRED_<comp>`` will be true. This can be tested with logic in the package configuration file: .. code-block:: cmake @@ -580,8 +580,8 @@ non-standard install locations or directly in their own build trees. A project may populate either the user or system registry (using its own means, see below) to refer to its location. In either case the package should store at the registered location a -`Package Configuration File`_ (``<package>Config.cmake``) and optionally a -`Package Version File`_ (``<package>ConfigVersion.cmake``). +`Package Configuration File`_ (``<PackageName>Config.cmake``) and optionally a +`Package Version File`_ (``<PackageName>ConfigVersion.cmake``). The :command:`find_package` command searches the two package registries as two of the search steps specified in its documentation. If it has @@ -603,18 +603,18 @@ must be manually taught to register their packages if desired. On Windows the user package registry is stored in the Windows registry under a key in ``HKEY_CURRENT_USER``. -A ``<package>`` may appear under registry key:: +A ``<PackageName>`` may appear under registry key:: - HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\<package> + HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\<PackageName> as a ``REG_SZ`` value, with arbitrary name, that specifies the directory containing the package configuration file. On UNIX platforms the user package registry is stored in the user home -directory under ``~/.cmake/packages``. A ``<package>`` may appear under +directory under ``~/.cmake/packages``. A ``<PackageName>`` may appear under the directory:: - ~/.cmake/packages/<package> + ~/.cmake/packages/<PackageName> as a file, with arbitrary name, whose content specifies the directory containing the package configuration file. @@ -629,10 +629,10 @@ CMake currently provides no interface to add to the system package registry. Installers must be manually taught to register their packages if desired. On Windows the system package registry is stored in the Windows registry -under a key in ``HKEY_LOCAL_MACHINE``. A ``<package>`` may appear under +under a key in ``HKEY_LOCAL_MACHINE``. A ``<PackageName>`` may appear under registry key:: - HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<package> + HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<PackageName> as a ``REG_SZ`` value, with arbitrary name, that specifies the directory containing the package configuration file. diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 631f75b6b..2cc52fe1a 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,19 @@ 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 + + CMP0081: Relative paths not allowed in LINK_DIRECTORIES target property. </policy/CMP0081> + CMP0080: BundleUtilities cannot be included at configure time. </policy/CMP0080> + CMP0079: target_link_libraries allows use with targets in other directories. </policy/CMP0079> + 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 9f9c53f08..5c3eb81fc 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,10 @@ 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_DIRECTORIES /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 @@ -247,6 +253,7 @@ Properties on Targets /prop_tgt/LINK_DEPENDS_NO_SHARED /prop_tgt/LINK_DEPENDS /prop_tgt/LINKER_LANGUAGE + /prop_tgt/LINK_DIRECTORIES /prop_tgt/LINK_FLAGS_CONFIG /prop_tgt/LINK_FLAGS /prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG @@ -254,6 +261,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 @@ -295,13 +303,16 @@ Properties on Targets /prop_tgt/SOVERSION /prop_tgt/STATIC_LIBRARY_FLAGS_CONFIG /prop_tgt/STATIC_LIBRARY_FLAGS + /prop_tgt/STATIC_LIBRARY_OPTIONS /prop_tgt/SUFFIX /prop_tgt/TYPE /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 @@ -331,6 +342,24 @@ Properties on Targets /prop_tgt/XCODE_ATTRIBUTE_an-attribute /prop_tgt/XCODE_EXPLICIT_FILE_TYPE /prop_tgt/XCODE_PRODUCT_TYPE + /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER + /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN + /prop_tgt/XCODE_SCHEME_THREAD_SANITIZER + /prop_tgt/XCODE_SCHEME_THREAD_SANITIZER_STOP + /prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER + /prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP + /prop_tgt/XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER + /prop_tgt/XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP + /prop_tgt/XCODE_SCHEME_MALLOC_SCRIBBLE + /prop_tgt/XCODE_SCHEME_MALLOC_GUARD_EDGES + /prop_tgt/XCODE_SCHEME_GUARD_MALLOC + /prop_tgt/XCODE_SCHEME_ZOMBIE_OBJECTS + /prop_tgt/XCODE_SCHEME_MALLOC_STACK + /prop_tgt/XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE + /prop_tgt/XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS + /prop_tgt/XCODE_SCHEME_EXECUTABLE + /prop_tgt/XCODE_SCHEME_ARGUMENTS + /prop_tgt/XCODE_SCHEME_ENVIRONMENT /prop_tgt/XCTEST .. _`Test Properties`: diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index f6bf0bd92..9dd36ede4 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -24,6 +24,7 @@ Variables that Provide Information /variable/CMAKE_CACHE_PATCH_VERSION /variable/CMAKE_CFG_INTDIR /variable/CMAKE_COMMAND + /variable/CMAKE_CPACK_COMMAND /variable/CMAKE_CROSSCOMPILING /variable/CMAKE_CROSSCOMPILING_EMULATOR /variable/CMAKE_CTEST_COMMAND @@ -77,6 +78,7 @@ Variables that Provide Information /variable/CMAKE_PROJECT_VERSION_TWEAK /variable/CMAKE_RANLIB /variable/CMAKE_ROOT + /variable/CMAKE_RULE_MESSAGES /variable/CMAKE_SCRIPT_MODE_FILE /variable/CMAKE_SHARED_LIBRARY_PREFIX /variable/CMAKE_SHARED_LIBRARY_SUFFIX @@ -177,6 +179,7 @@ Variables that Change Behavior /variable/CMAKE_INSTALL_PREFIX /variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT /variable/CMAKE_LIBRARY_PATH + /variable/CMAKE_LINK_DIRECTORIES_BEFORE /variable/CMAKE_MFC_FLAG /variable/CMAKE_MODULE_PATH /variable/CMAKE_NOT_USING_CONFIG_FLAGS @@ -204,6 +207,21 @@ Variables that Change Behavior /variable/CMAKE_WARN_DEPRECATED /variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION /variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY + /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER + /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN + /variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER + /variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP + /variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER + /variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP + /variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER + /variable/CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP + /variable/CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE + /variable/CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES + /variable/CMAKE_XCODE_SCHEME_GUARD_MALLOC + /variable/CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS + /variable/CMAKE_XCODE_SCHEME_MALLOC_STACK + /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE + /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS /variable/PackageName_ROOT Variables that Describe the System @@ -215,6 +233,7 @@ Variables that Describe the System /variable/ANDROID /variable/APPLE /variable/BORLAND + /variable/CACHE /variable/CMAKE_CL_64 /variable/CMAKE_COMPILER_2005 /variable/CMAKE_HOST_APPLE @@ -291,6 +310,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 @@ -375,6 +395,7 @@ Variables that Control the Build /variable/CMAKE_TRY_COMPILE_TARGET_TYPE /variable/CMAKE_USE_RELATIVE_PATHS /variable/CMAKE_VISIBILITY_INLINES_HIDDEN + /variable/CMAKE_VS_GLOBALS /variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD /variable/CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD /variable/CMAKE_VS_SDK_EXCLUDE_DIRECTORIES @@ -384,6 +405,7 @@ Variables that Control the Build /variable/CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES /variable/CMAKE_VS_SDK_REFERENCE_DIRECTORIES /variable/CMAKE_VS_SDK_SOURCE_DIRECTORIES + /variable/CMAKE_VS_WINRT_BY_DEFAULT /variable/CMAKE_WIN32_EXECUTABLE /variable/CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS /variable/CMAKE_XCODE_ATTRIBUTE_an-attribute @@ -461,6 +483,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/cmake.1.rst b/Help/manual/cmake.1.rst index 177acd4cc..b11526c43 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -9,6 +9,7 @@ Synopsis .. parsed-literal:: cmake [<options>] {<path-to-source> | <path-to-existing-build>} + cmake [<options>] -S <path-to-source> -B <path-to-build> cmake [{-D <var>=<value>}...] -P <cmake-script-file> cmake --build <dir> [<options>...] [-- <build-tool-options>...] cmake --open <dir> @@ -353,11 +354,6 @@ Available commands are: Touch a file if it exists but do not create it. If a file does not exist it will be silently ignored. -UNIX-specific Command-Line Tools --------------------------------- - -The following ``cmake -E`` commands are available only on UNIX: - ``create_symlink <old> <new>`` Create a symbolic link ``<new>`` naming ``<old>``. diff --git a/Help/manual/cpack-generators.7.rst b/Help/manual/cpack-generators.7.rst new file mode 100644 index 000000000..ade9149c1 --- /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/manual/cpack.1.rst b/Help/manual/cpack.1.rst index 87aa38d85..6159d7bee 100644 --- a/Help/manual/cpack.1.rst +++ b/Help/manual/cpack.1.rst @@ -29,9 +29,10 @@ Options package(s) in that generator's format according to the details provided in the ``CPackConfig.cmake`` configuration file. A generator is responsible for generating the required inputs for a particular package system and invoking - that system's package creation tools. Possible generator names are specified - in the :manual:`Generators <cmake-generators(7)>` section of the manual and + that system's package creation tools. All supported generators are specified + in the :manual:`Generators <cpack-generators(7)>` section of the manual and the ``--help`` option lists the generators supported for the target platform. + If this option is not given, the :variable:`CPACK_GENERATOR` variable determines the default set of generators that will be used. diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 9553d159a..e24b10daf 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -35,6 +35,19 @@ Options which one should be tested. Example configurations are "Debug" and "Release". +``--progress`` + Enable short progress output from tests. + + When the output of ``ctest`` is being sent directly to a terminal, the + progress through the set of tests is reported by updating the same line + rather than printing start and end messages for each test on new lines. + This can significantly reduce the verbosity of the test output. + Test completion messages are still output on their own line for failed + tests and the final test summary will also still be logged. + + This option can also be enabled by setting the environment variable + :envvar:`CTEST_PROGRESS_OUTPUT`. + ``-V,--verbose`` Enable verbose output from tests. @@ -55,8 +68,8 @@ Options ``--output-on-failure`` Output anything outputted by the test program if the test should fail. - This option can also be enabled by setting the environment variable - ``CTEST_OUTPUT_ON_FAILURE``. + This option can also be enabled by setting the + :envvar:`CTEST_OUTPUT_ON_FAILURE` environment variable ``-F`` Enable failover. @@ -70,7 +83,7 @@ Options This option tells CTest to run the tests in parallel using given number of jobs. This option can also be set by setting the - environment variable ``CTEST_PARALLEL_LEVEL``. + :envvar:`CTEST_PARALLEL_LEVEL` environment variable. This option can be used with the :prop_test:`PROCESSORS` test property. @@ -867,7 +880,7 @@ Configuration settings include: * `CTest Script`_ variable: :variable:`CTEST_CONFIGURATION_TYPE` * :module:`CTest` module variable: ``DEFAULT_CTEST_CONFIGURATION_TYPE``, - initialized by the ``CMAKE_CONFIG_TYPE`` environment variable + initialized by the :envvar:`CMAKE_CONFIG_TYPE` environment variable ``LabelsForSubprojects`` Specify a semicolon-separated list of labels that will be treated as diff --git a/Help/module/CPackArchive.rst b/Help/module/CPackArchive.rst index eb8d9d244..8616098cb 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 651e87426..513488427 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 21f447348..719dfceb1 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 784262c5e..e59dcbb7a 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 DragNDrop generator has moved here: :cpack_gen:`CPack DragNDrop Generator` diff --git a/Help/module/CPackDeb.rst b/Help/module/CPackDeb.rst index d1526ee49..cd7e5f305 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 083f0cbfa..69701b8e9 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 bb35ed60a..2cb407a97 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 a4cbb595f..4f39b3a7e 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 de5544869..226b6fd8e 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 6081fe48a..8cd9198b4 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 28d0e6912..00b7e0ad7 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 1f5e451e9..c88c7232c 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/CMP0053.rst b/Help/policy/CMP0053.rst index 2620a60e0..032b3e5c6 100644 --- a/Help/policy/CMP0053.rst +++ b/Help/policy/CMP0053.rst @@ -16,6 +16,10 @@ cleaned up to simplify the behavior. Specifically: * Literal ``${VAR}`` reference syntax may contain only alphanumeric characters (``A-Z``, ``a-z``, ``0-9``) and the characters ``_``, ``.``, ``/``, ``-``, and ``+``. + Note that ``$`` is technically allowed in the ``NEW`` behavior, but is + invalid for ``OLD`` behavior. This is due to an oversight during the + implementation of :policy:`CMP0053` and its use as a literal variable + reference is discouraged for this reason. Variables with other characters in their name may still be referenced indirectly, e.g. diff --git a/Help/policy/CMP0076.rst b/Help/policy/CMP0076.rst new file mode 100644 index 000000000..dd25f80c6 --- /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 000000000..44797b648 --- /dev/null +++ b/Help/policy/CMP0077.rst @@ -0,0 +1,52 @@ +CMP0077 +------- + +:command:`option` honors normal variables. + +The :command:`option` command is typically used to create a cache entry +to allow users to set the option. However, there are cases in which a +normal (non-cached) variable of the same name as the option may be +defined by the project prior to calling the :command:`option` command. +For example, a project that embeds another project as a subdirectory +may want to hard-code options of the subproject to build the way it needs. + +For historical reasons in CMake 3.12 and below the :command:`option` +command *removes* a normal (non-cached) variable of the same name when: + +* a cache entry of the specified name does not exist at all, or +* a cache entry of the specified name exists but has not been given + a type (e.g. via ``-D<name>=ON`` on the command line). + +In both of these cases (typically on the first run in a new build tree), +the :command:`option` command gives the cache entry type ``BOOL`` and +removes any normal (non-cached) variable of the same name. In the +remaining case that the cache entry of the specified name already +exists and has a type (typically on later runs in a build tree), the +:command:`option` command changes nothing and any normal variable of +the same name remains set. + +In CMake 3.13 and above the :command:`option` command prefers to +do nothing when a normal variable of the given name already exists. +It does not create or update a cache entry or remove the normal variable. +The new behavior is consistent between the first and later runs in a +build tree. This policy provides compatibility with projects that have +not been updated to expect the new behavior. + +When the :command:`option` command sees a normal variable of the given +name: + +* The ``OLD`` behavior for this policy is to proceed even when a normal + variable of the same name exists. If the cache entry does not already + exist and have a type then it is created and/or given a type and the + normal variable is removed. + +* The ``NEW`` behavior for this policy is to do nothing when a normal + variable of the same name exists. The normal variable is not removed. + The cache entry is not created or updated and is ignored if it 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 000000000..54cdc9cc7 --- /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/policy/CMP0079.rst b/Help/policy/CMP0079.rst new file mode 100644 index 000000000..0244d6ca6 --- /dev/null +++ b/Help/policy/CMP0079.rst @@ -0,0 +1,40 @@ +CMP0079 +------- + +:command:`target_link_libraries` allows use with targets in other directories. + +Prior to CMake 3.13 the :command:`target_link_libraries` command did not +accept targets not created in the calling directory as its first argument +for calls that update the :prop_tgt:`LINK_LIBRARIES` of the target itself. +It did accidentally accept targets from other directories on calls that +only update the :prop_tgt:`INTERFACE_LINK_LIBRARIES`, but would simply +add entries to the property as if the call were made in the original +directory. Thus link interface libraries specified this way were always +looked up by generators in the scope of the original target rather than +in the scope that called :command:`target_link_libraries`. + +CMake 3.13 now allows the :command:`target_link_libraries` command to +be called from any directory to add link dependencies and link interface +libraries to targets created in other directories. The entries are added +to :prop_tgt:`LINK_LIBRARIES` and :prop_tgt:`INTERFACE_LINK_LIBRARIES` +using a special (internal) suffix to tell the generators to look up the +names in the calling scope rather than the scope that created the target. + +This policy provides compatibility with projects that already use +:command:`target_link_libraries` with the ``INTERFACE`` keyword +on a target in another directory to add :prop_tgt:`INTERFACE_LINK_LIBRARIES` +entries to be looked up in the target's directory. Such projects should +be updated to be aware of the new scoping rules in that case. + +The ``OLD`` behavior of this policy is to disallow +:command:`target_link_libraries` calls naming targets from another directory +except in the previously accidentally allowed case of using the ``INTERFACE`` +keyword only. The ``NEW`` behavior of this policy is to allow all such +calls but use the new scoping 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/CMP0080.rst b/Help/policy/CMP0080.rst new file mode 100644 index 000000000..5ce9591da --- /dev/null +++ b/Help/policy/CMP0080.rst @@ -0,0 +1,25 @@ +CMP0080 +------- + +:module:`BundleUtilities` cannot be included at configure time. + +The macros provided by :module:`BundleUtilities` are intended to be invoked +at install time rather than at configure time, because they depend on the +listed targets already existing at the time they are invoked. If they are +invoked at configure time, the targets haven't been built yet, and the +commands will fail. + +This policy restricts the inclusion of :module:`BundleUtilities` to +``cmake -P`` style scripts and install rules. Specifically, it looks for the +presence of :variable:`CMAKE_GENERATOR` and throws a fatal error if it exists. + +The ``OLD`` behavior of this policy is to allow :module:`BundleUtilities` to +be included at configure time. The ``NEW`` behavior of this policy is to +disallow such inclusion. + +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/CMP0081.rst b/Help/policy/CMP0081.rst new file mode 100644 index 000000000..d3b2872c4 --- /dev/null +++ b/Help/policy/CMP0081.rst @@ -0,0 +1,22 @@ +CMP0081 +------- + +Relative paths not allowed in :prop_tgt:`LINK_DIRECTORIES` target property. + +CMake 3.12 and lower allowed the :prop_dir:`LINK_DIRECTORIES` directory +property to contain relative paths. The base path for such relative +entries is not well defined. CMake 3.13 and later will issue a +``FATAL_ERROR`` if the :prop_tgt:`LINK_DIRECTORIES` target property +(which is initialized by the :prop_dir:`LINK_DIRECTORIES` directory property) +contains a relative path. + +The ``OLD`` behavior for this policy is not to warn about relative paths +in the :prop_tgt:`LINK_DIRECTORIES` target property. The ``NEW`` behavior for +this policy is to issue a ``FATAL_ERROR`` if :prop_tgt:`LINK_DIRECTORIES` +contains a relative path. + +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/INCLUDE_DIRECTORIES.rst b/Help/prop_dir/INCLUDE_DIRECTORIES.rst index 6789a5644..5d856b80a 100644 --- a/Help/prop_dir/INCLUDE_DIRECTORIES.rst +++ b/Help/prop_dir/INCLUDE_DIRECTORIES.rst @@ -11,11 +11,17 @@ target property, which is used by the generators to set the include directories for the compiler. In addition to accepting values from that command, values may be set -directly on any directory using the :command:`set_property` command. A -directory gets its initial value from its parent directory if it has one. -The initial value of the :prop_tgt:`INCLUDE_DIRECTORIES` target property +directly on any directory using the :command:`set_property` command, and can be +set on the current directory using the :command:`set_directory_properties` +command. A directory gets its initial value from its parent directory if it has +one. The initial value of the :prop_tgt:`INCLUDE_DIRECTORIES` target property comes from the value of this property. Both directory and target property values are adjusted by calls to the :command:`include_directories` command. +Calls to :command:`set_property` or :command:`set_directory_properties`, +however, will update the directory property value without updating target +property values. Therefore direct property updates must be made before +calls to :command:`add_executable` or :command:`add_library` for targets +they are meant to affect. The target property values are used by the generators to set the include paths for the compiler. diff --git a/Help/prop_dir/LINK_DIRECTORIES.rst b/Help/prop_dir/LINK_DIRECTORIES.rst index fa375766d..f9fb81535 100644 --- a/Help/prop_dir/LINK_DIRECTORIES.rst +++ b/Help/prop_dir/LINK_DIRECTORIES.rst @@ -3,6 +3,15 @@ LINK_DIRECTORIES List of linker search directories. -This read-only property specifies the list of directories given so far -to the link_directories command. It is intended for debugging -purposes. +This property holds a :ref:`;-list <CMake Language Lists>` of directories +and is typically populated using the :command:`link_directories` command. +It gets its initial value from its parent directory, if it has one. + +The directory property is used to initialize the :prop_tgt:`LINK_DIRECTORIES` +target property when a target is created. That target property is used +by the generators to set the library search directories for the linker. + +Contents of ``LINK_DIRECTORIES`` 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_dir/LINK_OPTIONS.rst b/Help/prop_dir/LINK_OPTIONS.rst new file mode 100644 index 000000000..15c555fda --- /dev/null +++ b/Help/prop_dir/LINK_OPTIONS.rst @@ -0,0 +1,17 @@ +LINK_OPTIONS +------------ + +List of options to use for the link step of shared library, module +and executable targets. + +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_gbl/RULE_MESSAGES.rst b/Help/prop_gbl/RULE_MESSAGES.rst index 87a5ca613..a9734a730 100644 --- a/Help/prop_gbl/RULE_MESSAGES.rst +++ b/Help/prop_gbl/RULE_MESSAGES.rst @@ -8,6 +8,6 @@ progress message describing what each build rule does. If the property is not set the default is ON. Set the property to OFF to disable granular messages and report only as each target completes. This is intended to allow scripted builds to avoid the build time cost -of detailed reports. If a ``CMAKE_RULE_MESSAGES`` cache entry exists +of detailed reports. If a :variable:`CMAKE_RULE_MESSAGES` cache entry exists its value initializes the value of this property. Non-Makefile generators currently ignore this property. diff --git a/Help/prop_sf/MACOSX_PACKAGE_LOCATION.rst b/Help/prop_sf/MACOSX_PACKAGE_LOCATION.rst index a064afa63..d185d9197 100644 --- a/Help/prop_sf/MACOSX_PACKAGE_LOCATION.rst +++ b/Help/prop_sf/MACOSX_PACKAGE_LOCATION.rst @@ -3,19 +3,19 @@ MACOSX_PACKAGE_LOCATION Place a source file inside a Application Bundle (:prop_tgt:`MACOSX_BUNDLE`), Core Foundation Bundle (:prop_tgt:`BUNDLE`), -or Framework Bundle (:prop_tgt:`FRAMEWORK`). It is applicable for OS X +or Framework Bundle (:prop_tgt:`FRAMEWORK`). It is applicable for macOS and iOS. Executable targets with the :prop_tgt:`MACOSX_BUNDLE` property set are -built as OS X or iOS application bundles on Apple platforms. Shared +built as macOS or iOS application bundles on Apple platforms. Shared library targets with the :prop_tgt:`FRAMEWORK` property set are built as -OS X or iOS frameworks on Apple platforms. Module library targets with -the :prop_tgt:`BUNDLE` property set are built as OS X ``CFBundle`` bundles +macOS or iOS frameworks on Apple platforms. Module library targets with +the :prop_tgt:`BUNDLE` property set are built as macOS ``CFBundle`` bundles on Apple platforms. Source files listed in the target with this property set will be copied to a directory inside the bundle or framework content -folder specified by the property value. For OS X Application Bundles the -content folder is ``<name>.app/Contents``. For OS X Frameworks the -content folder is ``<name>.framework/Versions/<version>``. For OS X +folder specified by the property value. For macOS Application Bundles the +content folder is ``<name>.app/Contents``. For macOS Frameworks the +content folder is ``<name>.framework/Versions/<version>``. For macOS CFBundles the content folder is ``<name>.bundle/Contents`` (unless the extension is changed). See the :prop_tgt:`PUBLIC_HEADER`, :prop_tgt:`PRIVATE_HEADER`, and :prop_tgt:`RESOURCE` target properties for diff --git a/Help/prop_tgt/BUNDLE.rst b/Help/prop_tgt/BUNDLE.rst index 075f017df..c556ac32c 100644 --- a/Help/prop_tgt/BUNDLE.rst +++ b/Help/prop_tgt/BUNDLE.rst @@ -1,7 +1,7 @@ BUNDLE ------ -This target is a ``CFBundle`` on the OS X. +This target is a ``CFBundle`` on the macOS. If a module library target has this property set to true it will be built as a ``CFBundle`` when built on the mac. It will have the directory diff --git a/Help/prop_tgt/BUNDLE_EXTENSION.rst b/Help/prop_tgt/BUNDLE_EXTENSION.rst index 6b3d58023..70de11c40 100644 --- a/Help/prop_tgt/BUNDLE_EXTENSION.rst +++ b/Help/prop_tgt/BUNDLE_EXTENSION.rst @@ -2,7 +2,7 @@ BUNDLE_EXTENSION ---------------- The file extension used to name a :prop_tgt:`BUNDLE`, a :prop_tgt:`FRAMEWORK`, -or a :prop_tgt:`MACOSX_BUNDLE` target on the OS X and iOS. +or a :prop_tgt:`MACOSX_BUNDLE` target on the macOS and iOS. The default value is ``bundle``, ``framework``, or ``app`` for the respective target types. diff --git a/Help/prop_tgt/DEPLOYMENT_ADDITIONAL_FILES.rst b/Help/prop_tgt/DEPLOYMENT_ADDITIONAL_FILES.rst new file mode 100644 index 000000000..5e9c19158 --- /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/ENABLE_EXPORTS.rst b/Help/prop_tgt/ENABLE_EXPORTS.rst index 9e2230971..581c2b90c 100644 --- a/Help/prop_tgt/ENABLE_EXPORTS.rst +++ b/Help/prop_tgt/ENABLE_EXPORTS.rst @@ -12,7 +12,7 @@ dependency on the executable is created for targets that link to it. For DLL platforms an import library will be created for the exported symbols and then used for linking. All Windows-based systems including Cygwin are DLL platforms. For non-DLL platforms that -require all symbols to be resolved at link time, such as OS X, the +require all symbols to be resolved at link time, such as macOS, the module will "link" to the executable using a flag like ``-bundle_loader``. For other non-DLL platforms the link rule is simply ignored since the dynamic loader will automatically bind symbols when diff --git a/Help/prop_tgt/FRAMEWORK.rst b/Help/prop_tgt/FRAMEWORK.rst index 495d30e95..9dad06052 100644 --- a/Help/prop_tgt/FRAMEWORK.rst +++ b/Help/prop_tgt/FRAMEWORK.rst @@ -1,17 +1,17 @@ FRAMEWORK --------- -Build ``SHARED`` or ``STATIC`` library as Framework Bundle on the OS X and iOS. +Build ``SHARED`` or ``STATIC`` library as Framework Bundle on the macOS and iOS. If such a library target has this property set to ``TRUE`` it will be -built as a framework when built on the OS X and iOS. It will have the +built as a framework when built on the macOS and iOS. It will have the directory structure required for a framework and will be suitable to be used with the ``-framework`` option To customize ``Info.plist`` file in the framework, use :prop_tgt:`MACOSX_FRAMEWORK_INFO_PLIST` target property. -For OS X see also the :prop_tgt:`FRAMEWORK_VERSION` target property. +For macOS see also the :prop_tgt:`FRAMEWORK_VERSION` target property. Example of creation ``dynamicFramework``: diff --git a/Help/prop_tgt/FRAMEWORK_VERSION.rst b/Help/prop_tgt/FRAMEWORK_VERSION.rst index 6aa30268a..c2ae7b98f 100644 --- a/Help/prop_tgt/FRAMEWORK_VERSION.rst +++ b/Help/prop_tgt/FRAMEWORK_VERSION.rst @@ -4,5 +4,5 @@ FRAMEWORK_VERSION Version of a framework created using the :prop_tgt:`FRAMEWORK` target property (e.g. ``A``). -This property only affects OS X, as iOS doesn't have versioned +This property only affects macOS, as iOS doesn't have versioned directory structure. diff --git a/Help/prop_tgt/IMPORTED_LOCATION.rst b/Help/prop_tgt/IMPORTED_LOCATION.rst index 8cfef7343..2d07aadcf 100644 --- a/Help/prop_tgt/IMPORTED_LOCATION.rst +++ b/Help/prop_tgt/IMPORTED_LOCATION.rst @@ -5,11 +5,11 @@ Full path to the main file on disk for an IMPORTED target. Set this to the location of an IMPORTED target file on disk. For executables this is the location of the executable file. For bundles -on OS X this is the location of the executable file inside +on macOS this is the location of the executable file inside Contents/MacOS under the application bundle folder. For static libraries and modules this is the location of the library or module. For shared libraries on non-DLL platforms this is the location of the -shared library. For frameworks on OS X this is the location of the +shared library. For frameworks on macOS this is the location of the library file symlink just inside the framework folder. For DLLs this is the location of the ".dll" part of the library. For UNKNOWN libraries this is the location of the file to be linked. Ignored for diff --git a/Help/prop_tgt/INTERFACE_LINK_DEPENDS.rst b/Help/prop_tgt/INTERFACE_LINK_DEPENDS.rst new file mode 100644 index 000000000..d07f8ea03 --- /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_DIRECTORIES.rst b/Help/prop_tgt/INTERFACE_LINK_DIRECTORIES.rst new file mode 100644 index 000000000..56a4ec0ec --- /dev/null +++ b/Help/prop_tgt/INTERFACE_LINK_DIRECTORIES.rst @@ -0,0 +1,9 @@ +INTERFACE_LINK_DIRECTORIES +-------------------------- + +.. |property_name| replace:: link directories +.. |command_name| replace:: :command:`target_link_directories` +.. |PROPERTY_INTERFACE_NAME| replace:: ``INTERFACE_LINK_DIRECTORIES`` +.. |PROPERTY_LINK| replace:: :prop_tgt:`LINK_DIRECTORIES` +.. |PROPERTY_GENEX| replace:: ``$<TARGET_PROPERTY:foo,INTERFACE_LINK_DIRECTORIES>`` +.. include:: INTERFACE_BUILD_PROPERTY.txt diff --git a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst index 832d12bbc..bf7f72f4c 100644 --- a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst +++ b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst @@ -17,6 +17,8 @@ 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_LIBRARIES_INDIRECTION.txt + Creating Relocatable Packages ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/prop_tgt/INTERFACE_LINK_OPTIONS.rst b/Help/prop_tgt/INTERFACE_LINK_OPTIONS.rst new file mode 100644 index 000000000..c293b986d --- /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 5576b85fa..3ab8658e8 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_DIRECTORIES.rst b/Help/prop_tgt/LINK_DIRECTORIES.rst new file mode 100644 index 000000000..085a70119 --- /dev/null +++ b/Help/prop_tgt/LINK_DIRECTORIES.rst @@ -0,0 +1,18 @@ +LINK_DIRECTORIES +---------------- + +List of directories to use for the link step of shared library, module +and executable targets. + +This property holds a :ref:`;-list <CMake Language Lists>` of directories +specified so far for its target. Use the :command:`target_link_directories` +command to append more search directories. + +This property is initialized by the :prop_dir:`LINK_DIRECTORIES` directory +property when a target is created, and is used by the generators to set +the search directories for the linker. + +Contents of ``LINK_DIRECTORIES`` 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 b09e7c1d6..92cd3c0a5 100644 --- a/Help/prop_tgt/LINK_FLAGS.rst +++ b/Help/prop_tgt/LINK_FLAGS.rst @@ -1,9 +1,16 @@ LINK_FLAGS ---------- -Additional flags to use when linking this target. +Additional flags to use when linking this target if it is a shared library, +module library, or an executable. Static libraries need to use +:prop_tgt:`STATIC_LIBRARY_OPTIONS` or :prop_tgt:`STATIC_LIBRARY_FLAGS` +properties. -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 -configuration ``<CONFIG>``, for example, ``DEBUG``, ``RELEASE``, +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 ba7adc84f..e3918ca44 100644 --- a/Help/prop_tgt/LINK_FLAGS_CONFIG.rst +++ b/Help/prop_tgt/LINK_FLAGS_CONFIG.rst @@ -1,6 +1,11 @@ LINK_FLAGS_<CONFIG> ------------------- -Per-configuration linker flags for a target. +Per-configuration linker flags for a shared library, module or executable +target. -This is the configuration-specific version of LINK_FLAGS. +This is the configuration-specific version of :prop_tgt:`LINK_FLAGS`. + +.. note:: + + This property has been superseded by :prop_tgt:`LINK_OPTIONS` property. diff --git a/Help/prop_tgt/LINK_LIBRARIES.rst b/Help/prop_tgt/LINK_LIBRARIES.rst index aa4b9f55f..d88e79881 100644 --- a/Help/prop_tgt/LINK_LIBRARIES.rst +++ b/Help/prop_tgt/LINK_LIBRARIES.rst @@ -15,3 +15,5 @@ Contents of ``LINK_LIBRARIES`` 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_LIBRARIES_INDIRECTION.txt diff --git a/Help/prop_tgt/LINK_LIBRARIES_INDIRECTION.txt b/Help/prop_tgt/LINK_LIBRARIES_INDIRECTION.txt new file mode 100644 index 000000000..1fdb6ad0e --- /dev/null +++ b/Help/prop_tgt/LINK_LIBRARIES_INDIRECTION.txt @@ -0,0 +1,10 @@ +.. note:: + A call to :command:`target_link_libraries(<target> ...)` may update this + property on ``<target>``. If ``<target>`` was not created in the same + directory as the call then :command:`target_link_libraries` will add a + suffix of the form ``::@<directory-id>`` to each entry, where the + ``::@`` is a separator and the ``<directory-id>`` is unspecified. + This tells the generators that the named libraries must be looked up in + the scope of the caller rather than in the scope in which the + ``<target>`` was created. Valid directory ids are stripped on export + by the :command:`install(EXPORT)` and :command:`export` commands. diff --git a/Help/prop_tgt/LINK_OPTIONS.rst b/Help/prop_tgt/LINK_OPTIONS.rst new file mode 100644 index 000000000..bd5e9370b --- /dev/null +++ b/Help/prop_tgt/LINK_OPTIONS.rst @@ -0,0 +1,24 @@ +LINK_OPTIONS +------------ + +List of options to use for the link step of shared library, module +and executable targets. Targets that are static libraries need to use +the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property. + + +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/MACOSX_BUNDLE.rst b/Help/prop_tgt/MACOSX_BUNDLE.rst index f9e11ee3e..92bce53ee 100644 --- a/Help/prop_tgt/MACOSX_BUNDLE.rst +++ b/Help/prop_tgt/MACOSX_BUNDLE.rst @@ -1,9 +1,9 @@ MACOSX_BUNDLE ------------- -Build an executable as an Application Bundle on OS X or iOS. +Build an executable as an Application Bundle on macOS or iOS. -When this property is set to ``TRUE`` the executable when built on OS X +When this property is set to ``TRUE`` the executable when built on macOS or iOS will be created as an application bundle. This makes it a GUI executable that can be launched from the Finder. See the :prop_tgt:`MACOSX_BUNDLE_INFO_PLIST` target property for information about diff --git a/Help/prop_tgt/MACOSX_BUNDLE_INFO_PLIST.rst b/Help/prop_tgt/MACOSX_BUNDLE_INFO_PLIST.rst index 8515accc2..443a645e4 100644 --- a/Help/prop_tgt/MACOSX_BUNDLE_INFO_PLIST.rst +++ b/Help/prop_tgt/MACOSX_BUNDLE_INFO_PLIST.rst @@ -1,10 +1,10 @@ MACOSX_BUNDLE_INFO_PLIST ------------------------ -Specify a custom ``Info.plist`` template for a OS X and iOS Application Bundle. +Specify a custom ``Info.plist`` template for a macOS and iOS Application Bundle. An executable target with :prop_tgt:`MACOSX_BUNDLE` enabled will be built as an -application bundle on OS X. By default its ``Info.plist`` file is created +application bundle on macOS. By default its ``Info.plist`` file is created by configuring a template called ``MacOSXBundleInfo.plist.in`` located in the :variable:`CMAKE_MODULE_PATH`. This property specifies an alternative template file name which may be a full path. diff --git a/Help/prop_tgt/MACOSX_FRAMEWORK_INFO_PLIST.rst b/Help/prop_tgt/MACOSX_FRAMEWORK_INFO_PLIST.rst index 58f31d495..82fdcc0fb 100644 --- a/Help/prop_tgt/MACOSX_FRAMEWORK_INFO_PLIST.rst +++ b/Help/prop_tgt/MACOSX_FRAMEWORK_INFO_PLIST.rst @@ -1,10 +1,10 @@ MACOSX_FRAMEWORK_INFO_PLIST --------------------------- -Specify a custom ``Info.plist`` template for a OS X and iOS Framework. +Specify a custom ``Info.plist`` template for a macOS and iOS Framework. A library target with :prop_tgt:`FRAMEWORK` enabled will be built as a -framework on OS X. By default its ``Info.plist`` file is created by +framework on macOS. By default its ``Info.plist`` file is created by configuring a template called ``MacOSXFrameworkInfo.plist.in`` located in the :variable:`CMAKE_MODULE_PATH`. This property specifies an alternative template file name which may be a full path. diff --git a/Help/prop_tgt/MACOSX_RPATH.rst b/Help/prop_tgt/MACOSX_RPATH.rst index 1f9a036bf..acd5a7aa4 100644 --- a/Help/prop_tgt/MACOSX_RPATH.rst +++ b/Help/prop_tgt/MACOSX_RPATH.rst @@ -1,7 +1,7 @@ MACOSX_RPATH ------------ -Whether this target on OS X or iOS is located at runtime using rpaths. +Whether this target on macOS or iOS is located at runtime using rpaths. When this property is set to ``TRUE``, the directory portion of the ``install_name`` field of this shared library will be ``@rpath`` diff --git a/Help/prop_tgt/OSX_ARCHITECTURES.rst b/Help/prop_tgt/OSX_ARCHITECTURES.rst index cefe03f5b..996a4be72 100644 --- a/Help/prop_tgt/OSX_ARCHITECTURES.rst +++ b/Help/prop_tgt/OSX_ARCHITECTURES.rst @@ -1,10 +1,10 @@ OSX_ARCHITECTURES ----------------- -Target specific architectures for OS X. +Target specific architectures for macOS. The ``OSX_ARCHITECTURES`` property sets the target binary architecture for -targets on OS X (``-arch``). This property is initialized by the value of the +targets on macOS (``-arch``). This property is initialized by the value of the variable :variable:`CMAKE_OSX_ARCHITECTURES` if it is set when a target is created. Use :prop_tgt:`OSX_ARCHITECTURES_<CONFIG>` to set the binary architectures on a per-configuration basis, where ``<CONFIG>`` is an diff --git a/Help/prop_tgt/OSX_ARCHITECTURES_CONFIG.rst b/Help/prop_tgt/OSX_ARCHITECTURES_CONFIG.rst index fb78177fb..06da4fb09 100644 --- a/Help/prop_tgt/OSX_ARCHITECTURES_CONFIG.rst +++ b/Help/prop_tgt/OSX_ARCHITECTURES_CONFIG.rst @@ -1,7 +1,7 @@ OSX_ARCHITECTURES_<CONFIG> -------------------------- -Per-configuration OS X and iOS binary architectures for a target. +Per-configuration macOS and iOS binary architectures for a target. This property is the configuration-specific version of :prop_tgt:`OSX_ARCHITECTURES`. diff --git a/Help/prop_tgt/PRIVATE_HEADER.rst b/Help/prop_tgt/PRIVATE_HEADER.rst index c4412ed25..2bd4079fa 100644 --- a/Help/prop_tgt/PRIVATE_HEADER.rst +++ b/Help/prop_tgt/PRIVATE_HEADER.rst @@ -4,7 +4,7 @@ PRIVATE_HEADER Specify private header files in a :prop_tgt:`FRAMEWORK` shared library target. Shared library targets marked with the :prop_tgt:`FRAMEWORK` property generate -frameworks on OS X, iOS and normal shared libraries on other platforms. +frameworks on macOS, iOS and normal shared libraries on other platforms. This property may be set to a list of header files to be placed in the PrivateHeaders directory inside the framework folder. On non-Apple platforms these headers may be installed using the ``PRIVATE_HEADER`` diff --git a/Help/prop_tgt/PUBLIC_HEADER.rst b/Help/prop_tgt/PUBLIC_HEADER.rst index d4a636caf..549ac7ce1 100644 --- a/Help/prop_tgt/PUBLIC_HEADER.rst +++ b/Help/prop_tgt/PUBLIC_HEADER.rst @@ -4,7 +4,7 @@ PUBLIC_HEADER Specify public header files in a :prop_tgt:`FRAMEWORK` shared library target. Shared library targets marked with the :prop_tgt:`FRAMEWORK` property generate -frameworks on OS X, iOS and normal shared libraries on other platforms. +frameworks on macOS, iOS and normal shared libraries on other platforms. This property may be set to a list of header files to be placed in the ``Headers`` directory inside the framework folder. On non-Apple platforms these headers may be installed using the ``PUBLIC_HEADER`` option to the diff --git a/Help/prop_tgt/RESOURCE.rst b/Help/prop_tgt/RESOURCE.rst index d837f7b33..55ae7740b 100644 --- a/Help/prop_tgt/RESOURCE.rst +++ b/Help/prop_tgt/RESOURCE.rst @@ -4,10 +4,10 @@ RESOURCE Specify resource files in a :prop_tgt:`FRAMEWORK` or :prop_tgt:`BUNDLE`. Target marked with the :prop_tgt:`FRAMEWORK` or :prop_tgt:`BUNDLE` property -generate framework or application bundle (both OS X and iOS is supported) +generate framework or application bundle (both macOS and iOS is supported) or normal shared libraries on other platforms. This property may be set to a list of files to be placed in the corresponding -directory (eg. ``Resources`` directory for OS X) inside the bundle. +directory (eg. ``Resources`` directory for macOS) inside the bundle. On non-Apple platforms these files may be installed using the ``RESOURCE`` option to the ``install(TARGETS)`` command. @@ -42,7 +42,7 @@ will produce flat structure for iOS systems:: Info.plist resourcefile.txt -For OS X systems it will produce following directory structure:: +For macOS systems it will produce following directory structure:: ExecutableTarget.app/ Contents diff --git a/Help/prop_tgt/SOVERSION.rst b/Help/prop_tgt/SOVERSION.rst index 82b6b976a..b07c17cfe 100644 --- a/Help/prop_tgt/SOVERSION.rst +++ b/Help/prop_tgt/SOVERSION.rst @@ -20,7 +20,7 @@ These numbers are used as the image version of the binary. Mach-O Versions ^^^^^^^^^^^^^^^ -For shared libraries and executables on Mach-O systems (e.g. OS X, iOS), +For shared libraries and executables on Mach-O systems (e.g. macOS, iOS), the ``SOVERSION`` property corresponds to *compatibility version* and :prop_tgt:`VERSION` to *current version*. See the :prop_tgt:`FRAMEWORK` target property for an example. Versions of Mach-O binaries may be checked with the diff --git a/Help/prop_tgt/STATIC_LIBRARY_FLAGS.rst b/Help/prop_tgt/STATIC_LIBRARY_FLAGS.rst index d3b2cd478..66e0e8b96 100644 --- a/Help/prop_tgt/STATIC_LIBRARY_FLAGS.rst +++ b/Help/prop_tgt/STATIC_LIBRARY_FLAGS.rst @@ -1,6 +1,17 @@ STATIC_LIBRARY_FLAGS -------------------- -Extra flags to use when linking static libraries. +Archiver (or MSVC librarian) flags for a static library target. +Targets that are shared libraries, modules, or executables need to use +the :prop_tgt:`LINK_OPTIONS` or :prop_tgt:`LINK_FLAGS` target properties. -Extra flags to use when linking a static library. +The ``STATIC_LIBRARY_FLAGS`` property, managed as a string, can be used to add +extra flags to the link step of a static library target. +:prop_tgt:`STATIC_LIBRARY_FLAGS_<CONFIG>` will add to the configuration +``<CONFIG>``, for example, ``DEBUG``, ``RELEASE``, ``MINSIZEREL``, +``RELWITHDEBINFO``, ... + +.. note:: + + This property has been superseded by :prop_tgt:`STATIC_LIBRARY_OPTIONS` + property. diff --git a/Help/prop_tgt/STATIC_LIBRARY_FLAGS_CONFIG.rst b/Help/prop_tgt/STATIC_LIBRARY_FLAGS_CONFIG.rst index cca353ddc..5b97941da 100644 --- a/Help/prop_tgt/STATIC_LIBRARY_FLAGS_CONFIG.rst +++ b/Help/prop_tgt/STATIC_LIBRARY_FLAGS_CONFIG.rst @@ -1,6 +1,12 @@ STATIC_LIBRARY_FLAGS_<CONFIG> ----------------------------- -Per-configuration flags for creating a static library. +Per-configuration archiver (or MSVC librarian) flags for a static library +target. -This is the configuration-specific version of STATIC_LIBRARY_FLAGS. +This is the configuration-specific version of :prop_tgt:`STATIC_LIBRARY_FLAGS`. + +.. note:: + + This property has been superseded by :prop_tgt:`STATIC_LIBRARY_OPTIONS` + property. diff --git a/Help/prop_tgt/STATIC_LIBRARY_OPTIONS.rst b/Help/prop_tgt/STATIC_LIBRARY_OPTIONS.rst new file mode 100644 index 000000000..6e0318594 --- /dev/null +++ b/Help/prop_tgt/STATIC_LIBRARY_OPTIONS.rst @@ -0,0 +1,20 @@ +STATIC_LIBRARY_OPTIONS +---------------------- + +Archiver (or MSVC librarian) flags for a static library target. +Targets that are shared libraries, modules, or executables need to use +the :prop_tgt:`LINK_OPTIONS` target property. + +This property holds a :ref:`;-list <CMake Language Lists>` of options +specified so far for its target. Use :command:`set_target_properties` or +:command:`set_property` commands to set its content. + +Contents of ``STATIC_LIBRARY_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:`STATIC_LIBRARY_FLAGS` + property. diff --git a/Help/prop_tgt/VERSION.rst b/Help/prop_tgt/VERSION.rst index 66e7bde71..ff3b3030f 100644 --- a/Help/prop_tgt/VERSION.rst +++ b/Help/prop_tgt/VERSION.rst @@ -22,7 +22,7 @@ These numbers are used as the image version of the binary. Mach-O Versions ^^^^^^^^^^^^^^^ -For shared libraries and executables on Mach-O systems (e.g. OS X, iOS), +For shared libraries and executables on Mach-O systems (e.g. macOS, iOS), the :prop_tgt:`SOVERSION` property correspond to *compatibility version* and ``VERSION`` to *current version*. See the :prop_tgt:`FRAMEWORK` target property for an example. Versions of Mach-O binaries may be checked with the diff --git a/Help/prop_tgt/VS_DEBUGGER_COMMAND.rst b/Help/prop_tgt/VS_DEBUGGER_COMMAND.rst index f89875093..ba5fd0aeb 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 000000000..06ef5d5fc --- /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 000000000..f55ac7bee --- /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 fb0389e8e..008bbf6e6 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/prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER.rst b/Help/prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER.rst new file mode 100644 index 000000000..694cd7717 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_ADDRESS_SANITIZER +------------------------------ + +Whether to enable ``Address Sanitizer`` in the Diagnostics +section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER` if it is set +when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN.rst b/Help/prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN.rst new file mode 100644 index 000000000..2803da0b4 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN +----------------------------------------------- + +Whether to enable ``Detect use of stack after return`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN` +if it is set when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_ARGUMENTS.rst b/Help/prop_tgt/XCODE_SCHEME_ARGUMENTS.rst new file mode 100644 index 000000000..2eac4a926 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_ARGUMENTS.rst @@ -0,0 +1,10 @@ +XCODE_SCHEME_ARGUMENTS +---------------------- + +Specify command line arguments that should be added to the Arguments +section of the generated Xcode scheme. + +If set to a list of arguments those will be added to the scheme. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER.rst b/Help/prop_tgt/XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER.rst new file mode 100644 index 000000000..75fc3262b --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER +---------------------------------------- + +Whether to disable the ``Main Thread Checker`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER` +if it is set when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS.rst b/Help/prop_tgt/XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS.rst new file mode 100644 index 000000000..a7fab6677 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS +---------------------------------- + +Whether to enable ``Dynamic Library Loads`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS` if it is set +when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE.rst b/Help/prop_tgt/XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE.rst new file mode 100644 index 000000000..162fc4576 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE +------------------------------------- + +Whether to enable ``Dynamic Linker API usage`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE` if it is set +when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_ENVIRONMENT.rst b/Help/prop_tgt/XCODE_SCHEME_ENVIRONMENT.rst new file mode 100644 index 000000000..1dbd6c437 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_ENVIRONMENT.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_ENVIRONMENT +------------------------ + +Specify environment variables that should be added to the Arguments +section of the generated Xcode scheme. + +If set to a list of environment variables and values of the form +``MYVAR=value`` those environment variables will be added to the +scheme. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_EXECUTABLE.rst b/Help/prop_tgt/XCODE_SCHEME_EXECUTABLE.rst new file mode 100644 index 000000000..d0427e266 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_EXECUTABLE.rst @@ -0,0 +1,9 @@ +XCODE_SCHEME_EXECUTABLE +----------------------- + +Specify path to executable in the Info section of the generated +Xcode scheme. If not set the schema generator will select the +current target if it is actually executable. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_GUARD_MALLOC.rst b/Help/prop_tgt/XCODE_SCHEME_GUARD_MALLOC.rst new file mode 100644 index 000000000..64e1990eb --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_GUARD_MALLOC.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_GUARD_MALLOC +------------------------------ + +Whether to enable ``Guard Malloc`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_GUARD_MALLOC` if it is set +when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP.rst b/Help/prop_tgt/XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP.rst new file mode 100644 index 000000000..99c112fbc --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP.rst @@ -0,0 +1,13 @@ +XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP +------------------------------------- + +Whether to enable the ``Main Thread Checker`` option +``Pause on issues`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP` if it is set +when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_MALLOC_GUARD_EDGES.rst b/Help/prop_tgt/XCODE_SCHEME_MALLOC_GUARD_EDGES.rst new file mode 100644 index 000000000..ef3852a35 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_MALLOC_GUARD_EDGES.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_MALLOC_GUARD_EDGES +------------------------------- + +Whether to enable ``Malloc Guard Edges`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES` if it is set +when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_MALLOC_SCRIBBLE.rst b/Help/prop_tgt/XCODE_SCHEME_MALLOC_SCRIBBLE.rst new file mode 100644 index 000000000..75baba2e0 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_MALLOC_SCRIBBLE.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_MALLOC_SCRIBBLE +------------------------------ + +Whether to enable ``Malloc Scribble`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE` if it is set +when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_MALLOC_STACK.rst b/Help/prop_tgt/XCODE_SCHEME_MALLOC_STACK.rst new file mode 100644 index 000000000..984022c71 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_MALLOC_STACK.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_MALLOC_STACK +------------------------- + +Whether to enable ``Malloc Stack`` in the Diagnostics +section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_MALLOC_STACK` if it is set +when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_THREAD_SANITIZER.rst b/Help/prop_tgt/XCODE_SCHEME_THREAD_SANITIZER.rst new file mode 100644 index 000000000..825ac5b30 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_THREAD_SANITIZER.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_THREAD_SANITIZER +----------------------------- + +Whether to enable ``Thread Sanitizer`` in the Diagnostics +section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_THREAD_SANITIZER` if it is set +when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_THREAD_SANITIZER_STOP.rst b/Help/prop_tgt/XCODE_SCHEME_THREAD_SANITIZER_STOP.rst new file mode 100644 index 000000000..86f894ecc --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_THREAD_SANITIZER_STOP.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_THREAD_SANITIZER_STOP +---------------------------------- + +Whether to enable ``Thread Sanitizer - Pause on issues`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP` if it is set +when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER.rst b/Help/prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER.rst new file mode 100644 index 000000000..829a62ecd --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER +------------------------------------------ + +Whether to enable ``Undefined Behavior Sanitizer`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER` +if it is set when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP.rst b/Help/prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP.rst new file mode 100644 index 000000000..5e382caca --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP.rst @@ -0,0 +1,13 @@ +XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP +----------------------------------------------- + +Whether to enable ``Undefined Behavior Sanitizer`` option +``Pause on issues`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP` +if it is set when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/prop_tgt/XCODE_SCHEME_ZOMBIE_OBJECTS.rst b/Help/prop_tgt/XCODE_SCHEME_ZOMBIE_OBJECTS.rst new file mode 100644 index 000000000..80b954a79 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_ZOMBIE_OBJECTS.rst @@ -0,0 +1,12 @@ +XCODE_SCHEME_ZOMBIE_OBJECTS +------------------------------ + +Whether to enable ``Zombie Objects`` +in the Diagnostics section of the generated Xcode scheme. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS` if it is set +when a target is created. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/release/3.1.rst b/Help/release/3.1.rst index dca42cdcd..8bea28f70 100644 --- a/Help/release/3.1.rst +++ b/Help/release/3.1.rst @@ -289,16 +289,16 @@ 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. -* The :manual:`cpack(1)` ``WiX`` generator learned to support +* The :cpack_gen:`CPack WIX Generator` learned to support a :prop_inst:`CPACK_WIX_ACL` installed file property to specify an Access Control List. diff --git a/Help/release/3.10.rst b/Help/release/3.10.rst index 1205b17e9..03eda362d 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 214da0dba..a80657d2d 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 f00be3e79..481027ec7 100644 --- a/Help/release/3.12.rst +++ b/Help/release/3.12.rst @@ -239,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.13.rst b/Help/release/3.13.rst new file mode 100644 index 000000000..9f7e61ffd --- /dev/null +++ b/Help/release/3.13.rst @@ -0,0 +1,241 @@ +CMake 3.13 Release Notes +************************ + +.. only:: html + + .. contents:: + +Changes made since CMake 3.12 include the following. + +New Features +============ + +Generators +---------- + +* The :ref:`Visual Studio Generators` for VS 2010 and above learned to + support the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property + and supporting :module:`CheckIPOSupported` module. + +* The :generator:`Xcode` generator learned to configure more Xcode Scheme + fields. See the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable. + +* The :generator:`Green Hills MULTI` generator has been 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. + +Command-Line +------------ + +* The :manual:`cmake(1)` command gained the ``-S <source_dir>`` + command line option to specify the location of the source directory. + This option can be used independently of ``-B``. + +* The :manual:`cmake(1)` command gained the ``-B <build_dir>`` + command line option to specify the location of the build directory. + This option can be used independently of ``-S``. + +* The :manual:`cmake(1)` ``-E create_symlink`` command can now be used + on Windows. + +Commands +-------- + +* The :command:`add_custom_command` and :command:`add_custom_target` commands + learned to support generator expressions in ``WORKING_DIRECTORY`` options. + +* The :command:`add_link_options` command was created to add link + options in the current directory. + +* The :command:`install(TARGETS)` command learned to install targets + created outside the current directory. + +* The :command:`link_directories` command gained options to control + insertion position. + +* The :command:`list(SORT)` command gained options to control the + comparison operation used to order the entries. + +* The :command:`math` command gained options for hexadecimal. + +* The :command:`target_link_directories` command was created to + specify link directories for targets and their dependents. + +* The :command:`target_link_options` command was created to + specify link options for targets and their dependents. + +* The :command:`target_link_libraries` command may now be called + to modify targets created outside the current directory. + See policy :policy:`CMP0079`. + +Variables +--------- + +* A :variable:`CMAKE_AUTOGEN_VERBOSE` variable was added to optionally + increase the verbosity of :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC` + and :prop_tgt:`AUTORCC` from within CMake project code. + +* A :variable:`CMAKE_VS_GLOBALS` variable was added to initialize + :prop_tgt:`VS_GLOBAL_<variable>` target properties on targets as + they are created. + +Properties +---------- + +* 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. + +* The :prop_tgt:`INTERFACE_LINK_DEPENDS` target property was created + to specify transitive link dependencies on files. + +* The :prop_tgt:`LINK_DEPENDS` target property learned to support + :manual:`generator expressions <cmake-generator-expressions(7)>`. + +* :prop_tgt:`LINK_DIRECTORIES` and :prop_tgt:`INTERFACE_LINK_DIRECTORIES` + target properties were added to collect link directories for a target + and its dependents. Use the :command:`target_link_directories` command + to set them. + +* :prop_tgt:`LINK_OPTIONS` and :prop_tgt:`INTERFACE_LINK_OPTIONS` target + properties were added to collect link options for a target and its + dependents. Use the :command:`target_link_options` command to set them. + +* A :prop_dir:`LINK_OPTIONS` directory property was added to collect + link options for targets created under the current directory. + Use the :command:`add_link_options` command to set it. + +* A :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property was created + to specify archiver options to use when creating static libraries. + +* 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. + +* The :prop_tgt:`VS_DEBUGGER_COMMAND` and + :prop_tgt:`VS_DEBUGGER_WORKING_DIRECTORY` target properties + now support generator expressions. + +Modules +------- + +* The :module:`FindBoost` module gained a ``Boost_ARCHITECTURE`` option + to specify a Boost architecture-specific library filename fragment. + +* The :module:`FindCURL` module learned to find debug and release variants + separately. + +* The :module:`FindMatlab` module gained new components ``ENGINE_LIBRARY`` and + ``DATAARRAY_LIBRARY`` to request finding the Matlab C++ Engine and DataArray + libraries respectively. + +* The :module:`FindMatlab` module now explicitly exports mexFunction in Visual + Studio. + +* The :module:`FindMatlab` module gained a new ``MCC_COMPILER`` + component to request finding the Matlab Compiler add-on. + +* The :module:`FindPkgConfig` module gained an option to create imported + targets in global scope. + +* The :module:`FindPkgConfig` module gained support for ``<`` and ``>`` + operators for version checks in addition to the already supported + operators ``>=``, ``<=``, and ``=``. + +* Modules :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython` + gain capability to control order of resource lookup on macOS (Framework) and + Windows (Registry). + +* The :module:`FindSubversion` module ``Subversion_WC_INFO`` command + gained an ``IGNORE_SVN_FAILURE`` option to suppress failures, + e.g. when the source tree is not under Subversion control. + +* The :module:`UseSWIG` module learned to manage target property + :prop_tgt:`INCLUDE_DIRECTORIES` for ``SWIG`` compilation. + +CTest +----- + +* :manual:`ctest(1)` gained a ``--progress`` option to enable a live + test progress summary when output goes to a terminal. + +CPack +----- + +* The :cpack_gen:`CPack DEB Generator` learned to split debug symbols into + a corresponding .ddeb package when ``CPACK_DEBIAN_DEBUGINFO_PACKAGE`` is + set. + +* 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. + +* 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. + +Deprecated and Removed Features +=============================== + +* An explicit deprecation diagnostic was added for policies ``CMP0055`` + through ``CMP0063`` (``CMP0054`` and below were already deprecated). + The :manual:`cmake-policies(7)` manual explains that the OLD behaviors + of all policies are deprecated and that projects should port to the + NEW behaviors. + +Other Changes +============= + +* The precompiled binaries provided on ``cmake.org`` now include + qthelp-format documentation. + +* The :command:`option` command now honors an existing normal variable + of the same name and does nothing instead of possibly creating a cache + entry (or setting its type) and removing the normal variable. + See policy :policy:`CMP0077`. + +* The :ref:`Makefile Generators` learned to remove custom command and + custom target byproducts during ``make clean``. + +* 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. + +* The :module:`BundleUtilities` module may no longer be included at configure + time. This was always a bug anyway. See policy :policy:`CMP0080`. + +* The :module:`UseSWIG` module has changed strategy for target naming. + See policy :policy:`CMP0078`. + +* The :prop_tgt:`LINK_DIRECTORIES` target property now expects absolute paths. + See policy :policy:`CMP0081`. + +* 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/3.2.rst b/Help/release/3.2.rst index 8abb1ca62..992d44b65 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 0beb354ac..6657e8df1 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 468627ef4..943d26716 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 009eb3c7c..58a5d4eef 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 DragNDrop 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 DragNDrop 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 a542b77dc..74dac1c20 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 DragNDrop 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 d4d374baa..345c056df 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 efb2aa5a7..de51a7bc3 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 897e268b5..ffa95aa27 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/index.rst b/Help/release/index.rst index 4b32eab0b..fbe4cf625 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -13,6 +13,7 @@ Releases .. toctree:: :maxdepth: 1 + 3.13 <3.13> 3.12 <3.12> 3.11 <3.11> 3.10 <3.10> diff --git a/Help/variable/CACHE.rst b/Help/variable/CACHE.rst new file mode 100644 index 000000000..230739acc --- /dev/null +++ b/Help/variable/CACHE.rst @@ -0,0 +1,17 @@ +CACHE +----- + +Read cache variables. + +Use the syntax ``$CACHE{VAR}`` to read cache entry ``VAR``. +See the :ref:`cmake-language(7) variables <CMake Language Variables>` +documentation for more complete documentation of the interaction of +normal variables and cache entries. + +When evaluating :ref:`Variable References` of the form ``${VAR}``, +CMake first searches for a normal variable with that name, and if not +found CMake will search for a cache entry with that name. +The ``$CACHE{VAR}`` syntax can be used to do direct cache lookup and +ignore any existing normal variable. + +See the :command:`set` command to see how to write cache variables. diff --git a/Help/variable/CMAKE_APPBUNDLE_PATH.rst b/Help/variable/CMAKE_APPBUNDLE_PATH.rst index 2bc79ac3a..c1f0951cc 100644 --- a/Help/variable/CMAKE_APPBUNDLE_PATH.rst +++ b/Help/variable/CMAKE_APPBUNDLE_PATH.rst @@ -2,5 +2,5 @@ CMAKE_APPBUNDLE_PATH -------------------- :ref:`;-list <CMake Language Lists>` of directories specifying a search path -for OS X application bundles used by the :command:`find_program`, and +for macOS application bundles used by the :command:`find_program`, and :command:`find_package` commands. diff --git a/Help/variable/CMAKE_AUTOGEN_VERBOSE.rst b/Help/variable/CMAKE_AUTOGEN_VERBOSE.rst new file mode 100644 index 000000000..bad9cf2b3 --- /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_CPACK_COMMAND.rst b/Help/variable/CMAKE_CPACK_COMMAND.rst new file mode 100644 index 000000000..559108a1a --- /dev/null +++ b/Help/variable/CMAKE_CPACK_COMMAND.rst @@ -0,0 +1,8 @@ +CMAKE_CPACK_COMMAND +------------------- + +Full path to :manual:`cpack(1)` command installed with CMake. + +This is the full path to the CPack executable :manual:`cpack(1)` which is +useful from custom commands that want to use the :manual:`cmake(1)` ``-E`` +option for portable system commands. diff --git a/Help/variable/CMAKE_DEBUG_TARGET_PROPERTIES.rst b/Help/variable/CMAKE_DEBUG_TARGET_PROPERTIES.rst index 513276e57..a1fa1fffa 100644 --- a/Help/variable/CMAKE_DEBUG_TARGET_PROPERTIES.rst +++ b/Help/variable/CMAKE_DEBUG_TARGET_PROPERTIES.rst @@ -5,10 +5,19 @@ Enables tracing output for target properties. This variable can be populated with a list of properties to generate debug output for when evaluating target properties. Currently it can -only be used when evaluating the :prop_tgt:`INCLUDE_DIRECTORIES`, -:prop_tgt:`COMPILE_DEFINITIONS`, :prop_tgt:`COMPILE_OPTIONS`, -:prop_tgt:`AUTOUIC_OPTIONS`, :prop_tgt:`SOURCES`, :prop_tgt:`COMPILE_FEATURES`, -:prop_tgt:`POSITION_INDEPENDENT_CODE` target properties and any other property -listed in :prop_tgt:`COMPATIBLE_INTERFACE_STRING` and other -``COMPATIBLE_INTERFACE_`` properties. It outputs an origin for each entry in -the target property. Default is unset. +only be used when evaluating: + +* :prop_tgt:`AUTOUIC_OPTIONS` +* :prop_tgt:`COMPILE_DEFINITIONS` +* :prop_tgt:`COMPILE_FEATURES` +* :prop_tgt:`COMPILE_OPTIONS` +* :prop_tgt:`INCLUDE_DIRECTORIES` +* :prop_tgt:`LINK_DIRECTORIES` +* :prop_tgt:`LINK_OPTIONS` +* :prop_tgt:`POSITION_INDEPENDENT_CODE` +* :prop_tgt:`SOURCES` + +target properties and any other property listed in +:prop_tgt:`COMPATIBLE_INTERFACE_STRING` and other +``COMPATIBLE_INTERFACE_`` properties. It outputs an origin for each entry +in the target property. Default is unset. diff --git a/Help/variable/CMAKE_ENABLE_EXPORTS.rst b/Help/variable/CMAKE_ENABLE_EXPORTS.rst index 9a877e7e6..7ec4d635d 100644 --- a/Help/variable/CMAKE_ENABLE_EXPORTS.rst +++ b/Help/variable/CMAKE_ENABLE_EXPORTS.rst @@ -12,7 +12,7 @@ dependency on the executable is created for targets that link to it. For DLL platforms an import library will be created for the exported symbols and then used for linking. All Windows-based systems including Cygwin are DLL platforms. For non-DLL platforms that -require all symbols to be resolved at link time, such as OS X, the +require all symbols to be resolved at link time, such as macOS, the module will ``link`` to the executable using a flag like ``-bundle_loader``. For other non-DLL platforms the link rule is simply ignored since the dynamic loader will automatically bind symbols when diff --git a/Help/variable/CMAKE_FIND_APPBUNDLE.rst b/Help/variable/CMAKE_FIND_APPBUNDLE.rst index e0727b547..7a05facf8 100644 --- a/Help/variable/CMAKE_FIND_APPBUNDLE.rst +++ b/Help/variable/CMAKE_FIND_APPBUNDLE.rst @@ -2,9 +2,9 @@ CMAKE_FIND_APPBUNDLE -------------------- This variable affects how ``find_*`` commands choose between -OS X Application Bundles and unix-style package components. +macOS Application Bundles and unix-style package components. -On Darwin or systems supporting OS X Application Bundles, the +On Darwin or systems supporting macOS Application Bundles, the ``CMAKE_FIND_APPBUNDLE`` variable can be set to empty or one of the following: diff --git a/Help/variable/CMAKE_FIND_FRAMEWORK.rst b/Help/variable/CMAKE_FIND_FRAMEWORK.rst index 790694ac5..4d5078fb6 100644 --- a/Help/variable/CMAKE_FIND_FRAMEWORK.rst +++ b/Help/variable/CMAKE_FIND_FRAMEWORK.rst @@ -2,9 +2,9 @@ CMAKE_FIND_FRAMEWORK -------------------- This variable affects how ``find_*`` commands choose between -OS X Frameworks and unix-style package components. +macOS Frameworks and unix-style package components. -On Darwin or systems supporting OS X Frameworks, the +On Darwin or systems supporting macOS Frameworks, the ``CMAKE_FIND_FRAMEWORK`` variable can be set to empty or one of the following: diff --git a/Help/variable/CMAKE_FRAMEWORK_PATH.rst b/Help/variable/CMAKE_FRAMEWORK_PATH.rst index 5ff08e679..04751f88d 100644 --- a/Help/variable/CMAKE_FRAMEWORK_PATH.rst +++ b/Help/variable/CMAKE_FRAMEWORK_PATH.rst @@ -2,6 +2,6 @@ CMAKE_FRAMEWORK_PATH -------------------- :ref:`;-list <CMake Language Lists>` of directories specifying a search path -for OS X frameworks used by the :command:`find_library`, +for macOS frameworks used by the :command:`find_library`, :command:`find_package`, :command:`find_path`, and :command:`find_file` commands. diff --git a/Help/variable/CMAKE_GENERATOR_PLATFORM.rst b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst index 50412ffff..963f0a479 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 3220244d7..e9bc28b9e 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_HOST_APPLE.rst b/Help/variable/CMAKE_HOST_APPLE.rst index ac7b03004..9c205ec34 100644 --- a/Help/variable/CMAKE_HOST_APPLE.rst +++ b/Help/variable/CMAKE_HOST_APPLE.rst @@ -1,6 +1,6 @@ CMAKE_HOST_APPLE ---------------- -``True`` for Apple OS X operating systems. +``True`` for Apple macOS operating systems. -Set to ``true`` when the host system is Apple OS X. +Set to ``true`` when the host system is Apple macOS. diff --git a/Help/variable/CMAKE_HOST_SYSTEM_NAME.rst b/Help/variable/CMAKE_HOST_SYSTEM_NAME.rst index c67359272..e8926771c 100644 --- a/Help/variable/CMAKE_HOST_SYSTEM_NAME.rst +++ b/Help/variable/CMAKE_HOST_SYSTEM_NAME.rst @@ -4,5 +4,5 @@ CMAKE_HOST_SYSTEM_NAME Name of the OS CMake is running on. On systems that have the uname command, this variable is set to the -output of ``uname -s``. ``Linux``, ``Windows``, and ``Darwin`` for OS X +output of ``uname -s``. ``Linux``, ``Windows``, and ``Darwin`` for macOS are the values found on the big three operating systems. diff --git a/Help/variable/CMAKE_INSTALL_NAME_DIR.rst b/Help/variable/CMAKE_INSTALL_NAME_DIR.rst index 1f2d62bf6..5ba4c04cb 100644 --- a/Help/variable/CMAKE_INSTALL_NAME_DIR.rst +++ b/Help/variable/CMAKE_INSTALL_NAME_DIR.rst @@ -1,7 +1,7 @@ CMAKE_INSTALL_NAME_DIR ---------------------- -OS X directory name for installed targets. +macOS directory name for installed targets. ``CMAKE_INSTALL_NAME_DIR`` is used to initialize the :prop_tgt:`INSTALL_NAME_DIR` property on all targets. See that target 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 000000000..321f97ed1 --- /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 000000000..faf14815c --- /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_LINK_DIRECTORIES_BEFORE.rst b/Help/variable/CMAKE_LINK_DIRECTORIES_BEFORE.rst new file mode 100644 index 000000000..026ca35b3 --- /dev/null +++ b/Help/variable/CMAKE_LINK_DIRECTORIES_BEFORE.rst @@ -0,0 +1,9 @@ +CMAKE_LINK_DIRECTORIES_BEFORE +----------------------------- + +Whether to append or prepend directories by default in +:command:`link_directories`. + +This variable affects the default behavior of the :command:`link_directories` +command. Setting this variable to ``ON`` is equivalent to using the ``BEFORE`` +option in all uses of that command. diff --git a/Help/variable/CMAKE_MACOSX_RPATH.rst b/Help/variable/CMAKE_MACOSX_RPATH.rst index 042e807f5..2fc648d61 100644 --- a/Help/variable/CMAKE_MACOSX_RPATH.rst +++ b/Help/variable/CMAKE_MACOSX_RPATH.rst @@ -1,7 +1,7 @@ CMAKE_MACOSX_RPATH ------------------- -Whether to use rpaths on OS X and iOS. +Whether to use rpaths on macOS and iOS. This variable is used to initialize the :prop_tgt:`MACOSX_RPATH` property on all targets. diff --git a/Help/variable/CMAKE_MAKE_PROGRAM.rst b/Help/variable/CMAKE_MAKE_PROGRAM.rst index a3b997af2..4f5a50fae 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_OSX_ARCHITECTURES.rst b/Help/variable/CMAKE_OSX_ARCHITECTURES.rst index 51b840d8f..fdaca28e3 100644 --- a/Help/variable/CMAKE_OSX_ARCHITECTURES.rst +++ b/Help/variable/CMAKE_OSX_ARCHITECTURES.rst @@ -1,7 +1,7 @@ CMAKE_OSX_ARCHITECTURES ----------------------- -Target specific architectures for OS X and iOS. +Target specific architectures for macOS and iOS. This variable is used to initialize the :prop_tgt:`OSX_ARCHITECTURES` property on each target as it is created. See that target property diff --git a/Help/variable/CMAKE_OSX_SYSROOT.rst b/Help/variable/CMAKE_OSX_SYSROOT.rst index f1d58c6b5..db9fccdd1 100644 --- a/Help/variable/CMAKE_OSX_SYSROOT.rst +++ b/Help/variable/CMAKE_OSX_SYSROOT.rst @@ -1,7 +1,7 @@ CMAKE_OSX_SYSROOT ----------------- -Specify the location or name of the OS X platform SDK to be used. +Specify the location or name of the macOS platform SDK to be used. CMake uses this value to compute the value of the ``-isysroot`` flag or equivalent and to help the ``find_*`` commands locate files in the SDK. diff --git a/Help/variable/CMAKE_OSX_VARIABLE.txt b/Help/variable/CMAKE_OSX_VARIABLE.txt index 5b8472604..16f3c1a1a 100644 --- a/Help/variable/CMAKE_OSX_VARIABLE.txt +++ b/Help/variable/CMAKE_OSX_VARIABLE.txt @@ -2,6 +2,8 @@ The value of this variable should be set prior to the first :command:`project` or :command:`enable_language` command invocation because it may influence configuration of the toolchain and flags. It is intended to be set locally by the user creating a build tree. +This variable should be set as a ``CACHE`` entry (or else CMake may +remove it while initializing a cache entry of the same name). Despite the ``OSX`` part in the variable name(s) they apply also to other SDKs than macOS like iOS, tvOS, or watchOS. diff --git a/Help/variable/CMAKE_RULE_MESSAGES.rst b/Help/variable/CMAKE_RULE_MESSAGES.rst new file mode 100644 index 000000000..7460a81ee --- /dev/null +++ b/Help/variable/CMAKE_RULE_MESSAGES.rst @@ -0,0 +1,8 @@ +CMAKE_RULE_MESSAGES +------------------- + +Specify whether to report a message for each make rule. + +If set in the cache it is used to initialize the value of the :prop_gbl:`RULE_MESSAGES` property. +Users may disable the option in their local build tree to disable granular messages +and report only as each target completes in Makefile builds. diff --git a/Help/variable/CMAKE_SYSTEM_APPBUNDLE_PATH.rst b/Help/variable/CMAKE_SYSTEM_APPBUNDLE_PATH.rst index 3c6687c6e..666af4615 100644 --- a/Help/variable/CMAKE_SYSTEM_APPBUNDLE_PATH.rst +++ b/Help/variable/CMAKE_SYSTEM_APPBUNDLE_PATH.rst @@ -1,7 +1,7 @@ CMAKE_SYSTEM_APPBUNDLE_PATH --------------------------- -Search path for OS X application bundles used by the :command:`find_program`, +Search path for macOS application bundles used by the :command:`find_program`, and :command:`find_package` commands. By default it contains the standard directories for the current system. It is *not* intended to be modified by the project, use :variable:`CMAKE_APPBUNDLE_PATH` for this. diff --git a/Help/variable/CMAKE_SYSTEM_FRAMEWORK_PATH.rst b/Help/variable/CMAKE_SYSTEM_FRAMEWORK_PATH.rst index 1e8b0d947..14ba18eff 100644 --- a/Help/variable/CMAKE_SYSTEM_FRAMEWORK_PATH.rst +++ b/Help/variable/CMAKE_SYSTEM_FRAMEWORK_PATH.rst @@ -1,7 +1,7 @@ CMAKE_SYSTEM_FRAMEWORK_PATH --------------------------- -Search path for OS X frameworks used by the :command:`find_library`, +Search path for macOS frameworks used by the :command:`find_library`, :command:`find_package`, :command:`find_path`, and :command:`find_file` commands. By default it contains the standard directories for the current system. It is *not* intended to be modified by the project, diff --git a/Help/variable/CMAKE_SYSTEM_PROCESSOR.rst b/Help/variable/CMAKE_SYSTEM_PROCESSOR.rst index 09280dee6..8ad89f128 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/CMAKE_VS_GLOBALS.rst b/Help/variable/CMAKE_VS_GLOBALS.rst new file mode 100644 index 000000000..83777b619 --- /dev/null +++ b/Help/variable/CMAKE_VS_GLOBALS.rst @@ -0,0 +1,21 @@ +CMAKE_VS_GLOBALS +---------------- + +List of ``Key=Value`` records to be set per target as target properties +:prop_tgt:`VS_GLOBAL_<variable>` with ``variable=Key`` and value ``Value``. + +For example: + +.. code-block:: cmake + + set(CMAKE_VS_GLOBALS + "DefaultLanguage=en-US" + "MinimumVisualStudioVersion=14.0" + ) + +will set properties ``VS_GLOBAL_DefaultLanguage`` to ``en-US`` and +``VS_GLOBAL_MinimumVisualStudioVersion`` to ``14.0`` for all targets +(except for ``INTERFACE`` libraries). + +This variable is meant to be set by a +:variable:`toolchain file <CMAKE_TOOLCHAIN_FILE>`. diff --git a/Help/variable/CMAKE_VS_WINRT_BY_DEFAULT.rst b/Help/variable/CMAKE_VS_WINRT_BY_DEFAULT.rst new file mode 100644 index 000000000..2ba8fe27e --- /dev/null +++ b/Help/variable/CMAKE_VS_WINRT_BY_DEFAULT.rst @@ -0,0 +1,8 @@ +CMAKE_VS_WINRT_BY_DEFAULT +------------------------- + +Tell :ref:`Visual Studio Generators` for VS 2010 and above that the +target platform compiles as WinRT by default (compiles with ``/ZW``). + +This variable is meant to be set by a +:variable:`toolchain file <CMAKE_TOOLCHAIN_FILE>` for such platforms. diff --git a/Help/variable/CMAKE_XCODE_GENERATE_SCHEME.rst b/Help/variable/CMAKE_XCODE_GENERATE_SCHEME.rst index c9fcc92e0..ed20bbe92 100644 --- a/Help/variable/CMAKE_XCODE_GENERATE_SCHEME.rst +++ b/Help/variable/CMAKE_XCODE_GENERATE_SCHEME.rst @@ -9,3 +9,31 @@ actions from the command line. The Xcode Schema Generator is still experimental and subject to change. + +The following target properties overwrite the default of the +corresponding settings on the "Diagnostic" tab for each schema file. +Each of those is initialized by the respective ``CMAKE_`` variable +at target creation time. + +- :prop_tgt:`XCODE_SCHEME_ADDRESS_SANITIZER` +- :prop_tgt:`XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN` +- :prop_tgt:`XCODE_SCHEME_THREAD_SANITIZER` +- :prop_tgt:`XCODE_SCHEME_THREAD_SANITIZER_STOP` +- :prop_tgt:`XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER` +- :prop_tgt:`XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP` +- :prop_tgt:`XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER` +- :prop_tgt:`XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP` +- :prop_tgt:`XCODE_SCHEME_MALLOC_SCRIBBLE` +- :prop_tgt:`XCODE_SCHEME_MALLOC_GUARD_EDGES` +- :prop_tgt:`XCODE_SCHEME_GUARD_MALLOC` +- :prop_tgt:`XCODE_SCHEME_ZOMBIE_OBJECTS` +- :prop_tgt:`XCODE_SCHEME_MALLOC_STACK` +- :prop_tgt:`XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE` +- :prop_tgt:`XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS` + +The following target properties will be applied on the +"Info" and "Arguments" tab: + +- :prop_tgt:`XCODE_SCHEME_EXECUTABLE` +- :prop_tgt:`XCODE_SCHEME_ARGUMENTS` +- :prop_tgt:`XCODE_SCHEME_ENVIRONMENT` diff --git a/Help/variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER.rst b/Help/variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER.rst new file mode 100644 index 000000000..37dc0ce80 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER +------------------------------------ + +Whether to enable ``Address Sanitizer`` in the Diagnostics +section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_ADDRESS_SANITIZER` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN.rst b/Help/variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN.rst new file mode 100644 index 000000000..05949c3a8 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN +----------------------------------------------------- + +Whether to enable ``Detect use of stack after return`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER.rst b/Help/variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER.rst new file mode 100644 index 000000000..81f49745a --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER +---------------------------------------------- + +Whether to disable the ``Main Thread Checker`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS.rst b/Help/variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS.rst new file mode 100644 index 000000000..5e133ac1f --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS +---------------------------------------- + +Whether to enable ``Dynamic Library Loads`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE.rst b/Help/variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE.rst new file mode 100644 index 000000000..33162d97e --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE +------------------------------------------- + +Whether to enable ``Dynamic Linker API usage`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_GUARD_MALLOC.rst b/Help/variable/CMAKE_XCODE_SCHEME_GUARD_MALLOC.rst new file mode 100644 index 000000000..03d88c232 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_GUARD_MALLOC.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_GUARD_MALLOC +------------------------------- + +Whether to enable ``Guard Malloc`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_GUARD_MALLOC` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP.rst b/Help/variable/CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP.rst new file mode 100644 index 000000000..fd6135f29 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP.rst @@ -0,0 +1,13 @@ +CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP +------------------------------------------- + +Whether to enable the ``Main Thread Checker`` option +``Pause on issues`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES.rst b/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES.rst new file mode 100644 index 000000000..8fedc20f3 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES +------------------------------------- + +Whether to enable ``Malloc Guard Edges`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_MALLOC_GUARD_EDGES` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE.rst b/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE.rst new file mode 100644 index 000000000..cddca7c97 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE +---------------------------------- + +Whether to enable ``Malloc Scribble`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_MALLOC_SCRIBBLE` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_STACK.rst b/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_STACK.rst new file mode 100644 index 000000000..9c83698f8 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_MALLOC_STACK.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_MALLOC_STACK +------------------------------- + +Whether to enable ``Malloc Stack`` in the Diagnostics +section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_MALLOC_STACK` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER.rst b/Help/variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER.rst new file mode 100644 index 000000000..c9373697e --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_THREAD_SANITIZER +----------------------------------- + +Whether to enable ``Thread Sanitizer`` in the Diagnostics +section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_THREAD_SANITIZER` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP.rst b/Help/variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP.rst new file mode 100644 index 000000000..eed796cc9 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP +---------------------------------------- + +Whether to enable ``Thread Sanitizer - Pause on issues`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_THREAD_SANITIZER_STOP` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER.rst b/Help/variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER.rst new file mode 100644 index 000000000..d14ba3f81 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER +------------------------------------------------ + +Whether to enable ``Undefined Behavior Sanitizer`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP.rst b/Help/variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP.rst new file mode 100644 index 000000000..f8df30473 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP.rst @@ -0,0 +1,13 @@ +CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP +----------------------------------------------------- + +Whether to enable ``Undefined Behavior Sanitizer`` option +``Pause on issues`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS.rst b/Help/variable/CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS.rst new file mode 100644 index 000000000..efc331a17 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS.rst @@ -0,0 +1,12 @@ +CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS +--------------------------------- + +Whether to enable ``Zombie Objects`` +in the Diagnostics section of the generated Xcode scheme. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_ZOMBIE_OBJECTS` +property on all targets. + +Please refer to the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable +documentation to see all Xcode schema related properties. diff --git a/Help/variable/ENV.rst b/Help/variable/ENV.rst index 368152aeb..98677ddc9 100644 --- a/Help/variable/ENV.rst +++ b/Help/variable/ENV.rst @@ -1,7 +1,8 @@ ENV --- -Access environment variables. +Read environment variables. -Use the syntax ``$ENV{VAR}`` to read environment variable ``VAR``. See also -the :command:`set` command to set ``ENV{VAR}``. +Use the syntax ``$ENV{VAR}`` to read environment variable ``VAR``. + +See the :command:`set` command to see how to write environment variables. |