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

Update upstream source from tag 'upstream/3.18.2'

Browse Source 
Update to upstream version '3.18.2'
with Debian dir fe8c3f89d2d31a5823bb0f32afa80544b0b9fce0
This commit is contained in:
Felix Geyer 2020-08-30 11:55:09 +02:00
commit 06be8a22a4
3731 changed files with 136749 additions and 194374 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
.clang-format
View File

@ -22,7 +22,9 @@ IncludeBlocks: Regroup
IncludeCategories:
- Regex: '^[<"]cmConfigure\.h'
Priority: -1
- Regex: '^(<|")cm/'
- Regex: '^<queue>'
Priority: 1
- Regex: '^(<|")cm(ext)?/'
Priority: 2
- Regex: '^(<|")windows\.h'
Priority: 3
@ -30,16 +32,18 @@ IncludeCategories:
Priority: 5
- Regex: '^(<|")Qt?[A-Z]'
Priority: 6
- Regex: '^(<|")cmsys/'
- Regex: '^<cmtp/'
Priority: 7
- Regex: '^(<|")cm_'
- Regex: '^(<|")cmsys/'
Priority: 8
- Regex: '^(<|")cm[A-Z][^.]+\.h'
- Regex: '^(<|")cm_'
Priority: 9
- Regex: '^(<|")cm[A-Z][^.]+\.h'
Priority: 10
- Regex: '^<[^.]+\.h'
Priority: 4
- Regex: '^<'
Priority: 1
- Regex: '.*'
Priority: 10
Priority: 11
...

2
.clang-tidy
View File

@ -13,9 +13,11 @@ modernize-*,\
-modernize-avoid-c-arrays,\
-modernize-use-nodiscard,\
-modernize-use-noexcept,\
-modernize-use-trailing-return-type,\
-modernize-use-transparent-functors,\
performance-*,\
readability-*,\
-readability-convert-member-functions-to-static,\
-readability-function-size,\
-readability-identifier-naming,\
-readability-implicit-bool-conversion,\

16
Auxiliary/CMakeLists.txt
View File

@ -1,4 +1,16 @@
install(DIRECTORY vim/indent vim/syntax DESTINATION ${CMAKE_DATA_DIR}/editors/vim)
install(FILES cmake-mode.el DESTINATION ${CMAKE_DATA_DIR}/editors/emacs)
# Install Vim files to a typical system integration directory.
# Packagers can set CMake_INSTALL_VIMFILES_DIR to control this.
if(NOT CMake_INSTALL_VIMFILES_DIR)
set(CMake_INSTALL_VIMFILES_DIR ${CMAKE_XDGDATA_DIR}/vim/vimfiles)
endif()
install(DIRECTORY vim/indent vim/syntax DESTINATION ${CMake_INSTALL_VIMFILES_DIR})
# Install Emacs files to a typical system integration directory.
# Packagers can set CMake_INSTALL_EMACS_DIR to control this.
if(NOT CMake_INSTALL_EMACS_DIR)
set(CMake_INSTALL_EMACS_DIR ${CMAKE_XDGDATA_DIR}/emacs/site-lisp)
endif()
install(FILES cmake-mode.el DESTINATION ${CMake_INSTALL_EMACS_DIR})
install(FILES cmake.m4 DESTINATION ${CMAKE_XDGDATA_DIR}/aclocal)
add_subdirectory (bash-completion)

29
Auxiliary/bash-completion/CMakeLists.txt
View File

@ -1,8 +1,21 @@
# Always install completion file in local dir
# in order to be sure to always be able to install
# in a local user directory rooted in a single directory.
# packager should either patch that out or
# add symlinks to the files in appropriate places
# /etc/bash_completion.d/
# DATADIR/completions (may be /usr/share/<package>/completions
install(FILES cmake cpack ctest DESTINATION ${CMAKE_DATA_DIR}/completions)
# We need to integrate into the system install, or this will silently fail to
# accomplish anything at all, and packagers won't even know it exists. Use the
# `<sharedir>/bash-completion/completions/` hierarchy by default, rooted in
# CMake's XDGDATA_DIR definition of the sharedir. This works with installation
# to `/usr` or `/usr/local` (or any prefix which bash-completion is configured
# with) as well as a simple installation by a local user into their home
# directory *if* the prefix is `$HOME/.local` since `.local/share/` is part of
# the bash-completion search path too.
# For more complex installations, packagers can set CMake_INSTALL_BASH_COMP_DIR
# to another system location.
if(NOT CMake_INSTALL_BASH_COMP_DIR)
if(CMAKE_BASH_COMP_DIR)
# Honor previous customization option.
set(CMake_INSTALL_BASH_COMP_DIR "${CMAKE_BASH_COMP_DIR}")
else()
# Default.
set(CMake_INSTALL_BASH_COMP_DIR ${CMAKE_XDGDATA_DIR}/bash-completion/completions)
endif()
endif()
install(FILES cmake cpack ctest DESTINATION ${CMake_INSTALL_BASH_COMP_DIR})

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

@ -101,6 +101,7 @@ syn keyword cmakeProperty contained
\ CLEAN_NO_CUSTOM
\ CMAKE_CONFIGURE_DEPENDS
\ CMAKE_CXX_KNOWN_FEATURES
\ CMAKE_CUDA_KNOWN_FEATURES
\ CMAKE_C_KNOWN_FEATURES
\ CMAKE_ROLE
\ COMMON_LANGUAGE_RUNTIME
@ -169,6 +170,7 @@ syn keyword cmakeProperty contained
\ FRAMEWORK_VERSION
\ Fortran_FORMAT
\ Fortran_MODULE_DIRECTORY
\ Fortran_PREPROCESS
\ GENERATED
\ GENERATOR_FILE_NAME
\ GENERATOR_IS_MULTI_CONFIG
@ -220,6 +222,7 @@ syn keyword cmakeProperty contained
\ JOB_POOLS
\ JOB_POOL_COMPILE
\ JOB_POOL_LINK
\ JOB_POOL_PRECOMPILE_HEADER
\ KEEP_EXTENSION
\ LABELS
\ LANGUAGE
@ -725,6 +728,7 @@ syn keyword cmakeVariable contained
\ CMAKE_CUDA_COMPILER_AR
\ CMAKE_CUDA_COMPILER_ARCHITECTURE_ID
\ CMAKE_CUDA_COMPILER_EXTERNAL_TOOLCHAIN
\ CMAKE_CUDA_COMPILE_FEATURES
\ CMAKE_CUDA_COMPILER_ID
\ CMAKE_CUDA_COMPILER_LAUNCHER
\ CMAKE_CUDA_COMPILER_LOADED
@ -1016,6 +1020,7 @@ syn keyword cmakeVariable contained
\ CMAKE_Fortran_MODULE_DIRECTORY
\ CMAKE_Fortran_OUTPUT_EXTENSION
\ CMAKE_Fortran_PLATFORM_ID
\ CMAKE_Fortran_PREPROCESS
\ CMAKE_Fortran_SIMULATE_ID
\ CMAKE_Fortran_SIMULATE_VERSION
\ CMAKE_Fortran_SIZEOF_DATA_PTR
@ -1064,6 +1069,7 @@ syn keyword cmakeVariable contained
\ CMAKE_JOB_POOLS
\ CMAKE_JOB_POOL_COMPILE
\ CMAKE_JOB_POOL_LINK
\ CMAKE_JOB_POOL_PRECOMPILE_HEADER
\ CMAKE_Java
\ CMAKE_Java_ANDROID_TOOLCHAIN_MACHINE
\ CMAKE_Java_ANDROID_TOOLCHAIN_PREFIX
@ -2862,6 +2868,11 @@ syn keyword cmakeKWtarget_link_options contained
\ _LINKER_WRAPPER_FLAG
\ _LINKER_WRAPPER_FLAG_SEP
syn keyword cmakeKWtarget_precompile_headers contained
\ INTERFACE
\ PRIVATE
\ PUBLIC
syn keyword cmakeKWtarget_sources contained
\ ALIAS
\ IMPORTED
@ -3166,6 +3177,7 @@ syn keyword cmakeCommand
\ target_link_directories
\ target_link_libraries
\ target_link_options
\ target_precompile_headers
\ target_sources
\ try_compile
\ try_run
@ -3322,6 +3334,7 @@ hi def link cmakeKWtarget_include_directories ModeMsg
hi def link cmakeKWtarget_link_directories ModeMsg
hi def link cmakeKWtarget_link_libraries ModeMsg
hi def link cmakeKWtarget_link_options ModeMsg
hi def link cmakeKWtarget_precompile_headers ModeMsg
hi def link cmakeKWtarget_sources ModeMsg
hi def link cmakeKWtry_compile ModeMsg
hi def link cmakeKWtry_run ModeMsg

127
CMakeLists.txt
View File

@ -37,7 +37,7 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
if(CMAKE_SYSTEM_NAME STREQUAL "HP-UX")
message(FATAL_ERROR
"CMake no longer compiles on HP-UX. See\n"
" https://gitlab.kitware.com/cmake/cmake/issues/17137\n"
" https://gitlab.kitware.com/cmake/cmake/-/issues/17137\n"
"Use CMake 3.9 or lower instead."
)
endif()
@ -154,7 +154,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 ZLIB ZSTD)
set(UTILITIES BZIP2 CURL EXPAT FORM JSONCPP LIBARCHIVE LIBLZMA LIBRHASH LIBUV NGHTTP2 ZLIB ZSTD)
foreach(util ${UTILITIES})
if(NOT DEFINED CMAKE_USE_SYSTEM_LIBRARY_${util}
AND DEFINED CMAKE_USE_SYSTEM_LIBRARIES)
@ -192,6 +192,8 @@ macro(CMAKE_HANDLE_SYSTEM_LIBRARIES)
"${CMAKE_USE_SYSTEM_LIBRARY_ZSTD}" "NOT CMAKE_USE_SYSTEM_LIBARCHIVE" ON)
CMAKE_DEPENDENT_OPTION(CMAKE_USE_SYSTEM_LIBLZMA "Use system-installed liblzma"
"${CMAKE_USE_SYSTEM_LIBRARY_LIBLZMA}" "NOT CMAKE_USE_SYSTEM_LIBARCHIVE" ON)
CMAKE_DEPENDENT_OPTION(CMAKE_USE_SYSTEM_NGHTTP2 "Use system-installed nghttp2"
"${CMAKE_USE_SYSTEM_LIBRARY_NGHTTP2}" "NOT CMAKE_USE_SYSTEM_CURL" ON)
option(CMAKE_USE_SYSTEM_FORM "Use system-installed libform" "${CMAKE_USE_SYSTEM_LIBRARY_FORM}")
option(CMAKE_USE_SYSTEM_JSONCPP "Use system-installed jsoncpp" "${CMAKE_USE_SYSTEM_LIBRARY_JSONCPP}")
option(CMAKE_USE_SYSTEM_LIBRHASH "Use system-installed librhash" "${CMAKE_USE_SYSTEM_LIBRARY_LIBRHASH}")
@ -264,7 +266,6 @@ macro(CMAKE_SETUP_TESTING)
${CMake_BINARY_DIR}/Testing/HTML/TestingResults/Icons/Logo.gif COPYONLY)
endif()
mark_as_advanced(DART_ROOT)
mark_as_advanced(CURL_TESTING)
endmacro()
@ -336,6 +337,9 @@ endmacro()
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)
@ -352,6 +356,21 @@ macro (CMAKE_BUILD_UTILITIES)
if(CMake_NO_CXX_STANDARD)
set(KWSYS_CXX_STANDARD "")
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}")
@ -368,17 +387,20 @@ macro (CMAKE_BUILD_UTILITIES)
# Setup third-party libraries.
# Everything in the tree should be able to include files from the
# Utilities directory.
if (CMAKE_SYSTEM_NAME STREQUAL "AIX" AND CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
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
${CMake_SOURCE_DIR}/Utilities
)
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.
@ -431,6 +453,13 @@ macro (CMAKE_BUILD_UTILITIES)
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()
@ -466,9 +495,19 @@ macro (CMAKE_BUILD_UTILITIES)
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()
#---------------------------------------------------------------------
@ -497,6 +536,11 @@ macro (CMAKE_BUILD_UTILITIES)
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()
@ -548,21 +592,25 @@ macro (CMAKE_BUILD_UTILITIES)
set(ZLIB_INCLUDE_DIR ${CMAKE_ZLIB_INCLUDES})
set(ZLIB_LIBRARY ${CMAKE_ZLIB_LIBRARIES})
add_definitions(-DLIBARCHIVE_STATIC)
set(ENABLE_MBEDTLS OFF CACHE INTERNAL "Enable use of mbed TLS")
set(ENABLE_NETTLE OFF CACHE INTERNAL "Enable use of Nettle")
set(ENABLE_OPENSSL ${CMAKE_USE_OPENSSL} CACHE INTERNAL "Enable use of OpenSSL")
set(ENABLE_LIBB2 OFF CACHE INTERNAL "Enable the use of the system LIBB2 library if found")
set(ENABLE_LZMA ON CACHE INTERNAL "Enable the use of the system LZMA library if found")
set(ENABLE_LZ4 OFF CACHE INTERNAL "Enable the use of the system LZ4 library if found")
set(ENABLE_LZO OFF CACHE INTERNAL "Enable the use of the system LZO library if found")
set(ENABLE_ZLIB ON CACHE INTERNAL "Enable the use of the system ZLIB library if found")
set(ENABLE_BZip2 ON CACHE INTERNAL "Enable the use of the system BZip2 library if found")
set(ENABLE_ZSTD ON CACHE INTERNAL "Enable the use of the system zstd library if found")
set(ENABLE_LIBXML2 OFF CACHE INTERNAL "Enable the use of the system libxml2 library if found")
set(ENABLE_EXPAT ON CACHE INTERNAL "Enable the use of the system EXPAT library if found")
set(ENABLE_EXPAT OFF CACHE INTERNAL "Enable the use of the system EXPAT library if found")
set(ENABLE_PCREPOSIX OFF CACHE INTERNAL "Enable the use of the system PCREPOSIX library if found")
set(ENABLE_LibGCC OFF CACHE INTERNAL "Enable the use of the system LibGCC library if found")
set(ENABLE_XATTR OFF CACHE INTERNAL "Enable extended attribute support")
set(ENABLE_ACL OFF CACHE INTERNAL "Enable ACL support")
set(ENABLE_ICONV OFF CACHE INTERNAL "Enable iconv support")
set(ENABLE_CNG OFF CACHE INTERNAL "Enable the use of CNG(Crypto Next Generation)")
SET(POSIX_REGEX_LIB "" CACHE INTERNAL "Choose what library should provide POSIX regular expression support")
add_subdirectory(Utilities/cmlibarchive)
CMAKE_SET_TARGET_FOLDER(cmlibarchive "Utilities/3rdParty")
set(CMAKE_TAR_LIBRARIES cmlibarchive ${BZIP2_LIBRARIES})
@ -671,10 +719,6 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
set(LIBRARY_OUTPUT_PATH "" CACHE INTERNAL
"Where to put the libraries for CMake")
# The CMake executables usually do not need any rpath to run in the build or
# install tree.
set(CMAKE_SKIP_RPATH ON CACHE INTERNAL "CMake does not need RPATHs.")
# Load install destinations.
include(Source/CMakeInstallDestinations.cmake)
@ -682,10 +726,15 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
include(${CMake_SOURCE_DIR}/Tests/CMakeInstall.cmake)
endif()
# no clue why we are testing for this here
include(CheckSymbolExists)
CHECK_SYMBOL_EXISTS(unsetenv "stdlib.h" HAVE_UNSETENV)
CHECK_SYMBOL_EXISTS(environ "stdlib.h" HAVE_ENVIRON_NOT_REQUIRE_PROTOTYPE)
# Checks for cmSystemTools.
if(WIN32)
set(HAVE_UNSETENV 0)
set(HAVE_ENVIRON_NOT_REQUIRE_PROTOTYPE 1)
else()
include(CheckSymbolExists)
CHECK_SYMBOL_EXISTS(unsetenv "stdlib.h" HAVE_UNSETENV)
CHECK_SYMBOL_EXISTS(environ "stdlib.h" HAVE_ENVIRON_NOT_REQUIRE_PROTOTYPE)
endif()
endif()
# CMAKE_TESTS_CDASH_SERVER: CDash server used by CMake/Tests.
@ -714,19 +763,6 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
# build the utilities (a macro defined in this file)
CMAKE_BUILD_UTILITIES()
# On NetBSD ncurses is required, since curses doesn't have the wsyncup()
# function. ncurses is installed via pkgsrc, so the library is in /usr/pkg/lib,
# which isn't in the default linker search path. So without RPATH ccmake
# doesn't run and the build doesn't succeed since ccmake is executed for
# generating the documentation.
if(BUILD_CursesDialog)
get_filename_component(_CURSES_DIR "${CURSES_LIBRARY}" PATH)
set(CURSES_NEED_RPATH FALSE)
if(NOT "${_CURSES_DIR}" STREQUAL "/lib" AND NOT "${_CURSES_DIR}" STREQUAL "/usr/lib" AND NOT "${_CURSES_DIR}" STREQUAL "/lib64" AND NOT "${_CURSES_DIR}" STREQUAL "/usr/lib64")
set(CURSES_NEED_RPATH TRUE)
endif()
endif()
if(BUILD_QtDialog)
if(APPLE)
set(CMAKE_BUNDLE_VERSION
@ -739,28 +775,15 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
set(CMAKE_INSTALL_PREFIX
"${CMAKE_INSTALL_PREFIX}CMake.app/Contents")
endif()
set(QT_NEED_RPATH FALSE)
if(NOT "${QT_LIBRARY_DIR}" STREQUAL "/lib" AND NOT "${QT_LIBRARY_DIR}" STREQUAL "/usr/lib" AND NOT "${QT_LIBRARY_DIR}" STREQUAL "/lib64" AND NOT "${QT_LIBRARY_DIR}" STREQUAL "/usr/lib64")
set(QT_NEED_RPATH TRUE)
endif()
endif()
# The same might be true on other systems for other libraries.
# Then only enable RPATH if we have are building at least with cmake 2.4,
# since this one has much better RPATH features than cmake 2.2.
# The executables are then built with the RPATH for the libraries outside
# the build tree, which is both the build and the install RPATH.
if (UNIX)
if( CMAKE_USE_SYSTEM_CURL OR CMAKE_USE_SYSTEM_ZLIB
OR CMAKE_USE_SYSTEM_EXPAT OR CURSES_NEED_RPATH OR QT_NEED_RPATH)
set(CMAKE_SKIP_RPATH OFF CACHE INTERNAL "CMake built with RPATH.")
set(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE)
set(CMAKE_BUILD_WITH_INSTALL_RPATH TRUE)
endif()
endif ()
if(UNIX)
# Install executables with the RPATH set for libraries outside the build tree.
# This is also suitable for binaries in the build tree. Avoid re-link on install.
set(CMAKE_INSTALL_RPATH_USE_LINK_PATH ON CACHE BOOL "Install with RPATH set to find custom-built libraries.")
set(CMAKE_BUILD_WITH_INSTALL_RPATH ON CACHE BOOL "Build with RPATH set to match install-tree RPATH.")
mark_as_advanced(CMAKE_INSTALL_RPATH_USE_LINK_PATH CMAKE_BUILD_WITH_INSTALL_RPATH)
endif()
# add the uninstall support
configure_file(
@ -841,6 +864,10 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
PATTERN "*.sh*" PERMISSIONS OWNER_READ OWNER_EXECUTE OWNER_WRITE
GROUP_READ GROUP_EXECUTE
WORLD_READ WORLD_EXECUTE
REGEX "/(ExportImportList|cpp)$"
PERMISSIONS OWNER_READ OWNER_EXECUTE OWNER_WRITE
GROUP_READ GROUP_EXECUTE
WORLD_READ WORLD_EXECUTE
REGEX "Help/(dev|guide)($|/)" EXCLUDE
)

4
CONTRIBUTING.rst
View File

@ -11,11 +11,11 @@ Community
CMake is maintained and supported by `Kitware`_ and developed in
collaboration with a productive community of contributors.
Please subscribe and post to the `CMake Developers List`_ to raise
Please post to the ``Development`` category of the `CMake Forum`_ to raise
discussion of development topics.
.. _`Kitware`: http://www.kitware.com/cmake
.. _`CMake Developers List`: https://cmake.org/mailman/listinfo/cmake-developers
.. _`CMake Forum`: https://discourse.cmake.org
Patches
=======

2
CTestConfig.cmake
View File

@ -1,6 +1,8 @@
# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
# file Copyright.txt or https://cmake.org/licensing for details.
# If changing this file, also update Utilities/Sphinx/CTestConfig.cmake
set(CTEST_PROJECT_NAME "CMake")
set(CTEST_NIGHTLY_START_TIME "1:00:00 UTC")

8
CTestCustom.cmake.in
View File

@ -11,6 +11,7 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
"warning: \\(Long double usage is reported only once for each file"
"warning: To disable this warning use"
"could not be inlined"
"libcmexpat.*has no symbols"
"libcmcurl.*has no symbols"
"not sorted slower link editing will result"
"stl_deque.h:479"
@ -64,6 +65,7 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
"ld: warning .*/libgcc.a archive's cputype"
"ld: warning: ignoring file .*/libgcc.a, file was built for archive which is not the architecture being linked"
"ld: warning: in .*/libgcc.a, file is not of required architecture"
"ld: warning: symbol .(deflate|inflate)_copyright. has differing sizes" # system libz and QtCore disagree
"warning.*This version of Mac OS X is unsupported"
"clang.*: warning: argument unused during compilation: .-g"
"note: in expansion of macro" # diagnostic context note
@ -72,6 +74,7 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
"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
"IPA warning: function.*multiply defined in"
"LICENSE WARNING" # PGI license expiry. Not useful in nightly testing.
# Ignore compiler summary warning, assuming prior text has matched some
# other warning expression:
@ -79,7 +82,7 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
"compilation completed with warnings" # PGI
"[0-9]+ Warning\\(s\\) detected" # SunPro
# scanbuild exceptions
# scanbuild exceptions
"char_traits.h:.*: warning: Null pointer argument in call to string length function"
"stl_construct.h:.*: warning: Forming reference to null pointer"
".*stl_uninitialized.h:75:19: warning: Forming reference to null pointer.*"
@ -98,6 +101,9 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
"liblzma/common/index_encoder.c:[0-9]+:[0-9]+: warning: Value stored to .* during its initialization is never read"
"libuv/src/.*:[0-9]+:[0-9]+: warning: Dereference of null pointer"
"libuv/src/.*:[0-9]+:[0-9]+: warning: The left operand of '==' is a garbage value"
"libuv/src/.*:[0-9]+:[0-9]+: warning: 1st function call argument is an uninitialized value"
"nghttp2/lib/.*:[0-9]+:[0-9]+: warning: Dereference of null pointer"
"nghttp2/lib/.*:[0-9]+:[0-9]+: warning: Value stored to .* is never read"
)
if(NOT "@CMAKE_GENERATOR@" MATCHES "Xcode")

