Lubuntu
/
cmake
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

New upstream version 3.26.4

Browse Source
ci/unstable
Timo Röhling 2 years ago
parent b61d7a265d
commit e6386a5b13
1502 changed files with 29777 additions and 13838 deletions
Show Stats Download Patch File Download Diff File

2
.clang-format
Unescape View File

@ -1,5 +1,5 @@
---
# This configuration requires clang-format version 6.0 exactly.
# This configuration requires clang-format version 15 exactly.
BasedOnStyle: Mozilla
AlignOperands: false
AllowShortFunctionsOnASingleLine: InlineOnly

13
.clang-tidy
Unescape View File

@ -1,24 +1,31 @@
---
Checks: "-*,\
bugprone-*,\
-bugprone-assignment-in-if-condition,\
-bugprone-easily-swappable-parameters,\
-bugprone-implicit-widening-of-multiplication-result,\
-bugprone-macro-parentheses,\
-bugprone-misplaced-widening-cast,\
-bugprone-narrowing-conversions,\
-bugprone-too-small-loop-variable,\
-bugprone-unchecked-optional-access,\
misc-*,\
-misc-confusable-identifiers,\
-misc-const-correctness,\
-misc-no-recursion,\
-misc-non-private-member-variables-in-classes,\
-misc-static-assert,\
modernize-*,\
-modernize-avoid-c-arrays,\
-modernize-macro-to-enum,\
-modernize-return-braced-init-list,\
-modernize-use-emplace,\
-modernize-use-nodiscard,\
-modernize-use-noexcept,\
-modernize-use-trailing-return-type,\
-modernize-use-transparent-functors,\
performance-*,\
-performance-inefficient-vector-operation,\
readability-*,\
-readability-convert-member-functions-to-static,\
-readability-function-cognitive-complexity,\
@ -28,11 +35,17 @@ readability-*,\
-readability-implicit-bool-conversion,\
-readability-inconsistent-declaration-parameter-name,\
-readability-magic-numbers,\
-readability-make-member-function-const,\
-readability-named-parameter,\
-readability-redundant-declaration,\
-readability-redundant-member-init,\
-readability-simplify-boolean-expr,\
-readability-suspicious-call-argument,\
-readability-uppercase-literal-suffix,\
cmake-*,\
-cmake-ostringstream-use-cmstrcat,\
-cmake-string-concatenation-use-cmstrcat,\
-cmake-use-bespoke-enum-class,\
"
HeaderFilterRegex: 'Source/cm[^/]*\.(h|hxx|cxx)$'
CheckOptions:

1
Auxiliary/vim/syntax/cmake.vim
Unescape View File

@ -2013,6 +2013,7 @@ syn keyword cmakeKWExternalProject contained
\ IGNORED
\ INACTIVITY_TIMEOUT
\ INDEPENDENT_STEP_TARGETS
\ INSTALL_BYPRODUCTS
\ INSTALL_COMMAND
\ INSTALL_DIR
\ JOB_POOLS

4
CMakeCPack.cmake
Unescape View File

@ -264,5 +264,9 @@ set(CPACK_SOURCE_IGNORE_FILES
"~$"
)
if(CMake_CPACK_CUSTOM_SCRIPT)
include(${CMake_CPACK_CUSTOM_SCRIPT})
endif()
# include CPack model once all variables are set
include(CPack)

49
CMakeLists.txt
Unescape View File

