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

Update upstream source from tag 'upstream/3.25.0'

Browse Source 
Update to upstream version '3.25.0'
with Debian dir 068404b33fb7dc12acbeace99a929ff77eabff70
This commit is contained in:
Timo Röhling 2022-11-16 20:14:46 +01:00
commit d0ed1a49c0
2039 changed files with 37736 additions and 14726 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
Auxiliary/cmake-mode.el
View File

@ -41,8 +41,8 @@ set the path with these commands:
:group 'cmake)
;; Keywords
(defconst cmake-keywords-block-open '("IF" "MACRO" "FOREACH" "ELSE" "ELSEIF" "WHILE" "FUNCTION"))
(defconst cmake-keywords-block-close '("ENDIF" "ENDFOREACH" "ENDMACRO" "ELSE" "ELSEIF" "ENDWHILE" "ENDFUNCTION"))
(defconst cmake-keywords-block-open '("BLOCK" "IF" "MACRO" "FOREACH" "ELSE" "ELSEIF" "WHILE" "FUNCTION"))
(defconst cmake-keywords-block-close '("ENDBLOCK" "ENDIF" "ENDFOREACH" "ENDMACRO" "ELSE" "ELSEIF" "ENDWHILE" "ENDFUNCTION"))
(defconst cmake-keywords
(let ((kwds (append cmake-keywords-block-open cmake-keywords-block-close nil)))
(delete-dups kwds)))
@ -288,6 +288,39 @@ This puts the mark at the end, and point at the beginning."
;------------------------------------------------------------------------------
(defun cmake--syntax-propertize-until-bracket-close (syntax)
;; This function assumes that a previous search has matched the
;; beginning of a bracket_comment or bracket_argument and that the
;; second capture group has matched the equal signs between the two
;; opening brackets
(let* ((mb (match-beginning 2))
(me (match-end 2))
(cb (format "]%s]" (buffer-substring mb me))))
(save-match-data
(if (search-forward cb end 'move)
(progn
(setq me (match-end 0))
(put-text-property
(1- me)
me
'syntax-table
(string-to-syntax syntax)))
(setq me end)))
(put-text-property
(match-beginning 1)
me
'syntax-multiline
t)))
(defconst cmake--syntax-propertize-function
(syntax-propertize-rules
("\\(#\\)\\[\\(=*\\)\\["
(1
(prog1 "!" (cmake--syntax-propertize-until-bracket-close "!"))))
("\\(\\[\\)\\(=*\\)\\["
(1
(prog1 "|" (cmake--syntax-propertize-until-bracket-close "|"))))))
;; Syntax table for this mode.
(defvar cmake-mode-syntax-table nil
"Syntax table for CMake mode.")
@ -318,7 +351,10 @@ This puts the mark at the end, and point at the beginning."
; Setup indentation function.
(set (make-local-variable 'indent-line-function) 'cmake-indent)
; Setup comment syntax.
(set (make-local-variable 'comment-start) "#"))
(set (make-local-variable 'comment-start) "#")
;; Setup syntax propertization
(set (make-local-variable 'syntax-propertize-function) cmake--syntax-propertize-function)
(add-hook 'syntax-propertize-extend-region-functions #'syntax-propertize-multiline nil t))
;; Default cmake-mode key bindings
(define-key cmake-mode-map "\e\C-a" #'cmake-beginning-of-defun)

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

@ -59,8 +59,8 @@ fun! CMakeGetIndent(lnum)
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*('
let cmake_indent_begin_regex = '^\s*\(BLOCK\|IF\|MACRO\|FOREACH\|ELSE\|ELSEIF\|WHILE\|FUNCTION\)\s*('
let cmake_indent_end_regex = '^\s*\(ENDBLOCK\|ENDIF\|ENDFOREACH\|ENDMACRO\|ELSE\|ELSEIF\|ENDWHILE\|ENDFUNCTION\)\s*('
if this_line =~? cmake_closing_parens_line
if previous_line !~? cmake_indent_open_regex

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

@ -436,6 +436,7 @@ syn keyword cmakeProperty contained
\ XCODE_SCHEME_ENVIRONMENT
\ XCODE_SCHEME_EXECUTABLE
\ XCODE_SCHEME_GUARD_MALLOC
\ XCODE_SCHEME_LAUNCH_MODE
\ XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP
\ XCODE_SCHEME_MALLOC_GUARD_EDGES
\ XCODE_SCHEME_MALLOC_SCRIBBLE
@ -444,6 +445,9 @@ syn keyword cmakeProperty contained
\ XCODE_SCHEME_THREAD_SANITIZER_STOP
\ XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER
\ XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP
\ XCODE_SCHEME_ENABLE_GPU_API_VALIDATION
\ XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION
\ XCODE_SCHEME_LAUNCH_CONFIGURATION
\ XCODE_SCHEME_WORKING_DIRECTORY
\ XCODE_SCHEME_ZOMBIE_OBJECTS
\ XCTEST
@ -1537,6 +1541,7 @@ syn keyword cmakeVariable contained
\ CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE
\ CMAKE_XCODE_SCHEME_ENVIRONMENT
\ CMAKE_XCODE_SCHEME_GUARD_MALLOC
\ CMAKE_XCODE_SCHEME_LAUNCH_MODE
\ CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP
\ CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES
\ CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE
@ -1545,6 +1550,9 @@ syn keyword cmakeVariable contained
\ CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP
\ CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER
\ CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP
\ CMAKE_XCODE_SCHEME_ENABLE_GPU_API_VALIDATION
\ CMAKE_XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION
\ CMAKE_XCODE_SCHEME_LAUNCH_CONFIGURATION
\ CMAKE_XCODE_SCHEME_WORKING_DIRECTORY
\ CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS
\ CPACK_ABSOLUTE_DESTINATION_FILES
@ -3830,6 +3838,7 @@ syn keyword cmakeCommand
\ add_subdirectory
\ add_test
\ aux_source_directory
\ block
\ break
\ build_command
\ cmake_host_system_information
@ -3857,6 +3866,7 @@ syn keyword cmakeCommand
\ define_property
\ enable_language
\ enable_testing
\ endblock
\ endfunction
\ endmacro
\ execute_process

468
CMakeLists.txt
View File

@ -1,7 +1,7 @@
# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
# file Copyright.txt or https://cmake.org/licensing for details.
cmake_minimum_required(VERSION 3.13...3.22 FATAL_ERROR)
cmake_minimum_required(VERSION 3.13...3.23 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)
@ -17,8 +17,8 @@ unset(CMAKE_USER_MAKE_RULES_OVERRIDE_C)
if(MSVC AND NOT CMAKE_VERSION VERSION_LESS 3.15)
# Filter out MSVC runtime library flags that may have come from
# the cache of an existing build tree or from scripts.
foreach(l C CXX)
foreach(c DEBUG MINSIZEREL RELEASE RELWITHDEBINFO)
foreach(l IN ITEMS C CXX)
foreach(c IN ITEMS DEBUG MINSIZEREL RELEASE RELWITHDEBINFO)
string(REGEX REPLACE "[-/]M[DT]d?( |$)" "" "CMAKE_${l}_FLAGS_${c}" "${CMAKE_${l}_FLAGS_${c}}")
endforeach()
endforeach()
@ -60,17 +60,6 @@ else()
set(USE_LGPL "")
endif()
if("${CMake_SOURCE_DIR}" STREQUAL "${CMAKE_SOURCE_DIR}")
# Disallow architecture-specific try_run. It may not run on the host.
macro(TRY_RUN)
if(CMAKE_TRY_COMPILE_OSX_ARCHITECTURES)
message(FATAL_ERROR "TRY_RUN not allowed with CMAKE_TRY_COMPILE_OSX_ARCHITECTURES=[${CMAKE_TRY_COMPILE_OSX_ARCHITECTURES}]")
else()
_TRY_RUN(${ARGV})
endif()
endmacro()
endif()
# Use most-recent available language dialects with GNU and Clang
if(NOT DEFINED CMAKE_C_STANDARD AND NOT CMake_NO_C_STANDARD)
include(${CMake_SOURCE_DIR}/Source/Checks/cm_c11_thread_local.cmake)
@ -81,7 +70,7 @@ if(NOT DEFINED CMAKE_C_STANDARD AND NOT CMake_NO_C_STANDARD)
endif()
endif()
if(NOT DEFINED CMAKE_CXX_STANDARD AND NOT CMake_NO_CXX_STANDARD)
if (CMAKE_CXX_COMPILER_ID STREQUAL SunPro AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS 5.14)
if(CMAKE_CXX_COMPILER_ID STREQUAL SunPro AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS 5.14)
set(CMAKE_CXX_STANDARD 98)
else()
if(NOT CMAKE_VERSION VERSION_LESS 3.8)
@ -114,9 +103,7 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
endif()
# Inform STL library header wrappers whether to use system versions.
configure_file(${CMake_SOURCE_DIR}/Utilities/std/cmSTL.hxx.in
${CMake_BINARY_DIR}/Utilities/cmSTL.hxx
@ONLY)
configure_file(Utilities/std/cmSTL.hxx.in Utilities/cmSTL.hxx @ONLY)
# set the internal encoding of CMake to UTF-8
set(KWSYS_ENCODING_DEFAULT_CODEPAGE CP_UTF8)
@ -143,7 +130,7 @@ option(CMake_BUILD_DEVELOPER_REFERENCE
mark_as_advanced(CMake_BUILD_DEVELOPER_REFERENCE)
# option to build using interprocedural optimizations (IPO/LTO)
if (NOT CMAKE_VERSION VERSION_LESS 3.12.2)
if(NOT CMAKE_VERSION VERSION_LESS 3.12.2)
option(CMake_BUILD_LTO "Compile CMake with link-time optimization if supported" OFF)
if(CMake_BUILD_LTO)
include(CheckIPOSupported)
@ -165,7 +152,7 @@ macro(CMAKE_HANDLE_SYSTEM_LIBRARIES)
# Allow the user to enable/disable all system utility library options by
# defining CMAKE_USE_SYSTEM_LIBRARIES or CMAKE_USE_SYSTEM_LIBRARY_${util}.
set(UTILITIES BZIP2 CURL EXPAT FORM JSONCPP LIBARCHIVE LIBLZMA LIBRHASH LIBUV NGHTTP2 ZLIB ZSTD)
foreach(util ${UTILITIES})
foreach(util IN LISTS UTILITIES)
if(NOT DEFINED CMAKE_USE_SYSTEM_LIBRARY_${util}
AND DEFINED CMAKE_USE_SYSTEM_LIBRARIES)
set(CMAKE_USE_SYSTEM_LIBRARY_${util} "${CMAKE_USE_SYSTEM_LIBRARIES}")
@ -215,16 +202,14 @@ macro(CMAKE_HANDLE_SYSTEM_LIBRARIES)
mark_as_advanced(CMAKE_USE_SYSTEM_KWIML)
# Mention to the user what system libraries are being used.
foreach(util ${UTILITIES} KWIML)
foreach(util IN LISTS UTILITIES ITEMS KWIML)
if(CMAKE_USE_SYSTEM_${util})
message(STATUS "Using system-installed ${util}")
endif()
endforeach()
# Inform utility library header wrappers whether to use system versions.
configure_file(${CMake_SOURCE_DIR}/Utilities/cmThirdParty.h.in
${CMake_BINARY_DIR}/Utilities/cmThirdParty.h
@ONLY)
configure_file(Utilities/cmThirdParty.h.in Utilities/cmThirdParty.h @ONLY)
endmacro()
@ -235,7 +220,7 @@ endmacro()
macro(CMAKE_SETUP_TESTING)
if(BUILD_TESTING)
set(CMAKE_TEST_SYSTEM_LIBRARIES 0)
foreach(util CURL EXPAT ZLIB)
foreach(util IN ITEMS CURL EXPAT ZLIB)
if(CMAKE_USE_SYSTEM_${util})
set(CMAKE_TEST_SYSTEM_LIBRARIES 1)
endif()
@ -250,7 +235,7 @@ macro(CMAKE_SETUP_TESTING)
set(CMAKE_CTEST_COMMAND "${CMake_TEST_EXTERNAL_CMAKE}/ctest")
set(CMAKE_CMAKE_COMMAND "${CMake_TEST_EXTERNAL_CMAKE}/cmake")
set(CMAKE_CPACK_COMMAND "${CMake_TEST_EXTERNAL_CMAKE}/cpack")
foreach(exe cmake ctest cpack)
foreach(exe IN ITEMS cmake ctest cpack)
add_executable(${exe} IMPORTED)
set_property(TARGET ${exe} PROPERTY IMPORTED_LOCATION ${CMake_TEST_EXTERNAL_CMAKE}/${exe})
endforeach()
@ -262,18 +247,12 @@ macro(CMAKE_SETUP_TESTING)
endif()
# configure some files for testing
configure_file("${CMAKE_CURRENT_SOURCE_DIR}/Templates/CTestScript.cmake.in"
"${CMAKE_CURRENT_BINARY_DIR}/CTestScript.cmake"
@ONLY)
configure_file(${CMake_SOURCE_DIR}/Tests/.NoDartCoverage
${CMake_BINARY_DIR}/Tests/.NoDartCoverage)
configure_file(${CMake_SOURCE_DIR}/Tests/.NoDartCoverage
${CMake_BINARY_DIR}/Modules/.NoDartCoverage)
configure_file(${CMake_SOURCE_DIR}/CTestCustom.cmake.in
${CMake_BINARY_DIR}/CTestCustom.cmake @ONLY)
configure_file(Templates/CTestScript.cmake.in CTestScript.cmake @ONLY)
configure_file(Tests/.NoDartCoverage Tests/.NoDartCoverage)
configure_file(Tests/.NoDartCoverage Modules/.NoDartCoverage)
configure_file(CTestCustom.cmake.in CTestCustom.cmake @ONLY)
if(BUILD_TESTING AND DART_ROOT)
configure_file(${CMake_SOURCE_DIR}/CMakeLogo.gif
${CMake_BINARY_DIR}/Testing/HTML/TestingResults/Icons/Logo.gif COPYONLY)
configure_file(CMakeLogo.gif Testing/HTML/TestingResults/Icons/Logo.gif COPYONLY)
endif()
mark_as_advanced(DART_ROOT)
endmacro()
@ -339,390 +318,6 @@ macro(CMAKE_SET_TARGET_FOLDER tgt folder)
endif()
endmacro()
#-----------------------------------------------------------------------
# a macro to build the utilities used by CMake
# Simply to improve readability of the main script.
#-----------------------------------------------------------------------
macro (CMAKE_BUILD_UTILITIES)
find_package(Threads)
# Suppress unnecessary checks in third-party code.
include(Utilities/cmThirdPartyChecks.cmake)
#---------------------------------------------------------------------
# Create the kwsys library for CMake.
set(KWSYS_NAMESPACE cmsys)
set(KWSYS_USE_SystemTools 1)
set(KWSYS_USE_Directory 1)
set(KWSYS_USE_RegularExpression 1)
set(KWSYS_USE_Base64 1)
set(KWSYS_USE_MD5 1)
set(KWSYS_USE_Process 1)
set(KWSYS_USE_CommandLineArguments 1)
set(KWSYS_USE_ConsoleBuf 1)
set(KWSYS_HEADER_ROOT ${CMake_BINARY_DIR}/Source)
set(KWSYS_INSTALL_DOC_DIR "${CMAKE_DOC_DIR}")
if(CMake_NO_CXX_STANDARD)
set(KWSYS_CXX_STANDARD "")
endif()
if(CMake_NO_SELF_BACKTRACE)
set(KWSYS_NO_EXECINFO 1)
endif()
if(WIN32)
# FIXME: Teach KWSys to hard-code these checks on Windows.
set(KWSYS_C_HAS_CLOCK_GETTIME_MONOTONIC_COMPILED 0)
set(KWSYS_C_HAS_PTRDIFF_T_COMPILED 1)
set(KWSYS_CXX_HAS_ENVIRON_IN_STDLIB_H_COMPILED 1)
set(KWSYS_CXX_HAS_RLIMIT64_COMPILED 0)
set(KWSYS_CXX_HAS_SETENV_COMPILED 0)
set(KWSYS_CXX_HAS_UNSETENV_COMPILED 0)
set(KWSYS_CXX_HAS_UTIMENSAT_COMPILED 0)
set(KWSYS_CXX_HAS_UTIMES_COMPILED 0)
set(KWSYS_CXX_STAT_HAS_ST_MTIM_COMPILED 0)
set(KWSYS_CXX_STAT_HAS_ST_MTIMESPEC_COMPILED 0)
set(KWSYS_STL_HAS_WSTRING_COMPILED 1)
set(KWSYS_SYS_HAS_IFADDRS_H 0)
endif()
add_subdirectory(Source/kwsys)
set(kwsys_folder "Utilities/KWSys")
CMAKE_SET_TARGET_FOLDER(${KWSYS_NAMESPACE} "${kwsys_folder}")
CMAKE_SET_TARGET_FOLDER(${KWSYS_NAMESPACE}_c "${kwsys_folder}")
if(BUILD_TESTING)
CMAKE_SET_TARGET_FOLDER(${KWSYS_NAMESPACE}TestDynload "${kwsys_folder}")
CMAKE_SET_TARGET_FOLDER(${KWSYS_NAMESPACE}TestProcess "${kwsys_folder}")
CMAKE_SET_TARGET_FOLDER(${KWSYS_NAMESPACE}TestsC "${kwsys_folder}")
CMAKE_SET_TARGET_FOLDER(${KWSYS_NAMESPACE}TestsCxx "${kwsys_folder}")
CMAKE_SET_TARGET_FOLDER(${KWSYS_NAMESPACE}TestSharedForward "${kwsys_folder}")
endif()
#---------------------------------------------------------------------
# Setup third-party libraries.
# Everything in the tree should be able to include files from the
# Utilities directory.
if ((CMAKE_SYSTEM_NAME STREQUAL "AIX" OR CMAKE_SYSTEM_NAME STREQUAL "OS400") AND CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
# using -isystem option generate error "template with C linkage"
include_directories("${CMake_SOURCE_DIR}/Utilities/std")
else()
include_directories(SYSTEM "${CMake_SOURCE_DIR}/Utilities/std")
endif()
include_directories("${CMake_BINARY_DIR}/Utilities")
if ((CMAKE_SYSTEM_NAME STREQUAL "AIX" OR CMAKE_SYSTEM_NAME STREQUAL "OS400") AND CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
# using -isystem option generate error "template with C linkage"
include_directories("${CMake_SOURCE_DIR}/Utilities")
else()
include_directories(SYSTEM "${CMake_SOURCE_DIR}/Utilities")
endif()
#---------------------------------------------------------------------
# Build CMake std library for CMake and CTest.
set(CMAKE_STD_LIBRARY cmstd)
add_subdirectory(Utilities/std)
CMAKE_SET_TARGET_FOLDER(cmstd "Utilities/std")
# check for the use of system libraries versus builtin ones
# (a macro defined in this file)
CMAKE_HANDLE_SYSTEM_LIBRARIES()
if(CMAKE_USE_SYSTEM_KWIML)
find_package(KWIML 1.0)
if(NOT KWIML_FOUND)
message(FATAL_ERROR "CMAKE_USE_SYSTEM_KWIML is ON but KWIML is not found!")
endif()
set(CMake_KWIML_LIBRARIES kwiml::kwiml)
else()
set(CMake_KWIML_LIBRARIES "")
if(BUILD_TESTING)
set(KWIML_TEST_ENABLE 1)
endif()
add_subdirectory(Utilities/KWIML)
endif()
if(CMAKE_USE_SYSTEM_LIBRHASH)
find_package(LibRHash)
if(NOT LibRHash_FOUND)
message(FATAL_ERROR
"CMAKE_USE_SYSTEM_LIBRHASH is ON but LibRHash is not found!")
endif()
set(CMAKE_LIBRHASH_LIBRARIES LibRHash::LibRHash)
else()
set(CMAKE_LIBRHASH_LIBRARIES cmlibrhash)
add_subdirectory(Utilities/cmlibrhash)
CMAKE_SET_TARGET_FOLDER(cmlibrhash "Utilities/3rdParty")
endif()
#---------------------------------------------------------------------
# Build zlib library for Curl, CMake, and CTest.
set(CMAKE_ZLIB_HEADER "cm_zlib.h")
if(CMAKE_USE_SYSTEM_ZLIB)
find_package(ZLIB)
if(NOT ZLIB_FOUND)
message(FATAL_ERROR
"CMAKE_USE_SYSTEM_ZLIB is ON but a zlib is not found!")
endif()
set(CMAKE_ZLIB_INCLUDES ${ZLIB_INCLUDE_DIR})
set(CMAKE_ZLIB_LIBRARIES ${ZLIB_LIBRARIES})
else()
set(CMAKE_ZLIB_INCLUDES ${CMake_SOURCE_DIR}/Utilities)
set(CMAKE_ZLIB_LIBRARIES cmzlib)
set(WITHOUT_ZLIB_DLL "")
set(WITHOUT_ZLIB_DLL_WITH_LIB cmzlib)
set(ZLIB_DLL "")
set(ZLIB_DLL_WITH_LIB cmzlib)
set(ZLIB_WINAPI "")
set(ZLIB_WINAPI_COMPILED 0)
set(ZLIB_WINAPI_WITH_LIB cmzlib)
add_subdirectory(Utilities/cmzlib)
CMAKE_SET_TARGET_FOLDER(cmzlib "Utilities/3rdParty")
endif()
#---------------------------------------------------------------------
# Build Curl library for CTest.
if(CMAKE_USE_SYSTEM_CURL)
find_package(CURL)
if(NOT CURL_FOUND)
message(FATAL_ERROR
"CMAKE_USE_SYSTEM_CURL is ON but a curl is not found!")
endif()
set(CMAKE_CURL_INCLUDES ${CURL_INCLUDE_DIRS})
set(CMAKE_CURL_LIBRARIES ${CURL_LIBRARIES})
else()
set(CURL_SPECIAL_ZLIB_H ${CMAKE_ZLIB_HEADER})
set(CURL_SPECIAL_LIBZ_INCLUDES ${CMAKE_ZLIB_INCLUDES})
set(CURL_SPECIAL_LIBZ ${CMAKE_ZLIB_LIBRARIES})
set(CMAKE_CURL_INCLUDES)
set(CMAKE_CURL_LIBRARIES cmcurl)
if(CMAKE_TESTS_CDASH_SERVER)
set(CMAKE_CURL_TEST_URL "${CMAKE_TESTS_CDASH_SERVER}/user.php")
endif()
set(_CMAKE_USE_OPENSSL_DEFAULT OFF)
if(NOT DEFINED CMAKE_USE_OPENSSL AND NOT WIN32 AND NOT APPLE
AND CMAKE_SYSTEM_NAME MATCHES "(Linux|FreeBSD)")
set(_CMAKE_USE_OPENSSL_DEFAULT ON)
endif()
option(CMAKE_USE_OPENSSL "Use OpenSSL." ${_CMAKE_USE_OPENSSL_DEFAULT})
mark_as_advanced(CMAKE_USE_OPENSSL)
if(CMAKE_USE_OPENSSL)
set(CURL_CA_BUNDLE "" CACHE FILEPATH "Path to SSL CA Certificate Bundle")
set(CURL_CA_PATH "" CACHE PATH "Path to SSL CA Certificate Directory")
mark_as_advanced(CURL_CA_BUNDLE CURL_CA_PATH)
endif()
if(NOT CMAKE_USE_SYSTEM_NGHTTP2)
# Tell curl's FindNGHTTP2 module to use our library.
set(NGHTTP2_LIBRARY cmnghttp2)
set(NGHTTP2_INCLUDE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/Utilities/cmnghttp2/lib/includes)
endif()
add_subdirectory(Utilities/cmcurl)
CMAKE_SET_TARGET_FOLDER(cmcurl "Utilities/3rdParty")
CMAKE_SET_TARGET_FOLDER(LIBCURL "Utilities/3rdParty")
if(NOT CMAKE_USE_SYSTEM_NGHTTP2)
# Configure after curl to re-use some check results.
add_subdirectory(Utilities/cmnghttp2)
CMAKE_SET_TARGET_FOLDER(cmnghttp2 "Utilities/3rdParty")
endif()
endif()
#---------------------------------------------------------------------
# Build expat library for CMake, CTest, and libarchive.
if(CMAKE_USE_SYSTEM_EXPAT)
find_package(EXPAT)
if(NOT EXPAT_FOUND)
message(FATAL_ERROR
"CMAKE_USE_SYSTEM_EXPAT is ON but a expat is not found!")
endif()
set(CMAKE_EXPAT_INCLUDES ${EXPAT_INCLUDE_DIRS})
set(CMAKE_EXPAT_LIBRARIES ${EXPAT_LIBRARIES})
else()
set(CMAKE_EXPAT_INCLUDES)
set(CMAKE_EXPAT_LIBRARIES cmexpat)
add_subdirectory(Utilities/cmexpat)
CMAKE_SET_TARGET_FOLDER(cmexpat "Utilities/3rdParty")
endif()
#---------------------------------------------------------------------
# Build or use system libbz2 for libarchive.
if(NOT CMAKE_USE_SYSTEM_LIBARCHIVE)
if(CMAKE_USE_SYSTEM_BZIP2)
find_package(BZip2)
else()
set(BZIP2_INCLUDE_DIR
"${CMAKE_CURRENT_SOURCE_DIR}/Utilities/cmbzip2")
set(BZIP2_LIBRARIES cmbzip2)
set(BZIP2_NEED_PREFIX "")
set(USE_BZIP2_DLL "")
set(USE_BZIP2_DLL_WITH_LIB cmbzip2)
set(USE_BZIP2_STATIC "")
set(USE_BZIP2_STATIC_WITH_LIB cmbzip2)
add_subdirectory(Utilities/cmbzip2)
CMAKE_SET_TARGET_FOLDER(cmbzip2 "Utilities/3rdParty")
endif()
endif()
#---------------------------------------------------------------------
# Build or use system zstd for libarchive.
if(NOT CMAKE_USE_SYSTEM_LIBARCHIVE)
if(NOT CMAKE_USE_SYSTEM_ZSTD)
set(ZSTD_INCLUDE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/Utilities/cmzstd")
set(ZSTD_LIBRARY cmzstd)
add_subdirectory(Utilities/cmzstd)
CMAKE_SET_TARGET_FOLDER(cmzstd "Utilities/3rdParty")
endif()
endif()
#---------------------------------------------------------------------
# Build or use system liblzma for libarchive.
if(NOT CMAKE_USE_SYSTEM_LIBARCHIVE)
if(CMAKE_USE_SYSTEM_LIBLZMA)
find_package(LibLZMA)
if(NOT LIBLZMA_FOUND)
message(FATAL_ERROR "CMAKE_USE_SYSTEM_LIBLZMA is ON but LibLZMA is not found!")
endif()
else()
add_subdirectory(Utilities/cmliblzma)
CMAKE_SET_TARGET_FOLDER(cmliblzma "Utilities/3rdParty")
set(LIBLZMA_HAS_AUTO_DECODER 1)
set(LIBLZMA_HAS_EASY_ENCODER 1)
set(LIBLZMA_HAS_LZMA_PRESET 1)
set(LIBLZMA_INCLUDE_DIR
"${CMAKE_CURRENT_SOURCE_DIR}/Utilities/cmliblzma/liblzma/api")
set(LIBLZMA_LIBRARY cmliblzma)
set(HAVE_LZMA_STREAM_ENCODER_MT 1)
endif()
endif()
#---------------------------------------------------------------------
# Build or use system libarchive for CMake and CTest.
if(CMAKE_USE_SYSTEM_LIBARCHIVE)
find_package(LibArchive 3.3.3)
if(NOT LibArchive_FOUND)
message(FATAL_ERROR "CMAKE_USE_SYSTEM_LIBARCHIVE is ON but LibArchive is not found!")
endif()
set(CMAKE_TAR_INCLUDES ${LibArchive_INCLUDE_DIRS})
set(CMAKE_TAR_LIBRARIES ${LibArchive_LIBRARIES})
else()
set(EXPAT_INCLUDE_DIR ${CMAKE_EXPAT_INCLUDES})
set(EXPAT_LIBRARY ${CMAKE_EXPAT_LIBRARIES})
set(ZLIB_INCLUDE_DIR ${CMAKE_ZLIB_INCLUDES})
set(ZLIB_LIBRARY ${CMAKE_ZLIB_LIBRARIES})
add_definitions(-DLIBARCHIVE_STATIC)
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})
endif()
#---------------------------------------------------------------------
# Build jsoncpp library.
if(CMAKE_USE_SYSTEM_JSONCPP)
find_package(JsonCpp 1.4.1)
if(NOT JsonCpp_FOUND)
message(FATAL_ERROR
"CMAKE_USE_SYSTEM_JSONCPP is ON but a JsonCpp is not found!")
endif()
if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|LCC|Clang")
set_property(TARGET JsonCpp::JsonCpp APPEND PROPERTY
INTERFACE_COMPILE_OPTIONS -Wno-deprecated-declarations)
endif()
set(CMAKE_JSONCPP_LIBRARIES JsonCpp::JsonCpp)
else()
set(CMAKE_JSONCPP_LIBRARIES cmjsoncpp)
add_subdirectory(Utilities/cmjsoncpp)
CMAKE_SET_TARGET_FOLDER(cmjsoncpp "Utilities/3rdParty")
endif()
#---------------------------------------------------------------------
# Build libuv library.
if(CMAKE_USE_SYSTEM_LIBUV)
if(WIN32)
find_package(LibUV 1.38.0)
else()
find_package(LibUV 1.28.0)
endif()
if(NOT LIBUV_FOUND)
message(FATAL_ERROR
"CMAKE_USE_SYSTEM_LIBUV is ON but a libuv is not found!")
endif()
set(CMAKE_LIBUV_LIBRARIES LibUV::LibUV)
else()
set(CMAKE_LIBUV_LIBRARIES cmlibuv)
add_subdirectory(Utilities/cmlibuv)
CMAKE_SET_TARGET_FOLDER(cmlibuv "Utilities/3rdParty")
endif()
#---------------------------------------------------------------------
# Use curses?
if(NOT DEFINED BUILD_CursesDialog)
if (UNIX)
include(${CMake_SOURCE_DIR}/Source/Checks/Curses.cmake)
set(BUILD_CursesDialog_DEFAULT "${CMakeCheckCurses_COMPILED}")
elseif(WIN32)
set(BUILD_CursesDialog_DEFAULT "OFF")
endif()
option(BUILD_CursesDialog "Build the CMake Curses Dialog ccmake" "${BUILD_CursesDialog_DEFAULT}")
endif ()
if(BUILD_CursesDialog)
if(UNIX)
set(CURSES_NEED_NCURSES TRUE)
find_package(Curses)
if(NOT CURSES_FOUND)
message(WARNING
"'ccmake' will not be built because Curses was not found.\n"
"Turn off BUILD_CursesDialog to suppress this message."
)
set(BUILD_CursesDialog 0)
endif()
elseif(WIN32)
# FIXME: Add support for system-provided pdcurses.
add_subdirectory(Utilities/cmpdcurses)
set(CURSES_LIBRARY cmpdcurses)
set(CURSES_INCLUDE_PATH "") # cmpdcurses has usage requirements
set(CMAKE_USE_SYSTEM_FORM 0)
set(HAVE_CURSES_USE_DEFAULT_COLORS 1)
endif()
endif()
if(BUILD_CursesDialog)
if(NOT CMAKE_USE_SYSTEM_FORM)
add_subdirectory(Source/CursesDialog/form)
elseif(NOT CURSES_FORM_LIBRARY)
message( FATAL_ERROR "CMAKE_USE_SYSTEM_FORM in ON but CURSES_FORM_LIBRARY is not set!" )
endif()
endif()
endmacro ()
#-----------------------------------------------------------------------
if(NOT CMake_TEST_EXTERNAL_CMAKE)
if(CMAKE_CXX_PLATFORM_ID MATCHES "OpenBSD")
@ -749,7 +344,7 @@ include(Source/CMakeVersion.cmake)
# Include the standard Dart testing module
enable_testing()
include (${CMAKE_ROOT}/Modules/Dart.cmake)
include(${CMAKE_ROOT}/Modules/Dart.cmake)
# Set up test-time configuration.
set_directory_properties(PROPERTIES
@ -803,8 +398,9 @@ if(CMake_TEST_EXTERNAL_CMAKE)
endif()
if(NOT CMake_TEST_EXTERNAL_CMAKE)
# build the utilities (a macro defined in this file)
CMAKE_BUILD_UTILITIES()
find_package(Threads)
# build the utilities
include(CMakeBuildUtilities)
if(BUILD_QtDialog)
if(APPLE)
@ -813,10 +409,9 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
set(CMAKE_BUNDLE_LOCATION "${CMAKE_INSTALL_PREFIX}")
# make sure CMAKE_INSTALL_PREFIX ends in /
if(NOT CMAKE_INSTALL_PREFIX MATCHES "/$")
set(CMAKE_INSTALL_PREFIX "${CMAKE_INSTALL_PREFIX}/")
string(APPEND CMAKE_INSTALL_PREFIX "/")
endif()
set(CMAKE_INSTALL_PREFIX
"${CMAKE_INSTALL_PREFIX}CMake.app/Contents")
string(APPEND CMAKE_INSTALL_PREFIX "CMake.app/Contents")
endif()
endif()
@ -829,14 +424,11 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
endif()
# add the uninstall support
configure_file(
"${CMAKE_CURRENT_SOURCE_DIR}/cmake_uninstall.cmake.in"
"${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake"
@ONLY)
configure_file(cmake_uninstall.cmake.in cmake_uninstall.cmake @ONLY)
add_custom_target(uninstall
"${CMAKE_COMMAND}" -P "${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake")
include (CMakeCPack.cmake)
include(CMakeCPack.cmake)
endif()
@ -860,10 +452,10 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
-Wshadow -Wpointer-arith -Wformat-security -Wundef
)
foreach(FLAG_LANG C CXX)
foreach(FLAG ${${FLAG_LANG}_FLAGS_LIST})
foreach(FLAG_LANG IN ITEMS C CXX)
foreach(FLAG IN LISTS ${FLAG_LANG}_FLAGS_LIST)
if(NOT " ${CMAKE_${FLAG_LANG}_FLAGS} " MATCHES " ${FLAG} ")
set(CMAKE_${FLAG_LANG}_FLAGS "${CMAKE_${FLAG_LANG}_FLAGS} ${FLAG}")
string(APPEND CMAKE_${FLAG_LANG}_FLAGS " ${FLAG}")
endif()
endforeach()
endforeach()
@ -883,9 +475,6 @@ add_subdirectory(Tests)
if(NOT CMake_TEST_EXTERNAL_CMAKE)
if(BUILD_TESTING)
CMAKE_SET_TARGET_FOLDER(CMakeLibTests "Tests")
IF(TARGET CMakeServerLibTests)
CMAKE_SET_TARGET_FOLDER(CMakeServerLibTests "Tests")
ENDIF()
endif()
if(TARGET documentation)
CMAKE_SET_TARGET_FOLDER(documentation "Documentation")
@ -894,7 +483,8 @@ endif()
if(BUILD_TESTING)
add_test(SystemInformationNew "${CMAKE_CMAKE_COMMAND}"
--system-information -G "${CMAKE_GENERATOR}" )
--system-information -G "${CMAKE_GENERATOR}"
)
endif()
if(NOT CMake_TEST_EXTERNAL_CMAKE)

6
CTestCustom.cmake.in
View File

@ -74,6 +74,7 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
"cm(StringCommand|CTestTestHandler)\\.cxx.*warning.*rand.*may return deterministic values"
"cm(StringCommand|CTestTestHandler)\\.cxx.*warning.*rand.*isn.*t random" # we do not do crypto
"cm(StringCommand|CTestTestHandler)\\.cxx.*warning.*srand.*seed choices are.*poor" # we do not do crypto
"cmFindPackageCommand.cxx.*: warning #177-D: parameter .* was declared but never referenced"
"IPA warning: function.*multiply defined in"
"LICENSE WARNING" # PGI license expiry. Not useful in nightly testing.
@ -83,6 +84,11 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
"compilation completed with warnings" # PGI
"[0-9]+ Warning\\(s\\) detected" # SunPro
# Ignore false positive on `cm::optional` usage from GCC
"cmGlobalNinjaGenerator.cxx:[0-9]*:[0-9]*: warning: '.*cm::optional<CxxModuleMapFormat>::_mem\\)\\)' may be used uninitialized \\[-Wmaybe-uninitialized\\]"
"cmGlobalNinjaGenerator.cxx:[0-9]*:[0-9]*: note: '.*cm::optional<CxxModuleMapFormat>::_mem\\)\\)' was declared here"
"cmGlobalNinjaGenerator.cxx:[0-9]*:[0-9]*: warning: '\\*\\(\\(void\\*\\)& modmap_fmt \\+4\\)' may be used uninitialized in this function \\[-Wmaybe-uninitialized\\]"
# clang-analyzer exceptions
"cmListFileLexer.c:[0-9]+:[0-9]+: warning: Array subscript is undefined"
"jsoncpp/src/.*:[0-9]+:[0-9]+: warning: Value stored to .* is never read"

17
CompileFlags.cmake
View File

@ -18,12 +18,12 @@ endif()
# not hurt other versions, and this will work into the
# future
if(MSVC OR _INTEL_WINDOWS OR _CLANG_MSVC_WINDOWS)
add_definitions(-D_CRT_SECURE_NO_DEPRECATE -D_CRT_NONSTDC_NO_DEPRECATE)
add_compile_definitions(_CRT_SECURE_NO_DEPRECATE _CRT_NONSTDC_NO_DEPRECATE)
else()
endif()
if(MSVC)
set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -stack:10000000")
set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} ${CMAKE_CXX_LINKER_WRAPPER_FLAG}-stack:10000000")
endif()
# MSVC 14.28 enables C5105, but the Windows SDK 10.0.18362.0 triggers it.
@ -62,7 +62,7 @@ endif()
# Use 64-bit off_t on 32-bit Linux
if (CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_SIZEOF_VOID_P EQUAL 4)
# ensure 64bit offsets are used for filesystem accesses for 32bit compilation
add_definitions(-D_FILE_OFFSET_BITS=64)
add_compile_definitions(_FILE_OFFSET_BITS=64)
endif()
# Workaround for TOC Overflow on ppc64
@ -98,7 +98,7 @@ if (CMAKE_CXX_COMPILER_ID STREQUAL SunPro AND
endif()
endif()
foreach(lang C CXX)
foreach(lang IN ITEMS C CXX)
# Suppress warnings from PGI compiler.
if (CMAKE_${lang}_COMPILER_ID STREQUAL "PGI")
set(CMAKE_${lang}_FLAGS "${CMAKE_${lang}_FLAGS} -w")
@ -136,3 +136,12 @@ OFF to disable /MP completely." )
endif()
endif()
endif()
# Get rid of excess -Wunused-but-set-variable on release builds with LCC >= 1.26
foreach(l IN ITEMS C CXX)
if(CMAKE_${l}_COMPILER_ID STREQUAL "LCC" AND NOT CMAKE_${l}_COMPILER_VERSION VERSION_LESS 1.26)
foreach(c IN ITEMS MINSIZEREL RELEASE RELWITHDEBINFO)
string(APPEND "CMAKE_${l}_FLAGS_${c}" " -Wno-unused-but-set-variable")
endforeach()
endif()
endforeach()

1
Copyright.txt
View File

@ -53,6 +53,7 @@ The following individuals and institutions are among the Contributors:
* Clement Creusot <creusot@cs.york.ac.uk>
* Daniel Blezek <blezek@gmail.com>
* Daniel Pfeifer <daniel@pfeifer-mail.de>
* Dawid Wróbel <me@dawidwrobel.com>
* Enrico Scholz <enrico.scholz@informatik.tu-chemnitz.de>
* Eran Ifrah <eran.ifrah@gmail.com>
* Esben Mose Hansen, Ange Optimization ApS

26
Help/command/FIND_XXX.txt
View File

@ -15,6 +15,7 @@ The general signature is:
[PATHS [path | ENV var]... ]
[REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[VALIDATOR function]
[DOC "cache documentation string"]
[NO_CACHE]
[REQUIRED]
@ -66,6 +67,31 @@ Options include:
Specify additional subdirectories to check below each directory
location otherwise considered.
``VALIDATOR``
.. versionadded:: 3.25
Specify a :command:`function` to be called for each candidate item found
(a :command:`macro` cannot be provided, that will result in an error).
Two arguments will be passed to the validator function: the name of a
result variable, and the absolute path to the candidate item. The item
will be accepted and the search will end unless the function sets the
value in the result variable to false in the calling scope. The result
variable will hold a true value when the validator function is entered.
.. parsed-literal::
function(my_check validator_result_var item)
if(NOT item MATCHES ...)
set(${validator_result_var} FALSE PARENT_SCOPE)
endif()
endfunction()
|FIND_XXX| (result NAMES ... VALIDATOR my_check)
Note that if a cached result is used, the search is skipped and any
``VALIDATOR`` is ignored. The cached result is not required to pass the
validation function.
``DOC``
Specify the documentation string for the ``<VAR>`` cache entry.

4
Help/command/add_custom_command.rst
View File

@ -67,6 +67,8 @@ The options are:
Each byproduct file will be marked with the :prop_sf:`GENERATED`
source file property automatically.
*See policy* :policy:`CMP0058` *for the motivation behind this feature.*
Explicit specification of byproducts is supported by the
:generator:`Ninja` generator to tell the ``ninja`` build tool
how to regenerate byproducts when they are missing. It is
@ -434,7 +436,7 @@ one of the keywords to make clear the behavior they expect.
Because generator expressions can be used in custom commands,
it is possible to define ``COMMAND`` lines or whole custom commands
which evaluate to empty strings for certain configurations.
For **Visual Studio 2010 (and newer)** generators these command
For **Visual Studio 11 2012 (and newer)** generators these command
lines or custom commands will be omitted for the specific
configuration and no "empty-string-command" will be added.

2
Help/command/add_custom_target.rst
View File

@ -42,6 +42,8 @@ The options are:
Each byproduct file will be marked with the :prop_sf:`GENERATED`
source file property automatically.
*See policy* :policy:`CMP0058` *for the motivation behind this feature.*
Explicit specification of byproducts is supported by the
:generator:`Ninja` generator to tell the ``ninja`` build tool
how to regenerate byproducts when they are missing. It is

9
Help/command/add_subdirectory.rst
View File

@ -5,7 +5,7 @@ Add a subdirectory to the build.
.. code-block:: cmake
add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL])
add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL] [SYSTEM])
Adds a subdirectory to the build. The source_dir specifies the
directory in which the source CMakeLists.txt and code files are
@ -33,3 +33,10 @@ dependencies supersede this exclusion. If a target built by the
parent project depends on a target in the subdirectory, the dependee
target will be included in the parent project build system to satisfy
the dependency.
If the ``SYSTEM`` argument is provided, the :prop_dir:`SYSTEM` directory
property of the subdirectory will be set to true. This property is
used to initialize the :prop_tgt:`SYSTEM` property of each target
created in that subdirectory. The include directories of targets with
:prop_tgt:`SYSTEM` set to true will be treated as ``SYSTEM`` when
compiling consumers.

76
Help/command/block.rst Normal file
View File

@ -0,0 +1,76 @@
block
-----
.. versionadded:: 3.25
Evaluate a group of commands with a dedicated variable and/or policy scope.
.. code-block:: cmake
block([SCOPE_FOR [POLICIES] [VARIABLES] ] [PROPAGATE <var-name>...])
<commands>
endblock()
All commands between ``block()`` and the matching :command:`endblock` are
recorded without being invoked. Once the :command:`endblock` is evaluated, the
recorded list of commands is invoked inside the requested scopes, then the
scopes created by the ``block()`` command are removed.
``SCOPE_FOR``
Specify which scopes must be created.
``POLICIES``
Create a new policy scope. This is equivalent to
:command:`cmake_policy(PUSH)`.
``VARIABLES``
Create a new variable scope.
If ``SCOPE_FOR`` is not specified, this is equivalent to:
.. code-block:: cmake
block(SCOPE_FOR VARIABLES POLICIES)
``PROPAGATE``
When a variable scope is created by the :command:`block` command, this
option sets or unsets the specified variables in the parent scope. This is
equivalent to :command:`set(PARENT_SCOPE)` or :command:`unset(PARENT_SCOPE)`
commands.
.. code-block:: cmake
set(var1 "INIT1")
set(var2 "INIT2")
block(PROPAGATE var1 var2)
set(var1 "VALUE1")
unset(var2)
endblock()
# Now var1 holds VALUE1, and var2 is unset
This option is only allowed when a variable scope is created. An error will
be raised in the other cases.
When the ``block()`` is inside a :command:`foreach` or :command:`while`
command, the :command:`break` and :command:`continue` commands can be used
inside the block.
.. code-block:: cmake
while(TRUE)
block()
...
# the break() command will terminate the while() command
break()
endblock()
endwhile()
See Also
^^^^^^^^
* :command:`endblock`
* :command:`return`
* :command:`cmake_policy`

8
Help/command/build_command.rst
View File

@ -24,12 +24,12 @@ options, if any. The trailing ``-- -i`` option is added for
:ref:`Makefile Generators` if policy :policy:`CMP0061` is not set to
``NEW``.
When invoked, this ``cmake --build`` command line will launch the
When invoked, this :option:`cmake --build` command line will launch the
underlying build system tool.
.. versionadded:: 3.21
The ``PARALLEL_LEVEL`` argument can be used to set the ``--parallel``
flag.
The ``PARALLEL_LEVEL`` argument can be used to set the
:option:`--parallel <cmake--build --parallel>` flag.
.. code-block:: cmake
@ -39,7 +39,7 @@ This second signature is deprecated, but still available for backwards
compatibility. Use the first signature instead.
It sets the given ``<cachevariable>`` to a command-line string as
above but without the ``--target`` option.
above but without the :option:`--target <cmake--build --target>` option.
The ``<makecommand>`` is ignored but should be the full path to
devenv, nmake, make or one of the end user build tools
for legacy invocations.

28
Help/command/cmake_language.rst
View File

@ -14,6 +14,7 @@ Synopsis
cmake_language(`EVAL`_ CODE <code>...)
cmake_language(`DEFER`_ <options>... CALL <command> [<arg>...])
cmake_language(`SET_DEPENDENCY_PROVIDER`_ <command> SUPPORTED_METHODS <methods>...)
cmake_language(`GET_MESSAGE_LOG_LEVEL`_ <out-var>)
Introduction
^^^^^^^^^^^^
@ -50,6 +51,7 @@ is equivalent to
To ensure consistency of the code, the following commands are not allowed:
* ``if`` / ``elseif`` / ``else`` / ``endif``
* ``block`` / ``endblock``
* ``while`` / ``endwhile``
* ``foreach`` / ``endforeach``
* ``function`` / ``endfunction``
@ -491,3 +493,29 @@ calling the provider command recursively for the same dependency.
SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
SUPPORTED_METHODS FIND_PACKAGE
)
Getting current message log level
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. versionadded:: 3.25
.. _GET_MESSAGE_LOG_LEVEL:
.. _query_message_log_level:
.. code-block:: cmake
cmake_language(GET_MESSAGE_LOG_LEVEL <output_variable>)
Writes the current :command:`message` logging level
into the given ``<output_variable>``.
See :command:`message` for the possible logging levels.
The current message logging level can be set either using the
:option:`--log-level <cmake --log-level>`
command line option of the :manual:`cmake(1)` program or using
the :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable.
If both the command line option and the variable are set, the command line
option takes precedence. If neither are set, the default logging level
is returned.

41
Help/command/cmake_policy.rst
View File

@ -103,6 +103,47 @@ Calls to the :command:`cmake_minimum_required(VERSION)`,
``cmake_policy(VERSION)``, or ``cmake_policy(SET)`` commands
influence only the current top of the policy stack.
.. versionadded:: 3.25
The :command:`block` and :command:`endblock` commands offer a more flexible
and more secure way to manage the policy stack. The pop action is done
automatically when the :command:`endblock` command is executed, so it avoid
to call the :command:`cmake_policy(POP)` command before each
:command:`return` command.
.. code-block:: cmake
# stack management with cmake_policy()
function(my_func)
cmake_policy(PUSH)
cmake_policy(SET ...)
if (<cond1>)
...
cmake_policy(POP)
return()
elseif(<cond2>)
...
cmake_policy(POP)
return()
endif()
...
cmake_policy(POP)
endfunction()
# stack management with block()/endblock()
function(my_func)
block(SCOPE_FOR POLICIES)
cmake_policy(SET ...)
if (<cond1>)
...
return()
elseif(<cond2>)
...
return()
endif()
...
endblock()
endfunction()
Commands created by the :command:`function` and :command:`macro`
commands record policy settings when they are created and
use the pre-record policies when they are invoked. If the function or

6
Help/command/continue.rst
View File

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

6
Help/command/ctest_build.rst
View File

@ -40,8 +40,8 @@ The options are:
``CONFIGURATION <config>``
Specify the build configuration (e.g. ``Debug``). If not
specified the ``CTEST_BUILD_CONFIGURATION`` variable will be checked.
Otherwise the ``-C <cfg>`` option given to the :manual:`ctest(1)`
command will be used, if any.
Otherwise the :option:`-C \<cfg\> <ctest -C>` option given to the
:manual:`ctest(1)` command will be used, if any.
``PARALLEL_LEVEL <parallel>``
.. versionadded:: 3.21
@ -54,7 +54,7 @@ The options are:
Pass additional arguments to the underlying build command.
If not specified the ``CTEST_BUILD_FLAGS`` variable will be checked.
This can, e.g., be used to trigger a parallel build using the
``-j`` option of make. See the :module:`ProcessorCount` module
``-j`` option of ``make``. See the :module:`ProcessorCount` module
for an example.
``PROJECT_NAME <project-name>``

6
Help/command/ctest_run_script.rst
View File

@ -1,15 +1,15 @@
ctest_run_script
----------------
runs a ctest -S script
runs a :option:`ctest -S` script
::
ctest_run_script([NEW_PROCESS] script_file_name script_file_name1
script_file_name2 ... [RETURN_VALUE var])
Runs a script or scripts much like if it was run from ctest -S. If no
argument is provided then the current script is run using the current
Runs a script or scripts much like if it was run from :option:`ctest -S`.
If no argument is provided then the current script is run using the current
settings of the variables. If ``NEW_PROCESS`` is specified then each
script will be run in a separate process.If ``RETURN_VALUE`` is specified
the return value of the last script run will be put into ``var``.

2
Help/command/ctest_start.rst
View File

@ -45,7 +45,7 @@ The parameters are as follows:
ctest_start(Experimental GROUP GroupExperimental)
Later, in another ``ctest -S`` script:
Later, in another :option:`ctest -S` script:
.. code-block:: cmake

10
Help/command/ctest_test.rst
View File

@ -109,8 +109,9 @@ The options are:
While running tests in parallel, try not to start tests when they
may cause the CPU load to pass above a given threshold. If not
specified the :variable:`CTEST_TEST_LOAD` variable will be checked,
and then the ``--test-load`` command-line argument to :manual:`ctest(1)`.
See also the ``TestLoad`` setting in the :ref:`CTest Test Step`.
and then the :option:`--test-load <ctest --test-load>` command-line
argument to :manual:`ctest(1)`. See also the ``TestLoad`` setting
in the :ref:`CTest Test Step`.
``REPEAT <mode>:<n>``
.. versionadded:: 3.17
@ -176,8 +177,9 @@ 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, along with their
corresponding :manual:`ctest(1)` command line options
``--test-output-size-passed``, ``--test-output-size-failed``, and
``--test-output-truncation``.
:option:`--test-output-size-passed <ctest --test-output-size-passed>`,
:option:`--test-output-size-failed <ctest --test-output-size-failed>`, and
:option:`--test-output-truncation <ctest --test-output-truncation>`.
.. _`Additional Test Measurements`:

9
Help/command/enable_language.rst
View File

@ -1,13 +1,14 @@
enable_language
---------------
Enable a language (CXX/C/OBJC/OBJCXX/Fortran/etc)
Enable languages (CXX/C/OBJC/OBJCXX/Fortran/etc)
.. code-block:: cmake
enable_language(<lang> [OPTIONAL] )
enable_language(<lang>... [OPTIONAL])
Enables support for the named language in CMake. This is
the same as the :command:`project` command but does not create any of the extra
Enables support for the named languages in CMake. This is the same as
the :command:`project` command but does not create any of the extra
variables that are created by the project command. Example languages
are ``CXX``, ``C``, ``CUDA``, ``OBJC``, ``OBJCXX``, ``Fortran``,
``HIP``, ``ISPC``, and ``ASM``.

11
Help/command/endblock.rst Normal file
View File

@ -0,0 +1,11 @@
endblock
--------
.. versionadded:: 3.25
Ends a list of commands in a :command:`block` and removes the scopes
created by the :command:`block` command.
.. code-block:: cmake
endblock()

16
Help/command/export.rst
View File

@ -25,7 +25,8 @@ Exporting Targets
.. code-block:: cmake
export(TARGETS <target>... [NAMESPACE <namespace>]
[APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
[APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES]
[CXX_MODULES_DIRECTORY <directory>])
Creates a file ``<filename>`` that may be included by outside projects to
import targets named by ``<target>...`` from the current project's build tree.
@ -52,6 +53,16 @@ The options are:
in the export, even when policy :policy:`CMP0022` is NEW. This is useful
to support consumers using CMake versions older than 2.8.12.
``CXX_MODULES_DIRECTORY <directory>``
.. note ::
Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
Export C++ module properties to files under the given directory. Each file
will be named according to the target's export name (without any namespace).
These files will automatically be included from the export file.
This signature requires all targets to be listed explicitly. If a library
target is included in the export, but a target to which it links is not
included, the behavior is unspecified. See the `export(EXPORT)`_ signature
@ -95,7 +106,8 @@ Exporting Targets matching install(EXPORT)
.. code-block:: cmake
export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>]
[CXX_MODULES_DIRECTORY <directory>])
Creates a file ``<filename>`` that may be included by outside projects to
import targets from the current project's build tree. This is the same

7
Help/command/file.rst
View File

@ -1121,8 +1121,11 @@ Additional options to ``DOWNLOAD`` are:
Verify that the downloaded content hash matches the expected value, where
``ALGO`` is one of the algorithms supported by ``file(<HASH>)``.
If it does not match, the operation fails with an error. It is an error to
specify this if ``DOWNLOAD`` is not given a ``<file>``.
If the file already exists and matches the hash, the download is skipped.
If the file already exists and does not match the hash, the file is
downloaded again. If after download the file does not match the hash, the
operation fails with an error. It is an error to specify this option if
``DOWNLOAD`` is not given a ``<file>``.
``EXPECTED_MD5 <value>``
Historical short-hand for ``EXPECTED_HASH MD5=<value>``. It is an error to

49
Help/command/find_package.rst
View File

@ -285,29 +285,40 @@ CMake constructs a set of possible installation prefixes for the
package. Under each prefix several directories are searched for a
configuration file. The tables below show the directories searched.
Each entry is meant for installation trees following Windows (``W``), UNIX
(``U``), or Apple (``A``) conventions::
(``U``), or Apple (``A``) conventions:
<prefix>/ (W)
<prefix>/(cmake|CMake)/ (W)
<prefix>/<name>*/ (W)
<prefix>/<name>*/(cmake|CMake)/ (W)
<prefix>/(lib/<arch>|lib*|share)/cmake/<name>*/ (U)
<prefix>/(lib/<arch>|lib*|share)/<name>*/ (U)
<prefix>/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (U)
<prefix>/<name>*/(lib/<arch>|lib*|share)/cmake/<name>*/ (W/U)
<prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/ (W/U)
<prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (W/U)
==================================================================== ==========
Entry Convention
==================================================================== ==========
``<prefix>/`` W
``<prefix>/(cmake|CMake)/`` W
``<prefix>/<name>*/`` W
``<prefix>/<name>*/(cmake|CMake)/`` W
``<prefix>/<name>*/(cmake|CMake)/<name>*/`` [#]_ W
``<prefix>/(lib/<arch>|lib*|share)/cmake/<name>*/`` U
``<prefix>/(lib/<arch>|lib*|share)/<name>*/`` U
``<prefix>/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/`` U
``<prefix>/<name>*/(lib/<arch>|lib*|share)/cmake/<name>*/`` W/U
``<prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/`` W/U
``<prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/`` W/U
==================================================================== ==========
.. [#] .. versionadded:: 3.25
On systems supporting macOS :prop_tgt:`FRAMEWORK` and :prop_tgt:`BUNDLE`, the
following directories are searched for Frameworks or Application Bundles
containing a configuration file::
containing a configuration file:
<prefix>/<name>.framework/Resources/ (A)
<prefix>/<name>.framework/Resources/CMake/ (A)
<prefix>/<name>.framework/Versions/*/Resources/ (A)
<prefix>/<name>.framework/Versions/*/Resources/CMake/ (A)
<prefix>/<name>.app/Contents/Resources/ (A)
<prefix>/<name>.app/Contents/Resources/CMake/ (A)
=========================================================== ==========
Entry Convention
=========================================================== ==========
``<prefix>/<name>.framework/Resources/`` A
``<prefix>/<name>.framework/Resources/CMake/`` A
``<prefix>/<name>.framework/Versions/*/Resources/`` A
``<prefix>/<name>.framework/Versions/*/Resources/CMake/`` A
``<prefix>/<name>.app/Contents/Resources/`` A
``<prefix>/<name>.app/Contents/Resources/CMake/`` A
=========================================================== ==========
In all cases the ``<name>`` is treated as case-insensitive and corresponds
to any of the names specified (``<PackageName>`` or names given by ``NAMES``).
@ -368,7 +379,7 @@ enabled.
See policy :policy:`CMP0074`.
2. Search paths specified in cmake-specific cache variables. These
are intended to be used on the command line with a ``-DVAR=value``.
are intended to be used on the command line with a :option:`-DVAR=VALUE <cmake -D>`.
The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`.
This can be skipped if ``NO_CMAKE_PATH`` is passed or by setting the
:variable:`CMAKE_FIND_USE_CMAKE_PATH` to ``FALSE``:

8
Help/command/foreach.rst
View File

@ -130,3 +130,11 @@ yields
-- en=two, ba=dua
-- en=three, ba=tiga
-- en=four, ba=
See Also
^^^^^^^^
* :command:`break`
* :command:`continue`
* :command:`endforeach`
* :command:`while`

6
Help/command/function.rst
View File

@ -73,3 +73,9 @@ argument. Referencing to ``ARGV#`` arguments beyond ``ARGC`` have
undefined behavior. Checking that ``ARGC`` is greater than ``#`` is
the only way to ensure that ``ARGV#`` was passed to the function as an
extra argument.
See Also
^^^^^^^^
* :command:`endfunction`
* :command:`return`

3
Help/command/get_test_property.rst
View File

@ -16,6 +16,7 @@ relevant parent scope as described for the :command:`define_property`
command and if still unable to find the property, ``VAR`` will be set to
an empty string.
For a list of standard properties you can type ``cmake --help-property-list``.
For a list of standard properties you can type
:option:`cmake --help-property-list`.
See also the more general :command:`get_property` command.

7
Help/command/if.rst
View File

@ -424,3 +424,10 @@ There is no automatic evaluation for environment or cache
:ref:`Variable References`. Their values must be referenced as
``$ENV{<name>}`` or ``$CACHE{<name>}`` wherever the above-documented
condition syntax accepts ``<variable|string>``.
See also
^^^^^^^^
* :command:`else`
* :command:`elseif`
* :command:`endif`

49
Help/command/install.rst
View File

@ -132,7 +132,7 @@ Installing Targets
install(TARGETS targets... [EXPORT <export-name>]
[RUNTIME_DEPENDENCIES args...|RUNTIME_DEPENDENCY_SET <set-name>]
[[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|
PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE|FILE_SET <set-name>]
PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE|FILE_SET <set-name>|CXX_MODULES_BMI]
[DESTINATION <dir>]
[PERMISSIONS permissions...]
[CONFIGURATIONS [Debug|Release|...]]
@ -215,11 +215,21 @@ that may be installed:
``/blah/include/myproj/here.h`` with a base directory ``/blah/include``
would be installed to ``myproj/here.h`` below the destination.
``CXX_MODULES_BMI``
.. note ::
Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
Any module files from C++ modules from ``PUBLIC`` sources in a file set of
type ``CXX_MODULES`` will be installed to the given ``DESTINATION``. All
modules are placed directly in the destination as no directory structure is
derived from the names of the modules. An empty ``DESTINATION`` may be used
to suppress installing these files (for use in generic code).
For each of these arguments given, the arguments following them only apply
to the target or file type specified in the argument. If none is given, the
installation properties apply to all target types. If only one is given then
only targets of that type will be installed (which can be used to install
just a DLL or just an import library.)
installation properties apply to all target types.
For regular executables, static libraries and shared libraries, the
``DESTINATION`` argument is not required. For these target types, when
@ -233,6 +243,14 @@ Apple bundles and frameworks. A destination can be omitted for interface and
object libraries, but they are handled differently (see the discussion of this
topic toward the end of this section).
For shared libraries on DLL platforms, if neither ``RUNTIME`` nor ``ARCHIVE``
destinations are specified, both the ``RUNTIME`` and ``ARCHIVE`` components are
installed to their default destinations. If either a ``RUNTIME`` or ``ARCHIVE``
destination is specified, the component is installed to that destination, and
the other component is not installed. If both ``RUNTIME`` and ``ARCHIVE``
destinations are specified, then both components are installed to their
respective destinations.
The following table shows the target types with their associated variables and
built-in defaults that apply when no destination is given:
@ -778,9 +796,10 @@ Installing Exports
.. code-block:: cmake
install(EXPORT <export-name> DESTINATION <dir>
[NAMESPACE <namespace>] [[FILE <name>.cmake]|
[NAMESPACE <namespace>] [FILE <name>.cmake]
[PERMISSIONS permissions...]
[CONFIGURATIONS [Debug|Release|...]]
[CONFIGURATIONS [Debug|Release|...]
[CXX_MODULES_DIRECTORY <directory>]
[EXPORT_LINK_INTERFACE_LIBRARIES]
[COMPONENT <component>]
[EXCLUDE_FROM_ALL])
@ -836,6 +855,18 @@ library is always installed if the headers and CMake export file are present.
to an ndk build system complete with transitive dependencies, include flags
and defines required to use the libraries.
``CXX_MODULES_DIRECTORY``
.. note ::
Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
Specify a subdirectory to store C++ module information for targets in the
export set. This directory will be populated with files which add the
necessary target property information to the relevant targets. Note that
without this information, none of the C++ modules which are part of the
targets in the export set will support being imported in consuming targets.
The ``EXPORT`` form is useful to help outside projects use targets built
and installed by the current project. For example, the code
@ -932,12 +963,12 @@ Generated Installation Script
.. note::
Use of this feature is not recommended. Please consider using the
``--install`` argument of :manual:`cmake(1)` instead.
:option:`cmake --install` instead.
The ``install()`` command generates a file, ``cmake_install.cmake``, inside
the build directory, which is used internally by the generated install target
and by CPack. You can also invoke this script manually with ``cmake -P``. This
script accepts several variables:
and by CPack. You can also invoke this script manually with
:option:`cmake -P`. This script accepts several variables:
``COMPONENT``
Set this variable to install only a single CPack component as opposed to all

7
Help/command/message.rst
View File

@ -83,8 +83,9 @@ are sent to stderr and are not prefixed with hyphens. The
:manual:`CMake GUI <cmake-gui(1)>` displays all messages in its log area.
The :manual:`curses interface <ccmake(1)>` shows ``STATUS`` to ``TRACE``
messages one at a time on a status line and other messages in an
interactive pop-up box. The ``--log-level`` command-line option to each of
these tools can be used to control which messages will be shown.
interactive pop-up box. The :option:`--log-level <cmake --log-level>`
command-line option to each of these tools can be used to control which
messages will be shown.
.. versionadded:: 3.17
To make a log level persist between CMake runs, the
@ -104,7 +105,7 @@ these tools can be used to control which messages will be shown.
list variable to a dot-separated string. The message context will always
appear before any indenting content but after any automatically added leading
hyphens. By default, message context is not shown, it has to be explicitly
enabled by giving the :manual:`cmake <cmake(1)>` ``--log-context``
enabled by giving the :option:`cmake --log-context`
command-line option or by setting the :variable:`CMAKE_MESSAGE_CONTEXT_SHOW`
variable to true. See the :variable:`CMAKE_MESSAGE_CONTEXT` documentation for
usage examples.

85
Help/command/return.rst
View File

@ -5,16 +5,87 @@ Return from a file, directory or function.
.. code-block:: cmake
return()
return([PROPAGATE <var-name>...])
Returns from a file, directory or function. When this command is
encountered in an included file (via :command:`include` or
When this command is encountered in an included file (via :command:`include` or
:command:`find_package`), it causes processing of the current file to stop
and control is returned to the including file. If it is encountered in a
file which is not included by another file, e.g. a ``CMakeLists.txt``,
file which is not included by another file, e.g. a ``CMakeLists.txt``,
deferred calls scheduled by :command:`cmake_language(DEFER)` are invoked and
control is returned to the parent directory if there is one. If return is
called in a function, control is returned to the caller of the function.
control is returned to the parent directory if there is one.
Note that a :command:`macro <macro>`, unlike a :command:`function <function>`,
If ``return()`` is called in a function, control is returned to the caller
of that function. Note that a :command:`macro`, unlike a :command:`function`,
is expanded in place and therefore cannot handle ``return()``.
Policy :policy:`CMP0140` controls the behavior regarding the arguments of the
command. All arguments are ignored unless that policy is set to ``NEW``.
``PROPAGATE``
.. versionadded:: 3.25
This option sets or unsets the specified variables in the parent directory or
function caller scope. This is equivalent to :command:`set(PARENT_SCOPE)` or
:command:`unset(PARENT_SCOPE)` commands, except for the way it interacts
with the :command:`block` command, as described below.
The ``PROPAGATE`` option can be very useful in conjunction with the
:command:`block` command. A :command:`return` will propagate the
specified variables through any enclosing block scopes created by the
:command:`block` commands. Inside a function, this ensures the variables
are propagated to the function's caller, regardless of any blocks within
the function. If not inside a function, it ensures the variables are
propagated to the parent file or directory scope. For example:
.. code-block:: cmake
:caption: CMakeLists.txt
cmake_version_required(VERSION 3.25)
project(example)
set(var1 "top-value")
block(SCOPE_FOR VARIABLES)
add_subdirectory(subDir)
# var1 has the value "block-nested"
endblock()
# var1 has the value "top-value"
.. code-block:: cmake
:caption: subDir/CMakeLists.txt
function(multi_scopes result_var1 result_var2)
block(SCOPE_FOR VARIABLES)
# This would only propagate out of the immediate block, not to
# the caller of the function.
#set(${result_var1} "new-value" PARENT_SCOPE)
#unset(${result_var2} PARENT_SCOPE)
# This propagates the variables through the enclosing block and
# out to the caller of the function.
set(${result_var1} "new-value")
unset(${result_var2})
return(PROPAGATE ${result_var1} ${result_var2})
endblock()
endfunction()
set(var1 "some-value")
set(var2 "another-value")
multi_scopes(var1 var2)
# Now var1 will hold "new-value" and var2 will be unset
block(SCOPE_FOR VARIABLES)
# This return() will set var1 in the directory scope that included us
# via add_subdirectory(). The surrounding block() here does not limit
# propagation to the current file, but the block() in the parent
# directory scope does prevent propagation going any further.
set(var1 "block-nested")
return(PROPAGATE var1)
endblock()
See Also
^^^^^^^^
* :command:`block`

19
Help/command/set.rst
View File

@ -22,12 +22,17 @@ Set Normal Variable
Sets the given ``<variable>`` in the current function or directory scope.
If the ``PARENT_SCOPE`` option is given the variable will be set in
the scope above the current scope. Each new directory or function
creates a new scope. This command will set the value of a variable
into the parent directory or calling function (whichever is applicable
to the case at hand). The previous state of the variable's value stays the
same in the current scope (e.g., if it was undefined before, it is still
undefined and if it had a value, it is still that value).
the scope above the current scope. Each new directory or :command:`function`
command creates a new scope. A scope can also be created with the
:command:`block` command. This command will set the value of a variable into
the parent directory, calling function or encompassing scope (whichever is
applicable to the case at hand). The previous state of the variable's value
stays the same in the current scope (e.g., if it was undefined before, it is
still undefined and if it had a value, it is still that value).
The :command:`block(PROPAGATE)` and :command:`return(PROPAGATE)` commands can
be used as an alternate method to the :command:`set(PARENT_SCOPE)` and
:command:`unset(PARENT_SCOPE)` commands to update the parent scope.
Set Cache Entry
^^^^^^^^^^^^^^^
@ -78,7 +83,7 @@ option is given then the cache entry will be set to the given value.
It is possible for the cache entry to exist prior to the call but
have no type set if it was created on the :manual:`cmake(1)` command
line by a user through the ``-D<var>=<value>`` option without
line by a user through the :option:`-D\<var\>=\<value\> <cmake -D>` option without
specifying a type. In this case the ``set`` command will add the
type. Furthermore, if the ``<type>`` is ``PATH`` or ``FILEPATH``
and the ``<value>`` provided on the command line is a relative path,

6
Help/command/target_compile_definitions.rst
View File

@ -15,9 +15,9 @@ named ``<target>`` must have been created by a command such as
:ref:`ALIAS target <Alias Targets>`.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC``
items will populate the :prop_tgt:`COMPILE_DEFINITIONS` property of
``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
specify the :ref:`scope <Target Usage Requirements>` of the following arguments.
``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`COMPILE_DEFINITIONS`
property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` property of ``<target>``.
The following arguments specify compile definitions. Repeated calls for the
same ``<target>`` append items in the order called.

6
Help/command/target_compile_options.rst
View File

@ -22,9 +22,9 @@ If ``BEFORE`` is specified, the content will be prepended to the property
instead of being appended.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC``
items will populate the :prop_tgt:`COMPILE_OPTIONS` property of
``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
specify the :ref:`scope <Target Usage Requirements>` of the following arguments.
``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`COMPILE_OPTIONS`
property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_COMPILE_OPTIONS` property of ``<target>``.
The following arguments specify compile options. Repeated calls for the same
``<target>`` append items in the order called.

6
Help/command/target_include_directories.rst
View File

@ -18,9 +18,9 @@ By using ``AFTER`` or ``BEFORE`` explicitly, you can select between appending
and prepending, independent of the default.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to specify
the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` items will
populate the :prop_tgt:`INCLUDE_DIRECTORIES` property of ``<target>``.
``PUBLIC`` and ``INTERFACE`` items will populate the
the :ref:`scope <Target Usage Requirements>` of the following arguments.
``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`INCLUDE_DIRECTORIES`
property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` property of ``<target>``.
The following arguments specify include directories.

11
Help/command/target_link_directories.rst
View File

@ -21,11 +21,12 @@ The named ``<target>`` must have been created by a command such as
:ref:`ALIAS target <Alias Targets>`.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the scope of the items that follow them. ``PRIVATE`` and
``PUBLIC`` items will populate the :prop_tgt:`LINK_DIRECTORIES` property
of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_LINK_DIRECTORIES` property of ``<target>``
(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items).
specify the :ref:`scope <Target Usage Requirements>` of the items that follow
them. ``PRIVATE`` and ``PUBLIC`` items will populate the
:prop_tgt:`LINK_DIRECTORIES` property of ``<target>``. ``PUBLIC`` and
``INTERFACE`` items will populate the :prop_tgt:`INTERFACE_LINK_DIRECTORIES`
property of ``<target>`` (:ref:`IMPORTED targets <Imported Targets>` only
support ``INTERFACE`` items).
Each item specifies a link directory and will be converted to an absolute
path if necessary before adding it to the relevant property. Repeated
calls for the same ``<target>`` append items in the order called.

4
Help/command/target_link_libraries.rst
View File

@ -146,8 +146,10 @@ Libraries for a Target and/or its Dependents
<PRIVATE|PUBLIC|INTERFACE> <item>...
[<PRIVATE|PUBLIC|INTERFACE> <item>...]...)
The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` keywords can be used to
The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE``
:ref:`scope <Target Usage Requirements>` keywords can be used to
specify both the link dependencies and the link interface in one command.
Libraries and targets following ``PUBLIC`` are linked to, and are made
part of the link interface. Libraries and targets following ``PRIVATE``
are linked to, but are not made part of the link interface. Libraries

6
Help/command/target_link_options.rst
View File

@ -32,9 +32,9 @@ If ``BEFORE`` is specified, the content will be prepended to the property
instead of being appended.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC``
items will populate the :prop_tgt:`LINK_OPTIONS` property of
``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
specify the :ref:`scope <Target Usage Requirements>` of the following arguments.
``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`LINK_OPTIONS`
property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_LINK_OPTIONS` property of ``<target>``.
The following arguments specify link options. Repeated calls for the same
``<target>`` append items in the order called.

6
Help/command/target_precompile_headers.rst
View File

@ -25,9 +25,9 @@ The named ``<target>`` must have been created by a command such as
:ref:`ALIAS target <Alias Targets>`.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC``
items will populate the :prop_tgt:`PRECOMPILE_HEADERS` property of
``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
specify the :ref:`scope <Target Usage Requirements>` of the following arguments.
``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`PRECOMPILE_HEADERS`
property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` property of ``<target>``
(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items).
Repeated calls for the same ``<target>`` will append items in the order called.

85
Help/command/target_sources.rst
View File

@ -22,10 +22,10 @@ The named ``<target>`` must have been created by a command such as
``<target>`` can be a custom target.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
specify the scope of the source file paths (``<items>``) that follow
them. ``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`SOURCES`
property of ``<target>``, which are used when building the target itself.
``PUBLIC`` and ``INTERFACE`` items will populate the
specify the :ref:`scope <Target Usage Requirements>` of the source file paths
(``<items>``) that follow them. ``PRIVATE`` and ``PUBLIC`` items will
populate the :prop_tgt:`SOURCES` property of ``<target>``, which are used when
building the target itself. ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_SOURCES` property of ``<target>``, which are used
when building dependents. A target created by :command:`add_custom_target`
can only have ``PRIVATE`` scope.
@ -75,9 +75,33 @@ File Sets
Adds a file set to a target, or adds files to an existing file set. Targets
have zero or more named file sets. Each file set has a name, a type, a scope of
``INTERFACE``, ``PUBLIC``, or ``PRIVATE``, one or more base directories, and
files within those directories. The only acceptable type is ``HEADERS``. The
optional default file sets are named after their type. The target may not be a
custom target or :prop_tgt:`FRAMEWORK` target.
files within those directories. The acceptable types include:
``HEADERS``
Sources intended to be used via a language's ``#include`` mechanism.
``CXX_MODULES``
.. note ::
Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
Sources which contain C++ interface module or partition units (i.e., those
using the ``export`` keyword). This file set type may not have an
``INTERFACE`` scope except on ``IMPORTED`` targets.
``CXX_MODULE_HEADER_UNITS``
.. note ::
Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
C++ header sources which may be imported by other C++ source code. This file
set type may not have an ``INTERFACE`` scope except on ``IMPORTED`` targets.
The optional default file sets are named after their type. The target may not
be a custom target or :prop_tgt:`FRAMEWORK` target.
Files in a ``PRIVATE`` or ``PUBLIC`` file set are marked as source files for
the purposes of IDE integration. Additionally, files in ``HEADERS`` file sets
@ -93,16 +117,17 @@ Each ``target_sources(FILE_SET)`` entry starts with ``INTERFACE``, ``PUBLIC``, o
The name of the file set to create or add to. It must contain only letters,
numbers and underscores. Names starting with a capital letter are reserved
for built-in file sets predefined by CMake. The only predefined set name is
``HEADERS``. All other set names must not start with a capital letter or
for built-in file sets predefined by CMake. The only predefined set names
are those matching the acceptable types. All other set names must not start
with a capital letter or
underscore.
``TYPE <type>``
Every file set is associated with a particular type of file. ``HEADERS``
is currently the only defined type and it is an error to specify anything
else. As a special case, if the name of the file set is ``HEADERS``, the
type does not need to be specified and the ``TYPE <type>`` arguments can be
Every file set is associated with a particular type of file. Only types
specified above may be used and it is an error to specify anything else. As
a special case, if the name of the file set is one of the types, the type
does not need to be specified and the ``TYPE <type>`` arguments can be
omitted. For all other file set names, ``TYPE`` is required.
``BASE_DIRS <dirs>...``
@ -134,6 +159,8 @@ Each ``target_sources(FILE_SET)`` entry starts with ``INTERFACE``, ``PUBLIC``, o
The following target properties are set by ``target_sources(FILE_SET)``,
but they should not generally be manipulated directly:
For file sets of type ``HEADERS``:
* :prop_tgt:`HEADER_SETS`
* :prop_tgt:`INTERFACE_HEADER_SETS`
* :prop_tgt:`HEADER_SET`
@ -141,17 +168,37 @@ but they should not generally be manipulated directly:
* :prop_tgt:`HEADER_DIRS`
* :prop_tgt:`HEADER_DIRS_<NAME>`
For file sets of type ``CXX_MODULES``:
* :prop_tgt:`CXX_MODULE_SETS`
* :prop_tgt:`INTERFACE_CXX_MODULE_SETS`
* :prop_tgt:`CXX_MODULE_SET`
* :prop_tgt:`CXX_MODULE_SET_<NAME>`
* :prop_tgt:`CXX_MODULE_DIRS`
* :prop_tgt:`CXX_MODULE_DIRS_<NAME>`
For file sets of type ``CXX_MODULE_HEADER_UNITS``:
* :prop_tgt:`CXX_MODULE_HEADER_UNIT_SETS`
* :prop_tgt:`INTERFACE_CXX_MODULE_HEADER_UNIT_SETS`
* :prop_tgt:`CXX_MODULE_HEADER_UNIT_SET`
* :prop_tgt:`CXX_MODULE_HEADER_UNIT_SET_<NAME>`
* :prop_tgt:`CXX_MODULE_HEADER_UNIT_DIRS`
* :prop_tgt:`CXX_MODULE_HEADER_UNIT_DIRS_<NAME>`
Target properties related to include directories are also modified by
``target_sources(FILE_SET)`` as follows:
:prop_tgt:`INCLUDE_DIRECTORIES`
If the ``TYPE`` is ``HEADERS``, and the scope of the file set is ``PRIVATE``
or ``PUBLIC``, all of the ``BASE_DIRS`` of the file set are wrapped in
:genex:`$<BUILD_INTERFACE>` and appended to this property.
If the ``TYPE`` is ``HEADERS`` or ``CXX_MODULE_HEADER_UNITS``, and the scope
of the file set is ``PRIVATE`` or ``PUBLIC``, all of the ``BASE_DIRS`` of
the file set are wrapped in :genex:`$<BUILD_INTERFACE>` and appended to this
property.
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`
If the ``TYPE`` is ``HEADERS``, and the scope of the file set is
``INTERFACE`` or ``PUBLIC``, all of the ``BASE_DIRS`` of the file set are
wrapped in :genex:`$<BUILD_INTERFACE>` and appended to this property.
If the ``TYPE`` is ``HEADERS`` or ``CXX_MODULE_HEADER_UNITS``, and the scope
of the file set is ``INTERFACE`` or ``PUBLIC``, all of the ``BASE_DIRS`` of
the file set are wrapped in :genex:`$<BUILD_INTERFACE>` and appended to this
property.

151
Help/command/try_compile.rst
View File

@ -14,10 +14,16 @@ Try Compiling Whole Projects
.. code-block:: cmake
try_compile(<resultVar> <bindir> <srcdir>
<projectName> [<targetName>] [CMAKE_FLAGS <flags>...]
try_compile(<resultVar> PROJECT <projectName>
SOURCE_DIR <srcdir>
[BINARY_DIR <bindir>]
[TARGET <targetName>]
[NO_CACHE]
[CMAKE_FLAGS <flags>...]
[OUTPUT_VARIABLE <var>])
.. versionadded:: 3.25
Try building a project. The success or failure of the ``try_compile``,
i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``<resultVar>``.
@ -34,6 +40,17 @@ below for the meaning of other options.
Previously this was only done by the
:ref:`source file <Try Compiling Source Files>` signature.
This command also supports an alternate signature
which was present in older versions of CMake:
.. code-block:: cmake
try_compile(<resultVar> <bindir> <srcdir>
<projectName> [<targetName>]
[NO_CACHE]
[CMAKE_FLAGS <flags>...]
[OUTPUT_VARIABLE <var>])
.. _`Try Compiling Source Files`:
Try Compiling Source Files
@ -41,7 +58,12 @@ Try Compiling Source Files
.. code-block:: cmake
try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...>
try_compile(<resultVar>
<SOURCES <srcfile...> |
SOURCE_FROM_CONTENT <name> <content> |
SOURCE_FROM_VAR <name> <var> |
SOURCE_FROM_FILE <name> <path> >...
[NO_CACHE]
[CMAKE_FLAGS <flags>...]
[COMPILE_DEFINITIONS <defs>...]
[LINK_OPTIONS <options>...]
@ -53,15 +75,19 @@ Try Compiling Source Files
[<LANG>_EXTENSIONS <bool>]
)
.. versionadded:: 3.25
Try building an executable or static library from one or more source files
(which one is determined by the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE`
variable). The success or failure of the ``try_compile``, i.e. ``TRUE`` or
``FALSE`` respectively, is returned in ``<resultVar>``.
In this form, one or more source files must be provided. If
:variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is unset or is set to ``EXECUTABLE``,
the sources must include a definition for ``main`` and CMake will create a
``CMakeLists.txt`` file to build the source(s) as an executable.
In this form, one or more source files must be provided. Additionally, one of
``SOURCES`` and/or ``SOURCE_FROM_*`` must precede other keywords.
If :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is unset or is set to
``EXECUTABLE``, the sources must include a definition for ``main`` and CMake
will create a ``CMakeLists.txt`` file to build the source(s) as an executable.
If :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``STATIC_LIBRARY``,
a static library will be built instead and no definition for ``main`` is
required. For an executable, the generated ``CMakeLists.txt`` file would
@ -76,11 +102,45 @@ contain something like the following:
target_link_options(cmTryCompileExec PRIVATE <LINK_OPTIONS from caller>)
target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})
CMake automatically generates, for each ``try_compile`` operation, a
unique directory under ``${CMAKE_BINARY_DIR}/CMakeFiles/CMakeScratch``
with an unspecified name. These directories are cleaned automatically unless
:option:`--debug-trycompile <cmake --debug-trycompile>` is passed to ``cmake``.
Such directories from previous runs are also unconditionally cleaned at the
beginning of any ``cmake`` execution.
This command also supports an alternate signature
which was present in older versions of CMake:
.. code-block:: cmake
try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...>
[NO_CACHE]
[CMAKE_FLAGS <flags>...]
[COMPILE_DEFINITIONS <defs>...]
[LINK_OPTIONS <options>...]
[LINK_LIBRARIES <libs>...]
[OUTPUT_VARIABLE <var>]
[COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
[<LANG>_STANDARD <std>]
[<LANG>_STANDARD_REQUIRED <bool>]
[<LANG>_EXTENSIONS <bool>]
)
In this version, ``try_compile`` will use ``<bindir>/CMakeFiles/CMakeTmp`` for
its operation, and all such files will be cleaned automatically.
For debugging, :option:`--debug-trycompile <cmake --debug-trycompile>` can be
passed to ``cmake`` to avoid this clean. However, multiple sequential
``try_compile`` operations, if given the same ``<bindir>``, will reuse this
single output directory, such that you can only debug one such ``try_compile``
call at a time. Use of the newer signature is recommended to simplify
debugging of multiple ``try_compile`` operations.
The options are:
``CMAKE_FLAGS <flags>...``
Specify flags of the form ``-DVAR:TYPE=VALUE`` to be passed to
the ``cmake`` command-line used to drive the test build.
Specify flags of the form :option:`-DVAR:TYPE=VALUE <cmake -D>` to be passed
to the :manual:`cmake(1)` command-line used to drive the test build.
The above example shows how values for variables
``INCLUDE_DIRECTORIES``, ``LINK_DIRECTORIES``, and ``LINK_LIBRARIES``
are used.
@ -111,9 +171,61 @@ The options are:
set the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property in the generated
project, depending on the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable.
``NO_CACHE``
.. versionadded:: 3.25
The result will be stored in a normal variable rather than a cache entry.
The result variable is normally cached so that a simple pattern can be used
to avoid repeating the test on subsequent executions of CMake:
.. code-block:: cmake
if(NOT DEFINED RESULTVAR)
# ...(check-specific setup code)...
try_compile(RESULTVAR ...)
# ...(check-specific logging and cleanup code)...
endif()
If the guard variable and result variable are not the same (for example, if
the test is part of a larger inspection), ``NO_CACHE`` may be useful to avoid
leaking the intermediate result variable into the cache.
``OUTPUT_VARIABLE <var>``
Store the output from the build process in the given variable.
``SOURCE_FROM_CONTENT <name> <content>``
.. versionadded:: 3.25
Write ``<content>`` to a file named ``<name>`` in the operation directory.
This can be used to bypass the need to separately write a source file when
the contents of the file are dynamically specified. The specified ``<name>``
is not allowed to contain path components.
``SOURCE_FROM_CONTENT`` may be specified multiple times.
``SOURCE_FROM_FILE <name> <path>``
.. versionadded:: 3.25
Copy ``<path>`` to a file named ``<name>`` in the operation directory. This
can be used to consolidate files into the operation directory, which may be
useful if a source which already exists (i.e. as a stand-alone file in a
project's source repository) needs to refer to other file(s) created by
``SOURCE_FROM_*``. (Otherwise, ``SOURCES`` is usually more convenient.) The
specified ``<name>`` is not allowed to contain path components.
``SOURCE_FROM_VAR <name> <var>``
.. versionadded:: 3.25
Write the contents of ``<var>`` to a file named ``<name>`` in the operation
directory. This is the same as ``SOURCE_FROM_CONTENT``, but takes the
contents from the specified CMake variable, rather than directly, which may
be useful when passing arguments through a function which wraps
``try_compile``. The specified ``<name>`` is not allowed to contain path
components.
``SOURCE_FROM_VAR`` may be specified multiple times.
``<LANG>_STANDARD <std>``
.. versionadded:: 3.8
@ -136,17 +248,6 @@ The options are:
:prop_tgt:`OBJC_EXTENSIONS`, :prop_tgt:`OBJCXX_EXTENSIONS`,
or :prop_tgt:`CUDA_EXTENSIONS` target property of the generated project.
In this version all files in ``<bindir>/CMakeFiles/CMakeTmp`` will be
cleaned automatically. For debugging, ``--debug-trycompile`` can be
passed to ``cmake`` to avoid this clean. However, multiple sequential
``try_compile`` operations reuse this single output directory. If you use
``--debug-trycompile``, you can only debug one ``try_compile`` call at a time.
The recommended procedure is to protect all ``try_compile`` calls in your
project by ``if(NOT DEFINED <resultVar>)`` logic, configure with cmake
all the way through once, then delete the cache entry associated with
the try_compile call of interest, and then re-run cmake again with
``--debug-trycompile``.
Other Behavior Settings
^^^^^^^^^^^^^^^^^^^^^^^
@ -214,9 +315,15 @@ a build configuration.
the generated project (unless overridden by an explicit option).
.. 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.
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.
.. versionadded:: 3.25
If :policy:`CMP0141` is set to ``NEW``, one can use
:variable:`CMAKE_MSVC_DEBUG_INFORMATION_FORMAT` to specify the MSVC debug
information format.

96
Help/command/try_run.rst
View File

@ -13,68 +13,99 @@ Try Compiling and Running Source Files
.. code-block:: cmake
try_run(<runResultVar> <compileResultVar>
<bindir> <srcfile> [CMAKE_FLAGS <flags>...]
<SOURCES <srcfile...> |
SOURCE_FROM_CONTENT <name> <content> |
SOURCE_FROM_VAR <name> <var> |
SOURCE_FROM_FILE <name> <path> >...
[NO_CACHE]
[CMAKE_FLAGS <flags>...]
[COMPILE_DEFINITIONS <defs>...]
[LINK_OPTIONS <options>...]
[LINK_LIBRARIES <libs>...]
[COMPILE_OUTPUT_VARIABLE <var>]
[COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
[<LANG>_STANDARD <std>]
[<LANG>_STANDARD_REQUIRED <bool>]
[<LANG>_EXTENSIONS <bool>]
[RUN_OUTPUT_VARIABLE <var>]
[RUN_OUTPUT_STDOUT_VARIABLE <var>]
[RUN_OUTPUT_STDERR_VARIABLE <var>]
[OUTPUT_VARIABLE <var>]
[WORKING_DIRECTORY <var>]
[ARGS <args>...])
[ARGS <args>...]
)
.. versionadded:: 3.25
Try compiling a ``<srcfile>``. Returns ``TRUE`` or ``FALSE`` for success
or failure in ``<compileResultVar>``. If the compile succeeded, runs the
executable and returns its exit code in ``<runResultVar>``. If the
executable was built, but failed to run, then ``<runResultVar>`` will be
set to ``FAILED_TO_RUN``. See the :command:`try_compile` command for
information on how the test project is constructed to build the source file.
documentation of options common to both commands, and for information on how
the test project is constructed to build the source file.
The options are:
One or more source files must be provided. Additionally, one of ``SOURCES``
and/or ``SOURCE_FROM_*`` must precede other keywords.
``CMAKE_FLAGS <flags>...``
Specify flags of the form ``-DVAR:TYPE=VALUE`` to be passed to
the ``cmake`` command-line used to drive the test build.
The example in :command:`try_compile` shows how values for variables
``INCLUDE_DIRECTORIES``, ``LINK_DIRECTORIES``, and ``LINK_LIBRARIES``
are used.
This command also supports an alternate signature
which was present in older versions of CMake:
``COMPILE_DEFINITIONS <defs>...``
Specify ``-Ddefinition`` arguments to pass to :command:`add_definitions`
in the generated test project.
.. code-block:: cmake
try_run(<runResultVar> <compileResultVar>
<bindir> <srcfile|SOURCES srcfile...>
[NO_CACHE]
[CMAKE_FLAGS <flags>...]
[COMPILE_DEFINITIONS <defs>...]
[LINK_OPTIONS <options>...]
[LINK_LIBRARIES <libs>...]
[COMPILE_OUTPUT_VARIABLE <var>]
[COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
[<LANG>_STANDARD <std>]
[<LANG>_STANDARD_REQUIRED <bool>]
[<LANG>_EXTENSIONS <bool>]
[RUN_OUTPUT_VARIABLE <var>]
[RUN_OUTPUT_STDOUT_VARIABLE <var>]
[RUN_OUTPUT_STDERR_VARIABLE <var>]
[OUTPUT_VARIABLE <var>]
[WORKING_DIRECTORY <var>]
[ARGS <args>...]
)
The options specific to ``try_run`` are:
``COMPILE_OUTPUT_VARIABLE <var>``
Report the compile step build output in a given variable.
``LINK_LIBRARIES <libs>...``
.. versionadded:: 3.2
Specify libraries to be linked in the generated project.
The list of libraries may refer to system libraries and to
:ref:`Imported Targets <Imported Targets>` from the calling project.
If this option is specified, any ``-DLINK_LIBRARIES=...`` value
given to the ``CMAKE_FLAGS`` option will be ignored.
``LINK_OPTIONS <options>...``
.. versionadded:: 3.14
Specify link step options to pass to :command:`target_link_options` in the
generated project.
``OUTPUT_VARIABLE <var>``
Report the compile build output and the output from running the executable
in the given variable. This option exists for legacy reasons. Prefer
``COMPILE_OUTPUT_VARIABLE`` and ``RUN_OUTPUT_VARIABLE`` instead.
in the given variable. This option exists for legacy reasons and is only
supported by the old ``try_run`` signature.
Prefer ``COMPILE_OUTPUT_VARIABLE`` and ``RUN_OUTPUT_VARIABLE`` instead.
``RUN_OUTPUT_VARIABLE <var>``
Report the output from running the executable in a given variable.
``RUN_OUTPUT_STDOUT_VARIABLE <var>``
.. versionadded:: 3.25
Report the output of stdout from running the executable in a given variable.
``RUN_OUTPUT_STDERR_VARIABLE <var>``
.. versionadded:: 3.25
Report the output of stderr from running the executable in a given variable.
``WORKING_DIRECTORY <var>``
.. versionadded:: 3.20
Run the executable in the given directory. If no ``WORKING_DIRECTORY`` is
specified, the executable will run in ``<bindir>``.
specified, the executable will run in ``<bindir>`` or the current build
directory.
``ARGS <args>...``
Additional arguments to pass to the executable when running it.
Other Behavior Settings
^^^^^^^^^^^^^^^^^^^^^^^
@ -110,6 +141,7 @@ These cache entries are:
In order to make cross compiling your project easier, use ``try_run``
only if really required. If you use ``try_run``, use the
``RUN_OUTPUT_STDOUT_VARIABLE``, ``RUN_OUTPUT_STDERR_VARIABLE``,
``RUN_OUTPUT_VARIABLE`` or ``OUTPUT_VARIABLE`` options only if really
required. Using them will require that when cross-compiling, the cache
variables will have to be set manually to the output of the executable.

8
Help/command/while.rst
View File

@ -23,3 +23,11 @@ Per legacy, the :command:`endwhile` command admits
an optional ``<condition>`` argument.
If used, it must be a verbatim repeat of the argument of the opening
``while`` command.
See Also
^^^^^^^^
* :command:`break`
* :command:`continue`
* :command:`foreach`
* :command:`endwhile`

6
Help/cpack_gen/archive.rst
View File

@ -57,6 +57,12 @@ Variables specific to CPack Archive generator
.. versionadded:: 3.9
Per-component ``CPACK_ARCHIVE_<component>_FILE_NAME`` variables.
.. variable:: CPACK_ARCHIVE_FILE_EXTENSION
.. versionadded:: 3.25
Package file extension. Default values are given in the list above.
.. variable:: CPACK_ARCHIVE_COMPONENT_INSTALL
Enable component packaging. If enabled (ON), then the archive generator

14
Help/cpack_gen/deb.rst
View File

@ -57,7 +57,7 @@ List of CPack DEB generator specific variables:
.. versionadded:: 3.5
Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_NAME`` variables.
See https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Source
See https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-source
.. variable:: CPACK_DEBIAN_FILE_NAME
CPACK_DEBIAN_<COMPONENT>_FILE_NAME
@ -399,7 +399,7 @@ List of CPack DEB generator specific variables:
.. versionadded:: 3.4
Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS`` variables.
See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
.. variable:: CPACK_DEBIAN_PACKAGE_ENHANCES
CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES
@ -419,7 +419,7 @@ List of CPack DEB generator specific variables:
.. versionadded:: 3.4
Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES`` variables.
See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
.. variable:: CPACK_DEBIAN_PACKAGE_BREAKS
CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS
@ -508,7 +508,7 @@ List of CPack DEB generator specific variables:
.. versionadded:: 3.4
Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_REPLACES`` variables.
See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
.. variable:: CPACK_DEBIAN_PACKAGE_RECOMMENDS
CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS
@ -527,7 +527,7 @@ List of CPack DEB generator specific variables:
.. versionadded:: 3.4
Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS`` variables.
See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
.. variable:: CPACK_DEBIAN_PACKAGE_SUGGESTS
CPACK_DEBIAN_<COMPONENT>_PACKAGE_SUGGESTS
@ -545,7 +545,7 @@ List of CPack DEB generator specific variables:
.. versionadded:: 3.4
Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_SUGGESTS`` variables.
See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
.. variable:: CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS
@ -639,7 +639,7 @@ List of CPack DEB generator specific variables:
- :variable:`CPACK_DEBIAN_PACKAGE_SOURCE` for component-based
installations.
See https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Source
See https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-source
.. note::

4
Help/cpack_gen/external.rst
View File

@ -207,8 +207,8 @@ following fields in the root:
set.
``buildConfig``
The build configuration given to CPack with the ``-C`` option. Only present
if this option is set.
The build configuration given to CPack with the :option:`cpack -C` option.
Only present if this option is set.
``defaultDirectoryPermissions``
The default directory permissions given in

12
Help/cpack_gen/freebsd.rst
View File

@ -62,8 +62,6 @@ the RPM information (e.g. package license).
- :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` (this is always set
by CPack itself, if nothing else sets it explicitly).
- :variable:`PROJECT_DESCRIPTION` (this can be set with the DESCRIPTION
parameter for :command:`project`).
.. variable:: CPACK_FREEBSD_PACKAGE_DESCRIPTION
@ -75,6 +73,10 @@ the RPM information (e.g. package license).
- :variable:`CPACK_DEBIAN_PACKAGE_DESCRIPTION` (this may be set already
for Debian packaging, so it is used as a fallback).
- :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY` (this is always set
by CPack itself, if nothing else sets it explicitly).
- :variable:`PROJECT_DESCRIPTION` (this can be set with the DESCRIPTION
parameter for :command:`project`).
.. variable:: CPACK_FREEBSD_PACKAGE_WWW
@ -85,12 +87,12 @@ the RPM information (e.g. package license).
* Mandatory: YES
* Default:
- :variable:`CMAKE_PROJECT_HOMEPAGE_URL`, or if that is not set,
:variable:`CPACK_DEBIAN_PACKAGE_HOMEPAGE` (this may be set already
- :variable:`CPACK_PACKAGE_HOMEPAGE_URL`, or if that is not set,
- :variable:`CPACK_DEBIAN_PACKAGE_HOMEPAGE` (this may be set already
for Debian packaging, so it is used as a fallback).
.. versionadded:: 3.12
The ``CMAKE_PROJECT_HOMEPAGE_URL`` variable.
The ``CPACK_PACKAGE_HOMEPAGE_URL`` variable.
.. variable:: CPACK_FREEBSD_PACKAGE_LICENSE

2
Help/cpack_gen/ifw.rst
View File

@ -14,7 +14,7 @@ Overview
This :manual:`cpack generator <cpack-generators(7)>` generates
configuration and meta information for the `Qt Installer Framework
<http://doc.qt.io/qtinstallerframework/index.html>`_ (QtIFW),
<https://doc.qt.io/qtinstallerframework/index.html>`_ (QtIFW),
and runs QtIFW tools to generate a Qt installer.
QtIFW provides tools and utilities to create installers for

31
Help/cpack_gen/nsis.rst
View File

@ -207,3 +207,34 @@ on Windows Nullsoft Scriptable Install System.
.. versionadded:: 3.22
If set, do not display the page containing the license during installation.
.. variable:: CPACK_NSIS_EXECUTABLE_PRE_ARGUMENTS
.. versionadded:: 3.25
This variable is a :ref:`semicolon-separated list <CMake Language Lists>` of
arguments to prepend to the nsis script to run.
If the arguments do not start with a ``/`` or a ``-``, it will add one
automatically to the corresponding arguments.
The command that will be run is::
makensis.exe <preArgs>... "nsisFileName.nsi" <postArgs>...
where ``<preArgs>...`` is constructed from ``CPACK_NSIS_EXECUTABLE_PRE_ARGUMENTS``
and ``<postArgs>...`` is constructed from ``CPACK_NSIS_EXECUTABLE_POST_ARGUMENTS``.
.. variable:: CPACK_NSIS_EXECUTABLE_POST_ARGUMENTS
.. versionadded:: 3.25
This variable is a :ref:`semicolon-separated list <CMake Language Lists>` of
arguments to append to the nsis script to run.
If the arguments do not start with a ``/`` or a ``-``, it will add one
automatically to the corresponding arguments.
The command that will be run is::
makensis.exe <preArgs>... "nsisFileName.nsi" <postArgs>...
where ``<preArgs>...`` is constructed from ``CPACK_NSIS_EXECUTABLE_PRE_ARGUMENTS``
and ``<postArgs>...`` is constructed from ``CPACK_NSIS_EXECUTABLE_POST_ARGUMENTS``.

20
Help/cpack_gen/nuget.rst
View File

@ -110,7 +110,7 @@ List of CPack NuGet generator specific variables:
.. deprecated:: 3.20
Use a local license file
(:variable:`CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME`)
or a `(SPDX) license identifier`_
or a `SPDX license identifier`_
(:variable:`CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION`) instead.
An URL for the package's license, often shown in UI displays as well
@ -124,7 +124,7 @@ List of CPack NuGet generator specific variables:
.. versionadded:: 3.20
A Software Package Data Exchange `(SPDX) license identifier`_ such as
A Software Package Data Exchange `SPDX license identifier`_ such as
``MIT``, ``BSD-3-Clause``, or ``LGPL-3.0-or-later``. In the case of a
choice of licenses or more complex restrictions, compound license
expressions may be formed using boolean operators, for example
@ -162,6 +162,14 @@ List of CPack NuGet generator specific variables:
* Mandatory : NO
* Default : -
.. variable:: CPACK_NUGET_PACKAGE_REQUIRE_LICENSE_ACCEPTANCE
When set to a true value, the user will be prompted to accept the license
before installing the package.
* Mandatory : NO
* Default : -
.. variable:: CPACK_NUGET_PACKAGE_ICON
CPACK_NUGET_<compName>_PACKAGE_ICON
@ -247,9 +255,9 @@ List of CPack NuGet generator specific variables:
* Default : OFF
.. _nuget.org: http://nuget.org
.. _version specification: https://docs.microsoft.com/en-us/nuget/reference/package-versioning#version-ranges-and-wildcards
.. _(SPDX) license identifier: https://spdx.org/licenses/
.. _SPDX specification: https://spdx.github.io/spdx-spec/appendix-IV-SPDX-license-expressions/
.. _nuget.org: https://www.nuget.org
.. _version specification: https://learn.microsoft.com/en-us/nuget/concepts/package-versioning#version-ranges
.. _SPDX license identifier: https://spdx.github.io/spdx-spec/SPDX-license-list
.. _SPDX specification: https://spdx.github.io/spdx-spec/SPDX-license-expressions
.. NuGet spec docs https://docs.microsoft.com/en-us/nuget/reference/nuspec

4
Help/cpack_gen/rpm.rst
View File

@ -18,7 +18,7 @@ The CPack RPM generator has specific features which are controlled by the specif
**grouping name** written in upper case. It may be either a component name or
a component GROUP name. Usually those variables correspond to RPM spec file
entities. One may find information about spec files here
http://www.rpm.org/wiki/Docs
https://rpm.org/documentation
.. versionchanged:: 3.6
@ -972,7 +972,7 @@ For CMake projects SRPM package would be produced by executing::
Produced SRPM package is expected to be built with :manual:`cmake(1)` executable
and packaged with :manual:`cpack(1)` executable so CMakeLists.txt has to be
located in root source directory and must be able to generate binary rpm
packages by executing ``cpack -G`` command. The two executables as well as
packages by executing :option:`cpack -G` command. The two executables as well as
rpmbuild must also be present when generating binary rpm packages from the
produced SRPM package.

2
Help/cpack_gen/wix.rst
View File

@ -111,7 +111,7 @@ Windows using WiX.
simply provide the name of the culture. If you specify more than one
culture identifier in a comma or semicolon delimited list, the first one
that is found will be used. You can find a list of supported languages at:
http://wix.sourceforge.net/manual-wix3/WixUI_localization.htm
https://wixtoolset.org//documentation/manual/v3/wixui/wixui_localization.html
.. variable:: CPACK_WIX_TEMPLATE

30
Help/dev/experimental.rst
View File

@ -7,6 +7,23 @@ See documentation on `CMake Development`_ for more information.
.. _`CMake Development`: README.rst
Features are gated behind ``CMAKE_EXPERIMENTAL_`` variables which must be set
to specific values in order to enable their gated behaviors. Note that the
specific values will change over time to reinforce their experimental nature.
When used, a warning will be generated to indicate that an experimental
feature is in use and that the affected behavior in the project is not part of
CMake's stability guarantees.
C++20 Module APIs
=================
Variable: ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
Value: ``3c375311-a3c9-4396-a187-3227ef642046``
In order to support C++20 modules, there are a number of behaviors that have
CMake APIs to provide the required features to build and export them from a
project.
C++20 Module Dependencies
=========================
@ -22,6 +39,10 @@ they can use it to develop and test their dependency scanning tool.
The ``CMAKE_EXPERIMENTAL_CXX_SCANDEP_SOURCE`` variable must also be set
to tell CMake how to invoke the C++20 module dependency scanning tool.
MSVC 19.34 (provided with Visual Studio 17.4) and above contains the support
that CMake needs and has these variables already set up as required and only
the UUID variable needs to be set.
For example, add code like the following to a test project:
.. code-block:: cmake
@ -40,13 +61,8 @@ 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.
by the `P1689r5`_ paper.
Compiler writers may try out their scanning functionality using
the `cxx-modules-sandbox`_ test project, modified to set variables
@ -73,5 +89,5 @@ the GCC documentation, but the relevant section for the purposes of CMake is:
-- GCC module mapper documentation
.. _`D1483r1`: https://mathstuf.fedorapeople.org/fortran-modules/fortran-modules.html
.. _`P1689r4`: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p1689r4.html
.. _`P1689r5`: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1689r5.html
.. _`cxx-modules-sandbox`: https://github.com/mathstuf/cxx-modules-sandbox

19
Help/envvar/ASM_DIALECTFLAGS.rst
View File

@ -3,13 +3,16 @@ ASM<DIALECT>FLAGS
.. include:: ENV_VAR.txt
Default compilation flags to be used when compiling a specific dialect of an
assembly language. ``ASM<DIALECT>FLAGS`` can be ``ASMFLAGS``, ``ASM_NASMFLAGS``,
``ASM_MASMFLAGS`` or ``ASM-ATTFLAGS``. Will only be used by CMake on the
first configuration to determine ``ASM_<DIALECT>`` default compilation
flags, after which the value for ``ASM<DIALECT>FLAGS`` is stored in the cache
as ``CMAKE_ASM<DIALECT>_FLAGS <CMAKE_<LANG>_FLAGS>``. For any configuration
run (including the first), the environment variable will be ignored, if the
``CMAKE_ASM<DIALECT>_FLAGS <CMAKE_<LANG>_FLAGS>`` variable is defined.
Add default compilation flags to be used when compiling a specific dialect
of an assembly language. ``ASM<DIALECT>FLAGS`` can be one of:
* ``ASMFLAGS``
* ``ASM_NASMFLAGS``
* ``ASM_MASMFLAGS``
* ``ASM-ATTFLAGS``
.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_ASM<DIALECT>_FLAGS <CMAKE_<LANG>_FLAGS>`
.. |LANG| replace:: ``ASM<DIALECT>``
.. include:: LANG_FLAGS.txt
See also :variable:`CMAKE_ASM<DIALECT>_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

11
Help/envvar/CFLAGS.rst
View File

@ -3,11 +3,10 @@ CFLAGS
.. include:: ENV_VAR.txt
Default compilation flags to be used when compiling ``C`` files. Will only be
used by CMake on the first configuration to determine ``CC`` default compilation
flags, after which the value for ``CFLAGS`` is stored in the cache
as :variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration run
(including the first), the environment variable will be ignored if the
:variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
Add default compilation flags to be used when compiling ``C`` files.
.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>`
.. |LANG| replace:: ``C``
.. include:: LANG_FLAGS.txt
See also :variable:`CMAKE_C_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

6
Help/envvar/CMAKE_GENERATOR.rst
View File

@ -6,9 +6,9 @@ CMAKE_GENERATOR
.. include:: ENV_VAR.txt
Specifies the CMake default generator to use when no generator is supplied
with ``-G``. If the provided value doesn't name a generator known by CMake,
the internal default is used. Either way the resulting generator selection
is stored in the :variable:`CMAKE_GENERATOR` variable.
with :option:`-G <cmake -G>`. If the provided value doesn't name a generator
known by CMake, the internal default is used. Either way the resulting
generator selection is stored in the :variable:`CMAKE_GENERATOR` variable.
Some generators may be additionally configured using the environment
variables:

2
Help/envvar/CMAKE_GENERATOR_PLATFORM.rst
View File

@ -6,5 +6,5 @@ CMAKE_GENERATOR_PLATFORM
.. include:: ENV_VAR.txt
Default value for :variable:`CMAKE_GENERATOR_PLATFORM` if no Cache entry
is present and no value is specified by :manual:`cmake(1)` ``-A`` option.
is present and no value is specified by :option:`cmake -A` option.
This value is only applied if :envvar:`CMAKE_GENERATOR` is set.

2
Help/envvar/CMAKE_GENERATOR_TOOLSET.rst
View File

@ -6,5 +6,5 @@ CMAKE_GENERATOR_TOOLSET
.. include:: ENV_VAR.txt
Default value for :variable:`CMAKE_GENERATOR_TOOLSET` if no Cache entry
is present and no value is specified by :manual:`cmake(1)` ``-T`` option.
is present and no value is specified by :option:`cmake -T` option.
This value is only applied if :envvar:`CMAKE_GENERATOR` is set.

11
Help/envvar/CSFLAGS.rst
View File

@ -5,11 +5,10 @@ CSFLAGS
.. include:: ENV_VAR.txt
Default compilation flags to be used when compiling ``CSharp`` files. Will only be
used by CMake on the first configuration to determine ``CSharp`` default
compilation flags, after which the value for ``CSFLAGS`` is stored in the cache
as :variable:`CMAKE_CSharp_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration
run (including the first), the environment variable will be ignored if the
:variable:`CMAKE_CSharp_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
Add default compilation flags to be used when compiling ``CSharp`` files.
.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_CSharp_FLAGS <CMAKE_<LANG>_FLAGS>`
.. |LANG| replace:: ``CSharp``
.. include:: LANG_FLAGS.txt
See also :variable:`CMAKE_CSharp_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

4
Help/envvar/CTEST_PROGRESS_OUTPUT.rst
View File

@ -14,5 +14,5 @@ variable is not set or has a value that evaluates to false, output is reported
normally with each test having its own start and end lines logged to the
output.
The ``--progress`` option to :manual:`ctest <ctest(1)>` overrides this
environment variable if both are given.
The :option:`--progress <ctest --progress>` option to :manual:`ctest <ctest(1)>`
overrides this environment variable if both are given.

11
Help/envvar/CUDAFLAGS.rst
View File

@ -5,11 +5,10 @@ CUDAFLAGS
.. include:: ENV_VAR.txt
Default compilation flags to be used when compiling ``CUDA`` files. Will only be
used by CMake on the first configuration to determine ``CUDA`` default
compilation flags, after which the value for ``CUDAFLAGS`` is stored in the
cache as :variable:`CMAKE_CUDA_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration
run (including the first), the environment variable will be ignored if
the :variable:`CMAKE_CUDA_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
Add default compilation flags to be used when compiling ``CUDA`` files.
.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_CUDA_FLAGS <CMAKE_<LANG>_FLAGS>`
.. |LANG| replace:: ``CUDA``
.. include:: LANG_FLAGS.txt
See also :variable:`CMAKE_CUDA_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

11
Help/envvar/CXXFLAGS.rst
View File

@ -3,11 +3,10 @@ CXXFLAGS
.. include:: ENV_VAR.txt
Default compilation flags to be used when compiling ``CXX`` (C++) files. Will
only be used by CMake on the first configuration to determine ``CXX`` default
compilation flags, after which the value for ``CXXFLAGS`` is stored in the cache
as :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration run (
including the first), the environment variable will be ignored if
the :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
Add default compilation flags to be used when compiling ``CXX`` (C++) files.
.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>`
.. |LANG| replace:: ``CXX``
.. include:: LANG_FLAGS.txt
See also :variable:`CMAKE_CXX_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

5
Help/envvar/DESTDIR.rst
View File

@ -20,8 +20,9 @@ The packaging tool may then construct the package from the content of the
See the :variable:`CMAKE_INSTALL_PREFIX` variable to control the
installation prefix when configuring a build tree. Or, when using
the :manual:`cmake(1)` command-line tool's ``--install`` mode,
one may specify a different prefix using the ``--prefix`` option.
the :manual:`cmake(1)` command-line tool's :option:`--install <cmake --install>`
mode, one may specify a different prefix using the
:option:`--prefix <cmake--install --prefix>` option.
.. note::

11
Help/envvar/FFLAGS.rst
View File

@ -3,11 +3,10 @@ FFLAGS
.. include:: ENV_VAR.txt
Default compilation flags to be used when compiling ``Fortran`` files. Will only
be used by CMake on the first configuration to determine ``Fortran`` default
compilation flags, after which the value for ``FFLAGS`` is stored in the cache
as :variable:`CMAKE_Fortran_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration
run (including the first), the environment variable will be ignored if
the :variable:`CMAKE_Fortran_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
Add default compilation flags to be used when compiling ``Fortran`` files.
.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_Fortran_FLAGS <CMAKE_<LANG>_FLAGS>`
.. |LANG| replace:: ``Fortran``
.. include:: LANG_FLAGS.txt
See also :variable:`CMAKE_Fortran_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

11
Help/envvar/HIPFLAGS.rst
View File

@ -5,11 +5,10 @@ HIPFLAGS
.. include:: ENV_VAR.txt
Default compilation flags to be used when compiling ``HIP`` files. Will only be
used by CMake on the first configuration to determine ``HIP`` default
compilation flags, after which the value for ``HIPFLAGS`` is stored in the
cache as :variable:`CMAKE_HIP_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration
run (including the first), the environment variable will be ignored if
the :variable:`CMAKE_HIP_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
Add default compilation flags to be used when compiling ``HIP`` files.
.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_HIP_FLAGS <CMAKE_<LANG>_FLAGS>`
.. |LANG| replace:: ``HIP``
.. include:: LANG_FLAGS.txt
See also :variable:`CMAKE_HIP_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

11
Help/envvar/ISPCFLAGS.rst
View File

@ -5,11 +5,10 @@ ISPCFLAGS
.. include:: ENV_VAR.txt
Default compilation flags to be used when compiling ``ISPC`` files. Will only be
used by CMake on the first configuration to determine ``ISPC`` default
compilation flags, after which the value for ``ISPCFLAGS`` is stored in the
cache as :variable:`CMAKE_ISPC_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration
run (including the first), the environment variable will be ignored if
the :variable:`CMAKE_ISPC_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
Add default compilation flags to be used when compiling ``ISPC`` files.
.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_ISPC_FLAGS <CMAKE_<LANG>_FLAGS>`
.. |LANG| replace:: ``ISPC``
.. include:: LANG_FLAGS.txt
See also :variable:`CMAKE_ISPC_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

6
Help/envvar/LANG_FLAGS.txt Normal file
View File

@ -0,0 +1,6 @@
CMake uses this environment variable value, in combination with its own
builtin default flags for the toolchain, to initialize and store the
|CMAKE_LANG_FLAGS| cache entry.
This occurs the first time a build tree is configured for language |LANG|.
For any configuration run (including the first), the environment variable
will be ignored if the |CMAKE_LANG_FLAGS| variable is already defined.

11
Help/envvar/RCFLAGS.rst
View File

@ -3,11 +3,10 @@ RCFLAGS
.. include:: ENV_VAR.txt
Default compilation flags to be used when compiling ``resource`` files. Will
only be used by CMake on the first configuration to determine ``resource``
default compilation flags, after which the value for ``RCFLAGS`` is stored in
the cache as :variable:`CMAKE_RC_FLAGS <CMAKE_<LANG>_FLAGS>`. For any
configuration run (including the first), the environment variable will be ignored
if the :variable:`CMAKE_RC_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined.
Add default compilation flags to be used when compiling ``RC`` (resource) files.
.. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_RC_FLAGS <CMAKE_<LANG>_FLAGS>`
.. |LANG| replace:: ``RC``
.. include:: LANG_FLAGS.txt
See also :variable:`CMAKE_RC_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

9
Help/envvar/SSL_CERT_DIR.rst Normal file
View File

@ -0,0 +1,9 @@
SSL_CERT_DIR
------------
.. versionadded:: 3.25
.. include:: ENV_VAR.txt
Specify default directory containing CA certificates. It overrides
the default CA directory used.

9
Help/envvar/SSL_CERT_FILE.rst Normal file
View File

@ -0,0 +1,9 @@
SSL_CERT_FILE
-------------
.. versionadded:: 3.25
.. include:: ENV_VAR.txt
Specify the file name containing CA certificates. It overrides the
default, os-specific CA file used.

12
Help/generator/Green Hills MULTI.rst
View File

@ -28,12 +28,12 @@ Otherwise the ``primaryTarget`` will be composed from the values of :variable:`C
and ``GHS_TARGET_PLATFORM``. Defaulting to the value of ``arm_integrity.tgt``
* The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
via the :manual:`cmake(1)` ``-A`` option.
via the :option:`cmake -A` option.
| Typical values of ``arm``, ``ppc``, ``86``, etcetera, are used.
* The variable ``GHS_TARGET_PLATFORM`` may be set, perhaps via the :manual:`cmake(1)`
``-D`` option.
* The variable ``GHS_TARGET_PLATFORM`` may be set, perhaps via the :option:`cmake -D`
option.
| Defaults to ``integrity``.
| Usual values are ``integrity``, ``threadx``, ``uvelosity``, ``velosity``,
@ -55,11 +55,11 @@ The generator searches for the latest compiler or can be given a location to use
``GHS_TOOLSET_ROOT`` is the directory that is checked for the latest compiler.
* The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
via the :manual:`cmake(1)` ``-T`` option, to specify the location of the toolset.
via the :option:`cmake -T` option, to specify the location of the toolset.
Both absolute and relative paths are valid. Paths are relative to ``GHS_TOOLSET_ROOT``.
* The variable ``GHS_TOOLSET_ROOT`` may be set, perhaps via the :manual:`cmake(1)`
``-D`` option.
* The variable ``GHS_TOOLSET_ROOT`` may be set, perhaps via the :option:`cmake -D`
option.
| Root path for toolset searches and relative paths.
| Defaults to ``C:/ghs`` in Windows or ``/usr/ghs`` in Linux.

4
Help/generator/Ninja Multi-Config.rst
View File

@ -20,8 +20,8 @@ are intended to be run with ``ninja -f build-<Config>.ninja``. A
:variable:`CMAKE_CONFIGURATION_TYPES`.
``cmake --build . --config <Config>`` will always use ``build-<Config>.ninja``
to build. If no ``--config`` argument is specified, ``cmake --build .`` will
use ``build.ninja``.
to build. If no :option:`--config <cmake--build --config>` argument is
specified, :option:`cmake --build . <cmake --build>` will use ``build.ninja``.
Each ``build-<Config>.ninja`` file contains ``<target>`` targets as well as
``<target>:<Config>`` targets, where ``<Config>`` is the same as the

54
Help/generator/Visual Studio 10 2010.rst
View File

@ -1,52 +1,8 @@
Visual Studio 10 2010
---------------------
Deprecated. Generates Visual Studio 10 (VS 2010) project files.
.. note::
This generator is deprecated and will be removed in a future version
of CMake. It will still be possible to build with VS 10 2010 tools
using the :generator:`Visual Studio 11 2012` (or above) generator
with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v100``, or by
using the :generator:`NMake Makefiles` generator.
For compatibility with CMake versions prior to 3.0, one may specify this
generator using the name ``Visual Studio 10`` without the year component.
Project Types
^^^^^^^^^^^^^
Only Visual C++ and C# projects may be generated (and Fortran with
Intel compiler integration). Other types of projects (Database,
Website, etc.) are not supported.
Platform Selection
^^^^^^^^^^^^^^^^^^
The default target platform name (architecture) is ``Win32``.
.. versionadded:: 3.1
The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
name (architecture). For example:
* ``cmake -G "Visual Studio 10 2010" -A Win32``
* ``cmake -G "Visual Studio 10 2010" -A x64``
* ``cmake -G "Visual Studio 10 2010" -A Itanium``
For compatibility with CMake versions prior to 3.1, one may specify
a target platform name optionally at the end of the generator name.
This is supported only for:
``Visual Studio 10 2010 Win64``
Specify target platform ``x64``.
``Visual Studio 10 2010 IA64``
Specify target platform ``Itanium``.
Toolset Selection
^^^^^^^^^^^^^^^^^
The ``v100`` toolset that comes with Visual Studio 10 2010 is selected by
default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
via the :manual:`cmake(1)` ``-T`` option, to specify another toolset.
Removed. This once generated Visual Studio 10 2010 project files, but
the generator has been removed since CMake 3.25. It is still possible
to build with VS 10 2010 tools using the :generator:`Visual Studio 12 2013`
(or above) generator with :variable:`CMAKE_GENERATOR_TOOLSET` set to
``v100``, or by using the :generator:`NMake Makefiles` generator.

13
Help/generator/Visual Studio 11 2012.rst
View File

@ -1,7 +1,14 @@
Visual Studio 11 2012
---------------------
Generates Visual Studio 11 (VS 2012) project files.
Deprecated. Generates Visual Studio 11 (VS 2012) project files.
.. note::
This generator is deprecated and will be removed in a future version
of CMake. It will still be possible to build with VS 11 2012 tools
using the :generator:`Visual Studio 12 2013` (or above) generator
with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v110``, or by
using the :generator:`NMake Makefiles` generator.
For compatibility with CMake versions prior to 3.0, one may specify this
generator using the name "Visual Studio 11" without the year component.
@ -20,7 +27,7 @@ The default target platform name (architecture) is ``Win32``.
.. versionadded:: 3.1
The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
via the :option:`cmake -A` option, to specify a target platform
name (architecture). For example:
* ``cmake -G "Visual Studio 11 2012" -A Win32``
@ -47,4 +54,4 @@ Toolset Selection
The ``v110`` toolset that comes with Visual Studio 11 2012 is selected by
default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
via the :manual:`cmake(1)` ``-T`` option, to specify another toolset.
via the :option:`cmake -T` option, to specify another toolset.

4
Help/generator/Visual Studio 12 2013.rst
View File

@ -20,7 +20,7 @@ The default target platform name (architecture) is ``Win32``.
.. versionadded:: 3.1
The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
via the :option:`cmake -A` option, to specify a target platform
name (architecture). For example:
* ``cmake -G "Visual Studio 12 2013" -A Win32``
@ -42,7 +42,7 @@ Toolset Selection
The ``v120`` toolset that comes with Visual Studio 12 2013 is selected by
default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
via the :manual:`cmake(1)` ``-T`` option, to specify another toolset.
via the :option:`cmake -T` option, to specify another toolset.
.. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace::
By default this generator uses the 32-bit variant even on a 64-bit host.

4
Help/generator/Visual Studio 14 2015.rst
View File

@ -18,7 +18,7 @@ Platform Selection
The default target platform name (architecture) is ``Win32``.
The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
via the :option:`cmake -A` option, to specify a target platform
name (architecture). For example:
* ``cmake -G "Visual Studio 14 2015" -A Win32``
@ -40,7 +40,7 @@ Toolset Selection
The ``v140`` toolset that comes with Visual Studio 14 2015 is selected by
default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
via the :manual:`cmake(1)` ``-T`` option, to specify another toolset.
via the :option:`cmake -T` option, to specify another toolset.
.. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace::
By default this generator uses the 32-bit variant even on a 64-bit host.

4
Help/generator/Visual Studio 15 2017.rst
View File

@ -26,7 +26,7 @@ Platform Selection
The default target platform name (architecture) is ``Win32``.
The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
via the :option:`cmake -A` option, to specify a target platform
name (architecture). For example:
* ``cmake -G "Visual Studio 15 2017" -A Win32``
@ -49,7 +49,7 @@ Toolset Selection
The ``v141`` toolset that comes with Visual Studio 15 2017 is selected by
default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
via the :manual:`cmake(1)` ``-T`` option, to specify another toolset.
via the :option:`cmake -T` option, to specify another toolset.
.. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace::
By default this generator uses the 32-bit variant even on a 64-bit host.

4
Help/generator/Visual Studio 16 2019.rst
View File

@ -25,7 +25,7 @@ The default target platform name (architecture) is that of the host
and is provided in the :variable:`CMAKE_VS_PLATFORM_NAME_DEFAULT` variable.
The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
via the :option:`cmake -A` option, to specify a target platform
name (architecture). For example:
* ``cmake -G "Visual Studio 16 2019" -A Win32``
@ -38,7 +38,7 @@ Toolset Selection
The ``v142`` toolset that comes with Visual Studio 16 2019 is selected by
default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
via the :manual:`cmake(1)` ``-T`` option, to specify another toolset.
via the :option:`cmake -T` option, to specify another toolset.
.. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace::
By default this generator uses the 64-bit variant on x64 hosts and

4
Help/generator/Visual Studio 17 2022.rst
View File

@ -25,7 +25,7 @@ The default target platform name (architecture) is that of the host
and is provided in the :variable:`CMAKE_VS_PLATFORM_NAME_DEFAULT` variable.
The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
via the :option:`cmake -A` option, to specify a target platform
name (architecture). For example:
* ``cmake -G "Visual Studio 17 2022" -A Win32``
@ -38,7 +38,7 @@ Toolset Selection
The ``v143`` toolset that comes with VS 17 2022 is selected by default.
The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
via the :manual:`cmake(1)` ``-T`` option, to specify another toolset.
via the :option:`cmake -T` option, to specify another toolset.
.. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace::
By default this generator uses the 64-bit variant on x64 hosts and

2
Help/generator/Visual Studio 9 2008.rst
View File

@ -10,7 +10,7 @@ The default target platform name (architecture) is ``Win32``.
.. versionadded:: 3.1
The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
via the :option:`cmake -A` option, to specify a target platform
name (architecture). For example:
* ``cmake -G "Visual Studio 9 2008" -A Win32``

14
Help/generator/Xcode.rst
View File

@ -13,7 +13,7 @@ Toolset and Build System Selection
By default Xcode is allowed to select its own default toolchain.
The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
via the :manual:`cmake(1)` ``-T`` option, to specify another toolset.
via the :option:`cmake -T` option, to specify another toolset.
.. versionadded:: 3.19
This generator supports toolset specification using one of these forms:
@ -34,7 +34,7 @@ Supported pairs are:
See the :variable:`CMAKE_XCODE_BUILD_SYSTEM` variable for allowed values.
For example, to select the original build system under Xcode 12,
run :manual:`cmake(1)` with the option ``-T buildsystem=1``.
run :manual:`cmake(1)` with the option :option:`-T buildsystem=1 <cmake -T>`.
Swift Support
^^^^^^^^^^^^^
@ -44,3 +44,13 @@ Swift Support
When using the :generator:`Xcode` generator with Xcode 6.1 or higher,
one may enable the ``Swift`` language with the :command:`enable_language`
command or the :command:`project`.
Limitations
^^^^^^^^^^^
The Xcode generator does not support per-configuration sources.
Code like the following will result in a generation error:
.. code-block:: cmake
add_executable(MyApp mymain-$<CONFIG>.cpp)

17
Help/guide/ide-integration/index.rst
View File

@ -47,8 +47,9 @@ does, and present the user with the presets listed in the file. Users should be
able to see (and possibly edit) the CMake cache variables, environment
variables, and command line options that are defined for a given preset. The
IDE should then construct the list of appropriate :manual:`cmake(1)` command
line arguments based on these settings, rather than using the ``--preset=``
option directly. The ``--preset=`` option is intended only as a convenient
line arguments based on these settings, rather than using the
:option:`--preset= <cmake --preset>` option directly. The
:option:`--preset= <cmake --preset>` option is intended only as a convenient
frontend for command line users, and should not be used by the IDE.
For example, if a preset named ``ninja`` specifies ``Ninja`` as the generator
@ -66,10 +67,9 @@ run:
cmake -S /path/to/source -B /path/to/source/build -G Ninja
In cases where a preset contains lots of cache variables, and passing all of
them as ``-D`` flags would cause the command line length limit of the platform
to be exceeded, the IDE should instead construct a temporary cache script and
pass it with the ``-C`` flag. See :ref:`CMake Options` for details on how the
``-C`` flag is used.
them as :option:`-D <cmake -D>` flags would cause the command line length limit
of the platform to be exceeded, the IDE should instead construct a temporary
cache script and pass it with the :option:`-C <cmake -C>` flag.
While reading, parsing, and evaluating the contents of ``CMakePresets.json`` is
straightforward, it is not trivial. In addition to the documentation, IDE
@ -110,8 +110,9 @@ Building
If a Makefile or Ninja generator is used to generate the build tree, it is not
recommended to invoke ``make`` or ``ninja`` directly. Instead, it is
recommended that the IDE invoke :manual:`cmake(1)` with the ``--build``
argument, which will in turn invoke the appropriate build tool.
recommended that the IDE invoke :manual:`cmake(1)` with the
:option:`--build <cmake --build>` argument, which will in turn invoke the
appropriate build tool.
If an IDE project generator is used, such as :generator:`Xcode` or one of the
Visual Studio generators, and the IDE understands the project format used, the

472
Help/guide/tutorial/A Basic Starting Point.rst
View File

@ -1,34 +1,81 @@
Step 1: A Basic Starting Point
==============================
The most basic project is an executable built from source code files.
For simple projects, a three line ``CMakeLists.txt`` file is all that is
required. This will be the starting point for our tutorial. Create a
``CMakeLists.txt`` file in the ``Step1`` directory that looks like:
Where do I start with CMake? This step will provide an introduction to some of
CMake's basic syntax, commands, and variables. As these concepts are
introduced, we will work through three exercises and create a simple CMake
project.
.. code-block:: cmake
:caption: CMakeLists.txt
:name: CMakeLists.txt-start
Each exercise in this step will start with some background information. Then, a
goal and list of helpful resources are provided. Each file in the
``Files to Edit`` section is in the ``Step1`` directory and contains one or
more ``TODO`` comments. Each ``TODO`` represents a line or two of code to
change or add. The ``TODO`` s are intended to be completed in numerical order,
first complete ``TODO 1`` then ``TODO 2``, etc. The ``Getting Started``
section will give some helpful hints and guide you through the exercise. Then
the ``Build and Run`` section will walk step-by-step through how to build and
test the exercise. Finally, at the end of each exercise the intended solution
is discussed.
cmake_minimum_required(VERSION 3.10)
Also note that each step in the tutorial builds on the next. So, for example,
the starting code for ``Step2`` is the complete solution to ``Step1``.
# set the project name
project(Tutorial)
Exercise 1 - Building a Basic Project
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
# add the executable
add_executable(Tutorial tutorial.cxx)
The most basic CMake project is an executable built from a single source code
file. For simple projects like this, a ``CMakeLists.txt`` file with three
commands is all that is required.
**Note:** Although upper, lower and mixed case commands are supported by CMake,
lower case commands are preferred and will be used throughout the tutorial.
Note that this example uses lower case commands in the ``CMakeLists.txt`` file.
Upper, lower, and mixed case commands are supported by CMake. The source
code for ``tutorial.cxx`` is provided in the ``Step1`` directory and can be
used to compute the square root of a number.
Any project's top most CMakeLists.txt must start by specifying a minimum CMake
version using the :command:`cmake_minimum_required` command. This establishes
policy settings and ensures that the following CMake functions are run with a
compatible version of CMake.
To start a project, we use the :command:`project` command to set the project
name. This call is required with every project and should be called soon after
:command:`cmake_minimum_required`. As we will see later, this command can
also be used to specify other project level information such as the language
or version number.
Finally, the :command:`add_executable` command tells CMake to create an
executable using the specified source code files.
Goal
----
Understand how to create a simple CMake project.
Helpful Resources
-----------------
* :command:`add_executable`
* :command:`cmake_minimum_required`
* :command:`project`
Files to Edit
-------------
* ``CMakeLists.txt``
Getting Started
----------------
The source code for ``tutorial.cxx`` is provided in the
``Help/guide/tutorial/Step1`` directory and can be used to compute the square
root of a number. This file does not need to be edited in this step.
In the same directory is a ``CMakeLists.txt`` file which you will complete.
Start with ``TODO 1`` and work through ``TODO 3``.
Build and Run
-------------
That's all that is needed - we can build and run our project now! First, run
the :manual:`cmake <cmake(1)>` executable or the
Once ``TODO 1`` through ``TODO 3`` have been completed, we are ready to build
and run our project! First, run the :manual:`cmake <cmake(1)>` executable or the
:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it
with your chosen build tool.
@ -40,8 +87,9 @@ build directory:
mkdir Step1_build
Next, navigate to the build directory and run CMake to configure the project
and generate a native build system:
Next, navigate to that build directory and run
:manual:`cmake <cmake(1)>` to configure the project and generate a native build
system:
.. code-block:: console
@ -62,108 +110,113 @@ Finally, try to use the newly built ``Tutorial`` with these commands:
Tutorial 10
Tutorial
Solution
--------
Adding a Version Number and Configured Header File
--------------------------------------------------
As mentioned above, a three line ``CMakeLists.txt`` is all that we need to get
up and running. The first line is to use :command:`cmake_minimum_required` to
set the CMake version as follows:
The first feature we will add is to provide our executable and project with a
version number. While we could do this exclusively in the source code, using
``CMakeLists.txt`` provides more flexibility.
.. raw:: html
First, modify the ``CMakeLists.txt`` file to use the :command:`project` command
to set the project name and version number.
<details><summary>TODO 1: Click to show/hide answer</summary>
.. literalinclude:: Step2/CMakeLists.txt
:caption: CMakeLists.txt
:name: CMakeLists.txt-project-VERSION
:caption: TODO 1: CMakeLists.txt
:name: CMakeLists.txt-cmake_minimum_required
:language: cmake
:end-before: # specify the C++ standard
:end-before: # set the project name and version
Then, configure a header file to pass the version number to the source
code:
.. raw:: html
</details>
The next step to make a basic project is to use the :command:`project`
command as follows to set the project name:
.. raw:: html
<details><summary>TODO 2: Click to show/hide answer</summary>
.. code-block:: cmake
:caption: TODO 2: CMakeLists.txt
:name: CMakeLists.txt-project
project(Tutorial)
.. raw:: html
</details>
The last command to call for a basic project is
:command:`add_executable`. We call it as follows:
.. raw:: html
<details><summary>TODO 3: Click to show/hide answer</summary>
.. literalinclude:: Step2/CMakeLists.txt
:caption: CMakeLists.txt
:name: CMakeLists.txt-configure_file
:caption: TODO 3: CMakeLists.txt
:name: CMakeLists.txt-add_executable
:language: cmake
:start-after: # to the source code
:end-before: # add the executable
:start-after: # add the executable
:end-before: # TODO 9:
Since the configured file will be written into the binary tree, we
must add that directory to the list of paths to search for include
files. Add the following lines to the end of the ``CMakeLists.txt`` file:
.. raw:: html
.. literalinclude:: Step2/CMakeLists.txt
:caption: CMakeLists.txt
:name: CMakeLists.txt-target_include_directories
:language: cmake
:start-after: # so that we will find TutorialConfig.h
</details>
Using your favorite editor, create ``TutorialConfig.h.in`` in the source
directory with the following contents:
Exercise 2 - Specifying the C++ Standard
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. literalinclude:: Step2/TutorialConfig.h.in
:caption: TutorialConfig.h.in
:name: TutorialConfig.h.in
:language: c++
CMake has some special variables that are either created behind the scenes or
have meaning to CMake when set by project code. Many of these variables start
with ``CMAKE_``. Avoid this naming convention when creating variables for your
projects. Two of these special user settable variables are
:variable:`CMAKE_CXX_STANDARD` and :variable:`CMAKE_CXX_STANDARD_REQUIRED`.
These may be used together to specify the C++ standard needed to build the
project.
When CMake configures this header file the values for
``@Tutorial_VERSION_MAJOR@`` and ``@Tutorial_VERSION_MINOR@`` will be
replaced.
Goal
----
Next modify ``tutorial.cxx`` to include the configured header file,
``TutorialConfig.h``.
Add a feature that requires C++11.
Finally, let's print out the executable name and version number by updating
``tutorial.cxx`` as follows:
Helpful Resources
-----------------
.. literalinclude:: Step2/tutorial.cxx
:caption: tutorial.cxx
:name: tutorial.cxx-print-version
:language: c++
:start-after: {
:end-before: // convert input to double
* :variable:`CMAKE_CXX_STANDARD`
* :variable:`CMAKE_CXX_STANDARD_REQUIRED`
* :command:`set`
Specify the C++ Standard
-------------------------
Files to Edit
-------------
Next let's add some C++11 features to our project by replacing ``atof`` with
``std::stod`` in ``tutorial.cxx``. At the same time, remove
``#include <cstdlib>``.
* ``CMakeLists.txt``
* ``tutorial.cxx``
.. literalinclude:: Step2/tutorial.cxx
:caption: tutorial.cxx
:name: tutorial.cxx-cxx11
:language: c++
:start-after: // convert input to double
:end-before: // calculate square root
Getting Started
---------------
We will need to explicitly state in the CMake code that it should use the
correct flags. The easiest way to enable support for a specific C++ standard
in CMake is by using the :variable:`CMAKE_CXX_STANDARD` variable. For this
tutorial, set the :variable:`CMAKE_CXX_STANDARD` variable in the
``CMakeLists.txt`` file to ``11`` and :variable:`CMAKE_CXX_STANDARD_REQUIRED`
to ``True``. Make sure to add the ``CMAKE_CXX_STANDARD`` declarations above the
call to ``add_executable``.
Continue editing files in the ``Step1`` directory. Start with ``TODO 4`` and
complete through ``TODO 6``.
.. literalinclude:: Step2/CMakeLists.txt
:caption: CMakeLists.txt
:name: CMakeLists.txt-CXX_STANDARD
:language: cmake
:end-before: # configure a header file to pass some of the CMake settings
First, edit ``tutorial.cxx`` by adding a feature that requires C++11. Then
update ``CMakeLists.txt`` to require C++11.
Rebuild
-------
Build and Run
-------------
Let's build our project again. We already created a build directory and ran
CMake, so we can skip to the build step:
Let's build our project again. Since we already created a build directory and
ran CMake for Exercise 1, we can skip to the build step:
.. code-block:: console
cd Step1_build
cmake --build .
Now we can try to use the newly built ``Tutorial`` with same commands as before:
Now we can try to use the newly built ``Tutorial`` with same commands as
before:
.. code-block:: console
@ -171,5 +224,238 @@ Now we can try to use the newly built ``Tutorial`` with same commands as before:
Tutorial 10
Tutorial
Check that the version number is now reported when running the executable without
any arguments.
Solution
--------
We start by adding some C++11 features to our project by replacing
``atof`` with ``std::stod`` in ``tutorial.cxx``. This looks like
the following:
.. raw:: html
<details><summary>TODO 4: Click to show/hide answer</summary>
.. literalinclude:: Step2/tutorial.cxx
:caption: TODO 4: tutorial.cxx
:name: tutorial.cxx-cxx11
:language: c++
:start-after: // convert input to double
:end-before: // TODO 12:
.. raw:: html
</details>
To complete ``TODO 5``, simply remove ``#include <cstdlib>``.
We will need to explicitly state in the CMake code that it should use the
correct flags. One way to enable support for a specific C++ standard in CMake
is by using the :variable:`CMAKE_CXX_STANDARD` variable. For this tutorial, set
the :variable:`CMAKE_CXX_STANDARD` variable in the ``CMakeLists.txt`` file to
``11`` and :variable:`CMAKE_CXX_STANDARD_REQUIRED` to ``True``. Make sure to
add the :variable:`CMAKE_CXX_STANDARD` declarations above the call to
:command:`add_executable`.
.. raw:: html
<details><summary>TODO 6: Click to show/hide answer</summary>
.. literalinclude:: Step2/CMakeLists.txt
:caption: TODO 6: CMakeLists.txt
:name: CMakeLists.txt-CXX_STANDARD
:language: cmake
:start-after: # specify the C++ standard
:end-before: # TODO 7:
.. raw:: html
</details>
Exercise 3 - Adding a Version Number and Configured Header File
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Sometimes it may be useful to have a variable that is defined in your
``CMakelists.txt`` file also be available in your source code. In this case, we
would like to print the project version.
One way to accomplish this is by using a configured header file. We create an
input file with one or more variables to replace. These variables have special
syntax which looks like ``@VAR@``.
Then, we use the :command:`configure_file` command to copy the input file to a
given output file and replace these variables with the current value of ``VAR``
in the ``CMakelists.txt`` file.
While we could edit the version directly in the source code, using this
feature is preferred since it creates a single source of truth and avoids
duplication.
Goal
----
Define and report the project's version number.
Helpful Resources
-----------------
* :variable:`<PROJECT-NAME>_VERSION_MAJOR`
* :variable:`<PROJECT-NAME>_VERSION_MINOR`
* :command:`configure_file`
* :command:`target_include_directories`
Files to Edit
-------------
* ``CMakeLists.txt``
* ``tutorial.cxx``
Getting Started
---------------
Continue to edit files from ``Step1``. Start on ``TODO 7`` and complete through
``TODO 12``. In this exercise, we start by adding a project version number in
``CMakeLists.txt``. In that same file, use :command:`configure_file` to copy a
given input file to an output file and substitute some variable values in the
input file content.
Next, create an input header file ``TutorialConfig.h.in`` defining version
numbers which will accept variables passed from :command:`configure_file`.
Finally, update ``tutorial.cxx`` to print out its version number.
Build and Run
-------------
Let's build our project again. As before, we already created a build directory
and ran CMake so we can skip to the build step:
.. code-block:: console
cd Step1_build
cmake --build .
Verify that the version number is now reported when running the executable
without any arguments.
Solution
--------
In this exercise, we improve our executable by printing a version number.
While we could do this exclusively in the source code, using ``CMakeLists.txt``
lets us maintain a single source of data for the version number.
First, we modify the ``CMakeLists.txt`` file to use the
:command:`project` command to set both the project name and version number.
When the :command:`project` command is called, CMake defines
``Tutorial_VERSION_MAJOR`` and ``Tutorial_VERSION_MINOR`` behind the scenes.
.. raw:: html
<details><summary>TODO 7: Click to show/hide answer</summary>
.. literalinclude:: Step2/CMakeLists.txt
:caption: TODO 7: CMakeLists.txt
:name: CMakeLists.txt-project-VERSION
:language: cmake
:start-after: # set the project name and version
:end-before: # specify the C++ standard
.. raw:: html
</details>
Then we used :command:`configure_file` to copy the input file with the
specified CMake variables replaced:
.. raw:: html
<details><summary>TODO 8: Click to show/hide answer</summary>
.. literalinclude:: Step2/CMakeLists.txt
:caption: TODO 8: CMakeLists.txt
:name: CMakeLists.txt-configure_file
:language: cmake
:start-after: # to the source code
:end-before: # TODO 8:
.. raw:: html
</details>
Since the configured file will be written into the project binary
directory, we must add that directory to the list of paths to search for
include files.
**Note:** Throughout this tutorial, we will refer to the project build and
the project binary directory interchangeably. These are the same and are not
meant to refer to a `bin/` directory.
We used :command:`target_include_directories` to specify
where the executable target should look for include files.
.. raw:: html
<details><summary>TODO 9: Click to show/hide answer</summary>
.. literalinclude:: Step2/CMakeLists.txt
:caption: TODO 9: CMakeLists.txt
:name: CMakeLists.txt-target_include_directories
:language: cmake
:start-after: # so that we will find TutorialConfig.h
.. raw:: html
</details>
``TutorialConfig.h.in`` is the input header file to be configured.
When :command:`configure_file` is called from our ``CMakeLists.txt``, the
values for ``@Tutorial_VERSION_MAJOR@`` and ``@Tutorial_VERSION_MINOR@`` will
be replaced with the corresponding version numbers from the project in
``TutorialConfig.h``.
.. raw:: html
<details><summary>TODO 10: Click to show/hide answer</summary>
.. literalinclude:: Step2/TutorialConfig.h.in
:caption: TODO 10: TutorialConfig.h.in
:name: TutorialConfig.h.in
:language: c++
:end-before: // TODO 13:
.. raw:: html
</details>
Next, we need to modify ``tutorial.cxx`` to include the configured header file,
``TutorialConfig.h``.
.. raw:: html
<details><summary>TODO 11: Click to show/hide answer</summary>
.. code-block:: c++
:caption: TODO 11: tutorial.cxx
#include "TutorialConfig.h"
.. raw:: html
</details>
Finally, we print out the executable name and version number by updating
``tutorial.cxx`` as follows:
.. raw:: html
<details><summary>TODO 12: Click to show/hide answer</summary>
.. literalinclude:: Step2/tutorial.cxx
:caption: TODO 12 : tutorial.cxx
:name: tutorial.cxx-print-version
:language: c++
:start-after: {
:end-before: // convert input to double
.. raw:: html
</details>

2
Help/guide/tutorial/Adding Export Configuration.rst
View File

@ -21,7 +21,7 @@ in ``MathFunctions/CMakeLists.txt`` to look like:
:caption: MathFunctions/CMakeLists.txt
:name: MathFunctions/CMakeLists.txt-install-TARGETS-EXPORT
:language: cmake
:start-after: # install rules
:start-after: # install libs
Now that we have ``MathFunctions`` being exported, we also need to explicitly
install the generated ``MathFunctionsTargets.cmake`` file. This is done by

300
Help/guide/tutorial/Adding Generator Expressions.rst
View File

@ -1,4 +1,4 @@
Step 10: Adding Generator Expressions
Step 4: Adding Generator Expressions
=====================================
:manual:`Generator expressions <cmake-generator-expressions(7)>` are evaluated
@ -27,58 +27,280 @@ expressions are the ``0`` and ``1`` expressions. A ``$<0:...>`` results in the
empty string, and ``<1:...>`` results in the content of ``...``. They can also
be nested.
Exercise 1 - Setting the C++ Standard with Interface Libraries
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Before we use :manual:`generator expressions <cmake-generator-expressions(7)>`
let's refactor our existing code to use an ``INTERFACE`` library. We will
use that library in the next step to demonstrate a common use for
:manual:`generator expressions <cmake-generator-expressions(7)>`.
Goal
----
Add an ``INTERFACE`` library target to specify the required C++ standard.
Helpful Resources
-----------------
* :command:`add_library`
* :command:`target_compile_features`
* :command:`target_link_libraries`
Files to Edit
-------------
* ``CMakeLists.txt``
* ``MathFunctions/CMakeLists.txt``
Getting Started
---------------
In this exercise, we will refactor our code to use an ``INTERFACE`` library to
specify the C++ standard.
The starting source code is provided in the ``Step4`` directory. In this
exercise, complete ``TODO 1`` through ``TODO 3``.
Start by editing the top level ``CMakeLists.txt`` file. Construct an
``INTERFACE`` library target called ``tutorial_compiler_flags`` and
specify ``cxx_std_11`` as a target compiler feature.
Modify ``CMakeLists.txt`` and ``MathFunctions/CMakeLists.txt`` so that all
targets have a :command:`target_link_libraries` call to
``tutorial_compiler_flags``.
Build and Run
-------------
Make a new directory called ``Step4_build``, run the :manual:`cmake <cmake(1)>`
executable or the :manual:`cmake-gui <cmake-gui(1)>` to configure the project
and then build it with your chosen build tool or by using ``cmake --build .``
from the build directory.
Here's a refresher of what that looks like from the command line:
.. code-block:: console
mkdir Step4_build
cd Step4_build
cmake ../Step4
cmake --build .
Next, use the newly built ``Tutorial`` and verify that it is working as
expected.
Solution
--------
Let's update our code from the previous step to use interface libraries
to set our C++ requirements.
To start, we need to remove the two :command:`set` calls on the variables
:variable:`CMAKE_CXX_STANDARD` and :variable:`CMAKE_CXX_STANDARD_REQUIRED`.
The specific lines to remove are as follows:
.. literalinclude:: Step4/CMakeLists.txt
:caption: CMakeLists.txt
:name: CMakeLists.txt-CXX_STANDARD-variable-remove
:language: cmake
:start-after: # specify the C++ standard
:end-before: # TODO 5: Create helper variables
Next, we need to create an interface library, ``tutorial_compiler_flags``. And
then use :command:`target_compile_features` to add the compiler feature
``cxx_std_11``.
.. raw:: html
<details><summary>TODO 1: Click to show/hide answer</summary>
.. literalinclude:: Step5/CMakeLists.txt
:caption: TODO 1: CMakeLists.txt
:name: CMakeLists.txt-cxx_std-feature
:language: cmake
:start-after: # specify the C++ standard
:end-before: # add compiler warning flags just
.. raw:: html
</details>
Finally, with our interface library set up, we need to link our
executable ``Target`` and our ``MathFunctions`` library to our new
``tutorial_compiler_flags`` library. Respectively, the code will look like
this:
.. raw:: html
<details><summary>TODO 2: Click to show/hide answer</summary>
.. literalinclude:: Step5/CMakeLists.txt
:caption: TODO 2: CMakeLists.txt
:name: CMakeLists.txt-target_link_libraries-step4
:language: cmake
:start-after: add_executable(Tutorial tutorial.cxx)
:end-before: # add the binary tree to the search path for include file
.. raw:: html
</details>
and this:
.. raw:: html
<details><summary>TODO 3: Click to show/hide answer</summary>
.. literalinclude:: Step5/MathFunctions/CMakeLists.txt
:caption: TODO 3: MathFunctions/CMakeLists.txt
:name: MathFunctions-CMakeLists.txt-target_link_libraries-step4
:language: cmake
:start-after: # link our compiler flags interface library
:end-before: # TODO 1
.. raw:: html
</details>
With this, all of our code still requires C++ 11 to build. Notice
though that with this method, it gives us the ability to be specific about
which targets get specific requirements. In addition, we create a single
source of truth in our interface library.
Exercise 2 - Adding Compiler Warning Flags with Generator Expressions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A common usage of
:manual:`generator expressions <cmake-generator-expressions(7)>` is to
conditionally add compiler flags, such as those for language levels or
warnings. A nice pattern is to associate this information to an ``INTERFACE``
target allowing this information to propagate. Let's start by constructing an
``INTERFACE`` target and specifying the required C++ standard level of ``11``
instead of using :variable:`CMAKE_CXX_STANDARD`.
target allowing this information to propagate.
So the following code:
Goal
----
.. literalinclude:: Step10/CMakeLists.txt
:caption: CMakeLists.txt
:name: CMakeLists.txt-CXX_STANDARD-variable-remove
Add compiler warning flags when building but not for installed versions.
Helpful Resources
-----------------
* :manual:`cmake-generator-expressions(7)`
* :command:`cmake_minimum_required`
* :command:`set`
* :command:`target_compile_options`
Files to Edit
-------------
* ``CMakeLists.txt``
Getting Started
---------------
Start with the resulting files from Exercise 1. Complete ``TODO 4`` through
``TODO 7``.
First, in the top level ``CMakeLists.txt`` file, we need to set the
:command:`cmake_minimum_required` to ``3.15``. In this exercise we are going
to use a generator expression which was introduced in CMake 3.15.
Next we add the desired compiler warning flags that we want for our project.
As warning flags vary based on the compiler, we use the
``COMPILE_LANG_AND_ID`` generator expression to control which flags to apply
given a language and a set of compiler ids.
Build and Run
-------------
Since we have our build directory already configured from Exercise 1, simply
rebuild our code by calling the following:
.. code-block:: console
cd Step4_build
cmake --build .
Solution
--------
Update the :command:`cmake_minimum_required` to require at least CMake
version ``3.15``:
.. raw:: html
<details><summary>TODO 4: Click to show/hide answer</summary>
.. literalinclude:: Step5/CMakeLists.txt
:caption: TODO 4: CMakeLists.txt
:name: MathFunctions-CMakeLists.txt-minimum-required-step4
:language: cmake
:start-after: project(Tutorial VERSION 1.0)
:end-before: # control where the static and shared libraries are built so that on windows
:end-before: # set the project name and version
Would be replaced with:
.. raw:: html
.. literalinclude:: Step11/CMakeLists.txt
:caption: CMakeLists.txt
:name: CMakeLists.txt-cxx_std-feature
:language: cmake
:start-after: project(Tutorial VERSION 1.0)
:end-before: # add compiler warning flags just when building this project via
</details>
**Note**: This upcoming section will require a change to the
:command:`cmake_minimum_required` usage in the code. The Generator Expression
that is about to be used was introduced in `3.15`. Update the call to require
that more recent version:
Next we determine which compiler our system is currently using to build
since warning flags vary based on the compiler we use. This is done with
the ``COMPILE_LANG_AND_ID`` generator expression. We set the result in the
variables ``gcc_like_cxx`` and ``msvc_cxx`` as follows:
.. code-block:: cmake
:caption: CMakeLists.txt
:name: CMakeLists.txt-version-update
.. raw:: html
cmake_minimum_required(VERSION 3.15)
<details><summary>TODO 5: Click to show/hide answer</summary>
Next we add the desired compiler warning flags that we want for our project. As
warning flags vary based on the compiler we use the ``COMPILE_LANG_AND_ID``
generator expression to control which flags to apply given a language and a set
of compiler ids as seen below:
.. literalinclude:: Step11/CMakeLists.txt
:caption: CMakeLists.txt
:name: CMakeLists.txt-target_compile_options-genex
.. literalinclude:: Step5/CMakeLists.txt
:caption: TODO 5: CMakeLists.txt
:name: CMakeLists.txt-compile_lang_and_id
:language: cmake
:start-after: # the BUILD_INTERFACE genex
:end-before: # control where the static and shared libraries are built so that on windows
:end-before: target_compile_options(tutorial_compiler_flags INTERFACE
Looking at this we see that the warning flags are encapsulated inside a
``BUILD_INTERFACE`` condition. This is done so that consumers of our installed
project will not inherit our warning flags.
.. raw:: html
**Exercise**: Modify ``MathFunctions/CMakeLists.txt`` so that all targets have
a :command:`target_link_libraries` call to ``tutorial_compiler_flags``.
</details>
Next we add the desired compiler warning flags that we want for our project.
Using our variables ``gcc_like_cxx`` and ``msvc_cxx``, we can use another
generator expression to apply the respective flags only when the variables are
true. We use :command:`target_compile_options` to apply these flags to our
interface library.
.. raw:: html
<details><summary>TODO 6: Click to show/hide answer</summary>
.. code-block:: cmake
:caption: TODO 6: CMakeLists.txt
:name: CMakeLists.txt-compile_flags
target_compile_options(tutorial_compiler_flags INTERFACE
"$<${gcc_like_cxx}:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>"
"$<${msvc_cxx}:-W3>"
)
.. raw:: html
</details>
Lastly, we only want these warning flags to be used during builds. Consumers
of our installed project should not inherit our warning flags. To specify
this, we wrap our flags in a generator expression using the ``BUILD_INTERFACE``
condition. The resulting full code looks like the following:
.. raw:: html
<details><summary>TODO 7: Click to show/hide answer</summary>
.. literalinclude:: Step5/CMakeLists.txt
:caption: TODO 7: CMakeLists.txt
:name: CMakeLists.txt-target_compile_options-genex
:language: cmake
:start-after: set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>")
:end-before: # should we use our own math functions
.. raw:: html
</details>

20
Help/guide/tutorial/Adding Support for a Testing Dashboard.rst
View File

@ -1,4 +1,4 @@
Step 8: Adding Support for a Testing Dashboard
Step 6: Adding Support for a Testing Dashboard
==============================================
Adding support for submitting our test results to a dashboard is simple. We
@ -9,21 +9,21 @@ we include the :module:`CTest` module in our top-level ``CMakeLists.txt``.
Replace:
.. code-block:: cmake
.. literalinclude:: Step6/CMakeLists.txt
:caption: CMakeLists.txt
:name: CMakeLists.txt-enable_testing-remove
# enable testing
enable_testing()
:language: cmake
:start-after: # enable testing
:end-before: # does the application run
With:
.. code-block:: cmake
.. literalinclude:: Step7/CMakeLists.txt
:caption: CMakeLists.txt
:name: CMakeLists.txt-include-CTest
# enable dashboard scripting
include(CTest)
:language: cmake
:start-after: # enable testing
:end-before: # does the application run
The :module:`CTest` module will automatically call ``enable_testing()``, so we
can remove it from our CMake files.
@ -46,7 +46,7 @@ downloaded from the ``Settings`` page of the project on the CDash
instance that will host and display the test results. Once downloaded from
CDash, the file should not be modified locally.
.. literalinclude:: Step9/CTestConfig.cmake
.. literalinclude:: Step7/CTestConfig.cmake
:caption: CTestConfig.cmake
:name: CTestConfig.cmake
:language: cmake

12
Help/guide/tutorial/Adding System Introspection.rst
View File

@ -1,4 +1,4 @@
Step 5: Adding System Introspection
Step 7: Adding System Introspection
===================================
Let us consider adding some code to our project that depends on features the
@ -15,7 +15,7 @@ these functions using the :module:`CheckCXXSourceCompiles` module in
Add the checks for ``log`` and ``exp`` to ``MathFunctions/CMakeLists.txt``,
after the call to :command:`target_include_directories`:
.. literalinclude:: Step6/MathFunctions/CMakeLists.txt
.. literalinclude:: Step8/MathFunctions/CMakeLists.txt
:caption: MathFunctions/CMakeLists.txt
:name: MathFunctions/CMakeLists.txt-check_cxx_source_compiles
:language: cmake
@ -25,19 +25,19 @@ after the call to :command:`target_include_directories`:
If available, use :command:`target_compile_definitions` to specify
``HAVE_LOG`` and ``HAVE_EXP`` as ``PRIVATE`` compile definitions.
.. literalinclude:: Step6/MathFunctions/CMakeLists.txt
.. literalinclude:: Step8/MathFunctions/CMakeLists.txt
:caption: MathFunctions/CMakeLists.txt
:name: MathFunctions/CMakeLists.txt-target_compile_definitions
:language: cmake
:start-after: # add compile definitions
:end-before: # install rules
:end-before: # install libs
If ``log`` and ``exp`` are available on the system, then we will use them to
compute the square root in the ``mysqrt`` function. Add the following code to
the ``mysqrt`` function in ``MathFunctions/mysqrt.cxx`` (don't forget the
``#endif`` before returning the result!):
.. literalinclude:: Step6/MathFunctions/mysqrt.cxx
.. literalinclude:: Step8/MathFunctions/mysqrt.cxx
:caption: MathFunctions/mysqrt.cxx
:name: MathFunctions/mysqrt.cxx-ifdef
:language: c++
@ -46,7 +46,7 @@ the ``mysqrt`` function in ``MathFunctions/mysqrt.cxx`` (don't forget the
We will also need to modify ``mysqrt.cxx`` to include ``cmath``.
.. literalinclude:: Step6/MathFunctions/mysqrt.cxx
.. literalinclude:: Step8/MathFunctions/mysqrt.cxx
:caption: MathFunctions/mysqrt.cxx
:name: MathFunctions/mysqrt.cxx-include-cmath
:language: c++

145
Help/guide/tutorial/Adding Usage Requirements for a Library.rst
View File

@ -1,52 +1,147 @@
Step 3: Adding Usage Requirements for a Library
===============================================
Usage requirements allow for far better control over a library or executable's
link and include line while also giving more control over the transitive
property of targets inside CMake. The primary commands that leverage usage
requirements are:
Exercise 1 - Adding Usage Requirements for a Library
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- :command:`target_compile_definitions`
- :command:`target_compile_options`
- :command:`target_include_directories`
- :command:`target_link_libraries`
:ref:`Usage requirements <Target Usage Requirements>` of a target parameters
allow for far better control over a library or executable's link and include
line while also giving more control over the transitive property of targets
inside CMake. The primary commands that
leverage usage requirements are:
Let's refactor our code from :guide:`tutorial/Adding a Library` to use the
modern CMake approach of usage requirements. We first state that anybody
linking to ``MathFunctions`` needs to include the current source directory,
while ``MathFunctions`` itself doesn't. So this can become an ``INTERFACE``
usage requirement.
* :command:`target_compile_definitions`
* :command:`target_compile_options`
* :command:`target_include_directories`
* :command:`target_link_directories`
* :command:`target_link_options`
* :command:`target_precompile_headers`
* :command:`target_sources`
Remember ``INTERFACE`` means things that consumers require but the producer
doesn't. Add the following lines to the end of
``MathFunctions/CMakeLists.txt``:
Goal
----
Add usage requirements for a library.
Helpful Materials
-----------------
* :variable:`CMAKE_CURRENT_SOURCE_DIR`
Files to Edit
-------------
* ``MathFunctions/CMakeLists.txt``
* ``CMakeLists.txt``
Getting Started
---------------
In this exercise, we will refactor our code from
:guide:`tutorial/Adding a Library` to use the modern CMake approach. We will
let our library define its own usage requirements so they are passed
transitively to other targets as necessary. In this case, ``MathFunctions``
will specify any needed include directories itself. Then, the consuming target
``Tutorial`` simply needs to link to ``MathFunctions`` and not worry about
any additional include directories.
The starting source code is provided in the ``Step3`` directory. In this
exercise, complete ``TODO 1`` through ``TODO 3``.
First, add a call to :command:`target_include_directories` in
``MathFunctions/CMakeLists``. Remember that
:variable:`CMAKE_CURRENT_SOURCE_DIR` is the path to the source directory
currently being processed.
Then, update (and simplify!) the call to
:command:`target_include_directories` in the top-level ``CMakeLists.txt``.
Build and Run
-------------
Make a new directory called ``Step3_build``, run the :manual:`cmake
<cmake(1)>` executable or the :manual:`cmake-gui <cmake-gui(1)>` to
configure the project and then build it with your chosen build tool or by
using :option:`cmake --build . <cmake --build>` from the build directory.
Here's a refresher of what that looks like from the command line:
.. code-block:: console
mkdir Step3_build
cd Step3_build
cmake ../Step3
cmake --build .
Next, use the newly built ``Tutorial`` and verify that it is working as
expected.
Solution
--------
Let's update the code from the previous step to use the modern CMake
approach of usage requirements.
We want to state that anybody linking to ``MathFunctions`` needs to include
the current source directory, while ``MathFunctions`` itself doesn't. This
can be expressed with an ``INTERFACE`` usage requirement. Remember
``INTERFACE`` means things that consumers require but the producer doesn't.
At the end of ``MathFunctions/CMakeLists.txt``, use
:command:`target_include_directories` with the ``INTERFACE`` keyword, as
follows:
.. raw:: html
<details><summary>TODO 1: Click to show/hide answer</summary>
.. literalinclude:: Step4/MathFunctions/CMakeLists.txt
:caption: MathFunctions/CMakeLists.txt
:caption: TODO 1: MathFunctions/CMakeLists.txt
:name: MathFunctions/CMakeLists.txt-target_include_directories-INTERFACE
:language: cmake
:start-after: # to find MathFunctions.h
:end-before: # TODO 3: Link to
Now that we've specified usage requirements for ``MathFunctions`` we can safely
remove our uses of the ``EXTRA_INCLUDES`` variable from the top-level
.. raw:: html
</details>
Now that we've specified usage requirements for ``MathFunctions`` we can
safely remove our uses of the ``EXTRA_INCLUDES`` variable from the top-level
``CMakeLists.txt``, here:
.. raw:: html
<details><summary>TODO 2: Click to show/hide answer</summary>
.. literalinclude:: Step4/CMakeLists.txt
:caption: CMakeLists.txt
:caption: TODO 2: CMakeLists.txt
:name: CMakeLists.txt-remove-EXTRA_INCLUDES
:language: cmake
:start-after: # add the MathFunctions library
:end-before: # add the executable
.. raw:: html
</details>
And here:
.. raw:: html
<details><summary>TODO 3: Click to show/hide answer</summary>
.. literalinclude:: Step4/CMakeLists.txt
:caption: CMakeLists.txt
:caption: TODO 3: CMakeLists.txt
:name: CMakeLists.txt-target_include_directories-remove-EXTRA_INCLUDES
:language: cmake
:start-after: # so that we will find TutorialConfig.h
Once this is done, run the :manual:`cmake <cmake(1)>` executable or the
:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it
with your chosen build tool or by using ``cmake --build .`` from the build
directory.
.. raw:: html
</details>
Notice that with this technique, the only thing our executable target does to
use our library is call :command:`target_link_libraries` with the name
of the library target. In larger projects, the classic method of specifying
library dependencies manually becomes very complicated very quickly.

14
Help/guide/tutorial/Adding a Custom Command and Generated File.rst
View File

@ -1,4 +1,4 @@
Step 6: Adding a Custom Command and Generated File
Step 8: Adding a Custom Command and Generated File
==================================================
Suppose, for the purpose of this tutorial, we decide that we never want to use
@ -26,7 +26,7 @@ accomplish this.
First, at the top of ``MathFunctions/CMakeLists.txt``, the executable for
``MakeTable`` is added as any other executable would be added.
.. literalinclude:: Step7/MathFunctions/CMakeLists.txt
.. literalinclude:: Step9/MathFunctions/CMakeLists.txt
:caption: MathFunctions/CMakeLists.txt
:name: MathFunctions/CMakeLists.txt-add_executable-MakeTable
:language: cmake
@ -36,7 +36,7 @@ First, at the top of ``MathFunctions/CMakeLists.txt``, the executable for
Then we add a custom command that specifies how to produce ``Table.h``
by running MakeTable.
.. literalinclude:: Step7/MathFunctions/CMakeLists.txt
.. literalinclude:: Step9/MathFunctions/CMakeLists.txt
:caption: MathFunctions/CMakeLists.txt
:name: MathFunctions/CMakeLists.txt-add_custom_command-Table.h
:language: cmake
@ -47,7 +47,7 @@ Next we have to let CMake know that ``mysqrt.cxx`` depends on the generated
file ``Table.h``. This is done by adding the generated ``Table.h`` to the list
of sources for the library MathFunctions.
.. literalinclude:: Step7/MathFunctions/CMakeLists.txt
.. literalinclude:: Step9/MathFunctions/CMakeLists.txt
:caption: MathFunctions/CMakeLists.txt
:name: MathFunctions/CMakeLists.txt-add_library-Table.h
:language: cmake
@ -57,17 +57,17 @@ of sources for the library MathFunctions.
We also have to add the current binary directory to the list of include
directories so that ``Table.h`` can be found and included by ``mysqrt.cxx``.
.. literalinclude:: Step7/MathFunctions/CMakeLists.txt
.. literalinclude:: Step9/MathFunctions/CMakeLists.txt
:caption: MathFunctions/CMakeLists.txt
:name: MathFunctions/CMakeLists.txt-target_include_directories-Table.h
:language: cmake
:start-after: # state that we depend on our bin
:end-before: # install rules
:end-before: # install libs
Now let's use the generated table. First, modify ``mysqrt.cxx`` to include
``Table.h``. Next, we can rewrite the ``mysqrt`` function to use the table:
.. literalinclude:: Step7/MathFunctions/mysqrt.cxx
.. literalinclude:: Step9/MathFunctions/mysqrt.cxx
:caption: MathFunctions/mysqrt.cxx
:name: MathFunctions/mysqrt.cxx
:language: c++

551
Help/guide/tutorial/Adding a Library.rst
View File

@ -1,136 +1,459 @@
Step 2: Adding a Library
========================
Now we will add a library to our project. This library will contain our own
At this point, we have seen how to create a basic project using CMake. In this
step, we will learn how to create and use a library in our project. We will
also see how to make the use of our library optional.
Exercise 1 - Creating a Library
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To add a library in CMake, use the :command:`add_library` command and specify
which source files should make up the library.
Rather than placing all of the source files in one directory, we can organize
our project with one or more subdirectories. In this case, we will create a
subdirectory specifically for our library. Here, we can add a new
``CMakeLists.txt`` file and one or more source files. In the top level
``CMakeLists.txt`` file, we will use the :command:`add_subdirectory` command
to add the subdirectory to the build.
Once the library is created, it is connected to our executable target with
:command:`target_include_directories` and :command:`target_link_libraries`.
Goal
----
Add and use a library.
Helpful Resources
-----------------
* :command:`add_library`
* :command:`add_subdirectory`
* :command:`target_include_directories`
* :command:`target_link_libraries`
* :variable:`PROJECT_SOURCE_DIR`
Files to Edit
-------------
* ``CMakeLists.txt``
* ``tutorial.cxx``
* ``MathFunctions/CMakeLists.txt``
Getting Started
---------------
In this exercise, we will add a library to our project that contains our own
implementation for computing the square root of a number. The executable can
then use this library instead of the standard square root function provided by
the compiler.
For this tutorial we will put the library into a subdirectory
called ``MathFunctions``. This directory already contains a header file,
``MathFunctions.h``, and a source file ``mysqrt.cxx``. The source file has one
function called ``mysqrt`` that provides similar functionality to the
compiler's ``sqrt`` function.
For this tutorial we will put the library into a subdirectory called
``MathFunctions``. This directory already contains a header file,
``MathFunctions.h``, and a source file ``mysqrt.cxx``. We will not need to
modify either of these files. The source file has one function called
``mysqrt`` that provides similar functionality to the compiler's ``sqrt``
function.
Add the following one line ``CMakeLists.txt`` file to the ``MathFunctions``
directory:
From the ``Help/guide/tutorial/Step2`` directory, start with ``TODO 1`` and
complete through ``TODO 6``.
.. literalinclude:: Step3/MathFunctions/CMakeLists.txt
:caption: MathFunctions/CMakeLists.txt
:name: MathFunctions/CMakeLists.txt
:language: cmake
First, fill in the one line ``CMakeLists.txt`` in the ``MathFunctions``
subdirectory.
To make use of the new library we will add an :command:`add_subdirectory`
call in the top-level ``CMakeLists.txt`` file so that the library will get
built. We add the new library to the executable, and add ``MathFunctions`` as
an include directory so that the ``MathFunctions.h`` header file can be found.
The last few lines of the top-level ``CMakeLists.txt`` file should now look
like:
Next, edit the top level ``CMakeLists.txt``.
.. code-block:: cmake
:caption: CMakeLists.txt
:name: CMakeLists.txt-add_subdirectory
Finally, use the newly created ``MathFunctions`` library in ``tutorial.cxx``
# add the MathFunctions library
add_subdirectory(MathFunctions)
# add the executable
add_executable(Tutorial tutorial.cxx)
target_link_libraries(Tutorial PUBLIC MathFunctions)
# add the binary tree to the search path for include files
# so that we will find TutorialConfig.h
target_include_directories(Tutorial PUBLIC
"${PROJECT_BINARY_DIR}"
"${PROJECT_SOURCE_DIR}/MathFunctions"
)
Now let us make the ``MathFunctions`` library optional. While for the tutorial
there really isn't any need to do so, for larger projects this is a common
occurrence. The first step is to add an option to the top-level
``CMakeLists.txt`` file.
.. literalinclude:: Step3/CMakeLists.txt
:caption: CMakeLists.txt
:name: CMakeLists.txt-option
:language: cmake
:start-after: # should we use our own math functions
:end-before: # add the MathFunctions library
This option will be displayed in the :manual:`cmake-gui <cmake-gui(1)>` and
:manual:`ccmake <ccmake(1)>`
with a default value of ``ON`` that can be changed by the user. This setting
will be stored in the cache so that the user does not need to set the value
each time they run CMake on a build directory.
The next change is to make building and linking the ``MathFunctions`` library
conditional. To do this, we will create an ``if`` statement which checks the
value of the option. Inside the ``if`` block, put the
:command:`add_subdirectory` command from above with some additional list
commands to store information needed to link to the library and add the
subdirectory as an include directory in the ``Tutorial`` target.
The end of the top-level ``CMakeLists.txt`` file will now look like the
following:
.. literalinclude:: Step3/CMakeLists.txt
:caption: CMakeLists.txt
:name: CMakeLists.txt-target_link_libraries-EXTRA_LIBS
:language: cmake
:start-after: # add the MathFunctions library
Note the use of the variable ``EXTRA_LIBS`` to collect up any optional
libraries to later be linked into the executable. The variable
``EXTRA_INCLUDES`` is used similarly for optional header files. This is a
classic approach when dealing with many optional components, we will cover
the modern approach in the next step.
The corresponding changes to the source code are fairly straightforward.
First, in ``tutorial.cxx``, include the ``MathFunctions.h`` header if we
need it:
.. literalinclude:: Step3/tutorial.cxx
:caption: tutorial.cxx
:name: tutorial.cxx-ifdef-include
:language: c++
:start-after: // should we include the MathFunctions header
:end-before: int main
Then, in the same file, make ``USE_MYMATH`` control which square root
function is used:
.. literalinclude:: Step3/tutorial.cxx
:caption: tutorial.cxx
:name: tutorial.cxx-ifdef-const
:language: c++
:start-after: // which square root function should we use?
:end-before: std::cout << "The square root of
Since the source code now requires ``USE_MYMATH`` we can add it to
``TutorialConfig.h.in`` with the following line:
.. literalinclude:: Step3/TutorialConfig.h.in
:caption: TutorialConfig.h.in
:name: TutorialConfig.h.in-cmakedefine
:language: c++
:lines: 4
**Exercise**: Why is it important that we configure ``TutorialConfig.h.in``
after the option for ``USE_MYMATH``? What would happen if we inverted the two?
Build and Run
-------------
Run the :manual:`cmake <cmake(1)>` executable or the
:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it
with your chosen build tool. Then run the built Tutorial executable.
with your chosen build tool.
Now let's update the value of ``USE_MYMATH``. The easiest way is to use the
:manual:`cmake-gui <cmake-gui(1)>` or :manual:`ccmake <ccmake(1)>` if you're
in the terminal. Or, alternatively, if you want to change the option from the
command-line, try:
Below is a refresher of what that looks like from the command line:
.. code-block:: console
mkdir Step2_build
cd Step2_build
cmake ../Step2
cmake --build .
Try to use the newly built ``Tutorial`` and ensure that it is still
producing accurate square root values.
Solution
--------
In the ``CMakeLists.txt`` file in the ``MathFunctions`` directory, we create
a library target called ``MathFunctions`` with :command:`add_library`. The
source file for the library is passed as an argument to
:command:`add_library`. This looks like the following line:
.. raw:: html
<details><summary>TODO 1: Click to show/hide answer</summary>
.. literalinclude:: Step3/MathFunctions/CMakeLists.txt
:caption: TODO 1: MathFunctions/CMakeLists.txt
:name: MathFunctions/CMakeLists.txt-add_library
:language: cmake
:end-before: # TODO 1
.. raw:: html
</details>
To make use of the new library we will add an :command:`add_subdirectory`
call in the top-level ``CMakeLists.txt`` file so that the library will get
built.
.. raw:: html
<details><summary>TODO 2: Click to show/hide answer</summary>
.. code-block:: cmake
:caption: TODO 2: CMakeLists.txt
:name: CMakeLists.txt-add_subdirectory
add_subdirectory(MathFunctions)
.. raw:: html
</details>
Next, the new library target is linked to the executable target using
:command:`target_link_libraries`.
.. raw:: html
<details><summary>TODO 3: Click to show/hide answer</summary>
.. code-block:: cmake
:caption: TODO 3: CMakeLists.txt
:name: CMakeLists.txt-target_link_libraries
target_link_libraries(Tutorial PUBLIC MathFunctions)
.. raw:: html
</details>
Finally we need to specify the library's header file location. Modify
:command:`target_include_directories` to add the ``MathFunctions`` subdirectory
as an include directory so that the ``MathFunctions.h`` header file can be
found.
.. raw:: html
<details><summary>TODO 4: Click to show/hide answer</summary>
.. code-block:: cmake
:caption: TODO 4: CMakeLists.txt
:name: CMakeLists.txt-target_include_directories-step2
target_include_directories(Tutorial PUBLIC
"${PROJECT_BINARY_DIR}"
"${PROJECT_SOURCE_DIR}/MathFunctions"
)
.. raw:: html
</details>
Now let's use our library. In ``tutorial.cxx``, include ``MathFunctions.h``:
.. raw:: html
<details><summary>TODO 5: Click to show/hide answer</summary>
.. code-block:: c++
:caption: TODO 5 : tutorial.cxx
:name: tutorial.cxx-include_MathFunctions.h
#include "MathFunctions.h"
.. raw:: html
</details>
Lastly, replace ``sqrt`` with our library function ``mysqrt``.
.. raw:: html
<details><summary>TODO 6: Click to show/hide answer</summary>
.. code-block:: c++
:caption: TODO 6 : tutorial.cxx
:name: tutorial.cxx-call_mysqrt
const double outputValue = mysqrt(inputValue);
.. raw:: html
</details>
Exercise 2 - Making Our Library Optional
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Now let us make the MathFunctions library optional. While for the tutorial
there really isn't any need to do so, for larger projects this is a common
occurrence.
CMake can do this using the :command:`option` command. This gives users a
variable which they can change when configuring their cmake build. This
setting will be stored in the cache so that the user does not need to set
the value each time they run CMake on a build directory.
Goal
----
Add the option to build without ``MathFunctions``.
Helpful Resources
-----------------
* :command:`if`
* :command:`list`
* :command:`option`
* :command:`cmakedefine <configure_file>`
Files to Edit
-------------
* ``CMakeLists.txt``
* ``tutorial.cxx``
* ``TutorialConfig.h.in``
Getting Started
---------------
Start with the resulting files from Exercise 1. Complete ``TODO 7`` through
``TODO 13``.
First create a variable ``USE_MYMATH`` using the :command:`option` command
in the top-level ``CMakeLists.txt`` file. In that same file, use that option
to determine whether to build and use the ``MathFunctions`` library.
Then, update ``tutorial.cxx`` and ``TutorialConfig.h.in`` to use
``USE_MYMATH``.
Build and Run
-------------
Since we have our build directory already configured from Exercise 1, we can
rebuild by simply calling the following:
.. code-block:: console
cd ../Step2_build
cmake --build .
Next, run the ``Tutorial`` executable on a few numbers to verify that it's
still correct.
Now let's update the value of ``USE_MYMATH`` to ``OFF``. The easiest way is to
use the :manual:`cmake-gui <cmake-gui(1)>` or :manual:`ccmake <ccmake(1)>`
if you're in the terminal. Or, alternatively, if you want to change the
option from the command-line, try:
.. code-block:: console
cmake ../Step2 -DUSE_MYMATH=OFF
Rebuild and run the tutorial again.
Now, rebuild the code with the following:
Which function gives better results, ``sqrt`` or ``mysqrt``?
.. code-block:: console
cmake --build .
Then, run the executable again to ensure that it still works with
``USE_MYMATH`` set to ``OFF``. Which function gives better results, ``sqrt``
or ``mysqrt``?
Solution
--------
The first step is to add an option to the top-level ``CMakeLists.txt`` file.
This option will be displayed in the :manual:`cmake-gui <cmake-gui(1)>` and
:manual:`ccmake <ccmake(1)>` with a default value of ``ON`` that can be
changed by the user.
.. raw:: html
<details><summary>TODO 7: Click to show/hide answer</summary>
.. literalinclude:: Step3/CMakeLists.txt
:caption: TODO 7: CMakeLists.txt
:name: CMakeLists.txt-option
:language: cmake
:start-after: # should we use our own math functions
:end-before: # configure a header file to pass some of the CMake settings
.. raw:: html
</details>
Next, make building and linking the ``MathFunctions`` library
conditional.
Start by creating a :command:`list` of the optional library targets for our
project. At the moment, it is just ``MathFunctions``. Let's name our list
``EXTRA_LIBS``.
Similarly, we need to make a :command:`list` for the optional includes which
we will call ``EXTRA_INCLUDES``. In this list, we will ``APPEND`` the path of
the header file needed for our library.
Next, create an :command:`if` statement which checks the value of
``USE_MYMATH``. Inside the :command:`if` block, put the
:command:`add_subdirectory` command from Exercise 1 with the additional
:command:`list` commands.
When ``USE_MYMATH`` is ``ON``, the lists will be generated and will be added to
our project. When ``USE_MYMATH`` is ``OFF``, the lists stay empty. With this
strategy, we allow users to toggle ``USE_MYMATH`` to manipulate what library is
used in the build.
The top-level CMakeLists.txt file will now look like the following:
.. raw:: html
<details><summary>TODO 8: Click to show/hide answer</summary>
.. literalinclude:: Step3/CMakeLists.txt
:caption: TODO 8: CMakeLists.txt
:name: CMakeLists.txt-USE_MYMATH
:language: cmake
:start-after: # add the MathFunctions library
:end-before: # add the executable
.. raw:: html
</details>
Now that we have these two lists, we need to update
:command:`target_link_libraries` and :command:`target_include_directories` to
use them. Changing them is fairly straightforward.
For :command:`target_link_libraries`, we replace the written out
library names with ``EXTRA_LIBS``. This looks like the following:
.. raw:: html
<details><summary>TODO 9: Click to show/hide answer</summary>
.. literalinclude:: Step3/CMakeLists.txt
:caption: TODO 9: CMakeLists.txt
:name: CMakeLists.txt-target_link_libraries-EXTRA_LIBS
:language: cmake
:start-after: add_executable(Tutorial tutorial.cxx)
:end-before: # TODO 3
.. raw:: html
</details>
Then, we do the same thing with :command:`target_include_directories` and
``EXTRA_INCLUDES``.
.. raw:: html
<details><summary>TODO 10: Click to show/hide answer</summary>
.. literalinclude:: Step3/CMakeLists.txt
:caption: TODO 10 : CMakeLists.txt
:name: CMakeLists.txt-target_link_libraries-EXTRA_INCLUDES
:language: cmake
:start-after: # so that we will find TutorialConfig.h
.. raw:: html
</details>
Note that this is a classic approach when dealing with many components. We
will cover the modern approach in the Step 3 of the tutorial.
The corresponding changes to the source code are fairly straightforward.
First, in ``tutorial.cxx``, we include the ``MathFunctions.h`` header if
``USE_MYMATH`` is defined.
.. raw:: html
<details><summary>TODO 11: Click to show/hide answer</summary>
.. literalinclude:: Step3/tutorial.cxx
:caption: TODO 11 : tutorial.cxx
:name: tutorial.cxx-ifdef-include
:language: c++
:start-after: // should we include the MathFunctions header
:end-before: int main
.. raw:: html
</details>
Then, in the same file, we make ``USE_MYMATH`` control which square root
function is used:
.. raw:: html
<details><summary>TODO 12: Click to show/hide answer</summary>
.. literalinclude:: Step3/tutorial.cxx
:caption: TODO 12 : tutorial.cxx
:name: tutorial.cxx-ifdef-const
:language: c++
:start-after: // which square root function should we use?
:end-before: std::cout << "The square root of
.. raw:: html
</details>
Since the source code now requires ``USE_MYMATH`` we can add it to
``TutorialConfig.h.in`` with the following line:
.. raw:: html
<details><summary>TODO 13: Click to show/hide answer</summary>
.. literalinclude:: Step3/TutorialConfig.h.in
:caption: TODO 13 : TutorialConfig.h.in
:name: TutorialConfig.h.in-cmakedefine
:language: c++
:lines: 4
.. raw:: html
</details>
With these changes, our library is now completely optional to whoever is
building and using it.
Bonus Question
--------------
Why is it important that we configure ``TutorialConfig.h.in``
after the option for ``USE_MYMATH``? What would happen if we inverted the two?
Answer
------
.. raw:: html
<details><summary>Click to show/hide answer</summary>
We configure after because ``TutorialConfig.h.in`` uses the value of
``USE_MYMATH``. If we configure the file before
calling :command:`option`, we won't be using the expected value of
``USE_MYMATH``.
.. raw:: html
</details>

3
Help/guide/tutorial/Complete/CMakeLists.txt
View File

@ -41,7 +41,7 @@ add_subdirectory(MathFunctions)
add_executable(Tutorial tutorial.cxx)
set_target_properties(Tutorial PROPERTIES DEBUG_POSTFIX ${CMAKE_DEBUG_POSTFIX})
target_link_libraries(Tutorial PUBLIC MathFunctions)
target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags)
# add the binary tree to the search path for include files
# so that we will find TutorialConfig.h
@ -84,6 +84,7 @@ do_test(Tutorial 25 "25 is 5")
do_test(Tutorial -25 "-25 is (-nan|nan|0)")
do_test(Tutorial 0.0001 "0.0001 is 0.01")
# setup installer
include(InstallRequiredSystemLibraries)
set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt")
set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}")

2
Help/guide/tutorial/Complete/License.txt
View File

@ -1,2 +1,2 @@
This is the open source License.txt file introduced in
CMake/Tutorial/Step7...
CMake/Tutorial/Step9...

3
Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt
View File

@ -56,7 +56,7 @@ target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")
set_property(TARGET MathFunctions PROPERTY VERSION "1.0.0")
set_property(TARGET MathFunctions PROPERTY SOVERSION "1")
# install rules
# install libs
set(installable_libs MathFunctions tutorial_compiler_flags)
if(TARGET SqrtLibrary)
list(APPEND installable_libs SqrtLibrary)
@ -64,4 +64,5 @@ endif()
install(TARGETS ${installable_libs}
EXPORT MathFunctionsTargets
DESTINATION lib)
# install include headers
install(FILES MathFunctions.h DESTINATION include)

332
Help/guide/tutorial/Installing and Testing.rst
View File

@ -1,95 +1,311 @@
Step 4: Installing and Testing
Step 5: Installing and Testing
==============================
Now we can start adding install rules and testing support to our project.
.. _`Tutorial Testing Support`:
Install Rules
Exercise 1 - Install Rules
^^^^^^^^^^^^^^^^^^^^^^^^^^
Often, it is not enough to only build an executable, it should also be
installable. With CMake, we can specify install rules using the
:command:`install` command. Supporting local installations for your builds in
CMake is often as simple as specifying an install location and the targets and
files to be installed.
Goal
----
Install the ``Tutorial`` executable and the ``MathFunctions`` library.
Helpful Materials
-----------------
* :command:`install`
Files to Edit
-------------
The install rules are fairly simple: for ``MathFunctions`` we want to install
the library and header file and for the application we want to install the
executable and configured header.
* ``MathFunctions/CMakeLists.txt``
* ``CMakeLists.txt``
So to the end of ``MathFunctions/CMakeLists.txt`` we add:
Getting Started
---------------
.. literalinclude:: Step5/MathFunctions/CMakeLists.txt
:caption: MathFunctions/CMakeLists.txt
:name: MathFunctions/CMakeLists.txt-install-TARGETS
:language: cmake
:start-after: # install rules
The starting code is provided in the ``Step5`` directory. In this
exercise, complete ``TODO 1`` through ``TODO 4``.
And to the end of the top-level ``CMakeLists.txt`` we add:
First, update ``MathFunctions/CMakeLists.txt`` to install the
``MathFunctions`` and ``tutorial_compiler_flags`` libraries to the ``lib``
directory. In that same file, specify the install rules needed to install
``MathFunctions.h`` to the ``include`` directory.
.. literalinclude:: Step5/CMakeLists.txt
:caption: CMakeLists.txt
:name: CMakeLists.txt-install-TARGETS
:language: cmake
:start-after: # add the install targets
:end-before: # enable testing
Then, update the top level ``CMakeLists.txt`` to install
the ``Tutorial`` executable to the ``bin`` directory. Lastly, any header files
should be installed to the ``include`` directory. Remember that
``TutorialConfig.h`` is in the :variable:`PROJECT_BINARY_DIR`.
That is all that is needed to create a basic local install of the tutorial.
Build and Run
-------------
Now run the :manual:`cmake <cmake(1)>` executable or the
Make a new directory called ``Step5_build``. Run the
:manual:`cmake <cmake(1)>` executable or the
:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it
with your chosen build tool.
Then run the install step by using the ``install`` option of the
:manual:`cmake <cmake(1)>` command (introduced in 3.15, older versions of
CMake must use ``make install``) from the command line. For
multi-configuration tools, don't forget to use the ``--config`` argument to
specify the configuration. If using an IDE, simply build the ``INSTALL``
target. This step will install the appropriate header files, libraries, and
executables. For example:
Then, run the install step by using the :option:`--install <cmake --install>`
option of the :manual:`cmake <cmake(1)>` command (introduced in 3.15, older
versions of CMake must use ``make install``) from the command line. This step
will install the appropriate header files, libraries, and executables.
For example:
.. code-block:: console
cmake --install .
For multi-configuration tools, don't forget to use the
:option:`--config <cmake--build --config>` argument to specify the configuration.
.. code-block:: console
cmake --install . --config Release
If using an IDE, simply build the ``INSTALL`` target. You can build the same
install target from the command line like the following:
.. code-block:: console
cmake --build . --target install --config Debug
The CMake variable :variable:`CMAKE_INSTALL_PREFIX` is used to determine the
root of where the files will be installed. If using the ``cmake --install``
command, the installation prefix can be overridden via the ``--prefix``
argument. For example:
root of where the files will be installed. If using the :option:`cmake --install`
command, the installation prefix can be overridden via the
:option:`--prefix <cmake--install --prefix>` argument. For example:
.. code-block:: console
cmake --install . --prefix "/home/myuser/installdir"
Navigate to the install directory and verify that the installed Tutorial runs.
Navigate to the install directory and verify that the installed ``Tutorial``
runs.
.. _`Tutorial Testing Support`:
Solution
--------
Testing Support
The install rules for our project are fairly simple:
* For ``MathFunctions``, we want to install the libraries and header file to
the ``lib`` and ``include`` directories respectively.
* For the ``Tutorial`` executable, we want to install the executable and
configured header file to the ``bin`` and ``include`` directories
respectively.
So to the end of ``MathFunctions/CMakeLists.txt`` we add:
.. raw:: html
<details><summary>TODO 1: Click to show/hide answer</summary>
.. literalinclude:: Step6/MathFunctions/CMakeLists.txt
:caption: TODO 1: MathFunctions/CMakeLists.txt
:name: MathFunctions/CMakeLists.txt-install-TARGETS
:language: cmake
:start-after: # install libs
:end-before: # install include headers
.. raw:: html
</details>
and
.. raw:: html
<details><summary>TODO 2: Click to show/hide answer</summary>
.. literalinclude:: Step6/MathFunctions/CMakeLists.txt
:caption: TODO 2: MathFunctions/CMakeLists.txt
:name: MathFunctions/CMakeLists.txt-install-headers
:language: cmake
:start-after: # install include headers
.. raw:: html
</details>
The install rules for the ``Tutorial`` executable and configured header file
are similar. To the end of the top-level ``CMakeLists.txt`` we add:
.. raw:: html
<details><summary>TODO 3,4: Click to show/hide answer</summary>
.. literalinclude:: Step6/CMakeLists.txt
:caption: CMakeLists.txt
:name: TODO 3,4: CMakeLists.txt-install-TARGETS
:language: cmake
:start-after: # add the install targets
:end-before: # enable testing
.. raw:: html
</details>
That is all that is needed to create a basic local
install of the tutorial.
Exercise 2 - Testing Support
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
CTest offers a way to easily manage tests for your project. Tests can be
added through the :command:`add_test` command. Although it is not
explicitly covered in this tutorial, there is a lot of compatibility
between CTest and other testing frameworks such as :module:`GoogleTest`.
Goal
----
Create unit tests for our executable using CTest.
Helpful Materials
-----------------
* :command:`enable_testing`
* :command:`add_test`
* :command:`function`
* :command:`set_tests_properties`
* :manual:`ctest <ctest(1)>`
Files to Edit
-------------
* ``CMakeLists.txt``
Getting Started
---------------
Next let's test our application. At the end of the top-level ``CMakeLists.txt``
file we can enable testing and then add a number of basic tests to verify that
the application is working correctly.
The starting source code is provided in the ``Step5`` directory. In this
exercise, complete ``TODO 5`` through ``TODO 9``.
.. literalinclude:: Step5/CMakeLists.txt
:caption: CMakeLists.txt
First, we need to enable testing. Next, begin adding tests to our project
using :command:`add_test`. We will work through adding 3 simple tests and
then you can add additional testing as you see fit.
Build and Run
-------------
Navigate to the build directory and rebuild the application. Then, run the
``ctest`` executable: :option:`ctest -N` and :option:`ctest -VV`. For
multi-config generators (e.g. Visual Studio), the configuration type must be
specified with the :option:`-C \<mode\> <ctest -C>` flag. For example, to run tests in Debug
mode use ``ctest -C Debug -VV`` from the build directory
(not the Debug subdirectory!). Release mode would be executed from the same
location but with a ``-C Release``. Alternatively, build the ``RUN_TESTS``
target from the IDE.
Solution
--------
Let's test our application. At the end of the top-level ``CMakeLists.txt``
file we first need to enable testing with the
:command:`enable_testing` command.
.. raw:: html
<details><summary>TODO 5: Click to show/hide answer</summary>
.. literalinclude:: Step6/CMakeLists.txt
:caption: TODO 5: CMakeLists.txt
:name: CMakeLists.txt-enable_testing
:language: cmake
:start-after: # enable testing
:end-before: # does the application run
The first test simply verifies that the application runs, does not segfault or
otherwise crash, and has a zero return value. This is the basic form of a
CTest test.
.. raw:: html
The next test makes use of the :prop_test:`PASS_REGULAR_EXPRESSION` test
property to verify that the output of the test contains certain strings. In
this case, verifying that the usage message is printed when an incorrect number
of arguments are provided.
</details>
Lastly, we have a function called ``do_test`` that runs the application and
verifies that the computed square root is correct for given input. For each
invocation of ``do_test``, another test is added to the project with a name,
input, and expected results based on the passed arguments.
With testing enabled, we will add a number of basic tests to verify
that the application is working correctly. First, we create a test using
:command:`add_test` which runs the ``Tutorial`` executable with the
parameter 25 passed in. For this test, we are not going to check the
executable's computed answer. This test will verify that
application runs, does not segfault or otherwise crash, and has a zero
return value. This is the basic form of a CTest test.
Rebuild the application and then cd to the binary directory and run the
:manual:`ctest <ctest(1)>` executable: ``ctest -N`` and ``ctest -VV``. For
multi-config generators (e.g. Visual Studio), the configuration type must be
specified with the ``-C <mode>`` flag. For example, to run tests in Debug
mode use ``ctest -C Debug -VV`` from the binary directory
(not the Debug subdirectory!). Release mode would be executed from the same
location but with a ``-C Release``. Alternatively, build the ``RUN_TESTS``
target from the IDE.
.. raw:: html
<details><summary>TODO 6: Click to show/hide answer</summary>
.. literalinclude:: Step6/CMakeLists.txt
:caption: TODO 6: CMakeLists.txt
:name: CMakeLists.txt-test-runs
:language: cmake
:start-after: # does the application run
:end-before: # does the usage message work
.. raw:: html
</details>
Next, let's use the :prop_test:`PASS_REGULAR_EXPRESSION` test property to
verify that the output of the test contains certain strings. In this case,
verifying that the usage message is printed when an incorrect number of
arguments are provided.
.. raw:: html
<details><summary>TODO 7: Click to show/hide answer</summary>
.. literalinclude:: Step6/CMakeLists.txt
:caption: TODO 7: CMakeLists.txt
:name: CMakeLists.txt-test-usage
:language: cmake
:start-after: # does the usage message work?
:end-before: # define a function to simplify adding tests
.. raw:: html
</details>
The next test we will add verifies the computed value is truly the
square root.
.. raw:: html
<details><summary>TODO 8: Click to show/hide answer</summary>
.. code-block:: cmake
:caption: TODO 8: CMakeLists.txt
:name: CMakeLists.txt-test-standard
add_test(NAME StandardUse COMMAND Tutorial 4)
set_tests_properties(StandardUse
PROPERTIES PASS_REGULAR_EXPRESSION "4 is 2"
)
.. raw:: html
</details>
This one test is not enough to give us confidence that it will
work for all values passed in. We should add more tests to verify this.
To easily add more tests, we make a function called ``do_test`` that runs the
application and verifies that the computed square root is correct for
given input. For each invocation of ``do_test``, another test is added to
the project with a name, input, and expected results based on the passed
arguments.
.. raw:: html
<details><summary>TODO 9: Click to show/hide answer</summary>
.. literalinclude:: Step6/CMakeLists.txt
:caption: TODO 9: CMakeLists.txt
:name: CMakeLists.txt-generalized-tests
:language: cmake
:start-after: # define a function to simplify adding tests
.. raw:: html
</details>

8
Help/guide/tutorial/Packaging Debug and Release.rst
View File

@ -10,8 +10,8 @@ possible, however, to setup CPack to bundle multiple build directories and
construct a package that contains multiple configurations of the same project.
First, we want to ensure that the debug and release builds use different names
for the executables and libraries that will be installed. Let's use `d` as the
postfix for the debug executable and libraries.
for the libraries that will be installed. Let's use `d` as the
postfix for the debug libraries.
Set :variable:`CMAKE_DEBUG_POSTFIX` near the beginning of the top-level
``CMakeLists.txt`` file:
@ -41,10 +41,10 @@ Let's also add version numbering to the ``MathFunctions`` library. In
:name: MathFunctions/CMakeLists.txt-VERSION-properties
:language: cmake
:start-after: # setup the version numbering
:end-before: # install rules
:end-before: # install libs
From the ``Step12`` directory, create ``debug`` and ``release``
subbdirectories. The layout will look like:
subdirectories. The layout will look like:
.. code-block:: none

10
Help/guide/tutorial/Packaging an Installer.rst
View File

@ -1,4 +1,4 @@
Step 7: Packaging an Installer
Step 9: Packaging an Installer
==============================
Next suppose that we want to distribute our project to other people so that
@ -11,7 +11,7 @@ installations and package management features. To accomplish this we will use
CPack to create platform specific installers. Specifically we need to add a
few lines to the bottom of our top-level ``CMakeLists.txt`` file.
.. literalinclude:: Step8/CMakeLists.txt
.. literalinclude:: Step10/CMakeLists.txt
:caption: CMakeLists.txt
:name: CMakeLists.txt-include-CPack
:language: cmake
@ -38,15 +38,15 @@ binary directory run:
cpack
To specify the generator, use the ``-G`` option. For multi-config builds, use
``-C`` to specify the configuration. For example:
To specify the generator, use the :option:`-G <cpack -G>` option. For multi-config builds,
use :option:`-C <cpack -C>` to specify the configuration. For example:
.. code-block:: console
cpack -G ZIP -C Debug
For a list of available generators, see :manual:`cpack-generators(7)` or call
``cpack --help``. An :cpack_gen:`archive generator <CPack Archive Generator>`
:option:`cpack --help`. An :cpack_gen:`archive generator <CPack Archive Generator>`
like ZIP creates a compressed archive of all *installed* files.
To create an archive of the *full* source tree you would type:

14
Help/guide/tutorial/Selecting Static or Shared Libraries.rst
View File

@ -1,5 +1,5 @@
Step 9: Selecting Static or Shared Libraries
============================================
Step 10: Selecting Static or Shared Libraries
=============================================
In this section we will show how the :variable:`BUILD_SHARED_LIBS` variable can
be used to control the default behavior of :command:`add_library`,
@ -19,7 +19,7 @@ library.
The first step is to update the starting section of the top-level
``CMakeLists.txt`` to look like:
.. literalinclude:: Step10/CMakeLists.txt
.. literalinclude:: Step11/CMakeLists.txt
:caption: CMakeLists.txt
:name: CMakeLists.txt-option-BUILD_SHARED_LIBS
:language: cmake
@ -33,7 +33,7 @@ explicitly require that SqrtLibrary is built statically.
The end result is that ``MathFunctions/CMakeLists.txt`` should look like:
.. literalinclude:: Step10/MathFunctions/CMakeLists.txt
.. literalinclude:: Step11/MathFunctions/CMakeLists.txt
:caption: MathFunctions/CMakeLists.txt
:name: MathFunctions/CMakeLists.txt-add_library-STATIC
:language: cmake
@ -42,7 +42,7 @@ The end result is that ``MathFunctions/CMakeLists.txt`` should look like:
Next, update ``MathFunctions/mysqrt.cxx`` to use the ``mathfunctions`` and
``detail`` namespaces:
.. literalinclude:: Step10/MathFunctions/mysqrt.cxx
.. literalinclude:: Step11/MathFunctions/mysqrt.cxx
:caption: MathFunctions/mysqrt.cxx
:name: MathFunctions/mysqrt.cxx-namespace
:language: c++
@ -56,7 +56,7 @@ uses ``USE_MYMATH``:
Finally, update ``MathFunctions/MathFunctions.h`` to use dll export defines:
.. literalinclude:: Step10/MathFunctions/MathFunctions.h
.. literalinclude:: Step11/MathFunctions/MathFunctions.h
:caption: MathFunctions/MathFunctions.h
:name: MathFunctions/MathFunctions.h
:language: c++
@ -67,7 +67,7 @@ library that has position independent code. The solution to this is to
explicitly set the :prop_tgt:`POSITION_INDEPENDENT_CODE` target property of
SqrtLibrary to be ``True`` no matter the build type.
.. literalinclude:: Step10/MathFunctions/CMakeLists.txt
.. literalinclude:: Step11/MathFunctions/CMakeLists.txt
:caption: MathFunctions/CMakeLists.txt
:name: MathFunctions/CMakeLists.txt-POSITION_INDEPENDENT_CODE
:language: cmake

16
Help/guide/tutorial/Step1/CMakeLists.txt Normal file
View File

@ -0,0 +1,16 @@
# TODO 1: Set the minimum required version of CMake to be 3.10
# TODO 2: Create a project named Tutorial
# TODO 7: Set the project version number as 1.0 in the above project command
# TODO 6: Set the variable CMAKE_CXX_STANDARD to 11
# and the variable CMAKE_CXX_STANDARD_REQUIRED to True
# TODO 8: Use configure_file to configure and copy TutorialConfig.h.in to
# TutorialConfig.h
# TODO 3: Add an executable called Tutorial to the project
# Hint: Be sure to specify the source file as tutorial.cxx
# TODO 9: Use target_include_directories to include ${PROJECT_BINARY_DIR}

2
Help/guide/tutorial/Step1/TutorialConfig.h.in Normal file
View File

@ -0,0 +1,2 @@
// the configured options and settings for Tutorial
// TODO 10: Define Tutorial_VERSION_MAJOR and Tutorial_VERSION_MINOR

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