summaryrefslogtreecommitdiffstats
path: root/Help/manual
diff options
context:
space:
mode:
Diffstat (limited to 'Help/manual')
-rw-r--r--Help/manual/OPTIONS_BUILD.txt15
-rw-r--r--Help/manual/cmake-buildsystem.7.rst80
-rw-r--r--Help/manual/cmake-compile-features.7.rst16
-rw-r--r--Help/manual/cmake-developer.7.rst29
-rw-r--r--Help/manual/cmake-generator-expressions.7.rst54
-rw-r--r--Help/manual/cmake-generators.7.rst27
-rw-r--r--Help/manual/cmake-language.7.rst4
-rw-r--r--Help/manual/cmake-modules.7.rst3
-rw-r--r--Help/manual/cmake-packages.7.rst178
-rw-r--r--Help/manual/cmake-policies.7.rst7
-rw-r--r--Help/manual/cmake-properties.7.rst23
-rw-r--r--Help/manual/cmake-variables.7.rst11
-rw-r--r--Help/manual/cmake.1.rst6
-rw-r--r--Help/manual/ctest.1.rst22
14 files changed, 355 insertions, 120 deletions
diff --git a/Help/manual/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt
index 363d0aa..4207db4 100644
--- a/Help/manual/OPTIONS_BUILD.txt
+++ b/Help/manual/OPTIONS_BUILD.txt
@@ -10,7 +10,7 @@
containing SET commands that use the CACHE option, not a
cache-format file.
-``-D <var>:<type>=<value>``
+``-D <var>:<type>=<value>, -D <var>=<value>``
Create a cmake cache entry.
When cmake is first run in an empty build tree, it creates a
@@ -19,6 +19,17 @@
takes priority over the project's default value. The option may be
repeated for as many cache entries as desired.
+ If the ``:<type>`` portion is given it must be one of the types
+ specified by the :command:`set` command documentation for its
+ ``CACHE`` signature.
+ If the ``:<type>`` portion is omitted the entry will be created
+ with no type if it does not exist with a type already. If a
+ command in the project sets the type to ``PATH`` or ``FILEPATH``
+ then the ``<value>`` will be converted to an absolute path.
+
+ This option may also be given as a single argument:
+ ``-D<var>:<type>=<value>`` or ``-D<var>=<value>``.
+
``-U <globbing_expr>``
Remove matching entries from CMake cache.
@@ -35,7 +46,7 @@
CMake may support multiple native build systems on certain
platforms. A generator is responsible for generating a particular
build system. Possible generator names are specified in the
- Generators section.
+ :manual:`cmake-generators(7)` manual.
``-T <toolset-name>``
Specify toolset name if supported by generator.
diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst
index 002f2c2..c456590 100644
--- a/Help/manual/cmake-buildsystem.7.rst
+++ b/Help/manual/cmake-buildsystem.7.rst
@@ -143,6 +143,11 @@ use particular :prop_tgt:`COMPILE_OPTIONS` or
the properties must be **requirements**, not merely recommendations or
convenience.
+See the :ref:`Creating Relocatable Packages` section of the
+:manual:`cmake-packages(7)` manual for discussion of additional care
+that must be taken when specifying usage requirements while creating
+packages for redistribution.
+
Target Properties
-----------------
@@ -690,8 +695,10 @@ edge of linking ``exe1`` is determined by the same
:prop_tgt:`POSITION_INDEPENDENT_CODE` property, the dependency graph above
contains a cycle. :manual:`cmake(1)` issues a diagnostic in this case.
-Output Files
-------------
+.. _`Output Artifacts`:
+
+Output Artifacts
+----------------
The buildsystem targets created by the :command:`add_library` and
:command:`add_executable` commands create rules to create binary outputs.
@@ -703,6 +710,71 @@ name and location of generated binaries. These expressions do not work
for ``OBJECT`` libraries however, as there is no single file generated
by such libraries which is relevant to the expressions.
+There are three kinds of output artifacts that may be build by targets
+as detailed in the following sections. Their classification differs
+between DLL platforms and non-DLL platforms. All Windows-based
+systems including Cygwin are DLL platforms.
+
+.. _`Runtime Output Artifacts`:
+
+Runtime Output Artifacts
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+A *runtime* output artifact of a buildsystem target may be:
+
+* The executable file (e.g. ``.exe``) of an executable target
+ created by the :command:`add_executable` command.
+
+* On DLL platforms: the executable file (e.g. ``.dll``) of a shared
+ library target created by the :command:`add_library` command
+ with the ``SHARED`` option.
+
+The :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` and :prop_tgt:`RUNTIME_OUTPUT_NAME`
+target properties may be used to control runtime output artifact locations
+and names in the build tree.
+
+.. _`Library Output Artifacts`:
+
+Library Output Artifacts
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+A *library* output artifact of a buildsystem target may be:
+
+* The loadable module file (e.g. ``.dll`` or ``.so``) of a module
+ library target created by the :command:`add_library` command
+ 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`
+ command with the ``SHARED`` option.
+
+The :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY` and :prop_tgt:`LIBRARY_OUTPUT_NAME`
+target properties may be used to control library output artifact locations
+and names in the build tree.
+
+.. _`Archive Output Artifacts`:
+
+Archive Output Artifacts
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+An *archive* output artifact of a buildsystem target may be:
+
+* The static library file (e.g. ``.lib`` or ``.a``) of a static
+ library target created by the :command:`add_library` command
+ with the ``STATIC`` option.
+
+* On DLL platforms: the import library file (e.g. ``.lib``) of a shared
+ library target created by the :command:`add_library` command
+ with the ``SHARED`` option.
+
+* On DLL platforms: the import library file (e.g. ``.lib``) of an
+ executable target created by the :command:`add_executable` command
+ when its :prop_tgt:`ENABLE_EXPORTS` target property is set.
+
+The :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY` and :prop_tgt:`ARCHIVE_OUTPUT_NAME`
+target properties may be used to control archive output artifact locations
+and names in the build tree.
+
Directory-Scoped Commands
-------------------------
@@ -814,9 +886,9 @@ It may specify usage requirements such as
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`,
:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`,
:prop_tgt:`INTERFACE_COMPILE_OPTIONS`,
-:prop_tgt:`INTERFACE_LINK_LIBRARIES`, and
+:prop_tgt:`INTERFACE_LINK_LIBRARIES`,
:prop_tgt:`INTERFACE_SOURCES`,
-:prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE`.
+and :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE`.
Only the ``INTERFACE`` modes of the :command:`target_include_directories`,
:command:`target_compile_definitions`, :command:`target_compile_options`,
:command:`target_sources`, and :command:`target_link_libraries` commands
diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst
index 7a6c249..caf5bac 100644
--- a/Help/manual/cmake-compile-features.7.rst
+++ b/Help/manual/cmake-compile-features.7.rst
@@ -278,7 +278,7 @@ properties:
add_library(foo INTERFACE)
set(with_variadics ${CMAKE_CURRENT_SOURCE_DIR}/with_variadics)
set(no_variadics ${CMAKE_CURRENT_SOURCE_DIR}/no_variadics)
- target_link_libraries(foo
+ target_include_directories(foo
INTERFACE
"$<$<COMPILE_FEATURES:cxx_variadic_templates>:${with_variadics}>"
"$<$<NOT:$<COMPILE_FEATURES:cxx_variadic_templates>>:${no_variadics}>"
@@ -295,3 +295,17 @@ the feature-appropriate include directory
add_executable(consumer_no consumer_no.cpp)
target_link_libraries(consumer_no foo)
+
+Supported Compilers
+===================
+
+CMake is currently aware of the :prop_tgt:`language standards <CXX_STANDARD>`
+and :prop_gbl:`compile features <CMAKE_CXX_KNOWN_FEATURES>` available from
+the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the
+versions specified for each:
+
+* ``AppleClang``: Apple Clang for Xcode versions 4.4 though 6.2.
+* ``Clang``: Clang compiler versions 2.9 through 3.4.
+* ``GNU``: GNU compiler versions 4.4 through 5.0.
+* ``MSVC``: Microsoft Visual Studio versions 2010 through 2015.
+* ``SunPro``: Oracle SolarisStudio version 12.4.
diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst
index e18250c..ab74140 100644
--- a/Help/manual/cmake-developer.7.rst
+++ b/Help/manual/cmake-developer.7.rst
@@ -28,34 +28,6 @@ Some implementations have a ``std::auto_ptr`` which can not be used as a
return value from a function. ``std::auto_ptr`` may not be used. Use
``cmsys::auto_ptr`` instead.
-Template Parameter Defaults
----------------------------
-
-On ancient compilers, C++ template must use template parameters in function
-arguments. If no parameter of that type is needed, the common workaround is
-to add a defaulted pointer to the type to the templated function. However,
-this does not work with other ancient compilers:
-
-.. code-block:: c++
-
- template<typename PropertyType>
- PropertyType getTypedProperty(cmTarget* tgt, const char* prop,
- PropertyType* = 0) // Wrong
- {
-
- }
-
-.. code-block:: c++
-
- template<typename PropertyType>
- PropertyType getTypedProperty(cmTarget* tgt, const char* prop,
- PropertyType*) // Ok
- {
-
- }
-
-and invoke it with the value ``0`` explicitly in all cases.
-
size_t
------
@@ -633,6 +605,7 @@ have a .cmake file in this directory NOT show up in the modules
documentation, simply leave out the ``Help/module/<module-name>.rst``
file and the ``Help/manual/cmake-modules.7.rst`` toctree entry.
+.. _`Find Modules`:
Find Modules
------------
diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst
index c47a7c4..189c3ef 100644
--- a/Help/manual/cmake-generator-expressions.7.rst
+++ b/Help/manual/cmake-generator-expressions.7.rst
@@ -40,10 +40,6 @@ otherwise expands to nothing.
Available logical expressions are:
-``$<0:...>``
- Empty string (ignores ``...``)
-``$<1:...>``
- Content of ``...``
``$<BOOL:...>``
``1`` if the ``...`` is true, else ``0``
``$<AND:?[,?]...>``
@@ -92,7 +88,47 @@ Available logical expressions are:
increases the required :prop_tgt:`C_STANDARD` or :prop_tgt:`CXX_STANDARD`
for the 'head' target, an error is reported. See the
:manual:`cmake-compile-features(7)` manual for information on
- compile features.
+ compile features and a list of supported compilers.
+``$<COMPILE_LANGUAGE:lang>``
+ ``1`` when the language used for compilation unit matches ``lang``,
+ otherwise ``0``. This expression used to specify compile options for
+ source files of a particular language in a target. For example, to specify
+ the use of the ``-fno-exceptions`` compile option (compiler id checks
+ elided):
+
+ .. code-block:: cmake
+
+ add_executable(myapp main.cpp foo.c bar.cpp)
+ target_compile_options(myapp
+ PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions>
+ )
+
+ This generator expression has limited use because it is not possible to
+ use it with the Visual Studio generators. Portable buildsystems would
+ not use this expression, and would create separate libraries for each
+ source file language instead:
+
+ .. code-block:: cmake
+
+ add_library(myapp_c foo.c)
+ add_library(myapp_cxx foo.c)
+ target_compile_options(myapp_cxx PUBLIC -fno-exceptions)
+ add_executable(myapp main.cpp)
+ target_link_libraries(myapp myapp_c myapp_cxx)
+
+ The ``Makefile`` and ``Ninja`` based generators can also use this
+ expression to specify compile-language specific compile definitions
+ and include directories:
+
+ .. code-block:: cmake
+
+ add_executable(myapp main.cpp foo.c bar.cpp)
+ target_compile_definitions(myapp
+ PRIVATE $<$<COMPILE_LANGUAGE:CXX>:COMPILING_CXX>
+ )
+ target_include_directories(myapp
+ PRIVATE $<$<COMPILE_LANGUAGE:CXX>:/opt/foo/cxx_headers>
+ )
Informational Expressions
=========================
@@ -174,6 +210,10 @@ Available informational expressions are:
``$<INSTALL_PREFIX>``
Content of the install prefix when the target is exported via
:command:`install(EXPORT)` and empty otherwise.
+``$<COMPILE_LANGUAGE>``
+ The compile language of source files when evaluating compile options. See
+ the unary version for notes about portability of this generator
+ expression.
Output Expressions
==================
@@ -197,6 +237,10 @@ where ``${prop}`` refers to a helper variable::
Available output expressions are:
+``$<0:...>``
+ Empty string (ignores ``...``)
+``$<1:...>``
+ Content of ``...``
``$<JOIN:list,...>``
Joins the list with the content of ``...``
``$<ANGLE-R>``
diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst
index bda7eef..cde8de8 100644
--- a/Help/manual/cmake-generators.7.rst
+++ b/Help/manual/cmake-generators.7.rst
@@ -34,6 +34,11 @@ These generators support command-line build tools. In order to use them,
one must launch CMake from a command-line prompt whose environment is
already configured for the chosen compiler and build tool.
+.. _`Makefile Generators`:
+
+Makefile Generators
+^^^^^^^^^^^^^^^^^^^
+
.. toctree::
:maxdepth: 1
@@ -42,10 +47,17 @@ already configured for the chosen compiler and build tool.
/generator/MinGW Makefiles
/generator/NMake Makefiles
/generator/NMake Makefiles JOM
- /generator/Ninja
/generator/Unix Makefiles
/generator/Watcom WMake
+Ninja Generator
+^^^^^^^^^^^^^^^
+
+.. toctree::
+ :maxdepth: 1
+
+ /generator/Ninja
+
IDE Build Tool Generators
-------------------------
@@ -53,6 +65,11 @@ These generators support Integrated Development Environment (IDE)
project files. Since the IDEs configure their own environment
one may launch CMake from any environment.
+.. _`Visual Studio Generators`:
+
+Visual Studio Generators
+^^^^^^^^^^^^^^^^^^^^^^^^
+
.. toctree::
:maxdepth: 1
@@ -65,6 +82,14 @@ one may launch CMake from any environment.
/generator/Visual Studio 11 2012
/generator/Visual Studio 12 2013
/generator/Visual Studio 14 2015
+
+Other Generators
+^^^^^^^^^^^^^^^^
+
+.. toctree::
+ :maxdepth: 1
+
+ /generator/Green Hills MULTI
/generator/Xcode
Extra Generators
diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst
index 3e0297c..41542c9 100644
--- a/Help/manual/cmake-language.7.rst
+++ b/Help/manual/cmake-language.7.rst
@@ -485,6 +485,8 @@ The :command:`macro`/:command:`endmacro`, and
:command:`function`/:command:`endfunction` commands delimit
code blocks to be recorded for later invocation as commands.
+.. _`CMake Language Variables`:
+
Variables
=========
@@ -538,6 +540,8 @@ The :manual:`cmake-variables(7)` manual documents many variables
that are provided by CMake or have meaning to CMake when set
by project code.
+.. _`CMake Language Lists`:
+
Lists
=====
diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst
index db56010..c9219d5 100644
--- a/Help/manual/cmake-modules.7.rst
+++ b/Help/manual/cmake-modules.7.rst
@@ -22,6 +22,7 @@ All Modules
/module/CheckCXXSourceCompiles
/module/CheckCXXSourceRuns
/module/CheckCXXSymbolExists
+ /module/CheckFortranCompilerFlag
/module/CheckFortranFunctionExists
/module/CheckFortranSourceCompiles
/module/CheckFunctionExists
@@ -126,7 +127,6 @@ All Modules
/module/FindJava
/module/FindJNI
/module/FindJPEG
- /module/FindJsonCpp
/module/FindKDE3
/module/FindKDE4
/module/FindLAPACK
@@ -212,6 +212,7 @@ All Modules
/module/FindWish
/module/FindwxWidgets
/module/FindwxWindows
+ /module/FindXCTest
/module/FindXercesC
/module/FindX11
/module/FindXMLRPC
diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst
index 3367ba4..b9073a5 100644
--- a/Help/manual/cmake-packages.7.rst
+++ b/Help/manual/cmake-packages.7.rst
@@ -373,38 +373,6 @@ attempt to use version 3 together with version 4. Packages can choose to
employ such a pattern if different major versions of the package are designed
to be incompatible.
-Note that it is not advisable to populate any properties which may contain
-paths, such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and
-:prop_tgt:`INTERFACE_LINK_LIBRARIES`, with paths relevnt to dependencies.
-That would hard-code into installed packages the include directory or library
-paths for dependencies **as found on the machine the package was made on**.
-
-That is, code like this is incorrect for targets which will be used to
-generate config file packages:
-
-.. code-block:: cmake
-
- target_link_libraries(ClimbingStats INTERFACE
- ${Boost_LIBRARIES};${OtherDep_LIBRARIES}>
- )
- target_include_directories(ClimbingStats INTERFACE
- $<INSTALL_INTERFACE:${Boost_INCLUDE_DIRS};${OtherDep_INCLUDE_DIRS}>
- )
-
-Dependencies must provide their own :ref:`IMPORTED targets <Imported Targets>`
-which have their own :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and
-:prop_tgt:`IMPORTED_LOCATION` populated appropriately. Those
-:ref:`IMPORTED targets <Imported Targets>` may then be
-used with the :command:`target_link_libraries` command for ``ClimbingStats``.
-
-That way, when a consumer uses the installed package, the
-consumer will run the appropriate :command:`find_package` command (via the
-find_dependency macro described below) to find
-the dependencies on their own machine and populate the
-:ref:`IMPORTED targets <Imported Targets>` with appropriate paths. Note that
-many modules currently shipped with CMake do not currently provide
-:ref:`IMPORTED targets <Imported Targets>`.
-
A ``NAMESPACE`` with double-colons is specified when exporting the targets
for installation. This convention of double-colons gives CMake a hint that
the name is an :prop_tgt:`IMPORTED` target when it is used by downstreams
@@ -418,6 +386,9 @@ directory in the :variable:`CMAKE_INSTALL_PREFIX`. When the ``IMPORTED``
target is used by downsteam, it automatically consumes the entries from
that property.
+Creating a Package Configuration File
+-------------------------------------
+
In this case, the ``ClimbingStatsConfig.cmake`` file could be as simple as:
.. code-block:: cmake
@@ -429,44 +400,6 @@ should be provided by the ``ClimbingStats`` package, they should
be in a separate file which is installed to the same location as the
``ClimbingStatsConfig.cmake`` file, and included from there.
-Packages created by :command:`install(EXPORT)` are designed to be relocatable,
-using paths relative to the location of the package itself. When defining
-the interface of a target for ``EXPORT``, keep in mind that the include
-directories should be specified as relative paths which are relative to the
-:variable:`CMAKE_INSTALL_PREFIX`:
-
-.. code-block:: cmake
-
- target_include_directories(tgt INTERFACE
- # Wrong, not relocatable:
- $<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/include/TgtName>
- )
-
- target_include_directories(tgt INTERFACE
- # Ok, relocatable:
- $<INSTALL_INTERFACE:include/TgtName>
- )
-
-The ``$<INSTALL_PREFIX>``
-:manual:`generator expression <cmake-generator-expressions(7)>` may be used as
-a placeholder for the install prefix without resulting in a non-relocatable
-package. This is necessary if complex generator expressions are used:
-
-.. code-block:: cmake
-
- target_include_directories(tgt INTERFACE
- # Ok, relocatable:
- $<INSTALL_INTERFACE:$<$<CONFIG:Debug>:$<INSTALL_PREFIX>/include/TgtName>>
- )
-
-The :command:`export(EXPORT)` command creates an :prop_tgt:`IMPORTED` targets
-definition file which is specific to the build-tree, and is not relocatable.
-This can similiarly be used with a suitable package configuration file and
-package version file to define a package for the build tree which may be used
-without installation. Consumers of the build tree can simply ensure that the
-:variable:`CMAKE_PREFIX_PATH` contains the build directory, or set the
-``ClimbingStats_DIR`` to ``<build_dir>/ClimbingStats`` in the cache.
-
This can also be extended to cover dependencies:
.. code-block:: cmake
@@ -526,6 +459,111 @@ could not be found because an invalid component was specified. This message
variable can be set for any case where the ``_FOUND`` variable is set to ``False``,
and will be displayed to the user.
+Creating a Package Configuration File for the Build Tree
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :command:`export(EXPORT)` command creates an :prop_tgt:`IMPORTED` targets
+definition file which is specific to the build-tree, and is not relocatable.
+This can similiarly be used with a suitable package configuration file and
+package version file to define a package for the build tree which may be used
+without installation. Consumers of the build tree can simply ensure that the
+:variable:`CMAKE_PREFIX_PATH` contains the build directory, or set the
+``ClimbingStats_DIR`` to ``<build_dir>/ClimbingStats`` in the cache.
+
+.. _`Creating Relocatable Packages`:
+
+Creating Relocatable Packages
+-----------------------------
+
+A relocatable package must not reference absolute paths of files on
+the machine where the package is built that will not exist on the
+machines where the package may be installed.
+
+Packages created by :command:`install(EXPORT)` are designed to be relocatable,
+using paths relative to the location of the package itself. When defining
+the interface of a target for ``EXPORT``, keep in mind that the include
+directories should be specified as relative paths which are relative to the
+:variable:`CMAKE_INSTALL_PREFIX`:
+
+.. code-block:: cmake
+
+ target_include_directories(tgt INTERFACE
+ # Wrong, not relocatable:
+ $<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/include/TgtName>
+ )
+
+ target_include_directories(tgt INTERFACE
+ # Ok, relocatable:
+ $<INSTALL_INTERFACE:include/TgtName>
+ )
+
+The ``$<INSTALL_PREFIX>``
+:manual:`generator expression <cmake-generator-expressions(7)>` may be used as
+a placeholder for the install prefix without resulting in a non-relocatable
+package. This is necessary if complex generator expressions are used:
+
+.. code-block:: cmake
+
+ target_include_directories(tgt INTERFACE
+ # Ok, relocatable:
+ $<INSTALL_INTERFACE:$<$<CONFIG:Debug>:$<INSTALL_PREFIX>/include/TgtName>>
+ )
+
+This also applies to paths referencing external dependencies.
+It is not advisable to populate any properties which may contain
+paths, such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and
+:prop_tgt:`INTERFACE_LINK_LIBRARIES`, with paths relevant to dependencies.
+For example, this code may not work well for a relocatable package:
+
+.. code-block:: cmake
+
+ target_link_libraries(ClimbingStats INTERFACE
+ ${Foo_LIBRARIES} ${Bar_LIBRARIES}
+ )
+ target_include_directories(ClimbingStats INTERFACE
+ "$<INSTALL_INTERFACE:${Foo_INCLUDE_DIRS};${Bar_INCLUDE_DIRS}>"
+ )
+
+The referenced variables may contain the absolute paths to libraries
+and include directories **as found on the machine the package was made on**.
+This would create a package with hard-coded paths to dependencies and not
+suitable for relocation.
+
+Ideally such dependencies should be used through their own
+:ref:`IMPORTED targets <Imported Targets>` that have their own
+:prop_tgt:`IMPORTED_LOCATION` and usage requirement properties
+such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` populated
+appropriately. Those imported targets may then be used with
+the :command:`target_link_libraries` command for ``ClimbingStats``:
+
+.. code-block:: cmake
+
+ target_link_libraries(ClimbingStats INTERFACE Foo::Foo Bar::Bar)
+
+With this approach the package references its external dependencies
+only through the names of :ref:`IMPORTED targets <Imported Targets>`.
+When a consumer uses the installed package, the consumer will run the
+appropriate :command:`find_package` commands (via the ``find_dependency``
+macro described above) to find the dependencies and populate the
+imported targets with appropriate paths on their own machine.
+
+Unfortunately many :manual:`modules <cmake-modules(7)>` shipped with
+CMake do not yet provide :ref:`IMPORTED targets <Imported Targets>`
+because their development pre-dated this approach. This may improve
+incrementally over time. Workarounds to create relocatable packages
+using such modules include:
+
+* When building the package, specify each ``Foo_LIBRARY`` cache
+ entry as just a library name, e.g. ``-DFoo_LIBRARY=foo``. This
+ tells the corresponding find module to populate the ``Foo_LIBRARIES``
+ with just ``foo`` to ask the linker to search for the library
+ instead of hard-coding a path.
+
+* Or, after installing the package content but before creating the
+ package installation binary for redistribution, manually replace
+ the absolute paths with placeholders for substitution by the
+ installation tool when the package is installed.
+
.. _`Package Registry`:
Package Registry
diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index 96f39e6..c5970bb 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -114,3 +114,10 @@ All Policies
/policy/CMP0054
/policy/CMP0055
/policy/CMP0056
+ /policy/CMP0057
+ /policy/CMP0058
+ /policy/CMP0059
+ /policy/CMP0060
+ /policy/CMP0061
+ /policy/CMP0062
+ /policy/CMP0063
diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst
index 25f989f..615254e 100644
--- a/Help/manual/cmake-properties.7.rst
+++ b/Help/manual/cmake-properties.7.rst
@@ -7,6 +7,8 @@ cmake-properties(7)
.. contents::
+.. _`Global Properties`:
+
Properties of Global Scope
==========================
@@ -41,6 +43,8 @@ Properties of Global Scope
/prop_gbl/TARGET_SUPPORTS_SHARED_LIBS
/prop_gbl/USE_FOLDERS
+.. _`Directory Properties`:
+
Properties on Directories
=========================
@@ -72,6 +76,8 @@ Properties on Directories
/prop_dir/VS_GLOBAL_SECTION_POST_section
/prop_dir/VS_GLOBAL_SECTION_PRE_section
+.. _`Target Properties`:
+
Properties on Targets
=====================
@@ -113,6 +119,7 @@ Properties on Targets
/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG
/prop_tgt/CONFIG_OUTPUT_NAME
/prop_tgt/CONFIG_POSTFIX
+ /prop_tgt/CROSSCOMPILING_EMULATOR
/prop_tgt/CXX_EXTENSIONS
/prop_tgt/CXX_STANDARD
/prop_tgt/CXX_STANDARD_REQUIRED
@@ -170,6 +177,7 @@ Properties on Targets
/prop_tgt/JOB_POOL_COMPILE
/prop_tgt/JOB_POOL_LINK
/prop_tgt/LABELS
+ /prop_tgt/LANG_INCLUDE_WHAT_YOU_USE
/prop_tgt/LANG_VISIBILITY_PRESET
/prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG
/prop_tgt/LIBRARY_OUTPUT_DIRECTORY
@@ -243,6 +251,9 @@ Properties on Targets
/prop_tgt/VS_WINRT_REFERENCES
/prop_tgt/WIN32_EXECUTABLE
/prop_tgt/XCODE_ATTRIBUTE_an-attribute
+ /prop_tgt/XCTEST
+
+.. _`Test Properties`:
Properties on Tests
===================
@@ -268,6 +279,8 @@ Properties on Tests
/prop_test/WILL_FAIL
/prop_test/WORKING_DIRECTORY
+.. _`Source File Properties`:
+
Properties on Source Files
==========================
@@ -297,10 +310,13 @@ Properties on Source Files
/prop_sf/VS_SHADER_FLAGS
/prop_sf/VS_SHADER_MODEL
/prop_sf/VS_SHADER_TYPE
+ /prop_sf/VS_XAML_TYPE
/prop_sf/WRAP_EXCLUDE
/prop_sf/XCODE_EXPLICIT_FILE_TYPE
/prop_sf/XCODE_LAST_KNOWN_FILE_TYPE
+.. _`Cache Entry Properties`:
+
Properties on Cache Entries
===========================
@@ -314,19 +330,24 @@ Properties on Cache Entries
/prop_cache/TYPE
/prop_cache/VALUE
+.. _`Installed File Properties`:
+
Properties on Installed Files
=============================
.. toctree::
:maxdepth: 1
+ /prop_inst/CPACK_DESKTOP_SHORTCUTS.rst
/prop_inst/CPACK_NEVER_OVERWRITE.rst
/prop_inst/CPACK_PERMANENT.rst
+ /prop_inst/CPACK_START_MENU_SHORTCUTS.rst
+ /prop_inst/CPACK_STARTUP_SHORTCUTS.rst
/prop_inst/CPACK_WIX_ACL.rst
Deprecated Properties on Directories
-=====================================
+====================================
.. toctree::
:maxdepth: 1
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index c342dbe..bd02f8b 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -25,6 +25,7 @@ Variables that Provide Information
/variable/CMAKE_CFG_INTDIR
/variable/CMAKE_COMMAND
/variable/CMAKE_CROSSCOMPILING
+ /variable/CMAKE_CROSSCOMPILING_EMULATOR
/variable/CMAKE_CTEST_COMMAND
/variable/CMAKE_CURRENT_BINARY_DIR
/variable/CMAKE_CURRENT_LIST_DIR
@@ -181,6 +182,7 @@ Variables that Describe the System
/variable/CMAKE_SYSTEM_VERSION
/variable/CYGWIN
/variable/ENV
+ /variable/GHS-MULTI
/variable/MINGW
/variable/MSVC10
/variable/MSVC11
@@ -211,6 +213,7 @@ Variables that Control the Build
/variable/CMAKE_ANDROID_API_MIN
/variable/CMAKE_ANDROID_GUI
/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY
+ /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG
/variable/CMAKE_AUTOMOC_MOC_OPTIONS
/variable/CMAKE_AUTOMOC
/variable/CMAKE_AUTORCC
@@ -232,8 +235,10 @@ Variables that Control the Build
/variable/CMAKE_INSTALL_NAME_DIR
/variable/CMAKE_INSTALL_RPATH
/variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH
+ /variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE
/variable/CMAKE_LANG_VISIBILITY_PRESET
/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY
+ /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG
/variable/CMAKE_LIBRARY_PATH_FLAG
/variable/CMAKE_LINK_DEF_FILE_FLAG
/variable/CMAKE_LINK_DEPENDS_NO_SHARED
@@ -254,6 +259,7 @@ Variables that Control the Build
/variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG
/variable/CMAKE_POSITION_INDEPENDENT_CODE
/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY
+ /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG
/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG
/variable/CMAKE_SHARED_LINKER_FLAGS
/variable/CMAKE_SKIP_BUILD_RPATH
@@ -263,6 +269,7 @@ Variables that Control the Build
/variable/CMAKE_TRY_COMPILE_CONFIGURATION
/variable/CMAKE_USE_RELATIVE_PATHS
/variable/CMAKE_VISIBILITY_INLINES_HIDDEN
+ /variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD
/variable/CMAKE_WIN32_EXECUTABLE
/variable/CMAKE_XCODE_ATTRIBUTE_an-attribute
/variable/EXECUTABLE_OUTPUT_PATH
@@ -306,6 +313,10 @@ Variables for Languages
/variable/CMAKE_LANG_FLAGS_RELEASE
/variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO
/variable/CMAKE_LANG_FLAGS
+ /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG
+ /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL
+ /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE
+ /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELWITHDEBINFO
/variable/CMAKE_LANG_IGNORE_EXTENSIONS
/variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES
/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES
diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
index da41bbb..4bd5a5e 100644
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@@ -9,7 +9,7 @@ Synopsis
.. parsed-literal::
cmake [<options>] (<path-to-source> | <path-to-existing-build>)
- cmake [(-D<var>=<value>)...] -P <cmake-script-file>
+ cmake [(-D <var>=<value>)...] -P <cmake-script-file>
cmake --build <dir> [<options>] [-- <build-tool-options>...]
cmake -E <command> [<options>...]
cmake --find-package <options>...
@@ -215,6 +215,10 @@ Available commands are:
names start in ``-``.
``--mtime=<date>``
Specify modification time recorded in tarball entries.
+ ``--format=<format>``
+ Specify the format of the archive to be created.
+ Supported formats are: ``7zip``, ``gnutar``, ``pax``,
+ ``paxr`` (restricted pax, default), and ``zip``.
``time <command> [<args>...]``
Run command and return elapsed time.
diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst
index cc132c2..c91321b 100644
--- a/Help/manual/ctest.1.rst
+++ b/Help/manual/ctest.1.rst
@@ -48,7 +48,9 @@ Options
useful for debugging dashboard problems.
``--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
+ 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``.
``-F``
Enable failover.
@@ -62,7 +64,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.
+ environment variable ``CTEST_PARALLEL_LEVEL``.
``-Q,--quiet``
Make ctest quiet.
@@ -194,6 +196,11 @@ Options
subsequent calls to ctest with the --rerun-failed option will run
the set of tests that most recently failed (if any).
+``--repeat-until-fail <n>``
+ Require each test to run ``<n>`` times without failing in order to pass.
+
+ This is useful in finding sporadic failures in test cases.
+
``--max-width <width>``
Set the max width for a test name to output
@@ -365,6 +372,8 @@ Options
.. include:: OPTIONS_HELP.txt
+.. _`Dashboard Client`:
+
Dashboard Client
================
@@ -568,7 +577,7 @@ Configuration settings to specify the version control tool include:
* :module:`CTest` module variable: ``GITCOMMAND``
``GITUpdateCustom``
- Specify a semicolon-separated list of custom command lines to run
+ Specify a custom command line (as a semicolon-separated list) to run
in the source tree (Git work tree) to update it instead of running
the ``GITCommand``.
@@ -612,7 +621,7 @@ Configuration settings to specify the version control tool include:
* :module:`CTest` module variable: ``CTEST_P4_OPTIONS``
``P4UpdateCustom``
- Specify a semicolon-separated list of custom command lines to run
+ Specify a custom command line (as a semicolon-separated list) to run
in the source tree (Perforce tree) to update it instead of running
the ``P4Command``.
@@ -742,8 +751,9 @@ Configuration settings include:
initialized by the :command:`build_command` command
``UseLaunchers``
- For build trees generated by CMake using a Makefile generator
- or the :generator:`Ninja` generator, specify whether the
+ For build trees generated by CMake using one of the
+ :ref:`Makefile Generators` or the :generator:`Ninja`
+ generator, specify whether the
``CTEST_USE_LAUNCHERS`` feature is enabled by the
:module:`CTestUseLaunchers` module (also included by the
:module:`CTest` module). When enabled, the generated build
generated by cgit v0.12 at 2025-01-25 17:08:36 (GMT)