@ -1,14 +1,10 @@
# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
# file Copyright.txt or https://cmake.org/licensing for details.
cmake_minimum_required(VERSION 3.13...3.23 FATAL_ERROR)
cmake_minimum_required(VERSION 3.13...3.24 FATAL_ERROR)
set(CMAKE_USER_MAKE_RULES_OVERRIDE_C ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideC.cmake)
set(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideCXX.cmake)
if(POLICY CMP0129)
cmake_policy(SET CMP0129 NEW) # CMake 3.23
endif()
project(CMake)
unset(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX)
unset(CMAKE_USER_MAKE_RULES_OVERRIDE_C)
@ -73,11 +69,7 @@ if(NOT DEFINED CMAKE_CXX_STANDARD AND NOT CMake_NO_CXX_STANDARD)
if(CMAKE_CXX_COMPILER_ID STREQUAL SunPro AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS 5.14)
set(CMAKE_CXX_STANDARD 98)
else()
if(NOT CMAKE_VERSION VERSION_LESS 3.8)
include(${CMake_SOURCE_DIR}/Source/Checks/cm_cxx17_check.cmake)
else()
set(CMake_CXX17_BROKEN 1)
endif()
if(NOT CMake_CXX17_BROKEN)
set(CMAKE_CXX_STANDARD 17)
else()
@ -130,7 +122,6 @@ option(CMake_BUILD_DEVELOPER_REFERENCE
mark_as_advanced(CMake_BUILD_DEVELOPER_REFERENCE)
# option to build using interprocedural optimizations (IPO/LTO)
if(NOT CMAKE_VERSION VERSION_LESS 3.12.2)
option(CMake_BUILD_LTO "Compile CMake with link-time optimization if supported" OFF)
if(CMake_BUILD_LTO)
include(CheckIPOSupported)
@ -139,7 +130,6 @@ if(NOT CMAKE_VERSION VERSION_LESS 3.12.2)
set(CMAKE_INTERPROCEDURAL_OPTIMIZATION TRUE)
endif()
endif()
endif()
#-----------------------------------------------------------------------
# a macro to deal with system libraries, implemented as a macro
@ -251,10 +241,6 @@ macro(CMAKE_SETUP_TESTING)
configure_file(Tests/.NoDartCoverage Tests/.NoDartCoverage)
configure_file(Tests/.NoDartCoverage Modules/.NoDartCoverage)
configure_file(CTestCustom.cmake.in CTestCustom.cmake @ONLY)
if(BUILD_TESTING AND DART_ROOT)
configure_file(CMakeLogo.gif Testing/HTML/TestingResults/Icons/Logo.gif COPYONLY)
endif()
mark_as_advanced(DART_ROOT)
endmacro()
@ -277,6 +263,25 @@ if(CMake_RUN_CLANG_TIDY)
endif()
set(CMAKE_CXX_CLANG_TIDY "${CLANG_TIDY_COMMAND}")
option(CMake_USE_CLANG_TIDY_MODULE "Use CMake's clang-tidy module." OFF)
if(CMake_USE_CLANG_TIDY_MODULE)
find_library(CMake_CLANG_TIDY_MODULE NAMES cmake-clang-tidy-module DOC "Location of the clang-tidy module")
if(NOT CMake_CLANG_TIDY_MODULE)
message(FATAL_ERROR "CMake_USE_CLANG_TIDY_MODULE is ON but cmake-clang-tidy-module is not found!")
endif()
list(APPEND CMAKE_CXX_CLANG_TIDY "--load=${CMake_CLANG_TIDY_MODULE}")
set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS "${CMake_CLANG_TIDY_MODULE}")
endif()
set(CMake_CLANG_TIDY_EXPORT_FIXES_DIR "" CACHE PATH "Directory to put clang-tidy fix files in.")
mark_as_advanced(CMake_CLANG_TIDY_EXPORT_FIXES_DIR)
if(CMake_CLANG_TIDY_EXPORT_FIXES_DIR)
if(NOT IS_ABSOLUTE "${CMake_CLANG_TIDY_EXPORT_FIXES_DIR}")
message(FATAL_ERROR "CMake_CLANG_TIDY_EXPORT_FIXES_DIR must be an absolute path!")
endif()
set(CMAKE_CXX_CLANG_TIDY_EXPORT_FIXES_DIR "${CMake_CLANG_TIDY_EXPORT_FIXES_DIR}")
endif()
# Create a preprocessor definition that depends on .clang-tidy content so
# the compile command will change when .clang-tidy changes. This ensures
# that a subsequent build re-runs clang-tidy on all sources even if they
@ -286,6 +291,11 @@ if(CMake_RUN_CLANG_TIDY)
file(SHA1 ${CMAKE_CURRENT_SOURCE_DIR}/.clang-tidy clang_tidy_sha1)
set(CLANG_TIDY_DEFINITIONS "CLANG_TIDY_SHA1=${clang_tidy_sha1}")
unset(clang_tidy_sha1)
if(CMake_USE_CLANG_TIDY_MODULE)
file(SHA1 "${CMake_CLANG_TIDY_MODULE}" clang_tidy_module_sha1)
list(APPEND CLANG_TIDY_DEFINITIONS "CLANG_TIDY_MODULE_SHA1=${clang_tidy_module_sha1}")
unset(clang_tidy_module_sha1)
endif()
endif()
configure_file(.clang-tidy .clang-tidy COPYONLY)
@ -299,6 +309,11 @@ if(CMake_RUN_IWYU)
endif()
set(CMAKE_CXX_INCLUDE_WHAT_YOU_USE
"${IWYU_COMMAND};-Xiwyu;--mapping_file=${CMake_SOURCE_DIR}/Utilities/IWYU/mapping.imp;-w")
option(CMake_IWYU_VERBOSE "Run include-what-you-use in verbose mode" OFF)
if (CMake_IWYU_VERBOSE)
list(APPEND CMAKE_CXX_INCLUDE_WHAT_YOU_USE
-Xiwyu -v7)
endif ()
list(APPEND CMAKE_CXX_INCLUDE_WHAT_YOU_USE ${CMake_IWYU_OPTIONS})
endif()
@ -342,9 +357,7 @@ endif()
#-----------------------------------------------------------------------
include(Source/CMakeVersion.cmake)
# Include the standard Dart testing module
enable_testing()
include(${CMAKE_ROOT}/Modules/Dart.cmake)
include(CTest)
# Set up test-time configuration.
set_directory_properties(PROPERTIES

5
CompileFlags.cmake
Unescape View File

@ -87,11 +87,6 @@ if (CMAKE_CXX_COMPILER_ID STREQUAL SunPro AND
if (NOT CMAKE_CXX_COMPILER_VERSION VERSION_LESS 5.13)
if (NOT CMAKE_CXX_STANDARD OR CMAKE_CXX_STANDARD EQUAL 98)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++03")
elseif(CMAKE_VERSION VERSION_LESS 3.8.20170502)
# CMake knows how to add this flag for compilation as C++11,
# but has not been taught that SunPro needs it for linking too.
# Add it in a place that will be used for both.
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++11")
endif()
else()
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -library=stlport4")

2
Copyright.txt
Unescape View File

@ -1,5 +1,5 @@
CMake - Cross Platform Makefile Generator
Copyright 2000-2022 Kitware, Inc. and Contributors
Copyright 2000-2023 Kitware, Inc. and Contributors
All rights reserved.
Redistribution and use in source and binary forms, with or without

8
Help/command/DEVICE_LINK_OPTIONS.txt
Unescape View File

@ -7,8 +7,6 @@ Host And Device Specific Link Options
:prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties and policy :policy:`CMP0105`,
the raw options will be delivered to the host and device link steps (wrapped in
``-Xcompiler`` or equivalent for device link). Options wrapped with
``$<DEVICE_LINK:...>``
:manual:`generator expression <cmake-generator-expressions(7)>` will be used
only for the device link step. Options wrapped with ``$<HOST_LINK:...>``
:manual:`generator expression <cmake-generator-expressions(7)>` will be used
only for the host link step.
:genex:`$<DEVICE_LINK:...>` generator expression will be used
only for the device link step. Options wrapped with :genex:`$<HOST_LINK:...>`
generator expression will be used only for the host link step.

6
Help/command/GENEX_NOTE.txt
Unescape View File

@ -0,0 +1,6 @@
.. |more_see_also| replace:: See the :manual:`cmake-buildsystem(7)` manual
for more on defining buildsystem properties.
Arguments to |command_name| may use generator expressions
with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions. |more_see_also|

25
Help/command/SUPPORTED_LANGUAGES.txt
Unescape View File

@ -0,0 +1,25 @@
Supported languages are ``C``, ``CXX`` (i.e. C++), ``CSharp`` (i.e. C#), ``CUDA``,
``OBJC`` (i.e. Objective-C), ``OBJCXX`` (i.e. Objective-C++), ``Fortran``, ``HIP``,
``ISPC``, ``Swift``, ``ASM``, ``ASM_NASM``, ``ASM_MARMASM``, ``ASM_MASM``, and ``ASM-ATT``.
.. versionadded:: 3.8
Added ``CSharp`` and ``CUDA`` support.
.. versionadded:: 3.15
Added ``Swift`` support.
.. versionadded:: 3.16
Added ``OBJC`` and ``OBJCXX`` support.
.. versionadded:: 3.18
Added ``ISPC`` support.
.. versionadded:: 3.21
Added ``HIP`` support.
.. versionadded:: 3.26
Added ``ASM_MARMASM`` support.
If enabling ``ASM``, list it last so that CMake can check whether
compilers for other languages like ``C`` work for assembly too.

14
Help/command/add_compile_definitions.rst
Unescape View File

@ -21,7 +21,13 @@ Function-style definitions are not supported. CMake will automatically
escape the value correctly for the native build system (note that CMake
language syntax may require escapes to specify some values).
Arguments to ``add_compile_definitions`` 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.
.. versionadded:: 3.26
Any leading ``-D`` on an item will be removed.
.. |command_name| replace:: ``add_compile_definitions``
.. include:: GENEX_NOTE.txt
See Also
^^^^^^^^
* The command :command:`target_compile_definitions` adds target-specific definitions.

23
Help/command/add_compile_options.rst
Unescape View File

@ -14,10 +14,8 @@ directory and below.
Arguments
^^^^^^^^^
Arguments to ``add_compile_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.
.. |command_name| replace:: ``add_compile_options``
.. include:: GENEX_NOTE.txt
.. include:: OPTIONS_SHELL.txt
@ -30,22 +28,25 @@ this command is in a compiler-specific conditional clause:
.. code-block:: cmake
if (MSVC)
# warning level 4 and all warnings as errors
add_compile_options(/W4 /WX)
# warning level 4
add_compile_options(/W4)
else()
# lots of warnings and all warnings as errors
add_compile_options(-Wall -Wextra -pedantic -Werror)
# additional warnings
add_compile_options(-Wall -Wextra -Wpedantic)
endif()
To set per-language options, use the :genex:`$<COMPILE_LANGUAGE>`
or :genex:`$<COMPILE_LANGUAGE:languages>` generator expressions.
See Also
^^^^^^^^
This command can be used to add any options. However, for
* This command can be used to add any options. However, for
adding preprocessor definitions and include directories it is recommended
to use the more specific commands :command:`add_compile_definitions`
and :command:`include_directories`.
The command :command:`target_compile_options` adds target-specific options.
* The command :command:`target_compile_options` adds target-specific options.
The source file property :prop_sf:`COMPILE_OPTIONS` adds options to one
* The source file property :prop_sf:`COMPILE_OPTIONS` adds options to one
source file.

79
Help/command/add_custom_command.rst
Unescape View File

@ -31,14 +31,12 @@ This defines a command to generate specified ``OUTPUT`` file(s).
A target created in the same directory (``CMakeLists.txt`` file)
that specifies any output of the custom command as a source file
is given a rule to generate the file using the command at build time.
Do not list the output in more than one independent target that
may build in parallel or the two instances of the rule may conflict
(instead use the :command:`add_custom_target` command to drive the
command and make the other targets depend on that one).
In makefile terms this creates a new target in the following form::
OUTPUT: MAIN_DEPENDENCY DEPENDS
COMMAND
Do not list the output in more than one independent target that
may build in parallel or the instances of the rule may conflict.
Instead, use the :command:`add_custom_target` command to drive the
command and make the other targets depend on that one. See the
`Example: Generating Files for Multiple Targets`_ below.
The options are:
@ -140,6 +138,10 @@ The options are:
Display the given message before the commands are executed at
build time.
.. versionadded:: 3.26
Arguments to ``COMMENT`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.
``DEPENDS``
Specify files on which the command depends. Each argument is converted
to a dependency as follows:
@ -229,15 +231,24 @@ The options are:
``OUTPUT``
Specify the output files the command is expected to produce.
If an output name is a relative path it will be interpreted
relative to the build tree directory corresponding to the
current source directory.
Each output file will be marked with the :prop_sf:`GENERATED`
source file property automatically.
If the output of the custom command is not actually created
as a file on disk it should be marked with the :prop_sf:`SYMBOLIC`
source file property.
If an output file name is a relative path, its absolute path is
determined by interpreting it relative to:
1. the build directory corresponding to the current source directory
(:variable:`CMAKE_CURRENT_BINARY_DIR`), or
2. the current source directory (:variable:`CMAKE_CURRENT_SOURCE_DIR`).
The path in the build directory is preferred unless the path in the
source tree is mentioned as an absolute source file path elsewhere
in the current directory.
.. versionadded:: 3.20
Arguments to ``OUTPUT`` may use a restricted set of
:manual:`generator expressions <cmake-generator-expressions(7)>`.
@ -385,6 +396,49 @@ will re-run whenever ``in.txt`` changes.
where ``<config>`` is the build configuration, and then compile the generated
source as part of a library.
Example: Generating Files for Multiple Targets
""""""""""""""""""""""""""""""""""""""""""""""
If multiple independent targets need the same custom command output,
it must be attached to a single custom target on which they all depend.
Consider the following example:
.. code-block:: cmake
add_custom_command(
OUTPUT table.csv
COMMAND makeTable -i ${CMAKE_CURRENT_SOURCE_DIR}/input.dat
-o table.csv
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/input.dat
VERBATIM)
add_custom_target(generate_table_csv DEPENDS table.csv)
add_custom_command(
OUTPUT foo.cxx
COMMAND genFromTable -i table.csv -case foo -o foo.cxx
DEPENDS table.csv # file-level dependency
generate_table_csv # target-level dependency
VERBATIM)
add_library(foo foo.cxx)
add_custom_command(
OUTPUT bar.cxx
COMMAND genFromTable -i table.csv -case bar -o bar.cxx
DEPENDS table.csv # file-level dependency
generate_table_csv # target-level dependency
VERBATIM)
add_library(bar bar.cxx)
Output ``foo.cxx`` is needed only by target ``foo`` and output ``bar.cxx``
is needed only by target ``bar``, but *both* targets need ``table.csv``,
transitively. Since ``foo`` and ``bar`` are independent targets that may
build concurrently, we prevent them from racing to generate ``table.csv``
by placing its custom command in a separate target, ``generate_table_csv``.
The custom commands generating ``foo.cxx`` and ``bar.cxx`` each specify a
target-level dependency on ``generate_table_csv``, so the targets using them,
``foo`` and ``bar``, will not build until after target ``generate_table_csv``
is built.
.. _`add_custom_command(TARGET)`:
Build Events
@ -490,3 +544,8 @@ Ninja Multi-Config
``add_custom_command`` supports the :generator:`Ninja Multi-Config`
generator's cross-config capabilities. See the generator documentation
for more information.
See Also
^^^^^^^^
* :command:`add_custom_target`

9
Help/command/add_custom_target.rst
Unescape View File

@ -109,6 +109,10 @@ The options are:
Display the given message before the commands are executed at
build time.
.. versionadded:: 3.26
Arguments to ``COMMENT`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.
``DEPENDS``
Reference files and outputs of custom commands created with
:command:`add_custom_command` command calls in the same directory
@ -181,3 +185,8 @@ Ninja Multi-Config
``add_custom_target`` supports the :generator:`Ninja Multi-Config`
generator's cross-config capabilities. See the generator documentation
for more information.
See Also
^^^^^^^^
* :command:`add_custom_command`

7
Help/command/add_definitions.rst
Unescape View File

@ -1,7 +1,7 @@
add_definitions
---------------
Add -D define flags to the compilation of source files.
Add ``-D`` define flags to the compilation of source files.
.. code-block:: cmake
@ -31,5 +31,8 @@ backwards compatibility. See documentation of the
properties for details on adding preprocessor definitions to specific
scopes and configurations.
See the :manual:`cmake-buildsystem(7)` manual for more on defining
See Also
^^^^^^^^
* The :manual:`cmake-buildsystem(7)` manual for more on defining
buildsystem properties.

11
Help/command/add_dependencies.rst
Unescape View File

@ -20,7 +20,12 @@ transitively in its place since the target itself does not build.
.. versionadded:: 3.3
Allow adding dependencies to interface libraries.
See the ``DEPENDS`` option of :command:`add_custom_target` and
See Also
^^^^^^^^
* The ``DEPENDS`` option of :command:`add_custom_target` and
:command:`add_custom_command` commands for adding file-level
dependencies in custom rules. See the :prop_sf:`OBJECT_DEPENDS`
source file property to add file-level dependencies to object files.
dependencies in custom rules.
* The :prop_sf:`OBJECT_DEPENDS` source file property to add
file-level dependencies to object files.

5
Help/command/add_executable.rst
Unescape View File

@ -107,3 +107,8 @@ The ``<name>`` may not be used to modify properties of ``<target>``, that
is, it may not be used as the operand of :command:`set_property`,
:command:`set_target_properties`, :command:`target_link_libraries` etc.
An ``ALIAS`` target may not be installed or exported.
See Also
^^^^^^^^
* :command:`add_library`

13
Help/command/add_library.rst
Unescape View File

@ -83,10 +83,10 @@ Object Libraries
Creates an :ref:`Object Library <Object Libraries>`. An object library
compiles source files but does not archive or link their object files into a
library. Instead other targets created by :command:`add_library` or
library. Instead other targets created by ``add_library`` or
:command:`add_executable` may reference the objects using an expression of the
form ``$<TARGET_OBJECTS:objlib>`` as a source, where ``objlib`` is the
object library name. For example:
form :genex:`$\<TARGET_OBJECTS:objlib\> <TARGET_OBJECTS>` as a source, where
``objlib`` is the object library name. For example:
.. code-block:: cmake
@ -101,7 +101,7 @@ They may contain custom commands generating such sources, but not
``PRE_BUILD``, ``PRE_LINK``, or ``POST_BUILD`` commands. Some native build
systems (such as Xcode) may not like targets that have only object files, so
consider adding at least one real source file to any target that references
``$<TARGET_OBJECTS:objlib>``.
:genex:`$\<TARGET_OBJECTS:objlib\> <TARGET_OBJECTS>`.
.. versionadded:: 3.12
Object libraries can be linked to with :command:`target_link_libraries`.
@ -261,3 +261,8 @@ to modify properties of ``<target>``, that is, it may not be used as the
operand of :command:`set_property`, :command:`set_target_properties`,
:command:`target_link_libraries` etc. An ``ALIAS`` target may not be
installed or exported.
See Also
^^^^^^^^
* :command:`add_executable`

13
Help/command/add_link_options.rst
Unescape View File

@ -23,13 +23,18 @@ exist to add libraries (:command:`target_link_libraries` or
since they do not use a linker. To add archiver or MSVC librarian flags,
see the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property.
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.
.. |command_name| replace:: ``add_link_options``
.. include:: GENEX_NOTE.txt
.. include:: DEVICE_LINK_OPTIONS.txt
.. include:: OPTIONS_SHELL.txt
.. include:: LINK_OPTIONS_LINKER.txt
See Also
^^^^^^^^
* :command:`link_libraries`
* :command:`target_link_libraries`
* :command:`target_link_options`

23
Help/command/add_subdirectory.rst
Unescape View File

@ -7,16 +7,16 @@ Add a subdirectory to the build.
add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL] [SYSTEM])
Adds a subdirectory to the build. The source_dir specifies the
directory in which the source CMakeLists.txt and code files are
located. If it is a relative path it will be evaluated with respect
Adds a subdirectory to the build. The ``source_dir`` specifies the
directory in which the source ``CMakeLists.txt`` and code files are
located. If it is a relative path, it will be evaluated with respect
to the current directory (the typical usage), but it may also be an
absolute path. The ``binary_dir`` specifies the directory in which to
place the output files. If it is a relative path it will be evaluated
place the output files. If it is a relative path, it will be evaluated
with respect to the current output directory, but it may also be an
absolute path. If ``binary_dir`` is not specified, the value of
``source_dir``, before expanding any relative path, will be used (the
typical usage). The CMakeLists.txt file in the specified source
typical usage). The ``CMakeLists.txt`` file in the specified source
directory will be processed immediately by CMake before processing in
the current input file continues beyond this command.
@ -28,15 +28,14 @@ meant for use when the subdirectory contains a separate part of the
project that is useful but not necessary, such as a set of examples.
Typically the subdirectory should contain its own :command:`project`
command invocation so that a full build system will be generated in the
subdirectory (such as a VS IDE solution file). Note that inter-target
dependencies supersede this exclusion. If a target built by the
parent project depends on a target in the subdirectory, the dependee
subdirectory (such as a Visual Studio IDE solution file). Note that
inter-target dependencies supersede this exclusion. If a target built by
the parent project depends on a target in the subdirectory, the dependee
target will be included in the parent project build system to satisfy
the dependency.
.. versionadded:: 3.25
If the ``SYSTEM`` argument is provided, the :prop_dir:`SYSTEM` directory
property of the subdirectory will be set to true. This property is
used to initialize the :prop_tgt:`SYSTEM` property of each target
created in that subdirectory. The include directories of targets with
:prop_tgt:`SYSTEM` set to true will be treated as ``SYSTEM`` when
compiling consumers.
used to initialize the :prop_tgt:`SYSTEM` property of each non-imported
target created in that subdirectory.

2
Help/command/build_name.rst
Unescape View File

@ -5,7 +5,7 @@ Disallowed since version 3.0. See CMake Policy :policy:`CMP0036`.
Use ``${CMAKE_SYSTEM}`` and ``${CMAKE_CXX_COMPILER}`` instead.
::
.. code-block:: cmake
build_name(variable)

2
Help/command/cmake_host_system_information.rst
Unescape View File

@ -17,7 +17,7 @@ Synopsis
Query host system specific information
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
::
.. code-block:: cmake
cmake_host_system_information(RESULT <variable> QUERY <key> ...)

5
Help/command/cmake_minimum_required.rst
Unescape View File

@ -79,3 +79,8 @@ invokes
cmake_policy(VERSION 2.4[...<max>])
which enables compatibility features for CMake 2.4 and lower.
See Also
^^^^^^^^
* :command:`cmake_policy`

6
Help/command/cmake_parse_arguments.rst
Unescape View File

@ -113,3 +113,9 @@ interpreted as the beginning of the new option. E.g.
is a keyword itself ``MY_INSTALL_DESTINATION`` will be empty (but added
to ``MY_INSTALL_KEYWORDS_MISSING_VALUES``) and ``MY_INSTALL_OPTIONAL`` will
therefore be set to ``TRUE``.
See Also
^^^^^^^^
* :command:`function`
* :command:`macro`

40
Help/command/cmake_path.rst
Unescape View File

@ -237,7 +237,7 @@ The following forms of the ``GET`` subcommand each retrieve a different
component or group of components from a path. See
`Path Structure And Terminology`_ for the meaning of each path component.
::
.. code-block:: cmake
cmake_path(GET <path-var> ROOT_NAME <out-var>)
cmake_path(GET <path-var> ROOT_DIRECTORY <out-var>)
@ -408,7 +408,7 @@ meaning of each path component.
.. _HAS_RELATIVE_PART:
.. _HAS_PARENT_PATH:
::
.. code-block:: cmake
cmake_path(HAS_ROOT_NAME <path-var> <out-var>)
cmake_path(HAS_ROOT_DIRECTORY <path-var> <out-var>)
@ -432,7 +432,7 @@ Note the following special cases:
.. _IS_ABSOLUTE:
::
.. code-block:: cmake
cmake_path(IS_ABSOLUTE <path-var> <out-var>)
@ -446,7 +446,7 @@ false while ``HAS_ROOT_DIRECTORY`` can be true.
.. _IS_RELATIVE:
::
.. code-block:: cmake
cmake_path(IS_RELATIVE <path-var> <out-var>)
@ -454,7 +454,7 @@ This will store the opposite of ``IS_ABSOLUTE`` in ``<out-var>``.
.. _IS_PREFIX:
::
.. code-block:: cmake
cmake_path(IS_PREFIX <path-var> <input> [NORMALIZE] <out-var>)
@ -476,7 +476,7 @@ are :ref:`normalized <Normalization>` before the check.
.. _Path COMPARE:
.. _COMPARE:
::
.. code-block:: cmake
cmake_path(COMPARE <input1> EQUAL <input2> <out-var>)
cmake_path(COMPARE <input1> NOT_EQUAL <input2> <out-var>)
@ -510,7 +510,7 @@ Modification
.. _cmake_path-SET:
::
.. code-block:: cmake
cmake_path(SET <path-var> [NORMALIZE] <input>)
@ -539,7 +539,7 @@ Output::
.. _APPEND:
::
.. code-block:: cmake
cmake_path(APPEND <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
@ -570,7 +570,7 @@ the following algorithm (pseudo-code) applies:
.. _APPEND_STRING:
::
.. code-block:: cmake
cmake_path(APPEND_STRING <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
@ -579,7 +579,7 @@ Append all the ``<input>`` arguments to the ``<path-var>`` without adding any
.. _REMOVE_FILENAME:
::
.. code-block:: cmake
cmake_path(REMOVE_FILENAME <path-var> [OUTPUT_VARIABLE <out-var>])
@ -609,7 +609,7 @@ Output::
.. _REPLACE_FILENAME:
::
.. code-block:: cmake
cmake_path(REPLACE_FILENAME <path-var> <input> [OUTPUT_VARIABLE <out-var>])
@ -628,7 +628,7 @@ equivalent to the following:
.. _REMOVE_EXTENSION:
::
.. code-block:: cmake
cmake_path(REMOVE_EXTENSION <path-var> [LAST_ONLY]
[OUTPUT_VARIABLE <out-var>])
@ -637,7 +637,7 @@ Removes the :ref:`extension <EXTENSION_DEF>`, if any, from ``<path-var>``.
.. _REPLACE_EXTENSION:
::
.. code-block:: cmake
cmake_path(REPLACE_EXTENSION <path-var> [LAST_ONLY] <input>
[OUTPUT_VARIABLE <out-var>])
@ -661,7 +661,7 @@ Generation
.. _NORMAL_PATH:
::
.. code-block:: cmake
cmake_path(NORMAL_PATH <path-var> [OUTPUT_VARIABLE <out-var>])
@ -670,7 +670,7 @@ Normalize ``<path-var>`` according the steps described in :ref:`Normalization`.
.. _cmake_path-RELATIVE_PATH:
.. _RELATIVE_PATH:
::
.. code-block:: cmake
cmake_path(RELATIVE_PATH <path-var> [BASE_DIRECTORY <input>]
[OUTPUT_VARIABLE <out-var>])
@ -686,7 +686,7 @@ as that used by C++
.. _ABSOLUTE_PATH:
::
.. code-block:: cmake
cmake_path(ABSOLUTE_PATH <path-var> [BASE_DIRECTORY <input>] [NORMALIZE]
[OUTPUT_VARIABLE <out-var>])
@ -713,7 +713,7 @@ target platform when cross-compiling.
.. _cmake_path-NATIVE_PATH:
.. _NATIVE_PATH:
::
.. code-block:: cmake
cmake_path(NATIVE_PATH <path-var> [NORMALIZE] <out-var>)
@ -727,7 +727,7 @@ When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
.. _cmake_path-TO_CMAKE_PATH_LIST:
.. _TO_CMAKE_PATH_LIST:
::
.. code-block:: cmake
cmake_path(CONVERT <input> TO_CMAKE_PATH_LIST <out-var> [NORMALIZE])
@ -749,7 +749,7 @@ When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
.. _cmake_path-TO_NATIVE_PATH_LIST:
.. _TO_NATIVE_PATH_LIST:
::
.. code-block:: cmake
cmake_path(CONVERT <input> TO_NATIVE_PATH_LIST <out-var> [NORMALIZE])
@ -788,7 +788,7 @@ Hashing
.. _HASH:
::
.. code-block:: cmake
cmake_path(HASH <path-var> <out-var>)

5
Help/command/cmake_policy.rst
Unescape View File

@ -150,3 +150,8 @@ use the pre-record policies when they are invoked. If the function or
macro implementation sets policies, the changes automatically
propagate up through callers until they reach the closest nested
policy stack entry.
See Also
^^^^^^^^
* :command:`cmake_minimum_required`

11
Help/command/configure_file.rst
Unescape View File

@ -58,7 +58,7 @@ or
#define VAR 1
Input lines of the form ``#cmakedefine01 VAR ...`` will expand
as ``#cmakedefine01 VAR ... 0`` or ``#cmakedefine01 VAR ... 0``,
as ``#cmakedefine01 VAR ... 0`` or ``#cmakedefine01 VAR ... 1``,
which may lead to undefined behavior.
.. versionadded:: 3.10
@ -174,11 +174,16 @@ Otherwise it will contain:
/* #undef FOO_ENABLE */
/* #undef FOO_STRING */
One may then use the :command:`include_directories` command to
One may then use the :command:`target_include_directories` command to
specify the output directory as an include directory:
.. code-block:: cmake
include_directories(${CMAKE_CURRENT_BINARY_DIR})
target_include_directories(<target> [SYSTEM] <INTERFACE|PUBLIC|PRIVATE> "${CMAKE_CURRENT_BINARY_DIR}")
so that sources may include the header as ``#include <foo.h>``.
See Also
^^^^^^^^
* :command:`file(GENERATE)`

2
Help/command/ctest_build.rst
Unescape View File

@ -3,7 +3,7 @@ ctest_build
Perform the :ref:`CTest Build Step` as a :ref:`Dashboard Client`.
::
.. code-block:: cmake
ctest_build([BUILD <build-dir>] [APPEND]
[CONFIGURATION <config>]

2
Help/command/ctest_configure.rst
Unescape View File

@ -3,7 +3,7 @@ ctest_configure
Perform the :ref:`CTest Configure Step` as a :ref:`Dashboard Client`.
::
.. code-block:: cmake
ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND]
[OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET]

2
Help/command/ctest_coverage.rst
Unescape View File

@ -3,7 +3,7 @@ ctest_coverage
Perform the :ref:`CTest Coverage Step` as a :ref:`Dashboard Client`.
::
.. code-block:: cmake
ctest_coverage([BUILD <build-dir>] [APPEND]
[LABELS <label>...]

4
Help/command/ctest_empty_binary_directory.rst
Unescape View File

@ -3,9 +3,9 @@ ctest_empty_binary_directory
empties the binary directory
::
.. code-block:: cmake
ctest_empty_binary_directory( directory )
ctest_empty_binary_directory(<directory>)
Removes a binary directory. This command will perform some checks
prior to deleting the directory in an attempt to avoid malicious or

2
Help/command/ctest_memcheck.rst
Unescape View File

@ -3,7 +3,7 @@ ctest_memcheck
Perform the :ref:`CTest MemCheck Step` as a :ref:`Dashboard Client`.
::
.. code-block:: cmake
ctest_memcheck([BUILD <build-dir>] [APPEND]
[START <start-number>]

4
Help/command/ctest_read_custom_files.rst
Unescape View File

@ -3,9 +3,9 @@ ctest_read_custom_files
read CTestCustom files.
::
.. code-block:: cmake
ctest_read_custom_files( directory ... )
ctest_read_custom_files(<directory>...)
Read all the CTestCustom.ctest or CTestCustom.cmake files from the
given directory.

2
Help/command/ctest_run_script.rst
Unescape View File

@ -3,7 +3,7 @@ ctest_run_script
runs a :option:`ctest -S` script
::
.. code-block:: cmake
ctest_run_script([NEW_PROCESS] script_file_name script_file_name1
script_file_name2 ... [RETURN_VALUE var])

4
Help/command/ctest_sleep.rst
Unescape View File

@ -3,13 +3,13 @@ ctest_sleep
sleeps for some amount of time
::
.. code-block:: cmake
ctest_sleep(<seconds>)
Sleep for given number of seconds.
::
.. code-block:: cmake
ctest_sleep(<time1> <duration> <time2>)

2
Help/command/ctest_start.rst
Unescape View File

@ -3,7 +3,7 @@ ctest_start
Starts the testing for a given model
::
.. code-block:: cmake
ctest_start(<model> [<source> [<binary>]] [GROUP <group>] [QUIET])

4
Help/command/ctest_submit.rst
Unescape View File

@ -3,7 +3,7 @@ ctest_submit
Perform the :ref:`CTest Submit Step` as a :ref:`Dashboard Client`.
::
.. code-block:: cmake
ctest_submit([PARTS <part>...] [FILES <file>...]
[SUBMIT_URL <url>]
@ -96,7 +96,7 @@ Submit to CDash Upload API
.. versionadded:: 3.2
::
.. code-block:: cmake
ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>]
[SUBMIT_URL <url>]

4
Help/command/ctest_test.rst
Unescape View File

@ -3,7 +3,7 @@ ctest_test
Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`.
::
.. code-block:: cmake
ctest_test([BUILD <build-dir>] [APPEND]
[START <start-number>]
@ -30,7 +30,7 @@ Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`.
)
..
_note: If updating the argument list here, please also update the argument
NOTE If updating the argument list here, please also update the argument
list documentation for :command:`ctest_memcheck` as well.
Run tests in the project build tree and store results in

2
Help/command/ctest_update.rst
Unescape View File

@ -3,7 +3,7 @@ ctest_update
Perform the :ref:`CTest Update Step` as a :ref:`Dashboard Client`.
::
.. code-block:: cmake
ctest_update([SOURCE <source-dir>]
[RETURN_VALUE <result-var>]

2
Help/command/ctest_upload.rst
Unescape View File

@ -3,7 +3,7 @@ ctest_upload
Upload files to a dashboard server as a :ref:`Dashboard Client`.
::
.. code-block:: cmake
ctest_upload(FILES <file>... [QUIET] [CAPTURE_CMAKE_ERROR <result-var>])

6
Help/command/define_property.rst
Unescape View File

@ -73,3 +73,9 @@ project via corresponding options to the :command:`get_property` command.
with ``CMAKE_`` or ``_CMAKE_``. The property name must contain at least one
underscore. It is recommended that the property name have a prefix specific
to the project.
See Also
^^^^^^^^
* :command:`get_property`
* :command:`set_property`

21
Help/command/enable_language.rst
Unescape View File

@ -9,24 +9,13 @@ Enable languages (CXX/C/OBJC/OBJCXX/Fortran/etc)
Enables support for the named languages in CMake. This is the same as
the :command:`project` command but does not create any of the extra
variables that are created by the project command. Example languages
are ``CXX``, ``C``, ``CUDA``, ``OBJC``, ``OBJCXX``, ``Fortran``,
``HIP``, ``ISPC``, and ``ASM``.
variables that are created by the project command.
.. versionadded:: 3.8
Added ``CUDA`` support.
.. include:: SUPPORTED_LANGUAGES.txt
.. versionadded:: 3.16
Added ``OBJC`` and ``OBJCXX`` support.
.. versionadded:: 3.18
Added ``ISPC`` support.
.. versionadded:: 3.21
Added ``HIP`` support.
If enabling ``ASM``, enable it last so that CMake can check whether
compilers for other languages like ``C`` work for assembly too.
By default ``C`` and ``CXX`` are enabled if no language options are given.
Specify language ``NONE``, or use the ``LANGUAGES`` keyword and list no languages,
to skip enabling any languages.
This command must be called in file scope, not in a function call.
Furthermore, it must be called in the highest directory common to all

2
Help/command/exec_program.rst
Unescape View File

@ -8,7 +8,7 @@ exec_program
Run an executable program during the processing of the CMakeList.txt
file.
::
.. code-block:: cmake
exec_program(Executable [directory in which to run]
[ARGS <arguments to executable>]

74
Help/command/execute_process.rst
Unescape View File

@ -32,6 +32,11 @@ Commands are executed concurrently as a pipeline, with the standard
output of each process piped to the standard input of the next.
A single standard error pipe is used for all processes.
``execute_process`` runs commands while CMake is configuring the project,
prior to build system generation. Use the :command:`add_custom_target` and
:command:`add_custom_command` commands to create custom commands that run
at build time.
Options:
``COMMAND``
@ -51,8 +56,8 @@ Options:
(Use the ``INPUT_*``, ``OUTPUT_*``, and ``ERROR_*`` options to
redirect stdin, stdout, and stderr.)
If a sequential execution of multiple commands is required, use multiple
:command:`execute_process` calls with a single ``COMMAND`` argument.
For **sequential execution** of multiple commands use multiple
``execute_process`` calls each with a single ``COMMAND`` argument.
``WORKING_DIRECTORY``
The named directory will be set as the current working directory of
@ -76,22 +81,46 @@ Options:
given ``COMMAND`` arguments. Each entry will be an integer return code
from the corresponding child or a string describing an error condition.
``INPUT_FILE <file>``
``<file>`` is attached to the standard input pipe of the *first* ``COMMAND``
process.
``OUTPUT_FILE <file>``
``<file>`` is attached to the standard output pipe of the *last* ``COMMAND``
process.
``ERROR_FILE <file>``
``<file>`` is attached to the standard error pipe of *all* ``COMMAND``
processes.
.. versionadded:: 3.3
If the same ``<file>`` is named for both ``OUTPUT_FILE`` and ``ERROR_FILE``
then it will be used for both standard output and standard error pipes.
``OUTPUT_QUIET``, ``ERROR_QUIET``
The standard output on ``OUTPUT_VARIABLE`` or standard error on
``ERROR_VARIABLE`` are not connected (no variable content).
The ``*_FILE`` and ``ECHO_*_VARIABLE`` options are not affected.
``OUTPUT_VARIABLE``, ``ERROR_VARIABLE``
The variable named will be set with the contents of the standard output
and standard error pipes, respectively. If the same variable is named
for both pipes their output will be merged in the order produced.
``INPUT_FILE, OUTPUT_FILE``, ``ERROR_FILE``
The file named will be attached to the standard input of the first
process, standard output of the last process, or standard error of
all processes, respectively.
``ECHO_OUTPUT_VARIABLE``, ``ECHO_ERROR_VARIABLE``
.. versionadded:: 3.18
.. versionadded:: 3.3
If the same file is named for both output and error then it will be used
for both.
The standard output or standard error will not be exclusively redirected to
the specified variables.
``OUTPUT_QUIET``, ``ERROR_QUIET``
The standard output or standard error results will be quietly ignored.
The output will be duplicated into the specified variables and also onto
standard output or standard error analogous to the ``tee`` Unix command.
.. note::
If more than one ``OUTPUT_*`` or ``ERROR_*`` option is given for the
same pipe the precedence is *not specified*.
If no ``OUTPUT_*`` or ``ERROR_*`` options are given the output will
be shared with the corresponding pipes of the CMake process itself.
``COMMAND_ECHO <where>``
.. versionadded:: 3.15
@ -126,17 +155,6 @@ Options:
Accept ``UTF-8`` spelling for consistency with the
`UTF-8 RFC <https://www.ietf.org/rfc/rfc3629>`_ naming convention.
``ECHO_OUTPUT_VARIABLE``, ``ECHO_ERROR_VARIABLE``
.. versionadded:: 3.18
The standard output or standard error will not be exclusively redirected to
the configured variables.
The output will be duplicated, it will be sent into the configured variables
and also on standard output or standard error.
This is analogous to the ``tee`` Unix command.
``COMMAND_ERROR_IS_FATAL <ANY|LAST>``
.. versionadded:: 3.19
@ -151,15 +169,3 @@ Options:
If the last command in the list of commands fails, the
``execute_process()`` command halts with an error. Commands earlier in the
list will not cause a fatal error.
If more than one ``OUTPUT_*`` or ``ERROR_*`` option is given for the
same pipe the precedence is not specified.
If no ``OUTPUT_*`` or ``ERROR_*`` options are given the output will
be shared with the corresponding pipes of the CMake process itself.
The :command:`execute_process` command is a newer more powerful version of
:command:`exec_program`, but the old command has been kept for compatibility.
Both commands run while CMake is processing the project prior to build
system generation. Use :command:`add_custom_target` and
:command:`add_custom_command` to create custom commands that run at
build time.

2
Help/command/export_library_dependencies.rst
Unescape View File

@ -15,7 +15,7 @@ The old-style library dependencies file does not take into account
per-configuration names of libraries or the
:prop_tgt:`LINK_INTERFACE_LIBRARIES` target property.
::
.. code-block:: cmake
export_library_dependencies(<file> [APPEND])

27
Help/command/file.rst
Unescape View File

@ -526,10 +526,10 @@ from the input content to produce the output content. The options are:
``OUTPUT <output-file>``
Specify the output file name to generate. Use generator expressions
such as ``$<CONFIG>`` to specify a configuration-specific output file
name. Multiple configurations may generate the same output file only
if the generated content is identical. Otherwise, the ``<output-file>``
must evaluate to an unique name for each configuration.
such as :genex:`$<CONFIG>` to specify a configuration-specific
output file name. Multiple configurations may generate the same output
file only if the generated content is identical. Otherwise, the
``<output-file>`` must evaluate to an unique name for each configuration.
.. versionchanged:: 3.10
A relative path (after evaluating generator expressions) is treated
@ -540,8 +540,9 @@ from the input content to produce the output content. The options are:
.. versionadded:: 3.19
Specify which target to use when evaluating generator expressions that
require a target for evaluation (e.g. ``$<COMPILE_FEATURES:...>``,
``$<TARGET_PROPERTY:prop>``).
require a target for evaluation (e.g.
:genex:`$<COMPILE_FEATURES:...>`,
:genex:`$<TARGET_PROPERTY:prop>`).
``NO_SOURCE_PERMISSIONS``
.. versionadded:: 3.20
@ -749,7 +750,8 @@ The options are:
file(COPY_FILE <oldname> <newname>
[RESULT <result>]
[ONLY_IF_DIFFERENT])
[ONLY_IF_DIFFERENT]
[INPUT_MAY_BE_RECENT])
.. versionadded:: 3.21
@ -768,6 +770,14 @@ The options are:
contents are already the same as ``<oldname>`` (this avoids updating
``<newname>``'s timestamp).
``INPUT_MAY_BE_RECENT``
.. versionadded:: 3.26
Tell CMake that the input file may have been recently created. This is
meaningful only on Windows, where files may be inaccessible for a short
time after they are created. With this option, if permission is denied,
CMake will retry reading the input a few times.
This sub-command has some similarities to :command:`configure_file` with the
``COPYONLY`` option. An important difference is that :command:`configure_file`
creates a dependency on the source file, so CMake will be re-run if it changes.
@ -1213,6 +1223,9 @@ directed to do so with the ``COMPRESSION`` option. Valid values for
The ``<compression-level>`` should be between 0-9, with the default being 0.
The ``COMPRESSION`` option must be present when ``COMPRESSION_LEVEL`` is given.
.. versionadded:: 3.26
The ``<compression-level>`` of the ``Zstd`` algorithm can be set between 0-19.
.. note::
With ``FORMAT`` set to ``raw`` only one file will be compressed with the
compression type specified by ``COMPRESSION``.

3
Help/command/find_package.rst
Unescape View File

@ -370,7 +370,8 @@ enabled.
1. .. versionadded:: 3.12
Search paths specified in the :variable:`<PackageName>_ROOT` CMake
variable and the :envvar:`<PackageName>_ROOT` environment variable,
where ``<PackageName>`` is the package to be found.
where ``<PackageName>`` is the package to be found
(the case-preserved first argument to ``find_package``).
The package root variables are maintained as a stack so if
called from within a find module, root paths from the parent's find
module will also be searched after paths for the current package.

6
Help/command/foreach.rst
Unescape View File

@ -74,8 +74,7 @@ processed:
message(STATUS "X=${X}")
endforeach()
yields
::
yields::
-- X=0
-- X=1
@ -119,8 +118,7 @@ iteration variables as follows:
message(STATUS "en=${en}, ba=${ba}")
endforeach()
yields
::
yields::
-- num_0=one, num_1=satu
-- num_0=two, num_1=dua

1
Help/command/function.rst
Unescape View File

@ -77,5 +77,6 @@ extra argument.
See Also
^^^^^^^^
* :command:`cmake_parse_arguments`
* :command:`endfunction`
* :command:`return`

7
Help/command/get_cmake_property.rst
Unescape View File

@ -12,9 +12,12 @@ the ``<property>`` is stored in the variable ``<var>``.
If the property is not found, ``<var>`` will be set to ``NOTFOUND``.
See the :manual:`cmake-properties(7)` manual for available properties.
See also the :command:`get_property` command ``GLOBAL`` option.
In addition to global properties, this command (for historical reasons)
also supports the :prop_dir:`VARIABLES` and :prop_dir:`MACROS` directory
properties. It also supports a special ``COMPONENTS`` global property that
lists the components given to the :command:`install` command.
See Also
^^^^^^^^
* the :command:`get_property` command ``GLOBAL`` option

7
Help/command/get_directory_property.rst
Unescape View File

@ -33,4 +33,9 @@ the search will chain to a parent scope as described for the
Get a variable definition from a directory. This form is useful to
get a variable definition from another directory.
See also the more general :command:`get_property` command.
See Also
^^^^^^^^
* :command:`define_property`
* the more general :command:`get_property` command

5
Help/command/get_filename_component.rst
Unescape View File

@ -69,3 +69,8 @@ left as a full path. If ``PROGRAM_ARGS`` is present with ``PROGRAM``, then
any command-line arguments present in the ``<FileName>`` string are split
from the program name and stored in ``<arg_var>``. This is used to
separate a program name from its arguments in a command line string.
See Also
^^^^^^^^
* :command:`cmake_path`

6
Help/command/get_property.rst
Unescape View File

@ -99,3 +99,9 @@ documentation is requested for a property that has not been defined
The :prop_sf:`GENERATED` source file property may be globally visible.
See its documentation for details.
See Also
^^^^^^^^
* :command:`define_property`
* :command:`set_property`

9
Help/command/get_source_file_property.rst
Unescape View File

@ -39,9 +39,14 @@ Use :command:`set_source_files_properties` to set property values. Source
file properties usually control how the file is built. One property that is
always there is :prop_sf:`LOCATION`.
See also the more general :command:`get_property` command.
.. note::
The :prop_sf:`GENERATED` source file property may be globally visible.
See its documentation for details.
See Also
^^^^^^^^
* :command:`define_property`
* the more general :command:`get_property` command
* :command:`set_source_files_properties`

8
Help/command/get_target_property.rst
Unescape View File

@ -22,6 +22,10 @@ query the target instead. This command can get properties for any
target so far created. The targets do not need to be in the current
``CMakeLists.txt`` file.
See also the more general :command:`get_property` command.
See Also
^^^^^^^^
See :ref:`Target Properties` for the list of properties known to CMake.
* :command:`define_property`
* the more general :command:`get_property` command
* :command:`set_target_properties`
* :ref:`Target Properties` for the list of properties known to CMake

6
Help/command/get_test_property.rst
Unescape View File

@ -19,4 +19,8 @@ an empty string.
For a list of standard properties you can type
:option:`cmake --help-property-list`.
See also the more general :command:`get_property` command.
See Also
^^^^^^^^
* :command:`define_property`
* the more general :command:`get_property` command

8
Help/command/if.rst
Unescape View File

@ -165,6 +165,8 @@ File Operations
Resolves symbolic links, i.e. if the named file or directory is a
symbolic link, returns true if the target of the symbolic link exists.
False if the given path is an empty string.
``if(file1 IS_NEWER_THAN file2)``
True if ``file1`` is newer than ``file2`` or if one of the two files doesn't
exist. Behavior is well-defined only for full paths. If the file
@ -173,10 +175,12 @@ File Operations
of a tie. This includes the case of passing the same file name for
both file1 and file2.
``if(IS_DIRECTORY path-to-directory)``
True if the given name is a directory. Behavior is well-defined only
``if(IS_DIRECTORY path)``
True if ``path`` is a directory. Behavior is well-defined only
for full paths.
False if the given path is an empty string.
``if(IS_SYMLINK file-name)``
True if the given name is a symbolic link. Behavior is well-defined
only for full paths.

11
Help/command/include_directories.rst
Unescape View File

@ -29,13 +29,16 @@ Signalling this setting might achieve effects such as the compiler
skipping warnings, or these fixed-install system files not being
considered in dependency calculations - see compiler docs.
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.
.. |command_name| replace:: ``include_directories``
.. include:: GENEX_NOTE.txt
.. note::
Prefer the :command:`target_include_directories` command to add include
directories to individual targets and optionally propagate/export them
to dependents.
See Also
^^^^^^^^
* :command:`target_include_directories`

2
Help/command/include_guard.rst
Unescape View File

@ -13,7 +13,7 @@ Sets up an include guard for the current CMake file (see the
:variable:`CMAKE_CURRENT_LIST_FILE` variable documentation).
CMake will end its processing of the current file at the location of the
:command:`include_guard` command if the current file has already been
``include_guard`` command if the current file has already been
processed for the applicable scope (see below). This provides functionality
similar to the include guards commonly used in source headers or to the
``#pragma once`` directive. If the current file has been processed previously

4
Help/command/install.rst
Unescape View File

@ -32,7 +32,7 @@ are executed in order during installation.
.. versionchanged:: 3.22
The environment variable :envvar:`CMAKE_INSTALL_MODE` can override the
default copying behavior of :command:`install()`.
default copying behavior of ``install()``.
There are multiple signatures for this command. Some of them define
installation options for files and targets. Options common to
@ -379,7 +379,7 @@ top level:
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property of the
``<targets>`` when exported by the `install(EXPORT)`_ command. If a
relative path is specified, it is treated as relative to the
``$<INSTALL_PREFIX>``.
:genex:`$<INSTALL_PREFIX>`.
``RUNTIME_DEPENDENCY_SET``
.. versionadded:: 3.21

6
Help/command/install_files.rst
Unescape View File

@ -11,7 +11,7 @@ directly replaced by the ``FILES`` form of the :command:`install`
command. The regexp form can be expressed more clearly using the ``GLOB``
form of the :command:`file` command.
::
.. code-block:: cmake
install_files(<dir> extension file file ...)
@ -23,14 +23,14 @@ removed first. This is useful for providing lists of source files
such as foo.cxx when you want the corresponding foo.h to be installed.
A typical extension is ``.h``.
::
.. code-block:: cmake
install_files(<dir> regexp)
Any files in the current source directory that match the regular
expression will be installed.
::
.. code-block:: cmake
install_files(<dir> FILES file file ...)

4
Help/command/install_programs.rst
Unescape View File

@ -11,7 +11,7 @@ directly replaced by the ``PROGRAMS`` form of the :command:`install`
command. The regexp form can be expressed more clearly using the ``GLOB``
form of the :command:`file` command.
::
.. code-block:: cmake
install_programs(<dir> file1 file2 [file3 ...])
install_programs(<dir> FILES file1 [file2 ...])
@ -20,7 +20,7 @@ Create rules to install the listed programs into the given directory.
Use the ``FILES`` argument to guarantee that the file list version of the
command will be used even when there is only one argument.
::
.. code-block:: cmake
install_programs(<dir> regexp)

2
Help/command/install_targets.rst
Unescape View File

@ -8,7 +8,7 @@ install_targets
This command has been superseded by the :command:`install` command. It is
provided for compatibility with older CMake code.
::
.. code-block:: cmake
install_targets(<dir> [RUNTIME_DIRECTORY dir] target target)

6
Help/command/link_directories.rst
Unescape View File

@ -53,3 +53,9 @@ The command will apply only to targets created after it is called.
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.
See Also
^^^^^^^^
* :command:`target_link_directories`
* :command:`target_link_libraries`

4
Help/command/load_command.rst
Unescape View File

@ -5,7 +5,7 @@ Disallowed since version 3.0. See CMake Policy :policy:`CMP0031`.
Load a command into a running CMake.
::
.. code-block:: cmake
load_command(COMMAND_NAME <loc1> [loc2 ...])
@ -15,7 +15,7 @@ added to the set of available CMake commands. Usually,
:command:`try_compile` is used before this command to compile the
module. If the command is successfully loaded a variable named
::
.. code-block:: cmake
CMAKE_LOADED_COMMAND_<COMMAND_NAME>

6
Help/command/macro.rst
Unescape View File

@ -149,3 +149,9 @@ existing variable instead of the arguments. For example:
Will loop over ``a;b;c`` and not over ``x;y;z`` as one might have expected.
If you want true CMake variables and/or better CMake scope control you
should look at the function command.
See Also
^^^^^^^^
* :command:`cmake_parse_arguments`
* :command:`endmacro`

2
Help/command/make_directory.rst
Unescape View File

@ -5,7 +5,7 @@ make_directory
Use the :command:`file(MAKE_DIRECTORY)` command instead.
::
.. code-block:: cmake
make_directory(directory)

55
Help/command/message.rst
Unescape View File

@ -14,6 +14,8 @@ Synopsis
`Reporting checks`_
message(<checkState> "message text" ...)
`Configure Log`_
message(CONFIGURE_LOG <text>...)
General messages
^^^^^^^^^^^^^^^^
@ -193,3 +195,56 @@ Output from the above would appear something like the following::
-- Finding partB
-- Finding partB - not found
-- Finding my things - missing components: B
Configure Log
^^^^^^^^^^^^^
.. versionadded:: 3.26
.. code-block:: cmake
message(CONFIGURE_LOG <text>...)
Record a :ref:`configure-log message event <message configure-log event>`
with the specified ``<text>``. By convention, if the text contains more
than one line, the first line should be a summary of the event.
This mode is intended to record the details of a system inspection check
or other one-time operation guarded by a cache entry, but that is not
performed using :command:`try_compile` or :command:`try_run`, which
automatically log their details. Projects should avoid calling it every
time CMake runs. For example:
.. code-block:: cmake
if (NOT DEFINED MY_CHECK_RESULT)
# Print check summary in configure output.
message(CHECK_START "My Check")
# ... perform system inspection, e.g., with execute_process ...
# Cache the result so we do not run the check again.
set(MY_CHECK_RESULT "${MY_CHECK_RESULT}" CACHE INTERNAL "My Check")
# Record the check details in the cmake-configure-log.
message(CONFIGURE_LOG
"My Check Result: ${MY_CHECK_RESULT}\n"
"${details}"
)
# Print check result in configure output.
if(MY_CHECK_RESULT)
message(CHECK_PASS "passed")
else()
message(CHECK_FAIL "failed")
endif()
endif()
If no project is currently being configured, such as in
:ref:`cmake -P <Script Processing Mode>` script mode,
this command does nothing.
See Also
^^^^^^^^
* :command:`cmake_language(GET_MESSAGE_LOG_LEVEL)`

2
Help/command/output_required_files.rst
Unescape View File

@ -9,7 +9,7 @@ This command exists only because ancient CMake versions provided it.
CMake handles preprocessor dependency scanning automatically using a
more advanced scanner.
::
.. code-block:: cmake
output_required_files(srcfile outputfile)

19
Help/command/project.rst
Unescape View File

@ -102,23 +102,9 @@ The options are:
Can also be specified without ``LANGUAGES`` keyword per the first, short signature.
Selects which programming languages are needed to build the project.
Supported languages include ``C``, ``CXX`` (i.e. C++), ``CUDA``,
``OBJC`` (i.e. Objective-C), ``OBJCXX``, ``Fortran``, ``HIP``, ``ISPC``, and ``ASM``.
By default ``C`` and ``CXX`` are enabled if no language options are given.
Specify language ``NONE``, or use the ``LANGUAGES`` keyword and list no languages,
to skip enabling any languages.
.. versionadded:: 3.8
Added ``CUDA`` support.
.. include:: SUPPORTED_LANGUAGES.txt
.. versionadded:: 3.16
Added ``OBJC`` and ``OBJCXX`` support.
.. versionadded:: 3.18
Added ``ISPC`` support.
If enabling ``ASM``, list it last so that CMake can check whether
compilers for other languages like ``C`` work for assembly too.
The variables set through the ``VERSION``, ``DESCRIPTION`` and ``HOMEPAGE_URL``
options are intended for use as default values in package metadata and documentation.
@ -188,5 +174,6 @@ call exists, CMake will issue a warning and pretend there is a
Call the ``project()`` command near the top of the top-level
``CMakeLists.txt``, but *after* calling :command:`cmake_minimum_required`.
It is important to establish version and policy settings before invoking
other commands whose behavior they may affect.
other commands whose behavior they may affect and for this reason the
``project()`` command will issue a warning if this order is not kept.
See also policy :policy:`CMP0000`.

2
Help/command/remove.rst
Unescape View File

@ -5,7 +5,7 @@ remove
Use the :command:`list(REMOVE_ITEM)` command instead.
::
.. code-block:: cmake
remove(VAR VALUE VALUE ...)

3
Help/command/return.rst
Unescape View File

@ -30,7 +30,7 @@ command. All arguments are ignored unless that policy is set to ``NEW``.
with the :command:`block` command, as described below.
The ``PROPAGATE`` option can be very useful in conjunction with the
:command:`block` command. A :command:`return` will propagate the
:command:`block` command. A ``return`` will propagate the
specified variables through any enclosing block scopes created by the
:command:`block` commands. Inside a function, this ensures the variables
are propagated to the function's caller, regardless of any blocks within
@ -89,3 +89,4 @@ See Also
^^^^^^^^
* :command:`block`
* :command:`function`

5
Help/command/set.rst
Unescape View File

@ -111,3 +111,8 @@ environment variable.
Arguments after ``<value>`` are ignored. If extra arguments are found,
then an author warning is issued.
See Also
^^^^^^^^
* :command:`unset`

7
Help/command/set_directory_properties.rst
Unescape View File

@ -13,3 +13,10 @@ See also the :command:`set_property(DIRECTORY)` command.
See :ref:`Directory Properties` for the list of properties known to CMake
and their individual documentation for the behavior of each property.
See Also
^^^^^^^^
* :command:`define_property`
* :command:`get_directory_property`
* the more general :command:`set_property` command

11
Help/command/set_property.rst
Unescape View File

@ -107,10 +107,15 @@ finding the initial value to append to. If the property is not already
directly set in the nominated scope, the command will behave as though
``APPEND`` or ``APPEND_STRING`` had not been given.
See the :manual:`cmake-properties(7)` manual for a list of properties
in each scope.
.. note::
The :prop_sf:`GENERATED` source file property may be globally visible.
See its documentation for details.
See Also
^^^^^^^^
* :command:`define_property`
* :command:`get_property`
* The :manual:`cmake-properties(7)` manual for a list of properties
in each scope.

11
Help/command/set_source_files_properties.rst
Unescape View File

@ -34,10 +34,15 @@ list.
Use :command:`get_source_file_property` to get property values.
See also the :command:`set_property(SOURCE)` command.
See :ref:`Source File Properties` for the list of properties known
to CMake.
.. note::
The :prop_sf:`GENERATED` source file property may be globally visible.
See its documentation for details.
See Also
^^^^^^^^
* :command:`define_property`
* :command:`get_source_file_property`
* :ref:`Source File Properties` for the list of properties known
to CMake

8
Help/command/set_target_properties.rst
Unescape View File

@ -15,6 +15,10 @@ set next. You can use any prop value pair you want and extract it
later with the :command:`get_property` or :command:`get_target_property`
command.
See also the :command:`set_property(TARGET)` command.
See Also
^^^^^^^^
See :ref:`Target Properties` for the list of properties known to CMake.
* :command:`define_property`
* :command:`get_target_property`
* the more general :command:`set_property` command
* :ref:`Target Properties` for the list of properties known to CMake

8
Help/command/set_tests_properties.rst
Unescape View File

@ -14,6 +14,10 @@ Test property values may be specified using
:manual:`generator expressions <cmake-generator-expressions(7)>`
for tests created by the :command:`add_test(NAME)` signature.
See also the :command:`set_property(TEST)` command.
See Also
^^^^^^^^
See :ref:`Test Properties` for the list of properties known to CMake.
* :command:`add_test`
* :command:`define_property`
* the more general :command:`set_property` command
* :ref:`Target Properties` for the list of properties known to CMake

33
Help/command/string.rst
Unescape View File

@ -45,16 +45,16 @@ Synopsis
`JSON`_
string(JSON <out-var> [ERROR_VARIABLE <error-var>]
{`GET`_ | `TYPE`_ | :ref:`LENGTH <JSONLENGTH>` | `REMOVE`_}
{:ref:`GET <JSON_GET>` | :ref:`TYPE <JSON_TYPE>` | :ref:`LENGTH <JSON_LENGTH>` | :ref:`REMOVE <JSON_REMOVE>`}
<json-string> <member|index> [<member|index> ...])
string(JSON <out-var> [ERROR_VARIABLE <error-var>]
`MEMBER`_ <json-string>
:ref:`MEMBER <JSON_MEMBER>` <json-string>
[<member|index> ...] <index>)
string(JSON <out-var> [ERROR_VARIABLE <error-var>]
`SET`_ <json-string>
:ref:`SET <JSON_SET>` <json-string>
<member|index> [<member|index> ...] <value>)
string(JSON <out-var> [ERROR_VARIABLE <error-var>]
`EQUAL`_ <json-string1> <json-string2>)
:ref:`EQUAL <JSON_EQUAL>` <json-string1> <json-string2>)
Search and Replace
^^^^^^^^^^^^^^^^^^
@ -522,6 +522,17 @@ specifiers:
``%Y``
The current year.
``%z``
.. versionadded:: 3.26
The offset of the time zone from UTC, in hours and minutes,
with format ``+hhmm`` or ``-hhmm``.
``%Z``
.. versionadded:: 3.26
The time zone name.
Unknown format specifiers will be ignored and copied to the output
as-is.
@ -575,7 +586,7 @@ Functionality for querying a JSON string.
option is not present, a fatal error message is generated. If no error
occurs, the ``<error-variable>`` will be set to ``NOTFOUND``.
.. _GET:
.. _JSON_GET:
.. code-block:: cmake
string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
@ -588,7 +599,7 @@ Boolean elements will be returned as ``ON`` or ``OFF``.
Null elements will be returned as an empty string.
Number and string types will be returned as strings.
.. _TYPE:
.. _JSON_TYPE:
.. code-block:: cmake
string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
@ -599,7 +610,7 @@ given by the list of ``<member|index>`` arguments. The ``<out-var>``
will be set to one of ``NULL``, ``NUMBER``, ``STRING``, ``BOOLEAN``,
``ARRAY``, or ``OBJECT``.
.. _MEMBER:
.. _JSON_MEMBER:
.. code-block:: cmake
string(JSON <out-var> [ERROR_VARIABLE <error-var>]
@ -610,7 +621,7 @@ Get the name of the ``<index>``-th member in ``<json-string>`` at the location
given by the list of ``<member|index>`` arguments.
Requires an element of object type.
.. _JSONLENGTH:
.. _JSON_LENGTH:
.. code-block:: cmake
string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
@ -620,7 +631,7 @@ Get the length of an element in ``<json-string>`` at the location
given by the list of ``<member|index>`` arguments.
Requires an element of array or object type.
.. _REMOVE:
.. _JSON_REMOVE:
.. code-block:: cmake
string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
@ -630,7 +641,7 @@ Remove an element from ``<json-string>`` at the location
given by the list of ``<member|index>`` arguments. The JSON string
without the removed element will be stored in ``<out-var>``.
.. _SET:
.. _JSON_SET:
.. code-block:: cmake
string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
@ -640,7 +651,7 @@ Set an element in ``<json-string>`` at the location
given by the list of ``<member|index>`` arguments to ``<value>``.
The contents of ``<value>`` should be valid JSON.
.. _EQUAL:
.. _JSON_EQUAL:
.. code-block:: cmake
string(JSON <out-var> [ERROR_VARIABLE <error-var>]

2
Help/command/subdir_depends.rst
Unescape View File

@ -5,7 +5,7 @@ Disallowed since version 3.0. See CMake Policy :policy:`CMP0029`.
Does nothing.
::
.. code-block:: cmake
subdir_depends(subdir dep1 dep2 ...)

2
Help/command/subdirs.rst
Unescape View File

@ -7,7 +7,7 @@ subdirs
Add a list of subdirectories to the build.
::
.. code-block:: cmake
subdirs(dir1 dir2 ...[EXCLUDE_FROM_ALL exclude_dir1 exclude_dir2 ...]
[PREORDER] )

19
Help/command/target_compile_definitions.rst
Unescape View File

@ -25,10 +25,8 @@ same ``<target>`` append items in the order called.
.. versionadded:: 3.11
Allow setting ``INTERFACE`` items on :ref:`IMPORTED targets <Imported Targets>`.
Arguments to ``target_compile_definitions`` 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.
.. |command_name| replace:: ``target_compile_definitions``
.. include:: GENEX_NOTE.txt
Any leading ``-D`` on an item will be removed. Empty items are ignored.
For example, the following are all equivalent:
@ -48,3 +46,16 @@ Definitions may optionally have values:
Note that many compilers treat ``-DFOO`` as equivalent to ``-DFOO=1``, but
other tools may not recognize this in all circumstances (e.g. IntelliSense).
See Also
^^^^^^^^
* :command:`add_compile_definitions`
* :command:`target_compile_features`
* :command:`target_compile_options`
* :command:`target_include_directories`
* :command:`target_link_libraries`
* :command:`target_link_directories`
* :command:`target_link_options`
* :command:`target_precompile_headers`
* :command:`target_sources`

22
Help/command/target_compile_features.rst
Unescape View File

@ -30,8 +30,20 @@ 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>`.
Arguments to ``target_compile_features`` may use "generator expressions"
with the syntax ``$<...>``.
See the :manual:`cmake-generator-expressions(7)` manual for available
expressions. See the :manual:`cmake-compile-features(7)` manual for
information on compile features and a list of supported compilers.
.. |command_name| replace:: ``target_compile_features``
.. |more_see_also| replace:: See the :manual:`cmake-compile-features(7)`
manual for information on compile features and a list of supported compilers.
.. include:: GENEX_NOTE.txt
:start-line: 1
See Also
^^^^^^^^
* :command:`target_compile_definitions`
* :command:`target_compile_options`
* :command:`target_include_directories`
* :command:`target_link_libraries`
* :command:`target_link_directories`
* :command:`target_link_options`
* :command:`target_precompile_headers`
* :command:`target_sources`

22
Help/command/target_compile_options.rst
Unescape View File

@ -19,7 +19,8 @@ Arguments
^^^^^^^^^
If ``BEFORE`` is specified, the content will be prepended to the property
instead of being appended.
instead of being appended. See policy :policy:`CMP0101` which affects
whether ``BEFORE`` will be ignored in certain cases.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the :ref:`scope <Target Usage Requirements>` of the following arguments.
@ -32,21 +33,26 @@ The following arguments specify compile options. Repeated calls for the same
.. versionadded:: 3.11
Allow setting ``INTERFACE`` items on :ref:`IMPORTED targets <Imported Targets>`.
Arguments to ``target_compile_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.
.. |command_name| replace:: ``target_compile_options``
.. include:: GENEX_NOTE.txt
.. include:: OPTIONS_SHELL.txt
See Also
^^^^^^^^
This command can be used to add any options. However, for adding
* This command can be used to add any options. However, for adding
preprocessor definitions and include directories it is recommended
to use the more specific commands :command:`target_compile_definitions`
and :command:`target_include_directories`.
For directory-wide settings, there is the command :command:`add_compile_options`.
* For directory-wide settings, there is the command :command:`add_compile_options`.
For file-specific settings, there is the source file property :prop_sf:`COMPILE_OPTIONS`.
* For file-specific settings, there is the source file property :prop_sf:`COMPILE_OPTIONS`.
* :command:`target_compile_features`
* :command:`target_link_libraries`
* :command:`target_link_directories`
* :command:`target_link_options`
* :command:`target_precompile_headers`
* :command:`target_sources`

19
Help/command/target_include_directories.rst
Unescape View File

@ -40,10 +40,8 @@ If ``SYSTEM`` is used together with ``PUBLIC`` or ``INTERFACE``, the
:prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` target property will be
populated with the specified directories.
Arguments to ``target_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.
.. |command_name| replace:: ``target_include_directories``
.. include:: GENEX_NOTE.txt
Specified include directories may be absolute paths or relative paths.
A relative path will be interpreted as relative to the current source
@ -74,3 +72,16 @@ Creating Relocatable Packages
.. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`
.. include:: /include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt
See Also
^^^^^^^^
* :command:`include_directories`
* :command:`target_compile_definitions`
* :command:`target_compile_features`
* :command:`target_compile_options`
* :command:`target_link_libraries`
* :command:`target_link_directories`
* :command:`target_link_options`
* :command:`target_precompile_headers`
* :command:`target_sources`

19
Help/command/target_link_directories.rst
Unescape View File

@ -34,10 +34,8 @@ 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.
.. |command_name| replace:: ``target_link_directories``
.. include:: GENEX_NOTE.txt
.. note::
@ -56,3 +54,16 @@ manual for more on defining buildsystem properties.
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``).
See Also
^^^^^^^^
* :command:`link_directories`
* :command:`target_compile_definitions`
* :command:`target_compile_features`
* :command:`target_compile_options`
* :command:`target_include_directories`
* :command:`target_link_libraries`
* :command:`target_link_options`
* :command:`target_precompile_headers`
* :command:`target_sources`

16
Help/command/target_link_libraries.rst
Unescape View File

@ -293,8 +293,8 @@ will be included in the link too.
.. _`Linking Object Libraries via $<TARGET_OBJECTS>`:
Linking Object Libraries via $<TARGET_OBJECTS>
""""""""""""""""""""""""""""""""""""""""""""""
Linking Object Libraries via ``$<TARGET_OBJECTS>``
""""""""""""""""""""""""""""""""""""""""""""""""""
.. versionadded:: 3.21
@ -407,3 +407,15 @@ Creating Relocatable Packages
.. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_LINK_LIBRARIES`
.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt
See Also
^^^^^^^^
* :command:`target_compile_definitions`
* :command:`target_compile_features`
* :command:`target_compile_options`
* :command:`target_include_directories`
* :command:`target_link_directories`
* :command:`target_link_options`
* :command:`target_precompile_headers`
* :command:`target_sources`

18
Help/command/target_link_options.rst
Unescape View File

@ -42,13 +42,23 @@ The following arguments specify link options. Repeated calls for the same
.. note::
:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.
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.
.. |command_name| replace:: ``target_link_options``
.. include:: GENEX_NOTE.txt
.. include:: DEVICE_LINK_OPTIONS.txt
.. include:: OPTIONS_SHELL.txt
.. include:: LINK_OPTIONS_LINKER.txt
See Also
^^^^^^^^
* :command:`target_compile_definitions`
* :command:`target_compile_features`
* :command:`target_compile_options`
* :command:`target_include_directories`
* :command:`target_link_libraries`
* :command:`target_link_directories`
* :command:`target_precompile_headers`
* :command:`target_sources`

34
Help/command/target_precompile_headers.rst
Unescape View File

@ -70,17 +70,16 @@ included by absolute path. For example:
<unordered_map>
)
Arguments to ``target_precompile_headers()`` may use "generator expressions"
with the syntax ``$<...>``.
See the :manual:`cmake-generator-expressions(7)` manual for available
expressions.
The :genex:`$<COMPILE_LANGUAGE:...>` generator expression is particularly
useful for specifying a language-specific header to precompile for
only one language (e.g. ``CXX`` and not ``C``). In this case, header
file names that are not explicitly in double quotes or angle brackets
must be specified by absolute path. Also, when specifying angle brackets
inside a generator expression, be sure to encode the closing ``>`` as
``$<ANGLE-R>``. For example:
.. |command_name| replace:: ``target_compile_features``
.. |more_see_also| replace:: The :genex:`$<COMPILE_LANGUAGE:...>` generator
expression is particularly useful for specifying a language-specific header
to precompile for only one language (e.g. ``CXX`` and not ``C``). In this
case, header file names that are not explicitly in double quotes or angle
brackets must be specified by absolute path. Also, when specifying angle
brackets inside a generator expression, be sure to encode the closing
``>`` as :genex:`$<ANGLE-R>`. For example:
.. include:: GENEX_NOTE.txt
:start-line: 1
.. code-block:: cmake
@ -118,8 +117,17 @@ the ``REUSE_FROM`` form is used.
See Also
^^^^^^^^
To disable precompile headers for specific targets, see the
* To disable precompile headers for specific targets, see the
:prop_tgt:`DISABLE_PRECOMPILE_HEADERS` target property.
To prevent precompile headers from being used when compiling a specific
* To prevent precompile headers from being used when compiling a specific
source file, see the :prop_sf:`SKIP_PRECOMPILE_HEADERS` source file property.
* :command:`target_compile_definitions`
* :command:`target_compile_features`
* :command:`target_compile_options`
* :command:`target_include_directories`
* :command:`target_link_libraries`
* :command:`target_link_directories`
* :command:`target_link_options`
* :command:`target_sources`

14
Help/command/target_sources.rst
Unescape View File

@ -202,3 +202,17 @@ Target properties related to include directories are also modified by
of the file set is ``INTERFACE`` or ``PUBLIC``, all of the ``BASE_DIRS`` of
the file set are wrapped in :genex:`$<BUILD_INTERFACE>` and appended to this
property.
See Also
^^^^^^^^
* :command:`add_executable`
* :command:`add_library`
* :command:`target_compile_definitions`
* :command:`target_compile_features`
* :command:`target_compile_options`
* :command:`target_include_directories`
* :command:`target_link_libraries`
* :command:`target_link_directories`
* :command:`target_link_options`
* :command:`target_precompile_headers`

68
Help/command/try_compile.rst
Unescape View File

@ -14,18 +14,20 @@ Try Compiling Whole Projects
.. code-block:: cmake
try_compile(<resultVar> PROJECT <projectName>
try_compile(<compileResultVar> PROJECT <projectName>
SOURCE_DIR <srcdir>
[BINARY_DIR <bindir>]
[TARGET <targetName>]
[LOG_DESCRIPTION <text>]
[NO_CACHE]
[NO_LOG]
[CMAKE_FLAGS <flags>...]
[OUTPUT_VARIABLE <var>])
.. versionadded:: 3.25
Try building a project. The success or failure of the ``try_compile``,
i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``<resultVar>``.
Try building a project. Build success returns ``TRUE`` and build failure
returns ``FALSE`` in ``<compileResultVar>``.
In this form, ``<srcdir>`` should contain a complete CMake project with a
``CMakeLists.txt`` file and all sources. The ``<bindir>`` and ``<srcdir>``
@ -40,14 +42,18 @@ below for the meaning of other options.
Previously this was only done by the
:ref:`source file <Try Compiling Source Files>` signature.
This command also supports an alternate signature
which was present in older versions of CMake:
.. versionadded:: 3.26
This command records a
:ref:`configure-log try_compile event <try_compile configure-log event>`
if the ``NO_LOG`` option is not specified.
This command supports an alternate signature for CMake older than 3.25.
The signature above is recommended for clarity.
.. code-block:: cmake
try_compile(<resultVar> <bindir> <srcdir>
try_compile(<compileResultVar> <bindir> <srcdir>
<projectName> [<targetName>]
[NO_CACHE]
[CMAKE_FLAGS <flags>...]
[OUTPUT_VARIABLE <var>])
@ -58,12 +64,14 @@ Try Compiling Source Files
.. code-block:: cmake
try_compile(<resultVar>
try_compile(<compileResultVar>
<SOURCES <srcfile...> |
SOURCE_FROM_CONTENT <name> <content> |
SOURCE_FROM_VAR <name> <var> |
SOURCE_FROM_FILE <name> <path> >...
[LOG_DESCRIPTION <text>]
[NO_CACHE]
[NO_LOG]
[CMAKE_FLAGS <flags>...]
[COMPILE_DEFINITIONS <defs>...]
[LINK_OPTIONS <options>...]
@ -79,8 +87,8 @@ Try Compiling Source Files
Try building an executable or static library from one or more source files
(which one is determined by the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE`
variable). The success or failure of the ``try_compile``, i.e. ``TRUE`` or
``FALSE`` respectively, is returned in ``<resultVar>``.
variable). Build success returns ``TRUE`` and build failure returns ``FALSE``
in ``<compileResultVar>``.
In this form, one or more source files must be provided. Additionally, one of
``SOURCES`` and/or ``SOURCE_FROM_*`` must precede other keywords.
@ -105,17 +113,16 @@ contain something like the following:
CMake automatically generates, for each ``try_compile`` operation, a
unique directory under ``${CMAKE_BINARY_DIR}/CMakeFiles/CMakeScratch``
with an unspecified name. These directories are cleaned automatically unless
:option:`--debug-trycompile <cmake --debug-trycompile>` is passed to ``cmake``.
:option:`--debug-trycompile <cmake --debug-trycompile>` is passed to :program:`cmake`.
Such directories from previous runs are also unconditionally cleaned at the
beginning of any ``cmake`` execution.
beginning of any :program:`cmake` execution.
This command also supports an alternate signature
which was present in older versions of CMake:
This command supports an alternate signature for CMake older than 3.25.
The signature above is recommended for clarity.
.. code-block:: cmake
try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...>
[NO_CACHE]
try_compile(<compileResultVar> <bindir> <srcfile|SOURCES srcfile...>
[CMAKE_FLAGS <flags>...]
[COMPILE_DEFINITIONS <defs>...]
[LINK_OPTIONS <options>...]
@ -130,7 +137,7 @@ which was present in older versions of CMake:
In this version, ``try_compile`` will use ``<bindir>/CMakeFiles/CMakeTmp`` for
its operation, and all such files will be cleaned automatically.
For debugging, :option:`--debug-trycompile <cmake --debug-trycompile>` can be
passed to ``cmake`` to avoid this clean. However, multiple sequential
passed to :program:`cmake` to avoid this clean. However, multiple sequential
``try_compile`` operations, if given the same ``<bindir>``, will reuse this
single output directory, such that you can only debug one such ``try_compile``
call at a time. Use of the newer signature is recommended to simplify
@ -171,6 +178,12 @@ The options are:
set the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property in the generated
project, depending on the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable.
``LOG_DESCRIPTION <text>``
.. versionadded:: 3.26
Specify a non-empty text description of the purpose of the check.
This is recorded in the :manual:`cmake-configure-log(7)` entry.
``NO_CACHE``
.. versionadded:: 3.25
@ -191,6 +204,11 @@ The options are:
the test is part of a larger inspection), ``NO_CACHE`` may be useful to avoid
leaking the intermediate result variable into the cache.
``NO_LOG``
.. versionadded:: 3.26
Do not record a :manual:`cmake-configure-log(7)` entry for this call.
``OUTPUT_VARIABLE <var>``
Store the output from the build process in the given variable.
@ -271,13 +289,18 @@ Other Behavior Settings
If :policy:`CMP0083` is set to ``NEW``, then in order to obtain correct
behavior at link time, the ``check_pie_supported()`` command from the
:module:`CheckPIESupported` module must be called before using the
:command:`try_compile` command.
``try_compile`` command.
The current settings of :policy:`CMP0065` and :policy:`CMP0083` are propagated
through to the generated test project.
Set the :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` variable to choose
a build configuration.
Set variable :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` to choose a build
configuration:
* For multi-config generators, this selects which configuration to build.
* For single-config generators, this sets :variable:`CMAKE_BUILD_TYPE` in
the test project.
.. versionadded:: 3.6
Set the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable to specify
@ -327,3 +350,8 @@ a build configuration.
If :policy:`CMP0141` is set to ``NEW``, one can use
:variable:`CMAKE_MSVC_DEBUG_INFORMATION_FORMAT` to specify the MSVC debug
information format.
See Also
^^^^^^^^
* :command:`try_run`

42
Help/command/try_run.rst
Unescape View File

@ -17,7 +17,9 @@ Try Compiling and Running Source Files
SOURCE_FROM_CONTENT <name> <content> |
SOURCE_FROM_VAR <name> <var> |
SOURCE_FROM_FILE <name> <path> >...
[LOG_DESCRIPTION <text>]
[NO_CACHE]
[NO_LOG]
[CMAKE_FLAGS <flags>...]
[COMPILE_DEFINITIONS <defs>...]
[LINK_OPTIONS <options>...]
@ -30,32 +32,36 @@ Try Compiling and Running Source Files
[RUN_OUTPUT_VARIABLE <var>]
[RUN_OUTPUT_STDOUT_VARIABLE <var>]
[RUN_OUTPUT_STDERR_VARIABLE <var>]
[OUTPUT_VARIABLE <var>]
[WORKING_DIRECTORY <var>]
[ARGS <args>...]
)
.. versionadded:: 3.25
Try compiling a ``<srcfile>``. Returns ``TRUE`` or ``FALSE`` for success
or failure in ``<compileResultVar>``. If the compile succeeded, runs the
executable and returns its exit code in ``<runResultVar>``. If the
executable was built, but failed to run, then ``<runResultVar>`` will be
set to ``FAILED_TO_RUN``. See the :command:`try_compile` command for
documentation of options common to both commands, and for information on how
the test project is constructed to build the source file.
Try building an executable from one or more source files. Build success
returns ``TRUE`` and build failure returns ``FALSE`` in ``<compileResultVar>``.
If the build succeeds, this runs the executable and stores the exit code in
``<runResultVar>``. If the executable was built, but failed to run, then
``<runResultVar>`` will be set to ``FAILED_TO_RUN``. See command
:command:`try_compile` for documentation of options common to both commands,
and for information on how the test project is constructed to build the source
file.
One or more source files must be provided. Additionally, one of ``SOURCES``
and/or ``SOURCE_FROM_*`` must precede other keywords.
This command also supports an alternate signature
which was present in older versions of CMake:
.. versionadded:: 3.26
This command records a
:ref:`configure-log try_run event <try_run configure-log event>`
if the ``NO_LOG`` option is not specified.
This command supports an alternate signature for CMake older than 3.25.
The signature above is recommended for clarity.
.. code-block:: cmake
try_run(<runResultVar> <compileResultVar>
<bindir> <srcfile|SOURCES srcfile...>
[NO_CACHE]
[CMAKE_FLAGS <flags>...]
[COMPILE_DEFINITIONS <defs>...]
[LINK_OPTIONS <options>...]
@ -66,8 +72,6 @@ which was present in older versions of CMake:
[<LANG>_STANDARD_REQUIRED <bool>]
[<LANG>_EXTENSIONS <bool>]
[RUN_OUTPUT_VARIABLE <var>]
[RUN_OUTPUT_STDOUT_VARIABLE <var>]
[RUN_OUTPUT_STDERR_VARIABLE <var>]
[OUTPUT_VARIABLE <var>]
[WORKING_DIRECTORY <var>]
[ARGS <args>...]
@ -110,15 +114,19 @@ The options specific to ``try_run`` are:
Other Behavior Settings
^^^^^^^^^^^^^^^^^^^^^^^
Set the :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` variable to choose
a build configuration.
Set variable :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` to choose a build
configuration:
* For multi-config generators, this selects which configuration to build.
* For single-config generators, this sets :variable:`CMAKE_BUILD_TYPE` in
the test project.
Behavior when Cross Compiling
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. versionadded:: 3.3
Use ``CMAKE_CROSSCOMPILING_EMULATOR`` when running cross-compiled
binaries.
Use ``CMAKE_CROSSCOMPILING_EMULATOR`` when running cross-compiled binaries.
When cross compiling, the executable compiled in the first step
usually cannot be run on the build host. The ``try_run`` command checks

5
Help/command/unset.rst
Unescape View File

@ -39,3 +39,8 @@ Subsequent calls of ``$ENV{<variable>}`` will return the empty string.
This command affects only the current CMake process, not the process
from which CMake was called, nor the system environment at large,
nor the environment of subsequent build or test processes.
See Also
^^^^^^^^
* :command:`set`

2
Help/command/use_mangled_mesa.rst
Unescape View File

@ -5,7 +5,7 @@ Disallowed since version 3.0. See CMake Policy :policy:`CMP0030`.
Copy mesa headers for use in combination with system GL.
::
.. code-block:: cmake
use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY)

2
Help/command/utility_source.rst
Unescape View File

@ -5,7 +5,7 @@ Disallowed since version 3.0. See CMake Policy :policy:`CMP0034`.
Specify the source tree of a third-party utility.
::
.. code-block:: cmake
utility_source(cache_entry executable_name
path_to_source [file1 file2 ...])

2
Help/command/variable_requires.rst
Unescape View File

@ -7,7 +7,7 @@ Use the :command:`if` command instead.
Assert satisfaction of an option's required variables.
::
.. code-block:: cmake
variable_requires(TEST_VARIABLE RESULT_VARIABLE
REQUIRED_VARIABLE1

2
Help/command/write_file.rst
Unescape View File

@ -5,7 +5,7 @@ write_file
Use the :command:`file(WRITE)` command instead.
::
.. code-block:: cmake
write_file(filename "message to write"... [APPEND])

50
Help/cpack_gen/archive.rst
Unescape View File

@ -4,19 +4,19 @@ CPack Archive Generator
CPack generator for packaging files into an archive, which can have
any of the following formats:
- 7Z - 7zip - (.7z)
- TBZ2 (.tar.bz2)
- TGZ (.tar.gz)
- TXZ (.tar.xz)
- TZ (.tar.Z)
- TZST (.tar.zst)
- ZIP (.zip)
- 7Z - 7zip - (``.7z``)
- TBZ2 (``.tar.bz2``)
- TGZ (``.tar.gz``)
- TXZ (``.tar.xz``)
- TZ (``.tar.Z``)
- TZST (``.tar.zst``)
- ZIP (``.zip``)
.. versionadded:: 3.1
``7Z`` and ``TXZ`` formats support.
7Z and TXZ formats support.
.. versionadded:: 3.16
``TZST`` format support.
TZST format support.
When this generator is called from ``CPackSourceConfig.cmake`` (or through
the ``package_source`` target), then the generated archive will contain all
@ -47,27 +47,34 @@ Variables specific to CPack Archive generator
.. variable:: CPACK_ARCHIVE_FILE_NAME
CPACK_ARCHIVE_<component>_FILE_NAME
Package file name without extension. The extension is determined from the
archive format (see list above) and automatically appended to the file name.
Note that ``<component>`` is all uppercase in the variable name.
Package file name without extension.
The default is ``<CPACK_PACKAGE_FILE_NAME>[-<component>]``, with spaces
:Default: The default is ``<CPACK_PACKAGE_FILE_NAME>[-<component>]``, with spaces
replaced by '-'.
The extension is determined from the archive format (see list above) and
automatically appended to the file name. Note that ``<component>`` is all
uppercase in the variable name.
.. versionadded:: 3.9
Per-component ``CPACK_ARCHIVE_<component>_FILE_NAME`` variables.
Per-component :variable:`!CPACK_ARCHIVE_<component>_FILE_NAME` variables.
.. variable:: CPACK_ARCHIVE_FILE_EXTENSION
.. versionadded:: 3.25
Package file extension. Default values are given in the list above.
Package file extension.
:Default: Default values are given in the list above.
.. variable:: CPACK_ARCHIVE_COMPONENT_INSTALL
Enable component packaging. If enabled (ON), then the archive generator
creates multiple packages. The default is OFF, which means that a single
package containing files of all components is generated.
Enable component packaging.
:Default: ``OFF``
If enabled (``ON``) multiple packages are generated. By default a single package
containing files of all components is generated.
Variables used by CPack Archive generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -80,10 +87,13 @@ CPack generators which are essentially archives at their core. These include:
.. variable:: CPACK_ARCHIVE_THREADS
The number of threads to use when performing the compression.
.. versionadded:: 3.18
The number of threads to use when performing the compression. If set to
``0``, the number of available cores on the machine will be used instead.
:Default: ``1``
If set to ``0``, the number of available cores on the machine will be used instead.
The default is ``1`` which limits compression to a single thread. Note that
not all compression modes support threading in all environments. Currently,
only the XZ compression may support it.

212
Help/cpack_gen/deb.rst
Unescape View File

@ -8,16 +8,16 @@ 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`.
:variable:`!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 ``CPACK_DEBIAN_XXX`` variables.
specifics :variable:`!CPACK_DEBIAN_XXX` variables.
``CPACK_DEBIAN_<COMPONENT>_XXXX`` variables may be used in order to have
:variable:`!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.
@ -34,10 +34,10 @@ List of CPack DEB generator specific variables:
Enable component packaging for CPackDEB
* Mandatory : NO
* Default : OFF
:Mandatory: No
:Default: ``OFF``
If enabled (ON) multiple packages are generated. By default a single package
If enabled (``ON``) multiple packages are generated. By default a single package
containing files of all components is generated.
.. variable:: CPACK_DEBIAN_PACKAGE_NAME
@ -46,16 +46,16 @@ List of CPack DEB generator specific variables:
Set Package control field (variable is automatically transformed to lower
case).
* Mandatory : YES
* Default :
:Mandatory: Yes
:Default:
- :variable:`CPACK_PACKAGE_NAME` for non-component based
installations
- :variable:`CPACK_DEBIAN_PACKAGE_NAME` suffixed with -<COMPONENT>
- :variable:`CPACK_DEBIAN_PACKAGE_NAME` suffixed with ``-<COMPONENT>``
for component-based installations.
.. versionadded:: 3.5
Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_NAME`` variables.
Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_NAME` variables.
See https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-source
@ -66,8 +66,8 @@ List of CPack DEB generator specific variables:
Package file name.
* Mandatory : YES
* Default : ``<CPACK_PACKAGE_FILE_NAME>[-<component>].deb``
: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::
@ -98,8 +98,8 @@ List of CPack DEB generator specific variables:
The Debian package epoch
* Mandatory : No
* Default : -
:Mandatory: No
:Default: None
Optional number that should be incremented when changing versioning schemas
or fixing mistakes in the version numbers of older packages.
@ -108,8 +108,8 @@ List of CPack DEB generator specific variables:
The Debian package version
* Mandatory : YES
* Default : :variable:`CPACK_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
@ -130,8 +130,8 @@ List of CPack DEB generator specific variables:
The Debian package release - Debian revision number.
* Mandatory : No
* Default : -
:Mandatory: No
:Default: None
This is the numbering of the DEB package itself, i.e. the version of the
packaging and not the version of the content (see
@ -144,20 +144,20 @@ List of CPack DEB generator specific variables:
The Debian package architecture
* Mandatory : YES
* Default : Output of ``dpkg --print-architecture`` (or ``i386``
:Mandatory: Yes
:Default: Output of ``dpkg --print-architecture`` (or ``i386``
if ``dpkg`` is not found)
.. versionadded:: 3.6
Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_ARCHITECTURE`` variables.
Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_ARCHITECTURE` variables.
.. variable:: CPACK_DEBIAN_PACKAGE_DEPENDS
CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS
Sets the Debian dependencies of this package.
* Mandatory : NO
* Default :
:Mandatory: No
:Default:
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_DEPENDS` for component-based
@ -165,7 +165,7 @@ List of CPack DEB generator specific variables:
.. versionadded:: 3.3
Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS`` variables.
Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS` variables.
.. note::
@ -178,7 +178,9 @@ List of CPack DEB generator specific variables:
only the automatically discovered dependencies will be set for this
component.
Example::
Example:
.. code-block:: cmake
set(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libc6 (< 2.4)")
@ -189,23 +191,23 @@ List of CPack DEB generator specific variables:
Sets inter-component dependencies if listed with
:variable:`CPACK_COMPONENT_<compName>_DEPENDS` variables.
* Mandatory : NO
* Default : -
:Mandatory: No
:Default: None
.. variable:: CPACK_DEBIAN_PACKAGE_MAINTAINER
The Debian package maintainer
* Mandatory : YES
* Default : ``CPACK_PACKAGE_CONTACT``
:Mandatory: Yes
:Default: :variable:`!CPACK_PACKAGE_CONTACT`
.. variable:: CPACK_DEBIAN_PACKAGE_DESCRIPTION
CPACK_DEBIAN_<COMPONENT>_DESCRIPTION
The Debian package description
* Mandatory : YES
* Default :
:Mandatory: Yes
:Default:
- :variable:`CPACK_DEBIAN_<COMPONENT>_DESCRIPTION` (component
based installers only) if set, or :variable:`CPACK_DEBIAN_PACKAGE_DESCRIPTION` if set, or
@ -218,13 +220,13 @@ List of CPack DEB generator specific variables:
line of description as defined in `Debian Policy Manual`_.
.. versionadded:: 3.3
Per-component ``CPACK_COMPONENT_<compName>_DESCRIPTION`` variables.
Per-component :variable:`!CPACK_COMPONENT_<compName>_DESCRIPTION` variables.
.. versionadded:: 3.16
Per-component ``CPACK_DEBIAN_<COMPONENT>_DESCRIPTION`` variables.
Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_DESCRIPTION` variables.
.. versionadded:: 3.16
The ``CPACK_PACKAGE_DESCRIPTION_FILE`` variable.
The :variable:`!CPACK_PACKAGE_DESCRIPTION_FILE` variable.
.. _Debian Policy Manual: https://www.debian.org/doc/debian-policy/ch-controlfields.html#description
@ -233,11 +235,11 @@ List of CPack DEB generator specific variables:
Set Section control field e.g. admin, devel, doc, ...
* Mandatory : YES
* Default : "devel"
:Mandatory: Yes
:Default: ``devel``
.. versionadded:: 3.5
Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_SECTION`` variables.
Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_SECTION` variables.
See https://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections
@ -249,12 +251,10 @@ List of CPack DEB generator specific variables:
The archive format used for creating the Debian package.
* Mandatory : YES
* Default : "gnutar"
Possible value is:
:Mandatory: Yes
:Default: ``gnutar``
- gnutar
Possible value is: ``gnutar``
.. note::
@ -269,8 +269,8 @@ List of CPack DEB generator specific variables:
The compression used for creating the Debian package.
* Mandatory : YES
* Default : "gzip"
:Mandatory: Yes
:Default: ``gzip``
Possible values are:
@ -298,11 +298,11 @@ List of CPack DEB generator specific variables:
Set Priority control field e.g. required, important, standard, optional,
extra
* Mandatory : YES
* Default : "optional"
:Mandatory: Yes
:Default: ``optional``
.. versionadded:: 3.5
Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY`` variables.
Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY` variables.
See https://www.debian.org/doc/debian-policy/ch-archive.html#s-priorities
@ -312,11 +312,11 @@ List of CPack DEB generator specific variables:
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`
:Mandatory: No
:Default: :variable:`CMAKE_PROJECT_HOMEPAGE_URL`
.. versionadded:: 3.12
The ``CMAKE_PROJECT_HOMEPAGE_URL`` variable.
The :variable:`!CMAKE_PROJECT_HOMEPAGE_URL` variable.
.. note::
@ -329,11 +329,11 @@ List of CPack DEB generator specific variables:
May be set to ON in order to use ``dpkg-shlibdeps`` to generate
better package dependency list.
* Mandatory : NO
* Default :
:Mandatory: No
:Default:
- :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS` if set or
- OFF
- ``OFF``
.. note::
@ -350,7 +350,7 @@ List of CPack DEB generator specific variables:
shared libraries that could not get resolved otherwise.
.. versionadded:: 3.3
Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS`` variables.
Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS` variables.
.. versionadded:: 3.6
Correct handling of ``$ORIGIN`` in :variable:`CMAKE_INSTALL_RPATH`.
@ -363,8 +363,8 @@ List of CPack DEB generator specific variables:
via its ``-l`` option. These will be searched by ``dpkg-shlibdeps`` in order
to find private shared library dependencies.
* Mandatory : NO
* Default :
:Mandatory: No
:Default: None
.. note::
@ -377,8 +377,8 @@ List of CPack DEB generator specific variables:
May be set when invoking cpack in order to trace debug information
during the CPack DEB generator run.
* Mandatory : NO
* Default : -
:Mandatory: No
:Default: None
.. variable:: CPACK_DEBIAN_PACKAGE_PREDEPENDS
CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS
@ -389,58 +389,58 @@ List of CPack DEB generator specific variables:
before even starting the installation of the package which declares the
pre-dependency.
* Mandatory : NO
* Default :
:Mandatory: No
:Default:
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_PREDEPENDS` for component-based
installations.
.. versionadded:: 3.4
Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS`` variables.
Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS` variables.
See https://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.
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 :
:Mandatory: No
:Default:
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_ENHANCES` for component-based
installations.
.. versionadded:: 3.4
Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES`` variables.
Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES` variables.
See https://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.
Sets the ``Breaks`` field of the Debian package.
When a binary package (P) declares that it breaks other packages (B),
``dpkg`` will not allow the package (P) which declares `Breaks` be
``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 :
:Mandatory: No
:Default:
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_BREAKS` for component-based
installations.
.. versionadded:: 3.4
Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS`` variables.
Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS` variables.
See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-breaks
@ -452,15 +452,15 @@ List of CPack DEB generator specific variables:
field, ``dpkg`` will not allow them to be unpacked on the system at
the same time.
* Mandatory : NO
* Default :
:Mandatory: No
:Default:
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_CONFLICTS` for component-based
installations.
.. versionadded:: 3.4
Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONFLICTS`` variables.
Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONFLICTS` variables.
See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-conflicts
@ -479,15 +479,15 @@ List of CPack DEB generator specific variables:
A virtual package is one which appears in the `Provides` control field of
another package.
* Mandatory : NO
* Default :
:Mandatory: No
:Default:
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_PROVIDES` for component-based
installations.
.. versionadded:: 3.4
Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_PROVIDES`` variables.
Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_PROVIDES` variables.
See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-virtual
@ -498,34 +498,34 @@ List of CPack DEB generator specific variables:
Packages can declare in their control file that they should overwrite
files in certain other packages, or completely replace other packages.
* Mandatory : NO
* Default :
:Mandatory: No
:Default:
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_REPLACES` for component-based
installations.
.. versionadded:: 3.4
Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_REPLACES`` variables.
Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_REPLACES` variables.
See https://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.
Sets the ``Recommends`` field of the Debian package.
Allows packages to declare a strong, but not absolute, dependency on other
packages.
* Mandatory : NO
* Default :
:Mandatory: No
:Default:
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_RECOMMENDS` for component-based
installations.
.. versionadded:: 3.4
Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS`` variables.
Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS` variables.
See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
@ -535,15 +535,15 @@ List of CPack DEB generator specific variables:
Sets the `Suggests` field of the Debian package.
Allows packages to declare a suggested package install grouping.
* Mandatory : NO
* Default :
:Mandatory: No
:Default:
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_SUGGESTS` for component-based
installations.
.. versionadded:: 3.4
Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_SUGGESTS`` variables.
Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_SUGGESTS` variables.
See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
@ -551,8 +551,8 @@ List of CPack DEB generator specific variables:
.. versionadded:: 3.6
* Mandatory : NO
* Default : OFF
:Mandatory: No
:Default: ``OFF``
Allows to generate shlibs control file automatically. Compatibility is defined by
:variable:`CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS_POLICY` variable value.
@ -569,11 +569,11 @@ List of CPack DEB generator specific variables:
Compatibility policy for auto-generated shlibs control file.
* Mandatory : NO
* Default : "="
:Mandatory: No
:Default: ``=``
Defines compatibility policy for auto-generated shlibs control file.
Possible values: "=", ">="
Possible values: ``=``, ``>=``
See https://www.debian.org/doc/debian-policy/ch-sharedlibs.html#s-sharedlibs-shlibdeps
@ -584,16 +584,18 @@ List of CPack DEB generator specific variables:
control.tar.gz.
Typical usage is for conffiles, postinst, postrm, prerm.
* Mandatory : NO
* Default : -
:Mandatory: No
:Default: None
Usage::
Usage:
.. code-block:: cmake
set(CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA
"${CMAKE_CURRENT_SOURCE_DIR}/prerm;${CMAKE_CURRENT_SOURCE_DIR}/postrm")
.. versionadded:: 3.4
Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_EXTRA`` variables.
Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_EXTRA` variables.
.. variable:: CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION
CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_STRICT_PERMISSION
@ -603,10 +605,12 @@ List of CPack DEB generator specific variables:
This variable indicates if the Debian policy on control files should be
strictly followed.
* Mandatory : NO
* Default : FALSE
:Mandatory: No
:Default: ``FALSE``
Usage:
Usage::
.. code-block:: cmake
set(CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION TRUE)
@ -632,8 +636,8 @@ List of CPack DEB generator specific variables:
source) the source from which the binary has been generated should be
indicated with the field ``Source``.
* Mandatory : NO
* Default :
:Mandatory: No
:Default:
- An empty string for non-component based installations
- :variable:`CPACK_DEBIAN_PACKAGE_SOURCE` for component-based
@ -660,8 +664,8 @@ Dbgsym packaging has its own set of variables:
Enable generation of dbgsym .ddeb package(s).
* Mandatory : NO
* Default : OFF
:Mandatory: No
:Default: ``OFF``
.. note::
@ -683,7 +687,7 @@ Building Debian packages on Windows
.. versionadded:: 3.10
To communicate UNIX file permissions from the install stage
to the CPack DEB generator the "cmake_mode_t" NTFS
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
@ -694,7 +698,7 @@ Reproducible packages
.. versionadded:: 3.13
The environment variable ``SOURCE_DATE_EPOCH`` may be set to a UNIX
The environment variable :envvar:`!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.

32
Help/cpack_gen/dmg.rst
Unescape View File

@ -11,14 +11,19 @@ on macOS:
.. variable:: CPACK_DMG_VOLUME_NAME
The volume name of the generated disk image. Defaults to
CPACK_PACKAGE_FILE_NAME.
The volume name of the generated disk image.
:Default: :variable:`CPACK_PACKAGE_FILE_NAME`
.. variable:: CPACK_DMG_FORMAT
The disk image format. Common values are ``UDRO`` (UDIF read-only), ``UDZO`` (UDIF
The disk image format.
:Default: ``UDZO``
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``.
more information on other available formats.
.. variable:: CPACK_DMG_DS_STORE
@ -41,6 +46,8 @@ on macOS:
.. variable:: CPACK_DMG_BACKGROUND_IMAGE
:Default:
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
@ -58,13 +65,15 @@ on macOS:
.. versionadded:: 3.23
:Default: ``OFF``
Control whether :variable:`CPACK_RESOURCE_FILE_LICENSE`, if set to a
non-default value, is used as the license agreement provided when
mounting the DMG. If ``CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE`` is
mounting the DMG. If :variable:`!CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` is
not set, :manual:`cpack(1)` defaults to off.
In a CMake project that uses the :module:`CPack` module to generate
``CPackConfig.cmake``, ``CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE``
``CPackConfig.cmake``, :variable:`!CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE`
must be explicitly enabled by the project to activate the SLA.
See policy :policy:`CMP0133`.
@ -82,8 +91,8 @@ on macOS:
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`` or ``<language>.license.rtf`` 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
language defined in :variable:`CPACK_DMG_SLA_LANGUAGES`. If both this variable and
:variable:`CPACK_RESOURCE_FILE_LICENSE` are set, CPack will only look for the menu
files and use the same license file for all languages. If both
``<language>.license.txt`` and ``<language>.license.rtf`` exist, the ``.txt``
file will be used.
@ -120,17 +129,18 @@ on macOS:
.. versionadded:: 3.17
File name when packaging ``<component>`` as its own DMG
(``CPACK_COMPONENTS_GROUPING`` set to IGNORE).
(:variable:`CPACK_COMPONENTS_GROUPING` set to ``IGNORE``).
- Default: ``CPACK_PACKAGE_FILE_NAME-<component>``
:Default: ``CPACK_PACKAGE_FILE_NAME-<component>``
.. variable:: CPACK_DMG_FILESYSTEM
.. versionadded:: 3.21
:Default: ``HFS+``
The filesystem format. Common values are ``APFS`` and ``HFS+``.
See ``man hdiutil`` for a full list of supported formats.
Defaults to ``HFS+``.
.. variable:: CPACK_COMMAND_HDIUTIL

Some files were not shown because too many files have changed in this diff Show More

Write Preview
Loading…
Cancel
Save