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

New upstream version 3.15.4

Browse Source
This commit is contained in:
Felix Geyer 2019-11-11 23:01:05 +01:00
parent a8473d76f3
commit 80652e0087
3936 changed files with 158588 additions and 60494 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
.clang-tidy
View File

@ -1,5 +1,8 @@
---
Checks: "-*,\
bugprone-*,\
-bugprone-macro-parentheses,\
-bugprone-misplaced-widening-cast,\
google-readability-casting,\
misc-*,\
-misc-incorrect-roundings,\
@ -8,14 +11,8 @@ misc-*,\
-misc-static-assert,\
modernize-*,\
-modernize-deprecated-headers,\
-modernize-pass-by-value,\
-modernize-raw-string-literal,\
-modernize-return-braced-init-list,\
-modernize-use-auto,\
-modernize-use-default-member-init,\
-modernize-use-emplace,\
-modernize-use-equals-default,\
-modernize-use-equals-delete,\
-modernize-use-noexcept,\
-modernize-use-transparent-functors,\
-modernize-use-using,\
@ -25,11 +22,15 @@ readability-*,\
-readability-function-size,\
-readability-identifier-naming,\
-readability-implicit-bool-cast,\
-readability-implicit-bool-conversion,\
-readability-inconsistent-declaration-parameter-name,\
-readability-named-parameter,\
-readability-redundant-declaration,\
-readability-redundant-member-init,\
-readability-simplify-boolean-expr,\
"
HeaderFilterRegex: 'Source/cm[^/]*\.(h|hxx|cxx)$'
CheckOptions:
- key: modernize-use-default-member-init.UseAssignment
value: '1'
- key: modernize-use-equals-default.IgnoreMacros
value: '0'
...

5
Auxiliary/bash-completion/cmake
View File