3
Copyright.txt
View File

@ -1,5 +1,5 @@
CMake - Cross Platform Makefile Generator
Copyright 2000-2019 Kitware, Inc. and Contributors
Copyright 2000-2020 Kitware, Inc. and Contributors
All rights reserved.
Redistribution and use in source and binary forms, with or without
@ -99,6 +99,7 @@ The following individuals and institutions are among the Contributors:
* Sebastian Holtermann <sebholt@xwmw.org>
* Stephen Kelly <steveire@gmail.com>
* Sylvain Joubert <joubert.sy@gmail.com>
* The Qt Company Ltd.
* Thomas Sondergaard <ts@medical-insight.com>
* Tobias Hunger <tobias.hunger@qt.io>
* Todd Gamblin <tgamblin@llnl.gov>

11
Help/command/DEVICE_LINK_OPTIONS.txt Normal file
View File

@ -0,0 +1,11 @@
When a device link step is involved, which is controlled by
:prop_tgt:`CUDA_SEPARABLE_COMPILATION` and
:prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties and policy :policy:`CMP0105`,
the raw options will be delivered to the host and device link steps (wrapped in
``-Xcompiler`` or equivalent for device link). Options wrapped with
``$<DEVICE_LINK:...>``
:manual:`generator expression <cmake-generator-expressions(7)>` will be used
only for the device link step. Options wrapped with ``$<HOST_LINK:...>``
:manual:`generator expression <cmake-generator-expressions(7)>` will be used
only for the host link step.

13
Help/command/FIND_XXX.txt
View File

@ -15,6 +15,7 @@ The general signature is:
[PATHS path1 [path2 ... ENV var]]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[DOC "cache documentation string"]
[REQUIRED]
[NO_DEFAULT_PATH]
[NO_PACKAGE_ROOT_PATH]
[NO_CMAKE_PATH]
@ -31,8 +32,9 @@ A cache entry named by ``<VAR>`` is created to store the result
of this command.
If the |SEARCH_XXX| is found the result is stored in the variable
and the search will not be repeated unless the variable is cleared.
If nothing is found, the result will be
``<VAR>-NOTFOUND``, and the search will be attempted again the
If nothing is found, the result will be ``<VAR>-NOTFOUND``.
The ``REQUIRED`` option stops processing with an error message if nothing
is found, otherwise the search will be attempted again the
next time |FIND_XXX| is invoked with the same variable.
Options include:
@ -57,6 +59,9 @@ Options include:
``DOC``
Specify the documentation string for the ``<VAR>`` cache entry.
``REQUIRED``
Stop processing with an error message if nothing is found.
If ``NO_DEFAULT_PATH`` is specified, then no additional paths are
added to the search.
If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
@ -138,6 +143,10 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
* |CMAKE_SYSTEM_XXX_PATH|
* |CMAKE_SYSTEM_XXX_MAC_PATH|
The platform paths that these variables contain are locations that
typically include installed software. An example being ``/usr/local`` for
UNIX based platforms.
7. Search the paths specified by the PATHS option
or in the short-hand version of the command.
These are typically hard-coded guesses.

10
Help/command/add_compile_definitions.rst
View File

@ -7,10 +7,12 @@ Add preprocessor definitions to the compilation of source files.
add_compile_definitions(<definition> ...)
Adds preprocessor definitions to the compiler command line for targets in the
current directory and below (whether added before or after this command is
invoked). See documentation of the :prop_dir:`directory <COMPILE_DEFINITIONS>`
and :prop_tgt:`target <COMPILE_DEFINITIONS>` ``COMPILE_DEFINITIONS`` properties.
Adds preprocessor definitions to the compiler command line.
The preprocessor definitions are added to the :prop_dir:`COMPILE_DEFINITIONS`
directory property for the current ``CMakeLists`` file. They are also added to
the :prop_tgt:`COMPILE_DEFINITIONS` target property for each target in the
current ``CMakeLists`` file.
Definitions are specified using the syntax ``VAR`` or ``VAR=value``.
Function-style definitions are not supported. CMake will automatically

3
Help/command/add_compile_options.rst
View File

@ -46,3 +46,6 @@ to use the more specific commands :command:`add_compile_definitions`
and :command:`include_directories`.
The command :command:`target_compile_options` adds target-specific options.
The source file property :prop_sf:`COMPILE_OPTIONS` adds options to one
source file.

47
Help/command/add_custom_command.rst
View File

@ -68,6 +68,9 @@ The options are:
order-only dependencies to ensure the byproducts will be
available before their dependents build.
The :ref:`Makefile Generators` will remove ``BYPRODUCTS`` and other
:prop_sf:`GENERATED` files during ``make clean``.
``COMMAND``
Specify the command-line(s) to execute at build time.
If more than one ``COMMAND`` is specified they will be executed in order,
@ -112,24 +115,42 @@ The options are:
build time.
``DEPENDS``
Specify files on which the command depends. If any dependency is
an ``OUTPUT`` of another custom command in the same directory
(``CMakeLists.txt`` file) CMake automatically brings the other
Specify files on which the command depends. Each argument is converted
to a dependency as follows:
1. If the argument is the name of a target (created by the
:command:`add_custom_target`, :command:`add_executable`, or
:command:`add_library` command) a target-level dependency is
created to make sure the target is built before any target
using this custom command. Additionally, if the target is an
executable or library, a file-level dependency is created to
cause the custom command to re-run whenever the target is
recompiled.
2. If the argument is an absolute path, a file-level dependency
is created on that path.
3. If the argument is the name of a source file that has been
added to a target or on which a source file property has been set,
a file-level dependency is created on that source file.
4. If the argument is a relative path and it exists in the current
source directory, a file-level dependency is created on that
file in the current source directory.
5. Otherwise, a file-level dependency is created on that path relative
to the current binary directory.
If any dependency is an ``OUTPUT`` of another custom command in the same
directory (``CMakeLists.txt`` file), CMake automatically brings the other
custom command into the target in which this command is built.
A target-level dependency is added if any dependency is listed as
``BYPRODUCTS`` of a target or any of its build events in the same
directory to ensure the byproducts will be available.
If ``DEPENDS`` is not specified the command will run whenever
If ``DEPENDS`` is not specified, the command will run whenever
the ``OUTPUT`` is missing; if the command does not actually
create the ``OUTPUT`` then the rule will always run.
If ``DEPENDS`` specifies any target (created by the
:command:`add_custom_target`, :command:`add_executable`, or
:command:`add_library` command) a target-level dependency is
created to make sure the target is built before any target
using this custom command. Additionally, if the target is an
executable or library a file-level dependency is created to
cause the custom command to re-run whenever the target is
recompiled.
create the ``OUTPUT``, the rule will always run.
Arguments to ``DEPENDS`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.

3
Help/command/add_custom_target.rst
View File

@ -49,6 +49,9 @@ The options are:
order-only dependencies to ensure the byproducts will be
available before their dependents build.
The :ref:`Makefile Generators` will remove ``BYPRODUCTS`` and other
:prop_sf:`GENERATED` files during ``make clean``.
``COMMAND``
Specify the command-line(s) to execute at build time.
If more than one ``COMMAND`` is specified they will be executed in order,

6
Help/command/add_definitions.rst
View File

@ -8,9 +8,9 @@ Add -D define flags to the compilation of source files.
add_definitions(-DFOO -DBAR ...)
Adds definitions to the compiler command line for targets in the current
directory and below (whether added before or after this command is invoked).
This command can be used to add any flags, but it is intended to add
preprocessor definitions.
directory, whether added before or after this command is invoked, and for
the ones in sub-directories added after. This command can be used to add any
flags, but it is intended to add preprocessor definitions.
.. note::

22
Help/command/add_executable.rst
View File

@ -1,8 +1,15 @@
add_executable
--------------
.. only:: html
.. contents::
Add an executable to the project using the specified source files.
Normal Executables
^^^^^^^^^^^^^^^^^^
.. code-block:: cmake
add_executable(<name> [WIN32] [MACOSX_BUNDLE]
@ -45,7 +52,8 @@ See also :prop_sf:`HEADER_FILE_ONLY` on what to do if some sources are
pre-processed, and you want to have the original sources reachable from
within IDE.
--------------------------------------------------------------------------
Imported Executables
^^^^^^^^^^^^^^^^^^^^
.. code-block:: cmake
@ -65,7 +73,8 @@ whose names begin in ``IMPORTED_``. The most important such property is
the main executable file on disk. See documentation of the ``IMPORTED_*``
properties for more information.
--------------------------------------------------------------------------
Alias Executables
^^^^^^^^^^^^^^^^^
.. code-block:: cmake
@ -74,8 +83,13 @@ properties for more information.
Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can
be used to refer to ``<target>`` in subsequent commands. The ``<name>``
does not appear in the generated buildsystem as a make target. The
``<target>`` may not be a non-``GLOBAL``
:ref:`Imported Target <Imported Targets>` or an ``ALIAS``.
``<target>`` may not be an ``ALIAS``.
An ``ALIAS`` to a non-``GLOBAL`` :ref:`Imported Target <Imported Targets>`
has scope in the directory in which the alias is created and below.
The :prop_tgt:`ALIAS_GLOBAL` target property can be used to check if the
alias is global or not.
``ALIAS`` targets can be used as targets to read properties
from, executables for custom commands and custom targets. They can also be
tested for existence with the regular :command:`if(TARGET)` subcommand.

9
Help/command/add_library.rst
View File

@ -139,8 +139,13 @@ Alias Libraries
Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be
used to refer to ``<target>`` in subsequent commands. The ``<name>`` does
not appear in the generated buildsystem as a make target. The ``<target>``
may not be a non-``GLOBAL`` :ref:`Imported Target <Imported Targets>` or an
``ALIAS``.
may not be an ``ALIAS``.
An ``ALIAS`` to a non-``GLOBAL`` :ref:`Imported Target <Imported Targets>`
has scope in the directory in which the alias is created and below.
The :prop_tgt:`ALIAS_GLOBAL` target property can be used to check if the
alias is global or not.
``ALIAS`` targets can be used as linkable targets and as targets to
read properties from. They can also be tested for existence with the
regular :command:`if(TARGET)` subcommand. The ``<name>`` may not be used

2
Help/command/add_link_options.rst
View File

@ -26,6 +26,8 @@ the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.
.. include:: DEVICE_LINK_OPTIONS.txt
.. include:: OPTIONS_SHELL.txt
.. include:: LINK_OPTIONS_LINKER.txt

99
Help/command/cmake_language.rst Normal file
View File

@ -0,0 +1,99 @@
cmake_language
--------------
Call meta-operations on CMake commands.
Synopsis
^^^^^^^^
.. parsed-literal::
cmake_language(`CALL`_ <command> [<args>...])
cmake_language(`EVAL`_ CODE <code>...)
Introduction
^^^^^^^^^^^^
This command will call meta-operations on built-in CMake commands or
those created via the :command:`macro` or :command:`function` commands.
``cmake_language`` does not introduce a new variable or policy scope.
Calling Commands
^^^^^^^^^^^^^^^^
.. _CALL:
.. code-block:: cmake
cmake_language(CALL <command> [<args>...])
Calls the named ``<command>`` with the given arguments (if any).
For example, the code:
.. code-block:: cmake
set(message_command "message")
cmake_language(CALL ${message_command} STATUS "Hello World!")
is equivalent to
.. code-block:: cmake
message(STATUS "Hello World!")
.. note::
To ensure consistency of the code, the following commands are not allowed:
* ``if`` / ``elseif`` / ``else`` / ``endif``
* ``while`` / ``endwhile``
* ``foreach`` / ``endforeach``
* ``function`` / ``endfunction``
* ``macro`` / ``endmacro``
Evaluating Code
^^^^^^^^^^^^^^^
.. _EVAL:
.. code-block:: cmake
cmake_language(EVAL CODE <code>...)
Evaluates the ``<code>...`` as CMake code.
For example, the code:
.. code-block:: cmake
set(A TRUE)
set(B TRUE)
set(C TRUE)
set(condition "(A AND B) OR C")
cmake_language(EVAL CODE "
if (${condition})
message(STATUS TRUE)
else()
message(STATUS FALSE)
endif()"
)
is equivalent to
.. code-block:: cmake
set(A TRUE)
set(B TRUE)
set(C TRUE)
set(condition "(A AND B) OR C")
file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake "
if (${condition})
message(STATUS TRUE)
else()
message(STATUS FALSE)
endif()"
)
include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake)

24
Help/command/ctest_test.rst
View File

@ -20,9 +20,11 @@ Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`.
[RESOURCE_SPEC_FILE <file>]
[TEST_LOAD <threshold>]
[SCHEDULE_RANDOM <ON|OFF>]
[STOP_ON_FAILURE]
[STOP_TIME <time-of-day>]
[RETURN_VALUE <result-var>]
[CAPTURE_CMAKE_ERROR <result-var>]
[REPEAT <mode>:<n>]
[QUIET]
)
@ -95,10 +97,32 @@ The options are:
and then the ``--test-load`` command-line argument to :manual:`ctest(1)`.
See also the ``TestLoad`` setting in the :ref:`CTest Test Step`.
``REPEAT <mode>:<n>``
Run tests repeatedly based on the given ``<mode>`` up to ``<n>`` times.
The modes are:
``UNTIL_FAIL``
Require each test to run ``<n>`` times without failing in order to pass.
This is useful in finding sporadic failures in test cases.
``UNTIL_PASS``
Allow each test to run up to ``<n>`` times in order to pass.
Repeats tests if they fail for any reason.
This is useful in tolerating sporadic failures in test cases.
``AFTER_TIMEOUT``
Allow each test to run up to ``<n>`` times in order to pass.
Repeats tests only if they timeout.
This is useful in tolerating sporadic timeouts in test cases
on busy machines.
``SCHEDULE_RANDOM <ON|OFF>``
Launch tests in a random order. This may be useful for detecting
implicit test dependencies.
``STOP_ON_FAILURE``
Stop the execution of the tests once one has failed.
``STOP_TIME <time-of-day>``
Specify a time of day at which the tests should all stop running.

13
Help/command/execute_process.rst
View File

@ -21,7 +21,9 @@ Execute one or more child processes.
[COMMAND_ECHO <where>]
[OUTPUT_STRIP_TRAILING_WHITESPACE]
[ERROR_STRIP_TRAILING_WHITESPACE]
[ENCODING <name>])
[ENCODING <name>]
[ECHO_OUTPUT_VARIABLE]
[ECHO_ERROR_VARIABLE])
Runs the given sequence of one or more commands.
@ -105,6 +107,15 @@ Options:
for this encoding. In CMake 3.11.0, ``UTF-8`` was added for consistency with
the `UTF-8 RFC <https://www.ietf.org/rfc/rfc3629>`_ naming convention.
``ECHO_OUTPUT_VARIABLE``, ``ECHO_ERROR_VARIABLE``
The standard output or standard error will not be exclusively redirected to
the configured variables.
The output will be duplicated, it will be sent into the configured variables
and also on standard output or standard error.
This is analogous to the ``tee`` Unix command.
If more than one ``OUTPUT_*`` or ``ERROR_*`` option is given for the
same pipe the precedence is not specified.
If no ``OUTPUT_*`` or ``ERROR_*`` options are given the output will

145
Help/command/file.rst
View File

