New upstream version 3.24.0
This commit is contained in:
parent
9a372f80f7
commit
5a50c91527
@ -7,7 +7,6 @@ bugprone-*,\
|
||||
-bugprone-misplaced-widening-cast,\
|
||||
-bugprone-narrowing-conversions,\
|
||||
-bugprone-too-small-loop-variable,\
|
||||
google-readability-casting,\
|
||||
misc-*,\
|
||||
-misc-no-recursion,\
|
||||
-misc-non-private-member-variables-in-classes,\
|
||||
@ -24,6 +23,7 @@ readability-*,\
|
||||
-readability-convert-member-functions-to-static,\
|
||||
-readability-function-cognitive-complexity,\
|
||||
-readability-function-size,\
|
||||
-readability-identifier-length,\
|
||||
-readability-identifier-naming,\
|
||||
-readability-implicit-bool-conversion,\
|
||||
-readability-inconsistent-declaration-parameter-name,\
|
||||
|
@ -96,7 +96,15 @@ _cmake()
|
||||
_filedir
|
||||
return
|
||||
;;
|
||||
--build|--install|--open)
|
||||
--build)
|
||||
# Seed the reply with non-directory arguments that we know are
|
||||
# allowed to follow --build. _filedir will then prepend any valid
|
||||
# directory matches to these.
|
||||
COMPREPLY=( $( compgen -W "--preset --list-presets" -- "$cur" ) )
|
||||
_filedir -d
|
||||
return
|
||||
;;
|
||||
--install|--open)
|
||||
_filedir -d
|
||||
return
|
||||
;;
|
||||
@ -149,6 +157,34 @@ _cmake()
|
||||
2>/dev/null | grep -v "^cmake version " )' -- "$cur" ) )
|
||||
return
|
||||
;;
|
||||
--list-presets)
|
||||
local IFS=$'\n'
|
||||
local quoted
|
||||
printf -v quoted %q "$cur"
|
||||
|
||||
if [[ ! "${IFS}${COMP_WORDS[*]}${IFS}" =~ "${IFS}--build${IFS}" ]]; then
|
||||
COMPREPLY=( $( compgen -W "configure${IFS}build${IFS}test${IFS}all" -- "$quoted" ) )
|
||||
fi
|
||||
return
|
||||
;;
|
||||
--preset)
|
||||
local IFS=$'\n'
|
||||
local quoted
|
||||
printf -v quoted %q "$cur"
|
||||
|
||||
local build_or_configure="configure"
|
||||
if [[ "${IFS}${COMP_WORDS[*]}${IFS}" =~ "${IFS}--build${IFS}" ]]; then
|
||||
build_or_configure="build"
|
||||
fi
|
||||
|
||||
local presets=$( cmake --list-presets="$build_or_configure" 2>/dev/null |
|
||||
grep -o "^ \".*\"" | sed \
|
||||
-e "s/^ //g" \
|
||||
-e "s/\"//g" \
|
||||
-e 's/ /\\\\ /g' )
|
||||
COMPREPLY=( $( compgen -W "$presets" -- "$quoted" ) )
|
||||
return
|
||||
;;
|
||||
esac
|
||||
|
||||
$split && return
|
||||
|
@ -103,6 +103,17 @@ _ctest()
|
||||
2>/dev/null | grep -v "^ctest version " )' -- "$cur" ) )
|
||||
return
|
||||
;;
|
||||
--preset)
|
||||
local IFS=$'\n'
|
||||
local quoted
|
||||
printf -v quoted %q "$cur"
|
||||
COMPREPLY=( $( compgen -W '$( ctest --list-presets 2>/dev/null |
|
||||
grep -o "^ \".*\"" | sed \
|
||||
-e "s/^ //g" \
|
||||
-e "s/\"//g" \
|
||||
-e "s/ /\\\\ /g" )' -- "$quoted" ) )
|
||||
return
|
||||
;;
|
||||
esac
|
||||
|
||||
if [[ "$cur" == -* ]]; then
|
||||
|
@ -53,6 +53,9 @@ set the path with these commands:
|
||||
(defconst cmake-regex-comment "#.*")
|
||||
(defconst cmake-regex-paren-left "(")
|
||||
(defconst cmake-regex-paren-right ")")
|
||||
(defconst cmake-regex-closing-parens-line (concat "^[[:space:]]*\\("
|
||||
cmake-regex-paren-right
|
||||
"+\\)[[:space:]]*$"))
|
||||
(defconst cmake-regex-argument-quoted
|
||||
(rx ?\" (* (or (not (any ?\" ?\\)) (and ?\\ anything))) ?\"))
|
||||
(defconst cmake-regex-argument-unquoted
|
||||
@ -74,6 +77,8 @@ set the path with these commands:
|
||||
(defconst cmake-regex-close
|
||||
(rx-to-string `(and bol (* space) (regexp ,cmake-regex-block-close)
|
||||
(* space) (regexp ,cmake-regex-paren-left))))
|
||||
(defconst cmake-regex-token-paren-left (concat "^" cmake-regex-paren-left "$"))
|
||||
(defconst cmake-regex-token-paren-right (concat "^" cmake-regex-paren-right "$"))
|
||||
|
||||
;------------------------------------------------------------------------------
|
||||
|
||||
@ -130,30 +135,47 @@ set the path with these commands:
|
||||
(save-excursion
|
||||
(beginning-of-line)
|
||||
(let ((point-start (point))
|
||||
(closing-parens-only (looking-at cmake-regex-closing-parens-line))
|
||||
(case-fold-search t) ;; case-insensitive
|
||||
token)
|
||||
; Search back for the last indented line.
|
||||
;; Search back for the last indented line.
|
||||
(cmake-find-last-indented-line)
|
||||
; Start with the indentation on this line.
|
||||
;; Start with the indentation on this line.
|
||||
(setq cur-indent (current-indentation))
|
||||
; Search forward counting tokens that adjust indentation.
|
||||
(while (re-search-forward cmake-regex-token point-start t)
|
||||
(setq token (match-string 0))
|
||||
(when (or (string-match (concat "^" cmake-regex-paren-left "$") token)
|
||||
(and (string-match cmake-regex-block-open token)
|
||||
(looking-at (concat "[ \t]*" cmake-regex-paren-left))))
|
||||
(setq cur-indent (+ cur-indent cmake-tab-width)))
|
||||
(when (string-match (concat "^" cmake-regex-paren-right "$") token)
|
||||
(setq cur-indent (- cur-indent cmake-tab-width)))
|
||||
)
|
||||
(goto-char point-start)
|
||||
;; If next token closes the block, decrease indentation
|
||||
(when (looking-at cmake-regex-close)
|
||||
(setq cur-indent (- cur-indent cmake-tab-width))
|
||||
(if closing-parens-only
|
||||
(let ((open-parens 0))
|
||||
(while (re-search-forward cmake-regex-token point-start t)
|
||||
(setq token (match-string 0))
|
||||
(cond
|
||||
((string-match cmake-regex-token-paren-left token)
|
||||
(setq open-parens (+ open-parens 1)))
|
||||
((string-match cmake-regex-token-paren-right token)
|
||||
(setq open-parens (- open-parens 1)))))
|
||||
;; Don't outdent if last indented line has open parens
|
||||
(unless (> open-parens 0)
|
||||
(setq cur-indent (- cur-indent cmake-tab-width))))
|
||||
;; Skip detailed analysis if last indented line is a 'closing
|
||||
;; parens only line'
|
||||
(unless (looking-at cmake-regex-closing-parens-line)
|
||||
;; Search forward counting tokens that adjust indentation.
|
||||
(while (re-search-forward cmake-regex-token point-start t)
|
||||
(setq token (match-string 0))
|
||||
(when (or (string-match cmake-regex-token-paren-left token)
|
||||
(and (string-match cmake-regex-block-open token)
|
||||
(looking-at (concat "[ \t]*" cmake-regex-paren-left))))
|
||||
(setq cur-indent (+ cur-indent cmake-tab-width)))
|
||||
(when (string-match cmake-regex-token-paren-right token)
|
||||
(setq cur-indent (- cur-indent cmake-tab-width)))
|
||||
))
|
||||
(goto-char point-start)
|
||||
;; If next token closes the block, decrease indentation
|
||||
(when (looking-at cmake-regex-close)
|
||||
(setq cur-indent (- cur-indent cmake-tab-width))
|
||||
)
|
||||
)
|
||||
)
|
||||
)
|
||||
; Indent this line by the amount selected.
|
||||
;; Indent this line by the amount selected.
|
||||
(cmake-indent-line-to (max cur-indent 0))
|
||||
)
|
||||
)
|
||||
|
@ -3,7 +3,7 @@
|
||||
" Author: Andy Cedilnik <andy.cedilnik@kitware.com>
|
||||
" Maintainer: Dimitri Merejkowsky <d.merej@gmail.com>
|
||||
" Former Maintainer: Karthik Krishnan <karthik.krishnan@kitware.com>
|
||||
" Last Change: 2017 Aug 30
|
||||
" Last Change: 2022 Mar 22
|
||||
"
|
||||
" License: The CMake license applies to this file. See
|
||||
" https://cmake.org/licensing
|
||||
@ -14,9 +14,6 @@ if exists("b:did_indent")
|
||||
endif
|
||||
let b:did_indent = 1
|
||||
|
||||
let s:keepcpo= &cpo
|
||||
set cpo&vim
|
||||
|
||||
setlocal indentexpr=CMakeGetIndent(v:lnum)
|
||||
setlocal indentkeys+==ENDIF(,ENDFOREACH(,ENDMACRO(,ELSE(,ELSEIF(,ENDWHILE(
|
||||
|
||||
@ -24,6 +21,8 @@ setlocal indentkeys+==ENDIF(,ENDFOREACH(,ENDMACRO(,ELSE(,ELSEIF(,ENDWHILE(
|
||||
if exists("*CMakeGetIndent")
|
||||
finish
|
||||
endif
|
||||
let s:keepcpo= &cpo
|
||||
set cpo&vim
|
||||
|
||||
fun! CMakeGetIndent(lnum)
|
||||
let this_line = getline(a:lnum)
|
||||
@ -54,32 +53,41 @@ fun! CMakeGetIndent(lnum)
|
||||
let cmake_indent_open_regex = '^\s*' . cmake_regex_identifier .
|
||||
\ '\s*(' . cmake_regex_arguments .
|
||||
\ '\(' . cmake_regex_comment . '\)\?$'
|
||||
|
||||
let cmake_indent_close_regex = '^' . cmake_regex_arguments .
|
||||
\ ')\s*' .
|
||||
\ '\(' . cmake_regex_comment . '\)\?$'
|
||||
|
||||
let cmake_closing_parens_line = '^\s*\()\+\)\s*$'
|
||||
|
||||
let cmake_indent_begin_regex = '^\s*\(IF\|MACRO\|FOREACH\|ELSE\|ELSEIF\|WHILE\|FUNCTION\)\s*('
|
||||
let cmake_indent_end_regex = '^\s*\(ENDIF\|ENDFOREACH\|ENDMACRO\|ELSE\|ELSEIF\|ENDWHILE\|ENDFUNCTION\)\s*('
|
||||
|
||||
" Add
|
||||
if previous_line =~? cmake_indent_comment_line " Handle comments
|
||||
let ind = ind
|
||||
if this_line =~? cmake_closing_parens_line
|
||||
if previous_line !~? cmake_indent_open_regex
|
||||
let ind = ind - shiftwidth()
|
||||
endif
|
||||
else
|
||||
if previous_line =~? cmake_indent_begin_regex
|
||||
let ind = ind + shiftwidth()
|
||||
" Add
|
||||
if previous_line =~? cmake_indent_comment_line " Handle comments
|
||||
let ind = ind
|
||||
else
|
||||
if previous_line =~? cmake_indent_begin_regex
|
||||
let ind = ind + shiftwidth()
|
||||
endif
|
||||
if previous_line =~? cmake_indent_open_regex
|
||||
let ind = ind + shiftwidth()
|
||||
endif
|
||||
endif
|
||||
if previous_line =~? cmake_indent_open_regex
|
||||
let ind = ind + shiftwidth()
|
||||
endif
|
||||
endif
|
||||
|
||||
" Subtract
|
||||
if this_line =~? cmake_indent_end_regex
|
||||
let ind = ind - shiftwidth()
|
||||
endif
|
||||
if previous_line =~? cmake_indent_close_regex
|
||||
let ind = ind - shiftwidth()
|
||||
" Subtract
|
||||
if this_line =~? cmake_indent_end_regex
|
||||
let ind = ind - shiftwidth()
|
||||
endif
|
||||
if previous_line !~? cmake_closing_parens_line
|
||||
if previous_line =~? cmake_indent_close_regex
|
||||
let ind = ind - shiftwidth()
|
||||
endif
|
||||
endif
|
||||
endif
|
||||
|
||||
return ind
|
||||
|
@ -370,6 +370,7 @@ syn keyword cmakeProperty contained
|
||||
\ VS_DOTNET_DOCUMENTATION_FILE
|
||||
\ VS_DOTNET_REFERENCES
|
||||
\ VS_DOTNET_REFERENCES_COPY_LOCAL
|
||||
\ VS_DOTNET_STARTUP_OBJECT
|
||||
\ VS_DOTNET_TARGET_FRAMEWORK_VERSION
|
||||
\ VS_DPI_AWARE
|
||||
\ VS_GLOBAL_KEYWORD
|
||||
@ -381,6 +382,7 @@ syn keyword cmakeProperty contained
|
||||
\ VS_JUST_MY_CODE_DEBUGGING
|
||||
\ VS_KEYWORD
|
||||
\ VS_MOBILE_EXTENSIONS_VERSION
|
||||
\ VS_NO_COMPILE_BATCHING
|
||||
\ VS_NO_SOLUTION_DEPLOY
|
||||
\ VS_PACKAGE_REFERENCES
|
||||
\ VS_PLATFORM_TOOLSET
|
||||
@ -704,6 +706,7 @@ syn keyword cmakeVariable contained
|
||||
\ CMAKE_CODEBLOCKS_COMPILER_ID
|
||||
\ CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES
|
||||
\ CMAKE_CODELITE_USE_TARGETS
|
||||
\ CMAKE_COLOR_DIAGNOSTICS
|
||||
\ CMAKE_COLOR_MAKEFILE
|
||||
\ CMAKE_COMMAND
|
||||
\ CMAKE_COMPILER_2005
|
||||
@ -1044,6 +1047,7 @@ syn keyword cmakeVariable contained
|
||||
\ CMAKE_FIND_ROOT_PATH_MODE_PACKAGE
|
||||
\ CMAKE_FIND_ROOT_PATH_MODE_PROGRAM
|
||||
\ CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH
|
||||
\ CMAKE_FIND_USE_INSTALL_PREFIX
|
||||
\ CMAKE_FIND_USE_CMAKE_PATH
|
||||
\ CMAKE_FIND_USE_CMAKE_SYSTEM_PATH
|
||||
\ CMAKE_FIND_USE_PACKAGE_REGISTRY
|
||||
@ -1572,6 +1576,7 @@ syn keyword cmakeVariable contained
|
||||
\ CTEST_CUSTOM_MAXIMUM_NUMBER_OF_ERRORS
|
||||
\ CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS
|
||||
\ CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE
|
||||
\ CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION
|
||||
\ CTEST_CUSTOM_MEMCHECK_IGNORE
|
||||
\ CTEST_CUSTOM_POST_MEMCHECK
|
||||
\ CTEST_CUSTOM_POST_TEST
|
||||
@ -3776,6 +3781,7 @@ syn keyword cmakeGeneratorExpressions contained
|
||||
\ STREQUAL
|
||||
\ TARGET_BUNDLE_CONTENT_DIR
|
||||
\ TARGET_BUNDLE_DIR
|
||||
\ TARGET_BUNDLE_DIR_NAME
|
||||
\ TARGET_EXISTS
|
||||
\ TARGET_FILE
|
||||
\ TARGET_FILE_BASE_NAME
|
||||
|
@ -22,6 +22,7 @@ set(CPACK_PACKAGE_NAME "${CMAKE_PROJECT_NAME}")
|
||||
set(CPACK_PACKAGE_VERSION "${CMake_VERSION}")
|
||||
set(CPACK_PACKAGE_INSTALL_DIRECTORY "${CPACK_PACKAGE_NAME}")
|
||||
set(CPACK_SOURCE_PACKAGE_FILE_NAME "cmake-${CMake_VERSION}")
|
||||
set(CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE OFF)
|
||||
|
||||
# Installers for 32- vs. 64-bit CMake:
|
||||
# - Root install directory (displayed to end user at installer-run time)
|
||||
|
@ -198,14 +198,6 @@ if(CPACK_GENERATOR MATCHES "IFW")
|
||||
|
||||
endif()
|
||||
|
||||
if("${CPACK_GENERATOR}" STREQUAL "PackageMaker")
|
||||
if(CMAKE_PACKAGE_QTGUI)
|
||||
set(CPACK_PACKAGE_DEFAULT_LOCATION "/Applications")
|
||||
else()
|
||||
set(CPACK_PACKAGE_DEFAULT_LOCATION "/usr")
|
||||
endif()
|
||||
endif()
|
||||
|
||||
if("${CPACK_GENERATOR}" STREQUAL "DragNDrop")
|
||||
set(CPACK_DMG_BACKGROUND_IMAGE
|
||||
"@CMake_SOURCE_DIR@/Packaging/CMakeDMGBackground.tif")
|
||||
@ -256,6 +248,13 @@ if("${CPACK_GENERATOR}" STREQUAL "WIX")
|
||||
|
||||
set(CPACK_WIX_LIGHT_EXTRA_FLAGS "-dcl:high")
|
||||
|
||||
if(NOT "$ENV{CMAKE_CI_PACKAGE}" STREQUAL "")
|
||||
# Suppress validation. It does not work without
|
||||
# an interactive session or an admin account.
|
||||
# https://github.com/wixtoolset/issues/issues/3968
|
||||
list(APPEND CPACK_WIX_LIGHT_EXTRA_FLAGS "-sval")
|
||||
endif()
|
||||
|
||||
set(CPACK_WIX_UI_BANNER
|
||||
"@CMake_SOURCE_DIR@/Utilities/Release/WiX/ui_banner.jpg"
|
||||
)
|
||||
|
@ -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...3.21 FATAL_ERROR)
|
||||
cmake_minimum_required(VERSION 3.13...3.22 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)
|
||||
|
||||
@ -606,25 +606,40 @@ macro (CMAKE_BUILD_UTILITIES)
|
||||
set(ZLIB_INCLUDE_DIR ${CMAKE_ZLIB_INCLUDES})
|
||||
set(ZLIB_LIBRARY ${CMAKE_ZLIB_LIBRARIES})
|
||||
add_definitions(-DLIBARCHIVE_STATIC)
|
||||
set(ENABLE_MBEDTLS OFF CACHE INTERNAL "Enable use of mbed TLS")
|
||||
set(ENABLE_NETTLE OFF CACHE INTERNAL "Enable use of Nettle")
|
||||
set(ENABLE_OPENSSL ${CMAKE_USE_OPENSSL} CACHE INTERNAL "Enable use of OpenSSL")
|
||||
set(ENABLE_LIBB2 OFF CACHE INTERNAL "Enable the use of the system LIBB2 library if found")
|
||||
set(ENABLE_LZMA ON CACHE INTERNAL "Enable the use of the system LZMA library if found")
|
||||
set(ENABLE_LZ4 OFF CACHE INTERNAL "Enable the use of the system LZ4 library if found")
|
||||
set(ENABLE_LZO OFF CACHE INTERNAL "Enable the use of the system LZO library if found")
|
||||
set(ENABLE_ZLIB ON CACHE INTERNAL "Enable the use of the system ZLIB library if found")
|
||||
set(ENABLE_BZip2 ON CACHE INTERNAL "Enable the use of the system BZip2 library if found")
|
||||
set(ENABLE_ZSTD ON CACHE INTERNAL "Enable the use of the system zstd library if found")
|
||||
set(ENABLE_LIBXML2 OFF CACHE INTERNAL "Enable the use of the system libxml2 library if found")
|
||||
set(ENABLE_EXPAT OFF CACHE INTERNAL "Enable the use of the system EXPAT library if found")
|
||||
set(ENABLE_PCREPOSIX OFF CACHE INTERNAL "Enable the use of the system PCREPOSIX library if found")
|
||||
set(ENABLE_LibGCC OFF CACHE INTERNAL "Enable the use of the system LibGCC library if found")
|
||||
set(ENABLE_XATTR OFF CACHE INTERNAL "Enable extended attribute support")
|
||||
set(ENABLE_ACL OFF CACHE INTERNAL "Enable ACL support")
|
||||
set(ENABLE_ICONV OFF CACHE INTERNAL "Enable iconv support")
|
||||
set(ENABLE_CNG OFF CACHE INTERNAL "Enable the use of CNG(Crypto Next Generation)")
|
||||
SET(POSIX_REGEX_LIB "" CACHE INTERNAL "Choose what library should provide POSIX regular expression support")
|
||||
set(ENABLE_MBEDTLS OFF)
|
||||
set(ENABLE_NETTLE OFF)
|
||||
if(DEFINED CMAKE_USE_OPENSSL)
|
||||
set(ENABLE_OPENSSL "${CMAKE_USE_OPENSSL}")
|
||||
else()
|
||||
set(ENABLE_OPENSSL OFF)
|
||||
endif()
|
||||
set(ENABLE_LIBB2 OFF)
|
||||
set(ENABLE_LZ4 OFF)
|
||||
set(ENABLE_LZO OFF)
|
||||
set(ENABLE_LZMA ON)
|
||||
set(ENABLE_ZSTD ON)
|
||||
set(ENABLE_ZLIB ON)
|
||||
set(ENABLE_BZip2 ON)
|
||||
set(ENABLE_LIBXML2 OFF)
|
||||
set(ENABLE_EXPAT OFF)
|
||||
set(ENABLE_PCREPOSIX OFF)
|
||||
set(ENABLE_LibGCC OFF)
|
||||
set(ENABLE_CNG OFF)
|
||||
set(ENABLE_TAR OFF)
|
||||
set(ENABLE_TAR_SHARED OFF)
|
||||
set(ENABLE_CPIO OFF)
|
||||
set(ENABLE_CPIO_SHARED OFF)
|
||||
set(ENABLE_CAT OFF)
|
||||
set(ENABLE_CAT_SHARED OFF)
|
||||
set(ENABLE_XATTR OFF)
|
||||
set(ENABLE_ACL OFF)
|
||||
set(ENABLE_ICONV OFF)
|
||||
set(ENABLE_TEST OFF)
|
||||
set(ENABLE_COVERAGE OFF)
|
||||
set(ENABLE_INSTALL OFF)
|
||||
set(POSIX_REGEX_LIB "" CACHE INTERNAL "libarchive: No POSIX regular expression support")
|
||||
set(ENABLE_SAFESEH "" CACHE INTERNAL "libarchive: No /SAFESEH linker flag")
|
||||
set(WINDOWS_VERSION "WIN7" CACHE INTERNAL "libarchive: Set Windows version to use (Windows only)")
|
||||
add_subdirectory(Utilities/cmlibarchive)
|
||||
CMAKE_SET_TARGET_FOLDER(cmlibarchive "Utilities/3rdParty")
|
||||
set(CMAKE_TAR_LIBRARIES cmlibarchive ${BZIP2_LIBRARIES})
|
||||
|
@ -98,6 +98,7 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
|
||||
"nghttp2/lib/.*:[0-9]+:[0-9]+: warning: Value stored to '[^']+' is never read"
|
||||
"zstd/lib/.*:[0-9]+:[0-9]+: warning: Assigned value is garbage or undefined"
|
||||
"zstd/lib/.*:[0-9]+:[0-9]+: warning: Dereference of null pointer"
|
||||
"zstd/lib/.*:[0-9]+:[0-9]+: warning: The right operand of .* is a garbage value due to array index out of bounds"
|
||||
)
|
||||
|
||||
if(NOT "@CMAKE_GENERATOR@" MATCHES "Xcode")
|
||||
|
@ -78,6 +78,7 @@ The following individuals and institutions are among the Contributors:
|
||||
* Michael Hirsch, Ph.D. <www.scivision.co>
|
||||
* Michael Stürmer
|
||||
* Miguel A. Figueroa-Villanueva
|
||||
* Mike Durso <rbprogrammer@gmail.com>
|
||||
* Mike Jackson
|
||||
* Mike McQuaid <mike@mikemcquaid.com>
|
||||
* Nicolas Bock <nicolasbock@gmail.com>
|
||||
|
@ -13,6 +13,7 @@ The general signature is:
|
||||
name | |NAMES|
|
||||
[HINTS [path | ENV var]... ]
|
||||
[PATHS [path | ENV var]... ]
|
||||
[REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
|
||||
[PATH_SUFFIXES suffix1 [suffix2 ...]]
|
||||
[DOC "cache documentation string"]
|
||||
[NO_CACHE]
|
||||
@ -23,6 +24,7 @@ The general signature is:
|
||||
[NO_CMAKE_ENVIRONMENT_PATH]
|
||||
[NO_SYSTEM_ENVIRONMENT_PATH]
|
||||
[NO_CMAKE_SYSTEM_PATH]
|
||||
[NO_CMAKE_INSTALL_PREFIX]
|
||||
[CMAKE_FIND_ROOT_PATH_BOTH |
|
||||
ONLY_CMAKE_FIND_ROOT_PATH |
|
||||
NO_CMAKE_FIND_ROOT_PATH]
|
||||
@ -50,6 +52,16 @@ Options include:
|
||||
The ``ENV var`` sub-option reads paths from a system environment
|
||||
variable.
|
||||
|
||||
.. versionchanged:: 3.24
|
||||
On ``Windows`` platform, it is possible to include registry queries as part
|
||||
of the directories, using a :ref:`dedicated syntax <Find Using Windows Registry>`.
|
||||
Such specifications will be ignored on all other platforms.
|
||||
|
||||
``REGISTRY_VIEW``
|
||||
.. versionadded:: 3.24
|
||||
|
||||
.. include:: FIND_XXX_REGISTRY_VIEW.txt
|
||||
|
||||
``PATH_SUFFIXES``
|
||||
Specify additional subdirectories to check below each directory
|
||||
location otherwise considered.
|
||||
@ -154,9 +166,11 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
|
||||
* |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX|
|
||||
|
||||
6. Search cmake variables defined in the Platform files
|
||||
for the current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH``
|
||||
is passed or by setting the :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`
|
||||
to ``FALSE``.
|
||||
for the current system. The searching of ``CMAKE_INSTALL_PREFIX`` can be
|
||||
skipped if ``NO_CMAKE_INSTALL_PREFIX`` is passed or by setting the
|
||||
:variable:`CMAKE_FIND_USE_INSTALL_PREFIX` to ``FALSE``. All these locations
|
||||
can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is passed or by setting the
|
||||
:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` to ``FALSE``.
|
||||
|
||||
* |CMAKE_SYSTEM_PREFIX_PATH_XXX|
|
||||
* |CMAKE_SYSTEM_XXX_PATH|
|
||||
|
41
Help/command/FIND_XXX_REGISTRY_VIEW.txt
Normal file
41
Help/command/FIND_XXX_REGISTRY_VIEW.txt
Normal file
@ -0,0 +1,41 @@
|
||||
Specify which registry views must be queried. This option is only meaningful
|
||||
on ``Windows`` platform and will be ignored on other ones. When not
|
||||
specified, |FIND_XXX_REGISTRY_VIEW_DEFAULT| view is used when :policy:`CMP0134`
|
||||
policy is ``NEW``. Refer to :policy:`CMP0134` policy for default view when
|
||||
policy is ``OLD`` or undefined.
|
||||
|
||||
``64``
|
||||
Query the 64bit registry. On ``32bit Windows``, returns always the string
|
||||
``/REGISTRY-NOTFOUND``.
|
||||
|
||||
``32``
|
||||
Query the 32bit registry.
|
||||
|
||||
``64_32``
|
||||
Query both views (``64`` and ``32``) and generate a path for each.
|
||||
|
||||
``32_64``
|
||||
Query both views (``32`` and ``64``) and generate a path for each.
|
||||
|
||||
``HOST``
|
||||
Query the registry matching the architecture of the host: ``64`` on ``64bit
|
||||
Windows`` and ``32`` on ``32bit Windows``.
|
||||
|
||||
``TARGET``
|
||||
Query the registry matching the architecture specified by
|
||||
:variable:`CMAKE_SIZEOF_VOID_P` variable. If not defined, fallback to
|
||||
``HOST`` view.
|
||||
|
||||
``BOTH``
|
||||
Query both views (``32`` and ``64``). The order depends of the following
|
||||
rules: If :variable:`CMAKE_SIZEOF_VOID_P` variable is defined. Use the
|
||||
following view depending of the content of this variable:
|
||||
|
||||
* ``8``: ``64_32``
|
||||
* ``4``: ``32_64``
|
||||
|
||||
If :variable:`CMAKE_SIZEOF_VOID_P` variable is not defined, rely on
|
||||
architecture of the host:
|
||||
|
||||
* ``64bit``: ``64_32``
|
||||
* ``32bit``: ``32``
|
@ -288,12 +288,12 @@ The options are:
|
||||
|
||||
.. productionlist:: depfile
|
||||
depfile: `rule`*
|
||||
rule: `targets` (`:` (`separator` `dependencies`?)?)? `eol`
|
||||
rule: `targets` (':' (`separator` `dependencies`?)?)? `eol`
|
||||
targets: `target` (`separator` `target`)* `separator`*
|
||||
target: `pathname`
|
||||
dependencies: `dependency` (`separator` `dependency`)* `separator`*
|
||||
dependency: `pathname`
|
||||
separator: (space | line_continue)+
|
||||
separator: (`space` | `line_continue`)+
|
||||
line_continue: '\' `eol`
|
||||
space: ' ' | '\t'
|
||||
pathname: `character`+
|
||||
@ -425,6 +425,11 @@ of the following is specified:
|
||||
``POST_BUILD``
|
||||
Run after all other rules within the target have been executed.
|
||||
|
||||
Projects should always specify one of the above three keywords when using
|
||||
the ``TARGET`` form. For backward compatibility reasons, ``POST_BUILD`` is
|
||||
assumed if no such keyword is given, but projects should explicitly provide
|
||||
one of the keywords to make clear the behavior they expect.
|
||||
|
||||
.. note::
|
||||
Because generator expressions can be used in custom commands,
|
||||
it is possible to define ``COMMAND`` lines or whole custom commands
|
||||
|
@ -1,9 +1,23 @@
|
||||
cmake_host_system_information
|
||||
-----------------------------
|
||||
|
||||
Query host system specific information.
|
||||
Query various host system information.
|
||||
|
||||
.. code-block:: cmake
|
||||
Synopsis
|
||||
^^^^^^^^
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
`Query host system specific information`_
|
||||
cmake_host_system_information(RESULT <variable> QUERY <key> ...)
|
||||
|
||||
`Query Windows registry`_
|
||||
cmake_host_system_information(RESULT <variable> QUERY WINDOWS_REGISTRY <key> ...)
|
||||
|
||||
Query host system specific information
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
cmake_host_system_information(RESULT <variable> QUERY <key> ...)
|
||||
|
||||
@ -180,7 +194,7 @@ distribution-specific files`_ to collect OS identification data and map it
|
||||
into `man 5 os-release`_ variables.
|
||||
|
||||
Fallback Interface Variables
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
""""""""""""""""""""""""""""
|
||||
|
||||
.. variable:: CMAKE_GET_OS_RELEASE_FALLBACK_SCRIPTS
|
||||
|
||||
@ -246,3 +260,137 @@ Example:
|
||||
|
||||
.. _man 5 os-release: https://www.freedesktop.org/software/systemd/man/os-release.html
|
||||
.. _various distribution-specific files: http://linuxmafia.com/faq/Admin/release-files.html
|
||||
|
||||
.. _Query Windows registry:
|
||||
|
||||
Query Windows registry
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. versionadded:: 3.24
|
||||
|
||||
::
|
||||
|
||||
cmake_host_system_information(RESULT <variable>
|
||||
QUERY WINDOWS_REGISTRY <key> [VALUE_NAMES|SUBKEYS|VALUE <name>]
|
||||
[VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
|
||||
[SEPARATOR <separator>]
|
||||
[ERROR_VARIABLE <result>])
|
||||
|
||||
Performs query operations on local computer registry subkey. Returns a list of
|
||||
subkeys or value names that are located under the specified subkey in the
|
||||
registry or the data of the specified value name. The result of the queried
|
||||
entity is stored in ``<variable>``.
|
||||
|
||||
.. note::
|
||||
|
||||
Querying registry for any other platforms than ``Windows``, including
|
||||
``CYGWIN``, will always returns an empty string and sets an error message in
|
||||
the variable specified with sub-option ``ERROR_VARIABLE``.
|
||||
|
||||
``<key>`` specify the full path of a subkey on the local computer. The
|
||||
``<key>`` must include a valid root key. Valid root keys for the local computer
|
||||
are:
|
||||
|
||||
* ``HKLM`` or ``HKEY_LOCAL_MACHINE``
|
||||
* ``HKCU`` or ``HKEY_CURRENT_USER``
|
||||
* ``HKCR`` or ``HKEY_CLASSES_ROOT``
|
||||
* ``HKU`` or ``HKEY_USERS``
|
||||
* ``HKCC`` or ``HKEY_CURRENT_CONFIG``
|
||||
|
||||
And, optionally, the path to a subkey under the specified root key. The path
|
||||
separator can be the slash or the backslash. ``<key>`` is not case sensitive.
|
||||
For example:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY "HKLM")
|
||||
cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Kitware")
|
||||
cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY "HKCU\\SOFTWARE\\Kitware")
|
||||
|
||||
``VALUE_NAMES``
|
||||
Request the list of value names defined under ``<key>``. If a default value
|
||||
is defined, it will be identified with the special name ``(default)``.
|
||||
|
||||
``SUBKEYS``
|
||||
Request the list of subkeys defined under ``<key>``.
|
||||
|
||||
``VALUE <name>``
|
||||
Request the data stored in value named ``<name>``. If ``VALUE`` is not
|
||||
specified or argument is the special name ``(default)``, the content of the
|
||||
default value, if any, will be returned.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
# query default value for HKLM/SOFTWARE/Kitware key
|
||||
cmake_host_system_information(RESULT result
|
||||
QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Kitware")
|
||||
|
||||
# query default value for HKLM/SOFTWARE/Kitware key using special value name
|
||||
cmake_host_system_information(RESULT result
|
||||
QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Kitware"
|
||||
VALUE "(default)")
|
||||
|
||||
Supported types are:
|
||||
|
||||
* ``REG_SZ``.
|
||||
* ``REG_EXPAND_SZ``. The returned data is expanded.
|
||||
* ``REG_MULTI_SZ``. The returned is expressed as a CMake list. See also
|
||||
``SEPARATOR`` sub-option.
|
||||
* ``REG_DWORD``.
|
||||
* ``REG_QWORD``.
|
||||
|
||||
For all other types, an empty string is returned.
|
||||
|
||||
``VIEW``
|
||||
Specify which registry views must be queried. When not specified, ``BOTH``
|
||||
view is used.
|
||||
|
||||
``64``
|
||||
Query the 64bit registry. On ``32bit Windows``, returns always an empty
|
||||
string.
|
||||
|
||||
``32``
|
||||
Query the 32bit registry.
|
||||
|
||||
``64_32``
|
||||
For ``VALUE`` sub-option or default value, query the registry using view
|
||||
``64``, and if the request failed, query the registry using view ``32``.
|
||||
For ``VALUE_NAMES`` and ``SUBKEYS`` sub-options, query both views (``64``
|
||||
and ``32``) and merge the results (sorted and duplicates removed).
|
||||
|
||||
``32_64``
|
||||
For ``VALUE`` sub-option or default value, query the registry using view
|
||||
``32``, and if the request failed, query the registry using view ``64``.
|
||||
For ``VALUE_NAMES`` and ``SUBKEYS`` sub-options, query both views (``32``
|
||||
and ``64``) and merge the results (sorted and duplicates removed).
|
||||
|
||||
``HOST``
|
||||
Query the registry matching the architecture of the host: ``64`` on ``64bit
|
||||
Windows`` and ``32`` on ``32bit Windows``.
|
||||
|
||||
``TARGET``
|
||||
Query the registry matching the architecture specified by
|
||||
:variable:`CMAKE_SIZEOF_VOID_P` variable. If not defined, fallback to
|
||||
``HOST`` view.
|
||||
|
||||
``BOTH``
|
||||
Query both views (``32`` and ``64``). The order depends of the following
|
||||
rules: If :variable:`CMAKE_SIZEOF_VOID_P` variable is defined. Use the
|
||||
following view depending of the content of this variable:
|
||||
|
||||
* ``8``: ``64_32``
|
||||
* ``4``: ``32_64``
|
||||
|
||||
If :variable:`CMAKE_SIZEOF_VOID_P` variable is not defined, rely on
|
||||
architecture of the host:
|
||||
|
||||
* ``64bit``: ``64_32``
|
||||
* ``32bit``: ``32``
|
||||
|
||||
``SEPARATOR``
|
||||
Specify the separator character for ``REG_MULTI_SZ`` type. When not
|
||||
specified, the character ``\0`` is used.
|
||||
|
||||
``ERROR_VARIABLE <result>``
|
||||
Returns any error raised during query operation. In case of success, the
|
||||
variable holds an empty string.
|
||||
|
@ -13,6 +13,7 @@ Synopsis
|
||||
cmake_language(`CALL`_ <command> [<arg>...])
|
||||
cmake_language(`EVAL`_ CODE <code>...)
|
||||
cmake_language(`DEFER`_ <options>... CALL <command> [<arg>...])
|
||||
cmake_language(`SET_DEPENDENCY_PROVIDER`_ <command> SUPPORTED_METHODS <methods>...)
|
||||
|
||||
Introduction
|
||||
^^^^^^^^^^^^
|
||||
@ -225,3 +226,268 @@ also prints::
|
||||
Immediate Message
|
||||
Deferred Message 1
|
||||
Deferred Message 2
|
||||
|
||||
|
||||
.. _SET_DEPENDENCY_PROVIDER:
|
||||
.. _dependency_providers:
|
||||
|
||||
Dependency Providers
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. versionadded:: 3.24
|
||||
|
||||
.. note:: A high-level introduction to this feature can be found in the
|
||||
:ref:`Using Dependencies Guide <dependency_providers_overview>`.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
cmake_language(SET_DEPENDENCY_PROVIDER <command>
|
||||
SUPPORTED_METHODS <methods>...)
|
||||
|
||||
When a call is made to :command:`find_package` or
|
||||
:command:`FetchContent_MakeAvailable`, the call may be forwarded to a
|
||||
dependency provider which then has the opportunity to fulfill the request.
|
||||
If the request is for one of the ``<methods>`` specified when the provider
|
||||
was set, CMake calls the provider's ``<command>`` with a set of
|
||||
method-specific arguments. If the provider does not fulfill the request,
|
||||
or if the provider doesn't support the request's method, or no provider
|
||||
is set, the built-in :command:`find_package` or
|
||||
:command:`FetchContent_MakeAvailable` implementation is used to fulfill
|
||||
the request in the usual way.
|
||||
|
||||
One or more of the following values can be specified for the ``<methods>``
|
||||
when setting the provider:
|
||||
|
||||
``FIND_PACKAGE``
|
||||
The provider command accepts :command:`find_package` requests.
|
||||
|
||||
``FETCHCONTENT_MAKEAVAILABLE_SERIAL``
|
||||
The provider command accepts :command:`FetchContent_MakeAvailable`
|
||||
requests. It expects each dependency to be fed to the provider command
|
||||
one at a time, not the whole list in one go.
|
||||
|
||||
Only one provider can be set at any point in time. If a provider is already
|
||||
set when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called, the new
|
||||
provider replaces the previously set one. The specified ``<command>`` must
|
||||
already exist when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called.
|
||||
As a special case, providing an empty string for the ``<command>`` and no
|
||||
``<methods>`` will discard any previously set provider.
|
||||
|
||||
The dependency provider can only be set while processing one of the files
|
||||
specified by the :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable.
|
||||
Thus, dependency providers can only be set as part of the first call to
|
||||
:command:`project`. Calling ``cmake_language(SET_DEPENDENCY_PROVIDER)``
|
||||
outside of that context will result in an error.
|
||||
|
||||
.. note::
|
||||
The choice of dependency provider should always be under the user's control.
|
||||
As a convenience, a project may choose to provide a file that users can
|
||||
list in their :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable, but
|
||||
the use of such a file should always be the user's choice.
|
||||
|
||||
Provider commands
|
||||
"""""""""""""""""
|
||||
|
||||
Providers define a single ``<command>`` to accept requests. The name of
|
||||
the command should be specific to that provider, not something overly
|
||||
generic that another provider might also use. This enables users to compose
|
||||
different providers in their own custom provider. The recommended form is
|
||||
``xxx_provide_dependency()``, where ``xxx`` is the provider-specific part
|
||||
(e.g. ``vcpkg_provide_dependency()``, ``conan_provide_dependency()``,
|
||||
``ourcompany_provide_dependency()``, and so on).
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
xxx_provide_dependency(<method> [<method-specific-args>...])
|
||||
|
||||
Because some methods expect certain variables to be set in the calling scope,
|
||||
the provider command should typically be implemented as a macro rather than a
|
||||
function. This ensures it does not introduce a new variable scope.
|
||||
|
||||
The arguments CMake passes to the dependency provider depend on the type of
|
||||
request. The first argument is always the method, and it will only ever
|
||||
be one of the ``<methods>`` that was specified when setting the provider.
|
||||
|
||||
``FIND_PACKAGE``
|
||||
The ``<method-specific-args>`` will be everything passed to the
|
||||
:command:`find_package` call that requested the dependency. The first of
|
||||
these ``<method-specific-args>`` will therefore always be the name of the
|
||||
dependency. Dependency names are case-sensitive for this method because
|
||||
:command:`find_package` treats them case-sensitively too.
|
||||
|
||||
If the provider command fulfills the request, it must set the same variable
|
||||
that :command:`find_package` expects to be set. For a dependency named
|
||||
``depName``, the provider must set ``depName_FOUND`` to true if it fulfilled
|
||||
the request. If the provider returns without setting this variable, CMake
|
||||
will assume the request was not fulfilled and will fall back to the
|
||||
built-in implementation.
|
||||
|
||||
If the provider needs to call the built-in :command:`find_package`
|
||||
implementation as part of its processing, it can do so by including the
|
||||
``BYPASS_PROVIDER`` keyword as one of the arguments.
|
||||
|
||||
``FETCHCONTENT_MAKEAVAILABE_SERIAL``
|
||||
The ``<method-specific-args>`` will be everything passed to the
|
||||
:command:`FetchContent_Declare` call that corresponds to the requested
|
||||
dependency, with the following exceptions:
|
||||
|
||||
* If ``SOURCE_DIR`` or ``BINARY_DIR`` were not part of the original
|
||||
declared arguments, they will be added with their default values.
|
||||
* If :variable:`FETCHCONTENT_TRY_FIND_PACKAGE_MODE` is set to ``NEVER``,
|
||||
any ``FIND_PACKAGE_ARGS`` will be omitted.
|
||||
* The ``OVERRIDE_FIND_PACKAGE`` keyword is always omitted.
|
||||
|
||||
The first of the ``<method-specific-args>`` will always be the name of the
|
||||
dependency. Dependency names are case-insensitive for this method because
|
||||
:module:`FetchContent` also treats them case-insensitively.
|
||||
|
||||
If the provider fulfills the request, it should call
|
||||
:command:`FetchContent_SetPopulated`, passing the name of the dependency as
|
||||
the first argument. The ``SOURCE_DIR`` and ``BINARY_DIR`` arguments to that
|
||||
command should only be given if the provider makes the dependency's source
|
||||
and build directories available in exactly the same way as the built-in
|
||||
:command:`FetchContent_MakeAvailable` command.
|
||||
|
||||
If the provider returns without calling :command:`FetchContent_SetPopulated`
|
||||
for the named dependency, CMake will assume the request was not fulfilled
|
||||
and will fall back to the built-in implementation.
|
||||
|
||||
Note that empty arguments may be significant for this method (e.g. an empty
|
||||
string following a ``GIT_SUBMODULES`` keyword). Therefore, if forwarding
|
||||
these arguments on to another command, extra care must be taken to avoid such
|
||||
arguments being silently dropped.
|
||||
|
||||
If ``FETCHCONTENT_SOURCE_DIR_<uppercaseDepName>`` is set, then the
|
||||
dependency provider will never see requests for the ``<depName>`` dependency
|
||||
for this method. When the user sets such a variable, they are explicitly
|
||||
overriding where to get that dependency from and are taking on the
|
||||
responsibility that their overriding version meets any requirements for that
|
||||
dependency and is compatible with whatever else in the project uses it.
|
||||
Depending on the value of :variable:`FETCHCONTENT_TRY_FIND_PACKAGE_MODE`
|
||||
and whether the ``OVERRIDE_FIND_PACKAGE`` option was given to
|
||||
:command:`FetchContent_Declare`, having
|
||||
``FETCHCONTENT_SOURCE_DIR_<uppercaseDepName>`` set may also prevent the
|
||||
dependency provider from seeing requests for a ``find_package(depName)``
|
||||
call too.
|
||||
|
||||
Provider Examples
|
||||
"""""""""""""""""
|
||||
|
||||
This first example only intercepts :command:`find_package` calls. The
|
||||
provider command runs an external tool which copies the relevant artifacts
|
||||
into a provider-specific directory, if that tool knows about the dependency.
|
||||
It then relies on the built-in implementation to then find those artifacts.
|
||||
:command:`FetchContent_MakeAvailable` calls would not go through the provider.
|
||||
|
||||
.. code-block:: cmake
|
||||
:caption: mycomp_provider.cmake
|
||||
|
||||
# Always ensure we have the policy settings this provider expects
|
||||
cmake_minimum_required(VERSION 3.24)
|
||||
|
||||
set(MYCOMP_PROVIDER_INSTALL_DIR ${CMAKE_BINARY_DIR}/mycomp_packages
|
||||
CACHE PATH "The directory this provider installs packages to"
|
||||
)
|
||||
# Tell the built-in implementation to look in our area first, unless
|
||||
# the find_package() call uses NO_..._PATH options to exclude it
|
||||
list(APPEND CMAKE_MODULE_PATH ${MYCOMP_PROVIDER_INSTALL_DIR}/cmake)
|
||||
list(APPEND CMAKE_PREFIX_PATH ${MYCOMP_PROVIDER_INSTALL_DIR})
|
||||
|
||||
macro(mycomp_provide_dependency method package_name)
|
||||
execute_process(
|
||||
COMMAND some_tool ${package_name} --installdir ${MYCOMP_PROVIDER_INSTALL_DIR}
|
||||
COMMAND_ERROR_IS_FATAL ANY
|
||||
)
|
||||
endmacro()
|
||||
|
||||
cmake_language(
|
||||
SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
|
||||
SUPPORTED_METHODS FIND_PACKAGE
|
||||
)
|
||||
|
||||
The user would then typically use the above file like so::
|
||||
|
||||
cmake -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=/path/to/mycomp_provider.cmake ...
|
||||
|
||||
The next example demonstrates a provider that accepts both methods, but
|
||||
only handles one specific dependency. It enforces providing Google Test
|
||||
using :module:`FetchContent`, but leaves all other dependencies to be
|
||||
fulfilled by CMake's built-in implementation. It accepts a few different
|
||||
names, which demonstrates one way of working around projects that hard-code
|
||||
an unusual or undesirable way of adding this particular dependency to the
|
||||
build. The example also demonstrates how to use the :command:`list` command
|
||||
to preserve variables that may be overwritten by a call to
|
||||
:command:`FetchContent_MakeAvailable`.
|
||||
|
||||
.. code-block:: cmake
|
||||
:caption: mycomp_provider.cmake
|
||||
|
||||
cmake_minimum_required(VERSION 3.24)
|
||||
|
||||
# Because we declare this very early, it will take precedence over any
|
||||
# details the project might declare later for the same thing
|
||||
include(FetchContent)
|
||||
FetchContent_Declare(
|
||||
googletest
|
||||
GIT_REPOSITORY https://github.com/google/googletest.git
|
||||
GIT_TAG e2239ee6043f73722e7aa812a459f54a28552929 # release-1.11.0
|
||||
)
|
||||
|
||||
# Both FIND_PACKAGE and FETCHCONTENT_MAKEAVAILABLE_SERIAL methods provide
|
||||
# the package or dependency name as the first method-specific argument.
|
||||
macro(mycomp_provide_dependency method dep_name)
|
||||
if("${dep_name}" MATCHES "^(gtest|googletest)$")
|
||||
# Save our current command arguments in case we are called recursively
|
||||
list(APPEND mycomp_provider_args ${method} ${dep_name})
|
||||
|
||||
# This will forward to the built-in FetchContent implementation,
|
||||
# which detects a recursive call for the same thing and avoids calling
|
||||
# the provider again if dep_name is the same as the current call.
|
||||
FetchContent_MakeAvailable(googletest)
|
||||
|
||||
# Restore our command arguments
|
||||
list(POP_BACK mycomp_provider_args dep_name method)
|
||||
|
||||
# Tell the caller we fulfilled the request
|
||||
if("${method}" STREQUAL "FIND_PACKAGE")
|
||||
# We need to set this if we got here from a find_package() call
|
||||
# since we used a different method to fulfill the request.
|
||||
# This example assumes projects only use the gtest targets,
|
||||
# not any of the variables the FindGTest module may define.
|
||||
set(${dep_name}_FOUND TRUE)
|
||||
elseif(NOT "${dep_name}" STREQUAL "googletest")
|
||||
# We used the same method, but were given a different name to the
|
||||
# one we populated with. Tell the caller about the name it used.
|
||||
FetchContent_SetPopulated(${dep_name}
|
||||
SOURCE_DIR "${googletest_SOURCE_DIR}"
|
||||
BINARY_DIR "${googletest_BINARY_DIR}"
|
||||
)
|
||||
endif()
|
||||
endif()
|
||||
endmacro()
|
||||
|
||||
cmake_language(
|
||||
SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
|
||||
SUPPORTED_METHODS
|
||||
FIND_PACKAGE
|
||||
FETCHCONTENT_MAKEAVAILABLE_SERIAL
|
||||
)
|
||||
|
||||
The final example demonstrates how to modify arguments to a
|
||||
:command:`find_package` call. It forces all such calls to have the
|
||||
``QUIET`` keyword. It uses the ``BYPASS_PROVIDER`` keyword to prevent
|
||||
calling the provider command recursively for the same dependency.
|
||||
|
||||
.. code-block:: cmake
|
||||
:caption: mycomp_provider.cmake
|
||||
|
||||
cmake_minimum_required(VERSION 3.24)
|
||||
|
||||
macro(mycomp_provide_dependency method)
|
||||
find_package(${ARGN} BYPASS_PROVIDER QUIET)
|
||||
endmacro()
|
||||
|
||||
cmake_language(
|
||||
SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
|
||||
SUPPORTED_METHODS FIND_PACKAGE
|
||||
)
|
||||
|
@ -96,6 +96,8 @@ The following conventions are used in this command's documentation:
|
||||
The name of a variable into which the result of a command will be written.
|
||||
|
||||
|
||||
.. _Path Structure And Terminology:
|
||||
|
||||
Path Structure And Terminology
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@ -216,6 +218,8 @@ normalize a path is as follows:
|
||||
is ``.``).
|
||||
|
||||
|
||||
.. _Path Decomposition:
|
||||
|
||||
Decomposition
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
@ -385,6 +389,8 @@ Path traversal examples
|
||||
Parent path is "c:/"
|
||||
|
||||
|
||||
.. _Path Query:
|
||||
|
||||
Query
|
||||
^^^^^
|
||||
|
||||
@ -467,6 +473,7 @@ are :ref:`normalized <Normalization>` before the check.
|
||||
set(path "/a/b")
|
||||
cmake_path(IS_PREFIX path "/a/c/../b" NORMALIZE result) # result = true
|
||||
|
||||
.. _Path COMPARE:
|
||||
.. _COMPARE:
|
||||
|
||||
::
|
||||
@ -475,8 +482,9 @@ are :ref:`normalized <Normalization>` before the check.
|
||||
cmake_path(COMPARE <input1> NOT_EQUAL <input2> <out-var>)
|
||||
|
||||
Compares the lexical representations of two paths provided as string literals.
|
||||
No normalization is performed on either path. Equality is determined
|
||||
according to the following pseudo-code logic:
|
||||
No normalization is performed on either path, except multiple consecutive
|
||||
directory separators are effectively collapsed into a single separator.
|
||||
Equality is determined according to the following pseudo-code logic:
|
||||
|
||||
::
|
||||
|
||||
@ -495,6 +503,8 @@ according to the following pseudo-code logic:
|
||||
takes literal strings as input, not the names of variables.
|
||||
|
||||
|
||||
.. _Path Modification:
|
||||
|
||||
Modification
|
||||
^^^^^^^^^^^^
|
||||
|
||||
@ -509,7 +519,7 @@ path, it is converted into a cmake-style path with forward-slashes
|
||||
(``/``). On Windows, the long filename marker is taken into account.
|
||||
|
||||
When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
|
||||
<Normalization>` before the conversion.
|
||||
<Normalization>` after the conversion.
|
||||
|
||||
For example:
|
||||
|
||||
@ -644,6 +654,8 @@ is equivalent to the following:
|
||||
cmake_path(APPEND_STRING path "input")
|
||||
|
||||
|
||||
.. _Path Generation:
|
||||
|
||||
Generation
|
||||
^^^^^^^^^^
|
||||
|
||||
|
@ -172,8 +172,9 @@ The options are:
|
||||
affected. Summary info detailing the percentage of passing tests is also
|
||||
unaffected by the ``QUIET`` option.
|
||||
|
||||
See also the :variable:`CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE`
|
||||
and :variable:`CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE` variables.
|
||||
See also the :variable:`CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE`,
|
||||
:variable:`CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE` and
|
||||
:variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` variables.
|
||||
|
||||
.. _`Additional Test Measurements`:
|
||||
|
||||
|
@ -37,8 +37,15 @@ Options:
|
||||
``COMMAND``
|
||||
A child process command line.
|
||||
|
||||
CMake executes the child process using operating system APIs directly.
|
||||
All arguments are passed VERBATIM to the child process.
|
||||
CMake executes the child process using operating system APIs directly:
|
||||
|
||||
* On POSIX platforms, the command line is passed to the
|
||||
child process in an ``argv[]`` style array.
|
||||
|
||||
* On Windows platforms, the command line is encoded as a string such
|
||||
that child processes using ``CommandLineToArgvW`` will decode the
|
||||
original arguments.
|
||||
|
||||
No intermediate shell is used, so shell operators such as ``>``
|
||||
are treated as normal arguments.
|
||||
(Use the ``INPUT_*``, ``OUTPUT_*``, and ``ERROR_*`` options to
|
||||
|
@ -1128,6 +1128,18 @@ Additional options to ``DOWNLOAD`` are:
|
||||
Historical short-hand for ``EXPECTED_HASH MD5=<value>``. It is an error to
|
||||
specify this if ``DOWNLOAD`` is not given a ``<file>``.
|
||||
|
||||
``RANGE_START <value>``
|
||||
.. versionadded:: 3.24
|
||||
|
||||
Offset of the start of the range in file in bytes. Could be omitted to
|
||||
download up to the specified ``RANGE_END``.
|
||||
|
||||
``RANGE_END <value>``
|
||||
.. versionadded:: 3.24
|
||||
|
||||
Offset of the end of the range in file in bytes. Could be omitted to
|
||||
download everything from the specified ``RANGE_START`` to the end of file.
|
||||
|
||||
Locking
|
||||
^^^^^^^
|
||||
|
||||
@ -1215,7 +1227,8 @@ the ``MTIME`` option.
|
||||
[DESTINATION <dir>]
|
||||
[PATTERNS <patterns>...]
|
||||
[LIST_ONLY]
|
||||
[VERBOSE])
|
||||
[VERBOSE]
|
||||
[TOUCH])
|
||||
|
||||
.. versionadded:: 3.18
|
||||
|
||||
@ -1233,4 +1246,8 @@ extracted.
|
||||
|
||||
``LIST_ONLY`` will list the files in the archive rather than extract them.
|
||||
|
||||
.. versionadded:: 3.24
|
||||
The ``TOUCH`` option gives extracted files a current local
|
||||
timestamp instead of extracting file timestamps from the archive.
|
||||
|
||||
With ``VERBOSE``, the command will produce verbose output.
|
||||
|
@ -8,6 +8,8 @@ find_file
|
||||
.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include``
|
||||
.. |entry_XXX_SUBDIR| replace:: ``<entry>/include``
|
||||
|
||||
.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``TARGET``
|
||||
|
||||
.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace::
|
||||
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
|
||||
is set, and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR|
|
||||
|
@ -8,6 +8,8 @@ find_library
|
||||
.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/lib``
|
||||
.. |entry_XXX_SUBDIR| replace:: ``<entry>/lib``
|
||||
|
||||
.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``TARGET``
|
||||
|
||||
.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace::
|
||||
``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
|
||||
and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR|
|
||||
|
@ -1,17 +1,30 @@
|
||||
find_package
|
||||
------------
|
||||
|
||||
.. |FIND_XXX| replace:: find_package
|
||||
.. |FIND_ARGS_XXX| replace:: <PackageName>
|
||||
.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``TARGET``
|
||||
.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
|
||||
:variable:`CMAKE_FIND_ROOT_PATH_MODE_PACKAGE`
|
||||
|
||||
.. only:: html
|
||||
|
||||
.. contents::
|
||||
|
||||
.. note:: The :guide:`Using Dependencies Guide` provides a high-level
|
||||
introduction to this general topic. It provides a broader overview of
|
||||
where the ``find_package()`` command fits into the bigger picture,
|
||||
including its relationship to the :module:`FetchContent` module.
|
||||
The guide is recommended pre-reading before moving on to the details below.
|
||||
|
||||
Find a package (usually provided by something external to the project),
|
||||
and load its package-specific details.
|
||||
and load its package-specific details. Calls to this command can also
|
||||
be intercepted by :ref:`dependency providers <dependency_providers>`.
|
||||
|
||||
Search Modes
|
||||
^^^^^^^^^^^^
|
||||
|
||||
The command has two very distinct ways of conducting the search:
|
||||
The command has a few modes by which it searches for packages:
|
||||
|
||||
**Module mode**
|
||||
In this mode, CMake searches for a file called ``Find<PackageName>.cmake``,
|
||||
@ -54,7 +67,17 @@ The command has two very distinct ways of conducting the search:
|
||||
Config mode is supported by both the :ref:`basic <Basic Signature>` and
|
||||
:ref:`full <Full Signature>` command signatures.
|
||||
|
||||
The command arguments determine which of the above modes is used. When the
|
||||
**FetchContent redirection mode**
|
||||
.. versionadded:: 3.24
|
||||
A call to ``find_package()`` can be redirected internally to a package
|
||||
provided by the :module:`FetchContent` module. To the caller, the behavior
|
||||
will appear similar to Config mode, except that the search logic is
|
||||
by-passed and the component information is not used. See
|
||||
:command:`FetchContent_Declare` and :command:`FetchContent_MakeAvailable`
|
||||
for further details.
|
||||
|
||||
When not redirected to a package provided by :module:`FetchContent`, the
|
||||
command arguments determine whether Module or Config mode is used. When the
|
||||
`basic signature`_ is used, the command searches in Module mode first.
|
||||
If the package is not found, the search falls back to Config mode.
|
||||
A user may set the :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` variable
|
||||
@ -64,7 +87,7 @@ forced to use only Module mode with a ``MODULE`` keyword. If the
|
||||
`full signature`_ is used, the command only searches in Config mode.
|
||||
|
||||
Where possible, user code should generally look for packages using the
|
||||
`basic signature`_, since that allows the package to be found with either mode.
|
||||
`basic signature`_, since that allows the package to be found with any mode.
|
||||
Project maintainers wishing to provide a config package should understand
|
||||
the bigger picture, as explained in :ref:`Full Signature` and all subsequent
|
||||
sections on this page.
|
||||
@ -74,12 +97,15 @@ sections on this page.
|
||||
Basic Signature
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block:: cmake
|
||||
.. parsed-literal::
|
||||
|
||||
find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]
|
||||
[REQUIRED] [[COMPONENTS] [components...]]
|
||||
[OPTIONAL_COMPONENTS components...]
|
||||
[NO_POLICY_SCOPE])
|
||||
[REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
|
||||
[GLOBAL]
|
||||
[NO_POLICY_SCOPE]
|
||||
[BYPASS_PROVIDER])
|
||||
|
||||
The basic signature is supported by both Module and Config modes.
|
||||
The ``MODULE`` keyword implies that only Module mode can be used to find
|
||||
@ -115,6 +141,18 @@ define what occurs in such cases. Common arrangements include assuming it
|
||||
should find all components, no components or some well-defined subset of the
|
||||
available components.
|
||||
|
||||
.. versionadded:: 3.24
|
||||
The ``REGISTRY_VIEW`` keyword enables to specify which registry views must be
|
||||
queried. This keyword is only meaningful on ``Windows`` platform and will be
|
||||
ignored on all other ones. Formally, it is up to the target package how to
|
||||
interpret the registry view information given to it.
|
||||
|
||||
.. versionadded:: 3.24
|
||||
Specifying the ``GLOBAL`` keyword will promote all imported targets to
|
||||
a global scope in the importing project. Alternatively, this functionality
|
||||
can be enabled by setting the :variable:`CMAKE_FIND_PACKAGE_TARGETS_GLOBAL`
|
||||
variable.
|
||||
|
||||
.. _FIND_PACKAGE_VERSION_FORMAT:
|
||||
|
||||
The ``[version]`` argument requests a version with which the package found
|
||||
@ -144,22 +182,33 @@ only take the single version at the lower end of the range into account.
|
||||
See the :command:`cmake_policy` command documentation for discussion
|
||||
of the ``NO_POLICY_SCOPE`` option.
|
||||
|
||||
.. versionadded:: 3.24
|
||||
The ``BYPASS_PROVIDER`` keyword is only allowed when ``find_package()`` is
|
||||
being called by a :ref:`dependency provider <dependency_providers>`.
|
||||
It can be used by providers to call the built-in ``find_package()``
|
||||
implementation directly and prevent that call from being re-routed back to
|
||||
itself. Future versions of CMake may detect attempts to use this keyword
|
||||
from places other than a dependency provider and halt with a fatal error.
|
||||
|
||||
.. _`full signature`:
|
||||
|
||||
Full Signature
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block:: cmake
|
||||
.. parsed-literal::
|
||||
|
||||
find_package(<PackageName> [version] [EXACT] [QUIET]
|
||||
[REQUIRED] [[COMPONENTS] [components...]]
|
||||
[OPTIONAL_COMPONENTS components...]
|
||||
[CONFIG|NO_MODULE]
|
||||
[GLOBAL]
|
||||
[NO_POLICY_SCOPE]
|
||||
[BYPASS_PROVIDER]
|
||||
[NAMES name1 [name2 ...]]
|
||||
[CONFIGS config1 [config2 ...]]
|
||||
[HINTS path1 [path2 ... ]]
|
||||
[PATHS path1 [path2 ... ]]
|
||||
[REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
|
||||
[PATH_SUFFIXES suffix1 [suffix2 ...]]
|
||||
[NO_DEFAULT_PATH]
|
||||
[NO_PACKAGE_ROOT_PATH]
|
||||
@ -169,6 +218,7 @@ Full Signature
|
||||
[NO_CMAKE_PACKAGE_REGISTRY]
|
||||
[NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing.
|
||||
[NO_CMAKE_SYSTEM_PATH]
|
||||
[NO_CMAKE_INSTALL_PREFIX]
|
||||
[NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
|
||||
[CMAKE_FIND_ROOT_PATH_BOTH |
|
||||
ONLY_CMAKE_FIND_ROOT_PATH |
|
||||
@ -181,9 +231,12 @@ proceeds at once with Config mode search.
|
||||
|
||||
Config mode search attempts to locate a configuration file provided by the
|
||||
package to be found. A cache entry called ``<PackageName>_DIR`` is created to
|
||||
hold the directory containing the file. By default the command
|
||||
searches for a package with the name ``<PackageName>``. If the ``NAMES`` option
|
||||
is given the names following it are used instead of ``<PackageName>``.
|
||||
hold the directory containing the file. By default, the command searches for
|
||||
a package with the name ``<PackageName>``. If the ``NAMES`` option is given,
|
||||
the names following it are used instead of ``<PackageName>``. The names are
|
||||
also considered when determining whether to redirect the call to a package
|
||||
provided by :module:`FetchContent`.
|
||||
|
||||
The command searches for a file called ``<PackageName>Config.cmake`` or
|
||||
``<lowercasePackageName>-config.cmake`` for each name specified.
|
||||
A replacement set of possible configuration file names may be given
|
||||
@ -220,6 +273,14 @@ Config Mode Search Procedure
|
||||
whether the :ref:`full <full signature>` or :ref:`basic <basic signature>`
|
||||
signature was given.
|
||||
|
||||
.. versionadded:: 3.24
|
||||
All calls to ``find_package()`` (even in Module mode) first look for a config
|
||||
package file in the :variable:`CMAKE_FIND_PACKAGE_REDIRECTS_DIR` directory.
|
||||
The :module:`FetchContent` module, or even the project itself, may write files
|
||||
to that location to redirect ``find_package()`` calls to content already
|
||||
provided by the project. If no config package file is found in that location,
|
||||
the search proceeds with the logic described below.
|
||||
|
||||
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.
|
||||
@ -264,6 +325,18 @@ that order).
|
||||
if the :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` property is set to ``TRUE``.
|
||||
* The ``lib`` path is always searched.
|
||||
|
||||
.. versionchanged:: 3.24
|
||||
On ``Windows`` platform, it is possible to include registry queries as part
|
||||
of the directories specified through ``HINTS`` and ``PATHS`` keywords, using
|
||||
a :ref:`dedicated syntax <Find Using Windows Registry>`. Such specifications
|
||||
will be ignored on all other platforms.
|
||||
|
||||
.. versionadded:: 3.24
|
||||
``REGISTRY_VIEW`` can be specified to manage ``Windows`` registry queries
|
||||
specified as part of ``PATHS`` and ``HINTS``.
|
||||
|
||||
.. include:: FIND_XXX_REGISTRY_VIEW.txt
|
||||
|
||||
If ``PATH_SUFFIXES`` is specified, the suffixes are appended to each
|
||||
(``W``) or (``U``) directory entry one-by-one.
|
||||
|
||||
@ -339,9 +412,11 @@ enabled.
|
||||
package registry.
|
||||
|
||||
7. Search cmake variables defined in the Platform files for the
|
||||
current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is
|
||||
passed or by setting the :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`
|
||||
to ``FALSE``:
|
||||
current system. The searching of :variable:`CMAKE_INSTALL_PREFIX` can be
|
||||
skipped if ``NO_CMAKE_INSTALL_PREFIX`` is passed or by setting the
|
||||
:variable:`CMAKE_FIND_USE_INSTALL_PREFIX` to ``FALSE``. All these locations
|
||||
can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is passed or by setting the
|
||||
:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` to ``FALSE``:
|
||||
|
||||
* :variable:`CMAKE_SYSTEM_PREFIX_PATH`
|
||||
* :variable:`CMAKE_SYSTEM_FRAMEWORK_PATH`
|
||||
@ -372,11 +447,6 @@ of the above locations to be ignored.
|
||||
Added the ``CMAKE_FIND_USE_<CATEGORY>`` variables to globally disable
|
||||
various search locations.
|
||||
|
||||
.. |FIND_XXX| replace:: find_package
|
||||
.. |FIND_ARGS_XXX| replace:: <PackageName>
|
||||
.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
|
||||
:variable:`CMAKE_FIND_ROOT_PATH_MODE_PACKAGE`
|
||||
|
||||
.. include:: FIND_XXX_ROOT.txt
|
||||
.. include:: FIND_XXX_ORDER.txt
|
||||
|
||||
@ -388,7 +458,8 @@ to resolve symbolic links and store the real path to the file.
|
||||
Every non-REQUIRED ``find_package`` call can be disabled or made REQUIRED:
|
||||
|
||||
* Setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable
|
||||
to ``TRUE`` disables the package.
|
||||
to ``TRUE`` disables the package. This also disables redirection to a
|
||||
package provided by :module:`FetchContent`.
|
||||
|
||||
* Setting the :variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` variable
|
||||
to ``TRUE`` makes the package REQUIRED.
|
||||
@ -411,8 +482,8 @@ version (see :ref:`format specification <FIND_PACKAGE_VERSION_FORMAT>`). If the
|
||||
``EXACT`` option is given, only a version of the package claiming an exact match
|
||||
of the requested version may be found. CMake does not establish any
|
||||
convention for the meaning of version numbers. Package version
|
||||
numbers are checked by "version" files provided by the packages
|
||||
themselves. For a candidate package configuration file
|
||||
numbers are checked by "version" files provided by the packages themselves
|
||||
or by :module:`FetchContent`. For a candidate package configuration file
|
||||
``<config-file>.cmake`` the corresponding version file is located next
|
||||
to it and named either ``<config-file>-version.cmake`` or
|
||||
``<config-file>Version.cmake``. If no such version file is available
|
||||
@ -547,6 +618,8 @@ restores their original state before returning):
|
||||
True if ``REQUIRED`` option was given
|
||||
``<PackageName>_FIND_QUIETLY``
|
||||
True if ``QUIET`` option was given
|
||||
``<PackageName>_FIND_REGISTRY_VIEW``
|
||||
The requested view if ``REGISTRY_VIEW`` option was given
|
||||
``<PackageName>_FIND_VERSION``
|
||||
Full requested version string
|
||||
``<PackageName>_FIND_VERSION_MAJOR``
|
||||
|
@ -8,6 +8,8 @@ find_path
|
||||
.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include``
|
||||
.. |entry_XXX_SUBDIR| replace:: ``<entry>/include``
|
||||
|
||||
.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``TARGET``
|
||||
|
||||
.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace::
|
||||
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
|
||||
is set, and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR|
|
||||
|
@ -8,6 +8,8 @@ find_program
|
||||
.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/[s]bin``
|
||||
.. |entry_XXX_SUBDIR| replace:: ``<entry>/[s]bin``
|
||||
|
||||
.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``BOTH``
|
||||
|
||||
.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace::
|
||||
|FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR|
|
||||
.. |CMAKE_PREFIX_PATH_XXX| replace::
|
||||
|
@ -4,10 +4,16 @@ get_filename_component
|
||||
Get a specific component of a full filename.
|
||||
|
||||
.. versionchanged:: 3.20
|
||||
This command been superseded by :command:`cmake_path` command, except
|
||||
``REALPATH`` now offered by :ref:`file(REAL_PATH) <REAL_PATH>` command and
|
||||
This command has been superseded by :command:`cmake_path` command, except
|
||||
``REALPATH`` now offered by :ref:`file(REAL_PATH)<REAL_PATH>` command and
|
||||
``PROGRAM`` now available in :command:`separate_arguments(PROGRAM)` command.
|
||||
|
||||
.. versionchanged:: 3.24
|
||||
The undocumented feature offering the capability to query the ``Windows``
|
||||
registry is superseded by
|
||||
:ref:`cmake_host_system_information(QUERY WINDOWS_REGISTRY)<Query Windows registry>`
|
||||
command.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
get_filename_component(<var> <FileName> <mode> [CACHE])
|
||||
|
@ -47,7 +47,7 @@ Compound conditions are evaluated in the following order of precedence:
|
||||
`GREATER_EQUAL`_, `STREQUAL`_, `STRLESS`_, `STRLESS_EQUAL`_,
|
||||
`STRGREATER`_, `STRGREATER_EQUAL`_, `VERSION_EQUAL`_, `VERSION_LESS`_,
|
||||
`VERSION_LESS_EQUAL`_, `VERSION_GREATER`_, `VERSION_GREATER_EQUAL`_,
|
||||
and `MATCHES`_.
|
||||
`PATH_EQUAL`_, and `MATCHES`_.
|
||||
|
||||
4. Unary logical operator `NOT`_.
|
||||
|
||||
@ -71,8 +71,9 @@ Basic Expressions
|
||||
True if given a variable that is defined to a value that is not a false
|
||||
constant. False otherwise, including if the variable is undefined.
|
||||
Note that macro arguments are not variables.
|
||||
Environment variables also cannot be tested this way, e.g.
|
||||
``if(ENV{some_var})`` will always evaluate to false.
|
||||
:ref:`Environment Variables <CMake Language Environment Variables>` also
|
||||
cannot be tested this way, e.g. ``if(ENV{some_var})`` will always evaluate
|
||||
to false.
|
||||
|
||||
``if(<string>)``
|
||||
A quoted string always evaluates to false unless:
|
||||
@ -313,6 +314,39 @@ Version Comparisons
|
||||
Any non-integer version component or non-integer trailing part of a version
|
||||
component effectively truncates the string at that point.
|
||||
|
||||
Path Comparisons
|
||||
""""""""""""""""
|
||||
|
||||
.. _PATH_EQUAL:
|
||||
|
||||
``if(<variable|string> PATH_EQUAL <variable|string>)``
|
||||
.. versionadded:: 3.24
|
||||
|
||||
Compares the two paths component-by-component. Only if every component of
|
||||
both paths match will the two paths compare equal. Multiple path separators
|
||||
are effectively collapsed into a single separator, but note that backslashes
|
||||
are not converted to forward slashes. No other
|
||||
:ref:`path normalization <Normalization>` is performed.
|
||||
|
||||
Component-wise comparison is superior to string-based comparison due to the
|
||||
handling of multiple path separators. In the following example, the
|
||||
expression evaluates to true using ``PATH_EQUAL``, but false with
|
||||
``STREQUAL``:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
# comparison is TRUE
|
||||
if ("/a//b/c" PATH_EQUAL "/a/b/c")
|
||||
...
|
||||
endif()
|
||||
|
||||
# comparison is FALSE
|
||||
if ("/a//b/c" STREQUAL "/a/b/c")
|
||||
...
|
||||
endif()
|
||||
|
||||
See :ref:`cmake_path(COMPARE) <Path COMPARE>` for more details.
|
||||
|
||||
Variable Expansion
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
@ -85,7 +85,7 @@ signatures that specify them. The common options are:
|
||||
|
||||
``COMPONENT``
|
||||
Specify an installation component name with which the install rule
|
||||
is associated, such as "runtime" or "development". During
|
||||
is associated, such as ``Runtime`` or ``Development``. During
|
||||
component-specific installation only install rules associated with
|
||||
the given component name will be executed. During a full installation
|
||||
all components are installed unless marked with ``EXCLUDE_FROM_ALL``.
|
||||
|
@ -32,6 +32,9 @@ influences the way the message is handled:
|
||||
``FATAL_ERROR``
|
||||
CMake Error, stop processing and generation.
|
||||
|
||||
The :manual:`cmake(1)` executable will return a non-zero
|
||||
:ref:`exit code <CMake Exit Code>`.
|
||||
|
||||
``SEND_ERROR``
|
||||
CMake Error, continue processing, but skip generation.
|
||||
|
||||
|
@ -1,16 +1,18 @@
|
||||
option
|
||||
------
|
||||
|
||||
Provide an option that the user can optionally select.
|
||||
Provide a boolean option that the user can optionally select.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
option(<variable> "<help_text>" [value])
|
||||
|
||||
Provides an option for the user to select as ``ON`` or ``OFF``.
|
||||
If no initial ``<value>`` is provided, ``OFF`` is used.
|
||||
If no initial ``<value>`` is provided, boolean ``OFF`` is the default value.
|
||||
If ``<variable>`` is already set as a normal or cache variable,
|
||||
then the command does nothing (see policy :policy:`CMP0077`).
|
||||
|
||||
If you have options that depend on the values of other options, see
|
||||
For options that depend on the values of other options, see
|
||||
the module help for :module:`CMakeDependentOption`.
|
||||
|
||||
In CMake project mode, a boolean cache variable is created with the option
|
||||
value. In CMake script mode, a boolean variable is set with the option value.
|
||||
|
@ -123,28 +123,56 @@ The options are:
|
||||
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`:
|
||||
|
||||
Code Injection
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
If the :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` or
|
||||
:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` variables are set,
|
||||
the files they point to will be included as the first step of the
|
||||
``project()`` command.
|
||||
If both are set, then :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` will be
|
||||
included before :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`.
|
||||
A number of variables can be defined by the user to specify files to include
|
||||
at different points during the execution of the ``project()`` command.
|
||||
The following outlines the steps performed during a ``project()`` call:
|
||||
|
||||
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`.
|
||||
* .. versionadded:: 3.15
|
||||
For every ``project()`` call regardless of the project
|
||||
name, include the file named by :variable:`CMAKE_PROJECT_INCLUDE_BEFORE`,
|
||||
if set.
|
||||
|
||||
.. versionadded:: 3.15
|
||||
Added the ``CMAKE_PROJECT_INCLUDE`` and ``CMAKE_PROJECT_INCLUDE_BEFORE``
|
||||
variables.
|
||||
* .. versionadded:: 3.17
|
||||
If the ``project()`` command specifies ``<PROJECT-NAME>`` as its project
|
||||
name, include the file named by
|
||||
:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`, if set.
|
||||
|
||||
.. versionadded:: 3.17
|
||||
Added the ``CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`` variable.
|
||||
* Set the various project-specific variables detailed in the `Synopsis`_
|
||||
and `Options`_ sections above.
|
||||
|
||||
* For the very first ``project()`` call only:
|
||||
|
||||
* If :variable:`CMAKE_TOOLCHAIN_FILE` is set, read it at least once.
|
||||
It may be read multiple times and it may also be read again when
|
||||
enabling languages later (see below).
|
||||
|
||||
* Set the variables describing the host and target platforms.
|
||||
Language-specific variables might or might not be set at this point.
|
||||
On the first run, the only language-specific variables that might be
|
||||
defined are those a toolchain file may have set. On subsequent runs,
|
||||
language-specific variables cached from a previous run may be set.
|
||||
|
||||
* .. versionadded:: 3.24
|
||||
Include each file listed in :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES`,
|
||||
if set. The variable is ignored by CMake thereafter.
|
||||
|
||||
* Enable any languages specified in the call, or the default languages if
|
||||
none were provided. The toolchain file may be re-read when enabling a
|
||||
language for the first time.
|
||||
|
||||
* .. versionadded:: 3.15
|
||||
For every ``project()`` call regardless of the project
|
||||
name, include the file named by :variable:`CMAKE_PROJECT_INCLUDE`,
|
||||
if set.
|
||||
|
||||
* If the ``project()`` command specifies ``<PROJECT-NAME>`` as its project
|
||||
name, include the file named by
|
||||
:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, if set.
|
||||
|
||||
Usage
|
||||
^^^^^
|
||||
|
@ -52,10 +52,10 @@ expressions to ensure the sources are correctly assigned to the target.
|
||||
.. code-block:: cmake
|
||||
|
||||
# WRONG: starts with generator expression, but relative path used
|
||||
target_sources(MyTarget "$<$<CONFIG:Debug>:dbgsrc.cpp>")
|
||||
target_sources(MyTarget PRIVATE "$<$<CONFIG:Debug>:dbgsrc.cpp>")
|
||||
|
||||
# CORRECT: absolute path used inside the generator expression
|
||||
target_sources(MyTarget "$<$<CONFIG:Debug>:${CMAKE_CURRENT_SOURCE_DIR}/dbgsrc.cpp>")
|
||||
target_sources(MyTarget PRIVATE "$<$<CONFIG:Debug>:${CMAKE_CURRENT_SOURCE_DIR}/dbgsrc.cpp>")
|
||||
|
||||
See the :manual:`cmake-buildsystem(7)` manual for more on defining
|
||||
buildsystem properties.
|
||||
|
@ -7,6 +7,8 @@ try_compile
|
||||
|
||||
Try building some code.
|
||||
|
||||
.. _`Try Compiling Whole Projects`:
|
||||
|
||||
Try Compiling Whole Projects
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@ -25,6 +27,15 @@ will not be deleted after this command is run. Specify ``<targetName>`` to
|
||||
build a specific target instead of the ``all`` or ``ALL_BUILD`` target. See
|
||||
below for the meaning of other options.
|
||||
|
||||
.. versionchanged:: 3.24
|
||||
CMake variables describing platform settings, and those listed by the
|
||||
:variable:`CMAKE_TRY_COMPILE_PLATFORM_VARIABLES` variable, are propagated
|
||||
into the project's build configuration. See policy :policy:`CMP0137`.
|
||||
Previously this was only done by the
|
||||
:ref:`source file <Try Compiling Source Files>` signature.
|
||||
|
||||
.. _`Try Compiling Source Files`:
|
||||
|
||||
Try Compiling Source Files
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@ -150,6 +161,7 @@ Other Behavior Settings
|
||||
* :variable:`CMAKE_LINK_SEARCH_END_STATIC`
|
||||
* :variable:`CMAKE_MSVC_RUNTIME_LIBRARY`
|
||||
* :variable:`CMAKE_POSITION_INDEPENDENT_CODE`
|
||||
* :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY`
|
||||
|
||||
If :policy:`CMP0056` is set to ``NEW``, then
|
||||
:variable:`CMAKE_EXE_LINKER_FLAGS` is passed in as well.
|
||||
@ -204,3 +216,7 @@ a build configuration.
|
||||
.. versionchanged:: 3.14
|
||||
For the :generator:`Green Hills MULTI` generator the GHS toolset and target
|
||||
system customization cache variables are also propagated into the test project.
|
||||
|
||||
.. versionadded:: 3.24
|
||||
The :variable:`CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES` variable may be
|
||||
set to disable passing platform variables into the test project.
|
||||
|
@ -49,6 +49,8 @@ Variables specific to CPack Archive generator
|
||||
|
||||
Package file name without extension. The extension is determined from the
|
||||
archive format (see list above) and automatically appended to the file name.
|
||||
Note that ``<component>`` is all uppercase in the variable name.
|
||||
|
||||
The default is ``<CPACK_PACKAGE_FILE_NAME>[-<component>]``, with spaces
|
||||
replaced by '-'.
|
||||
|
||||
|
@ -65,8 +65,8 @@ on macOS:
|
||||
|
||||
In a CMake project that uses the :module:`CPack` module to generate
|
||||
``CPackConfig.cmake``, ``CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE``
|
||||
is automatically enabled by default if it is not set and
|
||||
:variable:`CPACK_RESOURCE_FILE_LICENSE` is set to a non-default value.
|
||||
must be explicitly enabled by the project to activate the SLA.
|
||||
See policy :policy:`CMP0133`.
|
||||
|
||||
.. note::
|
||||
|
||||
|
@ -1,87 +1,7 @@
|
||||
CPack PackageMaker Generator
|
||||
----------------------------
|
||||
|
||||
PackageMaker CPack generator (macOS).
|
||||
|
||||
.. deprecated:: 3.17
|
||||
|
||||
Xcode no longer distributes the PackageMaker tools.
|
||||
This CPack generator will be removed in a future version of CPack.
|
||||
|
||||
Variables specific to CPack PackageMaker generator
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The following variable is specific to installers built on Mac
|
||||
macOS using PackageMaker:
|
||||
|
||||
.. variable:: CPACK_OSX_PACKAGE_VERSION
|
||||
|
||||
The version of macOS that the resulting PackageMaker archive should be
|
||||
compatible with. Different versions of macOS support different
|
||||
features. For example, CPack can only build component-based installers for
|
||||
macOS 10.4 or newer, and can only build installers that download
|
||||
components on-the-fly for macOS 10.5 or newer. If left blank, this value
|
||||
will be set to the minimum version of macOS that supports the requested
|
||||
features. Set this variable to some value (e.g., 10.4) only if you want to
|
||||
guarantee that your installer will work on that version of macOS, and
|
||||
don't mind missing extra features available in the installer shipping with
|
||||
later versions of macOS.
|
||||
|
||||
Background Image
|
||||
""""""""""""""""
|
||||
|
||||
.. versionadded:: 3.17
|
||||
|
||||
This group of variables controls the background image of the generated
|
||||
installer.
|
||||
|
||||
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND
|
||||
|
||||
Adds a background to Distribution XML if specified. The value contains the
|
||||
path to image in ``Resources`` directory.
|
||||
|
||||
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_ALIGNMENT
|
||||
|
||||
Adds an ``alignment`` attribute to the background in Distribution XML.
|
||||
Refer to Apple documentation for valid values.
|
||||
|
||||
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_SCALING
|
||||
|
||||
Adds a ``scaling`` attribute to the background in Distribution XML.
|
||||
Refer to Apple documentation for valid values.
|
||||
|
||||
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_MIME_TYPE
|
||||
|
||||
Adds a ``mime-type`` attribute to the background in Distribution XML.
|
||||
The option contains MIME type of an image.
|
||||
|
||||
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_UTI
|
||||
|
||||
Adds an ``uti`` attribute to the background in Distribution XML.
|
||||
The option contains UTI type of an image.
|
||||
|
||||
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA
|
||||
|
||||
Adds a background for the Dark Aqua theme to Distribution XML if
|
||||
specified. The value contains the path to image in ``Resources``
|
||||
directory.
|
||||
|
||||
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_ALIGNMENT
|
||||
|
||||
Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_ALIGNMENT` option,
|
||||
but for the dark theme.
|
||||
|
||||
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_SCALING
|
||||
|
||||
Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_SCALING` option,
|
||||
but for the dark theme.
|
||||
|
||||
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_MIME_TYPE
|
||||
|
||||
Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_MIME_TYPE` option,
|
||||
but for the dark theme.
|
||||
|
||||
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_UTI
|
||||
|
||||
Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_UTI` option,
|
||||
but for the dark theme.
|
||||
Removed. This once generated PackageMaker installers, but the
|
||||
generator has been removed since CMake 3.24. Xcode no longer distributes
|
||||
the PackageMaker tools. Use the :cpack_gen:`CPack productbuild Generator`
|
||||
instead.
|
||||
|
@ -328,3 +328,12 @@ Windows using WiX.
|
||||
If this variable is set then the inclusion of WixUIExtensions is skipped,
|
||||
i.e. the ``-ext "WixUIExtension"`` command line is not included during
|
||||
the execution of the WiX light tool.
|
||||
|
||||
.. variable:: CPACK_WIX_ARCHITECTURE
|
||||
|
||||
.. versionadded:: 3.24
|
||||
|
||||
This variable can be optionally set to specify the target architecture
|
||||
of the installer. May for example be set to ``x64`` or ``arm64``.
|
||||
|
||||
When unspecified, CPack will default to ``x64`` or ``x86``.
|
||||
|
@ -36,7 +36,14 @@ For example, add code like the following to a test project:
|
||||
The tool specified by ``CMAKE_EXPERIMENTAL_CXX_SCANDEP_SOURCE`` is
|
||||
expected to process the translation unit, write preprocessor dependencies
|
||||
to the file specified by the ``<DEP_FILE>`` placeholder, and write module
|
||||
dependencies to the file specified by the ``<DYNDEP_FILE>`` placeholder.
|
||||
dependencies to the file specified by the ``<DYNDEP_FILE>`` placeholder. The
|
||||
``CMAKE_EXPERIMENTAL_CXX_SCANDEP_DEPFILE_FORMAT`` file may be set to ``msvc``
|
||||
for scandep rules which use ``msvc``-style dependency reporting.
|
||||
|
||||
For tools which need to know the file set the source belongs to, the
|
||||
``CMAKE_EXPERIMENTAL_CXX_MODULE_SOURCE_TYPE_FLAG_<FILE_SET_TYPE>`` flag may
|
||||
be provided so that different source types can be distinguished prior to
|
||||
scanning.
|
||||
|
||||
The module dependencies should be written in the format described
|
||||
by the `P1689r4`_ paper.
|
||||
|
@ -35,6 +35,18 @@ Available features are:
|
||||
|
||||
* From ``C++14``:
|
||||
|
||||
* ``<cm/array>``:
|
||||
``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
|
||||
``cm::crbegin``, ``cm::crend``
|
||||
|
||||
* ``<cm/deque>``:
|
||||
``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
|
||||
``cm::crbegin``, ``cm::crend``
|
||||
|
||||
* ``<cm/forward_list>``:
|
||||
``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
|
||||
``cm::crbegin``, ``cm::crend``
|
||||
|
||||
* ``<cm/iomanip>``:
|
||||
``cm::quoted``
|
||||
|
||||
@ -42,68 +54,142 @@ Available features are:
|
||||
``cm::make_reverse_iterator``, ``cm::cbegin``, ``cm::cend``,
|
||||
``cm::rbegin``, ``cm::rend``, ``cm::crbegin``, ``cm::crend``
|
||||
|
||||
* ``<cm/list>``:
|
||||
``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
|
||||
``cm::crbegin``, ``cm::crend``
|
||||
|
||||
* ``<cm/map>``:
|
||||
``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
|
||||
``cm::crbegin``, ``cm::crend``
|
||||
|
||||
* ``<cm/memory>``:
|
||||
``cm::make_unique``
|
||||
|
||||
* ``<cm/set>``:
|
||||
``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
|
||||
``cm::crbegin``, ``cm::crend``
|
||||
|
||||
* ``<cm/string>``:
|
||||
``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
|
||||
``cm::crbegin``, ``cm::crend``
|
||||
|
||||
* ``<cm/string_view>``:
|
||||
``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
|
||||
``cm::crbegin``, ``cm::crend``
|
||||
|
||||
* ``<cm/shared_mutex>``:
|
||||
``cm::shared_lock``
|
||||
|
||||
* ``<cm/type_traits>``:
|
||||
``cm::enable_if_t``
|
||||
|
||||
* ``<cm/unordered_map>``:
|
||||
``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
|
||||
``cm::crbegin``, ``cm::crend``
|
||||
|
||||
* ``<cm/unordered_set>``:
|
||||
``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
|
||||
``cm::crbegin``, ``cm::crend``
|
||||
|
||||
* ``<cm/vector>``:
|
||||
``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
|
||||
``cm::crbegin``, ``cm::crend``
|
||||
|
||||
* From ``C++17``:
|
||||
|
||||
* ``<cm/algorithm>``:
|
||||
``cm::clamp``
|
||||
|
||||
* ``<cm/array>``:
|
||||
``cm::size``, ``cm::empty``, ``cm::data``
|
||||
|
||||
* ``<cm/deque>``:
|
||||
``cm::size``, ``cm::empty``, ``cm::data``
|
||||
|
||||
* ``cm/filesystem>``:
|
||||
``cm::filesystem::path``
|
||||
|
||||
* ``<cm/forward_list>``:
|
||||
``cm::size``, ``cm::empty``, ``cm::data``
|
||||
|
||||
* ``<cm/iterator>``:
|
||||
``cm::size``, ``cm::empty``, ``cm::data``
|
||||
|
||||
* ``<cm/list>``:
|
||||
``cm::size``, ``cm::empty``, ``cm::data``
|
||||
|
||||
* ``<cm/map>``:
|
||||
``cm::size``, ``cm::empty``, ``cm::data``
|
||||
|
||||
* ``<cm/optional>``:
|
||||
``cm::nullopt_t``, ``cm::nullopt``, ``cm::optional``,
|
||||
``cm::make_optional``, ``cm::bad_optional_access``
|
||||
|
||||
* ``<cm/set>``:
|
||||
``cm::size``, ``cm::empty``, ``cm::data``
|
||||
|
||||
* ``<cm/shared_mutex>``:
|
||||
``cm::shared_mutex``
|
||||
|
||||
* ``<cm/string>``:
|
||||
``cm::size``, ``cm::empty``, ``cm::data``
|
||||
|
||||
* ``<cm/string_view>``:
|
||||
``cm::string_view``
|
||||
``cm::string_view``, ``cm::size``, ``cm::empty``, ``cm::data``
|
||||
|
||||
* ``<cm/type_traits>``:
|
||||
``cm::bool_constant``, ``cm::invoke_result_t``, ``cm::invoke_result``,
|
||||
``cm::void_t``
|
||||
|
||||
* ``<cm/unordered_map>``:
|
||||
``cm::size``, ``cm::empty``, ``cm::data``
|
||||
|
||||
* ``<cm/unordered_set>``:
|
||||
``cm::size``, ``cm::empty``, ``cm::data``
|
||||
|
||||
* ``<cm/utility>``:
|
||||
``cm::in_place_t``, ``cm::in_place``
|
||||
|
||||
* ``<cm/vector>``:
|
||||
``cm::size``, ``cm::empty``, ``cm::data``
|
||||
|
||||
* From ``C++20``:
|
||||
|
||||
* ``<cm/array>``:
|
||||
``cm::ssize``
|
||||
|
||||
* ``<cm/deque>``:
|
||||
``cm::erase``, ``cm::erase_if``
|
||||
``cm::erase``, ``cm::erase_if``, ``cm::ssize``
|
||||
|
||||
* ``<cm/forward_list>``:
|
||||
``cm::ssize``
|
||||
|
||||
* ``<cm/iterator>``:
|
||||
``cm::ssize``
|
||||
|
||||
* ``<cm/list>``:
|
||||
``cm::erase``, ``cm::erase_if``
|
||||
``cm::erase``, ``cm::erase_if``, ``cm::ssize``
|
||||
|
||||
* ``<cm/map>`` :
|
||||
``cm::erase_if``
|
||||
``cm::erase_if``, ``cm::ssize``
|
||||
|
||||
* ``<cm/set>`` :
|
||||
``cm::erase_if``
|
||||
``cm::erase_if``, ``cm::ssize``
|
||||
|
||||
* ``<cm/string_view>``:
|
||||
``cm::ssize``
|
||||
|
||||
* ``<cm/string>``:
|
||||
``cm::erase``, ``cm::erase_if``
|
||||
``cm::erase``, ``cm::erase_if``, ``cm::ssize``
|
||||
|
||||
* ``<cm/unordered_map>``:
|
||||
``cm::erase_if``
|
||||
``cm::erase_if``, ``cm::ssize``
|
||||
|
||||
* ``<cm/unordered_set>``:
|
||||
``cm::erase_if``
|
||||
``cm::erase_if``, ``cm::ssize``
|
||||
|
||||
* ``<cm/vector>``:
|
||||
``cm::erase``, ``cm::erase_if``
|
||||
``cm::erase``, ``cm::erase_if``, ``cm::ssize``
|
||||
|
||||
Additionally, some useful non-standard extensions to the C++ standard library
|
||||
are available in headers under the directory ``cmext/`` in namespace ``cm``.
|
||||
@ -117,6 +203,11 @@ These are:
|
||||
* ``cm::contains``:
|
||||
Checks if element or key is contained in container.
|
||||
|
||||
* ``<cmext/enum_set>``
|
||||
|
||||
* ``cm::enum_set``:
|
||||
Container to manage set of elements from an ``enum class`` definition.
|
||||
|
||||
* ``<cmext/iterator>``:
|
||||
|
||||
* ``cm::is_terator``:
|
||||
|
10
Help/envvar/ADSP_ROOT.rst
Normal file
10
Help/envvar/ADSP_ROOT.rst
Normal file
@ -0,0 +1,10 @@
|
||||
ADSP_ROOT
|
||||
---------
|
||||
|
||||
.. versionadded:: 3.24
|
||||
|
||||
.. include:: ENV_VAR.txt
|
||||
|
||||
The ``ADSP_ROOT`` environment variable specifies a default value
|
||||
for the :variable:`CMAKE_ADSP_ROOT` variable when there is no explicit
|
||||
configuration given on the first run while creating a new build tree.
|
9
Help/envvar/CMAKE_COLOR_DIAGNOSTICS.rst
Normal file
9
Help/envvar/CMAKE_COLOR_DIAGNOSTICS.rst
Normal file
@ -0,0 +1,9 @@
|
||||
CMAKE_COLOR_DIAGNOSTICS
|
||||
-----------------------
|
||||
|
||||
.. versionadded:: 3.24
|
||||
|
||||
.. include:: ENV_VAR.txt
|
||||
|
||||
Specifies a default value for the :variable:`CMAKE_COLOR_DIAGNOSTICS` variable
|
||||
when there is no explicit value given on the first run.
|
@ -8,193 +8,412 @@ Using Dependencies Guide
|
||||
Introduction
|
||||
============
|
||||
|
||||
For developers wishing to use CMake to consume a third
|
||||
party binary package, there are multiple possibilities
|
||||
regarding how to optimally do so, depending on how
|
||||
CMake-aware the third-party library is.
|
||||
Projects will frequently depend on other projects, assets, and artifacts.
|
||||
CMake provides a number of ways to incorporate such things into the build.
|
||||
Projects and users have the flexibility to choose between methods that
|
||||
best suit their needs.
|
||||
|
||||
CMake files provided with a software package contain
|
||||
instructions for finding each build dependency. Some
|
||||
build dependencies are optional in that the build may
|
||||
succeed with a different feature set if the dependency
|
||||
is missing, and some dependencies are required. CMake
|
||||
searches well-known locations for each dependency, and
|
||||
the provided software may supply additional hints or
|
||||
locations to CMake to find each dependency.
|
||||
The primary methods of bringing dependencies into the build are the
|
||||
:command:`find_package` command and the :module:`FetchContent` module.
|
||||
The :module:`FindPkgConfig` module is also sometimes used, although it
|
||||
lacks some of the integration of the other two and is not discussed any
|
||||
further in this guide.
|
||||
|
||||
If a required dependency is not found by
|
||||
:manual:`cmake(1)`, the cache is populated with an entry
|
||||
which contains a ``NOTFOUND`` value. This value can be
|
||||
replaced by specifying it on the command line, or in
|
||||
the :manual:`ccmake(1)` or :manual:`cmake-gui(1)` tool.
|
||||
See the :guide:`User Interaction Guide` for
|
||||
more about setting cache entries.
|
||||
Dependencies can also be made available by a custom
|
||||
:ref:`dependency provider <dependency_providers>`.
|
||||
This might be a third party package manager, or it might be custom code
|
||||
implemented by the developer. Dependency providers co-operate with the
|
||||
primary methods mentioned above to extend their flexibility.
|
||||
|
||||
Libraries providing Config-file packages
|
||||
========================================
|
||||
.. _prebuilt_find_package:
|
||||
|
||||
The most convenient way for a third-party to provide library
|
||||
binaries for use with CMake is to provide
|
||||
:ref:`Config File Packages`. These packages are text files
|
||||
shipped with the library which instruct CMake how to use the
|
||||
library binaries and associated headers, helper tools and
|
||||
CMake macros provided by the library.
|
||||
Using Pre-built Packages With ``find_package()``
|
||||
================================================
|
||||
|
||||
The config files can usually be found in a directory whose
|
||||
name matches the pattern ``lib/cmake/<PackageName>``, though
|
||||
they may be in other locations instead. The
|
||||
``<PackageName>`` corresponds to use in CMake code with the
|
||||
:command:`find_package` command such as
|
||||
``find_package(PackageName REQUIRED)``.
|
||||
A package needed by the project may already be built and available at some
|
||||
location on the user's system. That package might have also been built by
|
||||
CMake, or it could have used a different build system entirely. It might
|
||||
even just be a collection of files that didn't need to be built at all.
|
||||
CMake provides the :command:`find_package` command for these scenarios.
|
||||
It searches well-known locations, along with additional hints and paths
|
||||
provided by the project or user. It also supports package components and
|
||||
packages being optional. Result variables are provided to allow the project
|
||||
to customize its own behavior according to whether the package or specific
|
||||
components were found.
|
||||
|
||||
The ``lib/cmake/<PackageName>`` directory will contain a
|
||||
file which is either named ``<PackageName>Config.cmake``
|
||||
or ``<PackageName>-config.cmake``. This is the entry point
|
||||
In most cases, projects should generally use the :ref:`basic signature`.
|
||||
Most of the time, this will involve just the package name, maybe a version
|
||||
constraint, and the ``REQUIRED`` keyword if the dependency is not optional.
|
||||
A set of package components may also be specified.
|
||||
|
||||
.. code-block:: cmake
|
||||
:caption: Examples of ``find_package()`` basic signature
|
||||
|
||||
find_package(Catch2)
|
||||
find_package(GTest REQUIRED)
|
||||
find_package(Boost 1.79 COMPONENTS date_time)
|
||||
|
||||
The :command:`find_package` command supports two main methods for carrying
|
||||
out the search:
|
||||
|
||||
**Config mode**
|
||||
With this method, the command looks for files that are typically provided
|
||||
by the package itself. This is the more reliable method of the two, since
|
||||
the package details should always be in sync with the package.
|
||||
|
||||
**Module mode**
|
||||
Not all packages are CMake-aware. Many don't provide the files needed to
|
||||
support config mode. For such cases, a Find module file can be provided
|
||||
separately, either by the project or by CMake. A Find module is typically
|
||||
a heuristic implementation which knows what the package normally provides
|
||||
and how to present that package to the project. Since Find modules are
|
||||
usually distributed separately from the package, they are not as reliable.
|
||||
They are typically maintained separately, and they are likely to follow
|
||||
different release schedules, so they can easily become out-of-date.
|
||||
|
||||
Depending on the arguments used, :command:`find_package` may use one or both
|
||||
of the above methods. By restricting the options to just the basic signature,
|
||||
both config mode and module mode can be used to satisfy the dependency.
|
||||
The presence of other options may restrict the call to using only one of the
|
||||
two methods, potentially reducing the command's ability to find the dependency.
|
||||
See the :command:`find_package` documentation for full details about this
|
||||
complex topic.
|
||||
|
||||
For both search methods, the user can also set cache variables on the
|
||||
:manual:`cmake(1)` command line or in the :manual:`ccmake(1)` or
|
||||
:manual:`cmake-gui(1)` UI tools to influence and override where to find
|
||||
packages. See the :ref:`User Interaction Guide <Setting Build Variables>`
|
||||
for more on how to set cache variables.
|
||||
|
||||
.. _Libraries providing Config-file packages:
|
||||
|
||||
Config-file packages
|
||||
--------------------
|
||||
|
||||
The preferred way for a third party to provide executables, libraries,
|
||||
headers, and other files for use with CMake is to provide
|
||||
:ref:`config files <Config File Packages>`. These are text files shipped
|
||||
with the package, which define CMake targets, variables, commands, and so on.
|
||||
The config file is an ordinary CMake script, which is read in by the
|
||||
:command:`find_package` command.
|
||||
|
||||
The config files can usually be found in a directory whose name matches the
|
||||
pattern ``lib/cmake/<PackageName>``, although they may be in other locations
|
||||
instead (see :ref:`search procedure`). The ``<PackageName>`` is usually the
|
||||
first argument to the :command:`find_package` command, and it may even be the
|
||||
only argument. Alternative names can also be specified with the ``NAMES``
|
||||
option:
|
||||
|
||||
.. code-block:: cmake
|
||||
:caption: Providing alternative names when finding a package
|
||||
|
||||
find_package(SomeThing
|
||||
NAMES
|
||||
SameThingOtherName # Another name for the package
|
||||
SomeThing # Also still look for its canonical name
|
||||
)
|
||||
|
||||
The config file must be named either ``<PackageName>Config.cmake`` or
|
||||
``<LowercasePackageName>-config.cmake`` (the former is used for the remainder
|
||||
of this guide, but both are supported). This file is the entry point
|
||||
to the package for CMake. A separate optional file named
|
||||
``<PackageName>ConfigVersion.cmake`` may also exist in the
|
||||
directory. This file is used by CMake to determine whether
|
||||
the version of the third party package satisfies uses of the
|
||||
:command:`find_package` command which specify version
|
||||
constraints. It is optional to specify a version when using
|
||||
:command:`find_package`, even if a ``ConfigVersion`` file is
|
||||
present.
|
||||
``<PackageName>ConfigVersion.cmake`` or
|
||||
``<LowercasePackageName>-config-version.cmake`` may also exist in the same
|
||||
directory. This file is used by CMake to determine whether the version of
|
||||
the package satisfies any version constraint included in the call to
|
||||
:command:`find_package`. It is optional to specify a version when calling
|
||||
:command:`find_package`, even if a ``<PackageName>ConfigVersion.cmake``
|
||||
file is present.
|
||||
|
||||
If the ``Config.cmake`` file is found and the
|
||||
optionally-specified version is satisfied, then the CMake
|
||||
:command:`find_package` command considers the package to be
|
||||
found and the entire library package is assumed to be
|
||||
complete as designed.
|
||||
If the ``<PackageName>Config.cmake`` file is found and any version constraint
|
||||
is satisfied, the :command:`find_package` command considers the package to be
|
||||
found, and the entire package is assumed to be complete as designed.
|
||||
|
||||
There may be additional files providing CMake macros or
|
||||
:ref:`imported targets` for you to use. CMake does not
|
||||
enforce any naming convention for these
|
||||
files. They are related to the primary ``Config`` file by
|
||||
use of the CMake :command:`include` command.
|
||||
There may be additional files providing CMake commands or
|
||||
:ref:`imported targets` for you to use. CMake does not enforce any naming
|
||||
convention for these files. They are related to the primary
|
||||
``<PackageName>Config.cmake`` file by use of the CMake :command:`include`
|
||||
command. The ``<PackageName>Config.cmake`` file would typically include
|
||||
these for you, so they won't usually require any additional step other than
|
||||
the call to :command:`find_package`.
|
||||
|
||||
:guide:`Invoking CMake <User Interaction Guide>` with the
|
||||
intent of using a package of third party binaries requires
|
||||
that cmake :command:`find_package` commands succeed in finding
|
||||
the package. If the location of the package is in a directory
|
||||
known to CMake, the :command:`find_package` call should
|
||||
succeed. The directories known to cmake are platform-specific.
|
||||
For example, packages installed on Linux with a standard
|
||||
system package manager will be found in the ``/usr`` prefix
|
||||
automatically. Packages installed in ``Program Files`` on
|
||||
Windows will similarly be found automatically.
|
||||
If the location of the package is in a
|
||||
:ref:`directory known to CMake <search procedure>`, the
|
||||
:command:`find_package` call should succeed. The directories known to CMake
|
||||
are platform-specific. For example, packages installed on Linux with a
|
||||
standard system package manager will be found in the ``/usr`` prefix
|
||||
automatically. Packages installed in ``Program Files`` on Windows will
|
||||
similarly be found automatically.
|
||||
|
||||
Packages which are not found automatically are in locations
|
||||
not predictable to CMake such as ``/opt/mylib`` or
|
||||
``$HOME/dev/prefix``. This is a normal situation and CMake
|
||||
provides several ways for users to specify where to find
|
||||
such libraries.
|
||||
Packages will not be found automatically without help if they are in
|
||||
locations not known to CMake, such as ``/opt/mylib`` or ``$HOME/dev/prefix``.
|
||||
This is a normal situation, and CMake provides several ways for users to
|
||||
specify where to find such libraries.
|
||||
|
||||
The :variable:`CMAKE_PREFIX_PATH` variable may be
|
||||
:ref:`set when invoking CMake <Setting Build Variables>`.
|
||||
It is treated as a list of paths to search for
|
||||
:ref:`Config File Packages`. A package installed in
|
||||
``/opt/somepackage`` will typically install config files
|
||||
such as
|
||||
It is treated as a list of base paths in which to search for
|
||||
:ref:`config files <Config File Packages>`. A package installed in
|
||||
``/opt/somepackage`` will typically install config files such as
|
||||
``/opt/somepackage/lib/cmake/somePackage/SomePackageConfig.cmake``.
|
||||
In that case, ``/opt/somepackage`` should be added to
|
||||
:variable:`CMAKE_PREFIX_PATH`.
|
||||
|
||||
The environment variable ``CMAKE_PREFIX_PATH`` may also be
|
||||
populated with prefixes to search for packages. Like the
|
||||
``PATH`` environment variable, this is a list and needs to use
|
||||
the platform-specific environment variable list item separator
|
||||
(``:`` on Unix and ``;`` on Windows).
|
||||
The environment variable ``CMAKE_PREFIX_PATH`` may also be populated with
|
||||
prefixes to search for packages. Like the ``PATH`` environment variable,
|
||||
this is a list, but it needs to use the platform-specific environment variable
|
||||
list item separator (``:`` on Unix and ``;`` on Windows).
|
||||
|
||||
The :variable:`CMAKE_PREFIX_PATH` variable provides convenience
|
||||
in cases where multiple prefixes need to be specified, or when
|
||||
multiple different package binaries are available in the same
|
||||
prefix. Paths to packages may also be specified by setting
|
||||
variables matching ``<PackageName>_DIR``, such as
|
||||
``SomePackage_DIR``. Note that this is not a prefix but should
|
||||
be a full path to a directory containing a config-style package
|
||||
file, such as ``/opt/somepackage/lib/cmake/SomePackage/`` in
|
||||
the above example.
|
||||
The :variable:`CMAKE_PREFIX_PATH` variable provides convenience in cases
|
||||
where multiple prefixes need to be specified, or when multiple packages
|
||||
are available under the same prefix. Paths to packages may also be
|
||||
specified by setting variables matching ``<PackageName>_DIR``, such as
|
||||
``SomePackage_DIR``. Note that this is not a prefix, but should be a full
|
||||
path to a directory containing a config-style package file, such as
|
||||
``/opt/somepackage/lib/cmake/SomePackage`` in the above example.
|
||||
See the :command:`find_package` documentation for other CMake variables and
|
||||
environment variables that can affect the search.
|
||||
|
||||
Imported Targets from Packages
|
||||
==============================
|
||||
.. _Libraries not Providing Config-file Packages:
|
||||
|
||||
A third-party package which provides config-file packages may
|
||||
also provide :ref:`Imported targets`. These will be
|
||||
specified in files containing configuration-specific file
|
||||
paths relevant to the package, such as debug and release
|
||||
versions of libraries.
|
||||
Find Module Files
|
||||
-----------------
|
||||
|
||||
Often the third-party package documentation will point out the
|
||||
names of imported targets available after a successful
|
||||
``find_package`` for a library. Those imported target names
|
||||
can be used with the :command:`target_link_libraries` command.
|
||||
Packages which do not provide config files can still be found with the
|
||||
:command:`find_package` command, if a ``FindSomePackage.cmake`` file is
|
||||
available. These Find module files are different to config files in that:
|
||||
|
||||
A complete example which makes a simple use of a third party
|
||||
library might look like:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
cmake_minimum_required(VERSION 3.10)
|
||||
project(MyExeProject VERSION 1.0.0)
|
||||
|
||||
find_package(SomePackage REQUIRED)
|
||||
add_executable(MyExe main.cpp)
|
||||
target_link_libraries(MyExe PRIVATE SomePrefix::LibName)
|
||||
|
||||
See :manual:`cmake-buildsystem(7)` for further information
|
||||
about developing a CMake buildsystem.
|
||||
|
||||
Libraries not Providing Config-file Packages
|
||||
--------------------------------------------
|
||||
|
||||
Third-party libraries which do not provide config-file packages
|
||||
can still be found with the :command:`find_package` command, if
|
||||
a ``FindSomePackage.cmake`` file is available.
|
||||
|
||||
These module-file packages are different to config-file packages
|
||||
in that:
|
||||
|
||||
#. They should not be provided by the third party, except
|
||||
perhaps in the form of documentation
|
||||
#. The availability of a ``Find<PackageName>.cmake`` file does
|
||||
not indicate the availability of the binaries themselves.
|
||||
#. CMake does not search the :variable:`CMAKE_PREFIX_PATH` for
|
||||
``Find<PackageName>.cmake`` files. Instead CMake searches
|
||||
for such files in the :variable:`CMAKE_MODULE_PATH`
|
||||
variable. It is common for users to set the
|
||||
:variable:`CMAKE_MODULE_PATH` when running CMake, and it is
|
||||
common for CMake projects to append to
|
||||
:variable:`CMAKE_MODULE_PATH` to allow use of local
|
||||
module-file packages.
|
||||
#. Find module files should not be provided by the package itself.
|
||||
#. The availability of a ``Find<PackageName>.cmake`` file does not indicate
|
||||
the availability of the package, or any particular part of the package.
|
||||
#. CMake does not search the locations specified in the
|
||||
:variable:`CMAKE_PREFIX_PATH` variable for ``Find<PackageName>.cmake``
|
||||
files. Instead, CMake searches for such files in the locations given
|
||||
by the :variable:`CMAKE_MODULE_PATH` variable. It is common for users to
|
||||
set the :variable:`CMAKE_MODULE_PATH` when running CMake, and it is common
|
||||
for CMake projects to append to :variable:`CMAKE_MODULE_PATH` to allow use
|
||||
of local Find module files.
|
||||
#. CMake ships ``Find<PackageName>.cmake`` files for some
|
||||
:manual:`third party packages <cmake-modules(7)>`
|
||||
for convenience in cases where the third party does
|
||||
not provide config-file packages directly. These files are
|
||||
a maintenance burden for CMake, so new Find modules are
|
||||
generally not added to CMake anymore. Third-parties should
|
||||
provide config file packages instead of relying on a Find
|
||||
module to be provided by CMake.
|
||||
:manual:`third party packages <cmake-modules(7)>`. These files are a
|
||||
maintenance burden for CMake, and it is not unusual for these to fall
|
||||
behind the latest releases of the packages they are associated with.
|
||||
In general, new Find modules are not added to CMake any more. Projects
|
||||
should encourage the upstream packages to provide a config file where
|
||||
possible. If that is unsuccessful, the project should provide its own
|
||||
Find module for the package.
|
||||
|
||||
Module-file packages may also provide :ref:`Imported targets`.
|
||||
A complete example which finds such a package might look
|
||||
like:
|
||||
See :ref:`Find Modules` for a detailed discussion of how to write a
|
||||
Find module file.
|
||||
|
||||
.. _Imported Targets from Packages:
|
||||
|
||||
Imported Targets
|
||||
----------------
|
||||
|
||||
Both config files and Find module files can define :ref:`Imported targets`.
|
||||
These will typically have names of the form ``SomePrefix::ThingName``.
|
||||
Where these are available, the project should prefer to use them instead of
|
||||
any CMake variables that may also be provided. Such targets typically carry
|
||||
usage requirements and apply things like header search paths, compiler
|
||||
definitions, etc. automatically to other targets that link to them (e.g. using
|
||||
:command:`target_link_libraries`). This is both more robust and more
|
||||
convenient than trying to apply the same things manually using variables.
|
||||
Check the documentation for the package or Find module to see what imported
|
||||
targets it defines, if any.
|
||||
|
||||
Imported targets should also encapsulate any configuration-specific paths.
|
||||
This includes the location of binaries (libraries, executables), compiler
|
||||
flags, and any other configuration-dependent quantities. Find modules may
|
||||
be less reliable in providing these details than config files.
|
||||
|
||||
A complete example which finds a third party package and uses a library
|
||||
from it might look like the following:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
cmake_minimum_required(VERSION 3.10)
|
||||
project(MyExeProject VERSION 1.0.0)
|
||||
cmake_minimum_required(VERSION 3.10)
|
||||
project(MyExeProject VERSION 1.0.0)
|
||||
|
||||
find_package(PNG REQUIRED)
|
||||
# Make project-provided Find modules available
|
||||
list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
|
||||
|
||||
# Add path to a FindSomePackage.cmake file
|
||||
list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")
|
||||
find_package(SomePackage REQUIRED)
|
||||
find_package(SomePackage REQUIRED)
|
||||
add_executable(MyExe main.cpp)
|
||||
target_link_libraries(MyExe PRIVATE SomePrefix::LibName)
|
||||
|
||||
add_executable(MyExe main.cpp)
|
||||
target_link_libraries(MyExe PRIVATE
|
||||
PNG::PNG
|
||||
SomePrefix::LibName
|
||||
)
|
||||
Note that the above call to :command:`find_package` could be resolved by
|
||||
a config file or a Find module. It uses only the basic arguments supported
|
||||
by the :ref:`basic signature`. A ``FindSomePackage.cmake`` file in the
|
||||
``${CMAKE_CURRENT_SOURCE_DIR}/cmake`` directory would allow the
|
||||
:command:`find_package` command to succeed using module mode, for example.
|
||||
If no such module file is present, the system would be searched for a config
|
||||
file.
|
||||
|
||||
The :variable:`<PackageName>_ROOT` variable is also
|
||||
searched as a prefix for :command:`find_package` calls using
|
||||
module-file packages such as ``FindSomePackage``.
|
||||
|
||||
Downloading And Building From Source With ``FetchContent``
|
||||
==========================================================
|
||||
|
||||
Dependencies do not necessarily have to be pre-built in order to use them
|
||||
with CMake. They can be built from sources as part of the main project.
|
||||
The :module:`FetchContent` module provides functionality to download
|
||||
content (typically sources, but can be anything) and add it to the main
|
||||
project if the dependency also uses CMake. The dependency's sources will
|
||||
be built along with the rest of the project, just as though the sources were
|
||||
part of the project's own sources.
|
||||
|
||||
The general pattern is that the project should first declare all the
|
||||
dependencies it wants to use, then ask for them to be made available.
|
||||
The following demonstrates the principle (see :ref:`fetch-content-examples`
|
||||
for more):
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
include(FetchContent)
|
||||
FetchContent_Declare(
|
||||
googletest
|
||||
GIT_REPOSITORY https://github.com/google/googletest.git
|
||||
GIT_TAG 703bd9caab50b139428cea1aaff9974ebee5742e # release-1.10.0
|
||||
)
|
||||
FetchContent_Declare(
|
||||
Catch2
|
||||
GIT_REPOSITORY https://github.com/catchorg/Catch2.git
|
||||
GIT_TAG de6fe184a9ac1a06895cdd1c9b437f0a0bdf14ad # v2.13.4
|
||||
)
|
||||
FetchContent_MakeAvailable(googletest Catch2)
|
||||
|
||||
Various download methods are supported, including downloading and extracting
|
||||
archives from a URL (a range of archive formats are supported), and a number
|
||||
of repository formats including Git, Subversion, and Mercurial.
|
||||
Custom download, update, and patch commands can also be used to support
|
||||
arbitrary use cases.
|
||||
|
||||
When a dependency is added to the project with :module:`FetchContent`, the
|
||||
project links to the dependency's targets just like any other target from the
|
||||
project. If the dependency provides namespaced targets of the form
|
||||
``SomePrefix::ThingName``, the project should link to those rather than to
|
||||
any non-namespaced targets. See the next section for why this is recommended.
|
||||
|
||||
Not all dependencies can be brought into the project this way. Some
|
||||
dependencies define targets whose names clash with other targets from the
|
||||
project or other dependencies. Concrete executable and library targets
|
||||
created by :command:`add_executable` and :command:`add_library` are global,
|
||||
so each one must be unique across the whole build. If a dependency would
|
||||
add a clashing target name, it cannot be brought directly into the build
|
||||
with this method.
|
||||
|
||||
``FetchContent`` And ``find_package()`` Integration
|
||||
===================================================
|
||||
|
||||
.. versionadded:: 3.24
|
||||
|
||||
Some dependencies support being added by either :command:`find_package` or
|
||||
:module:`FetchContent`. Such dependencies must ensure they define the same
|
||||
namespaced targets in both installed and built-from-source scenarios.
|
||||
A consuming project then links to those namespaced targets and can handle
|
||||
both scenarios transparently, as long as the project does not use anything
|
||||
else that isn't provided by both methods.
|
||||
|
||||
The project can indicate it is happy to accept a dependency by either method
|
||||
using the ``FIND_PACKAGE_ARGS`` option to :command:`FetchContent_Declare`.
|
||||
This allows :command:`FetchContent_MakeAvailable` to try satisfying the
|
||||
dependency with a call to :command:`find_package` first, using the arguments
|
||||
after the ``FIND_PACKAGE_ARGS`` keyword, if any. If that doesn't find the
|
||||
dependency, it is built from source as described previously instead.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
include(FetchContent)
|
||||
FetchContent_Declare(
|
||||
googletest
|
||||
GIT_REPOSITORY https://github.com/google/googletest.git
|
||||
GIT_TAG 703bd9caab50b139428cea1aaff9974ebee5742e # release-1.10.0
|
||||
FIND_PACKAGE_ARGS NAMES GTest
|
||||
)
|
||||
FetchContent_MakeAvailable(googletest)
|
||||
|
||||
add_executable(ThingUnitTest thing_ut.cpp)
|
||||
target_link_libraries(ThingUnitTest GTest::gtest_main)
|
||||
|
||||
The above example calls
|
||||
:command:`find_package(googletest NAMES GTest) <find_package>` first.
|
||||
CMake provides a :module:`FindGTest` module, so if that finds a GTest package
|
||||
installed somewhere, it will make it available, and the dependency will not be
|
||||
built from source. If no GTest package is found, it *will* be built from
|
||||
source. In either case, the ``GTest::gtest_main`` target is expected to be
|
||||
defined, so we link our unit test executable to that target.
|
||||
|
||||
High-level control is also available through the
|
||||
:variable:`FETCHCONTENT_TRY_FIND_PACKAGE_MODE` variable. This can be set to
|
||||
``NEVER`` to disable all redirection to :command:`find_package`. It can be
|
||||
set to ``ALWAYS`` to try :command:`find_package` even if ``FIND_PACKAGE_ARGS``
|
||||
was not specified (this should be used with caution).
|
||||
|
||||
The project might also decide that a particular dependency must be built from
|
||||
source. This might be needed if a patched or unreleased version of the
|
||||
dependency is required, or to satisfy some policy that requires all
|
||||
dependencies to be built from source. The project can enforce this by adding
|
||||
the ``OVERRIDE_FIND_PACKAGE`` keyword to :command:`FetchContent_Declare`.
|
||||
A call to :command:`find_package` for that dependency will then be redirected
|
||||
to :command:`FetchContent_MakeAvailable` instead.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
include(FetchContent)
|
||||
FetchContent_Declare(
|
||||
Catch2
|
||||
URL https://intranet.mycomp.com/vendored/Catch2_2.13.4_patched.tgz
|
||||
URL_HASH MD5=abc123...
|
||||
OVERRIDE_FIND_PACKAGE
|
||||
)
|
||||
|
||||
# The following is automatically redirected to FetchContent_MakeAvailable(Catch2)
|
||||
find_package(Catch2)
|
||||
|
||||
For more advanced use cases, see the
|
||||
:variable:`CMAKE_FIND_PACKAGE_REDIRECTS_DIR` variable.
|
||||
|
||||
.. _dependency_providers_overview:
|
||||
|
||||
Dependency Providers
|
||||
====================
|
||||
|
||||
.. versionadded:: 3.24
|
||||
|
||||
The preceding section discussed techniques that projects can use to specify
|
||||
their dependencies. Ideally, the project shouldn't really care where a
|
||||
dependency comes from, as long as it provides the things it expects (often
|
||||
just some imported targets). The project says what it needs and may also
|
||||
specify where to get it from, in the absence of any other details, so that it
|
||||
can still be built out-of-the-box.
|
||||
|
||||
The developer, on the other hand, may be much more interested in controlling
|
||||
*how* a dependency is provided to the project. You might want to use a
|
||||
particular version of a package that you built yourself. You might want
|
||||
to use a third party package manager. You might want to redirect some
|
||||
requests to a different URL on a system you control for security or
|
||||
performance reasons. CMake supports these sort of scenarios through
|
||||
:ref:`dependency_providers`.
|
||||
|
||||
A dependency provider can be set to intercept :command:`find_package` and
|
||||
:command:`FetchContent_MakeAvailable` calls. The provider is given an
|
||||
opportunity to satisfy such requests before falling back to the built-in
|
||||
implementation if the provider doesn't fulfill it.
|
||||
|
||||
Only one dependency provider can be set, and it can only be set at a very
|
||||
specific point early in the CMake run.
|
||||
The :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable lists CMake files
|
||||
that will be read while processing the first :command:`project()` call (and
|
||||
only that call). This is the only time a dependency provider may be set.
|
||||
At most, one single provider is expected to be used throughout the whole
|
||||
project.
|
||||
|
||||
For some scenarios, the user wouldn't need to know the details of how the
|
||||
dependency provider is set. A third party may provide a file that can be
|
||||
added to :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES`, which will set up
|
||||
the dependency provider on the user's behalf. This is the recommended
|
||||
approach for package managers. The developer can use such a file like so::
|
||||
|
||||
cmake -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=/path/to/package_manager/setup.cmake ...
|
||||
|
||||
For details on how to implement your own custom dependency provider, see the
|
||||
:command:`cmake_language(SET_DEPENDENCY_PROVIDER)` command.
|
||||
|
@ -1040,24 +1040,26 @@ Additionally, IDEs will show the source files as part of the target for
|
||||
interactive reading and editing.
|
||||
|
||||
A primary use-case for ``INTERFACE`` libraries is header-only libraries.
|
||||
Since CMake 3.23, header files may be associated with a library by adding
|
||||
them to a header set using the :command:`target_sources` command:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
add_library(Eigen INTERFACE
|
||||
src/eigen.h
|
||||
src/vector.h
|
||||
src/matrix.h
|
||||
)
|
||||
target_include_directories(Eigen INTERFACE
|
||||
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
|
||||
$<INSTALL_INTERFACE:include/Eigen>
|
||||
add_library(Eigen INTERFACE)
|
||||
|
||||
target_sources(Eigen INTERFACE
|
||||
FILE_SET HEADERS
|
||||
BASE_DIRS src
|
||||
FILES src/eigen.h src/vector.h src/matrix.h
|
||||
)
|
||||
|
||||
add_executable(exe1 exe1.cpp)
|
||||
target_link_libraries(exe1 Eigen)
|
||||
|
||||
Here, the usage requirements from the ``Eigen`` target are consumed and used
|
||||
when compiling, but it has no effect on linking.
|
||||
When we specify the ``FILE_SET`` here, the ``BASE_DIRS`` we define automatically
|
||||
become include directories in the usage requirements for the target ``Eigen``.
|
||||
The usage requirements from the target are consumed and used when compiling, but
|
||||
have no effect on linking.
|
||||
|
||||
Another use-case is to employ an entirely target-focussed design for usage
|
||||
requirements:
|
||||
@ -1081,26 +1083,25 @@ This way, the build specification of ``exe1`` is expressed entirely as linked
|
||||
targets, and the complexity of compiler-specific flags is encapsulated in an
|
||||
``INTERFACE`` library target.
|
||||
|
||||
``INTERFACE`` libraries may be installed and exported. Any content they refer
|
||||
to must be installed separately:
|
||||
``INTERFACE`` libraries may be installed and exported. We can install the
|
||||
default header set along with the target:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
set(Eigen_headers
|
||||
src/eigen.h
|
||||
src/vector.h
|
||||
src/matrix.h
|
||||
)
|
||||
add_library(Eigen INTERFACE ${Eigen_headers})
|
||||
target_include_directories(Eigen INTERFACE
|
||||
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
|
||||
$<INSTALL_INTERFACE:include/Eigen>
|
||||
add_library(Eigen INTERFACE)
|
||||
|
||||
target_sources(Eigen INTERFACE
|
||||
FILE_SET HEADERS
|
||||
BASE_DIRS src
|
||||
FILES src/eigen.h src/vector.h src/matrix.h
|
||||
)
|
||||
|
||||
install(TARGETS Eigen EXPORT eigenExport)
|
||||
install(TARGETS Eigen EXPORT eigenExport
|
||||
FILE_SET HEADERS DESTINATION include/Eigen)
|
||||
install(EXPORT eigenExport NAMESPACE Upstream::
|
||||
DESTINATION lib/cmake/Eigen
|
||||
)
|
||||
install(FILES ${Eigen_headers}
|
||||
DESTINATION include/Eigen
|
||||
)
|
||||
|
||||
Here, the headers defined in the header set are installed to ``include/Eigen``.
|
||||
The install destination automatically becomes an include directory that is a
|
||||
usage requirement for consumers.
|
||||
|
@ -242,6 +242,69 @@ backwards compatibility for any old names that were actually in use.
|
||||
Make sure you comment them as deprecated, so that no-one starts using
|
||||
them.
|
||||
|
||||
.. _`Find Using Windows Registry`:
|
||||
|
||||
Find Using Windows Registry
|
||||
---------------------------
|
||||
|
||||
.. versionchanged:: 3.24
|
||||
|
||||
Options ``HINTS`` and ``PATHS`` of :command:`find_file`,
|
||||
:command:`find_library`, :command:`find_path`, :command:`find_program`, and
|
||||
:command:`find_package` commands offer the possibility, on ``Windows``
|
||||
platform, to query the registry.
|
||||
|
||||
The formal syntax, as specified using
|
||||
`BNF <https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form>`_ notation with
|
||||
the regular extensions, for registry query is the following:
|
||||
|
||||
.. raw:: latex
|
||||
|
||||
\begin{small}
|
||||
|
||||
.. productionlist::
|
||||
registry_query: '[' `sep_definition`? `root_key`
|
||||
: ((`key_separator` `sub_key`)? (`value_separator` `value_name`_)?)? ']'
|
||||
sep_definition: '{' `value_separator` '}'
|
||||
root_key: 'HKLM' | 'HKEY_LOCAL_MACHINE' | 'HKCU' | 'HKEY_CURRENT_USER' |
|
||||
: 'HKCR' | 'HKEY_CLASSES_ROOT' | 'HKCC' | 'HKEY_CURRENT_CONFIG' |
|
||||
: 'HKU' | 'HKEY_USERS'
|
||||
sub_key: `element` (`key_separator` `element`)*
|
||||
key_separator: '/' | '\\'
|
||||
value_separator: `element` | ';'
|
||||
value_name: `element` | '(default)'
|
||||
element: `character`\+
|
||||
character: <any character except `key_separator` and `value_separator`>
|
||||
|
||||
.. raw:: latex
|
||||
|
||||
\end{small}
|
||||
|
||||
The :token:`sep_definition` optional item offers the possibility to specify
|
||||
the string used to separate the :token:`sub_key` from the :token:`value_name`
|
||||
item. If not specified, the character ``;`` is used. Multiple
|
||||
:token:`registry_query` items can be specified as part of a path.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
# example using default separator
|
||||
find_file(... PATHS "/root/[HKLM/Stuff;InstallDir]/lib[HKLM\\\\Stuff;Architecture]")
|
||||
|
||||
# example using different specified separators
|
||||
find_library(... HINTS "/root/[{|}HKCU/Stuff|InstallDir]/lib[{@@}HKCU\\\\Stuff@@Architecture]")
|
||||
|
||||
If the :token:`value_name` item is not specified or has the special name
|
||||
``(default)``, the content of the default value, if any, will be returned. The
|
||||
supported types for the :token:`value_name` are:
|
||||
|
||||
* ``REG_SZ``.
|
||||
* ``REG_EXPAND_SZ``. The returned data is expanded.
|
||||
* ``REG_DWORD``.
|
||||
* ``REG_QWORD``.
|
||||
|
||||
When the registry query failed, typically because the key does not exist or
|
||||
the data type is not supported, the string ``/REGISTRY-NOTFOUND`` is substituted
|
||||
to the ``[]`` query expression.
|
||||
|
||||
A Sample Find Module
|
||||
--------------------
|
||||
|
@ -28,9 +28,11 @@ Environment Variables that Control the Build
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
/envvar/ADSP_ROOT
|
||||
/envvar/CMAKE_APPLE_SILICON_PROCESSOR
|
||||
/envvar/CMAKE_BUILD_PARALLEL_LEVEL
|
||||
/envvar/CMAKE_BUILD_TYPE
|
||||
/envvar/CMAKE_COLOR_DIAGNOSTICS
|
||||
/envvar/CMAKE_CONFIGURATION_TYPES
|
||||
/envvar/CMAKE_CONFIG_TYPE
|
||||
/envvar/CMAKE_EXPORT_COMPILE_COMMANDS
|
||||
|
File diff suppressed because it is too large
Load Diff
@ -582,7 +582,8 @@ Scope
|
||||
They are never cached.
|
||||
|
||||
References
|
||||
`Variable References`_ have the form ``$ENV{<variable>}``.
|
||||
`Variable References`_ have the form ``$ENV{<variable>}``, using the
|
||||
:variable:`ENV` operator.
|
||||
|
||||
Initialization
|
||||
Initial values of the CMake environment variables are those of
|
||||
@ -594,6 +595,13 @@ Initialization
|
||||
Changed values are not written back to the calling process,
|
||||
and they are not seen by subsequent build or test processes.
|
||||
|
||||
See the :ref:`cmake -E env <Run a Command-Line Tool>` command-line
|
||||
tool to run a command in a modified environment.
|
||||
|
||||
Inspection
|
||||
See the :ref:`cmake -E environment <Run a Command-Line Tool>` command-line
|
||||
tool to display all current environment variables.
|
||||
|
||||
The :manual:`cmake-env-variables(7)` manual documents environment
|
||||
variables that have special meaning to CMake.
|
||||
|
||||
|
@ -317,7 +317,6 @@ used directly.
|
||||
/module/CPackFreeBSD
|
||||
/module/CPackNSIS
|
||||
/module/CPackNuGet
|
||||
/module/CPackPackageMaker
|
||||
/module/CPackProductBuild
|
||||
/module/CPackRPM
|
||||
/module/CPackWIX
|
||||
|
@ -52,6 +52,23 @@ to determine whether to report an error on use of deprecated macros or
|
||||
functions.
|
||||
|
||||
|
||||
Policies Introduced by CMake 3.24
|
||||
=================================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
CMP0139: The if() command supports path comparisons using PATH_EQUAL operator. </policy/CMP0139>
|
||||
CMP0138: CheckIPOSupported uses flags from calling project. </policy/CMP0138>
|
||||
CMP0137: try_compile() passes platform variables in project mode. </policy/CMP0137>
|
||||
CMP0136: Watcom runtime library flags are selected by an abstraction. </policy/CMP0136>
|
||||
CMP0135: ExternalProject ignores timestamps in archives by default for the URL download method. </policy/CMP0135>
|
||||
CMP0134: Fallback to \"HOST\" Windows registry view when \"TARGET\" view is not usable. </policy/CMP0134>
|
||||
CMP0133: The CPack module disables SLA by default in the CPack DragNDrop Generator. </policy/CMP0133>
|
||||
CMP0132: Do not set compiler environment variables on first run. </policy/CMP0132>
|
||||
CMP0131: LINK_LIBRARIES supports the LINK_ONLY generator expression. </policy/CMP0131>
|
||||
CMP0130: while() diagnoses condition evaluation errors. </policy/CMP0130>
|
||||
|
||||
Policies Introduced by CMake 3.23
|
||||
=================================
|
||||
|
||||
|
@ -42,7 +42,22 @@ The root object recognizes the following fields:
|
||||
``version``
|
||||
|
||||
A required integer representing the version of the JSON schema.
|
||||
The supported versions are ``1``, ``2``, ``3``, and ``4``.
|
||||
The supported versions are:
|
||||
|
||||
``1``
|
||||
.. versionadded:: 3.19
|
||||
|
||||
``2``
|
||||
.. versionadded:: 3.20
|
||||
|
||||
``3``
|
||||
.. versionadded:: 3.21
|
||||
|
||||
``4``
|
||||
.. versionadded:: 3.23
|
||||
|
||||
``5``
|
||||
.. versionadded:: 3.24
|
||||
|
||||
``cmakeMinimumRequired``
|
||||
|
||||
@ -715,6 +730,12 @@ that may contain the following fields:
|
||||
bytes. Equivalent to passing ``--test-output-size-failed`` on the
|
||||
command line.
|
||||
|
||||
``testOutputTruncation``
|
||||
|
||||
An optional string specifying the test output truncation mode. Equivalent
|
||||
to passing ``--test-output-truncation`` on the command line."
|
||||
This is allowed in preset files specifying version ``5`` or above.
|
||||
|
||||
``maxTestNameWidth``
|
||||
|
||||
An optional integer specifying the maximum width of a test name to
|
||||
@ -1062,6 +1083,17 @@ Recognized macros include:
|
||||
|
||||
A literal dollar sign (``$``).
|
||||
|
||||
``${pathListSep}``
|
||||
|
||||
Native character for separating lists of paths, such as ``:`` or ``;``.
|
||||
|
||||
For example, by setting ``PATH`` to
|
||||
``/path/to/ninja/bin${pathListSep}$env{PATH}``, ``${pathListSep}`` will
|
||||
expand to the underlying operating system's character used for
|
||||
concatenation in ``PATH``.
|
||||
|
||||
This is allowed in preset files specifying version ``5`` or above.
|
||||
|
||||
``$env{<variable-name>}``
|
||||
|
||||
Environment variable with name ``<variable-name>``. The variable name may
|
||||
|
@ -171,6 +171,7 @@ Properties on Targets
|
||||
/prop_tgt/COMPILE_PDB_NAME_CONFIG
|
||||
/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY
|
||||
/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG
|
||||
/prop_tgt/COMPILE_WARNING_AS_ERROR
|
||||
/prop_tgt/CONFIG_OUTPUT_NAME
|
||||
/prop_tgt/CONFIG_POSTFIX
|
||||
/prop_tgt/CROSSCOMPILING_EMULATOR
|
||||
@ -262,10 +263,13 @@ Properties on Targets
|
||||
/prop_tgt/INTERFACE_COMPILE_FEATURES
|
||||
/prop_tgt/INTERFACE_COMPILE_OPTIONS
|
||||
/prop_tgt/INTERFACE_HEADER_SETS
|
||||
/prop_tgt/INTERFACE_HEADER_SETS_TO_VERIFY
|
||||
/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES
|
||||
/prop_tgt/INTERFACE_LINK_DEPENDS
|
||||
/prop_tgt/INTERFACE_LINK_DIRECTORIES
|
||||
/prop_tgt/INTERFACE_LINK_LIBRARIES
|
||||
/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT
|
||||
/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
|
||||
/prop_tgt/INTERFACE_LINK_OPTIONS
|
||||
/prop_tgt/INTERFACE_POSITION_INDEPENDENT_CODE
|
||||
/prop_tgt/INTERFACE_PRECOMPILE_HEADERS
|
||||
@ -306,6 +310,8 @@ Properties on Targets
|
||||
/prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG
|
||||
/prop_tgt/LINK_LIBRARIES
|
||||
/prop_tgt/LINK_LIBRARIES_ONLY_TARGETS
|
||||
/prop_tgt/LINK_LIBRARY_OVERRIDE
|
||||
/prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY
|
||||
/prop_tgt/LINK_OPTIONS
|
||||
/prop_tgt/LINK_SEARCH_END_STATIC
|
||||
/prop_tgt/LINK_SEARCH_START_STATIC
|
||||
@ -376,6 +382,7 @@ Properties on Targets
|
||||
/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE
|
||||
/prop_tgt/UNITY_BUILD_MODE
|
||||
/prop_tgt/UNITY_BUILD_UNIQUE_ID
|
||||
/prop_tgt/VERIFY_INTERFACE_HEADER_SETS
|
||||
/prop_tgt/VERSION
|
||||
/prop_tgt/VISIBILITY_INLINES_HIDDEN
|
||||
/prop_tgt/VS_CONFIGURATION_TYPE
|
||||
@ -389,6 +396,7 @@ Properties on Targets
|
||||
/prop_tgt/VS_DOTNET_REFERENCEPROP_refname_TAG_tagname
|
||||
/prop_tgt/VS_DOTNET_REFERENCES
|
||||
/prop_tgt/VS_DOTNET_REFERENCES_COPY_LOCAL
|
||||
/prop_tgt/VS_DOTNET_STARTUP_OBJECT
|
||||
/prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION
|
||||
/prop_tgt/VS_DPI_AWARE
|
||||
/prop_tgt/VS_GLOBAL_KEYWORD
|
||||
@ -400,6 +408,7 @@ Properties on Targets
|
||||
/prop_tgt/VS_JUST_MY_CODE_DEBUGGING
|
||||
/prop_tgt/VS_KEYWORD
|
||||
/prop_tgt/VS_MOBILE_EXTENSIONS_VERSION
|
||||
/prop_tgt/VS_NO_COMPILE_BATCHING
|
||||
/prop_tgt/VS_NO_SOLUTION_DEPLOY
|
||||
/prop_tgt/VS_PACKAGE_REFERENCES
|
||||
/prop_tgt/VS_PLATFORM_TOOLSET
|
||||
@ -416,6 +425,7 @@ Properties on Targets
|
||||
/prop_tgt/VS_WINRT_COMPONENT
|
||||
/prop_tgt/VS_WINRT_EXTENSIONS
|
||||
/prop_tgt/VS_WINRT_REFERENCES
|
||||
/prop_tgt/WATCOM_RUNTIME_LIBRARY
|
||||
/prop_tgt/WIN32_EXECUTABLE
|
||||
/prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS
|
||||
/prop_tgt/XCODE_ATTRIBUTE_an-attribute
|
||||
@ -451,6 +461,7 @@ Properties on Targets
|
||||
/prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP
|
||||
/prop_tgt/XCODE_SCHEME_WORKING_DIRECTORY
|
||||
/prop_tgt/XCODE_SCHEME_ZOMBIE_OBJECTS
|
||||
/prop_tgt/XCODE_XCCONFIG
|
||||
/prop_tgt/XCTEST
|
||||
|
||||
.. _`Test Properties`:
|
||||
|
@ -301,6 +301,28 @@ Windows Store may look like this:
|
||||
set(CMAKE_SYSTEM_NAME WindowsStore)
|
||||
set(CMAKE_SYSTEM_VERSION 8.1)
|
||||
|
||||
.. _`Cross Compiling for ADSP SHARC/Blackfin`:
|
||||
|
||||
Cross Compiling for ADSP SHARC/Blackfin
|
||||
---------------------------------------
|
||||
|
||||
Cross-compiling for ADSP SHARC or Blackfin can be configured
|
||||
by setting the :variable:`CMAKE_SYSTEM_NAME` variable to ``ADSP``
|
||||
and the :variable:`CMAKE_SYSTEM_PROCESSOR` variable
|
||||
to the "part number", excluding the ``ADSP-`` prefix,
|
||||
for example, ``21594``, ``SC589``, etc.
|
||||
This value is case insensitive.
|
||||
|
||||
CMake will automatically search for CCES or VDSP++ installs
|
||||
in their default install locations
|
||||
and select the most recent version found.
|
||||
CCES will be selected over VDSP++ if both are installed.
|
||||
Custom install paths can be set via the :variable:`CMAKE_ADSP_ROOT` variable
|
||||
or the :envvar:`ADSP_ROOT` environment variable.
|
||||
|
||||
The compiler (``cc21k`` vs. ``ccblkfn``) is selected automatically
|
||||
based on the :variable:`CMAKE_SYSTEM_PROCESSOR` value provided.
|
||||
|
||||
.. _`Cross Compiling for Android`:
|
||||
|
||||
Cross Compiling for Android
|
||||
|
@ -59,6 +59,7 @@ Variables that Provide Information
|
||||
/variable/CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES
|
||||
/variable/CMAKE_FIND_DEBUG_MODE
|
||||
/variable/CMAKE_FIND_PACKAGE_NAME
|
||||
/variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR
|
||||
/variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION
|
||||
/variable/CMAKE_FIND_PACKAGE_SORT_ORDER
|
||||
/variable/CMAKE_GENERATOR
|
||||
@ -172,6 +173,7 @@ Variables that Change Behavior
|
||||
/variable/CMAKE_CODEBLOCKS_COMPILER_ID
|
||||
/variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES
|
||||
/variable/CMAKE_CODELITE_USE_TARGETS
|
||||
/variable/CMAKE_COLOR_DIAGNOSTICS
|
||||
/variable/CMAKE_COLOR_MAKEFILE
|
||||
/variable/CMAKE_CONFIGURATION_TYPES
|
||||
/variable/CMAKE_DEPENDS_IN_PROJECT_ONLY
|
||||
@ -197,6 +199,7 @@ Variables that Change Behavior
|
||||
/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY
|
||||
/variable/CMAKE_FIND_PACKAGE_PREFER_CONFIG
|
||||
/variable/CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS
|
||||
/variable/CMAKE_FIND_PACKAGE_TARGETS_GLOBAL
|
||||
/variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE
|
||||
/variable/CMAKE_FIND_ROOT_PATH
|
||||
/variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE
|
||||
@ -204,6 +207,7 @@ Variables that Change Behavior
|
||||
/variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE
|
||||
/variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM
|
||||
/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH
|
||||
/variable/CMAKE_FIND_USE_INSTALL_PREFIX
|
||||
/variable/CMAKE_FIND_USE_CMAKE_PATH
|
||||
/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH
|
||||
/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY
|
||||
@ -239,6 +243,7 @@ Variables that Change Behavior
|
||||
/variable/CMAKE_PROJECT_INCLUDE_BEFORE
|
||||
/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE
|
||||
/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE
|
||||
/variable/CMAKE_PROJECT_TOP_LEVEL_INCLUDES
|
||||
/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName
|
||||
/variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY
|
||||
/variable/CMAKE_STAGING_PREFIX
|
||||
@ -283,6 +288,7 @@ Variables that Change Behavior
|
||||
/variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP
|
||||
/variable/CMAKE_XCODE_SCHEME_WORKING_DIRECTORY
|
||||
/variable/CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS
|
||||
/variable/CMAKE_XCODE_XCCONFIG
|
||||
/variable/PackageName_ROOT
|
||||
|
||||
Variables that Describe the System
|
||||
@ -344,6 +350,7 @@ Variables that Control the Build
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
/variable/CMAKE_ADSP_ROOT
|
||||
/variable/CMAKE_AIX_EXPORT_ALL_SYMBOLS
|
||||
/variable/CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS
|
||||
/variable/CMAKE_ANDROID_API
|
||||
@ -395,6 +402,7 @@ Variables that Control the Build
|
||||
/variable/CMAKE_BUILD_WITH_INSTALL_RPATH
|
||||
/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY
|
||||
/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG
|
||||
/variable/CMAKE_COMPILE_WARNING_AS_ERROR
|
||||
/variable/CMAKE_CONFIG_POSTFIX
|
||||
/variable/CMAKE_CROSS_CONFIGS
|
||||
/variable/CMAKE_CTEST_ARGUMENTS
|
||||
@ -437,7 +445,11 @@ Variables that Control the Build
|
||||
/variable/CMAKE_LANG_CPPCHECK
|
||||
/variable/CMAKE_LANG_CPPLINT
|
||||
/variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE
|
||||
/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE
|
||||
/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE_SUPPORTED
|
||||
/variable/CMAKE_LANG_LINKER_LAUNCHER
|
||||
/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE
|
||||
/variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE_SUPPORTED
|
||||
/variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG
|
||||
/variable/CMAKE_LANG_LINK_LIBRARY_FLAG
|
||||
/variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG
|
||||
@ -447,9 +459,13 @@ Variables that Control the Build
|
||||
/variable/CMAKE_LIBRARY_PATH_FLAG
|
||||
/variable/CMAKE_LINK_DEF_FILE_FLAG
|
||||
/variable/CMAKE_LINK_DEPENDS_NO_SHARED
|
||||
/variable/CMAKE_LINK_GROUP_USING_FEATURE
|
||||
/variable/CMAKE_LINK_GROUP_USING_FEATURE_SUPPORTED
|
||||
/variable/CMAKE_LINK_INTERFACE_LIBRARIES
|
||||
/variable/CMAKE_LINK_LIBRARY_FILE_FLAG
|
||||
/variable/CMAKE_LINK_LIBRARY_FLAG
|
||||
/variable/CMAKE_LINK_LIBRARY_USING_FEATURE
|
||||
/variable/CMAKE_LINK_LIBRARY_USING_FEATURE_SUPPORTED
|
||||
/variable/CMAKE_LINK_WHAT_YOU_USE
|
||||
/variable/CMAKE_LINK_WHAT_YOU_USE_CHECK
|
||||
/variable/CMAKE_MACOSX_BUNDLE
|
||||
@ -487,17 +503,20 @@ Variables that Control the Build
|
||||
/variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT
|
||||
/variable/CMAKE_STATIC_LINKER_FLAGS_INIT
|
||||
/variable/CMAKE_TRY_COMPILE_CONFIGURATION
|
||||
/variable/CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES
|
||||
/variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES
|
||||
/variable/CMAKE_TRY_COMPILE_TARGET_TYPE
|
||||
/variable/CMAKE_UNITY_BUILD
|
||||
/variable/CMAKE_UNITY_BUILD_BATCH_SIZE
|
||||
/variable/CMAKE_UNITY_BUILD_UNIQUE_ID
|
||||
/variable/CMAKE_USE_RELATIVE_PATHS
|
||||
/variable/CMAKE_VERIFY_INTERFACE_HEADER_SETS
|
||||
/variable/CMAKE_VISIBILITY_INLINES_HIDDEN
|
||||
/variable/CMAKE_VS_GLOBALS
|
||||
/variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD
|
||||
/variable/CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD
|
||||
/variable/CMAKE_VS_JUST_MY_CODE_DEBUGGING
|
||||
/variable/CMAKE_VS_NO_COMPILE_BATCHING
|
||||
/variable/CMAKE_VS_SDK_EXCLUDE_DIRECTORIES
|
||||
/variable/CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES
|
||||
/variable/CMAKE_VS_SDK_INCLUDE_DIRECTORIES
|
||||
@ -506,6 +525,7 @@ Variables that Control the Build
|
||||
/variable/CMAKE_VS_SDK_REFERENCE_DIRECTORIES
|
||||
/variable/CMAKE_VS_SDK_SOURCE_DIRECTORIES
|
||||
/variable/CMAKE_VS_WINRT_BY_DEFAULT
|
||||
/variable/CMAKE_WATCOM_RUNTIME_LIBRARY
|
||||
/variable/CMAKE_WIN32_EXECUTABLE
|
||||
/variable/CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS
|
||||
/variable/CMAKE_XCODE_ATTRIBUTE_an-attribute
|
||||
@ -633,6 +653,7 @@ Variables for CTest
|
||||
/variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_ERRORS
|
||||
/variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS
|
||||
/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE
|
||||
/variable/CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION
|
||||
/variable/CTEST_CUSTOM_MEMCHECK_IGNORE
|
||||
/variable/CTEST_CUSTOM_POST_MEMCHECK
|
||||
/variable/CTEST_CUSTOM_POST_TEST
|
||||
|
@ -197,6 +197,13 @@ Options
|
||||
|
||||
.. include:: OPTIONS_BUILD.txt
|
||||
|
||||
``--fresh``
|
||||
.. versionadded:: 3.24
|
||||
|
||||
Perform a fresh configuration of the build tree.
|
||||
This removes any existing ``CMakeCache.txt`` file and associated
|
||||
``CMakeFiles/`` directory, and recreates them from scratch.
|
||||
|
||||
``-L[A][H]``
|
||||
List non-advanced cached variables.
|
||||
|
||||
@ -326,7 +333,8 @@ Options
|
||||
"cmd": "add_executable",
|
||||
"args": ["foo", "bar"],
|
||||
"time": 1579512535.9687231,
|
||||
"frame": 2
|
||||
"frame": 2,
|
||||
"global_frame": 4
|
||||
}
|
||||
|
||||
The members are:
|
||||
@ -336,7 +344,13 @@ Options
|
||||
was called.
|
||||
|
||||
``line``
|
||||
The line in ``file`` of the function call.
|
||||
The line in ``file`` where the function call begins.
|
||||
|
||||
``line_end``
|
||||
If the function call spans multiple lines, this field will
|
||||
be set to the line where the function call ends. If the function
|
||||
calls spans a single line, this field will be unset. This field
|
||||
was added in minor version 2 of the ``json-v1`` format.
|
||||
|
||||
``defer``
|
||||
Optional member that is present when the function call was deferred
|
||||
@ -353,7 +367,13 @@ Options
|
||||
Timestamp (seconds since epoch) of the function call.
|
||||
|
||||
``frame``
|
||||
Stack frame depth of the function that was called.
|
||||
Stack frame depth of the function that was called, within the
|
||||
context of the ``CMakeLists.txt`` being processed currently.
|
||||
|
||||
``global_frame``
|
||||
Stack frame depth of the function that was called, tracked globally
|
||||
across all ``CMakeLists.txt`` files involved in the trace. This field
|
||||
was added in minor version 2 of the ``json-v1`` format.
|
||||
|
||||
Additionally, the first JSON document outputted contains the
|
||||
``version`` key for the current major and minor version of the
|
||||
@ -365,7 +385,7 @@ Options
|
||||
{
|
||||
"version": {
|
||||
"major": 1,
|
||||
"minor": 1
|
||||
"minor": 2
|
||||
}
|
||||
}
|
||||
|
||||
@ -406,6 +426,11 @@ Options
|
||||
in :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR`.
|
||||
This flag tells CMake to warn about other files as well.
|
||||
|
||||
``--compile-no-warning-as-error``
|
||||
Ignore target property :prop_tgt:`COMPILE_WARNING_AS_ERROR` and variable
|
||||
:variable:`CMAKE_COMPILE_WARNING_AS_ERROR`, preventing warnings from being
|
||||
treated as errors on compile.
|
||||
|
||||
``--profiling-output=<path>``
|
||||
Used in conjunction with ``--profiling-format`` to output to a given path.
|
||||
|
||||
@ -599,6 +624,8 @@ in the set of :variable:`CMAKE_ARGV<n> <CMAKE_ARGV0>` variables passed to the
|
||||
script (including the ``--`` itself).
|
||||
|
||||
|
||||
.. _`Run a Command-Line Tool`:
|
||||
|
||||
Run a Command-Line Tool
|
||||
=======================
|
||||
|
||||
@ -673,11 +700,17 @@ Available commands are:
|
||||
``true`` if cmake supports server-mode and ``false`` otherwise.
|
||||
Always false since CMake 3.20.
|
||||
|
||||
``cat <files>...``
|
||||
``cat [--] <files>...``
|
||||
.. versionadded:: 3.18
|
||||
|
||||
Concatenate files and print on the standard output.
|
||||
|
||||
.. versionadded:: 3.24
|
||||
Added support for the double dash argument ``--``. This basic implementation
|
||||
of ``cat`` does not support any options, so using a option starting with
|
||||
``-`` will result in an error. Use ``--`` to indicate the end of options, in
|
||||
case a file starts with ``-``.
|
||||
|
||||
``chdir <dir> <cmd> [<arg>...]``
|
||||
Change the current working directory and run a command.
|
||||
|
||||
@ -746,11 +779,16 @@ Available commands are:
|
||||
``echo_append [<string>...]``
|
||||
Displays arguments as text but no new line.
|
||||
|
||||
``env [--unset=NAME]... [NAME=VALUE]... COMMAND [ARG]...``
|
||||
``env [--unset=NAME ...] [NAME=VALUE ...] [--] <command> [<arg>...]``
|
||||
.. versionadded:: 3.1
|
||||
|
||||
Run command in a modified environment.
|
||||
|
||||
.. versionadded:: 3.24
|
||||
Added support for the double dash argument ``--``. Use ``--`` to stop
|
||||
interpreting options/environment variables and treat the next argument as
|
||||
the command, even if it start with ``-`` or contains a ``=``.
|
||||
|
||||
``environment``
|
||||
Display the current environment variables.
|
||||
|
||||
@ -843,16 +881,16 @@ Available commands are:
|
||||
Rename a file or directory (on one volume). If file with the ``<newname>`` name
|
||||
already exists, then it will be silently replaced.
|
||||
|
||||
``rm [-rRf] <file> <dir>...``
|
||||
``rm [-rRf] [--] <file|dir>...``
|
||||
.. versionadded:: 3.17
|
||||
|
||||
Remove the files ``<file>`` or directories ``<dir>``.
|
||||
|
||||
Use ``-r`` or ``-R`` to remove directories and their contents recursively.
|
||||
If any of the listed files/directories do not exist, the command returns a
|
||||
non-zero exit code, but no message is logged. The ``-f`` option changes
|
||||
the behavior to return a zero exit code (i.e. success) in such
|
||||
situations instead.
|
||||
situations instead. Use ``--`` to stop interpreting options and treat all
|
||||
remaining arguments as paths, even if they start with ``-``.
|
||||
|
||||
``server``
|
||||
Launch :manual:`cmake-server(7)` mode.
|
||||
@ -924,6 +962,12 @@ Available commands are:
|
||||
|
||||
Specify modification time recorded in tarball entries.
|
||||
|
||||
``--touch``
|
||||
.. versionadded:: 3.24
|
||||
|
||||
Use current local timestamp instead of extracting file timestamps
|
||||
from the archive.
|
||||
|
||||
``--``
|
||||
.. versionadded:: 3.1
|
||||
|
||||
@ -1022,6 +1066,18 @@ To view the presets available for a project, use
|
||||
|
||||
cmake <source-dir> --list-presets
|
||||
|
||||
|
||||
.. _`CMake Exit Code`:
|
||||
|
||||
Return Value (Exit Code)
|
||||
========================
|
||||
|
||||
Upon regular termination, the ``cmake`` executable returns the exit code ``0``.
|
||||
|
||||
If termination is caused by the command :command:`message(FATAL_ERROR)`,
|
||||
or another error condition, then a non-zero exit code is returned.
|
||||
|
||||
|
||||
See Also
|
||||
========
|
||||
|
||||
|
@ -357,11 +357,21 @@ See `Build and Test Mode`_.
|
||||
Specify the directory in which to look for tests.
|
||||
|
||||
``--test-output-size-passed <size>``
|
||||
.. versionadded:: 3.4
|
||||
|
||||
Limit the output for passed tests to ``<size>`` bytes.
|
||||
|
||||
``--test-output-size-failed <size>``
|
||||
.. versionadded:: 3.4
|
||||
|
||||
Limit the output for failed tests to ``<size>`` bytes.
|
||||
|
||||
``--test-output-truncation <mode>``
|
||||
.. versionadded:: 3.24
|
||||
|
||||
Truncate ``tail`` (default), ``middle`` or ``head`` of test output once
|
||||
maximum output size is reached.
|
||||
|
||||
``--overwrite``
|
||||
Overwrite CTest configuration option.
|
||||
|
||||
|
@ -1,5 +1,5 @@
|
||||
{
|
||||
"version": 4,
|
||||
"version": 5,
|
||||
"cmakeMinimumRequired": {
|
||||
"major": 3,
|
||||
"minor": 23,
|
||||
|
@ -57,6 +57,21 @@
|
||||
"include": { "$ref": "#/definitions/include"}
|
||||
},
|
||||
"additionalProperties": false
|
||||
},
|
||||
{
|
||||
"properties": {
|
||||
"version": {
|
||||
"const": 5,
|
||||
"description": "A required integer representing the version of the JSON schema."
|
||||
},
|
||||
"cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"},
|
||||
"vendor": { "$ref": "#/definitions/vendor" },
|
||||
"configurePresets": { "$ref": "#/definitions/configurePresetsV3"},
|
||||
"buildPresets": { "$ref": "#/definitions/buildPresetsV4"},
|
||||
"testPresets": { "$ref": "#/definitions/testPresetsV5"},
|
||||
"include": { "$ref": "#/definitions/include"}
|
||||
},
|
||||
"additionalProperties": false
|
||||
}
|
||||
],
|
||||
"required": [
|
||||
@ -673,6 +688,28 @@
|
||||
"additionalProperties": false
|
||||
}
|
||||
},
|
||||
"testPresetsItemsV5": {
|
||||
"type": "array",
|
||||
"description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 5 and higher.",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"output": {
|
||||
"type": "object",
|
||||
"description": "An optional object specifying output options.",
|
||||
"properties": {
|
||||
"testOutputTruncation": {
|
||||
"type": "string",
|
||||
"description": "An optional string specifying the test output truncation mode. Equivalent to passing --test-output-truncation on the command line. Must be one of the following values: \"tail\", \"middle\", or \"head\".",
|
||||
"enum": [
|
||||
"tail", "middle", "head"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"testPresetsItemsV3": {
|
||||
"type": "array",
|
||||
"description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 3 and higher.",
|
||||
@ -821,8 +858,7 @@
|
||||
"type": "integer",
|
||||
"description": "An optional integer specifying the maximum width of a test name to output. Equivalent to passing --max-width on the command line."
|
||||
}
|
||||
},
|
||||
"additionalProperties": false
|
||||
}
|
||||
},
|
||||
"filter": {
|
||||
"type": "object",
|
||||
@ -998,6 +1034,39 @@
|
||||
]
|
||||
}
|
||||
},
|
||||
"testPresetsV5": {
|
||||
"type": "array",
|
||||
"description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 5 and higher.",
|
||||
"allOf": [
|
||||
{ "$ref": "#/definitions/testPresetsItemsV2" },
|
||||
{ "$ref": "#/definitions/testPresetsItemsV3" },
|
||||
{ "$ref": "#/definitions/testPresetsItemsV5" }
|
||||
],
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"name": {},
|
||||
"hidden": {},
|
||||
"inherits": {},
|
||||
"configurePreset": {},
|
||||
"vendor": {},
|
||||
"displayName": {},
|
||||
"description": {},
|
||||
"inheritConfigureEnvironment": {},
|
||||
"environment": {},
|
||||
"configuration": {},
|
||||
"overwriteConfigurationFile": {},
|
||||
"output": {},
|
||||
"filter": {},
|
||||
"execution": {},
|
||||
"condition": {}
|
||||
},
|
||||
"required": [
|
||||
"name"
|
||||
],
|
||||
"additionalProperties": false
|
||||
}
|
||||
},
|
||||
"testPresetsV3": {
|
||||
"type": "array",
|
||||
"description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 3 and higher.",
|
||||
|
@ -1,4 +0,0 @@
|
||||
CPackPackageMaker
|
||||
-----------------
|
||||
|
||||
The documentation for the CPack PackageMaker generator has moved here: :cpack_gen:`CPack PackageMaker Generator`
|
@ -4,9 +4,11 @@ CMP0097
|
||||
.. versionadded:: 3.16
|
||||
|
||||
:command:`ExternalProject_Add` with ``GIT_SUBMODULES ""`` initializes no
|
||||
submodules.
|
||||
submodules. The policy also applies to :command:`FetchContent_Declare`,
|
||||
which uses the same download and update features as
|
||||
:command:`ExternalProject_Add`.
|
||||
|
||||
The module provides a ``GIT_SUBMODULES`` option which controls what submodules
|
||||
The commands provide a ``GIT_SUBMODULES`` option which controls what submodules
|
||||
to initialize and update. Starting with CMake 3.16, explicitly setting
|
||||
``GIT_SUBMODULES`` to an empty string means no submodules will be initialized
|
||||
or updated.
|
||||
|
@ -18,6 +18,7 @@ file name components no longer add a dependency on the evaluated target.
|
||||
- ``TARGET_PDB_FILE_NAME``
|
||||
- ``TARGET_PDB_FILE_DIR``
|
||||
- ``TARGET_BUNDLE_DIR``
|
||||
- ``TARGET_BUNDLE_DIR_NAME``
|
||||
- ``TARGET_BUNDLE_CONTENT_DIR``
|
||||
|
||||
|
||||
|
32
Help/policy/CMP0130.rst
Normal file
32
Help/policy/CMP0130.rst
Normal file
@ -0,0 +1,32 @@
|
||||
CMP0130
|
||||
-------
|
||||
|
||||
.. versionadded:: 3.24
|
||||
|
||||
:command:`while` diagnoses condition evaluation errors.
|
||||
|
||||
CMake 3.23 and below accidentally tolerated errors encountered while
|
||||
evaluating the condition passed to the :command:`while` command
|
||||
(but not the :command:`if` command). For example, the code
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
set(paren "(")
|
||||
while(${paren})
|
||||
endwhile()
|
||||
|
||||
creates an unbalanced parenthesis during condition evaluation.
|
||||
|
||||
CMake 3.24 and above prefer to diagnose such errors. This policy
|
||||
provides compatibility for projects that have not been updated to
|
||||
fix their condition errors.
|
||||
|
||||
The ``OLD`` behavior for this policy is to ignore errors in
|
||||
:command:`while` conditions. The ``NEW`` behavior for this
|
||||
policy is to diagnose errors in :command:`while` conditions.
|
||||
|
||||
This policy was introduced in CMake version 3.24. CMake version |release|
|
||||
warns when the policy is not set and uses ``OLD`` behavior. Use the
|
||||
:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
|
||||
|
||||
.. include:: DEPRECATED.txt
|
31
Help/policy/CMP0131.rst
Normal file
31
Help/policy/CMP0131.rst
Normal file
@ -0,0 +1,31 @@
|
||||
CMP0131
|
||||
-------
|
||||
|
||||
.. versionadded:: 3.24
|
||||
|
||||
:prop_tgt:`LINK_LIBRARIES` supports the :genex:`$<LINK_ONLY:...>`
|
||||
generator expression.
|
||||
|
||||
CMake 3.23 and below documented the :genex:`$<LINK_ONLY:...>` generator
|
||||
expression only for use in :prop_tgt:`INTERFACE_LINK_LIBRARIES`.
|
||||
When used in :prop_tgt:`LINK_LIBRARIES`, the content guarded inside
|
||||
:genex:`$<LINK_ONLY:...>` was always used, even when collecting non-linking
|
||||
usage requirements such as :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`.
|
||||
|
||||
CMake 3.24 and above prefer to support :genex:`$<LINK_ONLY:...>`, when
|
||||
used in :prop_tgt:`LINK_LIBRARIES`, by using the guarded content only
|
||||
for link dependencies and not other usage requirements. This policy
|
||||
provides compatibility for projects that have not been updated to
|
||||
account for this change.
|
||||
|
||||
The ``OLD`` behavior for this policy is to use :prop_tgt:`LINK_LIBRARIES`
|
||||
content guarded by :genex:`$<LINK_ONLY:...>` even for non-linking
|
||||
usage requirements. The ``NEW`` behavior for this policy is to use
|
||||
the guarded content only for link dependencies.
|
||||
|
||||
This policy was introduced in CMake version 3.24. Use the
|
||||
:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW``
|
||||
explicitly. Unlike many policies, CMake version |release| does *not*
|
||||
warn when this policy is not set, and simply uses ``OLD`` behavior.
|
||||
|
||||
.. include:: DEPRECATED.txt
|
26
Help/policy/CMP0132.rst
Normal file
26
Help/policy/CMP0132.rst
Normal file
@ -0,0 +1,26 @@
|
||||
CMP0132
|
||||
-------
|
||||
|
||||
.. versionadded:: 3.24
|
||||
|
||||
Apart from when using the Xcode generator and some Visual Studio generators,
|
||||
CMake 3.23 and below will set environment variables like :envvar:`CC`,
|
||||
:envvar:`CXX`, etc. when the corresponding language is enabled.
|
||||
This only occurs on the very first time CMake is run in a build directory,
|
||||
and the environment variables are only defined at configure time, not build
|
||||
time. On subsequent CMake runs, these environment variables are not set,
|
||||
opening up the opportunity for different behavior between the first and
|
||||
subsequent CMake runs. CMake 3.24 and above prefer to not set these
|
||||
environment variables when a language is enabled, even on the first run in
|
||||
a build directory.
|
||||
|
||||
The ``OLD`` behavior for this policy sets the relevant environment variable
|
||||
on the first run when a language is enabled. The ``NEW`` behavior for this
|
||||
policy does not set any such environment variables.
|
||||
|
||||
This policy was introduced in CMake version 3.24. Use the
|
||||
:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
|
||||
Unlike many policies, CMake version |release| does *not* warn
|
||||
when this policy is not set and simply uses ``OLD`` behavior.
|
||||
|
||||
.. include:: DEPRECATED.txt
|
32
Help/policy/CMP0133.rst
Normal file
32
Help/policy/CMP0133.rst
Normal file
@ -0,0 +1,32 @@
|
||||
CMP0133
|
||||
-------
|
||||
|
||||
.. versionadded:: 3.24
|
||||
|
||||
The :module:`CPack` module disables SLA by default in the
|
||||
:cpack_gen:`CPack DragNDrop Generator`.
|
||||
|
||||
The :cpack_gen:`CPack DragNDrop Generator` in CMake 3.22 and below attach a
|
||||
Software License Agreement (SLA) to ``.dmg`` files using the file specified
|
||||
by :variable:`CPACK_RESOURCE_FILE_LICENSE`, if set to a non-default value.
|
||||
macOS 12.0 deprecated the tools used to do this, so CMake 3.23 added
|
||||
the :variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` option to
|
||||
control the behavior. CMake 3.23 enables that option by default for
|
||||
compatibility with older versions. CMake 3.24 and above prefer to *not*
|
||||
enable the :variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` option by
|
||||
default. This policy provides compatibility with projects that have not
|
||||
been updated to account for the lack of a SLA in their ``.dmg`` packages.
|
||||
|
||||
The ``OLD`` behavior for this policy is to enable
|
||||
:variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` by default.
|
||||
The ``NEW`` behavior for this policy is to not enable it by default.
|
||||
|
||||
This policy was introduced in CMake version 3.24. Use the
|
||||
:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW``
|
||||
explicitly. Unlike many policies, CMake version |release| does *not* warn
|
||||
by default when this policy is not set and simply uses ``OLD`` behavior.
|
||||
See documentation of the
|
||||
:variable:`CMAKE_POLICY_WARNING_CMP0133 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
|
||||
variable to control the warning.
|
||||
|
||||
.. include:: DEPRECATED.txt
|
39
Help/policy/CMP0134.rst
Normal file
39
Help/policy/CMP0134.rst
Normal file
@ -0,0 +1,39 @@
|
||||
CMP0134
|
||||
-------
|
||||
|
||||
.. versionadded:: 3.24
|
||||
|
||||
The default registry view is ``TARGET`` for the :command:`find_file`,
|
||||
:command:`find_path`, :command:`find_library`, and :command:`find_package`
|
||||
commands and ``BOTH`` for the :command:`find_program` command.
|
||||
|
||||
The default registry views in CMake 3.23 and below are selected using the
|
||||
following rules:
|
||||
|
||||
* if :variable:`CMAKE_SIZEOF_VOID_P` has value ``8``:
|
||||
|
||||
* Use view ``64`` for all ``find_*`` commands except :command:`find_program`
|
||||
command.
|
||||
* Use view ``64_32`` for :command:`find_program` command.
|
||||
|
||||
* if :variable:`CMAKE_SIZEOF_VOID_P` has value ``4`` or is undefined:
|
||||
|
||||
* Use view ``32`` for all ``find_*`` commands except :command:`find_program`
|
||||
command.
|
||||
* Use view ``32_64`` for :command:`find_program` command.
|
||||
|
||||
The ``OLD`` behavior for this policy is to use registry views ``64`` and
|
||||
``64_32`` or ``32_64`` and ``32`` as default, depending of
|
||||
:variable:`CMAKE_SIZEOF_VOID_P` variable value.
|
||||
The ``NEW`` behavior for this policy is to use registry views ``TARGET`` and
|
||||
``BOTH`` as default.
|
||||
|
||||
This policy was introduced in CMake version 3.24. Use the
|
||||
:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW``
|
||||
explicitly. Unlike many policies, CMake version |release| does *not* warn
|
||||
by default when this policy is not set and simply uses ``OLD`` behavior.
|
||||
See documentation of the
|
||||
:variable:`CMAKE_POLICY_WARNING_CMP0133 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
|
||||
variable to control the warning.
|
||||
|
||||
.. include:: DEPRECATED.txt
|
29
Help/policy/CMP0135.rst
Normal file
29
Help/policy/CMP0135.rst
Normal file
@ -0,0 +1,29 @@
|
||||
CMP0135
|
||||
-------
|
||||
|
||||
.. versionadded:: 3.24
|
||||
|
||||
When using the ``URL`` download method with the :command:`ExternalProject_Add`
|
||||
command, CMake 3.23 and below sets the timestamps of the extracted contents
|
||||
to the same as the timestamps in the archive. When the ``URL`` changes, the
|
||||
new archive is downloaded and extracted, but the timestamps of the extracted
|
||||
contents might not be newer than the previous contents. Anything that depends
|
||||
on the extracted contents might not be rebuilt, even though the contents may
|
||||
change.
|
||||
|
||||
CMake 3.24 and above prefers to set the timestamps of all extracted contents
|
||||
to the time of the extraction. This ensures that anything that depends on the
|
||||
extracted contents will be rebuilt whenever the ``URL`` changes.
|
||||
|
||||
The ``DOWNLOAD_EXTRACT_TIMESTAMP`` option to the
|
||||
:command:`ExternalProject_Add` command can be used to explicitly specify how
|
||||
timestamps should be handled. When ``DOWNLOAD_EXTRACT_TIMESTAMP`` is not
|
||||
given, this policy controls the default behavior. The ``OLD`` behavior for
|
||||
this policy is to restore the timestamps from the archive. The ``NEW``
|
||||
behavior sets the timestamps of extracted contents to the time of extraction.
|
||||
|
||||
This policy was introduced in CMake version 3.24. CMake version |release|
|
||||
warns when the policy is not set and uses ``OLD`` behavior. Use the
|
||||
:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
|
||||
|
||||
.. include:: DEPRECATED.txt
|
50
Help/policy/CMP0136.rst
Normal file
50
Help/policy/CMP0136.rst
Normal file
@ -0,0 +1,50 @@
|
||||
CMP0136
|
||||
-------
|
||||
|
||||
.. versionadded:: 3.24
|
||||
|
||||
Watcom runtime library flags are selected by an abstraction.
|
||||
|
||||
Compilers targeting the Watcom ABI have flags to select the Watcom runtime
|
||||
library.
|
||||
|
||||
In CMake 3.23 and below, Watcom runtime library selection flags are added to
|
||||
the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache entries by CMake
|
||||
automatically. This allows users to edit their cache entries to adjust the
|
||||
flags. However, the presence of such default flags is problematic for
|
||||
projects that want to choose a different runtime library programmatically.
|
||||
In particular, it requires string editing of the
|
||||
:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variables with knowledge of the
|
||||
CMake builtin defaults so they can be replaced.
|
||||
|
||||
CMake 3.24 and above prefer to leave the Watcom runtime library selection flags
|
||||
out of the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` values and instead
|
||||
offer a first-class abstraction. The :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY`
|
||||
variable and :prop_tgt:`WATCOM_RUNTIME_LIBRARY` target property may be set to
|
||||
select the Watcom runtime library. If they are not set then CMake uses the
|
||||
default value ``MultiThreadedDLL`` on Windows and ``SingleThreaded`` on other
|
||||
platforms, which is equivalent to the original flags.
|
||||
|
||||
This policy provides compatibility with projects that have not been updated
|
||||
to be aware of the abstraction. The policy setting takes effect as of the
|
||||
first :command:`project` or :command:`enable_language` command that enables
|
||||
a language whose compiler targets the Watcom ABI.
|
||||
|
||||
.. note::
|
||||
|
||||
Once the policy has taken effect at the top of a project, that choice
|
||||
must be used throughout the tree. In projects that have nested projects
|
||||
in subdirectories, be sure to convert everything together.
|
||||
|
||||
The ``OLD`` behavior for this policy is to place Watcom runtime library
|
||||
flags in the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache
|
||||
entries and ignore the :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY` abstraction.
|
||||
The ``NEW`` behavior for this policy is to *not* place Watcom runtime
|
||||
library flags in the default cache entries and use the abstraction instead.
|
||||
|
||||
This policy was introduced in CMake version 3.24. Use the
|
||||
:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
|
||||
Unlike many policies, CMake version |release| does *not* warn
|
||||
when this policy is not set and simply uses ``OLD`` behavior.
|
||||
|
||||
.. include:: DEPRECATED.txt
|
33
Help/policy/CMP0137.rst
Normal file
33
Help/policy/CMP0137.rst
Normal file
@ -0,0 +1,33 @@
|
||||
CMP0137
|
||||
-------
|
||||
|
||||
.. versionadded:: 3.24
|
||||
|
||||
:command:`try_compile` passes platform variables in project mode.
|
||||
|
||||
The :command:`try_compile` command :ref:`source file <Try Compiling Source
|
||||
Files>` signature propagates CMake variables containing platform settings,
|
||||
and those specified by the :variable:`CMAKE_TRY_COMPILE_PLATFORM_VARIABLES`
|
||||
variable, into the generated test project. This helps the test project drive
|
||||
the toolchain the same way the calling project will. In CMake 3.23 and below,
|
||||
the :ref:`whole-project <Try Compiling Whole Projects>` signature does not
|
||||
propagate platform variables automatically. CMake 3.24 and above prefer to
|
||||
propagate platform variables in the :ref:`whole-project <Try Compiling Whole
|
||||
Projects>` signature. This policy provides compatibility with projects that
|
||||
have not been updated to expect the behavior.
|
||||
|
||||
The ``OLD`` behavior for this policy is to not pass any additional variables to
|
||||
the :ref:`whole-project <Try Compiling Whole Projects>` signature.
|
||||
The ``NEW`` behavior for this policy is to pass the same variables that the
|
||||
:ref:`source file <Try Compiling Source Files>` signature does.
|
||||
|
||||
Regardless of the policy setting, the
|
||||
:variable:`CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES` variable may be set
|
||||
to suppress passing the platform variables through either signature.
|
||||
|
||||
This policy was introduced in CMake version 3.24. Use the
|
||||
:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW``
|
||||
explicitly. Unlike many policies, CMake version |release| does *not* warn
|
||||
by default when this policy is not set and simply uses ``OLD`` behavior.
|
||||
|
||||
.. include:: DEPRECATED.txt
|
31
Help/policy/CMP0138.rst
Normal file
31
Help/policy/CMP0138.rst
Normal file
@ -0,0 +1,31 @@
|
||||
CMP0138
|
||||
-------
|
||||
|
||||
.. versionadded:: 3.24
|
||||
|
||||
:module:`CheckIPOSupported` uses flags from calling project.
|
||||
|
||||
The :module:`CheckIPOSupported` module :command:`check_ipo_supported`
|
||||
command compiles a test project to determine whether the toolchain
|
||||
supports :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION`. CMake 3.23 and
|
||||
below run the check with the default values of the
|
||||
:variable:`CMAKE_<LANG>_FLAGS` and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`
|
||||
variables for the current environment and toolchain settings.
|
||||
However, some projects may modify these flag variables to add
|
||||
flags that affect availability of the toolchain's IPO features.
|
||||
CMake 3.24 and above prefer to honor the calling project's values
|
||||
for these variables. This policy provides compatibility for projects
|
||||
that have not been updated to expect this behavior.
|
||||
|
||||
The ``OLD`` behavior for this policy is to ignore the calling
|
||||
project's values of :variable:`CMAKE_<LANG>_FLAGS` and
|
||||
:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`. The ``NEW`` behavior
|
||||
for this policy is to use the values of those variables as
|
||||
compiler flags in the test project.
|
||||
|
||||
This policy was introduced in CMake version 3.24. Use the
|
||||
:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
|
||||
Unlike many policies, CMake version |release| does *not* warn
|
||||
when this policy is not set and simply uses ``OLD`` behavior.
|
||||
|
||||
.. include:: DEPRECATED.txt
|
17
Help/policy/CMP0139.rst
Normal file
17
Help/policy/CMP0139.rst
Normal file
@ -0,0 +1,17 @@
|
||||
CMP0139
|
||||
-------
|
||||
|
||||
.. versionadded:: 3.24
|
||||
|
||||
The :command:`if` command supports path comparisons using ``PATH_EQUAL``
|
||||
operator.
|
||||
|
||||
The ``OLD`` behavior for this policy is to ignore the ``PATH_EQUAL`` operator.
|
||||
The ``NEW`` behavior is to interpret the ``PATH_EQUAL`` operator.
|
||||
|
||||
This policy was introduced in CMake version 3.24.
|
||||
CMake version |release| warns when the policy is not set and uses
|
||||
``OLD`` behavior. Use the :command:`cmake_policy` command to set
|
||||
it to ``OLD`` or ``NEW`` explicitly.
|
||||
|
||||
.. include:: DEPRECATED.txt
|
@ -3,5 +3,11 @@ RULE_LAUNCH_COMPILE
|
||||
|
||||
Specify a launcher for compile rules.
|
||||
|
||||
See the global property of the same name for details. This overrides
|
||||
the global property for a directory.
|
||||
.. note::
|
||||
This property is intended for internal use by :manual:`ctest(1)`. Projects
|
||||
and developers should use the :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target
|
||||
properties or the associated :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER`
|
||||
variables instead.
|
||||
|
||||
See the :prop_gbl:`global property <RULE_LAUNCH_COMPILE>` of the same name
|
||||
for details. This overrides the global property for a directory.
|
||||
|
@ -3,5 +3,11 @@ RULE_LAUNCH_LINK
|
||||
|
||||
Specify a launcher for link rules.
|
||||
|
||||
See the global property of the same name for details. This overrides
|
||||
the global property for a directory.
|
||||
.. note::
|
||||
This property is intended for internal use by :manual:`ctest(1)`. Projects
|
||||
and developers should use the :prop_tgt:`<LANG>_LINKER_LAUNCHER` target
|
||||
properties or the associated :variable:`CMAKE_<LANG>_LINKER_LAUNCHER`
|
||||
variables instead.
|
||||
|
||||
See the :prop_gbl:`global property <RULE_LAUNCH_LINK>` of the same name for
|
||||
details. This overrides the global property for a directory.
|
||||
|
@ -3,6 +3,12 @@ RULE_LAUNCH_COMPILE
|
||||
|
||||
Specify a launcher for compile rules.
|
||||
|
||||
.. note::
|
||||
This property is intended for internal use by :manual:`ctest(1)`. Projects
|
||||
and developers should use the :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target
|
||||
properties or the associated :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER`
|
||||
variables instead.
|
||||
|
||||
:ref:`Makefile Generators` and the :generator:`Ninja` generator prefix
|
||||
compiler commands with the given launcher command line.
|
||||
This is intended to allow launchers to intercept build problems
|
||||
|
@ -3,6 +3,12 @@ RULE_LAUNCH_LINK
|
||||
|
||||
Specify a launcher for link rules.
|
||||
|
||||
.. note::
|
||||
This property is intended for internal use by :manual:`ctest(1)`. Projects
|
||||
and developers should use the :prop_tgt:`<LANG>_LINKER_LAUNCHER` target
|
||||
properties or the associated :variable:`CMAKE_<LANG>_LINKER_LAUNCHER`
|
||||
variables instead.
|
||||
|
||||
:ref:`Makefile Generators` and the :generator:`Ninja` generator prefix
|
||||
link and archive commands with the given launcher command line.
|
||||
This is intended to allow launchers to intercept build problems
|
||||
|
@ -16,7 +16,7 @@ Example usage:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
set_source_files_property(<filename>
|
||||
set_source_files_properties(<filename>
|
||||
PROPERTIES
|
||||
VS_CSHARP_DependentUpon <other file>
|
||||
VS_CSHARP_SubType "Form")
|
||||
|
@ -19,17 +19,19 @@ property's value. The ``OP`` may be one of:
|
||||
to its state from the rest of the CTest execution.
|
||||
- ``set``: Replaces the current value of ``MYVAR`` with ``VALUE``.
|
||||
- ``unset``: Unsets the current value of ``MYVAR``.
|
||||
- ``string_append``: Appends ``VALUE`` to the current value of ``MYVAR``.
|
||||
- ``string_prepend``: Prepends ``VALUE`` to the current value of ``MYVAR``.
|
||||
- ``path_list_append``: Appends ``VALUE`` to the current value of ``MYVAR``
|
||||
using the host platform's path list separator (``;`` on Windows and ``:``
|
||||
elsewhere).
|
||||
- ``path_list_prepend``: Prepends ``VALUE`` to the current value of
|
||||
- ``string_append``: Appends singular ``VALUE`` to the current value of
|
||||
``MYVAR``.
|
||||
- ``string_prepend``: Prepends singular ``VALUE`` to the current value of
|
||||
``MYVAR``.
|
||||
- ``path_list_append``: Appends singular ``VALUE`` to the current value of
|
||||
``MYVAR`` using the host platform's path list separator (``;`` on Windows
|
||||
and ``:`` elsewhere).
|
||||
- ``cmake_list_append``: Appends ``VALUE`` to the current value of ``MYVAR``
|
||||
using ``;`` as the separator.
|
||||
- ``cmake_list_prepend``: Prepends ``VALUE`` to the current value of
|
||||
- ``path_list_prepend``: Prepends singular ``VALUE`` to the current value of
|
||||
``MYVAR`` using the host platform's path list separator (``;`` on Windows
|
||||
and ``:`` elsewhere).
|
||||
- ``cmake_list_append``: Appends singular ``VALUE`` to the current value of
|
||||
``MYVAR`` using ``;`` as the separator.
|
||||
- ``cmake_list_prepend``: Prepends singular ``VALUE`` to the current value of
|
||||
``MYVAR`` using ``;`` as the separator.
|
||||
|
||||
Unrecognized ``OP`` values will result in the test failing before it is
|
||||
|
10
Help/prop_tgt/COMPILE_WARNING_AS_ERROR.rst
Normal file
10
Help/prop_tgt/COMPILE_WARNING_AS_ERROR.rst
Normal file
@ -0,0 +1,10 @@
|
||||
COMPILE_WARNING_AS_ERROR
|
||||
------------------------
|
||||
|
||||
.. versionadded:: 3.24
|
||||
|
||||
Specify whether to treat warnings on compile as errors.
|
||||
If enabled, adds a flag to treat warnings on compile as errors.
|
||||
|
||||
This property is initialized by the value of the variable
|
||||
:variable:`CMAKE_COMPILE_WARNING_AS_ERROR` if it is set when a target is created.
|
@ -34,6 +34,11 @@ The ``CUDA_ARCHITECTURES`` may be set to one of the following special values:
|
||||
Compile for all supported major real architectures, and the highest
|
||||
major virtual architecture.
|
||||
|
||||
``native``
|
||||
.. versionadded:: 3.24
|
||||
|
||||
Compile for the architecture(s) of the host's GPU(s).
|
||||
|
||||
Examples
|
||||
^^^^^^^^
|
||||
|
||||
|
13
Help/prop_tgt/INTERFACE_HEADER_SETS_TO_VERIFY.rst
Normal file
13
Help/prop_tgt/INTERFACE_HEADER_SETS_TO_VERIFY.rst
Normal file
@ -0,0 +1,13 @@
|
||||
INTERFACE_HEADER_SETS_TO_VERIFY
|
||||
-------------------------------
|
||||
|
||||
.. versionadded:: 3.24
|
||||
|
||||
Used to specify which ``PUBLIC`` and ``INTERFACE`` header sets of a target
|
||||
should be verified.
|
||||
|
||||
This property contains a semicolon-separated list of header sets which
|
||||
should be verified if :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` is set to
|
||||
``TRUE``. If the list is empty, all ``PUBLIC`` and ``INTERFACE`` header sets
|
||||
are verified. (If the project does not want to verify any header sets on the
|
||||
target, simply set :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` to ``FALSE``.)
|
@ -26,6 +26,12 @@ manual for more on defining buildsystem properties.
|
||||
|
||||
.. include:: LINK_LIBRARIES_INDIRECTION.txt
|
||||
|
||||
``INTERFACE_LINK_LIBRARIES`` adds transitive link dependencies for a
|
||||
target's dependents. In advanced use cases, one may update the
|
||||
direct link dependencies of a target's dependents by using the
|
||||
:prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` and
|
||||
:prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` target properties.
|
||||
|
||||
Creating Relocatable Packages
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
236
Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT.rst
Normal file
236
Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT.rst
Normal file
@ -0,0 +1,236 @@
|
||||
INTERFACE_LINK_LIBRARIES_DIRECT
|
||||
-------------------------------
|
||||
|
||||
.. versionadded:: 3.24
|
||||
|
||||
List of libraries that consumers of this library should treat
|
||||
as direct link dependencies.
|
||||
|
||||
This target property may be set to *include* items in a dependent
|
||||
target's final set of direct link dependencies. See the
|
||||
:prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` target property
|
||||
to exclude items.
|
||||
|
||||
The initial set of a dependent target's direct link dependencies is
|
||||
specified by its :prop_tgt:`LINK_LIBRARIES` target property. Indirect
|
||||
link dependencies are specified by the transitive closure of the direct
|
||||
link dependencies' :prop_tgt:`INTERFACE_LINK_LIBRARIES` properties.
|
||||
Any link dependency may specify additional direct link dependencies
|
||||
using the ``INTERFACE_LINK_LIBRARIES_DIRECT`` target property.
|
||||
The set of direct link dependencies is then filtered to exclude items named
|
||||
by any dependency's :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`
|
||||
target property.
|
||||
|
||||
.. |INTERFACE_PROPERTY_LINK_DIRECT| replace:: ``INTERFACE_LINK_LIBRARIES_DIRECT``
|
||||
.. include:: INTERFACE_LINK_LIBRARIES_DIRECT.txt
|
||||
|
||||
Direct Link Dependencies as Usage Requirements
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The ``INTERFACE_LINK_LIBRARIES_DIRECT`` and
|
||||
``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target properties
|
||||
are :ref:`usage requirements <Target Usage Requirements>`.
|
||||
Their effects propagate to dependent targets transitively, and can
|
||||
therefore affect the direct link dependencies of every target in a
|
||||
chain of dependent libraries. Whenever some library target ``X`` links
|
||||
to another library target ``Y`` whose direct or transitive usage
|
||||
requirements contain ``INTERFACE_LINK_LIBRARIES_DIRECT`` or
|
||||
``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE``, the properties may affect
|
||||
``X``'s list of direct link dependencies:
|
||||
|
||||
* If ``X`` is a shared library or executable, its dependencies are linked.
|
||||
They also affect the usage requirements with which ``X``'s sources are
|
||||
compiled.
|
||||
|
||||
* If ``X`` is a static library or object library, it does not actually
|
||||
link, so its dependencies at most affect the usage requirements with
|
||||
which ``X``'s sources are compiled.
|
||||
|
||||
The properties may also affect the list of direct link dependencies
|
||||
on ``X``'s dependents:
|
||||
|
||||
* If ``X`` links ``Y`` publicly:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
target_link_libraries(X PUBLIC Y)
|
||||
|
||||
then ``Y`` is placed in ``X``'s :prop_tgt:`INTERFACE_LINK_LIBRARIES`,
|
||||
so ``Y``'s usage requirements, including ``INTERFACE_LINK_LIBRARIES_DIRECT``,
|
||||
``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE``, and the usage requirements
|
||||
declared by the direct link dependencies they add, are propagated to
|
||||
``X``'s dependents.
|
||||
|
||||
* If ``X`` is a static library or object library, and links ``Y`` privately:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
target_link_libraries(X PRIVATE Y)
|
||||
|
||||
then ``$<LINK_ONLY:Y>`` is placed in ``X``'s
|
||||
:prop_tgt:`INTERFACE_LINK_LIBRARIES`. ``Y``'s linking requirements,
|
||||
including ``INTERFACE_LINK_LIBRARIES_DIRECT``,
|
||||
``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE``, and the transitive link
|
||||
dependencies declared by the direct link dependencies they add, are
|
||||
propagated to ``X``'s dependents. However, ``Y``'s non-linking
|
||||
usage requirements are blocked by the :genex:`LINK_ONLY` generator
|
||||
expression, and are not propagated to ``X``'s dependents.
|
||||
|
||||
* If ``X`` is a shared library or executable, and links ``Y`` privately:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
target_link_libraries(X PRIVATE Y)
|
||||
|
||||
then ``Y`` is not placed in ``X``'s :prop_tgt:`INTERFACE_LINK_LIBRARIES`,
|
||||
so ``Y``'s usage requirements, even ``INTERFACE_LINK_LIBRARIES_DIRECT``
|
||||
and ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE``, are not propagated to
|
||||
``X``'s dependents.
|
||||
|
||||
* In all cases, the content of ``X``'s :prop_tgt:`INTERFACE_LINK_LIBRARIES`
|
||||
is not affected by ``Y``'s ``INTERFACE_LINK_LIBRARIES_DIRECT`` or
|
||||
``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE``.
|
||||
|
||||
One may limit the effects of ``INTERFACE_LINK_LIBRARIES_DIRECT`` and
|
||||
``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` to a subset of dependent
|
||||
targets by using the :genex:`TARGET_PROPERTY` generator expression.
|
||||
For example, to limit the effects to executable targets, use an
|
||||
entry of the form::
|
||||
|
||||
"$<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,EXECUTABLE>:...>"
|
||||
|
||||
Similarly, to limit the effects to specific targets, use an entry
|
||||
of the form::
|
||||
|
||||
"$<$<BOOL:$<TARGET_PROPERTY:USE_IT>>:...>"
|
||||
|
||||
This entry will only affect targets that set their ``USE_IT``
|
||||
target property to a true value.
|
||||
|
||||
Direct Link Dependency Ordering
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The list of direct link dependencies for a target is computed from an
|
||||
initial ordered list in its :prop_tgt:`LINK_LIBRARIES` target property.
|
||||
For each item, additional direct link dependencies are discovered from
|
||||
its direct and transitive ``INTERFACE_LINK_LIBRARIES_DIRECT`` usage
|
||||
requirements. Each discovered item is injected before the item that
|
||||
specified it. However, a discovered item is added at most once,
|
||||
and only if it did not appear anywhere in the initial list.
|
||||
This gives :prop_tgt:`LINK_LIBRARIES` control over ordering of
|
||||
those direct link dependencies that it explicitly specifies.
|
||||
|
||||
Once all direct link dependencies have been collected, items named by
|
||||
all of their :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`
|
||||
usage requirements are removed from the final list. This does not
|
||||
affect the order of the items that remain.
|
||||
|
||||
Example: Static Plugins
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Consider a static library ``Foo`` that provides a static plugin
|
||||
``FooPlugin`` to consuming application executables, where the
|
||||
implementation of the plugin depends on ``Foo`` and other things.
|
||||
In this case, the application should link to ``FooPlugin`` directly,
|
||||
before ``Foo``. However, the application author only knows about ``Foo``.
|
||||
We can express this as follows:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
# Core library used by other components.
|
||||
add_library(Core STATIC core.cpp)
|
||||
|
||||
# Foo is a static library for use by applications.
|
||||
# Implementation of Foo depends on Core.
|
||||
add_library(Foo STATIC foo.cpp foo_plugin_helper.cpp)
|
||||
target_link_libraries(Foo PRIVATE Core)
|
||||
|
||||
# Extra parts of Foo for use by its static plugins.
|
||||
# Implementation of Foo's extra parts depends on both Core and Foo.
|
||||
add_library(FooExtras STATIC foo_extras.cpp)
|
||||
target_link_libraries(FooExtras PRIVATE Core Foo)
|
||||
|
||||
# The Foo library has an associated static plugin
|
||||
# that should be linked into the final executable.
|
||||
# Implementation of the plugin depends on Core, Foo, and FooExtras.
|
||||
add_library(FooPlugin STATIC foo_plugin.cpp)
|
||||
target_link_libraries(FooPlugin PRIVATE Core Foo FooExtras)
|
||||
|
||||
# An app that links Foo should link Foo's plugin directly.
|
||||
set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT FooPlugin)
|
||||
|
||||
# An app does not need to link Foo directly because the plugin links it.
|
||||
set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE Foo)
|
||||
|
||||
An application ``app`` only needs to specify that it links to ``Foo``:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
add_executable(app main.cpp)
|
||||
target_link_libraries(app PRIVATE Foo)
|
||||
|
||||
The ``INTERFACE_LINK_LIBRARIES_DIRECT`` target property on ``Foo`` tells
|
||||
CMake to pretend that ``app`` also links directly to ``FooPlugin``.
|
||||
The ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target property on ``Foo``
|
||||
tells CMake to pretend that ``app`` did *not* link directly to ``Foo``.
|
||||
Instead, ``Foo`` will be linked as a dependency of ``FooPlugin``. The
|
||||
final link line for ``app`` will link the libraries in the following
|
||||
order:
|
||||
|
||||
* ``FooPlugin`` as a direct link dependency of ``app``
|
||||
(via ``Foo``'s usage requirements).
|
||||
* ``FooExtras`` as a dependency of ``FooPlugin``.
|
||||
* ``Foo`` as a dependency of ``FooPlugin`` and ``FooExtras``.
|
||||
* ``Core`` as a dependency of ``FooPlugin``, ``FooExtras``, and ``Foo``.
|
||||
|
||||
Note that without the ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target
|
||||
property, ``Foo`` would be linked twice: once as a direct dependency
|
||||
of ``app``, and once as a dependency of ``FooPlugin``.
|
||||
|
||||
Example: Opt-In Static Plugins
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
In the above `Example: Static Plugins`_, the ``app`` executable specifies
|
||||
that it links directly to ``Foo``. In a real application, there might
|
||||
be an intermediate library:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
add_library(app_impl STATIC app_impl.cpp)
|
||||
target_link_libraries(app_impl PRIVATE Foo)
|
||||
|
||||
add_executable(app main.cpp)
|
||||
target_link_libraries(app PRIVATE app_impl)
|
||||
|
||||
In this case we do not want ``Foo``'s ``INTERFACE_LINK_LIBRARIES_DIRECT``
|
||||
and ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target properties to affect
|
||||
the direct dependencies of ``app_impl``. To avoid this, we can revise
|
||||
the property values to make their effects opt-in:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
# An app that links Foo should link Foo's plugin directly.
|
||||
set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT
|
||||
"$<$<BOOL:$<TARGET_PROPERTY:FOO_STATIC_PLUGINS>>:FooPlugin>"
|
||||
)
|
||||
|
||||
# An app does not need to link Foo directly because the plugin links it.
|
||||
set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
|
||||
"$<$<BOOL:$<TARGET_PROPERTY:FOO_STATIC_PLUGINS>>:Foo>"
|
||||
)
|
||||
|
||||
Now, the ``app`` executable can opt-in to get ``Foo``'s plugin(s):
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
set_property(TARGET app PROPERTY FOO_STATIC_PLUGINS 1)
|
||||
|
||||
The final link line for ``app`` will now link the libraries in the following
|
||||
order:
|
||||
|
||||
* ``FooPlugin`` as a direct link dependency of ``app``
|
||||
(via ``Foo``'s usage requirements).
|
||||
* ``app_impl`` as a direct link dependency of ``app``.
|
||||
* ``FooExtras`` as a dependency of ``FooPlugin``.
|
||||
* ``Foo`` as a dependency of ``app_impl``, ``FooPlugin``, and ``FooExtras``.
|
||||
* ``Core`` as a dependency of ``FooPlugin``, ``FooExtras``, and ``Foo``.
|
9
Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT.txt
Normal file
9
Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT.txt
Normal file
@ -0,0 +1,9 @@
|
||||
The value of |INTERFACE_PROPERTY_LINK_DIRECT| may use
|
||||
:manual:`generator expressions <cmake-generator-expressions(7)>`.
|
||||
|
||||
.. note::
|
||||
|
||||
The |INTERFACE_PROPERTY_LINK_DIRECT| target property is intended for
|
||||
advanced use cases such as injection of static plugins into a consuming
|
||||
executable. It should not be used as a substitute for organizing
|
||||
normal calls to :command:`target_link_libraries`.
|
34
Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE.rst
Normal file
34
Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE.rst
Normal file
@ -0,0 +1,34 @@
|
||||
INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
|
||||
---------------------------------------
|
||||
|
||||
.. versionadded:: 3.24
|
||||
|
||||
List of libraries that consumers of this library should *not* treat
|
||||
as direct link dependencies.
|
||||
|
||||
This target property may be set to *exclude* items from a dependent
|
||||
target's final set of direct link dependencies. This property is
|
||||
processed after the :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT`
|
||||
target property of all other dependencies of the dependent target, so
|
||||
exclusion from direct link dependence takes priority over inclusion.
|
||||
|
||||
The initial set of a dependent target's direct link dependencies is
|
||||
specified by its :prop_tgt:`LINK_LIBRARIES` target property. Indirect
|
||||
link dependencies are specified by the transitive closure of the direct
|
||||
link dependencies' :prop_tgt:`INTERFACE_LINK_LIBRARIES` properties.
|
||||
Any link dependency may specify additional direct link dependencies
|
||||
using the :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` target property.
|
||||
The set of direct link dependencies is then filtered to exclude items named
|
||||
by any dependency's ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target
|
||||
property.
|
||||
|
||||
Excluding an item from a dependent target's direct link dependencies
|
||||
does not mean the dependent target won't link the item. The item
|
||||
may still be linked as an indirect link dependency via the
|
||||
:prop_tgt:`INTERFACE_LINK_LIBRARIES` property on other dependencies.
|
||||
|
||||
.. |INTERFACE_PROPERTY_LINK_DIRECT| replace:: ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE``
|
||||
.. include:: INTERFACE_LINK_LIBRARIES_DIRECT.txt
|
||||
|
||||
See the :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` target property
|
||||
documentation for more details and examples.
|
@ -14,9 +14,17 @@ followed by indirect dependencies from the transitive closure of the
|
||||
direct dependencies' :prop_tgt:`INTERFACE_LINK_LIBRARIES` properties.
|
||||
See policy :policy:`CMP0022`.
|
||||
|
||||
Contents of ``LINK_LIBRARIES`` may use "generator expressions" with the
|
||||
syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual
|
||||
for available expressions. See the :manual:`cmake-buildsystem(7)` manual
|
||||
for more on defining buildsystem properties.
|
||||
Contents of ``LINK_LIBRARIES`` may use
|
||||
:manual:`generator expressions <cmake-generator-expressions(7)>` with the
|
||||
syntax ``$<...>``. Policy :policy:`CMP0131` affects the behavior of the
|
||||
:genex:`LINK_ONLY` generator expression for this property.
|
||||
|
||||
See the :manual:`cmake-buildsystem(7)` manual for more on defining
|
||||
buildsystem properties.
|
||||
|
||||
.. include:: LINK_LIBRARIES_INDIRECTION.txt
|
||||
|
||||
In advanced use cases, the list of direct link dependencies specified
|
||||
by this property may be updated by usage requirements from dependencies.
|
||||
See the :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` and
|
||||
:prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` target properties.
|
||||
|
@ -8,6 +8,8 @@ Enforce that link items that can be target names are actually existing targets.
|
||||
Set this property to a true value to enable additional checks on the contents
|
||||
of the :prop_tgt:`LINK_LIBRARIES` and :prop_tgt:`INTERFACE_LINK_LIBRARIES`
|
||||
target properties, typically populated by :command:`target_link_libraries`.
|
||||
Checks are also applied to libraries added to a target through the
|
||||
:prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` properties of its dependencies.
|
||||
CMake will verify that link items that might be target names actually name
|
||||
existing targets. An item is considered a possible target name if:
|
||||
|
||||
|
65
Help/prop_tgt/LINK_LIBRARY_OVERRIDE.rst
Normal file
65
Help/prop_tgt/LINK_LIBRARY_OVERRIDE.rst
Normal file
@ -0,0 +1,65 @@
|
||||
LINK_LIBRARY_OVERRIDE
|
||||
---------------------
|
||||
|
||||
.. versionadded:: 3.24
|
||||
|
||||
Override the library features associated with libraries from
|
||||
:genex:`LINK_LIBRARY` generator expressions. This can be used to resolve
|
||||
incompatible library features that result from specifying different features
|
||||
for the same library in different :genex:`LINK_LIBRARY` generator expressions.
|
||||
|
||||
This property supports overriding multiple libraries and features. It expects
|
||||
a :ref:`semicolon-separated list <CMake Language Lists>`, where each list item
|
||||
has the following form::
|
||||
|
||||
feature[,link-item]*
|
||||
|
||||
For each comma-separated ``link-item``, any existing library feature associated
|
||||
with it will be ignored for the target this property is set on. The item
|
||||
will instead be associated with the specified ``feature``. Each ``link-item``
|
||||
can be anything that would be accepted as part of a ``library-list`` in a
|
||||
:genex:`LINK_LIBRARY` generator expression.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
add_library(lib1 ...)
|
||||
add_library(lib2 ...)
|
||||
add_library(lib3 ...)
|
||||
|
||||
target_link_libraries(lib1 PUBLIC "$<LINK_LIBRARY:feature1,external>")
|
||||
target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature2,lib1>")
|
||||
target_link_libraries(lib3 PRIVATE lib1 lib2)
|
||||
|
||||
# lib1 is associated with both feature2 and no feature. Without any override,
|
||||
# this would result in a fatal error at generation time for lib3.
|
||||
# Define an override to resolve the incompatible feature associations.
|
||||
set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE "feature2,lib1,external")
|
||||
|
||||
# lib1 and external will now be associated with feature2 instead when linking lib3
|
||||
|
||||
It is also possible to override any feature with the pre-defined ``DEFAULT``
|
||||
library feature. This effectively discards any feature for that link item,
|
||||
for that target only (``lib3`` in this example):
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
# When linking lib3, discard any library feature for lib1, and use feature2 for external
|
||||
set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE
|
||||
"DEFAULT,lib1"
|
||||
"feature2,external"
|
||||
)
|
||||
|
||||
The above example also demonstrates how to specify different feature overrides
|
||||
for different link items. See the :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>`
|
||||
target property for an alternative way of overriding library features for
|
||||
individual libraries, which may be simpler in some cases. If both properties
|
||||
are defined and specify an override for the same link item,
|
||||
:prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` takes precedence over
|
||||
``LINK_LIBRARY_OVERRIDE``.
|
||||
|
||||
Contents of ``LINK_LIBRARY_OVERRIDE`` may use
|
||||
:manual:`generator expressions <cmake-generator-expressions(7)>`.
|
||||
|
||||
For more information about library features, see the
|
||||
:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` and
|
||||
:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables.
|
51
Help/prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY.rst
Normal file
51
Help/prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY.rst
Normal file
@ -0,0 +1,51 @@
|
||||
LINK_LIBRARY_OVERRIDE_<LIBRARY>
|
||||
-------------------------------
|
||||
|
||||
.. versionadded:: 3.24
|
||||
|
||||
Override the library feature associated with ``<LIBRARY>`` from
|
||||
:genex:`LINK_LIBRARY` generator expressions. This can be used to resolve
|
||||
incompatible library features that result from specifying different features
|
||||
for ``<LIBRARY>`` in different :genex:`LINK_LIBRARY` generator expressions.
|
||||
|
||||
When set on a target, this property holds a single library feature name, which
|
||||
will be applied to ``<LIBRARY>`` when linking that target.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
add_library(lib1 ...)
|
||||
add_library(lib2 ...)
|
||||
add_library(lib3 ...)
|
||||
|
||||
target_link_libraries(lib1 PUBLIC "$<LINK_LIBRARY:feature1,external>")
|
||||
target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature2,lib1>")
|
||||
target_link_libraries(lib3 PRIVATE lib1 lib2)
|
||||
|
||||
# lib1 is associated with both feature2 and no feature. Without any override,
|
||||
# this would result in a fatal error at generation time for lib3.
|
||||
# Define an override to resolve the incompatible feature associations.
|
||||
set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE_lib1 feature2)
|
||||
|
||||
# lib1 will now be associated with feature2 instead when linking lib3
|
||||
|
||||
It is also possible to override any feature with the pre-defined ``DEFAULT``
|
||||
library feature. This effectively discards any feature for that link item,
|
||||
for that target only (``lib3`` in this example):
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
# When linking lib3, discard any library feature for lib1
|
||||
set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE_lib1 DEFAULT)
|
||||
|
||||
See the :prop_tgt:`LINK_LIBRARY_OVERRIDE` target property for an alternative
|
||||
way of overriding library features for multiple libraries at once. If both
|
||||
properties are defined and specify an override for the same link item,
|
||||
``LINK_LIBRARY_OVERRIDE_<LIBRARY>`` takes precedence over
|
||||
:prop_tgt:`LINK_LIBRARY_OVERRIDE`.
|
||||
|
||||
Contents of ``LINK_LIBRARY_OVERRIDE_<LIBRARY>`` may use
|
||||
:manual:`generator expressions <cmake-generator-expressions(7)>`.
|
||||
|
||||
For more information about library features, see the
|
||||
:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` and
|
||||
:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables.
|
@ -3,5 +3,11 @@ RULE_LAUNCH_COMPILE
|
||||
|
||||
Specify a launcher for compile rules.
|
||||
|
||||
See the global property of the same name for details. This overrides
|
||||
the global and directory property for a target.
|
||||
.. note::
|
||||
This property is intended for internal use by :manual:`ctest(1)`. Projects
|
||||
and developers should use the :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target
|
||||
properties or the associated :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER`
|
||||
variables instead.
|
||||
|
||||
See the :prop_gbl:`global property <RULE_LAUNCH_COMPILE>` of the same name
|
||||
for details. This overrides the global and directory property for a target.
|
||||
|
@ -3,5 +3,11 @@ RULE_LAUNCH_LINK
|
||||
|
||||
Specify a launcher for link rules.
|
||||
|
||||
See the global property of the same name for details. This overrides
|
||||
the global and directory property for a target.
|
||||
.. note::
|
||||
This property is intended for internal use by :manual:`ctest(1)`. Projects
|
||||
and developers should use the :prop_tgt:`<LANG>_LINKER_LAUNCHER` target
|
||||
properties or the associated :variable:`CMAKE_<LANG>_LINKER_LAUNCHER`
|
||||
variables instead.
|
||||
|
||||
See the :prop_gbl:`global property <RULE_LAUNCH_LINK>` of the same name for
|
||||
details. This overrides the global and directory property for a target.
|
||||
|
38
Help/prop_tgt/VERIFY_INTERFACE_HEADER_SETS.rst
Normal file
38
Help/prop_tgt/VERIFY_INTERFACE_HEADER_SETS.rst
Normal file
@ -0,0 +1,38 @@
|
||||
VERIFY_INTERFACE_HEADER_SETS
|
||||
----------------------------
|
||||
|
||||
.. versionadded:: 3.24
|
||||
|
||||
Used to verify that all headers in a target's ``PUBLIC`` and ``INTERFACE``
|
||||
header sets can be included on their own.
|
||||
|
||||
When this property is set to true, and the target is an object library, static
|
||||
library, shared library, interface library, or executable with exports enabled,
|
||||
and the target has one or more ``PUBLIC`` or ``INTERFACE`` header sets, an
|
||||
object library target named ``<target_name>_verify_interface_header_sets`` is
|
||||
created. This verification target has one source file per header in the
|
||||
``PUBLIC`` and ``INTERFACE`` header sets. Each source file only includes its
|
||||
associated header file. The verification target links against the original
|
||||
target to get all of its usage requirements. The verification target has its
|
||||
:prop_tgt:`EXCLUDE_FROM_ALL` and :prop_tgt:`DISABLE_PRECOMPILE_HEADERS`
|
||||
properties set to true, and its :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTORCC`,
|
||||
:prop_tgt:`AUTOUIC`, and :prop_tgt:`UNITY_BUILD` properties set to false.
|
||||
|
||||
If the header's :prop_sf:`LANGUAGE` property is set, the value of that property
|
||||
is used to determine the language with which to compile the header file.
|
||||
Otherwise, if the target has any C++ sources, the header is compiled as C++.
|
||||
Otherwise, if the target has any C sources, the header is compiled as C.
|
||||
Otherwise, if C++ is enabled globally, the header is compiled as C++.
|
||||
Otherwise, if C is enabled globally, the header is compiled as C. Otherwise,
|
||||
the header file is not compiled.
|
||||
|
||||
If any verification targets are created, a top-level target called
|
||||
``all_verify_interface_header_sets`` is created which depends on all
|
||||
verification targets.
|
||||
|
||||
This property is initialized by the value of the
|
||||
:variable:`CMAKE_VERIFY_INTERFACE_HEADER_SETS` variable if it is set when
|
||||
a target is created.
|
||||
|
||||
If the project wishes to control which header sets are verified by this
|
||||
property, it can set :prop_tgt:`INTERFACE_HEADER_SETS_TO_VERIFY`.
|
21
Help/prop_tgt/VS_DOTNET_STARTUP_OBJECT.rst
Normal file
21
Help/prop_tgt/VS_DOTNET_STARTUP_OBJECT.rst
Normal file
@ -0,0 +1,21 @@
|
||||
VS_DOTNET_STARTUP_OBJECT
|
||||
------------------------
|
||||
|
||||
.. versionadded:: 3.24
|
||||
|
||||
Sets the startup object property in Visual Studio .NET targets.
|
||||
The property value defines a full qualified class name (including package
|
||||
name), for example: ``MyCompany.Package.MyStarterClass``.
|
||||
|
||||
If the property is unset, Visual Studio uses the first matching
|
||||
``static void Main(string[])`` function signature by default. When more
|
||||
than one ``Main()`` method is available in the current project, the property
|
||||
becomes mandatory for building the project.
|
||||
|
||||
This property only works for Visual Studio 2010 and above;
|
||||
it is ignored on other generators.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
set_property(TARGET ${TARGET_NAME} PROPERTY
|
||||
VS_DOTNET_STARTUP_OBJECT "MyCompany.Package.MyStarterClass")
|
24
Help/prop_tgt/VS_NO_COMPILE_BATCHING.rst
Normal file
24
Help/prop_tgt/VS_NO_COMPILE_BATCHING.rst
Normal file
@ -0,0 +1,24 @@
|
||||
VS_NO_COMPILE_BATCHING
|
||||
----------------------
|
||||
|
||||
.. versionadded:: 3.24
|
||||
|
||||
Turn off compile batching for the target. Usually MSBuild calls the compiler
|
||||
with multiple c/cpp files and compiler starts subprocesses for each file to
|
||||
make the build parallel. If you want compiler to be invoked with one file at
|
||||
a time set ``VS_NO_COMPILE_BATCHING`` to ON. If this flag is set MSBuild will
|
||||
call compiler with one c/cpp file at a time. Useful when you want to use tool
|
||||
that replaces the compiler, for example some build caching tool.
|
||||
|
||||
This property is initialized by the :variable:`CMAKE_VS_NO_COMPILE_BATCHING`
|
||||
variable if it is set when a target is created.
|
||||
|
||||
Example
|
||||
^^^^^^^
|
||||
|
||||
This shows setting the property for the target ``foo``.
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
add_library(foo SHARED foo.cpp)
|
||||
set_property(TARGET foo PROPERTY VS_NO_COMPILE_BATCHING ON)
|
20
Help/prop_tgt/WATCOM_RUNTIME_LIBRARY-VALUES.txt
Normal file
20
Help/prop_tgt/WATCOM_RUNTIME_LIBRARY-VALUES.txt
Normal file
@ -0,0 +1,20 @@
|
||||
``SingleThreaded``
|
||||
Compile without additional flags to use a single-threaded
|
||||
statically-linked runtime library.
|
||||
``SingleThreadedDLL``
|
||||
Compile with ``-br`` or equivalent flag(s) to use a single-threaded
|
||||
dynamically-linked runtime library. This is not available for Linux
|
||||
targets.
|
||||
``MultiThreaded``
|
||||
Compile with ``-bm`` or equivalent flag(s) to use a multi-threaded
|
||||
statically-linked runtime library.
|
||||
``MultiThreadedDLL``
|
||||
Compile with ``-bm -br`` or equivalent flag(s) to use a multi-threaded
|
||||
dynamically-linked runtime library. This is not available for Linux
|
||||
targets.
|
||||
|
||||
The value is ignored on non-Watcom compilers but an unsupported value will
|
||||
be rejected as an error when using a compiler targeting the Watcom ABI.
|
||||
|
||||
The value may also be the empty string (``""``) in which case no runtime
|
||||
library selection flag will be added explicitly by CMake.
|
34
Help/prop_tgt/WATCOM_RUNTIME_LIBRARY.rst
Normal file
34
Help/prop_tgt/WATCOM_RUNTIME_LIBRARY.rst
Normal file
@ -0,0 +1,34 @@
|
||||
WATCOM_RUNTIME_LIBRARY
|
||||
----------------------
|
||||
|
||||
.. versionadded:: 3.24
|
||||
|
||||
Select the Watcom runtime library for use by compilers targeting the Watcom ABI.
|
||||
|
||||
The allowed values are:
|
||||
|
||||
.. include:: WATCOM_RUNTIME_LIBRARY-VALUES.txt
|
||||
|
||||
Use :manual:`generator expressions <cmake-generator-expressions(7)>` to
|
||||
support per-configuration specification.
|
||||
|
||||
For example, the code:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
add_executable(foo foo.c)
|
||||
set_property(TARGET foo PROPERTY
|
||||
WATCOM_RUNTIME_LIBRARY "MultiThreaded")
|
||||
|
||||
selects for the target ``foo`` a multi-threaded statically-linked runtime
|
||||
library.
|
||||
|
||||
If this property is not set then CMake uses the default value
|
||||
``MultiThreadedDLL`` on Windows and ``SingleThreaded`` on other
|
||||
platforms to select a Watcom runtime library.
|
||||
|
||||
.. note::
|
||||
|
||||
This property has effect only when policy :policy:`CMP0136` is set to ``NEW``
|
||||
prior to the first :command:`project` or :command:`enable_language` command
|
||||
that enables a language using a compiler targeting the Watcom ABI.
|
14
Help/prop_tgt/XCODE_XCCONFIG.rst
Normal file
14
Help/prop_tgt/XCODE_XCCONFIG.rst
Normal file
@ -0,0 +1,14 @@
|
||||
XCODE_XCCONFIG
|
||||
--------------
|
||||
|
||||
.. versionadded:: 3.24
|
||||
|
||||
If set, the :generator:`Xcode` generator will register the specified
|
||||
file as a target-level XCConfig file. For global XCConfig files see
|
||||
the :variable:`CMAKE_XCODE_XCCONFIG` variable.
|
||||
|
||||
This feature is intended to ease migration from native Xcode projects
|
||||
to CMake projects.
|
||||
|
||||
Contents of ``XCODE_XCCONFIG`` may use
|
||||
:manual:`generator expressions <cmake-generator-expressions(7)>`.
|
@ -272,7 +272,7 @@ Deprecated and Removed Features
|
||||
of all policies are deprecated and that projects should port to the
|
||||
NEW behaviors.
|
||||
|
||||
* The :cpack_gen:`CPack PackageMaker Generator` generator has been
|
||||
* The CPack ``PackageMaker`` generator has been
|
||||
deprecated because Xcode no longer distributes the PackageMaker tools.
|
||||
The undocumented ``OSXX11`` generator has also been deprecated.
|
||||
|
||||
|
@ -187,7 +187,7 @@ CPack
|
||||
|
||||
* The ``CPack.distribution.dist.in`` template used by the
|
||||
:cpack_gen:`CPack productbuild Generator` and
|
||||
:cpack_gen:`CPack PackageMaker Generator` was updated to use a new
|
||||
CPack ``PackageMaker`` generator was updated to use a new
|
||||
``CPACK_APPLE_PKG_INSTALLER_CONTENT`` variable for its main content.
|
||||
This replaced the previously undocumented and now deprecated
|
||||
``CPACK_PACKAGEMAKER_CHOICES`` variable.
|
||||
|
350
Help/release/3.24.rst
Normal file
350
Help/release/3.24.rst
Normal file
@ -0,0 +1,350 @@
|
||||
CMake 3.24 Release Notes
|
||||
************************
|
||||
|
||||
.. only:: html
|
||||
|
||||
.. contents::
|
||||
|
||||
Changes made since CMake 3.23 include the following.
|
||||
|
||||
New Features
|
||||
============
|
||||
|
||||
Presets
|
||||
-------
|
||||
|
||||
* :manual:`cmake-presets(7)` files now support schema version ``5``.
|
||||
|
||||
* :manual:`cmake-presets(7)` files now support a ``${pathListSep}`` macro,
|
||||
which expands to ``:`` or ``;`` based on the platform.
|
||||
|
||||
* :manual:`cmake-presets(7)` files gained support for specifying a
|
||||
``testOutputTruncation`` field in test presets, which specifies the
|
||||
truncation mode once the maximum test output size has been reached.
|
||||
|
||||
Generators
|
||||
----------
|
||||
|
||||
* The :generator:`Green Hills MULTI` generator now generates build
|
||||
rules to re-run CMake if any CMake files are updated.
|
||||
|
||||
* The :ref:`Visual Studio Generators` now support ``SYSTEM`` headers
|
||||
when using VS 2019 Update 11 or later.
|
||||
|
||||
Command-Line
|
||||
------------
|
||||
|
||||
* :manual:`cmake(1)` gained the ``--fresh`` command-line option to remove
|
||||
any existing ``CMakeCache.txt`` file and associated ``CMakeFiles/``
|
||||
directory, when configuring a build tree, thus starting a new configuration
|
||||
as if the build tree were freshly created.
|
||||
|
||||
* :manual:`cmake(1)` gained the ``--compile-no-warning-as-error`` command-line
|
||||
option which causes the effects of the :prop_tgt:`COMPILE_WARNING_AS_ERROR`
|
||||
target property and :variable:`CMAKE_COMPILE_WARNING_AS_ERROR` variable
|
||||
to be ignored.
|
||||
|
||||
* The :manual:`cmake(1)` ``--trace=json-v1`` trace format gained fields
|
||||
``global_frame`` and ``line_end``.
|
||||
|
||||
* The :manual:`cmake(1)` ``-E`` commands ``cat`` and ``env`` learned to respect
|
||||
a double dash (``--``) argument that acts as a delimiter indicating the end of
|
||||
options. Any following arguments are treated as operands/positional arguments,
|
||||
even if they begin with a dash ``-`` character.
|
||||
|
||||
* The :manual:`cmake(1)` ``-E tar`` command gained the ``--touch`` option
|
||||
to keep the current local timestamp instead of extracting file timestamps
|
||||
from the archive.
|
||||
|
||||
Compilers
|
||||
---------
|
||||
|
||||
* LLVM's `flang`_ Fortran compiler is now supported on some platforms,
|
||||
with compiler id ``LLVMFlang``.
|
||||
|
||||
.. _`flang`: https://github.com/llvm/llvm-project/tree/main/flang
|
||||
|
||||
* ADSP compiler support (SHARC and Blackfin) now covers both CCES and
|
||||
VDSP++ installations, with required configuration now done in the
|
||||
compiler module itself rather than the ``Generic-ADSP`` platform module.
|
||||
|
||||
Platforms
|
||||
---------
|
||||
|
||||
* A dedicated ``ADSP`` platform has been added
|
||||
to replace the existing ``Generic-ADSP`` implementation.
|
||||
This features automatic detection of the latest CCES/VDSP++ install
|
||||
and compiler selection (``cc21k`` vs. ``ccblkfn``)
|
||||
based off of the :variable:`CMAKE_SYSTEM_PROCESSOR` variable.
|
||||
|
||||
Commands
|
||||
--------
|
||||
|
||||
* The :command:`cmake_host_system_information` command, on Windows,
|
||||
gained a ``QUERY WINDOWS_REGISTRY`` mode.
|
||||
See its :ref:`Query Windows registry` section.
|
||||
|
||||
* The :command:`cmake_language` command gained a new
|
||||
``SET_DEPENDENCY_PROVIDER`` sub-command. When a dependency provider is set,
|
||||
calls to :command:`find_package` and :command:`FetchContent_MakeAvailable`
|
||||
can be redirected through a custom command, which can choose to fulfill the
|
||||
request directly, modify how the request is processed, or leave it to be
|
||||
fulfilled by the built-in implementation. See :ref:`dependency_providers`.
|
||||
|
||||
* The :command:`file(DOWNLOAD)` command gained options ``RANGE_START`` and
|
||||
``RANGE_END`` to specify a range of bytes to download. This can be
|
||||
useful for downloading parts of big binary files.
|
||||
|
||||
* The :command:`find_file`, :command:`find_path`, :command:`find_library`,
|
||||
:command:`find_program`, and :command:`find_package` commands gained the
|
||||
``NO_CMAKE_INSTALL_PREFIX`` option to control searching
|
||||
:variable:`CMAKE_INSTALL_PREFIX`.
|
||||
|
||||
* The :command:`find_file`, :command:`find_path`, :command:`find_library`,
|
||||
:command:`find_program`, and :command:`find_package` commands gained the
|
||||
ability to specify which Windows Registry views must be queried.
|
||||
|
||||
* The :command:`find_package` command gained a ``GLOBAL`` option that
|
||||
allows for the promotion of imported targets to global scope for the
|
||||
duration of the :command:`find_package` call.
|
||||
|
||||
* The :command:`if` command gained the capability to compare paths by
|
||||
using the ``PATH_EQUAL`` operator. See policy :policy:`CMP0139`.
|
||||
|
||||
Variables
|
||||
---------
|
||||
|
||||
* The :variable:`CMAKE_COLOR_DIAGNOSTICS` variable was added to control
|
||||
color diagnostics generated by compilers. This variable also controls
|
||||
color build system messages with :ref:`Makefile Generators`, replacing
|
||||
:variable:`CMAKE_COLOR_MAKEFILE`.
|
||||
|
||||
The :envvar:`CMAKE_COLOR_DIAGNOSTICS` environment variable was added to set
|
||||
a default value for :variable:`CMAKE_COLOR_DIAGNOSTICS`.
|
||||
|
||||
* The :variable:`CMAKE_COMPILE_WARNING_AS_ERROR` variable and corresponding
|
||||
:prop_tgt:`COMPILE_WARNING_AS_ERROR` target property were added to enable
|
||||
compilation with a compiler-specific flag to treat warnings as errors,
|
||||
such as ``-Werror``.
|
||||
|
||||
* The :variable:`CMAKE_CUDA_ARCHITECTURES` variable and associated
|
||||
:prop_tgt:`CUDA_ARCHITECTURES` target property now support the
|
||||
special ``native`` value to compile for the architectures(s)
|
||||
of the host's GPU(s).
|
||||
|
||||
* The :variable:`CMAKE_FIND_PACKAGE_TARGETS_GLOBAL` variable was added to
|
||||
toggle behavior of the :command:`find_package` command's new ``GLOBAL``
|
||||
option.
|
||||
|
||||
* The :variable:`CMAKE_FIND_USE_INSTALL_PREFIX` variable was added to toggle
|
||||
behavior of the :command:`find_file`, :command:`find_library`,
|
||||
:command:`find_path`, :command:`find_package`, and :command:`find_program`
|
||||
commands' new ``NO_CMAKE_INSTALL_PREFIX`` option.
|
||||
|
||||
* The :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable was added to allow
|
||||
injecting custom code at the site of the first :command:`project` call,
|
||||
after the host and target platform details have been determined.
|
||||
|
||||
* The :variable:`CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES` variable
|
||||
was added to tell the :command:`try_compile` command not to
|
||||
pass any platform variables to the test project.
|
||||
|
||||
* The :variable:`CMAKE_VERIFY_INTERFACE_HEADER_SETS` variable and
|
||||
corresponding :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` target property
|
||||
were added to enable build rules that verify all headers in header sets
|
||||
can be used on their own.
|
||||
|
||||
* The :variable:`CMAKE_VS_NO_COMPILE_BATCHING` variable and corresponding
|
||||
:prop_tgt:`VS_NO_COMPILE_BATCHING` target property were added to
|
||||
tell :ref:`Visual Studio Generators` whether to disable compiler
|
||||
parallelism and call the compiler with one source file at a time.
|
||||
|
||||
* The :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY` variable and
|
||||
:prop_tgt:`WATCOM_RUNTIME_LIBRARY` target property were introduced to
|
||||
select the runtime library used by compilers targeting the Watcom ABI.
|
||||
See policy :policy:`CMP0136`.
|
||||
|
||||
* The :variable:`CMAKE_XCODE_XCCONFIG` variable and corresponding
|
||||
:prop_tgt:`XCODE_XCCONFIG` target property were added to tell
|
||||
the :generator:`Xcode` generator to handle ``xcconfig`` files.
|
||||
|
||||
Properties
|
||||
----------
|
||||
|
||||
* The :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` and
|
||||
:prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` target properties
|
||||
were added to express usage requirements affecting a consumer's
|
||||
direct link dependencies.
|
||||
|
||||
* The :prop_tgt:`INTERFACE_HEADER_SETS_TO_VERIFY` target property was
|
||||
added to specify which header sets should be verified by
|
||||
:prop_tgt:`VERIFY_INTERFACE_HEADER_SETS`.
|
||||
|
||||
* The :prop_tgt:`LINK_LIBRARIES` target property now supports
|
||||
the :genex:`$<LINK_ONLY:...>` generator expression.
|
||||
See policy :policy:`CMP0131`.
|
||||
|
||||
* The :prop_tgt:`VS_DOTNET_STARTUP_OBJECT` target property was added to
|
||||
tell :ref:`Visual Studio Generators` which startup class shall be used
|
||||
when the program or project is executed. This is necessary when more
|
||||
than one ``static void Main(string[])`` function signature is available
|
||||
in a managed .NET project.
|
||||
|
||||
Modules
|
||||
-------
|
||||
|
||||
* The :module:`ExternalProject` module :command:`ExternalProject_Add`
|
||||
command gained a new ``DOWNLOAD_EXTRACT_TIMESTAMP`` option for
|
||||
controlling whether the timestamps of extracted contents are set to
|
||||
match those in the archive when the ``URL`` download method is used.
|
||||
Policy :policy:`CMP0135` was added to enable the option by default.
|
||||
|
||||
* The :module:`FetchContent` module and the :command:`find_package` command
|
||||
now support integration capabilities:
|
||||
|
||||
* :command:`FetchContent_MakeAvailable` can now try to satisfy a dependency
|
||||
by calling :command:`find_package` first. A new
|
||||
:variable:`FETCHCONTENT_TRY_FIND_PACKAGE_MODE` variable controls whether
|
||||
this is done by default for all dependencies, is opt-in per dependency,
|
||||
or is disabled entirely.
|
||||
|
||||
* :command:`find_package` can be re-routed to call
|
||||
:command:`FetchContent_MakeAvailable` instead. A new read-only
|
||||
:variable:`CMAKE_FIND_PACKAGE_REDIRECTS_DIR` variable points to a
|
||||
directory where config package files can be located to facilitate these
|
||||
re-routed calls.
|
||||
|
||||
* The :module:`FindJNI` module now provides imported targets.
|
||||
|
||||
* The :module:`FindMatlab` module :command:`matlab_add_mex` function
|
||||
gained a ``NO_IMPLICIT_LINK_TO_MATLAB_LIBRARIES`` option to disable
|
||||
automatic linking of MATLAB libraries.
|
||||
|
||||
* The :module:`FindVulkan` module now supports components to select which
|
||||
VulkanSDK tool and libraries to find in addition to the Vulkan SDK headers
|
||||
and library.
|
||||
|
||||
* The :module:`FindZLIB` gained a new ``ZLIB_USE_STATIC_LIBS`` variable to
|
||||
search only for static libraries.
|
||||
|
||||
Generator Expressions
|
||||
---------------------
|
||||
|
||||
* The :genex:`LINK_LIBRARY` generator expression was added to manage how
|
||||
libraries are specified during the link step.
|
||||
The :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` and
|
||||
:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables are used to define
|
||||
features usable by the :genex:`LINK_LIBRARY` generator expression.
|
||||
Moreover, the :prop_tgt:`LINK_LIBRARY_OVERRIDE` and
|
||||
:prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties are
|
||||
available to resolve incompatible features.
|
||||
|
||||
The :genex:`LINK_LIBRARY` generator expression can link frameworks in
|
||||
various ways when targeting ``Apple`` platforms.
|
||||
The following features were added:
|
||||
|
||||
* ``FRAMEWORK``
|
||||
* ``NEEDED_FRAMEWORK``
|
||||
* ``REEXPORT_FRAMEWORK``
|
||||
* ``WEAK_FRAMEWORK``
|
||||
|
||||
The :genex:`LINK_LIBRARY` generator expression can link libraries in
|
||||
various ways when targeting ``Apple`` platforms.
|
||||
The following features were added:
|
||||
|
||||
* ``NEEDED_LIBRARY``
|
||||
* ``REEXPORT_LIBRARY``
|
||||
* ``WEAK_LIBRARY``
|
||||
|
||||
The :genex:`LINK_LIBRARY` generator expression gained the feature
|
||||
``WHOLE_ARCHIVE`` to force load of all members in a static library.
|
||||
This feature is supported on the following target platforms:
|
||||
|
||||
* all ``Apple`` variants
|
||||
* ``Linux``
|
||||
* all ``BSD`` variants
|
||||
* ``SunOS``
|
||||
* ``Windows``
|
||||
* ``CYGWIN``
|
||||
* ``MSYS``
|
||||
|
||||
* The :genex:`LINK_GROUP` generator expression was added to manage the
|
||||
grouping of libraries during the link step. The
|
||||
:variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` and
|
||||
:variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` variables are used to define
|
||||
features usable with the :genex:`LINK_GROUP` generator expression.
|
||||
This release defines the ``RESCAN`` feature, which can be used to handle
|
||||
circular references among static libraries when using toolchains for
|
||||
Linux, BSD, SunOS and GNU toolchains for Windows.
|
||||
|
||||
* The :genex:`PATH` generator expression was added to manage paths.
|
||||
|
||||
* The :genex:`PATH_EQUAL` generator expression was added to manage path
|
||||
comparisons.
|
||||
|
||||
* The :genex:`TARGET_BUNDLE_DIR_NAME` generator expression
|
||||
was added to evaluate to the name of the bundle directory
|
||||
for a given bundle target.
|
||||
|
||||
CTest
|
||||
-----
|
||||
|
||||
* :manual:`ctest(1)` gained a ``--test-output-truncation`` option (and
|
||||
corresponding :variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` variable) to
|
||||
specify the truncation mode once the maximum test output size has been
|
||||
reached. Possible values are ``tail`` (default), ``middle`` or ``head``.
|
||||
|
||||
CPack
|
||||
-----
|
||||
|
||||
* The :cpack_gen:`CPack WIX Generator` gained a new variable,
|
||||
:variable:`CPACK_WIX_ARCHITECTURE`, to specify the installer architecture
|
||||
in order to support computers running Windows for ARM.
|
||||
|
||||
* CPack now supports the :variable:`CPACK_THREADS` option for ``zstd``
|
||||
compression when compiled with libarchive 3.6 or higher. It is
|
||||
supported by official CMake binaries available on `cmake.org`_.
|
||||
|
||||
Deprecated and Removed Features
|
||||
===============================
|
||||
|
||||
* The :module:`CPack` module no longer enables the SLA by default in the
|
||||
:cpack_gen:`CPack DragNDrop Generator`. See policy :policy:`CMP0133`
|
||||
and the :variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` variable.
|
||||
|
||||
* The deprecated :cpack_gen:`CPack PackageMaker Generator` has been removed.
|
||||
|
||||
* The :module:`FindGLUT` module no longer provides the undocumented
|
||||
``GLUT_LIBRARY`` and ``GLUT_INCLUDE_PATH`` result variables.
|
||||
|
||||
Other Changes
|
||||
=============
|
||||
|
||||
* CMake no longer sets environment variables like :envvar:`CC`, :envvar:`CXX`,
|
||||
etc. when enabling the corresponding language during the first CMake run in
|
||||
a build directory. See policy :policy:`CMP0132`.
|
||||
|
||||
* The :module:`CheckIPOSupported` module :command:`check_ipo_supported`
|
||||
command now uses the caller's :variable:`CMAKE_<LANG>_FLAGS`
|
||||
and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` values.
|
||||
See policy :policy:`CMP0138`.
|
||||
|
||||
* The :generator:`MSYS Makefiles` and :generator:`MinGW Makefiles`
|
||||
generators, when a compiler is not explicitly specified, now select
|
||||
the first compiler (of any name) found in directories listed by the
|
||||
``PATH`` environment variable.
|
||||
|
||||
* The :command:`try_compile` command
|
||||
:ref:`whole-project <Try Compiling Whole Projects>` signature
|
||||
now propagates platform variables. See policy :policy:`CMP0137`.
|
||||
|
||||
* The :command:`while` command now diagnoses errors during condition
|
||||
evaluation. See policy :policy:`CMP0130`.
|
||||
|
||||
* The precompiled macOS binaries provided on `cmake.org`_ no longer attach a
|
||||
SLA to the ``.dmg`` packages. This was removed because macOS 12 deprecated
|
||||
the tools used to attach ``.dmg`` resources.
|
||||
|
||||
* A precompiled Windows ``arm64`` binary is now provided on `cmake.org`_.
|
||||
|
||||
.. _`cmake.org`: https://cmake.org/download/
|
@ -13,6 +13,7 @@ Releases
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
3.24 <3.24>
|
||||
3.23 <3.23>
|
||||
3.22 <3.22>
|
||||
3.21 <3.21>
|
||||
|
11
Help/variable/CMAKE_ADSP_ROOT.rst
Normal file
11
Help/variable/CMAKE_ADSP_ROOT.rst
Normal file
@ -0,0 +1,11 @@
|
||||
CMAKE_ADSP_ROOT
|
||||
---------------
|
||||
|
||||
.. versionadded:: 3.24
|
||||
|
||||
When :ref:`Cross Compiling for ADSP SHARC/Blackfin`,
|
||||
this variable holds the absolute path to the latest CCES or VDSP++ install.
|
||||
The directory is expected to contain the ``cc21k.exe`` and ``ccblkfn.exe`` compilers.
|
||||
This will be set automatically if a default install of CCES or VDSP++ can be found.
|
||||
|
||||
See also the :envvar:`ADSP_ROOT` environment variable.
|
Some files were not shown because too many files have changed in this diff Show More
Loading…
x
Reference in New Issue
Block a user