@ -96,7 +96,7 @@ _cmake()
_filedir
return
;;
--build|--open)
--build|--install|--open)
_filedir -d
return
;;
@ -116,6 +116,9 @@ _cmake()
2>/dev/null )' -- "$quoted" ) )
return
;;
--loglevel)
COMPREPLY=( $(compgen -W 'error warning notice status verbose debug trace' -- $cur ) )
;;
--help-command)
COMPREPLY=( $( compgen -W '$( cmake --help-command-list 2>/dev/null|
grep -v "^cmake version " )' -- "$cur" ) )

2
Auxiliary/cmake.m4
View File

@ -13,7 +13,7 @@ fi
# $2: language (e.g. C/CXX/Fortran)
# $3: The compiler ID, defaults to GNU.
# Possible values are: GNU, Intel, Clang, SunPro, HP, XL, VisualAge, PGI,
# PathScale, Cray, SCO, MIPSpro, MSVC
# PathScale, Cray, SCO, MSVC
# $4: optional extra arguments to cmake, e.g. "-DCMAKE_SIZEOF_VOID_P=8"
# $5: optional path to cmake binary
AC_DEFUN([CMAKE_FIND_PACKAGE], [

4
Auxiliary/vim/cmake.vim.in
View File

@ -31,11 +31,11 @@ syn region cmakeGeneratorExpression start="$<" end=">" contained oneline contain
syn region cmakeString start='"' end='"' contained contains=cmakeTodo,cmakeVariableValue,cmakeEscaped
syn region cmakeVariableValue start="${" end="}" contained oneline contains=cmakeVariable,cmakeTodo
syn region cmakeVariableValue start="${" end="}" contained oneline contains=cmakeVariable,cmakeTodo,cmakeVariableValue
syn region cmakeEnvironment start="$ENV{" end="}" contained oneline contains=cmakeTodo
syn region cmakeArguments start="(" end=")" contains=ALLBUT,cmakeCommand,cmakeCommandConditional,cmakeCommandRepeat,cmakeCommandDeprecated,cmakeCommandManuallyAdded,cmakeArguments,cmakeTodo
syn region cmakeArguments start="(" end=")" contains=ALLBUT,cmakeGeneratorExpressions,cmakeCommand,cmakeCommandConditional,cmakeCommandRepeat,cmakeCommandDeprecated,cmakeCommandManuallyAdded,cmakeArguments,cmakeTodo
syn case match

18
Auxiliary/vim/extract-upper-case.pl
View File

@ -13,6 +13,9 @@ my @properties;
my @modules;
my %keywords; # command => keyword-list
# find cmake/Modules/ | sed -rn 's/.*CMakeDetermine(.+)Compiler.cmake/\1/p' | sort
my @languages = qw(ASM ASM_MASM ASM_NASM C CSharp CUDA CXX Fortran Java RC Swift);
# unwanted upper-cases
my %unwanted = map { $_ => 1 } qw(VS CXX IDE NOTFOUND NO_ DFOO DBAR NEW);
# cannot remove ALL - exists for add_custom_command
@ -30,8 +33,21 @@ push @modules, "ExternalProject";
# variables
open(CMAKE, "$cmake --help-variable-list|") or die "could not run cmake";
while (<CMAKE>) {
next if /\</; # skip if containing < or >
chomp;
if (/<(.*?)>/) {
if ($1 eq 'LANG') {
foreach my $lang (@languages) {
(my $V = $_) =~ s/<.*>/$lang/;
push @variables, $V;
}
next
} else {
next; # skip if containing < or >
}
}
push @variables, $_;
}
close(CMAKE);

889
Auxiliary/vim/syntax/cmake.vim
View File

File diff suppressed because it is too large Load Diff

3
CMakeCPack.cmake
View File

@ -102,9 +102,6 @@ if(CMake_INSTALL_COMPONENTS)
if(WIN32 AND NOT CYGWIN)
list(APPEND _CPACK_IFW_COMPONENTS_ALL cmcldeps)
endif()
if(APPLE)
list(APPEND _CPACK_IFW_COMPONENTS_ALL cmakexbuild)
endif()
if(CMAKE_INSTALL_DEFAULT_COMPONENT_NAME)
set(_CPACK_IFW_COMPONENT_UNSPECIFIED_NAME
${CMAKE_INSTALL_DEFAULT_COMPONENT_NAME})

10
CMakeCPackOptions.cmake.in
View File

@ -109,16 +109,6 @@ if(CPACK_GENERATOR MATCHES "IFW")
set(CPACK_IFW_COMPONENT_CMCLDEPS_VERSION
"@CMake_IFW_ROOT_COMPONENT_VERSION@")
set(CPACK_COMPONENT_CMAKEXBUILD_DISPLAY_NAME "cmakexbuild")
set(CPACK_COMPONENT_CMAKEXBUILD_DESCRIPTION
"The \"cmakexbuild\" executable is a wrapper program for \"xcodebuild\"")
set(CPACK_COMPONENT_CMAKEXBUILD_REQUIRED TRUE)
set(CPACK_COMPONENT_CMAKEXBUILD_GROUP Tools)
set(CPACK_IFW_COMPONENT_CMAKEXBUILD_NAME "CMakeXBuild")
set(CPACK_IFW_COMPONENT_CMAKEXBUILD_PRIORITY 85)
set(CPACK_IFW_COMPONENT_CMAKEXBUILD_VERSION
"@CMake_IFW_ROOT_COMPONENT_VERSION@")
# Dialogs
set(CPACK_COMPONENT_GROUP_DIALOGS_DISPLAY_NAME "Interactive Dialogs")
set(CPACK_COMPONENT_GROUP_DIALOGS_DESCRIPTION

80
CMakeLists.txt
View File

@ -1,7 +1,7 @@
# 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.1 FATAL_ERROR)
cmake_minimum_required(VERSION 3.1...3.14 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)
project(CMake)
@ -117,6 +117,18 @@ option(CMake_BUILD_DEVELOPER_REFERENCE
"Build CMake Developer Reference" OFF)
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)
check_ipo_supported(RESULT HAVE_IPO)
if(HAVE_IPO)
set(CMAKE_INTERPROCEDURAL_OPTIMIZATION TRUE)
endif()
endif()
endif()
#-----------------------------------------------------------------------
# a macro to deal with system libraries, implemented as a macro
# simply to improve readability of the main script
@ -125,13 +137,9 @@ macro(CMAKE_HANDLE_SYSTEM_LIBRARIES)
# Options have dependencies.
include(CMakeDependentOption)
# Optionally use system xmlrpc. We no longer build or use it by default.
option(CTEST_USE_XMLRPC "Enable xmlrpc submission method in CTest." OFF)
mark_as_advanced(CTEST_USE_XMLRPC)
# Allow the user to enable/disable all system utility library options by
# defining CMAKE_USE_SYSTEM_LIBRARIES or CMAKE_USE_SYSTEM_LIBRARY_${util}.
set(UTILITIES BZIP2 CURL EXPAT FORM JSONCPP LIBARCHIVE LIBLZMA LIBRHASH LIBUV ZLIB)
set(UTILITIES BZIP2 CURL EXPAT FORM JSONCPP LIBARCHIVE LIBLZMA LIBRHASH LIBUV ZLIB ZSTD)
foreach(util ${UTILITIES})
if(NOT DEFINED CMAKE_USE_SYSTEM_LIBRARY_${util}
AND DEFINED CMAKE_USE_SYSTEM_LIBRARIES)
@ -159,14 +167,14 @@ macro(CMAKE_HANDLE_SYSTEM_LIBRARIES)
# Optionally use system utility libraries.
option(CMAKE_USE_SYSTEM_LIBARCHIVE "Use system-installed libarchive" "${CMAKE_USE_SYSTEM_LIBRARY_LIBARCHIVE}")
CMAKE_DEPENDENT_OPTION(CMAKE_USE_SYSTEM_CURL "Use system-installed curl"
"${CMAKE_USE_SYSTEM_LIBRARY_CURL}" "NOT CTEST_USE_XMLRPC" ON)
CMAKE_DEPENDENT_OPTION(CMAKE_USE_SYSTEM_EXPAT "Use system-installed expat"
"${CMAKE_USE_SYSTEM_LIBRARY_EXPAT}" "NOT CTEST_USE_XMLRPC" ON)
option(CMAKE_USE_SYSTEM_CURL "Use system-installed curl" "${CMAKE_USE_SYSTEM_LIBRARY_CURL}")
option(CMAKE_USE_SYSTEM_EXPAT "Use system-installed expat" "${CMAKE_USE_SYSTEM_LIBRARY_EXPAT}")
CMAKE_DEPENDENT_OPTION(CMAKE_USE_SYSTEM_ZLIB "Use system-installed zlib"
"${CMAKE_USE_SYSTEM_LIBRARY_ZLIB}" "NOT CMAKE_USE_SYSTEM_LIBARCHIVE;NOT CMAKE_USE_SYSTEM_CURL" ON)
CMAKE_DEPENDENT_OPTION(CMAKE_USE_SYSTEM_BZIP2 "Use system-installed bzip2"
"${CMAKE_USE_SYSTEM_LIBRARY_BZIP2}" "NOT CMAKE_USE_SYSTEM_LIBARCHIVE" ON)
CMAKE_DEPENDENT_OPTION(CMAKE_USE_SYSTEM_ZSTD "Use system-installed zstd"
"${CMAKE_USE_SYSTEM_LIBRARY_ZSTD}" "NOT CMAKE_USE_SYSTEM_LIBARCHIVE" ON)
CMAKE_DEPENDENT_OPTION(CMAKE_USE_SYSTEM_LIBLZMA "Use system-installed liblzma"
"${CMAKE_USE_SYSTEM_LIBRARY_LIBLZMA}" "NOT CMAKE_USE_SYSTEM_LIBARCHIVE" ON)
option(CMAKE_USE_SYSTEM_FORM "Use system-installed libform" "${CMAKE_USE_SYSTEM_LIBRARY_FORM}")
@ -200,7 +208,7 @@ endmacro()
macro(CMAKE_SETUP_TESTING)
if(BUILD_TESTING)
set(CMAKE_TEST_SYSTEM_LIBRARIES 0)
foreach(util CURL EXPAT XMLRPC ZLIB)
foreach(util CURL EXPAT ZLIB)
if(CMAKE_USE_SYSTEM_${util})
set(CMAKE_TEST_SYSTEM_LIBRARIES 1)
endif()
@ -326,6 +334,9 @@ macro (CMAKE_BUILD_UTILITIES)
set(KWSYS_USE_ConsoleBuf 1)
set(KWSYS_HEADER_ROOT ${CMake_BINARY_DIR}/Source)
set(KWSYS_INSTALL_DOC_DIR "${CMAKE_DOC_DIR}")
if(CMake_NO_CXX_STANDARD)
set(KWSYS_CXX_STANDARD "")
endif()
add_subdirectory(Source/kwsys)
set(kwsys_folder "Utilities/KWSys")
CMAKE_SET_TARGET_FOLDER(${KWSYS_NAMESPACE} "${kwsys_folder}")
@ -435,14 +446,6 @@ macro (CMAKE_BUILD_UTILITIES)
CMAKE_SET_TARGET_FOLDER(LIBCURL "Utilities/3rdParty")
endif()
#---------------------------------------------------------------------
# Build Compress library for CTest.
set(CMAKE_COMPRESS_INCLUDES
"${CMAKE_CURRENT_BINARY_DIR}/Utilities/cmcompress")
set(CMAKE_COMPRESS_LIBRARIES "cmcompress")
add_subdirectory(Utilities/cmcompress)
CMAKE_SET_TARGET_FOLDER(cmcompress "Utilities/3rdParty")
#---------------------------------------------------------------------
# Build expat library for CMake, CTest, and libarchive.
if(CMAKE_USE_SYSTEM_EXPAT)
@ -474,6 +477,17 @@ macro (CMAKE_BUILD_UTILITIES)
endif()
endif()
#---------------------------------------------------------------------
# Build or use system zstd for libarchive.
if(NOT CMAKE_USE_SYSTEM_LIBARCHIVE)
if(NOT CMAKE_USE_SYSTEM_ZSTD)
set(ZSTD_INCLUDE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/Utilities/cmzstd")
set(ZSTD_LIBRARY cmzstd)
add_subdirectory(Utilities/cmzstd)
CMAKE_SET_TARGET_FOLDER(cmzstd "Utilities/3rdParty")
endif()
endif()
#---------------------------------------------------------------------
# Build or use system liblzma for libarchive.
if(NOT CMAKE_USE_SYSTEM_LIBARCHIVE)
@ -497,7 +511,7 @@ macro (CMAKE_BUILD_UTILITIES)
#---------------------------------------------------------------------
# Build or use system libarchive for CMake and CTest.
if(CMAKE_USE_SYSTEM_LIBARCHIVE)
find_package(LibArchive 3.1.0)
find_package(LibArchive 3.3.3)
if(NOT LibArchive_FOUND)
message(FATAL_ERROR "CMAKE_USE_SYSTEM_LIBARCHIVE is ON but LibArchive is not found!")
endif()
@ -532,11 +546,15 @@ macro (CMAKE_BUILD_UTILITIES)
#---------------------------------------------------------------------
# Build jsoncpp library.
if(CMAKE_USE_SYSTEM_JSONCPP)
find_package(JsonCpp)
find_package(JsonCpp 1.4.1)
if(NOT JsonCpp_FOUND)
message(FATAL_ERROR
"CMAKE_USE_SYSTEM_JSONCPP is ON but a JsonCpp is not found!")
endif()
if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
set_property(TARGET JsonCpp::JsonCpp APPEND PROPERTY
INTERFACE_COMPILE_OPTIONS -Wno-deprecated-declarations)
endif()
set(CMAKE_JSONCPP_LIBRARIES JsonCpp::JsonCpp)
else()
set(CMAKE_JSONCPP_LIBRARIES cmjsoncpp)
@ -559,18 +577,6 @@ macro (CMAKE_BUILD_UTILITIES)
CMAKE_SET_TARGET_FOLDER(cmlibuv "Utilities/3rdParty")
endif()
#---------------------------------------------------------------------
# Build XMLRPC library for CMake and CTest.
if(CTEST_USE_XMLRPC)
find_package(XMLRPC QUIET REQUIRED libwww-client)
if(NOT XMLRPC_FOUND)
message(FATAL_ERROR
"CTEST_USE_XMLRPC is ON but xmlrpc is not found!")
endif()
set(CMAKE_XMLRPC_INCLUDES ${XMLRPC_INCLUDE_DIRS})
set(CMAKE_XMLRPC_LIBRARIES ${XMLRPC_LIBRARIES})
endif()
#---------------------------------------------------------------------
# Use curses?
if (UNIX)
@ -724,7 +730,7 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
# the build tree, which is both the build and the install RPATH.
if (UNIX)
if( CMAKE_USE_SYSTEM_CURL OR CMAKE_USE_SYSTEM_ZLIB
OR CMAKE_USE_SYSTEM_EXPAT OR CTEST_USE_XMLRPC OR CURSES_NEED_RPATH OR QT_NEED_RPATH)
OR CMAKE_USE_SYSTEM_EXPAT OR CURSES_NEED_RPATH OR QT_NEED_RPATH)
set(CMAKE_SKIP_RPATH OFF CACHE INTERNAL "CMake built with RPATH.")
set(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE)
set(CMAKE_BUILD_WITH_INSTALL_RPATH TRUE)
@ -816,4 +822,10 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
# Install auxiliary files integrating with other tools.
add_subdirectory(Auxiliary)
# Optionally sign installed binaries.
if(CMake_INSTALL_SIGNTOOL)
configure_file(Source/CMakeInstallSignTool.cmake.in Source/CMakeInstallSignTool.cmake @ONLY)
install(SCRIPT ${CMAKE_CURRENT_BINARY_DIR}/Source/CMakeInstallSignTool.cmake)
endif()
endif()

4
CONTRIBUTING.rst
View File

@ -24,7 +24,8 @@ CMake uses `Kitware's GitLab Instance`_ to manage development and code review.
To contribute patches:
#. Fork the upstream `CMake Repository`_ into a personal account.
#. Run `Utilities/SetupForDevelopment.sh`_ for local configuration.
#. Run `Utilities/SetupForDevelopment.sh`_ for local git configuration.
#. See `Building CMake`_ for building CMake locally.
#. See the `CMake Source Code Guide`_ for coding guidelines.
#. Base all new work on the upstream ``master`` branch.
Base work on the upstream ``release`` branch only if it fixes a
@ -45,6 +46,7 @@ The merge request will enter the `CMake Review Process`_ for consideration.
.. _`Kitware's GitLab Instance`: https://gitlab.kitware.com
.. _`CMake Repository`: https://gitlab.kitware.com/cmake/cmake
.. _`Utilities/SetupForDevelopment.sh`: Utilities/SetupForDevelopment.sh
.. _`Building CMake`: README.rst#building-cmake
.. _`CMake Source Code Guide`: Help/dev/source.rst
.. _`commit messages`: Help/dev/review.rst#commit-messages
.. _`CMake Review Process`: Help/dev/review.rst

1
CTestCustom.cmake.in
View File

@ -52,6 +52,7 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
"(Lexer|Parser).*warning.*conversion.*may (alter its value|change the sign)"
"(Lexer|Parser).*warning.*(statement is unreachable|will never be executed)"
"(Lexer|Parser).*warning.*variable.*was set but never used"
"LexerParser.*warning.*empty expression statement has no effect; remove unnecessary"
"PGC-W-0095-Type cast required for this conversion.*ProcessUNIX.c"
"[Qq]t([Cc]ore|[Gg]ui|[Ww]idgets).*warning.*conversion.*may alter its value"
"warning:.*is.*very unsafe.*consider using.*"

27
CompileFlags.cmake
View File

@ -8,11 +8,16 @@ if(WIN32 AND CMAKE_C_COMPILER_ID STREQUAL "Intel")
set(_INTEL_WINDOWS 1)
endif()
if(WIN32 AND CMAKE_C_COMPILER_ID STREQUAL "Clang"
AND "x${CMAKE_CXX_SIMULATE_ID}" STREQUAL "xMSVC")
set(_CLANG_MSVC_WINDOWS 1)
endif()
# Disable deprecation warnings for standard C functions.
# really only needed for newer versions of VS, but should
# not hurt other versions, and this will work into the
# future
if(MSVC OR _INTEL_WINDOWS)
if(MSVC OR _INTEL_WINDOWS OR _CLANG_MSVC_WINDOWS)
add_definitions(-D_CRT_SECURE_NO_DEPRECATE -D_CRT_NONSTDC_NO_DEPRECATE)
else()
endif()
@ -21,6 +26,10 @@ if(MSVC)
set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -stack:10000000")
endif()
if(_CLANG_MSVC_WINDOWS AND "x${CMAKE_CXX_COMPILER_FRONTEND_VARIANT}" STREQUAL "xGNU")
set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -Xlinker -stack:20000000")
endif()
#silence duplicate symbol warnings on AIX
if(CMAKE_SYSTEM_NAME MATCHES "AIX")
if(NOT CMAKE_COMPILER_IS_GNUCXX)
@ -28,13 +37,6 @@ if(CMAKE_SYSTEM_NAME MATCHES "AIX")
endif()
endif()
if(CMAKE_SYSTEM_NAME MATCHES "IRIX")
if(NOT CMAKE_COMPILER_IS_GNUCXX)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wl,-woff84 -no_auto_include")
set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -Wl,-woff15")
endif()
endif()
if(CMAKE_SYSTEM MATCHES "OSF1-V")
if(NOT CMAKE_COMPILER_IS_GNUCXX)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -timplicit_local -no_implicit_include ")
@ -51,6 +53,15 @@ if(CMAKE_SYSTEM_PROCESSOR MATCHES "^parisc")
endif()
endif()
# Workaround for TOC Overflow on ppc64
if(CMAKE_SYSTEM_NAME STREQUAL "AIX" AND
CMAKE_SYSTEM_PROCESSOR MATCHES "powerpc")
set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -Wl,-bbigtoc")
elseif(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND
CMAKE_SYSTEM_PROCESSOR MATCHES "ppc64")
set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -Wl,--no-multi-toc")
endif()
if (CMAKE_CXX_COMPILER_ID STREQUAL SunPro AND
NOT DEFINED CMAKE_CXX${CMAKE_CXX_STANDARD}_STANDARD_COMPILE_OPTION)
if (NOT CMAKE_CXX_COMPILER_VERSION VERSION_LESS 5.13)

7
Copyright.txt
View File

@ -1,5 +1,5 @@
CMake - Cross Platform Makefile Generator
Copyright 2000-2018 Kitware, Inc. and Contributors
Copyright 2000-2019 Kitware, Inc. and Contributors
All rights reserved.
Redistribution and use in source and binary forms, with or without
@ -39,6 +39,7 @@ The following individuals and institutions are among the Contributors:
* Alexander Neundorf <neundorf@kde.org>
* Alexander Smorkalov <alexander.smorkalov@itseez.com>
* Alexey Sokolov <sokolov@google.com>
* Alex Merry <alex.merry@kde.org>
* Alex Turbov <i.zaufi@gmail.com>
* Andreas Pakulat <apaku@gmx.de>
* Andreas Schneider <asn@cryptomilk.org>
@ -62,13 +63,17 @@ The following individuals and institutions are among the Contributors:
* Ilya Lavrenov <ilya.lavrenov@itseez.com>
* Insight Software Consortium <insightsoftwareconsortium.org>
* Jan Woetzel
* Julien Schueller
* Kelly Thompson <kgt@lanl.gov>
* Laurent Montel <montel@kde.org>
* Konstantin Podsvirov <konstantin@podsvirov.pro>
* Mario Bensi <mbensi@ipsquad.net>
* Martin Gräßlin <mgraesslin@kde.org>
* Mathieu Malaterre <mathieu.malaterre@gmail.com>
* Matthaeus G. Chajdas
* Matthias Kretz <kretz@kde.org>
* Matthias Maennich <matthias@maennich.net>
* Michael Hirsch, Ph.D. <www.scivision.co>
* Michael Stürmer
* Miguel A. Figueroa-Villanueva
* Mike Jackson

2
Help/command/FIND_XXX.txt
View File

@ -96,7 +96,7 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
2. Search paths specified in cmake-specific cache variables.
These are intended to be used on the command line with a ``-DVAR=value``.
The values are interpreted as :ref:`;-lists <CMake Language Lists>`.
The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`.
This can be skipped if ``NO_CMAKE_PATH`` is passed.
* |CMAKE_PREFIX_PATH_XXX|

4
Help/command/add_compile_definitions.rst
View File

@ -1,9 +1,9 @@
add_compile_definitions
-----------------------
Adds preprocessor definitions to the compilation of source files.
Add preprocessor definitions to the compilation of source files.
::
.. code-block:: cmake
add_compile_definitions(<definition> ...)

43
Help/command/add_compile_options.rst
View File

@ -1,21 +1,18 @@
add_compile_options
-------------------
Adds options to the compilation of source files.
Add options to the compilation of source files.
::
.. code-block:: cmake
add_compile_options(<option> ...)
Adds options to the compiler command line for targets in the current
directory and below that are added after this command is invoked.
See documentation of the :prop_dir:`directory <COMPILE_OPTIONS>` and
:prop_tgt:`target <COMPILE_OPTIONS>` ``COMPILE_OPTIONS`` properties.
Adds options to the :prop_dir:`COMPILE_OPTIONS` directory property.
These options are used when compiling targets from the current
directory and below.
This command can be used to add any options, but alternative commands
exist to add preprocessor definitions (:command:`target_compile_definitions`
and :command:`add_compile_definitions`) or include directories
(:command:`target_include_directories` and :command:`include_directories`).
Arguments
^^^^^^^^^
Arguments to ``add_compile_options`` may use "generator expressions" with
the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
@ -23,3 +20,29 @@ manual for available expressions. See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.
.. include:: OPTIONS_SHELL.txt
Example
^^^^^^^
Since different compilers support different options, a typical use of
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)
else()
# lots of warnings and all warnings as errors
add_compile_options(-Wall -Wextra -pedantic -Werror)
endif()
See Also
^^^^^^^^
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.

14
Help/command/add_custom_command.rst
View File

@ -8,7 +8,9 @@ There are two main signatures for ``add_custom_command``.
Generating Files
^^^^^^^^^^^^^^^^
The first signature is for adding a custom command to produce an output::
The first signature is for adding a custom command to produce an output:
.. code-block:: cmake
add_custom_command(OUTPUT output1 [output2 ...]
COMMAND command1 [ARGS] [args1...]
@ -21,6 +23,7 @@ The first signature is for adding a custom command to produce an output::
[WORKING_DIRECTORY dir]
[COMMENT comment]
[DEPFILE depfile]
[JOB_POOL job_pool]
[VERBATIM] [APPEND] [USES_TERMINAL]
[COMMAND_EXPAND_LISTS])
@ -142,6 +145,13 @@ The options are:
Note that the ``IMPLICIT_DEPENDS`` option is currently supported
only for Makefile generators and will be ignored by other generators.
``JOB_POOL``
Specify a :prop_gbl:`pool <JOB_POOLS>` for the :generator:`Ninja`
generator. Incompatible with ``USES_TERMINAL``, which implies
the ``console`` pool.
Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes
an error by ninja at build time.
``MAIN_DEPENDENCY``
Specify the primary input source file to the command. This is
treated just like any value given to the ``DEPENDS`` option
@ -200,7 +210,7 @@ before or after building the target. The command becomes part of the
target and will only execute when the target itself is built. If the
target is already built, the command will not execute.
::
.. code-block:: cmake
add_custom_command(TARGET <target>
PRE_BUILD | PRE_LINK | POST_BUILD

10
Help/command/add_custom_target.rst
View File

@ -3,7 +3,7 @@ add_custom_target
Add a target with no output so it will always be built.
::
.. code-block:: cmake
add_custom_target(Name [ALL] [command1 [args1...]]
[COMMAND command2 [args2...] ...]
@ -11,6 +11,7 @@ Add a target with no output so it will always be built.
[BYPRODUCTS [files...]]
[WORKING_DIRECTORY dir]
[COMMENT comment]
[JOB_POOL job_pool]
[VERBATIM] [USES_TERMINAL]
[COMMAND_EXPAND_LISTS]
[SOURCES src1 [src2...]])
@ -97,6 +98,13 @@ The options are:
``${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc``
to be properly expanded.
``JOB_POOL``
Specify a :prop_gbl:`pool <JOB_POOLS>` for the :generator:`Ninja`
generator. Incompatible with ``USES_TERMINAL``, which implies
the ``console`` pool.
Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes
an error by ninja at build time.
``SOURCES``
Specify additional source files to be included in the custom target.
Specified source files will be added to IDE project files for

6
Help/command/add_definitions.rst
View File

@ -1,9 +1,9 @@
add_definitions
---------------
Adds -D define flags to the compilation of source files.
Add -D define flags to the compilation of source files.
::
.. code-block:: cmake
add_definitions(-DFOO -DBAR ...)
@ -20,7 +20,7 @@ preprocessor definitions.
* Use :command:`include_directories` to add include directories.
* Use :command:`add_compile_options` to add other options.
Flags beginning in -D or /D that look like preprocessor definitions are
Flags beginning in ``-D`` or ``/D`` that look like preprocessor definitions are
automatically added to the :prop_dir:`COMPILE_DEFINITIONS` directory
property for the current directory. Definitions with non-trivial values
may be left in the set of flags instead of being converted for reasons of

4
Help/command/add_dependencies.rst
View File

@ -3,11 +3,11 @@ add_dependencies
Add a dependency between top-level targets.
::
.. code-block:: cmake
add_dependencies(<target> [<target-dependency>]...)
Make a top-level ``<target>`` depend on other top-level targets to
Makes a top-level ``<target>`` depend on other top-level targets to
ensure that they build before ``<target>`` does. A top-level target
is one created by one of the :command:`add_executable`,
:command:`add_library`, or :command:`add_custom_target` commands

6
Help/command/add_executable.rst
View File

@ -3,7 +3,7 @@ add_executable
Add an executable to the project using the specified source files.
::
.. code-block:: cmake
add_executable(<name> [WIN32] [MACOSX_BUNDLE]
[EXCLUDE_FROM_ALL]
@ -47,7 +47,7 @@ within IDE.
--------------------------------------------------------------------------
::
.. code-block:: cmake
add_executable(<name> IMPORTED [GLOBAL])
@ -67,7 +67,7 @@ properties for more information.
--------------------------------------------------------------------------
::
.. code-block:: cmake
add_executable(<name> ALIAS <target>)

33
Help/command/add_library.rst
View File

@ -10,7 +10,7 @@ Add a library to the project using the specified source files.
Normal Libraries
^^^^^^^^^^^^^^^^
::
.. code-block:: cmake
add_library(<name> [STATIC | SHARED | MODULE]
[EXCLUDE_FROM_ALL]
@ -67,7 +67,7 @@ within IDE.
Imported Libraries
^^^^^^^^^^^^^^^^^^
::
.. code-block:: cmake
add_library(<name> <SHARED|STATIC|MODULE|OBJECT|UNKNOWN> IMPORTED
[GLOBAL])
@ -80,19 +80,30 @@ option extends visibility. It may be referenced like any target built
within the project. ``IMPORTED`` libraries are useful for convenient
reference from commands like :command:`target_link_libraries`. Details
about the imported library are specified by setting properties whose names
begin in ``IMPORTED_`` and ``INTERFACE_``. The most important such
property is :prop_tgt:`IMPORTED_LOCATION` (and its per-configuration
variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) which specifies the
location of the main library file on disk. Or, for object libraries,
:prop_tgt:`IMPORTED_OBJECTS` (and :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`)
specifies the locations of object files on disk.
begin in ``IMPORTED_`` and ``INTERFACE_``.
The most important properties are:
* :prop_tgt:`IMPORTED_LOCATION` (and its per-configuration
variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) which specifies the
location of the main library file on disk.
* :prop_tgt:`IMPORTED_OBJECTS` (and :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`)
for object libraries, specifies the locations of object files on disk.
* :prop_tgt:`PUBLIC_HEADER` files to be installed during :command:`install` invocation
See documentation of the ``IMPORTED_*`` and ``INTERFACE_*`` properties
for more information.
An ``UNKNOWN`` library type is typically only used in the implementation of
:ref:`Find Modules`. It allows the path to an imported library (often found
using the :command:`find_library` command) to be used without having to know
what type of library it is. This is especially useful on Windows where a
static library and a DLL's import library both have the same file extension.
Object Libraries
^^^^^^^^^^^^^^^^
::
.. code-block:: cmake
add_library(<name> OBJECT <src>...)
@ -121,7 +132,7 @@ consider adding at least one real source file to any target that references
Alias Libraries
^^^^^^^^^^^^^^^
::
.. code-block:: cmake
add_library(<name> ALIAS <target>)
@ -141,7 +152,7 @@ installed or exported.
Interface Libraries
^^^^^^^^^^^^^^^^^^^
::
.. code-block:: cmake
add_library(<name> INTERFACE [IMPORTED [GLOBAL]])

19
Help/command/add_link_options.rst
View File

@ -1,20 +1,25 @@
add_link_options
----------------
Adds options to the link of shared library, module and executable targets.
Add options to the link step for executable, shared library or module
library targets in the current directory and below that are added after
this command is invoked.
::
.. code-block:: cmake
add_link_options(<option> ...)
Adds options to the link step for targets in the current directory and below
that are added after this command is invoked. See documentation of the
This command can be used to add any link options, but alternative commands
exist to add libraries (:command:`target_link_libraries` or
:command:`link_libraries`). See documentation of the
:prop_dir:`directory <LINK_OPTIONS>` and
:prop_tgt:`target <LINK_OPTIONS>` ``LINK_OPTIONS`` properties.
This command can be used to add any options, but alternative commands
exist to add libraries (:command:`target_link_libraries` or
:command:`link_libraries`).
.. note::
This command cannot be used to add options for static library targets,
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)`

7
Help/command/add_subdirectory.rst
View File

@ -3,12 +3,11 @@ add_subdirectory
Add a subdirectory to the build.
::
.. code-block:: cmake
add_subdirectory(source_dir [binary_dir]
[EXCLUDE_FROM_ALL])
add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL])
Add a subdirectory to the build. The source_dir specifies the
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

13
Help/command/add_test.rst
View File

@ -3,13 +3,13 @@ add_test
Add a test to the project to be run by :manual:`ctest(1)`.
::
.. code-block:: cmake
add_test(NAME <name> COMMAND <command> [<arg>...]
[CONFIGURATIONS <config>...]
[WORKING_DIRECTORY <dir>])
Add a test called ``<name>``. The test name may not contain spaces,
Adds a test called ``<name>``. The test name may not contain spaces,
quotes, or other characters special in CMake syntax. The options are:
``COMMAND``
@ -39,7 +39,9 @@ The ``COMMAND`` and ``WORKING_DIRECTORY`` options may use "generator
expressions" with the syntax ``$<...>``. See the
:manual:`cmake-generator-expressions(7)` manual for available expressions.
Example usage::
Example usage:
.. code-block:: cmake
add_test(NAME mytest
COMMAND testDriver --config $<CONFIGURATION>
@ -53,11 +55,12 @@ file produced by target ``myexe``.
CMake will generate tests only if the :command:`enable_testing`
command has been invoked. The :module:`CTest` module invokes the
command automatically when the ``BUILD_TESTING`` option is ``ON``.
command automatically unless the ``BUILD_TESTING`` option is turned
``OFF``.
---------------------------------------------------------------------
::
.. code-block:: cmake
add_test(<name> <command> [<arg>...])

6
Help/command/aux_source_directory.rst
View File

@ -3,7 +3,7 @@ aux_source_directory
Find all source files in a directory.
::
.. code-block:: cmake
aux_source_directory(<dir> <variable>)
@ -11,14 +11,14 @@ Collects the names of all the source files in the specified directory
and stores the list in the ``<variable>`` provided. This command is
intended to be used by projects that use explicit template
instantiation. Template instantiation files can be stored in a
"Templates" subdirectory and collected automatically using this
``Templates`` subdirectory and collected automatically using this
command to avoid manually listing all instantiations.
It is tempting to use this command to avoid writing the list of source
files for a library or executable target. While this seems to work,
there is no way for CMake to generate a build system that knows when a
new source file has been added. Normally the generated build system
knows when it needs to rerun CMake because the CMakeLists.txt file is
knows when it needs to rerun CMake because the ``CMakeLists.txt`` file is
modified to add a new source. When the source is just added to the
directory without modifying this file, one would have to manually
rerun CMake to generate a build system incorporating the new file.

4
Help/command/break.rst
View File

@ -3,10 +3,10 @@ break
Break from an enclosing foreach or while loop.
::
.. code-block:: cmake
break()
Breaks from an enclosing foreach loop or while loop
Breaks from an enclosing :command:`foreach` or :command:`while` loop.
See also the :command:`continue` command.

2
Help/command/build_command.rst
View File

@ -14,7 +14,7 @@ This is mainly intended for internal use by the :module:`CTest` module.
Sets the given ``<variable>`` to a command-line string of the form::
<cmake> --build . [--config <config>] [--target <target>] [-- -i]
<cmake> --build . [--config <config>] [--target <target>...] [-- -i]
where ``<cmake>`` is the location of the :manual:`cmake(1)` command-line
tool, and ``<config>`` and ``<target>`` are the values provided to the

2
Help/command/build_name.rst
View File

@ -1,7 +1,7 @@
build_name
----------
Disallowed. See CMake Policy :policy:`CMP0036`.
Disallowed since version 3.0. See CMake Policy :policy:`CMP0036`.
Use ``${CMAKE_SYSTEM}`` and ``${CMAKE_CXX_COMPILER}`` instead.

2
Help/command/cmake_host_system_information.rst
View File

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

16
Help/command/cmake_minimum_required.rst
View File

@ -1,11 +1,15 @@
cmake_minimum_required
----------------------
Set the minimum required version of cmake for a project and
update `Policy Settings`_ to match the version given::
Require a minimum version of cmake.
.. code-block:: cmake
cmake_minimum_required(VERSION <min>[...<max>] [FATAL_ERROR])
Sets the minimum required version of cmake for a project.
Also updates the policy settings as explained below.
``<min>`` and the optional ``<max>`` are each CMake versions of the form
``major.minor[.patch[.tweak]]``, and the ``...`` is literal.
@ -47,13 +51,17 @@ as of a given CMake version and tells newer CMake versions to warn
about their new policies.
When a ``<min>`` version higher than 2.4 is specified the command
implicitly invokes::
implicitly invokes
.. code-block:: cmake
cmake_policy(VERSION <min>[...<max>])
which sets CMake policies based on the range of versions specified.
When a ``<min>`` version 2.4 or lower is given the command implicitly
invokes::
invokes
.. code-block:: cmake
cmake_policy(VERSION 2.4[...<max>])

48
Help/command/cmake_parse_arguments.rst
View File

@ -1,26 +1,28 @@
cmake_parse_arguments
---------------------
``cmake_parse_arguments`` is intended to be used in macros or functions for
parsing the arguments given to that macro or function. It processes the
arguments and defines a set of variables which hold the values of the
respective options.
Parse function or macro arguments.
::
.. code-block:: cmake
cmake_parse_arguments(<prefix> <options> <one_value_keywords>
<multi_value_keywords> args...)
<multi_value_keywords> <args>...)
cmake_parse_arguments(PARSE_ARGV N <prefix> <options> <one_value_keywords>
<multi_value_keywords>)
cmake_parse_arguments(PARSE_ARGV <N> <prefix> <options>
<one_value_keywords> <multi_value_keywords>)
The first signature reads processes arguments passed in the ``args...``.
This command is for use in macros or functions.
It processes the arguments given to that macro or function,
and defines a set of variables which hold the values of the
respective options.
The first signature reads processes arguments passed in the ``<args>...``.
This may be used in either a :command:`macro` or a :command:`function`.
The ``PARSE_ARGV`` signature is only for use in a :command:`function`
body. In this case the arguments that are parsed come from the
``ARGV#`` variables of the calling function. The parsing starts with
the Nth argument, where ``N`` is an unsigned integer. This allows for
the ``<N>``-th argument, where ``<N>`` is an unsigned integer. This allows for
the values to have special characters like ``;`` in them.
The ``<options>`` argument contains all options for the respective macro,
@ -53,12 +55,17 @@ For the ``<options>`` keywords, these will always be defined,
to ``TRUE`` or ``FALSE``, whether the option is in the argument list or not.
All remaining arguments are collected in a variable
``<prefix>_UNPARSED_ARGUMENTS`` that will be undefined if all argument
where recognized. This can be checked afterwards to see
``<prefix>_UNPARSED_ARGUMENTS`` that will be undefined if all arguments
were recognized. This can be checked afterwards to see
whether your macro was called with unrecognized parameters.
As an example here a ``my_install()`` macro, which takes similar arguments
as the real :command:`install` command:
``<one_value_keywords>`` and ``<multi_value_keywords>`` that were given no
values at all are collected in a variable ``<prefix>_KEYWORDS_MISSING_VALUES``
that will be undefined if all keywords received values. This can be checked
to see if there were keywords without any values given.
Consider the following example macro, ``my_install()``, which takes similar
arguments to the real :command:`install` command:
.. code-block:: cmake
@ -75,7 +82,7 @@ Assume ``my_install()`` has been called like this:
.. code-block:: cmake
my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub)
my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS)
After the ``cmake_parse_arguments`` call the macro will have set or undefined
the following variables::
@ -87,13 +94,16 @@ the following variables::
MY_INSTALL_TARGETS = "foo;bar"
MY_INSTALL_CONFIGURATIONS <UNDEFINED> # was not used
MY_INSTALL_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL"
MY_INSTALL_KEYWORDS_MISSING_VALUES = "CONFIGURATIONS"
# No value for "CONFIGURATIONS" given
You can then continue and process these variables.
Keywords terminate lists of values, e.g. if directly after a
one_value_keyword another recognized keyword follows, this is
Keywords terminate lists of values, e.g. if directly after a
``one_value_keyword`` another recognized keyword follows, this is
interpreted as the beginning of the new option. E.g.
``my_install(TARGETS foo DESTINATION OPTIONAL)`` would result in
``MY_INSTALL_DESTINATION`` set to ``"OPTIONAL"``, but as ``OPTIONAL``
is a keyword itself ``MY_INSTALL_DESTINATION`` will be empty and
``MY_INSTALL_OPTIONAL`` will therefore be set to ``TRUE``.
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``.