@ -19,6 +19,7 @@ Synopsis
file({`WRITE`_ | `APPEND`_} <filename> <content>...)
file({`TOUCH`_ | `TOUCH_NOCREATE`_} [<file>...])
file(`GENERATE`_ OUTPUT <output-file> [...])
file(`CONFIGURE`_ OUTPUT <output-file> CONTENT <content> [...])
`Filesystem`_
file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] [<globbing-expr>...])
@ -41,6 +42,10 @@ Synopsis
`Locking`_
file(`LOCK`_ <path> [...])
`Archiving`_
file(`ARCHIVE_CREATE`_ OUTPUT <archive> PATHS <paths>... [...])
file(`ARCHIVE_EXTRACT`_ INPUT <archive> [...])
Reading
^^^^^^^
@ -54,7 +59,9 @@ Reading
Read content from a file called ``<filename>`` and store it in a
``<variable>``. Optionally start from the given ``<offset>`` and
read at most ``<max-in>`` bytes. The ``HEX`` option causes data to
be converted to a hexadecimal representation (useful for binary data).
be converted to a hexadecimal representation (useful for binary data). If the
``HEX`` option is specified, letters in the output (``a`` through ``f``) are in
lowercase.
.. _STRINGS:
@ -243,8 +250,8 @@ be resolved. See below for a full description of how they work.
List of post-exclude regexes through which to filter the names of resolved
dependencies.
These arguments can be used to blacklist unwanted system libraries when
resolving the dependencies, or to whitelist libraries from a specific
These arguments can be used to exclude unwanted system libraries when
resolving the dependencies, or to include libraries from a specific
directory. The filtering works as follows:
1. If the not-yet-resolved dependency matches any of the
@ -395,8 +402,8 @@ dependency resolution:
Determines the path to the tool to use for dependency resolution. This is the
actual path to ``objdump``, ``dumpbin``, or ``otool``.
If this variable is not specified, it is determined automatically by system
introspection.
If this variable is not specified, it is determined by the value of
``CMAKE_OBJDUMP`` if set, else by system introspection.
Writing
^^^^^^^
@ -482,6 +489,44 @@ generation phase. The output file will not yet have been written when the
``file(GENERATE)`` command returns, it is written only after processing all
of a project's ``CMakeLists.txt`` files.
.. _CONFIGURE:
.. code-block:: cmake
file(CONFIGURE OUTPUT output-file
CONTENT content
[ESCAPE_QUOTES] [@ONLY]
[NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
Generate an output file using the input given by ``CONTENT`` and substitute
variable values referenced as ``@VAR@`` or ``${VAR}`` contained therein. The
substitution rules behave the same as the :command:`configure_file` command.
In order to match :command:`configure_file`'s behavior, generator expressions
are not supported for both ``OUTPUT`` and ``CONTENT``.
The arguments are:
``OUTPUT <output-file>``
Specify the output file name to generate. A relative path is treated with
respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
``<output-file>`` does not support generator expressions.
``CONTENT <content>``
Use the content given explicitly as input.
``<content>`` does not support generator expressions.
``ESCAPE_QUOTES``
Escape any substituted quotes with backslashes (C-style).
``@ONLY``
Restrict variable replacement to references of the form ``@VAR@``.
This is useful for configuring scripts that use ``${VAR}`` syntax.
``NEWLINE_STYLE <style>``
Specify the newline style for the output file. Specify
``UNIX`` or ``LF`` for ``\n`` newlines, or specify
``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines.
Filesystem
^^^^^^^^^^
@ -540,7 +585,7 @@ are only traversed if ``FOLLOW_SYMLINKS`` is given or policy
By default ``GLOB_RECURSE`` omits directories from result list - setting
``LIST_DIRECTORIES`` to true adds directories to result list.
If ``FOLLOW_SYMLINKS`` is given or policy :policy:`CMP0009` is not set to
``OLD`` then ``LIST_DIRECTORIES`` treats symlinks as directories.
``NEW`` then ``LIST_DIRECTORIES`` treats symlinks as directories.
Examples of recursive globbing include::
@ -790,6 +835,18 @@ Options to both ``DOWNLOAD`` and ``UPLOAD`` are:
If neither ``NETRC`` option is given CMake will check variables
``CMAKE_NETRC`` and ``CMAKE_NETRC_FILE``, respectively.
``TLS_VERIFY <ON|OFF>``
Specify whether to verify the server certificate for ``https://`` URLs.
The default is to *not* verify.
``TLS_CAINFO <file>``
Specify a custom Certificate Authority file for ``https://`` URLs.
For ``https://`` URLs CMake must be built with OpenSSL support. ``TLS/SSL``
certificates are not checked by default. Set ``TLS_VERIFY`` to ``ON`` to
check certificates. If neither ``TLS`` option is given CMake will check
variables ``CMAKE_TLS_VERIFY`` and ``CMAKE_TLS_CAINFO``, respectively.
Additional options to ``DOWNLOAD`` are:
``EXPECTED_HASH ALGO=<value>``
@ -801,19 +858,6 @@ Additional options to ``DOWNLOAD`` are:
``EXPECTED_MD5 <value>``
Historical short-hand for ``EXPECTED_HASH MD5=<value>``.
``TLS_VERIFY <ON|OFF>``
Specify whether to verify the server certificate for ``https://`` URLs.
The default is to *not* verify.
``TLS_CAINFO <file>``
Specify a custom Certificate Authority file for ``https://`` URLs.
For ``https://`` URLs CMake must be built with OpenSSL support. ``TLS/SSL``
certificates are not checked by default. Set ``TLS_VERIFY`` to ``ON`` to
check certificates and/or use ``EXPECTED_HASH`` to verify downloaded content.
If neither ``TLS`` option is given CMake will check variables
``CMAKE_TLS_VERIFY`` and ``CMAKE_TLS_CAINFO``, respectively.
Locking
^^^^^^^
@ -846,3 +890,66 @@ child directory or file.
Trying to lock file twice is not allowed. Any intermediate directories and
file itself will be created if they not exist. ``GUARD`` and ``TIMEOUT``
options ignored on ``RELEASE`` operation.
Archiving
^^^^^^^^^
.. _ARCHIVE_CREATE:
.. code-block:: cmake
file(ARCHIVE_CREATE OUTPUT <archive>
PATHS <paths>...
[FORMAT <format>]
[COMPRESSION <compression>]
[MTIME <mtime>]
[VERBOSE])
Creates the specified ``<archive>`` file with the files and directories
listed in ``<paths>``. Note that ``<paths>`` must list actual files or
directories, wildcards are not supported.
Use the ``FORMAT`` option to specify the archive format. Supported values
for ``<format>`` are ``7zip``, ``gnutar``, ``pax``, ``paxr``, ``raw`` and
``zip``. If ``FORMAT`` is not given, the default format is ``paxr``.
Some archive formats allow the type of compression to be specified.
The ``7zip`` and ``zip`` archive formats already imply a specific type of
compression. The other formats use no compression by default, but can be
directed to do so with the ``COMPRESSION`` option. Valid values for
``<compression>`` are ``None``, ``BZip2``, ``GZip``, ``XZ``, and ``Zstd``.
.. note::
With ``FORMAT`` set to ``raw`` only one file will be compressed with the
compression type specified by ``COMPRESSION``.
The ``VERBOSE`` option enables verbose output for the archive operation.
To specify the modification time recorded in tarball entries, use
the ``MTIME`` option.
.. _ARCHIVE_EXTRACT:
.. code-block:: cmake
file(ARCHIVE_EXTRACT INPUT <archive>
[DESTINATION <dir>]
[PATTERNS <patterns>...]
[LIST_ONLY]
[VERBOSE])
Extracts or lists the content of the specified ``<archive>``.
The directory where the content of the archive will be extracted to can
be specified using the ``DESTINATION`` option. If the directory does not
exist, it will be created. If ``DESTINATION`` is not given, the current
binary directory will be used.
If required, you may select which files and directories to list or extract
from the archive using the specified ``<patterns>``. Wildcards are supported.
If the ``PATTERNS`` option is not given, the entire archive will be listed or
extracted.
``LIST_ONLY`` will list the files in the archive rather than extract them.
With ``VERBOSE``, the command will produce verbose output.

36
Help/command/find_package.rst
View File

@ -59,7 +59,7 @@ for finding the package, checking the version, and producing any needed
messages. Some find-modules provide limited or no support for versioning;
check the module documentation.
If the ``MODULE`` option is not specfied in the above signature,
If the ``MODULE`` option is not specified in the above signature,
CMake first searches for the package using Module mode. Then, if the
package is not found, it searches again using Config mode. A user
may set the variable :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` to
@ -302,23 +302,23 @@ enabled.
are intended to be used on the command line with a ``-DVAR=value``.
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``::
:variable:`CMAKE_FIND_USE_CMAKE_PATH` to ``FALSE``:
CMAKE_PREFIX_PATH
CMAKE_FRAMEWORK_PATH
CMAKE_APPBUNDLE_PATH
* :variable:`CMAKE_PREFIX_PATH`
* :variable:`CMAKE_FRAMEWORK_PATH`
* :variable:`CMAKE_APPBUNDLE_PATH`
3. Search paths specified in cmake-specific environment variables.
These are intended to be set in the user's shell configuration,
and therefore use the host's native path separator
(``;`` on Windows and ``:`` on UNIX).
This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed or by setting
the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` to ``FALSE``::
the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` to ``FALSE``:
<PackageName>_DIR
CMAKE_PREFIX_PATH
CMAKE_FRAMEWORK_PATH
CMAKE_APPBUNDLE_PATH
* ``<PackageName>_DIR``
* :envvar:`CMAKE_PREFIX_PATH`
* ``CMAKE_FRAMEWORK_PATH``
* ``CMAKE_APPBUNDLE_PATH``
4. Search paths specified by the ``HINTS`` option. These should be paths
computed by system introspection, such as a hint provided by the
@ -329,9 +329,9 @@ enabled.
skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed or by setting the
:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` to ``FALSE``. Path entries
ending in ``/bin`` or ``/sbin`` are automatically converted to their
parent directories::
parent directories:
PATH
* ``PATH``
6. Search paths stored in the CMake :ref:`User Package Registry`.
This can be skipped if ``NO_CMAKE_PACKAGE_REGISTRY`` is passed or by
@ -345,11 +345,15 @@ enabled.
7. Search cmake variables defined in the Platform files for the
current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is
passed or by setting the :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`
to ``FALSE``::
to ``FALSE``:
CMAKE_SYSTEM_PREFIX_PATH
CMAKE_SYSTEM_FRAMEWORK_PATH
CMAKE_SYSTEM_APPBUNDLE_PATH
* :variable:`CMAKE_SYSTEM_PREFIX_PATH`
* :variable:`CMAKE_SYSTEM_FRAMEWORK_PATH`
* :variable:`CMAKE_SYSTEM_APPBUNDLE_PATH`
The platform paths that these variables contain are locations that
typically include installed software. An example being ``/usr/local`` for
UNIX based platforms.
8. Search paths stored in the CMake :ref:`System Package Registry`.
This can be skipped if ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` is passed

45
Help/command/foreach.rst
View File

@ -47,7 +47,7 @@ of undocumented behavior that may change in future releases.
.. code-block:: cmake
foreach(loop_var IN [LISTS [<lists>]] [ITEMS [<items>]])
foreach(<loop_var> IN [LISTS [<lists>]] [ITEMS [<items>]])
In this variant, ``<lists>`` is a whitespace or semicolon
separated list of list-valued variables. The ``foreach``
@ -82,3 +82,46 @@ yields
-- X=6
-- X=7
-- X=8
.. code-block:: cmake
foreach(<loop_var>... IN ZIP_LISTS <lists>)
In this variant, ``<lists>`` is a whitespace or semicolon
separated list of list-valued variables. The ``foreach``
command iterates over each list simultaneously setting the
iteration variables as follows:
- if the only ``loop_var`` given, then it sets a series of
``loop_var_N`` variables to the current item from the
corresponding list;
- if multiple variable names passed, their count should match
the lists variables count;
- if any of the lists are shorter, the corresponding iteration
variable is not defined for the current iteration.
.. code-block:: cmake
list(APPEND English one two three four)
list(APPEND Bahasa satu dua tiga)
foreach(num IN ZIP_LISTS English Bahasa)
message(STATUS "num_0=${num_0}, num_1=${num_1}")
endforeach()
foreach(en ba IN ZIP_LISTS English Bahasa)
message(STATUS "en=${en}, ba=${ba}")
endforeach()
yields
::
-- num_0=one, num_1=satu
-- num_0=two, num_1=dua
-- num_0=three, num_1=tiga
-- num_0=four, num_1=
-- en=one, ba=satu
-- en=two, ba=dua
-- en=three, ba=tiga
-- en=four, ba=

4
Help/command/function.rst
View File

@ -44,11 +44,15 @@ can be invoked through any of
foo()
Foo()
FOO()
cmake_language(CALL foo)
and so on. However, it is strongly recommended to stay with the
case chosen in the function definition. Typically functions use
all-lowercase names.
The :command:`cmake_language(CALL ...)` command can also be used to
invoke the function.
Arguments
^^^^^^^^^

21
Help/command/get_property.rst
View File

@ -10,6 +10,7 @@ Get a property.
DIRECTORY [<dir>] |
TARGET <target> |
SOURCE <source> |
[DIRECTORY <dir> | TARGET_DIRECTORY <target>] |
INSTALL <file> |
TEST <test> |
CACHE <entry> |
@ -30,18 +31,36 @@ It must be one of the following:
Scope defaults to the current directory but another
directory (already processed by CMake) may be named by the
full or relative path ``<dir>``.
See also the :command:`get_directory_property` command.
``TARGET``
Scope must name one existing target.
See also the :command:`get_target_property` command.
``SOURCE``
Scope must name one source file.
Scope must name one source file. By default, the source file's property
will be read from the current source directory's scope, but this can be
overridden with one of the following sub-options:
``DIRECTORY <dir>``
The source file property will be read from the ``<dir>`` directory's
scope. CMake must already know about that source directory, either by
having added it through a call to :command:`add_subdirectory` or ``<dir>``
being the top level source directory. Relative paths are treated as
relative to the current source directory.
``TARGET_DIRECTORY <target>``
The source file property will be read from the directory scope in which
``<target>`` was created (``<target>`` must therefore already exist).
See also the :command:`get_source_file_property` command.
``INSTALL``
Scope must name one installed file path.
``TEST``
Scope must name one existing test.
See also the :command:`get_test_property` command.
``CACHE``
Scope must name one cache entry.

32
Help/command/get_source_file_property.rst
View File

@ -5,15 +5,33 @@ Get a property for a source file.
.. code-block:: cmake
get_source_file_property(VAR file property)
get_source_file_property(<variable> <file>
[DIRECTORY <dir> | TARGET_DIRECTORY <target>]
<property>)
Gets a property from a source file. The value of the property is
stored in the variable ``VAR``. If the source property is not found, the
behavior depends on whether it has been defined to be an ``INHERITED`` property
or not (see :command:`define_property`). Non-inherited properties will set
``VAR`` to "NOTFOUND", whereas inherited properties will search the relevant
parent scope as described for the :command:`define_property` command and
if still unable to find the property, ``VAR`` will be set to an empty string.
stored in the specified ``<variable>``. If the source property is not found,
the behavior depends on whether it has been defined to be an ``INHERITED``
property or not (see :command:`define_property`). Non-inherited properties
will set ``variable`` to ``NOTFOUND``, whereas inherited properties will search
the relevant parent scope as described for the :command:`define_property`
command and if still unable to find the property, ``variable`` will be set to
an empty string.
By default, the source file's property will be read from the current source
directory's scope, but this can be overridden with one of the following
sub-options:
``DIRECTORY <dir>``
The source file property will be read from the ``<dir>`` directory's
scope. CMake must already know about that source directory, either by
having added it through a call to :command:`add_subdirectory` or ``<dir>``
being the top level source directory. Relative paths are treated as
relative to the current source directory.
``TARGET_DIRECTORY <target>``
The source file property will be read from the directory scope in which
``<target>`` was created (``<target>`` must therefore already exist).
Use :command:`set_source_files_properties` to set property values. Source
file properties usually control how the file is built. One property that is

10
Help/command/get_target_property.rst
View File

@ -5,15 +5,15 @@ Get a property from a target.
.. code-block:: cmake
get_target_property(VAR target property)
get_target_property(<VAR> target property)
Get a property from a target. The value of the property is stored in
the variable ``VAR``. If the target property is not found, the behavior
the variable ``<VAR>``. If the target property is not found, the behavior
depends on whether it has been defined to be an ``INHERITED`` property
or not (see :command:`define_property`). Non-inherited properties will
set ``VAR`` to ``NOTFOUND``, whereas inherited properties will search the
relevant parent scope as described for the :command:`define_property`
command and if still unable to find the property, ``VAR`` will be set to
set ``<VAR>`` to ``<VAR>-NOTFOUND``, whereas inherited properties will search
the relevant parent scope as described for the :command:`define_property`
command and if still unable to find the property, ``<VAR>`` will be set to
an empty string.
Use :command:`set_target_properties` to set target property values.

76
Help/command/install.rst
View File

@ -18,10 +18,12 @@ Synopsis
Introduction
^^^^^^^^^^^^
This command generates installation rules for a project. Rules
specified by calls to this command within a source directory are
executed in order during installation. The order across directories
is not defined.
This command generates installation rules for a project. Install rules
specified by calls to the ``install()`` command within a source directory
are executed in order during installation. Install rules in subdirectories
added by calls to the :command:`add_subdirectory` command are interleaved
with those in the parent directory to run in the order declared (see
policy :policy:`CMP0082`).
There are multiple signatures for this command. Some of them define
installation options for files and targets. Options common to
@ -30,13 +32,20 @@ signatures that specify them. The common options are:
``DESTINATION``
Specify the directory on disk to which a file will be installed.
If a full path (with a leading slash or drive letter) is given
it is used directly. If a relative path is given it is interpreted
relative to the value of the :variable:`CMAKE_INSTALL_PREFIX` variable.
Arguments can be relative or absolute paths.
If a relative path is given it is interpreted relative to the value
of the :variable:`CMAKE_INSTALL_PREFIX` variable.
The prefix can be relocated at install time using the ``DESTDIR``
mechanism explained in the :variable:`CMAKE_INSTALL_PREFIX` variable
documentation.
If an absolute path (with a leading slash or drive letter) is given
it is used verbatim.
As absolute paths are not supported by :manual:`cpack <cpack(1)>` installer
generators, it is preferable to use relative paths throughout.
``PERMISSIONS``
Specify permissions for installed files. Valid permissions are
``OWNER_READ``, ``OWNER_WRITE``, ``OWNER_EXECUTE``, ``GROUP_READ``,
@ -119,31 +128,38 @@ Installing Targets
)
The ``TARGETS`` form specifies rules for installing targets from a
project. There are several kinds of target files that may be installed:
project. There are several kinds of target :ref:`Output Artifacts`
that may be installed:
``ARCHIVE``
Static libraries are treated as ``ARCHIVE`` targets, except those
marked with the ``FRAMEWORK`` property on macOS (see ``FRAMEWORK``
below.) For DLL platforms (all Windows-based systems including
Cygwin), the DLL import library is treated as an ``ARCHIVE`` target.
On AIX, the linker import file created for executables with
:prop_tgt:`ENABLE_EXPORTS` is treated as an ``ARCHIVE`` target.
Target artifacts of this kind include:
* *Static libraries*
(except on macOS when marked as ``FRAMEWORK``, see below);
* *DLL import libraries*
(on all Windows-based systems including Cygwin; they have extension
``.lib``, in contrast to the ``.dll`` libraries that go to ``RUNTIME``);
* On AIX, the *linker import file* created for executables with
:prop_tgt:`ENABLE_EXPORTS` enabled.
``LIBRARY``
Module libraries are always treated as ``LIBRARY`` targets. For non-
DLL platforms shared libraries are treated as ``LIBRARY`` targets,
except those marked with the ``FRAMEWORK`` property on macOS (see
``FRAMEWORK`` below.)
Target artifacts of this kind include:
* *Shared libraries*, except
- DLLs (these go to ``RUNTIME``, see below),
- on macOS when marked as ``FRAMEWORK`` (see below).
``RUNTIME``
Executables are treated as ``RUNTIME`` objects, except those marked
with the ``MACOSX_BUNDLE`` property on macOS (see ``BUNDLE`` below.)
For DLL platforms (all Windows-based systems including Cygwin), the
DLL part of a shared library is treated as a ``RUNTIME`` target.
Target artifacts of this kind include:
* *Executables*
(except on macOS when marked as ``MACOSX_BUNDLE``, see ``BUNDLE`` below);
* DLLs (on all Windows-based systems including Cygwin; note that the
accompanying import libraries are of kind ``ARCHIVE``).
``OBJECTS``
Object libraries (a simple group of object files) are always treated
as ``OBJECTS`` targets.
Object files associated with *object libraries*.
``FRAMEWORK``
Both static and shared libraries marked with the ``FRAMEWORK``
@ -630,6 +646,13 @@ present, causes the contents of the properties matching
``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?`` to be exported, when
policy :policy:`CMP0022` is ``NEW``.
.. note::
The installed ``<export-name>.cmake`` file may come with additional
per-configuration ``<export-name>-*.cmake`` files to be loaded by
globbing. Do not use an export name that is the same as the package
name in combination with installing a ``<package-name>-config.cmake``
file or the latter may be incorrectly matched by the glob and loaded.
When a ``COMPONENT`` option is given, the listed ``<component>`` implicitly
depends on all components mentioned in the export set. The exported
``<name>.cmake`` file will require each of the exported components to be
@ -684,6 +707,11 @@ executable from the installation tree using the imported target name
Generated Installation Script
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. note::
Use of this feature is not recommended. Please consider using the
``--install`` argument of :manual:`cmake(1)` 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

7
Help/command/list.rst
View File

@ -308,6 +308,13 @@ The ``<compare>`` option should be one of:
* ``STRING``: Sorts a list of strings alphabetically. This is the
default behavior if the ``COMPARE`` option is not given.
* ``FILE_BASENAME``: Sorts a list of pathnames of files by their basenames.
* ``NATURAL``: Sorts a list of strings using natural order
(see ``strverscmp(3)`` manual), i.e. such that contiguous digits
are compared as whole numbers.
For example: the following list `10.0 1.1 2.1 8.0 2.0 3.1`
will be sorted as `1.1 2.0 2.1 3.1 8.0 10.0` if the ``NATURAL``
comparison is selected where it will be sorted as
`1.1 10.0 2.0 2.1 3.1 8.0` with the ``STRING`` comparison.
Use the ``CASE`` keyword to select a case sensitive or case insensitive
sort mode. The ``<case>`` option should be one of:

10
Help/command/macro.rst
View File

@ -42,11 +42,15 @@ can be invoked through any of
foo()
Foo()
FOO()
cmake_language(CALL foo)
and so on. However, it is strongly recommended to stay with the
case chosen in the macro definition. Typically macros use
all-lowercase names.
The :command:`cmake_language(CALL ...)` command can also be used to
invoke the macro.
Arguments
^^^^^^^^^
@ -91,6 +95,12 @@ just terminate execution of the macro; rather, control is returned
from the scope of the macro call. To avoid confusion, it is recommended
to avoid :command:`return()` in macros altogether.
Unlike a function, the :variable:`CMAKE_CURRENT_FUNCTION`,
:variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR`,
:variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE`,
:variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE` variables are not
set for a macro.
.. _`Argument Caveats`:
Argument Caveats

6
Help/command/mark_as_advanced.rst
View File

@ -22,3 +22,9 @@ If neither ``FORCE`` nor ``CLEAR`` is specified,
new values will be marked as advanced, but if a
variable already has an advanced/non-advanced state,
it will not be changed.
.. note::
Policy :policy:`CMP0102` affects the behavior of the ``mark_as_advanced``
call. When set to ``NEW``, variables passed to this command which are not
already in the cache are ignored. See policy :policy:`CMP0102`.

120
Help/command/message.rst
View File

@ -1,13 +1,33 @@
message
-------
Display a message to the user.
Log a message.
Synopsis
^^^^^^^^
.. parsed-literal::
`General messages`_
message([<mode>] "message text" ...)
`Reporting checks`_
message(<checkState> "message text" ...)
General messages
^^^^^^^^^^^^^^^^
.. code-block:: cmake
message([<mode>] "message to display" ...)
message([<mode>] "message text" ...)
The optional ``<mode>`` keyword determines the type of message:
Record the specified message text in the log. If more than one message
string is given, they are concatenated into a single message with no
separator between the strings.
The optional ``<mode>`` keyword determines the type of message, which
influences the way the message is handled:
``FATAL_ERROR``
CMake Error, stop processing and generation.
@ -59,12 +79,104 @@ 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.
To make a log level persist between CMake runs, the
:variable:`CMAKE_MESSAGE_LOG_LEVEL` variable can be set instead.
Note that the command line option takes precedence over the cache variable.
Messages of log levels ``NOTICE`` and below will also have each line preceded
Messages of log levels ``NOTICE`` and below will have each line preceded
by the content of the :variable:`CMAKE_MESSAGE_INDENT` variable (converted to
a single string by concatenating its list items). For ``STATUS`` to ``TRACE``
messages, this indenting content will be inserted after the hyphens.
Messages of log levels ``NOTICE`` and below can also have each line preceded
with context of the form ``[some.context.example]``. The content between the
square brackets is obtained by converting the :variable:`CMAKE_MESSAGE_CONTEXT`
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``
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.
CMake Warning and Error message text displays using a simple markup
language. Non-indented text is formatted in line-wrapped paragraphs
delimited by newlines. Indented text is considered pre-formatted.
Reporting checks
^^^^^^^^^^^^^^^^
A common pattern in CMake output is a message indicating the start of some
sort of check, followed by another message reporting the result of that check.
For example:
.. code-block:: cmake
message(STATUS "Looking for someheader.h")
#... do the checks, set checkSuccess with the result
if(checkSuccess)
message(STATUS "Looking for someheader.h - found")
else()
message(STATUS "Looking for someheader.h - not found")
endif()
This can be more robustly and conveniently expressed using the ``CHECK_...``
keyword form of the ``message()`` command:
.. code-block:: cmake
message(<checkState> "message" ...)
where ``<checkState>`` must be one of the following:
``CHECK_START``
Record a concise message about the check about to be performed.
``CHECK_PASS``
Record a successful result for a check.
``CHECK_FAIL``
Record an unsuccessful result for a check.
When recording a check result, the command repeats the message from the most
recently started check for which no result has yet been reported, then some
separator characters and then the message text provided after the
``CHECK_PASS`` or ``CHECK_FAIL`` keyword. Check messages are always reported
at ``STATUS`` log level.
Checks may be nested and every ``CHECK_START`` should have exactly one
matching ``CHECK_PASS`` or ``CHECK_FAIL``.
The :variable:`CMAKE_MESSAGE_INDENT` variable can also be used to add
indenting to nested checks if desired. For example:
.. code-block:: cmake
message(CHECK_START "Finding my things")
list(APPEND CMAKE_MESSAGE_INDENT " ")
unset(missingComponents)
message(CHECK_START "Finding partA")
# ... do check, assume we find A
message(CHECK_PASS "found")
message(CHECK_START "Finding partB")
# ... do check, assume we don't find B
list(APPEND missingComponents B)
message(CHECK_FAIL "not found")
list(POP_BACK CMAKE_MESSAGE_INDENT)
if(missingComponents)
message(CHECK_FAIL "missing components: ${missingComponents}")
else()
message(CHECK_PASS "all components found")
endif()
Output from the above would appear something like the following::
-- Finding my things
-- Finding partA
-- Finding partA - found
-- Finding partB
-- Finding partB - not found
-- Finding my things - missing components: B

2
Help/command/option.rst
View File

@ -9,7 +9,7 @@ Provide an option that the user can optionally select.
Provides an option for the user to select as ``ON`` or ``OFF``.
If no initial ``<value>`` is provided, ``OFF`` is used.
If ``<variable>`` is already set as a normal variable
If ``<variable>`` is already set as a normal or cache variable,
then the command does nothing (see policy :policy:`CMP0077`).
If you have options that depend on the values of other options, see

7
Help/command/project.rst
View File

@ -102,9 +102,12 @@ options are intended for use as default values in package metadata and documenta
Code Injection
^^^^^^^^^^^^^^
If the :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variable is set, the file
pointed to by that variable will be included as the first step of the
If the :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` or
:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` variables are set,
the files they point to will be included as the first step of the
``project()`` command.
If both are set, then :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` will be
included before :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`.
If the :variable:`CMAKE_PROJECT_INCLUDE` or
:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` variables are set, the files

2
Help/command/separate_arguments.rst
View File

@ -19,7 +19,7 @@ They are specified by the ``<mode>`` argument which must
be one of the following keywords:
``UNIX_COMMAND``
Arguments are separated by by unquoted whitespace.
Arguments are separated by unquoted whitespace.
Both single-quote and double-quote pairs are respected.
A backslash escapes the next literal character (``\"`` is ``"``);
there are no special escapes (``\n`` is just ``n``).

29
Help/command/set_property.rst
View File

@ -8,12 +8,14 @@ Set a named property in a given scope.
set_property(<GLOBAL |
DIRECTORY [<dir>] |
TARGET [<target1> ...] |
SOURCE [<src1> ...] |
SOURCE [<src1> ...]
[DIRECTORY <dirs> ...] |
[TARGET_DIRECTORY <targets> ...]
INSTALL [<file1> ...] |
TEST [<test1> ...] |
CACHE [<entry1> ...] >
[APPEND] [APPEND_STRING]
PROPERTY <name> [value1 ...])
PROPERTY <name> [<value1> ...])
Sets one property on zero or more objects of a scope.
@ -33,9 +35,23 @@ It must be one of the following:
See also the :command:`set_target_properties` command.
``SOURCE``
Scope may name zero or more source files. Note that source
file properties are visible only to targets added in the same
directory (``CMakeLists.txt``).
Scope may name zero or more source files. By default, source file properties
are only visible to targets added in the same directory (``CMakeLists.txt``).
Visibility can be set in other directory scopes using one or both of the
following sub-options:
``DIRECTORY <dirs>...``
The source file property will be set in each of the ``<dirs>``
directories' scopes. CMake must already know about each of these
source directories, either by having added them through a call to
:command:`add_subdirectory` or it being the top level source directory.
Relative paths are treated as relative to the current source directory.
``TARGET_DIRECTORY <targets>...``
The source file property will be set in each of the directory scopes
where any of the specified ``<targets>`` were created (the ``<targets>``
must therefore already exist).
See also the :command:`set_source_files_properties` command.
``INSTALL``
@ -66,7 +82,8 @@ the property to set. Remaining arguments are used to compose the
property value in the form of a semicolon-separated list.
If the ``APPEND`` option is given the list is appended to any existing
property value. If the ``APPEND_STRING`` option is given the string is
property value (except that empty values are ignored and not appended).
If the ``APPEND_STRING`` option is given the string is
appended to any existing property value as string, i.e. it results in a
longer string and not a list of strings. When using ``APPEND`` or
``APPEND_STRING`` with a property defined to support ``INHERITED``

