diff --git a/.clang-tidy b/.clang-tidy index 5e513fbd1b1..dda86b079c5 100644 --- a/.clang-tidy +++ b/.clang-tidy @@ -19,6 +19,7 @@ modernize-*,\ performance-*,\ readability-*,\ -readability-convert-member-functions-to-static,\ +-readability-function-cognitive-complexity,\ -readability-function-size,\ -readability-identifier-naming,\ -readability-implicit-bool-conversion,\ diff --git a/.codespellrc b/.codespellrc new file mode 100644 index 00000000000..a8be48762d3 --- /dev/null +++ b/.codespellrc @@ -0,0 +1,9 @@ +[codespell] +check-filenames = +check-hidden = +count = +# Disable warnings about binary files +quiet-level = 2 +builtin = clear,rare,en-GB_to_en-US +skip = */.git,*/build,*/Copyright.txt,*/doxygen.config,*/Modules/Internal/CPack/NSIS.template.in,*/Source/CursesDialog/form/*,*/Source/kwsys/*,*/Tests/RunCMake/CPack/tests/DMG_SLA/German.*,*/Tests/RunCMake/ParseImplicitData/*.input,*/Utilities/cm* +ignore-words-list = aci,ake,ans,ba,cconfiguration,conly,dependees,dne,dum,earch,ect,filetest,fo,helpfull,hiden,isnt,keypair,nd,ned,nin,nknown,ot,pard,seh,ser,te,upto,varn,vas,wee diff --git a/.gitattributes b/.gitattributes index fac38dfd741..79a0f0400ea 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,5 +1,6 @@ .git* export-ignore .hooks* export-ignore +.codespellrc export-ignore .editorconfig export-ignore # Custom attribute to mark sources as using our C code style. diff --git a/.gitignore b/.gitignore index ee6e0883a09..7537831370a 100644 --- a/.gitignore +++ b/.gitignore @@ -9,10 +9,16 @@ CMakeUserPresets.json # Visual Studio work directory .vs/ +# Visual Studio build directory +out/ # Visual Studio Code .vscode/ +# CLion work directory +.idea/ +# CLion build directories +cmake-build-*/ [Bb]uild*/ [Dd]ebug*/ [Rr]elease*/ diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index d0b3b1e00cf..06570d91beb 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -1,5 +1,5 @@ include: - # Metadata shared my many jobs + # Metadata shared by many jobs - local: .gitlab/rules.yml - local: .gitlab/artifacts.yml @@ -34,9 +34,16 @@ stages: # - dependency/needs jobs for required jobs ################################################################################ +# Job prefixes: +# - `b:` build +# - `l:` lint +# - `p:` prep +# - `t:` test +# - `u:` upload + # Prep jobs -prep:source-package: +p:source-package: extends: - .linux_prep_source - .cmake_prep_source_linux @@ -44,44 +51,84 @@ prep:source-package: - .cmake_release_artifacts - .run_only_for_package -prep:doc-package: +p:doc-package: extends: - - .fedora33_sphinx_package + - .fedora34_sphinx_package - .cmake_prep_doc_linux - .linux_builder_tags_qt - .cmake_doc_artifacts - .run_only_for_package -.upload:source-package: +.u:source-package: extends: - - .rsync_upload + - .rsync_upload_binary - .run_only_for_package dependencies: - - prep:source-package + - p:source-package needs: - - prep:source-package + - p:source-package variables: RSYNC_DESTINATION: dev +# Documentation builds + +b:help:master: + extends: + - .cmake_org_help + - .run_only_for_continuous_master + +.u:help:master: + extends: + - .rsync_upload_help + - .run_only_for_continuous_master + variables: + RSYNC_DESTINATION: git-master + dependencies: + - b:help:master + needs: + - b:help:master + +b:help:stage: + extends: + - .cmake_org_help + - .run_only_for_continuous_stage + +.u:help:stage: + extends: + - .rsync_upload_help + - .run_only_for_continuous_stage + variables: + RSYNC_DESTINATION: git-stage + dependencies: + - b:help:stage + needs: + - b:help:stage + # Lint builds -build:debian10-iwyu: +l:codespell: + extends: + - .cmake_codespell_linux + - .linux_builder_tags + - .run_automatically + +l:iwyu-debian10: extends: - .debian10_iwyu - .cmake_build_linux - .linux_builder_tags - .run_automatically -build:fedora33-tidy: +l:tidy-fedora34: extends: - - .fedora33_tidy + - .fedora34_tidy - .cmake_build_linux - .linux_builder_tags_qt - .run_automatically -build:fedora33-sphinx: +l:sphinx-fedora34: extends: - - .fedora33_sphinx + - .fedora34_sphinx - .cmake_build_linux - .linux_builder_tags_qt - .run_automatically @@ -89,9 +136,18 @@ build:fedora33-sphinx: CMAKE_CI_JOB_CONTINUOUS: "true" CMAKE_CI_JOB_HELP: "true" +l:clang-analyzer-fedora34: + extends: + - .fedora34_clang_analyzer + - .cmake_build_linux + - .linux_builder_tags_qt + - .run_automatically + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + # Linux builds -build:centos6-x86_64: +b:centos6-x86_64: extends: - .linux_release_x86_64 - .cmake_build_linux_release @@ -99,7 +155,7 @@ build:centos6-x86_64: - .linux_builder_tags - .run_manually -build:centos7-aarch64: +b:centos7-aarch64: extends: - .linux_release_aarch64 - .cmake_build_linux_release @@ -109,84 +165,358 @@ build:centos7-aarch64: variables: CMAKE_CI_NO_MR: "true" -test:debian10-ninja: +t:debian10-ninja: extends: - .debian10_ninja - .cmake_test_linux_release - .linux_builder_tags_qt + - .cmake_junit_artifacts - .run_dependent - dependencies: - - build:centos6-x86_64 - needs: - - build:centos6-x86_64 + - .needs_centos6_x86_64 + variables: + CMAKE_CI_JOB_NIGHTLY_NINJA: "true" -test:debian10-aarch64-ninja: +t:debian10-aarch64-ninja: extends: - .debian10_aarch64_ninja - .cmake_test_linux_release - .linux_builder_tags_aarch64_qt + - .cmake_junit_artifacts - .run_dependent - dependencies: - - build:centos7-aarch64 - needs: - - build:centos7-aarch64 + - .needs_centos7_aarch64 variables: CMAKE_CI_NO_MR: "true" -test:fedora33-makefiles: +t:debian10-ninja-clang: + extends: + - .debian10_ninja_clang + - .cmake_test_linux_release + - .linux_builder_tags_qt + - .run_manually + - .needs_centos6_x86_64 + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + +t:debian10-makefiles-clang: extends: - - .fedora33_makefiles + - .debian10_makefiles_clang + - .cmake_test_linux_release + - .linux_builder_tags_qt + - .run_manually + - .needs_centos6_x86_64 + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + +t:fedora34-makefiles: + extends: + - .fedora34_makefiles - .cmake_test_linux_release - .linux_builder_tags_qt - .run_dependent - dependencies: - - build:centos6-x86_64 - needs: - - build:centos6-x86_64 + - .needs_centos6_x86_64 -test:cuda10.2-nvidia: +t:fedora34-makefiles-nospace: + extends: + - .fedora34_makefiles + - .cmake_test_linux_release + - .linux_builder_tags_qt + - .cmake_junit_artifacts + - .run_dependent + - .needs_centos6_x86_64 + variables: + GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake-ci" + CMAKE_CI_BUILD_NAME: fedora34_makefiles_nospace + CMAKE_CI_JOB_NIGHTLY: "true" + +t:cuda9.2-nvidia: + extends: + - .cuda9.2_nvidia + - .cmake_test_linux_release + - .linux_builder_tags_cuda + - .run_dependent + - .needs_centos6_x86_64 + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + +t:cuda10.2-nvidia: extends: - .cuda10.2_nvidia - .cmake_test_linux_release - .linux_builder_tags_cuda + - .cmake_junit_artifacts - .run_dependent - dependencies: - - build:centos6-x86_64 - needs: - - build:centos6-x86_64 + - .needs_centos6_x86_64 -build:fedora33-ninja: +t:cuda10.2-clang: extends: - - .fedora33_ninja + - .cuda10.2_clang + - .cmake_test_linux_release + - .linux_builder_tags_cuda + - .run_dependent + - .needs_centos6_x86_64 + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + +t:hip4.2-radeon: + extends: + - .hip4.2_radeon + - .cmake_test_linux_release + - .linux_builder_tags_radeon + - .run_dependent + - .needs_centos6_x86_64 + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + +b:fedora34-ninja: + extends: + - .fedora34_ninja - .cmake_build_linux - .cmake_build_artifacts - .linux_builder_tags_qt - .run_manually -test:fedora33-ninja: +t:fedora34-ninja: extends: - - .fedora33_ninja + - .fedora34_ninja - .cmake_test_linux - .linux_builder_tags_x11 - .cmake_test_artifacts - .run_dependent dependencies: - - build:fedora33-ninja + - b:fedora34-ninja needs: - - build:fedora33-ninja + - b:fedora34-ninja -test:fedora33-ninja-multi: +t:fedora34-ninja-multi: extends: - - .fedora33_ninja_multi + - .fedora34_ninja_multi - .cmake_test_linux_external - .linux_builder_tags_qt + - .cmake_junit_artifacts - .run_dependent dependencies: - - test:fedora33-ninja + - t:fedora34-ninja needs: - - test:fedora33-ninja + - t:fedora34-ninja + +t:intel2016-makefiles: + extends: + - .cmake_test_linux_intelclassic_makefiles + variables: + CMAKE_CI_BUILD_NAME: intel2016_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2016-el7 + +t:intel2016u1-makefiles: + extends: + - .cmake_test_linux_intelclassic_makefiles + variables: + CMAKE_CI_BUILD_NAME: intel2016u1_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2016u1-el7 + +t:intel2016u2-makefiles: + extends: + - .cmake_test_linux_intelclassic_makefiles + variables: + CMAKE_CI_BUILD_NAME: intel2016u2_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2016u2-el7 -build:linux-x86_64-package: +t:intel2017-makefiles: + extends: + - .cmake_test_linux_intelclassic_makefiles + variables: + CMAKE_CI_BUILD_NAME: intel2017_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2017-el7 + +t:intel2017u1-makefiles: + extends: + - .cmake_test_linux_intelclassic_makefiles + variables: + CMAKE_CI_BUILD_NAME: intel2017u1_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2017u1-el7 + +t:intel2017u2-makefiles: + extends: + - .cmake_test_linux_intelclassic_makefiles + variables: + CMAKE_CI_BUILD_NAME: intel2017u2_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2017u2-el7 + +t:intel2017u3-makefiles: + extends: + - .cmake_test_linux_intelclassic_makefiles + variables: + CMAKE_CI_BUILD_NAME: intel2017u3_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2017u3-el7 + +t:intel2017u4-makefiles: + extends: + - .cmake_test_linux_intelclassic_makefiles + variables: + CMAKE_CI_BUILD_NAME: intel2017u4_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2017u4-el7 + +t:intel2017u5-makefiles: + extends: + - .cmake_test_linux_intelclassic_makefiles + variables: + CMAKE_CI_BUILD_NAME: intel2017u5_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2017u5-el7 + +t:intel2017u6-makefiles: + extends: + - .cmake_test_linux_intelclassic_makefiles + variables: + CMAKE_CI_BUILD_NAME: intel2017u6_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2017u6-el7 + +t:intel2017u7-makefiles: + extends: + - .cmake_test_linux_intelclassic_makefiles + variables: + CMAKE_CI_BUILD_NAME: intel2017u7_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2017u7-el7 + +t:intel2017u8-makefiles: + extends: + - .cmake_test_linux_intelclassic_makefiles + variables: + CMAKE_CI_BUILD_NAME: intel2017u8_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2017u8-el7 + +t:intel2018-makefiles: + extends: + - .cmake_test_linux_intelclassic_makefiles + variables: + CMAKE_CI_BUILD_NAME: intel2018_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2018-el7 + +t:intel2018u1-makefiles: + extends: + - .cmake_test_linux_intelclassic_makefiles + variables: + CMAKE_CI_BUILD_NAME: intel2018u1_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2018u1-el7 + +t:intel2018u2-makefiles: + extends: + - .cmake_test_linux_intelclassic_makefiles + variables: + CMAKE_CI_BUILD_NAME: intel2018u2_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2018u2-el7 + +t:intel2018u3-makefiles: + extends: + - .cmake_test_linux_intelclassic_makefiles + variables: + CMAKE_CI_BUILD_NAME: intel2018u3_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2018u3-el7 + +t:intel2018u4-makefiles: + extends: + - .cmake_test_linux_intelclassic_makefiles + variables: + CMAKE_CI_BUILD_NAME: intel2018u4_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2018u4-el7 + +t:intel2019-makefiles: + extends: + - .cmake_test_linux_intelclassic_makefiles + variables: + CMAKE_CI_BUILD_NAME: intel2019_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2019-el7 + +t:intel2019u1-makefiles: + extends: + - .cmake_test_linux_intelclassic_makefiles + variables: + CMAKE_CI_BUILD_NAME: intel2019u1_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2019u1-el7 + +t:intel2019u2-makefiles: + extends: + - .cmake_test_linux_intelclassic_makefiles + variables: + CMAKE_CI_BUILD_NAME: intel2019u2_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2019u2-el7 + +t:intel2019u3-makefiles: + extends: + - .cmake_test_linux_intelclassic_makefiles + variables: + CMAKE_CI_BUILD_NAME: intel2019u3_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2019u3-el7 + +t:intel2019u4-makefiles: + extends: + - .cmake_test_linux_intelclassic_makefiles + variables: + CMAKE_CI_BUILD_NAME: intel2019u4_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2019u4-el7 + +t:intel2020-makefiles: + extends: + - .cmake_test_linux_intelclassic_makefiles + variables: + CMAKE_CI_BUILD_NAME: intel2020_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2020-el8 + +t:intel2020u2-makefiles: + extends: + - .cmake_test_linux_intelclassic_makefiles + variables: + CMAKE_CI_BUILD_NAME: intel2020u2_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2020u2-el8 + +t:intel2020u4-makefiles: + extends: + - .cmake_test_linux_intelclassic_makefiles + variables: + CMAKE_CI_BUILD_NAME: intel2020u4_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2020u4-el8 + +t:intel2021.1.1-makefiles: + extends: + - .cmake_test_linux_intelclassic_makefiles + variables: + CMAKE_CI_BUILD_NAME: intel2021.1.1_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2021.1.1-el8 + +t:intel2021.1.2-makefiles: + extends: + - .cmake_test_linux_intelclassic_makefiles + variables: + CMAKE_CI_BUILD_NAME: intel2021.1.2_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2021.1.2-el8 + +t:intel2021.2.0-makefiles: + extends: + - .cmake_test_linux_intelclassic_makefiles + variables: + CMAKE_CI_BUILD_NAME: intel2021.2.0_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2021.2.0-el8 + +t:oneapi2021.1.1-makefiles: + extends: + - .cmake_test_linux_inteloneapi_makefiles + variables: + CMAKE_CI_BUILD_NAME: oneapi2021.1.1_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2021.1.1-el8 + +t:oneapi2021.1.2-makefiles: + extends: + - .cmake_test_linux_inteloneapi_makefiles + variables: + CMAKE_CI_BUILD_NAME: oneapi2021.1.2_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2021.1.2-el8 + +t:oneapi2021.2.0-makefiles: + extends: + - .cmake_test_linux_inteloneapi_makefiles + variables: + CMAKE_CI_BUILD_NAME: oneapi2021.2.0_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2021.2.0-el8 + +b:linux-x86_64-package: extends: - .linux_package - .linux_release_x86_64 @@ -195,22 +525,22 @@ build:linux-x86_64-package: - .linux_builder_tags - .run_only_for_package dependencies: - - prep:doc-package + - p:doc-package needs: - - prep:doc-package + - p:doc-package -.upload:linux-x86_64-package: +.u:linux-x86_64-package: extends: - - .rsync_upload + - .rsync_upload_binary - .run_only_for_package dependencies: - - build:linux-x86_64-package + - b:linux-x86_64-package needs: - - build:linux-x86_64-package + - b:linux-x86_64-package variables: RSYNC_DESTINATION: dev -build:linux-aarch64-package: +b:linux-aarch64-package: extends: - .linux_package - .linux_release_aarch64 @@ -219,24 +549,49 @@ build:linux-aarch64-package: - .linux_builder_tags_aarch64 - .run_only_for_package dependencies: - - prep:doc-package + - p:doc-package needs: - - prep:doc-package + - p:doc-package -.upload:linux-aarch64-package: +.u:linux-aarch64-package: extends: - - .rsync_upload + - .rsync_upload_binary - .run_only_for_package dependencies: - - build:linux-aarch64-package + - b:linux-aarch64-package needs: - - build:linux-aarch64-package + - b:linux-aarch64-package variables: RSYNC_DESTINATION: dev +## Sanitizer builds + +b:fedora34-asan: + extends: + - .fedora34_asan + - .cmake_build_linux + - .cmake_build_artifacts + - .linux_builder_tags_qt + - .run_manually + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + +t:fedora34-asan: + extends: + - .fedora34_asan + - .cmake_memcheck_linux + - .linux_builder_tags_qt + - .run_dependent + dependencies: + - b:fedora34-asan + needs: + - b:fedora34-asan + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + # macOS builds -build:macos-x86_64-ninja: +b:macos-x86_64-ninja: extends: - .macos_x86_64_ninja - .cmake_build_macos @@ -244,7 +599,7 @@ build:macos-x86_64-ninja: - .macos_x86_64_builder_tags - .run_manually -build:macos-arm64-ninja: +b:macos-arm64-ninja: extends: - .macos_arm64_ninja - .cmake_build_macos @@ -254,7 +609,7 @@ build:macos-arm64-ninja: variables: CMAKE_CI_NO_MR: "true" -test:macos-x86_64-ninja: +t:macos-x86_64-ninja: extends: - .macos_x86_64_ninja - .cmake_test_macos @@ -262,11 +617,13 @@ test:macos-x86_64-ninja: - .macos_x86_64_builder_tags - .run_dependent dependencies: - - build:macos-x86_64-ninja + - b:macos-x86_64-ninja needs: - - build:macos-x86_64-ninja + - b:macos-x86_64-ninja + variables: + CMAKE_CI_JOB_NIGHTLY_NINJA: "true" -test:macos-arm64-ninja: +t:macos-arm64-ninja: extends: - .macos_arm64_ninja - .cmake_test_macos @@ -274,13 +631,13 @@ test:macos-arm64-ninja: - .macos_arm64_builder_tags - .run_dependent dependencies: - - build:macos-arm64-ninja + - b:macos-arm64-ninja needs: - - build:macos-arm64-ninja + - b:macos-arm64-ninja variables: CMAKE_CI_NO_MR: "true" -build:macos-x86_64-makefiles: +b:macos-x86_64-makefiles: extends: - .macos_x86_64_makefiles - .cmake_build_macos @@ -288,42 +645,44 @@ build:macos-x86_64-makefiles: - .macos_x86_64_builder_tags - .run_manually -test:macos-x86_64-makefiles: +t:macos-x86_64-makefiles: extends: - .macos_x86_64_makefiles - .cmake_test_macos - .macos_x86_64_builder_tags - .run_dependent dependencies: - - build:macos-x86_64-makefiles + - b:macos-x86_64-makefiles needs: - - build:macos-x86_64-makefiles + - b:macos-x86_64-makefiles -test:macos-x86_64-xcode: +t:macos-x86_64-xcode: extends: - .macos_x86_64_xcode - .cmake_test_macos_external - .macos_x86_64_builder_ext_tags + - .cmake_junit_artifacts - .run_dependent dependencies: - - test:macos-x86_64-ninja + - t:macos-x86_64-ninja needs: - - test:macos-x86_64-ninja + - t:macos-x86_64-ninja -test:macos-arm64-xcode: +t:macos-arm64-xcode: extends: - .macos_arm64_xcode - .cmake_test_macos_external - .macos_arm64_builder_ext_tags + - .cmake_junit_artifacts - .run_dependent dependencies: - - test:macos-arm64-ninja + - t:macos-arm64-ninja needs: - - test:macos-arm64-ninja + - t:macos-arm64-ninja variables: CMAKE_CI_NO_MR: "true" -build:macos-package: +b:macos-package: extends: - .macos_package - .cmake_build_macos_package @@ -331,22 +690,22 @@ build:macos-package: - .macos_x86_64_builder_tags_package - .run_only_for_package dependencies: - - prep:doc-package + - p:doc-package needs: - - prep:doc-package + - p:doc-package -.upload:macos-package: +.u:macos-package: extends: - - .rsync_upload + - .rsync_upload_binary - .run_only_for_package dependencies: - - build:macos-package + - b:macos-package needs: - - build:macos-package + - b:macos-package variables: RSYNC_DESTINATION: dev -build:macos10.10-package: +b:macos10.10-package: extends: - .macos10.10_package - .cmake_build_macos_package @@ -354,50 +713,51 @@ build:macos10.10-package: - .macos_x86_64_builder_tags_package - .run_only_for_package dependencies: - - prep:doc-package + - p:doc-package needs: - - prep:doc-package + - p:doc-package -.upload:macos10.10-package: +.u:macos10.10-package: extends: - - .rsync_upload + - .rsync_upload_binary - .run_only_for_package dependencies: - - build:macos10.10-package + - b:macos10.10-package needs: - - build:macos10.10-package + - b:macos10.10-package variables: RSYNC_DESTINATION: dev # Windows builds -build:windows-vs2019-x64-ninja: +b:windows-vs2022-x64-ninja: extends: - - .windows_vs2019_x64_ninja + - .windows_vs2022_x64_ninja - .cmake_build_windows - .cmake_build_artifacts - - .windows_builder_tags + - .windows_tags_nonconcurrent_vs2022 - .run_manually -test:windows-vs2019-x64-ninja: +t:windows-vs2022-x64-ninja: extends: - - .windows_vs2019_x64_ninja + - .windows_vs2022_x64_ninja - .cmake_test_windows - - .windows_builder_tags + - .windows_tags_nonconcurrent_vs2022 - .cmake_test_artifacts - .run_dependent dependencies: - - build:windows-vs2019-x64-ninja + - b:windows-vs2022-x64-ninja needs: - - build:windows-vs2019-x64-ninja + - b:windows-vs2022-x64-ninja -test:windows-vs2019-x64: +t:windows-vs2022-x64: extends: - - .windows_vs2019_x64 + - .windows_vs2022_x64 - .cmake_test_windows_external - - .windows_builder_ext_tags + - .windows_tags_concurrent_vs2022 + - .cmake_junit_artifacts - .run_dependent dependencies: - - test:windows-vs2019-x64-ninja + - t:windows-vs2022-x64-ninja needs: - - test:windows-vs2019-x64-ninja + - t:windows-vs2022-x64-ninja diff --git a/.gitlab/artifacts.yml b/.gitlab/artifacts.yml index bf8e8b6d1d3..982f50b3bdb 100644 --- a/.gitlab/artifacts.yml +++ b/.gitlab/artifacts.yml @@ -56,7 +56,7 @@ # Test directories. - build/Tests/CTest* - build/Tests/Find* - - build/Tests/Qt5* + - build/Tests/Qt* - build/Tests/RunCMake/ - build/Tests/CMakeOnly/ - build/Tests/CMakeTests/ @@ -82,11 +82,22 @@ - build/cmake-*.tar.gz - build/cmake-*.zip +.cmake_junit_artifacts: + artifacts: + expire_in: 1d + when: always + reports: + junit: + - build/junit.xml + .cmake_test_artifacts: artifacts: expire_in: 1d # External testing can be useful even if test jobs fail. when: always + reports: + junit: + - build/junit.xml paths: # Take the install tree. - build/install/ @@ -97,3 +108,12 @@ paths: # Take the install tree. - build/install-doc/ + +.cmake_org_help_artifacts: + artifacts: + expire_in: 1d + paths: + - build/html + exclude: + - build/html/.buildinfo + - build/html/objects.inv diff --git a/.gitlab/ci/cmake.ps1 b/.gitlab/ci/cmake.ps1 index 3d6fb81ed57..5d01e3f9e33 100755 --- a/.gitlab/ci/cmake.ps1 +++ b/.gitlab/ci/cmake.ps1 @@ -1,8 +1,8 @@ $erroractionpreference = "stop" -$version = "3.19.7" -$sha256sum = "E6788D6E23B3026C37FCFA7658075D6B5F9113F26FAE17FE372AD4A7EE62D5FD" -$filename = "cmake-$version-win64-x64" +$version = "3.21.0" +$sha256sum = "C7B88C907A753F4EC86E43DDC89F91F70BF1B011859142F7F29E6D51EA4ABB3C" +$filename = "cmake-$version-windows-x86_64" $tarball = "$filename.zip" $outdir = $pwd.Path diff --git a/.gitlab/ci/cmake.sh b/.gitlab/ci/cmake.sh index e02eb8a33e6..c37f6dc55ff 100755 --- a/.gitlab/ci/cmake.sh +++ b/.gitlab/ci/cmake.sh @@ -2,22 +2,22 @@ set -e -readonly version="3.19.3" +readonly version="3.21.0" case "$(uname -s)-$(uname -m)" in Linux-x86_64) shatool="sha256sum" - sha256sum="c18b65697e9679e5c88dccede08c323cd3d3730648e59048047bba82097e0ffc" - platform="Linux-x86_64" + sha256sum="d54ef6909f519740bc85cec07ff54574cd1e061f9f17357d9ace69f61c6291ce" + platform="linux-x86_64" ;; Linux-aarch64) shatool="sha256sum" - sha256sum="66e507c97ffb586d7ca6567890808b792c8eb004b645706df6fbf27826a395a2" - platform="Linux-aarch64" + sha256sum="b1e46825bf370f45f8f47c3a497b1122759ee41fbd60187e525f517a4b0934eb" + platform="linux-aarch64" ;; Darwin-*) shatool="shasum -a 256" - sha256sum="a6b79ad05f89241a05797510e650354d74ff72cc988981cdd1eb2b3b2bda66ac" + sha256sum="c1c6f19dfc9c658a48b5aed22806595b2337bb3aedb71ab826552f74f568719f" platform="macos-universal" ;; *) diff --git a/.gitlab/ci/configure_common.cmake b/.gitlab/ci/configure_common.cmake index 436e5824f4e..a711f3bda42 100644 --- a/.gitlab/ci/configure_common.cmake +++ b/.gitlab/ci/configure_common.cmake @@ -6,8 +6,8 @@ set(CMAKE_SKIP_INSTALL_ALL_DEPENDENCY "ON" CACHE BOOL "") set(CMAKE_INSTALL_PREFIX "${CMAKE_BINARY_DIR}/install" CACHE PATH "") set(CMake_TEST_INSTALL "OFF" CACHE BOOL "") -if (NOT "$ENV{CMAKE_BUILD_TYPE}" STREQUAL "") - set(CMAKE_BUILD_TYPE "$ENV{CMAKE_BUILD_TYPE}" CACHE STRING "") +if (NOT "$ENV{CMAKE_CI_BUILD_TYPE}" STREQUAL "") + set(CMAKE_BUILD_TYPE "$ENV{CMAKE_CI_BUILD_TYPE}" CACHE STRING "") endif () if (NOT configure_no_sccache) diff --git a/.gitlab/ci/configure_cuda10.2_clang.cmake b/.gitlab/ci/configure_cuda10.2_clang.cmake new file mode 100644 index 00000000000..e13ca881d6c --- /dev/null +++ b/.gitlab/ci/configure_cuda10.2_clang.cmake @@ -0,0 +1,3 @@ +set(CMake_TEST_CUDA "Clang" CACHE STRING "") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake") diff --git a/.gitlab/ci/configure_cuda9.2_nvidia.cmake b/.gitlab/ci/configure_cuda9.2_nvidia.cmake new file mode 100644 index 00000000000..519699b0ccf --- /dev/null +++ b/.gitlab/ci/configure_cuda9.2_nvidia.cmake @@ -0,0 +1,3 @@ +set(CMake_TEST_CUDA "NVIDIA" CACHE STRING "") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake") diff --git a/.gitlab/ci/configure_debian10_aarch64_ninja.cmake b/.gitlab/ci/configure_debian10_aarch64_ninja.cmake index 023cc9e8e11..8e03eef59d8 100644 --- a/.gitlab/ci/configure_debian10_aarch64_ninja.cmake +++ b/.gitlab/ci/configure_debian10_aarch64_ninja.cmake @@ -1,10 +1,11 @@ set(CMake_TEST_FindALSA "ON" CACHE BOOL "") -set(CMake_TEST_FindBLAS "ON" CACHE BOOL "") +set(CMake_TEST_FindBLAS "All;static=1;Generic" CACHE STRING "") set(CMake_TEST_FindBoost "ON" CACHE BOOL "") set(CMake_TEST_FindBoost_Python "ON" CACHE BOOL "") set(CMake_TEST_FindBZip2 "ON" CACHE BOOL "") set(CMake_TEST_FindCups "ON" CACHE BOOL "") set(CMake_TEST_FindCURL "ON" CACHE BOOL "") +set(CMake_TEST_FindDevIL "ON" CACHE BOOL "") set(CMake_TEST_FindDoxygen_Dot "ON" CACHE BOOL "") set(CMake_TEST_FindDoxygen "ON" CACHE BOOL "") set(CMake_TEST_FindEXPAT "ON" CACHE BOOL "") @@ -14,6 +15,7 @@ set(CMake_TEST_FindGDAL "ON" CACHE BOOL "") set(CMake_TEST_FindGIF "ON" CACHE BOOL "") set(CMake_TEST_FindGit "ON" CACHE BOOL "") set(CMake_TEST_FindGLEW "ON" CACHE BOOL "") +set(CMake_TEST_FindGLUT "ON" CACHE BOOL "") set(CMake_TEST_FindGnuTLS "ON" CACHE BOOL "") set(CMake_TEST_FindGSL "ON" CACHE BOOL "") set(CMake_TEST_FindGTest "ON" CACHE BOOL "") @@ -22,7 +24,7 @@ set(CMake_TEST_FindIconv "ON" CACHE BOOL "") set(CMake_TEST_FindIntl "ON" CACHE BOOL "") set(CMake_TEST_FindJPEG "ON" CACHE BOOL "") set(CMake_TEST_FindJsonCpp "ON" CACHE BOOL "") -set(CMake_TEST_FindLAPACK "ON" CACHE BOOL "") +set(CMake_TEST_FindLAPACK "All;static=1;Generic" CACHE STRING "") set(CMake_TEST_FindLibArchive "ON" CACHE BOOL "") set(CMake_TEST_FindLibinput "ON" CACHE BOOL "") set(CMake_TEST_FindLibLZMA "ON" CACHE BOOL "") @@ -45,6 +47,7 @@ set(CMake_TEST_FindPatch "ON" CACHE BOOL "") set(CMake_TEST_FindPNG "ON" CACHE BOOL "") set(CMake_TEST_FindPostgreSQL "ON" CACHE BOOL "") set(CMake_TEST_FindProtobuf "ON" CACHE BOOL "") +set(CMake_TEST_FindProtobuf_gRPC "ON" CACHE BOOL "") set(CMake_TEST_FindPython "ON" CACHE BOOL "") set(CMake_TEST_FindPython_NumPy "ON" CACHE BOOL "") set(CMake_TEST_FindPython_PyPy "ON" CACHE BOOL "") diff --git a/.gitlab/ci/configure_debian10_makefiles_clang.cmake b/.gitlab/ci/configure_debian10_makefiles_clang.cmake new file mode 100644 index 00000000000..20863a2fb08 --- /dev/null +++ b/.gitlab/ci/configure_debian10_makefiles_clang.cmake @@ -0,0 +1 @@ +include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake") diff --git a/.gitlab/ci/configure_debian10_ninja.cmake b/.gitlab/ci/configure_debian10_ninja.cmake index 74d9f12ef0f..d50ab1f05a4 100644 --- a/.gitlab/ci/configure_debian10_ninja.cmake +++ b/.gitlab/ci/configure_debian10_ninja.cmake @@ -1,10 +1,11 @@ set(CMake_TEST_FindALSA "ON" CACHE BOOL "") -set(CMake_TEST_FindBLAS "ON" CACHE BOOL "") +set(CMake_TEST_FindBLAS "All;static=1;Generic" CACHE STRING "") set(CMake_TEST_FindBoost "ON" CACHE BOOL "") set(CMake_TEST_FindBoost_Python "ON" CACHE BOOL "") set(CMake_TEST_FindBZip2 "ON" CACHE BOOL "") set(CMake_TEST_FindCups "ON" CACHE BOOL "") set(CMake_TEST_FindCURL "ON" CACHE BOOL "") +set(CMake_TEST_FindDevIL "ON" CACHE BOOL "") set(CMake_TEST_FindDoxygen_Dot "ON" CACHE BOOL "") set(CMake_TEST_FindDoxygen "ON" CACHE BOOL "") set(CMake_TEST_FindEXPAT "ON" CACHE BOOL "") @@ -14,6 +15,7 @@ set(CMake_TEST_FindGDAL "ON" CACHE BOOL "") set(CMake_TEST_FindGIF "ON" CACHE BOOL "") set(CMake_TEST_FindGit "ON" CACHE BOOL "") set(CMake_TEST_FindGLEW "ON" CACHE BOOL "") +set(CMake_TEST_FindGLUT "ON" CACHE BOOL "") set(CMake_TEST_FindGnuTLS "ON" CACHE BOOL "") set(CMake_TEST_FindGSL "ON" CACHE BOOL "") set(CMake_TEST_FindGTest "ON" CACHE BOOL "") @@ -22,7 +24,7 @@ set(CMake_TEST_FindIconv "ON" CACHE BOOL "") set(CMake_TEST_FindIntl "ON" CACHE BOOL "") set(CMake_TEST_FindJPEG "ON" CACHE BOOL "") set(CMake_TEST_FindJsonCpp "ON" CACHE BOOL "") -set(CMake_TEST_FindLAPACK "ON" CACHE BOOL "") +set(CMake_TEST_FindLAPACK "All;static=1;Generic" CACHE STRING "") set(CMake_TEST_FindLibArchive "ON" CACHE BOOL "") set(CMake_TEST_FindLibinput "ON" CACHE BOOL "") set(CMake_TEST_FindLibLZMA "ON" CACHE BOOL "") @@ -45,6 +47,7 @@ set(CMake_TEST_FindPatch "ON" CACHE BOOL "") set(CMake_TEST_FindPNG "ON" CACHE BOOL "") set(CMake_TEST_FindPostgreSQL "ON" CACHE BOOL "") set(CMake_TEST_FindProtobuf "ON" CACHE BOOL "") +set(CMake_TEST_FindProtobuf_gRPC "ON" CACHE BOOL "") set(CMake_TEST_FindPython "ON" CACHE BOOL "") set(CMake_TEST_FindPython_IronPython "ON" CACHE BOOL "") set(CMake_TEST_FindPython_NumPy "ON" CACHE BOOL "") diff --git a/.gitlab/ci/configure_debian10_ninja_clang.cmake b/.gitlab/ci/configure_debian10_ninja_clang.cmake new file mode 100644 index 00000000000..20863a2fb08 --- /dev/null +++ b/.gitlab/ci/configure_debian10_ninja_clang.cmake @@ -0,0 +1 @@ +include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake") diff --git a/.gitlab/ci/configure_fedora33_tidy.cmake b/.gitlab/ci/configure_fedora33_tidy.cmake deleted file mode 100644 index 9052fdc5623..00000000000 --- a/.gitlab/ci/configure_fedora33_tidy.cmake +++ /dev/null @@ -1,3 +0,0 @@ -set(CMake_RUN_CLANG_TIDY ON CACHE BOOL "") - -include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora33_common.cmake") diff --git a/.gitlab/ci/configure_fedora34_asan.cmake b/.gitlab/ci/configure_fedora34_asan.cmake new file mode 100644 index 00000000000..c22cdb7bd1b --- /dev/null +++ b/.gitlab/ci/configure_fedora34_asan.cmake @@ -0,0 +1,4 @@ +set(CMAKE_C_FLAGS "-fsanitize=address" CACHE STRING "") +set(CMAKE_CXX_FLAGS "-fsanitize=address" CACHE STRING "") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora34_common.cmake") diff --git a/.gitlab/ci/configure_fedora34_clang_analyzer.cmake b/.gitlab/ci/configure_fedora34_clang_analyzer.cmake new file mode 100644 index 00000000000..e00f8a7b1bc --- /dev/null +++ b/.gitlab/ci/configure_fedora34_clang_analyzer.cmake @@ -0,0 +1 @@ +include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora34_common.cmake") diff --git a/.gitlab/ci/configure_fedora33_common.cmake b/.gitlab/ci/configure_fedora34_common.cmake similarity index 82% rename from .gitlab/ci/configure_fedora33_common.cmake rename to .gitlab/ci/configure_fedora34_common.cmake index dee78abfe73..4484e264ff0 100644 --- a/.gitlab/ci/configure_fedora33_common.cmake +++ b/.gitlab/ci/configure_fedora34_common.cmake @@ -1,5 +1,6 @@ set(BUILD_CursesDialog ON CACHE BOOL "") set(BUILD_QtDialog ON CACHE BOOL "") +set(CMake_QT_MAJOR_VERSION "5" CACHE STRING "") set(CMake_TEST_JQ "/usr/bin/jq" CACHE PATH "") set(CMake_TEST_JSON_SCHEMA ON CACHE BOOL "") diff --git a/.gitlab/ci/configure_fedora33_makefiles.cmake b/.gitlab/ci/configure_fedora34_makefiles.cmake similarity index 91% rename from .gitlab/ci/configure_fedora33_makefiles.cmake rename to .gitlab/ci/configure_fedora34_makefiles.cmake index db2d0059be0..a482378a4d3 100644 --- a/.gitlab/ci/configure_fedora33_makefiles.cmake +++ b/.gitlab/ci/configure_fedora34_makefiles.cmake @@ -1,10 +1,11 @@ set(CMake_TEST_FindALSA "ON" CACHE BOOL "") -set(CMake_TEST_FindBLAS "ON" CACHE BOOL "") +set(CMake_TEST_FindBLAS "All;static=1;Generic" CACHE STRING "") set(CMake_TEST_FindBoost "ON" CACHE BOOL "") set(CMake_TEST_FindBoost_Python "ON" CACHE BOOL "") set(CMake_TEST_FindBZip2 "ON" CACHE BOOL "") set(CMake_TEST_FindCups "ON" CACHE BOOL "") set(CMake_TEST_FindCURL "ON" CACHE BOOL "") +set(CMake_TEST_FindDevIL "ON" CACHE BOOL "") set(CMake_TEST_FindDoxygen_Dot "ON" CACHE BOOL "") set(CMake_TEST_FindDoxygen "ON" CACHE BOOL "") set(CMake_TEST_FindEXPAT "ON" CACHE BOOL "") @@ -14,6 +15,7 @@ set(CMake_TEST_FindGDAL "ON" CACHE BOOL "") set(CMake_TEST_FindGIF "ON" CACHE BOOL "") set(CMake_TEST_FindGit "ON" CACHE BOOL "") set(CMake_TEST_FindGLEW "ON" CACHE BOOL "") +set(CMake_TEST_FindGLUT "ON" CACHE BOOL "") set(CMake_TEST_FindGnuTLS "ON" CACHE BOOL "") set(CMake_TEST_FindGSL "ON" CACHE BOOL "") set(CMake_TEST_FindGTest "ON" CACHE BOOL "") @@ -22,7 +24,7 @@ set(CMake_TEST_FindIconv "ON" CACHE BOOL "") set(CMake_TEST_FindIntl "ON" CACHE BOOL "") set(CMake_TEST_FindJPEG "ON" CACHE BOOL "") set(CMake_TEST_FindJsonCpp "ON" CACHE BOOL "") -set(CMake_TEST_FindLAPACK "ON" CACHE BOOL "") +set(CMake_TEST_FindLAPACK "All;static=1;Generic" CACHE STRING "") set(CMake_TEST_FindLibArchive "ON" CACHE BOOL "") set(CMake_TEST_FindLibinput "ON" CACHE BOOL "") set(CMake_TEST_FindLibLZMA "ON" CACHE BOOL "") @@ -45,6 +47,7 @@ set(CMake_TEST_FindPatch "ON" CACHE BOOL "") set(CMake_TEST_FindPNG "ON" CACHE BOOL "") set(CMake_TEST_FindPostgreSQL "ON" CACHE BOOL "") set(CMake_TEST_FindProtobuf "ON" CACHE BOOL "") +set(CMake_TEST_FindProtobuf_gRPC "ON" CACHE BOOL "") set(CMake_TEST_FindPython "ON" CACHE BOOL "") set(CMake_TEST_FindPython_NumPy "ON" CACHE BOOL "") set(CMake_TEST_FindPython_PyPy "ON" CACHE BOOL "") diff --git a/.gitlab/ci/configure_fedora33_ninja.cmake b/.gitlab/ci/configure_fedora34_ninja.cmake similarity index 75% rename from .gitlab/ci/configure_fedora33_ninja.cmake rename to .gitlab/ci/configure_fedora34_ninja.cmake index 883f425e7bc..37bc189dbc6 100644 --- a/.gitlab/ci/configure_fedora33_ninja.cmake +++ b/.gitlab/ci/configure_fedora34_ninja.cmake @@ -4,4 +4,4 @@ set(CMake_TEST_GUI "ON" CACHE BOOL "") # Cover compilation with C++11 only and not higher standards. set(CMAKE_CXX_STANDARD "11" CACHE STRING "") -include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora33_common.cmake") +include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora34_common.cmake") diff --git a/.gitlab/ci/configure_fedora33_ninja_multi.cmake b/.gitlab/ci/configure_fedora34_ninja_multi.cmake similarity index 100% rename from .gitlab/ci/configure_fedora33_ninja_multi.cmake rename to .gitlab/ci/configure_fedora34_ninja_multi.cmake diff --git a/.gitlab/ci/configure_fedora33_sphinx.cmake b/.gitlab/ci/configure_fedora34_sphinx.cmake similarity index 100% rename from .gitlab/ci/configure_fedora33_sphinx.cmake rename to .gitlab/ci/configure_fedora34_sphinx.cmake diff --git a/.gitlab/ci/configure_fedora33_sphinx_package.cmake b/.gitlab/ci/configure_fedora34_sphinx_package.cmake similarity index 100% rename from .gitlab/ci/configure_fedora33_sphinx_package.cmake rename to .gitlab/ci/configure_fedora34_sphinx_package.cmake diff --git a/.gitlab/ci/configure_fedora34_tidy.cmake b/.gitlab/ci/configure_fedora34_tidy.cmake new file mode 100644 index 00000000000..9c79303dfe1 --- /dev/null +++ b/.gitlab/ci/configure_fedora34_tidy.cmake @@ -0,0 +1,3 @@ +set(CMake_RUN_CLANG_TIDY ON CACHE BOOL "") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora34_common.cmake") diff --git a/.gitlab/ci/configure_hip4.2_radeon.cmake b/.gitlab/ci/configure_hip4.2_radeon.cmake new file mode 100644 index 00000000000..58036b05a02 --- /dev/null +++ b/.gitlab/ci/configure_hip4.2_radeon.cmake @@ -0,0 +1,3 @@ +set(CMake_TEST_HIP "ON" CACHE BOOL "") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake") diff --git a/.gitlab/ci/configure_intelclassic_makefiles.cmake b/.gitlab/ci/configure_intelclassic_makefiles.cmake new file mode 100644 index 00000000000..469b8256613 --- /dev/null +++ b/.gitlab/ci/configure_intelclassic_makefiles.cmake @@ -0,0 +1 @@ +include("${CMAKE_CURRENT_LIST_DIR}/configure_intelcompiler_common.cmake") diff --git a/.gitlab/ci/configure_intelcompiler_common.cmake b/.gitlab/ci/configure_intelcompiler_common.cmake new file mode 100644 index 00000000000..bd34740f0cf --- /dev/null +++ b/.gitlab/ci/configure_intelcompiler_common.cmake @@ -0,0 +1,13 @@ +set(blas_lapack_cases + model=lp64 all=Intel10_64lp + static=0 All Intel10_64lp compiler=gcc Intel10_64lp compiler= + static=1 All Intel10_64lp compiler=gcc Intel10_64lp compiler= + + model=ilp64 all=Intel10_64ilp + static=0 All Intel10_64ilp compiler=gcc Intel10_64ilp compiler= + static=1 All Intel10_64ilp compiler=gcc Intel10_64ilp compiler= + ) +set(CMake_TEST_FindBLAS "${blas_lapack_cases}" CACHE STRING "") +set(CMake_TEST_FindLAPACK "${blas_lapack_cases}" CACHE STRING "") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake") diff --git a/.gitlab/ci/configure_inteloneapi_makefiles.cmake b/.gitlab/ci/configure_inteloneapi_makefiles.cmake new file mode 100644 index 00000000000..469b8256613 --- /dev/null +++ b/.gitlab/ci/configure_inteloneapi_makefiles.cmake @@ -0,0 +1 @@ +include("${CMAKE_CURRENT_LIST_DIR}/configure_intelcompiler_common.cmake") diff --git a/.gitlab/ci/configure_macos_common.cmake b/.gitlab/ci/configure_macos_common.cmake index 37cd51c2052..e78c9cec334 100644 --- a/.gitlab/ci/configure_macos_common.cmake +++ b/.gitlab/ci/configure_macos_common.cmake @@ -2,7 +2,7 @@ # detect that Java is available and working, but a test machine then not have a # working Java installed. To work around this, just act as if Java is not # available on any CI machine. -set(CMake_TEST_Java 0 CACHE FILEPATH "") +set(CMake_TEST_Java OFF CACHE BOOL "") # Qt binaries get placed inside the source directory, which causes them to not # be included in the install-time rpath, but we still want them in the diff --git a/.gitlab/ci/configure_windows_common.cmake b/.gitlab/ci/configure_windows_common.cmake index 45250acbe20..112846a9ad8 100644 --- a/.gitlab/ci/configure_windows_common.cmake +++ b/.gitlab/ci/configure_windows_common.cmake @@ -1,4 +1,5 @@ set(BUILD_QtDialog ON CACHE BOOL "") set(CMAKE_PREFIX_PATH "$ENV{CI_PROJECT_DIR}/.gitlab/qt" CACHE STRING "") +set(CMake_TEST_Java OFF CACHE BOOL "") include("${CMAKE_CURRENT_LIST_DIR}/configure_common.cmake") diff --git a/.gitlab/ci/configure_windows_vs2019_x64.cmake b/.gitlab/ci/configure_windows_vs2022_x64.cmake similarity index 75% rename from .gitlab/ci/configure_windows_vs2019_x64.cmake rename to .gitlab/ci/configure_windows_vs2022_x64.cmake index f6ece57c884..7c024a8e09b 100644 --- a/.gitlab/ci/configure_windows_vs2019_x64.cmake +++ b/.gitlab/ci/configure_windows_vs2022_x64.cmake @@ -1,3 +1,4 @@ set(CMake_TEST_WIX_NO_VERIFY "ON" CACHE BOOL "") +set(CMake_TEST_Java OFF CACHE BOOL "") include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake") diff --git a/.gitlab/ci/configure_windows_vs2019_x64_ninja.cmake b/.gitlab/ci/configure_windows_vs2022_x64_ninja.cmake similarity index 52% rename from .gitlab/ci/configure_windows_vs2019_x64_ninja.cmake rename to .gitlab/ci/configure_windows_vs2022_x64_ninja.cmake index 9c30a4b7836..e1ae81e3d36 100644 --- a/.gitlab/ci/configure_windows_vs2019_x64_ninja.cmake +++ b/.gitlab/ci/configure_windows_vs2022_x64_ninja.cmake @@ -1,4 +1,7 @@ set(CMake_TEST_WIX_NO_VERIFY "ON" CACHE BOOL "") set(CMake_TEST_GUI "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenGL "ON" CACHE BOOL "") +set(CMake_TEST_IPO_WORKS_C "ON" CACHE BOOL "") +set(CMake_TEST_IPO_WORKS_CXX "ON" CACHE BOOL "") include("${CMAKE_CURRENT_LIST_DIR}/configure_windows_common.cmake") diff --git a/.gitlab/ci/ctest_exclusions.cmake b/.gitlab/ci/ctest_exclusions.cmake index a68a693bf4c..3460d48cbd9 100644 --- a/.gitlab/ci/ctest_exclusions.cmake +++ b/.gitlab/ci/ctest_exclusions.cmake @@ -13,12 +13,10 @@ if (CTEST_CMAKE_GENERATOR MATCHES "Visual Studio") "^ExternalProjectUpdateSetup$") endif () -if (CMAKE_HOST_WIN32) +if ("$ENV{CMAKE_CONFIGURATION}" MATCHES "_asan") list(APPEND test_exclusions - # This test often fails with an undiagnosed subtle race due to the test - # re-using the same objects for many files. Some copy operations fail - # to open their input with ERROR_SHARING_VIOLATION. - "^Module.ExternalData$" + CTestTest2 # crashes on purpose + BootstrapTest # no need to cover this for asan ) endif() diff --git a/.gitlab/ci/ctest_memcheck.cmake b/.gitlab/ci/ctest_memcheck.cmake new file mode 100644 index 00000000000..dac907c1577 --- /dev/null +++ b/.gitlab/ci/ctest_memcheck.cmake @@ -0,0 +1,45 @@ +cmake_minimum_required(VERSION 3.8) + +include("${CMAKE_CURRENT_LIST_DIR}/gitlab_ci.cmake") + +# Read the files from the build directory. +ctest_read_custom_files("${CTEST_BINARY_DIRECTORY}") + +# Pick up from where the configure left off. +ctest_start(APPEND) + +include(ProcessorCount) +ProcessorCount(nproc) +if (NOT "$ENV{CTEST_MAX_PARALLELISM}" STREQUAL "") + if (nproc GREATER "$ENV{CTEST_MAX_PARALLELISM}") + set(nproc "$ENV{CTEST_MAX_PARALLELISM}") + endif () +endif () + +set(CTEST_MEMORYCHECK_TYPE "$ENV{CTEST_MEMORYCHECK_TYPE}") +set(CTEST_MEMORYCHECK_SANITIZER_OPTIONS "$ENV{CTEST_MEMORYCHECK_SANITIZER_OPTIONS}") + +set(lsan_suppressions "${CMAKE_CURRENT_LIST_DIR}/ctest_memcheck_$ENV{CMAKE_CONFIGURATION}.lsan.supp") +if (EXISTS "${lsan_suppressions}") + set(ENV{LSAN_OPTIONS} "suppressions='${lsan_suppressions}'") +endif () + +include("${CMAKE_CURRENT_LIST_DIR}/ctest_exclusions.cmake") +ctest_memcheck( + PARALLEL_LEVEL "${nproc}" + TEST_LOAD "${nproc}" + RETURN_VALUE test_result + EXCLUDE "${test_exclusions}" + DEFECT_COUNT defects) +ctest_submit(PARTS Test) +ctest_submit(PARTS Memcheck) + +if (test_result) + message(FATAL_ERROR + "Failed to test") +endif () + +if (defects) + message(FATAL_ERROR + "Found ${defects} memcheck defects") +endif () diff --git a/.gitlab/ci/ctest_memcheck_fedora34_asan.lsan.supp b/.gitlab/ci/ctest_memcheck_fedora34_asan.lsan.supp new file mode 100644 index 00000000000..8ec1a0358b2 --- /dev/null +++ b/.gitlab/ci/ctest_memcheck_fedora34_asan.lsan.supp @@ -0,0 +1 @@ +# Add 'leak:' lines here to suppress known leaks. diff --git a/.gitlab/ci/ctest_test.cmake b/.gitlab/ci/ctest_test.cmake index facf9ba4ba1..b02d032fa50 100644 --- a/.gitlab/ci/ctest_test.cmake +++ b/.gitlab/ci/ctest_test.cmake @@ -20,6 +20,7 @@ include("${CMAKE_CURRENT_LIST_DIR}/ctest_exclusions.cmake") ctest_test( PARALLEL_LEVEL "${nproc}" TEST_LOAD "${nproc}" + OUTPUT_JUNIT "${CTEST_BINARY_DIRECTORY}/junit.xml" RETURN_VALUE test_result EXCLUDE "${test_exclusions}") ctest_submit(PARTS Test) diff --git a/.gitlab/ci/ctest_test_external.cmake b/.gitlab/ci/ctest_test_external.cmake index 6576c263291..48e910b9966 100644 --- a/.gitlab/ci/ctest_test_external.cmake +++ b/.gitlab/ci/ctest_test_external.cmake @@ -74,6 +74,7 @@ include("${CMAKE_CURRENT_LIST_DIR}/ctest_exclusions.cmake") ctest_test( PARALLEL_LEVEL "${nproc}" TEST_LOAD "${nproc}" + OUTPUT_JUNIT "${CTEST_BINARY_DIRECTORY}/junit.xml" RETURN_VALUE test_result ${ctest_label_args} EXCLUDE "${test_exclusions}") diff --git a/.gitlab/ci/docker/cuda10.2/Dockerfile b/.gitlab/ci/docker/cuda10.2/Dockerfile index e0ea0e73623..b6f37b51789 100644 --- a/.gitlab/ci/docker/cuda10.2/Dockerfile +++ b/.gitlab/ci/docker/cuda10.2/Dockerfile @@ -1,5 +1,9 @@ FROM nvidia/cuda:10.2-devel-ubuntu18.04 MAINTAINER Ben Boeckel +COPY llvm.list /etc/apt/sources.list.d/llvm.list +COPY llvm-snapshot.gpg.key /root/llvm-snapshot.gpg.key +RUN apt-key add /root/llvm-snapshot.gpg.key + COPY install_deps.sh /root/install_deps.sh RUN sh /root/install_deps.sh diff --git a/.gitlab/ci/docker/cuda10.2/install_deps.sh b/.gitlab/ci/docker/cuda10.2/install_deps.sh index 0d57cd386d8..6d539979d96 100755 --- a/.gitlab/ci/docker/cuda10.2/install_deps.sh +++ b/.gitlab/ci/docker/cuda10.2/install_deps.sh @@ -7,6 +7,7 @@ apt-get update # Install development tools. apt-get install -y \ g++ \ + clang-11 \ curl \ git diff --git a/.gitlab/ci/docker/cuda10.2/llvm-snapshot.gpg.key b/.gitlab/ci/docker/cuda10.2/llvm-snapshot.gpg.key new file mode 100644 index 00000000000..aa6b105aa3d --- /dev/null +++ b/.gitlab/ci/docker/cuda10.2/llvm-snapshot.gpg.key @@ -0,0 +1,52 @@ +-----BEGIN PGP PUBLIC KEY BLOCK----- +Version: GnuPG v1.4.12 (GNU/Linux) + +mQINBFE9lCwBEADi0WUAApM/mgHJRU8lVkkw0CHsZNpqaQDNaHefD6Rw3S4LxNmM +EZaOTkhP200XZM8lVdbfUW9xSjA3oPldc1HG26NjbqqCmWpdo2fb+r7VmU2dq3NM +R18ZlKixiLDE6OUfaXWKamZsXb6ITTYmgTO6orQWYrnW6ckYHSeaAkW0wkDAryl2 +B5v8aoFnQ1rFiVEMo4NGzw4UX+MelF7rxaaregmKVTPiqCOSPJ1McC1dHFN533FY +Wh/RVLKWo6npu+owtwYFQW+zyQhKzSIMvNujFRzhIxzxR9Gn87MoLAyfgKEzrbbT +DhqqNXTxS4UMUKCQaO93TzetX/EBrRpJj+vP640yio80h4Dr5pAd7+LnKwgpTDk1 +G88bBXJAcPZnTSKu9I2c6KY4iRNbvRz4i+ZdwwZtdW4nSdl2792L7Sl7Nc44uLL/ +ZqkKDXEBF6lsX5XpABwyK89S/SbHOytXv9o4puv+65Ac5/UShspQTMSKGZgvDauU +cs8kE1U9dPOqVNCYq9Nfwinkf6RxV1k1+gwtclxQuY7UpKXP0hNAXjAiA5KS5Crq +7aaJg9q2F4bub0mNU6n7UI6vXguF2n4SEtzPRk6RP+4TiT3bZUsmr+1ktogyOJCc +Ha8G5VdL+NBIYQthOcieYCBnTeIH7D3Sp6FYQTYtVbKFzmMK+36ERreL/wARAQAB +tD1TeWx2ZXN0cmUgTGVkcnUgLSBEZWJpYW4gTExWTSBwYWNrYWdlcyA8c3lsdmVz +dHJlQGRlYmlhbi5vcmc+iQI4BBMBAgAiBQJRPZQsAhsDBgsJCAcDAgYVCAIJCgsE +FgIDAQIeAQIXgAAKCRAVz00Yr090Ibx+EADArS/hvkDF8juWMXxh17CgR0WZlHCC +9CTBWkg5a0bNN/3bb97cPQt/vIKWjQtkQpav6/5JTVCSx2riL4FHYhH0iuo4iAPR +udC7Cvg8g7bSPrKO6tenQZNvQm+tUmBHgFiMBJi92AjZ/Qn1Shg7p9ITivFxpLyX +wpmnF1OKyI2Kof2rm4BFwfSWuf8Fvh7kDMRLHv+MlnK/7j/BNpKdozXxLcwoFBmn +l0WjpAH3OFF7Pvm1LJdf1DjWKH0Dc3sc6zxtmBR/KHHg6kK4BGQNnFKujcP7TVdv +gMYv84kun14pnwjZcqOtN3UJtcx22880DOQzinoMs3Q4w4o05oIF+sSgHViFpc3W +R0v+RllnH05vKZo+LDzc83DQVrdwliV12eHxrMQ8UYg88zCbF/cHHnlzZWAJgftg +hB08v1BKPgYRUzwJ6VdVqXYcZWEaUJmQAPuAALyZESw94hSo28FAn0/gzEc5uOYx +K+xG/lFwgAGYNb3uGM5m0P6LVTfdg6vDwwOeTNIExVk3KVFXeSQef2ZMkhwA7wya +KJptkb62wBHFE+o9TUdtMCY6qONxMMdwioRE5BYNwAsS1PnRD2+jtlI0DzvKHt7B +MWd8hnoUKhMeZ9TNmo+8CpsAtXZcBho0zPGz/R8NlJhAWpdAZ1CmcPo83EW86Yq7 +BxQUKnNHcwj2ebkCDQRRPZQsARAA4jxYmbTHwmMjqSizlMJYNuGOpIidEdx9zQ5g +zOr431/VfWq4S+VhMDhs15j9lyml0y4ok215VRFwrAREDg6UPMr7ajLmBQGau0Fc +bvZJ90l4NjXp5p0NEE/qOb9UEHT7EGkEhaZ1ekkWFTWCgsy7rRXfZLxB6sk7pzLC +DshyW3zjIakWAnpQ5j5obiDy708pReAuGB94NSyb1HoW/xGsGgvvCw4r0w3xPStw +F1PhmScE6NTBIfLliea3pl8vhKPlCh54Hk7I8QGjo1ETlRP4Qll1ZxHJ8u25f/ta +RES2Aw8Hi7j0EVcZ6MT9JWTI83yUcnUlZPZS2HyeWcUj+8nUC8W4N8An+aNps9l/ +21inIl2TbGo3Yn1JQLnA1YCoGwC34g8QZTJhElEQBN0X29ayWW6OdFx8MDvllbBV +ymmKq2lK1U55mQTfDli7S3vfGz9Gp/oQwZ8bQpOeUkc5hbZszYwP4RX+68xDPfn+ +M9udl+qW9wu+LyePbW6HX90LmkhNkkY2ZzUPRPDHZANU5btaPXc2H7edX4y4maQa +xenqD0lGh9LGz/mps4HEZtCI5CY8o0uCMF3lT0XfXhuLksr7Pxv57yue8LLTItOJ +d9Hmzp9G97SRYYeqU+8lyNXtU2PdrLLq7QHkzrsloG78lCpQcalHGACJzrlUWVP/ +fN3Ht3kAEQEAAYkCHwQYAQIACQUCUT2ULAIbDAAKCRAVz00Yr090IbhWEADbr50X +OEXMIMGRLe+YMjeMX9NG4jxs0jZaWHc/WrGR+CCSUb9r6aPXeLo+45949uEfdSsB +pbaEdNWxF5Vr1CSjuO5siIlgDjmT655voXo67xVpEN4HhMrxugDJfCa6z97P0+ML +PdDxim57uNqkam9XIq9hKQaurxMAECDPmlEXI4QT3eu5qw5/knMzDMZj4Vi6hovL +wvvAeLHO/jsyfIdNmhBGU2RWCEZ9uo/MeerPHtRPfg74g+9PPfP6nyHD2Wes6yGd +oVQwtPNAQD6Cj7EaA2xdZYLJ7/jW6yiPu98FFWP74FN2dlyEA2uVziLsfBrgpS4l +tVOlrO2YzkkqUGrybzbLpj6eeHx+Cd7wcjI8CalsqtL6cG8cUEjtWQUHyTbQWAgG +5VPEgIAVhJ6RTZ26i/G+4J8neKyRs4vz+57UGwY6zI4AB1ZcWGEE3Bf+CDEDgmnP +LSwbnHefK9IljT9XU98PelSryUO/5UPw7leE0akXKB4DtekToO226px1VnGp3Bov +1GBGvpHvL2WizEwdk+nfk8LtrLzej+9FtIcq3uIrYnsac47Pf7p0otcFeTJTjSq3 +krCaoG4Hx0zGQG2ZFpHrSrZTVy6lxvIdfi0beMgY6h78p6M9eYZHQHc02DjFkQXN +bXb5c6gCHESH5PXwPU4jQEE7Ib9J6sbk7ZT2Mw== +=j+4q +-----END PGP PUBLIC KEY BLOCK----- diff --git a/.gitlab/ci/docker/cuda10.2/llvm.list b/.gitlab/ci/docker/cuda10.2/llvm.list new file mode 100644 index 00000000000..79f8265e72c --- /dev/null +++ b/.gitlab/ci/docker/cuda10.2/llvm.list @@ -0,0 +1,2 @@ +deb http://apt.llvm.org/bionic/ llvm-toolchain-bionic-11 main +deb-src http://apt.llvm.org/bionic/ llvm-toolchain-bionic-11 main diff --git a/.gitlab/ci/docker/cuda9.2/Dockerfile b/.gitlab/ci/docker/cuda9.2/Dockerfile new file mode 100644 index 00000000000..7eae886b53e --- /dev/null +++ b/.gitlab/ci/docker/cuda9.2/Dockerfile @@ -0,0 +1,5 @@ +FROM nvidia/cuda:9.2-devel-ubuntu16.04 +MAINTAINER Brad King + +COPY install_deps.sh /root/install_deps.sh +RUN sh /root/install_deps.sh diff --git a/.gitlab/ci/docker/cuda9.2/install_deps.sh b/.gitlab/ci/docker/cuda9.2/install_deps.sh new file mode 100755 index 00000000000..0dcb507e66b --- /dev/null +++ b/.gitlab/ci/docker/cuda9.2/install_deps.sh @@ -0,0 +1,20 @@ +#!/bin/sh + +set -e + +apt-get update + +# Update base packages. +apt-get install -y \ + libgnutls30 \ + libssl1.0.0 \ + openssl + +# Install development tools. +apt-get install -y \ + g++ \ + clang-3.8 \ + curl \ + git + +apt-get clean diff --git a/.gitlab/ci/docker/debian10-aarch64/install_deps.sh b/.gitlab/ci/docker/debian10-aarch64/install_deps.sh index d84b3c87d05..d5c5e22f544 100755 --- a/.gitlab/ci/docker/debian10-aarch64/install_deps.sh +++ b/.gitlab/ci/docker/debian10-aarch64/install_deps.sh @@ -23,10 +23,17 @@ apt-get install -y \ apt-get install -y \ jq +# Packages needed to test CTest. +apt-get install -y \ + cvs \ + subversion \ + mercurial + # Packages needed to test find modules. apt-get install -y \ alsa-utils \ doxygen graphviz \ + freeglut3-dev \ gnutls-dev \ libarchive-dev \ libblas-dev \ @@ -45,6 +52,8 @@ apt-get install -y \ libgif-dev \ libgl1-mesa-dev \ libglew-dev \ + libgmock-dev \ + libgrpc++-dev libgrpc-dev \ libgsl-dev \ libgtest-dev \ libgtk2.0-dev \ @@ -56,7 +65,7 @@ apt-get install -y \ libopenmpi-dev openmpi-bin \ libpng-dev \ libpq-dev postgresql-server-dev-11 \ - libprotobuf-dev libprotobuf-c-dev libprotoc-dev protobuf-compiler \ + libprotobuf-dev libprotobuf-c-dev libprotoc-dev protobuf-compiler protobuf-compiler-grpc \ libsdl-dev \ libsqlite3-dev \ libtiff-dev \ diff --git a/.gitlab/ci/docker/debian10/install_deps.sh b/.gitlab/ci/docker/debian10/install_deps.sh index e6c9ba09994..d3d6b672400 100755 --- a/.gitlab/ci/docker/debian10/install_deps.sh +++ b/.gitlab/ci/docker/debian10/install_deps.sh @@ -23,10 +23,17 @@ apt-get install -y \ apt-get install -y \ jq +# Packages needed to test CTest. +apt-get install -y \ + cvs \ + subversion \ + mercurial + # Packages needed to test find modules. apt-get install -y \ alsa-utils \ doxygen graphviz \ + freeglut3-dev \ gnutls-dev \ libarchive-dev \ libblas-dev \ @@ -45,6 +52,8 @@ apt-get install -y \ libgif-dev \ libgl1-mesa-dev \ libglew-dev \ + libgmock-dev \ + libgrpc++-dev libgrpc-dev \ libgsl-dev \ libgtest-dev \ libgtk2.0-dev \ @@ -56,7 +65,7 @@ apt-get install -y \ libopenmpi-dev openmpi-bin \ libpng-dev \ libpq-dev postgresql-server-dev-11 \ - libprotobuf-dev libprotobuf-c-dev libprotoc-dev protobuf-compiler \ + libprotobuf-dev libprotobuf-c-dev libprotoc-dev protobuf-compiler protobuf-compiler-grpc \ libsdl-dev \ libsqlite3-dev \ libtiff-dev \ diff --git a/.gitlab/ci/docker/debian10/install_rvm.sh b/.gitlab/ci/docker/debian10/install_rvm.sh index 2bea5119ad9..75c5adcb234 100755 --- a/.gitlab/ci/docker/debian10/install_rvm.sh +++ b/.gitlab/ci/docker/debian10/install_rvm.sh @@ -8,7 +8,7 @@ apt-get install -y \ gnupg2 \ procps -gpg2 --keyserver hkp://pool.sks-keyservers.net \ +gpg2 --keyserver hkps://keyserver.ubuntu.com \ --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 \ 7D2BAF1CF37B13E2069D6956105BD0E739499BDB diff --git a/.gitlab/ci/docker/fedora33/Dockerfile b/.gitlab/ci/docker/fedora34/Dockerfile similarity index 90% rename from .gitlab/ci/docker/fedora33/Dockerfile rename to .gitlab/ci/docker/fedora34/Dockerfile index 8ebcb9ee3f4..af2322d88d0 100644 --- a/.gitlab/ci/docker/fedora33/Dockerfile +++ b/.gitlab/ci/docker/fedora34/Dockerfile @@ -1,10 +1,10 @@ -FROM fedora:33 as rvm-build +FROM fedora:34 as rvm-build MAINTAINER Ben Boeckel COPY install_rvm.sh /root/install_rvm.sh RUN sh /root/install_rvm.sh -FROM fedora:33 +FROM fedora:34 MAINTAINER Ben Boeckel COPY install_deps.sh /root/install_deps.sh diff --git a/.gitlab/ci/docker/fedora33/install_deps.sh b/.gitlab/ci/docker/fedora34/install_deps.sh similarity index 70% rename from .gitlab/ci/docker/fedora33/install_deps.sh rename to .gitlab/ci/docker/fedora34/install_deps.sh index cdfe35e55e8..bef3a97e708 100755 --- a/.gitlab/ci/docker/fedora33/install_deps.sh +++ b/.gitlab/ci/docker/fedora34/install_deps.sh @@ -6,11 +6,13 @@ set -e dnf install --setopt=install_weak_deps=False -y \ ncurses-devel \ openssl-devel \ - qt5-qtbase-devel + qt5-qtbase-devel \ + qt6-qtbase-devel # Install development tools. dnf install --setopt=install_weak_deps=False -y \ clang-tools-extra \ + compiler-rt \ gcc-c++ \ git-core \ make @@ -19,7 +21,13 @@ dnf install --setopt=install_weak_deps=False -y \ dnf install --setopt=install_weak_deps=False -y \ python3-sphinx \ texinfo \ - qt5-qttools-devel + qt5-qttools-devel \ + qt6-qttools-devel + +# Install lint tools. +dnf install --setopt=install_weak_deps=False -y \ + clang-analyzer \ + codespell # Tools needed for the test suite. dnf install --setopt=install_weak_deps=False -y \ @@ -28,6 +36,15 @@ dnf install --setopt=install_weak_deps=False -y \ jq \ which +# Packages needed to test CTest. +dnf install --setopt=install_weak_deps=False -y \ + subversion \ + mercurial + +# Packages needed to test CPack. +dnf install --setopt=install_weak_deps=False -y \ + rpm-build + # Packages needed to test find modules. dnf install --setopt=install_weak_deps=False -y \ alsa-lib-devel \ @@ -39,6 +56,7 @@ dnf install --setopt=install_weak_deps=False -y \ doxygen \ expat-devel \ fontconfig-devel \ + freeglut-devel \ freetype-devel \ gdal-devel \ gettext \ @@ -46,6 +64,7 @@ dnf install --setopt=install_weak_deps=False -y \ glew-devel \ gmock \ gnutls-devel \ + grpc-devel grpc-plugins \ gsl-devel \ gtest-devel \ gtk2-devel \ @@ -61,13 +80,14 @@ dnf install --setopt=install_weak_deps=False -y \ libuv-devel \ libxml2-devel \ libxslt-devel \ + mpich-devel \ openmpi-devel \ patch \ perl \ protobuf-devel protobuf-c-devel protobuf-lite-devel \ pypy2 pypy2-devel \ pypy3 pypy3-devel \ - python2 python2-devel python2-numpy \ + python2 python2-devel \ python3 python3-devel python3-numpy \ python3-jsmin python3-jsonschema \ ruby rubygems ruby-devel \ @@ -80,3 +100,9 @@ dnf install --setopt=install_weak_deps=False -y \ xz-devel dnf clean all + +# Fedora no longer packages python2 numpy. +curl https://bootstrap.pypa.io/pip/2.7/get-pip.py -o get-pip.py +python2 get-pip.py +rm get-pip.py +pip2.7 install numpy diff --git a/.gitlab/ci/docker/fedora33/install_ispc.sh b/.gitlab/ci/docker/fedora34/install_ispc.sh similarity index 100% rename from .gitlab/ci/docker/fedora33/install_ispc.sh rename to .gitlab/ci/docker/fedora34/install_ispc.sh diff --git a/.gitlab/ci/docker/fedora33/install_rvm.sh b/.gitlab/ci/docker/fedora34/install_rvm.sh similarity index 90% rename from .gitlab/ci/docker/fedora33/install_rvm.sh rename to .gitlab/ci/docker/fedora34/install_rvm.sh index 6d4fa97f901..fca51045faf 100755 --- a/.gitlab/ci/docker/fedora33/install_rvm.sh +++ b/.gitlab/ci/docker/fedora34/install_rvm.sh @@ -2,7 +2,7 @@ set -e -gpg2 --keyserver hkp://pool.sks-keyservers.net \ +gpg2 --keyserver hkps://keyserver.ubuntu.com \ --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 \ 7D2BAF1CF37B13E2069D6956105BD0E739499BDB diff --git a/.gitlab/ci/docker/hip4.2/Dockerfile b/.gitlab/ci/docker/hip4.2/Dockerfile new file mode 100644 index 00000000000..563e94f4798 --- /dev/null +++ b/.gitlab/ci/docker/hip4.2/Dockerfile @@ -0,0 +1,7 @@ +FROM rocm/dev-ubuntu-20.04:4.2 +MAINTAINER Brad King + +ENV PATH="/opt/rocm/bin:$PATH" + +COPY install_deps.sh /root/install_deps.sh +RUN sh /root/install_deps.sh diff --git a/.gitlab/ci/docker/hip4.2/install_deps.sh b/.gitlab/ci/docker/hip4.2/install_deps.sh new file mode 100755 index 00000000000..2b45bc92863 --- /dev/null +++ b/.gitlab/ci/docker/hip4.2/install_deps.sh @@ -0,0 +1,13 @@ +#!/bin/sh + +set -e + +apt-get update + +# Install development tools. +apt-get install -y --no-install-recommends \ + g++ \ + curl \ + git + +apt-get clean diff --git a/.gitlab/ci/download_qt.cmake b/.gitlab/ci/download_qt.cmake index 3990430135e..5940a285e7b 100644 --- a/.gitlab/ci/download_qt.cmake +++ b/.gitlab/ci/download_qt.cmake @@ -18,7 +18,8 @@ if ("$ENV{CMAKE_CONFIGURATION}" MATCHES "windows") set(msvc_year "2015") set(qt_abi "win64_msvc${msvc_year}_64") elseif ("$ENV{CMAKE_CONFIGURATION}" MATCHES "vs2017" OR - "$ENV{CMAKE_CONFIGURATION}" MATCHES "vs2019") + "$ENV{CMAKE_CONFIGURATION}" MATCHES "vs2019" OR + "$ENV{CMAKE_CONFIGURATION}" MATCHES "vs2022") set(qt_platform "windows_x86") set(msvc_year "2019") set(qt_abi "win64_msvc${msvc_year}_64") diff --git a/.gitlab/ci/env.sh b/.gitlab/ci/env.sh new file mode 100644 index 00000000000..7634f5deeed --- /dev/null +++ b/.gitlab/ci/env.sh @@ -0,0 +1,14 @@ +quietly() { + readonly log="/tmp/quietly-$RANDOM.log" + if ! "$@" >"$log" 2>&1; then + ret=$? + cat "$log" + rm -f "$log" + exit $ret + fi + rm -f "$log" +} + +if test -r ".gitlab/ci/env_${CMAKE_CONFIGURATION}.sh"; then + source ".gitlab/ci/env_${CMAKE_CONFIGURATION}.sh" +fi diff --git a/.gitlab/ci/env_cuda10.2_clang.sh b/.gitlab/ci/env_cuda10.2_clang.sh new file mode 100644 index 00000000000..d3b253016e8 --- /dev/null +++ b/.gitlab/ci/env_cuda10.2_clang.sh @@ -0,0 +1,3 @@ +export CC=/usr/bin/clang-11 +export CXX=/usr/bin/clang++-11 +export CUDACXX=/usr/bin/clang++-11 diff --git a/.gitlab/ci/env_cuda9.2_nvidia.sh b/.gitlab/ci/env_cuda9.2_nvidia.sh new file mode 100644 index 00000000000..16bfba4eeea --- /dev/null +++ b/.gitlab/ci/env_cuda9.2_nvidia.sh @@ -0,0 +1,4 @@ +export CC=/usr/bin/clang-3.8 +export CXX=/usr/bin/clang++-3.8 +export CUDAHOSTCXX=/usr/bin/g++-5 +export CUDACXX=/usr/local/cuda/bin/nvcc diff --git a/.gitlab/ci/env_debian10_makefiles_clang.sh b/.gitlab/ci/env_debian10_makefiles_clang.sh new file mode 100644 index 00000000000..e0d5d6105b3 --- /dev/null +++ b/.gitlab/ci/env_debian10_makefiles_clang.sh @@ -0,0 +1,2 @@ +export CC=/usr/bin/clang-7 +export CXX=/usr/bin/clang++-7 diff --git a/.gitlab/ci/env_debian10_ninja_clang.sh b/.gitlab/ci/env_debian10_ninja_clang.sh new file mode 100644 index 00000000000..e0d5d6105b3 --- /dev/null +++ b/.gitlab/ci/env_debian10_ninja_clang.sh @@ -0,0 +1,2 @@ +export CC=/usr/bin/clang-7 +export CXX=/usr/bin/clang++-7 diff --git a/.gitlab/ci/env_fedora34_asan.sh b/.gitlab/ci/env_fedora34_asan.sh new file mode 100644 index 00000000000..e9764862eb2 --- /dev/null +++ b/.gitlab/ci/env_fedora34_asan.sh @@ -0,0 +1,2 @@ +export CC=/usr/bin/clang +export CXX=/usr/bin/clang++ diff --git a/.gitlab/ci/env_fedora34_clang_analyzer.sh b/.gitlab/ci/env_fedora34_clang_analyzer.sh new file mode 100644 index 00000000000..d732c0ba20b --- /dev/null +++ b/.gitlab/ci/env_fedora34_clang_analyzer.sh @@ -0,0 +1,2 @@ +export CC=/usr/libexec/ccc-analyzer +export CXX=/usr/libexec/c++-analyzer diff --git a/.gitlab/ci/env_fedora33_makefiles.cmake b/.gitlab/ci/env_fedora34_makefiles.cmake similarity index 53% rename from .gitlab/ci/env_fedora33_makefiles.cmake rename to .gitlab/ci/env_fedora34_makefiles.cmake index 1d0efa7d5ac..aa84e2396ad 100644 --- a/.gitlab/ci/env_fedora33_makefiles.cmake +++ b/.gitlab/ci/env_fedora34_makefiles.cmake @@ -1,2 +1,2 @@ set(ENV{MY_RUBY_HOME} "/usr/local/rvm/rubies/ruby-2.7.0") -set(ENV{PATH} "/usr/lib64/openmpi/bin:$ENV{PATH}") +set(ENV{PATH} "/usr/lib64/mpich/bin:$ENV{PATH}") diff --git a/.gitlab/ci/env_intelclassic_common.sh b/.gitlab/ci/env_intelclassic_common.sh new file mode 100644 index 00000000000..22b1d03ba3e --- /dev/null +++ b/.gitlab/ci/env_intelclassic_common.sh @@ -0,0 +1,9 @@ +source .gitlab/ci/env_intelcompiler_license.sh + +if test -r /opt/intel/oneapi/setvars.sh; then + source /opt/intel/oneapi/setvars.sh +elif test -r /opt/intel/bin/compilervars.sh; then + source /opt/intel/bin/compilervars.sh intel64 +fi + +export CC=icc CXX=icpc FC=ifort diff --git a/.gitlab/ci/env_intelclassic_makefiles.sh b/.gitlab/ci/env_intelclassic_makefiles.sh new file mode 100644 index 00000000000..d1ff85e0c54 --- /dev/null +++ b/.gitlab/ci/env_intelclassic_makefiles.sh @@ -0,0 +1 @@ +source .gitlab/ci/env_intelclassic_common.sh diff --git a/.gitlab/ci/env_intelcompiler_license.sh b/.gitlab/ci/env_intelcompiler_license.sh new file mode 100644 index 00000000000..54743b28e2e --- /dev/null +++ b/.gitlab/ci/env_intelcompiler_license.sh @@ -0,0 +1,8 @@ +if test -n "$CMAKE_CI_INTELCOMPILER_LICENSE"; then + if test -d /opt/intel/licenses; then + mv "$CMAKE_CI_INTELCOMPILER_LICENSE" /opt/intel/licenses/ci.lic + else + rm "$CMAKE_CI_INTELCOMPILER_LICENSE" + fi + unset CMAKE_CI_INTELCOMPILER_LICENSE +fi diff --git a/.gitlab/ci/env_inteloneapi_common.sh b/.gitlab/ci/env_inteloneapi_common.sh new file mode 100644 index 00000000000..beaf3feee9d --- /dev/null +++ b/.gitlab/ci/env_inteloneapi_common.sh @@ -0,0 +1,7 @@ +source .gitlab/ci/env_intelcompiler_license.sh + +if test -r /opt/intel/oneapi/setvars.sh; then + source /opt/intel/oneapi/setvars.sh +fi + +export CC=icx CXX=icpx FC=ifx diff --git a/.gitlab/ci/env_inteloneapi_makefiles.sh b/.gitlab/ci/env_inteloneapi_makefiles.sh new file mode 100644 index 00000000000..eefcddaeddc --- /dev/null +++ b/.gitlab/ci/env_inteloneapi_makefiles.sh @@ -0,0 +1 @@ +source .gitlab/ci/env_inteloneapi_common.sh diff --git a/.gitlab/ci/gitlab_ci.cmake b/.gitlab/ci/gitlab_ci.cmake index f863a279ce3..697162c7dd1 100644 --- a/.gitlab/ci/gitlab_ci.cmake +++ b/.gitlab/ci/gitlab_ci.cmake @@ -17,13 +17,17 @@ if ("$ENV{CMAKE_CONFIGURATION}" STREQUAL "") endif () # Set the build metadata. -set(CTEST_BUILD_NAME "$ENV{CI_PROJECT_NAME}-$ENV{CMAKE_CONFIGURATION}") +if(NOT "$ENV{CMAKE_CI_BUILD_NAME}" STREQUAL "") + set(CTEST_BUILD_NAME "$ENV{CI_PROJECT_NAME}-$ENV{CMAKE_CI_BUILD_NAME}") +else() + set(CTEST_BUILD_NAME "$ENV{CI_PROJECT_NAME}-$ENV{CMAKE_CONFIGURATION}") +endif() set(CTEST_SITE "gitlab-ci") set(ctest_model "Experimental") # Default to Release builds. -if (NOT "$ENV{CMAKE_BUILD_TYPE}" STREQUAL "") - set(CTEST_BUILD_CONFIGURATION "$ENV{CMAKE_BUILD_TYPE}") +if (NOT "$ENV{CMAKE_CI_BUILD_TYPE}" STREQUAL "") + set(CTEST_BUILD_CONFIGURATION "$ENV{CMAKE_CI_BUILD_TYPE}") endif () if (NOT CTEST_BUILD_CONFIGURATION) set(CTEST_BUILD_CONFIGURATION "Release") diff --git a/.gitlab/ci/ninja-nightly.sh b/.gitlab/ci/ninja-nightly.sh new file mode 100755 index 00000000000..b78b64e2404 --- /dev/null +++ b/.gitlab/ci/ninja-nightly.sh @@ -0,0 +1,11 @@ +#!/bin/sh + +set -e + +cd .gitlab + +git clone https://github.com/ninja-build/ninja.git ninja-src +cmake -S ninja-src -B ninja-src/build -DCMAKE_BUILD_TYPE=Release +cmake --build ninja-src/build --parallel --target ninja +mv ninja-src/build/ninja . +rm -rf ninja-src diff --git a/.gitlab/ci/ninja.sh b/.gitlab/ci/ninja.sh index 8ead67085e3..866d1d5edc7 100755 --- a/.gitlab/ci/ninja.sh +++ b/.gitlab/ci/ninja.sh @@ -2,6 +2,10 @@ set -e +if test "$CMAKE_CI_JOB_NIGHTLY_NINJA" = "true" -a "$CMAKE_CI_NIGHTLY" = "true"; then + exec .gitlab/ci/ninja-nightly.sh +fi + readonly version="1.10.2" baseurl="https://github.com/ninja-build/ninja/releases/download/v$version" diff --git a/.gitlab/ci/sccache.sh b/.gitlab/ci/sccache.sh index 12b8f9d0d39..b6b3751eecd 100755 --- a/.gitlab/ci/sccache.sh +++ b/.gitlab/ci/sccache.sh @@ -2,57 +2,42 @@ set -e -readonly kernel="$(uname -s)-$(uname -m)" -case $kernel in - Linux-x86_64) - version="v0.2.15" - shatool="sha256sum" - sha256sum="e5d03a9aa3b9fac7e490391bbe22d4f42c840d31ef9eaf127a03101930cbb7ca" - platform="x86_64-unknown-linux-musl" - ;; +readonly version="0.2.15-background-init" +readonly build_date="20210602.0" + +case "$( uname -s )-$(uname -m)" in Linux-aarch64) - version="v0.2.15" shatool="sha256sum" - sha256sum="90d91d21a767e3f558196dbd52395f6475c08de5c4951a4c8049575fa6894489" + sha256sum="28b9ad3f591874551a3f4c5c1ff32456d3328c15d7bd8bc63b4e5948a94f1def" platform="aarch64-unknown-linux-musl" ;; - Darwin-x86_64) - version="gfe63078" - shatool="shasum -a 256" - sha256sum="60a0302b1d7227f7ef56abd82266353f570d27c6e850c56c6448bf62def38888" - platform="x86_64-apple-darwin" - url="https://paraview.org/files/dependencies" + Linux-x86_64) + shatool="sha256sum" + sha256sum="34d62d30eae1a4145f00d62b01ad21c3456e28f11f8246c936b00cccf4855016" + platform="x86_64-unknown-linux-musl" ;; - Darwin-arm64) - version="0.2.15-1-disk_cache_init" + Darwin-x86_64|Darwin-arm64) shatool="shasum -a 256" - sha256sum="f7c9ff78e701810b8b1dbc2a163c7fda1177fc3f69c71f46e7a38242657a99fd" - platform="aarch64-apple-darwin" - url="https://cmake.org/files/dependencies/sccache" + sha256sum="2fa396e98cc8d07e39429b187a77386db63d35409902251d462080bdd0087c22" + platform="universal-apple-darwin" ;; *) - echo "Unrecognized platform $kernel" + echo "Unrecognized platform $( uname -s )-$( uname -m )" exit 1 ;; esac -readonly version readonly shatool readonly sha256sum readonly platform -readonly filename="sccache-$version-$platform" -readonly tarball="$filename.tar.gz" +readonly filename="sccache-v$version-$platform" -if [ -z "$url" ]; then - url="https://github.com/mozilla/sccache/releases/download/$version" -fi -readonly url +readonly url="https://gitlab.kitware.com/api/v4/projects/6955/packages/generic/sccache/v$version-$build_date/" cd .gitlab -echo "$sha256sum $tarball" > sccache.sha256sum -curl -OL "$url/$tarball" +echo "$sha256sum $filename" > sccache.sha256sum +curl -OL "$url/$filename" $shatool --check sccache.sha256sum -tar xf "$tarball" -mv "$filename/sccache" . +mv "$filename" sccache chmod +x sccache diff --git a/.gitlab/os-linux.yml b/.gitlab/os-linux.yml index 2670ba56171..c8315307019 100644 --- a/.gitlab/os-linux.yml +++ b/.gitlab/os-linux.yml @@ -5,7 +5,7 @@ ### Release .linux_prep_source: - image: "fedora:33" + image: "fedora:34" variables: GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake ci" @@ -30,10 +30,22 @@ variables: BOOTSTRAP_ARGS: '-- "-DCMake_DOC_ARTIFACT_PREFIX=$CI_PROJECT_DIR/build/install-doc"' +.needs_centos6_x86_64: + dependencies: + - b:centos6-x86_64 + needs: + - b:centos6-x86_64 + +.needs_centos7_aarch64: + dependencies: + - b:centos7-aarch64 + needs: + - b:centos7-aarch64 + ### Debian .debian10: - image: "kitware/cmake:ci-debian10-x86_64-2021-04-06" + image: "kitware/cmake:ci-debian10-x86_64-2021-11-18" variables: GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake ci" @@ -48,7 +60,7 @@ CMake_SKIP_INSTALL: 1 .debian10_aarch64: - image: "kitware/cmake:ci-debian10-aarch64-2021-04-06" + image: "kitware/cmake:ci-debian10-aarch64-2021-11-18" variables: GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake ci" @@ -56,8 +68,8 @@ ### Fedora -.fedora33: - image: "kitware/cmake:ci-fedora33-x86_64-2021-04-06" +.fedora34: + image: "kitware/cmake:ci-fedora34-x86_64-2021-10-05" variables: GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake ci/long file name for testing purposes" @@ -65,28 +77,37 @@ #### Lint builds -.fedora33_tidy: - extends: .fedora33 +.fedora34_tidy: + extends: .fedora34 variables: - CMAKE_CONFIGURATION: fedora33_tidy + CMAKE_CONFIGURATION: fedora34_tidy CTEST_NO_WARNINGS_ALLOWED: 1 CMake_SKIP_INSTALL: 1 -.fedora33_sphinx: - extends: .fedora33 +.fedora34_clang_analyzer: + extends: .fedora34 variables: - CMAKE_CONFIGURATION: fedora33_sphinx + CMAKE_CONFIGURATION: fedora34_clang_analyzer + CMAKE_CI_BUILD_TYPE: Debug + CTEST_NO_WARNINGS_ALLOWED: 1 + CMake_SKIP_INSTALL: 1 + +.fedora34_sphinx: + extends: .fedora34 + + variables: + CMAKE_CONFIGURATION: fedora34_sphinx CTEST_NO_WARNINGS_ALLOWED: 1 CTEST_SOURCE_SUBDIRECTORY: "Utilities/Sphinx" CMake_SKIP_INSTALL: 1 -.fedora33_sphinx_package: - extends: .fedora33 +.fedora34_sphinx_package: + extends: .fedora34 variables: - CMAKE_CONFIGURATION: fedora33_sphinx_package + CMAKE_CONFIGURATION: fedora34_sphinx_package CTEST_SOURCE_SUBDIRECTORY: "Utilities/Sphinx" #### Build and test @@ -105,33 +126,105 @@ CMAKE_CONFIGURATION: debian10_aarch64_ninja CTEST_NO_WARNINGS_ALLOWED: 1 -.fedora33_ninja: - extends: .fedora33 +.fedora34_ninja: + extends: .fedora34 variables: - CMAKE_CONFIGURATION: fedora33_ninja + CMAKE_CONFIGURATION: fedora34_ninja CTEST_NO_WARNINGS_ALLOWED: 1 -.fedora33_ninja_multi: - extends: .fedora33 +.fedora34_ninja_multi: + extends: .fedora34 variables: - CMAKE_CONFIGURATION: fedora33_ninja_multi + CMAKE_CONFIGURATION: fedora34_ninja_multi CTEST_NO_WARNINGS_ALLOWED: 1 CMAKE_GENERATOR: "Ninja Multi-Config" -.fedora33_makefiles: - extends: .fedora33 +.fedora34_makefiles: + extends: .fedora34 variables: - CMAKE_CONFIGURATION: fedora33_makefiles + CMAKE_CONFIGURATION: fedora34_makefiles CTEST_NO_WARNINGS_ALLOWED: 1 CMAKE_GENERATOR: "Unix Makefiles" +### Clang Compiler + +.debian10_makefiles_clang: + extends: .debian10 + + variables: + CMAKE_CONFIGURATION: debian10_makefiles_clang + CMAKE_GENERATOR: "Unix Makefiles" + +.debian10_ninja_clang: + extends: .debian10 + + variables: + CMAKE_CONFIGURATION: debian10_ninja_clang + +### Sanitizers + +.fedora_memcheck: + variables: + CMAKE_CI_BUILD_TYPE: RelWithDebInfo + +.fedora_asan_addon: + extends: .fedora_memcheck + + variables: + CTEST_MEMORYCHECK_TYPE: AddressSanitizer + CTEST_MEMORYCHECK_SANITIZER_OPTIONS: "" + +.fedora34_asan: + extends: + - .fedora34 + - .fedora_asan_addon + + variables: + CMAKE_CONFIGURATION: fedora34_asan + +### Intel Compiler + +.intelcompiler: + image: "kitware/intelcompiler:$CMAKE_CI_INTELCOMPILER_IMAGE_TAG" + environment: + name: intel-compiler + variables: + CMAKE_ARCH: x86_64 + +.intelclassic_makefiles: + extends: .intelcompiler + variables: + CMAKE_CONFIGURATION: intelclassic_makefiles + CMAKE_GENERATOR: "Unix Makefiles" + +.inteloneapi_makefiles: + extends: .intelcompiler + variables: + CMAKE_CONFIGURATION: inteloneapi_makefiles + CMAKE_GENERATOR: "Unix Makefiles" + ### CUDA builds +.cuda9.2: + image: "kitware/cmake:ci-cuda9.2-x86_64-2021-10-01" + + variables: + GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake ci" + CMAKE_ARCH: x86_64 + CTEST_LABELS: "CUDA" + +.cuda9.2_nvidia: + extends: .cuda9.2 + + variables: + CMAKE_CONFIGURATION: cuda9.2_nvidia + CMAKE_GENERATOR: "Ninja Multi-Config" + .cuda10.2: - image: "kitware/cmake:ci-cuda10.2-x86_64-2020-06-11" + image: "kitware/cmake:ci-cuda10.2-x86_64-2021-06-16" variables: GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake ci" @@ -145,6 +238,30 @@ CMAKE_CONFIGURATION: cuda10.2_nvidia CTEST_NO_WARNINGS_ALLOWED: 1 +.cuda10.2_clang: + extends: .cuda10.2 + + variables: + CMAKE_CONFIGURATION: cuda10.2_clang + CTEST_NO_WARNINGS_ALLOWED: 1 + +### HIP builds + +.hip4.2: + image: "kitware/cmake:ci-hip4.2-x86_64-2021-07-09" + + variables: + GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake ci" + CMAKE_ARCH: x86_64 + CTEST_LABELS: "HIP" + +.hip4.2_radeon: + extends: .hip4.2 + + variables: + CMAKE_CONFIGURATION: hip4.2_radeon + CMAKE_GENERATOR: "Ninja Multi-Config" + ## Tags .linux_builder_tags: @@ -177,6 +294,13 @@ - docker - linux +.linux_builder_tags_radeon: + tags: + - cmake + - radeon + - docker + - linux + .linux_builder_tags_aarch64: tags: - cmake @@ -195,9 +319,11 @@ ## Linux-specific scripts .before_script_linux: &before_script_linux + - source .gitlab/ci/env.sh - .gitlab/ci/cmake.sh + - export PATH=$PWD/.gitlab/cmake/bin:$PATH - .gitlab/ci/ninja.sh - - export PATH=$PWD/.gitlab:$PWD/.gitlab/cmake/bin:$PATH + - export PATH=$PWD/.gitlab:$PATH - cmake --version - ninja --version @@ -224,6 +350,13 @@ interruptible: true +.cmake_codespell_linux: + stage: build + extends: .fedora34 + script: + - codespell + interruptible: true + .cmake_build_linux: stage: build @@ -247,10 +380,20 @@ interruptible: true +.cmake_memcheck_linux: + stage: test + + script: + - *before_script_linux + - "$LAUNCHER ctest --output-on-failure -V -S .gitlab/ci/ctest_memcheck.cmake" + + interruptible: true + .cmake_build_linux_release: stage: build script: + - source .gitlab/ci/env.sh # Bootstrap. - mkdir -p build/ # Exclude documentation. A job dependency provides it for packaging. @@ -313,3 +456,38 @@ - sccache --show-stats interruptible: true + +.cmake_test_linux_intelclassic_makefiles: + extends: + - .intelclassic_makefiles + - .cmake_test_linux_release + - .linux_builder_tags_qt + - .run_manually + - .needs_centos6_x86_64 + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + +.cmake_test_linux_inteloneapi_makefiles: + extends: + - .inteloneapi_makefiles + - .cmake_test_linux_release + - .linux_builder_tags_qt + - .run_manually + - .needs_centos6_x86_64 + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + +### Documentation + +.cmake_org_help: + stage: build + extends: + - .fedora34 + - .linux_builder_tags + - .cmake_org_help_artifacts + script: + - *before_script_linux + - mkdir -p build/ + - cd build/ + - cmake ../Utilities/Sphinx -GNinja -DSPHINX_HTML=ON -DSPHINX_FLAGS="-A versionswitch=1" + - ninja diff --git a/.gitlab/os-macos.yml b/.gitlab/os-macos.yml index 1ce96b30cf7..66bbbf386eb 100644 --- a/.gitlab/os-macos.yml +++ b/.gitlab/os-macos.yml @@ -7,7 +7,7 @@ GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake ci ext/$CI_CONCURRENT_ID" # TODO: Factor this out so that each job selects the Xcode version to # use so that different versions can be tested in a single pipeline. - DEVELOPER_DIR: "/Applications/Xcode-12.4.app/Contents/Developer" + DEVELOPER_DIR: "/Applications/Xcode-13.1.app/Contents/Developer" # Avoid conflicting with other projects running on the same machine. SCCACHE_SERVER_PORT: 4227 @@ -87,7 +87,7 @@ - cmake # Since this is a bare runner, pin to a project. - macos - shell - - xcode-12.4 + - xcode-13.1 - nonconcurrent .macos_x86_64_builder_tags_package: @@ -95,7 +95,7 @@ - cmake # Since this is a bare runner, pin to a project. - macos - shell - - xcode-12.4 + - xcode-13.1 - nonconcurrent - finder @@ -104,7 +104,7 @@ - cmake # Since this is a bare runner, pin to a project. - macos - shell - - xcode-12.4 + - xcode-13.1 - concurrent .macos_arm64_builder_tags: @@ -112,7 +112,7 @@ - cmake # Since this is a bare runner, pin to a project. - macos-arm64 - shell - - xcode-12.4 + - xcode-13.1 - nonconcurrent .macos_arm64_builder_ext_tags: @@ -120,15 +120,16 @@ - cmake # Since this is a bare runner, pin to a project. - macos-arm64 - shell - - xcode-12.4 + - xcode-13.1 - concurrent ## macOS-specific scripts .before_script_macos: &before_script_macos - .gitlab/ci/cmake.sh + - export PATH=$PWD/.gitlab/cmake/bin:$PATH - .gitlab/ci/ninja.sh - - export PATH=$PWD/.gitlab:$PWD/.gitlab/cmake/bin:$PATH + - export PATH=$PWD/.gitlab:$PATH - cmake --version - ninja --version # Download Qt diff --git a/.gitlab/os-windows.yml b/.gitlab/os-windows.yml index cd2f1682c6d..a1194331bf3 100644 --- a/.gitlab/os-windows.yml +++ b/.gitlab/os-windows.yml @@ -28,48 +28,48 @@ # Debug and RelWithDebinfo build types use the `/Zi` which results in # uncacheable compiations. # https://github.com/mozilla/sccache/issues/242 - CMAKE_BUILD_TYPE: Release + CMAKE_CI_BUILD_TYPE: Release CTEST_NO_WARNINGS_ALLOWED: 1 -.windows_vs2019_x64_ninja: +.windows_vs2022_x64_ninja: extends: .windows_ninja variables: - CMAKE_CONFIGURATION: windows_vs2019_x64_ninja - VCVARSALL: "${VS160COMNTOOLS}\\..\\..\\VC\\Auxiliary\\Build\\vcvarsall.bat" + CMAKE_CONFIGURATION: windows_vs2022_x64_ninja + VCVARSALL: "${VS170COMNTOOLS}\\..\\..\\VC\\Auxiliary\\Build\\vcvarsall.bat" VCVARSPLATFORM: "x64" - VCVARSVERSION: "14.28.29910" + VCVARSVERSION: "14.30.30705" ### External testing -.windows_vs2019_x64: +.windows_vs2022_x64: extends: .windows variables: - CMAKE_CONFIGURATION: windows_vs2019_x64 - CMAKE_GENERATOR: "Visual Studio 16 2019" + CMAKE_CONFIGURATION: windows_vs2022_x64 + CMAKE_GENERATOR: "Visual Studio 17 2022" CMAKE_GENERATOR_PLATFORM: "x64" - CMAKE_GENERATOR_TOOLSET: "v142,version=14.28.29910" + CMAKE_GENERATOR_TOOLSET: "v143,version=14.30.30705" CMAKE_CI_NIGHTLY_IGNORE_DEPS: "true" ## Tags -.windows_builder_tags: +.windows_tags_nonconcurrent_vs2022: tags: - cmake # Since this is a bare runner, pin to a project. - windows - shell - - vs2019 - - msvc-19.28-16.9 + - vs2022 + - msvc-19.30 - nonconcurrent -.windows_builder_ext_tags: +.windows_tags_concurrent_vs2022: tags: - cmake # Since this is a bare runner, pin to a project. - windows - shell - - vs2019 - - msvc-19.28-16.9 + - vs2022 + - msvc-19.30 - concurrent ## Windows-specific scripts diff --git a/.gitlab/rules.yml b/.gitlab/rules.yml index 256f5677bf0..a871b8f6f28 100644 --- a/.gitlab/rules.yml +++ b/.gitlab/rules.yml @@ -6,16 +6,19 @@ when: never - if: '$CMAKE_CI_NIGHTLY == "true"' when: on_success - - if: '($CMAKE_CI_PROJECT_CONTINUOUS_BRANCH != "" && $CI_COMMIT_BRANCH == $CMAKE_CI_PROJECT_CONTINUOUS_BRANCH && $CMAKE_CI_JOB_CONTINUOUS == "true")' + - if: '$CMAKE_CI_JOB_NIGHTLY == "true"' + when: never + - if: '$CMAKE_CI_PROJECT_CONTINUOUS_BRANCH != null && $CI_COMMIT_BRANCH != null && $CMAKE_CI_PROJECT_CONTINUOUS_BRANCH == $CI_COMMIT_BRANCH && $CMAKE_CI_JOB_CONTINUOUS == "true"' when: delayed start_in: 5 minutes - if: '($CMAKE_CI_NO_MR == "true" && $CI_MERGE_REQUEST_ID)' when: never - if: '$CI_MERGE_REQUEST_ID' when: manual + - if: '$CI_PROJECT_PATH == "cmake/cmake" && $CI_PIPELINE_SOURCE == "schedule"' + when: on_success - if: '$CI_PROJECT_PATH == "cmake/cmake"' - when: delayed - start_in: 5 minutes + when: manual - when: never .run_automatically: @@ -24,12 +27,16 @@ when: never - if: '$CMAKE_CI_NIGHTLY == "true"' when: on_success - - if: '($CMAKE_CI_PROJECT_CONTINUOUS_BRANCH != "" && $CI_COMMIT_BRANCH == $CMAKE_CI_PROJECT_CONTINUOUS_BRANCH && $CMAKE_CI_JOB_CONTINUOUS == "true")' + - if: '$CMAKE_CI_JOB_NIGHTLY == "true"' + when: never + - if: '$CMAKE_CI_PROJECT_CONTINUOUS_BRANCH != null && $CI_COMMIT_BRANCH != null && $CMAKE_CI_PROJECT_CONTINUOUS_BRANCH == $CI_COMMIT_BRANCH && $CMAKE_CI_JOB_CONTINUOUS == "true"' when: on_success - if: '($CMAKE_CI_NO_MR == "true" && $CI_MERGE_REQUEST_ID)' when: never - if: '$CI_MERGE_REQUEST_ID' when: on_success + - if: '$CI_PROJECT_PATH == "cmake/cmake" && $CI_PIPELINE_SOURCE == "schedule"' + when: on_success - if: '$CI_PROJECT_PATH == "cmake/cmake"' when: delayed start_in: 5 minutes @@ -43,6 +50,8 @@ when: always - if: '$CMAKE_CI_NIGHTLY == "true"' when: on_success + - if: '$CMAKE_CI_JOB_NIGHTLY == "true"' + when: never - if: '($CMAKE_CI_NO_MR == "true" && $CI_MERGE_REQUEST_ID)' when: never - if: '$CI_MERGE_REQUEST_ID' @@ -56,3 +65,15 @@ - if: '$CMAKE_CI_PACKAGE == "true"' when: on_success - when: never + +.run_only_for_continuous_master: + rules: + - if: '$CMAKE_CI_PROJECT_MAIN_BRANCH != null && $CI_COMMIT_BRANCH != null && $CMAKE_CI_PROJECT_MAIN_BRANCH == $CI_COMMIT_BRANCH' + when: on_success + - when: never + +.run_only_for_continuous_stage: + rules: + - if: '$CMAKE_CI_PROJECT_CONTINUOUS_BRANCH != null && $CI_COMMIT_BRANCH != null && $CMAKE_CI_PROJECT_CONTINUOUS_BRANCH == $CI_COMMIT_BRANCH' + when: on_success + - when: never diff --git a/.gitlab/upload.yml b/.gitlab/upload.yml index 8b8daa106ff..693388d9bf9 100644 --- a/.gitlab/upload.yml +++ b/.gitlab/upload.yml @@ -1,9 +1,10 @@ # Steps for uploading artifacts -.rsync_upload: - image: "fedora:32" +.rsync_upload_binary: + image: "fedora:34" stage: upload tags: + - cmake - docker - linux - build @@ -16,3 +17,21 @@ - chmod 400 $RSYNC_BINARY_KEY - ssh-keygen -y -f $RSYNC_BINARY_KEY > $RSYNC_BINARY_KEY.pub - rsync -tv --recursive -e "ssh -i $RSYNC_BINARY_KEY -o StrictHostKeyChecking=no -o LogLevel=ERROR" build/ kitware@cmake.org:$RSYNC_DESTINATION/ + +.rsync_upload_help: + stage: upload + image: "fedora:34" + tags: + - cmake + - docker + - linux + - build + environment: + name: rsync-upload + + script: + - ls build/html/index.html + - dnf install -y --setopt=install_weak_deps=False rsync openssh-clients + - chmod 400 $RSYNC_HELP_KEY + - ssh-keygen -y -f $RSYNC_HELP_KEY > $RSYNC_HELP_KEY.pub + - rsync -tv --recursive --delete -e "ssh -i $RSYNC_HELP_KEY -o StrictHostKeyChecking=no -o LogLevel=ERROR" build/html/ kitware@cmake.org:$RSYNC_DESTINATION/ diff --git a/Auxiliary/vim/cmake.vim.in b/Auxiliary/vim/cmake.vim.in index 3471b5455bd..6edc0407354 100644 --- a/Auxiliary/vim/cmake.vim.in +++ b/Auxiliary/vim/cmake.vim.in @@ -9,7 +9,7 @@ " Former Maintainer: Karthik Krishnan " Last Change: @DATE@ " -" Licence: The CMake license applies to this file. See +" License: The CMake license applies to this file. See " https://cmake.org/licensing " This implies that distribution with Vim is allowed diff --git a/Auxiliary/vim/indent/cmake.vim b/Auxiliary/vim/indent/cmake.vim index 33e583d6247..f7ab24a5d02 100644 --- a/Auxiliary/vim/indent/cmake.vim +++ b/Auxiliary/vim/indent/cmake.vim @@ -5,7 +5,7 @@ " Former Maintainer: Karthik Krishnan " Last Change: 2017 Aug 30 " -" Licence: The CMake license applies to this file. See +" License: The CMake license applies to this file. See " https://cmake.org/licensing " This implies that distribution with Vim is allowed diff --git a/Auxiliary/vim/syntax/cmake.vim b/Auxiliary/vim/syntax/cmake.vim index 955beaea177..7a3e4ed6248 100644 --- a/Auxiliary/vim/syntax/cmake.vim +++ b/Auxiliary/vim/syntax/cmake.vim @@ -9,7 +9,7 @@ " Former Maintainer: Karthik Krishnan " Last Change: 2020 oct. 28 " -" Licence: The CMake license applies to this file. See +" License: The CMake license applies to this file. See " https://cmake.org/licensing " This implies that distribution with Vim is allowed @@ -92,6 +92,7 @@ syn keyword cmakeProperty contained \ AUTOUIC_EXECUTABLE \ AUTOUIC_OPTIONS \ AUTOUIC_SEARCH_PATHS + \ AUTOUIC_SOURCE_GROUP \ BINARY_DIR \ BUILDSYSTEM_TARGETS \ BUILD_RPATH @@ -159,6 +160,7 @@ syn keyword cmakeProperty contained \ ENABLED_LANGUAGES \ ENABLE_EXPORTS \ ENVIRONMENT + \ ENVIRONMENT_MODIFICATION \ EXCLUDE_FROM_ALL \ EXCLUDE_FROM_DEFAULT_BUILD \ EXPORT_NAME @@ -904,6 +906,7 @@ syn keyword cmakeVariable contained \ CMAKE_CXX_INCLUDE_WHAT_YOU_USE \ CMAKE_CXX_INIT \ CMAKE_CXX_LIBRARY_ARCHITECTURE + \ CMAKE_CXX_LINKER_LAUNCHER \ CMAKE_CXX_LINKER_PREFERENCE \ CMAKE_CXX_LINKER_PREFERENCE_PROPAGATES \ CMAKE_CXX_LINKER_WRAPPER_FLAG @@ -969,6 +972,7 @@ syn keyword cmakeVariable contained \ CMAKE_C_INCLUDE_WHAT_YOU_USE \ CMAKE_C_INIT \ CMAKE_C_LIBRARY_ARCHITECTURE + \ CMAKE_C_LINKER_LAUNCHER \ CMAKE_C_LINKER_PREFERENCE \ CMAKE_C_LINKER_PREFERENCE_PROPAGATES \ CMAKE_C_LINKER_WRAPPER_FLAG @@ -1262,10 +1266,12 @@ syn keyword cmakeVariable contained \ CMAKE_NO_SYSTEM_FROM_IMPORTED \ CMAKE_OBJCXX_CLANG_TIDY \ CMAKE_OBJCXX_EXTENSIONS + \ CMAKE_OBJCXX_LINKER_LAUNCHER \ CMAKE_OBJCXX_STANDARD \ CMAKE_OBJCXX_STANDARD_REQUIRED \ CMAKE_OBJC_CLANG_TIDY \ CMAKE_OBJC_EXTENSIONS + \ CMAKE_OBJC_LINKER_LAUNCHER \ CMAKE_OBJC_STANDARD \ CMAKE_OBJC_STANDARD_REQUIRED \ CMAKE_OBJECT_PATH_MAX @@ -2802,6 +2808,7 @@ syn keyword cmakeKWfind_package contained \ ABI \ BUNDLE \ CMAKE_DISABLE_FIND_PACKAGE_ + \ CMAKE_REQUIRE_FIND_PACKAGE_ \ CMAKE_FIND_ROOT_PATH_BOTH \ COMPONENTS \ CONFIG diff --git a/CMakeCPack.cmake b/CMakeCPack.cmake index 31c2fe45611..9357804634a 100644 --- a/CMakeCPack.cmake +++ b/CMakeCPack.cmake @@ -133,6 +133,9 @@ if(CMake_INSTALL_COMPONENTS) if(SPHINX_QTHELP) list(APPEND _CPACK_IFW_COMPONENTS_ALL sphinx-qthelp) endif() + if(SPHINX_LATEXPDF) + list(APPEND _CPACK_IFW_COMPONENTS_ALL sphinx-latexpdf) + endif() if(CMake_BUILD_DEVELOPER_REFERENCE) if(CMake_BUILD_DEVELOPER_REFERENCE_HTML) list(APPEND _CPACK_IFW_COMPONENTS_ALL cmake-developer-reference-html) diff --git a/CMakeLists.txt b/CMakeLists.txt index a2fcf2e3727..fdfe456aa92 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,7 +1,7 @@ # Distributed under the OSI-approved BSD 3-Clause License. See accompanying # file Copyright.txt or https://cmake.org/licensing for details. -cmake_minimum_required(VERSION 3.1...3.18 FATAL_ERROR) +cmake_minimum_required(VERSION 3.1...3.20 FATAL_ERROR) set(CMAKE_USER_MAKE_RULES_OVERRIDE_C ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideC.cmake) set(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideCXX.cmake) project(CMake) @@ -361,6 +361,9 @@ macro (CMAKE_BUILD_UTILITIES) if(CMake_NO_CXX_STANDARD) set(KWSYS_CXX_STANDARD "") endif() + if(CMake_NO_SELF_BACKTRACE) + set(KWSYS_NO_EXECINFO 1) + endif() if(WIN32) # FIXME: Teach KWSys to hard-code these checks on Windows. set(KWSYS_C_HAS_CLOCK_GETTIME_MONOTONIC_COMPILED 0) @@ -579,6 +582,7 @@ macro (CMAKE_BUILD_UTILITIES) set(LIBLZMA_INCLUDE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/Utilities/cmliblzma/liblzma/api") set(LIBLZMA_LIBRARY cmliblzma) + set(HAVE_LZMA_STREAM_ENCODER_MT 1) endif() endif() @@ -643,7 +647,11 @@ macro (CMAKE_BUILD_UTILITIES) #--------------------------------------------------------------------- # Build libuv library. if(CMAKE_USE_SYSTEM_LIBUV) - find_package(LibUV 1.10.0) + if(WIN32) + find_package(LibUV 1.38.0) + else() + find_package(LibUV 1.10.0) + endif() if(NOT LIBUV_FOUND) message(FATAL_ERROR "CMAKE_USE_SYSTEM_LIBUV is ON but a libuv is not found!") @@ -807,8 +815,12 @@ CMAKE_SETUP_TESTING() if(NOT CMake_TEST_EXTERNAL_CMAKE) if(NOT CMake_VERSION_IS_RELEASE) - if(CMAKE_C_COMPILER_ID STREQUAL "GNU" AND - NOT "${CMAKE_C_COMPILER_VERSION}" VERSION_LESS 4.2) + if((CMAKE_C_COMPILER_ID STREQUAL "GNU" AND + NOT "${CMAKE_C_COMPILER_VERSION}" VERSION_LESS 4.2) OR + (CMAKE_C_COMPILER_ID STREQUAL "Clang" AND + NOT "${CMAKE_C_COMPILER_VERSION}" VERSION_LESS 3.0 AND + NOT "x${CMAKE_C_SIMULATE_ID}" STREQUAL "xMSVC") OR + CMAKE_C_COMPILER_ID STREQUAL "AppleClang") set(C_FLAGS_LIST -Wcast-align -Werror-implicit-function-declaration -Wchar-subscripts -Wall -W -Wpointer-arith -Wwrite-strings -Wformat-security -Wmissing-format-attribute -fno-common -Wundef diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 300621405cb..a6a20827dcf 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -38,7 +38,7 @@ To contribute patches: #. Push the topic branch to a personal repository fork on GitLab. #. Create a GitLab Merge Request targeting the upstream ``master`` branch (even if the change is intended for merge to the ``release`` branch). - Check the box labelled "Allow commits from members who can merge to the + Check the box labeled "Allow commits from members who can merge to the target branch". This will allow maintainers to make minor edits on your behalf. diff --git a/CTestCustom.cmake.in b/CTestCustom.cmake.in index 4c8267de8c2..093c1d889e3 100644 --- a/CTestCustom.cmake.in +++ b/CTestCustom.cmake.in @@ -7,6 +7,7 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION "warning LNK4221" "warning LNK4204" # Occurs by race condition with objects in small libs "variable .var_args[2]*. is used before its value is set" + "warning: variable .__d[01]. was set but never used" # FD_ZERO on NVHPC "jobserver unavailable" "warning: \\(Long double usage is reported only once for each file" "warning: To disable this warning use" @@ -82,28 +83,21 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION "compilation completed with warnings" # PGI "[0-9]+ Warning\\(s\\) detected" # SunPro - # 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.*" - ".*stl_vector.h:.*: warning: Returning null reference.*" - "warning: Value stored to 'yymsg' is never read" - "warning: Value stored to 'yytoken' is never read" - "index_encoder.c.241.2. warning: Value stored to .out_start. is never read" - "index.c.*warning: Access to field.*results in a dereference of a null pointer.*loaded from variable.*" - "cmCommandArgumentLexer.cxx:[0-9]+:[0-9]+: warning: Call to 'realloc' has an allocation size of 0 bytes" - "cmDependsJavaLexer.cxx:[0-9]+:[0-9]+: warning: Call to 'realloc' has an allocation size of 0 bytes" - "cmExprLexer.cxx:[0-9]+:[0-9]+: warning: Call to 'realloc' has an allocation size of 0 bytes" - "cmListFileLexer.c:[0-9]+:[0-9]+: warning: Call to 'realloc' has an allocation size of 0 bytes" - "cmFortranLexer.cxx:[0-9]+:[0-9]+: warning: Call to 'realloc' has an allocation size of 0 bytes" - "testProcess.*warning: Dereference of null pointer .loaded from variable .invalidAddress.." + # clang-analyzer exceptions + "cmListFileLexer.c:[0-9]+:[0-9]+: warning: Array subscript is undefined" + "jsoncpp/src/.*:[0-9]+:[0-9]+: warning: Value stored to .* is never read" + "liblzma/common/index_encoder.c:[0-9]+:[0-9]+: warning: Value stored to '[^']+' during its initialization is never read" + "liblzma/liblzma/common/index.c:[0-9]+:[0-9]+: warning: Access to field '[^']+' results in a dereference of a null pointer" "liblzma/simple/x86.c:[0-9]+:[0-9]+: warning: The result of the '<<' expression is undefined" - "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" + "librhash/librhash/.*:[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" + "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" + "nghttp2/lib/.*:[0-9]+:[0-9]+: warning: Access to field '[^']+' results in a dereference of a null pointer" "nghttp2/lib/.*:[0-9]+:[0-9]+: warning: Dereference of null pointer" - "nghttp2/lib/.*:[0-9]+:[0-9]+: warning: Value stored to .* is never read" + "nghttp2/lib/.*:[0-9]+:[0-9]+: warning: Value stored to '[^']+' is never read" + "zstd/lib/.*:[0-9]+:[0-9]+: warning: Assigned value is garbage or undefined" + "zstd/lib/.*:[0-9]+:[0-9]+: warning: Dereference of null pointer" ) if(NOT "@CMAKE_GENERATOR@" MATCHES "Xcode") diff --git a/Help/command/DEVICE_LINK_OPTIONS.txt b/Help/command/DEVICE_LINK_OPTIONS.txt index 1297cd0547a..3d50208163e 100644 --- a/Help/command/DEVICE_LINK_OPTIONS.txt +++ b/Help/command/DEVICE_LINK_OPTIONS.txt @@ -1,3 +1,5 @@ +Host And Device Specific Link Options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. versionadded:: 3.18 When a device link step is involved, which is controlled by diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index 97eecfca36e..5b63e1cba90 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -11,10 +11,11 @@ The general signature is: |FIND_XXX| ( name | |NAMES| - [HINTS path1 [path2 ... ENV var]] - [PATHS path1 [path2 ... ENV var]] + [HINTS [path | ENV var]... ] + [PATHS [path | ENV var]... ] [PATH_SUFFIXES suffix1 [suffix2 ...]] [DOC "cache documentation string"] + [NO_CACHE] [REQUIRED] [NO_DEFAULT_PATH] [NO_PACKAGE_ROOT_PATH] @@ -28,8 +29,8 @@ The general signature is: ) This command is used to find a |SEARCH_XXX_DESC|. -A cache entry named by ```` is created to store the result -of this command. +A cache entry, or a normal variable if ``NO_CACHE`` is specified, +named by ```` 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 ``-NOTFOUND``. @@ -56,6 +57,22 @@ Options include: ``DOC`` Specify the documentation string for the ```` cache entry. +``NO_CACHE`` + .. versionadded:: 3.21 + + The result of the search will be stored in a normal variable rather than + a cache entry. + + .. note:: + + If the variable is already set before the call (as a normal or cache + variable) then the search will not occur. + + .. warning:: + + This option should be used with caution because it can greatly increase + the cost of repeated configure steps. + ``REQUIRED`` .. versionadded:: 3.18 diff --git a/Help/command/LINK_OPTIONS_LINKER.txt b/Help/command/LINK_OPTIONS_LINKER.txt index 3f66181befa..e71e5ea25dc 100644 --- a/Help/command/LINK_OPTIONS_LINKER.txt +++ b/Help/command/LINK_OPTIONS_LINKER.txt @@ -1,3 +1,6 @@ +Handling Compiler Driver Differences +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + To pass options to the linker tool, each compiler driver has its own syntax. The ``LINKER:`` prefix and ``,`` separator can be used to specify, in a portable way, options to pass to the linker tool. ``LINKER:`` is replaced by the diff --git a/Help/command/OPTIONS_SHELL.txt b/Help/command/OPTIONS_SHELL.txt index 4051ffe16ee..4171f016272 100644 --- a/Help/command/OPTIONS_SHELL.txt +++ b/Help/command/OPTIONS_SHELL.txt @@ -1,11 +1,15 @@ -The final set of compile or link options used for a target is constructed by +Option De-duplication +^^^^^^^^^^^^^^^^^^^^^ + +The final set of options used for a target is constructed by accumulating options from the current target and the usage requirements of its dependencies. The set of options is de-duplicated to avoid repetition. .. versionadded:: 3.12 While beneficial for individual options, the de-duplication step can break - up option groups. For example, ``-D A -D B`` becomes ``-D A B``. One may - specify a group of options using shell-like quoting along with a ``SHELL:`` - prefix. The ``SHELL:`` prefix is dropped, and the rest of the option string - is parsed using the :command:`separate_arguments` ``UNIX_COMMAND`` mode. - For example, ``"SHELL:-D A" "SHELL:-D B"`` becomes ``-D A -D B``. + up option groups. For example, ``-option A -option B`` becomes + ``-option A B``. One may specify a group of options using shell-like + quoting along with a ``SHELL:`` prefix. The ``SHELL:`` prefix is dropped, + and the rest of the option string is parsed using the + :command:`separate_arguments` ``UNIX_COMMAND`` mode. For example, + ``"SHELL:-option A" "SHELL:-option B"`` becomes ``-option A -option B``. diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index c0b95934bed..b45a0794d25 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -271,26 +271,40 @@ The options are: ``DEPFILE`` .. versionadded:: 3.7 - Specify a ``.d`` depfile for the :generator:`Ninja` generator and - :ref:`Makefile Generators`. - A ``.d`` file holds dependencies usually emitted by the custom - command itself. - Using ``DEPFILE`` with other generators than :generator:`Ninja` or - :ref:`Makefile Generators` is an error. + Specify a ``.d`` depfile which holds dependencies for the custom command. + It is usually emitted by the custom command itself. This keyword may only + be used if the generator supports it, as detailed below. + + .. versionadded:: 3.7 + The :generator:`Ninja` generator supports ``DEPFILE`` since the keyword + was first added. + + .. versionadded:: 3.17 + Added the :generator:`Ninja Multi-Config` generator, which included + support for the ``DEPFILE`` keyword. .. versionadded:: 3.20 - Added the support of :ref:`Makefile Generators`. + Added support for :ref:`Makefile Generators`. - If the ``DEPFILE`` argument is relative, it should be relative to - :variable:`CMAKE_CURRENT_BINARY_DIR`, and any relative paths inside the - ``DEPFILE`` should also be relative to :variable:`CMAKE_CURRENT_BINARY_DIR` - (see policy :policy:`CMP0116`. This policy is always ``NEW`` for - :ref:`Makefile Generators`). + .. note:: - .. note:: + ``DEPFILE`` cannot be specified at the same time as the + ``IMPLICIT_DEPENDS`` option for :ref:`Makefile Generators`. - For :ref:`Makefile Generators`, this option cannot be specified at the - same time as ``IMPLICIT_DEPENDS`` option. + .. versionadded:: 3.21 + Added support for :ref:`Visual Studio Generators` with VS 2012 and above, + and for the :generator:`Xcode` generator. Support for + :manual:`generator expressions ` was also + added. + + Using ``DEPFILE`` with generators other than those listed above is an error. + + If the ``DEPFILE`` argument is relative, it should be relative to + :variable:`CMAKE_CURRENT_BINARY_DIR`, and any relative paths inside the + ``DEPFILE`` should also be relative to :variable:`CMAKE_CURRENT_BINARY_DIR`. + See policy :policy:`CMP0116`, which is always ``NEW`` for + :ref:`Makefile Generators`, :ref:`Visual Studio Generators`, + and the :generator:`Xcode` generator. Examples: Generating Files ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -331,6 +345,8 @@ will re-run whenever ``in.txt`` changes. where ```` is the build configuration, and then compile the generated source as part of a library. +.. _`add_custom_command(TARGET)`: + Build Events ^^^^^^^^^^^^ @@ -381,6 +397,9 @@ of the following is specified: This allows to add individual build events for every configuration. +.. versionadded:: 3.21 + Support for target-dependent generator expressions. + Examples: Build Events ^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index dfc650091a7..1235155deba 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -166,6 +166,8 @@ itself and is not included as a target in the generated buildsystem. call are ``PRIVATE`` to the interface library and do not appear in its :prop_tgt:`INTERFACE_SOURCES` target property. +.. _`add_library imported libraries`: + Imported Libraries ^^^^^^^^^^^^^^^^^^ @@ -205,7 +207,8 @@ The ```` must be one of: :prop_tgt:`IMPORTED_IMPLIB_`) specifies the location of the DLL import library file (``.lib`` or ``.dll.a``) on disk, and the ``IMPORTED_LOCATION`` is the location of the ``.dll`` runtime - library (and is optional). + library (and is optional, but needed by the :genex:`TARGET_RUNTIME_DLLS` + generator expression). Additional usage requirements may be specified in ``INTERFACE_*`` properties. diff --git a/Help/command/build_command.rst b/Help/command/build_command.rst index 6659005bee2..a03979d10a4 100644 --- a/Help/command/build_command.rst +++ b/Help/command/build_command.rst @@ -8,23 +8,29 @@ This is mainly intended for internal use by the :module:`CTest` module. build_command( [CONFIGURATION ] + [PARALLEL_LEVEL ] [TARGET ] [PROJECT_NAME ] # legacy, causes warning ) Sets the given ```` to a command-line string of the form:: - --build . [--config ] [--target ...] [-- -i] + --build . [--config ] [--parallel ] [--target ...] [-- -i] where ```` is the location of the :manual:`cmake(1)` command-line -tool, and ```` and ```` are the values provided to the -``CONFIGURATION`` and ``TARGET`` options, if any. The trailing ``-- -i`` -option is added for :ref:`Makefile Generators` if policy :policy:`CMP0061` -is not set to ``NEW``. +tool, and ````, ```` and ```` are the values +provided to the ``CONFIGURATION``, ``PARALLEL_LEVEL`` and ``TARGET`` +options, if any. The trailing ``-- -i`` option is added for +:ref:`Makefile Generators` if policy :policy:`CMP0061` is not set to +``NEW``. When invoked, this ``cmake --build`` command line will launch the underlying build system tool. +.. versionadded:: 3.21 + The ``PARALLEL_LEVEL`` argument can be used to set the ``--parallel`` + flag. + .. code-block:: cmake build_command( ) diff --git a/Help/command/cmake_host_system_information.rst b/Help/command/cmake_host_system_information.rst index 2b902a9159f..998e1467429 100644 --- a/Help/command/cmake_host_system_information.rst +++ b/Help/command/cmake_host_system_information.rst @@ -13,46 +13,236 @@ queried. The list of queried values is stored in ````. ```` can be one of the following values: -============================= ================================================ -Key Description -============================= ================================================ -``NUMBER_OF_LOGICAL_CORES`` Number of logical cores -``NUMBER_OF_PHYSICAL_CORES`` Number of physical cores -``HOSTNAME`` Hostname -``FQDN`` Fully qualified domain name -``TOTAL_VIRTUAL_MEMORY`` Total virtual memory in MiB [#mebibytes]_ -``AVAILABLE_VIRTUAL_MEMORY`` Available virtual memory in MiB [#mebibytes]_ -``TOTAL_PHYSICAL_MEMORY`` Total physical memory in MiB [#mebibytes]_ -``AVAILABLE_PHYSICAL_MEMORY`` Available physical memory in MiB [#mebibytes]_ -============================= ================================================ - -.. versionadded:: 3.10 - Additional ```` values are available: - -============================= ================================================ -Key Description -============================= ================================================ -``IS_64BIT`` One if processor is 64Bit -``HAS_FPU`` One if processor has floating point unit -``HAS_MMX`` One if processor supports MMX instructions -``HAS_MMX_PLUS`` One if processor supports Ext. MMX instructions -``HAS_SSE`` One if processor supports SSE instructions -``HAS_SSE2`` One if processor supports SSE2 instructions -``HAS_SSE_FP`` One if processor supports SSE FP instructions -``HAS_SSE_MMX`` One if processor supports SSE MMX instructions -``HAS_AMD_3DNOW`` One if processor supports 3DNow instructions -``HAS_AMD_3DNOW_PLUS`` One if processor supports 3DNow+ instructions -``HAS_IA64`` One if IA64 processor emulating x86 -``HAS_SERIAL_NUMBER`` One if processor has serial number -``PROCESSOR_SERIAL_NUMBER`` Processor serial number -``PROCESSOR_NAME`` Human readable processor name -``PROCESSOR_DESCRIPTION`` Human readable full processor description -``OS_NAME`` See :variable:`CMAKE_HOST_SYSTEM_NAME` -``OS_RELEASE`` The OS sub-type e.g. on Windows ``Professional`` -``OS_VERSION`` The OS build ID -``OS_PLATFORM`` See :variable:`CMAKE_HOST_SYSTEM_PROCESSOR` -============================= ================================================ +``NUMBER_OF_LOGICAL_CORES`` + Number of logical cores + +``NUMBER_OF_PHYSICAL_CORES`` + Number of physical cores + +``HOSTNAME`` + Hostname + +``FQDN`` + Fully qualified domain name + +``TOTAL_VIRTUAL_MEMORY`` + Total virtual memory in MiB [#mebibytes]_ + +``AVAILABLE_VIRTUAL_MEMORY`` + Available virtual memory in MiB [#mebibytes]_ + +``TOTAL_PHYSICAL_MEMORY`` + Total physical memory in MiB [#mebibytes]_ + +``AVAILABLE_PHYSICAL_MEMORY`` + Available physical memory in MiB [#mebibytes]_ + +``IS_64BIT`` + .. versionadded:: 3.10 + + One if processor is 64Bit + +``HAS_FPU`` + .. versionadded:: 3.10 + + One if processor has floating point unit + +``HAS_MMX`` + .. versionadded:: 3.10 + + One if processor supports MMX instructions + +``HAS_MMX_PLUS`` + .. versionadded:: 3.10 + + One if processor supports Ext. MMX instructions + +``HAS_SSE`` + .. versionadded:: 3.10 + + One if processor supports SSE instructions + +``HAS_SSE2`` + .. versionadded:: 3.10 + + One if processor supports SSE2 instructions + +``HAS_SSE_FP`` + .. versionadded:: 3.10 + + One if processor supports SSE FP instructions + +``HAS_SSE_MMX`` + .. versionadded:: 3.10 + + One if processor supports SSE MMX instructions + +``HAS_AMD_3DNOW`` + .. versionadded:: 3.10 + + One if processor supports 3DNow instructions + +``HAS_AMD_3DNOW_PLUS`` + .. versionadded:: 3.10 + + One if processor supports 3DNow+ instructions + +``HAS_IA64`` + .. versionadded:: 3.10 + + One if IA64 processor emulating x86 + +``HAS_SERIAL_NUMBER`` + .. versionadded:: 3.10 + + One if processor has serial number + +``PROCESSOR_SERIAL_NUMBER`` + .. versionadded:: 3.10 + + Processor serial number + +``PROCESSOR_NAME`` + .. versionadded:: 3.10 + + Human readable processor name + +``PROCESSOR_DESCRIPTION`` + .. versionadded:: 3.10 + + Human readable full processor description + +``OS_NAME`` + .. versionadded:: 3.10 + + See :variable:`CMAKE_HOST_SYSTEM_NAME` + +``OS_RELEASE`` + .. versionadded:: 3.10 + + The OS sub-type e.g. on Windows ``Professional`` + +``OS_VERSION`` + .. versionadded:: 3.10 + + The OS build ID + +``OS_PLATFORM`` + .. versionadded:: 3.10 + + See :variable:`CMAKE_HOST_SYSTEM_PROCESSOR` + +``DISTRIB_INFO`` + .. versionadded:: 3.22 + + Read :file:`/etc/os-release` file and define the given ```` + into a list of read variables + +``DISTRIB_`` + .. versionadded:: 3.22 + + Get the ```` variable (see `man 5 os-release`_) if it exists in the + :file:`/etc/os-release` file + + Example: + + .. code-block:: cmake + + cmake_host_system_information(RESULT PRETTY_NAME QUERY DISTRIB_PRETTY_NAME) + message(STATUS "${PRETTY_NAME}") + + cmake_host_system_information(RESULT DISTRO QUERY DISTRIB_INFO) + + foreach(VAR IN LISTS DISTRO) + message(STATUS "${VAR}=`${${VAR}}`") + endforeach() + + + Output:: + + -- Ubuntu 20.04.2 LTS + -- DISTRO_BUG_REPORT_URL=`https://bugs.launchpad.net/ubuntu/` + -- DISTRO_HOME_URL=`https://www.ubuntu.com/` + -- DISTRO_ID=`ubuntu` + -- DISTRO_ID_LIKE=`debian` + -- DISTRO_NAME=`Ubuntu` + -- DISTRO_PRETTY_NAME=`Ubuntu 20.04.2 LTS` + -- DISTRO_PRIVACY_POLICY_URL=`https://www.ubuntu.com/legal/terms-and-policies/privacy-policy` + -- DISTRO_SUPPORT_URL=`https://help.ubuntu.com/` + -- DISTRO_UBUNTU_CODENAME=`focal` + -- DISTRO_VERSION=`20.04.2 LTS (Focal Fossa)` + -- DISTRO_VERSION_CODENAME=`focal` + -- DISTRO_VERSION_ID=`20.04` + +If :file:`/etc/os-release` file is not found, the command tries to gather OS +identification via fallback scripts. The fallback script can use `various +distribution-specific files`_ to collect OS identification data and map it +into `man 5 os-release`_ variables. + +Fallback Interface Variables +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. variable:: CMAKE_GET_OS_RELEASE_FALLBACK_SCRIPTS + + In addition to the scripts shipped with CMake, a user may append full + paths to his script(s) to the this list. The script filename has the + following format: ``NNN-.cmake``, where ``NNN`` is three digits + used to apply collected scripts in a specific order. + +.. variable:: CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ + + Variables collected by the user provided fallback script + ought to be assigned to CMake variables using this naming + convention. Example, the ``ID`` variable from the manual becomes + ``CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID``. + +.. variable:: CMAKE_GET_OS_RELEASE_FALLBACK_RESULT + + The fallback script ought to store names of all assigned + ``CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_`` variables in this list. + +Example: + +.. code-block:: cmake + + # Try to detect some old distribution + # See also + # - http://linuxmafia.com/faq/Admin/release-files.html + # + if(NOT EXISTS "${CMAKE_SYSROOT}/etc/foobar-release") + return() + endif() + # Get the first string only + file( + STRINGS "${CMAKE_SYSROOT}/etc/foobar-release" CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT + LIMIT_COUNT 1 + ) + # + # Example: + # + # Foobar distribution release 1.2.3 (server) + # + if(CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT MATCHES "Foobar distribution release ([0-9\.]+) .*") + set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_NAME Foobar) + set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_PRETTY_NAME "${CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT}") + set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID foobar) + set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION ${CMAKE_MATCH_1}) + set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION_ID ${CMAKE_MATCH_1}) + list( + APPEND CMAKE_GET_OS_RELEASE_FALLBACK_RESULT + CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_NAME + CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_PRETTY_NAME + CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID + CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION + CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION_ID + ) + endif() + unset(CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT) + .. rubric:: Footnotes .. [#mebibytes] One MiB (mebibyte) is equal to 1024x1024 bytes. + +.. _man 5 os-release: https://www.freedesktop.org/software/systemd/man/os-release.html +.. _various distribution-specific files: http://linuxmafia.com/faq/Admin/release-files.html diff --git a/Help/command/cmake_language.rst b/Help/command/cmake_language.rst index 99f874b197d..2859f6b6d70 100644 --- a/Help/command/cmake_language.rst +++ b/Help/command/cmake_language.rst @@ -190,7 +190,7 @@ For example, the code: .. code-block:: cmake cmake_language(DEFER CALL message "${deferred_message}") - cmake_language(DEFER ID_VAR id CALL message "Cancelled Message") + cmake_language(DEFER ID_VAR id CALL message "Canceled Message") cmake_language(DEFER CANCEL_CALL ${id}) message("Immediate Message") set(deferred_message "Deferred Message") @@ -201,7 +201,7 @@ prints:: Deferred Message The ``Cancelled Message`` is never printed because its command is -cancelled. The ``deferred_message`` variable reference is not evaluated +canceled. The ``deferred_message`` variable reference is not evaluated until the call site, so it can be set after the deferred call is scheduled. In order to evaluate variable references immediately when scheduling a diff --git a/Help/command/cmake_minimum_required.rst b/Help/command/cmake_minimum_required.rst index c3b3e7370c0..d159770492f 100644 --- a/Help/command/cmake_minimum_required.rst +++ b/Help/command/cmake_minimum_required.rst @@ -5,21 +5,21 @@ Require a minimum version of cmake. .. code-block:: cmake - cmake_minimum_required(VERSION [...] [FATAL_ERROR]) + cmake_minimum_required(VERSION [...] [FATAL_ERROR]) .. versionadded:: 3.12 - The optional ```` version. + The optional ```` version. Sets the minimum required version of cmake for a project. Also updates the policy settings as explained below. -```` and the optional ```` are each CMake versions of the form -``major.minor[.patch[.tweak]]``, and the ``...`` is literal. +```` and the optional ```` are each CMake versions of the +form ``major.minor[.patch[.tweak]]``, and the ``...`` is literal. If the running version of CMake is lower than the ```` required version it will stop processing the project and report an error. -The optional ```` version, if specified, must be at least the -```` version and affects policy settings as described below. +The optional ```` version, if specified, must be at least the +```` version and affects policy settings as described in `Policy Settings`_. If the running version of CMake is older than 3.12, the extra ``...`` dots will be seen as version component separators, resulting in the ``...`` part being ignored and preserving the pre-3.12 behavior @@ -40,8 +40,15 @@ with an error instead of just a warning. they may affect. See also policy :policy:`CMP0000`. Calling ``cmake_minimum_required()`` inside a :command:`function` - limits some effects to the function scope when invoked. Such calls - should not be made with the intention of having global effects. + limits some effects to the function scope when invoked. For example, + the :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable won't be set + in the calling scope. Functions do not introduce their own policy + scope though, so policy settings of the caller *will* be affected + (see below). Due to this mix of things that do and do not affect the + calling scope, calling ``cmake_minimum_required()`` inside a function + is generally discouraged. + +.. _`Policy Settings`: Policy Settings ^^^^^^^^^^^^^^^ diff --git a/Help/command/cmake_path.rst b/Help/command/cmake_path.rst index a8999f35b12..454c8605c7c 100644 --- a/Help/command/cmake_path.rst +++ b/Help/command/cmake_path.rst @@ -69,8 +69,8 @@ Synopsis `Native Conversion`_ cmake_path(`NATIVE_PATH`_ [NORMALIZE] ) - cmake_path(`CONVERT`_ `TO_CMAKE_PATH_LIST`_ ) - cmake_path(`CONVERT`_ `TO_NATIVE_PATH_LIST`_ ) + cmake_path(`CONVERT`_ `TO_CMAKE_PATH_LIST`_ [NORMALIZE]) + cmake_path(`CONVERT`_ `TO_NATIVE_PATH_LIST`_ [NORMALIZE]) `Hashing`_ cmake_path(`HASH`_ ) @@ -459,9 +459,10 @@ are :ref:`normalized ` before the check. .. code-block:: cmake - set(path "/a/b/c/d") - cmake_path(IS_PREFIX path "/a/b" result) # result = true - cmake_path(IS_PREFIX path "/x/y/z" result) # result = false + set(path "/a/b/c") + cmake_path(IS_PREFIX path "/a/b/c/d" result) # result = true + cmake_path(IS_PREFIX path "/a/b" result) # result = false + cmake_path(IS_PREFIX path "/x/y/z" result) # result = false set(path "/a/b") cmake_path(IS_PREFIX path "/a/c/../b" NORMALIZE result) # result = true @@ -687,7 +688,8 @@ When the ``NORMALIZE`` option is specified, the path is :ref:`normalized ` after the path computation. Because ``cmake_path()`` does not access the filesystem, symbolic links are -not resolved. To compute a real path with symbolic links resolved, use the +not resolved and any leading tilde is not expanded. To compute a real path +with symbolic links resolved and leading tildes expanded, use the :command:`file(REAL_PATH)` command instead. Native Conversion diff --git a/Help/command/configure_file.rst b/Help/command/configure_file.rst index d00f08b7a25..1d814235156 100644 --- a/Help/command/configure_file.rst +++ b/Help/command/configure_file.rst @@ -36,8 +36,30 @@ or depending on whether ``VAR`` is set in CMake to any value not considered a false constant by the :command:`if` command. The "..." content on the line after the variable name, if any, is processed as above. -Input file lines of the form ``#cmakedefine01 VAR`` will be replaced with -either ``#define VAR 1`` or ``#define VAR 0`` similarly. + +Unlike lines of the form ``#cmakedefine VAR ...``, in lines of the form +``#cmakedefine01 VAR``, ``VAR`` itself will expand to ``VAR 0`` or ``VAR 1`` +rather than being assigned the value ``...``. Therefore, input lines of the form + +.. code-block:: c + + #cmakedefine01 VAR + +will be replaced with either + +.. code-block:: c + + #define VAR 0 + +or + +.. code-block:: c + + #define VAR 1 + +Input lines of the form ``#cmakedefine01 VAR ...`` will expand +as ``#cmakedefine01 VAR ... 0`` or ``#cmakedefine01 VAR ... 0``, +which may lead to undefined behavior. .. versionadded:: 3.10 The result lines (with the exception of the ``#undef`` comments) can be @@ -74,6 +96,7 @@ The arguments are: with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. If the path names an existing directory the output file is placed in that directory with the same file name as the input file. + If the path contains non-existent directories, they are created. ``NO_SOURCE_PERMISSIONS`` .. versionadded:: 3.19 diff --git a/Help/command/ctest_build.rst b/Help/command/ctest_build.rst index 4d6dc5a43a9..e05df1afcd4 100644 --- a/Help/command/ctest_build.rst +++ b/Help/command/ctest_build.rst @@ -7,6 +7,7 @@ Perform the :ref:`CTest Build Step` as a :ref:`Dashboard Client`. ctest_build([BUILD ] [APPEND] [CONFIGURATION ] + [PARALLEL_LEVEL ] [FLAGS ] [PROJECT_NAME ] [TARGET ] @@ -42,6 +43,13 @@ The options are: Otherwise the ``-C `` option given to the :manual:`ctest(1)` command will be used, if any. +``PARALLEL_LEVEL `` + .. versionadded:: 3.21 + + Specify the parallel level of the underlying build system. If not + specified, the :envvar:`CMAKE_BUILD_PARALLEL_LEVEL` environment + variable will be checked. + ``FLAGS `` Pass additional arguments to the underlying build command. If not specified the ``CTEST_BUILD_FLAGS`` variable will be checked. diff --git a/Help/command/ctest_memcheck.rst b/Help/command/ctest_memcheck.rst index f655c2eb2e0..8b79077946f 100644 --- a/Help/command/ctest_memcheck.rst +++ b/Help/command/ctest_memcheck.rst @@ -17,10 +17,15 @@ Perform the :ref:`CTest MemCheck Step` as a :ref:`Dashboard Client`. [EXCLUDE_FIXTURE_SETUP ] [EXCLUDE_FIXTURE_CLEANUP ] [PARALLEL_LEVEL ] + [RESOURCE_SPEC_FILE ] [TEST_LOAD ] [SCHEDULE_RANDOM ] + [STOP_ON_FAILURE] [STOP_TIME ] [RETURN_VALUE ] + [CAPTURE_CMAKE_ERROR ] + [REPEAT :] + [OUTPUT_JUNIT ] [DEFECT_COUNT ] [QUIET] ) diff --git a/Help/command/ctest_submit.rst b/Help/command/ctest_submit.rst index e6d277f59da..d66182540a9 100644 --- a/Help/command/ctest_submit.rst +++ b/Help/command/ctest_submit.rst @@ -30,7 +30,8 @@ The options are: Build = ctest_build results, in Build.xml Test = ctest_test results, in Test.xml Coverage = ctest_coverage results, in Coverage.xml - MemCheck = ctest_memcheck results, in DynamicAnalysis.xml + MemCheck = ctest_memcheck results, in DynamicAnalysis.xml and + DynamicAnalysis-Test.xml Notes = Files listed by CTEST_NOTES_FILES, in Notes.xml ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES Upload = Files prepared for upload by ctest_upload(), in Upload.xml diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst index b4493a03dd7..6a9a6a04d8a 100644 --- a/Help/command/ctest_test.rst +++ b/Help/command/ctest_test.rst @@ -25,9 +25,14 @@ Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`. [RETURN_VALUE ] [CAPTURE_CMAKE_ERROR ] [REPEAT :] + [OUTPUT_JUNIT ] [QUIET] ) +.. + _note: If updating the argument list here, please also update the argument + list documentation for :command:`ctest_memcheck` as well. + Run tests in the project build tree and store results in ``Test.xml`` for submission with the :command:`ctest_submit` command. @@ -150,6 +155,15 @@ The options are: Store in the ```` variable -1 if there are any errors running the command and prevent ctest from returning non-zero if an error occurs. +``OUTPUT_JUNIT `` + .. versionadded:: 3.21 + + Write test results to ```` in JUnit XML format. If ```` is a + relative path, it will be placed in the build directory. If ```` + already exists, it will be overwritten. Note that the resulting JUnit XML + file is **not** uploaded to CDash because it would be redundant with + CTest's ``Test.xml`` file. + ``QUIET`` .. versionadded:: 3.3 @@ -160,3 +174,133 @@ The options are: See also the :variable:`CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE` and :variable:`CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE` variables. + +.. _`Additional Test Measurements`: + +Additional Test Measurements +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +CTest can parse the output of your tests for extra measurements to report +to CDash. + +When run as a :ref:`Dashboard Client`, CTest will include these custom +measurements in the ``Test.xml`` file that gets uploaded to CDash. + +Check the `CDash test measurement documentation +`_ +for more information on the types of test measurements that CDash recognizes. + +.. versionadded: 3.22 + CTest can parse custom measurements from tags named + ```` or ````. The older names + ```` and ```` are still supported. + +The following example demonstrates how to output a variety of custom test +measurements. + +.. code-block:: c++ + + std::cout << + "28.3" + << std::endl; + + std::cout << + "red" + << std::endl; + + std::cout << + "https://cmake.org" + << std::endl; + + std::cout << + "" << + "line 1.\n" << + " \033[31;1m line 2. Bold red, and indented!\033[0;0ml\n" << + "line 3. Not bold or indented...\n" << + "" << std::endl; + +Image Measurements +"""""""""""""""""" + +The following example demonstrates how to upload test images to CDash. + +.. code-block:: c++ + + std::cout << + "" << + "/dir/to/test_img.jpg" << std::endl; + + std::cout << + "" << + "/dir/to/valid_img.gif" << std::endl; + + std::cout << + " << + "/dir/to/img.png" + << std::endl; + +Images will be displayed together in an interactive comparison mode on CDash +if they are provided with two or more of the following names. + +* ``TestImage`` +* ``ValidImage`` +* ``BaselineImage`` +* ``DifferenceImage2`` + +By convention, ``TestImage`` is the image generated by your test, and +``ValidImage`` (or ``BaselineImage``) is basis of comparison used to determine +if the test passed or failed. + +If another image name is used it will be displayed by CDash as a static image +separate from the interactive comparison UI. + +Attached Files +"""""""""""""" + +.. versionadded:: 3.21 + +The following example demonstrates how to upload non-image files to CDash. + +.. code-block:: c++ + + std::cout << + "" << + "/dir/to/data1.csv\n" << + "" << + "/dir/to/data2.csv" << std::endl; + +If the name of the file to upload is known at configure time, you can use the +:prop_test:`ATTACHED_FILES` or :prop_test:`ATTACHED_FILES_ON_FAIL` test +properties instead. + +Custom Details +"""""""""""""" + +.. versionadded:: 3.21 + +The following example demonstrates how to specify a custom value for the +``Test Details`` field displayed on CDash. + +.. code-block:: c++ + + std::cout << + "My Custom Details Value" << std::endl; + +.. _`Additional Labels`: + +Additional Labels +""""""""""""""""" + +.. versionadded:: 3.22 + +The following example demonstrates how to add additional labels to a test +at runtime. + +.. code-block:: c++ + + std::cout << + "Custom Label 1\n" << + "Custom Label 2" << std::endl; + +Use the :prop_test:`LABELS` test property instead for labels that can be +determined at configure time. diff --git a/Help/command/enable_language.rst b/Help/command/enable_language.rst index ce765de684c..d2acbc85c69 100644 --- a/Help/command/enable_language.rst +++ b/Help/command/enable_language.rst @@ -10,7 +10,7 @@ Enables support for the named language in CMake. This is the same as the :command:`project` command but does not create any of the extra variables that are created by the project command. Example languages are ``CXX``, ``C``, ``CUDA``, ``OBJC``, ``OBJCXX``, ``Fortran``, -``ISPC``, and ``ASM``. +``HIP``, ``ISPC``, and ``ASM``. .. versionadded:: 3.8 Added ``CUDA`` support. @@ -21,6 +21,9 @@ are ``CXX``, ``C``, ``CUDA``, ``OBJC``, ``OBJCXX``, ``Fortran``, .. versionadded:: 3.18 Added ``ISPC`` support. +.. versionadded:: 3.21 + Added ``HIP`` support. + If enabling ``ASM``, enable it last so that CMake can check whether compilers for other languages like ``C`` work for assembly too. diff --git a/Help/command/file.rst b/Help/command/file.rst index 31de610b2b0..799b6ff106f 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -38,9 +38,10 @@ Synopsis `Filesystem`_ file({`GLOB`_ | `GLOB_RECURSE`_} [...] [...]) - file(`RENAME`_ ) - file({`REMOVE`_ | `REMOVE_RECURSE`_ } [...]) file(`MAKE_DIRECTORY`_ [...]) + file({`REMOVE`_ | `REMOVE_RECURSE`_ } [...]) + file(`RENAME`_ [...]) + file(`COPY_FILE`_ [...]) file({`COPY`_ | `INSTALL`_} ... DESTINATION [...]) file(`SIZE`_ ) file(`READ_SYMLINK`_ ) @@ -49,7 +50,7 @@ Synopsis file(`CHMOD_RECURSE`_ ... ... PERMISSIONS ... [...]) `Path Conversion`_ - file(`REAL_PATH`_ [BASE_DIRECTORY ]) + file(`REAL_PATH`_ [BASE_DIRECTORY ] [EXPAND_TILDE]) file(`RELATIVE_PATH`_ ) file({`TO_CMAKE_PATH`_ | `TO_NATIVE_PATH`_} ) @@ -115,7 +116,8 @@ Parse a list of ASCII strings from ```` and store it in binary while reading unless this option is given. ``REGEX `` - Consider only strings that match the given regular expression. + Consider only strings that match the given regular expression, + as described under :ref:`string(REGEX) `. ``ENCODING `` .. versionadded:: 3.1 @@ -178,6 +180,8 @@ the ```` and ``UTC`` options. [PRE_EXCLUDE_REGEXES [...]] [POST_INCLUDE_REGEXES [...]] [POST_EXCLUDE_REGEXES [...]] + [POST_INCLUDE_FILES [...]] + [POST_EXCLUDE_FILES [...]] ) .. versionadded:: 3.16 @@ -185,8 +189,10 @@ the ```` and ``UTC`` options. Recursively get the list of libraries depended on by the given files. Please note that this sub-command is not intended to be used in project mode. -Instead, use it in an :command:`install(CODE)` or :command:`install(SCRIPT)` -block. For example: +It is intended for use at install time, either from code generated by the +:command:`install(RUNTIME_DEPENDENCY_SET)` command, or from code provided by +the project via :command:`install(CODE)` or :command:`install(SCRIPT)`. +For example: .. code-block:: cmake @@ -275,6 +281,18 @@ 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. +``POST_INCLUDE_FILES `` + .. versionadded:: 3.21 + + List of post-include filenames through which to filter the names of resolved + dependencies. Symlinks are resolved when attempting to match these filenames. + +``POST_EXCLUDE_FILES `` + .. versionadded:: 3.21 + + List of post-exclude filenames through which to filter the names of resolved + dependencies. Symlinks are resolved when attempting to match these filenames. + 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: @@ -288,16 +306,18 @@ directory. The filtering works as follows: 4. ``file(GET_RUNTIME_DEPENDENCIES)`` searches for the dependency according to the linking rules of the platform (see below). 5. If the dependency is found, and its full path matches one of the - ``POST_INCLUDE_REGEXES``, the full path is added to the resolved - dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` recursively resolves - that library's own dependencies. Otherwise, resolution proceeds to step 6. + ``POST_INCLUDE_REGEXES`` or ``POST_INCLUDE_FILES``, the full path is added + to the resolved dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` + recursively resolves that library's own dependencies. Otherwise, resolution + proceeds to step 6. 6. If the dependency is found, but its full path matches one of the - ``POST_EXCLUDE_REGEXES``, it is not added to the resolved dependencies, and - dependency resolution stops for that dependency. + ``POST_EXCLUDE_REGEXES`` or ``POST_EXCLUDE_FILES``, it is not added to the + resolved dependencies, and dependency resolution stops for that dependency. 7. If the dependency is found, and its full path does not match either - ``POST_INCLUDE_REGEXES`` or ``POST_EXCLUDE_REGEXES``, the full path is added - to the resolved dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` - recursively resolves that library's own dependencies. + ``POST_INCLUDE_REGEXES``, ``POST_INCLUDE_FILES``, ``POST_EXCLUDE_REGEXES``, + or ``POST_EXCLUDE_FILES``, the full path is added to the resolved + dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` recursively resolves + that library's own dependencies. Different platforms have different rules for how dependencies are resolved. These specifics are described here. @@ -671,14 +691,13 @@ Examples of recursive globbing include:: /dir/*.py - match all python files in /dir and subdirectories -.. _RENAME: +.. _MAKE_DIRECTORY: .. code-block:: cmake - file(RENAME ) + file(MAKE_DIRECTORY [...]) -Move a file or directory within a filesystem from ```` to -````, replacing the destination atomically. +Create the given directories and their parents as needed. .. _REMOVE: .. _REMOVE_RECURSE: @@ -695,16 +714,67 @@ to the current source directory. .. versionchanged:: 3.15 Empty input paths are ignored with a warning. Previous versions of CMake - interpreted empty string as a relative path with respect to the current + interpreted empty strings as a relative path with respect to the current directory and removed its contents. -.. _MAKE_DIRECTORY: +.. _RENAME: .. code-block:: cmake - file(MAKE_DIRECTORY [...]) + file(RENAME + [RESULT ] + [NO_REPLACE]) -Create the given directories and their parents as needed. +Move a file or directory within a filesystem from ```` to +````, replacing the destination atomically. + +The options are: + +``RESULT `` + .. versionadded:: 3.21 + + Set ```` variable to ``0`` on success or an error message otherwise. + If ``RESULT`` is not specified and the operation fails, an error is emitted. + +``NO_REPLACE`` + .. versionadded:: 3.21 + + If the ```` path already exists, do not replace it. + If ``RESULT `` is used, the result variable will be + set to ``NO_REPLACE``. Otherwise, an error is emitted. + +.. _COPY_FILE: + +.. code-block:: cmake + + file(COPY_FILE + [RESULT ] + [ONLY_IF_DIFFERENT]) + +.. versionadded:: 3.21 + +Copy a file from ```` to ````. Directories are not +supported. Symlinks are ignored and ````'s content is read and +written to ```` as a new file. + +The options are: + +``RESULT `` + Set ```` variable to ``0`` on success or an error message otherwise. + If ``RESULT`` is not specified and the operation fails, an error is emitted. + +``ONLY_IF_DIFFERENT`` + If the ```` path already exists, do not replace it if the file's + contents are already the same as ```` (this avoids updating + ````'s timestamp). + +This sub-command has some similarities to :command:`configure_file` with the +``COPYONLY`` option. An important difference is that :command:`configure_file` +creates a dependency on the source file, so CMake will be re-run if it changes. +The ``file(COPY_FILE)`` sub-command does not create such a dependency. + +See also the ``file(COPY)`` sub-command just below which provides +further file-copying capabilities. .. _COPY: .. _INSTALL: @@ -720,6 +790,11 @@ Create the given directories and their parents as needed. [[PATTERN | REGEX ] [EXCLUDE] [PERMISSIONS ...]] [...]) +.. note:: + + For a simple file copying operation, the ``file(COPY_FILE)`` sub-command + just above may be easier to use. + The ``COPY`` signature copies files, directories, and symlinks to a destination folder. Relative input paths are evaluated with respect to the current source directory, and a relative destination is @@ -763,11 +838,16 @@ of their content even if options are used to select a subset of files. The ``INSTALL`` signature differs slightly from ``COPY``: it prints -status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable), -and ``NO_SOURCE_PERMISSIONS`` is default. +status messages, and ``NO_SOURCE_PERMISSIONS`` is default. + Installation scripts generated by the :command:`install` command use this signature (with some undocumented options for internal use). +.. versionchanged:: 3.22 + + The environment variable :envvar:`CMAKE_INSTALL_MODE` can override the + default copying behavior of :command:`file(INSTALL)`. + .. _SIZE: .. code-block:: cmake @@ -888,16 +968,26 @@ Path Conversion .. code-block:: cmake - file(REAL_PATH [BASE_DIRECTORY ]) + file(REAL_PATH [BASE_DIRECTORY ] [EXPAND_TILDE]) .. versionadded:: 3.19 Compute the absolute path to an existing file or directory with symlinks resolved. -If the provided ```` is a relative path, it is evaluated relative to the -given base directory ````. If no base directory is provided, the default -base directory will be :variable:`CMAKE_CURRENT_SOURCE_DIR`. +``BASE_DIRECTORY `` + If the provided ```` is a relative path, it is evaluated relative to the + given base directory ````. If no base directory is provided, the default + base directory will be :variable:`CMAKE_CURRENT_SOURCE_DIR`. + +``EXPAND_TILDE`` + .. versionadded:: 3.21 + + If the ```` is ``~`` or starts with ``~/``, the ``~`` is replaced by + the user's home directory. The path to the home directory is obtained from + environment variables. On Windows, the ``USERPROFILE`` environment variable + is used, falling back to the ``HOME`` environment variable if ``USERPROFILE`` + is not defined. On all other platforms, only ``HOME`` is used. .. _RELATIVE_PATH: @@ -983,7 +1073,7 @@ Options to both ``DOWNLOAD`` and ``UPLOAD`` are: .. versionadded:: 3.11 Specify whether the .netrc file is to be used for operation. If this - option is not specified, the value of the ``CMAKE_NETRC`` variable + option is not specified, the value of the :variable:`CMAKE_NETRC` variable will be used instead. Valid levels are: @@ -1002,29 +1092,28 @@ Options to both ``DOWNLOAD`` and ``UPLOAD`` are: Specify an alternative .netrc file to the one in your home directory, if the ``NETRC`` level is ``OPTIONAL`` or ``REQUIRED``. If this option - is not specified, the value of the ``CMAKE_NETRC_FILE`` variable will + is not specified, the value of the :variable:`CMAKE_NETRC_FILE` variable will be used instead. -If neither ``NETRC`` option is given CMake will check variables -``CMAKE_NETRC`` and ``CMAKE_NETRC_FILE``, respectively. - ``TLS_VERIFY `` Specify whether to verify the server certificate for ``https://`` URLs. - The default is to *not* verify. + The default is to *not* verify. If this option is not specified, the value + of the :variable:`CMAKE_TLS_VERIFY` variable will be used instead. .. versionadded:: 3.18 Added support to ``file(UPLOAD)``. ``TLS_CAINFO `` - Specify a custom Certificate Authority file for ``https://`` URLs. + Specify a custom Certificate Authority file for ``https://`` URLs. If this + option is not specified, the value of the :variable:`CMAKE_TLS_CAINFO` + variable will be used instead. .. versionadded:: 3.18 Added support to ``file(UPLOAD)``. 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. +check certificates. Additional options to ``DOWNLOAD`` are: diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 3dfd62fc32c..1a79a8af370 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -5,12 +5,74 @@ find_package .. contents:: -Find an external project, and load its settings. +Find a package (usually provided by something external to the project), +and load its package-specific details. + +Search Modes +^^^^^^^^^^^^ + +The command has two very distinct ways of conducting the search: + +**Module mode** + In this mode, CMake searches for a file called ``Find.cmake``, + looking first in the locations listed in the :variable:`CMAKE_MODULE_PATH`, + then among the :ref:`Find Modules` provided by the CMake installation. + If the file is found, it is read and processed by CMake. It is responsible + for finding the package, checking the version, and producing any needed + messages. Some Find modules provide limited or no support for versioning; + check the Find module's documentation. + + The ``Find.cmake`` file is not typically provided by the + package itself. Rather, it is normally provided by something external to + the package, such as the operating system, CMake itself, or even the project + from which the ``find_package()`` command was called. Being externally + provided, :ref:`Find Modules` tend to be heuristic in nature and are + susceptible to becoming out-of-date. They typically search for certain + libraries, files and other package artifacts. + + Module mode is only supported by the + :ref:`basic command signature `. + +**Config mode** + In this mode, CMake searches for a file called + ``-config.cmake`` or ``Config.cmake``. + It will also look for ``-config-version.cmake`` or + ``ConfigVersion.cmake`` if version details were specified + (see :ref:`version selection` for an explanation of how these separate + version files are used). + + In config mode, the command can be given a list of names to search for + as package names. The locations where CMake searches for the config and + version files is considerably more complicated than for Module mode + (see :ref:`search procedure`). + + The config and version files are typically installed as part of the + package, so they tend to be more reliable than Find modules. They usually + contain direct knowledge of the package contents, so no searching or + heuristics are needed within the config or version files themselves. + + Config mode is supported by both the :ref:`basic ` and + :ref:`full ` command signatures. + +The command arguments determine which of the above modes is used. When the +`basic signature`_ is used, the command searches in Module mode first. +If the package is not found, the search falls back to Config mode. +A user may set the :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` variable +to true to reverse the priority and direct CMake to search using Config mode +first before falling back to Module mode. The basic signature can also be +forced to use only Module mode with a ``MODULE`` keyword. If the +`full signature`_ is used, the command only searches in Config mode. + +Where possible, user code should generally look for packages using the +`basic signature`_, since that allows the package to be found with either mode. +Project maintainers wishing to provide a config package should understand +the bigger picture, as explained in :ref:`Full Signature` and all subsequent +sections on this page. .. _`basic signature`: -Basic Signature and Module Mode -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Basic Signature +^^^^^^^^^^^^^^^ .. code-block:: cmake @@ -19,20 +81,39 @@ Basic Signature and Module Mode [OPTIONAL_COMPONENTS components...] [NO_POLICY_SCOPE]) -Finds and loads settings from an external project. ``_FOUND`` -will be set to indicate whether the package was found. When the -package is found package-specific information is provided through -variables and :ref:`Imported Targets` documented by the package itself. The +The basic signature is supported by both Module and Config modes. +The ``MODULE`` keyword implies that only Module mode can be used to find +the package, with no fallback to Config mode. + +Regardless of the mode used, a ``_FOUND`` variable will be +set to indicate whether the package was found. When the package is found, +package-specific information may be provided through other variables and +:ref:`Imported Targets` documented by the package itself. The ``QUIET`` option disables informational messages, including those indicating that the package cannot be found if it is not ``REQUIRED``. The ``REQUIRED`` option stops processing with an error message if the package cannot be found. A package-specific list of required components may be listed after the -``COMPONENTS`` option (or after the ``REQUIRED`` option if present). +``COMPONENTS`` keyword. If any of these components are not able to be +satisfied, the package overall is considered to be not found. If the +``REQUIRED`` option is also present, this is treated as a fatal error, +otherwise execution still continues. As a form of shorthand, if the +``REQUIRED`` option is present, the ``COMPONENTS`` keyword can be omitted +and the required components can be listed directly after ``REQUIRED``. + Additional optional components may be listed after -``OPTIONAL_COMPONENTS``. Available components and their influence on -whether a package is considered to be found are defined by the target -package. +``OPTIONAL_COMPONENTS``. If these cannot be satisfied, the package overall +can still be considered found, as long as all required components are +satisfied. + +The set of available components and their meaning are defined by the +target package. Formally, it is up to the target package how to +interpret the component information given to it, but it should follow +the expectations stated above. For calls where no components are specified, +there is no single expected behavior and target packages should clearly +define what occurs in such cases. Common arrangements include assuming it +should find all components, no components or some well-defined subset of the +available components. .. _FIND_PACKAGE_VERSION_FORMAT: @@ -40,12 +121,13 @@ The ``[version]`` argument requests a version with which the package found should be compatible. There are two possible forms in which it may be specified: - * A single version with the format ``major[.minor[.patch[.tweak]]]``. + * A single version with the format ``major[.minor[.patch[.tweak]]]``, where + each component is a numeric value. * A version range with the format ``versionMin...[<]versionMax`` where - ``versionMin`` and ``versionMax`` have the same format as the single - version. By default, both end points are included. By specifying ``<``, - the upper end point will be excluded. Version ranges are only supported - with CMake 3.19 or later. + ``versionMin`` and ``versionMax`` have the same format and constraints + on components being integers as the single version. By default, both end + points are included. By specifying ``<``, the upper end point will be + excluded. Version ranges are only supported with CMake 3.19 or later. The ``EXACT`` option requests that the version be matched exactly. This option is incompatible with the specification of a version range. @@ -62,36 +144,10 @@ only take the single version at the lower end of the range into account. See the :command:`cmake_policy` command documentation for discussion of the ``NO_POLICY_SCOPE`` option. -The command has two modes by which it searches for packages: "Module" -mode and "Config" mode. The above signature selects Module mode. -If no module is found the command falls back to Config mode, described -below. This fall back is disabled if the ``MODULE`` option is given. - -In Module mode, CMake searches for a file called ``Find.cmake``. -The file is first searched in the :variable:`CMAKE_MODULE_PATH`, -then among the :ref:`Find Modules` provided by the CMake installation. -If the file is found, it is read and processed by CMake. It is responsible -for finding the package, checking the version, and producing any needed -messages. Some find-modules provide limited or no support for versioning; -check the module documentation. - -If the ``MODULE`` option is not 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 -``TRUE`` to direct CMake first search using Config mode before falling -back to Module mode. - -Full Signature and Config Mode -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -User code should generally look for packages using the above `basic -signature`_. The remainder of this command documentation specifies the -full command signature and details of the search process. Project -maintainers wishing to provide a package to be found by this command -are encouraged to read on. - -The complete Config mode command signature is +.. _`full signature`: + +Full Signature +^^^^^^^^^^^^^^ .. code-block:: cmake @@ -129,18 +185,19 @@ hold the directory containing the file. By default the command searches for a package with the name ````. If the ``NAMES`` option is given the names following it are used instead of ````. The command searches for a file called ``Config.cmake`` or -``-config.cmake`` for each name specified. +``-config.cmake`` for each name specified. A replacement set of possible configuration file names may be given -using the ``CONFIGS`` option. The search procedure is specified below. -Once found, the configuration file is read and processed by CMake. +using the ``CONFIGS`` option. The :ref:`search procedure` is specified below. +Once found, any :ref:`version constraint ` is checked, +and if satisfied, the configuration file is read and processed by CMake. Since the file is provided by the package it already knows the location of package contents. The full path to the configuration file is stored in the cmake variable ``_CONFIG``. All configuration files which have been considered by CMake while -searching for an installation of the package with an appropriate -version are stored in the cmake variable ``_CONSIDERED_CONFIGS``, -the associated versions in ``_CONSIDERED_VERSIONS``. +searching for the package with an appropriate version are stored in the +``_CONSIDERED_CONFIGS`` variable, and the associated versions +in the ``_CONSIDERED_VERSIONS`` variable. If the package configuration file cannot be found CMake will generate an error describing the problem unless the ``QUIET`` argument is @@ -150,143 +207,18 @@ fatal error is generated and the configure step stops executing. If configuration file CMake will ignore it and search from scratch. Package maintainers providing CMake package configuration files are -encouraged to name and install them such that the `Search Procedure`_ +encouraged to name and install them such that the :ref:`search procedure` outlined below will find them without requiring use of additional options. -Version Selection -^^^^^^^^^^^^^^^^^ +.. _`search procedure`: -When the ``[version]`` argument is given, Config mode will only find a -version of the package that claims compatibility with the requested -version (see :ref:`format specification `). If the -``EXACT`` option is given, only a version of the package claiming an exact match -of the requested version may be found. CMake does not establish any -convention for the meaning of version numbers. Package version -numbers are checked by "version" files provided by the packages -themselves. For a candidate package configuration file -``.cmake`` the corresponding version file is located next -to it and named either ``-version.cmake`` or -``Version.cmake``. If no such version file is available -then the configuration file is assumed to not be compatible with any -requested version. A basic version file containing generic version -matching code can be created using the -:module:`CMakePackageConfigHelpers` module. When a version file -is found it is loaded to check the requested version number. The -version file is loaded in a nested scope in which the following -variables have been defined: +Config Mode Search Procedure +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -``PACKAGE_FIND_NAME`` - The ```` -``PACKAGE_FIND_VERSION`` - Full requested version string -``PACKAGE_FIND_VERSION_MAJOR`` - Major version if requested, else 0 -``PACKAGE_FIND_VERSION_MINOR`` - Minor version if requested, else 0 -``PACKAGE_FIND_VERSION_PATCH`` - Patch version if requested, else 0 -``PACKAGE_FIND_VERSION_TWEAK`` - Tweak version if requested, else 0 -``PACKAGE_FIND_VERSION_COUNT`` - Number of version components, 0 to 4 - -When a version range is specified, the above version variables will hold -values based on the lower end of the version range. This is to preserve -compatibility with packages that have not been implemented to expect version -ranges. In addition, the version range will be described by the following -variables: - -``PACKAGE_FIND_VERSION_RANGE`` - Full requested version range string -``PACKAGE_FIND_VERSION_RANGE_MIN`` - This specifies whether the lower end point of the version range should be - included or excluded. Currently, the only supported value for this variable - is ``INCLUDE``. -``PACKAGE_FIND_VERSION_RANGE_MAX`` - This specifies whether the upper end point of the version range should be - included or excluded. The supported values for this variable are - ``INCLUDE`` and ``EXCLUDE``. - -``PACKAGE_FIND_VERSION_MIN`` - Full requested version string of the lower end point of the range -``PACKAGE_FIND_VERSION_MIN_MAJOR`` - Major version of the lower end point if requested, else 0 -``PACKAGE_FIND_VERSION_MIN_MINOR`` - Minor version of the lower end point if requested, else 0 -``PACKAGE_FIND_VERSION_MIN_PATCH`` - Patch version of the lower end point if requested, else 0 -``PACKAGE_FIND_VERSION_MIN_TWEAK`` - Tweak version of the lower end point if requested, else 0 -``PACKAGE_FIND_VERSION_MIN_COUNT`` - Number of version components of the lower end point, 0 to 4 - -``PACKAGE_FIND_VERSION_MAX`` - Full requested version string of the upper end point of the range -``PACKAGE_FIND_VERSION_MAX_MAJOR`` - Major version of the upper end point if requested, else 0 -``PACKAGE_FIND_VERSION_MAX_MINOR`` - Minor version of the upper end point if requested, else 0 -``PACKAGE_FIND_VERSION_MAX_PATCH`` - Patch version of the upper end point if requested, else 0 -``PACKAGE_FIND_VERSION_MAX_TWEAK`` - Tweak version of the upper end point if requested, else 0 -``PACKAGE_FIND_VERSION_MAX_COUNT`` - Number of version components of the upper end point, 0 to 4 - -Regardless of whether a single version or a version range is specified, the -variable ``PACKAGE_FIND_VERSION_COMPLETE`` will be defined and will hold -the full requested version string as specified. - -The version file checks whether it satisfies the requested version and -sets these variables: - -``PACKAGE_VERSION`` - Full provided version string -``PACKAGE_VERSION_EXACT`` - True if version is exact match -``PACKAGE_VERSION_COMPATIBLE`` - True if version is compatible -``PACKAGE_VERSION_UNSUITABLE`` - True if unsuitable as any version - -These variables are checked by the ``find_package`` command to determine -whether the configuration file provides an acceptable version. They -are not available after the ``find_package`` call returns. If the version -is acceptable the following variables are set: - -``_VERSION`` - Full provided version string -``_VERSION_MAJOR`` - Major version if provided, else 0 -``_VERSION_MINOR`` - Minor version if provided, else 0 -``_VERSION_PATCH`` - Patch version if provided, else 0 -``_VERSION_TWEAK`` - Tweak version if provided, else 0 -``_VERSION_COUNT`` - Number of version components, 0 to 4 - -and the corresponding package configuration file is loaded. -When multiple package configuration files are available whose version files -claim compatibility with the version requested it is unspecified which -one is chosen: unless the variable :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` -is set no attempt is made to choose a highest or closest version number. - -To control the order in which ``find_package`` checks for compatibility use -the two variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and -:variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`. -For instance in order to select the highest version one can set - -.. code-block:: cmake - - SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL) - SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC) - -before calling ``find_package``. - -Search Procedure -^^^^^^^^^^^^^^^^ +.. note:: + When Config mode is used, this search procedure is applied regardless of + whether the :ref:`full ` or :ref:`basic ` + signature was given. CMake constructs a set of possible installation prefixes for the package. Under each prefix several directories are searched for a @@ -432,7 +364,7 @@ enabled. hard-coded guesses. .. versionadded:: 3.16 - Added the ``CMAKE_FIND_USE__PATH`` variables to globally disable + Added the ``CMAKE_FIND_USE_`` variables to globally disable various search locations. .. |FIND_XXX| replace:: find_package @@ -448,8 +380,154 @@ which the file is found. The :variable:`CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS` variable may be set to ``TRUE`` before calling ``find_package`` in order to resolve symbolic links and store the real path to the file. -Every non-REQUIRED ``find_package`` call can be disabled by setting the -:variable:`CMAKE_DISABLE_FIND_PACKAGE_` variable to ``TRUE``. +Every non-REQUIRED ``find_package`` call can be disabled or made REQUIRED: + +* Setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_` variable + to ``TRUE`` disables the package. + +* Setting the :variable:`CMAKE_REQUIRE_FIND_PACKAGE_` variable + to ``TRUE`` makes the package REQUIRED. + +Setting both variables to ``TRUE`` simultaneously is an error. + +.. _`version selection`: + +Config Mode Version Selection +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. note:: + When Config mode is used, this version selection process is applied + regardless of whether the :ref:`full ` or + :ref:`basic ` signature was given. + +When the ``[version]`` argument is given, Config mode will only find a +version of the package that claims compatibility with the requested +version (see :ref:`format specification `). If the +``EXACT`` option is given, only a version of the package claiming an exact match +of the requested version may be found. CMake does not establish any +convention for the meaning of version numbers. Package version +numbers are checked by "version" files provided by the packages +themselves. For a candidate package configuration file +``.cmake`` the corresponding version file is located next +to it and named either ``-version.cmake`` or +``Version.cmake``. If no such version file is available +then the configuration file is assumed to not be compatible with any +requested version. A basic version file containing generic version +matching code can be created using the +:module:`CMakePackageConfigHelpers` module. When a version file +is found it is loaded to check the requested version number. The +version file is loaded in a nested scope in which the following +variables have been defined: + +``PACKAGE_FIND_NAME`` + The ```` +``PACKAGE_FIND_VERSION`` + Full requested version string +``PACKAGE_FIND_VERSION_MAJOR`` + Major version if requested, else 0 +``PACKAGE_FIND_VERSION_MINOR`` + Minor version if requested, else 0 +``PACKAGE_FIND_VERSION_PATCH`` + Patch version if requested, else 0 +``PACKAGE_FIND_VERSION_TWEAK`` + Tweak version if requested, else 0 +``PACKAGE_FIND_VERSION_COUNT`` + Number of version components, 0 to 4 + +When a version range is specified, the above version variables will hold +values based on the lower end of the version range. This is to preserve +compatibility with packages that have not been implemented to expect version +ranges. In addition, the version range will be described by the following +variables: + +``PACKAGE_FIND_VERSION_RANGE`` + Full requested version range string +``PACKAGE_FIND_VERSION_RANGE_MIN`` + This specifies whether the lower end point of the version range should be + included or excluded. Currently, the only supported value for this variable + is ``INCLUDE``. +``PACKAGE_FIND_VERSION_RANGE_MAX`` + This specifies whether the upper end point of the version range should be + included or excluded. The supported values for this variable are + ``INCLUDE`` and ``EXCLUDE``. + +``PACKAGE_FIND_VERSION_MIN`` + Full requested version string of the lower end point of the range +``PACKAGE_FIND_VERSION_MIN_MAJOR`` + Major version of the lower end point if requested, else 0 +``PACKAGE_FIND_VERSION_MIN_MINOR`` + Minor version of the lower end point if requested, else 0 +``PACKAGE_FIND_VERSION_MIN_PATCH`` + Patch version of the lower end point if requested, else 0 +``PACKAGE_FIND_VERSION_MIN_TWEAK`` + Tweak version of the lower end point if requested, else 0 +``PACKAGE_FIND_VERSION_MIN_COUNT`` + Number of version components of the lower end point, 0 to 4 + +``PACKAGE_FIND_VERSION_MAX`` + Full requested version string of the upper end point of the range +``PACKAGE_FIND_VERSION_MAX_MAJOR`` + Major version of the upper end point if requested, else 0 +``PACKAGE_FIND_VERSION_MAX_MINOR`` + Minor version of the upper end point if requested, else 0 +``PACKAGE_FIND_VERSION_MAX_PATCH`` + Patch version of the upper end point if requested, else 0 +``PACKAGE_FIND_VERSION_MAX_TWEAK`` + Tweak version of the upper end point if requested, else 0 +``PACKAGE_FIND_VERSION_MAX_COUNT`` + Number of version components of the upper end point, 0 to 4 + +Regardless of whether a single version or a version range is specified, the +variable ``PACKAGE_FIND_VERSION_COMPLETE`` will be defined and will hold +the full requested version string as specified. + +The version file checks whether it satisfies the requested version and +sets these variables: + +``PACKAGE_VERSION`` + Full provided version string +``PACKAGE_VERSION_EXACT`` + True if version is exact match +``PACKAGE_VERSION_COMPATIBLE`` + True if version is compatible +``PACKAGE_VERSION_UNSUITABLE`` + True if unsuitable as any version + +These variables are checked by the ``find_package`` command to determine +whether the configuration file provides an acceptable version. They +are not available after the ``find_package`` call returns. If the version +is acceptable the following variables are set: + +``_VERSION`` + Full provided version string +``_VERSION_MAJOR`` + Major version if provided, else 0 +``_VERSION_MINOR`` + Minor version if provided, else 0 +``_VERSION_PATCH`` + Patch version if provided, else 0 +``_VERSION_TWEAK`` + Tweak version if provided, else 0 +``_VERSION_COUNT`` + Number of version components, 0 to 4 + +and the corresponding package configuration file is loaded. +When multiple package configuration files are available whose version files +claim compatibility with the version requested it is unspecified which +one is chosen: unless the variable :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` +is set no attempt is made to choose a highest or closest version number. + +To control the order in which ``find_package`` checks for compatibility use +the two variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and +:variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`. +For instance in order to select the highest version one can set + +.. code-block:: cmake + + SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL) + SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC) + +before calling ``find_package``. Package File Interface Variables ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -479,7 +557,7 @@ restores their original state before returning): ``_FIND_VERSION_EXACT`` True if ``EXACT`` option was given ``_FIND_COMPONENTS`` - List of requested components + List of specified components (required and optional) ``_FIND_REQUIRED_`` True if component ```` is required, false if component ```` is optional diff --git a/Help/command/foreach.rst b/Help/command/foreach.rst index 8de6debae42..d9f54ca7502 100644 --- a/Help/command/foreach.rst +++ b/Help/command/foreach.rst @@ -14,9 +14,12 @@ semicolon or whitespace. All commands between ``foreach`` and the matching ``endforeach`` are recorded without being invoked. Once the ``endforeach`` is evaluated, the recorded list of commands is invoked once for each item in ````. -At the beginning of each iteration the variable ``loop_var`` will be set +At the beginning of each iteration the variable ```` will be set to the value of the current item. +The scope of ```` is restricted to the loop scope. See policy +:policy:`CMP0124` for details. + The commands :command:`break` and :command:`continue` provide means to escape from the normal control flow. diff --git a/Help/command/get_filename_component.rst b/Help/command/get_filename_component.rst index be9d00af30a..4bdd3885dc6 100644 --- a/Help/command/get_filename_component.rst +++ b/Help/command/get_filename_component.rst @@ -3,7 +3,7 @@ get_filename_component Get a specific component of a full filename. -.. versionchanged:: 3.19 +.. versionchanged:: 3.20 This command been superseded by :command:`cmake_path` command, except ``REALPATH`` now offered by :ref:`file(REAL_PATH) ` command and ``PROGRAM`` now available in :command:`separate_arguments(PROGRAM)` command. diff --git a/Help/command/get_property.rst b/Help/command/get_property.rst index f77d8af7858..46da2853b2c 100644 --- a/Help/command/get_property.rst +++ b/Help/command/get_property.rst @@ -9,7 +9,7 @@ Get a property. ] | TARGET | - SOURCE | + SOURCE [DIRECTORY | TARGET_DIRECTORY ] | INSTALL | TEST | diff --git a/Help/command/if.rst b/Help/command/if.rst index fbf3e363f3a..5dba13ef3a5 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -56,12 +56,23 @@ Basic Expressions ``NO``, ``FALSE``, ``N``, ``IGNORE``, ``NOTFOUND``, the empty string, or ends in the suffix ``-NOTFOUND``. Named boolean constants are case-insensitive. If the argument is not one of these specific - constants, it is treated as a variable or string and the following - signature is used. + constants, it is treated as a variable or string (see `Variable Expansion`_ + further below) and one of the following two forms applies. -``if()`` +``if()`` True if given a variable that is defined to a value that is not a false - constant. False otherwise. (Note macro arguments are not variables.) + constant. False otherwise, including if the variable is undefined. + Note that macro arguments are not variables. + Environment variables also cannot be tested this way, e.g. + ``if(ENV{some_var})`` will always evaluate to false. + +``if()`` + A quoted string always evaluates to false unless: + + * The string's value is one of the true constants, or + * Policy :policy:`CMP0054` is not set to ``NEW`` and the string's value + happens to be a variable name that is affected by :policy:`CMP0054`'s + behavior. Logic Operators """"""""""""""" @@ -171,7 +182,7 @@ Comparisons ``if( MATCHES regex)`` True if the given string or variable's value matches the given regular - condition. See :ref:`Regex Specification` for regex format. + expression. See :ref:`Regex Specification` for regex format. .. versionadded:: 3.9 ``()`` groups are captured in :variable:`CMAKE_MATCH_` variables. diff --git a/Help/command/install.rst b/Help/command/install.rst index 35207f4c47b..1236f1d32b7 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -9,11 +9,13 @@ Synopsis .. parsed-literal:: install(`TARGETS`_ ... [...]) + install(`IMPORTED_RUNTIME_ARTIFACTS`_ ... [...]) install({`FILES`_ | `PROGRAMS`_} ... [...]) install(`DIRECTORY`_ ... [...]) install(`SCRIPT`_ [...]) install(`CODE`_ [...]) install(`EXPORT`_ [...]) + install(`RUNTIME_DEPENDENCY_SET`_ [...]) Introduction ^^^^^^^^^^^^ @@ -28,6 +30,10 @@ are executed in order during installation. with those in the parent directory to run in the order declared (see policy :policy:`CMP0082`). +.. versionchanged:: 3.22 + The environment variable :envvar:`CMAKE_INSTALL_MODE` can override the + default copying behavior of :command:`install()`. + There are multiple signatures for this command. Some of them define installation options for files and targets. Options common to multiple signatures are covered here but they are valid only for @@ -124,6 +130,7 @@ Installing Targets .. code-block:: cmake install(TARGETS targets... [EXPORT ] + [RUNTIME_DEPENDENCIES args...|RUNTIME_DEPENDENCY_SET ] [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE| PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE] [DESTINATION ] @@ -338,6 +345,49 @@ top level: relative path is specified, it is treated as relative to the ``$``. +``RUNTIME_DEPENDENCY_SET`` + .. versionadded:: 3.21 + + This option causes all runtime dependencies of installed executable, shared + library, and module targets to be added to the specified runtime dependency + set. This set can then be installed with an + `install(RUNTIME_DEPENDENCY_SET)`_ command. + + This keyword and the ``RUNTIME_DEPENDENCIES`` keyword are mutually + exclusive. + +``RUNTIME_DEPENDENCIES`` + .. versionadded:: 3.21 + + This option causes all runtime dependencies of installed executable, shared + library, and module targets to be installed along with the targets + themselves. The ``RUNTIME``, ``LIBRARY``, ``FRAMEWORK``, and generic + arguments are used to determine the properties (``DESTINATION``, + ``COMPONENT``, etc.) of the installation of these dependencies. + + ``RUNTIME_DEPENDENCIES`` is semantically equivalent to the following pair + of calls: + + .. code-block:: cmake + + install(TARGETS ... RUNTIME_DEPENDENCY_SET ) + install(RUNTIME_DEPENDENCY_SET args...) + + where ```` will be a randomly generated set name. + The ``args...`` may include any of the following keywords supported by + the `install(RUNTIME_DEPENDENCY_SET)`_ command: + + * ``DIRECTORIES`` + * ``PRE_INCLUDE_REGEXES`` + * ``PRE_EXCLUDE_REGEXES`` + * ``POST_INCLUDE_REGEXES`` + * ``POST_EXCLUDE_REGEXES`` + * ``POST_INCLUDE_FILES`` + * ``POST_EXCLUDE_FILES`` + + The ``RUNTIME_DEPENDENCIES`` and ``RUNTIME_DEPENDENCY_SET`` keywords are + mutually exclusive. + One or more groups of properties may be specified in a single call to the ``TARGETS`` form of this command. A target may be installed more than once to different locations. Consider hypothetical targets ``myExe``, @@ -382,6 +432,44 @@ set to ``TRUE`` has undefined behavior. to ensure that such out-of-directory targets are built before the subdirectory-specific install rules are run. +Installing Imported Runtime Artifacts +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. _`install(IMPORTED_RUNTIME_ARTIFACTS)`: +.. _IMPORTED_RUNTIME_ARTIFACTS: + +.. versionadded:: 3.21 + +.. code-block:: cmake + + install(IMPORTED_RUNTIME_ARTIFACTS targets... + [RUNTIME_DEPENDENCY_SET ] + [[LIBRARY|RUNTIME|FRAMEWORK|BUNDLE] + [DESTINATION ] + [PERMISSIONS permissions...] + [CONFIGURATIONS [Debug|Release|...]] + [COMPONENT ] + [OPTIONAL] [EXCLUDE_FROM_ALL] + ] [...] + ) + +The ``IMPORTED_RUNTIME_ARTIFACTS`` form specifies rules for installing the +runtime artifacts of imported targets. Projects may do this if they want to +bundle outside executables or modules inside their installation. The +``LIBRARY``, ``RUNTIME``, ``FRAMEWORK``, and ``BUNDLE`` arguments have the +same semantics that they do in the `TARGETS`_ mode. Only the runtime artifacts +of imported targets are installed (except in the case of :prop_tgt:`FRAMEWORK` +libraries, :prop_tgt:`MACOSX_BUNDLE` executables, and :prop_tgt:`BUNDLE` +CFBundles.) For example, headers and import libraries associated with DLLs are +not installed. In the case of :prop_tgt:`FRAMEWORK` libraries, +:prop_tgt:`MACOSX_BUNDLE` executables, and :prop_tgt:`BUNDLE` CFBundles, the +entire directory is installed. + +The ``RUNTIME_DEPENDENCY_SET`` option causes the runtime artifacts of the +imported executable, shared library, and module library ``targets`` to be +added to the ```` runtime dependency set. This set can then be +installed with an `install(RUNTIME_DEPENDENCY_SET)`_ command. + Installing Files ^^^^^^^^^^^^^^^^ @@ -540,7 +628,8 @@ any expression. For example, the code will extract and install header files from a source tree. -Some options may follow a ``PATTERN`` or ``REGEX`` expression and are applied +Some options may follow a ``PATTERN`` or ``REGEX`` expression as described +under :ref:`string(REGEX) ` and are applied only to files or directories matching them. The ``EXCLUDE`` option will skip the matched file or directory. The ``PERMISSIONS`` option overrides the permissions setting for the matched file or directory. For @@ -619,7 +708,8 @@ Custom Installation Logic .. code-block:: cmake install([[SCRIPT ] [CODE ]] - [COMPONENT ] [EXCLUDE_FROM_ALL] [...]) + [ALL_COMPONENTS | COMPONENT ] + [EXCLUDE_FROM_ALL] [...]) The ``SCRIPT`` form will invoke the given CMake script files during installation. If the script file name is a relative path it will be @@ -634,6 +724,12 @@ example, the code will print a message during installation. +.. versionadded:: 3.21 + When the ``ALL_COMPONENTS`` option is given, the custom installation + script code will be executed for every component of a component-specific + installation. This option is mutually exclusive with the ``COMPONENT`` + option. + .. versionadded:: 3.14 ```` or ```` may use "generator expressions" with the syntax ``$<...>`` (in the case of ````, this refers to their use in the file @@ -724,7 +820,7 @@ executable from the installation tree using the imported target name ``mp_myexe`` as if the target were built in its own tree. .. note:: - This command supercedes the :command:`install_targets` command and + This command supersedes the :command:`install_targets` command and the :prop_tgt:`PRE_INSTALL_SCRIPT` and :prop_tgt:`POST_INSTALL_SCRIPT` target properties. It also replaces the ``FILES`` forms of the :command:`install_files` and :command:`install_programs` commands. @@ -733,6 +829,70 @@ executable from the installation tree using the imported target name :command:`install_files`, and :command:`install_programs` commands is not defined. +Installing Runtime Dependencies +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. _`install(RUNTIME_DEPENDENCY_SET)`: +.. _RUNTIME_DEPENDENCY_SET: + +.. versionadded:: 3.21 + +.. code-block:: cmake + + install(RUNTIME_DEPENDENCY_SET + [[LIBRARY|RUNTIME|FRAMEWORK] + [DESTINATION ] + [PERMISSIONS permissions...] + [CONFIGURATIONS [Debug|Release|...]] + [COMPONENT ] + [NAMELINK_COMPONENT ] + [OPTIONAL] [EXCLUDE_FROM_ALL] + ] [...] + [PRE_INCLUDE_REGEXES regexes...] + [PRE_EXCLUDE_REGEXES regexes...] + [POST_INCLUDE_REGEXES regexes...] + [POST_EXCLUDE_REGEXES regexes...] + [POST_INCLUDE_FILES files...] + [POST_EXCLUDE_FILES files...] + [DIRECTORIES directories...] + ) + +Installs a runtime dependency set previously created by one or more +`install(TARGETS)`_ or `install(IMPORTED_RUNTIME_ARTIFACTS)`_ commands. The +dependencies of targets belonging to a runtime dependency set are installed in +the ``RUNTIME`` destination and component on DLL platforms, and in the +``LIBRARY`` destination and component on non-DLL platforms. macOS frameworks +are installed in the ``FRAMEWORK`` destination and component. +Targets built within the build tree will never be installed as runtime +dependencies, nor will their own dependencies, unless the targets themselves +are installed with `install(TARGETS)`_. + +The generated install script calls :command:`file(GET_RUNTIME_DEPENDENCIES)` +on the build-tree files to calculate the runtime dependencies. The build-tree +executable files are passed as the ``EXECUTABLES`` argument, the build-tree +shared libraries as the ``LIBRARIES`` argument, and the build-tree modules as +the ``MODULES`` argument. On macOS, if one of the executables is a +:prop_tgt:`MACOSX_BUNDLE`, that executable is passed as the +``BUNDLE_EXECUTABLE`` argument. At most one such bundle executable may be in +the runtime dependency set on macOS. The :prop_tgt:`MACOSX_BUNDLE` property +has no effect on other platforms. Note that +:command:`file(GET_RUNTIME_DEPENDENCIES)` only supports collecting the runtime +dependencies for Windows, Linux and macOS platforms, so +``install(RUNTIME_DEPENDENCY_SET)`` has the same limitation. + +The following sub-arguments are forwarded through as the corresponding +arguments to :command:`file(GET_RUNTIME_DEPENDENCIES)` (for those that provide +a non-empty list of directories, regular expressions or files). They all +support :manual:`generator expressions `. + +* ``DIRECTORIES `` +* ``PRE_INCLUDE_REGEXES `` +* ``PRE_EXCLUDE_REGEXES `` +* ``POST_INCLUDE_REGEXES `` +* ``POST_EXCLUDE_REGEXES `` +* ``POST_INCLUDE_FILES `` +* ``POST_EXCLUDE_FILES `` + Generated Installation Script ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/command/install_files.rst b/Help/command/install_files.rst index ff074a8a770..494f3d0ee5a 100644 --- a/Help/command/install_files.rst +++ b/Help/command/install_files.rst @@ -5,7 +5,7 @@ install_files Use the :command:`install(FILES)` command instead. -This command has been superceded by the :command:`install` command. It is +This command has been superseded by the :command:`install` command. It is provided for compatibility with older CMake code. The ``FILES`` form is directly replaced by the ``FILES`` form of the :command:`install` command. The regexp form can be expressed more clearly using the ``GLOB`` diff --git a/Help/command/install_programs.rst b/Help/command/install_programs.rst index fab64820d27..eafae899668 100644 --- a/Help/command/install_programs.rst +++ b/Help/command/install_programs.rst @@ -5,7 +5,7 @@ install_programs Use the :command:`install(PROGRAMS)` command instead. -This command has been superceded by the :command:`install` command. It is +This command has been superseded by the :command:`install` command. It is provided for compatibility with older CMake code. The ``FILES`` form is directly replaced by the ``PROGRAMS`` form of the :command:`install` command. The regexp form can be expressed more clearly using the ``GLOB`` diff --git a/Help/command/install_targets.rst b/Help/command/install_targets.rst index c9efdce6787..9355f8d532a 100644 --- a/Help/command/install_targets.rst +++ b/Help/command/install_targets.rst @@ -5,7 +5,7 @@ install_targets Use the :command:`install(TARGETS)` command instead. -This command has been superceded by the :command:`install` command. It is +This command has been superseded by the :command:`install` command. It is provided for compatibility with older CMake code. :: diff --git a/Help/command/list.rst b/Help/command/list.rst index 7accc5a39e1..9b49cb493ac 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -141,8 +141,8 @@ Appends elements to the list. Includes or removes items from the list that match the mode's pattern. In ``REGEX`` mode, items will be matched against the given regular expression. -For more information on regular expressions see also the -:command:`string` command. +For more information on regular expressions look under +:ref:`string(REGEX) `. .. _INSERT: @@ -161,8 +161,9 @@ Inserts elements to the list to the specified location. .. versionadded:: 3.15 If no variable name is given, removes exactly one element. Otherwise, -assign the last element's value to the given variable and removes it, -up to the last variable name given. +with `N` variable names provided, assign the last `N` elements' values +to the given variables and then remove the last `N` values from +````. .. _POP_FRONT: @@ -173,8 +174,9 @@ up to the last variable name given. .. versionadded:: 3.15 If no variable name is given, removes exactly one element. Otherwise, -assign the first element's value to the given variable and removes it, -up to the last variable name given. +with `N` variable names provided, assign the first `N` elements' values +to the given variables and then remove the first `N` values from +````. .. _PREPEND: diff --git a/Help/command/project.rst b/Help/command/project.rst index 6c931b692ae..2a9dcfe3007 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -20,12 +20,18 @@ Sets the name of the project, and stores it in the variable ``CMakeLists.txt`` also stores the project name in the variable :variable:`CMAKE_PROJECT_NAME`. -Also sets the variables +Also sets the variables: -* :variable:`PROJECT_SOURCE_DIR`, - :variable:`_SOURCE_DIR` -* :variable:`PROJECT_BINARY_DIR`, - :variable:`_BINARY_DIR` +:variable:`PROJECT_SOURCE_DIR`, :variable:`_SOURCE_DIR` + Absolute path to the source directory for the project. + +:variable:`PROJECT_BINARY_DIR`, :variable:`_BINARY_DIR` + Absolute path to the binary directory for the project. + +:variable:`PROJECT_IS_TOP_LEVEL`, :variable:`_IS_TOP_LEVEL` + .. versionadded:: 3.21 + + Boolean value indicating whether the project is top-level. Further variables are set by the optional arguments described in the following. If any of these arguments is not used, then the corresponding variables are @@ -97,7 +103,7 @@ The options are: Selects which programming languages are needed to build the project. Supported languages include ``C``, ``CXX`` (i.e. C++), ``CUDA``, - ``OBJC`` (i.e. Objective-C), ``OBJCXX``, ``Fortran``, ``ISPC``, and ``ASM``. + ``OBJC`` (i.e. Objective-C), ``OBJCXX``, ``Fortran``, ``HIP``, ``ISPC``, and ``ASM``. By default ``C`` and ``CXX`` are enabled if no language options are given. Specify language ``NONE``, or use the ``LANGUAGES`` keyword and list no languages, to skip enabling any languages. diff --git a/Help/command/set.rst b/Help/command/set.rst index c0e02e2465a..af862e4da3e 100644 --- a/Help/command/set.rst +++ b/Help/command/set.rst @@ -68,9 +68,13 @@ users. If the cache entry does not exist prior to the call or the ``FORCE`` option is given then the cache entry will be set to the given value. -Furthermore, any normal variable binding in the current scope will -be removed to expose the newly cached value to any immediately -following evaluation. + +.. note:: + + The content of the cache variable will not be directly accessible if a normal + variable of the same name already exists (see :ref:`rules of variable + evaluation `). If policy :policy:`CMP0126` is set + to ``OLD``, any normal variable binding in the current scope will be removed. It is possible for the cache entry to exist prior to the call but have no type set if it was created on the :manual:`cmake(1)` command diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst index bf437b43473..555520d227c 100644 --- a/Help/command/set_property.rst +++ b/Help/command/set_property.rst @@ -9,8 +9,8 @@ Set a named property in a given scope. DIRECTORY [] | TARGET [ ...] | SOURCE [ ...] - [DIRECTORY ...] | - [TARGET_DIRECTORY ...] + [DIRECTORY ...] + [TARGET_DIRECTORY ...] | INSTALL [ ...] | TEST [ ...] | CACHE [ ...] > diff --git a/Help/command/source_group.rst b/Help/command/source_group.rst index 5db1ec8c54d..83ae2864cfc 100644 --- a/Help/command/source_group.rst +++ b/Help/command/source_group.rst @@ -11,6 +11,9 @@ There are two different signatures to create source groups. Defines a group into which sources will be placed in project files. This is intended to set up file tabs in Visual Studio. +The group is scoped in the directory where the command is called, +and applies to sources in targets created in that directory. + The options are: ``TREE`` @@ -19,7 +22,8 @@ The options are: CMake will automatically detect, from ```` files paths, source groups it needs to create, to keep structure of source groups analogically to the actual files and directories structure in the project. Paths of ```` - files will be cut to be relative to ````. + files will be cut to be relative to ````. The command fails if the + paths within ``src`` do not start with ``root``. ``PREFIX`` .. versionadded:: 3.8 diff --git a/Help/command/string.rst b/Help/command/string.rst index 8ad0089afd3..29ad082a905 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -449,38 +449,73 @@ be in Coordinated Universal Time (UTC) rather than local time. The optional ```` may contain the following format specifiers: -:: +``%%`` + .. versionadded:: 3.8 - %% A literal percent sign (%). - %d The day of the current month (01-31). - %H The hour on a 24-hour clock (00-23). - %I The hour on a 12-hour clock (01-12). - %j The day of the current year (001-366). - %m The month of the current year (01-12). - %b Abbreviated month name (e.g. Oct). - %B Full month name (e.g. October). - %M The minute of the current hour (00-59). - %s Seconds since midnight (UTC) 1-Jan-1970 (UNIX time). - %S The second of the current minute. - 60 represents a leap second. (00-60) - %U The week number of the current year (00-53). - %w The day of the current week. 0 is Sunday. (0-6) - %a Abbreviated weekday name (e.g. Fri). - %A Full weekday name (e.g. Friday). - %y The last two digits of the current year (00-99) - %Y The current year. - -.. versionadded:: 3.6 - ``%s`` format specifier (UNIX time). + A literal percent sign (%). -.. versionadded:: 3.7 - ``%a`` and ``%b`` format specifiers (abbreviated month and weekday names). +``%d`` + The day of the current month (01-31). -.. versionadded:: 3.8 - ``%%`` specifier (literal ``%``). +``%H`` + The hour on a 24-hour clock (00-23). -.. versionadded:: 3.7 - ``%A`` and ``%B`` format specifiers (full month and weekday names). +``%I`` + The hour on a 12-hour clock (01-12). + +``%j`` + The day of the current year (001-366). + +``%m`` + The month of the current year (01-12). + +``%b`` + .. versionadded:: 3.7 + + Abbreviated month name (e.g. Oct). + +``%B`` + .. versionadded:: 3.10 + + Full month name (e.g. October). + +``%M`` + The minute of the current hour (00-59). + +``%s`` + .. versionadded:: 3.6 + + Seconds since midnight (UTC) 1-Jan-1970 (UNIX time). + +``%S`` + The second of the current minute. 60 represents a leap second. (00-60) + +``%U`` + The week number of the current year (00-53). + +``%V`` + .. versionadded:: 3.22 + + The ISO 8601 week number of the current year (01-53). + +``%w`` + The day of the current week. 0 is Sunday. (0-6) + +``%a`` + .. versionadded:: 3.7 + + Abbreviated weekday name (e.g. Fri). + +``%A`` + .. versionadded:: 3.10 + + Full weekday name (e.g. Friday). + +``%y`` + The last two digits of the current year (00-99). + +``%Y`` + The current year. Unknown format specifiers will be ignored and copied to the output as-is. diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index 872e264e99a..c85094aa918 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -289,6 +289,91 @@ treated as :ref:`Interface Libraries`, but when they appear in a target's :prop_tgt:`LINK_LIBRARIES` property their object files will be included in the link too. +.. _`Linking Object Libraries via $`: + +Linking Object Libraries via $ +"""""""""""""""""""""""""""""""""""""""""""""" + +.. versionadded:: 3.21 + +The object files associated with an object library may be referenced +by the :genex:`$` generator expression. Such object +files are placed on the link line *before* all libraries, regardless +of their relative order. Additionally, an ordering dependency will be +added to the build system to make sure the object library is up-to-date +before the dependent target links. For example, the code + +.. code-block:: cmake + + add_library(obj3 OBJECT obj3.c) + target_compile_definitions(obj3 PUBLIC OBJ3) + + add_executable(main3 main3.c) + target_link_libraries(main3 PRIVATE a3 $ b3) + +links executable ``main3`` with object files from ``main3.c`` +and ``obj3.c`` followed by the ``a3`` and ``b3`` libraries. +``main3.c`` is *not* compiled with usage requirements from ``obj3``, +such as ``-DOBJ3``. + +This approach can be used to achieve transitive inclusion of object +files in link lines as usage requirements. Continuing the above +example, the code + +.. code-block:: cmake + + add_library(iface_obj3 INTERFACE) + target_link_libraries(iface_obj3 INTERFACE obj3 $) + +creates an interface library ``iface_obj3`` that forwards the ``obj3`` +usage requirements and adds the ``obj3`` object files to dependents' +link lines. The code + +.. code-block:: cmake + + add_executable(use_obj3 use_obj3.c) + target_link_libraries(use_obj3 PRIVATE iface_obj3) + +compiles ``use_obj3.c`` with ``-DOBJ3`` and links executable ``use_obj3`` +with object files from ``use_obj3.c`` and ``obj3.c``. + +This also works transitively through a static library. Since a static +library does not link, it does not consume the object files from +object libraries referenced this way. Instead, the object files +become transitive link dependencies of the static library. +Continuing the above example, the code + +.. code-block:: cmake + + add_library(static3 STATIC static3.c) + target_link_libraries(static3 PRIVATE iface_obj3) + + add_executable(use_static3 use_static3.c) + target_link_libraries(use_static3 PRIVATE static3) + +compiles ``static3.c`` with ``-DOBJ3`` and creates ``libstatic3.a`` +using only its own object file. ``use_static3.c`` is compiled *without* +``-DOBJ3`` because the usage requirement is not transitive through +the private dependency of ``static3``. However, the link dependencies +of ``static3`` are propagated, including the ``iface_obj3`` reference +to ``$``. The ``use_static3`` executable is +created with object files from ``use_static3.c`` and ``obj3.c``, and +linked to library ``libstatic3.a``. + +When using this approach, it is the project's responsibility to avoid +linking multiple dependent binaries to ``iface_obj3``, because they will +all get the ``obj3`` object files on their link lines. + +.. note:: + + Referencing :genex:`$` in ``target_link_libraries`` + calls worked in versions of CMake prior to 3.21 for some cases, + but was not fully supported: + + * It did not place the object files before libraries on link lines. + * It did not add an ordering dependency on the object library. + * It did not work in Xcode with multiple architectures. + Cyclic Dependencies of Static Libraries ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/cpack_gen/archive.rst b/Help/cpack_gen/archive.rst index b9418126f82..47e8e135466 100644 --- a/Help/cpack_gen/archive.rst +++ b/Help/cpack_gen/archive.rst @@ -82,7 +82,8 @@ CPack generators which are essentially archives at their core. These include: See also the :variable:`CPACK_THREADS` variable. -.. note:: + .. versionadded:: 3.21 - Official CMake binaries available on ``cmake.org`` ship with a ``liblzma`` - that does not support parallel compression. + Official CMake binaries available on ``cmake.org`` now ship + with a ``liblzma`` that supports parallel compression. + Older versions did not. diff --git a/Help/cpack_gen/deb.rst b/Help/cpack_gen/deb.rst index 03c4ea8dbc6..f96ca320396 100644 --- a/Help/cpack_gen/deb.rst +++ b/Help/cpack_gen/deb.rst @@ -274,10 +274,23 @@ List of CPack DEB generator specific variables: Possible values are: - - lzma - - xz - - bzip2 - - gzip + ``lzma`` + Lempel–Ziv–Markov chain algorithm + + ``xz`` + XZ Utils compression + + ``bzip2`` + bzip2 Burrows–Wheeler algorithm + + ``gzip`` + GNU Gzip compression + + ``zstd`` + .. versionadded:: 3.22 + + Zstandard compression + .. variable:: CPACK_DEBIAN_PACKAGE_PRIORITY CPACK_DEBIAN__PACKAGE_PRIORITY @@ -289,7 +302,7 @@ List of CPack DEB generator specific variables: * Default : "optional" .. versionadded:: 3.5 - Per-component ``CPACK_DEBIAN__PACKAGE_PRIORITY`` varables. + Per-component ``CPACK_DEBIAN__PACKAGE_PRIORITY`` variables. See https://www.debian.org/doc/debian-policy/ch-archive.html#s-priorities @@ -650,11 +663,20 @@ Dbgsym packaging has its own set of variables: * Mandatory : NO * Default : OFF +.. note:: + + Setting this also strips the ELF files in the generated non-dbgsym package, + which results in debuginfo only being available in the dbgsym package. + .. note:: Binaries must contain debug symbols before packaging so use either ``Debug`` or ``RelWithDebInfo`` for :variable:`CMAKE_BUILD_TYPE` variable value. + Additionally, if :variable:`CPACK_STRIP_FILES` is set, the files will be stripped before + they get to the DEB generator, so will not contain debug symbols and + a dbgsym package will not get built. Do not use with :variable:`CPACK_STRIP_FILES`. + Building Debian packages on Windows ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/cpack_gen/dmg.rst b/Help/cpack_gen/dmg.rst index 4c662a6f81e..1f05618cc7c 100644 --- a/Help/cpack_gen/dmg.rst +++ b/Help/cpack_gen/dmg.rst @@ -51,7 +51,7 @@ on macOS: .. versionadded:: 3.6 - Default behaviour is to include a symlink to ``/Applications`` in the DMG. + Default behavior is to include a symlink to ``/Applications`` in the DMG. Set this option to ``ON`` to avoid adding the symlink. .. variable:: CPACK_DMG_SLA_DIR @@ -103,6 +103,14 @@ on macOS: - Default: ``CPACK_PACKAGE_FILE_NAME-`` +.. variable:: CPACK_DMG_FILESYSTEM + + .. versionadded:: 3.21 + + The filesystem format. Common values are ``APFS`` and ``HFS+``. + See ``man hdiutil`` for a full list of supported formats. + Defaults to ``HFS+``. + .. variable:: CPACK_COMMAND_HDIUTIL Path to the ``hdiutil(1)`` command used to operate on disk image files on diff --git a/Help/cpack_gen/freebsd.rst b/Help/cpack_gen/freebsd.rst index 2c9356956cd..f429bc5fa9b 100644 --- a/Help/cpack_gen/freebsd.rst +++ b/Help/cpack_gen/freebsd.rst @@ -74,7 +74,7 @@ the RPM information (e.g. package license). * Default: - :variable:`CPACK_DEBIAN_PACKAGE_DESCRIPTION` (this may be set already - for Debian packaging, so we may as well re-use it). + for Debian packaging, so it is used as a fallback). .. variable:: CPACK_FREEBSD_PACKAGE_WWW @@ -87,7 +87,7 @@ the RPM information (e.g. package license). - :variable:`CMAKE_PROJECT_HOMEPAGE_URL`, or if that is not set, :variable:`CPACK_DEBIAN_PACKAGE_HOMEPAGE` (this may be set already - for Debian packaging, so we may as well re-use it). + for Debian packaging, so it is used as a fallback). .. versionadded:: 3.12 The ``CMAKE_PROJECT_HOMEPAGE_URL`` variable. diff --git a/Help/cpack_gen/nsis.rst b/Help/cpack_gen/nsis.rst index de1f3b5fb7a..299cfece94f 100644 --- a/Help/cpack_gen/nsis.rst +++ b/Help/cpack_gen/nsis.rst @@ -3,8 +3,8 @@ CPack NSIS Generator CPack Nullsoft Scriptable Install System (NSIS) generator specific options. -.. versionchanged:: 3.17 - The NSIS generator requires NSIS 3.0 or newer. +.. versionchanged:: 3.22 + The NSIS generator requires NSIS 3.03 or newer. Variables specific to CPack NSIS generator ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -195,3 +195,15 @@ on Windows Nullsoft Scriptable Install System. If set, trim down the size of the control to the size of the branding text string. Allowed values for this variable are ``LEFT``, ``CENTER`` or ``RIGHT``. If not specified, the default behavior is ``LEFT``. + +.. variable:: CPACK_NSIS_EXECUTABLE + + .. versionadded:: 3.21 + + If set, specify the name of the NSIS executable. Default is ``makensis``. + +.. variable:: CPACK_NSIS_IGNORE_LICENSE_PAGE + + .. versionadded:: 3.22 + + If set, do not display the page containing the license during installation. diff --git a/Help/cpack_gen/rpm.rst b/Help/cpack_gen/rpm.rst index 5260a1d7c30..0d287fc9122 100644 --- a/Help/cpack_gen/rpm.rst +++ b/Help/cpack_gen/rpm.rst @@ -394,8 +394,10 @@ List of CPack RPM generator specific variables: * Mandatory : NO * Default : - - May be used to set weak RPM dependencies (suggests). Note that you must - enclose the complete requires string between quotes. + May be used to set weak RPM dependencies (suggests). If ``rpmbuild`` doesn't + support the ``Suggests`` tag, CPack will emit a warning and ignore this + variable. Note that you must enclose the complete requires string between + quotes. .. variable:: CPACK_RPM_PACKAGE_PROVIDES CPACK_RPM__PACKAGE_PROVIDES @@ -838,6 +840,10 @@ Debuginfo RPM packaging has its own set of variables: Binaries must contain debug symbols before packaging so use either ``Debug`` or ``RelWithDebInfo`` for :variable:`CMAKE_BUILD_TYPE` variable value. + Additionally, if :variable:`CPACK_STRIP_FILES` is set, the files will be stripped before + they get to the RPM generator, so will not contain debug symbols and + a debuginfo package will not get built. Do not use with :variable:`CPACK_STRIP_FILES`. + .. note:: Packages generated from packages without binary files, with binary files but @@ -1021,7 +1027,7 @@ Source RPM packaging has its own set of variables: * Mandatory : YES * Default : "/" -.. VARIABLE:: CPACK_RPM_BUILDREQUIRES +.. variable:: CPACK_RPM_BUILDREQUIRES List of source rpm build dependencies. @@ -1033,3 +1039,16 @@ Source RPM packaging has its own set of variables: example:: set(CPACK_RPM_BUILDREQUIRES "python >= 2.5.0, cmake >= 2.8") + +.. variable:: CPACK_RPM_REQUIRES_EXCLUDE_FROM + + .. versionadded:: 3.22 + + * Mandatory : NO + * Default : - + + May be used to keep the dependency generator from scanning specific files + or directories for dependencies. Note that you can use a regular + expression that matches all of the directories or files, for example:: + + set(CPACK_RPM_REQUIRES_EXCLUDE_FROM "bin/libqsqloci.*\\.so.*") diff --git a/Help/dev/documentation.rst b/Help/dev/documentation.rst index 29fc8803314..4a2a5d963af 100644 --- a/Help/dev/documentation.rst +++ b/Help/dev/documentation.rst @@ -92,6 +92,11 @@ literal block after ``::`` the referenced documents inline as part of the referencing document. +``versionadded``, ``versionchanged`` directives + Specify that something was added or changed by a named CMake version. + The command-line help processor prints the block content as if the lines + were normal paragraph text with interpretation. + Inline markup constructs not listed above are printed literally in the command-line help output. We prefer to use inline markup constructs that look correct in source form, so avoid use of \\-escapes in favor of inline diff --git a/Help/dev/experimental.rst b/Help/dev/experimental.rst index d0191615a36..2380de4b7f2 100644 --- a/Help/dev/experimental.rst +++ b/Help/dev/experimental.rst @@ -39,7 +39,7 @@ to the file specified by the ```` placeholder, and write module dependencies to the file specified by the ```` placeholder. The module dependencies should be written in the format described -by the `P1689r3`_ paper. +by the `P1689r4`_ paper. Compiler writers may try out their scanning functionality using the `cxx-modules-sandbox`_ test project, modified to set variables @@ -66,5 +66,5 @@ the GCC documentation, but the relevant section for the purposes of CMake is: -- GCC module mapper documentation .. _`D1483r1`: https://mathstuf.fedorapeople.org/fortran-modules/fortran-modules.html -.. _`P1689r3`: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2020/p1689r3.html +.. _`P1689r4`: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p1689r4.html .. _`cxx-modules-sandbox`: https://github.com/mathstuf/cxx-modules-sandbox diff --git a/Help/dev/maint.rst b/Help/dev/maint.rst index 664b7a409f6..54d627dd52d 100644 --- a/Help/dev/maint.rst +++ b/Help/dev/maint.rst @@ -245,12 +245,12 @@ Commit with a message such as:: Release versions do not have the development topic section of the CMake Release Notes index page. -Update ``.gitlab-ci.yml`` to drop the ``upload:`` jobs from the +Update ``.gitlab-ci.yml`` to drop the upload jobs from the packaging pipeline by renaming them to start in ``.``: .. code-block:: shell - sed -i 's/^upload:/.upload:/' .gitlab-ci.yml + sed -i 's/^u:/.u:/' .gitlab-ci.yml Commit with a message such as:: @@ -298,7 +298,7 @@ the version date from ``origin/master``: git checkout origin/master -- \ Source/CMakeVersion.cmake Help/release/dev/0-sample-topic.rst sed -i $'/^Releases/ i\\\n.. include:: dev.txt\\\n' Help/release/index.rst - sed -i 's/^\.upload:/upload:/' .gitlab-ci.yml + sed -i 's/^\.u:/u:/' .gitlab-ci.yml Update ``Source/CMakeVersion.cmake`` to set the version to ``$major.$minor.$date``: diff --git a/Help/dev/review.rst b/Help/dev/review.rst index 8326e701525..34796a1a33e 100644 --- a/Help/dev/review.rst +++ b/Help/dev/review.rst @@ -20,8 +20,10 @@ creating a *merge request* ("MR"). The new MR will appear on the process is managed by the merge request page for the change. During the review process, the MR submitter should address review comments -or test failures by updating the MR with a (force-)push of the topic -branch. The update initiates a new round of review. +or test failures by updating their local topic branch to fix their commits +(e.g. via ``git commit --amend`` or ``git rebase -i``), and then issuing a +(force-)push of the topic branch to their remote (e.g. ``git push --force``). +This will automatically initiate a new round of review on the existing MR. We recommend that users enable the "Remove source branch when merge request is accepted" option when creating the MR or by editing it. @@ -254,7 +256,8 @@ The preferred form for references to other commits is The author date of the commit, in its original time zone, formatted as ``CCYY-MM-DD``. ``git-log(1)`` shows the original time zone by default. -This may be generated with +This may be generated with ``git show -s --pretty=reference `` with +Git 2.25 and newer. Older versions of Git can generate the same format via ``git show -s --date=short --pretty="format:%h (%s, %ad)" ``. If the commit is a fix for the mentioned commit, consider using a ``Fixes:`` @@ -321,6 +324,19 @@ Heavier jobs require a manual trigger to run: * ``failed``: Restart jobs which have completed, but without success. * ``completed``: Restart all completed jobs. + +In order to keep job names shorter and keep as much information visible on the +GitLab web interface as possible, jobs have a short prefix which indicates +what its main purpose is: + + * ``b:`` jobs build CMake for the purposes of running the + test suite. + * ``l:`` jobs perform "linting" on the CMake source tree such as static + analysis. + * ``p:`` jobs perform preparatory tasks for use in other jobs. + * ``t:`` jobs perform testing of CMake. + * ``u:`` jobs upload other job results to permanent locations. + 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. diff --git a/Help/envvar/CMAKE_BUILD_TYPE.rst b/Help/envvar/CMAKE_BUILD_TYPE.rst new file mode 100644 index 00000000000..f798aff1fa4 --- /dev/null +++ b/Help/envvar/CMAKE_BUILD_TYPE.rst @@ -0,0 +1,10 @@ +CMAKE_BUILD_TYPE +---------------- + +.. versionadded:: 3.22 + +.. include:: ENV_VAR.txt + +The ``CMAKE_BUILD_TYPE`` environment variable specifies a default value +for the :variable:`CMAKE_BUILD_TYPE` variable when there is no explicit +configuration given on the first run while creating a new build tree. diff --git a/Help/envvar/CMAKE_CONFIGURATION_TYPES.rst b/Help/envvar/CMAKE_CONFIGURATION_TYPES.rst new file mode 100644 index 00000000000..833aa4a9fd1 --- /dev/null +++ b/Help/envvar/CMAKE_CONFIGURATION_TYPES.rst @@ -0,0 +1,11 @@ +CMAKE_CONFIGURATION_TYPES +------------------------- + +.. versionadded:: 3.22 + +.. include:: ENV_VAR.txt + +The ``CMAKE_CONFIGURATION_TYPES`` environment variable specifies a +default value for the :variable:`CMAKE_CONFIGURATION_TYPES` variable +when there is no explicit configuration given on the first run while +creating a new build tree. diff --git a/Help/envvar/CMAKE_INSTALL_MODE.rst b/Help/envvar/CMAKE_INSTALL_MODE.rst new file mode 100644 index 00000000000..4549ea1498a --- /dev/null +++ b/Help/envvar/CMAKE_INSTALL_MODE.rst @@ -0,0 +1,116 @@ +CMAKE_INSTALL_MODE +------------------ + +.. versionadded:: 3.22 + +.. include:: ENV_VAR.txt + +The ``CMAKE_INSTALL_MODE`` environment variable allows users to operate +CMake in an alternate mode of :command:`file(INSTALL)` and :command:`install()`. + +The default behavior for an installation is to copy a source file from a +source directory into a destination directory. This environment variable +however allows the user to override this behavior, causing CMake to create +symbolic links instead. + +Usage Scenarios +^^^^^^^^^^^^^^^ + +Installing symbolic links rather than copying files can help in the following +ways: + +* Conserving storage space because files do not have to be duplicated on disk. +* Changes to the source of the symbolic link are seen at the install + destination without having to re-run the install step. +* Editing through the link at the install destination will modify the source + of the link. This may be useful when dealing with CMake project hierarchies, + i.e. using :module:`ExternalProject` and consistent source navigation and + refactoring is desired across projects. + +Allowed Values +^^^^^^^^^^^^^^ + +The following values are allowed for ``CMAKE_INSTALL_MODE``: + +``COPY``, empty or unset + Duplicate the file at its destination. This is the default behavior. + +``ABS_SYMLINK`` + Create an *absolute* symbolic link to the source file at the destination. + Halt with an error if the link cannot be created. + +``ABS_SYMLINK_OR_COPY`` + Like ``ABS_SYMLINK`` but fall back to silently copying if the symlink + couldn't be created. + +``REL_SYMLINK`` + Create a *relative* symbolic link to the source file at the destination. + Halt with an error if the link cannot be created. + +``REL_SYMLINK_OR_COPY`` + Like ``REL_SYMLINK`` but fall back to silently copying if the symlink + couldn't be created. + +``SYMLINK`` + Try as if through ``REL_SYMLINK`` and fall back to ``ABS_SYMLINK`` if the + referenced file cannot be expressed using a relative path. + Halt with an error if the link cannot be created. + +``SYMLINK_OR_COPY`` + Like ``SYMLINK`` but fall back to silently copying if the symlink couldn't + be created. + +.. note:: + A symbolic link consists of a reference file path rather than contents of its + own, hence there are two ways to express the relation, either by a *relative* + or an *absolute* path. + +When To Set The Environment Variable +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For the environment variable to take effect, it must be set during the correct +build phase(s). + +* If the project calls :command:`file(INSTALL)` directly, the environment + variable must be set during the configuration phase. +* In order to apply to :command:`install()`, the environment variable must be + set during installation. This could be during a build if using the + ``install`` or ``package`` build targets, or separate from the build when + invoking an install or running :manual:`cpack ` from the command + line. +* When using :module:`ExternalProject`, it might be required during the build + phase, since the external project's own configure, build and install steps + will execute during the main project's build phase. + +Given the above, it is recommended to set the environment variable consistently +across all phases (configure, build and install). + +Caveats +^^^^^^^ + +Use this environment variable with caution. The following highlights some +points to be considered: + +* ``CMAKE_INSTALL_MODE`` only affects files, not directories. + +* Symbolic links are not available on all platforms. + +* The way this environment variable interacts with the install step of + :module:`ExternalProject` is more complex. For further details, see that + module's documentation. + +* A symbolic link ties the destination to the source in a persistent way. + Writing to either of the two affects both file system objects. + This is in contrast to normal install behavior which only copies files as + they were at the time the install was performed, with no enduring + relationship between the source and destination of the install. + +* Combining ``CMAKE_INSTALL_MODE`` with :prop_tgt:`IOS_INSTALL_COMBINED` is + not supported. + +* Changing ``CMAKE_INSTALL_MODE`` from what it was on a previous run can lead + to unexpected results. Moving from a non-symlinking mode to a symlinking + mode will discard any previous file at the destination, but the reverse is + not true. Once a symlink exists at the destination, even if you switch to a + non-symlink mode, the symlink will continue to exist at the destination and + will not be replaced by an actual file. diff --git a/Help/envvar/CMAKE_LANG_LINKER_LAUNCHER.rst b/Help/envvar/CMAKE_LANG_LINKER_LAUNCHER.rst new file mode 100644 index 00000000000..6251d9c75d0 --- /dev/null +++ b/Help/envvar/CMAKE_LANG_LINKER_LAUNCHER.rst @@ -0,0 +1,13 @@ +CMAKE__LINKER_LAUNCHER +---------------------------- + +.. versionadded:: 3.21 + +.. include:: ENV_VAR.txt + +Default launcher to use when linking a target of 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__LINKER_LAUNCHER` +variable is defined. diff --git a/Help/envvar/CMAKE_TOOLCHAIN_FILE.rst b/Help/envvar/CMAKE_TOOLCHAIN_FILE.rst new file mode 100644 index 00000000000..7ea9cea3572 --- /dev/null +++ b/Help/envvar/CMAKE_TOOLCHAIN_FILE.rst @@ -0,0 +1,12 @@ +CMAKE_TOOLCHAIN_FILE +-------------------- + +.. versionadded:: 3.21 + +.. include:: ENV_VAR.txt + +The ``CMAKE_TOOLCHAIN_FILE`` environment variable specifies a default value +for the :variable:`CMAKE_TOOLCHAIN_FILE` variable 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_TOOLCHAIN_FILE`. diff --git a/Help/envvar/CUDAHOSTCXX.rst b/Help/envvar/CUDAHOSTCXX.rst index 963f9d11301..cf65927a51c 100644 --- a/Help/envvar/CUDAHOSTCXX.rst +++ b/Help/envvar/CUDAHOSTCXX.rst @@ -15,6 +15,10 @@ ignored if the :variable:`CMAKE_CUDA_HOST_COMPILER` variable is defined. This environment variable is primarily meant for use with projects that enable ``CUDA`` as a first-class language. +.. note:: + + Ignored when using :ref:`Visual Studio Generators`. + .. versionadded:: 3.13 The :module:`FindCUDA` module will use this variable to initialize its ``CUDA_HOST_COMPILER`` setting. diff --git a/Help/envvar/HIPCXX.rst b/Help/envvar/HIPCXX.rst new file mode 100644 index 00000000000..23329e978cb --- /dev/null +++ b/Help/envvar/HIPCXX.rst @@ -0,0 +1,13 @@ +HIPCXX +------ + +.. versionadded:: 3.21 + +.. include:: ENV_VAR.txt + +Preferred executable for compiling ``HIP`` language files. Will only be used by +CMake on the first configuration to determine ``HIP`` compiler, after which the +value for ``HIP`` is stored in the cache as +:variable:`CMAKE_HIP_COMPILER _COMPILER>`. For any configuration +run (including the first), the environment variable will be ignored if the +:variable:`CMAKE_HIP_COMPILER _COMPILER>` variable is defined. diff --git a/Help/envvar/HIPFLAGS.rst b/Help/envvar/HIPFLAGS.rst new file mode 100644 index 00000000000..0df3416e281 --- /dev/null +++ b/Help/envvar/HIPFLAGS.rst @@ -0,0 +1,15 @@ +HIPFLAGS +-------- + +.. versionadded:: 3.21 + +.. include:: ENV_VAR.txt + +Default compilation flags to be used when compiling ``HIP`` files. Will only be +used by CMake on the first configuration to determine ``HIP`` default +compilation flags, after which the value for ``HIPFLAGS`` is stored in the +cache as :variable:`CMAKE_HIP_FLAGS _FLAGS>`. For any configuration +run (including the first), the environment variable will be ignored if +the :variable:`CMAKE_HIP_FLAGS _FLAGS>` variable is defined. + +See also :variable:`CMAKE_HIP_FLAGS_INIT _FLAGS_INIT>`. diff --git a/Help/generator/Ninja Multi-Config.rst b/Help/generator/Ninja Multi-Config.rst index 89011925f8f..e5ce4f5cd41 100644 --- a/Help/generator/Ninja Multi-Config.rst +++ b/Help/generator/Ninja Multi-Config.rst @@ -34,7 +34,9 @@ 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. + Specifies the total set of configurations to build. Unlike with other + multi-config generators, this variable has a value of + ``Debug;Release;RelWithDebInfo`` by default. :variable:`CMAKE_CROSS_CONFIGS` Specifies a :ref:`semicolon-separated list ` of diff --git a/Help/generator/VS_TOOLSET_HOST_ARCH.txt b/Help/generator/VS_TOOLSET_HOST_ARCH.txt index e3617199904..029363115b6 100644 --- a/Help/generator/VS_TOOLSET_HOST_ARCH.txt +++ b/Help/generator/VS_TOOLSET_HOST_ARCH.txt @@ -1,11 +1,7 @@ -.. versionadded:: 3.8 - For each toolset that comes with this version of Visual Studio, there are - variants that are themselves compiled for 32-bit (``x86``) and - 64-bit (``x64``) hosts (independent of the architecture they target). - |VS_TOOLSET_HOST_ARCH_DEFAULT| - One may explicitly request use of either the 32-bit or 64-bit host tools - by adding either ``host=x86`` or ``host=x64`` to the toolset specification. - See the :variable:`CMAKE_GENERATOR_TOOLSET` variable for details. - -.. versionadded:: 3.14 - Added suport for ``host=x86`` option. +For each toolset that comes with this version of Visual Studio, there are +variants that are themselves compiled for 32-bit (``x86``) and +64-bit (``x64``) hosts (independent of the architecture they target). +|VS_TOOLSET_HOST_ARCH_DEFAULT| +One may explicitly request use of either the 32-bit or 64-bit host tools +by adding either ``host=x86`` or ``host=x64`` to the toolset specification. +See the :variable:`CMAKE_GENERATOR_TOOLSET` variable for details. diff --git a/Help/generator/VS_TOOLSET_HOST_ARCH_LEGACY.txt b/Help/generator/VS_TOOLSET_HOST_ARCH_LEGACY.txt new file mode 100644 index 00000000000..069638bd2de --- /dev/null +++ b/Help/generator/VS_TOOLSET_HOST_ARCH_LEGACY.txt @@ -0,0 +1,11 @@ +.. versionadded:: 3.8 + For each toolset that comes with this version of Visual Studio, there are + variants that are themselves compiled for 32-bit (``x86``) and + 64-bit (``x64``) hosts (independent of the architecture they target). + |VS_TOOLSET_HOST_ARCH_DEFAULT| + One may explicitly request use of either the 32-bit or 64-bit host tools + by adding either ``host=x86`` or ``host=x64`` to the toolset specification. + See the :variable:`CMAKE_GENERATOR_TOOLSET` variable for details. + +.. versionadded:: 3.14 + Added support for ``host=x86`` option. diff --git a/Help/generator/Visual Studio 10 2010.rst b/Help/generator/Visual Studio 10 2010.rst index b4376d88bd5..9ec33c3549e 100644 --- a/Help/generator/Visual Studio 10 2010.rst +++ b/Help/generator/Visual Studio 10 2010.rst @@ -1,7 +1,14 @@ Visual Studio 10 2010 --------------------- -Generates Visual Studio 10 (VS 2010) project files. +Deprecated. Generates Visual Studio 10 (VS 2010) project files. + +.. note:: + This generator is deprecated and will be removed in a future version + of CMake. It will still be possible to build with VS 10 2010 tools + using the :generator:`Visual Studio 11 2012` (or above) generator + with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v100``, or by + using the :generator:`NMake Makefiles` generator. For compatibility with CMake versions prior to 3.0, one may specify this generator using the name ``Visual Studio 10`` without the year component. @@ -9,8 +16,9 @@ generator using the name ``Visual Studio 10`` without the year component. Project Types ^^^^^^^^^^^^^ -Only Visual C++ and C# projects may be generated. Other types of -projects (Database, Website, etc.) are not supported. +Only Visual C++ and C# projects may be generated (and Fortran with +Intel compiler integration). Other types of projects (Database, +Website, etc.) are not supported. Platform Selection ^^^^^^^^^^^^^^^^^^ diff --git a/Help/generator/Visual Studio 11 2012.rst b/Help/generator/Visual Studio 11 2012.rst index 932548bd2a7..3952228fe90 100644 --- a/Help/generator/Visual Studio 11 2012.rst +++ b/Help/generator/Visual Studio 11 2012.rst @@ -9,8 +9,9 @@ generator using the name "Visual Studio 11" without the year component. Project Types ^^^^^^^^^^^^^ -Only Visual C++ and C# projects may be generated. Other types of -projects (JavaScript, Database, Website, etc.) are not supported. +Only Visual C++ and C# projects may be generated (and Fortran with +Intel compiler integration). Other types of projects (JavaScript, +Database, Website, etc.) are not supported. Platform Selection ^^^^^^^^^^^^^^^^^^ diff --git a/Help/generator/Visual Studio 12 2013.rst b/Help/generator/Visual Studio 12 2013.rst index b5fa1bf490a..54a4d7eb9f3 100644 --- a/Help/generator/Visual Studio 12 2013.rst +++ b/Help/generator/Visual Studio 12 2013.rst @@ -9,8 +9,9 @@ generator using the name "Visual Studio 12" without the year component. Project Types ^^^^^^^^^^^^^ -Only Visual C++ and C# projects may be generated. Other types of -projects (JavaScript, Powershell, Python, etc.) are not supported. +Only Visual C++ and C# projects may be generated (and Fortran with +Intel compiler integration). Other types of projects (JavaScript, +Powershell, Python, etc.) are not supported. Platform Selection ^^^^^^^^^^^^^^^^^^ @@ -46,4 +47,4 @@ via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. .. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace:: By default this generator uses the 32-bit variant even on a 64-bit host. -.. include:: VS_TOOLSET_HOST_ARCH.txt +.. include:: VS_TOOLSET_HOST_ARCH_LEGACY.txt diff --git a/Help/generator/Visual Studio 14 2015.rst b/Help/generator/Visual Studio 14 2015.rst index 9c616414f05..d704ab271e8 100644 --- a/Help/generator/Visual Studio 14 2015.rst +++ b/Help/generator/Visual Studio 14 2015.rst @@ -8,8 +8,9 @@ Generates Visual Studio 14 (VS 2015) project files. Project Types ^^^^^^^^^^^^^ -Only Visual C++ and C# projects may be generated. Other types of -projects (JavaScript, Powershell, Python, etc.) are not supported. +Only Visual C++ and C# projects may be generated (and Fortran with +Intel compiler integration). Other types of projects (JavaScript, +Powershell, Python, etc.) are not supported. Platform Selection ^^^^^^^^^^^^^^^^^^ @@ -44,7 +45,7 @@ via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. .. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace:: By default this generator uses the 32-bit variant even on a 64-bit host. -.. include:: VS_TOOLSET_HOST_ARCH.txt +.. include:: VS_TOOLSET_HOST_ARCH_LEGACY.txt .. _`Windows 10 SDK Maximum Version for VS 2015`: diff --git a/Help/generator/Visual Studio 15 2017.rst b/Help/generator/Visual Studio 15 2017.rst index a002f2ff6d6..b4d6f6d9f68 100644 --- a/Help/generator/Visual Studio 15 2017.rst +++ b/Help/generator/Visual Studio 15 2017.rst @@ -8,26 +8,27 @@ Generates Visual Studio 15 (VS 2017) project files. Project Types ^^^^^^^^^^^^^ -Only Visual C++ and C# projects may be generated. Other types of -projects (JavaScript, Powershell, Python, etc.) are not supported. +Only Visual C++ and C# projects may be generated (and Fortran with +Intel compiler integration). Other types of projects (JavaScript, +Powershell, Python, etc.) are not supported. Instance Selection ^^^^^^^^^^^^^^^^^^ -.. versionadded:: 3.9 - VS 2017 supports multiple installations on the same machine. - The :variable:`CMAKE_GENERATOR_INSTANCE` variable may be set as a - cache entry containing the absolute path to a Visual Studio instance. - If the value is not specified explicitly by the user or a toolchain file, - CMake queries the Visual Studio Installer to locate VS instances, chooses - one, and sets the variable as a cache entry to hold the value persistently. - .. versionadded:: 3.11 - When CMake first chooses an instance, if the ``VS150COMNTOOLS`` environment - variable is set and points to the ``Common7/Tools`` directory within - one of the instances, that instance will be used. Otherwise, if more - than one instance is installed we do not define which one is chosen - by default. + +VS 2017 supports multiple installations on the same machine. +The :variable:`CMAKE_GENERATOR_INSTANCE` variable may be set as a +cache entry containing the absolute path to a Visual Studio instance. +If the value is not specified explicitly by the user or a toolchain file, +CMake queries the Visual Studio Installer to locate VS instances, chooses +one, and sets the variable as a cache entry to hold the value persistently. + +When CMake first chooses an instance, if the ``VS150COMNTOOLS`` environment +variable is set and points to the ``Common7/Tools`` directory within +one of the instances, that instance will be used. Otherwise, if more +than one instance is installed we do not define which one is chosen +by default. Platform Selection ^^^^^^^^^^^^^^^^^^ @@ -63,4 +64,4 @@ via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. .. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace:: By default this generator uses the 32-bit variant even on a 64-bit host. -.. include:: VS_TOOLSET_HOST_ARCH.txt +.. include:: VS_TOOLSET_HOST_ARCH_LEGACY.txt diff --git a/Help/generator/Visual Studio 16 2019.rst b/Help/generator/Visual Studio 16 2019.rst index 3da80915adb..72399e0a25a 100644 --- a/Help/generator/Visual Studio 16 2019.rst +++ b/Help/generator/Visual Studio 16 2019.rst @@ -8,8 +8,9 @@ Generates Visual Studio 16 (VS 2019) project files. Project Types ^^^^^^^^^^^^^ -Only Visual C++ and C# projects may be generated. Other types of -projects (JavaScript, Powershell, Python, etc.) are not supported. +Only Visual C++ and C# projects may be generated (and Fortran with +Intel compiler integration). Other types of projects (JavaScript, +Powershell, Python, etc.) are not supported. Instance Selection ^^^^^^^^^^^^^^^^^^ diff --git a/Help/generator/Visual Studio 17 2022.rst b/Help/generator/Visual Studio 17 2022.rst new file mode 100644 index 00000000000..b3f49f3dfad --- /dev/null +++ b/Help/generator/Visual Studio 17 2022.rst @@ -0,0 +1,57 @@ +Visual Studio 17 2022 +--------------------- + +.. versionadded:: 3.21 + +Generates Visual Studio 17 (VS 2022) project files. + +Project Types +^^^^^^^^^^^^^ + +Only Visual C++ and C# projects may be generated (and Fortran with +Intel compiler integration). Other types of projects (JavaScript, +Powershell, Python, etc.) are not supported. + +Instance Selection +^^^^^^^^^^^^^^^^^^ + +VS 2022 supports multiple installations on the same machine. +The :variable:`CMAKE_GENERATOR_INSTANCE` variable may be set as a +cache entry containing the absolute path to a Visual Studio instance. +If the value is not specified explicitly by the user or a toolchain file, +CMake queries the Visual Studio Installer to locate VS instances, chooses +one, and sets the variable as a cache entry to hold the value persistently. + +When CMake first chooses an instance, if the ``VS170COMNTOOLS`` environment +variable is set and points to the ``Common7/Tools`` directory within +one of the instances, that instance will be used. Otherwise, if more +than one instance is installed we do not define which one is chosen +by default. + +Platform Selection +^^^^^^^^^^^^^^^^^^ + +The default target platform name (architecture) is that of the host +and is provided in the :variable:`CMAKE_VS_PLATFORM_NAME_DEFAULT` variable. + +The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps +via the :manual:`cmake(1)` ``-A`` option, to specify a target platform +name (architecture). For example: + +* ``cmake -G "Visual Studio 17 2022" -A Win32`` +* ``cmake -G "Visual Studio 17 2022" -A x64`` +* ``cmake -G "Visual Studio 17 2022" -A ARM`` +* ``cmake -G "Visual Studio 17 2022" -A ARM64`` + +Toolset Selection +^^^^^^^^^^^^^^^^^ + +The ``v143`` toolset that comes with VS 17 2022 is selected by default. +The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps +via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. + +.. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace:: + By default this generator uses the 64-bit variant on x64 hosts and + the 32-bit variant otherwise. + +.. include:: VS_TOOLSET_HOST_ARCH.txt diff --git a/Help/guide/ide-integration/index.rst b/Help/guide/ide-integration/index.rst index addf93215cb..779883b9622 100644 --- a/Help/guide/ide-integration/index.rst +++ b/Help/guide/ide-integration/index.rst @@ -69,9 +69,9 @@ While reading, parsing, and evaluating the contents of ``CMakePresets.json`` is straightforward, it is not trivial. In addition to the documentation, IDE vendors may also wish to refer to the CMake source code and test cases for a better understanding of how to implement the format. -:download:`This file ` provides a machine-readable -JSON schema for the ``CMakePresets.json`` format that IDE vendors may find -useful for validation and providing editing assistance. +:download:`This file <../../manual/presets/schema.json>` provides a +machine-readable JSON schema for the ``CMakePresets.json`` format that IDE +vendors may find useful for validation and providing editing assistance. Configuring =========== diff --git a/Help/guide/importing-exporting/MathFunctions/CMakeLists.txt b/Help/guide/importing-exporting/MathFunctions/CMakeLists.txt index 9a9e40ee23c..d277b541904 100644 --- a/Help/guide/importing-exporting/MathFunctions/CMakeLists.txt +++ b/Help/guide/importing-exporting/MathFunctions/CMakeLists.txt @@ -1,6 +1,9 @@ cmake_minimum_required(VERSION 3.15) project(MathFunctions) +# make cache variables for install destinations +include(GNUInstallDirs) + # specify the C++ standard set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED True) @@ -12,26 +15,26 @@ add_library(MathFunctions STATIC MathFunctions.cxx) target_include_directories(MathFunctions PUBLIC "$" - "$" + "$" ) # install the target and create export-set install(TARGETS MathFunctions EXPORT MathFunctionsTargets - LIBRARY DESTINATION lib - ARCHIVE DESTINATION lib - RUNTIME DESTINATION bin - INCLUDES DESTINATION include + LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} + ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR} + RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} + INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR} ) # install header file -install(FILES MathFunctions.h DESTINATION include) +install(FILES MathFunctions.h DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}) # generate and install export file install(EXPORT MathFunctionsTargets FILE MathFunctionsTargets.cmake NAMESPACE MathFunctions:: - DESTINATION lib/cmake/MathFunctions + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions ) # include CMakePackageConfigHelpers macro @@ -58,14 +61,14 @@ write_basic_package_version_file( # create config file configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake" - INSTALL_DESTINATION lib/cmake/MathFunctions + INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions ) # install config files install(FILES "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake" "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake" - DESTINATION lib/cmake/MathFunctions + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions ) # generate the export targets for the build tree diff --git a/Help/guide/importing-exporting/MathFunctionsComponents/Addition/CMakeLists.txt b/Help/guide/importing-exporting/MathFunctionsComponents/Addition/CMakeLists.txt index 17ad95210b4..9de935eea97 100644 --- a/Help/guide/importing-exporting/MathFunctionsComponents/Addition/CMakeLists.txt +++ b/Help/guide/importing-exporting/MathFunctionsComponents/Addition/CMakeLists.txt @@ -7,24 +7,24 @@ add_library(MathFunctions::Addition ALIAS Addition) target_include_directories(Addition PUBLIC "$" - $ + $ ) # install the target and create export-set install(TARGETS Addition EXPORT AdditionTargets - LIBRARY DESTINATION lib - ARCHIVE DESTINATION lib - RUNTIME DESTINATION bin - INCLUDES DESTINATION include + LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} + ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR} + RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} + INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR} ) # install header file -install(FILES Addition.h DESTINATION include) +install(FILES Addition.h DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}) # generate and install export file install(EXPORT AdditionTargets FILE MathFunctionsAdditionTargets.cmake NAMESPACE MathFunctions:: - DESTINATION lib/cmake/MathFunctions + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions ) diff --git a/Help/guide/importing-exporting/MathFunctionsComponents/CMakeLists.txt b/Help/guide/importing-exporting/MathFunctionsComponents/CMakeLists.txt index fd95e28df03..90ee89f0f67 100644 --- a/Help/guide/importing-exporting/MathFunctionsComponents/CMakeLists.txt +++ b/Help/guide/importing-exporting/MathFunctionsComponents/CMakeLists.txt @@ -1,6 +1,9 @@ cmake_minimum_required(VERSION 3.15) project(MathFunctionsComponents) +# make cache variables for install destinations +include(GNUInstallDirs) + # specify the C++ standard set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED True) @@ -24,7 +27,7 @@ write_basic_package_version_file( # create config file configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake" - INSTALL_DESTINATION lib/cmake/MathFunctions + INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions NO_CHECK_REQUIRED_COMPONENTS_MACRO ) @@ -32,5 +35,5 @@ configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in install(FILES "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake" "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake" - DESTINATION lib/cmake/MathFunctions + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions ) diff --git a/Help/guide/importing-exporting/MathFunctionsComponents/SquareRoot/CMakeLists.txt b/Help/guide/importing-exporting/MathFunctionsComponents/SquareRoot/CMakeLists.txt index be5ae65d1cf..517c5e26a90 100644 --- a/Help/guide/importing-exporting/MathFunctionsComponents/SquareRoot/CMakeLists.txt +++ b/Help/guide/importing-exporting/MathFunctionsComponents/SquareRoot/CMakeLists.txt @@ -7,24 +7,24 @@ add_library(MathFunctions::SquareRoot ALIAS SquareRoot) target_include_directories(SquareRoot PUBLIC "$" - "$" + "$" ) # install the target and create export-set install(TARGETS SquareRoot EXPORT SquareRootTargets - LIBRARY DESTINATION lib - ARCHIVE DESTINATION lib - RUNTIME DESTINATION bin - INCLUDES DESTINATION include + LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} + ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR} + RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} + INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR} ) # install header file -install(FILES SquareRoot.h DESTINATION include) +install(FILES SquareRoot.h DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}) # generate and install export file install(EXPORT SquareRootTargets FILE MathFunctionsSquareRootTargets.cmake NAMESPACE MathFunctions:: - DESTINATION lib/cmake/MathFunctions + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions ) diff --git a/Help/guide/importing-exporting/index.rst b/Help/guide/importing-exporting/index.rst index 2e6e06da4ed..dd3efb8bb9c 100644 --- a/Help/guide/importing-exporting/index.rst +++ b/Help/guide/importing-exporting/index.rst @@ -202,6 +202,10 @@ project. Start by specifying the :command:`cmake_minimum_required` version and :language: cmake :end-before: # create library +The :module:`GNUInstallDirs` module is included in order to provide the +project with the flexibility to install into different platform layouts by +making the directories available as cache variables. + Create a library called ``MathFunctions`` with the :command:`add_library` command: @@ -636,7 +640,7 @@ We can use the :command:`find_package` command: :start-after: # find MathFunctions :end-before: # create executable -Create an exectuable: +Create an executable: .. literalinclude:: Downstream/CMakeLists.txt :language: cmake diff --git a/Help/guide/tutorial/A Basic Starting Point.rst b/Help/guide/tutorial/A Basic Starting Point.rst new file mode 100644 index 00000000000..cf1ec018603 --- /dev/null +++ b/Help/guide/tutorial/A Basic Starting Point.rst @@ -0,0 +1,175 @@ +Step 1: A Basic Starting Point +============================== + +The most basic project is an executable built from source code files. +For simple projects, a three line ``CMakeLists.txt`` file is all that is +required. This will be the starting point for our tutorial. Create a +``CMakeLists.txt`` file in the ``Step1`` directory that looks like: + +.. code-block:: cmake + :caption: CMakeLists.txt + :name: CMakeLists.txt-start + + cmake_minimum_required(VERSION 3.10) + + # set the project name + project(Tutorial) + + # add the executable + add_executable(Tutorial tutorial.cxx) + + +Note that this example uses lower case commands in the ``CMakeLists.txt`` file. +Upper, lower, and mixed case commands are supported by CMake. The source +code for ``tutorial.cxx`` is provided in the ``Step1`` directory and can be +used to compute the square root of a number. + +Build and Run +------------- + +That's all that is needed - we can build and run our project now! First, run +the :manual:`cmake ` executable or the +:manual:`cmake-gui ` to configure the project and then build it +with your chosen build tool. + +For example, from the command line we could navigate to the +``Help/guide/tutorial`` directory of the CMake source code tree and create a +build directory: + +.. code-block:: console + + mkdir Step1_build + +Next, navigate to the build directory and run CMake to configure the project +and generate a native build system: + +.. code-block:: console + + cd Step1_build + cmake ../Step1 + +Then call that build system to actually compile/link the project: + +.. code-block:: console + + cmake --build . + +Finally, try to use the newly built ``Tutorial`` with these commands: + +.. code-block:: console + + Tutorial 4294967296 + Tutorial 10 + Tutorial + + +Adding a Version Number and Configured Header File +-------------------------------------------------- + +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 use the :command:`project` command +to set the project name and version number. + +.. literalinclude:: Step2/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-project-VERSION + :language: cmake + :end-before: # specify the C++ standard + +Then, configure a header file to pass the version number to the source +code: + +.. literalinclude:: Step2/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-configure_file + :language: cmake + :start-after: # to the source code + :end-before: # add the executable + +Since the configured file will be written into the binary tree, we +must add that directory to the list of paths to search for include +files. Add the following lines to the end of the ``CMakeLists.txt`` file: + +.. literalinclude:: Step2/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-target_include_directories + :language: cmake + :start-after: # so that we will find TutorialConfig.h + +Using your favorite editor, create ``TutorialConfig.h.in`` in the source +directory with the following contents: + +.. literalinclude:: Step2/TutorialConfig.h.in + :caption: TutorialConfig.h.in + :name: TutorialConfig.h.in + :language: c++ + +When CMake configures this header file the values for +``@Tutorial_VERSION_MAJOR@`` and ``@Tutorial_VERSION_MINOR@`` will be +replaced. + +Next modify ``tutorial.cxx`` to include the configured header file, +``TutorialConfig.h``. + +Finally, let's print out the executable name and version number by updating +``tutorial.cxx`` as follows: + +.. literalinclude:: Step2/tutorial.cxx + :caption: tutorial.cxx + :name: tutorial.cxx-print-version + :language: c++ + :start-after: { + :end-before: // convert input to double + +Specify the C++ Standard +------------------------- + +Next let's add some C++11 features to our project by replacing ``atof`` with +``std::stod`` in ``tutorial.cxx``. At the same time, remove +``#include ``. + +.. literalinclude:: Step2/tutorial.cxx + :caption: tutorial.cxx + :name: tutorial.cxx-cxx11 + :language: c++ + :start-after: // convert input to double + :end-before: // calculate square root + +We will need to explicitly state in the CMake code that it should use the +correct flags. The easiest way to enable support for a specific C++ standard +in CMake is by using the :variable:`CMAKE_CXX_STANDARD` variable. For this +tutorial, set the :variable:`CMAKE_CXX_STANDARD` variable in the +``CMakeLists.txt`` file to ``11`` and :variable:`CMAKE_CXX_STANDARD_REQUIRED` +to ``True``. Make sure to add the ``CMAKE_CXX_STANDARD`` declarations above the +call to ``add_executable``. + +.. literalinclude:: Step2/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-CXX_STANDARD + :language: cmake + :end-before: # configure a header file to pass some of the CMake settings + +Rebuild +------- + +Let's build our project again. We already created a build directory and ran +CMake, so we can skip to the build step: + +.. code-block:: console + + cd Step1_build + cmake --build . + +Now we can try to use the newly built ``Tutorial`` with same commands as before: + +.. code-block:: console + + Tutorial 4294967296 + Tutorial 10 + Tutorial + +Check that the version number is now reported when running the executable without +any arguments. diff --git a/Help/guide/tutorial/Adding Export Configuration.rst b/Help/guide/tutorial/Adding Export Configuration.rst new file mode 100644 index 00000000000..3bd6d64642b --- /dev/null +++ b/Help/guide/tutorial/Adding Export Configuration.rst @@ -0,0 +1,140 @@ +Step 11: Adding Export Configuration +==================================== + +During :guide:`tutorial/Installing and Testing` of the tutorial we added the +ability for CMake to install the library and headers of the project. During +:guide:`tutorial/Packaging an Installer` we added the ability to package up +this information so it could be distributed to other people. + +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 :command:`install(TARGETS)` commands to not +only specify a ``DESTINATION`` but also an ``EXPORT``. The ``EXPORT`` keyword +generates 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: + +.. literalinclude:: Complete/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-install-TARGETS-EXPORT + :language: cmake + :start-after: # install rules + +Now that we have ``MathFunctions`` being exported, we also need to explicitly +install the generated ``MathFunctionsTargets.cmake`` file. This is done by +adding the following to the bottom of the top-level ``CMakeLists.txt``: + +.. literalinclude:: Complete/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-install-EXPORT + :language: cmake + :start-after: # install the configuration targets + :end-before: include(CMakePackageConfigHelpers) + +At this point you should try and run CMake. If everything is setup properly +you will see that CMake will generate an error that looks like: + +.. code-block:: console + + Target "MathFunctions" INTERFACE_INCLUDE_DIRECTORIES property contains + path: + + "/Users/robert/Documents/CMakeClass/Tutorial/Step11/MathFunctions" + + which is prefixed in the source directory. + +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`` :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 +:command:`target_include_directories` call for ``MathFunctions`` to look like: + +.. literalinclude:: Step12/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-target_include_directories + :language: cmake + :start-after: # to find MathFunctions.h, while we don't. + :end-before: # should we use our own math functions + +Once this has been updated, we can re-run CMake and verify that it doesn't +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 :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:: Step12/Config.cmake.in + :caption: Config.cmake.in + :name: Config.cmake.in + +Then, to properly configure and install that file, add the following to the +bottom of the top-level ``CMakeLists.txt``: + +.. literalinclude:: Step12/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-install-Config.cmake + :language: cmake + :start-after: # install the configuration targets + :end-before: # generate the config file + + +Next, we execute the :command:`configure_package_config_file`. This command +will configure a provided file but with a few specific differences from the +standard :command:`configure_file` way. +To properly utilize this function, the input file should have a single line +with the text ``@PACKAGE_INIT@`` in addition to the content that is desired. +That variable will be replaced with a block of code which turns set values into +relative paths. These values which are new can be referenced by the same name +but prepended with a ``PACKAGE_`` prefix. + +.. literalinclude:: Step12/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-configure-package-config.cmake + :language: cmake + :start-after: # install the configuration targets + :end-before: # generate the version file + +The :command:`write_basic_package_version_file` is next. This command writes +a file which is used by the "find_package" document the version and +compatibility of the desired package. Here, we use the ``Tutorial_VERSION_*`` +variables and say that it is compatible with ``AnyNewerVersion``, which +denotes that this version or any higher one are compatible with the requested +version. + +.. literalinclude:: Step12/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-basic-version-file.cmake + :language: cmake + :start-after: # generate the version file + :end-before: # install the generated configuration files + +Finally, set both generated files to be installed: + +.. literalinclude:: Step12/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-install-configured-files.cmake + :language: cmake + :start-after: # install the generated configuration files + :end-before: # generate the export + +At this point, we have generated a relocatable CMake Configuration for our +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:: Step12/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-export + :language: cmake + :start-after: # needs to be after the install(TARGETS ) command + +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. diff --git a/Help/guide/tutorial/Adding Generator Expressions.rst b/Help/guide/tutorial/Adding Generator Expressions.rst new file mode 100644 index 00000000000..7fcc97fcc25 --- /dev/null +++ b/Help/guide/tutorial/Adding Generator Expressions.rst @@ -0,0 +1,84 @@ +Step 10: Adding Generator Expressions +===================================== + +:manual:`Generator expressions ` are evaluated +during build system generation to produce information specific to each build +configuration. + +:manual:`Generator expressions ` 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. + +:manual:`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. + +There are different types of +:manual:`generator expressions ` 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 +:manual:`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. Let's 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: + +.. literalinclude:: Step10/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-CXX_STANDARD-variable-remove + :language: cmake + :start-after: project(Tutorial VERSION 1.0) + :end-before: # control where the static and shared libraries are built so that on windows + +Would be replaced with: + +.. literalinclude:: Step11/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-cxx_std-feature + :language: cmake + :start-after: project(Tutorial VERSION 1.0) + :end-before: # add compiler warning flags just when building this project via + +**Note**: This upcoming section will require a change to the +:command:`cmake_minimum_required` usage in the code. The Generator Expression +that is about to be used was introduced in `3.15`. Update the call to require +that more recent version: + +.. code-block:: cmake + :caption: CMakeLists.txt + :name: CMakeLists.txt-version-update + + cmake_minimum_required(VERSION 3.15) + +Next we add the desired compiler warning flags that we want for our project. As +warning flags vary based on the compiler we use the ``COMPILE_LANG_AND_ID`` +generator expression to control which flags to apply given a language and a set +of compiler ids as seen below: + +.. literalinclude:: Step11/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-target_compile_options-genex + :language: cmake + :start-after: # the BUILD_INTERFACE genex + :end-before: # control where the static and shared libraries are built so that on windows + +Looking at this we see that the warning flags are encapsulated inside a +``BUILD_INTERFACE`` condition. This is done so that consumers of our installed +project will not inherit our warning flags. + +**Exercise**: Modify ``MathFunctions/CMakeLists.txt`` so that all targets have +a :command:`target_link_libraries` call to ``tutorial_compiler_flags``. diff --git a/Help/guide/tutorial/Adding Support for a Testing Dashboard.rst b/Help/guide/tutorial/Adding Support for a Testing Dashboard.rst new file mode 100644 index 00000000000..c6e0fd0b3b4 --- /dev/null +++ b/Help/guide/tutorial/Adding Support for a Testing Dashboard.rst @@ -0,0 +1,75 @@ +Step 8: Adding Support for a Testing Dashboard +============================================== + +Adding support for submitting our test results to a dashboard is simple. We +already defined a number of tests for our project in +:ref:`Testing Support `. Now we just have to run +those tests and submit them to a dashboard. To include support for dashboards +we include the :module:`CTest` module in our top-level ``CMakeLists.txt``. + +Replace: + +.. code-block:: cmake + :caption: CMakeLists.txt + :name: CMakeLists.txt-enable_testing-remove + + # enable testing + enable_testing() + +With: + +.. code-block:: cmake + :caption: CMakeLists.txt + :name: CMakeLists.txt-include-CTest + + # enable dashboard scripting + include(CTest) + +The :module:`CTest` module will automatically call ``enable_testing()``, so we +can remove it from our CMake files. + +We will also need to acquire a ``CTestConfig.cmake`` file to be placed in the +top-level directory where we can specify information to CTest about the +project. It contains: + +* The project name + +* The project "Nightly" start time + + * The time when a 24 hour "day" starts for this project. + +* The URL of the CDash instance where the submission's generated documents + will be sent + +One has been provided for you in this directory. It would normally be +downloaded from the ``Settings`` page of the project on the CDash +instance that will host and display the test results. Once downloaded from +CDash, the file should not be modified locally. + +.. literalinclude:: Step9/CTestConfig.cmake + :caption: CTestConfig.cmake + :name: CTestConfig.cmake + :language: cmake + +The :manual:`ctest ` executable will read in this file when it runs. +To create a simple dashboard you can run the :manual:`cmake ` +executable or the :manual:`cmake-gui ` to configure the project, +but do not build it yet. Instead, change directory to the binary tree, and then +run: + +.. code-block:: console + + ctest [-VV] -D Experimental + +Remember, for multi-config generators (e.g. Visual Studio), the configuration +type must be specified: + +.. code-block:: console + + ctest [-VV] -C Debug -D Experimental + +Or, from an IDE, build the ``Experimental`` target. + +The :manual:`ctest ` executable will build and test the project and +submit the results to Kitware's public dashboard: +https://my.cdash.org/index.php?project=CMakeTutorial. diff --git a/Help/guide/tutorial/Adding System Introspection.rst b/Help/guide/tutorial/Adding System Introspection.rst new file mode 100644 index 00000000000..e149110084b --- /dev/null +++ b/Help/guide/tutorial/Adding System Introspection.rst @@ -0,0 +1,61 @@ +Step 5: Adding System Introspection +=================================== + +Let us consider adding some code to our project that depends on features the +target platform may not have. For this example, we will add some code that +depends on whether or not the target platform has the ``log`` and ``exp`` +functions. Of course almost every platform has these functions but for this +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 :module:`CheckSymbolExists` module in +``MathFunctions/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. + +Add the checks for ``log`` and ``exp`` to ``MathFunctions/CMakeLists.txt``, +after the call to :command:`target_include_directories`: + +.. literalinclude:: Step6/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-check_symbol_exists + :language: cmake + :start-after: # to find MathFunctions.h, while we don't. + :end-before: # add compile definitions + +If available, use :command:`target_compile_definitions` to specify +``HAVE_LOG`` and ``HAVE_EXP`` as ``PRIVATE`` compile definitions. + +.. literalinclude:: Step6/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-target_compile_definitions + :language: cmake + :start-after: # add compile definitions + :end-before: # install rules + +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 + :caption: MathFunctions/mysqrt.cxx + :name: MathFunctions/mysqrt.cxx-ifdef + :language: c++ + :start-after: // if we have both log and exp then use them + :end-before: // do ten iterations + +We will also need to modify ``mysqrt.cxx`` to include ``cmath``. + +.. literalinclude:: Step6/MathFunctions/mysqrt.cxx + :caption: MathFunctions/mysqrt.cxx + :name: MathFunctions/mysqrt.cxx-include-cmath + :language: c++ + :end-before: #include + +Run the :manual:`cmake ` executable or the +:manual:`cmake-gui ` to configure the project and then build it +with your chosen build tool and run the Tutorial executable. + +Which function gives better results now, ``sqrt`` or ``mysqrt``? diff --git a/Help/guide/tutorial/Adding Usage Requirements for a Library.rst b/Help/guide/tutorial/Adding Usage Requirements for a Library.rst new file mode 100644 index 00000000000..a8e914edaf8 --- /dev/null +++ b/Help/guide/tutorial/Adding Usage Requirements for a Library.rst @@ -0,0 +1,52 @@ +Step 3: Adding Usage Requirements for a Library +=============================================== + +Usage requirements allow for far better control over a library or executable's +link and include line while also giving more control over the transitive +property of targets inside CMake. The primary commands that leverage usage +requirements are: + + - :command:`target_compile_definitions` + - :command:`target_compile_options` + - :command:`target_include_directories` + - :command:`target_link_libraries` + +Let's refactor our code from :guide:`tutorial/Adding a Library` to use the +modern CMake approach of usage requirements. We first state that anybody +linking to ``MathFunctions`` needs to include the current source directory, +while ``MathFunctions`` itself doesn't. So this can become an ``INTERFACE`` +usage requirement. + +Remember ``INTERFACE`` means things that consumers require but the producer +doesn't. Add the following lines to the end of +``MathFunctions/CMakeLists.txt``: + +.. literalinclude:: Step4/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-target_include_directories-INTERFACE + :language: cmake + :start-after: # to find MathFunctions.h + +Now that we've specified usage requirements for ``MathFunctions`` we can safely +remove our uses of the ``EXTRA_INCLUDES`` variable from the top-level +``CMakeLists.txt``, here: + +.. literalinclude:: Step4/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-remove-EXTRA_INCLUDES + :language: cmake + :start-after: # add the MathFunctions library + :end-before: # add the executable + +And here: + +.. literalinclude:: Step4/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-target_include_directories-remove-EXTRA_INCLUDES + :language: cmake + :start-after: # so that we will find TutorialConfig.h + +Once this is done, run the :manual:`cmake ` executable or the +:manual:`cmake-gui ` to configure the project and then build it +with your chosen build tool or by using ``cmake --build .`` from the build +directory. diff --git a/Help/guide/tutorial/Adding a Custom Command and Generated File.rst b/Help/guide/tutorial/Adding a Custom Command and Generated File.rst new file mode 100644 index 00000000000..70c66956231 --- /dev/null +++ b/Help/guide/tutorial/Adding a Custom Command and Generated File.rst @@ -0,0 +1,85 @@ +Step 6: Adding a Custom Command and Generated File +================================================== + +Suppose, for the purpose of this tutorial, we decide that we never want to use +the platform ``log`` and ``exp`` functions and instead would like to +generate a table of precomputed values to use in the ``mysqrt`` function. +In this section, we will create the table as part of the build process, +and then compile that table into our application. + +First, let's remove the check for the ``log`` and ``exp`` functions in +``MathFunctions/CMakeLists.txt``. Then remove the check for ``HAVE_LOG`` and +``HAVE_EXP`` from ``mysqrt.cxx``. At the same time, we can remove +:code:`#include `. + +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. + +The next step is to add the appropriate commands to the +``MathFunctions/CMakeLists.txt`` file to build the MakeTable executable and +then run it as part of the build process. A few commands are needed to +accomplish this. + +First, at the top of ``MathFunctions/CMakeLists.txt``, the executable for +``MakeTable`` is added as any other executable would be added. + +.. literalinclude:: Step7/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-add_executable-MakeTable + :language: cmake + :start-after: # first we add the executable that generates the table + :end-before: # add the command to generate the source code + +Then we add a custom command that specifies how to produce ``Table.h`` +by running MakeTable. + +.. literalinclude:: Step7/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-add_custom_command-Table.h + :language: cmake + :start-after: # add the command to generate the source code + :end-before: # add the main library + +Next we have to let CMake know that ``mysqrt.cxx`` depends on the generated +file ``Table.h``. This is done by adding the generated ``Table.h`` to the list +of sources for the library MathFunctions. + +.. literalinclude:: Step7/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-add_library-Table.h + :language: cmake + :start-after: # add the main library + :end-before: # state that anybody linking + +We also have to add the current binary directory to the list of include +directories so that ``Table.h`` can be found and included by ``mysqrt.cxx``. + +.. literalinclude:: Step7/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-target_include_directories-Table.h + :language: cmake + :start-after: # state that we depend on our bin + :end-before: # install rules + +Now let's use the generated table. First, modify ``mysqrt.cxx`` to include +``Table.h``. Next, we can rewrite the ``mysqrt`` function to use the table: + +.. literalinclude:: Step7/MathFunctions/mysqrt.cxx + :caption: MathFunctions/mysqrt.cxx + :name: MathFunctions/mysqrt.cxx + :language: c++ + :start-after: // a hack square root calculation using simple operations + +Run the :manual:`cmake ` executable or the +:manual:`cmake-gui ` 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. +It will then run ``MakeTable`` to produce ``Table.h``. Finally, it will +compile ``mysqrt.cxx`` which includes ``Table.h`` to produce the +``MathFunctions`` library. + +Run the Tutorial executable and verify that it is using the table. diff --git a/Help/guide/tutorial/Adding a Library.rst b/Help/guide/tutorial/Adding a Library.rst new file mode 100644 index 00000000000..ed034489c54 --- /dev/null +++ b/Help/guide/tutorial/Adding a Library.rst @@ -0,0 +1,135 @@ +Step 2: Adding a Library +======================== + +Now we will add a library to our project. This library will contain our own +implementation for computing the square root of a number. The executable can +then use this library instead of the standard square root function provided by +the compiler. + +For this tutorial we will put the library into a subdirectory +called ``MathFunctions``. This directory already contains a header file, +``MathFunctions.h``, and a source file ``mysqrt.cxx``. The source file has one +function called ``mysqrt`` that provides similar functionality to the +compiler's ``sqrt`` function. + +Add the following one line ``CMakeLists.txt`` file to the ``MathFunctions`` +directory: + +.. literalinclude:: Step3/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt + :language: cmake + +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 ``mysqrt.h`` header file can be found. The +last few lines of the top-level ``CMakeLists.txt`` file should now look like: + +.. code-block:: cmake + :caption: CMakeLists.txt + :name: CMakeLists.txt-add_subdirectory + + # add the MathFunctions library + add_subdirectory(MathFunctions) + + # add the executable + add_executable(Tutorial tutorial.cxx) + + target_link_libraries(Tutorial PUBLIC MathFunctions) + + # add the binary tree to the search path for include files + # so that we will find TutorialConfig.h + target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + "${PROJECT_SOURCE_DIR}/MathFunctions" + ) + +Now let us make the ``MathFunctions`` library optional. While for the tutorial +there really isn't any need to do so, for larger projects this is a common +occurrence. The first step is to add an option to the top-level +``CMakeLists.txt`` file. + +.. literalinclude:: Step3/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-option + :language: cmake + :start-after: # should we use our own math functions + :end-before: # add the MathFunctions library + +This option will be displayed in the :manual:`cmake-gui ` and +:manual:`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. + +The next change is to make building and linking the ``MathFunctions`` library +conditional. To do this, we will create an ``if`` statement which checks the +value of the option. Inside the ``if`` block, put the +:command:`add_subdirectory` command from above with some additional list +commands to store information needed to link to the library and add the +subdirectory as an include directory in the ``Tutorial`` target. +The end of the top-level ``CMakeLists.txt`` file will now look like the +following: + +.. literalinclude:: Step3/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-target_link_libraries-EXTRA_LIBS + :language: cmake + :start-after: # add the MathFunctions library + +Note the use of the variable ``EXTRA_LIBS`` to collect up any optional +libraries to later be linked into the executable. The variable +``EXTRA_INCLUDES`` is used similarly for optional header files. This is a +classic approach when dealing with many optional components, we will cover +the modern approach in the next step. + +The corresponding changes to the source code are fairly straightforward. +First, in ``tutorial.cxx``, include the ``MathFunctions.h`` header if we +need it: + +.. literalinclude:: Step3/tutorial.cxx + :caption: tutorial.cxx + :name: tutorial.cxx-ifdef-include + :language: c++ + :start-after: // should we include the MathFunctions header + :end-before: int main + +Then, in the same file, make ``USE_MYMATH`` control which square root +function is used: + +.. literalinclude:: Step3/tutorial.cxx + :caption: tutorial.cxx + :name: tutorial.cxx-ifdef-const + :language: c++ + :start-after: // which square root function should we use? + :end-before: std::cout << "The square root of + +Since the source code now requires ``USE_MYMATH`` we can add it to +``TutorialConfig.h.in`` with the following line: + +.. literalinclude:: Step3/TutorialConfig.h.in + :caption: TutorialConfig.h.in + :name: TutorialConfig.h.in-cmakedefine + :language: c++ + :lines: 4 + +**Exercise**: Why is it important that we configure ``TutorialConfig.h.in`` +after the option for ``USE_MYMATH``? What would happen if we inverted the two? + +Run the :manual:`cmake ` executable or the +:manual:`cmake-gui ` to configure the project and then build it +with your chosen build tool. Then run the built Tutorial executable. + +Now let's update the value of ``USE_MYMATH``. The easiest way is to use the +:manual:`cmake-gui ` or :manual:`ccmake ` if you're +in the terminal. Or, alternatively, if you want to change the option from the +command-line, try: + +.. code-block:: console + + cmake ../Step2 -DUSE_MYMATH=OFF + +Rebuild and run the tutorial again. + +Which function gives better results, ``sqrt`` or ``mysqrt``? diff --git a/Help/guide/tutorial/Complete/CMakeLists.txt b/Help/guide/tutorial/Complete/CMakeLists.txt index 4d8a3ada877..ac1d0839aa5 100644 --- a/Help/guide/tutorial/Complete/CMakeLists.txt +++ b/Help/guide/tutorial/Complete/CMakeLists.txt @@ -73,7 +73,7 @@ function(do_test target arg result) set_tests_properties(Comp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result} ) -endfunction(do_test) +endfunction() # do a bunch of result based tests do_test(Tutorial 4 "4 is 2") @@ -81,7 +81,7 @@ do_test(Tutorial 9 "9 is 3") do_test(Tutorial 5 "5 is 2.236") do_test(Tutorial 7 "7 is 2.645") do_test(Tutorial 25 "25 is 5") -do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") do_test(Tutorial 0.0001 "0.0001 is 0.01") include(InstallRequiredSystemLibraries) diff --git a/Help/guide/tutorial/Installing and Testing.rst b/Help/guide/tutorial/Installing and Testing.rst new file mode 100644 index 00000000000..394c9865f19 --- /dev/null +++ b/Help/guide/tutorial/Installing and Testing.rst @@ -0,0 +1,95 @@ +Step 4: Installing and Testing +============================== + +Now we can start adding install rules and testing support to our project. + +Install Rules +------------- + +The install rules are fairly simple: for ``MathFunctions`` we want to install +the library and header file and for the application we want to install the +executable and configured header. + +So to the end of ``MathFunctions/CMakeLists.txt`` we add: + +.. literalinclude:: Step5/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-install-TARGETS + :language: cmake + :start-after: # install rules + +And to the end of the top-level ``CMakeLists.txt`` we add: + +.. literalinclude:: Step5/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-install-TARGETS + :language: cmake + :start-after: # add the install targets + :end-before: # enable testing + +That is all that is needed to create a basic local install of the tutorial. + +Now run the :manual:`cmake ` executable or the +:manual:`cmake-gui ` to configure the project and then build it +with your chosen build tool. + +Then run the install step by using the ``install`` option of the +:manual:`cmake ` command (introduced in 3.15, older versions of +CMake must use ``make install``) from the command line. For +multi-configuration tools, don't forget to use the ``--config`` argument to +specify the configuration. If using an IDE, simply build the ``INSTALL`` +target. This step will install the appropriate header files, libraries, and +executables. For example: + +.. code-block:: console + + cmake --install . + +The CMake variable :variable:`CMAKE_INSTALL_PREFIX` is used to determine the +root of where the files will be installed. If using the ``cmake --install`` +command, the installation prefix can be overridden via the ``--prefix`` +argument. For example: + +.. code-block:: console + + cmake --install . --prefix "/home/myuser/installdir" + +Navigate to the install directory and verify that the installed Tutorial runs. + +.. _`Tutorial Testing Support`: + +Testing Support +--------------- + +Next let's test our application. At the end of the top-level ``CMakeLists.txt`` +file we can enable testing and then add a number of basic tests to verify that +the application is working correctly. + +.. literalinclude:: Step5/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-enable_testing + :language: cmake + :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. + +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 the +:manual:`ctest ` executable: ``ctest -N`` and ``ctest -VV``. For +multi-config generators (e.g. Visual Studio), the configuration type must be +specified with the ``-C `` flag. For example, to run tests in Debug +mode use ``ctest -C Debug -VV`` from the binary directory +(not the Debug subdirectory!). Release mode would be executed from the same +location but with a ``-C Release``. Alternatively, build the ``RUN_TESTS`` +target from the IDE. diff --git a/Help/guide/tutorial/Packaging Debug and Release.rst b/Help/guide/tutorial/Packaging Debug and Release.rst new file mode 100644 index 00000000000..91b46a77823 --- /dev/null +++ b/Help/guide/tutorial/Packaging Debug and Release.rst @@ -0,0 +1,86 @@ +Step 12: Packaging Debug and Release +==================================== + +**Note:** This example is valid for single-configuration generators and will +not work for multi-configuration generators (e.g. Visual Studio). + +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. + +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. + +Set :variable:`CMAKE_DEBUG_POSTFIX` near the beginning of the top-level +``CMakeLists.txt`` file: + +.. literalinclude:: Complete/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-CMAKE_DEBUG_POSTFIX-variable + :language: cmake + :start-after: project(Tutorial VERSION 1.0) + :end-before: target_compile_features(tutorial_compiler_flags + +And the :prop_tgt:`DEBUG_POSTFIX` property on the tutorial executable: + +.. literalinclude:: Complete/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-DEBUG_POSTFIX-property + :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 + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-VERSION-properties + :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 + + - Step12 + - debug + - release + +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 .. + cmake --build . + cd ../release + cmake -DCMAKE_BUILD_TYPE=Release .. + cmake --build . + +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 ` executable. + +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 + :caption: MultiCPackConfig.cmake + :name: MultiCPackConfig.cmake + :language: cmake + +From the ``Step12`` directory, run :manual:`cpack ` specifying our +custom configuration file with the ``config`` option: + +.. code-block:: console + + cpack --config MultiCPackConfig.cmake diff --git a/Help/guide/tutorial/Packaging an Installer.rst b/Help/guide/tutorial/Packaging an Installer.rst new file mode 100644 index 00000000000..5eb3e3e5f64 --- /dev/null +++ b/Help/guide/tutorial/Packaging an Installer.rst @@ -0,0 +1,57 @@ +Step 7: Packaging an Installer +============================== + +Next suppose that we want to distribute our project to other people so that +they can use it. We want to provide both binary and source distributions on a +variety of platforms. This is a little different from the install we did +previously in :guide:`tutorial/Installing and Testing`, 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. + +.. literalinclude:: Step8/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-include-CPack + :language: cmake + :start-after: # setup installer + +That is all there is to it. We start by including +: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 :module:`CPack module ` 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 the +:manual:`cpack ` executable. To build a binary distribution, from the +binary directory run: + +.. code-block:: console + + cpack + +To specify the generator, use the ``-G`` option. For multi-config builds, use +``-C`` to specify the configuration. For example: + +.. code-block:: console + + cpack -G ZIP -C Debug + +To create a source distribution you would type: + +.. code-block:: console + + cpack --config CPackSourceConfig.cmake + +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. diff --git a/Help/guide/tutorial/Selecting Static or Shared Libraries.rst b/Help/guide/tutorial/Selecting Static or Shared Libraries.rst new file mode 100644 index 00000000000..2d5f70e06af --- /dev/null +++ b/Help/guide/tutorial/Selecting Static or Shared Libraries.rst @@ -0,0 +1,77 @@ +Step 9: Selecting Static or Shared Libraries +============================================ + +In this section we will show how the :variable:`BUILD_SHARED_LIBS` variable can +be used to control the default behavior of :command:`add_library`, +and allow control over how libraries without an explicit type (``STATIC``, +``SHARED``, ``MODULE`` or ``OBJECT``) are built. + +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 ``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: + +.. literalinclude:: Step10/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-option-BUILD_SHARED_LIBS + :language: cmake + :end-before: # add the binary tree + +Now that we have made ``MathFunctions`` always be used, we will need to update +the logic of that library. So, in ``MathFunctions/CMakeLists.txt`` we need to +create a SqrtLibrary that will conditionally be built and installed when +``USE_MYMATH`` is enabled. Now, since this is a tutorial, we are going to +explicitly require that SqrtLibrary is built statically. + +The end result is that ``MathFunctions/CMakeLists.txt`` should look like: + +.. literalinclude:: Step10/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-add_library-STATIC + :language: cmake + :lines: 1-36,42- + +Next, update ``MathFunctions/mysqrt.cxx`` to use the ``mathfunctions`` and +``detail`` namespaces: + +.. literalinclude:: Step10/MathFunctions/mysqrt.cxx + :caption: MathFunctions/mysqrt.cxx + :name: MathFunctions/mysqrt.cxx-namespace + :language: c++ + +We also need to make some changes in ``tutorial.cxx``, so that it no longer +uses ``USE_MYMATH``: + +#. Always include ``MathFunctions.h`` +#. Always use ``mathfunctions::sqrt`` +#. Don't include ``cmath`` + +Finally, update ``MathFunctions/MathFunctions.h`` to use dll export defines: + +.. literalinclude:: Step10/MathFunctions/MathFunctions.h + :caption: MathFunctions/MathFunctions.h + :name: MathFunctions/MathFunctions.h + :language: c++ + +At this point, if you build everything, you may 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 :prop_tgt:`POSITION_INDEPENDENT_CODE` target property of +SqrtLibrary to be ``True`` no matter the build type. + +.. literalinclude:: Step10/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-POSITION_INDEPENDENT_CODE + :language: cmake + :lines: 37-42 + +**Exercise**: We modified ``MathFunctions.h`` to use dll export defines. +Using CMake documentation can you find a helper module to simplify this? diff --git a/Help/guide/tutorial/Step10/CMakeLists.txt b/Help/guide/tutorial/Step10/CMakeLists.txt index 34ae70c2741..dc9a0e8e62c 100644 --- a/Help/guide/tutorial/Step10/CMakeLists.txt +++ b/Help/guide/tutorial/Step10/CMakeLists.txt @@ -55,7 +55,7 @@ function(do_test target arg result) set_tests_properties(Comp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result} ) -endfunction(do_test) +endfunction() # do a bunch of result based tests do_test(Tutorial 4 "4 is 2") @@ -63,7 +63,7 @@ do_test(Tutorial 9 "9 is 3") do_test(Tutorial 5 "5 is 2.236") do_test(Tutorial 7 "7 is 2.645") do_test(Tutorial 25 "25 is 5") -do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") do_test(Tutorial 0.0001 "0.0001 is 0.01") include(InstallRequiredSystemLibraries) diff --git a/Help/guide/tutorial/Step11/CMakeLists.txt b/Help/guide/tutorial/Step11/CMakeLists.txt index 4763951c747..10f35ce2dd0 100644 --- a/Help/guide/tutorial/Step11/CMakeLists.txt +++ b/Help/guide/tutorial/Step11/CMakeLists.txt @@ -63,7 +63,7 @@ function(do_test target arg result) set_tests_properties(Comp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result} ) -endfunction(do_test) +endfunction() # do a bunch of result based tests do_test(Tutorial 4 "4 is 2") @@ -71,7 +71,7 @@ do_test(Tutorial 9 "9 is 3") do_test(Tutorial 5 "5 is 2.236") do_test(Tutorial 7 "7 is 2.645") do_test(Tutorial 25 "25 is 5") -do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") do_test(Tutorial 0.0001 "0.0001 is 0.01") include(InstallRequiredSystemLibraries) diff --git a/Help/guide/tutorial/Step12/CMakeLists.txt b/Help/guide/tutorial/Step12/CMakeLists.txt index eca79d9df7b..634b84cdd4d 100644 --- a/Help/guide/tutorial/Step12/CMakeLists.txt +++ b/Help/guide/tutorial/Step12/CMakeLists.txt @@ -69,7 +69,7 @@ function(do_test target arg result) set_tests_properties(Comp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result} ) -endfunction(do_test) +endfunction() # do a bunch of result based tests do_test(Tutorial 4 "4 is 2") @@ -77,7 +77,7 @@ do_test(Tutorial 9 "9 is 3") do_test(Tutorial 5 "5 is 2.236") do_test(Tutorial 7 "7 is 2.645") do_test(Tutorial 25 "25 is 5") -do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") do_test(Tutorial 0.0001 "0.0001 is 0.01") include(InstallRequiredSystemLibraries) @@ -107,9 +107,10 @@ write_basic_package_version_file( COMPATIBILITY AnyNewerVersion ) -# install the configuration file +# install the generated configuration files install(FILES ${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake + ${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake DESTINATION lib/cmake/MathFunctions ) diff --git a/Help/guide/tutorial/Step5/CMakeLists.txt b/Help/guide/tutorial/Step5/CMakeLists.txt index c3b375a3da9..82d00c8d47a 100644 --- a/Help/guide/tutorial/Step5/CMakeLists.txt +++ b/Help/guide/tutorial/Step5/CMakeLists.txt @@ -54,7 +54,7 @@ function(do_test target arg result) set_tests_properties(Comp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result} ) -endfunction(do_test) +endfunction() # do a bunch of result based tests do_test(Tutorial 4 "4 is 2") @@ -62,5 +62,5 @@ do_test(Tutorial 9 "9 is 3") do_test(Tutorial 5 "5 is 2.236") do_test(Tutorial 7 "7 is 2.645") do_test(Tutorial 25 "25 is 5") -do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") do_test(Tutorial 0.0001 "0.0001 is 0.01") diff --git a/Help/guide/tutorial/Step6/CMakeLists.txt b/Help/guide/tutorial/Step6/CMakeLists.txt index c3b375a3da9..82d00c8d47a 100644 --- a/Help/guide/tutorial/Step6/CMakeLists.txt +++ b/Help/guide/tutorial/Step6/CMakeLists.txt @@ -54,7 +54,7 @@ function(do_test target arg result) set_tests_properties(Comp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result} ) -endfunction(do_test) +endfunction() # do a bunch of result based tests do_test(Tutorial 4 "4 is 2") @@ -62,5 +62,5 @@ do_test(Tutorial 9 "9 is 3") do_test(Tutorial 5 "5 is 2.236") do_test(Tutorial 7 "7 is 2.645") do_test(Tutorial 25 "25 is 5") -do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") do_test(Tutorial 0.0001 "0.0001 is 0.01") diff --git a/Help/guide/tutorial/Step7/CMakeLists.txt b/Help/guide/tutorial/Step7/CMakeLists.txt index c3b375a3da9..82d00c8d47a 100644 --- a/Help/guide/tutorial/Step7/CMakeLists.txt +++ b/Help/guide/tutorial/Step7/CMakeLists.txt @@ -54,7 +54,7 @@ function(do_test target arg result) set_tests_properties(Comp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result} ) -endfunction(do_test) +endfunction() # do a bunch of result based tests do_test(Tutorial 4 "4 is 2") @@ -62,5 +62,5 @@ do_test(Tutorial 9 "9 is 3") do_test(Tutorial 5 "5 is 2.236") do_test(Tutorial 7 "7 is 2.645") do_test(Tutorial 25 "25 is 5") -do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") do_test(Tutorial 0.0001 "0.0001 is 0.01") diff --git a/Help/guide/tutorial/Step8/CMakeLists.txt b/Help/guide/tutorial/Step8/CMakeLists.txt index 19b9913e95c..4ae898f9ba6 100644 --- a/Help/guide/tutorial/Step8/CMakeLists.txt +++ b/Help/guide/tutorial/Step8/CMakeLists.txt @@ -54,7 +54,7 @@ function(do_test target arg result) set_tests_properties(Comp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result} ) -endfunction(do_test) +endfunction() # do a bunch of result based tests do_test(Tutorial 4 "4 is 2") @@ -62,7 +62,7 @@ do_test(Tutorial 9 "9 is 3") do_test(Tutorial 5 "5 is 2.236") do_test(Tutorial 7 "7 is 2.645") do_test(Tutorial 25 "25 is 5") -do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") do_test(Tutorial 0.0001 "0.0001 is 0.01") # setup installer diff --git a/Help/guide/tutorial/Step8/CTestConfig.cmake b/Help/guide/tutorial/Step8/CTestConfig.cmake new file mode 100644 index 00000000000..73efdb1f6e0 --- /dev/null +++ b/Help/guide/tutorial/Step8/CTestConfig.cmake @@ -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) diff --git a/Help/guide/tutorial/Step9/CMakeLists.txt b/Help/guide/tutorial/Step9/CMakeLists.txt index d5f1cc89745..130bc9a2085 100644 --- a/Help/guide/tutorial/Step9/CMakeLists.txt +++ b/Help/guide/tutorial/Step9/CMakeLists.txt @@ -54,7 +54,7 @@ function(do_test target arg result) set_tests_properties(Comp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result} ) -endfunction(do_test) +endfunction() # do a bunch of result based tests do_test(Tutorial 4 "4 is 2") @@ -62,7 +62,7 @@ do_test(Tutorial 9 "9 is 3") do_test(Tutorial 5 "5 is 2.236") do_test(Tutorial 7 "7 is 2.645") do_test(Tutorial 25 "25 is 5") -do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") do_test(Tutorial 0.0001 "0.0001 is 0.01") include(InstallRequiredSystemLibraries) diff --git a/Help/guide/tutorial/index.rst b/Help/guide/tutorial/index.rst index 94753d5dc9b..8b20a2dfe6f 100644 --- a/Help/guide/tutorial/index.rst +++ b/Help/guide/tutorial/index.rst @@ -1,946 +1,43 @@ CMake Tutorial ************** -.. only:: html - - .. contents:: - Introduction ============ The CMake tutorial provides a step-by-step guide that covers common build system issues that CMake helps address. Seeing how various topics all -work together in an example project can be very helpful. The tutorial -documentation and source code for examples can be found in the -``Help/guide/tutorial`` directory of the CMake source code tree. Each step has -its own subdirectory containing code that may be used as a starting point. The -tutorial examples are progressive so that each step provides the complete -solution for the previous step. - -A Basic Starting Point (Step 1) -=============================== - -The most basic project is an executable built from source code files. -For simple projects, a three line ``CMakeLists.txt`` file is all that is -required. This will be the starting point for our tutorial. Create a -``CMakeLists.txt`` file in the ``Step1`` directory that looks like: - -.. code-block:: cmake - - cmake_minimum_required(VERSION 3.10) - - # set the project name - project(Tutorial) - - # add the executable - add_executable(Tutorial tutorial.cxx) - - -Note that this example uses lower case commands in the ``CMakeLists.txt`` file. -Upper, lower, and mixed case commands are supported by CMake. The source -code for ``tutorial.cxx`` is provided in the ``Step1`` directory and can be -used to compute the square root of a number. - -Adding a Version Number and Configured Header File --------------------------------------------------- - -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 use the :command:`project` command -to set the project name and version number. - -.. literalinclude:: Step2/CMakeLists.txt - :language: cmake - :end-before: # specify the C++ standard - -Then, configure a header file to pass the version number to the source -code: - -.. literalinclude:: Step2/CMakeLists.txt - :language: cmake - :start-after: # to the source code - :end-before: # add the executable - -Since the configured file will be written into the binary tree, we -must add that directory to the list of paths to search for include -files. Add the following lines to the end of the ``CMakeLists.txt`` file: - -.. literalinclude:: Step2/CMakeLists.txt - :language: cmake - :start-after: # so that we will find TutorialConfig.h - -Using your favorite editor, create ``TutorialConfig.h.in`` in the source -directory with the following contents: - -.. literalinclude:: Step2/TutorialConfig.h.in - :language: cmake - -When CMake configures this header file the values for -``@Tutorial_VERSION_MAJOR@`` and ``@Tutorial_VERSION_MINOR@`` will be -replaced. - -Next modify ``tutorial.cxx`` to include the configured header file, -``TutorialConfig.h``. - -Finally, let's print out the executable name and version number by updating -``tutorial.cxx`` as follows: - -.. literalinclude:: Step2/tutorial.cxx - :language: c++ - :start-after: { - :end-before: // convert input to double - -Specify the C++ Standard -------------------------- - -Next let's add some C++11 features to our project by replacing ``atof`` with -``std::stod`` in ``tutorial.cxx``. At the same time, remove -``#include ``. - -.. literalinclude:: Step2/tutorial.cxx - :language: c++ - :start-after: // convert input to double - :end-before: // calculate square root - -We will need to explicitly state in the CMake code that it should use the -correct flags. The easiest way to enable support for a specific C++ standard -in CMake is by using the :variable:`CMAKE_CXX_STANDARD` variable. For this -tutorial, set the :variable:`CMAKE_CXX_STANDARD` variable in the -``CMakeLists.txt`` file to 11 and :variable:`CMAKE_CXX_STANDARD_REQUIRED` to -True. Make sure to add the ``CMAKE_CXX_STANDARD`` declarations above the call -to ``add_executable``. - -.. literalinclude:: Step2/CMakeLists.txt - :language: cmake - :end-before: # configure a header file to pass some of the CMake settings - -Build and Test --------------- - -Run the :manual:`cmake ` executable or the -:manual:`cmake-gui ` to configure the project and then build it -with your chosen build tool. - -For example, from the command line we could navigate to the -``Help/guide/tutorial`` directory of the CMake source code tree and create a -build directory: - -.. code-block:: console - - mkdir Step1_build - -Next, navigate to the build directory and run CMake to configure the project -and generate a native build system: - -.. code-block:: console - - cd Step1_build - cmake ../Step1 - -Then call that build system to actually compile/link the project: - -.. code-block:: console - - cmake --build . - -Finally, try to use the newly built ``Tutorial`` with these commands: - -.. code-block:: console - - Tutorial 4294967296 - Tutorial 10 - Tutorial - -Adding a Library (Step 2) -========================= - -Now we will add a library to our project. This library will contain our own -implementation for computing the square root of a number. The executable can -then use this library instead of the standard square root function provided by -the compiler. - -For this tutorial we will put the library into a subdirectory -called ``MathFunctions``. This directory already contains a header file, -``MathFunctions.h``, and a source file ``mysqrt.cxx``. The source file has one -function called ``mysqrt`` that provides similar functionality to the -compiler's ``sqrt`` function. - -Add the following one line ``CMakeLists.txt`` file to the ``MathFunctions`` -directory: - -.. literalinclude:: Step3/MathFunctions/CMakeLists.txt - :language: cmake - -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 ``mysqrt.h`` header file can be found. The -last few lines of the top-level ``CMakeLists.txt`` file should now look like: - -.. code-block:: cmake - - # add the MathFunctions library - add_subdirectory(MathFunctions) - - # add the executable - add_executable(Tutorial tutorial.cxx) - - target_link_libraries(Tutorial PUBLIC MathFunctions) - - # add the binary tree to the search path for include files - # so that we will find TutorialConfig.h - target_include_directories(Tutorial PUBLIC - "${PROJECT_BINARY_DIR}" - "${PROJECT_SOURCE_DIR}/MathFunctions" - ) - -Now let us make the MathFunctions library optional. While for the tutorial -there really isn't any need to do so, for larger projects this is a common -occurrence. The first step is to add an option to the top-level -``CMakeLists.txt`` file. - -.. literalinclude:: Step3/CMakeLists.txt - :language: cmake - :start-after: # should we use our own math functions - :end-before: # add the MathFunctions library - -This option will be displayed in the :manual:`cmake-gui ` and -:manual:`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. - -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`` -file to look like the following: - -.. literalinclude:: Step3/CMakeLists.txt - :language: cmake - :start-after: # add the MathFunctions library - -Note the use of the variable ``EXTRA_LIBS`` to collect up any optional -libraries to later be linked into the executable. The variable -``EXTRA_INCLUDES`` is used similarly for optional header files. This is a -classic approach when dealing with many optional components, we will cover -the modern approach in the next step. - -The corresponding changes to the source code are fairly straightforward. -First, in ``tutorial.cxx``, include the ``MathFunctions.h`` header if we -need it: - -.. literalinclude:: Step3/tutorial.cxx - :language: c++ - :start-after: // should we include the MathFunctions header - :end-before: int main - -Then, in the same file, make ``USE_MYMATH`` control which square root -function is used: - -.. literalinclude:: Step3/tutorial.cxx - :language: c++ - :start-after: // which square root function should we use? - :end-before: std::cout << "The square root of - -Since the source code now requires ``USE_MYMATH`` we can add it to -``TutorialConfig.h.in`` with the following line: - -.. literalinclude:: Step3/TutorialConfig.h.in - :language: c - :lines: 4 - -**Exercise**: Why is it important that we configure ``TutorialConfig.h.in`` -after the option for ``USE_MYMATH``? What would happen if we inverted the two? - -Run the :manual:`cmake ` executable or the -:manual:`cmake-gui ` to configure the project and then build it -with your chosen build tool. Then run the built Tutorial executable. - -Now let's update the value of ``USE_MYMATH``. The easiest way is to use the -:manual:`cmake-gui ` or :manual:`ccmake ` if you're -in the terminal. Or, alternatively, if you want to change the option from the -command-line, try: - -.. code-block:: console - - cmake ../Step2 -DUSE_MYMATH=OFF - -Rebuild and run the tutorial again. - -Which function gives better results, sqrt or mysqrt? - -Adding Usage Requirements for Library (Step 3) -============================================== - -Usage requirements allow for far better control over a library or executable's -link and include line while also giving more control over the transitive -property of targets inside CMake. The primary commands that leverage usage -requirements are: - - - :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 -requirement. - -Remember ``INTERFACE`` means things that consumers require but the producer -doesn't. Add the following lines to the end of -``MathFunctions/CMakeLists.txt``: - -.. literalinclude:: Step4/MathFunctions/CMakeLists.txt - :language: cmake - :start-after: # to find MathFunctions.h - -Now that we've specified usage requirements for MathFunctions we can safely -remove our uses of the ``EXTRA_INCLUDES`` variable from the top-level -``CMakeLists.txt``, here: - -.. literalinclude:: Step4/CMakeLists.txt - :language: cmake - :start-after: # add the MathFunctions library - :end-before: # add the executable - -And here: - -.. literalinclude:: Step4/CMakeLists.txt - :language: cmake - :start-after: # so that we will find TutorialConfig.h - -Once this is done, run the :manual:`cmake ` executable or the -:manual:`cmake-gui ` 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) -=============================== - -Now we can start adding install rules and testing support to our project. - -Install Rules -------------- - -The install rules are fairly simple: for MathFunctions we want to install the -library and header file and for the application we want to install the -executable and configured header. - -So to the end of ``MathFunctions/CMakeLists.txt`` we add: - -.. literalinclude:: Step5/MathFunctions/CMakeLists.txt - :language: cmake - :start-after: # install rules - -And to the end of the top-level ``CMakeLists.txt`` we add: - -.. literalinclude:: Step5/CMakeLists.txt - :language: cmake - :start-after: # add the install targets - :end-before: # enable testing - -That is all that is needed to create a basic local install of the tutorial. - -Now run the :manual:`cmake ` executable or the -:manual:`cmake-gui ` to configure the project and then build it -with your chosen build tool. - -Then run the install step by using the ``install`` option of the -:manual:`cmake ` command (introduced in 3.15, older versions of -CMake must use ``make install``) from the command line. For -multi-configuration tools, don't forget to use the ``--config`` argument to -specify the configuration. If using an IDE, simply build the ``INSTALL`` -target. This step will install the appropriate header files, libraries, and -executables. For example: - -.. code-block:: console - - cmake --install . - -The CMake variable :variable:`CMAKE_INSTALL_PREFIX` is used to determine the -root of where the files will be installed. If using the ``cmake --install`` -command, the installation prefix can be overridden via the ``--prefix`` -argument. For example: - -.. code-block:: console - - cmake --install . --prefix "/home/myuser/installdir" - -Navigate to the install directory and verify that the installed Tutorial runs. - -Testing Support ---------------- - -Next let's test our application. At the end of the top-level ``CMakeLists.txt`` -file we can enable testing and then add a number of basic tests to verify that -the application is working correctly. - -.. literalinclude:: Step5/CMakeLists.txt - :language: cmake - :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. - -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 the -:manual:`ctest ` 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) -==================================== - -Let us consider adding some code to our project that depends on features the -target platform may not have. For this example, we will add some code that -depends on whether or not the target platform has the ``log`` and ``exp`` -functions. Of course almost every platform has these functions but for this -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 :module:`CheckSymbolExists` module in -``MathFunctions/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. - -.. literalinclude:: Step6/MathFunctions/CMakeLists.txt - :language: cmake - :start-after: # does this system provide the log and exp functions? - :end-before: # add compile definitions - -If available, use :command:`target_compile_definitions` to specify -``HAVE_LOG`` and ``HAVE_EXP`` as ``PRIVATE`` compile definitions. - -.. literalinclude:: Step6/MathFunctions/CMakeLists.txt - :language: cmake - :start-after: # add compile definitions - :end-before: # install rules - -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 - -We will also need to modify ``mysqrt.cxx`` to include ``cmath``. - -.. literalinclude:: Step6/MathFunctions/mysqrt.cxx - :language: c++ - :end-before: #include - -Run the :manual:`cmake ` executable or the -:manual:`cmake-gui ` to configure the project and then build it -with your chosen build tool and run the Tutorial executable. - -Which function gives better results now, sqrt or mysqrt? - -Adding a Custom Command and Generated File (Step 6) -=================================================== - -Suppose, for the purpose of this tutorial, we decide that we never want to use -the platform ``log`` and ``exp`` functions and instead would like to -generate a table of precomputed values to use in the ``mysqrt`` function. -In this section, we will create the table as part of the build process, -and then compile that table into our application. - -First, let's remove the check for the ``log`` and ``exp`` functions in -``MathFunctions/CMakeLists.txt``. Then remove the check for ``HAVE_LOG`` and -``HAVE_EXP`` from ``mysqrt.cxx``. At the same time, we can remove -:code:`#include `. - -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. - -The next step is to add the appropriate commands to the -``MathFunctions/CMakeLists.txt`` file to build the MakeTable executable and -then run it as part of the build process. A few commands are needed to -accomplish this. - -First, at the top of ``MathFunctions/CMakeLists.txt``, the executable for -``MakeTable`` is added as any other executable would be added. - -.. literalinclude:: Step7/MathFunctions/CMakeLists.txt - :language: cmake - :start-after: # first we add the executable that generates the table - :end-before: # add the command to generate the source code - -Then we add a custom command that specifies how to produce ``Table.h`` -by running MakeTable. - -.. literalinclude:: Step7/MathFunctions/CMakeLists.txt - :language: cmake - :start-after: # add the command to generate the source code - :end-before: # add the main library - -Next we have to let CMake know that ``mysqrt.cxx`` depends on the generated -file ``Table.h``. This is done by adding the generated ``Table.h`` to the list -of sources for the library MathFunctions. - -.. literalinclude:: Step7/MathFunctions/CMakeLists.txt - :language: cmake - :start-after: # add the main library - :end-before: # state that anybody linking - -We also have to add the current binary directory to the list of include -directories so that ``Table.h`` can be found and included by ``mysqrt.cxx``. - -.. literalinclude:: Step7/MathFunctions/CMakeLists.txt - :language: cmake - :start-after: # state that we depend on our bin - :end-before: # install rules - -Now let's use the generated table. First, modify ``mysqrt.cxx`` to include -``Table.h``. Next, we can rewrite the mysqrt function to use the table: - -.. literalinclude:: Step7/MathFunctions/mysqrt.cxx - :language: c++ - :start-after: // a hack square root calculation using simple operations - -Run the :manual:`cmake ` executable or the -:manual:`cmake-gui ` 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. -It will then run ``MakeTable`` to produce ``Table.h``. Finally, it will -compile ``mysqrt.cxx`` which includes ``Table.h`` to produce the MathFunctions -library. - -Run the Tutorial executable and verify that it is using the table. - -Building an Installer (Step 7) -============================== - -Next suppose that we want to distribute our project to other people so that -they can use it. We want to provide both binary and source distributions on a -variety of platforms. This is a little different from the install we did -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. - -.. literalinclude:: Step8/CMakeLists.txt - :language: cmake - :start-after: # setup installer - -That is all there is to it. We start by including -: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 :module:`CPack module ` 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 the -:manual:`cpack ` executable. To build a binary distribution, from the -binary directory run: - -.. code-block:: console - - cpack - -To specify the generator, use the ``-G`` option. For multi-config builds, use -``-C`` to specify the configuration. For example: - -.. code-block:: console - - cpack -G ZIP -C Debug - -To create a source distribution you would type: - -.. code-block:: console - - cpack --config CPackSourceConfig.cmake - -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. - -Adding Support for a Dashboard (Step 8) -======================================= - -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 :module:`CTest` module in our top-level -``CMakeLists.txt``. - -Replace: - -.. code-block:: cmake - - # enable testing - enable_testing() - -With: - -.. code-block:: cmake - - # enable dashboard scripting - include(CTest) - -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 -dashboard. - -.. literalinclude:: Step9/CTestConfig.cmake - :language: cmake - -The :manual:`ctest ` executable will read in this file when it runs. -To create a simple dashboard you can run the :manual:`cmake ` -executable or the :manual:`cmake-gui ` to configure the project, -but do not build it yet. Instead, change directory to the binary tree, and then -run: - - ctest [-VV] -D Experimental - -Remember, for multi-config generators (e.g. Visual Studio), the configuration -type must be specified:: - - ctest [-VV] -C Debug -D Experimental - -Or, from an IDE, build the ``Experimental`` target. - -The :manual:`ctest ` 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 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 :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 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: - -.. literalinclude:: Step10/CMakeLists.txt - :language: cmake - :end-before: # add the binary tree - -Now that we have made MathFunctions always be used, we will need to update -the logic of that library. So, in ``MathFunctions/CMakeLists.txt`` we need to -create a SqrtLibrary that will conditionally be built and installed when -``USE_MYMATH`` is enabled. Now, since this is a tutorial, we are going to -explicitly require that SqrtLibrary is built statically. - -The end result is that ``MathFunctions/CMakeLists.txt`` should look like: - -.. literalinclude:: Step10/MathFunctions/CMakeLists.txt - :language: cmake - :lines: 1-36,42- - -Next, update ``MathFunctions/mysqrt.cxx`` to use the ``mathfunctions`` and -``detail`` namespaces: - -.. literalinclude:: Step10/MathFunctions/mysqrt.cxx - :language: c++ - -We also need to make some changes in ``tutorial.cxx``, so that it no longer -uses ``USE_MYMATH``: - -#. Always include ``MathFunctions.h`` -#. Always use ``mathfunctions::sqrt`` -#. Don't include cmath - -Finally, update ``MathFunctions/MathFunctions.h`` to use dll export defines: - -.. literalinclude:: Step10/MathFunctions/MathFunctions.h - :language: c++ - -At this point, if you build everything, you may 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 :prop_tgt:`POSITION_INDEPENDENT_CODE` target property of -SqrtLibrary to be True no matter the build type. - -.. literalinclude:: Step10/MathFunctions/CMakeLists.txt - :language: cmake - :lines: 37-42 - -**Exercise**: We modified ``MathFunctions.h`` to use dll export defines. -Using CMake documentation can you find a helper module to simplify this? - - -Adding Generator Expressions (Step 10) -====================================== - -:manual:`Generator expressions ` are evaluated -during build system generation to produce information specific to each build -configuration. - -:manual:`Generator expressions ` 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. - -:manual:`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. - -There are different types of -:manual:`generator expressions ` 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 -:manual:`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. Let's 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: - -.. literalinclude:: Step10/CMakeLists.txt - :language: cmake - :start-after: project(Tutorial VERSION 1.0) - :end-before: # control where the static and shared libraries are built so that on windows - -Would be replaced with: - -.. literalinclude:: Step11/CMakeLists.txt - :language: cmake - :start-after: project(Tutorial VERSION 1.0) - :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: - -.. literalinclude:: Step11/CMakeLists.txt - :language: cmake - :start-after: # the BUILD_INTERFACE genex - :end-before: # control where the static and shared libraries are built so that on windows - -Looking at this we see that the warning flags are encapsulated inside a -``BUILD_INTERFACE`` condition. This is done so that consumers of our installed -project will not inherit our warning flags. - - -**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) -===================================== - -During `Installing and Testing (Step 4)`_ of the tutorial we added the ability -for CMake to install the library and headers of the project. During -`Building an Installer (Step 7)`_ we added the ability to package up this -information so it could be distributed to other people. - -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 :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: - -.. literalinclude:: Complete/MathFunctions/CMakeLists.txt - :language: cmake - :start-after: # install rules - -Now that we have MathFunctions being exported, we also need to explicitly -install the generated ``MathFunctionsTargets.cmake`` file. This is done by -adding the following to the bottom of the top-level ``CMakeLists.txt``: - -.. literalinclude:: Complete/CMakeLists.txt - :language: cmake - :start-after: # install the configuration targets - :end-before: include(CMakePackageConfigHelpers) - -At this point you should try and run CMake. If everything is setup properly -you will see that CMake will generate an error that looks like: - -.. code-block:: console - - Target "MathFunctions" INTERFACE_INCLUDE_DIRECTORIES property contains - path: - - "/Users/robert/Documents/CMakeClass/Tutorial/Step11/MathFunctions" - - which is prefixed in the source directory. - -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 :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 -:command:`target_include_directories` call for MathFunctions to look like: - -.. 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 - -Once this has been updated, we can re-run CMake and verify that it doesn't -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 :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:: 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:: Step12/CMakeLists.txt - :language: cmake - :start-after: # install the configuration targets - :end-before: # generate the export - -At this point, we have generated a relocatable CMake Configuration for our -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:: Step12/CMakeLists.txt - :language: cmake - :start-after: # needs to be after the install(TARGETS ) command - -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. - -Packaging Debug and Release (Step 12) -===================================== - -**Note:** This example is valid for single-configuration generators and will -not work for multi-configuration generators (e.g. Visual Studio). - -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. - -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. - -Set :variable:`CMAKE_DEBUG_POSTFIX` near the beginning of the top-level -``CMakeLists.txt`` file: - -.. literalinclude:: Complete/CMakeLists.txt - :language: cmake - :start-after: project(Tutorial VERSION 1.0) - :end-before: target_compile_features(tutorial_compiler_flags - -And the :prop_tgt:`DEBUG_POSTFIX` property on the tutorial executable: - -.. 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 - - - Step12 - - debug - - release - -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 .. - cmake --build . - cd ../release - cmake -DCMAKE_BUILD_TYPE=Release .. - cmake --build . - -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 ` executable. - -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 ` specifying our -custom configuration file with the ``config`` option: - -.. code-block:: console - - cpack --config MultiCPackConfig.cmake +work together in an example project can be very helpful. + +Steps +===== + +The tutorial documentation and source code for examples can be found in +the ``Help/guide/tutorial`` directory of the CMake source code tree. +Each step has its own subdirectory containing code that may be used as a +starting point. The tutorial examples are progressive so that each step +provides the complete solution for the previous step. + +.. toctree:: + :maxdepth: 2 + + A Basic Starting Point + Adding a Library + Adding Usage Requirements for a Library + Installing and Testing + Adding System Introspection + Adding a Custom Command and Generated File + Packaging an Installer + Adding Support for a Testing Dashboard + Selecting Static or Shared Libraries + Adding Generator Expressions + Adding Export Configuration + Packaging Debug and Release + +.. + Whenever a step above is renamed or removed, leave forwarding text in + its original document file, and list it below to preserve old links + to cmake.org/cmake/help/latest/ URLs. + +.. toctree:: + :maxdepth: 1 + :hidden: diff --git a/Help/manual/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt index 0947e41cbf6..8e23b7711bd 100644 --- a/Help/manual/OPTIONS_BUILD.txt +++ b/Help/manual/OPTIONS_BUILD.txt @@ -76,6 +76,14 @@ native build system to choose a compiler or SDK. See the :variable:`CMAKE_GENERATOR_PLATFORM` variable for details. +``--toolchain `` + Specify the cross compiling toolchain file, equivalent to setting + :variable:`CMAKE_TOOLCHAIN_FILE` variable. + +``--install-prefix `` + Specify the installation directory, used by the + :variable:`CMAKE_INSTALL_PREFIX` variable. Must be an absolute path. + ``-Wno-dev`` Suppress developer warnings. diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 70083833d72..2f430705e4a 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -21,9 +21,9 @@ Binary Targets Executables and libraries are defined using the :command:`add_executable` and :command:`add_library` commands. The resulting binary files have -appropriate :prop_tgt:`PREFIX`, :prop_tgt:`SUFFIX` and extensions for the platform targeted. -Dependencies between binary targets are expressed using the -:command:`target_link_libraries` command: +appropriate :prop_tgt:`PREFIX`, :prop_tgt:`SUFFIX` and extensions for the +platform targeted. Dependencies between binary targets are expressed using +the :command:`target_link_libraries` command: .. code-block:: cmake @@ -530,38 +530,6 @@ the calculated "compatible" value of a property may be read with the In this case, the ``exe1`` source files will be compiled with ``-DCONTAINER_SIZE=200``. -Configuration determined build specifications may be conveniently set using -the ``CONFIG`` generator expression. - -.. code-block:: cmake - - target_compile_definitions(exe1 PRIVATE - $<$:DEBUG_BUILD> - ) - -The ``CONFIG`` parameter is compared case-insensitively with the configuration -being built. In the presence of :prop_tgt:`IMPORTED` targets, the content of -:prop_tgt:`MAP_IMPORTED_CONFIG_DEBUG >` is also -accounted for by this expression. - -Some buildsystems generated by :manual:`cmake(1)` have a predetermined -build-configuration set in the :variable:`CMAKE_BUILD_TYPE` variable. The -buildsystem for the IDEs such as Visual Studio and Xcode are generated -independent of the build-configuration, and the actual build configuration -is not known until build-time. Therefore, code such as - -.. code-block:: cmake - - string(TOLOWER ${CMAKE_BUILD_TYPE} _type) - if (_type STREQUAL debug) - target_compile_definitions(exe1 PRIVATE DEBUG_BUILD) - endif() - -may appear to work for :ref:`Makefile Generators` and :generator:`Ninja` -generators, but is not portable to IDE generators. Additionally, -the :prop_tgt:`IMPORTED` configuration-mappings are not accounted for -with code like this, so it should be avoided. - The unary ``TARGET_PROPERTY`` generator expression and the ``TARGET_POLICY`` generator expression are evaluated with the consuming target context. This means that a usage requirement specification may be evaluated differently based @@ -840,6 +808,121 @@ target at a time. The commands :command:`add_compile_definitions`, a similar function, but operate at directory scope instead of target scope for convenience. +.. _`Build Configurations`: + +Build Configurations +==================== + +Configurations determine specifications for a certain type of build, such +as ``Release`` or ``Debug``. The way this is specified depends on the type +of :manual:`generator ` being used. For single +configuration generators like :ref:`Makefile Generators` and +:generator:`Ninja`, the configuration is specified at configure time by the +:variable:`CMAKE_BUILD_TYPE` variable. For multi-configuration generators +like :ref:`Visual Studio `, :generator:`Xcode`, and +:generator:`Ninja Multi-Config`, the configuration is chosen by the user at +build time and :variable:`CMAKE_BUILD_TYPE` is ignored. In the +multi-configuration case, the set of *available* configurations is specified +at configure time by the :variable:`CMAKE_CONFIGURATION_TYPES` variable, +but the actual configuration used cannot be known until the build stage. +This difference is often misunderstood, leading to problematic code like the +following: + +.. code-block:: cmake + + # WARNING: This is wrong for multi-config generators because they don't use + # and typically don't even set CMAKE_BUILD_TYPE + string(TOLOWER ${CMAKE_BUILD_TYPE} build_type) + if (build_type STREQUAL debug) + target_compile_definitions(exe1 PRIVATE DEBUG_BUILD) + endif() + +:manual:`Generator expressions ` should be +used instead to handle configuration-specific logic correctly, regardless of +the generator used. For example: + +.. code-block:: cmake + + # Works correctly for both single and multi-config generators + target_compile_definitions(exe1 PRIVATE + $<$:DEBUG_BUILD> + ) + +In the presence of :prop_tgt:`IMPORTED` targets, the content of +:prop_tgt:`MAP_IMPORTED_CONFIG_DEBUG >` is also +accounted for by the above ``$`` expression. + + +Case Sensitivity +---------------- + +:variable:`CMAKE_BUILD_TYPE` and :variable:`CMAKE_CONFIGURATION_TYPES` are +just like other variables in that any string comparisons made with their +values will be case-sensitive. The ``$`` generator expression also +preserves the casing of the configuration as set by the user or CMake defaults. +For example: + +.. code-block:: cmake + + # NOTE: Don't use these patterns, they are for illustration purposes only. + + set(CMAKE_BUILD_TYPE Debug) + if(CMAKE_BUILD_TYPE STREQUAL DEBUG) + # ... will never get here, "Debug" != "DEBUG" + endif() + add_custom_target(print_config ALL + # Prints "Config is Debug" in this single-config case + COMMAND ${CMAKE_COMMAND} -E echo "Config is $" + VERBATIM + ) + + set(CMAKE_CONFIGURATION_TYPES Debug Release) + if(DEBUG IN_LIST CMAKE_CONFIGURATION_TYPES) + # ... will never get here, "Debug" != "DEBUG" + endif() + +In contrast, CMake treats the configuration type case-insensitively when +using it internally in places that modify behavior based on the configuration. +For example, the ``$`` generator expression will evaluate to 1 +for a configuration of not only ``Debug``, but also ``DEBUG``, ``debug`` or +even ``DeBuG``. Therefore, you can specify configuration types in +:variable:`CMAKE_BUILD_TYPE` and :variable:`CMAKE_CONFIGURATION_TYPES` with +any mixture of upper and lowercase, although there are strong conventions +(see the next section). If you must test the value in string comparisons, +always convert the value to upper or lowercase first and adjust the test +accordingly. + +Default And Custom Configurations +--------------------------------- + +By default, CMake defines a number of standard configurations: + +* ``Debug`` +* ``Release`` +* ``RelWithDebInfo`` +* ``MinSizeRel`` + +In multi-config generators, the :variable:`CMAKE_CONFIGURATION_TYPES` variable +will be populated with (potentially a subset of) the above list by default, +unless overridden by the project or user. The actual configuration used is +selected by the user at build time. + +For single-config generators, the configuration is specified with the +:variable:`CMAKE_BUILD_TYPE` variable at configure time and cannot be changed +at build time. The default value will often be none of the above standard +configurations and will instead be an empty string. A common misunderstanding +is that this is the same as ``Debug``, but that is not the case. Users should +always explicitly specify the build type instead to avoid this common problem. + +The above standard configuration types provide reasonable behavior on most +platforms, but they can be extended to provide other types. Each configuration +defines a set of compiler and linker flag variables for the language in use. +These variables follow the convention :variable:`CMAKE__FLAGS_`, +where ```` is always the uppercase configuration name. When defining +a custom configuration type, make sure these variables are set appropriately, +typically as cache variables. + + Pseudo Targets ============== diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst index 2c2b04cbe24..67b0f6ec73e 100644 --- a/Help/manual/cmake-compile-features.7.rst +++ b/Help/manual/cmake-compile-features.7.rst @@ -118,13 +118,12 @@ as well as any dependents (that may include headers from ``mylib``). Availability of Compiler Extensions ----------------------------------- -Because the :prop_tgt:`CXX_EXTENSIONS` target property is ``ON`` by default, -CMake uses extended variants of language dialects by default, such as -``-std=gnu++11`` instead of ``-std=c++11``. That target property may be -set to ``OFF`` to use the non-extended variant of the dialect flag. Note -that because most compilers enable extensions by default, this could -expose cross-platform bugs in user code or in the headers of third-party -dependencies. +The :prop_tgt:`_EXTENSIONS` target property defaults to the compiler's +default (see :variable:`CMAKE__EXTENSIONS_DEFAULT`). Note that because +most compilers enable extensions by default, this may expose portability bugs +in user code or in the headers of third-party dependencies. + +:prop_tgt:`_EXTENSIONS` used to default to ``ON``. See :policy:`CMP0128`. Optional Compile Features ========================= @@ -261,6 +260,7 @@ following :variable:`compiler ids _COMPILER_ID>` as of the versions specified for each: * ``Cray``: Cray Compiler Environment version 8.1+. +* ``Fujitsu``: Fujitsu HPC compiler 4.0+. * ``PGI``: PGI version 12.10+. * ``NVHPC``: NVIDIA HPC compilers version 11.0+. * ``TI``: Texas Instruments compiler. diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index af9a8ab0d48..fe146de0f10 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -350,6 +350,24 @@ look. PATHS ${PC_Foo_LIBRARY_DIRS} ) +Alternatively, if the library is available with multiple configurations, you can +use :module:`SelectLibraryConfigurations` to automatically set the +``Foo_LIBRARY`` variable instead: + +.. code-block:: cmake + + find_library(Foo_LIBRARY_RELEASE + NAMES foo + PATHS ${PC_Foo_LIBRARY_DIRS}/Release + ) + find_library(Foo_LIBRARY_DEBUG + NAMES foo + PATHS ${PC_Foo_LIBRARY_DIRS}/Debug + ) + + include(SelectLibraryConfigurations) + select_library_configurations(Foo) + If you have a good way of getting the version (from a header file, for example), you can use that information to set ``Foo_VERSION`` (although note that find modules have traditionally used ``Foo_VERSION_STRING``, diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index bc1fa1d8526..0799fddb67a 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -30,16 +30,21 @@ Environment Variables that Control the Build /envvar/CMAKE_APPLE_SILICON_PROCESSOR /envvar/CMAKE_BUILD_PARALLEL_LEVEL + /envvar/CMAKE_BUILD_TYPE + /envvar/CMAKE_CONFIGURATION_TYPES /envvar/CMAKE_CONFIG_TYPE /envvar/CMAKE_EXPORT_COMPILE_COMMANDS /envvar/CMAKE_GENERATOR /envvar/CMAKE_GENERATOR_INSTANCE /envvar/CMAKE_GENERATOR_PLATFORM /envvar/CMAKE_GENERATOR_TOOLSET + /envvar/CMAKE_INSTALL_MODE /envvar/CMAKE_LANG_COMPILER_LAUNCHER + /envvar/CMAKE_LANG_LINKER_LAUNCHER /envvar/CMAKE_MSVCIDE_RUN_PATH /envvar/CMAKE_NO_VERBOSE /envvar/CMAKE_OSX_ARCHITECTURES + /envvar/CMAKE_TOOLCHAIN_FILE /envvar/DESTDIR /envvar/LDFLAGS /envvar/MACOSX_DEPLOYMENT_TARGET @@ -65,6 +70,8 @@ Environment Variables for Languages /envvar/CXXFLAGS /envvar/FC /envvar/FFLAGS + /envvar/HIPCXX + /envvar/HIPFLAGS /envvar/ISPC /envvar/ISPCFLAGS /envvar/OBJC diff --git a/Help/manual/cmake-file-api.7.rst b/Help/manual/cmake-file-api.7.rst index 89739b7d55b..5e22ea9051a 100644 --- a/Help/manual/cmake-file-api.7.rst +++ b/Help/manual/cmake-file-api.7.rst @@ -443,7 +443,8 @@ Version 1 does not exist to avoid confusion with that from "hasInstallRule": true, "minimumCMakeVersion": { "string": "3.14" - } + }, + "jsonFile": "" }, { "source": "sub", @@ -453,7 +454,8 @@ Version 1 does not exist to avoid confusion with that from "targetIndexes": [ 1 ], "minimumCMakeVersion": { "string": "3.14" - } + }, + "jsonFile": "" } ], "projects": [ @@ -569,6 +571,13 @@ The members specific to ``codemodel`` objects are: :command:`install` rules, i.e. whether a ``make install`` or equivalent rule is available. + ``jsonFile`` + A JSON string specifying a path relative to the codemodel file + to another JSON file containing a + `"codemodel" version 2 "directory" object`_. + + This field was added in codemodel version 2.3. + ``projects`` A JSON array of entries corresponding to the top-level project and sub-projects defined in the build system. Each (sub-)project @@ -633,6 +642,216 @@ The members specific to ``codemodel`` objects are: to another JSON file containing a `"codemodel" version 2 "target" object`_. +"codemodel" version 2 "directory" object +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A codemodel "directory" object is referenced by a `"codemodel" version 2`_ +object's ``directories`` array. Each "directory" object is a JSON object +with members: + +``paths`` + A JSON object containing members: + + ``source`` + A string specifying the path to the source directory, represented + with forward slashes. If the directory is inside the top-level + source directory then the path is specified relative to that + directory (with ``.`` for the top-level source directory itself). + Otherwise the path is absolute. + + ``build`` + A string specifying the path to the build directory, represented + with forward slashes. If the directory is inside the top-level + build directory then the path is specified relative to that + directory (with ``.`` for the top-level build directory itself). + Otherwise the path is absolute. + +``installers`` + A JSON array of entries corresponding to :command:`install` rules. + Each entry is a JSON object containing members: + + ``component`` + A string specifying the component selected by the corresponding + :command:`install` command invocation. + + ``destination`` + Optional member that is present for specific ``type`` values below. + The value is a string specifying the install destination path. + The path may be absolute or relative to the install prefix. + + ``paths`` + Optional member that is present for specific ``type`` values below. + The value is a JSON array of entries corresponding to the paths + (files or directories) to be installed. Each entry is one of: + + * A string specifying the path from which a file or directory + is to be installed. The portion of the path not preceded by + a ``/`` also specifies the path (name) to which the file + or directory is to be installed under the destination. + + * A JSON object with members: + + ``from`` + A string specifying the path from which a file or directory + is to be installed. + + ``to`` + A string specifying the path to which the file or directory + is to be installed under the destination. + + In both cases the paths are represented with forward slashes. If + the "from" path is inside the top-level directory documented by the + corresponding ``type`` value, then the path is specified relative + to that directory. Otherwise the path is absolute. + + ``type`` + A string specifying the type of installation rule. The value is one + of the following, with some variants providing additional members: + + ``file`` + An :command:`install(FILES)` or :command:`install(PROGRAMS)` call. + The ``destination`` and ``paths`` members are populated, with paths + under the top-level *source* directory expressed relative to it. + The ``isOptional`` member may exist. + This type has no additional members. + + ``directory`` + An :command:`install(DIRECTORY)` call. + The ``destination`` and ``paths`` members are populated, with paths + under the top-level *source* directory expressed relative to it. + The ``isOptional`` member may exist. + This type has no additional members. + + ``target`` + An :command:`install(TARGETS)` call. + The ``destination`` and ``paths`` members are populated, with paths + under the top-level *build* directory expressed relative to it. + The ``isOptional`` member may exist. + This type has additional members ``targetId``, ``targetIndex``, + ``targetIsImportLibrary``, and ``targetInstallNamelink``. + + ``export`` + An :command:`install(EXPORT)` call. + The ``destination`` and ``paths`` members are populated, with paths + under the top-level *build* directory expressed relative to it. + The ``paths`` entries refer to files generated automatically by + CMake for installation, and their actual values are considered + private implementation details. + This type has additional members ``exportName`` and ``exportTargets``. + + ``script`` + An :command:`install(SCRIPT)` call. + This type has additional member ``scriptFile``. + + ``code`` + An :command:`install(CODE)` call. + This type has no additional members. + + ``importedRuntimeArtifacts`` + An :command:`install(IMPORTED_RUNTIME_ARTIFACTS)` call. + The ``destination`` member is populated. The ``isOptional`` member may + exist. This type has no additional members. + + ``runtimeDependencySet`` + An :command:`install(RUNTIME_DEPENDENCY_SET)` call or an + :command:`install(TARGETS)` call with ``RUNTIME_DEPENDENCIES``. The + ``destination`` member is populated. This type has additional members + ``runtimeDependencySetName`` and ``runtimeDependencySetType``. + + ``isExcludeFromAll`` + Optional member that is present with boolean value ``true`` when + :command:`install` is called with the ``EXCLUDE_FROM_ALL`` option. + + ``isForAllComponents`` + Optional member that is present with boolean value ``true`` when + :command:`install(SCRIPT|CODE)` is called with the + ``ALL_COMPONENTS`` option. + + ``isOptional`` + Optional member that is present with boolean value ``true`` when + :command:`install` is called with the ``OPTIONAL`` option. + This is allowed when ``type`` is ``file``, ``directory``, or ``target``. + + ``targetId`` + Optional member that is present when ``type`` is ``target``. + The value is a string uniquely identifying the target to be installed. + This matches the ``id`` member of the target in the main + "codemodel" object's ``targets`` array. + + ``targetIndex`` + Optional member that is present when ``type`` is ``target``. + The value is an unsigned integer 0-based index into the main "codemodel" + object's ``targets`` array for the target to be installed. + + ``targetIsImportLibrary`` + Optional member that is present when ``type`` is ``target`` and + the installer is for a Windows DLL import library file or for an + AIX linker import file. If present, it has boolean value ``true``. + + ``targetInstallNamelink`` + Optional member that is present when ``type`` is ``target`` and + the installer corresponds to a target that may use symbolic links + to implement the :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` + target properties. + The value is a string indicating how the installer is supposed to + handle the symlinks: ``skip`` means the installer should skip the + symlinks and install only the real file, and ``only`` means the + installer should install only the symlinks and not the real file. + In all cases the ``paths`` member lists what it actually installs. + + ``exportName`` + Optional member that is present when ``type`` is ``export``. + The value is a string specifying the name of the export. + + ``exportTargets`` + Optional member that is present when ``type`` is ``export``. + The value is a JSON array of entries corresponding to the targets + included in the export. Each entry is a JSON object with members: + + ``id`` + A string uniquely identifying the target. This matches + the ``id`` member of the target in the main "codemodel" + object's ``targets`` array. + + ``index`` + An unsigned integer 0-based index into the main "codemodel" + object's ``targets`` array for the target. + + ``runtimeDependencySetName`` + Optional member that is present when ``type`` is ``runtimeDependencySet`` + and the installer was created by an + :command:`install(RUNTIME_DEPENDENCY_SET)` call. The value is a string + specifying the name of the runtime dependency set that was installed. + + ``runtimeDependencySetType`` + Optional member that is present when ``type`` is ``runtimeDependencySet``. + The value is a string with one of the following values: + + ``library`` + Indicates that this installer installs dependencies that are not macOS + frameworks. + + ``framework`` + Indicates that this installer installs dependencies that are macOS + frameworks. + + ``scriptFile`` + Optional member that is present when ``type`` is ``script``. + The value is a string specifying the path to the script file on disk, + represented with forward slashes. If the file is inside the top-level + source directory then the path is specified relative to that directory. + Otherwise the path is absolute. + + ``backtrace`` + Optional member that is present when a CMake language backtrace to + the :command:`install` or other command invocation that added this + installer is available. The value is an unsigned integer 0-based + index into the ``backtraceGraph`` member's ``nodes`` array. + +``backtraceGraph`` + A `"codemodel" version 2 "backtrace graph"`_ whose nodes are referenced + from ``backtrace`` members elsewhere in this "directory" object. + "codemodel" version 2 "target" object ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -964,40 +1183,48 @@ with members: with forward slashes. ``backtraceGraph`` - A JSON object describing the graph of backtraces whose nodes are - referenced from ``backtrace`` members elsewhere. The members are: + A `"codemodel" version 2 "backtrace graph"`_ whose nodes are referenced + from ``backtrace`` members elsewhere in this "target" object. - ``nodes`` - A JSON array listing nodes in the backtrace graph. Each entry - is a JSON object with members: +"codemodel" version 2 "backtrace graph" +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - ``file`` - An unsigned integer 0-based index into the backtrace ``files`` array. +The ``backtraceGraph`` member of a `"codemodel" version 2 "directory" object`_, +or `"codemodel" version 2 "target" object`_ is a JSON object describing a +graph of backtraces. Its nodes are referenced from ``backtrace`` members +elsewhere in the containing object. The backtrace graph object members are: - ``line`` - An optional member present when the node represents a line within - the file. The value is an unsigned integer 1-based line number. +``nodes`` + A JSON array listing nodes in the backtrace graph. Each entry + is a JSON object with members: - ``command`` - An optional member present when the node represents a command - invocation within the file. The value is an unsigned integer - 0-based index into the backtrace ``commands`` array. + ``file`` + An unsigned integer 0-based index into the backtrace ``files`` array. - ``parent`` - An optional member present when the node is not the bottom of - the call stack. The value is an unsigned integer 0-based index - of another entry in the backtrace ``nodes`` array. + ``line`` + An optional member present when the node represents a line within + the file. The value is an unsigned integer 1-based line number. - ``commands`` - A JSON array listing command names referenced by backtrace nodes. - Each entry is a string specifying a command name. + ``command`` + An optional member present when the node represents a command + invocation within the file. The value is an unsigned integer + 0-based index into the backtrace ``commands`` array. - ``files`` - A JSON array listing CMake language files referenced by backtrace nodes. - Each entry is a string specifying the path to a file, represented - with forward slashes. If the file is inside the top-level source - directory then the path is specified relative to that directory. - Otherwise the path is absolute. + ``parent`` + An optional member present when the node is not the bottom of + the call stack. The value is an unsigned integer 0-based index + of another entry in the backtrace ``nodes`` array. + +``commands`` + A JSON array listing command names referenced by backtrace nodes. + Each entry is a string specifying a command name. + +``files`` + A JSON array listing CMake language files referenced by backtrace nodes. + Each entry is a string specifying the path to a file, represented + with forward slashes. If the file is inside the top-level source + directory then the path is specified relative to that directory. + Otherwise the path is absolute. Object Kind "cache" ------------------- @@ -1244,7 +1471,7 @@ The members specific to ``toolchains`` objects are: ``language`` A JSON string specifying the toolchain language, like C or CXX. Language - names are the same as langauge names that can be passed to the + names are the same as language names that can be passed to the :command:`project` command. Because CMake only supports a single toolchain per language, this field can be used as a key. diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 7bc490f7014..df13dd0aed9 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -94,6 +94,8 @@ String Comparisons .. genex:: $ + .. versionadded:: 3.12 + ``1`` if ``string`` is member of the semicolon-separated ``list``, else ``0``. Uses case-sensitive comparisons. @@ -111,10 +113,14 @@ String Comparisons .. genex:: $ + .. versionadded:: 3.7 + ``1`` if ``v1`` is a version less than or equal to ``v2``, else ``0``. .. genex:: $ + .. versionadded:: 3.7 + ``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``. Variable Queries @@ -122,12 +128,14 @@ Variable Queries .. genex:: $ + .. versionadded:: 3.12 + ``1`` if ``target`` exists, else ``0``. .. genex:: $ - ``1`` if config is any one of the entries in ``cfgs``, else ``0``. This is a - case-insensitive comparison. The mapping in + ``1`` if config is any one of the entries in comma-separated list + ``cfgs``, else ``0``. This is a case-insensitive comparison. The mapping in :prop_tgt:`MAP_IMPORTED_CONFIG_` is also considered by this expression when it is evaluated on a property on an :prop_tgt:`IMPORTED` target. @@ -155,6 +163,8 @@ Variable Queries .. genex:: $ + .. versionadded:: 3.15 + where ``compiler_ids`` is a comma-separated list. ``1`` if the CMake's compiler id of the CUDA compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. @@ -162,6 +172,8 @@ Variable Queries .. genex:: $ + .. versionadded:: 3.16 + where ``compiler_ids`` is a comma-separated list. ``1`` if the CMake's compiler id of the Objective-C compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. @@ -169,6 +181,8 @@ Variable Queries .. genex:: $ + .. versionadded:: 3.16 + where ``compiler_ids`` is a comma-separated list. ``1`` if the CMake's compiler id of the Objective-C++ compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. @@ -181,8 +195,17 @@ Variable Queries of the entries in ``compiler_ids``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_ID` variable. +.. genex:: $ + + where ``compiler_ids`` is a comma-separated list. + ``1`` if the CMake's compiler id of the HIP compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + See also the :variable:`CMAKE__COMPILER_ID` variable. + .. genex:: $ + .. versionadded:: 3.19 + where ``compiler_ids`` is a comma-separated list. ``1`` if the CMake's compiler id of the ISPC compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. @@ -200,16 +223,22 @@ Variable Queries .. genex:: $ + .. versionadded:: 3.15 + ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_VERSION` variable. .. genex:: $ + .. versionadded:: 3.16 + ``1`` if the version of the OBJC compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_VERSION` variable. .. genex:: $ + .. versionadded:: 3.16 + ``1`` if the version of the OBJCXX compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_VERSION` variable. @@ -218,8 +247,15 @@ Variable Queries ``1`` if the version of the Fortran compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_VERSION` variable. +.. genex:: $ + + ``1`` if the version of the HIP compiler matches ``version``, otherwise ``0``. + See also the :variable:`CMAKE__COMPILER_VERSION` variable. + .. genex:: $ + .. versionadded:: 3.19 + ``1`` if the version of the ISPC compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_VERSION` variable. @@ -232,6 +268,8 @@ Variable Queries .. genex:: $ + .. versionadded:: 3.1 + where ``features`` is a comma-spearated list. Evaluates to ``1`` if all of the ``features`` are available for the 'head' target, and ``0`` otherwise. If this expression is used while evaluating @@ -245,6 +283,8 @@ Variable Queries .. genex:: $ + .. versionadded:: 3.15 + ``1`` when the language used for compilation unit matches ``language`` and the CMake's compiler id of the language compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. This expression is a short form @@ -282,6 +322,8 @@ Variable Queries .. genex:: $ + .. versionadded:: 3.3 + ``1`` when the language used for compilation unit matches any of the entries in ``languages``, otherwise ``0``. This expression may be used to specify compile options, compile definitions, and include directories for source files of a @@ -328,6 +370,8 @@ Variable Queries .. genex:: $ + .. versionadded:: 3.18 + ``1`` when the language used for link step matches ``language`` and the CMake's compiler id of the language linker matches any one of the entries in ``compiler_ids``, otherwise ``0``. This expression is a short form for the @@ -368,6 +412,8 @@ Variable Queries .. genex:: $ + .. versionadded:: 3.18 + ``1`` when the language used for link step matches any of the entries in ``languages``, otherwise ``0``. This expression may be used to specify link libraries, link options, link directories and link dependencies of a @@ -431,6 +477,8 @@ Variable Queries .. genex:: $ + .. versionadded:: 3.18 + Returns the list if it is the device link step, an empty list otherwise. The device link step is controlled by :prop_tgt:`CUDA_SEPARABLE_COMPILATION` and :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties and @@ -439,6 +487,8 @@ Variable Queries .. genex:: $ + .. versionadded:: 3.18 + Returns the list if it is the normal link step, an empty list otherwise. This expression is mainly useful when a device link step is also involved (see ``$`` generator expression). This expression can only @@ -521,6 +571,8 @@ that must be ``0`` or ``1``. .. genex:: $ + .. versionadded:: 3.8 + Evaluates to ``true_string`` if ``condition`` is ``1``. Otherwise evaluates to ``false_string``. @@ -545,10 +597,14 @@ String Transformations .. genex:: $ + .. versionadded:: 3.15 + Removes duplicated items in the given ``list``. .. genex:: $ + .. versionadded:: 3.15 + Includes or removes items from ``list`` that match the regular expression ``regex``. .. genex:: $ @@ -561,12 +617,16 @@ String Transformations .. genex:: $ + .. versionadded:: 3.12 + Content of ``expr`` evaluated as a generator expression in the current context. This enables consumption of generator expressions whose evaluation results itself in generator expressions. .. genex:: $ + .. versionadded:: 3.12 + Content of ``expr`` evaluated as a generator expression in the context of ``tgt`` target. This enables consumption of custom target properties that themselves contain generator expressions. @@ -635,11 +695,15 @@ Variable Queries .. genex:: $ + .. versionadded:: 3.16 + The CMake's compiler id of the OBJC compiler used. See also the :variable:`CMAKE__COMPILER_ID` variable. .. genex:: $ + .. versionadded:: 3.16 + The CMake's compiler id of the OBJCXX compiler used. See also the :variable:`CMAKE__COMPILER_ID` variable. @@ -648,8 +712,15 @@ Variable Queries The CMake's compiler id of the Fortran compiler used. See also the :variable:`CMAKE__COMPILER_ID` variable. +.. genex:: $ + + The CMake's compiler id of the HIP compiler used. + See also the :variable:`CMAKE__COMPILER_ID` variable. + .. genex:: $ + .. versionadded:: 3.19 + The CMake's compiler id of the ISPC compiler used. See also the :variable:`CMAKE__COMPILER_ID` variable. @@ -670,11 +741,15 @@ Variable Queries .. genex:: $ + .. versionadded:: 3.16 + The version of the OBJC compiler used. See also the :variable:`CMAKE__COMPILER_VERSION` variable. .. genex:: $ + .. versionadded:: 3.16 + The version of the OBJCXX compiler used. See also the :variable:`CMAKE__COMPILER_VERSION` variable. @@ -683,13 +758,22 @@ Variable Queries The version of the Fortran compiler used. See also the :variable:`CMAKE__COMPILER_VERSION` variable. +.. genex:: $ + + The version of the HIP compiler used. + See also the :variable:`CMAKE__COMPILER_VERSION` variable. + .. genex:: $ + .. versionadded:: 3.19 + The version of the ISPC compiler used. See also the :variable:`CMAKE__COMPILER_VERSION` variable. .. genex:: $ + .. versionadded:: 3.3 + The compile language of source files when evaluating compile options. See :ref:`the related boolean expression ` @@ -698,6 +782,8 @@ Variable Queries .. genex:: $ + .. versionadded:: 3.18 + The link language of target when evaluating link options. See :ref:`the related boolean expression ` ``$`` @@ -728,6 +814,8 @@ which is just the string ``tgt``. .. genex:: $ + .. versionadded:: 3.12 + The target name ``tgt`` if the target exists, an empty string otherwise. Note that ``tgt`` is not added as a dependency of the target this @@ -739,6 +827,8 @@ which is just the string ``tgt``. .. genex:: $ + .. versionadded:: 3.15 + Base name of ``tgt``, i.e. ``$`` without prefix and suffix. For example, if the ``tgt`` filename is ``libbase.so``, the base name is ``base``. @@ -758,6 +848,8 @@ which is just the string ``tgt``. .. genex:: $ + .. versionadded:: 3.15 + Prefix of the ``tgt`` filename (such as ``lib``). See also the :prop_tgt:`PREFIX` target property. @@ -767,6 +859,8 @@ which is just the string ``tgt``. .. genex:: $ + .. versionadded:: 3.15 + Suffix of the ``tgt`` filename (extension such as ``.so`` or ``.exe``). See also the :prop_tgt:`SUFFIX` target property. @@ -797,6 +891,8 @@ which is just the string ``tgt``. .. genex:: $ + .. versionadded:: 3.15 + Base name of file used to link the target ``tgt``, i.e. ``$`` without prefix and suffix. For example, if target file name is ``libbase.a``, the base name is ``base``. @@ -815,6 +911,8 @@ which is just the string ``tgt``. .. genex:: $ + .. versionadded:: 3.15 + Prefix of file used to link target ``tgt``. See also the :prop_tgt:`PREFIX` and :prop_tgt:`IMPORT_PREFIX` target @@ -825,6 +923,8 @@ which is just the string ``tgt``. .. genex:: $ + .. versionadded:: 3.15 + Suffix of file used to link where ``tgt`` is the name of a target. The suffix corresponds to the file extension (such as ".so" or ".lib"). @@ -868,6 +968,8 @@ which is just the string ``tgt``. .. genex:: $ + .. versionadded:: 3.1 + Full path to the linker generated program database file (.pdb) where ``tgt`` is the name of a target. @@ -877,6 +979,8 @@ which is just the string ``tgt``. .. genex:: $ + .. versionadded:: 3.15 + Base name of the linker generated program database file (.pdb) where ``tgt`` is the name of a target. @@ -895,6 +999,8 @@ which is just the string ``tgt``. .. genex:: $ + .. versionadded:: 3.1 + Name of the linker generated program database file (.pdb). Note that ``tgt`` is not added as a dependency of the target this @@ -902,6 +1008,8 @@ which is just the string ``tgt``. .. genex:: $ + .. versionadded:: 3.1 + Directory of the linker generated program database file (.pdb). Note that ``tgt`` is not added as a dependency of the target this @@ -909,6 +1017,8 @@ which is just the string ``tgt``. .. genex:: $ + .. versionadded:: 3.9 + Full path to the bundle directory (``my.app``, ``my.framework``, or ``my.bundle``) where ``tgt`` is the name of a target. @@ -917,6 +1027,8 @@ which is just the string ``tgt``. .. genex:: $ + .. versionadded:: 3.9 + Full path to the bundle content directory where ``tgt`` is the name of a target. For the macOS SDK it leads to ``my.app/Contents``, ``my.framework``, or ``my.bundle/Contents``. For all other SDKs (e.g. iOS) it leads to @@ -940,11 +1052,46 @@ which is just the string ``tgt``. :ref:`Target Usage Requirements` this is the consuming target rather than the target specifying the requirement. +.. genex:: $ + + .. versionadded:: 3.21 + + List of DLLs that the target depends on at runtime. This is determined by + the locations of all the ``SHARED`` and ``MODULE`` targets in the target's + transitive dependencies. Using this generator expression on targets other + than executables, ``SHARED`` libraries, and ``MODULE`` libraries is an error. + On non-DLL platforms, it evaluates to an empty string. + + This generator expression can be used to copy all of the DLLs that a target + depends on into its output directory in a ``POST_BUILD`` custom command. For + example: + + .. code-block:: cmake + + find_package(foo CONFIG REQUIRED) # package generated by install(EXPORT) + + add_executable(exe main.c) + target_link_libraries(exe PRIVATE foo::foo foo::bar) + add_custom_command(TARGET exe POST_BUILD + COMMAND ${CMAKE_COMMAND} -E copy $ $ + COMMAND_EXPAND_LISTS + ) + + .. note:: + + :ref:`Imported Targets` are supported only if they know the location + of their ``.dll`` files. An imported ``SHARED`` or ``MODULE`` library + must have :prop_tgt:`IMPORTED_LOCATION` set to its ``.dll`` file. See + the :ref:`add_library imported libraries ` + section for details. Many :ref:`Find Modules` produce imported targets + with the ``UNKNOWN`` type and therefore will be ignored. + .. genex:: $ Content of the install prefix when the target is exported via - :command:`install(EXPORT)`, or when evaluated in - :prop_tgt:`INSTALL_NAME_DIR`, and empty otherwise. + :command:`install(EXPORT)`, or when evaluated in the + :prop_tgt:`INSTALL_NAME_DIR` property or the ``INSTALL_NAME_DIR`` argument of + :command:`install(RUNTIME_DEPENDENCY_SET)`, and empty otherwise. Output-Related Expressions -------------------------- @@ -957,6 +1104,8 @@ Output-Related Expressions .. genex:: $ + .. versionadded:: 3.1 + Content of ``...`` except when evaluated in a link interface while propagating :ref:`Target Usage Requirements`, in which case it is the empty string. @@ -982,18 +1131,24 @@ Output-Related Expressions .. genex:: $ + .. versionadded:: 3.1 + List of objects resulting from build of ``objLib``. .. genex:: $ + .. versionadded:: 3.4 + Content of ``...`` converted to shell path style. For example, slashes are converted to backslashes in Windows shells and drive letters are converted to posix paths in MSYS shells. The ``...`` must be an absolute path. - The ``...`` may be a :ref:`semicolon-separated list ` - of paths, in which case each path is converted individually and a result - list is generated using the shell path separator (``:`` on POSIX and - ``;`` on Windows). Be sure to enclose the argument containing this genex - in double quotes in CMake source code so that ``;`` does not split arguments. + + .. versionadded:: 3.14 + The ``...`` may be a :ref:`semicolon-separated list ` + of paths, in which case each path is converted individually and a result + list is generated using the shell path separator (``:`` on POSIX and + ``;`` on Windows). Be sure to enclose the argument containing this genex + in double quotes in CMake source code so that ``;`` does not split arguments. .. genex:: $ diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst index 8ca2bf6444e..663b18d4651 100644 --- a/Help/manual/cmake-generators.7.rst +++ b/Help/manual/cmake-generators.7.rst @@ -91,6 +91,7 @@ Visual Studio Generators /generator/Visual Studio 14 2015 /generator/Visual Studio 15 2017 /generator/Visual Studio 16 2019 + /generator/Visual Studio 17 2022 Other Generators ^^^^^^^^^^^^^^^^ diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 17c1a1e5c35..141eeaa76ca 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -185,6 +185,7 @@ They are normally called through the :command:`find_package` command. /module/FindMPEG /module/FindMPEG2 /module/FindMPI + /module/FindMsys /module/FindODBC /module/FindOpenACC /module/FindOpenAL diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst index 4b2934a8edd..5c109ff6722 100644 --- a/Help/manual/cmake-packages.7.rst +++ b/Help/manual/cmake-packages.7.rst @@ -74,7 +74,9 @@ package. By setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_` variable to ``TRUE``, the ```` package will not be searched, and will always -be ``NOTFOUND``. +be ``NOTFOUND``. Likewise, setting the +:variable:`CMAKE_REQUIRE_FIND_PACKAGE_` to ``TRUE`` will make the +package REQUIRED. .. _`Config File Packages`: @@ -447,7 +449,7 @@ be true. This can be tested with logic in the package configuration file: set(_supported_components Plot Table) foreach(_comp ${ClimbingStats_FIND_COMPONENTS}) - if (NOT ";${_supported_components};" MATCHES _comp) + if (NOT ";${_supported_components};" MATCHES ";${_comp};") set(ClimbingStats_FOUND False) set(ClimbingStats_NOT_FOUND_MESSAGE "Unsupported component: ${_comp}") endif() diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index bd6b2f0ca9f..3df4f9fa79e 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,28 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used to determine whether to report an error on use of deprecated macros or functions. +Policies Introduced by CMake 3.22 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0128: Selection of language standard and extension flags improved. + CMP0127: cmake_dependent_option() supports full Condition Syntax. + +Policies Introduced by CMake 3.21 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0126: set(CACHE) does not remove a normal variable of the same name. + CMP0125: find_(path|file|library|program) have consistent behavior for cache variables. + CMP0124: foreach() loop variables are only available in the loop scope. + CMP0123: ARMClang cpu/arch compile and link flags must be set explicitly. + CMP0122: UseSWIG use standard library name conventions for csharp language. + CMP0121: The list command detects invalid indices. + Policies Introduced by CMake 3.20 ================================= diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst index 467818dfa67..74e9faea9d2 100644 --- a/Help/manual/cmake-presets.7.rst +++ b/Help/manual/cmake-presets.7.rst @@ -39,7 +39,7 @@ The root object recognizes the following fields: ``version`` A required integer representing the version of the JSON schema. - The supported versions are ``1`` and ``2``. + The supported versions are ``1``, ``2``, and ``3``. ``cmakeMinimumRequired`` @@ -70,17 +70,17 @@ The root object recognizes the following fields: ``configurePresets`` An optional array of `Configure Preset`_ objects. - This is allowed in preset files specifying version 1 or above. + This is allowed in preset files specifying version ``1`` or above. ``buildPresets`` An optional array of `Build Preset`_ objects. - This is allowed in preset files specifying version 2 or above. + This is allowed in preset files specifying version ``2`` or above. ``testPresets`` An optional array of `Test Preset`_ objects. - This is allowed in preset files specifying version 2 or above. + This is allowed in preset files specifying version ``2`` or above. Configure Preset ^^^^^^^^^^^^^^^^ @@ -119,6 +119,11 @@ that may contain the following fields: This field can also be a string, which is equivalent to an array containing one string. +``condition`` + + An optional `Condition`_ object. This is allowed in preset files specifying + version ``3`` or above. + ``vendor`` An optional map containing vendor-specific information. CMake does not @@ -140,7 +145,9 @@ that may contain the following fields: An optional string representing the generator to use for the preset. If ``generator`` is not specified, it must be inherited from the - ``inherits`` preset (unless this preset is ``hidden``). + ``inherits`` preset (unless this preset is ``hidden``). In version ``3`` + or above, this field may be omitted to fall back to regular generator + discovery procedure. Note that for Visual Studio generators, unlike in the command line ``-G`` argument, you cannot include the platform name in the generator name. Use @@ -175,13 +182,30 @@ that may contain the following fields: ignore the field, but the IDE can use them to set up the environment before invoking CMake. +``toolchainFile`` + + An optional string representing the path to the toolchain file. + This field supports `macro expansion`_. If a relative path is specified, + it is calculated relative to the build directory, and if not found, + relative to the source directory. This field takes precedence over any + :variable:`CMAKE_TOOLCHAIN_FILE` value. It is allowed in preset files + specifying version ``3`` or above. + ``binaryDir`` An optional string representing the path to the output binary directory. This field supports `macro expansion`_. If a relative path is specified, it is calculated relative to the source directory. If ``binaryDir`` is not specified, it must be inherited from the ``inherits`` preset (unless this - preset is ``hidden``). + preset is ``hidden``). In version ``3`` or above, this field may be + omitted. + +``installDir`` + + An optional string representing the path to the installation directory. + This field supports `macro expansion`_. If a relative path is specified, + it is calculated relative to the source directory. This is allowed in + preset files specifying version ``3`` or above. ``cmakeExecutable`` @@ -338,6 +362,11 @@ that may contain the following fields: This field can also be a string, which is equivalent to an array containing one string. +``condition`` + + An optional `Condition`_ object. This is allowed in preset files specifying + version ``3`` or above. + ``vendor`` An optional map containing vendor-specific information. CMake does not @@ -373,6 +402,19 @@ that may contain the following fields: are applied. Setting a variable to ``null`` causes it to not be set, even if a value was inherited from another preset. + .. note:: + + For a CMake project using ExternalProject with a configuration preset + having environment variables needed in the ExternalProject, use a build + preset that inherits that configuration preset or the ExternalProject + will not have the environment variables set in the configuration preset. + Example: suppose the host defaults to one compiler (say Clang) + and the user wishes to use another compiler (say GCC). Set configuration + preset environment variables ``CC`` and ``CXX`` and use a build preset + that inherits that configuration preset. Otherwise the ExternalProject + may use a different (system default) compiler than the top-level CMake + project. + ``configurePreset`` An optional string specifying the name of a configure preset to @@ -457,6 +499,11 @@ that may contain the following fields: This field can also be a string, which is equivalent to an array containing one string. +``condition`` + + An optional `Condition`_ object. This is allowed in preset files specifying + version ``3`` or above. + ``vendor`` An optional map containing vendor-specific information. CMake does not @@ -609,7 +656,8 @@ that may contain the following fields: An optional string specifying a regex for test names. Equivalent to passing ``--tests-regex`` on the command line. This field supports - macro expansion. + macro expansion. CMake regex syntax is described under + :ref:`string(REGEX) `. ``label`` @@ -782,6 +830,103 @@ that may contain the following fields: Equivalent to passing ``--no-tests=ignore`` on the command line. +Condition +^^^^^^^^^ + +The ``condition`` field of a preset, allowed in preset files specifying version +``3`` or above, is used to determine whether or not the preset is enabled. For +example, this can be used to disable a preset on platforms other than Windows. +``condition`` may be either a boolean, ``null``, or an object. If it is a +boolean, the boolean indicates whether the preset is enabled or disabled. If it +is ``null``, the preset is enabled, but the ``null`` condition is not inherited +by any presets that may inherit from the preset. Sub-conditions (for example in +a ``not``, ``anyOf``, or ``allOf`` condition) may not be ``null``. If it is an +object, it has the following fields: + +``type`` + + A required string with one of the following values: + + ``"const"`` + + Indicates that the condition is constant. This is equivalent to using a + boolean in place of the object. The condition object will have the + following additional fields: + + ``value`` + + A required boolean which provides a constant value for the condition's + evaluation. + + ``"equals"`` + + ``"notEquals"`` + + Indicates that the condition compares two strings to see if they are equal + (or not equal). The condition object will have the following additional + fields: + + ``lhs`` + + First string to compare. This field supports macro expansion. + + ``rhs`` + + Second string to compare. This field supports macro expansion. + + ``"inList"`` + + ``"notInList"`` + + Indicates that the condition searches for a string in a list of strings. + The condition object will have the following additional fields: + + ``string`` + + A required string to search for. This field supports macro expansion. + + ``list`` + + A required list of strings to search. This field supports macro + expansion, and uses short-circuit evaluation. + + ``"matches"`` + + ``"notMatches"`` + + Indicates that the condition searches for a regular expression in a string. + The condition object will have the following additional fields: + + ``string`` + + A required string to search. This field supports macro expansion. + + ``regex`` + + A required regular expression to search for. This field supports macro + expansion. + + ``"anyOf"`` + + ``"allOf"`` + + Indicates that the condition is an aggregation of zero or more nested + conditions. The condition object will have the following additional fields: + + ``conditions`` + + A required array of condition objects. These conditions use short-circuit + evaluation. + + ``"not"`` + + Indicates that the condition is an inversion of another condition. The + condition object will have the following additional fields: + + ``condition`` + + A required condition object. + Macro Expansion ^^^^^^^^^^^^^^^ @@ -823,6 +968,12 @@ Recognized macros include: test presets, this will evaluate to the generator specified by ``configurePreset``. +``${hostSystemName}`` + + The name of the host operating system. Contains the same value as + :variable:`CMAKE_HOST_SYSTEM_NAME`. This is allowed in preset files + specifying version ``3`` or above. + ``${dollar}`` A literal dollar sign (``$``). diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index af170dabdea..bb5dba3f01b 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -21,6 +21,7 @@ Properties of Global Scope /prop_gbl/AUTOMOC_SOURCE_GROUP /prop_gbl/AUTOMOC_TARGETS_FOLDER /prop_gbl/AUTORCC_SOURCE_GROUP + /prop_gbl/AUTOUIC_SOURCE_GROUP /prop_gbl/CMAKE_C_KNOWN_FEATURES /prop_gbl/CMAKE_CUDA_KNOWN_FEATURES /prop_gbl/CMAKE_CXX_KNOWN_FEATURES @@ -73,6 +74,7 @@ Properties on Directories /prop_dir/DEFINITIONS /prop_dir/EXCLUDE_FROM_ALL /prop_dir/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM + /prop_dir/IMPORTED_TARGETS /prop_dir/INCLUDE_DIRECTORIES /prop_dir/INCLUDE_REGULAR_EXPRESSION /prop_dir/INTERPROCEDURAL_OPTIMIZATION @@ -200,6 +202,7 @@ Properties on Targets /prop_tgt/EXPORT_NAME /prop_tgt/EXPORT_PROPERTIES /prop_tgt/FOLDER + /prop_tgt/Fortran_BUILDING_INSTRINSIC_MODULES /prop_tgt/Fortran_FORMAT /prop_tgt/Fortran_MODULE_DIRECTORY /prop_tgt/Fortran_PREPROCESS @@ -211,6 +214,10 @@ Properties on Targets /prop_tgt/GHS_NO_SOURCE_GROUP_FILE /prop_tgt/GNUtoMS /prop_tgt/HAS_CXX + /prop_tgt/HIP_ARCHITECTURES + /prop_tgt/HIP_EXTENSIONS + /prop_tgt/HIP_STANDARD + /prop_tgt/HIP_STANDARD_REQUIRED /prop_tgt/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM /prop_tgt/IMPORTED /prop_tgt/IMPORTED_COMMON_LANGUAGE_RUNTIME @@ -270,7 +277,11 @@ Properties on Targets /prop_tgt/LANG_COMPILER_LAUNCHER /prop_tgt/LANG_CPPCHECK /prop_tgt/LANG_CPPLINT + /prop_tgt/LANG_EXTENSIONS /prop_tgt/LANG_INCLUDE_WHAT_YOU_USE + /prop_tgt/LANG_LINKER_LAUNCHER + /prop_tgt/LANG_STANDARD + /prop_tgt/LANG_STANDARD_REQUIRED /prop_tgt/LANG_VISIBILITY_PRESET /prop_tgt/LIBRARY_OUTPUT_DIRECTORY /prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG @@ -402,7 +413,9 @@ Properties on Targets /prop_tgt/XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY /prop_tgt/XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY /prop_tgt/XCODE_EMBED_type + /prop_tgt/XCODE_EMBED_type_CODE_SIGN_ON_COPY /prop_tgt/XCODE_EMBED_type_PATH + /prop_tgt/XCODE_EMBED_type_REMOVE_HEADERS_ON_COPY /prop_tgt/XCODE_EXPLICIT_FILE_TYPE /prop_tgt/XCODE_GENERATE_SCHEME /prop_tgt/XCODE_LINK_BUILD_PHASE_MODE @@ -444,6 +457,7 @@ Properties on Tests /prop_test/DEPENDS /prop_test/DISABLED /prop_test/ENVIRONMENT + /prop_test/ENVIRONMENT_MODIFICATION /prop_test/FAIL_REGULAR_EXPRESSION /prop_test/FIXTURES_CLEANUP /prop_test/FIXTURES_REQUIRED diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst index 1ededee1899..a94131049d0 100644 --- a/Help/manual/cmake-toolchains.7.rst +++ b/Help/manual/cmake-toolchains.7.rst @@ -96,8 +96,8 @@ Cross Compiling =============== If :manual:`cmake(1)` is invoked with the command line parameter -``-DCMAKE_TOOLCHAIN_FILE=path/to/file``, the file will be loaded early to set -values for the compilers. +``--toolchain path/to/file`` or ``-DCMAKE_TOOLCHAIN_FILE=path/to/file``, the +file will be loaded early to set values for the compilers. The :variable:`CMAKE_CROSSCOMPILING` variable is set to true when CMake is cross-compiling. diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 4317dd40719..4ed0b2e62a7 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -53,6 +53,7 @@ Variables that Provide Information /variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION /variable/CMAKE_EDIT_COMMAND /variable/CMAKE_EXECUTABLE_SUFFIX + /variable/CMAKE_EXECUTABLE_SUFFIX_LANG /variable/CMAKE_EXTRA_GENERATOR /variable/CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES /variable/CMAKE_FIND_DEBUG_MODE @@ -70,6 +71,7 @@ Variables that Provide Information /variable/CMAKE_JOB_POOL_PRECOMPILE_HEADER /variable/CMAKE_JOB_POOLS /variable/CMAKE_LANG_COMPILER_AR + /variable/CMAKE_LANG_COMPILER_FRONTEND_VARIANT /variable/CMAKE_LANG_COMPILER_RANLIB /variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX /variable/CMAKE_LINK_LIBRARY_SUFFIX @@ -123,6 +125,9 @@ Variables that Provide Information /variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR /variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE /variable/CMAKE_VS_PLATFORM_TOOLSET_VERSION + /variable/CMAKE_VS_TARGET_FRAMEWORK_VERSION + /variable/CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER + /variable/CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM /variable/CMAKE_XCODE_BUILD_SYSTEM @@ -130,6 +135,7 @@ Variables that Provide Information /variable/PROJECT-NAME_BINARY_DIR /variable/PROJECT-NAME_DESCRIPTION /variable/PROJECT-NAME_HOMEPAGE_URL + /variable/PROJECT-NAME_IS_TOP_LEVEL /variable/PROJECT-NAME_SOURCE_DIR /variable/PROJECT-NAME_VERSION /variable/PROJECT-NAME_VERSION_MAJOR @@ -139,6 +145,7 @@ Variables that Provide Information /variable/PROJECT_BINARY_DIR /variable/PROJECT_DESCRIPTION /variable/PROJECT_HOMEPAGE_URL + /variable/PROJECT_IS_TOP_LEVEL /variable/PROJECT_NAME /variable/PROJECT_SOURCE_DIR /variable/PROJECT_VERSION @@ -228,6 +235,7 @@ Variables that Change Behavior /variable/CMAKE_PROJECT_INCLUDE_BEFORE /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE + /variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName /variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY /variable/CMAKE_STAGING_PREFIX /variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS @@ -243,6 +251,8 @@ Variables that Change Behavior /variable/CMAKE_SYSTEM_LIBRARY_PATH /variable/CMAKE_SYSTEM_PREFIX_PATH /variable/CMAKE_SYSTEM_PROGRAM_PATH + /variable/CMAKE_TLS_CAINFO + /variable/CMAKE_TLS_VERIFY /variable/CMAKE_USER_MAKE_RULES_OVERRIDE /variable/CMAKE_WARN_DEPRECATED /variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION @@ -421,8 +431,10 @@ Variables that Control the Build /variable/CMAKE_LANG_CPPCHECK /variable/CMAKE_LANG_CPPLINT /variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE + /variable/CMAKE_LANG_LINKER_LAUNCHER /variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG /variable/CMAKE_LANG_LINK_LIBRARY_FLAG + /variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG /variable/CMAKE_LANG_VISIBILITY_PRESET /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG @@ -433,6 +445,7 @@ Variables that Control the Build /variable/CMAKE_LINK_LIBRARY_FILE_FLAG /variable/CMAKE_LINK_LIBRARY_FLAG /variable/CMAKE_LINK_WHAT_YOU_USE + /variable/CMAKE_LINK_WHAT_YOU_USE_CHECK /variable/CMAKE_MACOSX_BUNDLE /variable/CMAKE_MACOSX_RPATH /variable/CMAKE_MAP_IMPORTED_CONFIG_CONFIG @@ -519,6 +532,10 @@ Variables for Languages /variable/CMAKE_Fortran_MODDIR_DEFAULT /variable/CMAKE_Fortran_MODDIR_FLAG /variable/CMAKE_Fortran_MODOUT_FLAG + /variable/CMAKE_HIP_ARCHITECTURES + /variable/CMAKE_HIP_EXTENSIONS + /variable/CMAKE_HIP_STANDARD + /variable/CMAKE_HIP_STANDARD_REQUIRED /variable/CMAKE_ISPC_HEADER_DIRECTORY /variable/CMAKE_ISPC_HEADER_SUFFIX /variable/CMAKE_ISPC_INSTRUCTION_SETS @@ -540,6 +557,8 @@ Variables for Languages /variable/CMAKE_LANG_CREATE_SHARED_LIBRARY /variable/CMAKE_LANG_CREATE_SHARED_MODULE /variable/CMAKE_LANG_CREATE_STATIC_LIBRARY + /variable/CMAKE_LANG_EXTENSIONS + /variable/CMAKE_LANG_EXTENSIONS_DEFAULT /variable/CMAKE_LANG_FLAGS /variable/CMAKE_LANG_FLAGS_CONFIG /variable/CMAKE_LANG_FLAGS_CONFIG_INIT @@ -568,8 +587,11 @@ Variables for Languages /variable/CMAKE_LANG_SIMULATE_VERSION /variable/CMAKE_LANG_SIZEOF_DATA_PTR /variable/CMAKE_LANG_SOURCE_FILE_EXTENSIONS + /variable/CMAKE_LANG_STANDARD + /variable/CMAKE_LANG_STANDARD_DEFAULT /variable/CMAKE_LANG_STANDARD_INCLUDE_DIRECTORIES /variable/CMAKE_LANG_STANDARD_LIBRARIES + /variable/CMAKE_LANG_STANDARD_REQUIRED /variable/CMAKE_OBJC_EXTENSIONS /variable/CMAKE_OBJC_STANDARD /variable/CMAKE_OBJC_STANDARD_REQUIRED @@ -644,6 +666,7 @@ Variables for CTest /variable/CTEST_RESOURCE_SPEC_FILE /variable/CTEST_RUN_CURRENT_SCRIPT /variable/CTEST_SCP_COMMAND + /variable/CTEST_SCRIPT_DIRECTORY /variable/CTEST_SITE /variable/CTEST_SUBMIT_URL /variable/CTEST_SOURCE_DIRECTORY @@ -667,6 +690,7 @@ Variables for CPack /variable/CPACK_ABSOLUTE_DESTINATION_FILES /variable/CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY + /variable/CPACK_CUSTOM_INSTALL_VARIABLES /variable/CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION /variable/CPACK_INCLUDE_TOPLEVEL_DIRECTORY /variable/CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 02828ac5b14..e23ddd8231c 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -381,9 +381,9 @@ Options ``--preset ``, ``--preset=`` Reads a :manual:`preset ` from ``/CMakePresets.json`` and - ``/CMakeUserPresets.json``. The preset specifies the - generator and the build directory, and optionally a list of variables and - other arguments to pass to CMake. The current working directory must contain + ``/CMakeUserPresets.json``. The preset may specify the + generator and the build directory, and a list of variables and other + arguments to pass to CMake. The current working directory must contain CMake preset files. The :manual:`CMake GUI ` can also recognize ``CMakePresets.json`` and ``CMakeUserPresets.json`` files. For full details on these files, see :manual:`cmake-presets(7)`. @@ -408,7 +408,8 @@ project binary tree: .. code-block:: shell - cmake --build [ | --preset ] [] [-- ] + cmake --build [] [-- ] + cmake --build --preset [] [-- ] This abstracts a native build tool's command-line interface with the following options: @@ -575,6 +576,12 @@ Available commands are: ``true`` if the generator supports toolsets and ``false`` otherwise. ``platformSupport`` ``true`` if the generator supports platforms and ``false`` otherwise. + ``supportedPlatforms`` + .. versionadded:: 3.21 + + Optional member that may be present when the generator supports + platform specification via :variable:`CMAKE_GENERATOR_PLATFORM` + (``-A ...``). The value is a list of platforms known to be supported. ``extraGenerators`` A list of strings with all the extra generators compatible with the generator. @@ -702,7 +709,7 @@ Available commands are: ``remove [-f] ...`` .. deprecated:: 3.17 - Remove the file(s). The planned behaviour was that if any of the + Remove the file(s). The planned behavior was that if any of the listed files already do not exist, the command returns a non-zero exit code, but no message is logged. The ``-f`` option changes the behavior to return a zero exit code (i.e. success) in such situations instead. diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 175359d6c14..d66c5a9d587 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -134,6 +134,14 @@ Options This option tells CTest to write all its output to a ```` log file. +``--output-junit `` + Write test results in JUnit format. + + This option tells CTest to write test results to ```` in JUnit XML + format. If ```` already exists, it will be overwritten. If using the + ``-S`` option to run a dashboard script, use the ``OUTPUT_JUNIT`` keyword + with the :command:`ctest_test` command instead. + ``-N,--show-only[=]`` Disable actual execution of tests. @@ -152,10 +160,14 @@ Options See `Show as JSON Object Model`_. ``-L , --label-regex `` - Run tests with labels matching regular expression. + Run tests with labels matching regular expression as described under + :ref:`string(REGEX) `. This option tells CTest to run only the tests whose labels match the - given regular expression. + given regular expression. When more than one ``-L`` option is given, + a test will only be run if each regular expression matches at least one + of the test's labels (i.e. the multiple ``-L`` labels form an ``AND`` + relationship). See `Label Matching`_. ``-R , --tests-regex `` Run tests matching regular expression. @@ -173,7 +185,10 @@ Options Exclude tests with labels matching regular expression. This option tells CTest to NOT run the tests whose labels match the - given regular expression. + given regular expression. When more than one ``-LE`` option is given, + a test will only be excluded if each regular expression matches at least one + of the test's labels (i.e. the multiple ``-LE`` labels form an ``AND`` + relationship). See `Label Matching`_. ``-FA , --fixture-exclude-any `` Exclude fixtures matching ```` from automatically adding any tests to @@ -309,11 +324,13 @@ Options Set the interactive mode to ``0`` or ``1``. This option causes CTest to run tests in either an interactive mode - or a non-interactive mode. On Windows this means that in - non-interactive mode, all system debug pop up windows are blocked. - In dashboard mode (``Experimental``, ``Nightly``, ``Continuous``), the default - is non-interactive. When just running tests not for a dashboard the - default is to allow popups and interactive debugging. + or a non-interactive mode. In dashboard mode (``Experimental``, ``Nightly``, + ``Continuous``), the default is non-interactive. In non-interactive mode, + the environment variable :envvar:`DASHBOARD_TEST_FROM_CTEST` is set. + + Prior to CMake 3.11, interactive mode on Windows allowed system debug + popup windows to appear. Now, due to CTest's use of ``libuv`` to launch + test processes, all system debug popup windows are always blocked. ``--no-label-summary`` Disable timing summary information for labels. @@ -398,6 +415,46 @@ Specify the directory in which to look for tests. .. include:: OPTIONS_HELP.txt +.. _`Label Matching`: + +Label Matching +============== + +Tests may have labels attached to them. Tests may be included +or excluded from a test run by filtering on the labels. +Each individual filter is a regular expression applied to +the labels attached to a test. + +When ``-L`` is used, in order for a test to be included in a +test run, each regular expression must match at least one +label. Using more than one ``-L`` option means "match **all** +of these". + +The ``-LE`` option works just like ``-L``, but excludes tests +rather than including them. A test is excluded if each regular +expression matches at least one label. + +If a test has no labels attached to it, then ``-L`` will never +include that test, and ``-LE`` will never exclude that test. +As an example of tests with labels, consider five tests, +with the following labels: + +* *test1* has labels *tuesday* and *production* +* *test2* has labels *tuesday* and *test* +* *test3* has labels *wednesday* and *production* +* *test4* has label *wednesday* +* *test5* has labels *friday* and *test* + +Running ``ctest`` with ``-L tuesday -L test`` will select *test2*, which has +both labels. Running CTest with ``-L test`` will select *test2* and +*test5*, because both of them have a label that matches that regular +expression. + +Because the matching works with regular expressions, take note that +running CTest with ``-L es`` will match all five tests. +To select the *tuesday* and *wednesday* tests together, use a single +regular expression that matches either of them, like ``-L "tue|wed"``. + .. _`Label and Subproject Summary`: Label and Subproject Summary @@ -407,6 +464,10 @@ CTest prints timing summary information for each ``LABEL`` and subproject associated with the tests run. The label time summary will not include labels that are mapped to subprojects. +.. versionadded:: 3.22 + Labels added dynamically during test execution are also reported in the + timing summary. See :ref:`Additional Labels`. + When the :prop_test:`PROCESSORS` test property is set, CTest will display a weighted test timing result in label and subproject summaries. The time is reported with `sec*proc` instead of just `sec`. @@ -1043,6 +1104,8 @@ Configuration settings include: * `CTest Script`_ variable: :variable:`CTEST_TEST_TIMEOUT` * :module:`CTest` module variable: ``DART_TESTING_TIMEOUT`` +To report extra test values to CDash, see :ref:`Additional Test Measurements`. + .. _`CTest Coverage Step`: CTest Coverage Step @@ -1619,4 +1682,4 @@ See Also .. include:: LINKS.txt -.. _`CDash`: http://cdash.org/ +_`CDash`: https://cdash.org diff --git a/Help/manual/presets/example.json b/Help/manual/presets/example.json index dfc2910a2c4..b08445a471d 100644 --- a/Help/manual/presets/example.json +++ b/Help/manual/presets/example.json @@ -1,8 +1,8 @@ { - "version": 2, + "version": 3, "cmakeMinimumRequired": { "major": 3, - "minor": 20, + "minor": 21, "patch": 0 }, "configurePresets": [ @@ -35,6 +35,17 @@ "displayName": "Ninja Multi-Config", "description": "Default build using Ninja Multi-Config generator", "generator": "Ninja Multi-Config" + }, + { + "name": "windows-only", + "inherits": "default", + "displayName": "Windows-only configuration", + "description": "This build is only available on Windows", + "condition": { + "type": "equals", + "lhs": "${hostSystemName}", + "rhs": "Windows" + } } ], "buildPresets": [ diff --git a/Help/manual/presets/schema.json b/Help/manual/presets/schema.json index f8faf3dd7f1..7852550dcfa 100644 --- a/Help/manual/presets/schema.json +++ b/Help/manual/presets/schema.json @@ -11,7 +11,7 @@ }, "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, "vendor": { "$ref": "#/definitions/vendor" }, - "configurePresets": { "$ref": "#/definitions/configurePresets"} + "configurePresets": { "$ref": "#/definitions/configurePresetsV1"} }, "additionalProperties": false }, @@ -23,9 +23,23 @@ }, "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, "vendor": { "$ref": "#/definitions/vendor" }, - "configurePresets": { "$ref": "#/definitions/configurePresets"}, - "buildPresets": { "$ref": "#/definitions/buildPresets"}, - "testPresets": { "$ref": "#/definitions/testPresets"} + "configurePresets": { "$ref": "#/definitions/configurePresetsV1"}, + "buildPresets": { "$ref": "#/definitions/buildPresetsV2"}, + "testPresets": { "$ref": "#/definitions/testPresetsV2"} + }, + "additionalProperties": false + }, + { + "properties": { + "version": { + "const": 3, + "description": "A required integer representing the version of the JSON schema." + }, + "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, + "vendor": { "$ref": "#/definitions/vendor" }, + "configurePresets": { "$ref": "#/definitions/configurePresetsV3"}, + "buildPresets": { "$ref": "#/definitions/buildPresetsV3"}, + "testPresets": { "$ref": "#/definitions/testPresetsV3"} }, "additionalProperties": false } @@ -58,7 +72,34 @@ "description": "An optional map containing vendor-specific information. CMake does not interpret the contents of this field except to verify that it is a map if it does exist. However, the keys should be a vendor-specific domain name followed by a /-separated path. For example, the Example IDE 1.0 could use example.com/ExampleIDE/1.0. The value of each field can be anything desired by the vendor, though will typically be a map.", "properties": {} }, - "configurePresets": { + "configurePresetsItemsV3": { + "type": "array", + "description": "A configure preset object.", + "items": { + "type": "object", + "description": "A configure preset object.", + "properties": { + "binaryDir": { + "type": "string", + "description": "An optional string representing the path to the output binary directory. This field supports macro expansion. If a relative path is specified, it is calculated relative to the source directory. If binaryDir is not specified, the path is calculated using regular methods." + }, + "generator": { + "type": "string", + "description": "An optional string representing the generator to use for the preset. If generator is not specified, the normal generator discovery procedure is used. Note that for Visual Studio generators, unlike in the command line -G argument, you cannot include the platform name in the generator name. Use the architecture field instead." + }, + "toolchainFile": { + "type": "string", + "description": "An optional string representing the path to the toolchain file. This field supports macro expansion. If a relative path is specified, it is calculated relative to the build directory, and if not found, relative to the source directory." + }, + "installDir": { + "type": "string", + "description": "An optional string representing the path to the installation directory. This field supports macro expansion. If a relative path is specified, it is calculated relative to the source directory." + }, + "condition": { "$ref": "#/definitions/topCondition" } + } + } + }, + "configurePresetsItemsV1": { "type": "array", "description": "An optional array of configure preset objects.", "items": { @@ -83,7 +124,7 @@ }, { "type": "array", - "description": "An optional array of strings representing the names of presets to inherit from. The preset will inherit all of the fields from the inherits presets by default (except name, hidden, inherits, description, and displayName), but can override them as desired. If multiple inherits presets provide conflicting values for the same field, the earlier preset in the inherits list will be preferred. Presets in CMakePresets.json may not inherit from presets in CMakeUserPresets.json.", + "description": "An optional array of strings representing the names of presets to inherit from. The preset will inherit all of the fields from the inherits presets by default (except name, hidden, inherits, description, and displayName), but can override them as desired. If multiple inherits presets provide conflicting values for the same field, the earlier preset in the inherits list will be preferred. Presets in CMakePresets.json must not inherit from presets in CMakeUserPresets.json.", "items": { "type": "string", "description": "An optional string representing the name of the preset to inherit from.", @@ -302,6 +343,37 @@ }, "additionalProperties": false } + } + } + }, + "configurePresetsV3": { + "type": "array", + "description": "An optional array of configure preset objects.", + "allOf": [ + { "$ref": "#/definitions/configurePresetsItemsV1" }, + { "$ref": "#/definitions/configurePresetsItemsV3" } + ], + "items": { + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "generator": {}, + "architecture": {}, + "toolset": {}, + "toolchainFile": {}, + "binaryDir": {}, + "installDir": {}, + "cmakeExecutable": {}, + "cacheVariables": {}, + "environment": {}, + "warnings": {}, + "errors": {}, + "debug": {}, + "condition": {} }, "required": [ "name" @@ -309,7 +381,48 @@ "additionalProperties": false } }, - "buildPresets": { + "configurePresetsV1": { + "type": "array", + "description": "An optional array of configure preset objects.", + "allOf": [ + { "$ref": "#/definitions/configurePresetsItemsV1" } + ], + "items": { + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "generator": {}, + "architecture": {}, + "toolset": {}, + "binaryDir": {}, + "cmakeExecutable": {}, + "cacheVariables": {}, + "environment": {}, + "warnings": {}, + "errors": {}, + "debug": {} + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, + "buildPresetsItemsV3": { + "type": "array", + "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.", + "items": { + "type": "object", + "properties": { + "condition": { "$ref": "#/definitions/topCondition" } + } + } + }, + "buildPresetsItemsV2": { "type": "array", "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.", "items": { @@ -333,7 +446,7 @@ }, { "type": "array", - "description": "An optional array of strings representing the names of build presets to inherit from. The preset will inherit all of the fields from the inherits presets by default (except name, hidden, inherits, description, and displayName), but can override them as desired. If multiple inherits presets provide conflicting values for the same field, the earlier preset in the inherits list will be preferred. Presets in CMakePresets.json may not inherit from presets in CMakeUserPresets.json.", + "description": "An optional array of strings representing the names of build presets to inherit from. The preset will inherit all of the fields from the inherits presets by default (except name, hidden, inherits, description, and displayName), but can override them as desired. If multiple inherits presets provide conflicting values for the same field, the earlier preset in the inherits list will be preferred. Presets in CMakePresets.json must not inherit from presets in CMakeUserPresets.json.", "items": { "type": "string", "description": "An optional string representing the name of the preset to inherit from.", @@ -425,13 +538,86 @@ } } }, + "required": [ + "name" + ] + } + }, + "buildPresetsV3": { + "type": "array", + "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.", + "allOf": [ + { "$ref": "#/definitions/buildPresetsItemsV3" }, + { "$ref": "#/definitions/buildPresetsItemsV2" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "jobs": {}, + "targets": {}, + "configuration": {}, + "cleanFirst": {}, + "verbose": {}, + "nativeToolOptions": {}, + "condition": {} + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, + "buildPresetsV2": { + "type": "array", + "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.", + "allOf": [ + { "$ref": "#/definitions/buildPresetsItemsV2" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "jobs": {}, + "targets": {}, + "configuration": {}, + "cleanFirst": {}, + "verbose": {}, + "nativeToolOptions": {} + }, "required": [ "name" ], "additionalProperties": false } }, - "testPresets": { + "testPresetsItemsV3": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.", + "items": { + "type": "object", + "properties": { + "condition": { "$ref": "#/definitions/topCondition" } + } + } + }, + "testPresetsItemsV2": { "type": "array", "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.", "items": { @@ -455,7 +641,7 @@ }, { "type": "array", - "description": "An optional array of strings representing the names of test presets to inherit from. The preset will inherit all of the fields from the inherits presets by default (except name, hidden, inherits, description, and displayName), but can override them as desired. If multiple inherits presets provide conflicting values for the same field, the earlier preset in the inherits list will be preferred. Presets in CMakePresets.json may not inherit from presets in CMakeUserPresets.json.", + "description": "An optional array of strings representing the names of test presets to inherit from. The preset will inherit all of the fields from the inherits presets by default (except name, hidden, inherits, description, and displayName), but can override them as desired. If multiple inherits presets provide conflicting values for the same field, the earlier preset in the inherits list will be preferred. Presets in CMakePresets.json must not inherit from presets in CMakeUserPresets.json.", "items": { "type": "string", "description": "An optional string representing the name of the preset to inherit from.", @@ -741,11 +927,314 @@ "additionalProperties": false } }, + "required": [ + "name" + ] + } + }, + "testPresetsV3": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.", + "allOf": [ + { "$ref": "#/definitions/testPresetsItemsV2" }, + { "$ref": "#/definitions/testPresetsItemsV3" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "configuration": {}, + "overwriteConfigurationFile": {}, + "output": {}, + "filter": {}, + "execution": {}, + "condition": {} + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, + "testPresetsV2": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.", + "allOf": [ + { "$ref": "#/definitions/testPresetsItemsV2" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "configuration": {}, + "overwriteConfigurationFile": {}, + "output": {}, + "filter": {}, + "execution": {} + }, "required": [ "name" ], "additionalProperties": false } + }, + "condition": { + "anyOf": [ + { + "type": "boolean", + "description": "A boolean which provides a constant value for the condition's evaluation." + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "const" + }, + "value": { + "type": "boolean", + "description": "A required boolean which provides a constant value for the condition's evaluation." + } + }, + "required": [ + "type", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "equals" + }, + "lhs": { + "type": "string", + "description": "First string to compare. This field supports macro expansion." + }, + "rhs": { + "type": "string", + "description": "Second string to compare. This field supports macro expansion." + } + }, + "required": [ + "type", + "lhs", + "rhs" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "notEquals" + }, + "lhs": { + "type": "string", + "description": "First string to compare. This field supports macro expansion." + }, + "rhs": { + "type": "string", + "description": "Second string to compare. This field supports macro expansion." + } + }, + "required": [ + "type", + "lhs", + "rhs" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "inList" + }, + "string": { + "type": "string", + "description": "A required string to search for. This field supports macro expansion." + }, + "list": { + "type": "array", + "description": "A required list of strings to search. This field supports macro expansion, and uses short-circuit evaluation.", + "items": { + "type": "string" + } + } + }, + "required": [ + "type", + "string", + "list" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "notInList" + }, + "string": { + "type": "string", + "description": "A required string to search for. This field supports macro expansion." + }, + "list": { + "type": "array", + "description": "A required list of strings to search. This field supports macro expansion, and uses short-circuit evaluation.", + "items": { + "type": "string" + } + } + }, + "required": [ + "type", + "string", + "list" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "matches" + }, + "string": { + "type": "string", + "description": "A required string to search. This field supports macro expansion." + }, + "regex": { + "type": "string", + "description": "A required regular expression to search for. This field supports macro expansion." + } + }, + "required": [ + "type", + "string", + "regex" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "notMatches" + }, + "string": { + "type": "string", + "description": "A required string to search. This field supports macro expansion." + }, + "regex": { + "type": "string", + "description": "A required regular expression to search for. This field supports macro expansion." + } + }, + "required": [ + "type", + "string", + "regex" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "anyOf" + }, + "conditions": { + "type": "array", + "description": "A required array of condition objects. These conditions use short-circuit evaluation.", + "items": { "$ref": "#/definitions/condition" } + } + }, + "required": [ + "type", + "conditions" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "allOf" + }, + "conditions": { + "type": "array", + "description": "A required array of condition objects. These conditions use short-circuit evaluation.", + "items": { "$ref": "#/definitions/condition" } + } + }, + "required": [ + "type", + "conditions" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "not" + }, + "condition": { "$ref": "#/definitions/condition" } + }, + "required": [ + "type", + "condition" + ], + "additionalProperties": false + } + ] + }, + "topCondition": { + "anyOf": [ + { "$ref": "#/definitions/condition" }, + { + "type": "null", + "description": "Null indicates that the condition always evaluates to true and is not inherited." + } + ] } } } diff --git a/Help/module/FindMsys.rst b/Help/module/FindMsys.rst new file mode 100644 index 00000000000..fc5495ce703 --- /dev/null +++ b/Help/module/FindMsys.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindMsys.cmake diff --git a/Help/policy/CMP0077.rst b/Help/policy/CMP0077.rst index 174cde91bcd..482125a7947 100644 --- a/Help/policy/CMP0077.rst +++ b/Help/policy/CMP0077.rst @@ -46,9 +46,15 @@ name: variable of the same name exists. The normal variable is not removed. The cache entry is not created or updated and is ignored if it exists. +See :policy:`CMP0126` for a similar policy for the :command:`set(CACHE)` +command, but note that there are some differences in ``NEW`` behavior +between the two policies. + This policy was introduced in CMake version 3.13. CMake version |release| warns when the policy is not set and uses ``OLD`` behavior. Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` -explicitly. +explicitly within a project. Use the :variable:`CMAKE_POLICY_DEFAULT_CMP0077 +>` variable to set the policy for +a third-party project in a subdirectory without modifying it. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0102.rst b/Help/policy/CMP0102.rst index 78b5584808a..08024bfd384 100644 --- a/Help/policy/CMP0102.rst +++ b/Help/policy/CMP0102.rst @@ -22,6 +22,8 @@ already exist in the cache. This policy was introduced in CMake version 3.17. Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. Unlike many policies, CMake version |release| does *not* warn -when this policy is not set and simply uses ``OLD`` behavior. +when this policy is not set and simply uses ``OLD`` behavior. See +documentation of the :variable:`CMAKE_POLICY_WARNING_CMP0102 +>` variable to control the warning. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0104.rst b/Help/policy/CMP0104.rst index 7c7a16e3784..b125729ddf3 100644 --- a/Help/policy/CMP0104.rst +++ b/Help/policy/CMP0104.rst @@ -41,7 +41,7 @@ Examples .. code-block:: cmake - set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES 35 50 72) + set_target_properties(tgt PROPERTIES CUDA_ARCHITECTURES "35;50;72") Generates code for real and virtual architectures ``30``, ``50`` and ``72``. diff --git a/Help/policy/CMP0110.rst b/Help/policy/CMP0110.rst index 25a00089f19..6977d41e507 100644 --- a/Help/policy/CMP0110.rst +++ b/Help/policy/CMP0110.rst @@ -8,7 +8,7 @@ CMP0110 :command:`add_test` can now (officially) create tests with whitespace and other special characters in its name. Before CMake version 3.19 that was not allowed, however, it was possible to work around this limitation by explicitly -putting escaped quotes arount the test's name in the ``add_test`` command. +putting escaped quotes around the test's name in the ``add_test`` command. Although never officially supported several projects in the wild found and implemented this workaround. However, the new change which officially allows diff --git a/Help/policy/CMP0121.rst b/Help/policy/CMP0121.rst new file mode 100644 index 00000000000..326e7d59558 --- /dev/null +++ b/Help/policy/CMP0121.rst @@ -0,0 +1,21 @@ +CMP0121 +------- + +.. versionadded:: 3.21 + +The :command:`list` command now detects invalid indices. + +Prior to CMake version 3.21, the :command:`list` command's ``GET``, +``INSERT``, ``SUBLIST``, and ``REMOVE_AT`` subcommands did not detect invalid +index arguments. + +The ``OLD`` behavior of this policy is for invalid indices to be treated as +their integer value (if any) at the start of the string. For example, +``2good4you`` is a ``2`` and ``not_an_integer`` is a ``0``. The ``NEW`` +behavior is for invalid indices to trigger an error. + +This policy was introduced in CMake version 3.21. CMake version |release| +warns when the policy is not set and uses ``OLD`` behavior. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0122.rst b/Help/policy/CMP0122.rst new file mode 100644 index 00000000000..1ff8c48621e --- /dev/null +++ b/Help/policy/CMP0122.rst @@ -0,0 +1,17 @@ +CMP0122 +------- + +.. versionadded:: 3.21 + +:module:`UseSWIG` use library name conventions for ``CSharp`` language. + +Starting with CMake 3.21, :module:`UseSWIG` generates now a library using +default naming conventions. This policy provides compatibility with projects +that expect the legacy behavior. + +This policy was introduced in CMake version 3.21. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0123.rst b/Help/policy/CMP0123.rst new file mode 100644 index 00000000000..e09b5ec9788 --- /dev/null +++ b/Help/policy/CMP0123.rst @@ -0,0 +1,32 @@ +CMP0123 +------- + +.. versionadded:: 3.21 + +``ARMClang`` cpu/arch compile and link flags must be set explicitly. + +CMake 3.20 and lower automatically maps the :variable:`CMAKE_SYSTEM_PROCESSOR` +variable and an undocumented ``CMAKE_SYSTEM_ARCH`` to compile and link options +for ``ARMClang``. For example, the ``-mcpu=cortex-m33`` flag is added when +:variable:`CMAKE_SYSTEM_PROCESSOR` equals ``cortex-m33``. CMake requires +projects to set either variable or it raises a fatal error. However, the +project may need to additionally specify CPU features using e.g. +``-mcpu=cortex-m33+nodsp``, conflicting with the ``-mcpu=cortex-m33`` added +by CMake. This results in either link errors or unusable binaries. + +CMake 3.21 and above prefer instead to not add any cpu/arch compile and link +flags automatically. Instead, projects must specify them explicitly. +This policy provides compatibility for projects that have not been updated. + +The ``OLD`` behavior of this policy requires projects that use ``ARMClang`` +to set either :variable:`CMAKE_SYSTEM_PROCESSOR` or ``CMAKE_SYSTEM_ARCH`` +and it automatically adds a compile option ``-mcpu=`` or ``-march=`` and +a link option ``--cpu=`` based on those variables. The ``NEW`` behavior +does not add compile or link options, and projects are responsible for +setting correct options. + +This policy was introduced in CMake version 3.21. CMake version |release| +warns when the policy is not set and uses ``OLD`` behavior. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0124.rst b/Help/policy/CMP0124.rst new file mode 100644 index 00000000000..3935166ad5e --- /dev/null +++ b/Help/policy/CMP0124.rst @@ -0,0 +1,18 @@ +CMP0124 +------- + +.. versionadded:: 3.21 + +When this policy is set to ``NEW``, the scope of loop variables defined by the +:command:`foreach` command is restricted to the loop only. They will be unset +at the end of the loop. + +The ``OLD`` behavior for this policy still clears the loop variables at the end +of the loop, but does not unset them. This leaves them as defined, but empty. + +This policy was introduced in CMake version 3.21. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike many policies, CMake version |release| does *not* warn when the policy +is not set and simply uses ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0125.rst b/Help/policy/CMP0125.rst new file mode 100644 index 00000000000..0b1704e90bc --- /dev/null +++ b/Help/policy/CMP0125.rst @@ -0,0 +1,42 @@ +CMP0125 +------- + +.. versionadded:: 3.21 + +The :command:`find_file`, :command:`find_path`, :command:`find_library` and +:command:`find_program` commands cache their result in the variable specified +by their first argument. Prior to CMake 3.21, if a cache variable of that +name already existed before the call but the cache variable had no type, any +non-cache variable of the same name would be discarded and the cache variable +was always used (see also :policy:`CMP0126` for a different but similar +behavior). This contradicts the convention that a non-cache variable should +take precedence over a cache variable of the same name. Such a situation can +arise if a user sets a cache variable on the command line without specifying +a type, such as ``cmake -DMYVAR=blah ...`` instead of +``cmake -DMYVAR:FILEPATH=blah``. + +Related to the above, if a cache variable of the specified name already exists +and it *does* have a type, the various ``find_...()`` commands would return +that value unchanged. In particular, if it contained a relative path, it +would not be converted to an absolute path in this situation. + +When policy ``CMP0125`` is set to ``OLD`` or is unset, the behavior is as +described above. When it is set to ``NEW``, the behavior is as follows: + +* If a non-cache variable of the specified name exists when the ``find_...()`` + command is called, its value will be used regardless of whether a cache + variable of the same name already exists or not. A cache variable will not + be created in this case if no such cache variable existed before. + If a cache variable of the specified name did already exist, the cache will + be updated to match the non-cache variable. + +* The various ``find...()`` commands will always provide an absolute path in + the result variable, except where a relative path provided by a cache or + non-cache variable cannot be resolved to an existing path. + +This policy was introduced in CMake version 3.21. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike many policies, CMake version |release| does *not* warn when the policy +is not set and simply uses ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0126.rst b/Help/policy/CMP0126.rst new file mode 100644 index 00000000000..1b6995762dd --- /dev/null +++ b/Help/policy/CMP0126.rst @@ -0,0 +1,34 @@ +CMP0126 +------- + +.. versionadded:: 3.21 + +When this policy is set to ``NEW``, the :command:`set(CACHE)` command does not +remove any normal variable of the same name from the current scope. +The ``OLD`` behavior removes any normal variable of the same name from the +current scope in the following situations: + +* No cache variable of that name existed previously. + +* A cache variable of that name existed previously, but it had no type. + This can occur when the variable was set on the command line using a form + like ``cmake -DMYVAR=blah`` instead of ``cmake -DMYVAR:STRING=blah``. + +Note that the ``NEW`` behavior has an important difference to the similar +``NEW`` behavior of policy :policy:`CMP0077`. The :command:`set(CACHE)` +command always sets the cache variable if it did not exist previously, +regardless of the ``CMP0126`` policy setting. The :command:`option` command +will *not* set the cache variable if a non-cache variable of the same name +already exists and :policy:`CMP0077` is set to ``NEW``. + +Policy ``CMP0126`` was introduced in CMake version 3.21. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly +within a project. Use the :variable:`CMAKE_POLICY_DEFAULT_CMP0126 +>` variable to set the policy for +a third-party project in a subdirectory without modifying it. +Unlike many policies, CMake version |release| does *not* warn when the policy +is not set and simply uses ``OLD`` behavior. See documentation of the +:variable:`CMAKE_POLICY_WARNING_CMP0126 >` +variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0127.rst b/Help/policy/CMP0127.rst new file mode 100644 index 00000000000..2106110d4c0 --- /dev/null +++ b/Help/policy/CMP0127.rst @@ -0,0 +1,34 @@ +CMP0127 +------- + +.. versionadded:: 3.22 + +:command:`cmake_dependent_option` supports full :ref:`Condition Syntax`. + +The ```` parameter accepts a :ref:`semicolon-separated list ` of conditions. CMake 3.21 and lower evaluates each +``condition`` as ``if(${condition})``, which does not properly handle +conditions with nested paren groups. CMake 3.22 and above instead prefer +to evaluate each ``condition`` as ``if()``, where ```` +is re-parsed as if literally written in a call to :command:`if`. This +allows expressions like:: + + "A AND (B OR C)" + +but requires expressions like:: + + "FOO MATCHES (UPPER|lower)" + +to be re-written as:: + + "FOO MATCHES \"(UPPER|lower)\"" + +Policy ``CMP0127`` provides compatibility for projects that have not +been updated to expect the new behavior. + +This policy was introduced in CMake version 3.22. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0128.rst b/Help/policy/CMP0128.rst new file mode 100644 index 00000000000..604a146a160 --- /dev/null +++ b/Help/policy/CMP0128.rst @@ -0,0 +1,71 @@ +CMP0128 +------- + +.. versionadded:: 3.22 + +When this policy is set to ``NEW``: + +* :prop_tgt:`_EXTENSIONS` is initialized to + :variable:`CMAKE__EXTENSIONS` if set, otherwise falling back to + :variable:`CMAKE__EXTENSIONS_DEFAULT`. + +* Extensions are correctly enabled/disabled if :prop_tgt:`_STANDARD` is + unset or satisfied by the default. + +* Standard mode-affecting flags aren't added unless necessary to achieve the + specified mode. + +The ``OLD`` behavior: + +* Initializes :prop_tgt:`_EXTENSIONS` to + :variable:`CMAKE__EXTENSIONS` if set, otherwise falling back to ``ON``. + +* Always adds a flag if :prop_tgt:`_STANDARD` is set and + :prop_tgt:`_STANDARD_REQUIRED` is ``OFF``. + +* If :prop_tgt:`_STANDARD` is unset: + + * Doesn't disable extensions even if :prop_tgt:`_EXTENSIONS` is + ``OFF``. + + * Fails to enable extensions if :prop_tgt:`_EXTENSIONS` is ``ON`` + except for the ``IAR`` compiler. + +Code may need to be updated for the ``NEW`` behavior in the following cases: + +* If a standard mode flag previously overridden by CMake's and not used during + compiler detection now takes effect due to CMake no longer adding one as the + default detected is appropriate. + + Such code should be converted to either: + + * Use :prop_tgt:`_STANDARD` and :prop_tgt:`_EXTENSIONS` instead + of manually adding flags. + + * Or ensure the manually-specified flags are used during compiler detection. + +* If extensions were disabled without :prop_tgt:`_STANDARD` being set + CMake previously wouldn't actually disable extensions. + + Such code should be updated to not disable extensions if they are required. + +* If extensions were enabled/disabled when :prop_tgt:`_STANDARD` was + satisfied by the compiler's default CMake previously wouldn't actually + enable/disable extensions. + + Such code should be updated to set the correct extensions mode. + +If compiler flags affecting the standard mode are used during compiler +detection (for example in :manual:`a toolchain file ` +using :variable:`CMAKE__FLAGS_INIT`) then they will affect the detected +default :variable:`standard _STANDARD_DEFAULT>` and +:variable:`extensions _EXTENSIONS_DEFAULT>`. + +Unlike many policies, CMake version |release| does *not* warn when the policy +is not set and simply uses the ``OLD`` behavior. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +See documentation of the +:variable:`CMAKE_POLICY_WARNING_CMP0128 >` +variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/prop_dir/BUILDSYSTEM_TARGETS.rst b/Help/prop_dir/BUILDSYSTEM_TARGETS.rst index 5c5893dfc71..c998488b4af 100644 --- a/Help/prop_dir/BUILDSYSTEM_TARGETS.rst +++ b/Help/prop_dir/BUILDSYSTEM_TARGETS.rst @@ -11,3 +11,5 @@ and :command:`add_custom_target` commands. The list does not include any :ref:`Interface Libraries`. Each entry in the list is the logical name of a target, suitable to pass to the :command:`get_property` command ``TARGET`` option. + +See also the :prop_dir:`IMPORTED_TARGETS` directory property. diff --git a/Help/prop_dir/IMPORTED_TARGETS.rst b/Help/prop_dir/IMPORTED_TARGETS.rst new file mode 100644 index 00000000000..fea8a93d49c --- /dev/null +++ b/Help/prop_dir/IMPORTED_TARGETS.rst @@ -0,0 +1,14 @@ +IMPORTED_TARGETS +---------------- + +.. versionadded:: 3.21 + +This read-only directory property contains a +:ref:`semicolon-separated list ` of +:ref:`Imported Targets` added in the directory by calls to the +:command:`add_library` and :command:`add_executable` commands. +Each entry in the list is the logical name of a target, suitable +to pass to the :command:`get_property` command ``TARGET`` option +when called in the same directory. + +See also the :prop_dir:`BUILDSYSTEM_TARGETS` directory property. diff --git a/Help/prop_gbl/AUTOGEN_SOURCE_GROUP.rst b/Help/prop_gbl/AUTOGEN_SOURCE_GROUP.rst index 2e3232062ad..07c732bd471 100644 --- a/Help/prop_gbl/AUTOGEN_SOURCE_GROUP.rst +++ b/Help/prop_gbl/AUTOGEN_SOURCE_GROUP.rst @@ -3,15 +3,16 @@ AUTOGEN_SOURCE_GROUP .. versionadded:: 3.9 -Name of the :command:`source_group` for :prop_tgt:`AUTOMOC` and -:prop_tgt:`AUTORCC` generated files. +Name of the :command:`source_group` for :prop_tgt:`AUTOMOC`, +:prop_tgt:`AUTORCC` and :prop_tgt:`AUTOUIC` generated files. -Files generated by :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTORCC` are not always -known at configure time and therefore can't be passed to -:command:`source_group`. -:prop_gbl:`AUTOGEN_SOURCE_GROUP` an be used instead to generate or select -a source group for :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTORCC` generated files. +Files generated by :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTORCC` and +:prop_tgt:`AUTOUIC` are not always known at configure time and therefore can't +be passed to :command:`source_group`. +:prop_gbl:`AUTOGEN_SOURCE_GROUP` can be used instead to generate or select +a source group for :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTORCC` and +:prop_tgt:`AUTOUIC` generated files. -For :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTORCC` specific overrides see -:prop_gbl:`AUTOMOC_SOURCE_GROUP` and :prop_gbl:`AUTORCC_SOURCE_GROUP` -respectively. +For :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTORCC` and :prop_tgt:`AUTOUIC` specific +overrides see :prop_gbl:`AUTOMOC_SOURCE_GROUP`, :prop_gbl:`AUTORCC_SOURCE_GROUP` +and :prop_gbl:`AUTOUIC_SOURCE_GROUP` respectively. diff --git a/Help/prop_gbl/AUTOUIC_SOURCE_GROUP.rst b/Help/prop_gbl/AUTOUIC_SOURCE_GROUP.rst new file mode 100644 index 00000000000..79ebfe0eccc --- /dev/null +++ b/Help/prop_gbl/AUTOUIC_SOURCE_GROUP.rst @@ -0,0 +1,9 @@ +AUTOUIC_SOURCE_GROUP +-------------------- + +.. versionadded:: 3.21 + +Name of the :command:`source_group` for :prop_tgt:`AUTOUIC` generated files. + +When set this is used instead of :prop_gbl:`AUTOGEN_SOURCE_GROUP` for +files generated by :prop_tgt:`AUTOUIC`. diff --git a/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst index 6bbb870f151..3a1797356b0 100644 --- a/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst @@ -32,4 +32,6 @@ The features known to this version of CMake are: Compiler mode is at least CUDA/C++ 20. ``cuda_std_23`` + .. versionadded:: 3.20 + Compiler mode is at least CUDA/C++ 23. diff --git a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst index 73c0b34eef6..1a913fb65dd 100644 --- a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst @@ -18,6 +18,8 @@ The features known to this version of CMake are listed below. High level meta features indicating C++ standard support ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. versionadded:: 3.8 + The following meta features indicate general support for the associated language standard. It reflects the language support claimed by the compiler, but it does not necessarily imply complete conformance to that standard. @@ -35,9 +37,13 @@ but it does not necessarily imply complete conformance to that standard. Compiler mode is at least C++ 17. ``cxx_std_20`` + .. versionadded:: 3.12 + Compiler mode is at least C++ 20. ``cxx_std_23`` + .. versionadded:: 3.20 + Compiler mode is at least C++ 23. Low level individual compile features diff --git a/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst index 7166381aa4d..97da697e052 100644 --- a/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst @@ -13,7 +13,12 @@ The features listed here may be used with the :command:`target_compile_features` command. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. -The features known to this version of CMake are: +The features known to this version of CMake are listed below. + +High level meta features indicating C standard support +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.8 ``c_std_90`` Compiler mode is at least C 90. @@ -24,6 +29,19 @@ The features known to this version of CMake are: ``c_std_11`` Compiler mode is at least C 11. +``c_std_17`` + .. versionadded:: 3.21 + + Compiler mode is at least C 17. + +``c_std_23`` + .. versionadded:: 3.21 + + Compiler mode is at least C 23. + +Low level individual compile features +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + ``c_function_prototypes`` Function prototypes, as defined in ``ISO/IEC 9899:1990``. diff --git a/Help/prop_sf/COMPILE_FLAGS.rst b/Help/prop_sf/COMPILE_FLAGS.rst index c211b89acac..eefe7bff3a1 100644 --- a/Help/prop_sf/COMPILE_FLAGS.rst +++ b/Help/prop_sf/COMPILE_FLAGS.rst @@ -4,8 +4,11 @@ COMPILE_FLAGS Additional flags to be added when compiling this source file. The ``COMPILE_FLAGS`` property, managed as a string, sets additional compiler -flags used to build source files. Use :prop_sf:`COMPILE_DEFINITIONS` to pass -additional preprocessor definitions. +flags used that will be added to the list of compile flags when this source +file builds. The flags will be added after target-wide flags (except in +some cases not supported by the :generator:`Visual Studio 9 2008` generator). + +Use :prop_sf:`COMPILE_DEFINITIONS` to pass additional preprocessor definitions. Contents of ``COMPILE_FLAGS`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` diff --git a/Help/prop_sf/COMPILE_OPTIONS.rst b/Help/prop_sf/COMPILE_OPTIONS.rst index a694c3e61eb..84c543a2c17 100644 --- a/Help/prop_sf/COMPILE_OPTIONS.rst +++ b/Help/prop_sf/COMPILE_OPTIONS.rst @@ -5,9 +5,10 @@ COMPILE_OPTIONS List of additional options to pass to the compiler. -This property holds a :ref:`semicolon-separated list ` of options -and will be added to the list of compile flags when this -source file builds. +This property holds a :ref:`semicolon-separated list ` +of options and will be added to the list of compile flags when this source +file builds. The options will be added after target-wide options (except in +some cases not supported by the :generator:`Visual Studio 9 2008` generator). Contents of ``COMPILE_OPTIONS`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual diff --git a/Help/prop_sf/GENERATED.rst b/Help/prop_sf/GENERATED.rst index 6ef45802268..216dfe8da33 100644 --- a/Help/prop_sf/GENERATED.rst +++ b/Help/prop_sf/GENERATED.rst @@ -32,9 +32,10 @@ The :ref:`Makefile Generators` will remove ``GENERATED`` files during ``make clean``. Generated sources may be hidden in some IDE tools, while in others they might -be shown. For the special case of sources generated by CMake's :prop_tgt:`AUTOMOC` -or :prop_tgt:`AUTORCC` functionality, the :prop_gbl:`AUTOGEN_SOURCE_GROUP`, -:prop_gbl:`AUTOMOC_SOURCE_GROUP` and :prop_gbl:`AUTORCC_SOURCE_GROUP` target +be shown. For the special case of sources generated by CMake's :prop_tgt:`AUTOMOC`, +:prop_tgt:`AUTORCC` or :prop_tgt:`AUTOUIC` functionality, the +:prop_gbl:`AUTOGEN_SOURCE_GROUP`, :prop_gbl:`AUTOMOC_SOURCE_GROUP`, +:prop_gbl:`AUTORCC_SOURCE_GROUP` and :prop_gbl:`AUTOUIC_SOURCE_GROUP` target properties may influence where the generated sources are grouped in the project's file lists. diff --git a/Help/prop_sf/LANGUAGE.rst b/Help/prop_sf/LANGUAGE.rst index f14c176ca5c..a9b56387044 100644 --- a/Help/prop_sf/LANGUAGE.rst +++ b/Help/prop_sf/LANGUAGE.rst @@ -6,8 +6,8 @@ Specify the programming language in which a source file is written. A property that can be set to indicate what programming language the source file is. If it is not set the language is determined based on the file extension. Typical values are ``CXX`` (i.e. C++), ``C``, -``CSharp``, ``CUDA``, ``Fortran``, ``ISPC``, and ``ASM``. Setting this -property for a file means this file will be compiled. Do not set this +``CSharp``, ``CUDA``, ``Fortran``, ``HIP``, ``ISPC``, and ``ASM``. Setting +this property for a file means this file will be compiled. Do not set this for headers or files that should not be compiled. .. versionchanged:: 3.20 diff --git a/Help/prop_sf/VS_SETTINGS.rst b/Help/prop_sf/VS_SETTINGS.rst index 322f5a6d7f1..871e36e855d 100644 --- a/Help/prop_sf/VS_SETTINGS.rst +++ b/Help/prop_sf/VS_SETTINGS.rst @@ -3,7 +3,12 @@ VS_SETTINGS .. versionadded:: 3.18 -Set any item metadata on a non-built file. +Set any item metadata on a file. + +.. versionadded:: 3.22 + + This property is honored for all source file types. + Previously it worked only for non-built files. Takes a list of ``Key=Value`` pairs. Tells the Visual Studio generator to set ``Key`` to ``Value`` as item metadata on the file. diff --git a/Help/prop_test/ENVIRONMENT.rst b/Help/prop_test/ENVIRONMENT.rst index 102c7922f6b..43bcdbe1b01 100644 --- a/Help/prop_test/ENVIRONMENT.rst +++ b/Help/prop_test/ENVIRONMENT.rst @@ -5,5 +5,5 @@ Specify environment variables that should be defined for running a test. If set to a list of environment variables and values of the form ``MYVAR=value`` those environment variables will be defined while running -the test. The environment is restored to its previous state after the -test is done. +the test. The environment changes from this property do not affect other +tests. diff --git a/Help/prop_test/ENVIRONMENT_MODIFICATION.rst b/Help/prop_test/ENVIRONMENT_MODIFICATION.rst new file mode 100644 index 00000000000..1e17329344c --- /dev/null +++ b/Help/prop_test/ENVIRONMENT_MODIFICATION.rst @@ -0,0 +1,38 @@ +ENVIRONMENT_MODIFICATION +------------------------ + +.. versionadded:: 3.22 + +Specify environment variables that should be modified for running a test. Note +that the operations performed by this property are performed after the +:prop_test:`ENVIRONMENT` property is already applied. + +If set to a list of environment variables and values of the form +``MYVAR=OP:VALUE``, where ``MYVAR`` is the case-sensitive name of an +environment variable to be modified. Entries are considered in the +order specified in the property's value. The ``OP`` may be one of: + + - ``reset``: Reset to the unmodified value, ignoring all modifications to + ``MYVAR`` prior to this entry. Note that this will reset the variable to + the value set by :prop_test:`ENVIRONMENT`, if it was set, and otherwise + to its state from the rest of the CTest execution. + - ``set``: Replaces the current value of ``MYVAR`` with ``VALUE``. + - ``unset``: Unsets the current value of ``MYVAR``. + - ``string_append``: Appends ``VALUE`` to the current value of ``MYVAR``. + - ``string_prepend``: Prepends ``VALUE`` to the current value of ``MYVAR``. + - ``path_list_append``: Appends ``VALUE`` to the current value of ``MYVAR`` + using the host platform's path list separator (``;`` on Windows and ``:`` + elsewhere). + - ``path_list_prepend``: Prepends ``VALUE`` to the current value of + ``MYVAR`` using the host platform's path list separator (``;`` on Windows + and ``:`` elsewhere). + - ``cmake_list_append``: Appends ``VALUE`` to the current value of ``MYVAR`` + using ``;`` as the separator. + - ``cmake_list_prepend``: Prepends ``VALUE`` to the current value of + ``MYVAR`` using ``;`` as the separator. + +Unrecognized ``OP`` values will result in the test failing before it is +executed. This is so that future operations may be added without changing +valid behavior of existing tests. + +The environment changes from this property do not affect other tests. diff --git a/Help/prop_test/FAIL_REGULAR_EXPRESSION.rst b/Help/prop_test/FAIL_REGULAR_EXPRESSION.rst index facf90255d4..1ec451760a0 100644 --- a/Help/prop_test/FAIL_REGULAR_EXPRESSION.rst +++ b/Help/prop_test/FAIL_REGULAR_EXPRESSION.rst @@ -1,7 +1,8 @@ FAIL_REGULAR_EXPRESSION ----------------------- -If the output matches this regular expression the test will fail. +If the output matches this regular expression the test will fail, +regardless of the process exit code. If set, if the output matches one of specified regular expressions, the test will fail. Example: @@ -13,3 +14,6 @@ the test will fail. Example: ) ``FAIL_REGULAR_EXPRESSION`` expects a list of regular expressions. + +See also the :prop_test:`PASS_REGULAR_EXPRESSION` and +:prop_test:`SKIP_REGULAR_EXPRESSION` test properties. diff --git a/Help/prop_test/FIXTURES_REQUIRED.rst b/Help/prop_test/FIXTURES_REQUIRED.rst index d92808a63d2..f85083069c7 100644 --- a/Help/prop_test/FIXTURES_REQUIRED.rst +++ b/Help/prop_test/FIXTURES_REQUIRED.rst @@ -35,9 +35,9 @@ The concept of a fixture is different to that of a resource specified by set of tests which share setup and cleanup requirements, whereas a resource lock has the effect of ensuring a particular set of tests do not run in parallel. Some situations may need both, such as setting up a database, -serialising test access to that database and deleting the database again at the +serializing test access to that database and deleting the database again at the end. For such cases, tests would populate both ``FIXTURES_REQUIRED`` and -:prop_test:`RESOURCE_LOCK` to combine the two behaviours. Names used for +:prop_test:`RESOURCE_LOCK` to combine the two behaviors. Names used for :prop_test:`RESOURCE_LOCK` have no relationship with names of fixtures, so note that a resource lock does not imply a fixture and vice versa. diff --git a/Help/prop_test/LABELS.rst b/Help/prop_test/LABELS.rst index 8d755709596..a06f152747c 100644 --- a/Help/prop_test/LABELS.rst +++ b/Help/prop_test/LABELS.rst @@ -1,6 +1,10 @@ LABELS ------ -Specify a list of text labels associated with a test. +Specify a list of text labels associated with a test. The labels are +reported in both the ``ctest`` output summary and in dashboard submissions. +They can also be used to filter the set of tests to be executed (see the +``ctest -L`` and ``ctest -LE`` :ref:`CTest Options`). -The list is reported in dashboard submissions. +See :ref:`Additional Labels` for adding labels to a test dynamically during +test execution. diff --git a/Help/prop_test/PASS_REGULAR_EXPRESSION.rst b/Help/prop_test/PASS_REGULAR_EXPRESSION.rst index 0cd621526a5..96468c02a5b 100644 --- a/Help/prop_test/PASS_REGULAR_EXPRESSION.rst +++ b/Help/prop_test/PASS_REGULAR_EXPRESSION.rst @@ -2,6 +2,7 @@ PASS_REGULAR_EXPRESSION ----------------------- The output must match this regular expression for the test to pass. +The process exit code is ignored. If set, the test output will be checked against the specified regular expressions and at least one of the regular expressions has to match, @@ -14,3 +15,6 @@ otherwise the test will fail. Example: ) ``PASS_REGULAR_EXPRESSION`` expects a list of regular expressions. + +See also the :prop_test:`FAIL_REGULAR_EXPRESSION` and +:prop_test:`SKIP_REGULAR_EXPRESSION` test properties. diff --git a/Help/prop_test/SKIP_REGULAR_EXPRESSION.rst b/Help/prop_test/SKIP_REGULAR_EXPRESSION.rst index 46c4363c49c..60038e44075 100644 --- a/Help/prop_test/SKIP_REGULAR_EXPRESSION.rst +++ b/Help/prop_test/SKIP_REGULAR_EXPRESSION.rst @@ -16,4 +16,6 @@ the test will be marked as skipped. Example: ``SKIP_REGULAR_EXPRESSION`` expects a list of regular expressions. -See also the :prop_test:`SKIP_RETURN_CODE` property. +See also the :prop_test:`SKIP_RETURN_CODE`, +:prop_test:`PASS_REGULAR_EXPRESSION`, and :prop_test:`FAIL_REGULAR_EXPRESSION` +test properties. diff --git a/Help/prop_tgt/AUTOMOC.rst b/Help/prop_tgt/AUTOMOC.rst index 52d96e02fbf..ed8b2626b48 100644 --- a/Help/prop_tgt/AUTOMOC.rst +++ b/Help/prop_tgt/AUTOMOC.rst @@ -4,9 +4,9 @@ AUTOMOC Should the target be processed with auto-moc (for Qt projects). :prop_tgt:`AUTOMOC` is a boolean specifying whether CMake will handle the Qt -``moc`` preprocessor automatically, i.e. without having to use the -:module:`QT4_WRAP_CPP() ` or ``QT5_WRAP_CPP()`` macro. -Currently Qt4 and Qt5 are supported. +``moc`` preprocessor automatically, i.e. without having to use commands like +:module:`QT4_WRAP_CPP() `, ``QT5_WRAP_CPP()``, etc. +Currently, Qt versions 4 to 6 are supported. This property is initialized by the value of the :variable:`CMAKE_AUTOMOC` variable if it is set when a target is created. @@ -148,10 +148,13 @@ Qt version detection :prop_tgt:`AUTOMOC` enabled targets need to know the Qt major and minor version they're working with. The major version usually is provided by the -``INTERFACE_QT_MAJOR_VERSION`` property of the ``Qt[45]Core`` library, +``INTERFACE_QT_MAJOR_VERSION`` property of the ``Qt[456]Core`` library, that the target links to. To find the minor version, CMake builds a list of available Qt versions from +- ``Qt6Core_VERSION_MAJOR`` and ``Qt6Core_VERSION_MINOR`` variables + (usually set by ``find_package(Qt6...)``) +- ``Qt6Core_VERSION_MAJOR`` and ``Qt6Core_VERSION_MINOR`` directory properties - ``Qt5Core_VERSION_MAJOR`` and ``Qt5Core_VERSION_MINOR`` variables (usually set by ``find_package(Qt5...)``) - ``Qt5Core_VERSION_MAJOR`` and ``Qt5Core_VERSION_MINOR`` directory properties @@ -167,13 +170,13 @@ version was found, an error is generated. If ``INTERFACE_QT_MAJOR_VERSION`` is not a valid number, the first entry in the list is taken. -A ``find_package(Qt[45]...)`` call sets the ``QT/Qt5Core_VERSION_MAJOR/MINOR`` +A ``find_package(Qt[456]...)`` call sets the ``QT/Qt[56]Core_VERSION_MAJOR/MINOR`` variables. If the call is in a different context than the :command:`add_executable` or :command:`add_library` call, e.g. in a function, then the version variables might not be available to the :prop_tgt:`AUTOMOC` enabled target. In that case the version variables can be forwarded from the -``find_package(Qt[45]...)`` calling context to the :command:`add_executable` +``find_package(Qt[456]...)`` calling context to the :command:`add_executable` or :command:`add_library` calling context as directory properties. The following Qt5 example demonstrates the procedure. diff --git a/Help/prop_tgt/AUTORCC.rst b/Help/prop_tgt/AUTORCC.rst index 9a98f440ce9..0a0c2a11959 100644 --- a/Help/prop_tgt/AUTORCC.rst +++ b/Help/prop_tgt/AUTORCC.rst @@ -5,8 +5,8 @@ Should the target be processed with auto-rcc (for Qt projects). :prop_tgt:`AUTORCC` is a boolean specifying whether CMake will handle the Qt ``rcc`` code generator automatically, i.e. without having to use -the :module:`QT4_ADD_RESOURCES() ` or ``QT5_ADD_RESOURCES()`` -macro. Currently Qt4 and Qt5 are supported. +commands like :module:`QT4_ADD_RESOURCES() `, ``QT5_ADD_RESOURCES()``, +etc. Currently, Qt versions 4 to 6 are supported. When this property is ``ON``, CMake will handle ``.qrc`` files added as target sources at build time and invoke ``rcc`` accordingly. diff --git a/Help/prop_tgt/AUTOUIC.rst b/Help/prop_tgt/AUTOUIC.rst index cd24f5e5905..e0cea97a0a1 100644 --- a/Help/prop_tgt/AUTOUIC.rst +++ b/Help/prop_tgt/AUTOUIC.rst @@ -5,8 +5,8 @@ Should the target be processed with auto-uic (for Qt projects). :prop_tgt:`AUTOUIC` is a boolean specifying whether CMake will handle the Qt ``uic`` code generator automatically, i.e. without having to use -the :module:`QT4_WRAP_UI() ` or ``QT5_WRAP_UI()`` macro. Currently -Qt4 and Qt5 are supported. +commands like :module:`QT4_WRAP_UI() `, ``QT5_WRAP_UI()``, etc. +Currently, Qt versions 4 to 6 are supported. This property is initialized by the value of the :variable:`CMAKE_AUTOUIC` variable if it is set when a target is created. diff --git a/Help/prop_tgt/COMPILE_OPTIONS.rst b/Help/prop_tgt/COMPILE_OPTIONS.rst index 0cd68361041..0fd6aac609b 100644 --- a/Help/prop_tgt/COMPILE_OPTIONS.rst +++ b/Help/prop_tgt/COMPILE_OPTIONS.rst @@ -3,9 +3,13 @@ COMPILE_OPTIONS List of options to pass to the compiler. -This property holds a :ref:`semicolon-separated list ` of options -specified so far for its target. Use the :command:`target_compile_options` -command to append more options. +This property holds a :ref:`semicolon-separated list ` +of options specified so far for its target. Use the +:command:`target_compile_options` command to append more options. +The options will be added after after flags in the +:variable:`CMAKE__FLAGS` and :variable:`CMAKE__FLAGS_` +variables, but before those propagated from dependencies by the +:prop_tgt:`INTERFACE_COMPILE_OPTIONS` property. This property is initialized by the :prop_dir:`COMPILE_OPTIONS` directory property when a target is created, and is used by the generators to set @@ -15,3 +19,5 @@ Contents of ``COMPILE_OPTIONS`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem properties. + +.. include:: ../command/OPTIONS_SHELL.txt diff --git a/Help/prop_tgt/CUDA_ARCHITECTURES.rst b/Help/prop_tgt/CUDA_ARCHITECTURES.rst index d56b76908dc..a3191e8e012 100644 --- a/Help/prop_tgt/CUDA_ARCHITECTURES.rst +++ b/Help/prop_tgt/CUDA_ARCHITECTURES.rst @@ -25,7 +25,7 @@ Examples .. code-block:: cmake - set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES 35 50 72) + set_target_properties(tgt PROPERTIES CUDA_ARCHITECTURES "35;50;72") Generates code for real and virtual architectures ``30``, ``50`` and ``72``. diff --git a/Help/prop_tgt/CUDA_EXTENSIONS.rst b/Help/prop_tgt/CUDA_EXTENSIONS.rst index 2ddba0b4198..ab467ac408c 100644 --- a/Help/prop_tgt/CUDA_EXTENSIONS.rst +++ b/Help/prop_tgt/CUDA_EXTENSIONS.rst @@ -15,5 +15,7 @@ See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. This property is initialized by the value of -the :variable:`CMAKE_CUDA_EXTENSIONS` variable if it is set when a target -is created. +the :variable:`CMAKE_CUDA_EXTENSIONS` variable if set when a target is created +and otherwise by the value of +:variable:`CMAKE_CUDA_EXTENSIONS_DEFAULT _EXTENSIONS_DEFAULT>` +(see :policy:`CMP0128`). diff --git a/Help/prop_tgt/CUDA_STANDARD.rst b/Help/prop_tgt/CUDA_STANDARD.rst index 6517035a297..950ba12e657 100644 --- a/Help/prop_tgt/CUDA_STANDARD.rst +++ b/Help/prop_tgt/CUDA_STANDARD.rst @@ -9,7 +9,35 @@ This property specifies the CUDA/C++ standard whose features are requested to build this target. For some compilers, this results in adding a flag such as ``-std=gnu++11`` to the compile line. -Supported values are ``98``, ``03``, ``11``, ``14``, ``17``, ``20``, ``23``. +Supported values are: + +``98`` + CUDA C++98. Note that this maps to the same as ``03`` internally. + +``03`` + CUDA C++03 + +``11`` + CUDA C++11 + +``14`` + CUDA C++14. While CMake 3.8 and later *recognize* ``14`` as a valid value, + CMake 3.9 was the first version to include support for any compiler. + +``17`` + CUDA C++17. While CMake 3.8 and later *recognize* ``17`` as a valid value, + CMake 3.18 was the first version to include support for any compiler. + +``20`` + .. versionadded:: 3.12 + + CUDA C++20. While CMake 3.12 and later *recognize* ``20`` as a valid value, + CMake 3.18 was the first version to include support for any compiler. + +``23`` + .. versionadded:: 3.20 + + CUDA C++23 If the value requested does not result in a compile flag being added for the compiler in use, a previous standard flag will be added instead. This @@ -21,7 +49,7 @@ means that using: with a compiler which does not support ``-std=gnu++11`` or an equivalent flag will not result in an error or warning, but will instead add the -``-std=gnu++98`` flag if supported. This "decay" behavior may be controlled +``-std=gnu++03`` flag if supported. This "decay" behavior may be controlled with the :prop_tgt:`CUDA_STANDARD_REQUIRED` target property. Additionally, the :prop_tgt:`CUDA_EXTENSIONS` target property may be used to control whether compiler-specific extensions are enabled on a per-target basis. diff --git a/Help/prop_tgt/CXX_EXTENSIONS.rst b/Help/prop_tgt/CXX_EXTENSIONS.rst index bda531ec01c..9b52504efc8 100644 --- a/Help/prop_tgt/CXX_EXTENSIONS.rst +++ b/Help/prop_tgt/CXX_EXTENSIONS.rst @@ -15,5 +15,7 @@ See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. This property is initialized by the value of -the :variable:`CMAKE_CXX_EXTENSIONS` variable if it is set when a target -is created. +the :variable:`CMAKE_CXX_EXTENSIONS` variable if set when a target is created +and otherwise by the value of +:variable:`CMAKE_CXX_EXTENSIONS_DEFAULT _EXTENSIONS_DEFAULT>` (see +:policy:`CMP0128`). diff --git a/Help/prop_tgt/CXX_STANDARD.rst b/Help/prop_tgt/CXX_STANDARD.rst index be0dab565c2..b10d201738f 100644 --- a/Help/prop_tgt/CXX_STANDARD.rst +++ b/Help/prop_tgt/CXX_STANDARD.rst @@ -11,7 +11,31 @@ flag such as ``-std=gnu++11`` to the compile line. For compilers that have no notion of a standard level, such as Microsoft Visual C++ before 2015 Update 3, this has no effect. -Supported values are ``98``, ``11``, ``14``, ``17``, ``20``, ``23``. +Supported values are: + +``98`` + C++98 + +``11`` + C++11 + +``14`` + C++14 + +``17`` + .. versionadded:: 3.8 + + C++17 + +``20`` + .. versionadded:: 3.12 + + C++20 + +``23`` + .. versionadded:: 3.20 + + C++23 If the value requested does not result in a compile flag being added for the compiler in use, a previous standard flag will be added instead. This diff --git a/Help/prop_tgt/C_EXTENSIONS.rst b/Help/prop_tgt/C_EXTENSIONS.rst index b2abb462fc7..a53090c57fd 100644 --- a/Help/prop_tgt/C_EXTENSIONS.rst +++ b/Help/prop_tgt/C_EXTENSIONS.rst @@ -15,5 +15,7 @@ See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. This property is initialized by the value of -the :variable:`CMAKE_C_EXTENSIONS` variable if it is set when a target -is created. +the :variable:`CMAKE_C_EXTENSIONS` variable if set when a target is created and +otherwise by the value of +:variable:`CMAKE_C_EXTENSIONS_DEFAULT _EXTENSIONS_DEFAULT>` (see +:policy:`CMP0128`). diff --git a/Help/prop_tgt/C_STANDARD.rst b/Help/prop_tgt/C_STANDARD.rst index 3f0d242f497..ecba2a8f1f1 100644 --- a/Help/prop_tgt/C_STANDARD.rst +++ b/Help/prop_tgt/C_STANDARD.rst @@ -11,7 +11,26 @@ flag such as ``-std=gnu11`` to the compile line. For compilers that have no notion of a C standard level, such as Microsoft Visual C++ before VS 16.7, this property has no effect. -Supported values are ``90``, ``99`` and ``11``. +Supported values are: + +``90`` + C89/C90 + +``99`` + C99 + +``11`` + C11 + +``17`` + .. versionadded:: 3.21 + + C17 + +``23`` + .. versionadded:: 3.21 + + C23 If the value requested does not result in a compile flag being added for the compiler in use, a previous standard flag will be added instead. This diff --git a/Help/prop_tgt/Fortran_BUILDING_INSTRINSIC_MODULES.rst b/Help/prop_tgt/Fortran_BUILDING_INSTRINSIC_MODULES.rst new file mode 100644 index 00000000000..3533ef9c8f1 --- /dev/null +++ b/Help/prop_tgt/Fortran_BUILDING_INSTRINSIC_MODULES.rst @@ -0,0 +1,16 @@ +Fortran_BUILDING_INSTRINSIC_MODULES +----------------------------------- + +.. versionadded:: 3.22 + +Instructs the CMake Fortran preprocessor that the target is building +Fortran intrinsics for building a Fortran compiler. + +This property is off by default and should be turned only on projects +that build a Fortran compiler. It should not be turned on for projects +that use a Fortran compiler. + +Turning this property on will correctly add dependencies for building +Fortran intrinsic modules whereas turning the property off will ignore +Fortran intrinsic modules in the dependency graph as they are supplied +by the compiler itself. diff --git a/Help/prop_tgt/HIP_ARCHITECTURES.rst b/Help/prop_tgt/HIP_ARCHITECTURES.rst new file mode 100644 index 00000000000..06f956b18e6 --- /dev/null +++ b/Help/prop_tgt/HIP_ARCHITECTURES.rst @@ -0,0 +1,27 @@ +HIP_ARCHITECTURES +----------------- + +.. versionadded:: 3.21 + +List of AMD GPU architectures to generate device code for. + +A non-empty false value (e.g. ``OFF``) disables adding architectures. +This is intended to support packagers and rare cases where full control +over the passed flags is required. + +This property is initialized by the value of the :variable:`CMAKE_HIP_ARCHITECTURES` +variable if it is set when a target is created. + +The HIP compilation model has two modes: whole and separable. Whole compilation +generates device code at compile time. Separable compilation generates device +code at link time. Therefore the ``HIP_ARCHITECTURES`` target property should +be set on targets that compile or link with any HIP sources. + +Examples +^^^^^^^^ + +.. code-block:: cmake + + set_property(TARGET tgt PROPERTY HIP_ARCHITECTURES gfx801 gfx900) + +Generates code for both ``gfx801`` and ``gfx900``. diff --git a/Help/prop_tgt/HIP_EXTENSIONS.rst b/Help/prop_tgt/HIP_EXTENSIONS.rst new file mode 100644 index 00000000000..d1475c96420 --- /dev/null +++ b/Help/prop_tgt/HIP_EXTENSIONS.rst @@ -0,0 +1,21 @@ +HIP_EXTENSIONS +-------------- + +.. versionadded:: 3.21 + +Boolean specifying whether compiler specific extensions are requested. + +This property specifies whether compiler specific extensions should be +used. For some compilers, this results in adding a flag such +as ``-std=gnu++11`` instead of ``-std=c++11`` to the compile line. This +property is ``ON`` by default. The basic HIP/C++ standard level is +controlled by the :prop_tgt:`HIP_STANDARD` target property. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +This property is initialized by the value of +the :variable:`CMAKE_HIP_EXTENSIONS` variable if set when a target is created +and otherwise by the value of +:variable:`CMAKE_HIP_EXTENSIONS_DEFAULT _EXTENSIONS_DEFAULT>` (see +:policy:`CMP0128`). diff --git a/Help/prop_tgt/HIP_STANDARD.rst b/Help/prop_tgt/HIP_STANDARD.rst new file mode 100644 index 00000000000..0c767c629d6 --- /dev/null +++ b/Help/prop_tgt/HIP_STANDARD.rst @@ -0,0 +1,48 @@ +HIP_STANDARD +------------ + +.. versionadded:: 3.21 + +The HIP/C++ standard requested to build this target. + +Supported values are: + +``98`` + HIP C++98 + +``11`` + HIP C++11 + +``14`` + HIP C++14 + +``17`` + HIP C++17 + +``20`` + HIP C++20 + +``23`` + HIP C++23 + +If the value requested does not result in a compile flag being added for +the compiler in use, a previous standard flag will be added instead. This +means that using: + +.. code-block:: cmake + + set_property(TARGET tgt PROPERTY HIP_STANDARD 11) + +with a compiler which does not support ``-std=gnu++11`` or an equivalent +flag will not result in an error or warning, but will instead add the +``-std=gnu++98`` flag if supported. This "decay" behavior may be controlled +with the :prop_tgt:`HIP_STANDARD_REQUIRED` target property. +Additionally, the :prop_tgt:`HIP_EXTENSIONS` target property may be used to +control whether compiler-specific extensions are enabled on a per-target basis. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +This property is initialized by the value of +the :variable:`CMAKE_HIP_STANDARD` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/HIP_STANDARD_REQUIRED.rst b/Help/prop_tgt/HIP_STANDARD_REQUIRED.rst new file mode 100644 index 00000000000..e56209a3cbc --- /dev/null +++ b/Help/prop_tgt/HIP_STANDARD_REQUIRED.rst @@ -0,0 +1,19 @@ +HIP_STANDARD_REQUIRED +--------------------- + +.. versionadded:: 3.21 + +Boolean describing whether the value of :prop_tgt:`HIP_STANDARD` is a requirement. + +If this property is set to ``ON``, then the value of the +:prop_tgt:`HIP_STANDARD` target property is treated as a requirement. If this +property is ``OFF`` or unset, the :prop_tgt:`HIP_STANDARD` target property is +treated as optional and may "decay" to a previous standard if the requested is +not available. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +This property is initialized by the value of +the :variable:`CMAKE_HIP_STANDARD_REQUIRED` variable if it is set when a +target is created. diff --git a/Help/prop_tgt/IMPORTED_OBJECTS.rst b/Help/prop_tgt/IMPORTED_OBJECTS.rst index f3577eb99e2..d71c2199952 100644 --- a/Help/prop_tgt/IMPORTED_OBJECTS.rst +++ b/Help/prop_tgt/IMPORTED_OBJECTS.rst @@ -68,26 +68,24 @@ architecture: # /path/to/somewhere/objects-iphonesimulator/x86_64/func.o In some cases, you may want to have configuration-specific object files -as well. The :variable:`CMAKE_CFG_INTDIR` variable can be a convenient -way of capturing this in combination with the SDK: +as well. The ``$(CONFIGURATION)`` Xcode variable is often used for this and +can be used in conjunction with the others mentioned above: .. code-block:: cmake add_library(someObjs OBJECT IMPORTED) set_property(TARGET someObjs PROPERTY IMPORTED_OBJECTS - "/path/to/somewhere/${CMAKE_CFG_INTDIR}/$(CURRENT_ARCH)/func.o" + "/path/to/somewhere/$(CONFIGURATION)$(EFFECTIVE_PLATFORM_NAME)/$(CURRENT_ARCH)/func.o" ) # Example paths: # /path/to/somewhere/Release-iphoneos/arm64/func.o # /path/to/somewhere/Debug-iphonesimulator/x86_64/func.o -When any Xcode variable or :variable:`CMAKE_CFG_INTDIR` is used, CMake is -not able to fully evaluate the path(s) at configure time. One consequence -of this is that the configuration-specific -:prop_tgt:`IMPORTED_OBJECTS_` properties cannot be used, since -CMake cannot determine whether an object file exists at a particular -```` location. The ``IMPORTED_OBJECTS`` property must be used for -these situations and the configuration-specific aspects of the path must be -handled by using :variable:`CMAKE_CFG_INTDIR` or with another Xcode variable -``$(CONFIGURATION)``. +When any Xcode variable is used, CMake is not able to fully evaluate the +path(s) at configure time. One consequence of this is that the +configuration-specific :prop_tgt:`IMPORTED_OBJECTS_` properties cannot +be used, since CMake cannot determine whether an object file exists at a +particular ```` location. The ``IMPORTED_OBJECTS`` property must be +used for these situations and the configuration-specific aspects of the path +should be handled by the ``$(CONFIGURATION)`` Xcode variable. diff --git a/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst b/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst index 16be3cd1bb6..cba8ac98ce0 100644 --- a/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst +++ b/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst @@ -4,7 +4,7 @@ .. versionadded:: 3.4 This property is implemented only when ```` is ``C``, ``CXX``, -``Fortran``, ``ISPC``, ``OBJC``, ``OBJCXX``, or ``CUDA``. +``Fortran``, ``HIP``, ``ISPC``, ``OBJC``, ``OBJCXX``, or ``CUDA``. Specify a :ref:`semicolon-separated list ` containing a command line for a compiler launching tool. The :ref:`Makefile Generators` and the diff --git a/Help/prop_tgt/LANG_EXTENSIONS.rst b/Help/prop_tgt/LANG_EXTENSIONS.rst new file mode 100644 index 00000000000..afc2ad367ec --- /dev/null +++ b/Help/prop_tgt/LANG_EXTENSIONS.rst @@ -0,0 +1,24 @@ +_EXTENSIONS +----------------- + +The variations are: + +* :prop_tgt:`C_EXTENSIONS` +* :prop_tgt:`CXX_EXTENSIONS` +* :prop_tgt:`CUDA_EXTENSIONS` +* :prop_tgt:`HIP_EXTENSIONS` +* :prop_tgt:`OBJC_EXTENSIONS` +* :prop_tgt:`OBJCXX_EXTENSIONS` + +These properties specify whether compiler-specific extensions are requested. + +These properties are initialized by the value of the +:variable:`CMAKE__EXTENSIONS` variable if it is set when a target is +created and otherwise by the value of +:variable:`CMAKE__EXTENSIONS_DEFAULT` (see :policy:`CMP0128`). + +For supported CMake versions see the respective pages. +To control language standard versions see :prop_tgt:`_STANDARD`. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/prop_tgt/LANG_LINKER_LAUNCHER.rst b/Help/prop_tgt/LANG_LINKER_LAUNCHER.rst new file mode 100644 index 00000000000..f6ca5ad43d7 --- /dev/null +++ b/Help/prop_tgt/LANG_LINKER_LAUNCHER.rst @@ -0,0 +1,16 @@ +_LINKER_LAUNCHER +---------------------- + +.. versionadded:: 3.21 + +This property is implemented only when ```` is ``C``, ``CXX``, +``OBJC``, or ``OBJCXX`` + +Specify a :ref:`semicolon-separated list ` containing a +command line for a linker launching tool. The :ref:`Makefile Generators` and the +:generator:`Ninja` generator will run this tool and pass the linker and its +arguments to the tool. This is useful for tools such as static analyzers. + +This property is initialized by the value of the +:variable:`CMAKE__LINKER_LAUNCHER` variable if it is set when a target is +created. diff --git a/Help/prop_tgt/LANG_STANDARD.rst b/Help/prop_tgt/LANG_STANDARD.rst new file mode 100644 index 00000000000..bd377eccd64 --- /dev/null +++ b/Help/prop_tgt/LANG_STANDARD.rst @@ -0,0 +1,26 @@ +_STANDARD +--------------- + +The variations are: + +* :prop_tgt:`C_STANDARD` +* :prop_tgt:`CXX_STANDARD` +* :prop_tgt:`CUDA_STANDARD` +* :prop_tgt:`HIP_STANDARD` +* :prop_tgt:`OBJC_STANDARD` +* :prop_tgt:`OBJCXX_STANDARD` + +These properties specify language standard versions which are requested. When a +newer standard is specified than is supported by the compiler, then it will +fallback to the latest supported standard. This "decay" behavior may be +controlled with the :prop_tgt:`_STANDARD_REQUIRED` target property. + +These properties are initialized by the value of the +:variable:`CMAKE__STANDARD` variable if it is set when a target is +created. + +For supported values and CMake versions see the respective pages. +To control compiler-specific extensions see :prop_tgt:`_EXTENSIONS`. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/prop_tgt/LANG_STANDARD_REQUIRED.rst b/Help/prop_tgt/LANG_STANDARD_REQUIRED.rst new file mode 100644 index 00000000000..56ecef85f52 --- /dev/null +++ b/Help/prop_tgt/LANG_STANDARD_REQUIRED.rst @@ -0,0 +1,26 @@ +_STANDARD_REQUIRED +------------------------ + +The variations are: + +* :prop_tgt:`C_STANDARD_REQUIRED` +* :prop_tgt:`CXX_STANDARD_REQUIRED` +* :prop_tgt:`CUDA_STANDARD_REQUIRED` +* :prop_tgt:`HIP_STANDARD_REQUIRED` +* :prop_tgt:`OBJC_STANDARD_REQUIRED` +* :prop_tgt:`OBJCXX_STANDARD_REQUIRED` + +These properties specify whether the value of :prop_tgt:`_STANDARD` is a +requirement. When ``OFF`` or unset, the :prop_tgt:`_STANDARD` target +property is treated as optional and may "decay" to a previous standard if the +requested is not available. + +These properties are initialized by the value of the +:variable:`CMAKE__STANDARD_REQUIRED` variable if it is set when a target +is created. + +For supported CMake versions see the respective pages. +To control language standard versions see :prop_tgt:`_STANDARD`. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/prop_tgt/LINK_DEPENDS_NO_SHARED.rst b/Help/prop_tgt/LINK_DEPENDS_NO_SHARED.rst index 5c6778d2454..dc2dc9e320e 100644 --- a/Help/prop_tgt/LINK_DEPENDS_NO_SHARED.rst +++ b/Help/prop_tgt/LINK_DEPENDS_NO_SHARED.rst @@ -10,5 +10,6 @@ to re-link this target. Logical target-level dependencies will not be affected so the linked shared libraries will still be brought up to date before this target is built. -This property is initialized by the value of the variable -CMAKE_LINK_DEPENDS_NO_SHARED if it is set when a target is created. +This property is initialized by the value of the +:variable:`CMAKE_LINK_DEPENDS_NO_SHARED` variable if it is set when a +target is created. diff --git a/Help/prop_tgt/LINK_OPTIONS.rst b/Help/prop_tgt/LINK_OPTIONS.rst index 8c0dfc42667..27eadf92dbb 100644 --- a/Help/prop_tgt/LINK_OPTIONS.rst +++ b/Help/prop_tgt/LINK_OPTIONS.rst @@ -28,3 +28,9 @@ for more on defining buildsystem properties. .. note:: This property must be used in preference to :prop_tgt:`LINK_FLAGS` property. + +.. include:: ../command/DEVICE_LINK_OPTIONS.txt + +.. include:: ../command/OPTIONS_SHELL.txt + +.. include:: ../command/LINK_OPTIONS_LINKER.txt diff --git a/Help/prop_tgt/LINK_WHAT_YOU_USE.rst b/Help/prop_tgt/LINK_WHAT_YOU_USE.rst index 2ed93adfd97..d6de0d49c75 100644 --- a/Help/prop_tgt/LINK_WHAT_YOU_USE.rst +++ b/Help/prop_tgt/LINK_WHAT_YOU_USE.rst @@ -1,16 +1,22 @@ LINK_WHAT_YOU_USE ---------------------------- +----------------- .. versionadded:: 3.7 -This is a boolean option that when set to ``TRUE`` will automatically run -``ldd -r -u`` on the target after it is linked. In addition, the linker flag -``-Wl,--no-as-needed`` will be passed to the target with the link command so -that all libraries specified on the command line will be linked into the -target. This will result in the link producing a list of libraries that -provide no symbols used by this target but are being linked to it. -This is only applicable to executable and shared library targets and -will only work when ld and ldd accept the flags used. +This is a boolean option that, when set to ``TRUE``, will automatically run +contents of variable :variable:`CMAKE_LINK_WHAT_YOU_USE_CHECK` on the target +after it is linked. In addition, the linker flag specified by variable +:variable:`CMAKE__LINK_WHAT_YOU_USE_FLAG` will be passed to the target +with the link command so that all libraries specified on the command line will +be linked into the target. This will result in the link producing a list of +libraries that provide no symbols used by this target but are being linked to +it. + +.. note:: + + For now, it is only supported for ``ELF`` platforms and is only applicable to + executable and shared or module library targets. This property will be + ignored for any other targets and configurations. This property is initialized by the value of the :variable:`CMAKE_LINK_WHAT_YOU_USE` variable if it is set diff --git a/Help/prop_tgt/OBJCXX_EXTENSIONS.rst b/Help/prop_tgt/OBJCXX_EXTENSIONS.rst index 8a254f20a56..2a15dec9066 100644 --- a/Help/prop_tgt/OBJCXX_EXTENSIONS.rst +++ b/Help/prop_tgt/OBJCXX_EXTENSIONS.rst @@ -18,5 +18,7 @@ If the property is not set, and the project has set the :prop_tgt:`CXX_EXTENSION the value of :prop_tgt:`CXX_EXTENSIONS` is set for :prop_tgt:`OBJCXX_EXTENSIONS`. This property is initialized by the value of -the :variable:`CMAKE_OBJCXX_EXTENSIONS` variable if it is set when a target -is created. +the :variable:`CMAKE_OBJCXX_EXTENSIONS` variable if set when a target is +created and otherwise by the value of +:variable:`CMAKE_OBJCXX_EXTENSIONS_DEFAULT _EXTENSIONS_DEFAULT>` +(see :policy:`CMP0128`). diff --git a/Help/prop_tgt/OBJCXX_STANDARD.rst b/Help/prop_tgt/OBJCXX_STANDARD.rst index 96088af9616..654e6877d99 100644 --- a/Help/prop_tgt/OBJCXX_STANDARD.rst +++ b/Help/prop_tgt/OBJCXX_STANDARD.rst @@ -9,7 +9,27 @@ This property specifies the ObjC++ standard whose features are requested to build this target. For some compilers, this results in adding a flag such as ``-std=gnu++11`` to the compile line. -Supported values are ``98``, ``11``, ``14``, ``17``, ``20``, ``23``. +Supported values are: + +``98`` + Objective C++98 + +``11`` + Objective C++11 + +``14`` + Objective C++14 + +``17`` + Objective C++17 + +``20`` + Objective C++20 + +``23`` + .. versionadded:: 3.20 + + Objective C++23 If the value requested does not result in a compile flag being added for the compiler in use, a previous standard flag will be added instead. This diff --git a/Help/prop_tgt/OBJC_EXTENSIONS.rst b/Help/prop_tgt/OBJC_EXTENSIONS.rst index ef1c7543cd9..cd72e5fcca1 100644 --- a/Help/prop_tgt/OBJC_EXTENSIONS.rst +++ b/Help/prop_tgt/OBJC_EXTENSIONS.rst @@ -18,5 +18,7 @@ See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. This property is initialized by the value of -the :variable:`CMAKE_OBJC_EXTENSIONS` variable if it is set when a target -is created. +the :variable:`CMAKE_OBJC_EXTENSIONS` variable if set when a target is created +and otherwise by the value of +:variable:`CMAKE_OBJC_EXTENSIONS_DEFAULT _EXTENSIONS_DEFAULT>` +(see :policy:`CMP0128`). diff --git a/Help/prop_tgt/OBJC_STANDARD.rst b/Help/prop_tgt/OBJC_STANDARD.rst index 2143ff92d97..2d27bcf0005 100644 --- a/Help/prop_tgt/OBJC_STANDARD.rst +++ b/Help/prop_tgt/OBJC_STANDARD.rst @@ -9,7 +9,16 @@ This property specifies the OBJC standard whose features are requested to build this target. For some compilers, this results in adding a flag such as ``-std=gnu11`` to the compile line. -Supported values are ``90``, ``99`` and ``11``. +Supported values are: + +``90`` + Objective C89/C90 + +``99`` + Objective C99 + +``11`` + Objective C11 If the value requested does not result in a compile flag being added for the compiler in use, a previous standard flag will be added instead. This diff --git a/Help/prop_tgt/STATIC_LIBRARY_OPTIONS.rst b/Help/prop_tgt/STATIC_LIBRARY_OPTIONS.rst index 2f4a3baab3b..f5d943723ba 100644 --- a/Help/prop_tgt/STATIC_LIBRARY_OPTIONS.rst +++ b/Help/prop_tgt/STATIC_LIBRARY_OPTIONS.rst @@ -20,3 +20,5 @@ for more on defining buildsystem properties. This property must be used in preference to :prop_tgt:`STATIC_LIBRARY_FLAGS` property. + +.. include:: ../command/OPTIONS_SHELL.txt diff --git a/Help/prop_tgt/Swift_MODULE_DIRECTORY.rst b/Help/prop_tgt/Swift_MODULE_DIRECTORY.rst index a6484f2fd43..619377a11c8 100644 --- a/Help/prop_tgt/Swift_MODULE_DIRECTORY.rst +++ b/Help/prop_tgt/Swift_MODULE_DIRECTORY.rst @@ -9,4 +9,4 @@ If the target contains Swift source files, this specifies the directory in which the modules will be placed. When this property is not set, the modules will be placed in the build directory corresponding to the target's source directory. If the variable :variable:`CMAKE_Swift_MODULE_DIRECTORY` is set when a target is -created its value is used to initialise this property. +created its value is used to initialize this property. diff --git a/Help/prop_tgt/UNITY_BUILD_UNIQUE_ID.rst b/Help/prop_tgt/UNITY_BUILD_UNIQUE_ID.rst index 2c95e027c17..d288dd3b4fb 100644 --- a/Help/prop_tgt/UNITY_BUILD_UNIQUE_ID.rst +++ b/Help/prop_tgt/UNITY_BUILD_UNIQUE_ID.rst @@ -50,6 +50,6 @@ be used to avoid that with code like the following: return MY_UNITY_ID::i; } -The pseudononymous namespace is used within a truly anonymous namespace. +The pseudonymous namespace is used within a truly anonymous namespace. On many platforms, this maintains the invariant that the symbols within do not get external linkage when performing a unity build. diff --git a/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY.rst b/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY.rst index 7b681267895..2a4d66672c9 100644 --- a/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY.rst +++ b/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY.rst @@ -6,3 +6,8 @@ XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY Tell the :generator:`Xcode` generator to perform code signing for all the frameworks and libraries that are embedded using the :prop_tgt:`XCODE_EMBED_FRAMEWORKS >` property. + +.. versionadded:: 3.21 + +This property was generalized to other types of embedded items. See +:prop_tgt:`XCODE_EMBED__CODE_SIGN_ON_COPY` for the more general form. diff --git a/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY.rst b/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY.rst index 29f8c5c0341..04daa8559f8 100644 --- a/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY.rst +++ b/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY.rst @@ -6,3 +6,9 @@ XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY Tell the :generator:`Xcode` generator to remove headers from all the frameworks that are embedded using the :prop_tgt:`XCODE_EMBED_FRAMEWORKS >` property. + +.. versionadded:: 3.21 + +This property was generalized to other types of embedded items. See +:prop_tgt:`XCODE_EMBED__REMOVE_HEADERS_ON_COPY` for the more +general form. diff --git a/Help/prop_tgt/XCODE_EMBED_type.rst b/Help/prop_tgt/XCODE_EMBED_type.rst index 90c5bc7879f..a1af56f12c2 100644 --- a/Help/prop_tgt/XCODE_EMBED_type.rst +++ b/Help/prop_tgt/XCODE_EMBED_type.rst @@ -5,10 +5,20 @@ XCODE_EMBED_ Tell the :generator:`Xcode` generator to embed the specified list of items into the target bundle. ```` specifies the embed build phase to use. +See the Xcode documentation for the base location of each ````. + +The supported values for ```` are: + +``FRAMEWORKS`` + The specified items will be added to the ``Embed Frameworks`` build phase. + The items can be CMake target names or paths to frameworks or libraries. + +``APP_EXTENSIONS`` + .. versionadded:: 3.21 + + The specified items will be added to the ``Embed App Extensions`` build phase. + They must be CMake target names. -Currently, the only supported value for ```` is ``FRAMEWORKS``. -The specified items will be added to the ``Embed Frameworks`` build phase. -The items can be CMake target names or paths to frameworks or libraries. See also :prop_tgt:`XCODE_EMBED__PATH`, -:prop_tgt:`XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY` and -:prop_tgt:`XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY`. +:prop_tgt:`XCODE_EMBED__REMOVE_HEADERS_ON_COPY` and +:prop_tgt:`XCODE_EMBED__CODE_SIGN_ON_COPY`. diff --git a/Help/prop_tgt/XCODE_EMBED_type_CODE_SIGN_ON_COPY.rst b/Help/prop_tgt/XCODE_EMBED_type_CODE_SIGN_ON_COPY.rst new file mode 100644 index 00000000000..7ec03857b47 --- /dev/null +++ b/Help/prop_tgt/XCODE_EMBED_type_CODE_SIGN_ON_COPY.rst @@ -0,0 +1,18 @@ +XCODE_EMBED__CODE_SIGN_ON_COPY +------------------------------------ + +.. versionadded:: 3.20 + +Boolean property used only by the :generator:`Xcode` generator. It specifies +whether to perform code signing for the items that are embedded using the +:prop_tgt:`XCODE_EMBED_` property. + +The supported values for ```` are: + +``FRAMEWORKS`` + +``APP_EXTENSIONS`` + .. versionadded:: 3.21 + +If a ``XCODE_EMBED__CODE_SIGN_ON_COPY`` property is not defined on the +target, no code signing on copy will be performed for that ````. diff --git a/Help/prop_tgt/XCODE_EMBED_type_PATH.rst b/Help/prop_tgt/XCODE_EMBED_type_PATH.rst index 887cf5721e4..a6f980dccf5 100644 --- a/Help/prop_tgt/XCODE_EMBED_type_PATH.rst +++ b/Help/prop_tgt/XCODE_EMBED_type_PATH.rst @@ -3,7 +3,16 @@ XCODE_EMBED__PATH .. versionadded:: 3.20 -Tell the :generator:`Xcode` generator the relative path to use when embedding -the items specified by :prop_tgt:`XCODE_EMBED_`. The path is relative +This property is used only by the :generator:`Xcode` generator. When defined, +it specifies the relative path to use when embedding the items specified by +:prop_tgt:`XCODE_EMBED_`. The path is relative to the base location of the ``Embed XXX`` build phase associated with +````. See the Xcode documentation for the base location of each ````. + +The supported values for ```` are: + +``FRAMEWORKS`` + +``APP_EXTENSIONS`` + .. versionadded:: 3.21 diff --git a/Help/prop_tgt/XCODE_EMBED_type_REMOVE_HEADERS_ON_COPY.rst b/Help/prop_tgt/XCODE_EMBED_type_REMOVE_HEADERS_ON_COPY.rst new file mode 100644 index 00000000000..75c8eae13e5 --- /dev/null +++ b/Help/prop_tgt/XCODE_EMBED_type_REMOVE_HEADERS_ON_COPY.rst @@ -0,0 +1,20 @@ +XCODE_EMBED__REMOVE_HEADERS_ON_COPY +----------------------------------------- + +.. versionadded:: 3.20 + +Boolean property used only by the :generator:`Xcode` generator. It specifies +whether to remove headers from all the frameworks that are embedded using the +:prop_tgt:`XCODE_EMBED_` property. + +The supported values for ```` are: + +``FRAMEWORKS`` + If the ``XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY`` property is not + defined, headers will not be removed on copy by default. + +``APP_EXTENSIONS`` + .. versionadded:: 3.21 + + If the ``XCODE_EMBED_APP_EXTENSIONS_REMOVE_HEADERS_ON_COPY`` property is not + defined, headers WILL be removed on copy by default. diff --git a/Help/release/3.15.rst b/Help/release/3.15.rst index e68e7d38b4b..6b1a8007a06 100644 --- a/Help/release/3.15.rst +++ b/Help/release/3.15.rst @@ -40,7 +40,7 @@ Languages customize the Swift module name. * The :prop_sf:`Swift_DIAGNOSTICS_FILE` source property was added to - indicate where to write the serialised Swift diagnostics. + indicate where to write the serialized Swift diagnostics. The Swift support is experimental, not considered stable, and may change in future releases of CMake. diff --git a/Help/release/3.16.rst b/Help/release/3.16.rst index 84d96cdc8f4..28273a762f8 100644 --- a/Help/release/3.16.rst +++ b/Help/release/3.16.rst @@ -233,7 +233,7 @@ Deprecated and Removed Features instead. * The :module:`GetPrerequisites` module has been deprecated, as it has been - superceded by :command:`file(GET_RUNTIME_DEPENDENCIES)`. + superseded by :command:`file(GET_RUNTIME_DEPENDENCIES)`. * The ``CPACK_INSTALL_SCRIPT`` variable has been deprecated in favor of the new, more accurately named :variable:`CPACK_INSTALL_SCRIPTS` variable. diff --git a/Help/release/3.20.rst b/Help/release/3.20.rst index f77304fcffd..42e95beec4f 100644 --- a/Help/release/3.20.rst +++ b/Help/release/3.20.rst @@ -362,3 +362,10 @@ Changes made since CMake 3.20.0 include the following. a special case to recognize oneAPI 2021.1 Fortran as ``IntelLLVM``. The oneAPI 2021.2 Fortran compiler defines the proper identification macro and so is identified as ``IntelLLVM`` by all CMake 3.20 versions. + +3.20.3, 3.20.4, 3.20.5, 3.20.6 +------------------------------ + +These versions made no changes to documented features or interfaces. +Some implementation updates were made to support ecosystem changes +and/or fix regressions. diff --git a/Help/release/3.21.rst b/Help/release/3.21.rst new file mode 100644 index 00000000000..e1c6172b2a4 --- /dev/null +++ b/Help/release/3.21.rst @@ -0,0 +1,336 @@ +CMake 3.21 Release Notes +************************ + +.. only:: html + + .. contents:: + +Changes made since CMake 3.20 include the following. + +New Features +============ + +Presets +------- + +* :manual:`cmake-presets(7)` gained support for specifying the install prefix + in a configure preset. + +* :manual:`cmake-presets(7)` gained support for conditional enabling of presets. + +* :manual:`cmake-presets(7)` gained support for a ``${hostSystemName}`` macro. + +* :manual:`cmake-presets(7)` gained support for omitting the ``generator`` and + ``binaryDir`` fields. + +Generators +---------- + +* The :generator:`Visual Studio 17 2022` generator was added. + +* The :ref:`Makefile Generators` and the :generator:`Ninja` generator + learned to add linker launcher tools along with the linker for ``C``, + ``CXX``, ``OBJC``, and ``OBJCXX`` languages. + See the :variable:`CMAKE__LINKER_LAUNCHER` variable + and :prop_tgt:`_LINKER_LAUNCHER` target property for details. + +Languages +--------- + +* CMake learned to support ``HIP`` as a first-class language that can be + enabled via the :command:`project` and :command:`enable_language` commands. + +* :prop_tgt:`C_STANDARD`, :prop_tgt:`OBJC_STANDARD`, and the + :manual:`Compile Features ` functionality gained + support for C17 and C23. + +* Source file extensions ``.ixx`` and ``.cppm`` are now treated as C++. + +Command-Line +------------ + +* :manual:`cmake(1)` gained the ``--install-prefix `` + command-line option to specify the location of the install prefix. + +* :manual:`cmake(1)` gained the ``--toolchain `` + command-line option to specify a toolchain file. + +* :manual:`cmake(1)` ``-E capabilities`` output, for some generators, + may now contain a ``supportedPlatforms`` field listing platforms + known to be supported in :variable:`CMAKE_GENERATOR_PLATFORM`. + +* Messages printed to a terminal now may be colored by message type. + +Compilers +--------- + +* The Fujitsu compiler is now supported using compiler id ``Fujitsu`` + in traditional (``Trad``) mode, and compiler id ``FujitsuClang`` + in ``Clang`` mode. + +Platforms +--------- + +* CMake now supports the MSYS runtime environment, much like CYGWIN. + +File-Based API +-------------- + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field + has been updated to 2.3. + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 gained a + new "directory" object containing directory-level information. + This includes a list of installers generated by the :command:`install` + command. + +Commands +-------- + +* The :command:`add_custom_command` command ``DEPFILE`` option: + + * may now use + :manual:`generator expressions `, + + * is now supported by :ref:`Visual Studio Generators` for VS 2012 + and above, and + + * is now supported by the :generator:`Xcode` generator. + +* The :command:`add_custom_command(TARGET)` command + (for :ref:`Build Events `) + gained support for resolving target-dependent generator expressions. + +* The :command:`build_command` command gained a ``PARALLEL_LEVEL`` option. + +* The :command:`file(COPY_FILE)` command was added to copy a single file. + +* The :command:`file(GET_RUNTIME_DEPENDENCIES)` command gained new + ``POST_INCLUDE_FILES`` and ``POST_EXCLUDE_FILES`` arguments. + +* The :command:`file(REAL_PATH)` command gained the option ``EXPAND_TILDE`` to + replace any leading tilde with the path to the user's home directory. + +* The :command:`file(RENAME)` command learned to optionally capture + failure in a result variable. It also gained a ``NO_REPLACE`` + option to fail if the destination exists. + +* The :command:`install` command gained a new ``IMPORTED_RUNTIME_ARTIFACTS`` + mode, which can be used to install the runtime artifacts of imported targets. + +* The :command:`install` command gained a new ``RUNTIME_DEPENDENCY_SET`` mode, + which can be used to install runtime dependencies using + :command:`file(GET_RUNTIME_DEPENDENCIES)`. + +* The :command:`install(TARGETS)` command gained new ``RUNTIME_DEPENDENCIES`` + and ``RUNTIME_DEPENDENCY_SET`` arguments, which can be used to install + runtime dependencies using :command:`file(GET_RUNTIME_DEPENDENCIES)`. + +* The :command:`install(SCRIPT|CODE)` command + supports a new option ``ALL_COMPONENTS`` which allows + the corresponding code to run for every component of + a per component installation. + +* The :command:`project` command now sets variables + :variable:`PROJECT_IS_TOP_LEVEL` and :variable:`_IS_TOP_LEVEL` + to indicate whether it was called in a top-level ``CMakeLists.txt`` file. + +Variables +--------- + +* The :envvar:`CMAKE_TOOLCHAIN_FILE` environment variable was added to + provide a default value for the :variable:`CMAKE_TOOLCHAIN_FILE` variable. + +Properties +---------- + +* The :prop_dir:`IMPORTED_TARGETS` directory property was added to + get a list of :ref:`Imported Targets` created in the current + directory. + +* The :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS >` target property + was added to tell the :generator:`Xcode` generator to embed app extensions + such as iMessage sticker packs. + Aspects of the embedding can be customized with the + :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS_PATH >`, + :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS_CODE_SIGN_ON_COPY _CODE_SIGN_ON_COPY>` and + :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS_REMOVE_HEADERS_ON_COPY _REMOVE_HEADERS_ON_COPY>` + properties. + +Modules +------- + +* The :module:`FindBLAS` and :module:`FindLAPACK` modules learned to support + the serial ``Fujitsu_SSL2`` and parallel ``Fujitsu_SSL2BLAMP`` libraries. + +* The :module:`FindDevIL` module now provides imported targets. + +* The :module:`FindIconv` module now has version support. + +* The :module:`FindIntl` module now has version support. + +* The :module:`FindMPI` module learned to support ``Fujitsu`` and + ``FujitsuClang`` in both host and cross compiling modes. + +* The :module:`FindMsys` module was added to find MSYS installations. + Like :module:`FindCygwin`, it is used automatically by some other + find modules to locate UNIX-style tools on Windows. + +* The :module:`FindOpenMP` module learned to support ``Fujitsu`` and + ``FujitsuClang``. + +* The :module:`FindVulkan` module gained imported targets + ``Vulkan::Headers`` and ``Vulkan::glslangValidator``. + +* The :module:`UseJava` module command ``add_jar`` gained a ``RESOURCES`` + option to allow explicit naming of resources with non-optional namespace. + +* The :module:`UseSWIG` module use now standard library naming conventions + for the ``CSharp`` language. See policy :policy:`CMP0122`. + +* The :module:`UseSWIG` module now supports using the ``swig`` tool to + generate implicit dependencies with the :generator:`Xcode` generator. + +Generator Expressions +--------------------- + +* A new :genex:`TARGET_RUNTIME_DLLS` generator expression was added. + +CTest +----- + +* :manual:`ctest(1)` gained documentation for its ability to capture + :ref:`Additional Test Measurements`. + +* :manual:`ctest(1)` learned to recognize files attached to a test at run time. + Previously it was only possible to attach files to tests at configure time + by using the :prop_test:`ATTACHED_FILES` or + :prop_test:`ATTACHED_FILES_ON_FAIL` test properties. + See :ref:`Additional Test Measurements` for more information. + +* :manual:`ctest(1)` gained a ``--output-junit`` option to write test results + to a JUnit XML file. + +* The :command:`ctest_build` command gained a ``PARALLEL_LEVEL`` option. + +CPack +----- + +* The :cpack_gen:`CPack DragNDrop Generator` gained option + :variable:`CPACK_DMG_FILESYSTEM` to control the ``.dmg`` filesystem. + +* The :cpack_gen:`CPack IFW Generator` now supports hyphens in names + given to :command:`cpack_ifw_configure_component` or + :command:`cpack_ifw_configure_component_group` as ``DEPENDS`` or + ``DEPENDENCIES`` arguments. This requires QtIFW 3.1 or later. + +* The :cpack_gen:`CPack NSIS Generator` gained a new + :variable:`CPACK_NSIS_EXECUTABLE` variable to specify the ``makensis`` + executable to use instead of the default one. + +* The :variable:`CPACK_CUSTOM_INSTALL_VARIABLES` variable was added to set + variables in ``cmake_install.cmake`` script invocations made by CPack. + +Deprecated and Removed Features +=============================== + +* Undocumented :variable:`CMAKE_SYSTEM_NAME` version-stripping behavior has + been removed entirely. If it is set by a ``-D`` flag or by a + :manual:`toolchain file `, it is left unaltered, + even if it still contains a version number. + Similar :variable:`CMAKE_HOST_SYSTEM_NAME` version-stripping behavior, + also undocumented, has been moved earlier, before :command:`project` or + :command:`enable_language` is called. + +* ``ARMClang`` cpu/arch compile and link flags are no longer added + automatically based on the :variable:`CMAKE_SYSTEM_PROCESSOR` + variable or the undocumented ``CMAKE_SYSTEM_ARCH`` variable. + They must be specified explicitly. See policy :policy:`CMP0123`. + +Other Changes +============= + +* The :command:`find_file`, :command:`find_path`, :command:`find_program`, + and :command:`find_library` commands handle cache variables in the same way + regardless how they are defined. See policy :policy:`CMP0125` for details. + +* The :command:`find_file`, :command:`find_path`, :command:`find_program`, + and :command:`find_library` commands gained the option ``NO_CACHE`` to store + find result in normal variable. + +* The :command:`foreach` command now isolates loop variables in the loop scope. + See policy :policy:`CMP0124` for details. + +* The :command:`list` command's ``GET``, ``INSERT``, ``SUBLIST``, and + ``REMOVE_AT`` subcommands now error with invalid (i.e., non-integer) values + are given as any of their index arguments based on the setting of policy + :policy:`CMP0121`. + +* The :command:`set(CACHE)` command no longer removes a normal variable + of the same name, if any. See policy :policy:`CMP0126`. + +* :command:`target_link_libraries` calls referencing object libraries + via the :genex:`TARGET_OBJECTS` generator expression now place the + object files before all libraries on the link line, regardless of + their specified order. See documentation on + :ref:`Linking Object Libraries via \$\` for details. + +* The :ref:`Ninja Generators` now pass source files and include directories + to the compiler using absolute paths. This makes diagnostic messages and + debug symbols more consistent, and matches the :ref:`Makefile Generators`. + +* The :generator:`NMake Makefiles` generator now encodes the generated + makefiles as UTF-8 with a BOM when using ``nmake`` from VS 9 or above. + +* The :ref:`Visual Studio Generators` for VS 2010 and above now place + per-source preprocessor definitions after target-wide preprocssor + definitions. This makes VS consistent with the :ref:`Ninja Generators` + and the :ref:`Makefile Generators`. + +* The precompiled binaries provided on + `cmake.org `_ now support + ``liblzma`` multi-threading. See the :variable:`CPACK_THREADS` and + :variable:`CPACK_ARCHIVE_THREADS` variables. + +Updates +======= + +Changes made since CMake 3.21.0 include the following. + +3.21.1 +------ + +* The :generator:`Visual Studio 17 2022` generator is now based on + "Visual Studio 2022 Preview 2". Previously it was based on "Preview 1.1". + +3.21.2 +------ + +* ``CUDA`` targets with :prop_tgt:`CUDA_SEPARABLE_COMPILATION` enabled are now + correctly generated in non-root directories. + +* The :generator:`Visual Studio 17 2022` generator is now based on + "Visual Studio 2022 Preview 3.1". Previously it was based on "Preview 2". + +3.21.3 +------ + +* The :generator:`Visual Studio 17 2022` generator is now based on + "Visual Studio 2022 Preview 4". Previously it was based on "Preview 3.1". + +* The AMD ROCm Platform ``hipcc`` compiler was identifed by CMake 3.21.0 + through 3.21.2 as a distinct compiler with id ``ROCMClang``. This has + been removed because it caused regressions. Instead: + + * ``hipcc`` may no longer be used as a ``HIP`` compiler because it + interferes with flags CMake needs to pass to Clang. Use Clang directly. + + * ``hipcc`` may once again be used as a ``CXX`` compiler, and is treated as + whatever compiler it selects underneath, as CMake 3.20 and below did. + +3.21.4 +------ + +* The :generator:`Visual Studio 17 2022` generator is now based on the + "Visual Studio 2022" release candidates. Previously it was based on + preview versions. diff --git a/Help/release/3.22.rst b/Help/release/3.22.rst new file mode 100644 index 00000000000..fcb655d196b --- /dev/null +++ b/Help/release/3.22.rst @@ -0,0 +1,144 @@ +CMake 3.22 Release Notes +************************ + +.. only:: html + + .. contents:: + +Changes made since CMake 3.21 include the following. + +New Features +============ + +Commands +-------- + +* The :command:`cmake_host_system_information` command can now query + `OS identification variables`_ from the :file:`/etc/os-release` file. + +* The :command:`string(TIMESTAMP)` command now supports the ``%V`` + specifier for ISO 8601 week numbers. + +.. _`OS identification variables`: https://www.freedesktop.org/software/systemd/man/os-release.html + +Variables +--------- + +* The :envvar:`CMAKE_BUILD_TYPE` environment variable was added to + provide a default value for the :variable:`CMAKE_BUILD_TYPE` variable. + +* The :envvar:`CMAKE_CONFIGURATION_TYPES` environment variable was added to + provide a default value for the :variable:`CMAKE_CONFIGURATION_TYPES` + variable. + +* The :envvar:`CMAKE_INSTALL_MODE` environment variable was added to + tell :command:`install` rules (implemented by :command:`file(INSTALL)`) + to install symbolic links instead of copying of files. + +* The :variable:`CMAKE__LINK_WHAT_YOU_USE_FLAG` and + :variable:`CMAKE_LINK_WHAT_YOU_USE_CHECK` variables were added to + control the linker flag and check used by the + :prop_tgt:`LINK_WHAT_YOU_USE` target property. + +* The :variable:`CMAKE_REQUIRE_FIND_PACKAGE_` variable + was added to turn a non-REQUIRED :command:`find_package` call into + a REQUIRED one. + +Properties +---------- + +* The :prop_tgt:`_EXTENSIONS` target property is now initialized to + :variable:`CMAKE__EXTENSIONS_DEFAULT`, detected from the compiler. + See :policy:`CMP0128`. + +* The :prop_sf:`VS_SETTINGS` source file property is now supported for + all source file types. Previously it worked only for non-built sources. + +Modules +------- + +* The :module:`CMakeDependentOption` module :command:`cmake_dependent_option` + macro now supports full :ref:`Condition Syntax`. + See policy :policy:`CMP0127`. + +* The :module:`FetchContent` module now passes through the + :variable:`CMAKE_TLS_VERIFY`, :variable:`CMAKE_TLS_CAINFO`, + :variable:`CMAKE_NETRC` and :variable:`CMAKE_NETRC_FILE` variables (when + defined) to the underlying :module:`ExternalProject` sub-build. + Previously, those variables were silently ignored by :module:`FetchContent`. + +* The :module:`FindBLAS` and :module:`FindLAPACK` modules gained + a ``BLA_SIZEOF_INTEGER`` option to find a BLAS/LAPACK whose ABI + uses a specific integer size. + +* The :module:`FindJasper` module now provides an imported target. + +* The :module:`FindMatlab` module now provides imported targets. + +* The :module:`FindPkgConfig` module gained a :variable:`PKG_CONFIG_ARGN` + variable to specify arguments to ``pkg-config`` calls. + +* The :module:`GoogleTest` module :command:`gtest_discover_tests` + function gained a ``TEST_FILTER`` option to filter tests using + ``--gtest_filter`` during test discovery. + +* The :module:`UseSWIG` module, for :ref:`Visual Studio Generators`, + can now use the ``swig`` tool to generate implicit dependencies. + +CTest +----- + +* :manual:`ctest(1)` learned to recognize labels attached to a test at run time. + Previously it was only possible to attach labels to tests at configure time + by using the :prop_test:`LABELS` test property. + See :ref:`Additional Test Measurements` for more information. + +* :manual:`ctest(1)` learned to be able to modify the environment for a test + through the :prop_test:`ENVIRONMENT_MODIFICATION` property. This is allows + for updates to environment variables based on the environment present at + test time. + +* The :command:`ctest_memcheck` command now also generates a + :file:`DynamicAnalysis-Test.xml` file which may be used to submit test + results to CDash. + +CPack +----- + +* The :cpack_gen:`CPack DEB Generator` gained the + option to set :variable:`CPACK_DEBIAN_COMPRESSION_TYPE` to ``zstd``, + which enables Zstandard compression for deb packages. + +* The :cpack_gen:`CPack NSIS Generator` gained a new + :variable:`CPACK_NSIS_IGNORE_LICENSE_PAGE` variable to suppress + the license page in the installer. + +* The :cpack_gen:`CPack RPM Generator` gained the + :variable:`CPACK_RPM_REQUIRES_EXCLUDE_FROM` option to avoid scanning + specific paths for dependencies. + +Deprecated and Removed Features +=============================== + +* The :generator:`Visual Studio 10 2010` generator is now deprecated + and will be removed in a future version of CMake. + +Other Changes +============= + +* The :manual:`Compile Features ` functionality now + correctly disables or enables compiler extensions when no standard level is + specified and avoids unnecessarily adding language standard flags if the + requested settings match the compiler's defaults. See :policy:`CMP0128`. + +* The :manual:`Compile Features ` functionality + now ignores features for languages that are not enabled. + +* The :ref:`Ninja Generators` now implement the ``edit_cache`` target + using :manual:`ccmake(1)` if available. + +* The :generator:`Ninja` and :generator:`NMake Makefiles` generators + now use the MSVC ``-external:I`` flag for system includes. + This became available as of VS 16.10 (toolchain version 14.29.30037). + +* The :cpack_gen:`CPack NSIS Generator` now requires NSIS 3.03 or later. diff --git a/Help/release/3.6.rst b/Help/release/3.6.rst index f0add07ff2b..b798f0d6ecd 100644 --- a/Help/release/3.6.rst +++ b/Help/release/3.6.rst @@ -170,7 +170,7 @@ CPack is used for dependency auto detection. * The :cpack_gen:`CPack DEB Generator` learned how to generate - ``DEBIAN/shlibs`` contorl file when package contains shared libraries. + ``DEBIAN/shlibs`` control file when package contains shared libraries. * The :cpack_gen:`CPack DEB Generator` learned how to generate ``DEBIAN/postinst`` and ``DEBIAN/postrm`` files if the package installs diff --git a/Help/release/index.rst b/Help/release/index.rst index 95b41fb63b4..3d2ed43105c 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -13,6 +13,8 @@ Releases .. toctree:: :maxdepth: 1 + 3.22 <3.22> + 3.21 <3.21> 3.20 <3.20> 3.19 <3.19> 3.18 <3.18> diff --git a/Help/variable/CMAKE_AUTOMOC_RELAXED_MODE.rst b/Help/variable/CMAKE_AUTOMOC_RELAXED_MODE.rst index 6c0c61b112b..0b0b11414a0 100644 --- a/Help/variable/CMAKE_AUTOMOC_RELAXED_MODE.rst +++ b/Help/variable/CMAKE_AUTOMOC_RELAXED_MODE.rst @@ -8,7 +8,7 @@ Switch between strict and relaxed automoc mode. By default, :prop_tgt:`AUTOMOC` behaves exactly as described in the documentation of the :prop_tgt:`AUTOMOC` target property. When set to ``TRUE``, it accepts more input and tries to find the correct input file for -``moc`` even if it differs from the documented behaviour. In this mode it +``moc`` even if it differs from the documented behavior. In this mode it e.g. also checks whether a header file is intended to be processed by moc when a ``"foo.moc"`` file has been included. diff --git a/Help/variable/CMAKE_BUILD_TYPE.rst b/Help/variable/CMAKE_BUILD_TYPE.rst index 405f7d5901c..bb95436ad35 100644 --- a/Help/variable/CMAKE_BUILD_TYPE.rst +++ b/Help/variable/CMAKE_BUILD_TYPE.rst @@ -1,25 +1,21 @@ CMAKE_BUILD_TYPE ---------------- -Specifies the build type on single-configuration generators. +Specifies the build type on single-configuration generators (e.g. +:ref:`Makefile Generators` or :generator:`Ninja`). Typical values include +``Debug``, ``Release``, ``RelWithDebInfo`` and ``MinSizeRel``, but custom +build types can also be defined. -This statically specifies what build type (configuration) will be -built in this build tree. Possible values are empty, ``Debug``, ``Release``, -``RelWithDebInfo``, ``MinSizeRel``, ... This variable is only meaningful to -single-configuration generators (such as :ref:`Makefile Generators` and -:generator:`Ninja`) i.e. those which choose a single configuration when CMake -runs to generate a build tree as opposed to multi-configuration generators -which offer selection of the build configuration within the generated build -environment. There are many per-config properties and variables -(usually following clean ``SOME_VAR_`` order conventions), such as -``CMAKE_C_FLAGS_``, specified as uppercase: -``CMAKE_C_FLAGS_[DEBUG|RELEASE|RELWITHDEBINFO|MINSIZEREL|...]``. For example, -in a build tree configured to build type ``Debug``, CMake will see to -having :variable:`CMAKE_C_FLAGS_DEBUG _FLAGS_DEBUG>` settings get -added to the :variable:`CMAKE_C_FLAGS _FLAGS>` settings. See -also :variable:`CMAKE_CONFIGURATION_TYPES`. +This variable is initialized by the first :command:`project` or +:command:`enable_language` command called in a project when a new build +tree is first created. If the :envvar:`CMAKE_BUILD_TYPE` environment +variable is set, its value is used. Otherwise, a toolchain-specific +default is chosen when a language is enabled. The default value is often +an empty string, but this is usually not desirable and one of the other +standard build types is usually more appropriate. -Note that configuration names are case-insensitive. The value of this -variable will be the same as it is specified when invoking CMake. -For instance, if ``-DCMAKE_BUILD_TYPE=ReLeAsE`` is specified, then the -value of ``CMAKE_BUILD_TYPE`` will be ``ReLeAsE``. +Depending on the situation, the value of this variable may be treated +case-sensitively or case-insensitively. See :ref:`Build Configurations` +for discussion of this and other related topics. + +For multi-config generators, see :variable:`CMAKE_CONFIGURATION_TYPES`. diff --git a/Help/variable/CMAKE_CFG_INTDIR.rst b/Help/variable/CMAKE_CFG_INTDIR.rst index 842654ec5c3..43668eaac87 100644 --- a/Help/variable/CMAKE_CFG_INTDIR.rst +++ b/Help/variable/CMAKE_CFG_INTDIR.rst @@ -1,6 +1,12 @@ CMAKE_CFG_INTDIR ---------------- +.. deprecated:: 3.21 + + This variable has poor support on :generator:`Ninja Multi-Config`, and + predates the existence of the :genex:`$` generator expression. Use + ``$`` instead. + Build-time reference to per-configuration output subdirectory. For native build systems supporting multiple configurations in the @@ -19,11 +25,6 @@ Example values: . = Ninja ${CONFIGURATION} = Ninja Multi-Config -Note that this variable only has limited support on -:generator:`Ninja Multi-Config`. It is recommended that you use the -``$`` :manual:`generator expression ` -instead. - Since these values are evaluated by the native build system, this variable is suitable only for use in command lines that will be evaluated at build time. Example of intended usage: diff --git a/Help/variable/CMAKE_CONFIGURATION_TYPES.rst b/Help/variable/CMAKE_CONFIGURATION_TYPES.rst index 34e99ebf709..75ff8a12a74 100644 --- a/Help/variable/CMAKE_CONFIGURATION_TYPES.rst +++ b/Help/variable/CMAKE_CONFIGURATION_TYPES.rst @@ -1,10 +1,20 @@ CMAKE_CONFIGURATION_TYPES ------------------------- -Specifies the available build types on multi-config generators. +Specifies the available build types (configurations) on multi-config +generators (e.g. :ref:`Visual Studio `, +:generator:`Xcode`, or :generator:`Ninja Multi-Config`). Typical values +include ``Debug``, ``Release``, ``RelWithDebInfo`` and ``MinSizeRel``, +but custom build types can also be defined. -This specifies what build types (configurations) will be available -such as ``Debug``, ``Release``, ``RelWithDebInfo`` etc. This has reasonable -defaults on most platforms, but can be extended to provide other build -types. See also :variable:`CMAKE_BUILD_TYPE` for details of managing -configuration data, and :variable:`CMAKE_CFG_INTDIR`. +This variable is initialized by the first :command:`project` or +:command:`enable_language` command called in a project when a new build +tree is first created. If the :envvar:`CMAKE_CONFIGURATION_TYPES` +environment variable is set, its value is used. Otherwise, the default +value is generator-specific. + +Depending on the situation, the values in this variable may be treated +case-sensitively or case-insensitively. See :ref:`Build Configurations` +for discussion of this and other related topics. + +For single-config generators, see :variable:`CMAKE_BUILD_TYPE`. diff --git a/Help/variable/CMAKE_CUDA_EXTENSIONS.rst b/Help/variable/CMAKE_CUDA_EXTENSIONS.rst index b86c0ea39cd..12749ce5975 100644 --- a/Help/variable/CMAKE_CUDA_EXTENSIONS.rst +++ b/Help/variable/CMAKE_CUDA_EXTENSIONS.rst @@ -3,11 +3,8 @@ CMAKE_CUDA_EXTENSIONS .. versionadded:: 3.8 -Default value for :prop_tgt:`CUDA_EXTENSIONS` property of targets. - -This variable is used to initialize the :prop_tgt:`CUDA_EXTENSIONS` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`CUDA_EXTENSIONS` target property if set when a +target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst b/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst index d5fcb7dbf0b..9817b1a1207 100644 --- a/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst +++ b/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst @@ -23,3 +23,7 @@ is read-only and changes to it are undefined behavior. :variable:`CMAKE_CUDA_COMPILER_ID _COMPILER_ID>` is ``NVIDIA``, it does not make sense to set ``CMAKE_CUDA_HOST_COMPILER`` without also setting ``CMAKE_CUDA_COMPILER`` to NVCC. + +.. note:: + + Ignored when using :ref:`Visual Studio Generators`. diff --git a/Help/variable/CMAKE_CUDA_STANDARD.rst b/Help/variable/CMAKE_CUDA_STANDARD.rst index 798ab1e7442..ee9395aef4e 100644 --- a/Help/variable/CMAKE_CUDA_STANDARD.rst +++ b/Help/variable/CMAKE_CUDA_STANDARD.rst @@ -3,11 +3,8 @@ CMAKE_CUDA_STANDARD .. versionadded:: 3.8 -Default value for :prop_tgt:`CUDA_STANDARD` property of targets. - -This variable is used to initialize the :prop_tgt:`CUDA_STANDARD` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`CUDA_STANDARD` target property if set when a +target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_CUDA_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_CUDA_STANDARD_REQUIRED.rst index ae2f52f8bcf..0c85a04d7cc 100644 --- a/Help/variable/CMAKE_CUDA_STANDARD_REQUIRED.rst +++ b/Help/variable/CMAKE_CUDA_STANDARD_REQUIRED.rst @@ -3,11 +3,8 @@ CMAKE_CUDA_STANDARD_REQUIRED .. versionadded:: 3.8 -Default value for :prop_tgt:`CUDA_STANDARD_REQUIRED` property of targets. - -This variable is used to initialize the :prop_tgt:`CUDA_STANDARD_REQUIRED` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`CUDA_STANDARD_REQUIRED` target property if set +when a target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_CXX_EXTENSIONS.rst b/Help/variable/CMAKE_CXX_EXTENSIONS.rst index ea8c4be7051..017f503aec2 100644 --- a/Help/variable/CMAKE_CXX_EXTENSIONS.rst +++ b/Help/variable/CMAKE_CXX_EXTENSIONS.rst @@ -3,11 +3,8 @@ CMAKE_CXX_EXTENSIONS .. versionadded:: 3.1 -Default value for :prop_tgt:`CXX_EXTENSIONS` property of targets. - -This variable is used to initialize the :prop_tgt:`CXX_EXTENSIONS` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`CXX_EXTENSIONS` target property if set when a +target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_CXX_STANDARD.rst b/Help/variable/CMAKE_CXX_STANDARD.rst index 8ef8c80e31e..33eb89e035e 100644 --- a/Help/variable/CMAKE_CXX_STANDARD.rst +++ b/Help/variable/CMAKE_CXX_STANDARD.rst @@ -3,11 +3,8 @@ CMAKE_CXX_STANDARD .. versionadded:: 3.1 -Default value for :prop_tgt:`CXX_STANDARD` property of targets. - -This variable is used to initialize the :prop_tgt:`CXX_STANDARD` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`CXX_STANDARD` target property if set when a target +is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst index f7b2ae92ea2..1c6c0cc9684 100644 --- a/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst +++ b/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst @@ -3,11 +3,8 @@ CMAKE_CXX_STANDARD_REQUIRED .. versionadded:: 3.1 -Default value for :prop_tgt:`CXX_STANDARD_REQUIRED` property of targets. - -This variable is used to initialize the :prop_tgt:`CXX_STANDARD_REQUIRED` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`CXX_STANDARD_REQUIRED` target property if set when +a target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_C_EXTENSIONS.rst b/Help/variable/CMAKE_C_EXTENSIONS.rst index fce8fc72204..66805211194 100644 --- a/Help/variable/CMAKE_C_EXTENSIONS.rst +++ b/Help/variable/CMAKE_C_EXTENSIONS.rst @@ -3,11 +3,8 @@ CMAKE_C_EXTENSIONS .. versionadded:: 3.1 -Default value for :prop_tgt:`C_EXTENSIONS` property of targets. - -This variable is used to initialize the :prop_tgt:`C_EXTENSIONS` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`C_EXTENSIONS` target property if set when a target +is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_C_STANDARD.rst b/Help/variable/CMAKE_C_STANDARD.rst index 64ef8ce2966..ec1e5131e79 100644 --- a/Help/variable/CMAKE_C_STANDARD.rst +++ b/Help/variable/CMAKE_C_STANDARD.rst @@ -3,11 +3,8 @@ CMAKE_C_STANDARD .. versionadded:: 3.1 -Default value for :prop_tgt:`C_STANDARD` property of targets. - -This variable is used to initialize the :prop_tgt:`C_STANDARD` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`C_STANDARD` target property if set when a target +is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_C_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_C_STANDARD_REQUIRED.rst index e70b6bd26a8..2bd9d51b5bb 100644 --- a/Help/variable/CMAKE_C_STANDARD_REQUIRED.rst +++ b/Help/variable/CMAKE_C_STANDARD_REQUIRED.rst @@ -3,11 +3,8 @@ CMAKE_C_STANDARD_REQUIRED .. versionadded:: 3.1 -Default value for :prop_tgt:`C_STANDARD_REQUIRED` property of targets. - -This variable is used to initialize the :prop_tgt:`C_STANDARD_REQUIRED` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`C_STANDARD_REQUIRED` target property if set when +a target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst b/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst index ed600202ced..f77e939163a 100644 --- a/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst +++ b/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst @@ -14,3 +14,5 @@ the package has already been found in a previous CMake run, the variables which have been stored in the cache will still be there. In that case it is recommended to remove the cache variables for this package from the cache using the cache editor or :manual:`cmake(1)` ``-U`` + +See also the :variable:`CMAKE_REQUIRE_FIND_PACKAGE_` variable. diff --git a/Help/variable/CMAKE_EXECUTABLE_SUFFIX.rst b/Help/variable/CMAKE_EXECUTABLE_SUFFIX.rst index 356590f6fba..bc4b9df4774 100644 --- a/Help/variable/CMAKE_EXECUTABLE_SUFFIX.rst +++ b/Help/variable/CMAKE_EXECUTABLE_SUFFIX.rst @@ -6,4 +6,5 @@ The suffix for executables on this platform. The suffix to use for the end of an executable filename if any, ``.exe`` on Windows. -``CMAKE_EXECUTABLE_SUFFIX_`` overrides this for language ````. +:variable:`CMAKE_EXECUTABLE_SUFFIX_` overrides this for +language ````. diff --git a/Help/variable/CMAKE_EXECUTABLE_SUFFIX_LANG.rst b/Help/variable/CMAKE_EXECUTABLE_SUFFIX_LANG.rst new file mode 100644 index 00000000000..a68150ebde6 --- /dev/null +++ b/Help/variable/CMAKE_EXECUTABLE_SUFFIX_LANG.rst @@ -0,0 +1,7 @@ +CMAKE_EXECUTABLE_SUFFIX_ +------------------------------ + +The suffix to use for the end of an executable filename of ```` +compiler target architecture, if any. + +It overrides :variable:`CMAKE_EXECUTABLE_SUFFIX` for language ````. diff --git a/Help/variable/CMAKE_FIND_LIBRARY_SUFFIXES.rst b/Help/variable/CMAKE_FIND_LIBRARY_SUFFIXES.rst index 4a64e33e9b6..c2c2609dfc6 100644 --- a/Help/variable/CMAKE_FIND_LIBRARY_SUFFIXES.rst +++ b/Help/variable/CMAKE_FIND_LIBRARY_SUFFIXES.rst @@ -5,5 +5,8 @@ Suffixes to append when looking for libraries. This specifies what suffixes to add to library names when the :command:`find_library` command looks for libraries. On Windows systems this -is typically ``.lib`` and ``.dll``, meaning that when trying to find the -``foo`` library it will look for ``foo.dll`` etc. +is typically ``.lib`` and, depending on the compiler, ``.dll.a``, ``.a`` +(e.g. GCC and Clang), so when it tries to find the ``foo`` library, it will +look for ``[]foo.lib`` and/or ``[]foo[.dll].a``, depending on +the compiler used and the ```` specified in the +:variable:`CMAKE_FIND_LIBRARY_PREFIXES`. diff --git a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst index 53ad2f3e760..45f2d3236b2 100644 --- a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst +++ b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst @@ -63,3 +63,27 @@ Supported pairs are: Specify an alternative ``VCTargetsPath`` value for Visual Studio project files. This allows use of VS platform extension configuration files (``.props`` and ``.targets``) that are not installed with VS. + +Visual Studio Toolset Customization +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**These are unstable interfaces with no compatibility guarantees** +because they hook into undocumented internal CMake implementation details. +Institutions may use these to internally maintain support for non-public +Visual Studio platforms and toolsets, but must accept responsibility to +make updates as changes are made to CMake. + +Additional ``key=value`` pairs are available: + +``customFlagTableDir=`` + .. versionadded:: 3.21 + + Specify the absolute path to a directory from which to load custom + flag tables stored as JSON documents with file names of the form + ``__.json`` or ``_.json``, + where ```` is the :variable:`CMAKE_VS_PLATFORM_NAME`, + ```` is the :variable:`CMAKE_VS_PLATFORM_TOOLSET`, + and ```` is the tool for which the flag table is meant. + **This naming pattern is an internal CMake implementation detail.** + The ```` names are undocumented. The format of the ``.json`` + flag table files is undocumented. diff --git a/Help/variable/CMAKE_HIP_ARCHITECTURES.rst b/Help/variable/CMAKE_HIP_ARCHITECTURES.rst new file mode 100644 index 00000000000..bcc6b35cddb --- /dev/null +++ b/Help/variable/CMAKE_HIP_ARCHITECTURES.rst @@ -0,0 +1,12 @@ +CMAKE_HIP_ARCHITECTURES +----------------------- + +.. versionadded:: 3.21 + +Default value for :prop_tgt:`HIP_ARCHITECTURES` property of targets. + +This is initialized to the architectures reported by ``rocm_agent_enumerator``, +if available, and otherwise to the default chosen by the compiler. + +This variable is used to initialize the :prop_tgt:`HIP_ARCHITECTURES` property +on all targets. See the target property for additional information. diff --git a/Help/variable/CMAKE_HIP_EXTENSIONS.rst b/Help/variable/CMAKE_HIP_EXTENSIONS.rst new file mode 100644 index 00000000000..13987dcdab4 --- /dev/null +++ b/Help/variable/CMAKE_HIP_EXTENSIONS.rst @@ -0,0 +1,10 @@ +CMAKE_HIP_EXTENSIONS +-------------------- + +.. versionadded:: 3.21 + +Default value for :prop_tgt:`HIP_EXTENSIONS` target property if set when a +target is created. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_HIP_STANDARD.rst b/Help/variable/CMAKE_HIP_STANDARD.rst new file mode 100644 index 00000000000..5f151458617 --- /dev/null +++ b/Help/variable/CMAKE_HIP_STANDARD.rst @@ -0,0 +1,10 @@ +CMAKE_HIP_STANDARD +------------------ + +.. versionadded:: 3.21 + +Default value for :prop_tgt:`HIP_STANDARD` target property if set when a target +is created. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_HIP_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_HIP_STANDARD_REQUIRED.rst new file mode 100644 index 00000000000..5d35e4e2892 --- /dev/null +++ b/Help/variable/CMAKE_HIP_STANDARD_REQUIRED.rst @@ -0,0 +1,10 @@ +CMAKE_HIP_STANDARD_REQUIRED +--------------------------- + +.. versionadded:: 3.21 + +Default value for :prop_tgt:`HIP_STANDARD_REQUIRED` target property if set when +a target is created. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_LANG_COMPILER_FRONTEND_VARIANT.rst b/Help/variable/CMAKE_LANG_COMPILER_FRONTEND_VARIANT.rst new file mode 100644 index 00000000000..128b1fbbebe --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_FRONTEND_VARIANT.rst @@ -0,0 +1,18 @@ +CMAKE__COMPILER_FRONTEND_VARIANT +-------------------------------------- + +.. versionadded:: 3.14 + +Identification string of the compiler frontend variant. + +Some compilers have multiple, different frontends for accepting command +line options. (For example ``Clang`` originally only had a frontend +compatible with the ``GNU`` compiler but since its port to Windows +(``Clang-Cl``) it now also supports a frontend compatible with ``MSVC``.) +When CMake detects such a compiler it sets this +variable to what would have been the :variable:`CMAKE__COMPILER_ID` for +the compiler whose frontend it resembles. + +.. note:: + In other words, this variable describes what command line options + and language extensions the compiler frontend expects. diff --git a/Help/variable/CMAKE_LANG_COMPILER_ID.rst b/Help/variable/CMAKE_LANG_COMPILER_ID.rst index 89d9e2757e7..0abedde6a56 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_ID.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_ID.rst @@ -19,6 +19,8 @@ include: Cray = Cray Compiler (cray.com) Embarcadero, Borland = Embarcadero (embarcadero.com) Flang = Flang LLVM Fortran Compiler + Fujitsu = Fujitsu HPC compiler (Trad mode) + FujitsuClang = Fujitsu HPC compiler (Clang mode) G95 = G95 Fortran (g95.org) GNU = GNU Compiler Collection (gcc.gnu.org) GHS = Green Hills Software (www.ghs.com) diff --git a/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst b/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst index 89fd7bcda5f..f16e594469e 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst @@ -6,7 +6,7 @@ CMAKE__COMPILER_LAUNCHER Default value for :prop_tgt:`_COMPILER_LAUNCHER` target property. This variable is used to initialize the property on each target as it is created. This is done only when ```` is ``C``, ``CXX``, ``Fortran``, -``ISPC``, ``OBJC``, ``OBJCXX``, or ``CUDA``. +``HIP``, ``ISPC``, ``OBJC``, ``OBJCXX``, or ``CUDA``. This variable is initialized to the :envvar:`CMAKE__COMPILER_LAUNCHER` environment variable if it is set. diff --git a/Help/variable/CMAKE_LANG_EXTENSIONS.rst b/Help/variable/CMAKE_LANG_EXTENSIONS.rst new file mode 100644 index 00000000000..3a32002f612 --- /dev/null +++ b/Help/variable/CMAKE_LANG_EXTENSIONS.rst @@ -0,0 +1,20 @@ +CMAKE__EXTENSIONS +----------------------- + +The variations are: + +* :variable:`CMAKE_C_EXTENSIONS` +* :variable:`CMAKE_CXX_EXTENSIONS` +* :variable:`CMAKE_CUDA_EXTENSIONS` +* :variable:`CMAKE_HIP_EXTENSIONS` +* :variable:`CMAKE_OBJC_EXTENSIONS` +* :variable:`CMAKE_OBJCXX_EXTENSIONS` + +Default values for :prop_tgt:`_EXTENSIONS` target properties if set when +a target is created. For the compiler's default setting see +:variable:`CMAKE__EXTENSIONS_DEFAULT`. + +For supported CMake versions see the respective pages. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_LANG_EXTENSIONS_DEFAULT.rst b/Help/variable/CMAKE_LANG_EXTENSIONS_DEFAULT.rst new file mode 100644 index 00000000000..a66453acb1d --- /dev/null +++ b/Help/variable/CMAKE_LANG_EXTENSIONS_DEFAULT.rst @@ -0,0 +1,10 @@ +CMAKE__EXTENSIONS_DEFAULT +------------------------------- + +.. versionadded:: 3.22 + +Compiler's default extensions mode. Used as the default for the +:prop_tgt:`_EXTENSIONS` target property when +:variable:`CMAKE__EXTENSIONS` is not set (see :policy:`CMP0128`). + +This variable is read-only. Modifying it is undefined behavior. diff --git a/Help/variable/CMAKE_LANG_FLAGS.rst b/Help/variable/CMAKE_LANG_FLAGS.rst index 14b2694ef37..2784397ac28 100644 --- a/Help/variable/CMAKE_LANG_FLAGS.rst +++ b/Help/variable/CMAKE_LANG_FLAGS.rst @@ -15,3 +15,11 @@ This is initialized for each language from environment variables: Initialized by the :envvar:`CUDAFLAGS` environment variable. * ``CMAKE_Fortran_FLAGS``: Initialized by the :envvar:`FFLAGS` environment variable. + +This value is a command-line string fragment. Therefore, multiple options +should be separated by spaces, and options with spaces should be quoted. + +The flags in this variable will be passed to the compiler before those +in the per-configuration :variable:`CMAKE__FLAGS_` variant, +and before flags added by the :command:`add_compile_options` or +:command:`target_compile_options` commands. diff --git a/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst b/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst index 628b62ba2d7..f0900fdc8dd 100644 --- a/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst +++ b/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst @@ -1,6 +1,9 @@ CMAKE__FLAGS_ --------------------------- -.. versionadded:: 3.11 - Flags for language ```` when building for the ```` configuration. + +The flags in this variable will be passed to the compiler after those +in the :variable:`CMAKE__FLAGS` variable, but before flags added +by the :command:`add_compile_options` or :command:`target_compile_options` +commands. diff --git a/Help/variable/CMAKE_LANG_FLAGS_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_INIT.rst index 67ff2cb3eb0..ca13a29a059 100644 --- a/Help/variable/CMAKE_LANG_FLAGS_INIT.rst +++ b/Help/variable/CMAKE_LANG_FLAGS_INIT.rst @@ -12,6 +12,8 @@ the contents of a ``xxxFLAGS`` environment variable will be prepended, where ``xxx`` will be language-specific but not necessarily the same as ```` (e.g. :envvar:`CXXFLAGS` for ``CXX``, :envvar:`FFLAGS` for ``Fortran``, and so on). +This value is a command-line string fragment. Therefore, multiple options +should be separated by spaces, and options with spaces should be quoted. See also the configuration-specific :variable:`CMAKE__FLAGS__INIT` variable. diff --git a/Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst index e9e04be6ea9..081c4da6b52 100644 --- a/Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst +++ b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst @@ -6,8 +6,20 @@ Implicit linker search path detected for language ````. Compilers typically pass directories containing language runtime libraries and default library search paths when they invoke a linker. These paths are implicit linker search directories for the compiler's -language. CMake automatically detects these directories for each -language and reports the results in this variable. +language. For each language enabled by the :command:`project` or +:command:`enable_language` command, CMake automatically detects these +directories and reports the results in this variable. + +When linking to a static library, CMake adds the implicit link directories +from this variable for each language used in the static library (except +the language whose compiler is used to drive linking). In the case of an +imported static library, the :prop_tgt:`IMPORTED_LINK_INTERFACE_LANGUAGES` +target property lists the languages whose implicit link information is +needed. If any of the languages is not enabled, its value for the +``CMAKE__IMPLICIT_LINK_DIRECTORIES`` variable may instead be provided +by the project. Or, a :variable:`toolchain file ` +may set the variable to a value known for the specified toolchain. It will +either be overridden when the language is enabled, or used as a fallback. Some toolchains read implicit directories from an environment variable such as ``LIBRARY_PATH``. If using such an environment variable, keep its value @@ -18,3 +30,5 @@ If policy :policy:`CMP0060` is not set to ``NEW``, then when a library in one of these directories is given by full path to :command:`target_link_libraries` CMake will generate the ``-l`` form on link lines for historical purposes. + +See also the :variable:`CMAKE__IMPLICIT_LINK_LIBRARIES` variable. diff --git a/Help/variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES.rst b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES.rst index ec164774bd9..0c25489ca8a 100644 --- a/Help/variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES.rst +++ b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES.rst @@ -5,6 +5,20 @@ Implicit link libraries and flags detected for language ````. Compilers typically pass language runtime library names and other flags when they invoke a linker. These flags are implicit link -options for the compiler's language. CMake automatically detects -these libraries and flags for each language and reports the results in -this variable. +options for the compiler's language. For each language enabled +by the :command:`project` or :command:`enable_language` command, +CMake automatically detects these libraries and flags and reports +the results in this variable. + +When linking to a static library, CMake adds the implicit link libraries and +flags from this variable for each language used in the static library (except +the language whose compiler is used to drive linking). In the case of an +imported static library, the :prop_tgt:`IMPORTED_LINK_INTERFACE_LANGUAGES` +target property lists the languages whose implicit link information is +needed. If any of the languages is not enabled, its value for the +``CMAKE__IMPLICIT_LINK_LIBRARIES`` variable may instead be provided +by the project. Or, a :variable:`toolchain file ` +may set the variable to a value known for the specified toolchain. It will +either be overridden when the language is enabled, or used as a fallback. + +See also the :variable:`CMAKE__IMPLICIT_LINK_DIRECTORIES` variable. diff --git a/Help/variable/CMAKE_LANG_LINKER_LAUNCHER.rst b/Help/variable/CMAKE_LANG_LINKER_LAUNCHER.rst new file mode 100644 index 00000000000..b76b9391b1e --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINKER_LAUNCHER.rst @@ -0,0 +1,11 @@ +CMAKE__LINKER_LAUNCHER +---------------------------- + +.. versionadded:: 3.21 + +Default value for :prop_tgt:`_LINKER_LAUNCHER` target property. This +variable is used to initialize the property on each target as it is created. +This is done only when ```` is ``C``, ``CXX``, ``OBJC``, or ``OBJCXX``. + +This variable is initialized to the :envvar:`CMAKE__LINKER_LAUNCHER` +environment variable if it is set. diff --git a/Help/variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG.rst b/Help/variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG.rst new file mode 100644 index 00000000000..50045303968 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG.rst @@ -0,0 +1,9 @@ +CMAKE__LINK_WHAT_YOU_USE_FLAG +----------------------------------- + +.. versionadded:: 3.22 + +Linker flag to be used to configure linker so that all specified libraries on +the command line will be linked into the target. + +See also variable :variable:`CMAKE_LINK_WHAT_YOU_USE_CHECK`. diff --git a/Help/variable/CMAKE_LANG_SIMULATE_ID.rst b/Help/variable/CMAKE_LANG_SIMULATE_ID.rst index 15c87a186fd..3226352a293 100644 --- a/Help/variable/CMAKE_LANG_SIMULATE_ID.rst +++ b/Help/variable/CMAKE_LANG_SIMULATE_ID.rst @@ -1,9 +1,13 @@ CMAKE__SIMULATE_ID ------------------------ -Identification string of "simulated" compiler. +Identification string of the "simulated" compiler. Some compilers simulate other compilers to serve as drop-in replacements. When CMake detects such a compiler it sets this variable to what would have been the :variable:`CMAKE__COMPILER_ID` for the simulated compiler. + +.. note:: + In other words, this variable describes the ABI compatibility + of the generated code. diff --git a/Help/variable/CMAKE_LANG_STANDARD.rst b/Help/variable/CMAKE_LANG_STANDARD.rst new file mode 100644 index 00000000000..0c41e196817 --- /dev/null +++ b/Help/variable/CMAKE_LANG_STANDARD.rst @@ -0,0 +1,19 @@ +CMAKE__STANDARD +--------------------- + +The variations are: + +* :variable:`CMAKE_C_STANDARD` +* :variable:`CMAKE_CXX_STANDARD` +* :variable:`CMAKE_CUDA_STANDARD` +* :variable:`CMAKE_HIP_STANDARD` +* :variable:`CMAKE_OBJC_STANDARD` +* :variable:`CMAKE_OBJCXX_STANDARD` + +Default values for :prop_tgt:`_STANDARD` target properties if set when a +target is created. + +For supported CMake versions see the respective pages. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_LANG_STANDARD_DEFAULT.rst b/Help/variable/CMAKE_LANG_STANDARD_DEFAULT.rst new file mode 100644 index 00000000000..eb63d208a3c --- /dev/null +++ b/Help/variable/CMAKE_LANG_STANDARD_DEFAULT.rst @@ -0,0 +1,7 @@ +CMAKE__STANDARD_DEFAULT +----------------------------- + +.. versionadded:: 3.9 + +The compiler's default standard for the language ````. Empty if the +compiler has no conception of standard levels. diff --git a/Help/variable/CMAKE_LANG_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_LANG_STANDARD_REQUIRED.rst new file mode 100644 index 00000000000..d7fa9b69b5d --- /dev/null +++ b/Help/variable/CMAKE_LANG_STANDARD_REQUIRED.rst @@ -0,0 +1,19 @@ +CMAKE__STANDARD_REQUIRED +------------------------------ + +The variations are: + +* :variable:`CMAKE_C_STANDARD_REQUIRED` +* :variable:`CMAKE_CXX_STANDARD_REQUIRED` +* :variable:`CMAKE_CUDA_STANDARD_REQUIRED` +* :variable:`CMAKE_HIP_STANDARD_REQUIRED` +* :variable:`CMAKE_OBJC_STANDARD_REQUIRED` +* :variable:`CMAKE_OBJCXX_STANDARD_REQUIRED` + +Default values for :prop_tgt:`_STANDARD_REQUIRED` target properties if +set when a target is created. + +For supported CMake versions see the respective pages. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst b/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst index 06b3aa89bad..bca4519a8fd 100644 --- a/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst +++ b/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst @@ -1,5 +1,5 @@ CMAKE_LINK_WHAT_YOU_USE ---------------------------------- +----------------------- .. versionadded:: 3.7 diff --git a/Help/variable/CMAKE_LINK_WHAT_YOU_USE_CHECK.rst b/Help/variable/CMAKE_LINK_WHAT_YOU_USE_CHECK.rst new file mode 100644 index 00000000000..e626641bc80 --- /dev/null +++ b/Help/variable/CMAKE_LINK_WHAT_YOU_USE_CHECK.rst @@ -0,0 +1,10 @@ +CMAKE_LINK_WHAT_YOU_USE_CHECK +----------------------------- + +.. versionadded:: 3.22 + +Defines the command executed after the link step to check libraries usage. +This check is currently only defined on ``ELF`` platforms with value +``ldd -u -r``. + +See also :variable:`CMAKE__LINK_WHAT_YOU_USE_FLAG` variables. diff --git a/Help/variable/CMAKE_MINIMUM_REQUIRED_VERSION.rst b/Help/variable/CMAKE_MINIMUM_REQUIRED_VERSION.rst index f466468d812..8d6b533692d 100644 --- a/Help/variable/CMAKE_MINIMUM_REQUIRED_VERSION.rst +++ b/Help/variable/CMAKE_MINIMUM_REQUIRED_VERSION.rst @@ -2,4 +2,5 @@ CMAKE_MINIMUM_REQUIRED_VERSION ------------------------------ The ```` version of CMake given to the most recent call to the -:command:`cmake_minimum_required(VERSION)` command. +:command:`cmake_minimum_required(VERSION)` command in the current +variable scope or any parent variable scope. diff --git a/Help/variable/CMAKE_NETRC.rst b/Help/variable/CMAKE_NETRC.rst index 2c64a814957..bddfca555d8 100644 --- a/Help/variable/CMAKE_NETRC.rst +++ b/Help/variable/CMAKE_NETRC.rst @@ -3,9 +3,11 @@ CMAKE_NETRC .. versionadded:: 3.11 -This variable is used to initialize the ``NETRC`` option for -:command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands and the -module :module:`ExternalProject`. See those commands for additional -information. +This variable is used to initialize the ``NETRC`` option for the +:command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands. +See those commands for additional information. + +This variable is also used by the :module:`ExternalProject` and +:module:`FetchContent` modules for internal calls to :command:`file(DOWNLOAD)`. The local option takes precedence over this variable. diff --git a/Help/variable/CMAKE_NETRC_FILE.rst b/Help/variable/CMAKE_NETRC_FILE.rst index 97a645efea3..af98170b965 100644 --- a/Help/variable/CMAKE_NETRC_FILE.rst +++ b/Help/variable/CMAKE_NETRC_FILE.rst @@ -3,9 +3,11 @@ CMAKE_NETRC_FILE .. versionadded:: 3.11 -This variable is used to initialize the ``NETRC_FILE`` option for -:command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands and the -module :module:`ExternalProject`. See those commands for additional -information. +This variable is used to initialize the ``NETRC_FILE`` option for the +:command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands. +See those commands for additional information. + +This variable is also used by the :module:`ExternalProject` and +:module:`FetchContent` modules for internal calls to :command:`file(DOWNLOAD)`. The local option takes precedence over this variable. diff --git a/Help/variable/CMAKE_OBJCXX_EXTENSIONS.rst b/Help/variable/CMAKE_OBJCXX_EXTENSIONS.rst index b5225ea68fb..46736aa7d4f 100644 --- a/Help/variable/CMAKE_OBJCXX_EXTENSIONS.rst +++ b/Help/variable/CMAKE_OBJCXX_EXTENSIONS.rst @@ -3,11 +3,8 @@ CMAKE_OBJCXX_EXTENSIONS .. versionadded:: 3.16 -Default value for :prop_tgt:`OBJCXX_EXTENSIONS` property of targets. - -This variable is used to initialize the :prop_tgt:`OBJCXX_EXTENSIONS` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`OBJCXX_EXTENSIONS` target property if set when a +target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJCXX_STANDARD.rst b/Help/variable/CMAKE_OBJCXX_STANDARD.rst index 98e462414fa..0913382a4b9 100644 --- a/Help/variable/CMAKE_OBJCXX_STANDARD.rst +++ b/Help/variable/CMAKE_OBJCXX_STANDARD.rst @@ -3,11 +3,8 @@ CMAKE_OBJCXX_STANDARD .. versionadded:: 3.16 -Default value for :prop_tgt:`OBJCXX_STANDARD` property of targets. - -This variable is used to initialize the :prop_tgt:`OBJCXX_STANDARD` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`OBJCXX_STANDARD` target property if set when a +target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJCXX_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_OBJCXX_STANDARD_REQUIRED.rst index 4b5e77cf052..9afc4eab486 100644 --- a/Help/variable/CMAKE_OBJCXX_STANDARD_REQUIRED.rst +++ b/Help/variable/CMAKE_OBJCXX_STANDARD_REQUIRED.rst @@ -3,11 +3,8 @@ CMAKE_OBJCXX_STANDARD_REQUIRED .. versionadded:: 3.16 -Default value for :prop_tgt:`OBJCXX_STANDARD_REQUIRED` property of targets. - -This variable is used to initialize the :prop_tgt:`OBJCXX_STANDARD_REQUIRED` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`OBJCXX_STANDARD_REQUIRED` target property if set +when a target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJC_EXTENSIONS.rst b/Help/variable/CMAKE_OBJC_EXTENSIONS.rst index d6e3c7dc0dc..9df11f1c8d0 100644 --- a/Help/variable/CMAKE_OBJC_EXTENSIONS.rst +++ b/Help/variable/CMAKE_OBJC_EXTENSIONS.rst @@ -3,11 +3,8 @@ CMAKE_OBJC_EXTENSIONS .. versionadded:: 3.16 -Default value for :prop_tgt:`OBJC_EXTENSIONS` property of targets. - -This variable is used to initialize the :prop_tgt:`OBJC_EXTENSIONS` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`OBJC_EXTENSIONS` target property if set when a +target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJC_STANDARD.rst b/Help/variable/CMAKE_OBJC_STANDARD.rst index fde367dfd26..0b9b63ff260 100644 --- a/Help/variable/CMAKE_OBJC_STANDARD.rst +++ b/Help/variable/CMAKE_OBJC_STANDARD.rst @@ -3,11 +3,8 @@ CMAKE_OBJC_STANDARD .. versionadded:: 3.16 -Default value for :prop_tgt:`OBJC_STANDARD` property of targets. - -This variable is used to initialize the :prop_tgt:`OBJC_STANDARD` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`OBJC_STANDARD` target property if set when a +target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJC_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_OBJC_STANDARD_REQUIRED.rst index 8d26d952a3f..c74db55c154 100644 --- a/Help/variable/CMAKE_OBJC_STANDARD_REQUIRED.rst +++ b/Help/variable/CMAKE_OBJC_STANDARD_REQUIRED.rst @@ -3,11 +3,8 @@ CMAKE_OBJC_STANDARD_REQUIRED .. versionadded:: 3.16 -Default value for :prop_tgt:`OBJC_STANDARD_REQUIRED` property of targets. - -This variable is used to initialize the :prop_tgt:`OBJC_STANDARD_REQUIRED` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`OBJC_STANDARD_REQUIRED` target property if set +when a target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_POLICY_DEFAULT_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_DEFAULT_CMPNNNN.rst index 43582be94d0..d643fb8df1b 100644 --- a/Help/variable/CMAKE_POLICY_DEFAULT_CMPNNNN.rst +++ b/Help/variable/CMAKE_POLICY_DEFAULT_CMPNNNN.rst @@ -9,9 +9,16 @@ the given version unset. Set ``CMAKE_POLICY_DEFAULT_CMP`` to ``OLD`` or ``NEW`` to specify the default for policy ``CMP``, where ```` is the policy number. -This variable should not be set by a project in CMake code; use -:command:`cmake_policy(SET)` instead. Users running CMake may set this -variable in the cache (e.g. ``-DCMAKE_POLICY_DEFAULT_CMP=``) -to set a policy not otherwise set by the project. Set to ``OLD`` to quiet a -policy warning while using old behavior or to ``NEW`` to try building the -project with new behavior. +This variable should not be set by a project in CMake code as a way to +set its own policies; use :command:`cmake_policy(SET)` instead. This +variable is meant to externally set policies for which a project has +not itself been updated: + +* Users running CMake may set this variable in the cache + (e.g. ``-DCMAKE_POLICY_DEFAULT_CMP=``). Set it to ``OLD`` + to quiet a policy warning while using old behavior or to ``NEW`` to + try building the project with new behavior. + +* Projects may set this variable before a call to :command:`add_subdirectory` + that adds a third-party project in order to set its policies without + modifying third-party code. diff --git a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst index 9f68741a511..02316682ed2 100644 --- a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst +++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst @@ -2,8 +2,9 @@ CMAKE_POLICY_WARNING_CMP ------------------------------ Explicitly enable or disable the warning when CMake Policy ``CMP`` -is not set. This is meaningful only for the few policies that do not -warn by default: +has not been set explicitly by :command:`cmake_policy` or implicitly +by :command:`cmake_minimum_required`. This is meaningful +only for the policies that do not warn by default: * ``CMAKE_POLICY_WARNING_CMP0025`` controls the warning for policy :policy:`CMP0025`. @@ -29,6 +30,10 @@ warn by default: policy :policy:`CMP0112`. * ``CMAKE_POLICY_WARNING_CMP0116`` controls the warning for policy :policy:`CMP0116`. +* ``CMAKE_POLICY_WARNING_CMP0126`` controls the warning for + policy :policy:`CMP0126`. +* ``CMAKE_POLICY_WARNING_CMP0128`` controls the warning for + policy :policy:`CMP0128`. This variable should not be set by a project in CMake code. Project developers running CMake may set this variable in their cache to diff --git a/Help/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.rst b/Help/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.rst new file mode 100644 index 00000000000..893f1aec80d --- /dev/null +++ b/Help/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.rst @@ -0,0 +1,14 @@ +CMAKE_REQUIRE_FIND_PACKAGE_ +---------------------------------------- + +.. versionadded:: 3.22 + +Variable for making :command:`find_package` call ``REQUIRED``. + +Every non-``REQUIRED`` :command:`find_package` call in a project can be +turned into ``REQUIRED`` by setting the variable +``CMAKE_REQUIRE_FIND_PACKAGE_`` to ``TRUE``. +This can be used to assert assumptions about build environment and to +ensure the build will fail early if they do not hold. + +See also the :variable:`CMAKE_DISABLE_FIND_PACKAGE_` variable. diff --git a/Help/variable/CMAKE_Swift_MODULE_DIRECTORY.rst b/Help/variable/CMAKE_Swift_MODULE_DIRECTORY.rst index 36949739fff..6036c04bb13 100644 --- a/Help/variable/CMAKE_Swift_MODULE_DIRECTORY.rst +++ b/Help/variable/CMAKE_Swift_MODULE_DIRECTORY.rst @@ -5,6 +5,6 @@ CMAKE_Swift_MODULE_DIRECTORY Swift module output directory. -This variable is used to initialise the :prop_tgt:`Swift_MODULE_DIRECTORY` +This variable is used to initialize the :prop_tgt:`Swift_MODULE_DIRECTORY` property on all the targets. See the target property for additional information. diff --git a/Help/variable/CMAKE_TLS_CAINFO.rst b/Help/variable/CMAKE_TLS_CAINFO.rst new file mode 100644 index 00000000000..07f63660db4 --- /dev/null +++ b/Help/variable/CMAKE_TLS_CAINFO.rst @@ -0,0 +1,9 @@ +CMAKE_TLS_CAINFO +---------------- + +Specify the default value for the :command:`file(DOWNLOAD)` and +:command:`file(UPLOAD)` commands' ``TLS_CAINFO`` options. +It is unset by default. + +This variable is also used by the :module:`ExternalProject` and +:module:`FetchContent` modules for internal calls to :command:`file(DOWNLOAD)`. diff --git a/Help/variable/CMAKE_TLS_VERIFY.rst b/Help/variable/CMAKE_TLS_VERIFY.rst new file mode 100644 index 00000000000..b22f1cefc68 --- /dev/null +++ b/Help/variable/CMAKE_TLS_VERIFY.rst @@ -0,0 +1,17 @@ +CMAKE_TLS_VERIFY +---------------- + +Specify the default value for the :command:`file(DOWNLOAD)` and +:command:`file(UPLOAD)` commands' ``TLS_VERIFY`` options. +If not set, the default is *off*. + +This variable is also used by the :module:`ExternalProject` and +:module:`FetchContent` modules for internal calls to :command:`file(DOWNLOAD)`. + +TLS verification can help provide confidence that one is connecting +to the desired server. When downloading known content, one should +also use file hashes to verify it. + +.. code-block:: cmake + + set(CMAKE_TLS_VERIFY TRUE) diff --git a/Help/variable/CMAKE_TOOLCHAIN_FILE.rst b/Help/variable/CMAKE_TOOLCHAIN_FILE.rst index 168ee74c756..ff8d59a69b8 100644 --- a/Help/variable/CMAKE_TOOLCHAIN_FILE.rst +++ b/Help/variable/CMAKE_TOOLCHAIN_FILE.rst @@ -7,3 +7,9 @@ This variable is specified on the command line when cross-compiling with CMake. It is the path to a file which is read early in the CMake run and which specifies locations for compilers and toolchain utilities, and other target platform and compiler related information. + +Relative paths are allowed and are interpreted first as relative to the +build directory, and if not found, relative to the source directory. + +This is initialized by the :envvar:`CMAKE_TOOLCHAIN_FILE` environment +variable if it is set when a new build tree is first created. diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR.rst index 74db6b143f0..a19e7e148d8 100644 --- a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR.rst +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR.rst @@ -9,10 +9,9 @@ The :ref:`Visual Studio Generators` for VS 2010 and above support using a standalone (non-installed) NVIDIA CUDA toolkit. The path may be specified by a field in :variable:`CMAKE_GENERATOR_TOOLSET` of the form ``cuda=C:\path\to\cuda``. The given directory must at least -contain a folder ``.\nvcc`` and must provide Visual Studio integration -files in path ``.\CUDAVisualStudioIntegration\extras\ -visual_studio_integration\MSBuildExtensions\``. One can create a standalone -CUDA toolkit directory by either opening a installer with 7zip or -copying the files that are extracted by the running installer. -The value may be empty if no path to a standalone CUDA Toolkit was -specified. +contain the nvcc compiler in path ``.\bin`` and must provide Visual Studio +integration files in path ``.\extras\visual_studio_integration\ +MSBuildExtensions\``. One can create a standalone CUDA toolkit directory by +either opening a installer with 7zip or copying the files that are extracted +by the running installer. The value may be empty if no path to a standalone +CUDA Toolkit was specified. diff --git a/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER.rst b/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER.rst new file mode 100644 index 00000000000..5ad589719e7 --- /dev/null +++ b/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER.rst @@ -0,0 +1,13 @@ +CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER +------------------------------------ + +.. versionadded:: 3.22 + +Visual Studio target framework identifier. + +In some cases, the :ref:`Visual Studio Generators` may use an explicit value +for the MSBuild ``TargetFrameworkIdentifier`` setting in ``.csproj`` files. +CMake provides the chosen value in this variable. + +See also :variable:`CMAKE_VS_TARGET_FRAMEWORK_VERSION` and +:variable:`CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION`. diff --git a/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION.rst b/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION.rst new file mode 100644 index 00000000000..8dcb3a72b39 --- /dev/null +++ b/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION.rst @@ -0,0 +1,13 @@ +CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION +----------------------------------------- + +.. versionadded:: 3.22 + +Visual Studio target framework targets version. + +In some cases, the :ref:`Visual Studio Generators` may use an explicit value +for the MSBuild ``TargetFrameworkTargetsVersion`` setting in ``.csproj`` files. +CMake provides the chosen value in this variable. + +See also :variable:`CMAKE_VS_TARGET_FRAMEWORK_VERSION` and +:variable:`CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER`. diff --git a/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_VERSION.rst b/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_VERSION.rst new file mode 100644 index 00000000000..5489f791966 --- /dev/null +++ b/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_VERSION.rst @@ -0,0 +1,17 @@ +CMAKE_VS_TARGET_FRAMEWORK_VERSION +--------------------------------- + +.. versionadded:: 3.22 + +Visual Studio target framework version. + +In some cases, the :ref:`Visual Studio Generators` may use an explicit value +for the MSBuild ``TargetFrameworkVersion`` setting in ``.csproj`` files. +CMake provides the chosen value in this variable. + +See the :variable:`CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION` variable +and :prop_tgt:`DOTNET_TARGET_FRAMEWORK_VERSION` target property to +specify custom ``TargetFrameworkVersion`` values for project targets. + +See also :variable:`CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER` and +:variable:`CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION`. diff --git a/Help/variable/CPACK_CUSTOM_INSTALL_VARIABLES.rst b/Help/variable/CPACK_CUSTOM_INSTALL_VARIABLES.rst new file mode 100644 index 00000000000..1c070b8faf6 --- /dev/null +++ b/Help/variable/CPACK_CUSTOM_INSTALL_VARIABLES.rst @@ -0,0 +1,44 @@ +CPACK_CUSTOM_INSTALL_VARIABLES +------------------------------ + +.. versionadded:: 3.21 + +CPack variables (set via e.g. ``cpack -D``, ``CPackConfig.cmake`` or +:variable:`CPACK_PROJECT_CONFIG_FILE` scripts) are not directly visible in +installation scripts. Instead, one can pass a list of ``varName=value`` +pairs in the ``CPACK_CUSTOM_INSTALL_VARIABLES`` variable. At install time, +each list item will result in a variable of the specified name (``varName``) +being set to the given ``value``. The ``=`` can be omitted for an empty +``value``. + +``CPACK_CUSTOM_INSTALL_VARIABLES`` allows the packaging installation to be +influenced by the user or driving script at CPack runtime without having to +regenerate the install scripts. + +Example +""""""" + +.. code-block:: cmake + + install(FILES large.txt DESTINATION data) + + install(CODE [[ + if(ENABLE_COMPRESSION) + # "run-compressor" is a fictional tool that produces + # large.txt.xz from large.txt and then removes the input file + execute_process(COMMAND run-compressor $ENV{DESTDIR}${CMAKE_INSTALL_PREFIX}/large.txt) + endif() + ]]) + +With the above example snippet, :manual:`cpack ` will by default +run the installation script with ``ENABLE_COMPRESSION`` unset, resulting in +a package containing the uncompressed ``large.txt``. This can be overridden +when invoking :manual:`cpack ` like so: + +.. code-block:: shell + + cpack -D "CPACK_CUSTOM_INSTALL_VARIABLES=ENABLE_COMPRESSION=TRUE" + +The installation script will then run with ``ENABLE_COMPRESSION`` set to +``TRUE``, resulting in a package containing the compressed ``large.txt.xz`` +instead. diff --git a/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst b/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst index 5aeae88a4ec..7e7d431e6d0 100644 --- a/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst +++ b/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst @@ -5,4 +5,10 @@ When saving a failing test's output, this is the maximum size, in bytes, that will be collected by the :command:`ctest_test` command. Defaults to 307200 (300 KiB). +If a test's output contains the literal string "CTEST_FULL_OUTPUT", +the output will not be truncated and may exceed the maximum size. + .. include:: CTEST_CUSTOM_XXX.txt + +For controlling the output collection of passing tests, see +:variable:`CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE`. diff --git a/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst b/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst index 1fbb8c53f47..64367f9a363 100644 --- a/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst +++ b/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst @@ -5,4 +5,10 @@ When saving a passing test's output, this is the maximum size, in bytes, that will be collected by the :command:`ctest_test` command. Defaults to 1024 (1 KiB). +If a test's output contains the literal string "CTEST_FULL_OUTPUT", +the output will not be truncated and may exceed the maximum size. + .. include:: CTEST_CUSTOM_XXX.txt + +For controlling the output collection of failing tests, see +:variable:`CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE`. diff --git a/Help/variable/CTEST_SCRIPT_DIRECTORY.rst b/Help/variable/CTEST_SCRIPT_DIRECTORY.rst new file mode 100644 index 00000000000..77d4e58c93a --- /dev/null +++ b/Help/variable/CTEST_SCRIPT_DIRECTORY.rst @@ -0,0 +1,5 @@ +CTEST_SCRIPT_DIRECTORY +---------------------- + +The directory containing the top-level CTest script. +The concept is similar to :variable:`CMAKE_SOURCE_DIR`. diff --git a/Help/variable/EXECUTABLE_OUTPUT_PATH.rst b/Help/variable/EXECUTABLE_OUTPUT_PATH.rst index 26d3e92a10d..245b9eb2653 100644 --- a/Help/variable/EXECUTABLE_OUTPUT_PATH.rst +++ b/Help/variable/EXECUTABLE_OUTPUT_PATH.rst @@ -3,6 +3,6 @@ EXECUTABLE_OUTPUT_PATH Old executable location variable. -The target property :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` supercedes this +The target property :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` supersedes this variable for a target if it is set. Executable targets are otherwise placed in this directory. diff --git a/Help/variable/MSVC_VERSION.rst b/Help/variable/MSVC_VERSION.rst index 45df37fa002..cbb3a3c3828 100644 --- a/Help/variable/MSVC_VERSION.rst +++ b/Help/variable/MSVC_VERSION.rst @@ -19,6 +19,7 @@ Known version numbers are:: 1900 = VS 14.0 (v140 toolset) 1910-1919 = VS 15.0 (v141 toolset) 1920-1929 = VS 16.0 (v142 toolset) + 1930-1939 = VS 17.0 (v143 toolset) See also the :variable:`CMAKE__COMPILER_VERSION` and :variable:`MSVC_TOOLSET_VERSION` variable. diff --git a/Help/variable/PROJECT-NAME_IS_TOP_LEVEL.rst b/Help/variable/PROJECT-NAME_IS_TOP_LEVEL.rst new file mode 100644 index 00000000000..6718ecfd95a --- /dev/null +++ b/Help/variable/PROJECT-NAME_IS_TOP_LEVEL.rst @@ -0,0 +1,21 @@ +_IS_TOP_LEVEL +--------------------------- + +.. versionadded:: 3.21 + +A boolean variable indicating whether the named project was called in a top +level ``CMakeLists.txt`` file. + +To obtain the value from the most recent call to :command:`project` in +the current directory scope or above, see the +:variable:`PROJECT_IS_TOP_LEVEL` variable. + +The variable value will be true in: + +* the top-level directory of the project +* the top-level directory of an external project added by :module:`ExternalProject` + +The variable value will be false in: + +* a directory added by :command:`add_subdirectory` +* a directory added by :module:`FetchContent` diff --git a/Help/variable/PROJECT_IS_TOP_LEVEL.rst b/Help/variable/PROJECT_IS_TOP_LEVEL.rst new file mode 100644 index 00000000000..7e407045a5c --- /dev/null +++ b/Help/variable/PROJECT_IS_TOP_LEVEL.rst @@ -0,0 +1,32 @@ +PROJECT_IS_TOP_LEVEL +-------------------- + +.. versionadded:: 3.21 + +A boolean variable indicating whether the most recently called +:command:`project` command in the current scope or above was in the top +level ``CMakeLists.txt`` file. + +Some modules should only be included as part of the top level +``CMakeLists.txt`` file to not cause unintended side effects in the build +tree, and this variable can be used to conditionally execute such code. For +example, consider the :module:`CTest` module, which creates targets and +options: + +.. code-block:: cmake + + project(MyProject) + ... + if(PROJECT_IS_TOP_LEVEL) + include(CTest) + endif() + +The variable value will be true in: + +* the top-level directory of the project +* the top-level directory of an external project added by :module:`ExternalProject` + +The variable value will be false in: + +* a directory added by :command:`add_subdirectory` +* a directory added by :module:`FetchContent` diff --git a/Modules/BasicConfigVersion-ExactVersion.cmake.in b/Modules/BasicConfigVersion-ExactVersion.cmake.in index 3507a2283cc..c8d26950070 100644 --- a/Modules/BasicConfigVersion-ExactVersion.cmake.in +++ b/Modules/BasicConfigVersion-ExactVersion.cmake.in @@ -18,14 +18,43 @@ endif() set(PACKAGE_VERSION "@CVF_VERSION@") -if("@CVF_VERSION@" MATCHES "^([0-9]+\\.[0-9]+\\.[0-9]+)\\.") # strip the tweak version - set(CVF_VERSION_NO_TWEAK "${CMAKE_MATCH_1}") +if("@CVF_VERSION@" MATCHES "^([0-9]+)\\.([0-9]+)\\.([0-9]+)") # strip the tweak version + set(CVF_VERSION_MAJOR "${CMAKE_MATCH_1}") + set(CVF_VERSION_MINOR "${CMAKE_MATCH_2}") + set(CVF_VERSION_PATCH "${CMAKE_MATCH_3}") + + if(NOT CVF_VERSION_MAJOR VERSION_EQUAL 0) + string(REGEX REPLACE "^0+" "" CVF_VERSION_MAJOR "${CVF_VERSION_MAJOR}") + endif() + if(NOT CVF_VERSION_MINOR VERSION_EQUAL 0) + string(REGEX REPLACE "^0+" "" CVF_VERSION_MINOR "${CVF_VERSION_MINOR}") + endif() + if(NOT CVF_VERSION_PATCH VERSION_EQUAL 0) + string(REGEX REPLACE "^0+" "" CVF_VERSION_PATCH "${CVF_VERSION_PATCH}") + endif() + + set(CVF_VERSION_NO_TWEAK "${CVF_VERSION_MAJOR}.${CVF_VERSION_MINOR}.${CVF_VERSION_PATCH}") else() set(CVF_VERSION_NO_TWEAK "@CVF_VERSION@") endif() -if(PACKAGE_FIND_VERSION MATCHES "^([0-9]+\\.[0-9]+\\.[0-9]+)\\.") # strip the tweak version - set(REQUESTED_VERSION_NO_TWEAK "${CMAKE_MATCH_1}") +if(PACKAGE_FIND_VERSION MATCHES "^([0-9]+)\\.([0-9]+)\\.([0-9]+)") # strip the tweak version + set(REQUESTED_VERSION_MAJOR "${CMAKE_MATCH_1}") + set(REQUESTED_VERSION_MINOR "${CMAKE_MATCH_2}") + set(REQUESTED_VERSION_PATCH "${CMAKE_MATCH_3}") + + if(NOT REQUESTED_VERSION_MAJOR VERSION_EQUAL 0) + string(REGEX REPLACE "^0+" "" REQUESTED_VERSION_MAJOR "${REQUESTED_VERSION_MAJOR}") + endif() + if(NOT REQUESTED_VERSION_MINOR VERSION_EQUAL 0) + string(REGEX REPLACE "^0+" "" REQUESTED_VERSION_MINOR "${REQUESTED_VERSION_MINOR}") + endif() + if(NOT REQUESTED_VERSION_PATCH VERSION_EQUAL 0) + string(REGEX REPLACE "^0+" "" REQUESTED_VERSION_PATCH "${REQUESTED_VERSION_PATCH}") + endif() + + set(REQUESTED_VERSION_NO_TWEAK + "${REQUESTED_VERSION_MAJOR}.${REQUESTED_VERSION_MINOR}.${REQUESTED_VERSION_PATCH}") else() set(REQUESTED_VERSION_NO_TWEAK "${PACKAGE_FIND_VERSION}") endif() diff --git a/Modules/BasicConfigVersion-SameMajorVersion.cmake.in b/Modules/BasicConfigVersion-SameMajorVersion.cmake.in index dc04e54cd0d..cf73f603d42 100644 --- a/Modules/BasicConfigVersion-SameMajorVersion.cmake.in +++ b/Modules/BasicConfigVersion-SameMajorVersion.cmake.in @@ -17,6 +17,9 @@ else() if("@CVF_VERSION@" MATCHES "^([0-9]+)\\.") set(CVF_VERSION_MAJOR "${CMAKE_MATCH_1}") + if(NOT CVF_VERSION_MAJOR VERSION_EQUAL 0) + string(REGEX REPLACE "^0+" "" CVF_VERSION_MAJOR "${CVF_VERSION_MAJOR}") + endif() else() set(CVF_VERSION_MAJOR "@CVF_VERSION@") endif() diff --git a/Modules/BasicConfigVersion-SameMinorVersion.cmake.in b/Modules/BasicConfigVersion-SameMinorVersion.cmake.in index 9bb2efcfca2..ef21df60f93 100644 --- a/Modules/BasicConfigVersion-SameMinorVersion.cmake.in +++ b/Modules/BasicConfigVersion-SameMinorVersion.cmake.in @@ -19,6 +19,13 @@ else() if("@CVF_VERSION@" MATCHES "^([0-9]+)\\.([0-9]+)") set(CVF_VERSION_MAJOR "${CMAKE_MATCH_1}") set(CVF_VERSION_MINOR "${CMAKE_MATCH_2}") + + if(NOT CVF_VERSION_MAJOR VERSION_EQUAL 0) + string(REGEX REPLACE "^0+" "" CVF_VERSION_MAJOR "${CVF_VERSION_MAJOR}") + endif() + if(NOT CVF_VERSION_MINOR VERSION_EQUAL 0) + string(REGEX REPLACE "^0+" "" CVF_VERSION_MINOR "${CVF_VERSION_MINOR}") + endif() else() set(CVF_VERSION_MAJOR "@CVF_VERSION@") set(CVF_VERSION_MINOR "") @@ -44,6 +51,13 @@ else() set(PACKAGE_VERSION_COMPATIBLE FALSE) endif() else() + if(NOT PACKAGE_FIND_VERSION_MAJOR VERSION_EQUAL 0) + string(REGEX REPLACE "^0+" "" PACKAGE_FIND_VERSION_MAJOR "${PACKAGE_FIND_VERSION_MAJOR}") + endif() + if(NOT PACKAGE_FIND_VERSION_MINOR VERSION_EQUAL 0) + string(REGEX REPLACE "^0+" "" PACKAGE_FIND_VERSION_MINOR "${PACKAGE_FIND_VERSION_MINOR}") + endif() + if((PACKAGE_FIND_VERSION_MAJOR STREQUAL CVF_VERSION_MAJOR) AND (PACKAGE_FIND_VERSION_MINOR STREQUAL CVF_VERSION_MINOR)) set(PACKAGE_VERSION_COMPATIBLE TRUE) diff --git a/Modules/CMakeASM_MASMInformation.cmake b/Modules/CMakeASM_MASMInformation.cmake index 6d1e174e38c..656b75e7d99 100644 --- a/Modules/CMakeASM_MASMInformation.cmake +++ b/Modules/CMakeASM_MASMInformation.cmake @@ -8,7 +8,7 @@ set(ASM_DIALECT "_MASM") set(CMAKE_ASM${ASM_DIALECT}_SOURCE_FILE_EXTENSIONS asm) -set(CMAKE_ASM${ASM_DIALECT}_COMPILE_OBJECT " /c /Fo ") +set(CMAKE_ASM${ASM_DIALECT}_COMPILE_OBJECT " -c -Fo ") # The ASM_MASM compiler id for this compiler is "MSVC", so fill out the runtime library table. set(CMAKE_ASM${ASM_DIALECT}_COMPILE_OPTIONS_MSVC_RUNTIME_LIBRARY_MultiThreaded "") diff --git a/Modules/CMakeASM_NASMInformation.cmake b/Modules/CMakeASM_NASMInformation.cmake index 97cb4880fd8..a72575b4aaf 100644 --- a/Modules/CMakeASM_NASMInformation.cmake +++ b/Modules/CMakeASM_NASMInformation.cmake @@ -35,7 +35,18 @@ if(NOT CMAKE_ASM_NASM_OBJECT_FORMAT) endif() if(NOT CMAKE_ASM_NASM_COMPILE_OBJECT) - set(CMAKE_ASM_NASM_COMPILE_OBJECT " -f ${CMAKE_ASM_NASM_OBJECT_FORMAT} -o ") + set(CMAKE_ASM_NASM_COMPILE_OBJECT " -f ${CMAKE_ASM_NASM_OBJECT_FORMAT} -o ") +endif() + +if(CMAKE_ASM_NASM_COMPILER_ID STREQUAL "NASM") + set(CMAKE_DEPFILE_FLAGS_ASM_NASM "-MD -MT ") + + if((NOT DEFINED CMAKE_DEPENDS_USE_COMPILER OR CMAKE_DEPENDS_USE_COMPILER) + AND CMAKE_GENERATOR MATCHES "Makefiles|WMake") + # dependencies are computed by the compiler itself + set(CMAKE_ASM_NASM_DEPFILE_FORMAT gcc) + set(CMAKE_ASM_NASM_DEPENDS_USE_COMPILER TRUE) + endif() endif() # Load the generic ASMInformation file: diff --git a/Modules/CMakeCCompiler.cmake.in b/Modules/CMakeCCompiler.cmake.in index 7f73891fafc..2b24ff2aadf 100644 --- a/Modules/CMakeCCompiler.cmake.in +++ b/Modules/CMakeCCompiler.cmake.in @@ -5,10 +5,13 @@ set(CMAKE_C_COMPILER_VERSION "@CMAKE_C_COMPILER_VERSION@") set(CMAKE_C_COMPILER_VERSION_INTERNAL "@CMAKE_C_COMPILER_VERSION_INTERNAL@") set(CMAKE_C_COMPILER_WRAPPER "@CMAKE_C_COMPILER_WRAPPER@") set(CMAKE_C_STANDARD_COMPUTED_DEFAULT "@CMAKE_C_STANDARD_COMPUTED_DEFAULT@") +set(CMAKE_C_EXTENSIONS_COMPUTED_DEFAULT "@CMAKE_C_EXTENSIONS_COMPUTED_DEFAULT@") set(CMAKE_C_COMPILE_FEATURES "@CMAKE_C_COMPILE_FEATURES@") set(CMAKE_C90_COMPILE_FEATURES "@CMAKE_C90_COMPILE_FEATURES@") set(CMAKE_C99_COMPILE_FEATURES "@CMAKE_C99_COMPILE_FEATURES@") set(CMAKE_C11_COMPILE_FEATURES "@CMAKE_C11_COMPILE_FEATURES@") +set(CMAKE_C17_COMPILE_FEATURES "@CMAKE_C17_COMPILE_FEATURES@") +set(CMAKE_C23_COMPILE_FEATURES "@CMAKE_C23_COMPILE_FEATURES@") set(CMAKE_C_PLATFORM_ID "@CMAKE_C_PLATFORM_ID@") set(CMAKE_C_SIMULATE_ID "@CMAKE_C_SIMULATE_ID@") @@ -28,18 +31,9 @@ set(CMAKE_COMPILER_IS_GNUCC @CMAKE_COMPILER_IS_GNUCC@) set(CMAKE_C_COMPILER_LOADED 1) set(CMAKE_C_COMPILER_WORKS @CMAKE_C_COMPILER_WORKS@) set(CMAKE_C_ABI_COMPILED @CMAKE_C_ABI_COMPILED@) -set(CMAKE_COMPILER_IS_MINGW @CMAKE_COMPILER_IS_MINGW@) -set(CMAKE_COMPILER_IS_CYGWIN @CMAKE_COMPILER_IS_CYGWIN@) -if(CMAKE_COMPILER_IS_CYGWIN) - set(CYGWIN 1) - set(UNIX 1) -endif() set(CMAKE_C_COMPILER_ENV_VAR "CC") -if(CMAKE_COMPILER_IS_MINGW) - set(MINGW 1) -endif() set(CMAKE_C_COMPILER_ID_RUN 1) set(CMAKE_C_SOURCE_FILE_EXTENSIONS c;m) set(CMAKE_C_IGNORE_EXTENSIONS h;H;o;O;obj;OBJ;def;DEF;rc;RC) diff --git a/Modules/CMakeCCompilerId.c.in b/Modules/CMakeCCompilerId.c.in index 14e1282c835..30ad9824eed 100644 --- a/Modules/CMakeCCompilerId.c.in +++ b/Modules/CMakeCCompilerId.c.in @@ -11,6 +11,12 @@ # define volatile #endif +#if !defined(__has_include) +/* If the compiler does not have __has_include, pretend the answer is + always no. */ +# define __has_include(x) 0 +#endif + @CMAKE_C_COMPILER_ID_CONTENT@ /* Construct the string literal in pieces to prevent the source from @@ -33,22 +39,36 @@ char const *info_cray = "INFO" ":" "compiler_wrapper[CrayPrgEnv]"; @CMAKE_C_COMPILER_ID_PLATFORM_CONTENT@ @CMAKE_C_COMPILER_ID_ERROR_FOR_TEST@ -#if !defined(__STDC__) -# if (defined(_MSC_VER) && !defined(__clang__)) \ - || (defined(__ibmxl__) || defined(__IBMC__)) -# define C_DIALECT "90" +#if !defined(__STDC__) && !defined(__clang__) +# if defined(_MSC_VER) || defined(__ibmxl__) || defined(__IBMC__) +# define C_VERSION "90" # else -# define C_DIALECT +# define C_VERSION # endif +#elif __STDC_VERSION__ > 201710L +# define C_VERSION "23" +#elif __STDC_VERSION__ >= 201710L +# define C_VERSION "17" #elif __STDC_VERSION__ >= 201000L -# define C_DIALECT "11" +# define C_VERSION "11" #elif __STDC_VERSION__ >= 199901L -# define C_DIALECT "99" +# define C_VERSION "99" +#else +# define C_VERSION "90" +#endif +const char* info_language_standard_default = + "INFO" ":" "standard_default[" C_VERSION "]"; + +const char* info_language_extensions_default = "INFO" ":" "extensions_default[" +/* !defined(_MSC_VER) to exclude Clang's MSVC compatibility mode. */ +#if (defined(__clang__) || defined(__GNUC__) || \ + defined(__TI_COMPILER_VERSION__)) && \ + !defined(__STRICT_ANSI__) && !defined(_MSC_VER) + "ON" #else -# define C_DIALECT "90" + "OFF" #endif -const char* info_language_dialect_default = - "INFO" ":" "dialect_default[" C_DIALECT "]"; +"]"; /*--------------------------------------------------------------------------*/ @@ -80,7 +100,8 @@ int main(int argc, char* argv[]) #if defined(__CRAYXT_COMPUTE_LINUX_TARGET) require += info_cray[argc]; #endif - require += info_language_dialect_default[argc]; + require += info_language_standard_default[argc]; + require += info_language_extensions_default[argc]; (void)argv; return require; } diff --git a/Modules/CMakeCInformation.cmake b/Modules/CMakeCInformation.cmake index f6d620f40e9..665f3092786 100644 --- a/Modules/CMakeCInformation.cmake +++ b/Modules/CMakeCInformation.cmake @@ -91,6 +91,14 @@ if(CMAKE_USER_MAKE_RULES_OVERRIDE_C) set(CMAKE_USER_MAKE_RULES_OVERRIDE_C "${_override}") endif() +if(CMAKE_EXECUTABLE_FORMAT STREQUAL "ELF") + if(NOT DEFINED CMAKE_C_LINK_WHAT_YOU_USE_FLAG) + set(CMAKE_C_LINK_WHAT_YOU_USE_FLAG "LINKER:--no-as-needed") + endif() + if(NOT DEFINED CMAKE_LINK_WHAT_YOU_USE_CHECK) + set(CMAKE_LINK_WHAT_YOU_USE_CHECK ldd -u -r) + endif() +endif() # for most systems a module is the same as a shared library # so unless the variable CMAKE_MODULE_EXISTS is set just @@ -115,6 +123,11 @@ if(NOT CMAKE_C_COMPILER_LAUNCHER AND DEFINED ENV{CMAKE_C_COMPILER_LAUNCHER}) CACHE STRING "Compiler launcher for C.") endif() +if(NOT CMAKE_C_LINKER_LAUNCHER AND DEFINED ENV{CMAKE_C_LINKER_LAUNCHER}) + set(CMAKE_C_LINKER_LAUNCHER "$ENV{CMAKE_C_LINKER_LAUNCHER}" + CACHE STRING "Linker launcher for C.") +endif() + include(CMakeCommonLanguageInclude) # now define the following rule variables @@ -191,5 +204,3 @@ if(NOT CMAKE_EXECUTABLE_RPATH_LINK_C_FLAG) endif() set(CMAKE_C_INFORMATION_LOADED 1) - - diff --git a/Modules/CMakeCSharpCompilerId.cs.in b/Modules/CMakeCSharpCompilerId.cs.in index 987f63aa806..b43ec043ec5 100644 --- a/Modules/CMakeCSharpCompilerId.cs.in +++ b/Modules/CMakeCSharpCompilerId.cs.in @@ -15,6 +15,10 @@ namespace CSharp + "Visual Studio" #elif PlatformToolsetv141 + "Visual Studio" +#elif PlatformToolsetv142 + + "Visual Studio" +#elif PlatformToolsetv143 + + "Visual Studio" #else + "unknown" #endif @@ -45,6 +49,10 @@ namespace CSharp + "2015" #elif PlatformToolsetv141 + "2017" +#elif PlatformToolsetv142 + + "2019" +#elif PlatformToolsetv143 + + "2022" #else + "9999" #endif diff --git a/Modules/CMakeCUDACompiler.cmake.in b/Modules/CMakeCUDACompiler.cmake.in index 56ae7324b2d..2f3e9a8ce87 100644 --- a/Modules/CMakeCUDACompiler.cmake.in +++ b/Modules/CMakeCUDACompiler.cmake.in @@ -6,6 +6,7 @@ set(CMAKE_CUDA_COMPILER_VERSION "@CMAKE_CUDA_COMPILER_VERSION@") set(CMAKE_CUDA_DEVICE_LINKER "@CMAKE_CUDA_DEVICE_LINKER@") set(CMAKE_CUDA_FATBINARY "@CMAKE_CUDA_FATBINARY@") set(CMAKE_CUDA_STANDARD_COMPUTED_DEFAULT "@CMAKE_CUDA_STANDARD_COMPUTED_DEFAULT@") +set(CMAKE_CUDA_EXTENSIONS_COMPUTED_DEFAULT "@CMAKE_CUDA_EXTENSIONS_COMPUTED_DEFAULT@") set(CMAKE_CUDA_COMPILE_FEATURES "@CMAKE_CUDA_COMPILE_FEATURES@") set(CMAKE_CUDA03_COMPILE_FEATURES "@CMAKE_CUDA03_COMPILE_FEATURES@") set(CMAKE_CUDA11_COMPILE_FEATURES "@CMAKE_CUDA11_COMPILE_FEATURES@") diff --git a/Modules/CMakeCUDACompilerId.cu.in b/Modules/CMakeCUDACompilerId.cu.in index 91039e5ae97..becb9b4cb41 100644 --- a/Modules/CMakeCUDACompilerId.cu.in +++ b/Modules/CMakeCUDACompilerId.cu.in @@ -16,7 +16,7 @@ char const* info_simulate = "INFO" ":" "simulate[" SIMULATE_ID "]"; @CMAKE_CUDA_COMPILER_ID_PLATFORM_CONTENT@ @CMAKE_CUDA_COMPILER_ID_ERROR_FOR_TEST@ -const char* info_language_dialect_default = "INFO" ":" "dialect_default[" +const char* info_language_standard_default = "INFO" ":" "standard_default[" #if __cplusplus > 202002L "23" #elif __cplusplus > 201703L @@ -32,6 +32,16 @@ const char* info_language_dialect_default = "INFO" ":" "dialect_default[" #endif "]"; +const char* info_language_extensions_default = "INFO" ":" "extensions_default[" +/* !defined(_MSC_VER) to exclude Clang's MSVC compatibility mode. */ +#if (defined(__clang__) || defined(__GNUC__)) && !defined(__STRICT_ANSI__) && \ + !defined(_MSC_VER) + "ON" +#else + "OFF" +#endif +"]"; + /*--------------------------------------------------------------------------*/ int main(int argc, char* argv[]) @@ -48,7 +58,8 @@ int main(int argc, char* argv[]) #ifdef SIMULATE_VERSION_MAJOR require += info_simulate_version[argc]; #endif - require += info_language_dialect_default[argc]; + require += info_language_standard_default[argc]; + require += info_language_extensions_default[argc]; (void)argv; return require; } diff --git a/Modules/CMakeCUDAInformation.cmake b/Modules/CMakeCUDAInformation.cmake index 5fd54c13a8e..e9cfed607bf 100644 --- a/Modules/CMakeCUDAInformation.cmake +++ b/Modules/CMakeCUDAInformation.cmake @@ -9,15 +9,15 @@ endif() set(CMAKE_INCLUDE_FLAG_CUDA "-I") # Set implicit links early so compiler-specific modules can use them. -set(__IMPLICT_LINKS ) +set(__IMPLICIT_LINKS) foreach(dir ${CMAKE_CUDA_HOST_IMPLICIT_LINK_DIRECTORIES}) - string(APPEND __IMPLICT_LINKS " -L\"${dir}\"") + string(APPEND __IMPLICIT_LINKS " -L\"${dir}\"") endforeach() foreach(lib ${CMAKE_CUDA_HOST_IMPLICIT_LINK_LIBRARIES}) if(${lib} MATCHES "/") - string(APPEND __IMPLICT_LINKS " \"${lib}\"") + string(APPEND __IMPLICIT_LINKS " \"${lib}\"") else() - string(APPEND __IMPLICT_LINKS " -l${lib}") + string(APPEND __IMPLICIT_LINKS " -l${lib}") endif() endforeach() @@ -36,6 +36,25 @@ if(CMAKE_CUDA_COMPILER_ID) endif() +# This should be included before the _INIT variables are +# used to initialize the cache. Since the rule variables +# have if blocks on them, users can still define them here. +# But, it should still be after the platform file so changes can +# be made to those values. + +if(CMAKE_USER_MAKE_RULES_OVERRIDE) + # Save the full path of the file so try_compile can use it. + include(${CMAKE_USER_MAKE_RULES_OVERRIDE} RESULT_VARIABLE _override) + set(CMAKE_USER_MAKE_RULES_OVERRIDE "${_override}") +endif() + +if(CMAKE_USER_MAKE_RULES_OVERRIDE_CUDA) + # Save the full path of the file so try_compile can use it. + include(${CMAKE_USER_MAKE_RULES_OVERRIDE_CUDA} RESULT_VARIABLE _override) + set(CMAKE_USER_MAKE_RULES_OVERRIDE_CUDA "${_override}") +endif() + + if(NOT CMAKE_SHARED_LIBRARY_RUNTIME_CUDA_FLAG) set(CMAKE_SHARED_LIBRARY_RUNTIME_CUDA_FLAG ${CMAKE_SHARED_LIBRARY_RUNTIME_C_FLAG}) endif() @@ -81,6 +100,15 @@ if(NOT CMAKE_MODULE_EXISTS) set(CMAKE_SHARED_MODULE_CREATE_CUDA_FLAGS ${CMAKE_SHARED_LIBRARY_CREATE_CUDA_FLAGS}) endif() +if(CMAKE_EXECUTABLE_FORMAT STREQUAL "ELF") + if(NOT DEFINED CMAKE_CUDA_LINK_WHAT_YOU_USE_FLAG) + set(CMAKE_CUDA_LINK_WHAT_YOU_USE_FLAG "LINKER:--no-as-needed") + endif() + if(NOT DEFINED CMAKE_LINK_WHAT_YOU_USE_CHECK) + set(CMAKE_LINK_WHAT_YOU_USE_CHECK ldd -u -r) + endif() +endif() + # add the flags to the cache based # on the initial values computed in the platform/*.cmake files # use _INIT variables so that this only happens the first time @@ -110,17 +138,10 @@ include(CMakeCommonLanguageInclude) # CMAKE_CUDA_COMPILE_SEPARABLE_COMPILATION # CMAKE_CUDA_LINK_EXECUTABLE -if(CMAKE_CUDA_HOST_COMPILER AND CMAKE_CUDA_COMPILER_ID STREQUAL "NVIDIA") - # FIXME: This is too late for the Platform/Windows-NVIDIA-CUDA module to - # see it, so we do not support CMAKE_CUDA_HOST_COMPILER on Windows. - # Move this to Compiler/NVIDIA-CUDA and update the VS generator too. - string(APPEND _CMAKE_CUDA_EXTRA_FLAGS " -ccbin=") -endif() - # create a shared library if(NOT CMAKE_CUDA_CREATE_SHARED_LIBRARY) set(CMAKE_CUDA_CREATE_SHARED_LIBRARY - " -o ${__IMPLICT_LINKS}") + " -o ${__IMPLICIT_LINKS}") endif() # create a shared module copy the shared library rule by default @@ -160,32 +181,32 @@ endif() # compile a cu file into an executable if(NOT CMAKE_CUDA_LINK_EXECUTABLE) set(CMAKE_CUDA_LINK_EXECUTABLE - " -o ${__IMPLICT_LINKS}") + " -o ${__IMPLICIT_LINKS}") endif() # Add implicit host link directories that contain device libraries # to the device link line. -set(__IMPLICT_DLINK_DIRS ${CMAKE_CUDA_IMPLICIT_LINK_DIRECTORIES}) -if(__IMPLICT_DLINK_DIRS) - list(REMOVE_ITEM __IMPLICT_DLINK_DIRS ${CMAKE_CUDA_HOST_IMPLICIT_LINK_DIRECTORIES}) +set(__IMPLICIT_DLINK_DIRS ${CMAKE_CUDA_IMPLICIT_LINK_DIRECTORIES}) +if(__IMPLICIT_DLINK_DIRS) + list(REMOVE_ITEM __IMPLICIT_DLINK_DIRS ${CMAKE_CUDA_HOST_IMPLICIT_LINK_DIRECTORIES}) endif() -set(__IMPLICT_DLINK_FLAGS ) -foreach(dir ${__IMPLICT_DLINK_DIRS}) +set(__IMPLICIT_DLINK_FLAGS) +foreach(dir ${__IMPLICIT_DLINK_DIRS}) if(EXISTS "${dir}/libcurand_static.a") - string(APPEND __IMPLICT_DLINK_FLAGS " -L\"${dir}\"") + string(APPEND __IMPLICIT_DLINK_FLAGS " -L\"${dir}\"") endif() endforeach() -unset(__IMPLICT_DLINK_DIRS) +unset(__IMPLICIT_DLINK_DIRS) #These are used when linking relocatable (dc) cuda code if(NOT CMAKE_CUDA_DEVICE_LINK_LIBRARY) set(CMAKE_CUDA_DEVICE_LINK_LIBRARY - " ${_CMAKE_CUDA_EXTRA_FLAGS} ${CMAKE_CUDA_COMPILE_OPTIONS_PIC} ${_CMAKE_CUDA_EXTRA_DEVICE_LINK_FLAGS} -shared -dlink -o ${__IMPLICT_DLINK_FLAGS}") + " ${_CMAKE_CUDA_EXTRA_FLAGS} ${CMAKE_CUDA_COMPILE_OPTIONS_PIC} ${_CMAKE_CUDA_EXTRA_DEVICE_LINK_FLAGS} -shared -dlink -o ${__IMPLICIT_DLINK_FLAGS}") endif() if(NOT CMAKE_CUDA_DEVICE_LINK_EXECUTABLE) set(CMAKE_CUDA_DEVICE_LINK_EXECUTABLE - " ${_CMAKE_CUDA_EXTRA_FLAGS} ${CMAKE_CUDA_COMPILE_OPTIONS_PIC} ${_CMAKE_CUDA_EXTRA_DEVICE_LINK_FLAGS} -shared -dlink -o ${__IMPLICT_DLINK_FLAGS}") + " ${_CMAKE_CUDA_EXTRA_FLAGS} ${CMAKE_CUDA_COMPILE_OPTIONS_PIC} ${_CMAKE_CUDA_EXTRA_DEVICE_LINK_FLAGS} -shared -dlink -o ${__IMPLICIT_DLINK_FLAGS}") endif() # Used when device linking is handled by CMake. @@ -193,6 +214,6 @@ if(NOT CMAKE_CUDA_DEVICE_LINK_COMPILE) set(CMAKE_CUDA_DEVICE_LINK_COMPILE " ${_CMAKE_CUDA_EXTRA_FLAGS} -D__CUDA_INCLUDE_COMPILER_INTERNAL_HEADERS__ -D__NV_EXTRA_INITIALIZATION=\"\" -D__NV_EXTRA_FINALIZATION=\"\" -DREGISTERLINKBINARYFILE=\\\"\\\" -DFATBINFILE=\\\"\\\" ${_CMAKE_COMPILE_AS_CUDA_FLAG} -c \"${CMAKE_CUDA_COMPILER_TOOLKIT_LIBRARY_ROOT}/bin/crt/link.stub\" -o ") endif() -unset(__IMPLICT_DLINK_FLAGS) +unset(__IMPLICIT_DLINK_FLAGS) set(CMAKE_CUDA_INFORMATION_LOADED 1) diff --git a/Modules/CMakeCXXCompiler.cmake.in b/Modules/CMakeCXXCompiler.cmake.in index 45acfe732b0..534e96055f9 100644 --- a/Modules/CMakeCXXCompiler.cmake.in +++ b/Modules/CMakeCXXCompiler.cmake.in @@ -5,6 +5,7 @@ set(CMAKE_CXX_COMPILER_VERSION "@CMAKE_CXX_COMPILER_VERSION@") set(CMAKE_CXX_COMPILER_VERSION_INTERNAL "@CMAKE_CXX_COMPILER_VERSION_INTERNAL@") set(CMAKE_CXX_COMPILER_WRAPPER "@CMAKE_CXX_COMPILER_WRAPPER@") set(CMAKE_CXX_STANDARD_COMPUTED_DEFAULT "@CMAKE_CXX_STANDARD_COMPUTED_DEFAULT@") +set(CMAKE_CXX_EXTENSIONS_COMPUTED_DEFAULT "@CMAKE_CXX_EXTENSIONS_COMPUTED_DEFAULT@") set(CMAKE_CXX_COMPILE_FEATURES "@CMAKE_CXX_COMPILE_FEATURES@") set(CMAKE_CXX98_COMPILE_FEATURES "@CMAKE_CXX98_COMPILE_FEATURES@") set(CMAKE_CXX11_COMPILE_FEATURES "@CMAKE_CXX11_COMPILE_FEATURES@") @@ -31,20 +32,11 @@ set(CMAKE_COMPILER_IS_GNUCXX @CMAKE_COMPILER_IS_GNUCXX@) set(CMAKE_CXX_COMPILER_LOADED 1) set(CMAKE_CXX_COMPILER_WORKS @CMAKE_CXX_COMPILER_WORKS@) set(CMAKE_CXX_ABI_COMPILED @CMAKE_CXX_ABI_COMPILED@) -set(CMAKE_COMPILER_IS_MINGW @CMAKE_COMPILER_IS_MINGW@) -set(CMAKE_COMPILER_IS_CYGWIN @CMAKE_COMPILER_IS_CYGWIN@) -if(CMAKE_COMPILER_IS_CYGWIN) - set(CYGWIN 1) - set(UNIX 1) -endif() set(CMAKE_CXX_COMPILER_ENV_VAR "CXX") -if(CMAKE_COMPILER_IS_MINGW) - set(MINGW 1) -endif() set(CMAKE_CXX_COMPILER_ID_RUN 1) -set(CMAKE_CXX_SOURCE_FILE_EXTENSIONS C;M;c++;cc;cpp;cxx;m;mm;mpp;CPP) +set(CMAKE_CXX_SOURCE_FILE_EXTENSIONS C;M;c++;cc;cpp;cxx;m;mm;mpp;CPP;ixx;cppm) set(CMAKE_CXX_IGNORE_EXTENSIONS inl;h;hpp;HPP;H;o;O;obj;OBJ;def;DEF;rc;RC) foreach (lang C OBJC OBJCXX) diff --git a/Modules/CMakeCXXCompilerId.cpp.in b/Modules/CMakeCXXCompilerId.cpp.in index a67caba2c38..e7a54874264 100644 --- a/Modules/CMakeCXXCompilerId.cpp.in +++ b/Modules/CMakeCXXCompilerId.cpp.in @@ -5,6 +5,12 @@ # error "A C compiler has been selected for C++." #endif +#if !defined(__has_include) +/* If the compiler does not have __has_include, pretend the answer is + always no. */ +# define __has_include(x) 0 +#endif + @CMAKE_CXX_COMPILER_ID_CONTENT@ /* Construct the string literal in pieces to prevent the source from @@ -43,7 +49,7 @@ char const *info_cray = "INFO" ":" "compiler_wrapper[CrayPrgEnv]"; # define CXX_STD __cplusplus #endif -const char* info_language_dialect_default = "INFO" ":" "dialect_default[" +const char* info_language_standard_default = "INFO" ":" "standard_default[" #if CXX_STD > 202002L "23" #elif CXX_STD > 201703L @@ -59,6 +65,17 @@ const char* info_language_dialect_default = "INFO" ":" "dialect_default[" #endif "]"; +const char* info_language_extensions_default = "INFO" ":" "extensions_default[" +/* !defined(_MSC_VER) to exclude Clang's MSVC compatibility mode. */ +#if (defined(__clang__) || defined(__GNUC__) || \ + defined(__TI_COMPILER_VERSION__)) && \ + !defined(__STRICT_ANSI__) && !defined(_MSC_VER) + "ON" +#else + "OFF" +#endif +"]"; + /*--------------------------------------------------------------------------*/ int main(int argc, char* argv[]) @@ -81,7 +98,8 @@ int main(int argc, char* argv[]) #if defined(__CRAYXT_COMPUTE_LINUX_TARGET) require += info_cray[argc]; #endif - require += info_language_dialect_default[argc]; + require += info_language_standard_default[argc]; + require += info_language_extensions_default[argc]; (void)argv; return require; } diff --git a/Modules/CMakeCXXInformation.cmake b/Modules/CMakeCXXInformation.cmake index dbb4366757c..53abf378d50 100644 --- a/Modules/CMakeCXXInformation.cmake +++ b/Modules/CMakeCXXInformation.cmake @@ -193,6 +193,15 @@ foreach(type SHARED_LIBRARY SHARED_MODULE EXE) endif() endforeach() +if(CMAKE_EXECUTABLE_FORMAT STREQUAL "ELF") + if(NOT DEFINED CMAKE_CXX_LINK_WHAT_YOU_USE_FLAG) + set(CMAKE_CXX_LINK_WHAT_YOU_USE_FLAG "LINKER:--no-as-needed") + endif() + if(NOT DEFINED CMAKE_LINK_WHAT_YOU_USE_CHECK) + set(CMAKE_LINK_WHAT_YOU_USE_CHECK ldd -u -r) + endif() +endif() + # add the flags to the cache based # on the initial values computed in the platform/*.cmake files # use _INIT variables so that this only happens the first time @@ -212,6 +221,11 @@ if(NOT CMAKE_CXX_COMPILER_LAUNCHER AND DEFINED ENV{CMAKE_CXX_COMPILER_LAUNCHER}) CACHE STRING "Compiler launcher for CXX.") endif() +if(NOT CMAKE_CXX_LINKER_LAUNCHER AND DEFINED ENV{CMAKE_CXX_LINKER_LAUNCHER}) + set(CMAKE_CXX_LINKER_LAUNCHER "$ENV{CMAKE_CXX_LINKER_LAUNCHER}" + CACHE STRING "Linker launcher for CXX.") +endif() + include(CMakeCommonLanguageInclude) # now define the following rules: diff --git a/Modules/CMakeCheckCompilerFlagCommonPatterns.cmake b/Modules/CMakeCheckCompilerFlagCommonPatterns.cmake index 2dc75d694b0..bda1d711108 100644 --- a/Modules/CMakeCheckCompilerFlagCommonPatterns.cmake +++ b/Modules/CMakeCheckCompilerFlagCommonPatterns.cmake @@ -8,7 +8,7 @@ macro (CHECK_COMPILER_FLAG_COMMON_PATTERNS _VAR) set(${_VAR} - FAIL_REGEX "[Uu]nrecogni[sz]ed .*option" # GNU, NAG + FAIL_REGEX "[Uu]nrecogni[sz]ed .*option" # GNU, NAG, Fujitsu FAIL_REGEX "switch .* is no longer supported" # GNU FAIL_REGEX "unknown .*option" # Clang FAIL_REGEX "optimization flag .* not supported" # Clang @@ -32,5 +32,6 @@ macro (CHECK_COMPILER_FLAG_COMMON_PATTERNS _VAR) FAIL_REGEX "Warning: illegal option" # SunStudio 12 FAIL_REGEX "[Ww]arning: Invalid suboption" # Fujitsu FAIL_REGEX "An invalid option .* appears on the command line" # Cray + FAIL_REGEX "WARNING: invalid compiler option" # TI armcl ) endmacro () diff --git a/Modules/CMakeCompilerIdDetection.cmake b/Modules/CMakeCompilerIdDetection.cmake index 214d58a8ef3..e6b3ee32e68 100644 --- a/Modules/CMakeCompilerIdDetection.cmake +++ b/Modules/CMakeCompilerIdDetection.cmake @@ -13,12 +13,12 @@ endfunction() function(compiler_id_detection outvar lang) - if (NOT lang STREQUAL Fortran AND NOT lang STREQUAL CSharp - AND NOT lang STREQUAL ISPC) + if (NOT "x${lang}" STREQUAL "xFortran" AND NOT "x${lang}" STREQUAL "xCSharp" + AND NOT "x${lang}" STREQUAL "xISPC") file(GLOB lang_files "${CMAKE_ROOT}/Modules/Compiler/*-DetermineCompiler.cmake") set(nonlang CXX) - if (lang STREQUAL CXX) + if ("x${lang}" STREQUAL "xCXX") set(nonlang C) endif() @@ -42,7 +42,7 @@ function(compiler_id_detection outvar lang) # Order is relevant here. For example, compilers which pretend to be # GCC must appear before the actual GCC. - if (lang STREQUAL CXX) + if ("x${lang}" STREQUAL "xCXX") list(APPEND ordered_compilers Comeau ) @@ -66,10 +66,11 @@ function(compiler_id_detection outvar lang) PGI Cray TI + FujitsuClang Fujitsu GHS ) - if (lang STREQUAL C) + if ("x${lang}" STREQUAL "xC") list(APPEND ordered_compilers TinyCC Bruce @@ -80,19 +81,21 @@ function(compiler_id_detection outvar lang) ARMCC AppleClang ARMClang + ) + list(APPEND ordered_compilers Clang GNU MSVC ADSP IAR ) - if (lang STREQUAL C) + if ("x${lang}" STREQUAL "xC") list(APPEND ordered_compilers SDCC ) endif() - if(lang STREQUAL CUDA) + if("x${lang}" STREQUAL "xCUDA") set(ordered_compilers NVIDIA Clang) endif() diff --git a/Modules/CMakeDependentOption.cmake b/Modules/CMakeDependentOption.cmake index 96855d28f1c..b7c478f6440 100644 --- a/Modules/CMakeDependentOption.cmake +++ b/Modules/CMakeDependentOption.cmake @@ -10,44 +10,62 @@ Macro to provide an option dependent on other options. This macro presents an option to the user only if a set of other conditions are true. -Usage: +.. command:: cmake_dependent_option -.. code-block:: cmake + .. code-block:: cmake - cmake_dependent_option(