14
Help/command/cmake_policy.rst
View File

@ -22,7 +22,9 @@ Setting Policies by CMake Version
The ``cmake_policy`` command is used to set policies to ``OLD`` or ``NEW``
behavior. While setting policies individually is supported, we
encourage projects to set policies based on CMake versions::
encourage projects to set policies based on CMake versions:
.. code-block:: cmake
cmake_policy(VERSION <min>[...<max>])
@ -50,7 +52,7 @@ command implicitly calls ``cmake_policy(VERSION)`` too.
Setting Policies Explicitly
^^^^^^^^^^^^^^^^^^^^^^^^^^^
::
.. code-block:: cmake
cmake_policy(SET CMP<NNNN> NEW)
cmake_policy(SET CMP<NNNN> OLD)
@ -66,7 +68,7 @@ policy state to ``NEW``.
Checking Policy Settings
^^^^^^^^^^^^^^^^^^^^^^^^
::
.. code-block:: cmake
cmake_policy(GET CMP<NNNN> <variable>)
@ -78,14 +80,16 @@ CMake Policy Stack
^^^^^^^^^^^^^^^^^^
CMake keeps policy settings on a stack, so changes made by the
cmake_policy command affect only the top of the stack. A new entry on
``cmake_policy`` command affect only the top of the stack. A new entry on
the policy stack is managed automatically for each subdirectory to
protect its parents and siblings. CMake also manages a new entry for
scripts loaded by :command:`include` and :command:`find_package` commands
except when invoked with the ``NO_POLICY_SCOPE`` option
(see also policy :policy:`CMP0011`).
The ``cmake_policy`` command provides an interface to manage custom
entries on the policy stack::
entries on the policy stack:
.. code-block:: cmake
cmake_policy(PUSH)
cmake_policy(POP)

22
Help/command/configure_file.rst
View File