28
Help/command/set_source_files_properties.rst
View File

@ -5,15 +5,33 @@ Source files can have properties that affect how they are built.
.. code-block:: cmake
set_source_files_properties([file1 [file2 [...]]]
PROPERTIES prop1 value1
[prop2 value2 [...]])
set_source_files_properties(<files> ...
[DIRECTORY <dirs> ...]
[TARGET_DIRECTORY <targets> ...]
PROPERTIES <prop1> <value1>
[<prop2> <value2>] ...)
Sets properties associated with source files using a key/value paired
list.
By default, source file properties are only visible to targets added in the
same directory (``CMakeLists.txt``). Visibility can be set in other directory
scopes using one or both of the following options:
``DIRECTORY <dirs>...``
The source file properties will be set in each of the ``<dirs>``
directories' scopes. CMake must already know about each of these
source directories, either by having added them through a call to
:command:`add_subdirectory` or it being the top level source directory.
Relative paths are treated as relative to the current source directory.
``TARGET_DIRECTORY <targets>...``
The source file properties will be set in each of the directory scopes
where any of the specified ``<targets>`` were created (the ``<targets>``
must therefore already exist).
Use :command:`get_source_file_property` to get property values.
See also the :command:`set_property(SOURCE)` command.
See :ref:`Source File Properties` for the list of properties known
to CMake. Source file properties are visible only to targets added
in the same directory (``CMakeLists.txt``).
to CMake.

6
Help/command/source_group.rst
View File

@ -37,11 +37,13 @@ explicitly lists the file with ``FILES`` will be favored, if any.
If no group explicitly lists the file, the *last* group whose
regular expression matches the file will be favored.
The ``<name>`` of the group and ``<prefix>`` argument may contain backslashes
to specify subgroups:
The ``<name>`` of the group and ``<prefix>`` argument may contain forward
slashes or backslashes to specify subgroups. Backslashes need to be escaped
appropriately:
.. code-block:: cmake
source_group(base/subdir ...)
source_group(outer\\inner ...)
source_group(TREE <root> PREFIX sources\\inc ...)

21
Help/command/string.rst
View File

@ -11,8 +11,6 @@ Synopsis
`Search and Replace`_
string(`FIND`_ <string> <substring> <out-var> [...])
string(`REPLACE`_ <match-string> <replace-string> <out-var> <input>...)
`Regular Expressions`_
string(`REGEX MATCH`_ <match-regex> <out-var> <input>...)
string(`REGEX MATCHALL`_ <match-regex> <out-var> <input>...)
string(`REGEX REPLACE`_ <match-regex> <replace-expr> <out-var> <input>...)
@ -38,6 +36,7 @@ Synopsis
`Generation`_
string(`ASCII`_ <number>... <out-var>)
string(`HEX`_ <string> <out-var>)
string(`CONFIGURE`_ <string> <out-var> [...])
string(`MAKE_C_IDENTIFIER`_ <string> <out-var>)
string(`RANDOM`_ [<option>...] <out-var>)
@ -47,6 +46,9 @@ Synopsis
Search and Replace
^^^^^^^^^^^^^^^^^^
Search and Replace With Plain Strings
"""""""""""""""""""""""""""""""""""""
.. _FIND:
.. code-block:: cmake
@ -74,8 +76,8 @@ so strings containing multi-byte characters may lead to unexpected results.
Replace all occurrences of ``<match_string>`` in the ``<input>``
with ``<replace_string>`` and store the result in the ``<output_variable>``.
Regular Expressions
^^^^^^^^^^^^^^^^^^^
Search and Replace With Regular Expressions
"""""""""""""""""""""""""""""""""""""""""""
.. _`REGEX MATCH`:
@ -87,6 +89,7 @@ Regular Expressions
Match the ``<regular_expression>`` once and store the match in the
``<output_variable>``.
All ``<input>`` arguments are concatenated before matching.
Regular expressions are specified in the subsection just below.
.. _`REGEX MATCHALL`:
@ -353,6 +356,16 @@ Generation
Convert all numbers into corresponding ASCII characters.
.. _HEX:
.. code-block:: cmake
string(HEX <string> <output_variable>)
Convert each byte in the input ``<string>`` to its hexadecimal representation
and store the concatenated hex digits in the ``<output_variable>``. Letters in
the output (``a`` through ``f``) are in lowercase.
.. _CONFIGURE:
.. code-block:: cmake

6
Help/command/target_compile_features.rst
View File

@ -8,9 +8,9 @@ Add expected compiler features to a target.
target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...])
Specifies compiler features required when compiling a given target. If the
feature is not listed in the :variable:`CMAKE_C_COMPILE_FEATURES` variable
or :variable:`CMAKE_CXX_COMPILE_FEATURES` variable,
then an error will be reported by CMake. If the use of the feature requires
feature is not listed in the :variable:`CMAKE_C_COMPILE_FEATURES`,
:variable:`CMAKE_CUDA_COMPILE_FEATURES`, or :variable:`CMAKE_CXX_COMPILE_FEATURES`
variables, then an error will be reported by CMake. If the use of the feature requires
an additional compiler flag, such as ``-std=gnu++11``, the flag will be added
automatically.

2
Help/command/target_compile_options.rst
View File

@ -46,3 +46,5 @@ to use the more specific commands :command:`target_compile_definitions`
and :command:`target_include_directories`.
For directory-wide settings, there is the command :command:`add_compile_options`.
For file-specific settings, there is the source file property :prop_sf:`COMPILE_OPTIONS`.

2
Help/command/target_link_options.rst
View File

@ -43,6 +43,8 @@ with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.
.. include:: DEVICE_LINK_OPTIONS.txt
.. include:: OPTIONS_SHELL.txt
.. include:: LINK_OPTIONS_LINKER.txt

29
Help/command/target_precompile_headers.rst
View File

@ -56,35 +56,34 @@ e.g. ``[["other_header.h"]]``) will be treated as is, and include directories
must be available for the compiler to find them. Other header file names
(e.g. ``project_header.h``) are interpreted as being relative to the current
source directory (e.g. :variable:`CMAKE_CURRENT_SOURCE_DIR`) and will be
included by absolute path.
Arguments to ``target_precompile_headers()`` may use "generator expressions"
with the syntax ``$<...>``.
See the :manual:`cmake-generator-expressions(7)` manual for available
expressions. See the :manual:`cmake-compile-features(7)` manual for
information on compile features and a list of supported compilers.
The ``$<COMPILE_LANGUAGE:...>`` generator expression is particularly
useful for specifying a language-specific header to precompile for
only one language (e.g. ``CXX`` and not ``C``). For example:
included by absolute path. For example:
.. code-block:: cmake
target_precompile_headers(myTarget
PUBLIC
project_header.h
"$<$<COMPILE_LANGUAGE:CXX>:cxx_only.h>"
PRIVATE
[["other_header.h"]]
<unordered_map>
)
When specifying angle brackets inside a :manual:`generator expression
<cmake-generator-expressions(7)>`, be sure to encode the closing ``>``
as ``$<ANGLE-R>``. For example:
Arguments to ``target_precompile_headers()`` may use "generator expressions"
with the syntax ``$<...>``.
See the :manual:`cmake-generator-expressions(7)` manual for available
expressions.
The ``$<COMPILE_LANGUAGE:...>`` generator expression is particularly
useful for specifying a language-specific header to precompile for
only one language (e.g. ``CXX`` and not ``C``). In this case, header
file names that are not explicitly in double quotes or angle brackets
must be specified by absolute path. Also, when specifying angle brackets
inside a generator expression, be sure to encode the closing ``>`` as
``$<ANGLE-R>``. For example:
.. code-block:: cmake
target_precompile_headers(mylib PRIVATE
"$<$<COMPILE_LANGUAGE:CXX>:${CMAKE_CURRENT_SOURCE_DIR}/cxx_only.h>"
"$<$<COMPILE_LANGUAGE:C>:<stddef.h$<ANGLE-R>>"
"$<$<COMPILE_LANGUAGE:CXX>:<cstddef$<ANGLE-R>>"
)
@ -94,7 +93,7 @@ Reusing Precompile Headers
^^^^^^^^^^^^^^^^^^^^^^^^^^
The command also supports a second signature which can be used to specify that
one target re-uses a precompiled header file artefact from another target
one target re-uses a precompiled header file artifact from another target
instead of generating its own:
.. code-block:: cmake

1
Help/command/try_compile.rst
View File

@ -135,6 +135,7 @@ If set, the following variables are passed in to the generated
try_compile CMakeLists.txt to initialize compile target properties with
default values:
* :variable:`CMAKE_CUDA_RUNTIME_LIBRARY`
* :variable:`CMAKE_ENABLE_EXPORTS`
* :variable:`CMAKE_LINK_SEARCH_START_STATIC`
* :variable:`CMAKE_LINK_SEARCH_END_STATIC`

65
Help/cpack_gen/archive.rst
View File

@ -1,8 +1,8 @@
CPack Archive Generator
-----------------------
Archive CPack generator that supports packaging of sources and binaries in
different formats:
CPack generator for packaging files into an archive, which can have
any of the following formats:
- 7Z - 7zip - (.7z)
- TBZ2 (.tar.bz2)
@ -12,25 +12,64 @@ different formats:
- TZST (.tar.zst)
- ZIP (.zip)
When this generator is called from ``CPackSourceConfig.cmake`` (or through
the ``package_source`` target), then the generated archive will contain all
files in the project directory, except those specified in
:variable:`CPACK_SOURCE_IGNORE_FILES`. The following is one example of
packaging all source files of a project:
.. code-block:: cmake
set(CPACK_SOURCE_GENERATOR "TGZ")
set(CPACK_SOURCE_IGNORE_FILES
\\.git/
build/
".*~$"
)
set(CPACK_VERBATIM_VARIABLES YES)
include(CPack)
When this generator is called from ``CPackConfig.cmake`` (or through the
``package`` target), then the generated archive will contain all files
that have been installed via CMake's :command:`install` command (and the
deprecated commands :command:`install_files`, :command:`install_programs`,
and :command:`install_targets`).
Variables specific to CPack Archive generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. variable:: CPACK_ARCHIVE_FILE_NAME
CPACK_ARCHIVE_<component>_FILE_NAME
Package file name without extension which is added automatically depending
on the archive format.
* Mandatory : YES
* Default : ``<CPACK_PACKAGE_FILE_NAME>[-<component>].<extension>`` with
spaces replaced by '-'
Package file name without extension. The extension is determined from the
archive format (see list above) and automatically appended to the file name.
The default is ``<CPACK_PACKAGE_FILE_NAME>[-<component>]``, with spaces
replaced by '-'.
.. variable:: CPACK_ARCHIVE_COMPONENT_INSTALL
Enable component packaging for CPackArchive
Enable component packaging. If enabled (ON), then the archive generator
creates multiple packages. The default is OFF, which means that a single
package containing files of all components is generated.
* Mandatory : NO
* Default : OFF
Variables used by CPack Archive generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If enabled (ON) multiple packages are generated. By default a single package
containing files of all components is generated.
These variables are used by the Archive generator, but are also available to
CPack generators which are essentially archives at their core. These include:
- :cpack_gen:`CPack Cygwin Generator`
- :cpack_gen:`CPack FreeBSD Generator`
.. variable:: CPACK_ARCHIVE_THREADS
The number of threads to use when performing the compression. If set to
``0``, the number of available cores on the machine will be used instead.
The default is ``1`` which limits compression to a single thread. Note that
not all compression modes support threading in all environments. Currently,
only the XZ compression may support it.
.. note::
Official CMake binaries available on ``cmake.org`` ship with a ``liblzma``
that does not support parallel compression.

