diff options
Diffstat (limited to 'Help')
24 files changed, 223 insertions, 103 deletions
diff --git a/Help/command/add_link_options.rst b/Help/command/add_link_options.rst index 821198d..551d440 100644 --- a/Help/command/add_link_options.rst +++ b/Help/command/add_link_options.rst @@ -1,7 +1,7 @@ add_link_options ---------------- -Adds options to the link of targets. +Adds options to the link of shared library, module and executable targets. :: diff --git a/Help/command/ctest_submit.rst b/Help/command/ctest_submit.rst index cc9612b..2ba6bef 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 b205bca..df1a4e5 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 0c676c6..8c49328 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 a4416ab..bbe8c4d 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -5,12 +5,12 @@ Load settings for an external project. :: - 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 @@ -44,7 +44,7 @@ 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` +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. Many @@ -54,7 +54,7 @@ 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] @@ -82,29 +82,29 @@ mode is also implied by use of options not specified in the reduced signature. Config mode attempts to locate a configuration file provided by the -package to be found. A cache entry called ``<package>_DIR`` is created to +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. When the ``[version]`` argument is given Config mode will only find a @@ -127,7 +127,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 +158,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. @@ -192,7 +192,7 @@ 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]) + find_package(<PackageName> [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 @@ -228,7 +228,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 +286,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 +329,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` @@ -344,28 +344,28 @@ 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,7 +375,7 @@ 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 diff --git a/Help/command/include_directories.rst b/Help/command/include_directories.rst index f694934..e797b5d 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/unset.rst b/Help/command/unset.rst index a1fc95c..c19dd31 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/external.rst b/Help/cpack_gen/external.rst index a69866d..f98e1c9 100644 --- a/Help/cpack_gen/external.rst +++ b/Help/cpack_gen/external.rst @@ -10,19 +10,32 @@ tools. For this reason, CPack provides the "External" generator, which allows external packaging software to take advantage of some of the functionality provided by CPack, such as component installation and the dependency graph. -The CPack External generator doesn't actually package any files. Instead, it -generates a .json file containing the CPack internal metadata, which gives -external software information on how to package the software. This metadata -file contains a list of CPack components and component groups, the various -options passed to :command:`cpack_add_component` and +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_EXT_PACKAGE_SCRIPT` instead. + +Staging of installation files may also optionally be +taken care of by the generator when enabled through the +:variable:`CPACK_EXT_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. -Format -^^^^^^ - -The file produced by the CPack External generator is a .json file with an -object as its root. This root object will always provide two fields: +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) @@ -247,3 +260,24 @@ Variables specific to CPack External generator If an invalid version is encountered in ``CPACK_EXT_REQUESTED_VERSIONS`` (one that doesn't match ``major.minor``, where ``major`` and ``minor`` are integers), it is ignored. + +.. variable:: CPACK_EXT_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_EXT_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/wix.rst b/Help/cpack_gen/wix.rst index 3822fa0..fc8a098 100644 --- a/Help/cpack_gen/wix.rst +++ b/Help/cpack_gen/wix.rst @@ -214,8 +214,8 @@ Windows using WiX. If this variable is set the generated installer will create an entry in the windows registry key - ``HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<package>`` - The value for ``<package>`` is provided by this variable. + ``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 diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index 32e8cfc..f05c4b1 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-packages.7.rst b/Help/manual/cmake-packages.7.rst index c9442bc..876ca84 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-properties.7.rst b/Help/manual/cmake-properties.7.rst index c9a38fc..8ccd7f6 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -301,6 +301,7 @@ 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 diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 4ddbfe5..3eea8a2 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -401,6 +401,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 diff --git a/Help/prop_dir/LINK_OPTIONS.rst b/Help/prop_dir/LINK_OPTIONS.rst index 04b9e08..15c555f 100644 --- a/Help/prop_dir/LINK_OPTIONS.rst +++ b/Help/prop_dir/LINK_OPTIONS.rst @@ -1,7 +1,8 @@ LINK_OPTIONS ------------ -List of options to use for the link step. +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. diff --git a/Help/prop_tgt/LINK_FLAGS.rst b/Help/prop_tgt/LINK_FLAGS.rst index e0b72b5..92cd3c0 100644 --- a/Help/prop_tgt/LINK_FLAGS.rst +++ b/Help/prop_tgt/LINK_FLAGS.rst @@ -1,11 +1,14 @@ 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, 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``, +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:: diff --git a/Help/prop_tgt/LINK_FLAGS_CONFIG.rst b/Help/prop_tgt/LINK_FLAGS_CONFIG.rst index 1f2910b..e3918ca 100644 --- a/Help/prop_tgt/LINK_FLAGS_CONFIG.rst +++ b/Help/prop_tgt/LINK_FLAGS_CONFIG.rst @@ -1,9 +1,10 @@ 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:: diff --git a/Help/prop_tgt/LINK_OPTIONS.rst b/Help/prop_tgt/LINK_OPTIONS.rst index c5263a2..bd5e937 100644 --- a/Help/prop_tgt/LINK_OPTIONS.rst +++ b/Help/prop_tgt/LINK_OPTIONS.rst @@ -1,7 +1,10 @@ LINK_OPTIONS ------------ -List of options to use when linking this target. +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` diff --git a/Help/prop_tgt/STATIC_LIBRARY_FLAGS.rst b/Help/prop_tgt/STATIC_LIBRARY_FLAGS.rst index d3b2cd4..66e0e8b 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 cca353d..5b97941 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 0000000..6e03185 --- /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/release/dev/STATIC_LIBRARY_OPTIONS.rst b/Help/release/dev/STATIC_LIBRARY_OPTIONS.rst new file mode 100644 index 0000000..087dc76 --- /dev/null +++ b/Help/release/dev/STATIC_LIBRARY_OPTIONS.rst @@ -0,0 +1,4 @@ +STATIC_LIBRARY_OPTIONS +---------------------- + +* static library targets gained new :prop_tgt:`STATIC_LIBRARY_OPTIONS` property. diff --git a/Help/variable/CMAKE_ANDROID_STL_TYPE.rst b/Help/variable/CMAKE_ANDROID_STL_TYPE.rst index cfb76aa..d174575 100644 --- a/Help/variable/CMAKE_ANDROID_STL_TYPE.rst +++ b/Help/variable/CMAKE_ANDROID_STL_TYPE.rst @@ -30,7 +30,8 @@ set to specify the STL variant to be used. The value may be one of: ``stlport_shared`` STLport Shared -The default value is ``gnustl_static``. Note that this default differs from +The default value is ``gnustl_static`` on NDK versions that provide it +and otherwise ``c++_static``. Note that this default differs from the native NDK build system because CMake may be used to build projects for Android that are not natively implemented for it and use the C++ standard library. diff --git a/Help/variable/CMAKE_LANG_CLANG_TIDY.rst b/Help/variable/CMAKE_LANG_CLANG_TIDY.rst index d1fccbb..bd49de3 100644 --- a/Help/variable/CMAKE_LANG_CLANG_TIDY.rst +++ b/Help/variable/CMAKE_LANG_CLANG_TIDY.rst @@ -9,5 +9,5 @@ created. For example: .. code-block:: cmake - set(CMAKE_CXX_CLANG_TIDY clang-tidy checks=-*,readability-*) + set(CMAKE_CXX_CLANG_TIDY clang-tidy -checks=-*,readability-*) add_executable(foo foo.cxx) 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 0000000..2ba8fe2 --- /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. |