@ -3,7 +3,7 @@ configure_file
Copy a file to another location and modify its contents.
::
.. code-block:: cmake
configure_file(<input> <output>
[COPYONLY] [ESCAPE_QUOTES] [@ONLY]
@ -13,15 +13,21 @@ Copies an ``<input>`` file to an ``<output>`` file and substitutes
variable values referenced as ``@VAR@`` or ``${VAR}`` in the input
file content. Each variable reference will be replaced with the
current value of the variable, or the empty string if the variable
is not defined. Furthermore, input lines of the form::
is not defined. Furthermore, input lines of the form
.. code-block:: c
#cmakedefine VAR ...
will be replaced with either::
will be replaced with either
.. code-block:: c
#define VAR ...
or::
or
.. code-block:: c
/* #undef VAR */
@ -33,12 +39,16 @@ either ``#define VAR 1`` or ``#define VAR 0`` similarly.
The result lines (with the exception of the ``#undef`` comments) can be
indented using spaces and/or tabs between the ``#`` character
and the ``cmakedefine`` or ``cmakedefine01`` words. This whitespace
indentation will be preserved in the output lines::
indentation will be preserved in the output lines:
.. code-block:: c
# cmakedefine VAR
# cmakedefine01 VAR
will be replaced, if ``VAR`` is defined, with::
will be replaced, if ``VAR`` is defined, with
.. code-block:: c
# define VAR
# define VAR 1

6
Help/command/continue.rst
View File

@ -3,10 +3,12 @@ continue
Continue to the top of enclosing foreach or while loop.
::
.. code-block:: cmake
continue()
The ``continue`` command allows a cmake script to abort the rest of a block
in a :command:`foreach` or :command:`while` loop, and start at the top of
the next iteration. See also the :command:`break` command.
the next iteration.
See also the :command:`break` command.

2
Help/command/create_test_sourcelist.rst
View File

@ -3,7 +3,7 @@ create_test_sourcelist
Create a test driver and source list for building test programs.
::
.. code-block:: cmake
create_test_sourcelist(sourceListName driverName
test1 test2 test3

4
Help/command/ctest_build.rst
View File

@ -50,9 +50,7 @@ The options are:
for an example.
``PROJECT_NAME <project-name>``
Set the name of the project to build. This should correspond
to the top-level call to the :command:`project` command.
If not specified the ``CTEST_PROJECT_NAME`` variable will be checked.
Ignored. This was once used but is no longer needed.
``TARGET <target-name>``
Specify the name of a target to build. If not specified the

27
Help/command/ctest_submit.rst
View File

@ -6,6 +6,8 @@ Perform the :ref:`CTest Submit Step` as a :ref:`Dashboard Client`.
::
ctest_submit([PARTS <part>...] [FILES <file>...]
[SUBMIT_URL <url>]
[BUILD_ID <result-var>]
[HTTPHEADER <header>]
[RETRY_COUNT <count>]
[RETRY_DELAY <delay>]
@ -33,14 +35,31 @@ The options are:
ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
Upload = Files prepared for upload by ctest_upload(), in Upload.xml
Submit = nothing
Done = Build is complete, in Done.xml
``FILES <file>...``
Specify an explicit list of specific files to be submitted.
Each individual file must exist at the time of the call.
``SUBMIT_URL <url>``
The ``http`` or ``https`` URL of the dashboard server to send the submission
to. If not given, the :variable:`CTEST_SUBMIT_URL` variable is used.
``BUILD_ID <result-var>``
Store in the ``<result-var>`` variable the ID assigned to this build by
CDash.
``HTTPHEADER <HTTP-header>``
Specify HTTP header to be included in the request to CDash during submission.
This suboption can be repeated several times.
For example, CDash can be configured to only accept submissions from
authenticated clients. In this case, you should provide a bearer token in your
header:
.. code-block:: cmake
ctest_submit(HTTPHEADER "Authorization: Bearer <auth-token>")
This suboption can be repeated several times for multiple headers.
``RETRY_COUNT <count>``
Specify how many times to retry a timed-out submission.
@ -67,6 +86,7 @@ Submit to CDash Upload API
::
ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>]
[SUBMIT_URL <url>]
[HTTPHEADER <header>]
[RETRY_COUNT <count>]
[RETRY_DELAY <delay>]
@ -79,5 +99,6 @@ with a content hash of the file. If CDash does not already have the file,
then it is uploaded. Along with the file, a CDash type string is specified
to tell CDash which handler to use to process the data.
This signature accepts the ``HTTPHEADER``, ``RETRY_COUNT``, ``RETRY_DELAY``,
``RETURN_VALUE`` and ``QUIET`` options as described above.
This signature accepts the ``SUBMIT_URL``, ``BUILD_ID``, ``HTTPHEADER``,
``RETRY_COUNT``, ``RETRY_DELAY``, ``RETURN_VALUE`` and ``QUIET`` options
as described above.

3
Help/command/ctest_update.rst
View File

@ -35,4 +35,5 @@ The options are:
The update always follows the version control branch currently checked
out in the source directory. See the :ref:`CTest Update Step`
documentation for more information.
documentation for information about variables that change the behavior
of ``ctest_update()``.

4
Help/command/define_property.rst
View File

@ -3,7 +3,7 @@ define_property
Define and document custom properties.
::
.. code-block:: cmake
define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
TEST | VARIABLE | CACHED_VARIABLE>
@ -11,7 +11,7 @@ Define and document custom properties.
BRIEF_DOCS <brief-doc> [docs...]
FULL_DOCS <full-doc> [docs...])
Define one property in a scope for use with the :command:`set_property` and
Defines one property in a scope for use with the :command:`set_property` and
:command:`get_property` commands. This is primarily useful to associate
documentation with property names that may be retrieved with the
:command:`get_property` command. The first argument determines the kind of

4
Help/command/else.rst
View File

@ -3,8 +3,8 @@ else
Starts the else portion of an if block.
::
.. code-block:: cmake
else(expression)
else([<condition>])
See the :command:`if` command.

9
Help/command/elseif.rst
View File

@ -1,10 +1,11 @@
elseif
------
Starts the elseif portion of an if block.
Starts an elseif portion of an if block.
::
.. code-block:: cmake
elseif(expression)
elseif(<condition>)
See the :command:`if` command.
See the :command:`if` command, especially for the syntax and logic
of the ``<condition>``.

6
Help/command/enable_language.rst
View File

@ -3,12 +3,12 @@ enable_language
Enable a language (CXX/C/Fortran/etc)
::
.. code-block:: cmake
enable_language(<lang> [OPTIONAL] )
This command enables support for the named language in CMake. This is
the same as the project command but does not create any of the extra
Enables support for the named language 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``, ``Fortran``, and ``ASM``.

17
Help/command/enable_testing.rst
View File

@ -3,11 +3,18 @@ enable_testing
Enable testing for current directory and below.
::
.. code-block:: cmake
enable_testing()
Enables testing for this directory and below. See also the
:command:`add_test` command. Note that ctest expects to find a test file
in the build directory root. Therefore, this command should be in the
source directory root.
Enables testing for this directory and below.
This command should be in the source directory root
because ctest expects to find a test file in the build
directory root.
This command is automatically invoked when the :module:`CTest`
module is included, except if the ``BUILD_TESTING`` option is
turned off.
See also the :command:`add_test` command.

8
Help/command/endforeach.rst
View File

@ -3,8 +3,12 @@ endforeach
Ends a list of commands in a foreach block.
::
.. code-block:: cmake
endforeach(expression)
endforeach([<loop_var>])
See the :command:`foreach` command.
The optional ``<loop_var>`` argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the ``<loop_var>`` argument of
the opening ``foreach`` clause.

8
Help/command/endfunction.rst
View File

@ -3,8 +3,12 @@ endfunction
Ends a list of commands in a function block.
::
.. code-block:: cmake
endfunction(expression)
endfunction([<name>])
See the :command:`function` command.
The optional ``<name>`` argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the ``<name>`` argument
of the opening ``function`` command.

8
Help/command/endif.rst
View File

@ -3,8 +3,12 @@ endif
Ends a list of commands in an if block.
::
.. code-block:: cmake
endif(expression)
endif([<condition>])
See the :command:`if` command.
The optional ``<condition>`` argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the argument of the opening
``if`` clause.

8
Help/command/endmacro.rst
View File

@ -3,8 +3,12 @@ endmacro
Ends a list of commands in a macro block.
::
.. code-block:: cmake
endmacro(expression)
endmacro([<name>])
See the :command:`macro` command.
The optional ``<name>`` argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the ``<name>`` argument
of the opening ``macro`` command.

8
Help/command/endwhile.rst
View File

@ -3,8 +3,12 @@ endwhile
Ends a list of commands in a while block.
::
.. code-block:: cmake
endwhile(expression)
endwhile([<condition>])
See the :command:`while` command.
The optional ``<condition>`` argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the argument of the opening
``while`` clause.

4
Help/command/exec_program.rst
View File

@ -1,7 +1,9 @@
exec_program
------------
Deprecated. Use the :command:`execute_process` command instead.
.. deprecated:: 3.0
Use the :command:`execute_process` command instead.
Run an executable program during the processing of the CMakeList.txt
file.

26
Help/command/execute_process.rst
View File

@ -5,8 +5,8 @@ Execute one or more child processes.
.. code-block:: cmake
execute_process(COMMAND <cmd1> [args1...]]
[COMMAND <cmd2> [args2...] [...]]
execute_process(COMMAND <cmd1> [<arguments>]
[COMMAND <cmd2> [<arguments>]]...
[WORKING_DIRECTORY <directory>]
[TIMEOUT <seconds>]
[RESULT_VARIABLE <variable>]
@ -18,11 +18,14 @@ Execute one or more child processes.
[ERROR_FILE <file>]
[OUTPUT_QUIET]
[ERROR_QUIET]
[COMMAND_ECHO <where>]
[OUTPUT_STRIP_TRAILING_WHITESPACE]
[ERROR_STRIP_TRAILING_WHITESPACE]
[ENCODING <name>])
Runs the given sequence of one or more commands in parallel with the standard
Runs the given sequence of one or more commands.
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.
@ -46,8 +49,9 @@ Options:
the child processes.
``TIMEOUT``
The child processes will be terminated if they do not finish in the
specified number of seconds (fractions are allowed).
After the specified number of seconds (fractions allowed), all unfinished
child processes will be terminated, and the ``RESULT_VARIABLE`` will be
set to a string mentioning the "timeout".
``RESULT_VARIABLE``
The variable will be set to contain the result of last child process.
@ -56,9 +60,9 @@ Options:
``RESULTS_VARIABLE <variable>``
The variable will be set to contain the result of all processes as a
:ref:`;-list <CMake Language Lists>`, in order of the given ``COMMAND``
arguments. Each entry will be an integer return code from the
corresponding child or a string describing an error condition.
:ref:`semicolon-separated list <CMake Language Lists>`, in order of the
given ``COMMAND`` arguments. Each entry will be an integer return code
from the corresponding child or a string describing an error condition.
``OUTPUT_VARIABLE``, ``ERROR_VARIABLE``
The variable named will be set with the contents of the standard output
@ -74,6 +78,12 @@ Options:
``OUTPUT_QUIET``, ``ERROR_QUIET``
The standard output or standard error results will be quietly ignored.
``COMMAND_ECHO <where>``
The command being run will be echo'ed to ``<where>`` with ``<where>``
being set to one of ``STDERR``, ``STDOUT`` or ``NONE``.
See the :variable:`CMAKE_EXECUTE_PROCESS_COMMAND_ECHO` variable for a way
to control the default behavior when this option is not present.
``ENCODING <name>``
On Windows, the encoding that is used to decode output from the process.
Ignored on other platforms.

21
Help/command/export.rst
View File

@ -3,11 +3,11 @@ export
Export targets from the build tree for use by outside projects.
::
.. code-block:: cmake
export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
Create a file ``<filename>`` that may be included by outside projects to
Creates a file ``<filename>`` that may be included by outside projects to
import targets from the current project's build tree. This is useful
during cross-compiling to build utility executables that can run on
the host platform in one project and then import them into another
@ -25,7 +25,7 @@ export targets from an installation tree.
The properties set on the generated IMPORTED targets will have the
same values as the final values of the input TARGETS.
::
.. code-block:: cmake
export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
[APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
@ -49,12 +49,12 @@ unspecified.
transitive usage requirements of other targets that link to the
object libraries in their implementation.
::
.. code-block:: cmake
export(PACKAGE <PackageName>)
Store the current build directory in the CMake user package registry
for package ``<PackageName>``. The find_package command may consider the
for package ``<PackageName>``. The :command:`find_package` command may consider the
directory while searching for package ``<PackageName>``. This helps dependent
projects find and use a package from the current project's build tree
without help from the user. Note that the entry in the package
@ -62,10 +62,15 @@ registry that this command creates works only in conjunction with a
package configuration file (``<PackageName>Config.cmake``) that works with the
build tree. In some cases, for example for packaging and for system
wide installations, it is not desirable to write the user package
registry. If the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable
is enabled, the ``export(PACKAGE)`` command will do nothing.
registry.
::
By default the ``export(PACKAGE)`` command does nothing (see policy
:policy:`CMP0090`) because populating the user package registry has effects
outside the source and build trees. Set the
:variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable to add build directories to
the CMake user package registry.
.. code-block:: cmake
export(TARGETS [target1 [target2 [...]]] [ANDROID_MK <filename>])

2
Help/command/export_library_dependencies.rst
View File

@ -1,7 +1,7 @@
export_library_dependencies
---------------------------
Disallowed. See CMake Policy :policy:`CMP0033`.
Disallowed since version 3.0. See CMake Policy :policy:`CMP0033`.
Use :command:`install(EXPORT)` or :command:`export` command.

120
Help/command/file.rst
View File

@ -25,6 +25,9 @@ Synopsis
file({`REMOVE`_ | `REMOVE_RECURSE`_ } [<files>...])
file(`MAKE_DIRECTORY`_ [<dir>...])
file({`COPY`_ | `INSTALL`_} <file>... DESTINATION <dir> [...])
file(`SIZE`_ <filename> <out-var>)
file(`READ_SYMLINK`_ <linkname> <out-var>)
file(`CREATE_LINK`_ <original> <linkname> [...])
`Path Conversion`_
file(`RELATIVE_PATH`_ <out-var> <directory> <file>)
@ -42,7 +45,7 @@ Reading
.. _READ:
::
.. code-block:: cmake
file(READ <filename> <variable>
[OFFSET <offset>] [LIMIT <max-in>] [HEX])
@ -54,7 +57,7 @@ be converted to a hexadecimal representation (useful for binary data).
.. _STRINGS:
::
.. code-block:: cmake
file(STRINGS <filename> <variable> [<options>...])
@ -105,7 +108,7 @@ from the input file.
.. _HASH:
::
.. code-block:: cmake
file(<HASH> <filename> <variable>)
@ -116,7 +119,7 @@ command.
.. _TIMESTAMP:
::
.. code-block:: cmake
file(TIMESTAMP <filename> <variable> [<format>] [UTC])
@ -133,7 +136,7 @@ Writing
.. _WRITE:
.. _APPEND:
::
.. code-block:: cmake
file(WRITE <filename> <content>...)
file(APPEND <filename> <content>...)
@ -150,7 +153,7 @@ to update the file only when its content changes.
.. _TOUCH:
.. _TOUCH_NOCREATE:
::
.. code-block:: cmake
file(TOUCH [<files>...])
file(TOUCH_NOCREATE [<files>...])
@ -167,7 +170,7 @@ modified.
.. _GENERATE:
::
.. code-block:: cmake
file(GENERATE OUTPUT output-file
<INPUT input-file|CONTENT content>
@ -217,7 +220,7 @@ Filesystem
.. _GLOB:
.. _GLOB_RECURSE:
::
.. code-block:: cmake
file(GLOB <variable>
[LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
@ -272,7 +275,7 @@ Examples of recursive globbing include::
.. _RENAME:
::
.. code-block:: cmake
file(RENAME <oldname> <newname>)
@ -282,18 +285,19 @@ Move a file or directory within a filesystem from ``<oldname>`` to
.. _REMOVE:
.. _REMOVE_RECURSE:
::
.. code-block:: cmake
file(REMOVE [<files>...])
file(REMOVE_RECURSE [<files>...])
Remove the given files. The ``REMOVE_RECURSE`` mode will remove the given
files and directories, also non-empty directories. No error is emitted if a
given file does not exist.
given file does not exist. Relative input paths are evaluated with respect
to the current source directory. Empty input paths are ignored with a warning.
.. _MAKE_DIRECTORY:
::
.. code-block:: cmake
file(MAKE_DIRECTORY [<directories>...])
@ -302,12 +306,13 @@ Create the given directories and their parents as needed.
.. _COPY:
.. _INSTALL:
::
.. code-block:: cmake
file(<COPY|INSTALL> <files>... DESTINATION <dir>
[FILE_PERMISSIONS <permissions>...]
[DIRECTORY_PERMISSIONS <permissions>...]
[NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
[FOLLOW_SYMLINK_CHAIN]
[FILES_MATCHING]
[[PATTERN <pattern> | REGEX <regex>]
[EXCLUDE] [PERMISSIONS <permissions>...]] [...])
@ -321,6 +326,32 @@ at the destination with the same timestamp. Copying preserves input
permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS``
are given (default is ``USE_SOURCE_PERMISSIONS``).
If ``FOLLOW_SYMLINK_CHAIN`` is specified, ``COPY`` will recursively resolve
the symlinks at the paths given until a real file is found, and install
a corresponding symlink in the destination for each symlink encountered. For
each symlink that is installed, the resolution is stripped of the directory,
leaving only the filename, meaning that the new symlink points to a file in
the same directory as the symlink. This feature is useful on some Unix systems,
where libraries are installed as a chain of symlinks with version numbers, with
less specific versions pointing to more specific versions.
``FOLLOW_SYMLINK_CHAIN`` will install all of these symlinks and the library
itself into the destination directory. For example, if you have the following
directory structure:
* ``/opt/foo/lib/libfoo.so.1.2.3``
* ``/opt/foo/lib/libfoo.so.1.2 -> libfoo.so.1.2.3``
* ``/opt/foo/lib/libfoo.so.1 -> libfoo.so.1.2``
* ``/opt/foo/lib/libfoo.so -> libfoo.so.1``
and you do:
.. code-block:: cmake
file(COPY /opt/foo/lib/libfoo.so DESTINATION lib FOLLOW_SYMLINK_CHAIN)
This will install all of the symlinks and ``libfoo.so.1.2.3`` itself into
``lib``.
See the :command:`install(DIRECTORY)` command for documentation of
permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and
``EXCLUDE`` options. Copying directories preserves the structure
@ -333,12 +364,67 @@ and ``NO_SOURCE_PERMISSIONS`` is default.
Installation scripts generated by the :command:`install` command
use this signature (with some undocumented options for internal use).
.. _SIZE:
.. code-block:: cmake
file(SIZE <filename> <variable>)
Determine the file size of the ``<filename>`` and put the result in
``<variable>`` variable. Requires that ``<filename>`` is a valid path
pointing to a file and is readable.
.. _READ_SYMLINK:
.. code-block:: cmake
file(READ_SYMLINK <linkname> <variable>)
This subcommand queries the symlink ``<linkname>`` and stores the path it
points to in the result ``<variable>``. If ``<linkname>`` does not exist or
is not a symlink, CMake issues a fatal error.
Note that this command returns the raw symlink path and does not resolve
a relative path. The following is an example of how to ensure that an
absolute path is obtained:
.. code-block:: cmake
set(linkname "/path/to/foo.sym")
file(READ_SYMLINK "${linkname}" result)
if(NOT IS_ABSOLUTE "${result}")
get_filename_component(dir "${linkname}" DIRECTORY)
set(result "${dir}/${result}")
endif()
.. _CREATE_LINK:
.. code-block:: cmake
file(CREATE_LINK <original> <linkname>
[RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC])
Create a link ``<linkname>`` that points to ``<original>``.
It will be a hard link by default, but providing the ``SYMBOLIC`` option
results in a symbolic link instead. Hard links require that ``original``
exists and is a file, not a directory. If ``<linkname>`` already exists,
it will be overwritten.
The ``<result>`` variable, if specified, receives the status of the operation.
It is set to ``0`` upon success or an error message otherwise. If ``RESULT``
is not specified and the operation fails, a fatal error is emitted.
Specifying ``COPY_ON_ERROR`` enables copying the file as a fallback if
creating the link fails. It can be useful for handling situations such as
``<original>`` and ``<linkname>`` being on different drives or mount points,
which would make them unable to support a hard link.
Path Conversion
^^^^^^^^^^^^^^^
.. _RELATIVE_PATH:
::
.. code-block:: cmake
file(RELATIVE_PATH <variable> <directory> <file>)
@ -348,7 +434,7 @@ store it in the ``<variable>``.
.. _TO_CMAKE_PATH:
.. _TO_NATIVE_PATH:
::
.. code-block:: cmake
file(TO_CMAKE_PATH "<path>" <variable>)
file(TO_NATIVE_PATH "<path>" <variable>)
@ -370,7 +456,7 @@ Transfer
.. _DOWNLOAD:
.. _UPLOAD:
::
.. code-block:: cmake
file(DOWNLOAD <url> <file> [<options>...])
file(UPLOAD <file> <url> [<options>...])
@ -460,7 +546,7 @@ Locking
.. _LOCK:
::
.. code-block:: cmake
file(LOCK <path> [DIRECTORY] [RELEASE]
[GUARD <FUNCTION|FILE|PROCESS>]

55
Help/command/find_package.rst
View File

@ -12,7 +12,7 @@ Find an external project, and load its settings.
Basic Signature and Module Mode
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
::
.. code-block:: cmake
find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]
[REQUIRED] [[COMPONENTS] [components...]]
@ -23,9 +23,9 @@ Finds and loads settings from an external project. ``<PackageName>_FOUND``
will be set to indicate whether the package was found. When the
package is found package-specific information is provided through
variables and :ref:`Imported Targets` documented by the package itself. The
``QUIET`` option disables messages if the package cannot be found. The
``REQUIRED`` option stops processing with an error message if the package
cannot be found.
``QUIET`` option disables informational messages, including those indicating
that the package cannot be found if it is not ``REQUIRED``. The ``REQUIRED``
option stops processing with an error message if the package cannot be found.
A package-specific list of required components may be listed after the
``COMPONENTS`` option (or after the ``REQUIRED`` option if present).
@ -51,13 +51,21 @@ mode and "Config" mode. The above signature selects Module mode.
If no module is found the command falls back to Config mode, described
below. This fall back is disabled if the ``MODULE`` option is given.
In Module mode, CMake searches for a file called ``Find<PackageName>.cmake``
in the :variable:`CMAKE_MODULE_PATH` followed by the CMake installation.
In Module mode, CMake searches for a file called ``Find<PackageName>.cmake``.
The file is first searched in the :variable:`CMAKE_MODULE_PATH`,
then among the :ref:`Find Modules` provided by the CMake installation.
If the file is found, it is read and processed by CMake. It is responsible
for finding the package, checking the version, and producing any needed
messages. Some find-modules provide limited or no support for versioning;
check the module documentation.
If the ``MODULE`` option is not specfied in the above signature,
CMake first searches for the package using Module mode. Then, if the
package is not found, it searches again using Config mode. A user
may set the variable :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` to
``TRUE`` to direct CMake first search using Config mode before falling
back to Module mode.
Full Signature and Config Mode
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -67,7 +75,9 @@ full command signature and details of the search process. Project
maintainers wishing to provide a package to be found by this command
are encouraged to read on.
The complete Config mode command signature is::
The complete Config mode command signature is
.. code-block:: cmake
find_package(<PackageName> [version] [EXACT] [QUIET]
[REQUIRED] [[COMPONENTS] [components...]]
@ -177,7 +187,7 @@ sets these variables:
These variables are checked by the ``find_package`` command to determine
whether the configuration file provides an acceptable version. They
are not available after the find_package call returns. If the version
are not available after the ``find_package`` call returns. If the version
is acceptable the following variables are set:
``<PackageName>_VERSION``
@ -202,7 +212,9 @@ is set no attempt is made to choose a highest or closest version number.
To control the order in which ``find_package`` checks for compatibility use
the two variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and
:variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`.
For instance in order to select the highest version one can set::
For instance in order to select the highest version one can set
.. code-block:: cmake
SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
@ -215,8 +227,8 @@ Search Procedure
CMake constructs a set of possible installation prefixes for the
package. Under each prefix several directories are searched for a
configuration file. The tables below show the directories searched.
Each entry is meant for installation trees following Windows (W), UNIX
(U), or Apple (A) conventions::
Each entry is meant for installation trees following Windows (``W``), UNIX
(``U``), or Apple (``A``) conventions::
<prefix>/ (W)
<prefix>/(cmake|CMake)/ (W)
@ -229,8 +241,8 @@ Each entry is meant for installation trees following Windows (W), UNIX
<prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/ (W/U)
<prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (W/U)
On systems supporting macOS Frameworks and Application Bundles the
following directories are searched for frameworks or bundles
On systems supporting macOS :prop_tgt:`FRAMEWORK` and :prop_tgt:`BUNDLE`, the
following directories are searched for Frameworks or Application Bundles
containing a configuration file::
<prefix>/<name>.framework/Resources/ (A)
@ -257,16 +269,16 @@ that order).
* The ``lib`` path is always searched.
If ``PATH_SUFFIXES`` is specified, the suffixes are appended to each
(W) or (U) directory entry one-by-one.
(``W``) or (``U``) directory entry one-by-one.
This set of directories is intended to work in cooperation with
projects that provide configuration files in their installation trees.
Directories above marked with (W) are intended for installations on
Directories above marked with (``W``) are intended for installations on
Windows where the prefix may point at the top of an application's
installation directory. Those marked with (U) are intended for
installation directory. Those marked with (``U``) are intended for
installations on UNIX platforms where the prefix is shared by multiple
packages. This is merely a convention, so all (W) and (U) directories
are still searched on all platforms. Directories marked with (A) are
packages. This is merely a convention, so all (``W``) and (``U``) directories
are still searched on all platforms. Directories marked with (``A``) are
intended for installations on Apple platforms. The
:variable:`CMAKE_FIND_FRAMEWORK` and :variable:`CMAKE_FIND_APPBUNDLE`
variables determine the order of preference.
@ -286,7 +298,7 @@ enabled.
2. Search paths specified in cmake-specific cache variables. These
are intended to be used on the command line with a ``-DVAR=value``.
The values are interpreted as :ref:`;-lists <CMake Language Lists>`.
The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`.
This can be skipped if ``NO_CMAKE_PATH`` is passed::
CMAKE_PREFIX_PATH
@ -349,6 +361,11 @@ enabled.
.. include:: FIND_XXX_ROOT.txt
.. include:: FIND_XXX_ORDER.txt
By default the value stored in the result variable will be the path at
which the file is found. The :variable:`CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS`
variable may be set to ``TRUE`` before calling ``find_package`` in order
to resolve symbolic links and store the real path to the file.
Every non-REQUIRED ``find_package`` call can be disabled by setting the
:variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to ``TRUE``.

2
Help/command/fltk_wrap_ui.rst
View File

@ -3,7 +3,7 @@ fltk_wrap_ui
Create FLTK user interfaces Wrappers.
::
.. code-block:: cmake
fltk_wrap_ui(resultingLibraryName source1
source2 ... sourceN )

117
Help/command/foreach.rst
View File

@ -3,45 +3,82 @@ foreach
Evaluate a group of commands for each value in a list.
.. code-block:: cmake
foreach(<loop_var> <items>)
<commands>
endforeach()
where ``<items>`` is a list of items that are separated by
semicolon or whitespace.
All commands between ``foreach`` and the matching ``endforeach`` are recorded
without being invoked. Once the ``endforeach`` is evaluated, the recorded
list of commands is invoked once for each item in ``<items>``.
At the beginning of each iteration the variable ``loop_var`` will be set
to the value of the current item.
The commands :command:`break` and :command:`continue` provide means to
escape from the normal control flow.
Per legacy, the :command:`endforeach` command admits
an optional ``<loop_var>`` argument.
If used, it must be a verbatim
repeat of the argument of the opening
``foreach`` command.
.. code-block:: cmake
foreach(<loop_var> RANGE <stop>)
In this variant, ``foreach`` iterates over the numbers
0, 1, ... up to (and including) the nonnegative integer ``<stop>``.
.. code-block:: cmake
foreach(<loop_var> RANGE <start> <stop> [<step>])
In this variant, ``foreach`` iterates over the numbers from
``<start>`` up to at most ``<stop>`` in steps of ``<step>``.
If ``<step>`` is not specified, then the step size is 1.
The three arguments ``<start>`` ``<stop>`` ``<step>`` must
all be nonnegative integers, and ``<stop>`` must not be
smaller than ``<start>``; otherwise you enter the danger zone
of undocumented behavior that may change in future releases.
.. code-block:: cmake
foreach(loop_var IN [LISTS [<lists>]] [ITEMS [<items>]])
In this variant, ``<lists>`` is a whitespace or semicolon
separated list of list-valued variables. The ``foreach``
command iterates over each item in each given list.
The ``<items>`` following the ``ITEMS`` keyword are processed
as in the first variant of the ``foreach`` command.
The forms ``LISTS A`` and ``ITEMS ${A}`` are
equivalent.
The following example shows how the ``LISTS`` option is
processed:
.. code-block:: cmake
set(A 0;1)
set(B 2 3)
set(C "4 5")
set(D 6;7 8)
set(E "")
foreach(X IN LISTS A B C D E)
message(STATUS "X=${X}")
endforeach()
yields
::
foreach(loop_var arg1 arg2 ...)
COMMAND1(ARGS ...)
COMMAND2(ARGS ...)
...
endforeach(loop_var)
All commands between foreach and the matching endforeach are recorded
without being invoked. Once the endforeach is evaluated, the recorded
list of commands is invoked once for each argument listed in the
original foreach command. Before each iteration of the loop
``${loop_var}`` will be set as a variable with the current value in the
list.
::
foreach(loop_var RANGE total)
foreach(loop_var RANGE start stop [step])
Foreach can also iterate over a generated range of numbers. There are
three types of this iteration:
* When specifying single number, the range will have elements [0, ... to
"total"] (inclusive).
* When specifying two numbers, the range will have elements from the
first number to the second number (inclusive).
* The third optional number is the increment used to iterate from the
first number to the second number (inclusive).
::
foreach(loop_var IN [LISTS [list1 [...]]]
[ITEMS [item1 [...]]])
Iterates over a precise list of items. The ``LISTS`` option names
list-valued variables to be traversed, including empty elements (an
empty string is a zero-length list). (Note macro
arguments are not variables.) The ``ITEMS`` option ends argument
parsing and includes all arguments following it in the iteration.
-- X=0
-- X=1
-- X=2
-- X=3
-- X=4 5
-- X=6
-- X=7
-- X=8

84
Help/command/function.rst
View File

@ -1,36 +1,70 @@
function
--------
Start recording a function for later invocation as a command::
Start recording a function for later invocation as a command.
function(<name> [arg1 [arg2 [arg3 ...]]])
COMMAND1(ARGS ...)
COMMAND2(ARGS ...)
...
endfunction(<name>)
.. code-block:: cmake
Define a function named ``<name>`` that takes arguments named ``arg1``,
``arg2``, ``arg3``, (...).
Commands listed after function, but before the matching
:command:`endfunction()`, are not invoked until the function is invoked.
When it is invoked, the commands recorded in the function are first
modified by replacing formal parameters (``${arg1}``) with the arguments
passed, and then invoked as normal commands.
In addition to referencing the formal parameters you can reference the
``ARGC`` variable which will be set to the number of arguments passed
into the function as well as ``ARGV0``, ``ARGV1``, ``ARGV2``, ... which
will have the actual values of the arguments passed in.
This facilitates creating functions with optional arguments.
Additionally ``ARGV`` holds the list of all arguments given to the
function and ``ARGN`` holds the list of arguments past the last expected
argument.
Referencing to ``ARGV#`` arguments beyond ``ARGC`` have undefined
behavior. Checking that ``ARGC`` is greater than ``#`` is the only way
to ensure that ``ARGV#`` was passed to the function as an extra
argument.
function(<name> [<arg1> ...])
<commands>
endfunction()
Defines a function named ``<name>`` that takes arguments named
``<arg1>``, ... The ``<commands>`` in the function definition
are recorded; they are not executed until the function is invoked.
Per legacy, the :command:`endfunction` command admits an optional
``<name>`` argument. If used, it must be a verbatim repeat of the
argument of the opening ``function`` command.
A function opens a new scope: see :command:`set(var PARENT_SCOPE)` for
details.
See the :command:`cmake_policy()` command documentation for the behavior
of policies inside functions.
See the :command:`macro()` command documentation for differences
between CMake functions and macros.
Invocation
^^^^^^^^^^
The function invocation is case-insensitive. A function defined as
.. code-block:: cmake
function(foo)
<commands>
endfunction()
can be invoked through any of
.. code-block:: cmake
foo()
Foo()
FOO()
and so on. However, it is strongly recommended to stay with the
case chosen in the function definition. Typically functions use
all-lowercase names.
Arguments
^^^^^^^^^
When the function is invoked, the recorded ``<commands>`` are first
modified by replacing formal parameters (``${arg1}``, ...) with the
arguments passed, and then invoked as normal commands.
In addition to referencing the formal parameters you can reference the
``ARGC`` variable which will be set to the number of arguments passed
into the function as well as ``ARGV0``, ``ARGV1``, ``ARGV2``, ... which
will have the actual values of the arguments passed in. This facilitates
creating functions with optional arguments.
Furthermore, ``ARGV`` holds the list of all arguments given to the
function and ``ARGN`` holds the list of arguments past the last expected
argument. Referencing to ``ARGV#`` arguments beyond ``ARGC`` have
undefined behavior. Checking that ``ARGC`` is greater than ``#`` is
the only way to ensure that ``ARGV#`` was passed to the function as an
extra argument.

12
Help/command/get_cmake_property.rst
View File

@ -3,14 +3,14 @@ get_cmake_property
Get a global property of the CMake instance.
::
.. code-block:: cmake
get_cmake_property(VAR property)
get_cmake_property(<var> <property>)
Get a global property from the CMake instance. The value of 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.
Gets a global property from the CMake instance. The value of
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.

6
Help/command/get_directory_property.rst
View File

@ -3,11 +3,11 @@ get_directory_property
Get a property of ``DIRECTORY`` scope.
::
.. code-block:: cmake
get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
Store a property of directory scope in the named ``<variable>``.
Stores a property of directory scope in the named ``<variable>``.
The ``DIRECTORY`` argument specifies another directory from which
to retrieve the property value instead of the current directory.
The specified directory must have already been traversed by CMake.
@ -18,7 +18,7 @@ if the property is not found for the nominated directory scope,
the search will chain to a parent scope as described for the
:command:`define_property` command.
::
.. code-block:: cmake
get_directory_property(<variable> [DIRECTORY <dir>]
DEFINITION <var-name>)

37
Help/command/get_filename_component.rst
View File

@ -3,13 +3,11 @@ get_filename_component
Get a specific component of a full filename.
------------------------------------------------------------------------------
.. code-block:: cmake
::
get_filename_component(<var> <FileName> <mode> [CACHE])
get_filename_component(<VAR> <FileName> <COMP> [CACHE])
Set ``<VAR>`` to a component of ``<FileName>``, where ``<COMP>`` is one of:
Sets ``<var>`` to a component of ``<FileName>``, where ``<mode>`` is one of:
::
@ -17,22 +15,19 @@ Set ``<VAR>`` to a component of ``<FileName>``, where ``<COMP>`` is one of:
NAME = File name without directory
EXT = File name longest extension (.b.c from d/a.b.c)
NAME_WE = File name without directory or longest extension
LAST_EXT = File name last extension (.c from d/a.b.c)
NAME_WLE = File name without directory or last extension
PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
Paths are returned with forward slashes and have no trailing slashes.
The longest file extension is always considered. If the optional
``CACHE`` argument is specified, the result variable is added to the
cache.
If the optional ``CACHE`` argument is specified, the result variable is
added to the cache.
------------------------------------------------------------------------------
.. code-block:: cmake
::
get_filename_component(<var> <FileName> <mode> [BASE_DIR <dir>] [CACHE])
get_filename_component(<VAR> <FileName>
<COMP> [BASE_DIR <BASE_DIR>]
[CACHE])
Set ``<VAR>`` to the absolute path of ``<FileName>``, where ``<COMP>`` is one
Sets ``<var>`` to the absolute path of ``<FileName>``, where ``<mode>`` is one
of:
::
@ -41,7 +36,7 @@ of:
REALPATH = Full path to existing file with symlinks resolved
If the provided ``<FileName>`` is a relative path, it is evaluated relative
to the given base directory ``<BASE_DIR>``. If no base directory is
to the given base directory ``<dir>``. If no base directory is
provided, the default base directory will be
:variable:`CMAKE_CURRENT_SOURCE_DIR`.
@ -49,16 +44,12 @@ Paths are returned with forward slashes and have no trailing slashes. If the
optional ``CACHE`` argument is specified, the result variable is added to the
cache.
------------------------------------------------------------------------------
.. code-block:: cmake
::
get_filename_component(<VAR> <FileName>
PROGRAM [PROGRAM_ARGS <ARG_VAR>]
[CACHE])
get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE])
The program in ``<FileName>`` will be found in the system search path or
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
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.

20
Help/command/get_property.rst
View File

@ -3,32 +3,33 @@ get_property
Get a property.
::
.. code-block:: cmake
get_property(<variable>
<GLOBAL |
DIRECTORY [dir] |
DIRECTORY [<dir>] |
TARGET <target> |
SOURCE <source> |
INSTALL <file> |
TEST <test> |
CACHE <entry> |
VARIABLE>
VARIABLE >
PROPERTY <name>
[SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
Get one property from one object in a scope. The first argument
specifies the variable in which to store the result. The second
argument determines the scope from which to get the property. It must
be one of the following:
Gets one property from one object in a scope.
The first argument specifies the variable in which to store the result.
The second argument determines the scope from which to get the property.
It must be one of the following:
``GLOBAL``
Scope is unique and does not accept a name.
``DIRECTORY``
Scope defaults to the current directory but another
directory (already processed by CMake) may be named by full or
relative path.
directory (already processed by CMake) may be named by the
full or relative path ``<dir>``.
``TARGET``
Scope must name one existing target.
@ -58,6 +59,7 @@ value indicating whether the property has been set. If the ``DEFINED``
option is given the variable is set to a boolean value indicating
whether the property has been defined such as with the
:command:`define_property` command.
If ``BRIEF_DOCS`` or ``FULL_DOCS`` is given then the variable is set to a
string containing documentation for the requested property. If
documentation is requested for a property that has not been defined

4
Help/command/get_source_file_property.rst
View File

@ -3,11 +3,11 @@ get_source_file_property
Get a property for a source file.
::
.. code-block:: cmake
get_source_file_property(VAR file property)
Get a property from a source file. The value of the property is
Gets a property from a source file. The value of the property is
stored in the variable ``VAR``. If the source property is not found, the
behavior depends on whether it has been defined to be an ``INHERITED`` property
or not (see :command:`define_property`). Non-inherited properties will set

6
Help/command/get_target_property.rst
View File

@ -3,7 +3,7 @@ get_target_property
Get a property from a target.
::
.. code-block:: cmake
get_target_property(VAR target property)
@ -11,7 +11,7 @@ Get a property from a target. The value of the property is stored in
the variable ``VAR``. If the target property is not found, the behavior
depends on whether it has been defined to be an ``INHERITED`` property
or not (see :command:`define_property`). Non-inherited properties will
set ``VAR`` to "NOTFOUND", whereas inherited properties will search the
set ``VAR`` to ``NOTFOUND``, whereas inherited properties will search the
relevant parent scope as described for the :command:`define_property`
command and if still unable to find the property, ``VAR`` will be set to
an empty string.
@ -23,3 +23,5 @@ 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 :ref:`Target Properties` for the list of properties known to CMake.

2
Help/command/get_test_property.rst
View File

@ -3,7 +3,7 @@ get_test_property
Get a property of the test.
::
.. code-block:: cmake
get_test_property(test property VAR)

124
Help/command/if.rst
View File

@ -3,41 +3,49 @@ if
Conditionally execute a group of commands.
Synopsis
^^^^^^^^
.. code-block:: cmake
if(expression)
# then section.
COMMAND1(ARGS ...)
COMMAND2(ARGS ...)
#...
elseif(expression2)
# elseif section.
COMMAND1(ARGS ...)
COMMAND2(ARGS ...)
#...
else(expression)
# else section.
COMMAND1(ARGS ...)
COMMAND2(ARGS ...)
#...
endif(expression)
if(<condition>)
<commands>
elseif(<condition>) # optional block, can be repeated
<commands>
else() # optional block
<commands>
endif()
Evaluates the given expression. If the result is true, the commands
in the THEN section are invoked. Otherwise, the commands in the else
section are invoked. The elseif and else sections are optional. You
may have multiple elseif clauses. Note that the expression in the
else and endif clause is optional. Long expressions can be used and
there is a traditional order of precedence. Parenthetical expressions
are evaluated first followed by unary tests such as ``EXISTS``,
``COMMAND``, and ``DEFINED``. Then any binary tests such as
Evaluates the ``condition`` argument of the ``if`` clause according to the
`Condition syntax`_ described below. If the result is true, then the
``commands`` in the ``if`` block are executed.
Otherwise, optional ``elseif`` blocks are processed in the same way.
Finally, if no ``condition`` is true, ``commands`` in the optional ``else``
block are executed.
Per legacy, the :command:`else` and :command:`endif` commands admit
an optional ``<condition>`` argument.
If used, it must be a verbatim
repeat of the argument of the opening
``if`` command.
Condition Syntax
^^^^^^^^^^^^^^^^
The following syntax applies to the ``condition`` argument of
the ``if``, ``elseif`` and :command:`while` clauses.
Compound conditions are evaluated in the following order of precedence:
Innermost parentheses are evaluated first. Next come unary tests such
as ``EXISTS``, ``COMMAND``, and ``DEFINED``. Then binary tests such as
``EQUAL``, ``LESS``, ``LESS_EQUAL``, ``GREATER``, ``GREATER_EQUAL``,
``STREQUAL``, ``STRLESS``, ``STRLESS_EQUAL``, ``STRGREATER``,
``STRGREATER_EQUAL``, ``VERSION_EQUAL``, ``VERSION_LESS``,
``VERSION_LESS_EQUAL``, ``VERSION_GREATER``, ``VERSION_GREATER_EQUAL``,
and ``MATCHES`` will be evaluated. Then boolean ``NOT`` operators and
finally boolean ``AND`` and then ``OR`` operators will be evaluated.
and ``MATCHES``. Then the boolean operators in the order ``NOT``, ``AND``,
and finally ``OR``.
Possible expressions are:
Possible conditions are:
``if(<constant>)``
True if the constant is ``1``, ``ON``, ``YES``, ``TRUE``, ``Y``,
@ -52,14 +60,14 @@ Possible expressions are:
True if given a variable that is defined to a value that is not a false
constant. False otherwise. (Note macro arguments are not variables.)
``if(NOT <expression>)``
True if the expression is not true.
``if(NOT <condition>)``
True if the condition is not true.
``if(<expr1> AND <expr2>)``
True if both expressions would be considered true individually.
``if(<cond1> AND <cond2>)``
True if both conditions would be considered true individually.
``if(<expr1> OR <expr2>)``
True if either expression would be considered true individually.
``if(<cond1> OR <cond2>)``
True if either condition would be considered true individually.
``if(COMMAND command-name)``
True if the given name is a command, macro or function that can be
@ -80,7 +88,9 @@ Possible expressions are:
``if(EXISTS path-to-file-or-directory)``
True if the named file or directory exists. Behavior is well-defined
only for full paths.
only for full paths. 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.
``if(file1 IS_NEWER_THAN file2)``
True if ``file1`` is newer than ``file2`` or if one of the two files doesn't
@ -103,7 +113,7 @@ Possible expressions are:
``if(<variable|string> MATCHES regex)``
True if the given string or variable's value matches the given regular
expression. See :ref:`Regex Specification` for regex format.
condition. See :ref:`Regex Specification` for regex format.
``()`` groups are captured in :variable:`CMAKE_MATCH_<n>` variables.
``if(<variable|string> LESS <variable|string>)``
@ -179,42 +189,51 @@ Possible expressions are:
``if(<variable|string> IN_LIST <variable>)``
True if the given element is contained in the named list variable.
``if(DEFINED <variable>)``
True if the given variable is defined. It does not matter if the
variable is true or false just if it has been set. (Note macro
arguments are not variables.)
``if(DEFINED <name>|CACHE{<name>}|ENV{<name>})``
True if a variable, cache variable or environment variable
with given ``<name>`` is defined. The value of the variable
does not matter. Note that macro arguments are not variables.
``if((expression) AND (expression OR (expression)))``
The expressions inside the parenthesis are evaluated first and then
the remaining expression is evaluated as in the previous examples.
``if((condition) AND (condition OR (condition)))``
The conditions inside the parenthesis are evaluated first and then
the remaining condition is evaluated as in the previous examples.
Where there are nested parenthesis the innermost are evaluated as part
of evaluating the expression that contains them.
of evaluating the condition that contains them.
Variable Expansion
^^^^^^^^^^^^^^^^^^
The if command was written very early in CMake's history, predating
the ``${}`` variable evaluation syntax, and for convenience evaluates
variables named by its arguments as shown in the above signatures.
Note that normal variable evaluation with ``${}`` applies before the if
command even receives the arguments. Therefore code like::
command even receives the arguments. Therefore code like
.. code-block:: cmake
set(var1 OFF)
set(var2 "var1")
if(${var2})
appears to the if command as::
appears to the if command as
if(var1)
.. code-block:: cmake
if(var1)
and is evaluated according to the ``if(<variable>)`` case documented
above. The result is ``OFF`` which is false. However, if we remove the
``${}`` from the example then the command sees::
``${}`` from the example then the command sees
if(var2)
.. code-block:: cmake
which is true because ``var2`` is defined to "var1" which is not a false
if(var2)
which is true because ``var2`` is defined to ``var1`` which is not a false
constant.
Automatic evaluation applies in the other cases whenever the
above-documented signature accepts ``<variable|string>``:
above-documented condition syntax accepts ``<variable|string>``:
* The left hand argument to ``MATCHES`` is first checked to see if it is
a defined variable, if so the variable's value is used, otherwise the
@ -252,3 +271,8 @@ specified in a :ref:`Quoted Argument` or a :ref:`Bracket Argument`.
A quoted or bracketed variable or keyword will be interpreted as a
string and not dereferenced or interpreted.
See policy :policy:`CMP0054`.
There is no automatic evaluation for environment or cache
:ref:`Variable References`. Their values must be referenced as
``$ENV{<name>}`` or ``$CACHE{<name>}`` wherever the above-documented
condition syntax accepts ``<variable|string>``.

10
Help/command/include.rst
View File

@ -3,16 +3,16 @@ include
Load and run CMake code from a file or module.
::
.. code-block:: cmake
include(<file|module> [OPTIONAL] [RESULT_VARIABLE <VAR>]
include(<file|module> [OPTIONAL] [RESULT_VARIABLE <var>]
[NO_POLICY_SCOPE])
Load and run CMake code from the file given. Variable reads and
Loads and runs CMake code from the file given. Variable reads and
writes access the scope of the caller (dynamic scoping). If ``OPTIONAL``
is present, then no error is raised if the file does not exist. If
``RESULT_VARIABLE`` is given the variable will be set to the full filename
which has been included or NOTFOUND if it failed.
``RESULT_VARIABLE`` is given the variable ``<var>`` will be set to the
full filename which has been included or ``NOTFOUND`` if it failed.
If a module is specified instead of a file, the file with name
``<modulename>.cmake`` is searched first in :variable:`CMAKE_MODULE_PATH`,

2
Help/command/include_directories.rst
View File

@ -3,7 +3,7 @@ include_directories
Add include directories to the build.
::
.. code-block:: cmake
include_directories([AFTER|BEFORE] [SYSTEM] dir1 [dir2 ...])

6
Help/command/include_external_msproject.rst
View File

@ -3,7 +3,7 @@ include_external_msproject
Include an external Microsoft project file in a workspace.
::
.. code-block:: cmake
include_external_msproject(projectname location
[TYPE projectTypeGUID]
@ -13,11 +13,11 @@ Include an external Microsoft project file in a workspace.
Includes an external Microsoft project in the generated workspace
file. Currently does nothing on UNIX. This will create a target
named [projectname]. This can be used in the :command:`add_dependencies`
named ``[projectname]``. This can be used in the :command:`add_dependencies`
command to make things depend on the external project.
``TYPE``, ``GUID`` and ``PLATFORM`` are optional parameters that allow one to
specify the type of project, id (GUID) of the project and the name of
specify the type of project, id (``GUID``) of the project and the name of
the target platform. This is useful for projects requiring values
other than the default (e.g. WIX projects).

2
Help/command/include_guard.rst
View File

@ -3,7 +3,7 @@ include_guard
Provides an include guard for the file currently being processed by CMake.
::
.. code-block:: cmake
include_guard([DIRECTORY|GLOBAL])

4
Help/command/include_regular_expression.rst
View File

@ -3,11 +3,11 @@ include_regular_expression
Set the regular expression used for dependency checking.
::
.. code-block:: cmake
include_regular_expression(regex_match [regex_complain])
Set the regular expressions used in dependency checking. Only files
Sets the regular expressions used in dependency checking. Only files
matching ``regex_match`` will be traced as dependencies. Only files
matching ``regex_complain`` will generate warnings if they cannot be found
(standard header paths are not searched). The defaults are:

205
Help/command/install.rst
View File

@ -9,11 +9,11 @@ Synopsis
.. parsed-literal::
install(`TARGETS`_ <target>... [...])
install({`FILES`_ | `PROGRAMS`_} <file>... DESTINATION <dir> [...])
install(`DIRECTORY`_ <dir>... DESTINATION <dir> [...])
install({`FILES`_ | `PROGRAMS`_} <file>... [...])
install(`DIRECTORY`_ <dir>... [...])
install(`SCRIPT`_ <file> [...])
install(`CODE`_ <code> [...])
install(`EXPORT`_ <export-name> DESTINATION <dir> [...])
install(`EXPORT`_ <export-name> [...])
Introduction
^^^^^^^^^^^^
@ -99,9 +99,10 @@ Windows platforms are unaffected.
Installing Targets
^^^^^^^^^^^^^^^^^^
.. _`install(TARGETS)`:
.. _TARGETS:
::
.. code-block:: cmake
install(TARGETS targets... [EXPORT <export-name>]
[[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|
@ -147,13 +148,13 @@ project. There are several kinds of target files that may be installed:
property are treated as ``FRAMEWORK`` targets on macOS.
``BUNDLE``
Executables marked with the ``MACOSX_BUNDLE`` property are treated as
Executables marked with the :prop_tgt:`MACOSX_BUNDLE` property are treated as
``BUNDLE`` targets on macOS.
``PUBLIC_HEADER``
Any ``PUBLIC_HEADER`` files associated with a library are installed in
Any :prop_tgt:`PUBLIC_HEADER` files associated with a library are installed in
the destination specified by the ``PUBLIC_HEADER`` argument on non-Apple
platforms. Rules defined by this argument are ignored for ``FRAMEWORK``
platforms. Rules defined by this argument are ignored for :prop_tgt:`FRAMEWORK`
libraries on Apple platforms because the associated files are installed
into the appropriate locations inside the framework folder. See
:prop_tgt:`PUBLIC_HEADER` for details.
@ -172,6 +173,54 @@ installation properties apply to all target types. If only one is given then
only targets of that type will be installed (which can be used to install
just a DLL or just an import library.)
For regular executables, static libraries and shared libraries, the
``DESTINATION`` argument is not required. For these target types, when
``DESTINATION`` is omitted, a default destination will be taken from the
appropriate variable from :module:`GNUInstallDirs`, or set to a built-in
default value if that variable is not defined. The same is true for the
public and private headers associated with the installed targets through the
:prop_tgt:`PUBLIC_HEADER` and :prop_tgt:`PRIVATE_HEADER` target properties.
A destination must always be provided for module libraries, Apple bundles and
frameworks. A destination can be omitted for interface and object libraries,
but they are handled differently (see the discussion of this topic toward the
end of this section).
The following table shows the target types with their associated variables and
built-in defaults that apply when no destination is given:
================== =============================== ======================
Target Type GNUInstallDirs Variable Built-In Default
================== =============================== ======================
``RUNTIME`` ``${CMAKE_INSTALL_BINDIR}`` ``bin``
``LIBRARY`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib``
``ARCHIVE`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib``
``PRIVATE_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
``PUBLIC_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
================== =============================== ======================
Projects wishing to follow the common practice of installing headers into a
project-specific subdirectory will need to provide a destination rather than
rely on the above.
To make packages compliant with distribution filesystem layout policies, if
projects must specify a ``DESTINATION``, it is recommended that they use a
path that begins with the appropriate :module:`GNUInstallDirs` variable.
This allows package maintainers to control the install destination by setting
the appropriate cache variables. The following example shows a static library
being installed to the default destination provided by
:module:`GNUInstallDirs`, but with its headers installed to a project-specific
subdirectory that follows the above recommendation:
.. code-block:: cmake
add_library(mylib STATIC ...)
set_target_properties(mylib PROPERTIES PUBLIC_HEADER mylib.h)
include(GNUInstallDirs)
install(TARGETS mylib
PUBLIC_HEADER
DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
)
In addition to the common options listed above, each target can accept
the following additional arguments:
@ -195,11 +244,9 @@ the following additional arguments:
install(TARGETS mylib
LIBRARY
DESTINATION lib
COMPONENT Libraries
NAMELINK_COMPONENT Development
PUBLIC_HEADER
DESTINATION include
COMPONENT Development
)
@ -242,18 +289,20 @@ the following additional arguments:
is not recommended to use ``NAMELINK_SKIP`` in conjunction with
``NAMELINK_COMPONENT``.
The ``install(TARGETS)`` command can also accept the following options at the
The `install(TARGETS)`_ command can also accept the following options at the
top level:
``EXPORT``
This option associates the installed target files with an export called
``<export-name>``. It must appear before any target options. To actually
install the export file itself, call ``install(EXPORT)``, documented below.
install the export file itself, call `install(EXPORT)`_, documented below.
See documentation of the :prop_tgt:`EXPORT_NAME` target property to change
the name of the exported target.
``INCLUDES DESTINATION``
This option specifies a list of directories which will be added to the
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property of the
``<targets>`` when exported by the :command:`install(EXPORT)` command. If a
``<targets>`` when exported by the `install(EXPORT)`_ command. If a
relative path is specified, it is treated as relative to the
``$<INSTALL_PREFIX>``.
@ -287,7 +336,7 @@ targets that link to the object libraries in their implementation.
Installing a target with the :prop_tgt:`EXCLUDE_FROM_ALL` target property
set to ``TRUE`` has undefined behavior.
:command:`install(TARGETS)` can install targets that were created in
`install(TARGETS)`_ can install targets that were created in
other directories. When using such cross-directory install rules, running
``make install`` (or similar) from a subdirectory will not guarantee that
targets from other directories are up-to-date. You can use
@ -295,19 +344,22 @@ targets from other directories are up-to-date. You can use
to ensure that such out-of-directory targets are built before the
subdirectory-specific install rules are run.
The install destination given to the target install ``DESTINATION`` may
An install destination given as a ``DESTINATION`` argument may
use "generator expressions" with the syntax ``$<...>``. See the
:manual:`cmake-generator-expressions(7)` manual for available expressions.
Installing Files
^^^^^^^^^^^^^^^^
.. _`install(FILES)`:
.. _`install(PROGRAMS)`:
.. _FILES:
.. _PROGRAMS:
::
.. code-block:: cmake
install(<FILES|PROGRAMS> files... DESTINATION <dir>
install(<FILES|PROGRAMS> files...
TYPE <type> | DESTINATION <dir>
[PERMISSIONS permissions...]
[CONFIGURATIONS [Debug|Release|...]]
[COMPONENT <component>]
@ -331,18 +383,71 @@ The list of ``files...`` given to ``FILES`` or ``PROGRAMS`` may use
However, if any item begins in a generator expression it must evaluate
to a full path.
The install destination given to the files install ``DESTINATION`` may
Either a ``TYPE`` or a ``DESTINATION`` must be provided, but not both.
A ``TYPE`` argument specifies the generic file type of the files being
installed. A destination will then be set automatically by taking the
corresponding variable from :module:`GNUInstallDirs`, or by using a
built-in default if that variable is not defined. See the table below for
the supported file types and their corresponding variables and built-in
defaults. Projects can provide a ``DESTINATION`` argument instead of a
file type if they wish to explicitly define the install destination.
======================= ================================== =========================
``TYPE`` Argument GNUInstallDirs Variable Built-In Default
======================= ================================== =========================
``BIN`` ``${CMAKE_INSTALL_BINDIR}`` ``bin``
``SBIN`` ``${CMAKE_INSTALL_SBINDIR}`` ``sbin``
``LIB`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib``
``INCLUDE`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
``SYSCONF`` ``${CMAKE_INSTALL_SYSCONFDIR}`` ``etc``
``SHAREDSTATE`` ``${CMAKE_INSTALL_SHARESTATEDIR}`` ``com``
``LOCALSTATE`` ``${CMAKE_INSTALL_LOCALSTATEDIR}`` ``var``
``RUNSTATE`` ``${CMAKE_INSTALL_RUNSTATEDIR}`` ``<LOCALSTATE dir>/run``
``DATA`` ``${CMAKE_INSTALL_DATADIR}`` ``<DATAROOT dir>``
``INFO`` ``${CMAKE_INSTALL_INFODIR}`` ``<DATAROOT dir>/info``
``LOCALE`` ``${CMAKE_INSTALL_LOCALEDIR}`` ``<DATAROOT dir>/locale``
``MAN`` ``${CMAKE_INSTALL_MANDIR}`` ``<DATAROOT dir>/man``
``DOC`` ``${CMAKE_INSTALL_DOCDIR}`` ``<DATAROOT dir>/doc``
======================= ================================== =========================
Projects wishing to follow the common practice of installing headers into a
project-specific subdirectory will need to provide a destination rather than
rely on the above.
Note that some of the types' built-in defaults use the ``DATAROOT`` directory as
a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with
``CMAKE_INSTALL_DATAROOTDIR`` as the variable and ``share`` as the built-in
default. You cannot use ``DATAROOT`` as a ``TYPE`` parameter; please use
``DATA`` instead.
To make packages compliant with distribution filesystem layout policies, if
projects must specify a ``DESTINATION``, it is recommended that they use a
path that begins with the appropriate :module:`GNUInstallDirs` variable.
This allows package maintainers to control the install destination by setting
the appropriate cache variables. The following example shows how to follow
this advice while installing headers to a project-specific subdirectory:
.. code-block:: cmake
include(GNUInstallDirs)
install(FILES mylib.h
DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
)
An install destination given as a ``DESTINATION`` argument may
use "generator expressions" with the syntax ``$<...>``. See the
:manual:`cmake-generator-expressions(7)` manual for available expressions.
Installing Directories
^^^^^^^^^^^^^^^^^^^^^^
.. _`install(DIRECTORY)`:
.. _DIRECTORY:
::
.. code-block:: cmake
install(DIRECTORY dirs... DESTINATION <dir>
install(DIRECTORY dirs...
TYPE <type> | DESTINATION <dir>
[FILE_PERMISSIONS permissions...]
[DIRECTORY_PERMISSIONS permissions...]
[USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
@ -413,18 +518,60 @@ will install the ``icons`` directory to ``share/myproj/icons`` and the
file permissions, the scripts will be given specific permissions, and any
``CVS`` directories will be excluded.
The list of ``dirs...`` given to ``DIRECTORY`` and the install destination
given to the directory install ``DESTINATION`` may use "generator expressions"
Either a ``TYPE`` or a ``DESTINATION`` must be provided, but not both.
A ``TYPE`` argument specifies the generic file type of the files within the
listed directories being installed. A destination will then be set
automatically by taking the corresponding variable from
:module:`GNUInstallDirs`, or by using a built-in default if that variable
is not defined. See the table below for the supported file types and their
corresponding variables and built-in defaults. Projects can provide a
``DESTINATION`` argument instead of a file type if they wish to explicitly
define the install destination.
======================= ================================== =========================
``TYPE`` Argument GNUInstallDirs Variable Built-In Default
======================= ================================== =========================
``BIN`` ``${CMAKE_INSTALL_BINDIR}`` ``bin``
``SBIN`` ``${CMAKE_INSTALL_SBINDIR}`` ``sbin``
``LIB`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib``
``INCLUDE`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
``SYSCONF`` ``${CMAKE_INSTALL_SYSCONFDIR}`` ``etc``
``SHAREDSTATE`` ``${CMAKE_INSTALL_SHARESTATEDIR}`` ``com``
``LOCALSTATE`` ``${CMAKE_INSTALL_LOCALSTATEDIR}`` ``var``
``RUNSTATE`` ``${CMAKE_INSTALL_RUNSTATEDIR}`` ``<LOCALSTATE dir>/run``
``DATA`` ``${CMAKE_INSTALL_DATADIR}`` ``<DATAROOT dir>``
``INFO`` ``${CMAKE_INSTALL_INFODIR}`` ``<DATAROOT dir>/info``
``LOCALE`` ``${CMAKE_INSTALL_LOCALEDIR}`` ``<DATAROOT dir>/locale``
``MAN`` ``${CMAKE_INSTALL_MANDIR}`` ``<DATAROOT dir>/man``
``DOC`` ``${CMAKE_INSTALL_DOCDIR}`` ``<DATAROOT dir>/doc``
======================= ================================== =========================
Note that some of the types' built-in defaults use the ``DATAROOT`` directory as
a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with
``CMAKE_INSTALL_DATAROOTDIR`` as the variable and ``share`` as the built-in
default. You cannot use ``DATAROOT`` as a ``TYPE`` parameter; please use
``DATA`` instead.
To make packages compliant with distribution filesystem layout policies, if
projects must specify a ``DESTINATION``, it is recommended that they use a
path that begins with the appropriate :module:`GNUInstallDirs` variable.
This allows package maintainers to control the install destination by setting
the appropriate cache variables.
The list of ``dirs...`` given to ``DIRECTORY`` and an install destination
given as a ``DESTINATION`` argument may use "generator expressions"
with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions.
Custom Installation Logic
^^^^^^^^^^^^^^^^^^^^^^^^^
.. _`install(CODE)`:
.. _`install(SCRIPT)`:
.. _CODE:
.. _SCRIPT:
::
.. code-block:: cmake
install([[SCRIPT <file>] [CODE <code>]]
[COMPONENT <component>] [EXCLUDE_FROM_ALL] [...])
@ -442,12 +589,18 @@ example, the code
will print a message during installation.
``<file>`` or ``<code>`` may use "generator expressions" with the syntax
``$<...>`` (in the case of ``<file>``, this refers to their use in the file
name, not the file's contents). See the
:manual:`cmake-generator-expressions(7)` manual for available expressions.
Installing Exports
^^^^^^^^^^^^^^^^^^
.. _`install(EXPORT)`:
.. _EXPORT:
::
.. code-block:: cmake
install(EXPORT <export-name> DESTINATION <dir>
[NAMESPACE <namespace>] [[FILE <name>.cmake]|
@ -461,7 +614,7 @@ Installing Exports
The ``EXPORT`` form generates and installs a CMake file containing code to
import targets from the installation tree into another project.
Target installations are associated with the export ``<export-name>``
using the ``EXPORT`` option of the ``install(TARGETS)`` signature
using the ``EXPORT`` option of the `install(TARGETS)`_ signature
documented above. The ``NAMESPACE`` option will prepend ``<namespace>`` to
the target names as they are written to the import file. By default
the generated file will be called ``<export-name>.cmake`` but the ``FILE``
@ -507,9 +660,9 @@ and installed by the current project. For example, the code
install(TARGETS myexe EXPORT myproj DESTINATION bin)
install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
install(EXPORT_ANDROID_MK myexp DESTINATION share/ndk-modules)
install(EXPORT_ANDROID_MK myproj DESTINATION share/ndk-modules)
will install the executable myexe to ``<prefix>/bin`` and code to import
will install the executable ``myexe`` to ``<prefix>/bin`` and code to import
it in the file ``<prefix>/lib/myproj/myproj.cmake`` and
``<prefix>/share/ndk-modules/Android.mk``. An outside project
may load this file with the include command and reference the ``myexe``

6
Help/command/install_files.rst
View File

@ -1,7 +1,9 @@
install_files
-------------
Deprecated. Use the :command:`install(FILES)` command instead.
.. deprecated:: 3.0
Use the :command:`install(FILES)` command instead.
This command has been superceded by the :command:`install` command. It is
provided for compatibility with older CMake code. The ``FILES`` form is
@ -19,7 +21,7 @@ or its corresponding location in the binary tree may be listed. If a
file specified already has an extension, that extension will be
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'.
A typical extension is ``.h``.
::

4
Help/command/install_programs.rst
View File

@ -1,7 +1,9 @@
install_programs
----------------
Deprecated. Use the :command:`install(PROGRAMS)` command instead.
.. deprecated:: 3.0
Use the :command:`install(PROGRAMS)` command instead.
This command has been superceded by the :command:`install` command. It is
provided for compatibility with older CMake code. The ``FILES`` form is

4
Help/command/install_targets.rst
View File

@ -1,7 +1,9 @@
install_targets
---------------
Deprecated. Use the :command:`install(TARGETS)` command instead.
.. deprecated:: 3.0
Use the :command:`install(TARGETS)` command instead.
This command has been superceded by the :command:`install` command. It is
provided for compatibility with older CMake code.

4
Help/command/link_directories.rst
View File

@ -3,11 +3,11 @@ link_directories
Add directories in which the linker will look for libraries.
::
.. code-block:: cmake
link_directories([AFTER|BEFORE] directory1 [directory2 ...])
Add the paths in which the linker should search for libraries.
Adds the paths in which the linker should search for libraries.
Relative paths given to this command are interpreted as relative to
the current source directory, see :policy:`CMP0015`.

2
Help/command/link_libraries.rst
View File

@ -3,7 +3,7 @@ link_libraries
Link libraries to all targets added later.
::
.. code-block:: cmake
link_libraries([item1 [item2 [...]]]
[[debug|optimized|general] <item>] ...)

138
Help/command/list.rst
View File

@ -21,6 +21,9 @@ Synopsis
list(`APPEND`_ <list> [<element>...])
list(`FILTER`_ <list> {INCLUDE | EXCLUDE} REGEX <regex>)
list(`INSERT`_ <list> <index> [<element>...])
list(`POP_BACK`_ <list> [<out-var>...])
list(`POP_FRONT`_ <list> [<out-var>...])
list(`PREPEND`_ <list> [<element>...])
list(`REMOVE_ITEM`_ <list> <value>...)
list(`REMOVE_AT`_ <list> <index>...)
list(`REMOVE_DUPLICATES`_ <list>)
@ -33,8 +36,9 @@ Synopsis
Introduction
^^^^^^^^^^^^
The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``REMOVE_AT``,
``REMOVE_ITEM``, ``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create
The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``PREPEND``,
``POP_BACK``, ``POP_FRONT``, ``REMOVE_AT``, ``REMOVE_ITEM``,
``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create
new values for the list within the current CMake variable scope. Similar to
the :command:`set` command, the LIST command creates new variable values in
the current scope, even if the list itself is actually defined in a parent
@ -64,7 +68,7 @@ Reading
.. _LENGTH:
::
.. code-block:: cmake
list(LENGTH <list> <output variable>)
@ -72,7 +76,7 @@ Returns the list's length.
.. _GET:
::
.. code-block:: cmake
list(GET <list> <element index> [<element index> ...] <output variable>)
@ -80,7 +84,7 @@ Returns the list of elements specified by indices from the list.
.. _JOIN:
::
.. code-block:: cmake
list(JOIN <list> <glue> <output variable>)
@ -90,7 +94,7 @@ from :command:`string` command.
.. _SUBLIST:
::
.. code-block:: cmake
list(SUBLIST <list> <begin> <length> <output variable>)
@ -104,7 +108,7 @@ Search
.. _FIND:
::
.. code-block:: cmake
list(FIND <list> <value> <output variable>)
@ -116,7 +120,7 @@ Modification
.. _APPEND:
::
.. code-block:: cmake
list(APPEND <list> [<element> ...])
@ -124,7 +128,7 @@ Appends elements to the list.
.. _FILTER:
::
.. code-block:: cmake
list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>)
@ -136,15 +140,43 @@ For more information on regular expressions see also the
.. _INSERT:
::
.. code-block:: cmake
list(INSERT <list> <element_index> <element> [<element> ...])
Inserts elements to the list to the specified location.
.. _POP_BACK:
.. code-block:: cmake
list(POP_BACK <list> [<out-var>...])
If no variable name is given, removes exactly one element. Otherwise,
assign the last element's value to the given variable and removes it,
up to the last variable name given.
.. _POP_FRONT:
.. code-block:: cmake
list(POP_FRONT <list> [<out-var>...])
If no variable name is given, removes exactly one element. Otherwise,
assign the first element's value to the given variable and removes it,
up to the last variable name given.
.. _PREPEND:
.. code-block:: cmake
list(PREPEND <list> [<element> ...])
Insert elements to the 0th position in the list.
.. _REMOVE_ITEM:
::
.. code-block:: cmake
list(REMOVE_ITEM <list> <value> [<value> ...])
@ -152,7 +184,7 @@ Removes the given items from the list.
.. _REMOVE_AT:
::
.. code-block:: cmake
list(REMOVE_AT <list> <index> [<index> ...])
@ -160,82 +192,96 @@ Removes items at given indices from the list.
.. _REMOVE_DUPLICATES:
::
.. code-block:: cmake
list(REMOVE_DUPLICATES <list>)
Removes duplicated items in the list.
Removes duplicated items in the list. The relative order of items is preserved,
but if duplicates are encountered, only the first instance is preserved.
.. _TRANSFORM:
::
.. code-block:: cmake
list(TRANSFORM <list> <ACTION> [<SELECTOR>]
[OUTPUT_VARIABLE <output variable>])
Transforms the list by applying an action to all or, by specifying a
``<SELECTOR>``, to the selected elements of the list, storing result in-place
or in the specified output variable.
``<SELECTOR>``, to the selected elements of the list, storing the result
in-place or in the specified output variable.
.. note::
``TRANSFORM`` sub-command does not change the number of elements of the
The ``TRANSFORM`` sub-command does not change the number of elements in the
list. If a ``<SELECTOR>`` is specified, only some elements will be changed,
the other ones will remain same as before the transformation.
the other ones will remain the same as before the transformation.
``<ACTION>`` specify the action to apply to the elements of list.
The actions have exactly the same semantics as sub-commands of
:command:`string` command.
The ``<ACTION>`` may be one of:
``<ACTION>`` specifies the action to apply to the elements of the list.
The actions have exactly the same semantics as sub-commands of the
:command:`string` command. ``<ACTION>`` must be one of the following:
``APPEND``, ``PREPEND``: Append, prepend specified value to each element of
the list. ::
the list.
list(TRANSFORM <list> <APPEND|PREPEND> <value> ...)
.. code-block:: cmake
list(TRANSFORM <list> <APPEND|PREPEND> <value> ...)
``TOUPPER``, ``TOLOWER``: Convert each element of the list to upper, lower
characters. ::
characters.
list(TRANSFORM <list> <TOLOWER|TOUPPER> ...)
.. code-block:: cmake
list(TRANSFORM <list> <TOLOWER|TOUPPER> ...)
``STRIP``: Remove leading and trailing spaces from each element of the
list. ::
list.
list(TRANSFORM <list> STRIP ...)
.. code-block:: cmake
list(TRANSFORM <list> STRIP ...)
``GENEX_STRIP``: Strip any
:manual:`generator expressions <cmake-generator-expressions(7)>` from each
element of the list. ::
element of the list.
list(TRANSFORM <list> GENEX_STRIP ...)
.. code-block:: cmake
list(TRANSFORM <list> GENEX_STRIP ...)
``REPLACE``: Match the regular expression as many times as possible and
substitute the replacement expression for the match for each element
of the list
(Same semantic as ``REGEX REPLACE`` from :command:`string` command). ::
(Same semantic as ``REGEX REPLACE`` from :command:`string` command).
list(TRANSFORM <list> REPLACE <regular_expression>
<replace_expression> ...)
.. code-block:: cmake
``<SELECTOR>`` select which elements of the list will be transformed. Only one
type of selector can be specified at a time.
list(TRANSFORM <list> REPLACE <regular_expression>
<replace_expression> ...)
The ``<SELECTOR>`` may be one of:
``<SELECTOR>`` determines which elements of the list will be transformed.
Only one type of selector can be specified at a time. When given,
``<SELECTOR>`` must be one of the following:
``AT``: Specify a list of indexes. ::
``AT``: Specify a list of indexes.
list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...)
.. code-block:: cmake
list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...)
``FOR``: Specify a range with, optionally, an increment used to iterate over
the range. ::
the range.
list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...)
.. code-block:: cmake
list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...)
``REGEX``: Specify a regular expression. Only elements matching the regular
expression will be transformed. ::
expression will be transformed.
list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...)
.. code-block:: cmake
list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...)
Ordering
@ -243,7 +289,7 @@ Ordering
.. _REVERSE:
::
.. code-block:: cmake
list(REVERSE <list>)
@ -251,7 +297,7 @@ Reverses the contents of the list in-place.
.. _SORT:
::
.. code-block:: cmake
list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>])

11
Help/command/load_cache.rst
View File

@ -3,21 +3,20 @@ load_cache
Load in the values from another project's CMake cache.
::
.. code-block:: cmake
load_cache(pathToCacheFile READ_WITH_PREFIX
prefix entry1...)
load_cache(pathToCacheFile READ_WITH_PREFIX prefix entry1...)
Read the cache and store the requested entries in variables with their
Reads the cache and store the requested entries in variables with their
name prefixed with the given prefix. This only reads the values, and
does not create entries in the local project's cache.
::
.. code-block:: cmake
load_cache(pathToCacheFile [EXCLUDE entry1...]
[INCLUDE_INTERNALS entry1...])
Load in the values from another cache and store them in the local
Loads in the values from another cache and store them in the local
project's cache as internal entries. This is useful for a project
that depends on another project built in a different tree. ``EXCLUDE``
option can be used to provide a list of entries to be excluded.

2
Help/command/load_command.rst
View File

@ -1,7 +1,7 @@
load_command
------------
Disallowed. See CMake Policy :policy:`CMP0031`.
Disallowed since version 3.0. See CMake Policy :policy:`CMP0031`.
Load a command into a running CMake.

134
Help/command/macro.rst
View File

@ -1,27 +1,66 @@
macro
-----
Start recording a macro for later invocation as a command::
Start recording a macro for later invocation as a command
macro(<name> [arg1 [arg2 [arg3 ...]]])
COMMAND1(ARGS ...)
COMMAND2(ARGS ...)
...
endmacro(<name>)
.. code-block:: cmake
macro(<name> [<arg1> ...])
<commands>
endmacro()
Defines a macro named ``<name>`` that takes arguments named
``<arg1>``, ... Commands listed after macro, but before the
matching :command:`endmacro()`, are not executed until the macro
is invoked.
Per legacy, the :command:`endmacro` command admits an optional
``<name>`` argument. If used, it must be a verbatim repeat of the
argument of the opening ``macro`` command.
See the :command:`cmake_policy()` command documentation for the behavior
of policies inside macros.
See the :ref:`Macro vs Function` section below for differences
between CMake macros and :command:`functions <function>`.
Invocation
^^^^^^^^^^
The macro invocation is case-insensitive. A macro defined as
.. code-block:: cmake
macro(foo)
<commands>
endmacro()
can be invoked through any of
.. code-block:: cmake
foo()
Foo()
FOO()
and so on. However, it is strongly recommended to stay with the
case chosen in the macro definition. Typically macros use
all-lowercase names.
Arguments
^^^^^^^^^
When a macro is invoked, the commands recorded in the macro are
first modified by replacing formal parameters (``${arg1}``, ...)
with the arguments passed, and then invoked as normal commands.
Define a macro named ``<name>`` that takes arguments named ``arg1``,
``arg2``, ``arg3``, (...).
Commands listed after macro, but before the matching
:command:`endmacro()`, are not invoked until the macro is invoked.
When it is invoked, the commands recorded in the macro are first
modified by replacing formal parameters (``${arg1}``) with the arguments
passed, and then invoked as normal commands.
In addition to referencing the formal parameters you can reference the
values ``${ARGC}`` which will be set to the number of arguments passed
into the function as well as ``${ARGV0}``, ``${ARGV1}``, ``${ARGV2}``,
... which will have the actual values of the arguments passed in.
This facilitates creating macros with optional arguments.
Additionally ``${ARGV}`` holds the list of all arguments given to the
Furthermore, ``${ARGV}`` holds the list of all arguments given to the
macro and ``${ARGN}`` holds the list of arguments past the last expected
argument.
Referencing to ``${ARGV#}`` arguments beyond ``${ARGC}`` have undefined
@ -29,48 +68,73 @@ behavior. Checking that ``${ARGC}`` is greater than ``#`` is the only
way to ensure that ``${ARGV#}`` was passed to the function as an extra
argument.
See the :command:`cmake_policy()` command documentation for the behavior
of policies inside macros.
.. _`Macro vs Function`:
Macro Argument Caveats
^^^^^^^^^^^^^^^^^^^^^^
Macro vs Function
^^^^^^^^^^^^^^^^^
Note that the parameters to a macro and values such as ``ARGN`` are
not variables in the usual CMake sense. They are string
replacements much like the C preprocessor would do with a macro.
Therefore you will NOT be able to use commands like::
The ``macro`` command is very similar to the :command:`function` command.
Nonetheless, there are a few important differences.
In a function, ``ARGN``, ``ARGC``, ``ARGV`` and ``ARGV0``, ``ARGV1``, ...
are true variables in the usual CMake sense. In a macro, they are not,
they are string replacements much like the C preprocessor would do
with a macro. This has a number of consequences, as explained in
the :ref:`Argument Caveats` section below.
Another difference between macros and functions is the control flow.
A function is executed by transferring control from the calling
statement to the function body. A macro is executed as if the macro
body were pasted in place of the calling statement. This has the
consequence that a :command:`return()` in a macro body does not
just terminate execution of the macro; rather, control is returned
from the scope of the macro call. To avoid confusion, it is recommended
to avoid :command:`return()` in macros altogether.
.. _`Argument Caveats`:
Argument Caveats
^^^^^^^^^^^^^^^^
Since ``ARGN``, ``ARGC``, ``ARGV``, ``ARGV0`` etc. are not variables,
you will NOT be able to use commands like
.. code-block:: cmake
if(ARGV1) # ARGV1 is not a variable
if(DEFINED ARGV2) # ARGV2 is not a variable
if(ARGC GREATER 2) # ARGC is not a variable
foreach(loop_var IN LISTS ARGN) # ARGN is not a variable
In the first case, you can use ``if(${ARGV1})``.
In the second and third case, the proper way to check if an optional
variable was passed to the macro is to use ``if(${ARGC} GREATER 2)``.
In the last case, you can use ``foreach(loop_var ${ARGN})`` but this
will skip empty arguments.
If you need to include them, you can use::
In the first case, you can use ``if(${ARGV1})``. In the second and
third case, the proper way to check if an optional variable was
passed to the macro is to use ``if(${ARGC} GREATER 2)``. In the
last case, you can use ``foreach(loop_var ${ARGN})`` but this will
skip empty arguments. If you need to include them, you can use
.. code-block:: cmake
set(list_var "${ARGN}")
foreach(loop_var IN LISTS list_var)
Note that if you have a variable with the same name in the scope from
which the macro is called, using unreferenced names will use the
existing variable instead of the arguments. For example::
existing variable instead of the arguments. For example:
macro(_BAR)
.. code-block:: cmake
macro(bar)
foreach(arg IN LISTS ARGN)
[...]
<commands>
endforeach()
endmacro()
function(_FOO)
_bar(x y z)
function(foo)
bar(x y z)
endfunction()
_foo(a b c)
foo(a b c)
Will loop over ``a;b;c`` and not over ``x;y;z`` as one might be expecting.
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.

4
Help/command/make_directory.rst
View File

@ -1,7 +1,9 @@
make_directory
--------------
Deprecated. Use the :command:`file(MAKE_DIRECTORY)` command instead.
.. deprecated:: 3.0
Use the :command:`file(MAKE_DIRECTORY)` command instead.
::

27
Help/command/mark_as_advanced.rst
View File

@ -3,17 +3,22 @@ mark_as_advanced
Mark cmake cached variables as advanced.
::
.. code-block:: cmake
mark_as_advanced([CLEAR|FORCE] VAR [VAR2 ...])
mark_as_advanced([CLEAR|FORCE] <var1> ...)
Mark the named cached variables as advanced. An advanced variable
will not be displayed in any of the cmake GUIs unless the show
advanced option is on. If ``CLEAR`` is the first argument advanced
variables are changed back to unadvanced. If ``FORCE`` is the first
argument, then the variable is made advanced. If neither ``FORCE`` nor
``CLEAR`` is specified, new values will be marked as advanced, but if the
variable already has an advanced/non-advanced state, it will not be
changed.
Sets the advanced/non-advanced state of the named
cached variables.
It does nothing in script mode.
An advanced variable will not be displayed in any
of the cmake GUIs unless the ``show advanced`` option is on.
In script mode, the advanced/non-advanced state has no effect.
If the keyword ``CLEAR`` is given
then advanced variables are changed back to unadvanced.
If the keyword ``FORCE`` is given
then the variables are made advanced.
If neither ``FORCE`` nor ``CLEAR`` is specified,
new values will be marked as advanced, but if a
variable already has an advanced/non-advanced state,
it will not be changed.

40
Help/command/math.rst
View File

@ -1,30 +1,36 @@
math
----
Mathematical expressions.
Evaluate a mathematical expression.
::
.. code-block:: cmake
math(EXPR <output-variable> <math-expression> [OUTPUT_FORMAT <format>])
math(EXPR <variable> "<expression>" [OUTPUT_FORMAT <format>])
``EXPR`` evaluates mathematical expression and returns result in the
output variable. Example mathematical expression is ``5 * (10 + 13)``.
Evaluates a mathematical ``<expression>`` and sets ``<variable>`` to the
resulting value.
The mathematical expression must be given as a string (i.e. enclosed in
double quotation marks). An example is ``"5 * (10 + 13)"``.
Supported operators are ``+``, ``-``, ``*``, ``/``, ``%``, ``|``, ``&``,
``^``, ``~``, ``<<``, ``>>``, and ``(...)``. They have the same meaning
as they do in C code.
``^``, ``~``, ``<<``, ``>>``, and ``(...)``; they have the same meaning
as in C code.
Numeric constants are evaluated in decimal or hexadecimal representation.
Hexadecimal numbers are recognized when prefixed with ``0x``, as in C code.
The result is formatted according to the option "OUTPUT_FORMAT" ,
where ``<format>`` is one of:
::
The result is formatted according to the option ``OUTPUT_FORMAT``,
where ``<format>`` is one of
HEXADECIMAL = Result in output variable will be formatted in C code
Hexadecimal notation.
DECIMAL = Result in output variable will be formatted in decimal notation.
``HEXADECIMAL``
Hexadecimal notation as in C code, i. e. starting with "0x".
``DECIMAL``
Decimal notation. Which is also used if no ``OUTPUT_FORMAT`` option
is specified.
For example::
For example
math(EXPR value "100 * 0xA" DECIMAL) results in value is set to "1000"
math(EXPR value "100 * 0xA" HEXADECIMAL) results in value is set to "0x3e8"
.. code-block:: cmake
math(EXPR value "100 * 0xA" OUTPUT_FORMAT DECIMAL) # value is set to "1000"
math(EXPR value "100 * 0xA" OUTPUT_FORMAT HEXADECIMAL) # value is set to "0x3e8"

66
Help/command/message.rst
View File

@ -3,30 +3,62 @@ message
Display a message to the user.
::
.. code-block:: cmake
message([<mode>] "message to display" ...)
The optional ``<mode>`` keyword determines the type of message:
::
``FATAL_ERROR``
CMake Error, stop processing and generation.
(none) = Important information
STATUS = Incidental information
WARNING = CMake Warning, continue processing
AUTHOR_WARNING = CMake Warning (dev), continue processing
SEND_ERROR = CMake Error, continue processing,
but skip generation
FATAL_ERROR = CMake Error, stop processing and generation
DEPRECATION = CMake Deprecation Error or Warning if variable
CMAKE_ERROR_DEPRECATED or CMAKE_WARN_DEPRECATED
is enabled, respectively, else no message.
``SEND_ERROR``
CMake Error, continue processing, but skip generation.
The CMake command-line tool displays STATUS messages on stdout and all
other message types on stderr. The CMake GUI displays all messages in
its log area. The interactive dialogs (ccmake and CMakeSetup) show
STATUS messages one at a time on a status line and other messages in
interactive pop-up boxes.
``WARNING``
CMake Warning, continue processing.
``AUTHOR_WARNING``
CMake Warning (dev), continue processing.
``DEPRECATION``
CMake Deprecation Error or Warning if variable
:variable:`CMAKE_ERROR_DEPRECATED` or :variable:`CMAKE_WARN_DEPRECATED`
is enabled, respectively, else no message.
(none) or ``NOTICE``
Important message printed to stderr to attract user's attention.
``STATUS``
The main interesting messages that project users might be interested in.
Ideally these should be concise, no more than a single line, but still
informative.
``VERBOSE``
Detailed informational messages intended for project users. These messages
should provide additional details that won't be of interest in most cases,
but which may be useful to those building the project when they want deeper
insight into what's happening.
``DEBUG``
Detailed informational messages intended for developers working on the
project itself as opposed to users who just want to build it. These messages
will not typically be of interest to other users building the project and
will often be closely related to internal implementation details.
``TRACE``
Fine-grained messages with very low-level implementation details. Messages
using this log level would normally only be temporary and would expect to be
removed before releasing the project, packaging up the files, etc.
The CMake command-line tool displays ``STATUS`` to ``TRACE`` messages on stdout
with the message preceded by two hyphens and a space. All other message types
are sent to stderr and are not prefixed with hyphens. The
:manual:`CMake GUI <cmake-gui(1)>` displays all messages in its log area.
The :manual:`curses interface <ccmake(1)>` shows ``STATUS`` to ``TRACE``
messages one at a time on a status line and other messages in an
interactive pop-up box. The ``--loglevel`` command-line option to each of
these tools can be used to control which messages will be shown.
CMake Warning and Error message text displays using a simple markup
language. Non-indented text is formatted in line-wrapped paragraphs

15
Help/command/option.rst
View File

@ -1,17 +1,16 @@
option
------
Provides an option that the user can optionally select.
Provide an option that the user can optionally select.
::
.. code-block:: cmake
option(<option_variable> "help string describing option"
[initial value])
option(<variable> "<help_text>" [value])
Provide an option for the user to select as ``ON`` or ``OFF``. If no
initial value is provided, ``OFF`` is used. If the option is already
set as a normal variable then the command does nothing
(see policy :policy:`CMP0077`).
Provides an option for the user to select as ``ON`` or ``OFF``.
If no initial ``<value>`` is provided, ``OFF`` is used.
If ``<variable>`` is already set as a normal variable
then the command does nothing (see policy :policy:`CMP0077`).
If you have options that depend on the values of other options, see
the module help for :module:`CMakeDependentOption`.

8
Help/command/output_required_files.rst
View File

@ -1,7 +1,7 @@
output_required_files
---------------------
Disallowed. See CMake Policy :policy:`CMP0032`.
Disallowed since version 3.0. See CMake Policy :policy:`CMP0032`.
Approximate C preprocessor dependency scanning.
@ -14,6 +14,6 @@ more advanced scanner.
output_required_files(srcfile outputfile)
Outputs a list of all the source files that are required by the
specified srcfile. This list is written into outputfile. This is
similar to writing out the dependencies for srcfile except that it
jumps from .h files into .cxx, .c and .cpp files if possible.
specified ``srcfile``. This list is written into ``outputfile``. This is
similar to writing out the dependencies for ``srcfile`` except that it
jumps from ``.h`` files into ``.cxx``, ``.c`` and ``.cpp`` files if possible.

155
Help/command/project.rst
View File

@ -1,90 +1,129 @@
project
-------
Sets project details such as name, version, etc. and enables languages.
Set the name of the project.
Synopsis
^^^^^^^^
.. code-block:: cmake
project(<PROJECT-NAME> [LANGUAGES] [<language-name>...])
project(<PROJECT-NAME> [<language-name>...])
project(<PROJECT-NAME>
[VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
[DESCRIPTION <project-description-string>]
[HOMEPAGE_URL <url-string>]
[LANGUAGES <language-name>...])
Sets the name of the project and stores the name in the
:variable:`PROJECT_NAME` variable. Additionally this sets variables
Sets the name of the project, and stores it in the variable
:variable:`PROJECT_NAME`. When called from the top-level
``CMakeLists.txt`` also stores the project name in the
variable :variable:`CMAKE_PROJECT_NAME`.
Also sets the variables
* :variable:`PROJECT_SOURCE_DIR`,
:variable:`<PROJECT-NAME>_SOURCE_DIR`
* :variable:`PROJECT_BINARY_DIR`,
:variable:`<PROJECT-NAME>_BINARY_DIR`
If ``VERSION`` is specified, given components must be non-negative integers.
If ``VERSION`` is not specified, the default version is the empty string.
The ``VERSION`` option may not be used unless policy :policy:`CMP0048` is
set to ``NEW``.
Further variables are set by the optional arguments described in the following.
If any of these arguments is not used, then the corresponding variables are
set to the empty string.
The :command:`project()` command stores the version number and its components
in variables
Options
^^^^^^^
* :variable:`PROJECT_VERSION`,
:variable:`<PROJECT-NAME>_VERSION`
* :variable:`PROJECT_VERSION_MAJOR`,
:variable:`<PROJECT-NAME>_VERSION_MAJOR`
* :variable:`PROJECT_VERSION_MINOR`,
:variable:`<PROJECT-NAME>_VERSION_MINOR`
* :variable:`PROJECT_VERSION_PATCH`,
:variable:`<PROJECT-NAME>_VERSION_PATCH`
* :variable:`PROJECT_VERSION_TWEAK`,
:variable:`<PROJECT-NAME>_VERSION_TWEAK`
The options are:
Variables corresponding to unspecified versions are set to the empty string
(if policy :policy:`CMP0048` is set to ``NEW``).
``VERSION <version>``
Optional; may not be used unless policy :policy:`CMP0048` is
set to ``NEW``.
If the optional ``DESCRIPTION`` is given, then :variable:`PROJECT_DESCRIPTION`
and :variable:`<PROJECT-NAME>_DESCRIPTION` will be set to its argument.
These variables will be cleared if ``DESCRIPTION`` is not given.
The description is expected to be a relatively short string, usually no more
than a few words.
Takes a ``<version>`` argument composed of non-negative integer components,
i.e. ``<major>[.<minor>[.<patch>[.<tweak>]]]``,
and sets the variables
The optional ``HOMEPAGE_URL`` sets the analogous variables
:variable:`PROJECT_HOMEPAGE_URL` and :variable:`<PROJECT-NAME>_HOMEPAGE_URL`.
When this option is given, the URL provided should be the canonical home for
the project.
These variables will be cleared if ``HOMEPAGE_URL`` is not given.
* :variable:`PROJECT_VERSION`,
:variable:`<PROJECT-NAME>_VERSION`
* :variable:`PROJECT_VERSION_MAJOR`,
:variable:`<PROJECT-NAME>_VERSION_MAJOR`
* :variable:`PROJECT_VERSION_MINOR`,
:variable:`<PROJECT-NAME>_VERSION_MINOR`
* :variable:`PROJECT_VERSION_PATCH`,
:variable:`<PROJECT-NAME>_VERSION_PATCH`
* :variable:`PROJECT_VERSION_TWEAK`,
:variable:`<PROJECT-NAME>_VERSION_TWEAK`.
Note that the description and homepage URL may be used as defaults for
things like packaging meta-data, documentation, etc.
When the ``project()`` command is called from the top-level ``CMakeLists.txt``,
then the version is also stored in the variable :variable:`CMAKE_PROJECT_VERSION`.
Optionally you can specify which languages your project supports.
Example languages include ``C``, ``CXX`` (i.e. C++), ``CUDA``,
``Fortran``, 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.
``DESCRIPTION <project-description-string>``
Optional.
Sets the variables
If enabling ``ASM``, list it last so that CMake can check whether
compilers for other languages like ``C`` work for assembly too.
* :variable:`PROJECT_DESCRIPTION`, :variable:`<PROJECT-NAME>_DESCRIPTION`
If a variable exists called :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`,
the file pointed to by that variable will be included as the last step of the
project command.
to ``<project-description-string>``.
It is recommended that this description is a relatively short string,
usually no more than a few words.
When the ``project()`` command is called from the top-level ``CMakeLists.txt``,
then the description is also stored in the variable :variable:`CMAKE_PROJECT_DESCRIPTION`.
``HOMEPAGE_URL <url-string>``
Optional.
Sets the variables
* :variable:`PROJECT_HOMEPAGE_URL`, :variable:`<PROJECT-NAME>_HOMEPAGE_URL`
to ``<url-string>``, which should be the canonical home URL for the project.
When the ``project()`` command is called from the top-level ``CMakeLists.txt``,
then the URL also is stored in the variable :variable:`CMAKE_PROJECT_HOMEPAGE_URL`.
``LANGUAGES <language-name>...``
Optional.
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``, ``Fortran``, 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.
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.
Code Injection
^^^^^^^^^^^^^^
If the :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variable is set, the file
pointed to by that variable will be included as the first step of the
``project()`` command.
If the :variable:`CMAKE_PROJECT_INCLUDE` or
:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` variables are set, the files
they point to will be included as the last step of the ``project()`` command.
If both are set, then :variable:`CMAKE_PROJECT_INCLUDE` will be included before
:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`.
Usage
^^^^^
The top-level ``CMakeLists.txt`` file for a project must contain a
literal, direct call to the :command:`project` command; loading one
literal, direct call to the ``project()`` command; loading one
through the :command:`include` command is not sufficient. If no such
call exists CMake will implicitly add one to the top that enables the
default languages (``C`` and ``CXX``). The name of the project set in
the top level ``CMakeLists.txt`` file is available from the
:variable:`CMAKE_PROJECT_NAME` variable, its description from
:variable:`CMAKE_PROJECT_DESCRIPTION`, its homepage URL from
:variable:`CMAKE_PROJECT_HOMEPAGE_URL` and its version from
:variable:`CMAKE_PROJECT_VERSION`.
call exists, CMake will issue a warning and pretend there is a
``project(Project)`` at the top to enable the default languages
(``C`` and ``CXX``).
.. note::
Call the :command:`cmake_minimum_required` command at the beginning
of the top-level ``CMakeLists.txt`` file even before calling the
``project()`` command. It is important to establish version and
policy settings before invoking other commands whose behavior they
may affect. See also policy :policy:`CMP0000`.
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.
See also policy :policy:`CMP0000`.

21
Help/command/qt_wrap_cpp.rst
View File

@ -1,12 +1,23 @@
qt_wrap_cpp
-----------
Create Qt Wrappers.
.. deprecated:: 3.14
::
This command was originally added to support Qt 3 before the
:command:`add_custom_command()` command was sufficiently mature. The
:module:`FindQt4` module provides the ``qt4_wrap_cpp()`` macro, which
should be used instead for Qt 4 projects. For projects using Qt 5 or
later, use the equivalent macro provided by Qt itself (e.g. Qt 5 provides
``qt5_wrap_cpp()``).
qt_wrap_cpp(resultingLibraryName DestName
SourceLists ...)
Manually create Qt Wrappers.
Produce moc files for all the .h files listed in the SourceLists. The
.. code-block:: cmake
qt_wrap_cpp(resultingLibraryName DestName SourceLists ...)
Produces moc files for all the .h files listed in the SourceLists. The
moc files will be added to the library using the ``DestName`` source list.
Consider updating the project to use the :prop_tgt:`AUTOMOC` target property
instead for a more automated way of invoking the ``moc`` tool.

18
Help/command/qt_wrap_ui.rst
View File

@ -1,14 +1,26 @@
qt_wrap_ui
----------
Create Qt user interfaces Wrappers.
.. deprecated:: 3.14
::
This command was originally added to support Qt 3 before the
:command:`add_custom_command()` command was sufficiently mature. The
:module:`FindQt4` module provides the ``qt4_wrap_ui()`` macro, which
should be used instead for Qt 4 projects. For projects using Qt 5 or
later, use the equivalent macro provided by Qt itself (e.g. Qt 5 provides
``qt5_wrap_ui()``).
Manually create Qt user interfaces Wrappers.
.. code-block:: cmake
qt_wrap_ui(resultingLibraryName HeadersDestName
SourcesDestName SourceLists ...)
Produce .h and .cxx files for all the .ui files listed in the
Produces .h and .cxx files for all the .ui files listed in the
``SourceLists``. The .h files will be added to the library using the
``HeadersDestNamesource`` list. The .cxx files will be added to the
library using the ``SourcesDestNamesource`` list.
Consider updating the project to use the :prop_tgt:`AUTOUIC` target property
instead for a more automated way of invoking the ``uic`` tool.

4
Help/command/remove.rst
View File

@ -1,7 +1,9 @@
remove
------
Deprecated. Use the :command:`list(REMOVE_ITEM)` command instead.
.. deprecated:: 3.0
Use the :command:`list(REMOVE_ITEM)` command instead.
::

4
Help/command/remove_definitions.rst
View File

@ -1,9 +1,9 @@
remove_definitions
------------------
Removes -D define flags added by :command:`add_definitions`.
Remove -D define flags added by :command:`add_definitions`.
::
.. code-block:: cmake
remove_definitions(-DFOO -DBAR ...)

7
Help/command/return.rst
View File

@ -3,7 +3,7 @@ return
Return from a file, directory or function.
::
.. code-block:: cmake
return()
@ -14,5 +14,6 @@ and control is returned to the including file. If it is encountered in a
file which is not included by another file, e.g. a ``CMakeLists.txt``,
control is returned to the parent directory if there is one. If return is
called in a function, control is returned to the caller of the function.
Note that a macro is not a function and does not handle return like a
function does.
Note that a :command:`macro <macro>`, unlike a :command:`function <function>`,
is expanded in place and therefore cannot handle ``return()``.

46
Help/command/separate_arguments.rst
View File

@ -1,33 +1,43 @@
separate_arguments
------------------
Parse space-separated arguments into a semicolon-separated list.
Parse command-line arguments into a semicolon-separated list.
::
.. code-block:: cmake
separate_arguments(<var> <NATIVE|UNIX|WINDOWS>_COMMAND "<args>")
separate_arguments(<variable> <mode> <args>)
Parses a UNIX- or Windows-style command-line string "<args>" and
stores a semicolon-separated list of the arguments in ``<var>``. The
entire command line must be given in one "<args>" argument.
Parses a space-separated string ``<args>`` into a list of items,
and stores this list in semicolon-separated standard form in ``<variable>``.
The ``UNIX_COMMAND`` mode separates arguments by unquoted whitespace. It
recognizes both single-quote and double-quote pairs. A backslash
escapes the next literal character (``\"`` is ``"``); there are no special
escapes (``\n`` is just ``n``).
This function is intended for parsing command-line arguments.
The entire command line must be passed as one string in the
argument ``<args>``.
The ``WINDOWS_COMMAND`` mode parses a Windows command-line using the same
syntax the runtime library uses to construct argv at startup. It
separates arguments by whitespace that is not double-quoted.
Backslashes are literal unless they precede double-quotes. See the
MSDN article `Parsing C Command-Line Arguments`_ for details.
The exact parsing rules depend on the operating system.
They are specified by the ``<mode>`` argument which must
be one of the following keywords:
The ``NATIVE_COMMAND`` mode parses a Windows command-line if the host
system is Windows, and a UNIX command-line otherwise.
``UNIX_COMMAND``
Arguments are separated by by unquoted whitespace.
Both single-quote and double-quote pairs are respected.
A backslash escapes the next literal character (``\"`` is ``"``);
there are no special escapes (``\n`` is just ``n``).
``WINDOWS_COMMAND``
A Windows command-line is parsed using the same
syntax the runtime library uses to construct argv at startup. It
separates arguments by whitespace that is not double-quoted.
Backslashes are literal unless they precede double-quotes. See the
MSDN article `Parsing C Command-Line Arguments`_ for details.
``NATIVE_COMMAND``
Proceeds as in ``WINDOWS_COMMAND`` mode if the host system is Windows.
Otherwise proceeds as in ``UNIX_COMMAND`` mode.
.. _`Parsing C Command-Line Arguments`: https://msdn.microsoft.com/library/a1y7w461.aspx
::
.. code-block:: cmake
separate_arguments(<var>)

29
Help/command/set.rst
View File

@ -8,18 +8,18 @@ and cache entries.
Signatures of this command that specify a ``<value>...`` placeholder
expect zero or more arguments. Multiple arguments will be joined as
a :ref:`;-list <CMake Language Lists>` to form the actual variable
a :ref:`semicolon-separated list <CMake Language Lists>` to form the actual variable
value to be set. Zero arguments will cause normal variables to be
unset. See the :command:`unset` command to unset variables explicitly.
Set Normal Variable
^^^^^^^^^^^^^^^^^^^
::
.. code-block:: cmake
set(<variable> <value>... [PARENT_SCOPE])
Set the given ``<variable>`` in the current function or directory scope.
Sets the given ``<variable>`` in the current function or directory scope.
If the ``PARENT_SCOPE`` option is given the variable will be set in
the scope above the current scope. Each new directory or function
@ -32,11 +32,11 @@ undefined and if it had a value, it is still that value).
Set Cache Entry
^^^^^^^^^^^^^^^
::
.. code-block:: cmake
set(<variable> <value>... CACHE <type> <docstring> [FORCE])
Set the given cache ``<variable>`` (cache entry). Since cache entries
Sets the given cache ``<variable>`` (cache entry). Since cache entries
are meant to provide user-settable values this does not overwrite
existing cache entries by default. Use the ``FORCE`` option to
overwrite existing entries.
@ -84,8 +84,21 @@ current working directory and convert it to an absolute path.
Set Environment Variable
^^^^^^^^^^^^^^^^^^^^^^^^
::
.. code-block:: cmake
set(ENV{<variable>} <value>...)
set(ENV{<variable>} [<value>])
Set the current process environment ``<variable>`` to the given value.
Sets an :manual:`Environment Variable <cmake-env-variables(7)>`
to the given value.
Subsequent calls of ``$ENV{<variable>}`` will return this new value.
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.
If no argument is given after ``ENV{<variable>}`` or if ``<value>`` is
an empty string, then this command will clear any existing value of the
environment variable.
Arguments after ``<value>`` are ignored. If extra arguments are found,
then an author warning is issued.

10
Help/command/set_directory_properties.rst
View File

@ -1,11 +1,15 @@
set_directory_properties
------------------------
Set properties of the current directory and subdirectories in key-value pairs.
Set properties of the current directory and subdirectories.
::
.. code-block:: cmake
set_directory_properties(PROPERTIES prop1 value1 prop2 value2)
set_directory_properties(PROPERTIES prop1 value1 [prop2 value2] ...)
Sets properties of the current directory and its subdirectories in key-value pairs.
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.

38
Help/command/set_property.rst
View File

@ -3,37 +3,40 @@ set_property
Set a named property in a given scope.
::
.. code-block:: cmake
set_property(<GLOBAL |
DIRECTORY [dir] |
TARGET [target1 [target2 ...]] |
SOURCE [src1 [src2 ...]] |
INSTALL [file1 [file2 ...]] |
TEST [test1 [test2 ...]] |
CACHE [entry1 [entry2 ...]]>
set_property(<GLOBAL |
DIRECTORY [<dir>] |
TARGET [<target1> ...] |
SOURCE [<src1> ...] |
INSTALL [<file1> ...] |
TEST [<test1> ...] |
CACHE [<entry1> ...] >
[APPEND] [APPEND_STRING]
PROPERTY <name> [value1 [value2 ...]])
PROPERTY <name> [value1 ...])
Set one property on zero or more objects of a scope. The first
argument determines the scope in which the property is set. It must
be one of the following:
Sets one property on zero or more objects of a scope.
The first argument determines the scope in which the property is set.
It must be one of the following:
``GLOBAL``
Scope is unique and does not accept a name.
``DIRECTORY``
Scope defaults to the current directory but another
directory (already processed by CMake) may be named by full or
relative path.
Scope defaults to the current directory but another directory
(already processed by CMake) may be named by full or relative path.
See also the :command:`set_directory_properties` command.
``TARGET``
Scope may name zero or more existing targets.
See also the :command:`set_target_properties` command.
``SOURCE``
Scope may name zero or more source files. Note that source
file properties are visible only to targets added in the same
directory (CMakeLists.txt).
directory (``CMakeLists.txt``).
See also the :command:`set_source_files_properties` command.
``INSTALL``
Scope may name zero or more installed file paths.
@ -45,7 +48,7 @@ be one of the following:
Path components have to be separated by forward slashes,
must be normalized and are case sensitive.
To reference the installation prefix itself with a relative path use ".".
To reference the installation prefix itself with a relative path use ``.``.
Currently installed file properties are only defined for
the WIX generator where the given paths are relative
@ -53,6 +56,7 @@ be one of the following:
``TEST``
Scope may name zero or more existing tests.
See also the :command:`set_tests_properties` command.
``CACHE``
Scope must name zero or more cache existing entries.

12
Help/command/set_source_files_properties.rst
View File

@ -3,13 +3,17 @@ set_source_files_properties
Source files can have properties that affect how they are built.
::
.. code-block:: cmake
set_source_files_properties([file1 [file2 [...]]]
PROPERTIES prop1 value1
[prop2 value2 [...]])
Set properties associated with source files using a key/value paired
list. See :ref:`Source File Properties` for the list of properties known
Sets properties associated with source files using a key/value paired
list.
See also the :command:`set_property(SOURCE)` command.
See :ref:`Source File Properties` for the list of properties known
to CMake. Source file properties are visible only to targets added
in the same directory (CMakeLists.txt).
in the same directory (``CMakeLists.txt``).

4
Help/command/set_target_properties.rst
View File

@ -3,13 +3,13 @@ set_target_properties
Targets can have properties that affect how they are built.
::
.. code-block:: cmake
set_target_properties(target1 target2 ...
PROPERTIES prop1 value1
prop2 value2 ...)
Set properties on targets. The syntax for the command is to list all
Sets properties on targets. The syntax for the command is to list all
the targets you want to change, and then provide the values you want to
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`

11
Help/command/set_tests_properties.rst
View File

@ -3,12 +3,15 @@ set_tests_properties
Set a property of the tests.
::
.. code-block:: cmake
set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2)
Set a property for the tests. If the test is not found, CMake
Sets a property for the tests. If the test is not found, CMake
will report an error.
:manual:`Generator expressions <cmake-generator-expressions(7)>` will be
expanded the same as supported by the test's :command:`add_test` call. See
:ref:`Test Properties` for the list of properties known to CMake.
expanded the same as supported by the test's :command:`add_test` call.
See also the :command:`set_property(TEST)` command.
See :ref:`Test Properties` for the list of properties known to CMake.

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