5
Help/cpack_gen/cygwin.rst
View File

@ -3,6 +3,11 @@ CPack Cygwin Generator
Cygwin CPack generator (Cygwin).
Variables affecting the CPack Cygwin generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- :variable:`CPACK_ARCHIVE_THREADS`
Variables specific to CPack Cygwin generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

6
Help/cpack_gen/deb.rst
View File

@ -25,8 +25,8 @@ or a component GROUP name.
Here are some CPack DEB generator wiki resources that are here for historic
reasons and are no longer maintained but may still prove useful:
- https://gitlab.kitware.com/cmake/community/wikis/doc/cpack/Configuration
- https://gitlab.kitware.com/cmake/community/wikis/doc/cpack/PackageGenerators#deb-unix-only
- https://gitlab.kitware.com/cmake/community/-/wikis/doc/cpack/Configuration
- https://gitlab.kitware.com/cmake/community/-/wikis/doc/cpack/PackageGenerators#deb-unix-only
List of CPack DEB generator specific variables:
@ -282,7 +282,7 @@ List of CPack DEB generator specific variables:
You may need set :variable:`CMAKE_INSTALL_RPATH` to an appropriate value
if you use this feature, because if you don't ``dpkg-shlibdeps``
may fail to find your own shared libs.
See https://gitlab.kitware.com/cmake/community/wikis/doc/cmake/RPATH-handling
See https://gitlab.kitware.com/cmake/community/-/wikis/doc/cmake/RPATH-handling
.. variable:: CPACK_DEBIAN_PACKAGE_DEBUG

15
Help/cpack_gen/dmg.rst
View File

@ -54,10 +54,12 @@ on macOS:
Directory where license and menu files for different languages are stored.
Setting this causes CPack to look for a ``<language>.menu.txt`` and
``<language>.license.txt`` file for every language defined in
``CPACK_DMG_SLA_LANGUAGES``. If both this variable and
``<language>.license.txt`` or ``<language>.license.rtf`` file for every
language defined in ``CPACK_DMG_SLA_LANGUAGES``. If both this variable and
``CPACK_RESOURCE_FILE_LICENSE`` are set, CPack will only look for the menu
files and use the same license file for all languages.
files and use the same license file for all languages. If both
``<language>.license.txt`` and ``<language>.license.rtf`` exist, the ``.txt``
file will be used.
.. variable:: CPACK_DMG_SLA_LANGUAGES
@ -81,6 +83,13 @@ on macOS:
``<language>.menu.txt`` and ``<language>.license.txt`` in the directory
specified by the :variable:`CPACK_DMG_SLA_DIR` variable.
.. variable:: CPACK_DMG_<component>_FILE_NAME
File name when packaging ``<component>`` as its own DMG
(``CPACK_COMPONENTS_GROUPING`` set to IGNORE).
- Default: ``CPACK_PACKAGE_FILE_NAME-<component>``
.. variable:: CPACK_COMMAND_HDIUTIL
Path to the ``hdiutil(1)`` command used to operate on disk image files on

5
Help/cpack_gen/freebsd.rst
View File

@ -3,6 +3,11 @@ CPack FreeBSD Generator
The built in (binary) CPack FreeBSD (pkg) generator (Unix only)
Variables affecting the CPack FreeBSD (pkg) generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- :variable:`CPACK_ARCHIVE_THREADS`
Variables specific to CPack FreeBSD (pkg) generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

198
Help/cpack_gen/ifw.rst
View File

@ -1,78 +1,28 @@
CPack IFW Generator
-------------------
See :module:`CPackIFW` for details on the CPackIFW module.
Configure and run the Qt Installer Framework to generate a Qt installer.
.. _QtIFW: http://doc.qt.io/qtinstallerframework/index.html
.. only:: html
.. contents::
Overview
^^^^^^^^
CPack ``IFW`` generator helps you to create online and offline
binary cross-platform installers with a graphical user interface.
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),
and runs QtIFW tools to generate a Qt installer.
CPack IFW generator prepares project installation and generates configuration
and meta information for QtIFW_ tools.
QtIFW provides tools and utilities to create installers for
the platforms supported by `Qt <https://www.qt.io>`_: Linux,
Microsoft Windows, and macOS.
The QtIFW_ provides a set of tools and utilities to create
installers for the supported desktop Qt platforms: Linux, Microsoft Windows,
and macOS.
You should also install QtIFW_ to use CPack ``IFW`` generator.
Hints
^^^^^
Generally, the CPack ``IFW`` generator automatically finds QtIFW_ tools,
but if you don't use a default path for installation of the QtIFW_ tools,
the path may be specified in either a CMake or an environment variable:
.. variable:: CPACK_IFW_ROOT
An CMake variable which specifies the location of the QtIFW_ tool suite.
The variable will be cached in the ``CPackConfig.cmake`` file and used at
CPack runtime.
.. variable:: QTIFWDIR
An environment variable which specifies the location of the QtIFW_ tool
suite.
.. note::
The specified path should not contain "bin" at the end
(for example: "D:\\DevTools\\QtIFW2.0.5").
The :variable:`CPACK_IFW_ROOT` variable has a higher priority and overrides
the value of the :variable:`QTIFWDIR` variable.
Internationalization
^^^^^^^^^^^^^^^^^^^^
Some variables and command arguments support internationalization via
CMake script. This is an optional feature.
Installers created by QtIFW_ tools have built-in support for
internationalization and many phrases are localized to many languages,
but this does not apply to the description of the your components and groups
that will be distributed.
Localization of the description of your components and groups is useful for
users of your installers.
A localized variable or argument can contain a single default value, and a
set of pairs the name of the locale and the localized value.
For example:
.. code-block:: cmake
set(LOCALIZABLE_VARIABLE "Default value"
en "English value"
en_US "American value"
en_GB "Great Britain value"
)
To make use of this generator, QtIFW needs to be installed.
The :module:`CPackIFW` module looks for the location of the
QtIFW command-line utilities, and defines several commands to
control the behavior of this generator.
Variables
^^^^^^^^^
@ -162,6 +112,8 @@ Package
Default target directory for installation.
By default used
"@ApplicationsDir@/:variable:`CPACK_PACKAGE_INSTALL_DIRECTORY`"
(variables embedded in '@' are expanded by the
`QtIFW scripting engine <https://doc.qt.io/qtinstallerframework/scripting.html>`_).
You can use predefined variables.
@ -185,7 +137,7 @@ Package
Filename of the generated maintenance tool.
The platform-specific executable file extension is appended.
By default used QtIFW_ defaults (``maintenancetool``).
By default used QtIFW defaults (``maintenancetool``).
.. variable:: CPACK_IFW_PACKAGE_REMOVE_TARGET_DIR
@ -197,19 +149,19 @@ Package
Filename for the configuration of the generated maintenance tool.
By default used QtIFW_ defaults (``maintenancetool.ini``).
By default used QtIFW defaults (``maintenancetool.ini``).
.. variable:: CPACK_IFW_PACKAGE_ALLOW_NON_ASCII_CHARACTERS
Set to ``ON`` if the installation path can contain non-ASCII characters.
Is ``ON`` for QtIFW_ less 2.0 tools.
Is ``ON`` for QtIFW less 2.0 tools.
.. variable:: CPACK_IFW_PACKAGE_ALLOW_SPACE_IN_PATH
Set to ``OFF`` if the installation path cannot contain space characters.
Is ``ON`` for QtIFW_ less 2.0 tools.
Is ``ON`` for QtIFW less 2.0 tools.
.. variable:: CPACK_IFW_PACKAGE_CONTROL_SCRIPT
@ -266,57 +218,113 @@ Components
Additional prepared repository dirs that will be used to resolve and
repack dependent components. This feature available only
since QtIFW_ 3.1.
since QtIFW 3.1.
Tools
"""""
QtIFW Tools
"""""""""""
.. variable:: CPACK_IFW_FRAMEWORK_VERSION
The version of used QtIFW_ tools.
The version of used QtIFW tools.
The following variables provide the locations of the QtIFW
command-line tools as discovered by the module :module:`CPackIFW`.
These variables are cached, and may be configured if needed.
.. variable:: CPACK_IFW_BINARYCREATOR_EXECUTABLE
The path to "binarycreator" command line client.
This variable is cached and may be configured if needed.
The path to ``binarycreator``.
.. variable:: CPACK_IFW_REPOGEN_EXECUTABLE
The path to "repogen" command line client.
This variable is cached and may be configured if needed.
The path to ``repogen``.
.. variable:: CPACK_IFW_INSTALLERBASE_EXECUTABLE
The path to "installerbase" installer executable base.
This variable is cached and may be configured if needed.
The path to ``installerbase``.
.. variable:: CPACK_IFW_DEVTOOL_EXECUTABLE
The path to "devtool" command line client.
The path to ``devtool``.
This variable is cached and may be configured if needed.
Hints for Finding QtIFW
"""""""""""""""""""""""
Generally, the CPack ``IFW`` generator automatically finds QtIFW tools,
but if you don't use a default path for installation of the QtIFW tools,
the path may be specified in either a CMake or an environment variable:
.. variable:: CPACK_IFW_ROOT
An CMake variable which specifies the location of the QtIFW tool suite.
The variable will be cached in the ``CPackConfig.cmake`` file and used at
CPack runtime.
.. variable:: QTIFWDIR
An environment variable which specifies the location of the QtIFW tool
suite.
.. note::
The specified path should not contain "bin" at the end
(for example: "D:\\DevTools\\QtIFW2.0.5").
The :variable:`CPACK_IFW_ROOT` variable has a higher priority and overrides
the value of the :variable:`QTIFWDIR` variable.
Other Settings
^^^^^^^^^^^^^^
Online installer
^^^^^^^^^^^^^^^^
""""""""""""""""
By default CPack IFW generator makes offline installer. This means that all
components will be packaged into a binary file.
By default, this generator generates an *offline installer*. This means that
that all packaged files are fully contained in the installer executable.
To make a component downloaded, you must set the ``DOWNLOADED`` option in
:command:`cpack_add_component`.
In contrast, an *online installer* will download some or all components from
a remote server.
Then you would use the command :command:`cpack_configure_downloads`.
If you set ``ALL`` option all components will be downloaded.
The ``DOWNLOADED`` option in the :command:`cpack_add_component` command
specifies that a component is to be downloaded. Alternatively, the ``ALL``
option in the :command:`cpack_configure_downloads` command specifies that
`all` components are to be be downloaded.
You also can use command :command:`cpack_ifw_add_repository` and
variable :variable:`CPACK_IFW_DOWNLOAD_ALL` for more specific configuration.
The :command:`cpack_ifw_add_repository` command and the
:variable:`CPACK_IFW_DOWNLOAD_ALL` variable allow for more specific
configuration.
CPack IFW generator creates "repository" dir in current binary dir. You
would copy content of this dir to specified ``site`` (``url``).
When there are online components, CPack will write them to archive files.
The help page of the :module:`CPackComponent` module, especially the section
on the :command:`cpack_configure_downloads` function, explains how to make
these files accessible from a download URL.
Internationalization
""""""""""""""""""""
Some variables and command arguments support internationalization via
CMake script. This is an optional feature.
Installers created by QtIFW tools have built-in support for
internationalization and many phrases are localized to many languages,
but this does not apply to the description of the your components and groups
that will be distributed.
Localization of the description of your components and groups is useful for
users of your installers.
A localized variable or argument can contain a single default value, and a
set of pairs the name of the locale and the localized value.
For example:
.. code-block:: cmake
set(LOCALIZABLE_VARIABLE "Default value"
en "English value"
en_US "American value"
en_GB "Great Britain value"
)
See Also
^^^^^^^^
@ -335,5 +343,5 @@ Qt Installer Framework Manual:
* Promoting Updates:
http://doc.qt.io/qtinstallerframework/ifw-updates.html
Download Qt Installer Framework for you platform from Qt site:
Download Qt Installer Framework for your platform from Qt site:
http://download.qt.io/official_releases/qt-installer-framework

33
Help/cpack_gen/nsis.rst
View File

@ -1,7 +1,9 @@
CPack NSIS Generator
--------------------
CPack Nullsoft Scriptable Install System (NSIS) generator specific options
CPack Nullsoft Scriptable Install System (NSIS) generator specific options.
The NSIS generator requires NSIS 3.0 or newer.
Variables specific to CPack NSIS generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -128,3 +130,32 @@ on Windows Nullsoft Scriptable Install System.
set(CPACK_NSIS_MENU_LINKS
"doc/cmake-@CMake_VERSION_MAJOR@.@CMake_VERSION_MINOR@/cmake.html"
"CMake Help" "https://cmake.org" "CMake Web Site")
.. variable:: CPACK_NSIS_UNINSTALL_NAME
Specify the name of the program to uninstall the version.
Default is ``Uninstall``.
.. variable:: CPACK_NSIS_WELCOME_TITLE
The title to display on the top of the page for the welcome page.
.. variable:: CPACK_NSIS_WELCOME_TITLE_3LINES
Display the title in the welcome page on 3 lines instead of 2.
.. variable:: CPACK_NSIS_FINISH_TITLE
The title to display on the top of the page for the finish page.
.. variable:: CPACK_NSIS_FINISH_TITLE_3LINES
Display the title in the finish page on 3 lines instead of 2.
.. variable:: CPACK_NSIS_MUI_HEADERIMAGE
The image to display on the header of installers pages.
.. variable:: CPACK_NSIS_MANIFEST_DPI_AWARE
If set, declares that the installer is DPI-aware.

58
Help/cpack_gen/packagemaker.rst
View File

@ -3,6 +3,11 @@ CPack PackageMaker Generator
PackageMaker CPack generator (macOS).
.. deprecated:: 3.17
Xcode no longer distributes the PackageMaker tools.
This CPack generator will be removed in a future version of CPack.
Variables specific to CPack PackageMaker generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -15,9 +20,60 @@ macOS using PackageMaker:
compatible with. Different versions of macOS support different
features. For example, CPack can only build component-based installers for
macOS 10.4 or newer, and can only build installers that download
component son-the-fly for macOS 10.5 or newer. If left blank, this value
components on-the-fly for macOS 10.5 or newer. If left blank, this value
will be set to the minimum version of macOS that supports the requested
features. Set this variable to some value (e.g., 10.4) only if you want to
guarantee that your installer will work on that version of macOS, and
don't mind missing extra features available in the installer shipping with
later versions of macOS.
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND
Adds a background to Distribtion XML if specified. The value contains the
path to image in ``Resources`` directory.
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_ALIGNMENT
Adds an ``alignment`` attribute to the background in Distribution XML.
Refer to Apple documentation for valid values.
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_SCALING
Adds a ``scaling`` attribute to the background in Distribution XML.
Refer to Apple documentation for valid values.
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_MIME_TYPE
Adds a ``mime-type`` attribute to the background in Distribution XML.
The option contains MIME type of an image.
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_UTI
Adds an ``uti`` attribute to the background in Distribution XML.
The option contains UTI type of an image.
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA
Adds a background for the Dark Aqua theme to Distribution XML if
specified. The value contains the path to image in ``Resources``
directory.
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_ALIGNMENT
Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_ALIGNMENT` option,
but for the dark theme.
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_SCALING
Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_SCALING` option,
but for the dark theme.
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_MIME_TYPE
Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_MIME_TYPE` option,
but for the dark theme.
.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_UTI
Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_UTI` option,
but for the dark theme.

52
Help/cpack_gen/productbuild.rst
View File

@ -58,7 +58,6 @@ macOS using ProductBuild:
component name. No ``postinstall`` script is added if this variable is not
defined for a given component.
.. variable:: CPACK_PRODUCTBUILD_RESOURCES_DIR
If specified the productbuild generator copies files from this directory
@ -66,3 +65,54 @@ macOS using ProductBuild:
before the :variable:`CPACK_RESOURCE_FILE_WELCOME`,
:variable:`CPACK_RESOURCE_FILE_README`, and
:variable:`CPACK_RESOURCE_FILE_LICENSE` files are copied.
.. variable:: CPACK_PRODUCTBUILD_BACKGROUND
Adds a background to Distribtion XML if specified. The value contains the
path to image in ``Resources`` directory.
.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_ALIGNMENT
Adds an ``alignment`` attribute to the background in Distribution XML.
Refer to Apple documentation for valid values.
.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_SCALING
Adds a ``scaling`` attribute to the background in Distribution XML.
Refer to Apple documentation for valid values.
.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_MIME_TYPE
Adds a ``mime-type`` attribute to the background in Distribution XML.
The option contains MIME type of an image.
.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_UTI
Adds an ``uti`` attribute to the background in Distribution XML.
The option contains UTI type of an image.
.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA
Adds a background for the Dark Aqua theme to Distribution XML if
specified. The value contains the path to image in ``Resources``
directory.
.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_ALIGNMENT
Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_ALIGNMENT` option,
but for the dark theme.
.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_SCALING
Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_SCALING` option,
but for the dark theme.
.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_MIME_TYPE
Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_MIME_TYPE` option,
but for the dark theme.
.. variable:: CPACK_PRODUCTBUILD_BACKGROUND_DARKAQUA_UTI
Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_UTI` option,
but for the dark theme.

28
Help/cpack_gen/rpm.rst
View File

@ -36,8 +36,8 @@ http://www.rpm.org/wiki/Docs
Here are some CPack RPM generator wiki resources that are here for historic
reasons and are no longer maintained but may still prove useful:
- https://gitlab.kitware.com/cmake/community/wikis/doc/cpack/Configuration
- https://gitlab.kitware.com/cmake/community/wikis/doc/cpack/PackageGenerators#rpm-unix-only
- https://gitlab.kitware.com/cmake/community/-/wikis/doc/cpack/Configuration
- https://gitlab.kitware.com/cmake/community/-/wikis/doc/cpack/PackageGenerators#rpm-unix-only
List of CPack RPM generator specific variables:
@ -473,38 +473,42 @@ List of CPack RPM generator specific variables:
.. variable:: CPACK_RPM_PRE_INSTALL_SCRIPT_FILE
CPACK_RPM_PRE_UNINSTALL_SCRIPT_FILE
CPACK_RPM_PRE_TRANS_SCRIPT_FILE
Path to file containing pre (un)install script.
Path to file containing pre install/uninstall/transaction script.
* Mandatory : NO
* Default : -
May be used to embed a pre (un)installation script in the spec file.
May be used to embed a pre installation/uninstallation/transaction script in the spec file.
The referred script file (or both) will be read and directly
put after the ``%pre`` or ``%preun`` section
If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the (un)install
If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the install/uninstall/transaction
script for each component can be overridden with
``CPACK_RPM_<COMPONENT>_PRE_INSTALL_SCRIPT_FILE`` and
``CPACK_RPM_<COMPONENT>_PRE_UNINSTALL_SCRIPT_FILE``.
``CPACK_RPM_<COMPONENT>_PRE_INSTALL_SCRIPT_FILE``,
``CPACK_RPM_<COMPONENT>_PRE_UNINSTALL_SCRIPT_FILE``, and
``CPACK_RPM_<COMPONENT>_PRE_TRANS_SCRIPT_FILE``
One may verify which scriptlet has been included with::
rpm -qp --scripts package.rpm
.. variable:: CPACK_RPM_POST_INSTALL_SCRIPT_FILE
CPACK_RPM_POST_UNINSTALL_SCRIPT_FILE
CPACK_RPM_POST_TRANS_SCRIPT_FILE
Path to file containing post (un)install script.
Path to file containing post install/uninstall/transaction script.
* Mandatory : NO
* Default : -
May be used to embed a post (un)installation script in the spec file.
May be used to embed a post installation/uninstallation/transaction script in the spec file.
The referred script file (or both) will be read and directly
put after the ``%post`` or ``%postun`` section.
If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the (un)install
If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the install/uninstall/transaction
script for each component can be overridden with
``CPACK_RPM_<COMPONENT>_POST_INSTALL_SCRIPT_FILE`` and
``CPACK_RPM_<COMPONENT>_POST_UNINSTALL_SCRIPT_FILE``.
``CPACK_RPM_<COMPONENT>_POST_INSTALL_SCRIPT_FILE``,
``CPACK_RPM_<COMPONENT>_POST_UNINSTALL_SCRIPT_FILE``, and
``CPACK_RPM_<COMPONENT>_POST_TRANS_SCRIPT_FILE``
One may verify which scriptlet has been included with::
rpm -qp --scripts package.rpm

18
Help/dev/maint.rst
View File

@ -14,6 +14,11 @@ Review a Merge Request
The `CMake Review Process`_ requires a maintainer to issue the ``Do: merge``
command to integrate a merge request. Please check at least the following:
* If the MR source branch (or part of it) should be backported
to the ``release`` branch (and is already based on a commit
contained in the ``release`` branch), add a ``Backport: release`` or
``Backport: release:<commit-ish>`` trailing line to the MR description.
* If the MR source branch is not named well for the change it makes
(e.g. it is just ``master`` or the patch changed during review),
add a ``Topic-rename: <topic>`` trailing line to the MR description
@ -38,9 +43,10 @@ command to integrate a merge request. Please check at least the following:
of various nightly builders.)
* Ensure that the MR targets the ``master`` branch. A MR intended for
the ``release`` branch should be based on ``release`` but still merged
to ``master`` first (via ``Do: merge``). A maintainer may then merge
the MR topic to ``release`` manually.
the ``release`` branch should be based on ``release`` but still target
``master``. Use the above-mentioned ``Backport: release`` line to tell
``Do: merge`` to merge to both. If a MR is merged without the backport
line, a maintainer may still merge the MR topic to ``release`` manually.
Maintain Current Release
========================
@ -51,6 +57,12 @@ using a local branch named ``release-$ver``, where ``$ver`` is the version
number of the current release in the form ``$major.$minor``. It is always
merged into ``master`` before publishing.
To merge an open MR to the ``release`` branch, edit its description to
use the ``Backport: release`` line mentioned above and then ``Do: merge``
normally. To update the ``release`` branch manually (e.g. to merge a
``$topic`` branch that was merged without the backport line), use the
following procedure.
Before merging a ``$topic`` branch into ``release``, verify that the
``$topic`` branch has already been merged to ``master`` via the usual
``Do: merge`` process. Then, to merge the ``$topic`` branch into

93
Help/dev/review.rst
View File

@ -28,7 +28,7 @@ request is accepted" option when creating the MR or by editing it.
This will cause the MR topic branch to be automatically removed from
the user's fork during the `Merge`_ step.
.. _`CMake Merge Requests Page`: https://gitlab.kitware.com/cmake/cmake/merge_requests
.. _`CMake Merge Requests Page`: https://gitlab.kitware.com/cmake/cmake/-/merge_requests
.. _`CMake Repository`: https://gitlab.kitware.com/cmake/cmake
Workflow Status
@ -53,10 +53,14 @@ in GitLab to track the state of a MR:
to a period of inactivity. See the `Expire`_ step. Use this label
after closing a MR for this reason.
* ``workflow:external-discussion`` indicates that the MR has been closed
pending discussion elsewhere. See the `External Discussion`_ step.
Use this label after closing a MR for this reason.
The workflow status labels are intended to be mutually exclusive,
so please remove any existing workflow label when adding one.
.. _`CMake GitLab Project Developers`: https://gitlab.kitware.com/cmake/cmake/settings/members
.. _`CMake GitLab Project Developers`: https://gitlab.kitware.com/cmake/cmake/-/settings/members
Robot Review
============
@ -274,42 +278,52 @@ merging.
Topic Testing
=============
CMake has a `buildbot`_ instance watching for merge requests to test.
`CMake GitLab Project Developers`_ may activate buildbot on a MR by
adding a comment with a command among the `comment trailing lines`_::
CMake uses `GitLab CI`_ to test merge requests, configured by the top-level
``.gitlab-ci.yml`` file. Results may be seen both on the merge request's
pipeline page and on the `CMake CDash Page`_. Filtered CDash results
showing just the pipeline's jobs can be reached by selecting the ``cdash``
job in the ``External`` stage of the pipeline.
Do: test
Lint and documentation build jobs run automatically after every push.
Heavier jobs require a manual trigger to run:
``@kwrobot`` will add an award emoji to the comment to indicate that it
was processed and also inform buildbot about the request. The buildbot
user (``@buildbot``) will schedule builds and respond with a comment
linking to the `CMake CDash Page`_ with a filter for results associated
with the topic test request. If the MR topic branch is updated by a
push a new ``Do: test`` command is needed to activate testing again.
* Merge request authors may visit their merge request's pipeline and click the
"Play" button on one or more jobs manually. If the merge request has the
"Allow commits from members who can merge to the target branch" check box
enabled, CMake maintainers may use the "Play" button too.
The ``Do: test`` command accepts the following arguments:
* `CMake GitLab Project Developers`_ may trigger CI on a merge request by
adding a comment with a command among the `comment trailing lines`_::
* ``--stop``: clear the list of commands for the merge request
* ``--clear``: clear previous commands before adding this command
* ``--regex-include <arg>`` or ``-i <arg>``: only build on builders
matching ``<arg>`` (a Python regular expression)
* ``--regex-exclude <arg>`` or ``-e <arg>``: exclude builds on builders
matching ``<arg>`` (a Python regular expression)
Do: test
Builder names follow the pattern ``project-host-os-buildtype-generator``:
``@kwrobot`` will add an award emoji to the comment to indicate that it
was processed and also trigger all manual jobs in the merge request's
pipeline.
* ``project``: always ``cmake`` for CMake builds
* ``host``: the buildbot host
* ``os``: one of ``windows``, ``osx``, or ``linux``
* ``buildtype``: ``release`` or ``debug``
* ``generator``: ``ninja``, ``makefiles``, ``vs<year>``,
or ``lint-iwyu-tidy``
The ``Do: test`` command accepts the following arguments:
The special ``lint-<tools>`` generator name is a builder that builds
CMake using lint tools but does not run the test suite (so the actual
generator does not matter).
* ``--named <regex>``, ``-n <regex>``: Trigger jobs matching ``<regex>``
anywhere in their name. Job names may be seen on the merge request's
pipeline page.
* ``--stage <stage>``, ``-s <stage>``: Only affect jobs in a given stage.
Stage names may be seen on the merge request's pipeline page. Note that
the names are determined by what is in the ``.gitlab-ci.yml`` file and may
be capitalized in the web page, so lowercasing the webpage's display name
for stages may be required.
* ``--action <action>``, ``-a <action>``: The action to perform on the jobs.
Possible actions:
.. _`buildbot`: http://buildbot.net
* ``manual`` (the default): Start jobs awaiting manual interaction.
* ``unsuccessful``: Start or restart jobs which have not completed
successfully.
* ``failed``: Restart jobs which have completed, but without success.
* ``completed``: Restart all completed jobs.
If the merge request topic branch is updated by a push, a new manual trigger
using one of the above methods is needed to start CI again.
.. _`GitLab CI`: https://gitlab.kitware.com/help/ci/README.md
.. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake
Integration Testing
@ -429,13 +443,30 @@ Additionally, ``Do: merge`` extracts configuration from trailing lines
in the MR description (the following have no effect if used in a MR
comment instead):
* ``Backport: release[:<commit-ish>]``: merge the topic branch into
the ``release`` branch to backport the change. This is allowed
only if the topic branch is based on a commit in ``release`` already.
If only part of the topic branch should be backported, specify it as
``:<commit-ish>``. The ``<commit-ish>`` may use `git rev-parse`_
syntax to reference commits relative to the topic ``HEAD``.
See additional `backport instructions`_ for details.
For example:
``Backport: release``
Merge the topic branch head into both ``release`` and ``master``.
``Backport: release:HEAD~1^2``
Merge the topic branch head's parent's second parent commit into
the ``release`` branch. Merge the topic branch head to ``master``.
* ``Topic-rename: <topic>``: substitute ``<topic>`` for the name of
the MR topic branch in the constructed merge commit message.
It is also used in merge commits constructed by ``Do: stage``.
The ``-t`` option to a ``Do: merge`` command overrides any topic
rename set in the MR description.
.. _`CMake GitLab Project Masters`: https://gitlab.kitware.com/cmake/cmake/settings/members
.. _`CMake GitLab Project Masters`: https://gitlab.kitware.com/cmake/cmake/-/settings/members
.. _`backport instructions`: https://gitlab.kitware.com/utils/git-workflow/-/wikis/Backport-topics
.. _`git rev-parse`: https://git-scm.com/docs/git-rev-parse
Close
-----

162
Help/dev/source.rst
View File

@ -23,12 +23,157 @@ format only a subset of files, such as those that are locally modified.
C++ Subset Permitted
====================
CMake requires compiling as C++11 or above. However, in order to support
building on older toolchains some constructs need to be handled with care:
CMake requires compiling as C++11 in order to support building on older
toolchains. However, to facilitate development, some standard library
features from more recent C++ standards are supported through a compatibility
layer. These features are defined under the namespace ``cm`` and headers
are accessible under the ``cm/`` directory. The headers under ``cm/`` can
be used in place of the standard ones when extended features are needed.
For example ``<cm/memory>`` can be used in place of ``<memory>``.
* Do not use ``std::auto_ptr``.
Available features are:
The ``std::auto_ptr`` template is deprecated in C++11. Use ``std::unique_ptr``.
* From ``C++14``:
* ``<cm/iterator>``:
``cm::make_reverse_iterator``, ``cm::cbegin``, ``cm::cend``,
``cm::rbegin``, ``cm::rend``, ``cm::crbegin``, ``cm::crend``
* ``<cm/memory>``:
``cm::make_unique``
* ``<cm/shared_mutex>``:
``cm::shared_lock``
* ``<cm/type_traits>``:
``cm::enable_if_t``
* From ``C++17``:
* ``<cm/algorithm>``:
``cm::clamp``
* ``<cm/iterator>``:
``cm::size``, ``cm::empty``, ``cm::data``
* ``<cm/optional>``:
``cm::nullopt_t``, ``cm::nullopt``, ``cm::optional``,
``cm::make_optional``, ``cm::bad_optional_access``
* ``<cm/shared_mutex>``:
``cm::shared_mutex``
* ``<cm/string_view>``:
``cm::string_view``
* ``<cm/type_traits>``:
``cm::bool_constant``, ``cm::invoke_result_t``, ``cm::invoke_result``,
``cm::void_t``
* ``<cm/utility>``:
``cm::in_place_t``, ``cm::in_place``
* From ``C++20``:
* ``<cm/deque>``:
``cm::erase``, ``cm::erase_if``
* ``<cm/list>``:
``cm::erase``, ``cm::erase_if``
* ``<cm/map>`` :
``cm::erase_if``
* ``<cm/set>`` :
``cm::erase_if``
* ``<cm/string>``:
``cm::erase``, ``cm::erase_if``
* ``<cm/unordered_map>``:
``cm::erase_if``
* ``<cm/unordered_set>``:
``cm::erase_if``
* ``<cm/vector>``:
``cm::erase``, ``cm::erase_if``
Additionally, some useful non-standard extensions to the C++ standard library
are available in headers under the directory ``cmext/`` in namespace ``cm``.
These are:
* ``<cmext/algorithm>``:
* ``cm::append``:
Append elements to a sequential container.
* ``cm::contains``:
Checks if element or key is contained in container.
* ``<cmext/iterator>``:
* ``cm::is_terator``:
Checks if a type is an iterator type.
* ``cm::is_input_iterator``:
Checks if a type is an input iterator type.
* ``cm::is_range``:
Checks if a type is a range type: functions ``std::begin()`` and
``std::end()`` apply.
* ``cm::is_input_range``:
Checks if a type is an input range type: functions ``std::begin()`` and
``std::end()`` apply and return an input iterator.
* ``<cmext/memory>``:
* ``cm::static_reference_cast``:
Apply a ``static_cast`` to a smart pointer.
* ``cm::dynamic_reference_cast``:
Apply a ``dynamic_cast`` to a smart pointer.
* ``<cmext/type_traits>``:
* ``cm::is_container``:
Checks if a type is a container type.
* ``cm::is_associative_container``:
Checks if a type is an associative container type.
* ``cm::is_unordered_associative_container``:
Checks if a type is an unordered associative container type.
* ``cm::is_sequence_container``:
Checks if a type is a sequence container type.
* ``cm::is_unique_ptr``:
Checks if a type is a ``std::unique_ptr`` type.
Dynamic Memory Management
=========================
To ensure efficient memory management, i.e. no memory leaks, it is required
to use smart pointers. Any dynamic memory allocation must be handled by a
smart pointer such as ``std::unique_ptr`` or ``std::shared_ptr``.
It is allowed to pass raw pointers between objects to enable objects sharing.
A raw pointer **must** not be deleted. Only the object(s) owning the smart
pointer are allowed to delete dynamically allocated memory.
Third Parties
=============
To build CMake, some third parties are needed. Under ``Utilities``
directory, are versions of these third parties which can be used as an
alternate to the ones provided by the system.
To enable the selection of the third parties between the system and CMake ones,
in CMake sources, third parties headers must be prefixed by ``cm3p/``
(for example: ``<cm3p/json/reader.h>``). These wrappers are located under
``Utilities/cm3p`` directory.
Source Tree Layout
==================
@ -69,6 +214,15 @@ The CMake source tree is organized as follows.
* ``Utilities/``:
Scripts, third-party source code.
* ``Utilities/std/cm``:
Support files for various C++ standards.
* ``Utilities/std/cmext``:
Extensions to the C++ STL.
* ``Utilities/cm3p``:
Public headers for third parties needed to build CMake.
* ``Utilities/Sphinx/``:
Sphinx configuration to build CMake user documentation.

2
Help/dev/testing.rst
View File

@ -33,7 +33,7 @@ CTest script with local settings and include ``cmake_common.cmake``.
.. _`CMake Review Process`: review.rst
.. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake
.. _`CMake Dashboard Scripts Repository`: https://gitlab.kitware.com/cmake/dashboard-scripts
.. _`cmake_common.cmake`: https://gitlab.kitware.com/cmake/dashboard-scripts/blob/master/cmake_common.cmake
.. _`cmake_common.cmake`: https://gitlab.kitware.com/cmake/dashboard-scripts/-/blob/master/cmake_common.cmake
Nightly Start Time
------------------

2
Help/envvar/ASM_DIALECTFLAGS.rst
View File

@ -11,3 +11,5 @@ 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.
See also :variable:`CMAKE_ASM<DIALECT>_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

34
Help/envvar/CCMAKE_COLORS.rst Normal file
View File

@ -0,0 +1,34 @@
CCMAKE_COLORS
-------------
Determines what colors are used by the CMake curses interface,
when run on a terminal that supports colors.
The syntax follows the same conventions as ``LS_COLORS``;
that is, a list of key/value pairs separated by ``:``.
Keys are a single letter corresponding to a CMake cache variable type:
- ``s``: A ``STRING``.
- ``p``: A ``FILEPATH``.
- ``c``: A value which has an associated list of choices.
- ``y``: A ``BOOL`` which has a true-like value (e.g. ``ON``, ``YES``).
- ``n``: A ``BOOL`` which has a false-like value (e.g. ``OFF``, ``NO``).
Values are an integer number that specifies what color to use.
``0`` is black (you probably don't want to use that).
Others are determined by your terminal's color support.
Most (color) terminals will support at least 8 or 16 colors.
Some will support up to 256 colors. The colors will likely match
`this chart <https://upload.wikimedia.org/wikipedia/commons/1/15/Xterm_256color_chart.svg>`_,
although the first 16 colors may match the original
`CGA color palette <https://en.wikipedia.org/wiki/Color_Graphics_Adapter#Color_palette>`_.
(Many modern terminal emulators also allow their color palette,
at least for the first 16 colors, to be configured by the user.)
Note that fairly minimal checking is done for bad colors
(although a value higher than what curses believes your terminal supports
will be silently ignored) or bad syntax.
For example::
CCMAKE_COLORS='s=39:p=220:c=207:n=196:y=46'

2
Help/envvar/CFLAGS.rst
View File

@ -9,3 +9,5 @@ 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.
See also :variable:`CMAKE_C_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

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

@ -0,0 +1,9 @@
CMAKE_EXPORT_COMPILE_COMMANDS
-----------------------------
.. include:: ENV_VAR.txt
The default value for :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` when there
is no explicit configuration given on the first run while creating a new
build tree. On later runs in an existing build tree the value persists in
the cache as :variable:`CMAKE_EXPORT_COMPILE_COMMANDS`.

10
Help/envvar/CMAKE_LANG_COMPILER_LAUNCHER.rst Normal file
View File

@ -0,0 +1,10 @@
CMAKE_<LANG>_COMPILER_LAUNCHER
------------------------------
.. include:: ENV_VAR.txt
Default compiler launcher to use for the specified language. Will only be used
by CMake to initialize the variable on the first configuration. Afterwards, it
is available through the cache setting of the variable of the same name. For
any configuration run (including the first), the environment variable will be
ignored if the :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable is defined.

17
Help/envvar/CMAKE_PREFIX_PATH.rst Normal file
View File

@ -0,0 +1,17 @@
CMAKE_PREFIX_PATH
-----------------
.. include:: ENV_VAR.txt
The ``CMAKE_PREFIX_PATH`` environment variable may be set to a list of
directories specifying installation *prefixes* to be searched by the
:command:`find_package`, :command:`find_program`, :command:`find_library`,
:command:`find_file`, and :command:`find_path` commands. Each command will
add appropriate subdirectories (like ``bin``, ``lib``, or ``include``)
as specified in its own documentation.
This variable may hold a single prefix or a list of prefixes separated
by ``:`` on UNIX or ``;`` on Windows (the same as the ``PATH`` environment
variable convention on those platforms).
See also the :variable:`CMAKE_PREFIX_PATH` CMake variable.

2
Help/envvar/CSFLAGS.rst
View File

@ -9,3 +9,5 @@ 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.
See also :variable:`CMAKE_CSharp_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

2
Help/envvar/CUDAFLAGS.rst
View File

@ -9,3 +9,5 @@ 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.
See also :variable:`CMAKE_CUDA_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

2
Help/envvar/CXXFLAGS.rst
View File

@ -9,3 +9,5 @@ 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.
See also :variable:`CMAKE_CXX_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

2
Help/envvar/FFLAGS.rst
View File

@ -9,3 +9,5 @@ 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.
See also :variable:`CMAKE_Fortran_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

14
Help/envvar/OBJC.rst Normal file
View File

@ -0,0 +1,14 @@
OBJC
----
.. include:: ENV_VAR.txt
Preferred executable for compiling ``OBJC`` language files. Will only be used
by CMake on the first configuration to determine ``OBJC`` compiler, after
which the value for ``OBJC`` is stored in the cache as
:variable:`CMAKE_OBJC_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration
run (including the first), the environment variable will be ignored if the
:variable:`CMAKE_OBJC_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined.
If ``OBJC`` is not defined, the :envvar:`CC` environment variable will
be checked instead.

14
Help/envvar/OBJCXX.rst Normal file
View File

@ -0,0 +1,14 @@
OBJCXX
------
.. include:: ENV_VAR.txt
Preferred executable for compiling ``OBJCXX`` language files. Will only be used
by CMake on the first configuration to determine ``OBJCXX`` compiler, after
which the value for ``OBJCXX`` is stored in the cache as
:variable:`CMAKE_OBJCXX_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration
run (including the first), the environment variable will be ignored if the
:variable:`CMAKE_OBJCXX_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined.
If ``OBJCXX`` is not defined, the :envvar:`CXX` environment variable will
be checked instead.

2
Help/envvar/RCFLAGS.rst
View File

@ -9,3 +9,5 @@ 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.
See also :variable:`CMAKE_RC_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`.

87
Help/generator/Ninja Multi-Config.rst Normal file
View File

@ -0,0 +1,87 @@
Ninja Multi-Config
------------------
Generates multiple ``build-<Config>.ninja`` files.
This generator is very much like the :generator:`Ninja` generator, but with
some key differences. Only these differences will be discussed in this
document.
Unlike the :generator:`Ninja` generator, ``Ninja Multi-Config`` generates
multiple configurations at once with :variable:`CMAKE_CONFIGURATION_TYPES`
instead of only one configuration with :variable:`CMAKE_BUILD_TYPE`. One
``build-<Config>.ninja`` file will be generated for each of these
configurations (with ``<Config>`` being the configuration name.) These files
are intended to be run with ``ninja -f build-<Config>.ninja``. A
``build.ninja`` file is also generated, using the configuration from either
:variable:`CMAKE_DEFAULT_BUILD_TYPE` or the first item from
: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
default to ``build-Debug.ninja``, unless a ``build.ninja`` is generated (see
below), in which case that will be used instead.
Each ``build-<Config>.ninja`` file contains ``<target>`` targets as well as
``<target>:<Config>`` targets, where ``<Config>`` is the same as the
configuration specified in ``build-<Config>.ninja`` Additionally, if
cross-config mode is enabled, ``build-<Config>.ninja`` may contain
``<target>:<OtherConfig>`` targets, where ``<OtherConfig>`` is a cross-config,
as well as ``<target>:all``, which builds the target in all cross-configs. See
below for how to enable cross-config mode.
The ``Ninja Multi-Config`` generator recognizes the following variables:
:variable:`CMAKE_CONFIGURATION_TYPES`
Specifies the total set of configurations to build.
:variable:`CMAKE_CROSS_CONFIGS`
Specifies a :ref:`semicolon-separated list <CMake Language Lists>` of
configurations available from all ``build-<Config>.ninja`` files.
:variable:`CMAKE_DEFAULT_BUILD_TYPE`
Specifies the configuration to use by default in a ``build.ninja`` file.
:variable:`CMAKE_DEFAULT_CONFIGS`
Specifies a :ref:`semicolon-separated list <CMake Language Lists>` of
configurations to build for a target in ``build.ninja``
if no ``:<Config>`` suffix is specified.
Consider the following example:
.. code-block:: cmake
cmake_minimum_required(VERSION 3.16)
project(MultiConfigNinja C)
add_executable(generator generator.c)
add_custom_command(OUTPUT generated.c COMMAND generator generated.c)
add_library(generated ${CMAKE_BINARY_DIR}/generated.c)
Now assume you configure the project with ``Ninja Multi-Config`` and run one of
the following commands:
.. code-block:: shell
ninja -f build-Debug.ninja generated
# OR
cmake --build . --config Debug --target generated
This would build the ``Debug`` configuration of ``generator``, which would be
used to generate ``generated.c``, which would be used to build the ``Debug``
configuration of ``generated``.
But if :variable:`CMAKE_CROSS_CONFIGS` is set to ``all``, and you run the
following instead:
.. code-block:: shell
ninja -f build-Release.ninja generated:Debug
# OR
cmake --build . --config Release --target generated:Debug
This would build the ``Release`` configuration of ``generator``, which would be
used to generate ``generated.c``, which would be used to build the ``Debug``
configuration of ``generated``. This is useful for running a release-optimized
version of a generator utility while still building the debug version of the
targets built with the generated code.

12
Help/generator/Ninja.rst
View File

@ -1,7 +1,7 @@
Ninja
-----
Generates build.ninja files.
Generates ``build.ninja`` files.
A ``build.ninja`` file is generated into the build tree. Use the ninja
program to build the project through the ``all`` target and install the
@ -33,8 +33,10 @@ Fortran Support
^^^^^^^^^^^^^^^
The ``Ninja`` generator conditionally supports Fortran when the ``ninja``
tool has the required features. As of this version of CMake the needed
features have not been integrated into upstream Ninja. Kitware maintains
a branch of Ninja with the required features on `github.com/Kitware/ninja`_.
tool is at least version 1.10 (which has the required features).
.. _`github.com/Kitware/ninja`: https://github.com/Kitware/ninja/tree/features-for-fortran#readme
See Also
^^^^^^^^
The :generator:`Ninja Multi-Config` generator is similar to the ``Ninja``
generator, but generates multiple configurations at once.

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

@ -3,6 +3,8 @@ cmake_minimum_required(VERSION 3.15)
# set the project name and version
project(Tutorial VERSION 1.0)
set(CMAKE_DEBUG_POSTFIX d)
add_library(tutorial_compiler_flags INTERFACE)
target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11)
@ -37,6 +39,8 @@ add_subdirectory(MathFunctions)
# add the executable
add_executable(Tutorial tutorial.cxx)
set_target_properties(Tutorial PROPERTIES DEBUG_POSTFIX ${CMAKE_DEBUG_POSTFIX})
target_link_libraries(Tutorial PUBLIC MathFunctions)
# add the binary tree to the search path for include files

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

@ -17,7 +17,7 @@ if(USE_MYMATH)
# first we add the executable that generates the table
add_executable(MakeTable MakeTable.cxx)
target_link_libraries(MakeTable tutorial_compiler_flags)
target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags)
# add the command to generate the source code
add_custom_command(

1
Help/guide/tutorial/MultiPackage/MultiCPackConfig.cmake → Help/guide/tutorial/Complete/MultiCPackConfig.cmake
View File

@ -1,4 +1,3 @@
include("release/CPackConfig.cmake")
set(CPACK_INSTALL_CMAKE_PROJECTS

4
Help/guide/tutorial/Complete/tutorial.cxx
View File

@ -1,6 +1,5 @@
// A simple program that computes the square root of a number
#include <iostream>
#include <sstream>
#include <string>
#include "MathFunctions.h"
@ -9,6 +8,7 @@
int main(int argc, char* argv[])
{
if (argc < 2) {
// report version
std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
<< Tutorial_VERSION_MINOR << std::endl;
std::cout << "Usage: " << argv[0] << " number" << std::endl;
@ -18,8 +18,8 @@ int main(int argc, char* argv[])
// convert input to double
const double inputValue = std::stod(argv[1]);
// calculate square root
const double outputValue = mathfunctions::sqrt(inputValue);
std::cout << "The square root of " << inputValue << " is " << outputValue
<< std::endl;
return 0;

51
Help/guide/tutorial/Consumer/CMakeLists.txt
View File

@ -1,51 +0,0 @@
cmake_minimum_required(VERSION 3.10)
if(NOT DEFINED CMAKE_CXX_STANDARD)
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED True)
endif()
function(find_external_dependency name)
set(${name}_ROOT "" CACHE PATH "Root directory to find ${name}")
mark_as_advanced(${name}_DIR)
find_package(${name} PATHS ${${name}_ROOT} REQUIRED)
endfunction()
project(Consumer)
find_external_dependency(MathFunctions)
add_library(consumer consumer.cxx)
target_link_libraries(consumer PUBLIC MathFunctions)
# install the consumer library
install(TARGETS consumer DESTINATION bin EXPORT ConsumerTargets)
# install the configuration targets
install(EXPORT ConsumerTargets
FILE ConsumerTargets.cmake
DESTINATION lib/cmake/Consumer
)
include(CMakePackageConfigHelpers)
# generate the config file that is includes the exports
configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in
"${CMAKE_CURRENT_BINARY_DIR}/ConsumerConfig.cmake"
INSTALL_DESTINATION "lib/cmake/example"
NO_SET_AND_CHECK_MACRO
NO_CHECK_REQUIRED_COMPONENTS_MACRO
)
# install the configuration file
install(FILES
${CMAKE_CURRENT_BINARY_DIR}/ConsumerConfig.cmake
DESTINATION lib/cmake/Consumer
)
# generate the export targets for the build tree
# needs to be after the install(TARGETS ) command
export(EXPORT ConsumerTargets
FILE "${CMAKE_CURRENT_BINARY_DIR}/ConsumerTargets.cmake"
)

14
Help/guide/tutorial/Consumer/Config.cmake.in
View File

@ -1,14 +0,0 @@
@PACKAGE_INIT@
include(CMakeFindDependencyMacro)
function(find_external_dependency name)
set(${name}_ROOT "" CACHE PATH "Root directory to find ${name}")
mark_as_advanced(${name}_DIR)
find_dependency(${name} PATHS ${${name}_ROOT} REQUIRED)
endfunction()
find_external_dependency(MathFunctions)
include ( "${CMAKE_CURRENT_LIST_DIR}/ConsumerTargets.cmake" )

11
Help/guide/tutorial/Consumer/consumer.cxx
View File

@ -1,11 +0,0 @@
// A simple function that computes the square root of a number
#include <iostream>
#include <sstream>
#include <string>
#include "MathFunctions.h"
double string_square_root(std::string const& value)
{
return mathfunctions::sqrt(std::stod(value));
}

2
Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt
View File

@ -15,7 +15,7 @@ if(USE_MYMATH)
# first we add the executable that generates the table
add_executable(MakeTable MakeTable.cxx)
target_link_libraries(MakeTable tutorial_compiler_flags)
target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags)
# add the command to generate the source code
add_custom_command(

14
Help/guide/tutorial/MultiPackage/CMakeLists.txt → Help/guide/tutorial/Step12/CMakeLists.txt
View File

@ -1,11 +1,19 @@
cmake_minimum_required(VERSION 3.10)
cmake_minimum_required(VERSION 3.15)
# set the project name and version
project(Tutorial VERSION 1.0)
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED True)
add_library(tutorial_compiler_flags INTERFACE)
target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11)
# add compiler warning flags just when building this project via
# the BUILD_INTERFACE genex
set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU>")
set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>")
target_compile_options(tutorial_compiler_flags INTERFACE
"$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>"
"$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>"
)
# control where the static and shared libraries are built so that on windows
# we don't need to tinker with the path to run the executable

7
Help/guide/tutorial/Step12/CTestConfig.cmake Normal file
View File

@ -0,0 +1,7 @@
set(CTEST_PROJECT_NAME "CMakeTutorial")
set(CTEST_NIGHTLY_START_TIME "00:00:00 EST")
set(CTEST_DROP_METHOD "http")
set(CTEST_DROP_SITE "my.cdash.org")
set(CTEST_DROP_LOCATION "/submit.php?project=CMakeTutorial")
set(CTEST_DROP_SITE_CDASH TRUE)

0
Help/guide/tutorial/MultiPackage/Config.cmake.in → Help/guide/tutorial/Step12/Config.cmake.in
View File

0
Help/guide/tutorial/MultiPackage/License.txt → Help/guide/tutorial/Step12/License.txt
View File

10
Help/guide/tutorial/MultiPackage/MathFunctions/CMakeLists.txt → Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt
View File

@ -17,6 +17,7 @@ if(USE_MYMATH)
# first we add the executable that generates the table
add_executable(MakeTable MakeTable.cxx)
target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags)
# add the command to generate the source code
add_custom_command(
@ -41,19 +42,18 @@ if(USE_MYMATH)
POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS}
)
target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags)
target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
endif()
target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)
# define the symbol stating we are using the declspec(dllexport) when
# building on windows
target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")
# setup the version numbering
set_property(TARGET MathFunctions PROPERTY VERSION "1.0.0")
set_property(TARGET MathFunctions PROPERTY SOVERSION "1")
# install rules
install(TARGETS MathFunctions
install(TARGETS MathFunctions tutorial_compiler_flags
DESTINATION lib
EXPORT MathFunctionsTargets)
install(FILES MathFunctions.h DESTINATION include)

0
Help/guide/tutorial/MultiPackage/MathFunctions/MakeTable.cxx → Help/guide/tutorial/Step12/MathFunctions/MakeTable.cxx
View File

0
Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.cxx → Help/guide/tutorial/Step12/MathFunctions/MathFunctions.cxx
View File

0
Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.h → Help/guide/tutorial/Step12/MathFunctions/MathFunctions.h
View File

3
Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.cxx → Help/guide/tutorial/Step12/MathFunctions/mysqrt.cxx
View File

@ -17,11 +17,10 @@ double mysqrt(double x)
// use the table to help find an initial value
double result = x;
if (x >= 1 && x < 10) {
std::cout << "Use the table to help find an initial value " << std::endl;
result = sqrtTable[static_cast<int>(x)];
}
// if we have both log and exp then use them
// do ten iterations
for (int i = 0; i < 10; ++i) {
if (result <= 0) {

0
Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.h → Help/guide/tutorial/Step12/MathFunctions/mysqrt.h
View File

2
Help/guide/tutorial/MultiPackage/TutorialConfig.h.in → Help/guide/tutorial/Step12/TutorialConfig.h.in
View File

@ -1,3 +1,3 @@
// the configured version number
// the configured options and settings for Tutorial
#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@
#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@

3
Help/guide/tutorial/MultiPackage/tutorial.cxx → Help/guide/tutorial/Step12/tutorial.cxx
View File

@ -8,6 +8,7 @@
int main(int argc, char* argv[])
{
if (argc < 2) {
// report version
std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
<< Tutorial_VERSION_MINOR << std::endl;
std::cout << "Usage: " << argv[0] << " number" << std::endl;
@ -15,7 +16,7 @@ int main(int argc, char* argv[])
}
// convert input to double
double inputValue = std::stod(argv[1]);
const double inputValue = std::stod(argv[1]);
const double outputValue = mathfunctions::sqrt(inputValue);

25
Help/guide/tutorial/Step5/MathFunctions/MakeTable.cxx
View File

@ -1,25 +0,0 @@
// A simple program that builds a sqrt table
#include <cmath>
#include <fstream>
#include <iostream>
int main(int argc, char* argv[])
{
// make sure we have enough arguments
if (argc < 2) {
return 1;
}
std::ofstream fout(argv[1], std::ios_base::out);
const bool fileOpen = fout.is_open();
if (fileOpen) {
fout << "double sqrtTable[] = {" << std::endl;
for (int i = 0; i < 10; ++i) {
fout << sqrt(static_cast<double>(i)) << "," << std::endl;
}
// close the table with a zero
fout << "0};" << std::endl;
fout.close();
}
return fileOpen ? 0 : 1; // return 0 if wrote the file
}

12
Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt
View File

@ -8,10 +8,20 @@ target_include_directories(MathFunctions
# does this system provide the log and exp functions?
include(CheckSymbolExists)
set(CMAKE_REQUIRED_LIBRARIES "m")
check_symbol_exists(log "math.h" HAVE_LOG)
check_symbol_exists(exp "math.h" HAVE_EXP)
if(NOT (HAVE_LOG AND HAVE_EXP))
unset(HAVE_LOG CACHE)
unset(HAVE_EXP CACHE)
set(CMAKE_REQUIRED_LIBRARIES "m")
check_symbol_exists(log "math.h" HAVE_LOG)
check_symbol_exists(exp "math.h" HAVE_EXP)
if(HAVE_LOG AND HAVE_EXP)
target_link_libraries(MathFunctions PRIVATE m)
endif()
endif()
# add compile definitions
if(HAVE_LOG AND HAVE_EXP)
target_compile_definitions(MathFunctions
PRIVATE "HAVE_LOG" "HAVE_EXP")

387
Help/guide/tutorial/index.rst
View File

@ -45,7 +45,8 @@ 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.
First, modify the ``CMakeLists.txt`` file to set the version number.
First, modify the ``CMakeLists.txt`` file to use the :command:`project` command
to set the project name and version number.
.. literalinclude:: Step2/CMakeLists.txt
:language: cmake
@ -102,9 +103,10 @@ Next let's add some C++11 features to our project by replacing ``atof`` with
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 ``CMAKE_CXX_STANDARD`` variable. For this tutorial,
set the ``CMAKE_CXX_STANDARD`` variable in the ``CMakeLists.txt`` file to 11
and ``CMAKE_CXX_STANDARD_REQUIRED`` to True:
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:
.. literalinclude:: Step2/CMakeLists.txt
:language: cmake
@ -113,7 +115,8 @@ and ``CMAKE_CXX_STANDARD_REQUIRED`` to True:
Build and Test
--------------
Run **cmake** or **cmake-gui** to configure the project and then build it
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.
For example, from the command line we could navigate to the
@ -156,11 +159,11 @@ directory:
.. literalinclude:: Step3/MathFunctions/CMakeLists.txt
:language: cmake
To make use of the new library we will add an ``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 ``mqsqrt.h`` header file can be found. The last few lines
of the top-level ``CMakeLists.txt`` file should now look like:
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 ``mqsqrt.h`` header file can be found. The
last few lines of the top-level ``CMakeLists.txt`` file should now look like:
.. code-block:: cmake
@ -180,7 +183,7 @@ of the top-level ``CMakeLists.txt`` file should now look like:
)
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
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.
@ -189,10 +192,11 @@ occurrence. The first step is to add an option to the top-level
:start-after: # should we use our own math functions
:end-before: # add the MathFunctions library
This option will be displayed in the CMake GUI and ccmake 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.
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 change the end of the top-level ``CMakeLists.txt``
@ -234,11 +238,13 @@ Since the source code now requires ``USE_MYMATH`` we can add it to
**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?
Run **cmake** or **cmake-gui** to configure the project and then build it
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.
Use ccmake or the CMake GUI to update the value of ``USE_MYMATH``. Rebuild and
run the tutorial again. Which function gives better results, sqrt or mysqrt?
Use the :manual:`ccmake <ccmake(1)>` executable or the :manual:`cmake-gui <cmake-gui(1)>`
to update the value of ``USE_MYMATH``. Rebuild and run the tutorial again.
Which function gives better results, sqrt or mysqrt?
Adding Usage Requirements for Library (Step 3)
==============================================
@ -248,19 +254,20 @@ 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:
- ``target_compile_definitions``
- ``target_compile_options``
- ``target_include_directories``
- ``target_link_libraries``
- :command:`target_compile_definitions`
- :command:`target_compile_options`
- :command:`target_include_directories`
- :command:`target_link_libraries`
Let's refactor our code from `Adding a Library (Step 2)`_ 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
MathFunctions itself doesn't. So this can become an ``INTERFACE`` usage
requirement.
Remember ``INTERFACE`` means things that consumers require but the producer
doesn't. Add the following lines to the end of ``MathFunctions/CMakeLists.txt``:
doesn't. Add the following lines to the end of
``MathFunctions/CMakeLists.txt``:
.. literalinclude:: Step4/MathFunctions/CMakeLists.txt
:language: cmake
@ -281,9 +288,10 @@ And here:
:language: cmake
:start-after: # so that we will find TutorialConfig.h
Once this is done, run **cmake** or **cmake-gui** to configure the project
and then build it with your chosen build tool or by using ``cmake --build .``
from the build directory.
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.
Installing and Testing (Step 4)
===============================
@ -312,16 +320,17 @@ And to the end of the top-level ``CMakeLists.txt`` we add:
That is all that is needed to create a basic local install of the tutorial.
Run **cmake** or **cmake-gui** to configure the project and then build it
with your chosen build tool. Run the install step by typing
``cmake --install .`` (introduced in 3.15, older versions of CMake must use
``make install``) from the command line, or build the ``INSTALL`` target from
an IDE. This will install the appropriate header files, libraries, and
executables.
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. 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, or build
the ``INSTALL`` target from an IDE. This will install the appropriate header
files, libraries, and executables.
The CMake variable ``CMAKE_INSTALL_PREFIX`` is used to determine the root of
where the files will be installed. If using ``cmake --install`` a custom
installation directory can be given via ``--prefix`` argument. For
The CMake variable :variable:`CMAKE_INSTALL_PREFIX` is used to determine the
root of where the files will be installed. If using ``cmake --install`` a
custom installation directory can be given via the ``--prefix`` argument. For
multi-configuration tools, use the ``--config`` argument to specify the
configuration.
@ -339,25 +348,25 @@ the application is working correctly.
:start-after: # enable testing
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.
otherwise crash, and has a zero return value. This is the basic form of a
CTest test.
The next test makes use of the ``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.
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.
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.
Rebuild the application and then cd to the binary directory and run
``ctest -N`` and ``ctest -VV``. For multi-config generators (e.g. Visual
Studio), the configuration type must be specified. To run tests in Debug mode,
for example, use ``ctest -C Debug -VV`` from the build directory (not the
Debug subdirectory!). Alternatively, build the ``RUN_TESTS`` target from the
IDE.
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. To run tests in Debug mode, for example, use ``ctest -C Debug -VV``
from the build directory (not the Debug subdirectory!). Alternatively, build
the ``RUN_TESTS`` target from the IDE.
Adding System Introspection (Step 5)
====================================
@ -370,14 +379,18 @@ tutorial assume that they are not common.
If the platform has ``log`` and ``exp`` then we will use them to compute the
square root in the ``mysqrt`` function. We first test for the availability of
these functions using the ``CheckSymbolExists`` module in the top-level
``CMakeLists.txt``. We're going to use the new defines in
``TutorialConfig.h.in``, so be sure to set them before that file is configured.
these functions using the :module:`CheckSymbolExists` module in the top-level
``CMakeLists.txt``. On some platforms, we will need to link to the m library.
If ``log`` and ``exp`` are not initially found, require the m library and try
again.
We're going to use the new defines in ``TutorialConfig.h.in``, so be sure to
set them before that file is configured.
.. literalinclude:: Step6/MathFunctions/CMakeLists.txt
:language: cmake
:start-after: # does this system provide the log and exp functions?
:end-before: if(HAVE_LOG AND HAVE_EXP)
:end-before: # add compile definitions
Now let's add these defines to ``TutorialConfig.h.in`` so that we can use them
from ``mysqrt.cxx``:
@ -388,22 +401,29 @@ from ``mysqrt.cxx``:
#cmakedefine HAVE_LOG
#cmakedefine HAVE_EXP
Modify ``mysqrt.cxx`` to include cmath. Next, in that same file in the
``mysqrt`` function we can provide an alternate implementation based on
``log`` and ``exp`` if they are available on the system using the following
code (don't forget the ``#endif`` before returning the result!):
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
:language: c++
:start-after: // if we have both log and exp then use them
:end-before: // do ten iterations
Run **cmake** or **cmake-gui** to configure the project and then build it
We will also need to modify ``mysqrt.cxx`` to include ``cmath``.
.. literalinclude:: Step6/MathFunctions/mysqrt.cxx
:language: c++
:end-before: #include <iostream>
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 and run the Tutorial executable.
You will notice that we're not using ``log`` and ``exp``, even if we think they
should be available. We should realize quickly that we have forgotten to include
``TutorialConfig.h`` in ``mysqrt.cxx``.
should be available. We should realize quickly that we have forgotten to
include ``TutorialConfig.h`` in ``mysqrt.cxx``.
We will also need to update ``MathFunctions/CMakeLists.txt`` so ``mysqrt.cxx``
knows where this file is located:
@ -415,10 +435,10 @@ knows where this file is located:
PRIVATE ${CMAKE_BINARY_DIR}
)
After making this update, go ahead and build the project again and run the built
Tutorial executable. If ``log`` and ``exp`` are still not being used, open the
generated ``TutorialConfig.h`` file from the build directory. Maybe they aren't
available on the current system?
After making this update, go ahead and build the project again and run the
built Tutorial executable. If ``log`` and ``exp`` are still not being used,
open the generated ``TutorialConfig.h`` file from the build directory. Maybe
they aren't available on the current system?
Which function gives better results now, sqrt or mysqrt?
@ -427,7 +447,7 @@ Specify Compile Definition
Is there a better place for us to save the ``HAVE_LOG`` and ``HAVE_EXP`` values
other than in ``TutorialConfig.h``? Let's try to use
``target_compile_definitions``.
:command:`target_compile_definitions`.
First, remove the defines from ``TutorialConfig.h.in``. We no longer need to
include ``TutorialConfig.h`` from ``mysqrt.cxx`` or the extra include in
@ -460,8 +480,8 @@ First, let's remove the check for the ``log`` and ``exp`` functions in
``HAVE_EXP`` from ``mysqrt.cxx``. At the same time, we can remove
:code:`#include <cmath>`.
In the ``MathFunctions`` subdirectory, a new source file named ``MakeTable.cxx``
has been provided to generate the table.
In the ``MathFunctions`` subdirectory, a new source file named
``MakeTable.cxx`` has been provided to generate the table.
After reviewing the file, we can see that the table is produced as valid C++
code and that the output filename is passed in as an argument.
@ -510,7 +530,8 @@ Now let's use the generated table. First, modify ``mysqrt.cxx`` to include
:language: c++
:start-after: // a hack square root calculation using simple operations
Run **cmake** or **cmake-gui** to configure the project and then build it
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.
When this project is built it will first build the ``MakeTable`` executable.
@ -530,26 +551,28 @@ previously in `Installing and Testing (Step 4)`_ , where we were
installing the binaries that we had built from the source code. In this
example we will be building installation packages that support binary
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.
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
:language: cmake
:start-after: # setup installer
That is all there is to it. We start by including
``InstallRequiredSystemLibraries``. This module will include any runtime
libraries that are needed by the project for the current platform. Next we
set some CPack variables to where we have stored the license and version
:module:`InstallRequiredSystemLibraries`. This module will include any runtime
libraries that are needed by the project for the current platform. Next we set
some CPack variables to where we have stored the license and version
information for this project. The version information was set earlier in this
tutorial and the ``license.txt`` has been included in the top-level source
directory for this step.
Finally we include the CPack module which will use these variables and some
other properties of the current system to setup an installer.
Finally we include the :module:`CPack module <CPack>` which will use these
variables and some other properties of the current system to setup an
installer.
The next step is to build the project in the usual manner and then run
CPack on it. To build a binary distribution, from the binary directory run:
The next step is to build the project in the usual manner and then run the
:manual:`cpack <cpack(1)>` executable. To build a binary distribution, from the
binary directory run:
.. code-block:: console
@ -571,16 +594,17 @@ To create a source distribution you would type:
Alternatively, run ``make package`` or right click the ``Package`` target and
``Build Project`` from an IDE.
Run the installer found in the binary directory. Then run the
installed executable and verify that it works.
Run the installer found in the binary directory. Then run the installed
executable and verify that it works.
Adding Support for a Dashboard (Step 8)
=======================================
Adding support for submitting our test results to a dashboard is very easy. We
Adding support for submitting our test results to a dashboard is simple. We
already defined a number of tests for our project in `Testing Support`_. Now we
just have to run those tests and submit them to a dashboard. To include support
for dashboards we include the CTest module in our top-level ``CMakeLists.txt``.
for dashboards we include the :module:`CTest` module in our top-level
``CMakeLists.txt``.
Replace:
@ -596,8 +620,8 @@ With:
# enable dashboard scripting
include(CTest)
The CTest module will automatically call ``enable_testing()``, so
we can remove it from our CMake files.
The :module:`CTest` module will automatically call ``enable_testing()``, so we
can remove it from our CMake files.
We will also need to create a ``CTestConfig.cmake`` file in the top-level
directory where we can specify the name of the project and where to submit the
@ -606,9 +630,11 @@ dashboard.
.. literalinclude:: Step9/CTestConfig.cmake
:language: cmake
CTest will read in this file when it runs. To create a simple dashboard you can
run **cmake** or **cmake-gui** to configure the project, but do not build it
yet. Instead, change directory to the binary tree, and then run::
The :manual:`ctest <ctest(1)>` executable will read in this file when it runs.
To create a simple dashboard you can run the :manual:`cmake <cmake(1)>`
executable or the :manual:`cmake-gui <cmake-gui(1)>` to configure the project,
but do not build it yet. Instead, change directory to the binary tree, and then
run:
ctest [-VV] -D Experimental
@ -619,26 +645,26 @@ type must be specified::
Or, from an IDE, build the ``Experimental`` target.
``ctest`` will build and test the project and submit the results to the Kitware
public dashboard. The results of your dashboard will be uploaded to Kitware's
public dashboard here: https://my.cdash.org/index.php?project=CMakeTutorial.
The :manual:`ctest <ctest(1)>` executable will build and test the project and
submit the results to Kitware's public dashboard:
https://my.cdash.org/index.php?project=CMakeTutorial.
Mixing Static and Shared (Step 9)
=================================
In this section we will show how by using the ``BUILD_SHARED_LIBS`` variable
we can control the default behavior of ``add_library``, and allow control
over how libraries without an explicit type (``STATIC``, ``SHARED``, ``MODULE``
or ``OBJECT``) are built.
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`,
and allow control over how libraries without an explicit type (``STATIC``,
``SHARED``, ``MODULE`` or ``OBJECT``) are built.
To accomplish this we need to add ``BUILD_SHARED_LIBS`` to the top-level
``CMakeLists.txt``. We use the ``option`` command as it allows users to
optionally select if the value should be On or Off.
To accomplish this we need to add :variable:`BUILD_SHARED_LIBS` to the
top-level ``CMakeLists.txt``. We use the :command:`option` command as it allows
users to optionally select if the value should be ON or OFF.
Next we are going to refactor MathFunctions to become a real library that
encapsulates using ``mysqrt`` or ``sqrt``, instead of requiring the calling
code to do this logic. This will also mean that ``USE_MYMATH`` will not control
building MathFuctions, but instead will control the behavior of this library.
building MathFunctions, but instead will control the behavior of this library.
The first step is to update the starting section of the top-level
``CMakeLists.txt`` to look like:
@ -680,8 +706,8 @@ Finally, update ``MathFunctions/MathFunctions.h`` to use dll export defines:
At this point, if you build everything, you will notice that linking fails
as we are combining a static library without position independent code with a
library that has position independent code. The solution to this is to
explicitly set the ``POSITION_INDEPENDENT_CODE`` target property of SqrtLibrary
to be True no matter the build type.
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
:language: cmake
@ -694,35 +720,39 @@ Using CMake documentation can you find a helper module to simplify this?
Adding Generator Expressions (Step 10)
======================================
Generator expressions are evaluated during build system generation to produce
information specific to each build configuration.
:manual:`Generator expressions <cmake-generator-expressions(7)>` are evaluated
during build system generation to produce information specific to each build
configuration.
Generator expressions are allowed in the context of many target properties,
such as ``LINK_LIBRARIES``, ``INCLUDE_DIRECTORIES``, ``COMPILE_DEFINITIONS``
and others. They may also be used when using commands to populate those
properties, such as ``target_link_libraries()``,
``target_include_directories()``,
``target_compile_definitions()`` and others.
:manual:`Generator expressions <cmake-generator-expressions(7)>` are allowed in
the context of many target properties, such as :prop_tgt:`LINK_LIBRARIES`,
:prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_DEFINITIONS` and others.
They may also be used when using commands to populate those properties, such as
:command:`target_link_libraries`, :command:`target_include_directories`,
:command:`target_compile_definitions` and others.
Generator expressions may be used to enable conditional linking, conditional
definitions used when compiling, conditional include directories and more.
The conditions may be based on the build configuration, target properties,
platform information or any other queryable information.
:manual:`Generator expressions <cmake-generator-expressions(7)>` may be used
to enable conditional linking, conditional definitions used when compiling,
conditional include directories and more. The conditions may be based on the
build configuration, target properties, platform information or any other
queryable information.
There are different types of generator expressions including Logical,
Informational, and Output expressions.
There are different types of
:manual:`generator expressions <cmake-generator-expressions(7)>` including
Logical, Informational, and Output expressions.
Logical expressions are used to create conditional output. The basic
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.
A common usage of generator expressions 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. Lets start by constructing an ``INTERFACE``
target and specifying the required C++ standard level of ``11`` instead
of using ``CMAKE_CXX_STANDARD``.
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. Lets start by constructing an
``INTERFACE`` target and specifying the required C++ standard level of ``11``
instead of using :variable:`CMAKE_CXX_STANDARD`.
So the following code:
@ -739,11 +769,10 @@ Would be replaced with:
:end-before: # add compiler warning flags just when building this project via
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:
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
:language: cmake
@ -755,8 +784,8 @@ Looking at this we see that the warning flags are encapsulated inside a
project will not inherit our warning flags.
**Exercise**: Modify ``MathFunctions/CMakeLists.txt`` so that
all targets have a ``target_link_libraries()`` call to ``tutorial_compiler_flags``.
**Exercise**: Modify ``MathFunctions/CMakeLists.txt`` so that all targets have
a :command:`target_link_libraries` call to ``tutorial_compiler_flags``.
Adding Export Configuration (Step 11)
@ -771,12 +800,12 @@ The next step is to add the necessary information so that other CMake projects
can use our project, be it from a build directory, a local install or when
packaged.
The first step is to update our ``install(TARGETS)`` commands to not only
specify a ``DESTINATION`` but also an ``EXPORT``. The ``EXPORT`` keyword
The first step is to update our :command:`install(TARGETS)` commands to not
only specify a ``DESTINATION`` but also an ``EXPORT``. The ``EXPORT`` keyword
generates and installs a CMake file containing code to import all targets
listed in the install command from the installation tree. So let's go ahead
and explicitly ``EXPORT`` the MathFunctions library by updating the
``install`` command in ``MathFunctions/CMakeLists.txt`` to look like:
listed in the install command from the installation tree. So let's go ahead and
explicitly ``EXPORT`` the MathFunctions library by updating the ``install``
command in ``MathFunctions/CMakeLists.txt`` to look like:
.. literalinclude:: Complete/MathFunctions/CMakeLists.txt
:language: cmake
@ -806,12 +835,12 @@ you will see that CMake will generate an error that looks like:
What CMake is trying to say is that during generating the export information
it will export a path that is intrinsically tied to the current machine and
will not be valid on other machines. The solution to this is to update the
MathFunctions ``target_include_directories`` to understand that it needs
MathFunctions :command:`target_include_directories` to understand that it needs
different ``INTERFACE`` locations when being used from within the build
directory and from an install / package. This means converting the
``target_include_directories`` call for MathFunctions to look like:
:command:`target_include_directories` call for MathFunctions to look like:
.. literalinclude:: Complete/MathFunctions/CMakeLists.txt
.. literalinclude:: Step12/MathFunctions/CMakeLists.txt
:language: cmake
:start-after: # to find MathFunctions.h, while we don't.
:end-before: # should we use our own math functions
@ -821,16 +850,16 @@ warn anymore.
At this point, we have CMake properly packaging the target information that is
required but we will still need to generate a ``MathFunctionsConfig.cmake`` so
that the CMake ``find_package`` command can find our project. So let's go
that the CMake :command:`find_package` command can find our project. So let's go
ahead and add a new file to the top-level of the project called
``Config.cmake.in`` with the following contents:
.. literalinclude:: Complete/Config.cmake.in
.. literalinclude:: Step12/Config.cmake.in
Then, to properly configure and install that file, add the following to the
bottom of the top-level ``CMakeLists.txt``:
.. literalinclude:: Complete/CMakeLists.txt
.. literalinclude:: Step12/CMakeLists.txt
:language: cmake
:start-after: # install the configuration targets
:end-before: # generate the export
@ -840,7 +869,7 @@ project that can be used after the project has been installed or packaged. If
we want our project to also be used from a build directory we only have to add
the following to the bottom of the top level ``CMakeLists.txt``:
.. literalinclude:: Complete/CMakeLists.txt
.. literalinclude:: Step12/CMakeLists.txt
:language: cmake
:start-after: # needs to be after the install(TARGETS ) command
@ -848,55 +877,81 @@ With this export call we now generate a ``Targets.cmake``, allowing the
configured ``MathFunctionsConfig.cmake`` in the build directory to be used by
other projects, without needing it to be installed.
Import a CMake Project (Consumer)
=================================
Packaging Debug and Release (Step 12)
=====================================
This example shows how a project can find other CMake packages that
generate ``Config.cmake`` files.
**Note:** This example is valid for single-configuration generators and will
not work for multi-configuration generators (e.g. Visual Studio).
It also shows how to state a project's external dependencies when generating
a ``Config.cmake``.
By default, CMake's model is that a build directory only contains a single
configuration, be it Debug, Release, MinSizeRel, or RelWithDebInfo. It is
possible, however, to setup CPack to bundle multiple build directories and
construct a package that contains multiple configurations of the same project.
Packaging Debug and Release (MultiPackage)
==========================================
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.
By default CMake's model is that a build directory only contains a single
configuration, be it Debug, Release, MinSizeRel, or RelWithDebInfo.
Set :variable:`CMAKE_DEBUG_POSTFIX` near the beginning of the top-level
``CMakeLists.txt`` file:
But it is possible to setup CPack to bundle multiple build directories at the
same time to build a package that contains multiple configurations of the
same project.
.. literalinclude:: Complete/CMakeLists.txt
:language: cmake
:start-after: project(Tutorial VERSION 1.0)
:end-before: target_compile_features(tutorial_compiler_flags
First we need to construct a directory called ``multi_config``, which
will contain all the builds that we want to package together.
And the :prop_tgt:`DEBUG_POSTFIX` property on the tutorial executable:
Second create a ``debug`` and ``release`` directory underneath
``multi_config``. At the end you should have a layout that looks like:
.. literalinclude:: Complete/CMakeLists.txt
:language: cmake
:start-after: # add the executable
:end-before: # add the binary tree to the search path for include files
Let's also add version numbering to the MathFunctions library. In
``MathFunctions/CMakeLists.txt``, set the :prop_tgt:`VERSION` and
:prop_tgt:`SOVERSION` properties:
.. literalinclude:: Complete/MathFunctions/CMakeLists.txt
:language: cmake
:start-after: # setup the version numbering
:end-before: # install rules
From the ``Step12`` directory, create ``debug`` and ``release``
subbdirectories. The layout will look like:
.. code-block:: none
─ multi_config
├── debug
└── release
- Step12
- debug
- release
Now we need to setup debug and release builds, which would roughly entail
the following:
Now we need to setup debug and release builds. We can use
:variable:`CMAKE_BUILD_TYPE` to set the configuration type:
.. code-block:: console
cd debug
cmake -DCMAKE_BUILD_TYPE=Debug ../../MultiPackage/
cmake -DCMAKE_BUILD_TYPE=Debug ..
cmake --build .
cd ../release
cmake -DCMAKE_BUILD_TYPE=Release ../../MultiPackage/
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build .
cd ..
Now that both the debug and release builds are complete, we can use a custom
configuration file to package both builds into a single release. In the
``Step12`` directory, create a file called ``MultiCPackConfig.cmake``. In this
file, first include the default configuration file that was created by the
:manual:`cmake <cmake(1)>` executable.
Now that both the debug and release builds are complete, we can use
a custom ``MultiCPackConfig.cmake`` file to package both builds into a single
release.
Next, use the ``CPACK_INSTALL_CMAKE_PROJECTS`` variable to specify which
projects to install. In this case, we want to install both debug and release.
.. literalinclude:: Complete/MultiCPackConfig.cmake
:language: cmake
From the ``Step12`` directory, run :manual:`cpack <cpack(1)>` specifying our
custom configuration file with the ``config`` option:
.. code-block:: console
cpack --config ../../MultiPackage/MultiCPackConfig.cmake
cpack --config MultiCPackConfig.cmake

BIN
Help/guide/user-interaction/GUI-Add-Entry.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 33 KiB

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