Merge topic 'gcc-implicit-libs' into release-4.3 168785c67e GCC: Fix linking mixed C and C++ binaries with GCC 16+ Acked-by: Kitware Robot <kwrobot@kitware.com> Merge-request: !12027
diff --git a/.clang-tidy b/.clang-tidy index 35503d4..f83585a 100644 --- a/.clang-tidy +++ b/.clang-tidy
@@ -36,6 +36,7 @@ -modernize-use-emplace,\ -modernize-use-nodiscard,\ -modernize-use-noexcept,\ +-modernize-use-scoped-lock,\ -modernize-use-trailing-return-type,\ -modernize-use-transparent-functors,\ performance-*,\ @@ -62,6 +63,7 @@ -readability-static-accessed-through-instance,\ -readability-suspicious-call-argument,\ -readability-uppercase-literal-suffix,\ +-readability-use-concise-preprocessor-directives,\ -readability-use-std-min-max,\ cmake-*,\ -cmake-ostringstream-use-cmstrcat,\
diff --git a/.codespellrc b/.codespellrc index 383e9ce..1149f41 100644 --- a/.codespellrc +++ b/.codespellrc
@@ -20,15 +20,15 @@ Tests/StringFileTest/test.utf8, Utilities/cm*, *.pfx, + *-stdout.txt, + *-stderr.txt # noqa: spellcheck off ignore-words-list = abd, - aci, ags, ake, ans, - ba, ccompiler, cconfiguration, certi, @@ -42,9 +42,6 @@ filetest, fo, helpfull, - hiden, - isnt, - keypair, nd, ned, nin, @@ -55,7 +52,6 @@ seh, ser, te, - upto, varn, vas, wee,
diff --git a/.git-remote-files b/.git-remote-files new file mode 100644 index 0000000..ec5762d --- /dev/null +++ b/.git-remote-files
@@ -0,0 +1,5 @@ +[file "update-common.sh" from "https://gitlab.kitware.com/utils/git-import-third-party.git"] +commit = 8f83cbcdac0af41574abfb632dfbe2c403948803 +branch = master +target = Utilities/Scripts/update-third-party.bash +comment = Core third party import logic
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index cccd68c..289c6c6 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml
@@ -31,7 +31,9 @@ # - a "base image" # - a build script # - tags for the jobs -# - rules for when to run the job +# - the `.rules` block +# - see `.gitlab/rules.yml` for variables jobs may set to control when the +# job is executed # # Additionally, jobs may also contain: # @@ -40,6 +42,7 @@ ################################################################################ # Job prefixes: +# - `a:` analysis # - `b:` build # - `k:` package # - `l:` lint @@ -55,22 +58,28 @@ - .cmake_prep_source_linux - .linux_x86_64_tags - .cmake_release_artifacts - - .run_only_for_package + - .rules variables: CMAKE_CI_ARTIFACTS_NAME: "artifacts-source" + CMAKE_CI_JOB_PACKAGE_ONLY: "true" p:doc-package: extends: - - .fedora42_sphinx_package + - .fedora43_sphinx_package - .cmake_prep_doc_linux - .linux_x86_64_tags - .cmake_doc_artifacts - - .run_only_for_package + - .rules + variables: + CMAKE_CI_JOB_PACKAGE_ONLY: "true" u:source-package: extends: - .rsync_upload_package - - .run_only_for_package + - .rules + variables: + CMAKE_CI_JOB_PACKAGE_ONLY: "true" + CMAKE_CI_JOB_NO_MR: "true" needs: - p:source-package @@ -78,20 +87,29 @@ extends: - .cmake_version_update_linux - .linux_x86_64_tags - - .run_version_update + - .rules + variables: + CMAKE_CI_JOB_UPDATES_VERSION: "true" + CMAKE_CI_JOB_NO_MR: "true" # Documentation builds b:cmake.org-help: extends: - .cmake_org_help - - .run_cmake_org_help + - .rules + variables: + CMAKE_CI_JOB_UPDATES_WEBSITE_HELP: "true" + CMAKE_CI_JOB_NO_MR: "true" needs: [] u:cmake.org-help: extends: - .rsync_upload_help - - .run_cmake_org_help + - .rules + variables: + CMAKE_CI_JOB_UPDATES_WEBSITE_HELP: "true" + CMAKE_CI_JOB_NO_MR: "true" needs: - b:cmake.org-help @@ -101,45 +119,138 @@ extends: - .cmake_spellcheck_linux - .linux_x86_64_tags - - .run_automatically + - .rules -l:iwyu-debian12: +l:iwyu-debian13: extends: - - .debian12_iwyu + - .debian13_iwyu - .cmake_build_linux - .linux_x86_64_tags - .cmake_cdash_artifacts - - .run_automatically + - .rules -l:tidy-fedora42: +l:tidy-fedora43: extends: - - .fedora42_tidy + - .fedora43_tidy - .cmake_build_linux - .cmake_tidy_artifacts - .linux_x86_64_tags - .cmake_cdash_artifacts - - .run_automatically + - .rules -l:sphinx-fedora42: +l:sphinx-fedora43: extends: - - .fedora42_sphinx + - .fedora43_sphinx - .cmake_build_linux - .cmake_sphinx_artifacts - .linux_x86_64_tags - - .run_automatically + - .rules variables: CMAKE_CI_JOB_CONTINUOUS: "true" CMAKE_CI_JOB_HELP: "true" -l:clang-analyzer-fedora42: +l:clang-analyzer-fedora43: extends: - - .fedora42_clang_analyzer + - .fedora43_clang_analyzer - .cmake_build_linux - .linux_x86_64_tags - - .run_automatically + - .rules variables: CMAKE_CI_JOB_NIGHTLY: "true" +l:clang-fuzzing-fedora43: + extends: + - .fedora43_clang_fuzzing + - .cmake_build_linux + - .linux_x86_64_tags + - .rules + +l:clazy-fedora43: + extends: + - .fedora43_clazy + - .cmake_build_linux + - .linux_x86_64_tags + - .rules + +# Coverage builds + +b:fedora43-gcc-gcov: + extends: + - .fedora43_gcc_gcov + - .cmake_build_linux + - .cmake_build_artifacts + - .linux_x86_64_tags + - .rules + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + CMAKE_CI_JOB_RUN_MANUALLY: "true" + +t:fedora43-gcc-gcov: + extends: + - .fedora43_gcc_gcov + - .cmake_test_linux + - .cmake_coverage_artifacts + - .linux_x86_64_tags_x11 + - .rules + # Run coverage analysis even if the tests fail. + allow_failure: true + needs: + - b:fedora43-gcc-gcov + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + +a:fedora43-gcc-gcov: + extends: + - .fedora43_gcc_gcov + - .cmake_coverage_linux + - .cmake_cdash_artifacts + - .linux_x86_64_tags + - .rules + needs: + - t:fedora43-gcc-gcov + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + +b:fedora43-bullseye-coverage: + extends: + - .fedora43_bullseye_coverage + - .cmake_build_linux + - .cmake_build_artifacts + - .linux_x86_64_tags + - .rules + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + CMAKE_CI_JOB_NO_MR: "true" + CMAKE_CI_JOB_RUN_MANUALLY: "true" + +t:fedora43-bullseye-coverage: + extends: + - .fedora43_bullseye_coverage + - .cmake_test_linux + - .cmake_coverage_artifacts + - .linux_x86_64_tags_x11 + - .rules + # Run coverage analysis even if the tests fail. + allow_failure: true + needs: + - b:fedora43-bullseye-coverage + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + CMAKE_CI_JOB_NO_MR: "true" + +a:fedora43-bullseye-coverage: + extends: + - .fedora43_bullseye_coverage + - .cmake_coverage_linux + - .cmake_cdash_artifacts + - .linux_x86_64_tags + - .rules + needs: + - t:fedora43-bullseye-coverage + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + CMAKE_CI_JOB_NO_MR: "true" + # Linux builds b:centos7-x86_64: @@ -148,164 +259,195 @@ - .cmake_build_linux_release - .cmake_release_artifacts - .linux_x86_64_tags - - .run_manually + - .rules variables: CMAKE_CI_ARTIFACTS_NAME: "artifacts-centos7-x86_64" + CMAKE_CI_JOB_RUN_MANUALLY: "true" -b:centos7-aarch64: +b:centos8-aarch64: extends: - .linux_release_aarch64 - .cmake_build_linux_release - .cmake_release_artifacts - .linux_aarch64_tags - - .run_manually + - .rules variables: - CMAKE_CI_ARTIFACTS_NAME: "artifacts-centos7-aarch64" - CMAKE_CI_NO_MR: "true" + CMAKE_CI_ARTIFACTS_NAME: "artifacts-centos8-aarch64" + CMAKE_CI_JOB_NO_MR: "true" + CMAKE_CI_JOB_RUN_MANUALLY: "true" -t:debian12-ninja: +t:debian13-ninja: extends: - - .debian12_ninja + - .debian13_ninja - .cmake_test_linux_release - .linux_x86_64_tags - .cmake_junit_artifacts - - .run_dependent + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY_NINJA: "true" -t:debian12-aarch64-ninja: +t:debian13-aarch64-ninja: extends: - - .debian12_aarch64_ninja + - .debian13_aarch64_ninja - .cmake_test_linux_release - .linux_aarch64_tags - .cmake_junit_artifacts - - .run_dependent - - .needs_centos7_aarch64 + - .rules + - .needs_centos8_aarch64 variables: - CMAKE_CI_NO_MR: "true" + CMAKE_CI_JOB_NO_MR: "true" -t:debian12-ninja-clang: +t:debian13-ninja-clang: extends: - - .debian12_ninja_clang + - .debian13_ninja_clang - .cmake_test_linux_release - .linux_x86_64_tags - - .run_dependent + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" -t:debian12-makefiles-clang: +t:debian13-makefiles-clang: extends: - - .debian12_makefiles_clang + - .debian13_makefiles_clang - .cmake_test_linux_release - .linux_x86_64_tags - - .run_dependent + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" -t:debian12-ninja-multi-symlinked: +t:debian13-ninja-multi-symlinked: extends: - - .debian12_ninja_multi_symlinked + - .debian13_ninja_multi_symlinked - .cmake_test_linux_release - .linux_x86_64_tags - .cmake_junit_artifacts - - .run_dependent + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" CMAKE_CI_JOB_NIGHTLY_NINJA: "true" -t:debian12-hip-radeon: +t:debian13-hip-radeon: extends: - - .debian12_hip_radeon + - .debian13_hip_radeon - .cmake_test_linux_release - - .linux_x86_64_tags_rocm5.2 - - .run_dependent + - .linux_x86_64_tags_rocm5.7 + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" -t:fedora42-hip-radeon: +t:fedora43-hip-radeon: extends: - - .fedora42_hip_radeon + - .fedora43_hip_radeon - .cmake_test_linux_release - .linux_x86_64_tags_rocm6.2 - - .run_dependent + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" -t:fedora42-makefiles-lfortran: +t:fedora43-makefiles-lfortran: extends: - - .fedora42_makefiles_lfortran + - .fedora43_makefiles_lfortran - .cmake_test_linux_release - .linux_x86_64_tags - - .run_dependent + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" -t:fedora42-ninja-lfortran: +t:fedora43-ninja-lfortran: extends: - - .fedora42_ninja_lfortran + - .fedora43_ninja_lfortran - .cmake_test_linux_release - .linux_x86_64_tags - - .run_dependent + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" -t:fedora42-ninja-clang: +t:fedora43-ninja-multi: extends: - - .fedora42_ninja_clang + - .fedora43_ninja_multi - .cmake_test_linux_release - .linux_x86_64_tags - - .run_dependent + - .rules - .needs_centos7_x86_64 - variables: - CMAKE_CI_JOB_NIGHTLY: "true" -t:fedora42-ninja-multi-clang: +t:fedora43-ninja-clang: extends: - - .fedora42_ninja_multi_clang + - .fedora43_ninja_clang - .cmake_test_linux_release - .linux_x86_64_tags - - .run_dependent + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" -t:fedora42-makefiles-clang: +t:fedora43-ninja-multi-clang: extends: - - .fedora42_makefiles_clang + - .fedora43_ninja_multi_clang - .cmake_test_linux_release - .linux_x86_64_tags - - .run_dependent + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" -t:fedora42-makefiles: +t:fedora43-makefiles-clang: extends: - - .fedora42_makefiles + - .fedora43_makefiles_clang + - .cmake_test_linux_release + - .linux_x86_64_tags + - .rules + - .needs_centos7_x86_64 + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + +t:fedora43-makefiles: + extends: + - .fedora43_makefiles - .cmake_test_linux_release - .linux_x86_64_v3_tags - - .run_dependent + - .rules - .needs_centos7_x86_64 -t:fedora42-makefiles-nospace: +t:fedora43-makefiles-nospace: extends: - - .fedora42_makefiles + - .fedora43_makefiles - .cmake_test_linux_release - .linux_x86_64_v3_tags - .cmake_junit_artifacts - - .run_dependent + - .rules - .needs_centos7_x86_64 variables: GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake-ci" - CMAKE_CI_BUILD_NAME: fedora42_makefiles_nospace + CMAKE_CI_BUILD_NAME: fedora43_makefiles_nospace + CMAKE_CI_JOB_NIGHTLY: "true" + +t:fedora43-fastbuild: + extends: + - .fedora43_fastbuild + - .cmake_test_linux_release + - .linux_x86_64_v3_tags + - .rules + - .needs_centos7_x86_64 + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + +t:fedora43-instrumentation: + extends: + - .fedora43_ninja_instrumentation + - .cmake_test_linux_release + - .linux_x86_64_tags + - .rules + - .needs_centos7_x86_64 + - .cmake_junit_artifacts + variables: CMAKE_CI_JOB_NIGHTLY: "true" t:nvhpc24.9-ninja: @@ -313,7 +455,7 @@ - .nvhpc_ninja - .cmake_test_linux_release - .linux_x86_64_v3_tags_cuda_arch_52 - - .run_dependent + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" @@ -323,7 +465,7 @@ - .cuda9.2_nvidia - .cmake_test_linux_release - .linux_x86_64_tags_cuda_arch_30 - - .run_dependent + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" @@ -334,7 +476,7 @@ - .cmake_test_linux_release - .linux_x86_64_tags_cuda_arch_52 - .cmake_junit_artifacts - - .run_dependent + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" @@ -344,7 +486,7 @@ - .cuda10.2_clang - .cmake_test_linux_release - .linux_x86_64_tags_cuda_arch_52 - - .run_dependent + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" @@ -355,7 +497,7 @@ - .cmake_test_linux_release - .linux_x86_64_tags_cuda_arch_52 - .cmake_junit_artifacts - - .run_dependent + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" @@ -365,7 +507,7 @@ - .cuda11.6_clang - .cmake_test_linux_release - .linux_x86_64_tags_cuda_arch_52 - - .run_dependent + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" @@ -375,7 +517,7 @@ - .cuda11.8_minimal_nvidia - .cmake_test_linux_release - .linux_x86_64_tags_cuda_arch_52 - - .run_dependent + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" @@ -385,7 +527,7 @@ - .cuda11.8_splayed_nvidia - .cmake_test_linux_release - .linux_x86_64_tags_cuda_arch_52 - - .run_dependent + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" @@ -396,7 +538,7 @@ - .cmake_test_linux_release - .linux_x86_64_tags_cuda_arch_52 - .cmake_junit_artifacts - - .run_dependent + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" @@ -406,7 +548,7 @@ - .cuda12.2_clang - .cmake_test_linux_release - .linux_x86_64_tags_cuda_arch_52 - - .run_dependent + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" @@ -417,8 +559,10 @@ - .cmake_test_linux_release - .linux_x86_64_tags_cuda_arch_52 - .cmake_junit_artifacts - - .run_dependent + - .rules - .needs_centos7_x86_64 + variables: + CMAKE_CI_JOB_NIGHTLY: "true" t:cuda12.6-nvidia-clang: extends: @@ -426,7 +570,7 @@ - .cmake_test_linux_release - .linux_x86_64_tags_cuda_arch_52 - .cmake_junit_artifacts - - .run_dependent + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" @@ -436,7 +580,39 @@ - .cuda12.6_clang - .cmake_test_linux_release - .linux_x86_64_tags_cuda_arch_52 - - .run_dependent + - .rules + - .needs_centos7_x86_64 + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + +t:cuda13.0-nvidia: + extends: + - .cuda13.0_nvidia + - .cmake_test_linux_release + - .linux_x86_64_tags_cuda_arch_75 + - .cmake_junit_artifacts + - .rules + - .needs_centos7_x86_64 + +t:cuda13.0-aarch64-nvidia: + extends: + - .cuda13.0_aarch64_nvidia + - .cmake_test_linux_release + - .linux_aarch64_tags_cuda_arch_75 + - .cmake_junit_artifacts + - .rules + - .needs_centos8_aarch64 + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + CMAKE_CI_JOB_NO_MR: "true" + +t:cuda13.0-nvidia-fastbuild: + extends: + - .cuda13.0_nvidia_fastbuild + - .cmake_test_linux_release + - .linux_x86_64_tags_cuda_arch_75 + - .cmake_junit_artifacts + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" @@ -446,7 +622,7 @@ - .hip6.3_nvidia - .cmake_test_linux_release - .linux_x86_64_tags_cuda_arch_52 - - .run_dependent + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" @@ -456,7 +632,17 @@ - .hip6.3_radeon - .cmake_test_linux_release - .linux_x86_64_tags_rocm6.3 - - .run_dependent + - .rules + - .needs_centos7_x86_64 + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + +t:linux-gcc-cxx-modules-reloc-ninja: + extends: + - .gcc_cxx_modules_reloc_ninja + - .cmake_test_linux_release + - .linux_x86_64_tags + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" @@ -466,7 +652,7 @@ - .gcc_cxx_modules_ninja - .cmake_test_linux_release - .linux_x86_64_tags - - .run_dependent + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" @@ -476,7 +662,7 @@ - .gcc_cxx_modules_ninja_multi - .cmake_test_linux_release - .linux_x86_64_tags - - .run_dependent + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" @@ -487,101 +673,97 @@ - .cmake_test_linux_release - .linux_x86_64_tags - .cmake_junit_artifacts - - .run_dependent + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" -b:fedora42-ninja: +b:fedora43-ninja: extends: - - .fedora42_ninja + - .fedora43_ninja - .cmake_build_linux - .cmake_build_artifacts - .linux_x86_64_tags - - .run_manually + - .rules variables: CMAKE_CI_JOB_CONTINUOUS: "true" + CMAKE_CI_JOB_RUN_MANUALLY: "true" -b:fedora42-makefiles-symlinked: +b:fedora43-makefiles-symlinked: extends: - - .fedora42_makefiles_symlinked + - .fedora43_makefiles_symlinked - .cmake_build_linux - .cmake_build_artifacts - .linux_x86_64_tags - - .run_manually + - .rules variables: CMAKE_CI_JOB_NIGHTLY: "true" + CMAKE_CI_JOB_RUN_MANUALLY: "true" -b:debian12-makefiles-inplace: +b:debian13-makefiles-inplace: extends: - - .debian12_makefiles_inplace + - .debian13_makefiles_inplace - .cmake_build_linux_standalone - .linux_x86_64_tags - - .run_manually + - .rules variables: CMAKE_CI_JOB_NIGHTLY: "true" + CMAKE_CI_JOB_RUN_MANUALLY: "true" -b:debian12-extdeps: +b:debian13-extdeps: extends: - - .debian12_extdeps + - .debian13_extdeps - .cmake_build_linux_standalone - .linux_x86_64_tags - - .run_manually + - .rules variables: CMAKE_CI_JOB_NIGHTLY: "true" + CMAKE_CI_JOB_RUN_MANUALLY: "true" -b:debian12-aarch64-extdeps: +b:debian13-aarch64-extdeps: extends: - - .debian12_aarch64_extdeps + - .debian13_aarch64_extdeps - .cmake_build_linux_standalone - .linux_aarch64_tags - - .run_manually + - .rules variables: CMAKE_CI_JOB_NIGHTLY: "true" + CMAKE_CI_JOB_RUN_MANUALLY: "true" -b:fedora42-extdeps: +b:fedora43-extdeps: extends: - - .fedora42_extdeps + - .fedora43_extdeps - .cmake_build_linux_standalone - .linux_x86_64_tags - - .run_manually + - .rules variables: CMAKE_CI_JOB_NIGHTLY: "true" + CMAKE_CI_JOB_RUN_MANUALLY: "true" -t:fedora42-ninja: +t:fedora43-ninja: extends: - - .fedora42_ninja + - .fedora43_ninja - .cmake_test_linux - .linux_x86_64_tags_x11 - .cmake_test_artifacts - - .run_dependent + - .rules needs: - - b:fedora42-ninja + - b:fedora43-ninja variables: CMAKE_CI_JOB_CONTINUOUS: "true" -t:fedora42-makefiles-symlinked: +t:fedora43-makefiles-symlinked: extends: - - .fedora42_makefiles_symlinked + - .fedora43_makefiles_symlinked - .cmake_test_linux - .linux_x86_64_tags_x11 - .cmake_test_artifacts - - .run_dependent + - .rules needs: - - b:fedora42-makefiles-symlinked + - b:fedora43-makefiles-symlinked variables: CMAKE_CI_JOB_NIGHTLY: "true" -t:fedora42-ninja-multi: - extends: - - .fedora42_ninja_multi - - .cmake_test_linux_external - - .linux_x86_64_tags - - .cmake_junit_artifacts - - .run_dependent - needs: - - t:fedora42-ninja - t:intel2016u2-makefiles: extends: - .cmake_test_linux_intelclassic_makefiles @@ -806,6 +988,20 @@ CMAKE_CI_BUILD_NAME: oneapi2025.1.0_makefiles CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2025.1.0-rocky9 +t:oneapi2025.2.0-makefiles: + extends: + - .cmake_test_linux_inteloneapi_makefiles + variables: + CMAKE_CI_BUILD_NAME: oneapi2025.2.0_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2025.2.0-rocky9 + +t:oneapi2025.3.0-makefiles: + extends: + - .cmake_test_linux_inteloneapi_makefiles + variables: + CMAKE_CI_BUILD_NAME: oneapi2025.3.0_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2025.3.0-rocky9 + b:linux-x86_64-package: extends: - .linux_package @@ -813,16 +1009,20 @@ - .cmake_build_linux_release - .cmake_release_artifacts - .linux_x86_64_tags - - .run_only_for_package + - .rules needs: - p:doc-package variables: CMAKE_CI_ARTIFACTS_NAME: "artifacts-linux-x86_64" + CMAKE_CI_JOB_PACKAGE_ONLY: "true" u:linux-x86_64-package: extends: - .rsync_upload_package - - .run_only_for_package + - .rules + variables: + CMAKE_CI_JOB_PACKAGE_ONLY: "true" + CMAKE_CI_JOB_NO_MR: "true" needs: - b:linux-x86_64-package @@ -833,16 +1033,20 @@ - .cmake_build_linux_release - .cmake_release_artifacts - .linux_aarch64_tags - - .run_only_for_package + - .rules needs: - p:doc-package variables: CMAKE_CI_ARTIFACTS_NAME: "artifacts-linux-aarch64" + CMAKE_CI_JOB_PACKAGE_ONLY: "true" u:linux-aarch64-package: extends: - .rsync_upload_package - - .run_only_for_package + - .rules + variables: + CMAKE_CI_JOB_PACKAGE_ONLY: "true" + CMAKE_CI_JOB_NO_MR: "true" needs: - b:linux-aarch64-package @@ -853,16 +1057,20 @@ - .cmake_build_sunos_release - .cmake_release_artifacts - .linux_x86_64_tags - - .run_only_for_package + - .rules needs: - p:doc-package variables: CMAKE_CI_ARTIFACTS_NAME: "artifacts-sunos-x86_64" + CMAKE_CI_JOB_PACKAGE_ONLY: "true" u:sunos-x86_64-package: extends: - .rsync_upload_package - - .run_only_for_package + - .rules + variables: + CMAKE_CI_JOB_PACKAGE_ONLY: "true" + CMAKE_CI_JOB_NO_MR: "true" needs: - b:sunos-x86_64-package @@ -873,41 +1081,60 @@ - .cmake_build_sunos_release - .cmake_release_artifacts - .linux_x86_64_tags - - .run_only_for_package + - .rules needs: - p:doc-package variables: CMAKE_CI_ARTIFACTS_NAME: "artifacts-sunos-sparc64" + CMAKE_CI_JOB_PACKAGE_ONLY: "true" u:sunos-sparc64-package: extends: - .rsync_upload_package - - .run_only_for_package + - .rules + variables: + CMAKE_CI_JOB_PACKAGE_ONLY: "true" + CMAKE_CI_JOB_NO_MR: "true" needs: - b:sunos-sparc64-package ## Sanitizer builds -b:fedora42-asan: +b:fedora43-asan: extends: - - .fedora42_asan + - .fedora43_asan - .cmake_build_linux - .cmake_build_artifacts - .linux_x86_64_tags - - .run_manually + - .rules + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + CMAKE_CI_JOB_RUN_MANUALLY: "true" + +t:fedora43-asan: + extends: + - .fedora43_asan + - .cmake_memcheck_linux + - .linux_x86_64_tags + - .cmake_junit_artifacts + - .rules + needs: + - b:fedora43-asan variables: CMAKE_CI_JOB_NIGHTLY: "true" -t:fedora42-asan: +t:fedora43-ninja-valgrind: extends: - - .fedora42_asan - - .cmake_memcheck_linux - - .linux_x86_64_tags - - .run_dependent - needs: - - b:fedora42-asan + - .fedora43_ninja_valgrind + - .cmake_test_linux_release + # Use a fast CPU so that timeouts are less of a concern. + - .linux_x86_64_tags_fast_x11 + - .cmake_valgrind_artifacts + - .rules + - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" + timeout: 2 hours # macOS builds @@ -917,9 +1144,10 @@ - .cmake_build_macos - .cmake_build_artifacts - .macos_x86_64_tags - - .run_manually + - .rules variables: - CMAKE_CI_NO_MR: "true" + CMAKE_CI_JOB_NO_MR: "true" + CMAKE_CI_JOB_RUN_MANUALLY: "true" b:macos-arm64-ninja: extends: @@ -927,9 +1155,10 @@ - .cmake_build_macos - .cmake_build_artifacts - .macos_arm64_tags - - .run_manually + - .rules variables: CMAKE_CI_JOB_CONTINUOUS: "true" + CMAKE_CI_JOB_RUN_MANUALLY: "true" b:macos-arm64-ninja-symlinked: extends: @@ -937,28 +1166,20 @@ - .cmake_build_macos - .cmake_build_artifacts - .macos_arm64_tags - - .run_manually + - .rules variables: CMAKE_CI_JOB_NIGHTLY: "true" - -b:macos-arm64-curl: - extends: - - .macos_arm64_curl - - .cmake_build_macos - - .cmake_build_artifacts - - .macos_arm64_tags - - .run_manually - variables: - CMAKE_CI_JOB_NIGHTLY: "true" + CMAKE_CI_JOB_RUN_MANUALLY: "true" b:macos-arm64-pch: extends: - .macos_arm64_pch - .cmake_build_macos - .macos_arm64_tags - - .run_manually + - .rules variables: CMAKE_CI_JOB_NIGHTLY: "true" + CMAKE_CI_JOB_RUN_MANUALLY: "true" t:macos-x86_64-ninja: extends: @@ -966,11 +1187,11 @@ - .cmake_test_macos - .cmake_test_artifacts - .macos_x86_64_tags - - .run_dependent + - .rules needs: - b:macos-x86_64-ninja variables: - CMAKE_CI_NO_MR: "true" + CMAKE_CI_JOB_NO_MR: "true" t:macos-arm64-ninja: extends: @@ -978,7 +1199,7 @@ - .cmake_test_macos - .cmake_test_artifacts - .macos_arm64_tags - - .run_dependent + - .rules needs: - b:macos-arm64-ninja variables: @@ -991,38 +1212,29 @@ - .cmake_test_macos - .cmake_test_artifacts - .macos_arm64_tags - - .run_dependent + - .rules needs: - b:macos-arm64-ninja-symlinked variables: CMAKE_CI_JOB_NIGHTLY: "true" CMAKE_CI_JOB_NIGHTLY_NINJA: "true" -t:macos-arm64-curl: - extends: - - .macos_arm64_curl - - .cmake_test_macos - - .macos_arm64_tags - - .run_dependent - needs: - - b:macos-arm64-curl - variables: - CMAKE_CI_JOB_NIGHTLY: "true" - b:macos-x86_64-makefiles: extends: - .macos_x86_64_makefiles - .cmake_build_macos - .cmake_build_artifacts - .macos_x86_64_tags - - .run_manually + - .rules + variables: + CMAKE_CI_JOB_RUN_MANUALLY: "true" t:macos-x86_64-makefiles: extends: - .macos_x86_64_makefiles - .cmake_test_macos - .macos_x86_64_tags - - .run_dependent + - .rules needs: - b:macos-x86_64-makefiles @@ -1032,7 +1244,7 @@ - .cmake_test_macos_external - .macos_arm64_tags_ext - .cmake_junit_artifacts - - .run_dependent + - .rules needs: - t:macos-arm64-ninja variables: @@ -1044,11 +1256,11 @@ - .cmake_test_macos_external - .macos_x86_64_tags_ext - .cmake_junit_artifacts - - .run_dependent + - .rules needs: - t:macos-x86_64-ninja variables: - CMAKE_CI_NO_MR: "true" + CMAKE_CI_JOB_NO_MR: "true" t:macos-arm64-xcode: extends: @@ -1056,17 +1268,29 @@ - .cmake_test_macos_external - .macos_arm64_tags_ext - .cmake_junit_artifacts - - .run_dependent + - .rules needs: - t:macos-arm64-ninja +t:macos-arm64-fastbuild: + extends: + - .macos_arm64_fastbuild + - .cmake_test_macos_external + - .macos_arm64_tags_ext + - .cmake_junit_artifacts + - .rules + needs: + - t:macos-arm64-ninja + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + t:macos-arm64-xcode-symlinked: extends: - .macos_arm64_xcode_symlinked - .cmake_test_macos_external - .macos_arm64_tags_ext - .cmake_junit_artifacts - - .run_dependent + - .rules needs: - t:macos-arm64-ninja variables: @@ -1078,11 +1302,11 @@ - .cmake_test_macos_external - .macos_x86_64_tags_ext - .cmake_junit_artifacts - - .run_dependent + - .rules needs: - t:macos-x86_64-ninja variables: - CMAKE_CI_JOB_NIGHTLY: "true" + CMAKE_CI_JOB_NO_MR: "true" t:macos-arm64-xcode-ub: extends: @@ -1090,7 +1314,7 @@ - .cmake_test_macos_external - .macos_arm64_tags_ext - .cmake_junit_artifacts - - .run_dependent + - .rules needs: - t:macos-arm64-ninja variables: @@ -1102,18 +1326,34 @@ - .cmake_build_macos - .cmake_release_artifacts - .macos_arm64_tags_package - - .run_only_for_package + - .rules needs: - p:doc-package variables: + CMAKE_CI_JOB_PACKAGE_ONLY: "true" + +k:macos-package: + extends: + - .macos_sign + - .cmake_sign_macos + - .cmake_release_artifacts + - .macos_sign_tags + - .rules + needs: + - b:macos-package + variables: CMAKE_CI_ARTIFACTS_NAME: "artifacts-macos-universal" + CMAKE_CI_JOB_PACKAGE_ONLY: "true" u:macos-package: extends: - .rsync_upload_package - - .run_only_for_package + - .rules + variables: + CMAKE_CI_JOB_PACKAGE_ONLY: "true" + CMAKE_CI_JOB_NO_MR: "true" needs: - - b:macos-package + - k:macos-package b:macos10.10-package: extends: @@ -1121,95 +1361,125 @@ - .cmake_build_macos - .cmake_release_artifacts - .macos_arm64_tags_package - - .run_only_for_package + - .rules needs: - p:doc-package variables: + CMAKE_CI_JOB_PACKAGE_ONLY: "true" + +k:macos10.10-package: + extends: + - .macos_sign + - .cmake_sign_macos + - .cmake_release_artifacts + - .macos_sign_tags + - .rules + needs: + - b:macos10.10-package + variables: CMAKE_CI_ARTIFACTS_NAME: "artifacts-macos10.10-universal" + CMAKE_CI_JOB_PACKAGE_ONLY: "true" u:macos10.10-package: extends: - .rsync_upload_package - - .run_only_for_package + - .rules + variables: + CMAKE_CI_JOB_PACKAGE_ONLY: "true" + CMAKE_CI_JOB_NO_MR: "true" needs: - - b:macos10.10-package + - k:macos10.10-package # Windows x86_64 jobs -b:windows-vs2022-x64-ninja: +b:windows-vs2026-x64-ninja: extends: - - .windows_vs2022_x64_ninja + - .windows_vs2026_x64_ninja - .cmake_build_windows - .cmake_build_artifacts - - .windows_x86_64_tags_nonconcurrent_vs2022 - - .run_manually + - .windows_x86_64_tags_nonconcurrent_vs2026 + - .rules variables: CMAKE_CI_JOB_CONTINUOUS: "true" + CMAKE_CI_JOB_RUN_MANUALLY: "true" -b:windows-vs2022-x64-pch: +b:windows-vs2026-x64-pch: extends: - - .windows_vs2022_x64_pch + - .windows_vs2026_x64_pch - .cmake_build_windows - - .windows_x86_64_tags_nonconcurrent_vs2022 - - .run_manually + - .windows_x86_64_tags_nonconcurrent_vs2026 + - .rules variables: CMAKE_CI_JOB_NIGHTLY: "true" + CMAKE_CI_JOB_RUN_MANUALLY: "true" -t:windows-vs2022-x64-ninja: +t:windows-vs2026-x64-ninja: extends: - - .windows_vs2022_x64_ninja + - .windows_vs2026_x64_ninja - .cmake_test_windows - - .windows_x86_64_tags_nonconcurrent_vs2022 + - .windows_x86_64_tags_nonconcurrent_vs2026 - .cmake_test_artifacts - - .run_dependent + - .rules needs: - - b:windows-vs2022-x64-ninja + - b:windows-vs2026-x64-ninja variables: CMAKE_CI_JOB_CONTINUOUS: "true" CMAKE_CI_JOB_NIGHTLY_NINJA: "true" -t:windows-vs2022-x64-ninja-multi: +t:windows-vs2026-x64-ninja-multi: extends: - - .windows_vs2022_x64_ninja_multi + - .windows_vs2026_x64_ninja_multi - .cmake_test_windows_external - - .windows_x86_64_tags_concurrent_vs2022 + - .windows_x86_64_tags_concurrent_vs2026 - .cmake_junit_artifacts - - .run_dependent + - .rules needs: - - t:windows-vs2022-x64-ninja + - t:windows-vs2026-x64-ninja variables: CMAKE_CI_JOB_NIGHTLY: "true" -.t:windows-vs2022-x64: +.t:windows-vs2026-x64: extends: - - .windows_vs2022_x64 + - .windows_vs2026_x64 - .cmake_test_windows_external - .cmake_junit_artifacts - - .run_dependent + - .rules needs: - - t:windows-vs2022-x64-ninja + - t:windows-vs2026-x64-ninja -t:windows-vs2022-x64: +t:windows-vs2026-x64: extends: - - .t:windows-vs2022-x64 - - .windows_x86_64_tags_concurrent_vs2022 + - .t:windows-vs2026-x64 + - .windows_x86_64_tags_concurrent_vs2026 variables: CMAKE_CI_JOB_NIGHTLY: "false" -t:windows-vs2022-x64-nightly: +t:windows-vs2026-x64-nightly: extends: - - .t:windows-vs2022-x64 - - .windows_x86_64_tags_concurrent_vs2022_android + - .t:windows-vs2026-x64 + - .windows_x86_64_tags_concurrent_vs2026_android variables: CMAKE_CI_JOB_NIGHTLY: "true" -t:windows-vs2022-x64-i18n: +t:windows-vs2026-x64-i18n: extends: - - .t:windows-vs2022-x64 - - .windows_x86_64_tags_concurrent_vs2022_android + - .t:windows-vs2026-x64 + - .windows_x86_64_tags_concurrent_vs2026_android variables: GIT_CLONE_PATH: "$CI_BUILDS_DIR\\cmake i18n cï\\$CI_CONCURRENT_ID" - CMAKE_CONFIGURATION: windows_vs2022_x64_i18n + CMAKE_CONFIGURATION: windows_vs2026_x64_i18n + CMAKE_CI_JOB_NIGHTLY: "true" + +t:windows-vs2022-x64: + extends: + - .windows_vs2022_x64 + - .cmake_test_windows_external + - .windows_x86_64_tags_concurrent_vs2022_android + - .cmake_junit_artifacts + - .rules + needs: + - t:windows-vs2026-x64-ninja + variables: CMAKE_CI_JOB_NIGHTLY: "true" t:windows-vs2019-x64: @@ -1218,33 +1488,45 @@ - .cmake_test_windows_external - .windows_x86_64_tags_concurrent_vs2019_android - .cmake_junit_artifacts - - .run_dependent + - .rules needs: - - t:windows-vs2022-x64-ninja + - t:windows-vs2026-x64-ninja variables: CMAKE_CI_JOB_NIGHTLY: "true" -t:windows-vs2022-x64-nmake: +t:windows-vs2026-x64-nmake: extends: - - .windows_vs2022_x64_nmake + - .windows_vs2026_x64_nmake - .cmake_test_windows_external - - .windows_x86_64_tags_concurrent_vs2022 + - .windows_x86_64_tags_concurrent_vs2026 - .cmake_junit_artifacts - - .run_dependent + - .rules needs: - - t:windows-vs2022-x64-ninja + - t:windows-vs2026-x64-ninja variables: CMAKE_CI_JOB_NIGHTLY: "true" -t:windows-vs2022-x64-jom: +t:windows-vs2026-x64-jom: extends: - - .windows_vs2022_x64_jom + - .windows_vs2026_x64_jom - .cmake_test_windows_external - - .windows_x86_64_tags_concurrent_vs2022 + - .windows_x86_64_tags_concurrent_vs2026 - .cmake_junit_artifacts - - .run_dependent + - .rules needs: - - t:windows-vs2022-x64-ninja + - t:windows-vs2026-x64-ninja + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + +t:windows-vs2026-x64-fastbuild: + extends: + - .windows_vs2026_x64_fastbuild + - .cmake_test_windows_external + - .windows_x86_64_tags_concurrent_vs2026 + - .cmake_junit_artifacts + - .rules + needs: + - t:windows-vs2026-x64-ninja variables: CMAKE_CI_JOB_NIGHTLY: "true" @@ -1254,9 +1536,9 @@ - .cmake_test_windows_external - .windows_x86_64_tags_concurrent - .cmake_junit_artifacts - - .run_dependent + - .rules needs: - - t:windows-vs2022-x64-ninja + - t:windows-vs2026-x64-ninja variables: CMAKE_CI_JOB_NIGHTLY: "true" @@ -1266,62 +1548,62 @@ - .cmake_test_windows_external - .windows_x86_64_tags_concurrent - .cmake_junit_artifacts - - .run_dependent + - .rules needs: - - t:windows-vs2022-x64-ninja + - t:windows-vs2026-x64-ninja variables: CMAKE_CI_JOB_NIGHTLY: "true" -t:windows-clang19.1-cl-ninja: +t:windows-clang21.1-cl-ninja: extends: - .windows_clang_ninja - .cmake_test_windows_external - - .windows_x86_64_tags_concurrent + - .windows_x86_64_tags_concurrent_vs2022_msvc14.44 - .cmake_junit_artifacts - - .run_dependent + - .rules needs: - - t:windows-vs2022-x64-ninja + - t:windows-vs2026-x64-ninja variables: - CMAKE_CI_BUILD_NAME: windows_clang19.1_cl_ninja + CMAKE_CI_BUILD_NAME: windows_clang21.1_cl_ninja CMAKE_CI_JOB_NIGHTLY: "true" -t:windows-clang19.1-cl-nmake: +t:windows-clang21.1-cl-nmake: extends: - .windows_clang_nmake - .cmake_test_windows_external - - .windows_x86_64_tags_concurrent + - .windows_x86_64_tags_concurrent_vs2022_msvc14.44 - .cmake_junit_artifacts - - .run_dependent + - .rules needs: - - t:windows-vs2022-x64-ninja + - t:windows-vs2026-x64-ninja variables: - CMAKE_CI_BUILD_NAME: windows_clang19.1_cl_nmake + CMAKE_CI_BUILD_NAME: windows_clang21.1_cl_nmake CMAKE_CI_JOB_NIGHTLY: "true" -t:windows-clang19.1-gnu-ninja: +t:windows-clang21.1-gnu-ninja: extends: - .windows_clang_ninja - .cmake_test_windows_external - - .windows_x86_64_tags_concurrent + - .windows_x86_64_tags_concurrent_vs2022_msvc14.44 - .cmake_junit_artifacts - - .run_dependent + - .rules needs: - - t:windows-vs2022-x64-ninja + - t:windows-vs2026-x64-ninja variables: - CMAKE_CI_BUILD_NAME: windows_clang19.1_gnu_ninja + CMAKE_CI_BUILD_NAME: windows_clang21.1_gnu_ninja CMAKE_CI_JOB_NIGHTLY: "true" -t:windows-clang19.1-gnu-nmake: +t:windows-clang21.1-gnu-nmake: extends: - .windows_clang_nmake - .cmake_test_windows_external - - .windows_x86_64_tags_concurrent + - .windows_x86_64_tags_concurrent_vs2022_msvc14.44 - .cmake_junit_artifacts - - .run_dependent + - .rules needs: - - t:windows-vs2022-x64-ninja + - t:windows-vs2026-x64-ninja variables: - CMAKE_CI_BUILD_NAME: windows_clang19.1_gnu_nmake + CMAKE_CI_BUILD_NAME: windows_clang21.1_gnu_nmake CMAKE_CI_JOB_NIGHTLY: "true" t:windows-intel2021.9-ninja: @@ -1330,9 +1612,9 @@ - .cmake_test_windows_external - .windows_x86_64_tags_concurrent_vs2022_msvc14.43 - .cmake_junit_artifacts - - .run_dependent + - .rules needs: - - t:windows-vs2022-x64-ninja + - t:windows-vs2026-x64-ninja variables: CMAKE_CI_BUILD_NAME: windows_intel2021.9_ninja CMAKE_CI_JOB_NIGHTLY: "true" @@ -1341,11 +1623,11 @@ extends: - .windows_inteloneapi_ninja - .cmake_test_windows_external - - .windows_x86_64_tags_concurrent_vs2022 + - .windows_x86_64_tags_concurrent_vs2022_msvc14.44 - .cmake_junit_artifacts - - .run_dependent + - .rules needs: - - t:windows-vs2022-x64-ninja + - t:windows-vs2026-x64-ninja variables: CMAKE_CI_BUILD_NAME: windows_oneapi2025.1_ninja CMAKE_CI_JOB_NIGHTLY: "true" @@ -1356,9 +1638,9 @@ - .cmake_test_windows_external - .windows_x86_64_tags_concurrent - .cmake_junit_artifacts - - .run_dependent + - .rules needs: - - t:windows-vs2022-x64-ninja + - t:windows-vs2026-x64-ninja variables: CMAKE_CI_JOB_NIGHTLY: "true" @@ -1368,9 +1650,9 @@ - .cmake_test_windows_external - .windows_x86_64_tags_concurrent - .cmake_junit_artifacts - - .run_dependent + - .rules needs: - - t:windows-vs2022-x64-ninja + - t:windows-vs2026-x64-ninja variables: CMAKE_CI_JOB_NIGHTLY: "true" @@ -1380,9 +1662,9 @@ - .cmake_test_windows_external - .windows_x86_64_tags_concurrent - .cmake_junit_artifacts - - .run_dependent + - .rules needs: - - t:windows-vs2022-x64-ninja + - t:windows-vs2026-x64-ninja variables: CMAKE_CI_JOB_NIGHTLY: "true" @@ -1392,9 +1674,9 @@ - .cmake_test_windows_external - .windows_x86_64_tags_concurrent - .cmake_junit_artifacts - - .run_dependent + - .rules needs: - - t:windows-vs2022-x64-ninja + - t:windows-vs2026-x64-ninja variables: CMAKE_CI_JOB_NIGHTLY: "true" @@ -1404,33 +1686,46 @@ - .cmake_test_windows_external - .windows_x86_64_tags_concurrent - .cmake_junit_artifacts - - .run_dependent + - .rules needs: - - t:windows-vs2022-x64-ninja + - t:windows-vs2026-x64-ninja variables: CMAKE_CI_JOB_NIGHTLY: "true" # Windows arm64 jobs -b:windows-arm64-vs2022-ninja: +b:windows-arm64-vs2026-ninja: extends: - - .windows_arm64_vs2022_ninja + - .windows_arm64_vs2026_ninja - .cmake_build_windows - .cmake_build_artifacts - - .windows_arm64_tags_nonconcurrent_vs2022 - - .run_manually + - .windows_arm64_tags_nonconcurrent_vs2026 + - .rules + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + CMAKE_CI_JOB_RUN_MANUALLY: "true" + +t:windows-arm64-vs2026-ninja: + extends: + - .windows_arm64_vs2026_ninja + - .cmake_test_windows + - .windows_arm64_tags_nonconcurrent_vs2026 + - .cmake_test_artifacts + - .rules + needs: + - b:windows-arm64-vs2026-ninja variables: CMAKE_CI_JOB_NIGHTLY: "true" -t:windows-arm64-vs2022-ninja: +t:windows-arm64-vs2026: extends: - - .windows_arm64_vs2022_ninja - - .cmake_test_windows - - .windows_arm64_tags_nonconcurrent_vs2022 - - .cmake_test_artifacts - - .run_dependent + - .windows_arm64_vs2026 + - .cmake_test_windows_external + - .windows_arm64_tags_concurrent_vs2026 + - .cmake_junit_artifacts + - .rules needs: - - b:windows-arm64-vs2022-ninja + - t:windows-arm64-vs2026-ninja variables: CMAKE_CI_JOB_NIGHTLY: "true" @@ -1440,9 +1735,9 @@ - .cmake_test_windows_external - .windows_arm64_tags_concurrent_vs2022 - .cmake_junit_artifacts - - .run_dependent + - .rules needs: - - t:windows-arm64-vs2022-ninja + - t:windows-arm64-vs2026-ninja variables: CMAKE_CI_JOB_NIGHTLY: "true" @@ -1453,12 +1748,13 @@ - .windows_x86_64_package - .cmake_build_windows - .cmake_build_package_artifacts - - .windows_x86_64_tags_nonconcurrent_vs2022 - - .run_only_for_package + - .windows_x86_64_tags_nonconcurrent_vs2026 + - .rules needs: - p:doc-package variables: CMAKE_CI_ARTIFACTS_NAME: "artifacts-windows-x86_64-build" + CMAKE_CI_JOB_PACKAGE_ONLY: "true" k:windows-x86_64-package: extends: @@ -1466,16 +1762,20 @@ - .cmake_package_windows - .cmake_release_artifacts - .windows_x86_64_tags_nonconcurrent_sign - - .run_only_for_package + - .rules needs: - b:windows-x86_64-package variables: CMAKE_CI_ARTIFACTS_NAME: "artifacts-windows-x86_64" + CMAKE_CI_JOB_PACKAGE_ONLY: "true" u:windows-x86_64-package: extends: - .rsync_upload_package - - .run_only_for_package + - .rules + variables: + CMAKE_CI_JOB_PACKAGE_ONLY: "true" + CMAKE_CI_JOB_NO_MR: "true" needs: - k:windows-x86_64-package @@ -1484,12 +1784,13 @@ - .windows_i386_package - .cmake_build_windows - .cmake_build_package_artifacts - - .windows_x86_64_tags_nonconcurrent_vs2022 - - .run_only_for_package + - .windows_x86_64_tags_nonconcurrent_vs2026 + - .rules needs: - p:doc-package variables: CMAKE_CI_ARTIFACTS_NAME: "artifacts-windows-i386-build" + CMAKE_CI_JOB_PACKAGE_ONLY: "true" k:windows-i386-package: extends: @@ -1497,16 +1798,20 @@ - .cmake_package_windows - .cmake_release_artifacts - .windows_x86_64_tags_nonconcurrent_sign - - .run_only_for_package + - .rules needs: - b:windows-i386-package variables: CMAKE_CI_ARTIFACTS_NAME: "artifacts-windows-i386" + CMAKE_CI_JOB_PACKAGE_ONLY: "true" u:windows-i386-package: extends: - .rsync_upload_package - - .run_only_for_package + - .rules + variables: + CMAKE_CI_JOB_PACKAGE_ONLY: "true" + CMAKE_CI_JOB_NO_MR: "true" needs: - k:windows-i386-package @@ -1515,12 +1820,13 @@ - .windows_arm64_package - .cmake_build_windows - .cmake_build_package_artifacts - - .windows_x86_64_tags_nonconcurrent_vs2022_arm64 - - .run_only_for_package + - .windows_x86_64_tags_nonconcurrent_vs2026_arm64 + - .rules needs: - p:doc-package variables: CMAKE_CI_ARTIFACTS_NAME: "artifacts-windows-arm64-build" + CMAKE_CI_JOB_PACKAGE_ONLY: "true" k:windows-arm64-package: extends: @@ -1528,15 +1834,19 @@ - .cmake_package_windows - .cmake_release_artifacts - .windows_x86_64_tags_nonconcurrent_sign - - .run_only_for_package + - .rules needs: - b:windows-arm64-package variables: CMAKE_CI_ARTIFACTS_NAME: "artifacts-windows-arm64" + CMAKE_CI_JOB_PACKAGE_ONLY: "true" u:windows-arm64-package: extends: - .rsync_upload_package - - .run_only_for_package + - .rules + variables: + CMAKE_CI_JOB_PACKAGE_ONLY: "true" + CMAKE_CI_JOB_NO_MR: "true" needs: - k:windows-arm64-package
diff --git a/.gitlab/.gitignore b/.gitlab/.gitignore index f66ad97..91e677b 100644 --- a/.gitlab/.gitignore +++ b/.gitlab/.gitignore
@@ -1,14 +1,17 @@ # Ignore files known to be downloaded by CI jobs. -/5.15.1-0-202009071110* +/6.9.3-0-202509261208* +/6.9.3-0-202509261207* +/appimagetool /bcc* /cmake* +/emsdk +/fastbuild /iar /intel /ispc* /innosetup /jom /llvm* -/MacOS* /mingw /msvc* /ninja*
diff --git a/.gitlab/artifacts.yml b/.gitlab/artifacts.yml index f11706c..af7fbac 100644 --- a/.gitlab/artifacts.yml +++ b/.gitlab/artifacts.yml
@@ -62,6 +62,13 @@ - ${CMAKE_CI_BUILD_DIR}/DartConfiguration.tcl - ${CMAKE_CI_BUILD_DIR}/CTestCustom.cmake - ${CMAKE_CI_BUILD_DIR}/cdash-build-id + + # CTest coverage files. + - ${CMAKE_CI_BUILD_DIR}/CMakeFiles/TargetDirectories.txt + - ${CMAKE_CI_BUILD_DIR}/Bullseye/ + - ${CMAKE_CI_BUILD_DIR}/**/*.gcno + - ${CMAKE_CI_BUILD_DIR}/Source/QtDialog/moc_*.cpp + - ${CMAKE_CI_BUILD_DIR}/Source/QtDialog/ui_*.h reports: annotations: - ${CMAKE_CI_BUILD_DIR}/annotations.json @@ -115,8 +122,6 @@ # Any source packages made. - ${CMAKE_CI_BUILD_DIR}/cmake-*.tar.gz - ${CMAKE_CI_BUILD_DIR}/cmake-*.zip - # Any unsigned packages made. - - ${CMAKE_CI_BUILD_DIR}/unsigned/cmake-* reports: annotations: - ${CMAKE_CI_BUILD_DIR}/annotations.json @@ -139,6 +144,19 @@ junit: - ${CMAKE_CI_BUILD_DIR}/junit.xml +.cmake_valgrind_artifacts: + artifacts: + expire_in: 1d + when: always + reports: + annotations: + - ${CMAKE_CI_BUILD_DIR}/annotations.json + junit: + - ${CMAKE_CI_BUILD_DIR}/junit.xml + paths: + # Valgrind logs. + - ${CMAKE_CI_BUILD_DIR}/Testing/Temporary/MemoryChecker.*.log + .cmake_sphinx_artifacts: artifacts: expire_in: 1d @@ -167,6 +185,33 @@ # Take the install tree. - ${CMAKE_CI_BUILD_DIR}/install/ +.cmake_coverage_artifacts: + artifacts: + expire_in: 1d + # External testing can be useful even if test jobs fail. + when: always + reports: + junit: + - ${CMAKE_CI_BUILD_DIR}/junit.xml + annotations: + - ${CMAKE_CI_BUILD_DIR}/annotations.json + paths: + # Generated sources. + - ${CMAKE_CI_BUILD_DIR}/Source/QtDialog/moc_*.cpp + - ${CMAKE_CI_BUILD_DIR}/Source/QtDialog/ui_*.h + + # CTest coverage files. + - ${CMAKE_CI_BUILD_DIR}/CMakeFiles/TargetDirectories.txt + - ${CMAKE_CI_BUILD_DIR}/Bullseye/ + - ${CMAKE_CI_BUILD_DIR}/**/*.gcno + - ${CMAKE_CI_BUILD_DIR}/**/*.gcda + + # CTest/CDash information. + - ${CMAKE_CI_BUILD_DIR}/Testing/ + - ${CMAKE_CI_BUILD_DIR}/DartConfiguration.tcl + - ${CMAKE_CI_BUILD_DIR}/CTestCustom.cmake + - ${CMAKE_CI_BUILD_DIR}/cdash-build-id + .cmake_doc_artifacts: artifacts: expire_in: 1d
diff --git a/.gitlab/ci/.gitattributes b/.gitlab/ci/.gitattributes new file mode 100644 index 0000000..b4f5f9d --- /dev/null +++ b/.gitlab/ci/.gitattributes
@@ -0,0 +1,2 @@ +# Do not apply a size limit to suppression files. +*.valgrind.supp -hooks-max-size
diff --git a/.gitlab/ci/appimagetool-env.sh b/.gitlab/ci/appimagetool-env.sh new file mode 100644 index 0000000..1dd4674 --- /dev/null +++ b/.gitlab/ci/appimagetool-env.sh
@@ -0,0 +1,3 @@ +.gitlab/ci/appimagetool.sh +export PATH=$PWD/.gitlab/appimagetool/bin:$PATH +appimagetool --version
diff --git a/.gitlab/ci/appimagetool.sh b/.gitlab/ci/appimagetool.sh new file mode 100755 index 0000000..6ab430f --- /dev/null +++ b/.gitlab/ci/appimagetool.sh
@@ -0,0 +1,32 @@ +#!/bin/sh + +set -e + +readonly version="1.9.0.20250814" + +case "$(uname -s)-$(uname -m)" in + Linux-x86_64) + shatool="sha256sum" + sha256sum="6414d395eafee09453d2e203d9cc65f867e6ff7e1a8a6c08e444d86cb1d106ad" + filename="appimagetool-$version-x86_64" + ;; + *) + echo "Unrecognized platform $(uname -s)-$(uname -m)" + exit 1 + ;; +esac +readonly shatool +readonly sha256sum + +cd .gitlab + +# This URL is only visible inside of Kitware's network. See above filename table. +baseurl="https://cmake.org/files/dependencies/internal" + +tarball="$filename.tar.gz" +echo "$sha256sum $tarball" > appimagetool.sha256sum +curl -OL "$baseurl/$tarball" +$shatool --check appimagetool.sha256sum +tar xzf "$tarball" +rm "$tarball" appimagetool.sha256sum +mv "$filename" "appimagetool"
diff --git a/.gitlab/ci/bullseye-env.sh b/.gitlab/ci/bullseye-env.sh new file mode 100644 index 0000000..d3aa9d7 --- /dev/null +++ b/.gitlab/ci/bullseye-env.sh
@@ -0,0 +1,14 @@ +# Install Bullseye +.gitlab/ci/bullseye.sh +unset CMAKE_CI_BULLSEYE_LICENSE + +# Make Bullseye tools available but do not override compilers. +export PATH="$PATH:/opt/bullseye/bin" + +# Print the Bullseye startup banner once. +covc --help 2>&1 | head -1 + +# Suppress the Bullseye startup banner. +for tool in cov01 covc; do + echo "--no-banner" > "/opt/bullseye/bin/$tool.cfg" +done
diff --git a/.gitlab/ci/bullseye.sh b/.gitlab/ci/bullseye.sh new file mode 100755 index 0000000..8c4cd2b --- /dev/null +++ b/.gitlab/ci/bullseye.sh
@@ -0,0 +1,36 @@ +#!/bin/sh + +set -e + +if ! test -f "$CMAKE_CI_BULLSEYE_LICENSE"; then + echo "No CMAKE_CI_BULLSEYE_LICENSE file provided!" + exit 1 +fi + +readonly version="9.22.3" + +case "$(uname -s)-$(uname -m)" in + Linux-x86_64) + tarball="BullseyeCoverage-$version-Linux-x64.tar.xz" + sha256sum="d5be7e65d9363161b67fa77a30407c7c200d995af79a422c4e2e278802ba0776" + shatool="sha256sum" + ;; + *) + echo "Unrecognized platform $(uname -s)-$(uname -m)" + exit 1 + ;; +esac +readonly shatool +readonly sha256sum + +# See https://www.bullseye.com/download-archive for original archives. +# This URL is only visible inside of Kitware's network. +baseurl="https://cmake.org/files/dependencies/internal/bullseye" + +dirname="BullseyeCoverage-$version" +echo "$sha256sum $tarball" > bullseye.sha256sum +curl -OL "$baseurl/$tarball" +$shatool --check bullseye.sha256sum +tar xJf "$tarball" +"$dirname/install" --key "$(<"$CMAKE_CI_BULLSEYE_LICENSE")" --prefix=/opt/bullseye +rm -r "$dirname" "$tarball" bullseye.sha256sum "$CMAKE_CI_BULLSEYE_LICENSE"
diff --git a/.gitlab/ci/clang.ps1 b/.gitlab/ci/clang.ps1 index 61361b1..327fe3b 100644 --- a/.gitlab/ci/clang.ps1 +++ b/.gitlab/ci/clang.ps1
@@ -1,10 +1,10 @@ $erroractionpreference = "stop" -if ("$env:CMAKE_CI_BUILD_NAME".Contains("clang19.1")) { - # LLVM/Clang 19.1.0 - # https://github.com/llvm/llvm-project/releases/tag/llvmorg-19.1.0 - $filename = "llvm-19.1.0-win-x86_64-1" - $sha256sum = "C1F974511A6FA2DC5B4892996C064A55BF81D7F244514F8AB5A453110ADEC0EC" +if ("$env:CMAKE_CI_BUILD_NAME".Contains("clang21.1")) { + # LLVM/Clang 21.1.8 + # https://github.com/llvm/llvm-project/releases/tag/llvmorg-21.1.8 + $filename = "llvm-21.1.8-win-x86_64-1" + $sha256sum = "3DB0063A6E434C694799CDD70052F27F08A758F1FF4B4C04D9910AD4198F6064" } else { throw ('unknown CMAKE_CI_BUILD_NAME: ' + "$env:CMAKE_CI_BUILD_NAME") }
diff --git a/.gitlab/ci/cmake.ps1 b/.gitlab/ci/cmake.ps1 index 1353150..94f6694 100644 --- a/.gitlab/ci/cmake.ps1 +++ b/.gitlab/ci/cmake.ps1
@@ -1,12 +1,12 @@ $erroractionpreference = "stop" -$version = "3.31.5" +$version = "4.2.0" if ("$env:PROCESSOR_ARCHITECTURE" -eq "AMD64") { - $sha256sum = "D4D2D4B9CCD68DAE975A066FCD42EA9807EF40F79EE6971923FD3788E7917585" + $sha256sum = "CF35A516C4F5F4646B301E51C8E24B168CC012C3B1453B8F675303B54EB0EF45" $platform = "windows-x86_64" } elseif ("$env:PROCESSOR_ARCHITECTURE" -eq "ARM64") { - $sha256sum = "A734E4E970FDAA4B5957157C059556F56CA5D655014CD4B5FD9194AABA316F31" + $sha256sum = "9EB3E88083DDA569A4086C48517F5D49BD7B505DADA79075EA7CB6E2AC6E0A1E" $platform = "windows-arm64" } else { throw ('unknown PROCESSOR_ARCHITECTURE: ' + "$env:PROCESSOR_ARCHITECTURE")
diff --git a/.gitlab/ci/cmake.sh b/.gitlab/ci/cmake.sh index 10aba43..a0e2a5a 100755 --- a/.gitlab/ci/cmake.sh +++ b/.gitlab/ci/cmake.sh
@@ -2,22 +2,22 @@ set -e -readonly version="3.31.5" +readonly version="4.2.0" case "$(uname -s)-$(uname -m)" in Linux-x86_64) shatool="sha256sum" - sha256sum="2984e70515ff60c5e4a41922b5d715a8168a696a89721e3b114e36f453244f72" + sha256sum="bbcebd4c433eab3af03a8c80bb5d84e8dfc3ff8a4ab9d01547b21240c23f7c2c" platform="linux-x86_64" ;; Linux-aarch64) shatool="sha256sum" - sha256sum="eb92af175ea91e3706ff62484088c3a3774ef3e1a8c399111785dd5f47010164" + sha256sum="86f52e9769cd7745e5227931e689e122dc1afc5648cc9b04db601b165f3ac993" platform="linux-aarch64" ;; Darwin-*) shatool="shasum -a 256" - sha256sum="cc8e3d9bef7eee70db52601a5ed60d221436a8def18388effdab0e7d0866f50d" + sha256sum="b8b040a06343b2b6bc090b03a9c2bb4e98037518846989fb7c40ebbf30655c5d" platform="macos-universal" ;; *)
diff --git a/.gitlab/ci/configure_cuda13.0_aarch64_nvidia.cmake b/.gitlab/ci/configure_cuda13.0_aarch64_nvidia.cmake new file mode 100644 index 0000000..71aafcf --- /dev/null +++ b/.gitlab/ci/configure_cuda13.0_aarch64_nvidia.cmake
@@ -0,0 +1 @@ +include("${CMAKE_CURRENT_LIST_DIR}/configure_cuda13.0_nvidia_common.cmake")
diff --git a/.gitlab/ci/configure_cuda13.0_nvidia.cmake b/.gitlab/ci/configure_cuda13.0_nvidia.cmake new file mode 100644 index 0000000..71aafcf --- /dev/null +++ b/.gitlab/ci/configure_cuda13.0_nvidia.cmake
@@ -0,0 +1 @@ +include("${CMAKE_CURRENT_LIST_DIR}/configure_cuda13.0_nvidia_common.cmake")
diff --git a/.gitlab/ci/configure_cuda13.0_nvidia_common.cmake b/.gitlab/ci/configure_cuda13.0_nvidia_common.cmake new file mode 100644 index 0000000..6a66194 --- /dev/null +++ b/.gitlab/ci/configure_cuda13.0_nvidia_common.cmake
@@ -0,0 +1,8 @@ +set(CMake_TEST_CUDA "NVIDIA" CACHE STRING "") +set(CMake_TEST_CUDA_ARCH "75" CACHE STRING "") +set(CMake_TEST_CUDA_CUPTI "ON" CACHE STRING "") +set(CMake_TEST_CUDA_STANDARDS "03;11;14;17;20" CACHE STRING "") +set(CMake_TEST_FindOpenMP "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenMP_CUDA "ON" CACHE BOOL "") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake")
diff --git a/.gitlab/ci/configure_cuda13.0_nvidia_fastbuild.cmake b/.gitlab/ci/configure_cuda13.0_nvidia_fastbuild.cmake new file mode 100644 index 0000000..71aafcf --- /dev/null +++ b/.gitlab/ci/configure_cuda13.0_nvidia_fastbuild.cmake
@@ -0,0 +1 @@ +include("${CMAKE_CURRENT_LIST_DIR}/configure_cuda13.0_nvidia_common.cmake")
diff --git a/.gitlab/ci/configure_debian12_aarch64_ninja.cmake b/.gitlab/ci/configure_debian12_aarch64_ninja.cmake deleted file mode 100644 index b533822..0000000 --- a/.gitlab/ci/configure_debian12_aarch64_ninja.cmake +++ /dev/null
@@ -1,116 +0,0 @@ -set(CMake_TEST_C_STANDARDS "90;99;11;17;23" CACHE STRING "") -set(CMake_TEST_CXX_STANDARDS "98;11;14;17;20;23" CACHE STRING "") - -set(blas_lapack_cases - All - static=1 Generic - model=lp64 - static=0 thread=SEQ NVPL thread=OMP NVPL thread= NVPL - model=ilp64 - static=0 thread=SEQ NVPL thread=OMP NVPL thread= NVPL - ) - -set(CMake_TEST_CTestUpdate_BZR "ON" CACHE BOOL "") -set(CMake_TEST_CTestUpdate_CVS "ON" CACHE BOOL "") -set(CMake_TEST_CTestUpdate_GIT "ON" CACHE BOOL "") -set(CMake_TEST_CTestUpdate_HG "ON" CACHE BOOL "") -set(CMake_TEST_CTestUpdate_SVN "ON" CACHE BOOL "") -set(CMake_TEST_FindALSA "ON" CACHE BOOL "") -set(CMake_TEST_FindASPELL "ON" CACHE BOOL "") -set(CMake_TEST_FindBLAS "${blas_lapack_cases}" 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 "") -set(CMake_TEST_FindFontconfig "ON" CACHE BOOL "") -set(CMake_TEST_FindFreetype "ON" CACHE BOOL "") -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 "") -set(CMake_TEST_FindGTK2 "ON" CACHE BOOL "") -set(CMake_TEST_FindHDF5 "ON" CACHE BOOL "") -set(CMake_TEST_FindHDF5_MPICH_C_COMPILER "/usr/bin/h5pcc.mpich" CACHE FILEPATH "") -set(CMake_TEST_FindHDF5_MPICH_C_COMPILER_EXPLICIT "ON" CACHE BOOL "") -set(CMake_TEST_FindHDF5_MPICH_CXX_COMPILER "/usr/bin/h5c++.mpich" CACHE FILEPATH "") -set(CMake_TEST_FindHDF5_MPICH_CXX_COMPILER_EXPLICIT "ON" CACHE BOOL "") -set(CMake_TEST_FindHDF5_MPICH_Fortran_COMPILER "/usr/bin/h5pfc.mpich" CACHE FILEPATH "") -set(CMake_TEST_FindHDF5_MPICH_Fortran_COMPILER_EXPLICIT "ON" CACHE BOOL "") -set(CMake_TEST_FindHDF5_OpenMPI_C_COMPILER "/usr/bin/h5pcc.openmpi" CACHE FILEPATH "") -set(CMake_TEST_FindHDF5_OpenMPI_C_COMPILER_EXPLICIT "ON" CACHE BOOL "") -set(CMake_TEST_FindHDF5_OpenMPI_CXX_COMPILER "/usr/bin/h5c++.openmpi" CACHE FILEPATH "") -set(CMake_TEST_FindHDF5_OpenMPI_CXX_COMPILER_EXPLICIT "ON" CACHE BOOL "") -set(CMake_TEST_FindHDF5_OpenMPI_Fortran_COMPILER "/usr/bin/h5pfc.openmpi" CACHE FILEPATH "") -set(CMake_TEST_FindHDF5_OpenMPI_Fortran_COMPILER_EXPLICIT "ON" CACHE BOOL "") -set(CMake_TEST_FindHDF5_Serial_C_COMPILER "/usr/bin/h5cc" CACHE FILEPATH "") -set(CMake_TEST_FindHDF5_Serial_CXX_COMPILER "/usr/bin/h5c++" CACHE FILEPATH "") -set(CMake_TEST_FindHDF5_Serial_Fortran_COMPILER "/usr/bin/h5fc" CACHE FILEPATH "") -set(CMake_TEST_FindIconv "ON" CACHE BOOL "") -set(CMake_TEST_FindICU "ON" CACHE BOOL "") -set(CMake_TEST_FindImageMagick "ON" CACHE BOOL "") -set(CMake_TEST_FindIntl "ON" CACHE BOOL "") -set(CMake_TEST_FindJNI "ON" CACHE BOOL "") -set(CMake_TEST_FindJPEG "ON" CACHE BOOL "") -set(CMake_TEST_FindJsonCpp "ON" CACHE BOOL "") -set(CMake_TEST_FindLAPACK "${blas_lapack_cases}" CACHE STRING "") -set(CMake_TEST_FindLibArchive "ON" CACHE BOOL "") -set(CMake_TEST_FindLibinput "ON" CACHE BOOL "") -set(CMake_TEST_FindLibLZMA "ON" CACHE BOOL "") -set(CMake_TEST_FindLibUV "ON" CACHE BOOL "") -set(CMake_TEST_FindLibXml2 "ON" CACHE BOOL "") -set(CMake_TEST_FindLibXslt "ON" CACHE BOOL "") -set(CMake_TEST_FindMPI_C "ON" CACHE BOOL "") -set(CMake_TEST_FindMPI_CXX "ON" CACHE BOOL "") -set(CMake_TEST_FindMPI_Fortran "ON" CACHE BOOL "") -set(CMake_TEST_FindMPI "ON" CACHE BOOL "") -set(CMake_TEST_FindODBC "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenACC "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenACC_C "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenACC_CXX "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenACC_Fortran "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenAL "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenGL "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenMP_C "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenMP_CXX "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenMP_Fortran "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenMP "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenSP "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenSSL "ON" CACHE BOOL "") -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_FindPython3 "ON" CACHE BOOL "") -set(CMake_TEST_FindPython3_NumPy "ON" CACHE BOOL "") -set(CMake_TEST_FindPython3_PyPy "ON" CACHE BOOL "") -set(CMake_TEST_FindRuby "ON" CACHE BOOL "") -set(CMake_TEST_FindSDL "ON" CACHE BOOL "") -set(CMake_TEST_FindSQLite3 "ON" CACHE BOOL "") -set(CMake_TEST_FindTIFF "ON" CACHE BOOL "") -set(CMake_TEST_FindwxWidgets "ON" CACHE BOOL "") -set(CMake_TEST_FindX11 "ON" CACHE BOOL "") -set(CMake_TEST_FindXalanC "ON" CACHE BOOL "") -set(CMake_TEST_FindXercesC "ON" CACHE BOOL "") -set(CMake_TEST_Fortran_SUBMODULES "ON" CACHE BOOL "") -set(CMake_TEST_IPO_WORKS_C "ON" CACHE BOOL "") -set(CMake_TEST_IPO_WORKS_CXX "ON" CACHE BOOL "") -set(CMake_TEST_IPO_WORKS_Fortran "ON" CACHE BOOL "") -set(CMake_TEST_JQ "/usr/bin/jq" CACHE PATH "") -set(CMake_TEST_Qt5 "ON" CACHE BOOL "") -set(CMake_TEST_TLS_VERIFY_URL "https://gitlab.kitware.com" CACHE STRING "") -set(CMake_TEST_TLS_VERIFY_URL_BAD "https://badtls-expired.kitware.com" CACHE STRING "") -set(CMake_TEST_TLS_VERSION "1.3" CACHE STRING "") -set(CMake_TEST_TLS_VERSION_URL_BAD "https://badtls-v1-1.kitware.com:8011" CACHE STRING "") -set(CMake_TEST_UseSWIG "ON" CACHE BOOL "") - -include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake")
diff --git a/.gitlab/ci/configure_debian12_iwyu.cmake b/.gitlab/ci/configure_debian12_iwyu.cmake deleted file mode 100644 index 37ccbf4..0000000 --- a/.gitlab/ci/configure_debian12_iwyu.cmake +++ /dev/null
@@ -1,7 +0,0 @@ -set(CMake_RUN_IWYU ON CACHE BOOL "") -set(CMake_IWYU_OPTIONS "-DCMAKE_IWYU_FORWARD_STD_HASH" CACHE STRING "") -# Uncomment to diagnose IWYU problems as needed. -#set(CMake_IWYU_VERBOSE ON CACHE BOOL "") -set(IWYU_COMMAND "/usr/bin/include-what-you-use-15" CACHE FILEPATH "") - -include("${CMAKE_CURRENT_LIST_DIR}/configure_common.cmake")
diff --git a/.gitlab/ci/configure_debian12_makefiles_clang.cmake b/.gitlab/ci/configure_debian12_makefiles_clang.cmake deleted file mode 100644 index 9bd6275..0000000 --- a/.gitlab/ci/configure_debian12_makefiles_clang.cmake +++ /dev/null
@@ -1,9 +0,0 @@ -set(CMake_TEST_C_STANDARDS "90;99;11;17;23" CACHE STRING "") -set(CMake_TEST_CXX_STANDARDS "98;11;14;17;20;23" CACHE STRING "") - -if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "") - set(CMake_TEST_IAR_TOOLCHAINS "/opt/iarsystems" CACHE PATH "") - set(CMake_TEST_TICLANG_TOOLCHAINS "$ENV{CI_PROJECT_DIR}/.gitlab/ticlang" CACHE PATH "") -endif() - -include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake")
diff --git a/.gitlab/ci/configure_debian12_ninja.cmake b/.gitlab/ci/configure_debian12_ninja.cmake deleted file mode 100644 index efca7a1..0000000 --- a/.gitlab/ci/configure_debian12_ninja.cmake +++ /dev/null
@@ -1,4 +0,0 @@ -set(CMake_TEST_ASM_NASM "ON" CACHE BOOL "") - -include("${CMAKE_CURRENT_LIST_DIR}/configure_debian12_ninja_common.cmake") -set(CMake_TEST_UseSWIG "ON" CACHE BOOL "")
diff --git a/.gitlab/ci/configure_debian12_ninja_clang.cmake b/.gitlab/ci/configure_debian12_ninja_clang.cmake deleted file mode 100644 index 1a8e192..0000000 --- a/.gitlab/ci/configure_debian12_ninja_clang.cmake +++ /dev/null
@@ -1,6 +0,0 @@ -if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "") - set(CMake_TEST_IAR_TOOLCHAINS "/opt/iarsystems" CACHE PATH "") - set(CMake_TEST_TICLANG_TOOLCHAINS "$ENV{CI_PROJECT_DIR}/.gitlab/ticlang" CACHE PATH "") -endif() - -include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake")
diff --git a/.gitlab/ci/configure_debian12_ninja_common.cmake b/.gitlab/ci/configure_debian12_ninja_common.cmake deleted file mode 100644 index 3022725..0000000 --- a/.gitlab/ci/configure_debian12_ninja_common.cmake +++ /dev/null
@@ -1,123 +0,0 @@ -set(CMake_TEST_C_STANDARDS "90;99;11;17;23" CACHE STRING "") -set(CMake_TEST_CXX_STANDARDS "98;11;14;17;20;23" CACHE STRING "") - -set(CMake_TEST_CTestUpdate_BZR "ON" CACHE BOOL "") -set(CMake_TEST_CTestUpdate_CVS "ON" CACHE BOOL "") -set(CMake_TEST_CTestUpdate_GIT "ON" CACHE BOOL "") -set(CMake_TEST_CTestUpdate_HG "ON" CACHE BOOL "") -set(CMake_TEST_CTestUpdate_SVN "ON" CACHE BOOL "") -if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "") - set(CMake_TEST_CTestUpdate_P4 "ON" CACHE BOOL "") -endif() - -set(CMake_TEST_FindALSA "ON" CACHE BOOL "") -set(CMake_TEST_FindASPELL "ON" CACHE BOOL "") -set(CMake_TEST_FindBacktrace "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 "") -set(CMake_TEST_FindFontconfig "ON" CACHE BOOL "") -set(CMake_TEST_FindFreetype "ON" CACHE BOOL "") -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 "") -set(CMake_TEST_FindGTK2 "ON" CACHE BOOL "") -set(CMake_TEST_FindHDF5 "ON" CACHE BOOL "") -set(CMake_TEST_FindHDF5_MPICH_C_COMPILER "/usr/bin/h5pcc.mpich" CACHE FILEPATH "") -set(CMake_TEST_FindHDF5_MPICH_C_COMPILER_EXPLICIT "ON" CACHE BOOL "") -set(CMake_TEST_FindHDF5_MPICH_CXX_COMPILER "/usr/bin/h5c++.mpich" CACHE FILEPATH "") -set(CMake_TEST_FindHDF5_MPICH_CXX_COMPILER_EXPLICIT "ON" CACHE BOOL "") -set(CMake_TEST_FindHDF5_MPICH_Fortran_COMPILER "/usr/bin/h5pfc.mpich" CACHE FILEPATH "") -set(CMake_TEST_FindHDF5_MPICH_Fortran_COMPILER_EXPLICIT "ON" CACHE BOOL "") -set(CMake_TEST_FindHDF5_OpenMPI_C_COMPILER "/usr/bin/h5pcc.openmpi" CACHE FILEPATH "") -set(CMake_TEST_FindHDF5_OpenMPI_C_COMPILER_EXPLICIT "ON" CACHE BOOL "") -set(CMake_TEST_FindHDF5_OpenMPI_CXX_COMPILER "/usr/bin/h5c++.openmpi" CACHE FILEPATH "") -set(CMake_TEST_FindHDF5_OpenMPI_CXX_COMPILER_EXPLICIT "ON" CACHE BOOL "") -set(CMake_TEST_FindHDF5_OpenMPI_Fortran_COMPILER "/usr/bin/h5pfc.openmpi" CACHE FILEPATH "") -set(CMake_TEST_FindHDF5_OpenMPI_Fortran_COMPILER_EXPLICIT "ON" CACHE BOOL "") -set(CMake_TEST_FindHDF5_Serial_C_COMPILER "/usr/bin/h5cc" CACHE FILEPATH "") -set(CMake_TEST_FindHDF5_Serial_CXX_COMPILER "/usr/bin/h5c++" CACHE FILEPATH "") -set(CMake_TEST_FindHDF5_Serial_Fortran_COMPILER "/usr/bin/h5fc" CACHE FILEPATH "") -set(CMake_TEST_FindIconv "ON" CACHE BOOL "") -set(CMake_TEST_FindICU "ON" CACHE BOOL "") -set(CMake_TEST_FindImageMagick "ON" CACHE BOOL "") -set(CMake_TEST_FindIntl "ON" CACHE BOOL "") -set(CMake_TEST_FindJNI "ON" CACHE BOOL "") -set(CMake_TEST_FindJPEG "ON" CACHE BOOL "") -set(CMake_TEST_FindJsonCpp "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 "") -set(CMake_TEST_FindLibUV "ON" CACHE BOOL "") -set(CMake_TEST_FindLibXml2 "ON" CACHE BOOL "") -set(CMake_TEST_FindLibXslt "ON" CACHE BOOL "") -set(CMake_TEST_FindMPI_C "ON" CACHE BOOL "") -set(CMake_TEST_FindMPI_CXX "ON" CACHE BOOL "") -set(CMake_TEST_FindMPI_Fortran "ON" CACHE BOOL "") -set(CMake_TEST_FindMPI "ON" CACHE BOOL "") -set(CMake_TEST_FindODBC "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenACC "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenACC_C "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenACC_CXX "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenACC_Fortran "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenAL "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenGL "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenMP_C "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenMP_CXX "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenMP_Fortran "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenMP "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenSP "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenSSL "ON" CACHE BOOL "") -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_FindPython3 "ON" CACHE BOOL "") -set(CMake_TEST_FindPython3_IronPython "ON" CACHE BOOL "") -set(CMake_TEST_FindPython3_PyPy "ON" CACHE BOOL "") -set(CMake_TEST_FindRuby "ON" CACHE BOOL "") -#set(CMake_TEST_FindRuby_RBENV "ON" CACHE BOOL "") # fails because system and rbenv versions are same -set(CMake_TEST_FindRuby_RVM "ON" CACHE BOOL "") -set(CMake_TEST_FindSDL "ON" CACHE BOOL "") -set(CMake_TEST_FindSQLite3 "ON" CACHE BOOL "") -set(CMake_TEST_FindTIFF "ON" CACHE BOOL "") -set(CMake_TEST_FindwxWidgets "ON" CACHE BOOL "") -set(CMake_TEST_FindX11 "ON" CACHE BOOL "") -set(CMake_TEST_FindXalanC "ON" CACHE BOOL "") -set(CMake_TEST_FindXercesC "ON" CACHE BOOL "") - -set(CMake_TEST_ELF_LARGE "ON" CACHE BOOL "") -set(CMake_TEST_Fortran_SUBMODULES "ON" CACHE BOOL "") -set(CMake_TEST_IPO_WORKS_C "ON" CACHE BOOL "") -set(CMake_TEST_IPO_WORKS_CXX "ON" CACHE BOOL "") -set(CMake_TEST_IPO_WORKS_Fortran "ON" CACHE BOOL "") -set(CMake_TEST_JQ "/usr/bin/jq" CACHE PATH "") -set(CMake_TEST_Qt5 "ON" CACHE BOOL "") -set(CMake_TEST_TLS_VERIFY_URL "https://gitlab.kitware.com" CACHE STRING "") -set(CMake_TEST_TLS_VERIFY_URL_BAD "https://badtls-expired.kitware.com" CACHE STRING "") -set(CMake_TEST_TLS_VERSION "1.3" CACHE STRING "") -set(CMake_TEST_TLS_VERSION_URL_BAD "https://badtls-v1-1.kitware.com:8011" CACHE STRING "") - -if (NOT "$ENV{SWIFTC}" STREQUAL "") - set(CMAKE_Swift_COMPILER "$ENV{SWIFTC}" CACHE FILEPATH "") -endif() - -if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "") - set(CMAKE_TESTS_CDASH_SERVER "https://open.cdash.org" CACHE STRING "") -endif() - -include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake")
diff --git a/.gitlab/ci/configure_debian12_ninja_multi_symlinked.cmake b/.gitlab/ci/configure_debian12_ninja_multi_symlinked.cmake deleted file mode 100644 index 646dac8..0000000 --- a/.gitlab/ci/configure_debian12_ninja_multi_symlinked.cmake +++ /dev/null
@@ -1,7 +0,0 @@ -if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "") - set(CMake_TEST_IAR_TOOLCHAINS "/opt/iarsystems" CACHE PATH "") -endif() - -include("${CMAKE_CURRENT_LIST_DIR}/configure_symlinked_common.cmake") -include("${CMAKE_CURRENT_LIST_DIR}/configure_debian12_ninja_common.cmake") -set(CMake_TEST_UseSWIG "OFF" CACHE BOOL "")
diff --git a/.gitlab/ci/configure_debian12_aarch64_extdeps.cmake b/.gitlab/ci/configure_debian13_aarch64_extdeps.cmake similarity index 100% rename from .gitlab/ci/configure_debian12_aarch64_extdeps.cmake rename to .gitlab/ci/configure_debian13_aarch64_extdeps.cmake
diff --git a/.gitlab/ci/configure_debian13_aarch64_ninja.cmake b/.gitlab/ci/configure_debian13_aarch64_ninja.cmake new file mode 100644 index 0000000..90fb7d9 --- /dev/null +++ b/.gitlab/ci/configure_debian13_aarch64_ninja.cmake
@@ -0,0 +1,116 @@ +set(CMake_TEST_C_STANDARDS "90;99;11;17;23" CACHE STRING "") +set(CMake_TEST_CXX_STANDARDS "98;11;14;17;20;23;26" CACHE STRING "") + +set(blas_lapack_cases + All + static=1 Generic + model=lp64 + static=0 thread=SEQ NVPL thread=OMP NVPL thread= NVPL + model=ilp64 + static=0 thread=SEQ NVPL thread=OMP NVPL thread= NVPL + ) + +set(CMake_TEST_CTestUpdate_BZR "ON" CACHE BOOL "") +set(CMake_TEST_CTestUpdate_CVS "ON" CACHE BOOL "") +set(CMake_TEST_CTestUpdate_GIT "ON" CACHE BOOL "") +set(CMake_TEST_CTestUpdate_HG "ON" CACHE BOOL "") +set(CMake_TEST_CTestUpdate_SVN "ON" CACHE BOOL "") +set(CMake_TEST_FindALSA "ON" CACHE BOOL "") +set(CMake_TEST_FindASPELL "ON" CACHE BOOL "") +set(CMake_TEST_FindBLAS "${blas_lapack_cases}" 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 "") +set(CMake_TEST_FindFontconfig "ON" CACHE BOOL "") +set(CMake_TEST_FindFreetype "ON" CACHE BOOL "") +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 "") +set(CMake_TEST_FindGTK2 "ON" CACHE BOOL "") +set(CMake_TEST_FindHDF5 "ON" CACHE BOOL "") +set(CMake_TEST_FindHDF5_MPICH_C_COMPILER "/usr/bin/h5pcc.mpich" CACHE FILEPATH "") +set(CMake_TEST_FindHDF5_MPICH_C_COMPILER_EXPLICIT "ON" CACHE BOOL "") +set(CMake_TEST_FindHDF5_MPICH_CXX_COMPILER "/usr/bin/h5c++.mpich" CACHE FILEPATH "") +set(CMake_TEST_FindHDF5_MPICH_CXX_COMPILER_EXPLICIT "ON" CACHE BOOL "") +set(CMake_TEST_FindHDF5_MPICH_Fortran_COMPILER "/usr/bin/h5pfc.mpich" CACHE FILEPATH "") +set(CMake_TEST_FindHDF5_MPICH_Fortran_COMPILER_EXPLICIT "ON" CACHE BOOL "") +set(CMake_TEST_FindHDF5_OpenMPI_C_COMPILER "/usr/bin/h5pcc.openmpi" CACHE FILEPATH "") +set(CMake_TEST_FindHDF5_OpenMPI_C_COMPILER_EXPLICIT "ON" CACHE BOOL "") +set(CMake_TEST_FindHDF5_OpenMPI_CXX_COMPILER "/usr/bin/h5c++.openmpi" CACHE FILEPATH "") +set(CMake_TEST_FindHDF5_OpenMPI_CXX_COMPILER_EXPLICIT "ON" CACHE BOOL "") +set(CMake_TEST_FindHDF5_OpenMPI_Fortran_COMPILER "/usr/bin/h5pfc.openmpi" CACHE FILEPATH "") +set(CMake_TEST_FindHDF5_OpenMPI_Fortran_COMPILER_EXPLICIT "ON" CACHE BOOL "") +set(CMake_TEST_FindHDF5_Serial_C_COMPILER "/usr/bin/h5cc" CACHE FILEPATH "") +set(CMake_TEST_FindHDF5_Serial_CXX_COMPILER "/usr/bin/h5c++" CACHE FILEPATH "") +set(CMake_TEST_FindHDF5_Serial_Fortran_COMPILER "/usr/bin/h5fc" CACHE FILEPATH "") +set(CMake_TEST_FindIconv "ON" CACHE BOOL "") +set(CMake_TEST_FindICU "ON" CACHE BOOL "") +set(CMake_TEST_FindImageMagick "ON" CACHE BOOL "") +set(CMake_TEST_FindIntl "ON" CACHE BOOL "") +set(CMake_TEST_FindJNI "ON" CACHE BOOL "") +set(CMake_TEST_FindJPEG "ON" CACHE BOOL "") +set(CMake_TEST_FindJsonCpp "ON" CACHE BOOL "") +set(CMake_TEST_FindLAPACK "${blas_lapack_cases}" CACHE STRING "") +set(CMake_TEST_FindLibArchive "ON" CACHE BOOL "") +set(CMake_TEST_FindLibinput "ON" CACHE BOOL "") +set(CMake_TEST_FindLibLZMA "ON" CACHE BOOL "") +set(CMake_TEST_FindLibUV "ON" CACHE BOOL "") +set(CMake_TEST_FindLibXml2 "ON" CACHE BOOL "") +set(CMake_TEST_FindLibXslt "ON" CACHE BOOL "") +set(CMake_TEST_FindMPI_C "ON" CACHE BOOL "") +set(CMake_TEST_FindMPI_CXX "ON" CACHE BOOL "") +set(CMake_TEST_FindMPI_Fortran "ON" CACHE BOOL "") +set(CMake_TEST_FindMPI "ON" CACHE BOOL "") +set(CMake_TEST_FindODBC "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenACC "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenACC_C "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenACC_CXX "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenACC_Fortran "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenAL "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenGL "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenMP_C "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenMP_CXX "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenMP_Fortran "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenMP "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenSP "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenSSL "ON" CACHE BOOL "") +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_FindPython3 "ON" CACHE BOOL "") +set(CMake_TEST_FindPython3_NumPy "ON" CACHE BOOL "") +set(CMake_TEST_FindPython3_PyPy "ON" CACHE BOOL "") +set(CMake_TEST_FindRuby "ON" CACHE BOOL "") +set(CMake_TEST_FindSDL "ON" CACHE BOOL "") +set(CMake_TEST_FindSQLite3 "ON" CACHE BOOL "") +set(CMake_TEST_FindTIFF "ON" CACHE BOOL "") +set(CMake_TEST_FindwxWidgets "ON" CACHE BOOL "") +set(CMake_TEST_FindX11 "ON" CACHE BOOL "") +set(CMake_TEST_FindXalanC "ON" CACHE BOOL "") +set(CMake_TEST_FindXercesC "ON" CACHE BOOL "") +set(CMake_TEST_Fortran_SUBMODULES "ON" CACHE BOOL "") +set(CMake_TEST_IPO_WORKS_C "ON" CACHE BOOL "") +set(CMake_TEST_IPO_WORKS_CXX "ON" CACHE BOOL "") +set(CMake_TEST_IPO_WORKS_Fortran "ON" CACHE BOOL "") +set(CMake_TEST_JQ "/usr/bin/jq" CACHE PATH "") +set(CMake_TEST_Qt5 "ON" CACHE BOOL "") +set(CMake_TEST_TLS_VERIFY_URL "https://gitlab.kitware.com" CACHE STRING "") +set(CMake_TEST_TLS_VERIFY_URL_BAD "https://badtls-expired.kitware.com" CACHE STRING "") +set(CMake_TEST_TLS_VERSION "1.3" CACHE STRING "") +set(CMake_TEST_TLS_VERSION_URL_BAD "https://badtls-v1-1.kitware.com:8011" CACHE STRING "") +set(CMake_TEST_UseSWIG "ON" CACHE BOOL "") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake")
diff --git a/.gitlab/ci/configure_debian12_extdeps.cmake b/.gitlab/ci/configure_debian13_extdeps.cmake similarity index 100% rename from .gitlab/ci/configure_debian12_extdeps.cmake rename to .gitlab/ci/configure_debian13_extdeps.cmake
diff --git a/.gitlab/ci/configure_debian12_hip_radeon.cmake b/.gitlab/ci/configure_debian13_hip_radeon.cmake similarity index 100% rename from .gitlab/ci/configure_debian12_hip_radeon.cmake rename to .gitlab/ci/configure_debian13_hip_radeon.cmake
diff --git a/.gitlab/ci/configure_debian13_iwyu.cmake b/.gitlab/ci/configure_debian13_iwyu.cmake new file mode 100644 index 0000000..150eb9c --- /dev/null +++ b/.gitlab/ci/configure_debian13_iwyu.cmake
@@ -0,0 +1,7 @@ +set(CMake_RUN_IWYU ON CACHE BOOL "") +set(CMake_IWYU_OPTIONS "-DCMAKE_IWYU_FORWARD_STD_HASH" CACHE STRING "") +# Uncomment to diagnose IWYU problems as needed. +#set(CMake_IWYU_VERBOSE ON CACHE BOOL "") +set(IWYU_COMMAND "/usr/bin/include-what-you-use-19" CACHE FILEPATH "") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_common.cmake")
diff --git a/.gitlab/ci/configure_debian13_makefiles_clang.cmake b/.gitlab/ci/configure_debian13_makefiles_clang.cmake new file mode 100644 index 0000000..f928ecc --- /dev/null +++ b/.gitlab/ci/configure_debian13_makefiles_clang.cmake
@@ -0,0 +1,11 @@ +set(CMake_TEST_C_STANDARDS "90;99;11;17;23" CACHE STRING "") +set(CMake_TEST_CXX_STANDARDS "98;11;14;17;20;23;26" CACHE STRING "") + +if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "") + set(CMake_TEST_IAR_TOOLCHAINS "/opt/iarsystems" CACHE PATH "") + set(CMake_TEST_TICLANG_TOOLCHAINS "$ENV{CI_PROJECT_DIR}/.gitlab/ticlang" CACHE PATH "") + set(CMake_TEST_Emscripten_TOOLCHAINS "$ENV{EMSDK}/upstream/emscripten" CACHE PATH "") + set(CMake_TEST_Emscripten_NODE "$ENV{EMSDK_NODE}" CACHE PATH "") +endif() + +include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake")
diff --git a/.gitlab/ci/configure_debian12_makefiles_inplace.cmake b/.gitlab/ci/configure_debian13_makefiles_inplace.cmake similarity index 100% rename from .gitlab/ci/configure_debian12_makefiles_inplace.cmake rename to .gitlab/ci/configure_debian13_makefiles_inplace.cmake
diff --git a/.gitlab/ci/configure_debian13_ninja.cmake b/.gitlab/ci/configure_debian13_ninja.cmake new file mode 100644 index 0000000..89d9818 --- /dev/null +++ b/.gitlab/ci/configure_debian13_ninja.cmake
@@ -0,0 +1,4 @@ +set(CMake_TEST_ASM_NASM "ON" CACHE BOOL "") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_debian13_ninja_common.cmake") +set(CMake_TEST_UseSWIG "ON" CACHE BOOL "")
diff --git a/.gitlab/ci/configure_debian13_ninja_clang.cmake b/.gitlab/ci/configure_debian13_ninja_clang.cmake new file mode 100644 index 0000000..8280304 --- /dev/null +++ b/.gitlab/ci/configure_debian13_ninja_clang.cmake
@@ -0,0 +1,8 @@ +if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "") + set(CMake_TEST_IAR_TOOLCHAINS "/opt/iarsystems" CACHE PATH "") + set(CMake_TEST_TICLANG_TOOLCHAINS "$ENV{CI_PROJECT_DIR}/.gitlab/ticlang" CACHE PATH "") + set(CMake_TEST_Emscripten_TOOLCHAINS "$ENV{EMSDK}/upstream/emscripten" CACHE PATH "") + set(CMake_TEST_Emscripten_NODE "$ENV{EMSDK_NODE}" CACHE PATH "") +endif() + +include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake")
diff --git a/.gitlab/ci/configure_debian13_ninja_common.cmake b/.gitlab/ci/configure_debian13_ninja_common.cmake new file mode 100644 index 0000000..8b1bf14 --- /dev/null +++ b/.gitlab/ci/configure_debian13_ninja_common.cmake
@@ -0,0 +1,123 @@ +set(CMake_TEST_C_STANDARDS "90;99;11;17;23" CACHE STRING "") +set(CMake_TEST_CXX_STANDARDS "98;11;14;17;20;23;26" CACHE STRING "") + +set(CMake_TEST_CTestUpdate_BZR "ON" CACHE BOOL "") +set(CMake_TEST_CTestUpdate_CVS "ON" CACHE BOOL "") +set(CMake_TEST_CTestUpdate_GIT "ON" CACHE BOOL "") +set(CMake_TEST_CTestUpdate_HG "ON" CACHE BOOL "") +set(CMake_TEST_CTestUpdate_SVN "ON" CACHE BOOL "") +if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "") + set(CMake_TEST_CTestUpdate_P4 "ON" CACHE BOOL "") +endif() + +set(CMake_TEST_FindALSA "ON" CACHE BOOL "") +set(CMake_TEST_FindASPELL "ON" CACHE BOOL "") +set(CMake_TEST_FindBacktrace "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 "") +set(CMake_TEST_FindFontconfig "ON" CACHE BOOL "") +set(CMake_TEST_FindFreetype "ON" CACHE BOOL "") +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 "") +set(CMake_TEST_FindGTK2 "ON" CACHE BOOL "") +set(CMake_TEST_FindHDF5 "ON" CACHE BOOL "") +set(CMake_TEST_FindHDF5_MPICH_C_COMPILER "/usr/bin/h5pcc.mpich" CACHE FILEPATH "") +set(CMake_TEST_FindHDF5_MPICH_C_COMPILER_EXPLICIT "ON" CACHE BOOL "") +set(CMake_TEST_FindHDF5_MPICH_CXX_COMPILER "/usr/bin/h5c++.mpich" CACHE FILEPATH "") +set(CMake_TEST_FindHDF5_MPICH_CXX_COMPILER_EXPLICIT "ON" CACHE BOOL "") +set(CMake_TEST_FindHDF5_MPICH_Fortran_COMPILER "/usr/bin/h5pfc.mpich" CACHE FILEPATH "") +set(CMake_TEST_FindHDF5_MPICH_Fortran_COMPILER_EXPLICIT "ON" CACHE BOOL "") +set(CMake_TEST_FindHDF5_OpenMPI_C_COMPILER "/usr/bin/h5pcc.openmpi" CACHE FILEPATH "") +set(CMake_TEST_FindHDF5_OpenMPI_C_COMPILER_EXPLICIT "ON" CACHE BOOL "") +set(CMake_TEST_FindHDF5_OpenMPI_CXX_COMPILER "/usr/bin/h5c++.openmpi" CACHE FILEPATH "") +set(CMake_TEST_FindHDF5_OpenMPI_CXX_COMPILER_EXPLICIT "ON" CACHE BOOL "") +set(CMake_TEST_FindHDF5_OpenMPI_Fortran_COMPILER "/usr/bin/h5pfc.openmpi" CACHE FILEPATH "") +set(CMake_TEST_FindHDF5_OpenMPI_Fortran_COMPILER_EXPLICIT "ON" CACHE BOOL "") +set(CMake_TEST_FindHDF5_Serial_C_COMPILER "/usr/bin/h5cc" CACHE FILEPATH "") +set(CMake_TEST_FindHDF5_Serial_CXX_COMPILER "/usr/bin/h5c++" CACHE FILEPATH "") +set(CMake_TEST_FindHDF5_Serial_Fortran_COMPILER "/usr/bin/h5fc" CACHE FILEPATH "") +set(CMake_TEST_FindIconv "ON" CACHE BOOL "") +set(CMake_TEST_FindICU "ON" CACHE BOOL "") +set(CMake_TEST_FindImageMagick "ON" CACHE BOOL "") +set(CMake_TEST_FindIntl "ON" CACHE BOOL "") +set(CMake_TEST_FindJNI "ON" CACHE BOOL "") +set(CMake_TEST_FindJPEG "ON" CACHE BOOL "") +set(CMake_TEST_FindJsonCpp "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 "") +set(CMake_TEST_FindLibUV "ON" CACHE BOOL "") +set(CMake_TEST_FindLibXml2 "ON" CACHE BOOL "") +set(CMake_TEST_FindLibXslt "ON" CACHE BOOL "") +set(CMake_TEST_FindMPI_C "ON" CACHE BOOL "") +set(CMake_TEST_FindMPI_CXX "ON" CACHE BOOL "") +set(CMake_TEST_FindMPI_Fortran "ON" CACHE BOOL "") +set(CMake_TEST_FindMPI "ON" CACHE BOOL "") +set(CMake_TEST_FindODBC "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenACC "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenACC_C "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenACC_CXX "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenACC_Fortran "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenAL "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenGL "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenMP_C "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenMP_CXX "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenMP_Fortran "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenMP "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenSP "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenSSL "ON" CACHE BOOL "") +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_FindPython3 "ON" CACHE BOOL "") +set(CMake_TEST_FindPython3_IronPython "ON" CACHE BOOL "") +set(CMake_TEST_FindPython3_PyPy "ON" CACHE BOOL "") +set(CMake_TEST_FindRuby "ON" CACHE BOOL "") +set(CMake_TEST_FindRuby_RBENV "ON" CACHE BOOL "") +set(CMake_TEST_FindRuby_RVM "ON" CACHE BOOL "") +set(CMake_TEST_FindSDL "ON" CACHE BOOL "") +set(CMake_TEST_FindSQLite3 "ON" CACHE BOOL "") +set(CMake_TEST_FindTIFF "ON" CACHE BOOL "") +set(CMake_TEST_FindwxWidgets "ON" CACHE BOOL "") +set(CMake_TEST_FindX11 "ON" CACHE BOOL "") +set(CMake_TEST_FindXalanC "ON" CACHE BOOL "") +set(CMake_TEST_FindXercesC "ON" CACHE BOOL "") + +set(CMake_TEST_ELF_LARGE "ON" CACHE BOOL "") +set(CMake_TEST_Fortran_SUBMODULES "ON" CACHE BOOL "") +set(CMake_TEST_IPO_WORKS_C "ON" CACHE BOOL "") +set(CMake_TEST_IPO_WORKS_CXX "ON" CACHE BOOL "") +set(CMake_TEST_IPO_WORKS_Fortran "ON" CACHE BOOL "") +set(CMake_TEST_JQ "/usr/bin/jq" CACHE PATH "") +set(CMake_TEST_Qt5 "ON" CACHE BOOL "") +set(CMake_TEST_TLS_VERIFY_URL "https://gitlab.kitware.com" CACHE STRING "") +set(CMake_TEST_TLS_VERIFY_URL_BAD "https://badtls-expired.kitware.com" CACHE STRING "") +set(CMake_TEST_TLS_VERSION "1.3" CACHE STRING "") +set(CMake_TEST_TLS_VERSION_URL_BAD "https://badtls-v1-1.kitware.com:8011" CACHE STRING "") + +if (NOT "$ENV{SWIFTC}" STREQUAL "") + set(CMAKE_Swift_COMPILER "$ENV{SWIFTC}" CACHE FILEPATH "") +endif() + +if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "") + set(CMAKE_TESTS_CDASH_SERVER "https://open.cdash.org" CACHE STRING "") +endif() + +include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake")
diff --git a/.gitlab/ci/configure_debian13_ninja_multi_symlinked.cmake b/.gitlab/ci/configure_debian13_ninja_multi_symlinked.cmake new file mode 100644 index 0000000..7455791 --- /dev/null +++ b/.gitlab/ci/configure_debian13_ninja_multi_symlinked.cmake
@@ -0,0 +1,7 @@ +if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "") + set(CMake_TEST_IAR_TOOLCHAINS "/opt/iarsystems" CACHE PATH "") +endif() + +include("${CMAKE_CURRENT_LIST_DIR}/configure_symlinked_common.cmake") +include("${CMAKE_CURRENT_LIST_DIR}/configure_debian13_ninja_common.cmake") +set(CMake_TEST_UseSWIG "OFF" CACHE BOOL "")
diff --git a/.gitlab/ci/configure_fedora42_asan.cmake b/.gitlab/ci/configure_fedora42_asan.cmake deleted file mode 100644 index 60a3cb1..0000000 --- a/.gitlab/ci/configure_fedora42_asan.cmake +++ /dev/null
@@ -1,5 +0,0 @@ -set(CMAKE_C_FLAGS "-fsanitize=address" CACHE STRING "") -set(CMAKE_CXX_FLAGS "-fsanitize=address" CACHE STRING "") -set(CMake_QT_MAJOR_VERSION "5" CACHE STRING "") - -include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora42_common.cmake")
diff --git a/.gitlab/ci/configure_fedora42_clang_analyzer.cmake b/.gitlab/ci/configure_fedora42_clang_analyzer.cmake deleted file mode 100644 index c484570..0000000 --- a/.gitlab/ci/configure_fedora42_clang_analyzer.cmake +++ /dev/null
@@ -1,4 +0,0 @@ -set(configure_no_sccache 1) -set(CMake_QT_MAJOR_VERSION "5" CACHE STRING "") - -include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora42_common.cmake")
diff --git a/.gitlab/ci/configure_fedora42_common_clang.cmake b/.gitlab/ci/configure_fedora42_common_clang.cmake deleted file mode 100644 index a4ae3f3..0000000 --- a/.gitlab/ci/configure_fedora42_common_clang.cmake +++ /dev/null
@@ -1,17 +0,0 @@ -set(CMAKE_Fortran_COMPILER "/usr/bin/flang-new" CACHE FILEPATH "") -set(CMAKE_Fortran_COMPILER_ID "LLVMFlang" CACHE STRING "") -set(CMAKE_Fortran_COMPILER_SUPPORTS_F90 "1" CACHE BOOL "") - -set(CMake_TEST_C_STANDARDS "90;99;11;17;23" CACHE STRING "") -set(CMake_TEST_CXX_STANDARDS "98;11;14;17;20;23;26" CACHE STRING "") - -set(CMake_TEST_FindOpenACC "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenACC_C "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenACC_CXX "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenACC_Fortran "OFF" CACHE BOOL "") # flang-new fails producing LLVM IR -set(CMake_TEST_FindOpenMP_C "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenMP_CXX "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenMP_Fortran "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenMP "ON" CACHE BOOL "") - -include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake")
diff --git a/.gitlab/ci/configure_fedora42_extdeps.cmake b/.gitlab/ci/configure_fedora42_extdeps.cmake deleted file mode 100644 index 8e545f5..0000000 --- a/.gitlab/ci/configure_fedora42_extdeps.cmake +++ /dev/null
@@ -1 +0,0 @@ -include("${CMAKE_CURRENT_LIST_DIR}/configure_extdeps_common.cmake")
diff --git a/.gitlab/ci/configure_fedora42_makefiles.cmake b/.gitlab/ci/configure_fedora42_makefiles.cmake deleted file mode 100644 index e84dcbd..0000000 --- a/.gitlab/ci/configure_fedora42_makefiles.cmake +++ /dev/null
@@ -1,117 +0,0 @@ -set(CMake_TEST_C_STANDARDS "90;99;11;17;23" CACHE STRING "") -set(CMake_TEST_CXX_STANDARDS "98;11;14;17;20;23;26" CACHE STRING "") - -set(CMake_TEST_CTestUpdate_BZR "ON" CACHE BOOL "") -set(CMake_TEST_CTestUpdate_GIT "ON" CACHE BOOL "") -set(CMake_TEST_CTestUpdate_HG "ON" CACHE BOOL "") -set(CMake_TEST_CTestUpdate_SVN "ON" CACHE BOOL "") -if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "") - set(CMake_TEST_CTestUpdate_P4 "ON" CACHE BOOL "") -endif() - -set(CMake_TEST_ASM_NASM "ON" CACHE BOOL "") -set(CMake_TEST_FindALSA "ON" CACHE BOOL "") -set(CMake_TEST_FindASPELL "ON" CACHE BOOL "") -set(CMake_TEST_FindBacktrace "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 "") -set(CMake_TEST_FindFontconfig "ON" CACHE BOOL "") -set(CMake_TEST_FindFreetype "ON" CACHE BOOL "") -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 "") -set(CMake_TEST_FindGTK2 "ON" CACHE BOOL "") -set(CMake_TEST_FindHDF5 "ON" CACHE BOOL "") -set(CMake_TEST_FindHDF5_MPICH_C_COMPILER "/usr/lib64/mpich/bin/h5pcc" CACHE FILEPATH "") -# set(CMake_TEST_FindHDF5_MPICH_CXX_COMPILER "/usr/lib64/mpich/bin/h5pc++" CACHE FILEPATH "") # h5pc++ does not exist -set(CMake_TEST_FindHDF5_MPICH_ENVMOD "PATH=path_list_prepend:/usr/lib64/mpich/bin;LD_LIBRARY_PATH=path_list_prepend:/usr/lib64/mpich/lib" CACHE STRING "") -set(CMake_TEST_FindHDF5_MPICH_Fortran_COMPILER "/usr/lib64/mpich/bin/h5pfc" CACHE FILEPATH "") -set(CMake_TEST_FindHDF5_OpenMPI_C_COMPILER "/usr/lib64/openmpi/bin/h5pcc" CACHE FILEPATH "") -set(CMake_TEST_FindHDF5_OpenMPI_ENVMOD "PATH=path_list_prepend:/usr/lib64/openmpi/bin;LD_LIBRARY_PATH=path_list_prepend:/usr/lib64/openmpi/lib" CACHE STRING "") -# set(CMake_TEST_FindHDF5_OpenMPI_CXX_COMPILER "/usr/lib64/openmpi/bin/h5pc++" CACHE FILEPATH "") # h5pc++ does not exist -set(CMake_TEST_FindHDF5_OpenMPI_Fortran_COMPILER "/usr/lib64/openmpi/bin/h5pfc" CACHE FILEPATH "") -set(CMake_TEST_FindHDF5_Serial_C_COMPILER "/usr/bin/h5cc" CACHE FILEPATH "") -set(CMake_TEST_FindHDF5_Serial_CXX_COMPILER "/usr/bin/h5c++" CACHE FILEPATH "") -set(CMake_TEST_FindHDF5_Serial_Fortran_COMPILER "/usr/bin/h5fc" CACHE FILEPATH "") -set(CMake_TEST_FindIconv "ON" CACHE BOOL "") -set(CMake_TEST_FindICU "ON" CACHE BOOL "") -set(CMake_TEST_FindImageMagick "ON" CACHE BOOL "") -set(CMake_TEST_FindIntl "ON" CACHE BOOL "") -set(CMake_TEST_FindJasper "ON" CACHE BOOL "") -set(CMake_TEST_FindJNI "ON" CACHE BOOL "") -set(CMake_TEST_FindJPEG "ON" CACHE BOOL "") -set(CMake_TEST_FindJsonCpp "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 "") -set(CMake_TEST_FindLibUV "ON" CACHE BOOL "") -set(CMake_TEST_FindLibXml2 "ON" CACHE BOOL "") -set(CMake_TEST_FindLibXslt "ON" CACHE BOOL "") -set(CMake_TEST_FindMPI_C "ON" CACHE BOOL "") -set(CMake_TEST_FindMPI_CXX "ON" CACHE BOOL "") -set(CMake_TEST_FindMPI_Fortran "ON" CACHE BOOL "") -set(CMake_TEST_FindMPI_ENVMOD "PATH=path_list_prepend:/usr/lib64/mpich/bin;LD_LIBRARY_PATH=path_list_prepend:/usr/lib64/mpich/lib;FI_PROVIDER=set:tcp" CACHE STRING "") -set(CMake_TEST_FindMPI "ON" CACHE BOOL "") -set(CMake_TEST_FindODBC "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenACC "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenACC_C "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenACC_CXX "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenACC_Fortran "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenAL "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenGL "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenMP_C "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenMP_CXX "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenMP_Fortran "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenMP "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenSP "ON" CACHE BOOL "") -set(CMake_TEST_FindOpenSSL "ON" CACHE BOOL "") -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_FindPython3 "ON" CACHE BOOL "") -set(CMake_TEST_FindPython3_NumPy "ON" CACHE BOOL "") -set(CMake_TEST_FindPython2_PyPy "ON" CACHE BOOL "") -set(CMake_TEST_FindPython3_PyPy "ON" CACHE BOOL "") -set(CMake_TEST_FindRuby "ON" CACHE BOOL "") -set(CMake_TEST_FindRuby_RBENV "ON" CACHE BOOL "") -set(CMake_TEST_FindRuby_RVM "ON" CACHE BOOL "") -set(CMake_TEST_FindSDL "ON" CACHE BOOL "") -set(CMake_TEST_FindSQLite3 "ON" CACHE BOOL "") -set(CMake_TEST_FindTIFF "ON" CACHE BOOL "") -set(CMake_TEST_FindwxWidgets "ON" CACHE BOOL "") -set(CMake_TEST_FindX11 "ON" CACHE BOOL "") -set(CMake_TEST_FindXalanC "ON" CACHE BOOL "") -set(CMake_TEST_FindXercesC "ON" CACHE BOOL "") - -set(CMake_TEST_ELF_LARGE "ON" CACHE BOOL "") -set(CMake_TEST_Fortran_SUBMODULES "ON" CACHE BOOL "") -set(CMake_TEST_IPO_WORKS_C "ON" CACHE BOOL "") -set(CMake_TEST_IPO_WORKS_CXX "ON" CACHE BOOL "") -set(CMake_TEST_IPO_WORKS_Fortran "ON" CACHE BOOL "") -if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "") - set(CMake_TEST_ISPC "ON" CACHE STRING "") -endif() -set(CMake_TEST_Qt5 "ON" CACHE BOOL "") -set(CMake_TEST_TLS_VERIFY_URL "https://gitlab.kitware.com" CACHE STRING "") -set(CMake_TEST_TLS_VERIFY_URL_BAD "https://badtls-expired.kitware.com" CACHE STRING "") -set(CMake_TEST_TLS_VERSION "1.3" CACHE STRING "") -set(CMake_TEST_TLS_VERSION_URL_BAD "https://badtls-v1-1.kitware.com:8011" CACHE STRING "") -set(CMake_TEST_UseSWIG "ON" CACHE BOOL "") - -include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake")
diff --git a/.gitlab/ci/configure_fedora42_makefiles_clang.cmake b/.gitlab/ci/configure_fedora42_makefiles_clang.cmake deleted file mode 100644 index 36588a5..0000000 --- a/.gitlab/ci/configure_fedora42_makefiles_clang.cmake +++ /dev/null
@@ -1,5 +0,0 @@ -if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "") - set(CMAKE_TESTS_CDASH_SERVER "https://open.cdash.org" CACHE STRING "") -endif() - -include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora42_common_clang.cmake")
diff --git a/.gitlab/ci/configure_fedora42_makefiles_lfortran.cmake b/.gitlab/ci/configure_fedora42_makefiles_lfortran.cmake deleted file mode 100644 index ae32c04..0000000 --- a/.gitlab/ci/configure_fedora42_makefiles_lfortran.cmake +++ /dev/null
@@ -1 +0,0 @@ -include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora42_common_lfortran.cmake")
diff --git a/.gitlab/ci/configure_fedora42_makefiles_symlinked.cmake b/.gitlab/ci/configure_fedora42_makefiles_symlinked.cmake deleted file mode 100644 index e498a48..0000000 --- a/.gitlab/ci/configure_fedora42_makefiles_symlinked.cmake +++ /dev/null
@@ -1,5 +0,0 @@ -set(CMake_QT_MAJOR_VERSION "6" CACHE STRING "") -set(CMake_TEST_GUI "ON" CACHE BOOL "") - -include("${CMAKE_CURRENT_LIST_DIR}/configure_symlinked_common.cmake") -include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora42_common.cmake")
diff --git a/.gitlab/ci/configure_fedora42_ninja.cmake b/.gitlab/ci/configure_fedora42_ninja.cmake deleted file mode 100644 index 07ce93b..0000000 --- a/.gitlab/ci/configure_fedora42_ninja.cmake +++ /dev/null
@@ -1,20 +0,0 @@ -set(CMake_TEST_GUI "ON" CACHE BOOL "") -if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "") - set(CMake_TEST_ISPC "ON" CACHE STRING "") -endif() -set(CMake_TEST_MODULE_COMPILATION "named,compile_commands,collation,partitions,internal_partitions,export_bmi,install_bmi,shared,bmionly,build_database" CACHE STRING "") -set(CMake_TEST_TLS_VERIFY_URL "https://gitlab.kitware.com" CACHE STRING "") -set(CMake_TEST_TLS_VERIFY_URL_BAD "https://badtls-expired.kitware.com" CACHE STRING "") -set(CMake_TEST_TLS_VERSION "1.3" CACHE STRING "") -set(CMake_TEST_TLS_VERSION_URL_BAD "https://badtls-v1-1.kitware.com:8011" CACHE STRING "") - -# "Release" flags without "-DNDEBUG" so we get assertions. -set(CMAKE_C_FLAGS_RELEASE "-O3" CACHE STRING "") -set(CMAKE_CXX_FLAGS_RELEASE "-O3" CACHE STRING "") - -# Cover compilation with C++11 only and not higher standards. -set(CMAKE_CXX_STANDARD "11" CACHE STRING "") -# Qt 6 requires C++17, so use Qt 5. -set(CMake_QT_MAJOR_VERSION "5" CACHE STRING "") - -include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora42_common.cmake")
diff --git a/.gitlab/ci/configure_fedora42_ninja_clang.cmake b/.gitlab/ci/configure_fedora42_ninja_clang.cmake deleted file mode 100644 index c95388f..0000000 --- a/.gitlab/ci/configure_fedora42_ninja_clang.cmake +++ /dev/null
@@ -1,3 +0,0 @@ -set(CMake_TEST_MODULE_COMPILATION "named,compile_commands,collation,partitions,internal_partitions,export_bmi,install_bmi,shared,bmionly,build_database,import_std23" CACHE STRING "") - -include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora42_common_clang.cmake")
diff --git a/.gitlab/ci/configure_fedora42_ninja_lfortran.cmake b/.gitlab/ci/configure_fedora42_ninja_lfortran.cmake deleted file mode 100644 index ae32c04..0000000 --- a/.gitlab/ci/configure_fedora42_ninja_lfortran.cmake +++ /dev/null
@@ -1 +0,0 @@ -include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora42_common_lfortran.cmake")
diff --git a/.gitlab/ci/configure_fedora42_ninja_multi.cmake b/.gitlab/ci/configure_fedora42_ninja_multi.cmake deleted file mode 100644 index b4d9a70..0000000 --- a/.gitlab/ci/configure_fedora42_ninja_multi.cmake +++ /dev/null
@@ -1,6 +0,0 @@ -if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "") - set(CMake_TEST_ISPC "ON" CACHE STRING "") -endif() -set(CMake_TEST_MODULE_COMPILATION "named,compile_commands,collation,partitions,internal_partitions,export_bmi,install_bmi,shared,bmionly,build_database" CACHE STRING "") - -include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake")
diff --git a/.gitlab/ci/configure_fedora42_ninja_multi_clang.cmake b/.gitlab/ci/configure_fedora42_ninja_multi_clang.cmake deleted file mode 100644 index a1c7fc0..0000000 --- a/.gitlab/ci/configure_fedora42_ninja_multi_clang.cmake +++ /dev/null
@@ -1,3 +0,0 @@ -set(CMake_TEST_MODULE_COMPILATION "named,compile_commands,collation,partitions,internal_partitions,export_bmi,install_bmi,shared,bmionly,build_database" CACHE STRING "") - -include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora42_common_clang.cmake")
diff --git a/.gitlab/ci/configure_fedora42_tidy.cmake b/.gitlab/ci/configure_fedora42_tidy.cmake deleted file mode 100644 index f5dbe06..0000000 --- a/.gitlab/ci/configure_fedora42_tidy.cmake +++ /dev/null
@@ -1,7 +0,0 @@ -set(CMake_RUN_CLANG_TIDY ON CACHE BOOL "") -set(CMake_USE_CLANG_TIDY_MODULE ON CACHE BOOL "") -set(CMake_CLANG_TIDY_MODULE "$ENV{CI_PROJECT_DIR}/Utilities/ClangTidyModule/build/libcmake-clang-tidy-module.so" CACHE FILEPATH "") -set(CMake_CLANG_TIDY_EXPORT_FIXES_DIR "$ENV{CI_PROJECT_DIR}/.gitlab/clang-tidy-fixes" CACHE PATH "") -set(CMake_QT_MAJOR_VERSION "5" CACHE STRING "") - -include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora42_common.cmake")
diff --git a/.gitlab/ci/configure_fedora43_asan.cmake b/.gitlab/ci/configure_fedora43_asan.cmake new file mode 100644 index 0000000..9913430 --- /dev/null +++ b/.gitlab/ci/configure_fedora43_asan.cmake
@@ -0,0 +1,5 @@ +set(CMAKE_C_FLAGS "-fsanitize=address" CACHE STRING "") +set(CMAKE_CXX_FLAGS "-fsanitize=address" CACHE STRING "") +set(CMake_QT_MAJOR_VERSION "5" CACHE STRING "") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora43_common.cmake")
diff --git a/.gitlab/ci/configure_fedora43_bullseye_coverage.cmake b/.gitlab/ci/configure_fedora43_bullseye_coverage.cmake new file mode 100644 index 0000000..5b35c57 --- /dev/null +++ b/.gitlab/ci/configure_fedora43_bullseye_coverage.cmake
@@ -0,0 +1,21 @@ +# Compile with Bullseye compiler wrappers, but do not test with them. +set(CMAKE_C_COMPILER "/opt/bullseye/bin/cc" CACHE PATH "") +set(CMAKE_CXX_COMPILER "/opt/bullseye/bin/c++" CACHE PATH "") + +# Bullseye records a COVFILE id in object files, so they cannot be cached. +set(configure_no_sccache 1) + +# Do not bootstrap for the coverage test suite. +set(CMAKE_SKIP_BOOTSTRAP_TEST TRUE CACHE BOOL "") + +# Shrink stress tests when running with Bullseye. +set(ENV{KWSYS_TEST_PROCESS_1_COUNT} 11) + +set(CMake_TEST_GUI "ON" CACHE BOOL "") +set(CMake_TEST_MODULE_COMPILATION "named,compile_commands,collation,partitions,internal_partitions,export_bmi,install_bmi,shared,bmionly,build_database,import_std23" CACHE STRING "") +set(CMake_TEST_TLS_VERIFY_URL "https://gitlab.kitware.com" CACHE STRING "") +set(CMake_TEST_TLS_VERIFY_URL_BAD "https://badtls-expired.kitware.com" CACHE STRING "") +set(CMake_TEST_TLS_VERSION "1.3" CACHE STRING "") +set(CMake_TEST_TLS_VERSION_URL_BAD "https://badtls-v1-1.kitware.com:8011" CACHE STRING "") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora43_common.cmake")
diff --git a/.gitlab/ci/configure_fedora43_clang_analyzer.cmake b/.gitlab/ci/configure_fedora43_clang_analyzer.cmake new file mode 100644 index 0000000..c18dfe6 --- /dev/null +++ b/.gitlab/ci/configure_fedora43_clang_analyzer.cmake
@@ -0,0 +1,4 @@ +set(configure_no_sccache 1) +set(CMake_QT_MAJOR_VERSION "5" CACHE STRING "") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora43_common.cmake")
diff --git a/.gitlab/ci/configure_fedora43_clang_fuzzing.cmake b/.gitlab/ci/configure_fedora43_clang_fuzzing.cmake new file mode 100644 index 0000000..48a4b7b --- /dev/null +++ b/.gitlab/ci/configure_fedora43_clang_fuzzing.cmake
@@ -0,0 +1,3 @@ +set(CMake_BUILD_FUZZING ON CACHE BOOL "") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_common.cmake")
diff --git a/.gitlab/ci/configure_fedora43_clazy.cmake b/.gitlab/ci/configure_fedora43_clazy.cmake new file mode 100644 index 0000000..1943447 --- /dev/null +++ b/.gitlab/ci/configure_fedora43_clazy.cmake
@@ -0,0 +1,5 @@ +set(configure_no_sccache 1) +set(CMake_QT_MAJOR_VERSION "5" CACHE STRING "") +set(CMAKE_USE_SYSTEM_JSONCPP ON CACHE BOOL "") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora43_common.cmake")
diff --git a/.gitlab/ci/configure_fedora42_common.cmake b/.gitlab/ci/configure_fedora43_common.cmake similarity index 100% rename from .gitlab/ci/configure_fedora42_common.cmake rename to .gitlab/ci/configure_fedora43_common.cmake
diff --git a/.gitlab/ci/configure_fedora43_common_clang.cmake b/.gitlab/ci/configure_fedora43_common_clang.cmake new file mode 100644 index 0000000..941a040 --- /dev/null +++ b/.gitlab/ci/configure_fedora43_common_clang.cmake
@@ -0,0 +1,17 @@ +set(CMAKE_Fortran_COMPILER "/usr/bin/flang-21" CACHE FILEPATH "") +set(CMAKE_Fortran_COMPILER_ID "LLVMFlang" CACHE STRING "") +set(CMAKE_Fortran_COMPILER_SUPPORTS_F90 "1" CACHE BOOL "") + +set(CMake_TEST_C_STANDARDS "90;99;11;17;23" CACHE STRING "") +set(CMake_TEST_CXX_STANDARDS "98;11;14;17;20;23;26" CACHE STRING "") + +set(CMake_TEST_FindOpenACC "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenACC_C "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenACC_CXX "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenACC_Fortran "OFF" CACHE BOOL "") # flang-new fails producing LLVM IR +set(CMake_TEST_FindOpenMP_C "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenMP_CXX "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenMP_Fortran "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenMP "ON" CACHE BOOL "") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake")
diff --git a/.gitlab/ci/configure_fedora42_common_lfortran.cmake b/.gitlab/ci/configure_fedora43_common_lfortran.cmake similarity index 100% rename from .gitlab/ci/configure_fedora42_common_lfortran.cmake rename to .gitlab/ci/configure_fedora43_common_lfortran.cmake
diff --git a/.gitlab/ci/configure_debian12_extdeps.cmake b/.gitlab/ci/configure_fedora43_extdeps.cmake similarity index 100% copy from .gitlab/ci/configure_debian12_extdeps.cmake copy to .gitlab/ci/configure_fedora43_extdeps.cmake
diff --git a/.gitlab/ci/configure_fedora43_fastbuild.cmake b/.gitlab/ci/configure_fedora43_fastbuild.cmake new file mode 100644 index 0000000..20863a2 --- /dev/null +++ b/.gitlab/ci/configure_fedora43_fastbuild.cmake
@@ -0,0 +1 @@ +include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake")
diff --git a/.gitlab/ci/configure_fedora43_gcc_gcov.cmake b/.gitlab/ci/configure_fedora43_gcc_gcov.cmake new file mode 100644 index 0000000..b2eb3ac --- /dev/null +++ b/.gitlab/ci/configure_fedora43_gcc_gcov.cmake
@@ -0,0 +1,41 @@ +set(CMake_TEST_GUI "ON" CACHE BOOL "") +set(CMake_TEST_MODULE_COMPILATION "named,compile_commands,collation,partitions,internal_partitions,export_bmi,install_bmi,shared,bmionly,build_database,import_std23" CACHE STRING "") +set(CMake_TEST_TLS_VERIFY_URL "https://gitlab.kitware.com" CACHE STRING "") +set(CMake_TEST_TLS_VERIFY_URL_BAD "https://badtls-expired.kitware.com" CACHE STRING "") +set(CMake_TEST_TLS_VERSION "1.3" CACHE STRING "") +set(CMake_TEST_TLS_VERSION_URL_BAD "https://badtls-v1-1.kitware.com:8011" CACHE STRING "") + +string(CONCAT coverage_flags + "--coverage " + "-fprofile-abs-path " + # These files are committed generated sources and contain relative path + # `#line` directives. CI coverage then cannot find the source files reliably. + # See related issue #20001. + "-fprofile-exclude-files=cmExprParser[.].*\\;cmFortranParser[.].* " + "-fdiagnostics-show-option " + "-Wall " + "-Wextra " + "-Wshadow " + "-Wpointer-arith " + "-Winvalid-pch " + "-Wcast-align " + "-Wdisabled-optimization " + "-Wwrite-strings " + "-fstack-protector-all " + "-Wconversion " + "-Wno-error=sign-conversion " + "-Wno-error=conversion ") +string(CONCAT link_flags + "--coverage ") + +set(CMAKE_C_FLAGS "${coverage_flags}" CACHE STRING "") +set(CMAKE_CXX_FLAGS "${coverage_flags} -Woverloaded-virtual -Wstrict-null-sentinel" CACHE STRING "") +# Apply `LDFLAGS`. +set(CMAKE_EXE_LINKER_FLAGS_INIT "${link_flags}" CACHE STRING "") +set(CMAKE_SHARED_LINKER_FLAGS_INIT "${link_flags}" CACHE STRING "") +set(CMAKE_MODULE_LINKER_FLAGS_INIT "${link_flags}" CACHE STRING "") + +# Do not bootstrap for the coverage test suite. +set(CMAKE_SKIP_BOOTSTRAP_TEST TRUE CACHE BOOL "") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora43_common.cmake")
diff --git a/.gitlab/ci/configure_fedora42_hip_radeon.cmake b/.gitlab/ci/configure_fedora43_hip_radeon.cmake similarity index 100% rename from .gitlab/ci/configure_fedora42_hip_radeon.cmake rename to .gitlab/ci/configure_fedora43_hip_radeon.cmake
diff --git a/.gitlab/ci/configure_fedora43_makefiles.cmake b/.gitlab/ci/configure_fedora43_makefiles.cmake new file mode 100644 index 0000000..3ddf236 --- /dev/null +++ b/.gitlab/ci/configure_fedora43_makefiles.cmake
@@ -0,0 +1,119 @@ +set(CMake_TEST_C_STANDARDS "90;99;11;17;23" CACHE STRING "") +set(CMake_TEST_CXX_STANDARDS "98;11;14;17;20;23;26" CACHE STRING "") + +set(CMake_TEST_CTestUpdate_BZR "ON" CACHE BOOL "") +set(CMake_TEST_CTestUpdate_GIT "ON" CACHE BOOL "") +set(CMake_TEST_CTestUpdate_HG "ON" CACHE BOOL "") +set(CMake_TEST_CTestUpdate_SVN "ON" CACHE BOOL "") +if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "") + set(CMake_TEST_BIN2C_LARGE_FILE "ON" CACHE BOOL "") + set(CMake_TEST_CTestUpdate_P4 "ON" CACHE BOOL "") +endif() + +set(CMake_TEST_ASM_NASM "ON" CACHE BOOL "") +set(CMake_TEST_FindALSA "ON" CACHE BOOL "") +set(CMake_TEST_FindASPELL "ON" CACHE BOOL "") +set(CMake_TEST_FindBacktrace "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 "") +set(CMake_TEST_FindFontconfig "ON" CACHE BOOL "") +set(CMake_TEST_FindFreetype "ON" CACHE BOOL "") +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 "") +set(CMake_TEST_FindGTK2 "ON" CACHE BOOL "") +set(CMake_TEST_FindHDF5 "ON" CACHE BOOL "") +set(CMake_TEST_FindHDF5_MPICH_C_COMPILER "/usr/lib64/mpich/bin/h5pcc" CACHE FILEPATH "") +# set(CMake_TEST_FindHDF5_MPICH_CXX_COMPILER "/usr/lib64/mpich/bin/h5pc++" CACHE FILEPATH "") # h5pc++ does not exist +set(CMake_TEST_FindHDF5_MPICH_ENVMOD "PATH=path_list_prepend:/usr/lib64/mpich/bin;LD_LIBRARY_PATH=path_list_prepend:/usr/lib64/mpich/lib" CACHE STRING "") +set(CMake_TEST_FindHDF5_MPICH_Fortran_COMPILER "/usr/lib64/mpich/bin/h5pfc" CACHE FILEPATH "") +set(CMake_TEST_FindHDF5_OpenMPI_C_COMPILER "/usr/lib64/openmpi/bin/h5pcc" CACHE FILEPATH "") +set(CMake_TEST_FindHDF5_OpenMPI_ENVMOD "PATH=path_list_prepend:/usr/lib64/openmpi/bin;LD_LIBRARY_PATH=path_list_prepend:/usr/lib64/openmpi/lib" CACHE STRING "") +# set(CMake_TEST_FindHDF5_OpenMPI_CXX_COMPILER "/usr/lib64/openmpi/bin/h5pc++" CACHE FILEPATH "") # h5pc++ does not exist +set(CMake_TEST_FindHDF5_OpenMPI_Fortran_COMPILER "/usr/lib64/openmpi/bin/h5pfc" CACHE FILEPATH "") +set(CMake_TEST_FindHDF5_Serial_C_COMPILER "/usr/bin/h5cc" CACHE FILEPATH "") +set(CMake_TEST_FindHDF5_Serial_CXX_COMPILER "/usr/bin/h5c++" CACHE FILEPATH "") +set(CMake_TEST_FindHDF5_Serial_Fortran_COMPILER "/usr/bin/h5fc" CACHE FILEPATH "") +set(CMake_TEST_FindIconv "ON" CACHE BOOL "") +set(CMake_TEST_FindICU "ON" CACHE BOOL "") +set(CMake_TEST_FindImageMagick "ON" CACHE BOOL "") +set(CMake_TEST_FindIntl "ON" CACHE BOOL "") +set(CMake_TEST_FindJasper "ON" CACHE BOOL "") +set(CMake_TEST_FindJNI "ON" CACHE BOOL "") +set(CMake_TEST_FindJPEG "ON" CACHE BOOL "") +set(CMake_TEST_FindJsonCpp "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 "") +set(CMake_TEST_FindLibUV "ON" CACHE BOOL "") +set(CMake_TEST_FindLibXml2 "ON" CACHE BOOL "") +set(CMake_TEST_FindLibXslt "ON" CACHE BOOL "") +set(CMake_TEST_FindMPI_C "ON" CACHE BOOL "") +set(CMake_TEST_FindMPI_CXX "ON" CACHE BOOL "") +set(CMake_TEST_FindMPI_Fortran "ON" CACHE BOOL "") +set(CMake_TEST_FindMPI_ENVMOD "PATH=path_list_prepend:/usr/lib64/mpich/bin;LD_LIBRARY_PATH=path_list_prepend:/usr/lib64/mpich/lib;FI_PROVIDER=set:tcp" CACHE STRING "") +set(CMake_TEST_FindMPI "ON" CACHE BOOL "") +set(CMake_TEST_FindODBC "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenACC "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenACC_C "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenACC_CXX "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenACC_Fortran "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenAL "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenGL "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenMP_C "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenMP_CXX "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenMP_Fortran "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenMP "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenSP "ON" CACHE BOOL "") +set(CMake_TEST_FindOpenSSL "ON" CACHE BOOL "") +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_FindPython3 "ON" CACHE BOOL "") +set(CMake_TEST_FindPython3_NumPy "ON" CACHE BOOL "") +set(CMake_TEST_FindPython2_PyPy "ON" CACHE BOOL "") +set(CMake_TEST_FindPython3_PyPy "ON" CACHE BOOL "") +set(CMake_TEST_FindRuby "ON" CACHE BOOL "") +set(CMake_TEST_FindRuby_RBENV "ON" CACHE BOOL "") +set(CMake_TEST_FindRuby_RVM "ON" CACHE BOOL "") +set(CMake_TEST_FindSDL "ON" CACHE BOOL "") +set(CMake_TEST_FindSQLite3 "ON" CACHE BOOL "") +set(CMake_TEST_FindTIFF "ON" CACHE BOOL "") +set(CMake_TEST_FindwxWidgets "ON" CACHE BOOL "") +set(CMake_TEST_FindX11 "ON" CACHE BOOL "") +set(CMake_TEST_FindXalanC "ON" CACHE BOOL "") +set(CMake_TEST_FindXercesC "ON" CACHE BOOL "") + +set(CMake_TEST_ELF_LARGE "ON" CACHE BOOL "") +set(CMake_TEST_Fortran_SUBMODULES "ON" CACHE BOOL "") +set(CMake_TEST_IPO_WORKS_C "ON" CACHE BOOL "") +set(CMake_TEST_IPO_WORKS_CXX "ON" CACHE BOOL "") +set(CMake_TEST_IPO_WORKS_Fortran "ON" CACHE BOOL "") +if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "") + set(CMake_TEST_ISPC "ON" CACHE STRING "") +endif() +set(CMake_TEST_LOCALE_CHARSET "ISO-8859-1" CACHE STRING "") +set(CMake_TEST_Qt5 "ON" CACHE BOOL "") +set(CMake_TEST_TLS_VERIFY_URL "https://gitlab.kitware.com" CACHE STRING "") +set(CMake_TEST_TLS_VERIFY_URL_BAD "https://badtls-expired.kitware.com" CACHE STRING "") +set(CMake_TEST_TLS_VERSION "1.3" CACHE STRING "") +set(CMake_TEST_TLS_VERSION_URL_BAD "https://badtls-v1-1.kitware.com:8011" CACHE STRING "") +set(CMake_TEST_UseSWIG "ON" CACHE BOOL "") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake")
diff --git a/.gitlab/ci/configure_fedora43_makefiles_clang.cmake b/.gitlab/ci/configure_fedora43_makefiles_clang.cmake new file mode 100644 index 0000000..e3f1ef9 --- /dev/null +++ b/.gitlab/ci/configure_fedora43_makefiles_clang.cmake
@@ -0,0 +1,5 @@ +if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "") + set(CMAKE_TESTS_CDASH_SERVER "https://open.cdash.org" CACHE STRING "") +endif() + +include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora43_common_clang.cmake")
diff --git a/.gitlab/ci/configure_fedora43_makefiles_lfortran.cmake b/.gitlab/ci/configure_fedora43_makefiles_lfortran.cmake new file mode 100644 index 0000000..918c2c3 --- /dev/null +++ b/.gitlab/ci/configure_fedora43_makefiles_lfortran.cmake
@@ -0,0 +1 @@ +include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora43_common_lfortran.cmake")
diff --git a/.gitlab/ci/configure_fedora43_makefiles_symlinked.cmake b/.gitlab/ci/configure_fedora43_makefiles_symlinked.cmake new file mode 100644 index 0000000..c5ef84c --- /dev/null +++ b/.gitlab/ci/configure_fedora43_makefiles_symlinked.cmake
@@ -0,0 +1,5 @@ +set(CMake_QT_MAJOR_VERSION "6" CACHE STRING "") +set(CMake_TEST_GUI "ON" CACHE BOOL "") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_symlinked_common.cmake") +include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora43_common.cmake")
diff --git a/.gitlab/ci/configure_fedora43_ninja.cmake b/.gitlab/ci/configure_fedora43_ninja.cmake new file mode 100644 index 0000000..0371ebc --- /dev/null +++ b/.gitlab/ci/configure_fedora43_ninja.cmake
@@ -0,0 +1,24 @@ +set(CMake_TEST_GUI "ON" CACHE BOOL "") +if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "") + set(CMake_TEST_CPACK_APPIMAGE "ON" CACHE STRING "") + set(CMake_TEST_CPACK_APPIMAGE_RUNTIME_FILE "$ENV{CI_PROJECT_DIR}/.gitlab/appimagetool/lib/appimagetool/runtime" CACHE FILEPATH "") + set(CMake_TEST_ISPC "ON" CACHE STRING "") +endif() +set(CMake_TEST_LOCALE_CHARSET "UTF-8" CACHE STRING "") +set(CMake_TEST_MODULE_COMPILATION "named,compile_commands,collation,partitions,internal_partitions,export_bmi,install_bmi,shared,bmionly,build_database,import_std23" CACHE STRING "") +set(CMake_TEST_Rust "ON" CACHE STRING "") +set(CMake_TEST_TLS_VERIFY_URL "https://gitlab.kitware.com" CACHE STRING "") +set(CMake_TEST_TLS_VERIFY_URL_BAD "https://badtls-expired.kitware.com" CACHE STRING "") +set(CMake_TEST_TLS_VERSION "1.3" CACHE STRING "") +set(CMake_TEST_TLS_VERSION_URL_BAD "https://badtls-v1-1.kitware.com:8011" CACHE STRING "") + +# "Release" flags without "-DNDEBUG" so we get assertions. +set(CMAKE_C_FLAGS_RELEASE "-O3" CACHE STRING "") +set(CMAKE_CXX_FLAGS_RELEASE "-O3" CACHE STRING "") + +# Cover compilation with C++11 only and not higher standards. +set(CMAKE_CXX_STANDARD "11" CACHE STRING "") +# Qt 6 requires C++17, so use Qt 5. +set(CMake_QT_MAJOR_VERSION "5" CACHE STRING "") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora43_common.cmake")
diff --git a/.gitlab/ci/configure_fedora43_ninja_clang.cmake b/.gitlab/ci/configure_fedora43_ninja_clang.cmake new file mode 100644 index 0000000..6cf0f85 --- /dev/null +++ b/.gitlab/ci/configure_fedora43_ninja_clang.cmake
@@ -0,0 +1,3 @@ +set(CMake_TEST_MODULE_COMPILATION "named,compile_commands,collation,partitions,internal_partitions,export_bmi,install_bmi,shared,bmionly,build_database,import_std23" CACHE STRING "") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora43_common_clang.cmake")
diff --git a/.gitlab/ci/configure_fedora43_ninja_instrumentation.cmake b/.gitlab/ci/configure_fedora43_ninja_instrumentation.cmake new file mode 100644 index 0000000..daf845f --- /dev/null +++ b/.gitlab/ci/configure_fedora43_ninja_instrumentation.cmake
@@ -0,0 +1,3 @@ +set(CMake_ENABLE_INSTRUMENTATION "ON" CACHE BOOL "") +set(CMake_TEST_GUI "OFF" CACHE BOOL "") +include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora43_ninja.cmake")
diff --git a/.gitlab/ci/configure_fedora43_ninja_lfortran.cmake b/.gitlab/ci/configure_fedora43_ninja_lfortran.cmake new file mode 100644 index 0000000..918c2c3 --- /dev/null +++ b/.gitlab/ci/configure_fedora43_ninja_lfortran.cmake
@@ -0,0 +1 @@ +include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora43_common_lfortran.cmake")
diff --git a/.gitlab/ci/configure_fedora43_ninja_multi.cmake b/.gitlab/ci/configure_fedora43_ninja_multi.cmake new file mode 100644 index 0000000..a99b5d1 --- /dev/null +++ b/.gitlab/ci/configure_fedora43_ninja_multi.cmake
@@ -0,0 +1,7 @@ +if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "") + set(CMake_TEST_ISPC "ON" CACHE STRING "") +endif() +set(CMake_TEST_MODULE_COMPILATION "named,compile_commands,collation,partitions,internal_partitions,export_bmi,install_bmi,shared,bmionly,build_database,import_std23" CACHE STRING "") +set(CMake_TEST_Rust "ON" CACHE STRING "") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake")
diff --git a/.gitlab/ci/configure_fedora43_ninja_multi_clang.cmake b/.gitlab/ci/configure_fedora43_ninja_multi_clang.cmake new file mode 100644 index 0000000..522d012 --- /dev/null +++ b/.gitlab/ci/configure_fedora43_ninja_multi_clang.cmake
@@ -0,0 +1,3 @@ +set(CMake_TEST_MODULE_COMPILATION "named,compile_commands,collation,partitions,internal_partitions,export_bmi,install_bmi,shared,bmionly,build_database" CACHE STRING "") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora43_common_clang.cmake")
diff --git a/.gitlab/ci/configure_fedora43_ninja_valgrind.cmake b/.gitlab/ci/configure_fedora43_ninja_valgrind.cmake new file mode 100644 index 0000000..d156e20 --- /dev/null +++ b/.gitlab/ci/configure_fedora43_ninja_valgrind.cmake
@@ -0,0 +1,6 @@ +set(CMake_TEST_Qt5 ON CACHE BOOL "") +set(CMake_TEST_Qt6 ON CACHE BOOL "") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora43_valgrind.cmake") +include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora43_ninja.cmake") +include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake")
diff --git a/.gitlab/ci/configure_fedora42_sphinx.cmake b/.gitlab/ci/configure_fedora43_sphinx.cmake similarity index 100% rename from .gitlab/ci/configure_fedora42_sphinx.cmake rename to .gitlab/ci/configure_fedora43_sphinx.cmake
diff --git a/.gitlab/ci/configure_fedora42_sphinx_package.cmake b/.gitlab/ci/configure_fedora43_sphinx_package.cmake similarity index 100% rename from .gitlab/ci/configure_fedora42_sphinx_package.cmake rename to .gitlab/ci/configure_fedora43_sphinx_package.cmake
diff --git a/.gitlab/ci/configure_fedora43_tidy.cmake b/.gitlab/ci/configure_fedora43_tidy.cmake new file mode 100644 index 0000000..5b0bd62 --- /dev/null +++ b/.gitlab/ci/configure_fedora43_tidy.cmake
@@ -0,0 +1,7 @@ +set(CMake_RUN_CLANG_TIDY ON CACHE BOOL "") +set(CMake_USE_CLANG_TIDY_MODULE ON CACHE BOOL "") +set(CMake_CLANG_TIDY_MODULE "$ENV{CI_PROJECT_DIR}/Utilities/ClangTidyModule/build/libcmake-clang-tidy-module.so" CACHE FILEPATH "") +set(CMake_CLANG_TIDY_EXPORT_FIXES_DIR "$ENV{CI_PROJECT_DIR}/.gitlab/clang-tidy-fixes" CACHE PATH "") +set(CMake_QT_MAJOR_VERSION "5" CACHE STRING "") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora43_common.cmake")
diff --git a/.gitlab/ci/configure_fedora43_valgrind.cmake b/.gitlab/ci/configure_fedora43_valgrind.cmake new file mode 100644 index 0000000..0175395 --- /dev/null +++ b/.gitlab/ci/configure_fedora43_valgrind.cmake
@@ -0,0 +1,2 @@ +# Disable bootstrap testing for Valgrind testing. +set(CMAKE_SKIP_BOOTSTRAP_TEST OFF CACHE BOOL "")
diff --git a/.gitlab/ci/configure_linux_gcc_cxx_modules_reloc_ninja.cmake b/.gitlab/ci/configure_linux_gcc_cxx_modules_reloc_ninja.cmake new file mode 100644 index 0000000..eb728ed --- /dev/null +++ b/.gitlab/ci/configure_linux_gcc_cxx_modules_reloc_ninja.cmake
@@ -0,0 +1,13 @@ +# "Misplace" the `libstdc++.modules.json` file so that +# `CMAKE_CXX_STDLIB_MODULES_JSON` is needed to use `import std`. +set(gcc_prefix "/opt/gcc-importstd") +set(CMake_TEST_CXX_STDLIB_MODULES_JSON + "${gcc_prefix}/lib64.reloc/libstdc++.modules.json" + CACHE FILEPATH "") +file(MAKE_DIRECTORY + "${gcc_prefix}/lib64.reloc") +file(RENAME + "${gcc_prefix}/lib64/libstdc++.modules.json" + "${CMake_TEST_CXX_STDLIB_MODULES_JSON}") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake")
diff --git a/.gitlab/ci/configure_macos_arm64_curl.cmake b/.gitlab/ci/configure_macos_arm64_curl.cmake deleted file mode 100644 index 73263cb..0000000 --- a/.gitlab/ci/configure_macos_arm64_curl.cmake +++ /dev/null
@@ -1,10 +0,0 @@ -# Build with our vendored curl instead of the default system version. -set(CMAKE_USE_SYSTEM_CURL "OFF" CACHE BOOL "") - -set(CMake_TEST_TLS_VERIFY_URL "https://gitlab.kitware.com" CACHE STRING "") -set(CMake_TEST_TLS_VERIFY_URL_BAD "https://badtls-expired.kitware.com" CACHE STRING "") -set(CMake_TEST_TLS_VERSION "1.2" CACHE STRING "") -set(CMake_TEST_TLS_VERSION_URL_BAD "https://badtls-v1-1.kitware.com:8011" CACHE STRING "") - -include("${CMAKE_CURRENT_LIST_DIR}/configure_macos_common.cmake") -include("${CMAKE_CURRENT_LIST_DIR}/configure_common.cmake")
diff --git a/.gitlab/ci/configure_macos_arm64_fastbuild.cmake b/.gitlab/ci/configure_macos_arm64_fastbuild.cmake new file mode 100644 index 0000000..1b976d2 --- /dev/null +++ b/.gitlab/ci/configure_macos_arm64_fastbuild.cmake
@@ -0,0 +1,2 @@ +include("${CMAKE_CURRENT_LIST_DIR}/configure_macos_common.cmake") +include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake")
diff --git a/.gitlab/ci/configure_macos_arm64_ninja.cmake b/.gitlab/ci/configure_macos_arm64_ninja.cmake index eb319c9..c1924fe 100644 --- a/.gitlab/ci/configure_macos_arm64_ninja.cmake +++ b/.gitlab/ci/configure_macos_arm64_ninja.cmake
@@ -1,11 +1,12 @@ set(CMake_TEST_C_STANDARDS "90;99;11;17;23" CACHE STRING "") -set(CMake_TEST_CXX_STANDARDS "98;11;14;17;20;23" CACHE STRING "") +set(CMake_TEST_CXX_STANDARDS "98;11;14;17;20;23;26" CACHE STRING "") set(CMake_TEST_FindOpenAL "ON" CACHE BOOL "") set(CMake_TEST_FindOpenMP "ON" CACHE BOOL "") set(CMake_TEST_FindOpenMP_C "ON" CACHE BOOL "") set(CMake_TEST_FindOpenMP_CXX "ON" CACHE BOOL "") set(CMake_TEST_GUI "ON" CACHE BOOL "") +set(CMake_TEST_LOCALE_CHARSET "UTF-8" CACHE STRING "") set(CMake_TEST_TLS_VERIFY_URL "https://gitlab.kitware.com" CACHE STRING "") set(CMake_TEST_TLS_VERIFY_URL_BAD "https://badtls-expired.kitware.com" CACHE STRING "") set(CMake_TEST_TLS_VERSION "1.2" CACHE STRING "")
diff --git a/.gitlab/ci/configure_macos_package.cmake b/.gitlab/ci/configure_macos_package.cmake index cdc8fd2..9a86aeb 100644 --- a/.gitlab/ci/configure_macos_package.cmake +++ b/.gitlab/ci/configure_macos_package.cmake
@@ -1,5 +1,6 @@ set(CPACK_SYSTEM_NAME "macos-universal" CACHE STRING "") set(CMAKE_OSX_DEPLOYMENT_TARGET "10.13" CACHE STRING "") +set(CMake_GUI_OSX_DEPLOYMENT_TARGET "12" CACHE STRING "") set(CMAKE_C_STANDARD "11" CACHE STRING "") set(CMAKE_CXX_STANDARD "17" CACHE STRING "")
diff --git a/.gitlab/ci/configure_macos_package_common.cmake b/.gitlab/ci/configure_macos_package_common.cmake index 2ac7ad6..05206bd 100644 --- a/.gitlab/ci/configure_macos_package_common.cmake +++ b/.gitlab/ci/configure_macos_package_common.cmake
@@ -11,7 +11,6 @@ set(BUILD_QtDialog "TRUE" CACHE BOOL "") set(CMake_GUI_DISTRIBUTE_WITH_Qt_LGPL "3" CACHE STRING "") set(CMake_INSTALL_DEPENDENCIES "ON" CACHE BOOL "") -set(CMAKE_SKIP_RPATH "TRUE" CACHE BOOL "") set(CMake_TEST_BOOTSTRAP OFF CACHE BOOL "") set(CMake_TEST_NO_FindPackageModeMakefileTest "TRUE" CACHE BOOL "")
diff --git a/.gitlab/ci/configure_macos_x86_64_ninja.cmake b/.gitlab/ci/configure_macos_x86_64_ninja.cmake index 9de043e..1af144f 100644 --- a/.gitlab/ci/configure_macos_x86_64_ninja.cmake +++ b/.gitlab/ci/configure_macos_x86_64_ninja.cmake
@@ -1,5 +1,5 @@ set(CMake_TEST_C_STANDARDS "90;99;11;17;23" CACHE STRING "") -set(CMake_TEST_CXX_STANDARDS "98;11;14;17;20;23" CACHE STRING "") +set(CMake_TEST_CXX_STANDARDS "98;11;14;17;20;23;26" CACHE STRING "") set(CMake_TEST_FindOpenAL "ON" CACHE BOOL "") set(CMake_TEST_FindOpenMP "ON" CACHE BOOL "") @@ -9,6 +9,7 @@ if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "") set(CMake_TEST_ISPC "ON" CACHE STRING "") endif() +set(CMake_TEST_LOCALE_CHARSET "UTF-8" CACHE STRING "") set(CMake_TEST_TLS_VERIFY_URL "https://gitlab.kitware.com" CACHE STRING "") set(CMake_TEST_TLS_VERIFY_URL_BAD "https://badtls-expired.kitware.com" CACHE STRING "") set(CMake_TEST_TLS_VERSION "1.2" CACHE STRING "")
diff --git a/.gitlab/ci/configure_windows_arm64_package.cmake b/.gitlab/ci/configure_windows_arm64_package.cmake index f3ce853..de88acd 100644 --- a/.gitlab/ci/configure_windows_arm64_package.cmake +++ b/.gitlab/ci/configure_windows_arm64_package.cmake
@@ -4,7 +4,7 @@ # Tell WiX to package for this architecture. set(CPACK_WIX_ARCHITECTURE "arm64" CACHE STRING "") -# Use APIs from at most Windows 7 +# Use APIs from at most Windows 10 set(CMAKE_C_FLAGS "-D_WIN32_WINNT=0x0A00 -DNTDDI_VERSION=0x0A000008" CACHE STRING "") set(CMAKE_CXX_FLAGS "-GR -EHsc -D_WIN32_WINNT=0x0A00 -DNTDDI_VERSION=0x0A000008" CACHE STRING "") set(CMAKE_EXE_LINKER_FLAGS "-machine:arm64 -subsystem:console,6.02" CACHE STRING "")
diff --git a/.gitlab/ci/configure_windows_arm64_vs2022.cmake b/.gitlab/ci/configure_windows_arm64_vs2022.cmake index 290d380..51ee514 100644 --- a/.gitlab/ci/configure_windows_arm64_vs2022.cmake +++ b/.gitlab/ci/configure_windows_arm64_vs2022.cmake
@@ -1,4 +1,4 @@ -set(CMake_TEST_MODULE_COMPILATION "named,partitions,internal_partitions" CACHE STRING "") +set(CMake_TEST_MODULE_COMPILATION "named,partitions,internal_partitions,shared" CACHE STRING "") include("${CMAKE_CURRENT_LIST_DIR}/configure_windows_msvc_cxx_modules_common.cmake") include("${CMAKE_CURRENT_LIST_DIR}/configure_windows_vs_common.cmake")
diff --git a/.gitlab/ci/configure_windows_arm64_vs2026.cmake b/.gitlab/ci/configure_windows_arm64_vs2026.cmake new file mode 100644 index 0000000..51ee514 --- /dev/null +++ b/.gitlab/ci/configure_windows_arm64_vs2026.cmake
@@ -0,0 +1,4 @@ +set(CMake_TEST_MODULE_COMPILATION "named,partitions,internal_partitions,shared" CACHE STRING "") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_windows_msvc_cxx_modules_common.cmake") +include("${CMAKE_CURRENT_LIST_DIR}/configure_windows_vs_common.cmake")
diff --git a/.gitlab/ci/configure_windows_arm64_vs2022_ninja.cmake b/.gitlab/ci/configure_windows_arm64_vs2026_ninja.cmake similarity index 100% rename from .gitlab/ci/configure_windows_arm64_vs2022_ninja.cmake rename to .gitlab/ci/configure_windows_arm64_vs2026_ninja.cmake
diff --git a/.gitlab/ci/configure_windows_common.cmake b/.gitlab/ci/configure_windows_common.cmake index 7467cfd..1246885 100644 --- a/.gitlab/ci/configure_windows_common.cmake +++ b/.gitlab/ci/configure_windows_common.cmake
@@ -2,6 +2,7 @@ set(BUILD_CursesDialog ON CACHE BOOL "") set(CMAKE_PREFIX_PATH "$ENV{CI_PROJECT_DIR}/.gitlab/qt" CACHE STRING "") set(CMake_TEST_Java OFF CACHE BOOL "") +set(CMake_TEST_LOCALE_CHARSET "UTF-8" CACHE STRING "") set(Python_FIND_REGISTRY NEVER CACHE STRING "") include("${CMAKE_CURRENT_LIST_DIR}/configure_common.cmake")
diff --git a/.gitlab/ci/configure_windows_i386_package.cmake b/.gitlab/ci/configure_windows_i386_package.cmake index c80ebcc..650a898 100644 --- a/.gitlab/ci/configure_windows_i386_package.cmake +++ b/.gitlab/ci/configure_windows_i386_package.cmake
@@ -4,10 +4,12 @@ # Tell WiX to package for this architecture. set(CPACK_WIX_ARCHITECTURE "x86" CACHE STRING "") -# Use APIs from at most Windows 7 -set(CMAKE_C_FLAGS "-D_WIN32_WINNT=0x601 -DNTDDI_VERSION=0x06010000" CACHE STRING "") -set(CMAKE_CXX_FLAGS "-GR -EHsc -D_WIN32_WINNT=0x601 -DNTDDI_VERSION=0x06010000" CACHE STRING "") -set(CMAKE_EXE_LINKER_FLAGS "-machine:x86 -subsystem:console,6.01" CACHE STRING "") +# Use APIs from at most Windows 10 +set(CMAKE_C_FLAGS "-D_WIN32_WINNT=0x0A00 -DNTDDI_VERSION=0x0A000000" CACHE STRING "") +set(CMAKE_CXX_FLAGS "-GR -EHsc -D_WIN32_WINNT=0x0A00 -DNTDDI_VERSION=0x0A000000" CACHE STRING "") +set(CMAKE_EXE_LINKER_FLAGS "-machine:x86 -subsystem:console,6.02" CACHE STRING "") -include("${CMAKE_CURRENT_LIST_DIR}/configure_windows_package_common_x86.cmake") +set(qt "$ENV{CI_PROJECT_DIR}/.gitlab/qt") +set(CMAKE_PREFIX_PATH "${qt}" CACHE STRING "") + include("${CMAKE_CURRENT_LIST_DIR}/configure_windows_package_common.cmake")
diff --git a/.gitlab/ci/configure_windows_msvc_v71_nmake.cmake b/.gitlab/ci/configure_windows_msvc_v71_nmake.cmake index 166690a..78587a9 100644 --- a/.gitlab/ci/configure_windows_msvc_v71_nmake.cmake +++ b/.gitlab/ci/configure_windows_msvc_v71_nmake.cmake
@@ -1 +1,3 @@ +set(CMake_TEST_PrecompileHeaders_TIMEOUT 1000 CACHE STRING "") + include("${CMAKE_CURRENT_LIST_DIR}/configure_windows_msvc_common.cmake")
diff --git a/.gitlab/ci/configure_windows_package_common_x86.cmake b/.gitlab/ci/configure_windows_package_common_x86.cmake deleted file mode 100644 index a8b5928..0000000 --- a/.gitlab/ci/configure_windows_package_common_x86.cmake +++ /dev/null
@@ -1,13 +0,0 @@ -set(qt "$ENV{CI_PROJECT_DIR}/.gitlab/qt") -set(CMake_QT_STATIC_QWindowsIntegrationPlugin_LIBRARIES - ${qt}/plugins/platforms/qwindows.lib - ${qt}/plugins/styles/qwindowsvistastyle.lib - ${qt}/lib/Qt5EventDispatcherSupport.lib - ${qt}/lib/Qt5FontDatabaseSupport.lib - ${qt}/lib/Qt5ThemeSupport.lib - ${qt}/lib/qtfreetype.lib - ${qt}/lib/qtlibpng.lib - imm32.lib - wtsapi32.lib - CACHE STRING "") -set(CMAKE_PREFIX_PATH "${qt}" CACHE STRING "")
diff --git a/.gitlab/ci/configure_windows_vs2019_x64_ninja.cmake b/.gitlab/ci/configure_windows_vs2019_x64_ninja.cmake deleted file mode 100644 index c078f90..0000000 --- a/.gitlab/ci/configure_windows_vs2019_x64_ninja.cmake +++ /dev/null
@@ -1 +0,0 @@ -include("${CMAKE_CURRENT_LIST_DIR}/configure_windows_vs_common_ninja.cmake")
diff --git a/.gitlab/ci/configure_windows_vs2022_x64_i18n.cmake b/.gitlab/ci/configure_windows_vs2022_x64_i18n.cmake deleted file mode 100644 index 3932f8a..0000000 --- a/.gitlab/ci/configure_windows_vs2022_x64_i18n.cmake +++ /dev/null
@@ -1 +0,0 @@ -include("${CMAKE_CURRENT_LIST_DIR}/configure_windows_vs2022_x64.cmake")
diff --git a/.gitlab/ci/configure_windows_vs2022_x64_ninja.cmake b/.gitlab/ci/configure_windows_vs2022_x64_ninja.cmake deleted file mode 100644 index 3fb894c..0000000 --- a/.gitlab/ci/configure_windows_vs2022_x64_ninja.cmake +++ /dev/null
@@ -1,23 +0,0 @@ -set(CMake_TEST_C_STANDARDS "90;99;11;17" CACHE STRING "") -set(CMake_TEST_CXX_STANDARDS "98;11;14;17;20;23" CACHE STRING "") - -if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "") - set(CMake_TEST_CPACK_INNOSETUP "ON" CACHE STRING "") - set(CMake_TEST_CPACK_NUGET "ON" CACHE STRING "") - set(CMake_TEST_IAR_TOOLCHAINS "$ENV{CI_PROJECT_DIR}/.gitlab/iar" CACHE PATH "") - set(CMake_TEST_ISPC "ON" CACHE STRING "") - set(CMake_TEST_Swift "ON" CACHE STRING "") -endif() - -set(CMake_TEST_TLS_VERIFY_URL "https://gitlab.kitware.com" CACHE STRING "") -set(CMake_TEST_TLS_VERIFY_URL_BAD "https://badtls-expired.kitware.com" CACHE STRING "") -set(CMake_TEST_TLS_VERSION "1.2" CACHE STRING "") -set(CMake_TEST_TLS_VERSION_URL_BAD "https://badtls-v1-1.kitware.com:8011" CACHE STRING "") - -# Release flags without -DNDEBUG so we get assertions. -set(CMAKE_C_FLAGS_RELEASE "-O2 -Ob2" CACHE STRING "") -set(CMAKE_CXX_FLAGS_RELEASE "-O2 -Ob2" CACHE STRING "") - -include("${CMAKE_CURRENT_LIST_DIR}/configure_windows_msvc_cxx_modules_common.cmake") -include("${CMAKE_CURRENT_LIST_DIR}/configure_windows_wix_common.cmake") -include("${CMAKE_CURRENT_LIST_DIR}/configure_windows_vs_common_ninja.cmake")
diff --git a/.gitlab/ci/configure_windows_vs2026_x64.cmake b/.gitlab/ci/configure_windows_vs2026_x64.cmake new file mode 100644 index 0000000..89cfdda --- /dev/null +++ b/.gitlab/ci/configure_windows_vs2026_x64.cmake
@@ -0,0 +1,8 @@ +if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "") + set(CMake_TEST_ANDROID_VS18 ON CACHE BOOL "") +endif() + +set(CMake_TEST_MODULE_COMPILATION "named,partitions,internal_partitions,shared" CACHE STRING "") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_windows_msvc_cxx_modules_common.cmake") +include("${CMAKE_CURRENT_LIST_DIR}/configure_windows_vs_common.cmake")
diff --git a/.gitlab/ci/configure_windows_vs2022_x64_jom.cmake b/.gitlab/ci/configure_windows_vs2026_x64_fastbuild.cmake similarity index 100% copy from .gitlab/ci/configure_windows_vs2022_x64_jom.cmake copy to .gitlab/ci/configure_windows_vs2026_x64_fastbuild.cmake
diff --git a/.gitlab/ci/configure_windows_vs2026_x64_i18n.cmake b/.gitlab/ci/configure_windows_vs2026_x64_i18n.cmake new file mode 100644 index 0000000..958351d --- /dev/null +++ b/.gitlab/ci/configure_windows_vs2026_x64_i18n.cmake
@@ -0,0 +1 @@ +include("${CMAKE_CURRENT_LIST_DIR}/configure_windows_vs2026_x64.cmake")
diff --git a/.gitlab/ci/configure_windows_vs2022_x64_jom.cmake b/.gitlab/ci/configure_windows_vs2026_x64_jom.cmake similarity index 100% rename from .gitlab/ci/configure_windows_vs2022_x64_jom.cmake rename to .gitlab/ci/configure_windows_vs2026_x64_jom.cmake
diff --git a/.gitlab/ci/configure_windows_vs2026_x64_ninja.cmake b/.gitlab/ci/configure_windows_vs2026_x64_ninja.cmake new file mode 100644 index 0000000..ad0af0b --- /dev/null +++ b/.gitlab/ci/configure_windows_vs2026_x64_ninja.cmake
@@ -0,0 +1,24 @@ +set(CMake_TEST_C_STANDARDS "90;99;11;17;23" CACHE STRING "") +set(CMake_TEST_CXX_STANDARDS "98;11;14;17;20;23" CACHE STRING "") + +if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "") + set(CMake_TEST_BIN2C_LARGE_FILE "ON" CACHE BOOL "") + set(CMake_TEST_CPACK_INNOSETUP "ON" CACHE STRING "") + set(CMake_TEST_CPACK_NUGET "ON" CACHE STRING "") + set(CMake_TEST_IAR_TOOLCHAINS "$ENV{CI_PROJECT_DIR}/.gitlab/iar" CACHE PATH "") + set(CMake_TEST_ISPC "ON" CACHE STRING "") + set(CMake_TEST_Swift "ON" CACHE STRING "") +endif() + +set(CMake_TEST_TLS_VERIFY_URL "https://gitlab.kitware.com" CACHE STRING "") +set(CMake_TEST_TLS_VERIFY_URL_BAD "https://badtls-expired.kitware.com" CACHE STRING "") +set(CMake_TEST_TLS_VERSION "1.2" CACHE STRING "") +set(CMake_TEST_TLS_VERSION_URL_BAD "https://badtls-v1-1.kitware.com:8011" CACHE STRING "") + +# Release flags without -DNDEBUG so we get assertions. +set(CMAKE_C_FLAGS_RELEASE "-O2 -Ob2" CACHE STRING "") +set(CMAKE_CXX_FLAGS_RELEASE "-O2 -Ob2" CACHE STRING "") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_windows_msvc_cxx_modules_common.cmake") +include("${CMAKE_CURRENT_LIST_DIR}/configure_windows_wix_common.cmake") +include("${CMAKE_CURRENT_LIST_DIR}/configure_windows_vs_common_ninja.cmake")
diff --git a/.gitlab/ci/configure_windows_vs2022_x64_ninja_multi.cmake b/.gitlab/ci/configure_windows_vs2026_x64_ninja_multi.cmake similarity index 100% rename from .gitlab/ci/configure_windows_vs2022_x64_ninja_multi.cmake rename to .gitlab/ci/configure_windows_vs2026_x64_ninja_multi.cmake
diff --git a/.gitlab/ci/configure_windows_vs2022_x64_nmake.cmake b/.gitlab/ci/configure_windows_vs2026_x64_nmake.cmake similarity index 100% rename from .gitlab/ci/configure_windows_vs2022_x64_nmake.cmake rename to .gitlab/ci/configure_windows_vs2026_x64_nmake.cmake
diff --git a/.gitlab/ci/configure_windows_vs2022_x64_pch.cmake b/.gitlab/ci/configure_windows_vs2026_x64_pch.cmake similarity index 100% rename from .gitlab/ci/configure_windows_vs2022_x64_pch.cmake rename to .gitlab/ci/configure_windows_vs2026_x64_pch.cmake
diff --git a/.gitlab/ci/configure_windows_x86_64_package.cmake b/.gitlab/ci/configure_windows_x86_64_package.cmake index 051e3fc..b61e199 100644 --- a/.gitlab/ci/configure_windows_x86_64_package.cmake +++ b/.gitlab/ci/configure_windows_x86_64_package.cmake
@@ -4,10 +4,12 @@ # Tell WiX to package for this architecture. set(CPACK_WIX_ARCHITECTURE "x64" CACHE STRING "") -# Use APIs from at most Windows 7 -set(CMAKE_C_FLAGS "-D_WIN32_WINNT=0x601 -DNTDDI_VERSION=0x06010000" CACHE STRING "") -set(CMAKE_CXX_FLAGS "-GR -EHsc -D_WIN32_WINNT=0x601 -DNTDDI_VERSION=0x06010000" CACHE STRING "") -set(CMAKE_EXE_LINKER_FLAGS "-machine:x64 -subsystem:console,6.01" CACHE STRING "") +# Use APIs from at most Windows 10 +set(CMAKE_C_FLAGS "-D_WIN32_WINNT=0x0A00 -DNTDDI_VERSION=0x0A000000" CACHE STRING "") +set(CMAKE_CXX_FLAGS "-GR -EHsc -D_WIN32_WINNT=0x0A00 -DNTDDI_VERSION=0x0A000000" CACHE STRING "") +set(CMAKE_EXE_LINKER_FLAGS "-machine:x64 -subsystem:console,6.02" CACHE STRING "") -include("${CMAKE_CURRENT_LIST_DIR}/configure_windows_package_common_x86.cmake") +set(qt "$ENV{CI_PROJECT_DIR}/.gitlab/qt") +set(CMAKE_PREFIX_PATH "${qt}" CACHE STRING "") + include("${CMAKE_CURRENT_LIST_DIR}/configure_windows_package_common.cmake")
diff --git a/.gitlab/ci/ctest_coverage.cmake b/.gitlab/ci/ctest_coverage.cmake new file mode 100644 index 0000000..c8bcd0a --- /dev/null +++ b/.gitlab/ci/ctest_coverage.cmake
@@ -0,0 +1,29 @@ +cmake_minimum_required(VERSION 3.29) + +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) + +find_program(GCOV NAMES gcov) +set(CTEST_COVERAGE_COMMAND "${GCOV}") +set(CTEST_COVERAGE_EXTRA_FLAGS + --hash-filenames + --long-file-names) +string(REPLACE ";" " " CTEST_COVERAGE_EXTRA_FLAGS "${CTEST_COVERAGE_EXTRA_FLAGS}") +ctest_coverage( + RETURN_VALUE coverage_result) +ctest_submit(PARTS Coverage) + +include("${CMAKE_CURRENT_LIST_DIR}/ctest_annotation.cmake") +ctest_annotation_report("${CTEST_BINARY_DIRECTORY}/annotations.json" + "Coverage Report" "https://open.cdash.org/viewCoverage.php?buildid=${build_id}" +) + +if (coverage_result) + message(FATAL_ERROR + "Failed to gather coverage") +endif ()
diff --git a/.gitlab/ci/ctest_exclusions.cmake b/.gitlab/ci/ctest_exclusions.cmake index 89a5ace..e04dea3 100644 --- a/.gitlab/ci/ctest_exclusions.cmake +++ b/.gitlab/ci/ctest_exclusions.cmake
@@ -27,6 +27,28 @@ ) endif() +if ("$ENV{CMAKE_CONFIGURATION}" MATCHES "_valgrind") + list(APPEND test_exclusions + # Tests that timeout under valgrind. + "^RunCMake.NinjaMultiConfig$" + "^RunCMake.Autogen_Qt6_1$" + "^RunCMake.GoogleTest$" + "^RunCMake.CXXModules$" + "^RunCMake.CXXModulesCompile$" + "^RunCMake.CommandLine$" + + # Too spurious under Valgrind. + "^RunCMake.testUVProcessChain$" + ) +endif() + +if ("$ENV{CMAKE_CONFIGURATION}" MATCHES "^macos_x86_64_") + list(APPEND test_exclusions + # FIXME(#27376): CMakeGUI's simpleConfigure:fail case hangs. + "^CMakeGUI$" + ) +endif() + string(REPLACE ";" "|" test_exclusions "${test_exclusions}") if (test_exclusions) set(test_exclusions "(${test_exclusions})")
diff --git a/.gitlab/ci/ctest_memcheck.cmake b/.gitlab/ci/ctest_memcheck.cmake index 36c7777..7121015 100644 --- a/.gitlab/ci/ctest_memcheck.cmake +++ b/.gitlab/ci/ctest_memcheck.cmake
@@ -16,18 +16,17 @@ 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}'") +if (NOT "$ENV{CMAKE_CI_TEST_TIMEOUT}" STREQUAL "") + set(CTEST_TEST_TIMEOUT "$ENV{CMAKE_CI_TEST_TIMEOUT}") endif () +include("${CMAKE_CURRENT_LIST_DIR}/ctest_memcheck_prep.cmake") + include("${CMAKE_CURRENT_LIST_DIR}/ctest_exclusions.cmake") ctest_memcheck( PARALLEL_LEVEL "${nproc}" TEST_LOAD "${nproc}" + OUTPUT_JUNIT "${CTEST_BINARY_DIRECTORY}/junit.xml" RETURN_VALUE test_result EXCLUDE "${test_exclusions}" DEFECT_COUNT defects)
diff --git a/.gitlab/ci/ctest_memcheck_fedora43.valgrind.supp b/.gitlab/ci/ctest_memcheck_fedora43.valgrind.supp new file mode 100644 index 0000000..acc1d2c --- /dev/null +++ b/.gitlab/ci/ctest_memcheck_fedora43.valgrind.supp
@@ -0,0 +1,91 @@ +# Add Valgrind suppressions here. +{ + libc_start_main-malloc + Memcheck:Leak + match-leak-kinds: reachable + fun:malloc + ... + fun:__libc_start_main@@GLIBC_2.34 + ... +} +{ + dl_init-malloc + Memcheck:Leak + match-leak-kinds: reachable + fun:malloc + ... + fun:_dl_init + ... +} +{ + dl_init-calloc + Memcheck:Leak + match-leak-kinds: reachable + fun:calloc + ... + fun:_dl_init + ... +} +{ + dl_init-realloc + Memcheck:Leak + match-leak-kinds: reachable + fun:realloc + ... + fun:_dl_init + ... +} +{ + dl_open-malloc + Memcheck:Leak + match-leak-kinds: reachable + fun:malloc + ... + fun:_dl_open + ... +} +{ + dl_open-calloc + Memcheck:Leak + match-leak-kinds: reachable + fun:calloc + ... + fun:_dl_open + ... +} +{ + qt5-object-new + Memcheck:Leak + match-leak-kinds: reachable + fun:_Znwm + ... + fun:_ZN7QObjectC1ER14QObjectPrivatePS_ + ... +} +{ + qt5-logger-malloc + Memcheck:Leak + match-leak-kinds: reachable + fun:malloc + ... + fun:_ZNK14QMessageLogger5debugEv + ... +} +{ + strerror_l-malloc + Memcheck:Leak + match-leak-kinds: reachable + fun:malloc + fun:__vasprintf_internal + fun:__asprintf_chk + fun:strerror_l + ... +} +{ + bash + Memcheck:Leak + match-leak-kinds: reachable + ... + obj:/usr/bin/bash + ... +}
diff --git a/.gitlab/ci/ctest_memcheck_fedora42_asan.lsan.supp b/.gitlab/ci/ctest_memcheck_fedora43_asan.lsan.supp similarity index 100% rename from .gitlab/ci/ctest_memcheck_fedora42_asan.lsan.supp rename to .gitlab/ci/ctest_memcheck_fedora43_asan.lsan.supp
diff --git a/.gitlab/ci/ctest_memcheck_prep.cmake b/.gitlab/ci/ctest_memcheck_prep.cmake new file mode 100644 index 0000000..9b4c2f5 --- /dev/null +++ b/.gitlab/ci/ctest_memcheck_prep.cmake
@@ -0,0 +1,50 @@ +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 () + +if (CTEST_MEMORYCHECK_TYPE STREQUAL "Valgrind") + find_program(valgrind_exe NAMES valgrind) + set(CTEST_MEMORYCHECK_COMMAND "${valgrind_exe}") + + set(valgrind_suppressions "${CMAKE_CURRENT_LIST_DIR}/ctest_memcheck_$ENV{CMAKE_CONFIGURATION}.valgrind.supp") + set(common_valgrind_suppressions "${CMAKE_CURRENT_LIST_DIR}/ctest_memcheck_$ENV{CMAKE_VALGRIND_CONFIGURATION}.valgrind.supp") + if (EXISTS "${valgrind_suppressions}") + set(CTEST_MEMORYCHECK_SUPPRESSIONS_FILE "${valgrind_suppressions}") + elseif (EXISTS "${common_valgrind_suppressions}") + set(CTEST_MEMORYCHECK_SUPPRESSIONS_FILE "${common_valgrind_suppressions}") + endif () + + set(valgrind_skip + /bin/* + /sbin/* + /usr/bin/* + /usr/lib64/qt5/bin/* + /usr/lib64/qt6/bin/* + /usr/lib64/qt6/libexec/* + bootstrap + sample_script + */Tests/CTestTest2/kwsysBin/* + */Tests/CTestTestCrash/Crash + */Tests/Qt*Autogen/* + # Ignore ISPC files which may contain unimplemented instructions. + */build/Tests/ISPC/TryCompile/ISPCTryCompile + # Ignore anything CI downloads. + */.gitlab/*) + list(JOIN valgrind_skip "," valgrind_skip) + string(CONCAT valgrind_options + "--gen-suppressions=all " + "--child-silent-after-fork=yes " + "--trace-children=yes " + "--trace-children-skip=${valgrind_skip} " + "--track-origins=yes " + "-q " + "--leak-check=yes " + "--show-reachable=yes " + "--num-callers=50 " + "-v ") + set(CTEST_MEMORYCHECK_COMMAND_OPTIONS "${valgrind_options}") +endif ()
diff --git a/.gitlab/ci/ctest_standalone.cmake b/.gitlab/ci/ctest_standalone.cmake index a55ab6c..2981264 100644 --- a/.gitlab/ci/ctest_standalone.cmake +++ b/.gitlab/ci/ctest_standalone.cmake
@@ -14,6 +14,10 @@ endif () endif () +if (NOT "$ENV{CMAKE_CI_TEST_TIMEOUT}" STREQUAL "") + set(CTEST_TEST_TIMEOUT "$ENV{CMAKE_CI_TEST_TIMEOUT}") +endif () + # Create an entry in CDash. ctest_start("${ctest_model}" GROUP "${ctest_group}") @@ -29,6 +33,10 @@ set(CTEST_CONFIGURE_COMMAND "/opt/extdeps/bin/cmake -C \"${initial_cache}\" -G \"${CTEST_CMAKE_GENERATOR}\" \"${CTEST_SOURCE_DIRECTORY}\"") endif() +if ("$ENV{CMAKE_CI_RUN_MEMCHECK}" STREQUAL "true") + include("${CMAKE_CURRENT_LIST_DIR}/ctest_memcheck_prep.cmake") +endif () + # Configure the project. ctest_configure( OPTIONS "${cmake_args}" @@ -89,20 +97,37 @@ endif () 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}") -ctest_submit(PARTS Test) +set(extra_annotations) +if ("$ENV{CMAKE_CI_RUN_MEMCHECK}" STREQUAL "true") + ctest_memcheck( + PARALLEL_LEVEL "${nproc}" + TEST_LOAD "${nproc}" + OUTPUT_JUNIT "${CTEST_BINARY_DIRECTORY}/junit.xml" + RETURN_VALUE test_result + ${ctest_label_args} + EXCLUDE "${test_exclusions}") + ctest_submit(PARTS Test) + ctest_submit(PARTS Memcheck) + list(APPEND extra_annotations + "Dynamic Analysis" "https://open.cdash.org/viewDynamicAnalysis.php?buildid=${build_id}" + ) +else () + 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}") + ctest_submit(PARTS Test) +endif () ctest_annotation_report("${CTEST_BINARY_DIRECTORY}/annotations.json" "All Tests" "https://open.cdash.org/viewTest.php?buildid=${build_id}" "Test Failures" "https://open.cdash.org/viewTest.php?onlyfailed&buildid=${build_id}" "Tests Not Run" "https://open.cdash.org/viewTest.php?onlynotrun&buildid=${build_id}" - "Test Passes" "https://open.cdash.org/viewTest.php?onlypassed&buildid=${build_id}") + "Test Passes" "https://open.cdash.org/viewTest.php?onlypassed&buildid=${build_id}" + ${extra_annotations}) if (test_result) ctest_submit(PARTS Done)
diff --git a/.gitlab/ci/ctest_test.cmake b/.gitlab/ci/ctest_test.cmake index fa60dd0..f6165b1 100644 --- a/.gitlab/ci/ctest_test.cmake +++ b/.gitlab/ci/ctest_test.cmake
@@ -16,6 +16,10 @@ endif () endif () +if (NOT "$ENV{CMAKE_CI_TEST_TIMEOUT}" STREQUAL "") + set(CTEST_TEST_TIMEOUT "$ENV{CMAKE_CI_TEST_TIMEOUT}") +endif () + include("${CMAKE_CURRENT_LIST_DIR}/ctest_exclusions.cmake") ctest_test( PARALLEL_LEVEL "${nproc}"
diff --git a/.gitlab/ci/docker/cuda13.0-aarch64/Dockerfile b/.gitlab/ci/docker/cuda13.0-aarch64/Dockerfile new file mode 100644 index 0000000..1dc4131 --- /dev/null +++ b/.gitlab/ci/docker/cuda13.0-aarch64/Dockerfile
@@ -0,0 +1,32 @@ +# syntax=docker/dockerfile:1 + +ARG BASE_IMAGE=kitware/nvidia-cuda:13.0.1-devel-ubuntu24.04 + +FROM ${BASE_IMAGE} AS apt-config +ADD https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/sbsa/cuda-keyring_1.1-1_all.deb /root/ +RUN --mount=type=tmpfs,target=/var/log \ + dpkg -i /root/cuda-keyring_1.1-1_all.deb \ + && rm /root/cuda-keyring_1.1-1_all.deb /etc/apt/sources.list.d/cuda.list + +FROM apt-config AS apt-cache +# Populate APT cache w/ the fresh metadata and prefetch packages. +# Use an empty `docker-clean` file to "hide" the image-provided +# file to disallow removing packages after `apt-get` operations. +RUN --mount=type=tmpfs,target=/var/log \ + --mount=type=bind,source=docker-clean,target=/etc/apt/apt.conf.d/docker-clean \ + --mount=type=bind,source=deps_packages.lst,target=/root/deps_packages.lst \ + apt-get update \ + && apt-get --download-only -y install $(grep -h '^[^#]\+$' /root/*.lst) + +FROM apt-config +MAINTAINER Brad King <brad.king@kitware.com> + +RUN --mount=type=bind,source=install_deps.sh,target=/root/install_deps.sh \ + --mount=type=bind,source=deps_packages.lst,target=/root/deps_packages.lst \ + --mount=type=bind,source=dpkg-exclude,target=/etc/dpkg/dpkg.cfg.d/exclude \ + --mount=type=bind,source=docker-clean,target=/etc/apt/apt.conf.d/docker-clean \ + --mount=type=cache,from=apt-cache,source=/var/lib/apt/lists,target=/var/lib/apt/lists \ + --mount=type=cache,from=apt-cache,source=/var/cache/apt,target=/var/cache/apt,sharing=private \ + --mount=type=tmpfs,target=/var/log \ + --mount=type=tmpfs,target=/tmp \ + sh /root/install_deps.sh
diff --git a/.gitlab/ci/docker/cuda13.0-aarch64/deps_packages.lst b/.gitlab/ci/docker/cuda13.0-aarch64/deps_packages.lst new file mode 100644 index 0000000..4637272 --- /dev/null +++ b/.gitlab/ci/docker/cuda13.0-aarch64/deps_packages.lst
@@ -0,0 +1,11 @@ +# Host tools +curl +git +unzip + +# Compilers +g++ + +# CUDA Dependencies +ocl-icd-opencl-dev +opencl-headers
diff --git a/.gitlab/ci/docker/debian12-aarch64/docker-clean b/.gitlab/ci/docker/cuda13.0-aarch64/docker-clean similarity index 100% copy from .gitlab/ci/docker/debian12-aarch64/docker-clean copy to .gitlab/ci/docker/cuda13.0-aarch64/docker-clean
diff --git a/.gitlab/ci/docker/debian12-aarch64/dpkg-exclude b/.gitlab/ci/docker/cuda13.0-aarch64/dpkg-exclude similarity index 100% copy from .gitlab/ci/docker/debian12-aarch64/dpkg-exclude copy to .gitlab/ci/docker/cuda13.0-aarch64/dpkg-exclude
diff --git a/.gitlab/ci/docker/debian12-aarch64/install_deps.sh b/.gitlab/ci/docker/cuda13.0-aarch64/install_deps.sh similarity index 100% rename from .gitlab/ci/docker/debian12-aarch64/install_deps.sh rename to .gitlab/ci/docker/cuda13.0-aarch64/install_deps.sh
diff --git a/.gitlab/ci/docker/cuda13.0-x86_64/Dockerfile b/.gitlab/ci/docker/cuda13.0-x86_64/Dockerfile new file mode 100644 index 0000000..9433296 --- /dev/null +++ b/.gitlab/ci/docker/cuda13.0-x86_64/Dockerfile
@@ -0,0 +1,32 @@ +# syntax=docker/dockerfile:1 + +ARG BASE_IMAGE=kitware/nvidia-cuda:13.0.1-devel-ubuntu24.04 + +FROM ${BASE_IMAGE} AS apt-config +ADD https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/cross-linux-sbsa/cuda-keyring_1.1-1_all.deb /root/ +RUN --mount=type=tmpfs,target=/var/log \ + dpkg -i /root/cuda-keyring_1.1-1_all.deb \ + && rm /root/cuda-keyring_1.1-1_all.deb + +FROM apt-config AS apt-cache +# Populate APT cache w/ the fresh metadata and prefetch packages. +# Use an empty `docker-clean` file to "hide" the image-provided +# file to disallow removing packages after `apt-get` operations. +RUN --mount=type=tmpfs,target=/var/log \ + --mount=type=bind,source=docker-clean,target=/etc/apt/apt.conf.d/docker-clean \ + --mount=type=bind,source=deps_packages.lst,target=/root/deps_packages.lst \ + apt-get update \ + && apt-get --download-only -y install $(grep -h '^[^#]\+$' /root/*.lst) + +FROM apt-config +MAINTAINER Brad King <brad.king@kitware.com> + +RUN --mount=type=bind,source=install_deps.sh,target=/root/install_deps.sh \ + --mount=type=bind,source=deps_packages.lst,target=/root/deps_packages.lst \ + --mount=type=bind,source=dpkg-exclude,target=/etc/dpkg/dpkg.cfg.d/exclude \ + --mount=type=bind,source=docker-clean,target=/etc/apt/apt.conf.d/docker-clean \ + --mount=type=cache,from=apt-cache,source=/var/lib/apt/lists,target=/var/lib/apt/lists \ + --mount=type=cache,from=apt-cache,source=/var/cache/apt,target=/var/cache/apt,sharing=private \ + --mount=type=tmpfs,target=/var/log \ + --mount=type=tmpfs,target=/tmp \ + sh /root/install_deps.sh
diff --git a/.gitlab/ci/docker/cuda13.0-x86_64/deps_packages.lst b/.gitlab/ci/docker/cuda13.0-x86_64/deps_packages.lst new file mode 100644 index 0000000..9863134 --- /dev/null +++ b/.gitlab/ci/docker/cuda13.0-x86_64/deps_packages.lst
@@ -0,0 +1,12 @@ +# Host tools +curl +git +unzip + +# Compilers +g++ +g++-aarch64-linux-gnu + +# CUDA Extras +cuda-cross-sbsa-13-0 +cuda-opencl-dev-13-0
diff --git a/.gitlab/ci/docker/debian12-x86_64/docker-clean b/.gitlab/ci/docker/cuda13.0-x86_64/docker-clean similarity index 100% copy from .gitlab/ci/docker/debian12-x86_64/docker-clean copy to .gitlab/ci/docker/cuda13.0-x86_64/docker-clean
diff --git a/.gitlab/ci/docker/debian12-x86_64/dpkg-exclude b/.gitlab/ci/docker/cuda13.0-x86_64/dpkg-exclude similarity index 100% copy from .gitlab/ci/docker/debian12-x86_64/dpkg-exclude copy to .gitlab/ci/docker/cuda13.0-x86_64/dpkg-exclude
diff --git a/.gitlab/ci/docker/debian12-aarch64/install_deps.sh b/.gitlab/ci/docker/cuda13.0-x86_64/install_deps.sh similarity index 100% copy from .gitlab/ci/docker/debian12-aarch64/install_deps.sh copy to .gitlab/ci/docker/cuda13.0-x86_64/install_deps.sh
diff --git a/.gitlab/ci/docker/debian12-aarch64/Dockerfile b/.gitlab/ci/docker/debian12-aarch64/Dockerfile deleted file mode 100644 index 2344ce5..0000000 --- a/.gitlab/ci/docker/debian12-aarch64/Dockerfile +++ /dev/null
@@ -1,34 +0,0 @@ -# syntax=docker/dockerfile:1 - -ARG BASE_IMAGE=arm64v8/debian:12 - -FROM ${BASE_IMAGE} AS cuda-keyring -ADD https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/sbsa/cuda-keyring_1.1-1_all.deb /root/ -RUN --mount=type=tmpfs,target=/var/log \ - apt-get update \ - && apt-get -y install ca-certificates \ - && dpkg -i /root/cuda-keyring_1.1-1_all.deb \ - && rm /root/cuda-keyring_1.1-1_all.deb - -FROM cuda-keyring AS apt-cache -# Populate APT cache w/ the fresh metadata and prefetch packages. -# Use an empty `docker-clean` file to "hide" the image-provided -# file to disallow removing packages after `apt-get` operations. -RUN --mount=type=tmpfs,target=/var/log \ - --mount=type=bind,source=docker-clean,target=/etc/apt/apt.conf.d/docker-clean \ - --mount=type=bind,source=deps_packages.lst,target=/root/deps_packages.lst \ - apt-get update \ - && apt-get --download-only -y install $(grep -h '^[^#]\+$' /root/*.lst) - -FROM cuda-keyring -LABEL maintainer="Brad King <brad.king@kitware.com>" - -RUN --mount=type=bind,source=install_deps.sh,target=/root/install_deps.sh \ - --mount=type=bind,source=deps_packages.lst,target=/root/deps_packages.lst \ - --mount=type=bind,source=dpkg-exclude,target=/etc/dpkg/dpkg.cfg.d/exclude \ - --mount=type=bind,source=docker-clean,target=/etc/apt/apt.conf.d/docker-clean \ - --mount=type=cache,from=apt-cache,source=/var/lib/apt/lists,target=/var/lib/apt/lists \ - --mount=type=cache,from=apt-cache,source=/var/cache/apt,target=/var/cache/apt,sharing=private \ - --mount=type=tmpfs,target=/var/log \ - --mount=type=tmpfs,target=/tmp \ - sh /root/install_deps.sh
diff --git a/.gitlab/ci/docker/debian12-aarch64/deps_packages.lst b/.gitlab/ci/docker/debian12-aarch64/deps_packages.lst deleted file mode 100644 index 2328194..0000000 --- a/.gitlab/ci/docker/debian12-aarch64/deps_packages.lst +++ /dev/null
@@ -1,99 +0,0 @@ -# Install build requirements. -libssl-dev - -# Install development tools. -g++ -curl -git - -# Install optional external build dependencies. -libarchive-dev -libbz2-dev -libcurl4-gnutls-dev -libexpat1-dev -libjsoncpp-dev -liblzma-dev -libncurses-dev -librhash-dev -libuv1-dev -libzstd-dev -zlib1g-dev - -# Install iwyu runtime deps. -clang-15 -libncurses6 - -# Tools needed for the test suite. -jq - -# Packages needed to test CTest. -bzr -cvs -subversion -mercurial - -# Packages needed to test find modules. -alsa-utils -aspell -aspell-en -doxygen graphviz -freeglut3-dev -gnutls-dev -libarchive-dev -libaspell-dev -libblas-dev -libboost-dev -libboost-filesystem-dev -libboost-program-options-dev -libboost-python-dev -libboost-thread-dev -libbz2-dev -libcups2-dev -libcurl4-gnutls-dev -libdevil-dev -libfontconfig1-dev -libfreetype6-dev -libgdal-dev -libgif-dev -libgl1-mesa-dev -libglew-dev -libgmock-dev -libgrpc++-dev libgrpc-dev -libgsl-dev -libgtest-dev -libgtk2.0-dev -libhdf5-dev -libhdf5-mpich-dev -libhdf5-openmpi-dev -libicu-dev -libinput-dev -libjpeg-dev -libjsoncpp-dev -liblapack-dev -liblzma-dev -libmagick++-dev -libnvpl-blas-dev -libnvpl-common-dev -libnvpl-lapack-dev -libopenal-dev -libopenmpi-dev openmpi-bin -libosp-dev -libpng-dev -libpq-dev postgresql-server-dev-15 -libprotobuf-dev libprotobuf-c-dev libprotoc-dev protobuf-compiler protobuf-compiler-grpc -libsdl1.2-dev -libsqlite3-dev -libtiff-dev -libuv1-dev -libwxgtk3.2-dev -libx11-dev -libxalan-c-dev -libxerces-c-dev -libxml2-dev libxml2-utils -libxslt-dev xsltproc -openjdk-17-jdk -python3 python3-dev python3-numpy pypy3 pypy3-dev python3-venv -qtbase5-dev qtbase5-dev-tools -ruby ruby-dev -swig -unixodbc-dev
diff --git a/.gitlab/ci/docker/debian12-x86_64/Dockerfile b/.gitlab/ci/docker/debian12-x86_64/Dockerfile deleted file mode 100644 index 3a9a6a1..0000000 --- a/.gitlab/ci/docker/debian12-x86_64/Dockerfile +++ /dev/null
@@ -1,64 +0,0 @@ -# syntax=docker/dockerfile:1 - -ARG BASE_IMAGE=debian:12 - -FROM ${BASE_IMAGE} AS apt-cache -# Populate APT cache w/ the fresh metadata and prefetch packages. -# Use an empty `docker-clean` file to "hide" the image-provided -# file to disallow removing packages after `apt-get` operations. -RUN --mount=type=tmpfs,target=/var/log \ - --mount=type=bind,source=docker-clean,target=/etc/apt/apt.conf.d/docker-clean \ - --mount=type=bind,source=deps_packages.lst,target=/root/deps_packages.lst \ - --mount=type=bind,source=iwyu_packages.lst,target=/root/iwyu_packages.lst \ - --mount=type=bind,source=rvm_packages.lst,target=/root/rvm_packages.lst \ - apt-get update \ - && apt-get --download-only -y install $(grep -h '^[^#]\+$' /root/*.lst) - - -FROM ${BASE_IMAGE} AS iwyu-build -LABEL maintainer="Ben Boeckel <ben.boeckel@kitware.com>" - -RUN --mount=type=bind,source=install_iwyu.sh,target=/root/install_iwyu.sh \ - --mount=type=bind,source=iwyu_packages.lst,target=/root/iwyu_packages.lst \ - --mount=type=bind,source=docker-clean,target=/etc/apt/apt.conf.d/docker-clean \ - --mount=type=cache,from=apt-cache,source=/var/lib/apt/lists,target=/var/lib/apt/lists \ - --mount=type=cache,from=apt-cache,source=/var/cache/apt,target=/var/cache/apt,sharing=private \ - --mount=type=tmpfs,target=/var/log \ - --mount=type=tmpfs,target=/tmp \ - sh /root/install_iwyu.sh - - -FROM ${BASE_IMAGE} AS rvm-build -LABEL maintainer="Ben Boeckel <ben.boeckel@kitware.com>" - -RUN --mount=type=bind,source=install_rvm.sh,target=/root/install_rvm.sh \ - --mount=type=bind,source=rvm_packages.lst,target=/root/rvm_packages.lst \ - --mount=type=bind,source=docker-clean,target=/etc/apt/apt.conf.d/docker-clean \ - --mount=type=cache,from=apt-cache,source=/var/lib/apt/lists,target=/var/lib/apt/lists \ - --mount=type=cache,from=apt-cache,source=/var/cache/apt,target=/var/cache/apt,sharing=private \ - --mount=type=tmpfs,target=/var/log \ - --mount=type=tmpfs,target=/tmp \ - sh /root/install_rvm.sh - - -FROM ${BASE_IMAGE} -LABEL maintainer="Ben Boeckel <ben.boeckel@kitware.com>" - -ENV RBENV_ROOT=/opt/rbenv - -RUN --mount=type=bind,source=install_deps.sh,target=/root/install_deps.sh \ - --mount=type=bind,source=deps_packages.lst,target=/root/deps_packages.lst \ - --mount=type=bind,source=dpkg-exclude,target=/etc/dpkg/dpkg.cfg.d/exclude \ - --mount=type=bind,source=docker-clean,target=/etc/apt/apt.conf.d/docker-clean \ - --mount=type=cache,from=apt-cache,source=/var/lib/apt/lists,target=/var/lib/apt/lists \ - --mount=type=cache,from=apt-cache,source=/var/cache/apt,target=/var/cache/apt,sharing=private \ - --mount=type=tmpfs,target=/var/log \ - --mount=type=tmpfs,target=/tmp \ - sh /root/install_deps.sh - -RUN --mount=type=bind,from=iwyu-build,source=/root,target=/root \ - tar -C / -xf /root/iwyu.tar \ - && ln -s /usr/lib/llvm-15/bin/include-what-you-use /usr/bin/include-what-you-use-15 - -RUN --mount=type=bind,from=rvm-build,source=/root,target=/root \ - tar -C /usr/local -xf /root/rvm.tar
diff --git a/.gitlab/ci/docker/debian12-x86_64/deps_packages.lst b/.gitlab/ci/docker/debian12-x86_64/deps_packages.lst deleted file mode 100644 index e6f1188..0000000 --- a/.gitlab/ci/docker/debian12-x86_64/deps_packages.lst +++ /dev/null
@@ -1,114 +0,0 @@ -# Install build requirements. -libssl-dev - -# Install development tools. -g++ -curl -git - -# Install optional external build dependencies. -libarchive-dev -libbz2-dev -libcurl4-gnutls-dev -libexpat1-dev -libjsoncpp-dev -liblzma-dev -libncurses-dev -librhash-dev -libuv1-dev -libzstd-dev -zlib1g-dev - -# Install iwyu runtime deps. -clang-15 -libncurses6 - -# Tools needed for the test suite. -jq - -# Packages needed to test CTest. -bzr -cvs -subversion -mercurial - -# Install ASM_NASM language toolchain. -nasm - -# Install HIP language toolchain. -hipcc - -# Install swift runtime deps. -libncurses5 - -# Install IAR compiler package dependencies. -libusb-1.0-0 -udev -sudo - -# Packages needed to test find modules. -alsa-utils -aspell -aspell-en -doxygen graphviz -freeglut3-dev -gnutls-dev -libarchive-dev -libaspell-dev -libblas-dev -libboost-dev -libboost-filesystem-dev -libboost-program-options-dev -libboost-python-dev -libboost-thread-dev -libbz2-dev -libcups2-dev -libcurl4-gnutls-dev -libdevil-dev -libfontconfig1-dev -libfreetype6-dev -libgdal-dev -libgif-dev -libgl1-mesa-dev -libglew-dev -libgmock-dev -libgrpc++-dev libgrpc-dev -libgsl-dev -libgtest-dev -libgtk2.0-dev -libhdf5-dev -libhdf5-mpich-dev -libhdf5-openmpi-dev -libicu-dev -libinput-dev -libjpeg-dev -libjsoncpp-dev -liblapack-dev -liblzma-dev -libmagick++-dev -libopenal-dev -libopenmpi-dev openmpi-bin -libosp-dev -libpng-dev -libpq-dev postgresql-server-dev-15 -libprotobuf-dev libprotobuf-c-dev libprotoc-dev protobuf-compiler protobuf-compiler-grpc -libsdl1.2-dev -libsqlite3-dev -libtiff-dev -libuv1-dev -libwxgtk3.2-dev -libx11-dev -libxalan-c-dev -libxerces-c-dev -libxml2-dev libxml2-utils -libxslt-dev xsltproc -openjdk-17-jdk -python3 python3-dev python3-numpy pypy3 pypy3-dev python3-venv -qtbase5-dev qtbase5-dev-tools -rbenv ruby-build -ruby ruby-dev -swig -unixodbc-dev - -# Packages needed to test ironpython. -libmono-system-windows-forms4.0-cil
diff --git a/.gitlab/ci/docker/debian12-x86_64/install_deps.sh b/.gitlab/ci/docker/debian12-x86_64/install_deps.sh deleted file mode 100755 index 1493f1e..0000000 --- a/.gitlab/ci/docker/debian12-x86_64/install_deps.sh +++ /dev/null
@@ -1,19 +0,0 @@ -#!/bin/sh - -set -e - -apt-get install -y $(grep '^[^#]\+$' /root/deps_packages.lst) - -curl -L -O https://github.com/IronLanguages/ironpython3/releases/download/v3.4.0/ironpython_3.4.0.deb -echo '7dcd10b7a0ec0342bd7e20eebb597a96bb15267eb797d59358a3b1cfaa3e1adc ironpython_3.4.0.deb' > ironpython.sha256sum -sha256sum --check ironpython.sha256sum -dpkg -i ironpython_3.4.0.deb -rm ironpython_3.4.0.deb ironpython.sha256sum - -# Ruby rbenv -rbenv install 3.1.2 -rbenv global 3.1.2 - -# Perforce -curl -L https://www.perforce.com/downloads/perforce/r21.2/bin.linux26x86_64/helix-core-server.tgz -o - \ - | tar -C /usr/local/bin -xvzf - -- p4 p4d
diff --git a/.gitlab/ci/docker/debian12-x86_64/install_iwyu.sh b/.gitlab/ci/docker/debian12-x86_64/install_iwyu.sh deleted file mode 100755 index bbeceb8..0000000 --- a/.gitlab/ci/docker/debian12-x86_64/install_iwyu.sh +++ /dev/null
@@ -1,22 +0,0 @@ -#!/bin/sh - -set -e - -# Install development tools. -apt-get install -y $(grep '^[^#]\+$' /root/iwyu_packages.lst) - -cd /root -git clone "https://github.com/include-what-you-use/include-what-you-use.git" -cd include-what-you-use -readonly llvm_version="$( clang-15 --version | head -n1 | cut -d' ' -f4 | cut -d. -f-1 )" -git checkout "clang_$llvm_version" -mkdir build -cd build - -cmake -GNinja \ - -DCMAKE_BUILD_TYPE=Release \ - "-DCMAKE_INSTALL_PREFIX=/usr/lib/llvm-$llvm_version" \ - .. -ninja -DESTDIR=/root/iwyu-destdir ninja install -tar -C /root/iwyu-destdir -cf /root/iwyu.tar .
diff --git a/.gitlab/ci/docker/debian12-x86_64/iwyu_packages.lst b/.gitlab/ci/docker/debian12-x86_64/iwyu_packages.lst deleted file mode 100644 index 2dbddba..0000000 --- a/.gitlab/ci/docker/debian12-x86_64/iwyu_packages.lst +++ /dev/null
@@ -1,9 +0,0 @@ -# Install development tools. -clang-15 -libclang-15-dev -llvm-15-dev -libz-dev -g++ -cmake -ninja-build -git
diff --git a/.gitlab/ci/docker/debian12-x86_64/rvm_packages.lst b/.gitlab/ci/docker/debian12-x86_64/rvm_packages.lst deleted file mode 100644 index 80f079c..0000000 --- a/.gitlab/ci/docker/debian12-x86_64/rvm_packages.lst +++ /dev/null
@@ -1,25 +0,0 @@ -autoconf -automake -bison -bzip2 -curl -g++ -gawk -gcc -gnupg2 -libc6-dev -libffi-dev -libgdbm-dev -libgmp-dev -libncurses5-dev -libreadline-dev -libsqlite3-dev -libssl-dev -libtool -libyaml-dev -make -patch -pkg-config -procps -sqlite3 -zlib1g-dev
diff --git a/.gitlab/ci/docker/debian13-aarch64/Dockerfile b/.gitlab/ci/docker/debian13-aarch64/Dockerfile new file mode 100644 index 0000000..5a7f2fb --- /dev/null +++ b/.gitlab/ci/docker/debian13-aarch64/Dockerfile
@@ -0,0 +1,34 @@ +# syntax=docker/dockerfile:1 + +ARG BASE_IMAGE=arm64v8/debian:13 + +FROM ${BASE_IMAGE} AS cuda-keyring +ADD https://developer.download.nvidia.com/compute/cuda/repos/debian13/sbsa/cuda-keyring_1.1-1_all.deb /root/ +RUN --mount=type=tmpfs,target=/var/log \ + apt-get update \ + && apt-get -y install ca-certificates \ + && dpkg -i /root/cuda-keyring_1.1-1_all.deb \ + && rm /root/cuda-keyring_1.1-1_all.deb + +FROM cuda-keyring AS apt-cache +# Populate APT cache w/ the fresh metadata and prefetch packages. +# Use an empty `docker-clean` file to "hide" the image-provided +# file to disallow removing packages after `apt-get` operations. +RUN --mount=type=tmpfs,target=/var/log \ + --mount=type=bind,source=docker-clean,target=/etc/apt/apt.conf.d/docker-clean \ + --mount=type=bind,source=deps_packages.lst,target=/root/deps_packages.lst \ + apt-get update \ + && apt-get --download-only -y install $(grep -h '^[^#]\+$' /root/*.lst) + +FROM cuda-keyring +LABEL maintainer="Brad King <brad.king@kitware.com>" + +RUN --mount=type=bind,source=install_deps.sh,target=/root/install_deps.sh \ + --mount=type=bind,source=deps_packages.lst,target=/root/deps_packages.lst \ + --mount=type=bind,source=dpkg-exclude,target=/etc/dpkg/dpkg.cfg.d/exclude \ + --mount=type=bind,source=docker-clean,target=/etc/apt/apt.conf.d/docker-clean \ + --mount=type=cache,from=apt-cache,source=/var/lib/apt/lists,target=/var/lib/apt/lists \ + --mount=type=cache,from=apt-cache,source=/var/cache/apt,target=/var/cache/apt,sharing=private \ + --mount=type=tmpfs,target=/var/log \ + --mount=type=tmpfs,target=/tmp \ + sh /root/install_deps.sh
diff --git a/.gitlab/ci/docker/debian13-aarch64/deps_packages.lst b/.gitlab/ci/docker/debian13-aarch64/deps_packages.lst new file mode 100644 index 0000000..2e13e5b --- /dev/null +++ b/.gitlab/ci/docker/debian13-aarch64/deps_packages.lst
@@ -0,0 +1,101 @@ +locales + +# Install build requirements. +libssl-dev + +# Install development tools. +g++ +curl +git + +# Install optional external build dependencies. +libarchive-dev +libbz2-dev +libcurl4-gnutls-dev +libexpat1-dev +libjsoncpp-dev +liblzma-dev +libncurses-dev +librhash-dev +libuv1-dev +libzstd-dev +zlib1g-dev + +# Install iwyu runtime deps. +clang-19 +libncurses6 + +# Tools needed for the test suite. +jq + +# Packages needed to test CTest. +bzr +cvs +subversion +mercurial + +# Packages needed to test find modules. +alsa-utils +aspell +aspell-en +doxygen graphviz +freeglut3-dev +gnutls-dev +libarchive-dev +libaspell-dev +libblas-dev +libboost-dev +libboost-filesystem-dev +libboost-program-options-dev +libboost-python-dev +libboost-thread-dev +libbz2-dev +libcups2-dev +libcurl4-gnutls-dev +libdevil-dev +libfontconfig1-dev +libfreetype6-dev +libgdal-dev +libgif-dev +libgl1-mesa-dev +libglew-dev +libgmock-dev +libgrpc++-dev libgrpc-dev +libgsl-dev +libgtest-dev +libgtk2.0-dev +libhdf5-dev +libhdf5-mpich-dev +libhdf5-openmpi-dev +libicu-dev +libinput-dev +libjpeg-dev +libjsoncpp-dev +liblapack-dev +liblzma-dev +libmagick++-dev +libnvpl-blas-dev +libnvpl-common-dev +libnvpl-lapack-dev +libopenal-dev +libopenmpi-dev openmpi-bin +libosp-dev +libpng-dev +libpq-dev postgresql-server-dev-17 +libprotobuf-dev libprotobuf-c-dev libprotoc-dev protobuf-compiler protobuf-compiler-grpc +libsdl1.2-dev +libsqlite3-dev +libtiff-dev +libuv1-dev +libwxgtk3.2-dev +libx11-dev +libxalan-c-dev +libxerces-c-dev +libxml2-dev libxml2-utils +libxslt-dev xsltproc +openjdk-25-jdk +python3 python3-dev python3-numpy pypy3 pypy3-dev python3-venv +qtbase5-dev qtbase5-dev-tools +ruby ruby-dev +swig +unixodbc-dev
diff --git a/.gitlab/ci/docker/debian12-aarch64/docker-clean b/.gitlab/ci/docker/debian13-aarch64/docker-clean similarity index 100% rename from .gitlab/ci/docker/debian12-aarch64/docker-clean rename to .gitlab/ci/docker/debian13-aarch64/docker-clean
diff --git a/.gitlab/ci/docker/debian12-aarch64/dpkg-exclude b/.gitlab/ci/docker/debian13-aarch64/dpkg-exclude similarity index 100% rename from .gitlab/ci/docker/debian12-aarch64/dpkg-exclude rename to .gitlab/ci/docker/debian13-aarch64/dpkg-exclude
diff --git a/.gitlab/ci/docker/debian13-aarch64/install_deps.sh b/.gitlab/ci/docker/debian13-aarch64/install_deps.sh new file mode 100755 index 0000000..25b59aa --- /dev/null +++ b/.gitlab/ci/docker/debian13-aarch64/install_deps.sh
@@ -0,0 +1,9 @@ +#!/bin/sh + +set -e + +apt-get install -y $(grep '^[^#]\+$' /root/deps_packages.lst) + +# Add locales. +sed -i -E '/^# en_US[ .](ISO-8859-1|UTF-8)( |$)/ s/^# //' /etc/locale.gen +dpkg-reconfigure --frontend=noninteractive locales
diff --git a/.gitlab/ci/docker/debian13-x86_64/Dockerfile b/.gitlab/ci/docker/debian13-x86_64/Dockerfile new file mode 100644 index 0000000..defa93f --- /dev/null +++ b/.gitlab/ci/docker/debian13-x86_64/Dockerfile
@@ -0,0 +1,64 @@ +# syntax=docker/dockerfile:1 + +ARG BASE_IMAGE=debian:13 + +FROM ${BASE_IMAGE} AS apt-cache +# Populate APT cache w/ the fresh metadata and prefetch packages. +# Use an empty `docker-clean` file to "hide" the image-provided +# file to disallow removing packages after `apt-get` operations. +RUN --mount=type=tmpfs,target=/var/log \ + --mount=type=bind,source=docker-clean,target=/etc/apt/apt.conf.d/docker-clean \ + --mount=type=bind,source=deps_packages.lst,target=/root/deps_packages.lst \ + --mount=type=bind,source=iwyu_packages.lst,target=/root/iwyu_packages.lst \ + --mount=type=bind,source=rvm_packages.lst,target=/root/rvm_packages.lst \ + apt-get update \ + && apt-get --download-only -y install $(grep -h '^[^#]\+$' /root/*.lst) + + +FROM ${BASE_IMAGE} AS iwyu-build +LABEL maintainer="Brad King <brad.king@kitware.com>" + +RUN --mount=type=bind,source=install_iwyu.sh,target=/root/install_iwyu.sh \ + --mount=type=bind,source=iwyu_packages.lst,target=/root/iwyu_packages.lst \ + --mount=type=bind,source=docker-clean,target=/etc/apt/apt.conf.d/docker-clean \ + --mount=type=cache,from=apt-cache,source=/var/lib/apt/lists,target=/var/lib/apt/lists \ + --mount=type=cache,from=apt-cache,source=/var/cache/apt,target=/var/cache/apt,sharing=private \ + --mount=type=tmpfs,target=/var/log \ + --mount=type=tmpfs,target=/tmp \ + sh /root/install_iwyu.sh + + +FROM ${BASE_IMAGE} AS rvm-build +LABEL maintainer="Brad King <brad.king@kitware.com>" + +RUN --mount=type=bind,source=install_rvm.sh,target=/root/install_rvm.sh \ + --mount=type=bind,source=rvm_packages.lst,target=/root/rvm_packages.lst \ + --mount=type=bind,source=docker-clean,target=/etc/apt/apt.conf.d/docker-clean \ + --mount=type=cache,from=apt-cache,source=/var/lib/apt/lists,target=/var/lib/apt/lists \ + --mount=type=cache,from=apt-cache,source=/var/cache/apt,target=/var/cache/apt,sharing=private \ + --mount=type=tmpfs,target=/var/log \ + --mount=type=tmpfs,target=/tmp \ + sh /root/install_rvm.sh + + +FROM ${BASE_IMAGE} +LABEL maintainer="Brad King <brad.king@kitware.com>" + +ENV RBENV_ROOT=/opt/rbenv + +RUN --mount=type=bind,source=install_deps.sh,target=/root/install_deps.sh \ + --mount=type=bind,source=deps_packages.lst,target=/root/deps_packages.lst \ + --mount=type=bind,source=dpkg-exclude,target=/etc/dpkg/dpkg.cfg.d/exclude \ + --mount=type=bind,source=docker-clean,target=/etc/apt/apt.conf.d/docker-clean \ + --mount=type=cache,from=apt-cache,source=/var/lib/apt/lists,target=/var/lib/apt/lists \ + --mount=type=cache,from=apt-cache,source=/var/cache/apt,target=/var/cache/apt,sharing=private \ + --mount=type=tmpfs,target=/var/log \ + --mount=type=tmpfs,target=/tmp \ + sh /root/install_deps.sh + +RUN --mount=type=bind,from=iwyu-build,source=/root,target=/root \ + tar -C / -xf /root/iwyu.tar \ + && ln -s /usr/lib/llvm-19/bin/include-what-you-use /usr/bin/include-what-you-use-19 + +RUN --mount=type=bind,from=rvm-build,source=/root,target=/root \ + tar -C /usr/local -xf /root/rvm.tar
diff --git a/.gitlab/ci/docker/debian13-x86_64/deps_packages.lst b/.gitlab/ci/docker/debian13-x86_64/deps_packages.lst new file mode 100644 index 0000000..339053d --- /dev/null +++ b/.gitlab/ci/docker/debian13-x86_64/deps_packages.lst
@@ -0,0 +1,113 @@ +locales + +# Install build requirements. +libssl-dev + +# Install development tools. +g++ +curl +git + +# Install optional external build dependencies. +libarchive-dev +libbz2-dev +libcurl4-gnutls-dev +libexpat1-dev +libjsoncpp-dev +liblzma-dev +libncurses-dev +librhash-dev +libuv1-dev +libzstd-dev +zlib1g-dev + +# Install iwyu runtime deps. +clang-19 +libncurses6 + +# Tools needed for the test suite. +jq + +# Packages needed to test CTest. +bzr +cvs +subversion +mercurial + +# Install ASM_NASM language toolchain. +nasm + +# Install HIP language toolchain. +hipcc + +# Install IAR compiler package dependencies. +libusb-1.0-0 +udev +sudo + +# Packages needed to test find modules. +alsa-utils +aspell +aspell-en +doxygen graphviz +freeglut3-dev +gnutls-dev +libarchive-dev +libaspell-dev +libblas-dev +libboost-dev +libboost-filesystem-dev +libboost-program-options-dev +libboost-python-dev +libboost-thread-dev +libbz2-dev +libcups2-dev +libcurl4-gnutls-dev +libdevil-dev +libfontconfig1-dev +libfreetype6-dev +libgdal-dev +libgif-dev +libgl1-mesa-dev +libglew-dev +libgmock-dev +libgrpc++-dev libgrpc-dev +libgsl-dev +libgtest-dev +libgtk2.0-dev +libhdf5-dev +libhdf5-mpich-dev +libhdf5-openmpi-dev +libicu-dev +libinput-dev +libjpeg-dev +libjsoncpp-dev +liblapack-dev +liblzma-dev +libmagick++-dev +libopenal-dev +libopenmpi-dev openmpi-bin +libosp-dev +libpng-dev +libpq-dev postgresql-server-dev-17 +libprotobuf-dev libprotobuf-c-dev libprotoc-dev protobuf-compiler protobuf-compiler-grpc +libsdl1.2-dev +libsqlite3-dev +libtiff-dev +libuv1-dev +libwxgtk3.2-dev +libx11-dev +libxalan-c-dev +libxerces-c-dev +libxml2-dev libxml2-utils +libxslt-dev xsltproc +openjdk-25-jdk +python3 python3-dev python3-numpy pypy3 pypy3-dev python3-venv +qtbase5-dev qtbase5-dev-tools +rbenv ruby-build +ruby ruby-dev +swig +unixodbc-dev + +# Packages needed to test ironpython. +libmono-system-windows-forms4.0-cil
diff --git a/.gitlab/ci/docker/debian12-x86_64/docker-clean b/.gitlab/ci/docker/debian13-x86_64/docker-clean similarity index 100% rename from .gitlab/ci/docker/debian12-x86_64/docker-clean rename to .gitlab/ci/docker/debian13-x86_64/docker-clean
diff --git a/.gitlab/ci/docker/debian12-x86_64/dpkg-exclude b/.gitlab/ci/docker/debian13-x86_64/dpkg-exclude similarity index 100% rename from .gitlab/ci/docker/debian12-x86_64/dpkg-exclude rename to .gitlab/ci/docker/debian13-x86_64/dpkg-exclude
diff --git a/.gitlab/ci/docker/debian13-x86_64/install_deps.sh b/.gitlab/ci/docker/debian13-x86_64/install_deps.sh new file mode 100755 index 0000000..c916159 --- /dev/null +++ b/.gitlab/ci/docker/debian13-x86_64/install_deps.sh
@@ -0,0 +1,23 @@ +#!/bin/sh + +set -e + +apt-get install -y $(grep '^[^#]\+$' /root/deps_packages.lst) + +# Add locales. +sed -i -E '/^# en_US[ .](ISO-8859-1|UTF-8)( |$)/ s/^# //' /etc/locale.gen +dpkg-reconfigure --frontend=noninteractive locales + +curl -L -O https://github.com/IronLanguages/ironpython3/releases/download/v3.4.0/ironpython_3.4.0.deb +echo '7dcd10b7a0ec0342bd7e20eebb597a96bb15267eb797d59358a3b1cfaa3e1adc ironpython_3.4.0.deb' > ironpython.sha256sum +sha256sum --check ironpython.sha256sum +dpkg -i ironpython_3.4.0.deb +rm ironpython_3.4.0.deb ironpython.sha256sum + +# Ruby rbenv +rbenv install 3.1.2 +rbenv global 3.1.2 + +# Perforce +curl -L https://www.perforce.com/downloads/perforce/r21.2/bin.linux26x86_64/helix-core-server.tgz -o - \ + | tar -C /usr/local/bin -xvzf - -- p4 p4d
diff --git a/.gitlab/ci/docker/debian13-x86_64/install_iwyu.sh b/.gitlab/ci/docker/debian13-x86_64/install_iwyu.sh new file mode 100755 index 0000000..6247d8a --- /dev/null +++ b/.gitlab/ci/docker/debian13-x86_64/install_iwyu.sh
@@ -0,0 +1,22 @@ +#!/bin/sh + +set -e + +# Install development tools. +apt-get install -y $(grep '^[^#]\+$' /root/iwyu_packages.lst) + +cd /root +git clone "https://github.com/include-what-you-use/include-what-you-use.git" +cd include-what-you-use +readonly llvm_version="$( clang-19 --version | head -n1 | cut -d' ' -f4 | cut -d. -f-1 )" +git checkout "clang_$llvm_version" +mkdir build +cd build + +cmake -GNinja \ + -DCMAKE_BUILD_TYPE=Release \ + "-DCMAKE_INSTALL_PREFIX=/usr/lib/llvm-$llvm_version" \ + .. +ninja +DESTDIR=/root/iwyu-destdir ninja install +tar -C /root/iwyu-destdir -cf /root/iwyu.tar .
diff --git a/.gitlab/ci/docker/debian12-x86_64/install_rvm.sh b/.gitlab/ci/docker/debian13-x86_64/install_rvm.sh similarity index 100% rename from .gitlab/ci/docker/debian12-x86_64/install_rvm.sh rename to .gitlab/ci/docker/debian13-x86_64/install_rvm.sh
diff --git a/.gitlab/ci/docker/debian13-x86_64/iwyu_packages.lst b/.gitlab/ci/docker/debian13-x86_64/iwyu_packages.lst new file mode 100644 index 0000000..7301924 --- /dev/null +++ b/.gitlab/ci/docker/debian13-x86_64/iwyu_packages.lst
@@ -0,0 +1,9 @@ +# Install development tools. +clang-19 +libclang-19-dev +llvm-19-dev +libz-dev +g++ +cmake +ninja-build +git
diff --git a/.gitlab/ci/docker/debian13-x86_64/rvm_packages.lst b/.gitlab/ci/docker/debian13-x86_64/rvm_packages.lst new file mode 100644 index 0000000..6ea8a8f --- /dev/null +++ b/.gitlab/ci/docker/debian13-x86_64/rvm_packages.lst
@@ -0,0 +1,25 @@ +autoconf +automake +bison +bzip2 +curl +g++ +gawk +gcc +gnupg2 +libc6-dev +libffi-dev +libgdbm-dev +libgmp-dev +libncurses-dev +libreadline-dev +libsqlite3-dev +libssl-dev +libtool +libyaml-dev +make +patch +pkg-config +procps +sqlite3 +zlib1g-dev
diff --git a/.gitlab/ci/docker/fedora42-hip/Dockerfile b/.gitlab/ci/docker/fedora42-hip/Dockerfile deleted file mode 100644 index 22e5e2f..0000000 --- a/.gitlab/ci/docker/fedora42-hip/Dockerfile +++ /dev/null
@@ -1,12 +0,0 @@ -# syntax=docker/dockerfile:1 - -ARG BASE_IMAGE=fedora:42 - -FROM ${BASE_IMAGE} AS dnf-cache -LABEL maintainer="Brad King <brad.king@kitware.com>" -RUN --mount=type=bind,source=dnf.conf,target=/etc/dnf/dnf.conf \ - --mount=type=bind,source=deps_packages.lst,target=/root/deps_packages.lst \ - --mount=type=cache,target=/var/lib/dnf \ - --mount=type=tmpfs,target=/var/log \ - --mount=type=tmpfs,target=/tmp \ - dnf install -y $(grep -h '^[^#]\+$' /root/*.lst)
diff --git a/.gitlab/ci/docker/fedora42/Dockerfile b/.gitlab/ci/docker/fedora42/Dockerfile deleted file mode 100644 index e78b76b..0000000 --- a/.gitlab/ci/docker/fedora42/Dockerfile +++ /dev/null
@@ -1,135 +0,0 @@ -# syntax=docker/dockerfile:1 - -ARG BASE_IMAGE=fedora:42 - -FROM ${BASE_IMAGE} AS dnf-cache -# Populate DNF cache w/ the fresh metadata and prefetch packages. -RUN --mount=type=bind,source=dnf.conf,target=/etc/dnf/dnf.conf \ - --mount=type=bind,source=deps_packages.lst,target=/root/deps_packages.lst \ - --mount=type=bind,source=iwyu_packages.lst,target=/root/iwyu_packages.lst \ - --mount=type=bind,source=rbenv_packages.lst,target=/root/rbenv_packages.lst \ - --mount=type=bind,source=rust_packages.lst,target=/root/rust_packages.lst \ - --mount=type=bind,source=rvm_packages.lst,target=/root/rvm_packages.lst \ - --mount=type=tmpfs,target=/var/log \ - --mount=type=tmpfs,target=/tmp \ - dnf install --downloadonly -y $(grep -h '^[^#]\+$' /root/*.lst) - - -FROM ${BASE_IMAGE} AS rust-build-env -LABEL maintainer="Ben Boeckel <ben.boeckel@kitware.com>" -# Pre-install prerequisites to build Rust projects. -RUN --mount=type=bind,source=dnf.conf,target=/etc/dnf/dnf.conf \ - --mount=type=bind,source=rust_packages.lst,target=/root/rust_packages.lst \ - --mount=type=cache,from=dnf-cache,source=/var/cache/libdnf5,target=/var/cache/libdnf5,sharing=private \ - --mount=type=tmpfs,target=/var/log \ - --mount=type=tmpfs,target=/tmp \ - dnf install -y $(grep '^[^#]\+$' /root/rust_packages.lst) - - -FROM rust-build-env AS rust-build -LABEL maintainer="Ben Boeckel <ben.boeckel@kitware.com>" -# Build the needed Rust packages. -# https://doc.rust-lang.org/cargo/guide/cargo-home.html?highlight=.cargo#caching-the-cargo-home-in-ci -RUN --mount=type=bind,source=build_rust.sh,target=/root/build_rust.sh \ - --mount=type=cache,target=/root/.cargo/registry/index \ - --mount=type=cache,target=/root/.cargo/registry/cache \ - --mount=type=tmpfs,target=/tmp \ - sh /root/build_rust.sh - - -FROM ${BASE_IMAGE} AS rvm-build-env -LABEL maintainer="Ben Boeckel <ben.boeckel@kitware.com>" -# Pre-install prerequisites for RVM. -RUN --mount=type=bind,source=dnf.conf,target=/etc/dnf/dnf.conf \ - --mount=type=bind,source=rvm_packages.lst,target=/root/rvm_packages.lst \ - --mount=type=cache,from=dnf-cache,source=/var/cache/libdnf5,target=/var/cache/libdnf5,sharing=private \ - --mount=type=tmpfs,target=/var/log \ - --mount=type=tmpfs,target=/tmp \ - dnf install -y $(grep '^[^#]\+$' /root/rvm_packages.lst) - - -FROM rvm-build-env AS rvm-build -LABEL maintainer="Ben Boeckel <ben.boeckel@kitware.com>" -# Build Ruby with RVM. -RUN --mount=type=bind,source=build_rvm.sh,target=/root/build_rvm.sh \ - --mount=type=cache,target=/usr/local/rvm/archives \ - --mount=type=cache,target=/usr/local/rvm/gem-cache \ - --mount=type=cache,target=/usr/local/rvm/src \ - --mount=type=tmpfs,target=/tmp \ - sh /root/build_rvm.sh - - -FROM ${BASE_IMAGE} AS rbenv -# Pre-install prerequisites for `rbenv`. -RUN --mount=type=bind,source=dnf.conf,target=/etc/dnf/dnf.conf \ - --mount=type=bind,source=rbenv_packages.lst,target=/root/rbenv_packages.lst \ - --mount=type=cache,from=dnf-cache,source=/var/cache/libdnf5,target=/var/cache/libdnf5,sharing=private \ - --mount=type=tmpfs,target=/var/log \ - --mount=type=tmpfs,target=/tmp \ - dnf install -y $(grep '^[^#]\+$' /root/rbenv_packages.lst) - - -FROM rbenv AS rbenv-build -ENV RBENV_ROOT=/opt/rbenv -ENV RBENV_BUILD_ROOT=/root/.cache/rbenv-build -ENV RUBY_BUILD_CACHE_PATH=/root/.cache/rbenv -# Build Ruby with `rbenv`. -RUN --mount=type=cache,target=/root/.cache \ - --mount=type=bind,source=build_rbenv.sh,target=/root/build_rbenv.sh \ - --mount=type=tmpfs,target=/tmp \ - sh /root/build_rbenv.sh - - -FROM ${BASE_IMAGE} AS iwyu-build-env -LABEL maintainer="Kyle Edwards <kyle.edwards@kitware.com>" -# Pre-install prerequisites to build IWYU. -RUN --mount=type=bind,source=dnf.conf,target=/etc/dnf/dnf.conf \ - --mount=type=bind,source=iwyu_packages.lst,target=/root/iwyu_packages.lst \ - --mount=type=cache,from=dnf-cache,source=/var/cache/libdnf5,target=/var/cache/libdnf5,sharing=private \ - --mount=type=tmpfs,target=/var/log \ - --mount=type=tmpfs,target=/tmp \ - dnf install -y $(grep '^[^#]\+$' /root/iwyu_packages.lst) - - -FROM iwyu-build-env AS iwyu-build -LABEL maintainer="Kyle Edwards <kyle.edwards@kitware.com>" -# Build IWYU. -RUN --mount=type=bind,source=build_iwyu.sh,target=/root/build_iwyu.sh \ - --mount=type=cache,target=/root/include-what-you-use \ - --mount=type=tmpfs,target=/tmp \ - sh /root/build_iwyu.sh - - -FROM ${BASE_IMAGE} AS p4-dl -# Download Perforce. -# NOTE `curl` is pre-installed in the base image. -RUN curl -C- -L https://www.perforce.com/downloads/perforce/r21.2/bin.linux26x86_64/helix-core-server.tgz \ - | tar -C /usr/local/bin -xvzf - -- p4 p4d - - -FROM ${BASE_IMAGE} -LABEL maintainer="Ben Boeckel <ben.boeckel@kitware.com>" - -ENV RBENV_ROOT=/opt/rbenv - -COPY --from=p4-dl --chown=root:root /usr/local/bin/p4 /usr/local/bin/p4d /usr/local/bin - -RUN --mount=type=bind,source=dnf.conf,target=/etc/dnf/dnf.conf \ - --mount=type=bind,source=install_deps.sh,target=/root/install_deps.sh \ - --mount=type=bind,source=deps_packages.lst,target=/root/deps_packages.lst \ - --mount=type=cache,from=dnf-cache,source=/var/cache/libdnf5,target=/var/cache/libdnf5,sharing=private \ - --mount=type=tmpfs,target=/var/log \ - --mount=type=tmpfs,target=/tmp \ - sh /root/install_deps.sh - -RUN --mount=type=bind,from=iwyu-build,source=/root,target=/root \ - tar -C / -xf /root/iwyu.tar - -RUN --mount=type=bind,from=rust-build,source=/root,target=/root \ - tar -C /usr/local -xf /root/rust.tar - -RUN --mount=type=bind,from=rvm-build,source=/root,target=/root \ - tar -C /usr/local -xf /root/rvm.tar - -RUN --mount=type=bind,from=rbenv-build,source=/root,target=/root \ - tar -C / -xf /root/rbenv.tar && rbenv global 3.4.3
diff --git a/.gitlab/ci/docker/fedora42/build_rust.sh b/.gitlab/ci/docker/fedora42/build_rust.sh deleted file mode 100755 index f20949b..0000000 --- a/.gitlab/ci/docker/fedora42/build_rust.sh +++ /dev/null
@@ -1,10 +0,0 @@ -#!/bin/sh - -set -e - -typos_version=1.29.4 -cargo install --root /usr/local --version "$typos_version" typos-cli - -strip /usr/local/bin/typos - -tar -C /usr/local -cf /root/rust.tar bin/typos
diff --git a/.gitlab/ci/docker/fedora42/deps_packages.lst b/.gitlab/ci/docker/fedora42/deps_packages.lst deleted file mode 100644 index 5682514..0000000 --- a/.gitlab/ci/docker/fedora42/deps_packages.lst +++ /dev/null
@@ -1,141 +0,0 @@ -# Install build requirements. -ncurses-devel -openssl-devel -qt5-qtbase-devel -qt6-qtbase-devel - -# Install development tools. -clang -clang-devel -clang-tools-extra -clang-tools-extra-devel -compiler-rt -flang -gcc-c++ -git-core -lfortran -llvm-devel -make - -# Install optional external build dependencies. -bzip2-devel -expat-devel -jsoncpp-devel -libarchive-devel -libcurl-devel -libuv-devel -libzstd-devel -rhash-devel -xz-devel -zlib-devel - -# Install documentation tools. -python3-sphinx -python3-sphinxcontrib-qthelp -qt5-qttools-devel -qt6-qttools-devel -texinfo - -# Install lint tools. -clang-analyzer -codespell - -# Tools needed for the test suite. -file -findutils -jq -which - -# Install ASM_NASM language toolchain. -nasm - -# Packages needed to test CTest. -breezy -mercurial -subversion - -# Packages needed to test CPack. -rpm-build - -# Packages needed to test find modules. -alsa-lib-devel -aspell -aspell-devel -aspell-en -blas-devel -boost-devel -boost-python3-devel -bzip2-devel -cups-devel -DevIL-devel -doxygen -expat-devel -fontconfig-devel -freeglut-devel -freetype-devel -gdal-devel -gettext -giflib-devel -glew-devel -gmock -gnutls-devel -grpc-devel -grpc-plugins -gsl-devel -gtest-devel -gtk2-devel -hdf5-devel -hdf5-mpich-devel -hdf5-openmpi-devel -ImageMagick-c++-devel -jasper-devel -java-21-openjdk-devel -jsoncpp-devel -lapack-devel -libarchive-devel -libcurl-devel -libicu-devel -libinput-devel -libjpeg-turbo-devel -libomp-devel -libpng-devel -libtiff-devel -libuv-devel -libxml2-devel -libxslt-devel -mpich-devel -openal-soft-devel -openmpi-devel -opensp-devel -patch -perl -postgresql-server-devel -protobuf-c-devel -protobuf-devel -protobuf-lite-devel -pypy2 -pypy2-devel -pypy3 -pypy3-devel -python3 -python3-devel -python3-jsmin -python3-jsonschema -python3-numpy -rbenv -ruby -ruby-build-rbenv -ruby-devel -rubygems -SDL-devel -sqlite-devel -swig -systemd-devel -unixODBC-devel -wxGTK-devel -xalan-c-devel -xerces-c-devel -xz-devel - -# Packages needed to test third-party binaries. -ncurses-compat-libs
diff --git a/.gitlab/ci/docker/fedora42/install_deps.sh b/.gitlab/ci/docker/fedora42/install_deps.sh deleted file mode 100755 index d9c9b5c..0000000 --- a/.gitlab/ci/docker/fedora42/install_deps.sh +++ /dev/null
@@ -1,10 +0,0 @@ -#!/bin/sh - -set -e - -dnf install -y $(grep '^[^#]\+$' /root/deps_packages.lst) - -# Remove tests for Python packages -for v in 3.13; do - find /usr/lib64/python${v}/site-packages -type d -a -name tests -exec rm -rf {} + -done
diff --git a/.gitlab/ci/docker/fedora43-hip/Dockerfile b/.gitlab/ci/docker/fedora43-hip/Dockerfile new file mode 100644 index 0000000..0f0cbed --- /dev/null +++ b/.gitlab/ci/docker/fedora43-hip/Dockerfile
@@ -0,0 +1,12 @@ +# syntax=docker/dockerfile:1 + +ARG BASE_IMAGE=fedora:43 + +FROM ${BASE_IMAGE} AS dnf-cache +LABEL maintainer="Brad King <brad.king@kitware.com>" +RUN --mount=type=bind,source=dnf.conf,target=/etc/dnf/dnf.conf \ + --mount=type=bind,source=deps_packages.lst,target=/root/deps_packages.lst \ + --mount=type=cache,target=/var/lib/dnf \ + --mount=type=tmpfs,target=/var/log \ + --mount=type=tmpfs,target=/tmp \ + dnf install -y $(grep -h '^[^#]\+$' /root/*.lst)
diff --git a/.gitlab/ci/docker/fedora42-hip/deps_packages.lst b/.gitlab/ci/docker/fedora43-hip/deps_packages.lst similarity index 100% rename from .gitlab/ci/docker/fedora42-hip/deps_packages.lst rename to .gitlab/ci/docker/fedora43-hip/deps_packages.lst
diff --git a/.gitlab/ci/docker/fedora42-hip/dnf.conf b/.gitlab/ci/docker/fedora43-hip/dnf.conf similarity index 100% rename from .gitlab/ci/docker/fedora42-hip/dnf.conf rename to .gitlab/ci/docker/fedora43-hip/dnf.conf
diff --git a/.gitlab/ci/docker/fedora43/Dockerfile b/.gitlab/ci/docker/fedora43/Dockerfile new file mode 100644 index 0000000..86ee3b8 --- /dev/null +++ b/.gitlab/ci/docker/fedora43/Dockerfile
@@ -0,0 +1,135 @@ +# syntax=docker/dockerfile:1 + +ARG BASE_IMAGE=fedora:43 + +FROM ${BASE_IMAGE} AS dnf-cache +# Populate DNF cache w/ the fresh metadata and prefetch packages. +RUN --mount=type=bind,source=dnf.conf,target=/etc/dnf/dnf.conf \ + --mount=type=bind,source=deps_packages.lst,target=/root/deps_packages.lst \ + --mount=type=bind,source=iwyu_packages.lst,target=/root/iwyu_packages.lst \ + --mount=type=bind,source=rbenv_packages.lst,target=/root/rbenv_packages.lst \ + --mount=type=bind,source=rust_packages.lst,target=/root/rust_packages.lst \ + --mount=type=bind,source=rvm_packages.lst,target=/root/rvm_packages.lst \ + --mount=type=tmpfs,target=/var/log \ + --mount=type=tmpfs,target=/tmp \ + dnf install --downloadonly -y $(grep -h '^[^#]\+$' /root/*.lst) + + +FROM ${BASE_IMAGE} AS rust-build-env +LABEL maintainer="Brad King <brad.king@kitware.com>" +# Pre-install prerequisites to build Rust projects. +RUN --mount=type=bind,source=dnf.conf,target=/etc/dnf/dnf.conf \ + --mount=type=bind,source=rust_packages.lst,target=/root/rust_packages.lst \ + --mount=type=cache,from=dnf-cache,source=/var/cache/libdnf5,target=/var/cache/libdnf5,sharing=private \ + --mount=type=tmpfs,target=/var/log \ + --mount=type=tmpfs,target=/tmp \ + dnf install -y $(grep '^[^#]\+$' /root/rust_packages.lst) + + +FROM rust-build-env AS rust-build +LABEL maintainer="Brad King <brad.king@kitware.com>" +# Build the needed Rust packages. +# https://doc.rust-lang.org/cargo/guide/cargo-home.html?highlight=.cargo#caching-the-cargo-home-in-ci +RUN --mount=type=bind,source=build_rust.sh,target=/root/build_rust.sh \ + --mount=type=cache,target=/root/.cargo/registry/index \ + --mount=type=cache,target=/root/.cargo/registry/cache \ + --mount=type=tmpfs,target=/tmp \ + sh /root/build_rust.sh + + +FROM ${BASE_IMAGE} AS rvm-build-env +LABEL maintainer="Brad King <brad.king@kitware.com>" +# Pre-install prerequisites for RVM. +RUN --mount=type=bind,source=dnf.conf,target=/etc/dnf/dnf.conf \ + --mount=type=bind,source=rvm_packages.lst,target=/root/rvm_packages.lst \ + --mount=type=cache,from=dnf-cache,source=/var/cache/libdnf5,target=/var/cache/libdnf5,sharing=private \ + --mount=type=tmpfs,target=/var/log \ + --mount=type=tmpfs,target=/tmp \ + dnf install -y $(grep '^[^#]\+$' /root/rvm_packages.lst) + + +FROM rvm-build-env AS rvm-build +LABEL maintainer="Brad King <brad.king@kitware.com>" +# Build Ruby with RVM. +RUN --mount=type=bind,source=build_rvm.sh,target=/root/build_rvm.sh \ + --mount=type=cache,target=/usr/local/rvm/archives \ + --mount=type=cache,target=/usr/local/rvm/gem-cache \ + --mount=type=cache,target=/usr/local/rvm/src \ + --mount=type=tmpfs,target=/tmp \ + sh /root/build_rvm.sh + + +FROM ${BASE_IMAGE} AS rbenv +# Pre-install prerequisites for `rbenv`. +RUN --mount=type=bind,source=dnf.conf,target=/etc/dnf/dnf.conf \ + --mount=type=bind,source=rbenv_packages.lst,target=/root/rbenv_packages.lst \ + --mount=type=cache,from=dnf-cache,source=/var/cache/libdnf5,target=/var/cache/libdnf5,sharing=private \ + --mount=type=tmpfs,target=/var/log \ + --mount=type=tmpfs,target=/tmp \ + dnf install -y $(grep '^[^#]\+$' /root/rbenv_packages.lst) + + +FROM rbenv AS rbenv-build +ENV RBENV_ROOT=/opt/rbenv +ENV RBENV_BUILD_ROOT=/root/.cache/rbenv-build +ENV RUBY_BUILD_CACHE_PATH=/root/.cache/rbenv +# Build Ruby with `rbenv`. +RUN --mount=type=cache,target=/root/.cache \ + --mount=type=bind,source=build_rbenv.sh,target=/root/build_rbenv.sh \ + --mount=type=tmpfs,target=/tmp \ + sh /root/build_rbenv.sh + + +FROM ${BASE_IMAGE} AS iwyu-build-env +LABEL maintainer="Kyle Edwards <kyle.edwards@kitware.com>" +# Pre-install prerequisites to build IWYU. +RUN --mount=type=bind,source=dnf.conf,target=/etc/dnf/dnf.conf \ + --mount=type=bind,source=iwyu_packages.lst,target=/root/iwyu_packages.lst \ + --mount=type=cache,from=dnf-cache,source=/var/cache/libdnf5,target=/var/cache/libdnf5,sharing=private \ + --mount=type=tmpfs,target=/var/log \ + --mount=type=tmpfs,target=/tmp \ + dnf install -y $(grep '^[^#]\+$' /root/iwyu_packages.lst) + + +FROM iwyu-build-env AS iwyu-build +LABEL maintainer="Kyle Edwards <kyle.edwards@kitware.com>" +# Build IWYU. +RUN --mount=type=bind,source=build_iwyu.sh,target=/root/build_iwyu.sh \ + --mount=type=cache,target=/root/include-what-you-use \ + --mount=type=tmpfs,target=/tmp \ + sh /root/build_iwyu.sh + + +FROM ${BASE_IMAGE} AS p4-dl +# Download Perforce. +# NOTE `curl` is pre-installed in the base image. +RUN curl -C- -L https://www.perforce.com/downloads/perforce/r21.2/bin.linux26x86_64/helix-core-server.tgz \ + | tar -C /usr/local/bin -xvzf - -- p4 p4d + + +FROM ${BASE_IMAGE} +LABEL maintainer="Brad King <brad.king@kitware.com>" + +ENV RBENV_ROOT=/opt/rbenv + +COPY --from=p4-dl --chown=root:root /usr/local/bin/p4 /usr/local/bin/p4d /usr/local/bin + +RUN --mount=type=bind,source=dnf.conf,target=/etc/dnf/dnf.conf \ + --mount=type=bind,source=install_deps.sh,target=/root/install_deps.sh \ + --mount=type=bind,source=deps_packages.lst,target=/root/deps_packages.lst \ + --mount=type=cache,from=dnf-cache,source=/var/cache/libdnf5,target=/var/cache/libdnf5,sharing=private \ + --mount=type=tmpfs,target=/var/log \ + --mount=type=tmpfs,target=/tmp \ + sh /root/install_deps.sh + +RUN --mount=type=bind,from=iwyu-build,source=/root,target=/root \ + tar -C / -xf /root/iwyu.tar + +RUN --mount=type=bind,from=rust-build,source=/root,target=/root \ + tar -C /usr/local -xf /root/rust.tar + +RUN --mount=type=bind,from=rvm-build,source=/root,target=/root \ + tar -C /usr/local -xf /root/rvm.tar + +RUN --mount=type=bind,from=rbenv-build,source=/root,target=/root \ + tar -C / -xf /root/rbenv.tar && rbenv global 3.4.3
diff --git a/.gitlab/ci/docker/fedora42/build_iwyu.sh b/.gitlab/ci/docker/fedora43/build_iwyu.sh similarity index 100% rename from .gitlab/ci/docker/fedora42/build_iwyu.sh rename to .gitlab/ci/docker/fedora43/build_iwyu.sh
diff --git a/.gitlab/ci/docker/fedora42/build_rbenv.sh b/.gitlab/ci/docker/fedora43/build_rbenv.sh similarity index 100% rename from .gitlab/ci/docker/fedora42/build_rbenv.sh rename to .gitlab/ci/docker/fedora43/build_rbenv.sh
diff --git a/.gitlab/ci/docker/fedora43/build_rust.sh b/.gitlab/ci/docker/fedora43/build_rust.sh new file mode 100755 index 0000000..5ab91f7 --- /dev/null +++ b/.gitlab/ci/docker/fedora43/build_rust.sh
@@ -0,0 +1,10 @@ +#!/bin/sh + +set -e + +typos_version=1.44.0 +cargo install --root /usr/local --version "$typos_version" typos-cli + +strip /usr/local/bin/typos + +tar -C /usr/local -cf /root/rust.tar bin/typos
diff --git a/.gitlab/ci/docker/fedora42/build_rvm.sh b/.gitlab/ci/docker/fedora43/build_rvm.sh similarity index 100% rename from .gitlab/ci/docker/fedora42/build_rvm.sh rename to .gitlab/ci/docker/fedora43/build_rvm.sh
diff --git a/.gitlab/ci/docker/fedora43/deps_packages.lst b/.gitlab/ci/docker/fedora43/deps_packages.lst new file mode 100644 index 0000000..143c296 --- /dev/null +++ b/.gitlab/ci/docker/fedora43/deps_packages.lst
@@ -0,0 +1,148 @@ +glibc-locale-source + +# Install build requirements. +ncurses-devel +openssl-devel +qt5-qtbase-devel +qt6-qtbase-devel + +# Install development tools. +clang +clang-devel +clang-tools-extra +clang-tools-extra-devel +compiler-rt +flang +gcc-c++ +git-core +lfortran +llvm-devel +make +rust + +# Install optional external build dependencies. +bzip2-devel +expat-devel +jsoncpp-devel +libarchive-devel +libcurl-devel +libuv-devel +libzstd-devel +rhash-devel +xz-devel +zlib-devel + +# Install documentation tools. +python3-sphinx +python3-sphinxcontrib-qthelp +qt5-qttools-devel +qt6-qttools-devel +texinfo + +# Install lint tools. +clang-analyzer +clazy +codespell +valgrind + +# Tools needed for the test suite. +file +findutils +jq +which + +# Install ASM_NASM language toolchain. +nasm + +# Packages needed to test CTest. +breezy +mercurial +subversion + +# Packages needed to test CPack. +appstream +patchelf +rpm-build + +# Packages needed to test find modules. +alsa-lib-devel +aspell +aspell-devel +aspell-en +blas-devel +boost-devel +boost-python3-devel +bzip2-devel +cups-devel +DevIL-devel +doxygen +expat-devel +fontconfig-devel +freeglut-devel +freetype-devel +gdal-devel +gettext +giflib-devel +glew-devel +gmock +gnutls-devel +grpc-devel +grpc-plugins +gsl-devel +gtest-devel +gtk2-devel +hdf5-devel +hdf5-mpich-devel +hdf5-openmpi-devel +ImageMagick-c++-devel +jasper-devel +java-21-openjdk-devel +jsoncpp-devel +lapack-devel +libarchive-devel +libcurl-devel +libicu-devel +libinput-devel +libjpeg-turbo-devel +libomp-devel +libpng-devel +libtiff-devel +libuv-devel +libxml2-devel +libxslt-devel +mpich-devel +openal-soft-devel +openmpi-devel +opensp-devel +patch +perl +postgresql-server-devel +protobuf-c-devel +protobuf-devel +protobuf-lite-devel +pypy2 +pypy2-devel +pypy3 +pypy3-devel +python3 +python3-devel +python3-jsmin +python3-jsonschema +python3-numpy +rbenv +ruby +ruby-build-rbenv +ruby-devel +rubygems +SDL-devel +sqlite-devel +swig +systemd-devel +unixODBC-devel +wxGTK-devel +xalan-c-devel +xerces-c-devel +xz-devel + +# Packages needed to test third-party binaries. +ncurses-compat-libs
diff --git a/.gitlab/ci/docker/fedora42/dnf.conf b/.gitlab/ci/docker/fedora43/dnf.conf similarity index 100% rename from .gitlab/ci/docker/fedora42/dnf.conf rename to .gitlab/ci/docker/fedora43/dnf.conf
diff --git a/.gitlab/ci/docker/fedora43/install_deps.sh b/.gitlab/ci/docker/fedora43/install_deps.sh new file mode 100755 index 0000000..cc3480a --- /dev/null +++ b/.gitlab/ci/docker/fedora43/install_deps.sh
@@ -0,0 +1,14 @@ +#!/bin/sh + +set -e + +dnf install -y $(grep '^[^#]\+$' /root/deps_packages.lst) + +# Add locales. +localedef --no-archive --inputfile=en_US --charmap=ISO-8859-1 en_US.ISO-8859-1 +localedef --no-archive --inputfile=en_US --charmap=UTF-8 en_US.UTF-8 + +# Remove tests for Python packages +for v in 3.14; do + find /usr/lib64/python${v}/site-packages -type d -a -name tests -exec rm -rf {} + +done
diff --git a/.gitlab/ci/docker/fedora42/iwyu_packages.lst b/.gitlab/ci/docker/fedora43/iwyu_packages.lst similarity index 100% rename from .gitlab/ci/docker/fedora42/iwyu_packages.lst rename to .gitlab/ci/docker/fedora43/iwyu_packages.lst
diff --git a/.gitlab/ci/docker/fedora42/rbenv_packages.lst b/.gitlab/ci/docker/fedora43/rbenv_packages.lst similarity index 100% rename from .gitlab/ci/docker/fedora42/rbenv_packages.lst rename to .gitlab/ci/docker/fedora43/rbenv_packages.lst
diff --git a/.gitlab/ci/docker/fedora42/rust_packages.lst b/.gitlab/ci/docker/fedora43/rust_packages.lst similarity index 100% rename from .gitlab/ci/docker/fedora42/rust_packages.lst rename to .gitlab/ci/docker/fedora43/rust_packages.lst
diff --git a/.gitlab/ci/docker/fedora42/rvm_packages.lst b/.gitlab/ci/docker/fedora43/rvm_packages.lst similarity index 100% rename from .gitlab/ci/docker/fedora42/rvm_packages.lst rename to .gitlab/ci/docker/fedora43/rvm_packages.lst
diff --git a/.gitlab/ci/download_qt.cmake b/.gitlab/ci/download_qt.cmake index d2560dd..759365e 100644 --- a/.gitlab/ci/download_qt.cmake +++ b/.gitlab/ci/download_qt.cmake
@@ -1,74 +1,49 @@ cmake_minimum_required(VERSION 3.29) -# Input variables. -set(qt_version_major "5") -set(qt_version_minor "15") -set(qt_version_patch "1") - -# Combined version variables. -set(qt_version "${qt_version_major}.${qt_version_minor}.${qt_version_patch}") -set(qt_version_nodot "${qt_version_major}${qt_version_minor}${qt_version_patch}") +set(qt_tar_workdir ".gitlab") # Files needed to download. set(qt_files) if ("$ENV{CMAKE_CONFIGURATION}" MATCHES "windows.*package") - set(qt_url_root "https://cmake.org/files/dependencies") + set(qt_url_root "https://cmake.org/files/dependencies/qt") set(qt_url_path "") if ("$ENV{CMAKE_CONFIGURATION}" MATCHES "windows_x86_64_package") - list(APPEND qt_files "qt-5.15.10-win-x86_64-msvc_v142-1.zip") - set(qt_subdir "qt-5.15.10-win-x86_64-msvc_v142-1") + list(APPEND qt_files "qt-6.10.1-win-x86_64-msvc_v145-1.zip") + set(qt_subdir "qt-6.10.1-win-x86_64-msvc_v145-1") elseif ("$ENV{CMAKE_CONFIGURATION}" MATCHES "windows_i386_package") - list(APPEND qt_files "qt-5.15.10-win-i386-msvc_v142-1.zip") - set(qt_subdir "qt-5.15.10-win-i386-msvc_v142-1") + list(APPEND qt_files "qt-6.10.1-win-i386-msvc_v145-1.zip") + set(qt_subdir "qt-6.10.1-win-i386-msvc_v145-1") elseif ("$ENV{CMAKE_CONFIGURATION}" MATCHES "windows_arm64_package") - list(APPEND qt_files "qt-6.3.0-win-arm64-msvc_v143-1.zip") - set(qt_subdir "qt-6.3.0-win-arm64-msvc_v143-1") - list(APPEND qt_files "qt-6.3.0-win-x86_64-msvc_v143-1.zip") - set(qt_host_subdir "qt-6.3.0-win-x86_64-msvc_v143-1") + list(APPEND qt_files "qt-6.10.1-win-arm64-msvc_v145-1.zip") + set(qt_subdir "qt-6.10.1-win-arm64-msvc_v145-1") + list(APPEND qt_files "qt-6.10.1-win-x86_64-msvc_v145-1.zip") + set(qt_host_subdir "qt-6.10.1-win-x86_64-msvc_v145-1") else () message(FATAL_ERROR "Unknown arch to use for Qt") endif() elseif ("$ENV{CMAKE_CONFIGURATION}" MATCHES "windows") - # Determine the ABI to fetch for Qt. - if ("$ENV{CMAKE_CONFIGURATION}" MATCHES "vs2015") - set(qt_platform "windows_x86") - set(msvc_year "2015") - set(qt_abi "win64_msvc${msvc_year}_64") - elseif ("$ENV{CMAKE_CONFIGURATION}" MATCHES "vs2017" OR - "$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") - else () - message(FATAL_ERROR "Unknown ABI to use for Qt") - endif () - - set(qt_build_stamp "202009071110") - - set(qt_file_name_prefix "${qt_version}-0-${qt_build_stamp}") - - foreach (qt_component IN ITEMS qtbase qtwinextras) - list(APPEND qt_files - "${qt_file_name_prefix}${qt_component}-Windows-Windows_10-MSVC${msvc_year}-Windows-Windows_10-X86_64.7z") - endforeach () - - set(qt_subdir "${qt_version}/msvc${msvc_year}_64") - # This URL is only visible inside of Kitware's network. # Please use your own Qt Account to obtain these files. set(qt_url_root "https://paraview.org/files/dependencies/internal/qt") - set(qt_url_path "${qt_platform}/desktop/qt5_${qt_version_nodot}/qt.qt5.${qt_version_nodot}.${qt_abi}") + set(qt_url_path "windows_x86/desktop/qt6_693/qt6_693/qt.qt6.693.win64_msvc2022_64") + list(APPEND qt_files "6.9.3-0-202509261208qtbase-Windows-Windows_11_23H2-MSVC2022-Windows-Windows_11_23H2-X86_64.7z") + set(qt_subdir "qt-extract") + set(qt_tar_workdir ".gitlab/${qt_subdir}") elseif ("$ENV{CMAKE_CONFIGURATION}" MATCHES "macos") if ("$ENV{CMAKE_CONFIGURATION}" MATCHES "macos10.10_package") + set(qt_url_root "https://cmake.org/files/dependencies/qt") + set(qt_url_path "") list(APPEND qt_files "qt-5.9.9-macosx10.10-x86_64-arm64.tar.xz") set(qt_subdir "qt-5.9.9-macosx10.10-x86_64-arm64") else () - list(APPEND qt_files "qt-5.15.2-macosx10.13-x86_64-arm64.tar.xz") - set(qt_subdir "qt-5.15.2-macosx10.13-x86_64-arm64") + # This URL is only visible inside of Kitware's network. + # Please use your own Qt Account to obtain these files. + set(qt_url_root "https://www.paraview.org/files/dependencies/internal/qt") + set(qt_url_path "mac_x64/desktop/qt6_693/qt6_693/qt.qt6.693.clang_64") + list(APPEND qt_files "6.9.3-0-202509261207qtbase-MacOS-MacOS_15-Clang-MacOS-MacOS_15-X86_64-ARM64.7z") + set(qt_subdir "qt-extract") + set(qt_tar_workdir ".gitlab/${qt_subdir}") endif() - set(qt_url_root "https://cmake.org/files/dependencies") - set(qt_url_path "") else() message(FATAL_ERROR "Unknown OS to use for Qt") endif () @@ -109,12 +84,13 @@ endif () # Extract the file. + file(MAKE_DIRECTORY "${qt_tar_workdir}") execute_process( COMMAND "${CMAKE_COMMAND}" -E tar - xf "${qt_file}" - WORKING_DIRECTORY ".gitlab" + xf "${CMAKE_CURRENT_SOURCE_DIR}/.gitlab/${qt_file}" + WORKING_DIRECTORY "${qt_tar_workdir}" RESULT_VARIABLE res ERROR_VARIABLE err ERROR_STRIP_TRAILING_WHITESPACE) @@ -125,29 +101,6 @@ file(REMOVE "${qt_file}") endforeach () -# The Windows tarballs have some unfortunate permissions in them that prevent -# deletion when `git clean -ffdx` tries to clean up the directory. -if (qt_platform STREQUAL "windows_x86") - # Fix permissions. - file(TO_NATIVE_PATH ".gitlab/${qt_subdir}/*.*" native_qt_dir) - execute_process( - # Remove any read-only flags that aren't affected by `icacls`. - COMMAND - attrib - -r # Remove readonly flag - "${native_qt_dir}" - /d # Treat as a directory - /s # Recursive - /l # Don't dereference symlinks - RESULT_VARIABLE res - ERROR_VARIABLE err - ERROR_STRIP_TRAILING_WHITESPACE) - if (res) - message(FATAL_ERROR - "Failed to fix remove read-only flags in ${qt_file}: ${err}") - endif () -endif () - # Move to a predictable prefix. file(RENAME ".gitlab/${qt_subdir}"
diff --git a/.gitlab/ci/download_qt_hashes.cmake b/.gitlab/ci/download_qt_hashes.cmake index 1b9cf14..ea3220a 100644 --- a/.gitlab/ci/download_qt_hashes.cmake +++ b/.gitlab/ci/download_qt_hashes.cmake
@@ -2,20 +2,11 @@ # # sha256sum $files | awk '{ print "set(\"" $2 "_hash\" " $1 ")" }' >> $thisfile -set("5.15.1-0-202009071110qtbase-Windows-Windows_10-MSVC2019-Windows-Windows_10-X86_64.7z_hash" a5635124a135f383d9fb92bf628b018cff9f781addfd388926a367cda5b7cd38) -set("5.15.1-0-202009071110qtwinextras-Windows-Windows_10-MSVC2019-Windows-Windows_10-X86_64.7z_hash" 908947855b5d7a854886746365ac29e9296b5d64d4e18089641a6988167807d3) - -set("5.15.1-0-202009071110qtbase-Windows-Windows_10-MSVC2015-Windows-Windows_10-X86_64.7z_hash" 5d0d2e71e3b00cf88ac4c616b4b314a7e73871f325512821f53c464cdfee961f) -set("5.15.1-0-202009071110qtwinextras-Windows-Windows_10-MSVC2015-Windows-Windows_10-X86_64.7z_hash" 803e0234169464babb5305dedc21382e90c3266c6f9414ff0cff04be578681e1) - -set("5.15.1-0-202009071110qtbase-MacOS-MacOS_10_13-Clang-MacOS-MacOS_10_13-X86_64.7z_hash" df2813ce7c6cb4287abd7956cd1cb9d08312e4ac1208b6cb57af4df11b8ebba1) - set("qt-5.9.9-macosx10.10-x86_64-arm64.tar.xz_hash" d4449771afa0bc6a809c14f1e6d939e7732494cf059503ae451e2bfe8fc60cc1) -set("qt-5.15.2-macosx10.13-x86_64-arm64.tar.xz_hash" 7b9463a01c8beeee5bf8d01c70deff2d08561cd20aaf6f7a2f41cf8b68ce8a6b) +set("6.9.3-0-202509261207qtbase-MacOS-MacOS_15-Clang-MacOS-MacOS_15-X86_64-ARM64.7z_hash" 805144e619b7c7b0e9c985d929e1f290241d88b884218db3ad7d56bd579d6b4a) -set("qt-5.15.10-win-i386-msvc_v142-1.zip_hash" c158cebc054d3f4f09733772a8a04789e2884912d45782e8c0c5e6a0b2773e92) -set("qt-5.15.10-win-x86_64-msvc_v142-1.zip_hash" d55c017aef359f6aa8c592b18ba13cc120c749417b55671548970690126cd139) +set("6.9.3-0-202509261208qtbase-Windows-Windows_11_23H2-MSVC2022-Windows-Windows_11_23H2-X86_64.7z_hash" 94f8a097d3078661943446c9ecfee3fb4375d9b992a91a1a2d1856379c749d8d) -set("qt-6.3.0-win-arm64-msvc_v143-1.zip_hash" f794c035fd4ff9f04468e1787a60d93d7496119c0060c3173a76d24a6b551b14) -set("qt-6.3.0-win-i386-msvc_v143-1.zip_hash" 972bc707f78d11b44f360643ca4d0c898e761f7add43b96117d958c70d84a443) -set("qt-6.3.0-win-x86_64-msvc_v143-1.zip_hash" 4fb0aaebe184f40392f1bb246469dca591bfdfb8f915e19f921476222473ac90) +set("qt-6.10.1-win-arm64-msvc_v145-1.zip_hash" 59e150883f31c0e31a2890f06b6e434ad44505dba876fda4a7c0994c9b0bdfe1) +set("qt-6.10.1-win-i386-msvc_v145-1.zip_hash" 09100628aecb7cdde07040d7437c09830ed8c17720960b10339b114cb4bbf18b) +set("qt-6.10.1-win-x86_64-msvc_v145-1.zip_hash" 931f2354c715b30bc0ac35028f9d778aa552aa8a66580fc73c6a32384c5fa042)
diff --git a/.gitlab/ci/emsdk-env.sh b/.gitlab/ci/emsdk-env.sh new file mode 100644 index 0000000..c62e0e7 --- /dev/null +++ b/.gitlab/ci/emsdk-env.sh
@@ -0,0 +1,3 @@ +.gitlab/ci/emsdk.sh +. .gitlab/emsdk/emsdk_env.sh +em++ --version
diff --git a/.gitlab/ci/emsdk.sh b/.gitlab/ci/emsdk.sh new file mode 100755 index 0000000..0a798a2 --- /dev/null +++ b/.gitlab/ci/emsdk.sh
@@ -0,0 +1,25 @@ +#!/bin/sh + +set -e + +case "$(uname -s)-$(uname -m)" in + Linux-x86_64) + ;; + *) + echo "Unrecognized platform $(uname -s)-$(uname -m)" + exit 1 + ;; +esac + +cd .gitlab + +version=4.0.9 +dirname="emsdk-$version" +filename="$dirname.tar.gz" +curl -OJL "https://github.com/emscripten-core/emsdk/archive/refs/tags/$version.tar.gz" +tar xzf "$filename" +mv "$dirname" emsdk +emsdk/emsdk install "$version" +emsdk/emsdk activate "$version" + +rm -f "$filename"
diff --git a/.gitlab/ci/env.sh b/.gitlab/ci/env.sh index de5cf6f..8b66654 100644 --- a/.gitlab/ci/env.sh +++ b/.gitlab/ci/env.sh
@@ -19,10 +19,21 @@ test "$(git -C "$CI_PROJECT_DIR/work/cmake" rev-parse HEAD)" = "$(git -C "$CI_PROJECT_DIR" rev-parse HEAD)" fi +# Default to a UTF-8 locale. The per-job environment may override it. +locales="$(locale -a 2>/dev/null)" +if echo "$locales" | grep -qE '^C\.(UTF-8|utf8)$'; then + export LANG=C.UTF-8 +elif echo "$locales" | grep -qE '^en_US\.(UTF-8|utf8)$'; then + export LANG=en_US.UTF-8 +fi + if test -r ".gitlab/ci/env_${CMAKE_CONFIGURATION}.sh"; then source ".gitlab/ci/env_${CMAKE_CONFIGURATION}.sh" fi +# Report the selected locale. +echo "locale: $(locale | grep '^LANG=') with $(locale -k charmap)" + case "$(uname -s)-$(uname -m)" in Linux-*) # Remove superuser tools from PATH.
diff --git a/.gitlab/ci/env_cuda13.0_nvidia_fastbuild.sh b/.gitlab/ci/env_cuda13.0_nvidia_fastbuild.sh new file mode 100644 index 0000000..5e8b2df --- /dev/null +++ b/.gitlab/ci/env_cuda13.0_nvidia_fastbuild.sh
@@ -0,0 +1 @@ +source .gitlab/ci/fastbuild-env.sh
diff --git a/.gitlab/ci/env_debian12_hip_radeon.sh b/.gitlab/ci/env_debian12_hip_radeon.sh deleted file mode 100644 index 793c985..0000000 --- a/.gitlab/ci/env_debian12_hip_radeon.sh +++ /dev/null
@@ -1,9 +0,0 @@ -export HIPCXX=/usr/bin/clang++-15 -export HIPFLAGS='--rocm-path=/usr --rocm-device-lib-path=/usr/lib/x86_64-linux-gnu/amdgcn/bitcode' - -# FIXME(debian): Clang is supposed to automatically parse a HIP version file. -# The ROCm installer places it at '$prefix/bin/.hipVersion', but the package -# on Debian moves it to '$prefix/share/hip/version'. llvm-toolchain package -# version 15.0.7-4 has 'debian/patches/amdgpu/usr-search-paths.patch' for this, -# but Debian 12 currently provides version 15.0.6-4 without the patch. -export HIPFLAGS="$HIPFLAGS --hip-version=5.2"
diff --git a/.gitlab/ci/env_debian12_makefiles_clang.sh b/.gitlab/ci/env_debian12_makefiles_clang.sh deleted file mode 100644 index e4ee249..0000000 --- a/.gitlab/ci/env_debian12_makefiles_clang.sh +++ /dev/null
@@ -1,7 +0,0 @@ -if test "$CMAKE_CI_NIGHTLY" = "true"; then - source .gitlab/ci/iar-env.sh - source .gitlab/ci/ticlang-env.sh -fi - -export CC=/usr/bin/clang-15 -export CXX=/usr/bin/clang++-15
diff --git a/.gitlab/ci/env_debian12_ninja_clang.sh b/.gitlab/ci/env_debian12_ninja_clang.sh deleted file mode 100644 index e4ee249..0000000 --- a/.gitlab/ci/env_debian12_ninja_clang.sh +++ /dev/null
@@ -1,7 +0,0 @@ -if test "$CMAKE_CI_NIGHTLY" = "true"; then - source .gitlab/ci/iar-env.sh - source .gitlab/ci/ticlang-env.sh -fi - -export CC=/usr/bin/clang-15 -export CXX=/usr/bin/clang++-15
diff --git a/.gitlab/ci/env_debian12_aarch64_extdeps.sh b/.gitlab/ci/env_debian13_aarch64_extdeps.sh similarity index 100% rename from .gitlab/ci/env_debian12_aarch64_extdeps.sh rename to .gitlab/ci/env_debian13_aarch64_extdeps.sh
diff --git a/.gitlab/ci/env_debian12_extdeps.sh b/.gitlab/ci/env_debian13_extdeps.sh similarity index 100% rename from .gitlab/ci/env_debian12_extdeps.sh rename to .gitlab/ci/env_debian13_extdeps.sh
diff --git a/.gitlab/ci/env_debian13_hip_radeon.sh b/.gitlab/ci/env_debian13_hip_radeon.sh new file mode 100644 index 0000000..0f7df8d --- /dev/null +++ b/.gitlab/ci/env_debian13_hip_radeon.sh
@@ -0,0 +1 @@ +export HIPCXX=/usr/bin/clang++-17
diff --git a/.gitlab/ci/env_debian13_makefiles_clang.sh b/.gitlab/ci/env_debian13_makefiles_clang.sh new file mode 100644 index 0000000..8878718 --- /dev/null +++ b/.gitlab/ci/env_debian13_makefiles_clang.sh
@@ -0,0 +1,8 @@ +if test "$CMAKE_CI_NIGHTLY" = "true"; then + source .gitlab/ci/iar-env.sh + source .gitlab/ci/ticlang-env.sh + source .gitlab/ci/emsdk-env.sh +fi + +export CC=/usr/bin/clang-19 +export CXX=/usr/bin/clang++-19
diff --git a/.gitlab/ci/env_debian12_ninja.sh b/.gitlab/ci/env_debian13_ninja.sh similarity index 100% rename from .gitlab/ci/env_debian12_ninja.sh rename to .gitlab/ci/env_debian13_ninja.sh
diff --git a/.gitlab/ci/env_debian13_ninja_clang.sh b/.gitlab/ci/env_debian13_ninja_clang.sh new file mode 100644 index 0000000..8878718 --- /dev/null +++ b/.gitlab/ci/env_debian13_ninja_clang.sh
@@ -0,0 +1,8 @@ +if test "$CMAKE_CI_NIGHTLY" = "true"; then + source .gitlab/ci/iar-env.sh + source .gitlab/ci/ticlang-env.sh + source .gitlab/ci/emsdk-env.sh +fi + +export CC=/usr/bin/clang-19 +export CXX=/usr/bin/clang++-19
diff --git a/.gitlab/ci/env_debian12_ninja_multi_symlinked.sh b/.gitlab/ci/env_debian13_ninja_multi_symlinked.sh similarity index 100% rename from .gitlab/ci/env_debian12_ninja_multi_symlinked.sh rename to .gitlab/ci/env_debian13_ninja_multi_symlinked.sh
diff --git a/.gitlab/ci/env_fedora42_common_clang.sh b/.gitlab/ci/env_fedora42_common_clang.sh deleted file mode 100644 index 43775d2..0000000 --- a/.gitlab/ci/env_fedora42_common_clang.sh +++ /dev/null
@@ -1,3 +0,0 @@ -export CC=/usr/bin/clang-20 -export CXX=/usr/bin/clang++-20 -export FC=/usr/bin/flang-20
diff --git a/.gitlab/ci/env_fedora42_extdeps.sh b/.gitlab/ci/env_fedora42_extdeps.sh deleted file mode 100644 index 7076e18..0000000 --- a/.gitlab/ci/env_fedora42_extdeps.sh +++ /dev/null
@@ -1 +0,0 @@ -source .gitlab/ci/env_extdeps_common.sh
diff --git a/.gitlab/ci/env_fedora42_hip_radeon.sh b/.gitlab/ci/env_fedora42_hip_radeon.sh deleted file mode 100644 index cc57cc7..0000000 --- a/.gitlab/ci/env_fedora42_hip_radeon.sh +++ /dev/null
@@ -1,2 +0,0 @@ -export HIPCXX=/usr/bin/clang++-20 -export HIPFLAGS='--rocm-path=/usr --rocm-device-lib-path=/usr/lib64/rocm/llvm/lib/clang/18/amdgcn/bitcode'
diff --git a/.gitlab/ci/env_fedora42_makefiles.sh b/.gitlab/ci/env_fedora42_makefiles.sh deleted file mode 100644 index 217ff30..0000000 --- a/.gitlab/ci/env_fedora42_makefiles.sh +++ /dev/null
@@ -1,3 +0,0 @@ -if test "$CMAKE_CI_NIGHTLY" = "true"; then - source .gitlab/ci/ispc-env.sh -fi
diff --git a/.gitlab/ci/env_fedora42_makefiles_clang.sh b/.gitlab/ci/env_fedora42_makefiles_clang.sh deleted file mode 100644 index 8067256..0000000 --- a/.gitlab/ci/env_fedora42_makefiles_clang.sh +++ /dev/null
@@ -1 +0,0 @@ -. .gitlab/ci/env_fedora42_common_clang.sh
diff --git a/.gitlab/ci/env_fedora42_makefiles_lfortran.sh b/.gitlab/ci/env_fedora42_makefiles_lfortran.sh deleted file mode 100644 index 9d559f9..0000000 --- a/.gitlab/ci/env_fedora42_makefiles_lfortran.sh +++ /dev/null
@@ -1 +0,0 @@ -. .gitlab/ci/env_fedora42_common_lfortran.sh
diff --git a/.gitlab/ci/env_fedora42_makefiles_symlinked.cmake b/.gitlab/ci/env_fedora42_makefiles_symlinked.cmake deleted file mode 100644 index fcf100a..0000000 --- a/.gitlab/ci/env_fedora42_makefiles_symlinked.cmake +++ /dev/null
@@ -1 +0,0 @@ -include("${CMAKE_CURRENT_LIST_DIR}/env_fedora42_makefiles.cmake")
diff --git a/.gitlab/ci/env_fedora42_makefiles_symlinked.sh b/.gitlab/ci/env_fedora42_makefiles_symlinked.sh deleted file mode 100644 index c18e125..0000000 --- a/.gitlab/ci/env_fedora42_makefiles_symlinked.sh +++ /dev/null
@@ -1 +0,0 @@ -. .gitlab/ci/env_fedora42_makefiles.sh
diff --git a/.gitlab/ci/env_fedora42_ninja.sh b/.gitlab/ci/env_fedora42_ninja.sh deleted file mode 100644 index 217ff30..0000000 --- a/.gitlab/ci/env_fedora42_ninja.sh +++ /dev/null
@@ -1,3 +0,0 @@ -if test "$CMAKE_CI_NIGHTLY" = "true"; then - source .gitlab/ci/ispc-env.sh -fi
diff --git a/.gitlab/ci/env_fedora42_ninja_clang.sh b/.gitlab/ci/env_fedora42_ninja_clang.sh deleted file mode 100644 index 8067256..0000000 --- a/.gitlab/ci/env_fedora42_ninja_clang.sh +++ /dev/null
@@ -1 +0,0 @@ -. .gitlab/ci/env_fedora42_common_clang.sh
diff --git a/.gitlab/ci/env_fedora42_ninja_lfortran.sh b/.gitlab/ci/env_fedora42_ninja_lfortran.sh deleted file mode 100644 index 9d559f9..0000000 --- a/.gitlab/ci/env_fedora42_ninja_lfortran.sh +++ /dev/null
@@ -1 +0,0 @@ -. .gitlab/ci/env_fedora42_common_lfortran.sh
diff --git a/.gitlab/ci/env_fedora42_ninja_multi_clang.sh b/.gitlab/ci/env_fedora42_ninja_multi_clang.sh deleted file mode 100644 index 8067256..0000000 --- a/.gitlab/ci/env_fedora42_ninja_multi_clang.sh +++ /dev/null
@@ -1 +0,0 @@ -. .gitlab/ci/env_fedora42_common_clang.sh
diff --git a/.gitlab/ci/env_fedora42_asan.sh b/.gitlab/ci/env_fedora43_asan.sh similarity index 100% rename from .gitlab/ci/env_fedora42_asan.sh rename to .gitlab/ci/env_fedora43_asan.sh
diff --git a/.gitlab/ci/env_fedora43_bullseye_coverage.sh b/.gitlab/ci/env_fedora43_bullseye_coverage.sh new file mode 100644 index 0000000..57f92ab --- /dev/null +++ b/.gitlab/ci/env_fedora43_bullseye_coverage.sh
@@ -0,0 +1,10 @@ +source .gitlab/ci/bullseye-env.sh + +# Store Bullseye activation state in the work directory. +export COVAPPDATADIR="$CI_PROJECT_DIR/build/Bullseye" + +# Collect all coverage in a single location. +export COVFILE="$COVAPPDATADIR/CMake.cov" + +# Suppress the Bullseye startup banner on compilation. +export COVCOPT="--no-banner"
diff --git a/.gitlab/ci/env_fedora42_clang_analyzer.sh b/.gitlab/ci/env_fedora43_clang_analyzer.sh similarity index 100% rename from .gitlab/ci/env_fedora42_clang_analyzer.sh rename to .gitlab/ci/env_fedora43_clang_analyzer.sh
diff --git a/.gitlab/ci/env_fedora43_clang_fuzzing.sh b/.gitlab/ci/env_fedora43_clang_fuzzing.sh new file mode 100644 index 0000000..729fb37 --- /dev/null +++ b/.gitlab/ci/env_fedora43_clang_fuzzing.sh
@@ -0,0 +1,5 @@ +export CC=/usr/bin/clang +export CXX=/usr/bin/clang++ + +export CFLAGS=-fsanitize=fuzzer-no-link,address +export CXXFLAGS=-fsanitize=fuzzer-no-link,address
diff --git a/.gitlab/ci/env_fedora43_clazy.sh b/.gitlab/ci/env_fedora43_clazy.sh new file mode 100644 index 0000000..007c52d --- /dev/null +++ b/.gitlab/ci/env_fedora43_clazy.sh
@@ -0,0 +1,25 @@ +export CC=/usr/bin/clang +export CXX=/usr/bin/clazy +export CLANGXX=/usr/bin/clang++ + +export CLAZY_CHECKS="level2\ +,no-base-class-event\ +,no-connect-3arg-lambda\ +,no-connect-by-name\ +,no-container-inside-loop\ +,no-copyable-polymorphic\ +,no-ctor-missing-parent-argument\ +,no-function-args-by-ref\ +,no-missing-qobject-macro\ +,no-non-pod-global-static\ +,no-old-style-connect\ +,no-qproperty-without-notify\ +,no-qstring-allocations\ +,no-range-loop-detach\ +,no-range-loop-reference\ +,no-reserve-candidates\ +,no-rule-of-three\ +,no-rule-of-two-soft\ +,no-static-pmf\ +,no-strict-iterators\ +"
diff --git a/.gitlab/ci/env_fedora43_common_clang.sh b/.gitlab/ci/env_fedora43_common_clang.sh new file mode 100644 index 0000000..55533e7 --- /dev/null +++ b/.gitlab/ci/env_fedora43_common_clang.sh
@@ -0,0 +1,3 @@ +export CC=/usr/bin/clang-21 +export CXX=/usr/bin/clang++-21 +export FC=/usr/bin/flang-21
diff --git a/.gitlab/ci/env_fedora42_common_lfortran.sh b/.gitlab/ci/env_fedora43_common_lfortran.sh similarity index 100% rename from .gitlab/ci/env_fedora42_common_lfortran.sh rename to .gitlab/ci/env_fedora43_common_lfortran.sh
diff --git a/.gitlab/ci/env_debian12_extdeps.sh b/.gitlab/ci/env_fedora43_extdeps.sh similarity index 100% copy from .gitlab/ci/env_debian12_extdeps.sh copy to .gitlab/ci/env_fedora43_extdeps.sh
diff --git a/.gitlab/ci/env_fedora43_fastbuild.sh b/.gitlab/ci/env_fedora43_fastbuild.sh new file mode 100644 index 0000000..5e8b2df --- /dev/null +++ b/.gitlab/ci/env_fedora43_fastbuild.sh
@@ -0,0 +1 @@ +source .gitlab/ci/fastbuild-env.sh
diff --git a/.gitlab/ci/env_fedora43_hip_radeon.sh b/.gitlab/ci/env_fedora43_hip_radeon.sh new file mode 100644 index 0000000..2c942a8 --- /dev/null +++ b/.gitlab/ci/env_fedora43_hip_radeon.sh
@@ -0,0 +1,2 @@ +export HIPCXX=/usr/bin/clang++-21 +export HIPFLAGS='--rocm-path=/usr --rocm-device-lib-path=/usr/lib64/rocm/llvm/lib/clang/19/amdgcn/bitcode'
diff --git a/.gitlab/ci/env_fedora42_makefiles.cmake b/.gitlab/ci/env_fedora43_makefiles.cmake similarity index 100% rename from .gitlab/ci/env_fedora42_makefiles.cmake rename to .gitlab/ci/env_fedora43_makefiles.cmake
diff --git a/.gitlab/ci/env_fedora43_makefiles.sh b/.gitlab/ci/env_fedora43_makefiles.sh new file mode 100644 index 0000000..f02e487 --- /dev/null +++ b/.gitlab/ci/env_fedora43_makefiles.sh
@@ -0,0 +1,6 @@ +if test "$CMAKE_CI_NIGHTLY" = "true"; then + source .gitlab/ci/ispc-env.sh +fi + +# Test in a Latin-1 locale. +export LANG=en_US.ISO-8859-1
diff --git a/.gitlab/ci/env_fedora43_makefiles_clang.sh b/.gitlab/ci/env_fedora43_makefiles_clang.sh new file mode 100644 index 0000000..3953f88 --- /dev/null +++ b/.gitlab/ci/env_fedora43_makefiles_clang.sh
@@ -0,0 +1 @@ +. .gitlab/ci/env_fedora43_common_clang.sh
diff --git a/.gitlab/ci/env_fedora43_makefiles_lfortran.sh b/.gitlab/ci/env_fedora43_makefiles_lfortran.sh new file mode 100644 index 0000000..6b02339 --- /dev/null +++ b/.gitlab/ci/env_fedora43_makefiles_lfortran.sh
@@ -0,0 +1 @@ +. .gitlab/ci/env_fedora43_common_lfortran.sh
diff --git a/.gitlab/ci/env_fedora43_makefiles_symlinked.cmake b/.gitlab/ci/env_fedora43_makefiles_symlinked.cmake new file mode 100644 index 0000000..fb004e8 --- /dev/null +++ b/.gitlab/ci/env_fedora43_makefiles_symlinked.cmake
@@ -0,0 +1 @@ +include("${CMAKE_CURRENT_LIST_DIR}/env_fedora43_makefiles.cmake")
diff --git a/.gitlab/ci/env_fedora43_makefiles_symlinked.sh b/.gitlab/ci/env_fedora43_makefiles_symlinked.sh new file mode 100644 index 0000000..448b592 --- /dev/null +++ b/.gitlab/ci/env_fedora43_makefiles_symlinked.sh
@@ -0,0 +1 @@ +. .gitlab/ci/env_fedora43_makefiles.sh
diff --git a/.gitlab/ci/env_fedora43_ninja.sh b/.gitlab/ci/env_fedora43_ninja.sh new file mode 100644 index 0000000..0ef4bce --- /dev/null +++ b/.gitlab/ci/env_fedora43_ninja.sh
@@ -0,0 +1,7 @@ +if test "$CMAKE_CI_NIGHTLY" = "true"; then + source .gitlab/ci/appimagetool-env.sh + source .gitlab/ci/ispc-env.sh +fi + +# Test in a UTF-8 locale. +export LANG=en_US.UTF-8
diff --git a/.gitlab/ci/env_fedora43_ninja_clang.sh b/.gitlab/ci/env_fedora43_ninja_clang.sh new file mode 100644 index 0000000..3953f88 --- /dev/null +++ b/.gitlab/ci/env_fedora43_ninja_clang.sh
@@ -0,0 +1 @@ +. .gitlab/ci/env_fedora43_common_clang.sh
diff --git a/.gitlab/ci/env_fedora43_ninja_instrumentation.sh b/.gitlab/ci/env_fedora43_ninja_instrumentation.sh new file mode 100644 index 0000000..cc89d0b --- /dev/null +++ b/.gitlab/ci/env_fedora43_ninja_instrumentation.sh
@@ -0,0 +1 @@ +source .gitlab/ci/env_fedora43_ninja.sh
diff --git a/.gitlab/ci/env_fedora43_ninja_lfortran.sh b/.gitlab/ci/env_fedora43_ninja_lfortran.sh new file mode 100644 index 0000000..6b02339 --- /dev/null +++ b/.gitlab/ci/env_fedora43_ninja_lfortran.sh
@@ -0,0 +1 @@ +. .gitlab/ci/env_fedora43_common_lfortran.sh
diff --git a/.gitlab/ci/env_fedora42_ninja_multi.sh b/.gitlab/ci/env_fedora43_ninja_multi.sh similarity index 100% rename from .gitlab/ci/env_fedora42_ninja_multi.sh rename to .gitlab/ci/env_fedora43_ninja_multi.sh
diff --git a/.gitlab/ci/env_fedora43_ninja_multi_clang.sh b/.gitlab/ci/env_fedora43_ninja_multi_clang.sh new file mode 100644 index 0000000..3953f88 --- /dev/null +++ b/.gitlab/ci/env_fedora43_ninja_multi_clang.sh
@@ -0,0 +1 @@ +. .gitlab/ci/env_fedora43_common_clang.sh
diff --git a/.gitlab/ci/env_fedora43_ninja_valgrind.sh b/.gitlab/ci/env_fedora43_ninja_valgrind.sh new file mode 100644 index 0000000..cc89d0b --- /dev/null +++ b/.gitlab/ci/env_fedora43_ninja_valgrind.sh
@@ -0,0 +1 @@ +source .gitlab/ci/env_fedora43_ninja.sh
diff --git a/.gitlab/ci/env_macos_arm64_fastbuild.sh b/.gitlab/ci/env_macos_arm64_fastbuild.sh new file mode 100644 index 0000000..6b25127 --- /dev/null +++ b/.gitlab/ci/env_macos_arm64_fastbuild.sh
@@ -0,0 +1 @@ +. .gitlab/ci/fastbuild-env.sh
diff --git a/.gitlab/ci/env_macos_package.sh b/.gitlab/ci/env_macos_package.sh deleted file mode 100644 index e810f63..0000000 --- a/.gitlab/ci/env_macos_package.sh +++ /dev/null
@@ -1 +0,0 @@ -. .gitlab/ci/macos-env.sh
diff --git a/.gitlab/ci/env_macos_x86_64_makefiles.sh b/.gitlab/ci/env_macos_x86_64_makefiles.sh index 7496372..dca8dd7 100644 --- a/.gitlab/ci/env_macos_x86_64_makefiles.sh +++ b/.gitlab/ci/env_macos_x86_64_makefiles.sh
@@ -2,3 +2,4 @@ if test "$CMAKE_CI_NIGHTLY" = "true"; then source .gitlab/ci/ispc-env.sh fi +export CFLAGS=-Wstrict-prototypes
diff --git a/.gitlab/ci/env_windows_arm64_vs2022_ninja.ps1 b/.gitlab/ci/env_windows_arm64_vs2026_ninja.ps1 similarity index 100% rename from .gitlab/ci/env_windows_arm64_vs2022_ninja.ps1 rename to .gitlab/ci/env_windows_arm64_vs2026_ninja.ps1
diff --git a/.gitlab/ci/env_windows_vs2026_x64.ps1 b/.gitlab/ci/env_windows_vs2026_x64.ps1 new file mode 100644 index 0000000..42aec11 --- /dev/null +++ b/.gitlab/ci/env_windows_vs2026_x64.ps1
@@ -0,0 +1,4 @@ +if ("$env:CMAKE_CI_NIGHTLY" -eq "true") { + $cmake = "build\install\bin\cmake" + . ".gitlab/ci/qt-env.ps1" +}
diff --git a/.gitlab/ci/env_windows_vs2026_x64_fastbuild.ps1 b/.gitlab/ci/env_windows_vs2026_x64_fastbuild.ps1 new file mode 100644 index 0000000..803fefc --- /dev/null +++ b/.gitlab/ci/env_windows_vs2026_x64_fastbuild.ps1
@@ -0,0 +1,2 @@ +. .gitlab/ci/fastbuild-env.ps1 +Invoke-Expression -Command .gitlab/ci/vcvarsall.ps1
diff --git a/.gitlab/ci/env_windows_vs2022_x64_jom.ps1 b/.gitlab/ci/env_windows_vs2026_x64_jom.ps1 similarity index 100% rename from .gitlab/ci/env_windows_vs2022_x64_jom.ps1 rename to .gitlab/ci/env_windows_vs2026_x64_jom.ps1
diff --git a/.gitlab/ci/env_windows_vs2022_x64_ninja.ps1 b/.gitlab/ci/env_windows_vs2026_x64_ninja.ps1 similarity index 100% rename from .gitlab/ci/env_windows_vs2022_x64_ninja.ps1 rename to .gitlab/ci/env_windows_vs2026_x64_ninja.ps1
diff --git a/.gitlab/ci/env_windows_vs2022_x64_ninja_multi.ps1 b/.gitlab/ci/env_windows_vs2026_x64_ninja_multi.ps1 similarity index 100% rename from .gitlab/ci/env_windows_vs2022_x64_ninja_multi.ps1 rename to .gitlab/ci/env_windows_vs2026_x64_ninja_multi.ps1
diff --git a/.gitlab/ci/env_windows_vs2022_x64_nmake.ps1 b/.gitlab/ci/env_windows_vs2026_x64_nmake.ps1 similarity index 100% rename from .gitlab/ci/env_windows_vs2022_x64_nmake.ps1 rename to .gitlab/ci/env_windows_vs2026_x64_nmake.ps1
diff --git a/.gitlab/ci/fastbuild-env.ps1 b/.gitlab/ci/fastbuild-env.ps1 new file mode 100644 index 0000000..9b7cc8f --- /dev/null +++ b/.gitlab/ci/fastbuild-env.ps1
@@ -0,0 +1,4 @@ +$pwdpath = $pwd.Path +& "$pwsh" -File ".gitlab/ci/fastbuild.ps1" +Set-Item -Force -Path "env:PATH" -Value "$pwdpath\.gitlab\fastbuild;$env:PATH" +Write-Host "fbuild version: $(fbuild -version)"
diff --git a/.gitlab/ci/fastbuild-env.sh b/.gitlab/ci/fastbuild-env.sh new file mode 100644 index 0000000..2bdf524 --- /dev/null +++ b/.gitlab/ci/fastbuild-env.sh
@@ -0,0 +1,3 @@ +.gitlab/ci/fastbuild.sh +export PATH=$PWD/.gitlab/fastbuild:$PATH +fbuild -version
diff --git a/.gitlab/ci/fastbuild.ps1 b/.gitlab/ci/fastbuild.ps1 new file mode 100644 index 0000000..ac74fcb --- /dev/null +++ b/.gitlab/ci/fastbuild.ps1
@@ -0,0 +1,24 @@ +$erroractionpreference = "stop" + +if ("$env:PROCESSOR_ARCHITECTURE" -eq "AMD64") { + $sha256sum = "65EA2572275CD326116F39047F60008D8F90373AF1EB419C1CF1DE65379321AC" + $filename = "FASTBuild-Windows-x64-v1.15" +} else { + throw ('unknown PROCESSOR_ARCHITECTURE: ' + "$env:PROCESSOR_ARCHITECTURE") +} + +$tarball = "$filename.zip" + +$outdir = $pwd.Path +$outdir = "$outdir\.gitlab" +$ProgressPreference = 'SilentlyContinue' +# This URL is only visible inside of Kitware's network. See above filename table. +Invoke-WebRequest -Uri "https://cmake.org/files/dependencies/internal/$tarball" -OutFile "$outdir\$tarball" +$hash = Get-FileHash "$outdir\$tarball" -Algorithm SHA256 +if ($hash.Hash -ne $sha256sum) { + exit 1 +} + +Add-Type -AssemblyName System.IO.Compression.FileSystem +[System.IO.Compression.ZipFile]::ExtractToDirectory("$outdir\$tarball", "$outdir\fastbuild") +Remove-Item "$outdir\$tarball"
diff --git a/.gitlab/ci/fastbuild.sh b/.gitlab/ci/fastbuild.sh new file mode 100755 index 0000000..3a6625d --- /dev/null +++ b/.gitlab/ci/fastbuild.sh
@@ -0,0 +1,37 @@ +#!/bin/sh + +set -e + +case "$(uname -s)-$(uname -m)" in + Linux-x86_64) + shatool="sha256sum" + sha256sum="2c7b4c833c7f2846119aaa72bfa92df5b7da1aa17a0e62187ac0bbcbbf5cce8e" + filename="FASTBuild-Linux-x64-v1.15" + exenames="fastbuild/fbuild fastbuild/fbuildworker" + ;; + Darwin-*) + shatool="shasum -a 256" + sha256sum="875fedc71a2b479b22e90fcc77db75513b1d88794fd71cfe3889f41b225efbaa" + filename="FASTBuild-OSX-x64+ARM-v1.15" + exenames="fastbuild/FBuild fastbuild/FBuildWorker" + ;; + *) + echo "Unrecognized platform $(uname -s)-$(uname -m)" + exit 1 + ;; +esac +readonly shatool +readonly sha256sum + +readonly tarball="$filename.zip" + +cd .gitlab + +echo "$sha256sum $tarball" > fastbuild.sha256sum +# This URL is only visible inside of Kitware's network. See above filename table. +curl -OL "https://cmake.org/files/dependencies/internal/$tarball" +$shatool --check fastbuild.sha256sum +mkdir -p fastbuild +unzip -d fastbuild -q "$tarball" +chmod +x $exenames +rm "$tarball" fastbuild.sha256sum
diff --git a/.gitlab/ci/iar-env.sh b/.gitlab/ci/iar-env.sh index 9ec7494..67d9d54 100644 --- a/.gitlab/ci/iar-env.sh +++ b/.gitlab/ci/iar-env.sh
@@ -1,10 +1,10 @@ files=' -bxarm-9.60.4.deb -bxavr-8.10.2.deb -bxrh850-3.10.2.deb -bxriscv-3.30.1.deb -bxrl78-5.10.3.deb -bxrx-5.10.1.deb +bxarm-9.70.2.deb +bxavr-8.10.3.deb +bxrh850-3.20.1.deb +bxriscv-3.40.2.deb +bxrl78-5.20.2.deb +bxrx-5.20.1.deb ' for f in $files; do # This URL is only visible inside of Kitware's network. @@ -12,12 +12,12 @@ done echo ' -cd92a136bc9bbb1e713121cb407131b54250d2ae30809df3cd752c6383e1878f bxarm-9.60.4.deb -4a1065291952a23a8bfbbaa4eb36ca49b0af8653b8faab34ce955d9d48d64506 bxavr-8.10.2.deb -b14085a0f21750c58168125d3cece2e3fcbd4c6495c652b5e65b6637bac0ac31 bxrh850-3.10.2.deb -517e18dffdd4345f97c480b5128c7feea25ec1c3f06e62d8e2e6808c401d514a bxriscv-3.30.1.deb -3deca7f6afd5f47684464ad748334ab0690097a109d9c680603450074fc32ccf bxrl78-5.10.3.deb -260e592c48cbaf902b13bdb2feeeba83068978131fcb5c027dab17e715dec7e7 bxrx-5.10.1.deb +0a90ec54f097ebc24f7e12aa665b22cdaa78ea0a59792814392dce510d9fece1 bxarm-9.70.2.deb +4fc428eee8617d365c526d67f9a30ed0873cbb916160a35ab7b50b4de0628dc0 bxavr-8.10.3.deb +48b85860fc226aa8284b21ba3a49bfe018b12d61b5d0ab184e90840836583521 bxrh850-3.20.1.deb +e701a208d4fac3fe52f685b785c1983383de48d556a77c5921f649d983c7339f bxriscv-3.40.2.deb +eb672e903d11f45adb591cf4a56e45187fe979c05e1c21d30ba7c1f6d95ea648 bxrl78-5.20.2.deb +059667a53b6683b1b09b7842d71e784c04bc2376734421c3a628acdbc6bef9e3 bxrx-5.20.1.deb ' > bxdebs.sha256sum sha256sum --check bxdebs.sha256sum
diff --git a/.gitlab/ci/iar.ps1 b/.gitlab/ci/iar.ps1 index 2034fa2..d0f41b9 100644 --- a/.gitlab/ci/iar.ps1 +++ b/.gitlab/ci/iar.ps1
@@ -7,12 +7,12 @@ $iar_dir = New-Item -Force -ItemType Directory -Path "$outdir\iar" $files = @{ - "bxarm-9.60.4.11196-1.zip" = "0DE5F610D0FA3A6513C856BC2403A84D5277F1F6D0D65A6022D1FD745BC4AF6A" - "BXAVR-8102-1.zip" = "862EFD23531854506070D5647F9B32197B80E5A727304BFBD8E386A3DAADF093" - "BXRH850-3102-1.zip" = "8D1D009A0D138C7CA8431316123CB85CE1B41319A68B997F90D2E338CD469C7F" - "BXRISCV-3301-1.zip" = "59FF23F7B98EE72567A23942DE799AF137791A19BFEC102B2A59821FABBCA55A" - "BXRL78-5103-1.zip" = "00398E7197735A7B0A4310BF906808E883548814475C12D6EF2C03388F77E6A7" - "BXRX-5101-1.zip" = "D63E95ECD454B4998946C2D9DC1CB6CEF69CE15524C11A123263E6A8E88D9899" + "bxarm-9.70.2.18199-1.zip" = "47F91EB1829754440ED57B112D068345F1662309748AD5F1F8A6F6DA7362A54E" + "BXAVR-8103-1.zip" = "53DA32EC4CF0CD0A2D4B81EF2CB5B8AF4D48B14A65661CB112394C634F897C8C" + "bxrh850-3.20.1.2142-1.zip" = "21EBFC9B61F5B25DF91F6578C6311AABC5BEB9FC9A71CDC54B85727149079ACF" + "BXRISCV-3402-1.zip" = "6A694D111DED058944F55545F7E64E5B67DEC3E28B30B4436BEF6C0080C90F8D" + "bxrl78-5.20.2.2949-1.zip" = "81ED60CFB7A8528490C1CBFCB22894E56B0A32A401F2F79ADFEA1D626EE7AF34" + "bxrx-5.20.1.6541-1.zip" = "C000B333618A253482DCCB8F06CB902F6D9D0B7D554B863175D316004FBFFC82" } foreach ($f in $files.GetEnumerator()) {
diff --git a/.gitlab/ci/macos-env.sh b/.gitlab/ci/macos-env.sh deleted file mode 100644 index 1b8ad8e..0000000 --- a/.gitlab/ci/macos-env.sh +++ /dev/null
@@ -1,2 +0,0 @@ -.gitlab/ci/macos.sh -export SDKROOT="$PWD/.gitlab/MacOSX.sdk"
diff --git a/.gitlab/ci/macos.sh b/.gitlab/ci/macos.sh deleted file mode 100755 index 7e947a2..0000000 --- a/.gitlab/ci/macos.sh +++ /dev/null
@@ -1,28 +0,0 @@ -#!/bin/sh - -set -e - -# This URL is only visible inside of Kitware's network. -baseurl="https://cmake.org/files/dependencies/internal/macos" - -case "$(uname -s)-$(uname -m)" in - Darwin-*) - shatool="shasum -a 256" - sha256sum="427612880d6c40bcef2b0ecb39d92b057ee7a43ec3552fbd4449859991eb1cc6" - tarball="MacOSX15.5.sdk.tar.bz2" - ;; - *) - echo "Unrecognized platform $(uname -s)-$(uname -m)" - exit 1 - ;; -esac -readonly shatool -readonly sha256sum - -cd .gitlab - -echo "$sha256sum $tarball" > macos.sha256sum -curl -OL "$baseurl/$tarball" -$shatool --check macos.sha256sum -tar xjf "$tarball" -rm "$tarball" macos.sha256sum
diff --git a/.gitlab/ci/package_macos.sh b/.gitlab/ci/package_macos.sh index 7625c5d..21f5138 100644 --- a/.gitlab/ci/package_macos.sh +++ b/.gitlab/ci/package_macos.sh
@@ -1,12 +1,2 @@ cd build -cpack -G TGZ cpack -G DragNDrop - -case "$CMAKE_CI_PACKAGE" in - dev) - ;; - *) - mkdir -p unsigned - mv cmake-*-macos*-universal.* unsigned/ - ;; -esac
diff --git a/.gitlab/ci/package_macos_sign.sh b/.gitlab/ci/package_macos_sign.sh new file mode 100644 index 0000000..7ae21d7 --- /dev/null +++ b/.gitlab/ci/package_macos_sign.sh
@@ -0,0 +1 @@ +Utilities/Release/macos/sign-notarize.bash -- build/cmake-*-macos*-universal.dmg
diff --git a/.gitlab/ci/post_build_fedora42_tidy.sh b/.gitlab/ci/post_build_fedora43_tidy.sh similarity index 100% rename from .gitlab/ci/post_build_fedora42_tidy.sh rename to .gitlab/ci/post_build_fedora43_tidy.sh
diff --git a/.gitlab/ci/pre_build_fedora43_bullseye_coverage.sh b/.gitlab/ci/pre_build_fedora43_bullseye_coverage.sh new file mode 100644 index 0000000..ab78d8f --- /dev/null +++ b/.gitlab/ci/pre_build_fedora43_bullseye_coverage.sh
@@ -0,0 +1,2 @@ +# Turn on Bullseye coverage for build step. +cov01 --on
diff --git a/.gitlab/ci/pre_configure.ps1 b/.gitlab/ci/pre_configure.ps1 new file mode 100644 index 0000000..8c4a4a6 --- /dev/null +++ b/.gitlab/ci/pre_configure.ps1
@@ -0,0 +1,4 @@ +$pwsh = [System.Diagnostics.Process]::GetCurrentProcess().MainModule.FileName +if (Test-Path -Path ".gitlab/ci/pre_configure_$env:CMAKE_CONFIGURATION.ps1" -PathType Leaf) { + . ".gitlab/ci/pre_configure_$env:CMAKE_CONFIGURATION.ps1" +}
diff --git a/.gitlab/ci/pre_configure.sh b/.gitlab/ci/pre_configure.sh new file mode 100755 index 0000000..29ce813 --- /dev/null +++ b/.gitlab/ci/pre_configure.sh
@@ -0,0 +1,18 @@ +#!/bin/bash + +set -e + +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/pre_configure_${CMAKE_CONFIGURATION}.sh"; then + source ".gitlab/ci/pre_configure_${CMAKE_CONFIGURATION}.sh" +fi
diff --git a/.gitlab/ci/pre_configure_fedora43_bullseye_coverage.sh b/.gitlab/ci/pre_configure_fedora43_bullseye_coverage.sh new file mode 100644 index 0000000..ec54ff2 --- /dev/null +++ b/.gitlab/ci/pre_configure_fedora43_bullseye_coverage.sh
@@ -0,0 +1,2 @@ +# Turn off Bullseye coverage for configure step. +cov01 --off
diff --git a/.gitlab/ci/pre_build_fedora42_tidy.sh b/.gitlab/ci/pre_configure_fedora43_tidy.sh similarity index 100% rename from .gitlab/ci/pre_build_fedora42_tidy.sh rename to .gitlab/ci/pre_configure_fedora43_tidy.sh
diff --git a/.gitlab/ci/pre_test.ps1 b/.gitlab/ci/pre_test.ps1 new file mode 100644 index 0000000..4936d98 --- /dev/null +++ b/.gitlab/ci/pre_test.ps1
@@ -0,0 +1,4 @@ +$pwsh = [System.Diagnostics.Process]::GetCurrentProcess().MainModule.FileName +if (Test-Path -Path ".gitlab/ci/pre_test_$env:CMAKE_CONFIGURATION.ps1" -PathType Leaf) { + . ".gitlab/ci/pre_test_$env:CMAKE_CONFIGURATION.ps1" +}
diff --git a/.gitlab/ci/pre_test.sh b/.gitlab/ci/pre_test.sh new file mode 100755 index 0000000..f529861 --- /dev/null +++ b/.gitlab/ci/pre_test.sh
@@ -0,0 +1,18 @@ +#!/bin/bash + +set -e + +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/pre_test_${CMAKE_CONFIGURATION}.sh"; then + source ".gitlab/ci/pre_test_${CMAKE_CONFIGURATION}.sh" +fi
diff --git a/.gitlab/ci/pre_test_fedora43_bullseye_coverage.sh b/.gitlab/ci/pre_test_fedora43_bullseye_coverage.sh new file mode 100644 index 0000000..4e892d2 --- /dev/null +++ b/.gitlab/ci/pre_test_fedora43_bullseye_coverage.sh
@@ -0,0 +1,2 @@ +# Turn on Bullseye coverage for test step. +cov01 --on
diff --git a/.gitlab/ci/repackage/appimagetool.sh b/.gitlab/ci/repackage/appimagetool.sh new file mode 100755 index 0000000..03ce12d --- /dev/null +++ b/.gitlab/ci/repackage/appimagetool.sh
@@ -0,0 +1,28 @@ +#!/usr/bin/env bash + +set -e + +arch="$1" +version="${2-1.9.0.20250814}" + +dir="appimagetool-$version-$arch" +mkdir "$dir" +mkdir -p "$dir/lib/appimagetool" + +filename="appimagetool-$arch.AppImage" +curl -OL "https://github.com/AppImage/appimagetool/releases/download/continuous/$filename" +chmod +x "$filename" +"./$filename" --appimage-extract +mv "squashfs-root/usr/bin" "$dir/bin" +rm -rf "$filename" "squashfs-root" + +filename="runtime-$arch" +curl -OL "https://github.com/AppImage/type2-runtime/releases/download/continuous/$filename" +mv "$filename" "$dir/lib/appimagetool/runtime" + +cat >"$dir/README.txt" <<EOF +This was packaged using CMake's ".gitlab/ci/repackage/appimagetool.sh" script. +EOF + +tar czf "$dir.tar.gz" "$dir" +rm -rf "$dir"
diff --git a/.gitlab/ci/repackage/iar.ps1 b/.gitlab/ci/repackage/iar.ps1 index 5a8c1e5..01f0c79 100644 --- a/.gitlab/ci/repackage/iar.ps1 +++ b/.gitlab/ci/repackage/iar.ps1
@@ -21,14 +21,39 @@ $exclude = @( "arm/config/debugger" "arm/config/flashloader" + "arm/doc" "arm/drivers" "arm/src" + "avr/doc" + "avr/src/cstat" + "avr/src/lib" + "avr/src/lib_tiny" + "avr/src/linker" + "riscv/config/debugger" + "riscv/config/flashloader" + "riscv/doc" + "riscv/drivers" + "riscv/src" + "rh850/config/debugger" + "rh850/doc" + "rh850/src" + "rl78/config/debugger" + "rl78/config/renesas" + "rl78/doc" + "rl78/drivers" + "rl78/src" + "rx/config/debugger" + "rx/config/flashloader" + "rx/drivers" + "rx/src" ) Write-Host "Installing to: $package_dir" Start-Process -Wait -FilePath "$installer_file" -ArgumentList "/hide_usd /autoinstall/$package_dir" foreach ($p in $exclude) { - Remove-Item "$package_dir/$p" -Recurse -Force + if (Test-Path "$package_dir/$p") { + Remove-Item "$package_dir/$p" -Recurse -Force + } } @"
diff --git a/.gitlab/ci/repackage/macos.sh b/.gitlab/ci/repackage/macos.sh deleted file mode 100755 index 3499001..0000000 --- a/.gitlab/ci/repackage/macos.sh +++ /dev/null
@@ -1,8 +0,0 @@ -#!/usr/bin/env bash - -set -e - -sdkPath="$(xcrun --show-sdk-path)" -sdkVers="$(xcrun --show-sdk-version)" - -tar cjf "MacOSX${sdkVers}.sdk.tar.bz2" -C "${sdkPath%/*}" --no-fflags "MacOSX.sdk"
diff --git a/.gitlab/ci/swift-env.sh b/.gitlab/ci/swift-env.sh index fa0c81e..5225cdf 100644 --- a/.gitlab/ci/swift-env.sh +++ b/.gitlab/ci/swift-env.sh
@@ -1,7 +1,7 @@ -curl -L -O "https://download.swift.org/swift-5.7.1-release/ubuntu1804/swift-5.7.1-RELEASE/swift-5.7.1-RELEASE-ubuntu18.04.tar.gz" -echo '2b30f9efc969d9e96f0836d0871130dffb369822a3823ee6f3db44c29c1698e3 swift-5.7.1-RELEASE-ubuntu18.04.tar.gz' > swift.sha256sum +curl -L -O "https://download.swift.org/swift-6.2.1-release/debian12/swift-6.2.1-RELEASE/swift-6.2.1-RELEASE-debian12.tar.gz" +echo 'd6405e4fb7f092cbb9973a892ce8410837b4335f67d95bf8607baef1f69939e4 swift-6.2.1-RELEASE-debian12.tar.gz' > swift.sha256sum sha256sum --check swift.sha256sum mkdir /opt/swift -tar xzf swift-5.7.1-RELEASE-ubuntu18.04.tar.gz -C /opt/swift --strip-components=2 -rm swift-5.7.1-RELEASE-ubuntu18.04.tar.gz swift.sha256sum +tar xzf swift-6.2.1-RELEASE-debian12.tar.gz -C /opt/swift --strip-components=2 +rm swift-6.2.1-RELEASE-debian12.tar.gz swift.sha256sum export SWIFTC="/opt/swift/bin/swiftc"
diff --git a/.gitlab/ci/ticlang.sh b/.gitlab/ci/ticlang.sh index 66fa863..a0e4b19 100755 --- a/.gitlab/ci/ticlang.sh +++ b/.gitlab/ci/ticlang.sh
@@ -5,9 +5,9 @@ case "$(uname -s)-$(uname -m)" in Linux-x86_64) shatool="sha256sum" - sha256sum="c69ac58e403b82eac1c407cc67b35fab5d95c5d8db75b019095f9412aacff27d" - filename="ti_cgt_armllvm_3.2.1.LTS_linux-x64_installer.bin" - dirname="ti-cgt-armllvm_3.2.1.LTS" + sha256sum="98c60ecc259a07a54be6fcc0f55990332f493bfe5dad460c0ba83963f5dcb06f" + filename="ti_cgt_armllvm_4.0.4.LTS_linux-x64_installer.bin" + dirname="ti-cgt-armllvm_4.0.4.LTS" ;; *) echo "Unrecognized platform $(uname -s)-$(uname -m)"
diff --git a/.gitlab/os-linux.yml b/.gitlab/os-linux.yml index 47f0d5f..7ec2288 100644 --- a/.gitlab/os-linux.yml +++ b/.gitlab/os-linux.yml
@@ -5,13 +5,13 @@ ### Release .linux_prep_source: - image: "fedora:42" + image: "fedora:43" variables: GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake ci" .linux_release_x86_64: - image: "kitware/cmake:build-linux-x86_64-deps-2023-08-16@sha256:aa0ebdbd90a51cc83d31f393c5c48ec4599a28f7ccdc288558522c6265b24fae" + image: "kitware/cmake:build-linux-x86_64-deps-2026-01-13@sha256:eae18d032e8d7be3caa97d2e5754ae2b7196d7a3d375b7b4d1ba9034f1229317" variables: GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake ci" @@ -19,11 +19,10 @@ CMAKE_ARCH: x86_64 .linux_release_aarch64: - image: "kitware/cmake:build-linux-aarch64-deps-2020-12-21@sha256:0bd7dfe4e45593b04e39cd21e44011034610cfd376900558c5ef959bb1af15af" + image: "kitware/cmake:build-linux-aarch64-deps-2026-01-13@sha256:7373fe775ea571a3113251b3e8b5857ef321f6e9b5dfa5963f6e44d062349244" variables: GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake ci" - LAUNCHER: "scl enable devtoolset-7 --" CMAKE_ARCH: aarch64 .linux_package: @@ -52,29 +51,29 @@ needs: - b:centos7-x86_64 -.needs_centos7_aarch64: +.needs_centos8_aarch64: needs: - - b:centos7-aarch64 + - b:centos8-aarch64 ### Debian -.debian12: - image: "kitware/cmake:ci-debian12-x86_64-2025-03-31" +.debian13: + image: "kitware/cmake:ci-debian13-x86_64-2026-02-08" variables: GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake ci" CMAKE_ARCH: x86_64 -.debian12_iwyu: - extends: .debian12 +.debian13_iwyu: + extends: .debian13 variables: - CMAKE_CONFIGURATION: debian12_iwyu + CMAKE_CONFIGURATION: debian13_iwyu CTEST_NO_WARNINGS_ALLOWED: 1 CMAKE_CI_NO_INSTALL: 1 -.debian12_aarch64: - image: "kitware/cmake:ci-debian12-aarch64-2025-03-31" +.debian13_aarch64: + image: "kitware/cmake:ci-debian13-aarch64-2026-02-08" variables: GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake ci" @@ -82,202 +81,261 @@ ### Fedora -.fedora42: - image: "kitware/cmake:ci-fedora42-x86_64-2025-04-22" +.fedora43: + image: "kitware/cmake:ci-fedora43-x86_64-2026-02-08" variables: GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake ci/long file name for testing purposes" CMAKE_ARCH: x86_64 -.fedora42_hip: - image: "kitware/cmake:ci-fedora42-hip-x86_64-2025-04-22" +.fedora43_hip: + image: "kitware/cmake:ci-fedora43-hip-x86_64-2025-10-29" variables: # FIXME(rocclr): device modules fail loading from binaries in paths with spaces GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake-ci" CMAKE_ARCH: x86_64 -#### Lint builds +#### Coverage builds -.fedora42_tidy: - extends: .fedora42 +.fedora43_gcc_gcov: + extends: .fedora43 variables: - CMAKE_CONFIGURATION: fedora42_tidy + # See issue #20001 + CMAKE_GENERATOR: "Unix Makefiles" + CMAKE_CONFIGURATION: fedora43_gcc_gcov + CTEST_NO_WARNINGS_ALLOWED: 1 + CMAKE_CI_BUILD_TYPE: Debug + CMAKE_CI_TEST_TIMEOUT: "1500" CMAKE_CI_NO_INSTALL: 1 -.fedora42_clang_analyzer: - extends: .fedora42 +.fedora43_bullseye_coverage: + extends: .fedora43 + environment: + name: bullseye-coverage + variables: + # See issue #20001 + CMAKE_GENERATOR: "Unix Makefiles" + CMAKE_CONFIGURATION: fedora43_bullseye_coverage + CTEST_NO_WARNINGS_ALLOWED: 1 + CMAKE_CI_BUILD_TYPE: Debug + CMAKE_CI_TEST_TIMEOUT: "1500" + CMAKE_CI_NO_INSTALL: 1 + +#### Lint builds + +.fedora43_tidy: + extends: .fedora43 variables: - CMAKE_CONFIGURATION: fedora42_clang_analyzer + CMAKE_CONFIGURATION: fedora43_tidy + CMAKE_CI_NO_INSTALL: 1 + +.fedora43_clang_analyzer: + extends: .fedora43 + + variables: + CMAKE_CONFIGURATION: fedora43_clang_analyzer CMAKE_CI_BUILD_TYPE: Debug CTEST_NO_WARNINGS_ALLOWED: 1 CMAKE_CI_NO_INSTALL: 1 -.fedora42_sphinx: - extends: .fedora42 +.fedora43_clang_fuzzing: + extends: .fedora43 variables: - CMAKE_CONFIGURATION: fedora42_sphinx + CMAKE_CONFIGURATION: fedora43_clang_fuzzing + CTEST_NO_WARNINGS_ALLOWED: 1 + CMAKE_CI_NO_INSTALL: 1 + +.fedora43_clazy: + extends: .fedora43 + + variables: + CMAKE_CONFIGURATION: fedora43_clazy + CMAKE_CI_BUILD_TYPE: Debug + CTEST_NO_WARNINGS_ALLOWED: 1 + CMAKE_CI_NO_INSTALL: 1 + +.fedora43_sphinx: + extends: .fedora43 + + variables: + CMAKE_CONFIGURATION: fedora43_sphinx CTEST_NO_WARNINGS_ALLOWED: 1 CTEST_SOURCE_SUBDIRECTORY: "Utilities/Sphinx" CMAKE_CI_NO_INSTALL: 1 -.fedora42_sphinx_package: - extends: .fedora42 +.fedora43_sphinx_package: + extends: .fedora43 variables: - CMAKE_CONFIGURATION: fedora42_sphinx_package + CMAKE_CONFIGURATION: fedora43_sphinx_package CTEST_SOURCE_SUBDIRECTORY: "Utilities/Sphinx" #### Build and test -.debian12_ninja: - extends: .debian12 +.debian13_ninja: + extends: .debian13 variables: - CMAKE_CONFIGURATION: debian12_ninja + CMAKE_CONFIGURATION: debian13_ninja CTEST_NO_WARNINGS_ALLOWED: 1 -.debian12_aarch64_ninja: - extends: .debian12_aarch64 +.debian13_aarch64_ninja: + extends: .debian13_aarch64 variables: - CMAKE_CONFIGURATION: debian12_aarch64_ninja + CMAKE_CONFIGURATION: debian13_aarch64_ninja CTEST_NO_WARNINGS_ALLOWED: 1 -.debian12_makefiles_inplace: - extends: .debian12 +.debian13_makefiles_inplace: + extends: .debian13 variables: - CMAKE_CONFIGURATION: debian12_makefiles_inplace + CMAKE_CONFIGURATION: debian13_makefiles_inplace CMAKE_GENERATOR: "Unix Makefiles" CMAKE_CI_BOOTSTRAP: 1 CMAKE_CI_INPLACE: 1 CMAKE_CI_NO_INSTALL: 1 CTEST_NO_WARNINGS_ALLOWED: 1 -.debian12_ninja_multi_symlinked: - extends: .debian12 +.debian13_ninja_multi_symlinked: + extends: .debian13 variables: - CMAKE_CONFIGURATION: debian12_ninja_multi_symlinked + CMAKE_CONFIGURATION: debian13_ninja_multi_symlinked CMAKE_GENERATOR: "Ninja Multi-Config" CTEST_NO_WARNINGS_ALLOWED: 1 CMAKE_CI_IN_SYMLINK_TREE: 1 CMAKE_CI_BUILD_DIR: "real_work/work/build" -.debian12_extdeps: - extends: .debian12 +.debian13_extdeps: + extends: .debian13 variables: - CMAKE_CONFIGURATION: debian12_extdeps + CMAKE_CONFIGURATION: debian13_extdeps CMAKE_CI_BUILD_TYPE: Release CTEST_NO_WARNINGS_ALLOWED: 1 -.debian12_aarch64_extdeps: - extends: .debian12_aarch64 +.debian13_aarch64_extdeps: + extends: .debian13_aarch64 variables: - CMAKE_CONFIGURATION: debian12_aarch64_extdeps + CMAKE_CONFIGURATION: debian13_aarch64_extdeps CMAKE_CI_BUILD_TYPE: Release CTEST_NO_WARNINGS_ALLOWED: 1 -.fedora42_extdeps: - extends: .fedora42 +.fedora43_extdeps: + extends: .fedora43 variables: - CMAKE_CONFIGURATION: fedora42_extdeps + CMAKE_CONFIGURATION: fedora43_extdeps CMAKE_CI_BUILD_TYPE: Release CTEST_NO_WARNINGS_ALLOWED: 1 -.fedora42_ninja: - extends: .fedora42 +.fedora43_ninja: + extends: .fedora43 variables: - CMAKE_CONFIGURATION: fedora42_ninja + CMAKE_CONFIGURATION: fedora43_ninja CMAKE_CI_BUILD_TYPE: Release CTEST_NO_WARNINGS_ALLOWED: 1 -.fedora42_ninja_multi: - extends: .fedora42 +.fedora43_makefiles: + extends: .fedora43 variables: - CMAKE_CONFIGURATION: fedora42_ninja_multi - CTEST_NO_WARNINGS_ALLOWED: 1 - CMAKE_GENERATOR: "Ninja Multi-Config" - -.fedora42_makefiles: - extends: .fedora42 - - variables: - CMAKE_CONFIGURATION: fedora42_makefiles + CMAKE_CONFIGURATION: fedora43_makefiles CTEST_NO_WARNINGS_ALLOWED: 1 CMAKE_GENERATOR: "Unix Makefiles" -.fedora42_makefiles_symlinked: - extends: .fedora42 +.fedora43_makefiles_symlinked: + extends: .fedora43 variables: - CMAKE_CONFIGURATION: fedora42_makefiles_symlinked + CMAKE_CONFIGURATION: fedora43_makefiles_symlinked CTEST_NO_WARNINGS_ALLOWED: 1 CMAKE_GENERATOR: "Unix Makefiles" CMAKE_CI_IN_SYMLINK_TREE: 1 CMAKE_CI_BUILD_DIR: "real_work/work/build" +.fedora43_fastbuild: + extends: .fedora43 + + variables: + CMAKE_CONFIGURATION: fedora43_fastbuild + CTEST_NO_WARNINGS_ALLOWED: 1 + CMAKE_GENERATOR: "FASTBuild" + +.fedora43_ninja_instrumentation: + extends: .fedora43 + + variables: + CMAKE_CONFIGURATION: fedora43_ninja_instrumentation + CTEST_NO_WARNINGS_ALLOWED: 1 + CMAKE_GENERATOR: "Ninja" + ### Clang Compiler -.debian12_makefiles_clang: - extends: .debian12 +.debian13_makefiles_clang: + extends: .debian13 variables: - CMAKE_CONFIGURATION: debian12_makefiles_clang + CMAKE_CONFIGURATION: debian13_makefiles_clang CMAKE_GENERATOR: "Unix Makefiles" -.debian12_ninja_clang: - extends: .debian12 +.debian13_ninja_clang: + extends: .debian13 variables: - CMAKE_CONFIGURATION: debian12_ninja_clang + CMAKE_CONFIGURATION: debian13_ninja_clang -.fedora42_makefiles_clang: - extends: .fedora42 +.fedora43_makefiles_clang: + extends: .fedora43 variables: - CMAKE_CONFIGURATION: fedora42_makefiles_clang + CMAKE_CONFIGURATION: fedora43_makefiles_clang CMAKE_GENERATOR: "Unix Makefiles" -.fedora42_makefiles_lfortran: - extends: .fedora42 +.fedora43_makefiles_lfortran: + extends: .fedora43 variables: # FIXME(lfortran): -rpath flags with spaces not forwarded GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake-ci" - CMAKE_CONFIGURATION: fedora42_makefiles_lfortran + CMAKE_CONFIGURATION: fedora43_makefiles_lfortran CMAKE_GENERATOR: "Unix Makefiles" CTEST_LABELS: "Fortran" -.fedora42_ninja_lfortran: - extends: .fedora42 +.fedora43_ninja_lfortran: + extends: .fedora43 variables: # FIXME(lfortran): -rpath flags with spaces not forwarded GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake-ci" - CMAKE_CONFIGURATION: fedora42_ninja_lfortran + CMAKE_CONFIGURATION: fedora43_ninja_lfortran CTEST_LABELS: "Fortran" -.fedora42_ninja_clang: - extends: .fedora42 +.fedora43_ninja_multi: + extends: .fedora43 variables: - CMAKE_CONFIGURATION: fedora42_ninja_clang + CMAKE_CONFIGURATION: fedora43_ninja_multi + CMAKE_GENERATOR: "Ninja Multi-Config" -.fedora42_ninja_multi_clang: - extends: .fedora42 +.fedora43_ninja_clang: + extends: .fedora43 variables: - CMAKE_CONFIGURATION: fedora42_ninja_multi_clang + CMAKE_CONFIGURATION: fedora43_ninja_clang + +.fedora43_ninja_multi_clang: + extends: .fedora43 + + variables: + CMAKE_CONFIGURATION: fedora43_ninja_multi_clang CMAKE_GENERATOR: "Ninja Multi-Config" ### Sanitizers @@ -293,13 +351,30 @@ CTEST_MEMORYCHECK_TYPE: AddressSanitizer CTEST_MEMORYCHECK_SANITIZER_OPTIONS: "" -.fedora42_asan: +.fedora_valgrind_addon: + extends: .fedora_memcheck + + variables: + CTEST_MEMORYCHECK_TYPE: Valgrind + CMAKE_CI_RUN_MEMCHECK: "true" + CMAKE_CI_TEST_TIMEOUT: "1500" + CMAKE_VALGRIND_CONFIGURATION: fedora43 + +.fedora43_asan: extends: - - .fedora42 + - .fedora43 - .fedora_asan_addon variables: - CMAKE_CONFIGURATION: fedora42_asan + CMAKE_CONFIGURATION: fedora43_asan + +.fedora43_ninja_valgrind: + extends: + - .fedora43 + - .fedora_valgrind_addon + + variables: + CMAKE_CONFIGURATION: fedora43_ninja_valgrind ### Intel Compiler @@ -451,6 +526,38 @@ CMAKE_CONFIGURATION: cuda12.6_clang CTEST_NO_WARNINGS_ALLOWED: 1 +.cuda13.0: + extends: .cuda + image: "kitware/cmake:ci-cuda13.0-x86_64-2025-10-20" + variables: + CMAKE_ARCH: x86_64 + +.cuda13.0_nvidia: + extends: .cuda13.0 + variables: + CMAKE_CONFIGURATION: cuda13.0_nvidia + CTEST_NO_WARNINGS_ALLOWED: 1 + +.cuda13.0_nvidia_fastbuild: + extends: .cuda13.0 + + variables: + CMAKE_CONFIGURATION: cuda13.0_nvidia_fastbuild + CTEST_NO_WARNINGS_ALLOWED: 1 + CMAKE_GENERATOR: "FASTBuild" + +.cuda13.0_aarch64: + extends: .cuda + image: "kitware/cmake:ci-cuda13.0-aarch64-2025-10-31" + variables: + CMAKE_ARCH: aarch64 + +.cuda13.0_aarch64_nvidia: + extends: .cuda13.0_aarch64 + variables: + CMAKE_CONFIGURATION: cuda13.0_aarch64_nvidia + CTEST_NO_WARNINGS_ALLOWED: 1 + ### HIP builds .hip6.3: @@ -470,18 +577,18 @@ CMAKE_CONFIGURATION: hip6.3_radeon CMAKE_GENERATOR: "Ninja Multi-Config" -.debian12_hip_radeon: - extends: .debian12 +.debian13_hip_radeon: + extends: .debian13 variables: - CMAKE_CONFIGURATION: debian12_hip_radeon + CMAKE_CONFIGURATION: debian13_hip_radeon CTEST_LABELS: "HIP" -.fedora42_hip_radeon: - extends: .fedora42_hip +.fedora43_hip_radeon: + extends: .fedora43_hip variables: - CMAKE_CONFIGURATION: fedora42_hip_radeon + CMAKE_CONFIGURATION: fedora43_hip_radeon CTEST_LABELS: "HIP" .hip6.3_nvidia: @@ -490,6 +597,7 @@ variables: CMAKE_CONFIGURATION: hip6.3_nvidia CTEST_LABELS: "HIP" + CMAKE_CUDA_ARCHITECTURES_NATIVE_CLAMP: 1 ### C++ modules @@ -508,6 +616,13 @@ variables: CMAKE_CONFIGURATION: linux_gcc_cxx_modules_ninja +.gcc_cxx_modules_reloc_ninja: + extends: .gcc_cxx_modules_x86_64 + + variables: + CMAKE_CONFIGURATION: linux_gcc_cxx_modules_reloc_ninja + CTEST_LABELS: "CXXModules" + .gcc_cxx_modules_ninja_multi: extends: .gcc_cxx_modules_x86_64 @@ -554,6 +669,13 @@ - linux-x86_64 - x11 +.linux_x86_64_tags_fast_x11: + tags: + - cmake + - docker + - linux-x86_64-v4 + - x11 + .linux_x86_64_tags_cuda_arch_30: tags: - cmake @@ -575,11 +697,18 @@ - docker - linux-x86_64-v3 -.linux_x86_64_tags_rocm5.2: +.linux_x86_64_tags_cuda_arch_75: + tags: + - cmake + - cuda-arch-75 + - docker + - linux-x86_64 + +.linux_x86_64_tags_rocm5.7: tags: - cmake - radeon - - rocm-5.2 + - rocm-5.7 - docker - linux-x86_64 @@ -606,6 +735,13 @@ - docker - linux-aarch64 +.linux_aarch64_tags_cuda_arch_75: + tags: + - cmake + - cuda-arch-75 + - docker + - linux-aarch64 + ## Linux-specific scripts .before_script_linux: &before_script_linux @@ -638,14 +774,14 @@ .cmake_version_update_linux: stage: build - extends: .fedora42 + extends: .fedora43 script: - .gitlab/ci/cmake_version_update.sh interruptible: false # The job internally fetches and retries. .cmake_spellcheck_linux: stage: build - extends: .fedora42 + extends: .fedora43 script: - .gitlab/ci/codespell.bash - .gitlab/ci/typos.bash @@ -659,8 +795,9 @@ - .gitlab/ci/sccache.sh - sccache --start-server - sccache --show-stats - - .gitlab/ci/pre_build.sh + - .gitlab/ci/pre_configure.sh - "$LAUNCHER ctest -VV -S .gitlab/ci/ctest_configure.cmake" + - .gitlab/ci/pre_build.sh - "$LAUNCHER ctest -VV -S .gitlab/ci/ctest_build.cmake" - .gitlab/ci/post_build.sh - sccache --show-stats @@ -672,6 +809,7 @@ script: - *before_script_linux + - .gitlab/ci/pre_test.sh - "$LAUNCHER ctest --output-on-failure -V -S .gitlab/ci/ctest_test.cmake" interruptible: true @@ -685,6 +823,16 @@ interruptible: true +.cmake_coverage_linux: + stage: test + + script: + - *before_script_linux + - "$LAUNCHER ctest --output-on-failure -V -S .gitlab/ci/ctest_coverage.cmake" + coverage: '/Percentage Coverage: \d+.\d+%/' + + interruptible: true + .cmake_build_linux_release: stage: build @@ -751,35 +899,23 @@ interruptible: true -.cmake_test_linux_external: - stage: test-ext - - script: - - *before_script_linux - - .gitlab/ci/sccache.sh - - sccache --start-server - - sccache --show-stats - - "$LAUNCHER build/install/bin/ctest --output-on-failure -V -S .gitlab/ci/ctest_standalone.cmake" - - sccache --show-stats - - interruptible: true - .cmake_test_linux_intelclassic_makefiles: extends: - .intelclassic_makefiles - .cmake_test_linux_release - .linux_x86_64_tags - - .run_manually + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" + CMAKE_CI_JOB_NO_MR: "true" .cmake_test_linux_inteloneapi_makefiles: extends: - .inteloneapi_makefiles - .cmake_test_linux_release - .linux_x86_64_tags - - .run_manually + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" @@ -816,7 +952,7 @@ .cmake_org_help: stage: build extends: - - .fedora42 + - .fedora43 - .linux_x86_64_tags - .cmake_org_help_artifacts script:
diff --git a/.gitlab/os-macos.yml b/.gitlab/os-macos.yml index d090b25..7b13dee 100644 --- a/.gitlab/os-macos.yml +++ b/.gitlab/os-macos.yml
@@ -62,13 +62,6 @@ CMAKE_CI_IN_SYMLINK_TREE: 1 CMAKE_CI_BUILD_DIR: "real_work/work/build" -.macos_arm64_curl: - extends: .macos_arm64_build - - variables: - CMAKE_CONFIGURATION: macos_arm64_curl - CTEST_NO_WARNINGS_ALLOWED: 1 - .macos_arm64_pch: extends: .macos_arm64_ninja @@ -99,6 +92,11 @@ CTEST_NO_WARNINGS_ALLOWED: 1 CMAKE_CI_NO_INSTALL: 1 +.macos_sign: + variables: + GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake ci" + CMAKE_CONFIGURATION: macos_sign + ### External testing .macos_x86_64_xcode: @@ -107,7 +105,7 @@ variables: CMAKE_CONFIGURATION: macos_x86_64_xcode CMAKE_GENERATOR: Xcode - CMAKE_CI_NIGHTLY_IGNORE_DEPS: "true" + CMAKE_CI_JOB_NIGHTLY_IGNORE_DEPS: "true" .macos_arm64_xcode: extends: .macos_arm64 @@ -115,7 +113,7 @@ variables: CMAKE_CONFIGURATION: macos_arm64_xcode CMAKE_GENERATOR: Xcode - CMAKE_CI_NIGHTLY_IGNORE_DEPS: "true" + CMAKE_CI_JOB_NIGHTLY_IGNORE_DEPS: "true" .macos_arm64_xcode_symlinked: extends: .macos_arm64 @@ -123,7 +121,7 @@ variables: CMAKE_CONFIGURATION: macos_arm64_xcode_symlinked CMAKE_GENERATOR: Xcode - CMAKE_CI_NIGHTLY_IGNORE_DEPS: "true" + CMAKE_CI_JOB_NIGHTLY_IGNORE_DEPS: "true" CMAKE_CI_IN_SYMLINK_TREE: 1 CMAKE_CI_BUILD_DIR: "real_work/work/build" @@ -133,7 +131,7 @@ variables: CMAKE_CONFIGURATION: macos_arm64_xcode_ub CMAKE_GENERATOR: Xcode - CMAKE_CI_NIGHTLY_IGNORE_DEPS: "true" + CMAKE_CI_JOB_NIGHTLY_IGNORE_DEPS: "true" .macos_arm64_ninja_multi: extends: .macos_arm64 @@ -141,14 +139,22 @@ variables: CMAKE_CONFIGURATION: macos_arm64_ninja_multi CMAKE_GENERATOR: "Ninja Multi-Config" - CMAKE_CI_NIGHTLY_IGNORE_DEPS: "true" + CMAKE_CI_JOB_NIGHTLY_IGNORE_DEPS: "true" .macos_x86_64_ninja_ub: extends: .macos_x86_64 variables: CMAKE_CONFIGURATION: macos_x86_64_ninja_ub - CMAKE_CI_NIGHTLY_IGNORE_DEPS: "true" + CMAKE_CI_JOB_NIGHTLY_IGNORE_DEPS: "true" + +.macos_arm64_fastbuild: + extends: .macos_arm64 + + variables: + CMAKE_CONFIGURATION: macos_arm64_fastbuild + CMAKE_GENERATOR: FASTBuild + CMAKE_CI_JOB_NIGHTLY_IGNORE_DEPS: "true" ## Tags @@ -193,6 +199,13 @@ - nonconcurrent - finder +.macos_sign_tags: + tags: + - cmake # Since this is a bare runner, pin to a project. + - shell + - sign-macos-v1 + - nonconcurrent + ## macOS-specific scripts .before_script_macos: &before_script_macos @@ -212,8 +225,9 @@ # Allow the server to already be running. - "sccache --start-server || :" - sccache --show-stats - - .gitlab/ci/pre_build.sh + - .gitlab/ci/pre_configure.sh - ctest -VV -S .gitlab/ci/ctest_configure.cmake + - .gitlab/ci/pre_build.sh - ctest -VV -S .gitlab/ci/ctest_build.cmake - .gitlab/ci/post_build.sh - sccache --show-stats @@ -225,6 +239,7 @@ script: - *before_script_macos + - .gitlab/ci/pre_test.sh - ctest --output-on-failure -V -S .gitlab/ci/ctest_test.cmake interruptible: true @@ -242,3 +257,12 @@ - sccache --show-stats interruptible: true + +.cmake_sign_macos: + stage: package + environment: + name: sign-macos + script: + - source .gitlab/ci/env.sh + - source .gitlab/ci/package_macos_sign.sh + interruptible: true
diff --git a/.gitlab/os-windows.yml b/.gitlab/os-windows.yml index 34a4433..55bc515 100644 --- a/.gitlab/os-windows.yml +++ b/.gitlab/os-windows.yml
@@ -35,52 +35,58 @@ VCVARSPLATFORM: "x64" VCVARSVERSION: "14.43.34808" -.windows_vcvarsall_vs2022_x64: +.windows_vcvarsall_vs2022_x64_msvc14.44: variables: VCVARSALL: "${VS170COMNTOOLS}\\..\\..\\VC\\Auxiliary\\Build\\vcvarsall.bat" VCVARSPLATFORM: "x64" VCVARSVERSION: "14.44.35207" -.windows_vcvarsall_vs2022_x86: +.windows_vcvarsall_vs2026_x64: variables: - VCVARSALL: "${VS170COMNTOOLS}\\..\\..\\VC\\Auxiliary\\Build\\vcvarsall.bat" + VCVARSALL: "${VS180COMNTOOLS}\\..\\..\\VC\\Auxiliary\\Build\\vcvarsall.bat" + VCVARSPLATFORM: "x64" + VCVARSVERSION: "14.50.35717" + +.windows_vcvarsall_vs2026_x86: + variables: + VCVARSALL: "${VS180COMNTOOLS}\\..\\..\\VC\\Auxiliary\\Build\\vcvarsall.bat" VCVARSPLATFORM: "x86" - VCVARSVERSION: "14.44.35207" + VCVARSVERSION: "14.50.35717" -.windows_vcvarsall_vs2022_x64_arm64: +.windows_vcvarsall_vs2026_x64_arm64: variables: - VCVARSALL: "${VS170COMNTOOLS}\\..\\..\\VC\\Auxiliary\\Build\\vcvarsall.bat" + VCVARSALL: "${VS180COMNTOOLS}\\..\\..\\VC\\Auxiliary\\Build\\vcvarsall.bat" VCVARSPLATFORM: "x64_arm64" - VCVARSVERSION: "14.44.35207" + VCVARSVERSION: "14.50.35717" -.windows_arm64_vcvarsall_vs2022: +.windows_arm64_vcvarsall_vs2026: variables: - VCVARSALL: "${VS170COMNTOOLS}\\..\\..\\VC\\Auxiliary\\Build\\vcvarsall.bat" + VCVARSALL: "${VS180COMNTOOLS}\\..\\..\\VC\\Auxiliary\\Build\\vcvarsall.bat" VCVARSPLATFORM: "arm64" - VCVARSVERSION: "14.44.35207" + VCVARSVERSION: "14.50.35717" -.windows_vs2022_x64_pch: +.windows_vs2026_x64_pch: extends: - - .windows_vs2022_x64_ninja + - .windows_vs2026_x64_ninja variables: - CMAKE_CONFIGURATION: windows_vs2022_x64_pch + CMAKE_CONFIGURATION: windows_vs2026_x64_pch -.windows_vs2022_x64_ninja: +.windows_vs2026_x64_ninja: extends: - .windows_build_ninja - - .windows_vcvarsall_vs2022_x64 + - .windows_vcvarsall_vs2026_x64 variables: - CMAKE_CONFIGURATION: windows_vs2022_x64_ninja + CMAKE_CONFIGURATION: windows_vs2026_x64_ninja -.windows_arm64_vs2022_ninja: +.windows_arm64_vs2026_ninja: extends: - .windows_build_ninja - - .windows_arm64_vcvarsall_vs2022 + - .windows_arm64_vcvarsall_vs2026 variables: - CMAKE_CONFIGURATION: windows_arm64_vs2022_ninja + CMAKE_CONFIGURATION: windows_arm64_vs2026_ninja .windows_package: extends: @@ -93,7 +99,7 @@ .windows_x86_64_package: extends: - .windows_package - - .windows_vcvarsall_vs2022_x64 + - .windows_vcvarsall_vs2026_x64 variables: CMAKE_CONFIGURATION: windows_x86_64_package @@ -101,7 +107,7 @@ .windows_i386_package: extends: - .windows_package - - .windows_vcvarsall_vs2022_x86 + - .windows_vcvarsall_vs2026_x86 variables: CMAKE_CONFIGURATION: windows_i386_package @@ -109,13 +115,23 @@ .windows_arm64_package: extends: - .windows_package - - .windows_vcvarsall_vs2022_x64_arm64 + - .windows_vcvarsall_vs2026_x64_arm64 variables: CMAKE_CONFIGURATION: windows_arm64_package ### External testing +.windows_vs2026_x64: + extends: .windows + + variables: + CMAKE_CONFIGURATION: windows_vs2026_x64 + CMAKE_GENERATOR: "Visual Studio 18 2026" + CMAKE_GENERATOR_PLATFORM: "x64" + CMAKE_GENERATOR_TOOLSET: "v145,version=14.50.35717" + CMAKE_CI_JOB_NIGHTLY_IGNORE_DEPS: "true" + .windows_vs2022_x64: extends: .windows @@ -124,7 +140,7 @@ CMAKE_GENERATOR: "Visual Studio 17 2022" CMAKE_GENERATOR_PLATFORM: "x64" CMAKE_GENERATOR_TOOLSET: "v143,version=14.44.35207" - CMAKE_CI_NIGHTLY_IGNORE_DEPS: "true" + CMAKE_CI_JOB_NIGHTLY_IGNORE_DEPS: "true" .windows_vs2019_x64: extends: .windows @@ -134,7 +150,7 @@ CMAKE_GENERATOR: "Visual Studio 16 2019" CMAKE_GENERATOR_PLATFORM: "x64" CMAKE_GENERATOR_TOOLSET: "v142,version=14.29.30133" - CMAKE_CI_NIGHTLY_IGNORE_DEPS: "true" + CMAKE_CI_JOB_NIGHTLY_IGNORE_DEPS: "true" .windows_borland: extends: .windows @@ -142,7 +158,7 @@ variables: CMAKE_GENERATOR: "Borland Makefiles" CMAKE_CI_BUILD_TYPE: Release - CMAKE_CI_NIGHTLY_IGNORE_DEPS: "true" + CMAKE_CI_JOB_NIGHTLY_IGNORE_DEPS: "true" .windows_borland5.5: extends: .windows_borland @@ -162,14 +178,14 @@ variables: CMAKE_GENERATOR: "Ninja" CMAKE_CI_BUILD_TYPE: Release - CMAKE_CI_NIGHTLY_IGNORE_DEPS: "true" + CMAKE_CI_JOB_NIGHTLY_IGNORE_DEPS: "true" .windows_ninja_multi: extends: .windows variables: CMAKE_GENERATOR: "Ninja Multi-Config" - CMAKE_CI_NIGHTLY_IGNORE_DEPS: "true" + CMAKE_CI_JOB_NIGHTLY_IGNORE_DEPS: "true" .windows_nmake: extends: .windows @@ -177,7 +193,7 @@ variables: CMAKE_GENERATOR: "NMake Makefiles" CMAKE_CI_BUILD_TYPE: Release - CMAKE_CI_NIGHTLY_IGNORE_DEPS: "true" + CMAKE_CI_JOB_NIGHTLY_IGNORE_DEPS: "true" .windows_jom: extends: .windows @@ -185,36 +201,52 @@ variables: CMAKE_GENERATOR: "NMake Makefiles JOM" CMAKE_CI_BUILD_TYPE: Release - CMAKE_CI_NIGHTLY_IGNORE_DEPS: "true" + CMAKE_CI_JOB_NIGHTLY_IGNORE_DEPS: "true" -.windows_vs2022_x64_nmake: +.windows_fastbuild: + extends: .windows + + variables: + CMAKE_GENERATOR: "FASTBuild" + CMAKE_CI_BUILD_TYPE: Release + CMAKE_CI_JOB_NIGHTLY_IGNORE_DEPS: "true" + +.windows_vs2026_x64_nmake: extends: - .windows_nmake - - .windows_vcvarsall_vs2022_x64 + - .windows_vcvarsall_vs2026_x64 variables: - CMAKE_CONFIGURATION: windows_vs2022_x64_nmake + CMAKE_CONFIGURATION: windows_vs2026_x64_nmake -.windows_vs2022_x64_jom: +.windows_vs2026_x64_jom: extends: - .windows_jom - - .windows_vcvarsall_vs2022_x64 + - .windows_vcvarsall_vs2026_x64 variables: - CMAKE_CONFIGURATION: windows_vs2022_x64_jom + CMAKE_CONFIGURATION: windows_vs2026_x64_jom -.windows_vs2022_x64_ninja_multi: +.windows_vs2026_x64_ninja_multi: extends: - .windows_ninja_multi - - .windows_vcvarsall_vs2022_x64 + - .windows_vcvarsall_vs2026_x64 variables: - CMAKE_CONFIGURATION: windows_vs2022_x64_ninja_multi + CMAKE_CONFIGURATION: windows_vs2026_x64_ninja_multi + +.windows_vs2026_x64_fastbuild: + extends: + - .windows_fastbuild + - .windows_vcvarsall_vs2026_x64 + + variables: + CMAKE_CONFIGURATION: windows_vs2026_x64_fastbuild .windows_clang_ninja: extends: - .windows_ninja - - .windows_vcvarsall_vs2022_x64 + - .windows_vcvarsall_vs2022_x64_msvc14.44 variables: CMAKE_CONFIGURATION: windows_clang_ninja @@ -222,7 +254,7 @@ .windows_clang_nmake: extends: - .windows_nmake - - .windows_vcvarsall_vs2022_x64 + - .windows_vcvarsall_vs2022_x64_msvc14.44 variables: CMAKE_CONFIGURATION: windows_clang_nmake @@ -244,7 +276,7 @@ .windows_inteloneapi_ninja: extends: - .windows_ninja - - .windows_vcvarsall_vs2022_x64 + - .windows_vcvarsall_vs2022_x64_msvc14.44 variables: CMAKE_CONFIGURATION: windows_inteloneapi_ninja @@ -257,7 +289,7 @@ GIT_CLONE_PATH: "$CI_BUILDS_DIR\\cmake-ci-ext\\$CI_CONCURRENT_ID" CMAKE_GENERATOR: "Watcom WMake" CMAKE_CI_BUILD_TYPE: Release - CMAKE_CI_NIGHTLY_IGNORE_DEPS: "true" + CMAKE_CI_JOB_NIGHTLY_IGNORE_DEPS: "true" .windows_openwatcom1.9: extends: .windows_openwatcom @@ -271,7 +303,7 @@ variables: CMAKE_GENERATOR: "Ninja" CMAKE_CI_BUILD_TYPE: Release - CMAKE_CI_NIGHTLY_IGNORE_DEPS: "true" + CMAKE_CI_JOB_NIGHTLY_IGNORE_DEPS: "true" .windows_orangec6.73.1: extends: .windows_orangec @@ -279,6 +311,16 @@ variables: CMAKE_CONFIGURATION: windows_orangec6.73.1 +.windows_arm64_vs2026: + extends: .windows + + variables: + CMAKE_CONFIGURATION: windows_arm64_vs2026 + CMAKE_GENERATOR: "Visual Studio 18 2026" + CMAKE_GENERATOR_PLATFORM: "ARM64" + CMAKE_GENERATOR_TOOLSET: "v145,version=14.50.35717" + CMAKE_CI_JOB_NIGHTLY_IGNORE_DEPS: "true" + .windows_arm64_vs2022: extends: .windows @@ -287,7 +329,7 @@ CMAKE_GENERATOR: "Visual Studio 17 2022" CMAKE_GENERATOR_PLATFORM: "ARM64" CMAKE_GENERATOR_TOOLSET: "v143,version=14.44.35207" - CMAKE_CI_NIGHTLY_IGNORE_DEPS: "true" + CMAKE_CI_JOB_NIGHTLY_IGNORE_DEPS: "true" .mingw_osdn_io: extends: .windows @@ -296,7 +338,7 @@ # Place MinGW environment in a path without spaces. GIT_CLONE_PATH: "$CI_BUILDS_DIR\\cmake-ci-ext\\$CI_CONCURRENT_ID" CMAKE_CI_BUILD_TYPE: Debug - CMAKE_CI_NIGHTLY_IGNORE_DEPS: "true" + CMAKE_CI_JOB_NIGHTLY_IGNORE_DEPS: "true" .mingw_osdn_io_mingw_makefiles: extends: .mingw_osdn_io @@ -322,25 +364,44 @@ - sign-windows-v1 - nonconcurrent -.windows_x86_64_tags_nonconcurrent_vs2022: +.windows_x86_64_tags_nonconcurrent_vs2026: tags: - cmake # Since this is a bare runner, pin to a project. - windows-x86_64 - shell - - vs2022 - - msvc-14.44 + - vs2026 + - msvc-14.50 - nonconcurrent -.windows_x86_64_tags_nonconcurrent_vs2022_arm64: +.windows_x86_64_tags_nonconcurrent_vs2026_arm64: tags: - cmake # Since this is a bare runner, pin to a project. - windows-x86_64 - shell - - vs2022 - - msvc-14.44-arm64 + - vs2026 + - msvc-14.50-arm64 - nonconcurrent -.windows_x86_64_tags_concurrent_vs2022: +.windows_x86_64_tags_concurrent_vs2026: + tags: + - cmake # Since this is a bare runner, pin to a project. + - windows-x86_64 + - shell + - vs2026 + - msvc-14.50 + - concurrent + +.windows_x86_64_tags_concurrent_vs2026_android: + tags: + - cmake # Since this is a bare runner, pin to a project. + - windows-x86_64 + - shell + - vs2026 + - vs18-android + - msvc-14.50 + - concurrent + +.windows_x86_64_tags_concurrent_vs2022_msvc14.44: tags: - cmake # Since this is a bare runner, pin to a project. - windows-x86_64 @@ -385,15 +446,24 @@ - shell - concurrent -.windows_arm64_tags_nonconcurrent_vs2022: +.windows_arm64_tags_nonconcurrent_vs2026: tags: - cmake # Since this is a bare runner, pin to a project. - windows-arm64 - shell - - vs2022 - - msvc-14.44 + - vs2026 + - msvc-14.50 - nonconcurrent +.windows_arm64_tags_concurrent_vs2026: + tags: + - cmake # Since this is a bare runner, pin to a project. + - windows-arm64 + - shell + - vs2026 + - msvc-14.50 + - concurrent + .windows_arm64_tags_concurrent_vs2022: tags: - cmake # Since this is a bare runner, pin to a project. @@ -425,12 +495,14 @@ - Invoke-Expression -Command .gitlab/ci/vcvarsall.ps1 - sccache --start-server - sccache --show-stats - - (& "$pwsh" -File ".gitlab/ci/pre_build.ps1") + - (& "$pwsh" -File ".gitlab/ci/pre_configure.ps1") - ctest -VV -S .gitlab/ci/ctest_configure.cmake + - (& "$pwsh" -File ".gitlab/ci/pre_build.ps1") - ctest -VV -S .gitlab/ci/ctest_build.cmake - (& "$pwsh" -File ".gitlab/ci/post_build.ps1") - sccache --show-stats - - sccache --stop-server + # Tolerate already-stopped server. + - (sccache --stop-server) interruptible: true @@ -452,6 +524,7 @@ script: - *before_script_windows - Invoke-Expression -Command .gitlab/ci/vcvarsall.ps1 + - (& "$pwsh" -File ".gitlab/ci/pre_test.ps1") - ctest --output-on-failure -V -S .gitlab/ci/ctest_test.cmake interruptible: true
diff --git a/.gitlab/rules.yml b/.gitlab/rules.yml index efb7290..b0ac9a6 100644 --- a/.gitlab/rules.yml +++ b/.gitlab/rules.yml
@@ -1,117 +1,218 @@ # Rules for where jobs can run -.run_manually: - rules: - - if: '$CMAKE_CI_PACKAGE != null || $CMAKE_CI_VERSION_UPDATE != null' - when: never - - if: '($CMAKE_CI_NIGHTLY == "true" && $CMAKE_CI_JOB_NIGHTLY == "false")' - when: never - - if: '$CMAKE_CI_NIGHTLY == "true"' - when: on_success - - 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: manual - - when: never +### +## Job variables: +## CMAKE_CI_JOB_UPDATES_VERSION +## Set to "true" if the job performs a task that occurs with version +## updates. +## CMAKE_CI_JOB_UPDATES_WEBSITE_HELP +## Set to "true" if the job performs tasks to update website help. +## CMAKE_CI_JOB_NO_MR +## Set to "true" if the job should never run for merge requests. +## These jobs require secrets that MR pipelines cannot provide +## (software license information, upload secrets, etc.). +## CMAKE_CI_JOB_PACKAGE_ONLY +## Set to "true" if the job handles packaging tasks. These jobs will only +## run during packaging pipelines. +## CMAKE_CI_JOB_NIGHTLY +## Set to "true" if the job should only run for nightly pipelines. Set to +## "false" to suppress the job for nightly pipelines. +## CMAKE_CI_JOB_NIGHTLY_IGNORE_DEPS +## Set to "true" if the job should run even if dependent jobs fail (e.g., +## further testing of the same setup under a different generator. Should +## only be used on jobs with `needs` on other jobs. +## CMAKE_CI_JOB_RUN_MANUALLY +## Set to "true" if the job should be manually triggered in MRs. +## These jobs will also be delayed for branch update pipelines. +## Pipeline variables: +## CMAKE_CI_VERSION_UPDATE +## Set to "true" if the pipeline should perform version update tasks. +## No other tasks are performed if set. +## CMAKE_CI_PACKAGE +## Set to either "dev" or `vX.Y` to construct a packaging pipeline. Also +## uploads constructed packages. May also run website help jobs. No other +## tasks are performed if set. +## CMAKE_CI_NIGHTLY +## Set to "true" to enable nightly-only jobs. +## Project variables: +## CMAKE_CI_PROJECT_MAIN_BRANCH +## Set to the name of the main integration branch where development +## version documentation pipelines run. +## CMAKE_CI_PROJECT_CONTINUOUS_BRANCH +## Set to the name of the staging branch where continuous pipelines run. +#### -.run_automatically: - rules: - - if: '$CMAKE_CI_PACKAGE != null || $CMAKE_CI_VERSION_UPDATE != null' - when: never - - if: '($CMAKE_CI_NIGHTLY == "true" && $CMAKE_CI_JOB_NIGHTLY == "false")' - when: never - - if: '$CMAKE_CI_NIGHTLY == "true"' - when: on_success - - 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 - - when: never +variables: + CMAKE_CI_PIPELINE_NAME: 'Branch "$CI_COMMIT_REF_NAME"' -.run_dependent: +# When to even consider running a pipeline. +workflow: + name: "$CMAKE_CI_PIPELINE_NAME" rules: - - if: '$CMAKE_CI_PACKAGE != null || $CMAKE_CI_VERSION_UPDATE != null' - when: never - - if: '($CMAKE_CI_NIGHTLY == "true" && $CMAKE_CI_JOB_NIGHTLY == "false")' - when: never - - if: '($CMAKE_CI_NIGHTLY == "true" && $CMAKE_CI_NIGHTLY_IGNORE_DEPS == "true")' + # Run for merge requests. + - if: '$CI_MERGE_REQUEST_ID' when: always - - if: '$CMAKE_CI_NIGHTLY == "true"' - when: on_success - - if: '$CMAKE_CI_JOB_NIGHTLY == "true"' + auto_cancel: + # Cancel all pipeline jobs if a new commit comes in on the branch/tag. + on_new_commit: interruptible + variables: + CMAKE_CI_PIPELINE_NAME: 'Merge request !$CI_MERGE_REQUEST_IID' + # If this is not a MR, do not run for other projects. + - if: '$CI_PROJECT_PATH != "cmake/cmake" && $CMAKE_CI_PROJECT_CONTINUOUS_BRANCH == null && $CMAKE_CI_PROJECT_MAIN_BRANCH == null' 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"' - when: on_success + # Run for schedules. + - if: '$CI_PIPELINE_SOURCE == "schedule"' + when: always + auto_cancel: + # Never cancel scheduled pipelines because of new commits. + on_new_commit: none + variables: + CMAKE_CI_PIPELINE_NAME: 'Schedule "$CI_PIPELINE_SCHEDULE_DESCRIPTION"' + # Run for development documentation. + - if: '$CMAKE_CI_PROJECT_MAIN_BRANCH != null && $CI_COMMIT_BRANCH != null && $CMAKE_CI_PROJECT_MAIN_BRANCH == $CI_COMMIT_BRANCH' + when: always + variables: + CMAKE_CI_PIPELINE_NAME: 'Development documentation on branch "$CI_COMMIT_REF_NAME"' + # Run for continuous testing of staging branch. + - if: '$CMAKE_CI_PROJECT_CONTINUOUS_BRANCH != null && $CI_COMMIT_BRANCH != null && $CMAKE_CI_PROJECT_CONTINUOUS_BRANCH == $CI_COMMIT_BRANCH' + when: always + variables: + CMAKE_CI_PIPELINE_NAME: 'Continuous branch "$CI_COMMIT_REF_NAME"' + # Run for protected branches. + - if: '$CI_COMMIT_REF_PROTECTED == "true"' + when: always + auto_cancel: + # Cancel all pipeline jobs if a new commit comes in on the branch. + on_new_commit: interruptible + variables: + CMAKE_CI_PIPELINE_NAME: 'Protected branch "$CI_COMMIT_REF_NAME"' + # Run for tags. + - if: '$CI_COMMIT_TAG' + when: always + variables: + CMAKE_CI_PIPELINE_NAME: 'Tag "$CI_COMMIT_TAG"' + # Skip pipelines in all other cases. - when: never -.run_only_for_package: +.rules: rules: - - if: '$CMAKE_CI_PACKAGE == "dev" && $CI_JOB_STAGE != "upload"' + ### Version update pipelines. + # Version update pipelines run version update jobs automatically. + - if: '$CMAKE_CI_VERSION_UPDATE == "true" && $CMAKE_CI_JOB_UPDATES_VERSION == "true"' when: on_success - - if: '$CMAKE_CI_PACKAGE == "dev" && $CI_JOB_STAGE == "upload"' - variables: - RSYNC_DESTINATION: "kitware@cmake.org:dev/" - when: on_success - - if: '$CMAKE_CI_PACKAGE != null && $CI_JOB_STAGE == "prep"' - when: manual - - if: '$CMAKE_CI_PACKAGE != null && $CI_JOB_STAGE != "upload"' - when: on_success - - if: '$CMAKE_CI_PACKAGE != null && $CI_JOB_STAGE == "upload" && $CMAKE_CI_PACKAGE_URL != null' - variables: - RSYNC_DESTINATION: "$CMAKE_CI_PACKAGE_URL" - when: on_success - - when: never - -.run_cmake_org_help: - rules: + # Version update pipelines run no other jobs. - if: '$CMAKE_CI_VERSION_UPDATE != null' when: never - - if: '$CMAKE_CI_PACKAGE =~ /v[0-9]+\.[0-9]+/' + # Version update jobs do not run in any other situations. + - if: '$CMAKE_CI_JOB_UPDATES_VERSION == "true"' + when: never + + ### Website help update jobs run in a variety of pipeline kinds. + # Packaging pipelines upload release version documentation to the website upon request. + - if: '$CMAKE_CI_PACKAGE =~ /v[0-9]+\.[0-9]+/ && $CMAKE_CI_JOB_UPDATES_WEBSITE_HELP == "true"' variables: RSYNC_DESTINATION: "kitware@cmake.org:$CMAKE_CI_PACKAGE/" CMAKE_CI_SPHINX_QTHELP: "ON" CMAKE_CI_VERSION_NO_GIT: "ON" when: manual - - if: '$CMAKE_CI_PROJECT_MAIN_BRANCH != null && $CI_COMMIT_BRANCH != null && $CMAKE_CI_PROJECT_MAIN_BRANCH == $CI_COMMIT_BRANCH' + # Development documentation pipelines upload documentation to the website automatically. + - if: '$CMAKE_CI_PROJECT_MAIN_BRANCH != null && $CI_COMMIT_BRANCH != null && $CMAKE_CI_PROJECT_MAIN_BRANCH == $CI_COMMIT_BRANCH && $CMAKE_CI_JOB_UPDATES_WEBSITE_HELP == "true"' variables: RSYNC_DESTINATION: "kitware@cmake.org:git-master/" CMAKE_CI_SPHINX_QTHELP: "OFF" CMAKE_CI_VERSION_NO_GIT: "OFF" when: on_success - - if: '$CMAKE_CI_PROJECT_CONTINUOUS_BRANCH != null && $CI_COMMIT_BRANCH != null && $CMAKE_CI_PROJECT_CONTINUOUS_BRANCH == $CI_COMMIT_BRANCH' + # Continuous pipelines upload staging branch documentation to the website automatically. + - if: '$CMAKE_CI_PROJECT_CONTINUOUS_BRANCH != null && $CI_COMMIT_BRANCH != null && $CMAKE_CI_PROJECT_CONTINUOUS_BRANCH == $CI_COMMIT_BRANCH && $CMAKE_CI_JOB_UPDATES_WEBSITE_HELP == "true"' variables: RSYNC_DESTINATION: "kitware@cmake.org:git-stage/" CMAKE_CI_SPHINX_QTHELP: "OFF" CMAKE_CI_VERSION_NO_GIT: "OFF" when: on_success - - when: never + # Website help update jobs do not run in any other situations. + - if: '$CMAKE_CI_JOB_UPDATES_WEBSITE_HELP == "true"' + when: never -.run_version_update: - rules: - - if: '$CMAKE_CI_VERSION_UPDATE != null' + ### Packaging pipelines. + # Packaging pipelines build development version packages automatically. + - if: '$CMAKE_CI_PACKAGE == "dev" && $CMAKE_CI_JOB_PACKAGE_ONLY == "true" && $CI_JOB_STAGE != "upload"' when: on_success - - when: never + # Packaging pipelines upload development version packages to the website automatically. + - if: '$CMAKE_CI_PACKAGE == "dev" && $CMAKE_CI_JOB_PACKAGE_ONLY == "true" && $CI_JOB_STAGE == "upload"' + variables: + RSYNC_DESTINATION: "kitware@cmake.org:dev/" + when: on_success + # Packaging pipelines build release version packages upon request. + - if: '$CMAKE_CI_PACKAGE != null && $CMAKE_CI_JOB_PACKAGE_ONLY == "true" && $CI_JOB_STAGE == "prep"' + when: manual + - if: '$CMAKE_CI_PACKAGE != null && $CMAKE_CI_JOB_PACKAGE_ONLY == "true" && $CI_JOB_STAGE != "upload"' + when: on_success + # Packaging pipelines upload release version packages to a staging area. + - if: '$CMAKE_CI_PACKAGE != null && $CMAKE_CI_JOB_PACKAGE_ONLY == "true" && $CI_JOB_STAGE == "upload" && $CMAKE_CI_PACKAGE_URL != null' + variables: + RSYNC_DESTINATION: "$CMAKE_CI_PACKAGE_URL" + when: on_success + # Packaging pipelines run no other jobs. + - if: '$CMAKE_CI_PACKAGE != null' + when: never + # Package-only jobs do not run in any other situations. + - if: '$CMAKE_CI_JOB_PACKAGE_ONLY == "true"' + when: never + + ### Development documentation pipelines. + # Development documentation pipelines run no other jobs. + - if: '$CMAKE_CI_PROJECT_MAIN_BRANCH != null && $CI_COMMIT_BRANCH != null && $CMAKE_CI_PROJECT_MAIN_BRANCH == $CI_COMMIT_BRANCH' + when: never + + ### Continuous pipelines. + # Continuous pipelines run manual jobs automatically after 5 minutes. + - if: '$CMAKE_CI_PROJECT_CONTINUOUS_BRANCH != null && $CI_COMMIT_BRANCH != null && $CMAKE_CI_PROJECT_CONTINUOUS_BRANCH == $CI_COMMIT_BRANCH && $CMAKE_CI_JOB_CONTINUOUS == "true" && $CMAKE_CI_JOB_RUN_MANUALLY == "true"' + when: delayed + start_in: 5 minutes + # Continuous pipelines run other jobs automatically. + - 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 + # Continuous pipelines run no other jobs. + - if: '$CMAKE_CI_PROJECT_CONTINUOUS_BRANCH != null && $CI_COMMIT_BRANCH != null && $CMAKE_CI_PROJECT_CONTINUOUS_BRANCH == $CI_COMMIT_BRANCH' + when: never + + ### Nightly pipelines. + # Nightly pipelines do not run jobs that are explicitly excluded. + - if: '$CMAKE_CI_NIGHTLY == "true" && $CMAKE_CI_JOB_NIGHTLY == "false"' + when: never + # Nightly pipelines always run jobs that ignore their dependencies. + - if: '$CMAKE_CI_NIGHTLY == "true" && $CMAKE_CI_JOB_NIGHTLY_IGNORE_DEPS == "true"' + when: always + # Nightly pipelines run all other jobs automatically when ready. + - if: '$CMAKE_CI_NIGHTLY == "true"' + when: on_success + # Nightly-only jobs do not run in any other situations. + - if: '$CMAKE_CI_JOB_NIGHTLY == "true"' + when: never + + ### Merge request pipelines. + # Merge request pipelines do not run jobs that are explicitly excluded. + - if: '$CI_MERGE_REQUEST_ID && $CMAKE_CI_JOB_NO_MR == "true"' + when: never + # Merge request pipelines run manual jobs upon request. + - if: '$CI_MERGE_REQUEST_ID && $CMAKE_CI_JOB_RUN_MANUALLY == "true"' + when: manual + # Merge request pipelines run other jobs automatically when ready. + - if: '$CI_MERGE_REQUEST_ID' + when: on_success + + ### Scheduled pipelines. + # Scheduled pipelines run all jobs automatically when ready. + - if: '$CI_PIPELINE_SOURCE == "schedule"' + when: on_success + + ### Other pipelines. + # Other pipelines run manual jobs upon request. + - if: '$CMAKE_CI_JOB_RUN_MANUALLY == "true"' + when: manual + # Other pipelines run jobs in the `build` stage automatically after 5 minutes. + - if: '$CI_JOB_STAGE == "build"' + when: delayed + start_in: 5 minutes + # Other pipelines run other jobs automatically when ready. + - when: on_success
diff --git a/.gitlab/upload.yml b/.gitlab/upload.yml index c489c54..47316d1 100644 --- a/.gitlab/upload.yml +++ b/.gitlab/upload.yml
@@ -1,7 +1,7 @@ # Steps for uploading artifacts .rsync_upload_package: - image: "fedora:42" + image: "fedora:43" stage: upload tags: - cmake @@ -21,7 +21,7 @@ .rsync_upload_help: stage: upload - image: "fedora:42" + image: "fedora:43" tags: - cmake - docker
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 8b6d940..64acb89 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml
@@ -29,7 +29,7 @@ - id: check-useless-excludes - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v5.0.0 + rev: v6.0.0 hooks: - id: check-case-conflict - id: check-json @@ -39,6 +39,7 @@ CMakeLib/testCTestResourceSpec_data/spec13 | RunCMake/CTestResourceAllocation/invalid )\.json + - id: check-toml - id: check-yaml - id: end-of-file-fixer # NOTE Exclude tests directory: some test files have no @@ -61,8 +62,11 @@ | define_property/define_property-INITIALIZE_FROM_VARIABLE-invalid_[12]-result\.txt | FindMatlab/MatlabTest2-stderr\.txt | string/UTF-(16|32)LE\.txt - | Syntax/BOM-UTF-(16|32)-LE.cmake - | Syntax/CommandEOF\.cmake + | Syntax/( + OneCharacter + | (Broken-)?BOM-UTF-(16|32)-[BL]E + | CommandEOF + )\.cmake | VS10Project/shader2?\.hlsl ) | SourceGroups/README\.txt @@ -80,7 +84,7 @@ pass_filenames: false - repo: https://github.com/sphinx-contrib/sphinx-lint - rev: v1.0.0 + rev: v1.0.2 hooks: - id: sphinx-lint # NOTE Looks like `bad-dedent` gives too many false-positives. @@ -102,13 +106,14 @@ - id: rst-inline-touching-normal - repo: https://github.com/codespell-project/codespell - rev: v2.4.0 + rev: v2.4.1 hooks: - id: codespell stages: [commit-msg, pre-commit] - - repo: https://github.com/crate-ci/typos - rev: v1.30.0 + # NOTE See BUG https://github.com/crate-ci/typos/issues/390 + - repo: https://github.com/adhtruong/mirrors-typos + rev: v1.44.0 hooks: - id: typos # NOTE Override hook's default args to prevent automatic
diff --git a/.typos.toml b/.typos.toml index 5ad2245..0db7ca8 100644 --- a/.typos.toml +++ b/.typos.toml
@@ -5,10 +5,10 @@ check-file = true check-filename = true extend-ignore-re = [ - # NOTE Allow to mark a block of text to exclude from spellchecking - "(?s)(#|/(/|\\*)|\\.\\.)\\s*(NOQA|noqa):? spellcheck(: *|=| +)off.*?\\n\\s*(#|/(/|\\*)|\\.\\.)\\s*(NOQA|noqa):? spellcheck(: *|=| +)on" + # NOTE Allow to mark block of text to exclude from spellchecking inside C++ or hash-style comments (CMake,Python,&etc.) + "(?s)(#|//)\\s*(NOQA|noqa):? spellcheck(: *|=| +)off.*?\\n\\s*(#|//)\\s*(NOQA|noqa):? spellcheck(: *|=| +)on" # NOTE Allow to mark a line to exclude from spellchecking - , "(?Rm)^.*(#|/(/|\\*)|\\.\\.)\\s*(NOQA|noqa):? spellcheck(: *|=| +)disable-line$" + , "(?Rm)^.*(#|//)\\s*(NOQA|noqa):? spellcheck(: *|=| +)disable-line$" # NOTE Stop checking from this line to the end of file # This line is a marker added by Git to the `COMMIT_EDITMSG`. , "(?sm)^# ------------------------ >8 ------------------------$.*" @@ -18,7 +18,13 @@ # `extend-ignore-identifiers-re` to this section, # please also modify the `.gitlab/ci/typos.bash` # script accordingly. -#extend-ignore-identifiers-re=["\\b[0-9a-f]{10}\\b"] +#extend-ignore-identifiers-re=["\\b[0-9a-f]{8,12}\\b"] + +[default.extend-identifiers] +_tru64 = "_tru64" +__tru64 = "__tru64" +__TRU64__ = "__TRU64__" +Tru64 = "Tru64" # Add repo-wide false positives here in the form of `word = "word"`. # Check the manual for details. @@ -34,31 +40,10 @@ restat = "restat" # SpectreMitigation Spectre = "Spectre" - -[type.cmake.extend-identifiers] -COMMANDs = "COMMANDs" -xCOMMANDx = "xCOMMANDx" -TYPEs = "TYPEs" - -[type.cmake.extend-words] -# Some compiler's options trigger false-positives -Fo = "Fo" -ot = "ot" -# Part of compiler executable name, e.g., `arm-unknown-nto-qnx6`, but also could be in a literal string. -nto = "nto" - -[type.cpp.extend-identifiers] -APPENDed = "APPENDed" - -[type.json.extend-identifiers] -# Some compiler options from `Templates/MSBuild/FlagTables/*.json` trigger too many false-positives. -Fo = "Fo" -fo = "fo" -Ot = "Ot" -SEH = "SEH" - -[type.py.extend-identifiers] -typ = "typ" +# Identifier used in source code (`GlobalTargetInfo`) +gti = "gti" +# StrCpy in NSIS input. +Cpy = "Cpy" [files] ignore-hidden = false @@ -77,3 +62,41 @@ # FIXME: Fix spelling typos in tests. Exclude for now. , "Tests" ] + +# BEGIN Type-specific settings +[type.cmake.extend-identifiers] +COMMANDs = "COMMANDs" +xCOMMANDx = "xCOMMANDx" +TYPEs = "TYPEs" + +[type.cmake.extend-words] +# Some compiler's options trigger false-positives +Fo = "Fo" +ot = "ot" +# Part of compiler executable name, e.g., `arm-unknown-nto-qnx6`, but also could be in a literal string. +nto = "nto" + +[type.cpp.extend-identifiers] +APPENDed = "APPENDed" +setp = "setp" +setp_ = "setp_" + +[type.json.extend-identifiers] +# Some compiler options from `Templates/MSBuild/FlagTables/*.json` trigger too many false-positives. +Fo = "Fo" +fo = "fo" +Ot = "Ot" +SEH = "SEH" + +[type.py.extend-identifiers] +typ = "typ" + +[type.sh.extend-identifiers] +xTRUEx = "xTRUEx" + +[type.rst] +extend-ignore-re = [ + # NOTE Allow to mark block of text to exclude from spellchecking as RST comments + "(?s)\\.\\.\\s+(NOQA|noqa):? spellcheck(: *|=| +)off.*?\\n\\.\\.\\s+(NOQA|noqa):? spellcheck(: *|=| +)on" + ] +# END Type-specific settings
diff --git a/Auxiliary/CMakeLists.txt b/Auxiliary/CMakeLists.txt index c0aebef..ff6d308 100644 --- a/Auxiliary/CMakeLists.txt +++ b/Auxiliary/CMakeLists.txt
@@ -1,16 +1,16 @@ # Install Vim files to a typical system integration directory. # Packagers can set CMake_INSTALL_VIMFILES_DIR to control this. if(NOT CMake_INSTALL_VIMFILES_DIR) - set(CMake_INSTALL_VIMFILES_DIR ${CMAKE_XDGDATA_DIR}/vim/vimfiles) + set(CMake_INSTALL_VIMFILES_DIR ${CMake_INSTALL_XDGDATA_DIR}/vim/vimfiles) endif() install(DIRECTORY vim/indent vim/syntax DESTINATION ${CMake_INSTALL_VIMFILES_DIR}) # Install Emacs files to a typical system integration directory. # Packagers can set CMake_INSTALL_EMACS_DIR to control this. if(NOT CMake_INSTALL_EMACS_DIR) - set(CMake_INSTALL_EMACS_DIR ${CMAKE_XDGDATA_DIR}/emacs/site-lisp) + set(CMake_INSTALL_EMACS_DIR ${CMake_INSTALL_XDGDATA_DIR}/emacs/site-lisp) endif() install(FILES cmake-mode.el DESTINATION ${CMake_INSTALL_EMACS_DIR}) -install(FILES cmake.m4 DESTINATION ${CMAKE_XDGDATA_DIR}/aclocal) +install(FILES cmake.m4 DESTINATION ${CMake_INSTALL_XDGDATA_DIR}/aclocal) add_subdirectory (bash-completion)
diff --git a/Auxiliary/bash-completion/CMakeLists.txt b/Auxiliary/bash-completion/CMakeLists.txt index 93b6ffd..2c9e448 100644 --- a/Auxiliary/bash-completion/CMakeLists.txt +++ b/Auxiliary/bash-completion/CMakeLists.txt
@@ -15,7 +15,7 @@ set(CMake_INSTALL_BASH_COMP_DIR "${CMAKE_BASH_COMP_DIR}") else() # Default. - set(CMake_INSTALL_BASH_COMP_DIR ${CMAKE_XDGDATA_DIR}/bash-completion/completions) + set(CMake_INSTALL_BASH_COMP_DIR ${CMake_INSTALL_XDGDATA_DIR}/bash-completion/completions) endif() endif() install(FILES cmake cpack ctest DESTINATION ${CMake_INSTALL_BASH_COMP_DIR})
diff --git a/Auxiliary/vim/cmake.vim.in b/Auxiliary/vim/cmake.vim.in index 39d7193..a7c857e 100644 --- a/Auxiliary/vim/cmake.vim.in +++ b/Auxiliary/vim/cmake.vim.in
@@ -13,16 +13,25 @@ " https://cmake.org/licensing " This implies that distribution with Vim is allowed -if exists("b:current_syntax") +if exists('b:current_syntax') finish endif -let s:keepcpo= &cpo -set cpo&vim +let s:keepcpo= &cpoptions +set cpoptions&vim -syn region cmakeBracketArgument start="\[\z(=\?\|=[0-9]*\)\[" end="\]\z1\]" contains=cmakeTodo,@Spell +syn cluster cmakeControl contains= + \ cmakeIf, + \ cmakeElse, + \ cmakeForeach, + \ cmakeWhile, + \ cmakeBlock, + \ cmakeFunction, + \ cmakeMacro -syn region cmakeComment start="#" end="$" contains=cmakeTodo,@Spell -syn region cmakeBracketComment start="\[\z(=*\)\[" end="\]\z1\]" contains=cmakeTodo,@Spell +syn region cmakeBracketArgument start="\[\z(=*\)\[" end="\]\z1\]" fold contains=cmakeTodo,@Spell + +syn region cmakeComment start="#\(\[=*\[\)\@!" end="$" contains=cmakeTodo,@Spell +syn region cmakeBracketComment start="#\[\z(=*\)\[" end="\]\z1\]" fold contains=cmakeTodo,@Spell syn match cmakeEscaped /\(\\\\\|\\"\|\\n\|\\t\)/ contained syn region cmakeRegistry start="\[" end="]" contained oneline contains=cmakeTodo,cmakeEscaped @@ -35,7 +44,15 @@ syn region cmakeEnvironment start="$ENV{" end="}" contained oneline contains=cmakeTodo -syn region cmakeArguments start="(" end=")" contains=ALLBUT,cmakeGeneratorExpressions,cmakeCommand,cmakeCommandConditional,cmakeCommandRepeat,cmakeCommandDeprecated,cmakeCommandManuallyAdded,cmakeArguments,cmakeTodo,@Spell +syn region cmakeArguments start="(" end=")" contains=ALLBUT,@cmakeControl,cmakeGeneratorExpressions,cmakeCommand,cmakeCommandDeprecated,cmakeCommandManuallyAdded,cmakeArguments,cmakeTodo,@Spell fold +syn region cmakeIf matchgroup=cmakeKeyword start=/^\s*\<if\>/ end=/^\s*\<endif\>/ transparent fold contains=@cmakeControl,cmakeArguments +syn match cmakeElse /^\s*\<else\(if\)\?\>/ contained contains=NONE + +syn region cmakeForeach matchgroup=cmakeKeyword start=/^\s*\<foreach\>/ end=/^\s*\<endforeach\>/ transparent fold contains=@cmakeControl,cmakeArguments +syn region cmakeWhile matchgroup=cmakeKeyword start=/^\s*\<while\>/ end=/^\s*\<endwhile\>/ transparent fold contains=@cmakeControl,cmakeArguments +syn region cmakeFunction matchgroup=cmakeKeyword start=/^\s*\<function\>/ end=/^\s*\<endfunction\>/ transparent fold contains=@cmakeControl,cmakeArguments +syn region cmakeBlock matchgroup=cmakeKeyword start=/^\s*\<block\>/ end=/^\s*\<endblock\>/ transparent fold contains=@cmakeControl,cmakeArguments +syn region cmakeMacro matchgroup=cmakeKeyword start=/^\s*\<macro\>/ end=/^\s*\<endmacro\>/ transparent fold contains=@cmakeControl,cmakeArguments syn case match @@ -59,14 +76,6 @@ @COMMAND_LIST@ \ nextgroup=cmakeArguments -syn keyword cmakeCommandConditional -@CONDITIONALS@ - \ nextgroup=cmakeArguments - -syn keyword cmakeCommandRepeat -@LOOPS@ - \ nextgroup=cmakeArguments - syn keyword cmakeCommandDeprecated @DEPRECATED@ \ nextgroup=cmakeArguments @@ -80,14 +89,14 @@ hi def link cmakeBracketArgument String hi def link cmakeBracketComment Comment hi def link cmakeCommand Function -hi def link cmakeCommandConditional Conditional hi def link cmakeCommandDeprecated WarningMsg -hi def link cmakeCommandRepeat Repeat hi def link cmakeComment Comment +hi def link cmakeElse Conditional hi def link cmakeEnvironment Special hi def link cmakeEscaped Special hi def link cmakeGeneratorExpression WarningMsg hi def link cmakeGeneratorExpressions Constant +hi def link cmakeKeyword Conditional hi def link cmakeModule Include hi def link cmakeProperty Constant hi def link cmakeRegistry Underlined @@ -122,9 +131,9 @@ hi def link cmakeKWwrite_basic_package_version_file ModeMsg hi def link cmakeKWconfigure_package_config_file_constants Constant -let b:current_syntax = "cmake" +let b:current_syntax = 'cmake' -let &cpo = s:keepcpo +let &cpoptions = s:keepcpo unlet s:keepcpo " vim: set nowrap:
diff --git a/Auxiliary/vim/extract-upper-case.pl b/Auxiliary/vim/extract-upper-case.pl index 7f40b74..ed821b5 100755 --- a/Auxiliary/vim/extract-upper-case.pl +++ b/Auxiliary/vim/extract-upper-case.pl
@@ -24,7 +24,7 @@ # control-statements my %conditional = map { $_ => 1 } qw(if else elseif endif); -my %loop = map { $_ => 1 } qw(foreach while endforeach endwhile); +my %loopetc = map { $_ => 1 } qw(block foreach function macro while endblock endfunction endforeach endmacro endwhile); # decrecated my %deprecated = map { $_ => 1 } qw(build_name exec_program export_library_dependencies install_files install_programs install_targets link_libraries make_directory output_required_files remove subdir_depends subdirs use_mangled_mesa utility_source variable_requires write_file); @@ -141,7 +141,7 @@ if ($1 eq "COMMAND_LIST") { # do not include "special" commands in this list my @tmp = grep { ! exists $conditional{$_} and - ! exists $loop{$_} and + ! exists $loopetc{$_} and ! exists $deprecated{$_} } @commands; print_list(\*OUT, @tmp); } elsif ($1 eq "VARIABLE_LIST") { @@ -150,10 +150,6 @@ print_list(\*OUT, @modules); } elsif ($1 eq "GENERATOR_EXPRESSIONS") { print_list(\*OUT, @generator_expr); - } elsif ($1 eq "CONDITIONALS") { - print_list(\*OUT, keys %conditional); - } elsif ($1 eq "LOOPS") { - print_list(\*OUT, keys %loop); } elsif ($1 eq "DEPRECATED") { print_list(\*OUT, keys %deprecated); } elsif ($1 eq "PROPERTIES") {
diff --git a/Auxiliary/vim/indent/cmake.vim b/Auxiliary/vim/indent/cmake.vim index 28ecf84..fe30643 100644 --- a/Auxiliary/vim/indent/cmake.vim +++ b/Auxiliary/vim/indent/cmake.vim
@@ -9,7 +9,7 @@ " https://cmake.org/licensing " This implies that distribution with Vim is allowed -if exists("b:did_indent") +if exists('b:did_indent') finish endif let b:did_indent = 1 @@ -20,11 +20,11 @@ let b:undo_indent = "setl inde< indk<" " Only define the function once. -if exists("*CMakeGetIndent") +if exists('*CMakeGetIndent') finish endif -let s:keepcpo= &cpo -set cpo&vim +let s:keepcpo= &cpoptions +set cpoptions&vim fun! CMakeGetIndent(lnum) let this_line = getline(a:lnum) @@ -95,5 +95,5 @@ return ind endfun -let &cpo = s:keepcpo +let &cpoptions = s:keepcpo unlet s:keepcpo
diff --git a/Auxiliary/vim/syntax/cmake.vim b/Auxiliary/vim/syntax/cmake.vim index 64e18e8..280dd9b 100644 --- a/Auxiliary/vim/syntax/cmake.vim +++ b/Auxiliary/vim/syntax/cmake.vim
@@ -1,13 +1,13 @@ " Vim syntax file " Program: CMake - Cross-Platform Makefile Generator -" Version: cmake version 3.27.20230713-gdc88dd5 +" Version: cmake version 4.1.20250715-g2c3f83a " Language: CMake " Author: Andy Cedilnik <andy.cedilnik@kitware.com>, " Nicholas Hutchinson <nshutchinson@gmail.com>, " Patrick Boettcher <patrick.boettcher@posteo.de> " Maintainer: Dimitri Merejkowsky <d.merej@gmail.com> " Former Maintainer: Karthik Krishnan <karthik.krishnan@kitware.com> -" Last Change: 2023 Jul 13 +" Last Change: 2025 Jul 15 " " License: The CMake license applies to this file. See " https://cmake.org/licensing @@ -19,10 +19,19 @@ let s:keepcpo= &cpo set cpo&vim -syn region cmakeBracketArgument start="\[\z(=*\)\[" end="\]\z1\]" contains=cmakeTodo,@Spell +syn cluster cmakeControl contains= + \ cmakeIf, + \ cmakeElse, + \ cmakeForeach, + \ cmakeWhile, + \ cmakeBlock, + \ cmakeFunction, + \ cmakeMacro + +syn region cmakeBracketArgument start="\[\z(=*\)\[" end="\]\z1\]" fold contains=cmakeTodo,@Spell syn region cmakeComment start="#\(\[=*\[\)\@!" end="$" contains=cmakeTodo,@Spell -syn region cmakeBracketComment start="#\[\z(=*\)\[" end="\]\z1\]" contains=cmakeTodo,@Spell +syn region cmakeBracketComment start="#\[\z(=*\)\[" end="\]\z1\]" fold contains=cmakeTodo,@Spell syn match cmakeEscaped /\(\\\\\|\\"\|\\n\|\\t\)/ contained syn region cmakeRegistry start="\[" end="]" contained oneline contains=cmakeTodo,cmakeEscaped @@ -35,7 +44,15 @@ syn region cmakeEnvironment start="$ENV{" end="}" contained oneline contains=cmakeTodo -syn region cmakeArguments start="(" end=")" contains=ALLBUT,cmakeGeneratorExpressions,cmakeCommand,cmakeCommandConditional,cmakeCommandRepeat,cmakeCommandDeprecated,cmakeCommandManuallyAdded,cmakeArguments,cmakeTodo,@Spell +syn region cmakeArguments start="(" end=")" contains=ALLBUT,@cmakeControl,cmakeGeneratorExpressions,cmakeCommand,cmakeCommandDeprecated,cmakeCommandManuallyAdded,cmakeArguments,cmakeTodo,@Spell fold +syn region cmakeIf matchgroup=cmakeKeyword start=/^\s*\<if\>/ end=/^\s*\<endif\>/ transparent fold contains=@cmakeControl,cmakeArguments +syn match cmakeElse /^\s*\<else\(if\)\?\>/ contained contains=NONE + +syn region cmakeForeach matchgroup=cmakeKeyword start=/^\s*\<foreach\>/ end=/^\s*\<endforeach\>/ transparent fold contains=@cmakeControl,cmakeArguments +syn region cmakeWhile matchgroup=cmakeKeyword start=/^\s*\<while\>/ end=/^\s*\<endwhile\>/ transparent fold contains=@cmakeControl,cmakeArguments +syn region cmakeFunction matchgroup=cmakeKeyword start=/^\s*\<function\>/ end=/^\s*\<endfunction\>/ transparent fold contains=@cmakeControl,cmakeArguments +syn region cmakeBlock matchgroup=cmakeKeyword start=/^\s*\<block\>/ end=/^\s*\<endblock\>/ transparent fold contains=@cmakeControl,cmakeArguments +syn region cmakeMacro matchgroup=cmakeKeyword start=/^\s*\<macro\>/ end=/^\s*\<endmacro\>/ transparent fold contains=@cmakeControl,cmakeArguments syn case match @@ -45,6 +62,7 @@ \ ADDITIONAL_MAKE_CLEAN_FILES \ ADVANCED \ AIX_EXPORT_ALL_SYMBOLS + \ AIX_SHARED_LIBRARY_ARCHIVE \ ALIASED_TARGET \ ALIAS_GLOBAL \ ALLOW_DUPLICATE_CUSTOM_TARGETS @@ -69,20 +87,20 @@ \ ARCHIVE_OUTPUT_NAME \ ATTACHED_FILES \ ATTACHED_FILES_ON_FAIL + \ AUTOGEN_BETTER_GRAPH_MULTI_CONFIG \ AUTOGEN_BUILD_DIR \ AUTOGEN_COMMAND_LINE_LENGTH_MAX \ AUTOGEN_ORIGIN_DEPENDS \ AUTOGEN_PARALLEL \ AUTOGEN_SOURCE_GROUP - \ AUTOGEN_USE_SYSTEM_INCLUDE \ AUTOGEN_TARGETS_FOLDER \ AUTOGEN_TARGET_DEPENDS \ AUTOGEN_USE_SYSTEM_INCLUDE - \ AUTOGEN_BETTER_GRAPH_MULTI_CONFIG \ AUTOMOC \ AUTOMOC_COMPILER_PREDEFINES \ AUTOMOC_DEPEND_FILTERS \ AUTOMOC_EXECUTABLE + \ AUTOMOC_INCLUDE_DIRECTORIES \ AUTOMOC_MACRO_NAMES \ AUTOMOC_MOC_OPTIONS \ AUTOMOC_PATH_PREFIX @@ -111,6 +129,7 @@ \ CMAKE_CUDA_KNOWN_FEATURES \ CMAKE_CXX_KNOWN_FEATURES \ CMAKE_C_KNOWN_FEATURES + \ CMAKE_HIP_KNOWN_FEATURES \ CMAKE_ROLE \ COMMON_LANGUAGE_RUNTIME \ COMPATIBLE_INTERFACE_BOOL @@ -147,15 +166,16 @@ \ CXX_MODULE_DIRS \ CXX_MODULE_SET \ CXX_MODULE_SETS + \ CXX_MODULE_STD \ CXX_SCAN_FOR_MODULES \ CXX_STANDARD \ CXX_STANDARD_REQUIRED \ C_EXTENSIONS \ C_STANDARD \ C_STANDARD_REQUIRED + \ DEBUGGER_WORKING_DIRECTORY \ DEBUG_CONFIGURATIONS \ DEBUG_POSTFIX - \ DEBUGGER_WORKING_DIRECTORY \ DEFINE_SYMBOL \ DEFINITIONS \ DEPENDS @@ -178,12 +198,16 @@ \ ENVIRONMENT_MODIFICATION \ EXCLUDE_FROM_ALL \ EXCLUDE_FROM_DEFAULT_BUILD + \ EXPORT_BUILD_DATABASE \ EXPORT_COMPILE_COMMANDS + \ EXPORT_FIND_PACKAGE_NAME \ EXPORT_NAME \ EXPORT_NO_SYSTEM \ EXPORT_PROPERTIES \ EXTERNAL_OBJECT \ EchoString + \ FASTBUILD_CACHING + \ FASTBUILD_DISTRIBUTION \ FAIL_REGULAR_EXPRESSION \ FIND_LIBRARY_USE_LIB32_PATHS \ FIND_LIBRARY_USE_LIB64_PATHS @@ -195,11 +219,13 @@ \ FOLDER \ FRAMEWORK \ FRAMEWORK_VERSION + \ Fortran_BUILDING_INSTRINSIC_MODULES \ Fortran_BUILDING_INTRINSIC_MODULES \ Fortran_FORMAT \ Fortran_MODULE_DIRECTORY \ Fortran_PREPROCESS \ GENERATED + \ GENERATED_RESOURCE_SPEC_FILE \ GENERATOR_FILE_NAME \ GENERATOR_IS_MULTI_CONFIG \ GHS_INTEGRITY_APP @@ -221,6 +247,11 @@ \ IMPORTED \ IMPORTED_COMMON_LANGUAGE_RUNTIME \ IMPORTED_CONFIGURATIONS + \ IMPORTED_CXX_MODULES_COMPILE_DEFINITIONS + \ IMPORTED_CXX_MODULES_COMPILE_FEATURES + \ IMPORTED_CXX_MODULES_COMPILE_OPTIONS + \ IMPORTED_CXX_MODULES_INCLUDE_DIRECTORIES + \ IMPORTED_CXX_MODULES_LINK_LIBRARIES \ IMPORTED_GLOBAL \ IMPORTED_IMPLIB \ IMPORTED_LIBNAME @@ -239,12 +270,12 @@ \ INCLUDE_DIRECTORIES \ INCLUDE_REGULAR_EXPRESSION \ INSTALL_NAME_DIR + \ INSTALL_PARALLEL \ INSTALL_REMOVE_ENVIRONMENT_RPATH \ INSTALL_RPATH \ INSTALL_RPATH_USE_LINK_PATH \ INTERFACE_AUTOMOC_MACRO_NAMES \ INTERFACE_AUTOUIC_OPTIONS - \ INTERFACE_AUTOMOC_MACRO_NAMES \ INTERFACE_COMPILE_DEFINITIONS \ INTERFACE_COMPILE_FEATURES \ INTERFACE_COMPILE_OPTIONS @@ -278,6 +309,7 @@ \ LIBRARY_OUTPUT_DIRECTORY \ LIBRARY_OUTPUT_NAME \ LINKER_LANGUAGE + \ LINKER_TYPE \ LINK_DEPENDS \ LINK_DEPENDS_NO_SHARED \ LINK_DIRECTORIES @@ -286,10 +318,12 @@ \ LINK_INTERFACE_MULTIPLICITY \ LINK_LIBRARIES \ LINK_LIBRARIES_ONLY_TARGETS + \ LINK_LIBRARIES_STRATEGY \ LINK_LIBRARY_OVERRIDE \ LINK_OPTIONS \ LINK_SEARCH_END_STATIC \ LINK_SEARCH_START_STATIC + \ LINK_WARNING_AS_ERROR \ LINK_WHAT_YOU_USE \ LISTFILE_STACK \ LOCATION @@ -340,6 +374,7 @@ \ PROCESSORS \ PROCESSOR_AFFINITY \ PROJECT_LABEL + \ PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE \ PUBLIC_HEADER \ REPORT_UNDEFINED_PROPERTIES \ REQUIRED_FILES @@ -366,6 +401,7 @@ \ SOURCES \ SOURCE_DIR \ SOVERSION + \ SPDX_LICENSE \ STATIC_LIBRARY_FLAGS \ STATIC_LIBRARY_OPTIONS \ STRINGS @@ -373,28 +409,33 @@ \ SUFFIX \ SYMBOLIC \ SYSTEM + \ Swift_COMPILATION_MODE \ Swift_DEPENDENCIES_FILE \ Swift_DIAGNOSTICS_FILE \ Swift_LANGUAGE_VERSION \ Swift_MODULE_DIRECTORY \ Swift_MODULE_NAME - \ Swift_COMPILATION_MODE \ TARGET_ARCHIVES_MAY_BE_SHARED_LIBS \ TARGET_MESSAGES \ TARGET_SUPPORTS_SHARED_LIBS \ TESTS \ TEST_INCLUDE_FILE \ TEST_INCLUDE_FILES + \ TEST_LAUNCHER \ TIMEOUT \ TIMEOUT_AFTER_MATCH \ TIMEOUT_SIGNAL_GRACE_PERIOD \ TIMEOUT_SIGNAL_NAME + \ TRANSITIVE_COMPILE_PROPERTIES + \ TRANSITIVE_LINK_PROPERTIES \ TYPE \ UNITY_BUILD \ UNITY_BUILD_BATCH_SIZE \ UNITY_BUILD_CODE_AFTER_INCLUDE \ UNITY_BUILD_CODE_BEFORE_INCLUDE + \ UNITY_BUILD_FILENAME_PREFIX \ UNITY_BUILD_MODE + \ UNITY_BUILD_RELOCATABLE \ UNITY_BUILD_UNIQUE_ID \ UNITY_GROUP \ USE_FOLDERS @@ -405,6 +446,7 @@ \ VISIBILITY_INLINES_HIDDEN \ VS_CONFIGURATION_TYPE \ VS_COPY_TO_OUT_DIR + \ VS_CUSTOM_COMMAND_DISABLE_PARALLEL_BUILD \ VS_DEBUGGER_COMMAND \ VS_DEBUGGER_COMMAND_ARGUMENTS \ VS_DEBUGGER_ENVIRONMENT @@ -418,6 +460,7 @@ \ VS_DOTNET_STARTUP_OBJECT \ VS_DOTNET_TARGET_FRAMEWORK_VERSION \ VS_DPI_AWARE + \ VS_FILTER_PROPS \ VS_FRAMEWORK_REFERENCES \ VS_GLOBAL_KEYWORD \ VS_GLOBAL_PROJECT_TYPES @@ -450,10 +493,11 @@ \ VS_SHADER_TYPE \ VS_SHADER_VARIABLE_NAME \ VS_SOLUTION_DEPLOY + \ VS_SOLUTION_ITEMS \ VS_STARTUP_PROJECT \ VS_TOOL_OVERRIDE \ VS_USER_PROPS - \ VS_FILTER_PROPS + \ VS_USE_DEBUG_LIBRARIES \ VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION \ VS_WINRT_COMPONENT \ VS_WINRT_EXTENSIONS @@ -479,45 +523,46 @@ \ XCODE_SCHEME_ARGUMENTS \ XCODE_SCHEME_DEBUG_AS_ROOT \ XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING - \ XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE \ XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER \ XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS \ XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE \ XCODE_SCHEME_ENABLE_GPU_API_VALIDATION + \ XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE \ XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION \ XCODE_SCHEME_ENVIRONMENT \ XCODE_SCHEME_EXECUTABLE \ XCODE_SCHEME_GUARD_MALLOC + \ XCODE_SCHEME_LAUNCH_CONFIGURATION \ XCODE_SCHEME_LAUNCH_MODE \ XCODE_SCHEME_LLDB_INIT_FILE \ XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP \ XCODE_SCHEME_MALLOC_GUARD_EDGES \ XCODE_SCHEME_MALLOC_SCRIBBLE \ XCODE_SCHEME_MALLOC_STACK + \ XCODE_SCHEME_TEST_CONFIGURATION \ XCODE_SCHEME_THREAD_SANITIZER \ XCODE_SCHEME_THREAD_SANITIZER_STOP \ XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER \ XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP - \ XCODE_SCHEME_ENABLE_GPU_API_VALIDATION - \ XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION - \ XCODE_SCHEME_LAUNCH_CONFIGURATION - \ XCODE_SCHEME_TEST_CONFIGURATION \ XCODE_SCHEME_WORKING_DIRECTORY \ XCODE_SCHEME_ZOMBIE_OBJECTS \ XCODE_XCCONFIG \ XCTEST syn keyword cmakeVariable contained + \ AIX \ ANDROID \ APPLE \ BORLAND \ BSD \ BUILD_SHARED_LIBS + \ BUILD_TESTING \ CACHE \ CMAKE_ABSOLUTE_DESTINATION_FILES \ CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY \ CMAKE_ADSP_ROOT \ CMAKE_AIX_EXPORT_ALL_SYMBOLS + \ CMAKE_AIX_SHARED_LIBRARY_ARCHIVE \ CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS \ CMAKE_ANDROID_API \ CMAKE_ANDROID_API_MIN @@ -556,9 +601,12 @@ \ CMAKE_ASM_ANDROID_TOOLCHAIN_MACHINE \ CMAKE_ASM_ANDROID_TOOLCHAIN_PREFIX \ CMAKE_ASM_ANDROID_TOOLCHAIN_SUFFIX + \ CMAKE_ASM_ARCHIVER_WRAPPER_FLAG + \ CMAKE_ASM_ARCHIVER_WRAPPER_FLAG_SEP \ CMAKE_ASM_ARCHIVE_APPEND \ CMAKE_ASM_ARCHIVE_CREATE \ CMAKE_ASM_ARCHIVE_FINISH + \ CMAKE_ASM_ATTRIBUTES \ CMAKE_ASM_BYTE_ORDER \ CMAKE_ASM_CLANG_TIDY \ CMAKE_ASM_CLANG_TIDY_EXPORT_FIXES_DIR @@ -570,6 +618,10 @@ \ CMAKE_ASM_COMPILER_FRONTEND_VARIANT \ CMAKE_ASM_COMPILER_ID \ CMAKE_ASM_COMPILER_LAUNCHER + \ CMAKE_ASM_COMPILER_LINKER + \ CMAKE_ASM_COMPILER_LINKER_FRONTEND_VARIANT + \ CMAKE_ASM_COMPILER_LINKER_ID + \ CMAKE_ASM_COMPILER_LINKER_VERSION \ CMAKE_ASM_COMPILER_LOADED \ CMAKE_ASM_COMPILER_PREDEFINES_COMMAND \ CMAKE_ASM_COMPILER_RANLIB @@ -580,8 +632,10 @@ \ CMAKE_ASM_CPPCHECK \ CMAKE_ASM_CPPLINT \ CMAKE_ASM_CREATE_SHARED_LIBRARY + \ CMAKE_ASM_CREATE_SHARED_LIBRARY_ARCHIVE \ CMAKE_ASM_CREATE_SHARED_MODULE \ CMAKE_ASM_CREATE_STATIC_LIBRARY + \ CMAKE_ASM_DEVICE_LINK_MODE \ CMAKE_ASM_EXTENSIONS \ CMAKE_ASM_EXTENSIONS_DEFAULT \ CMAKE_ASM_FLAGS @@ -594,6 +648,10 @@ \ CMAKE_ASM_FLAGS_RELEASE_INIT \ CMAKE_ASM_FLAGS_RELWITHDEBINFO \ CMAKE_ASM_FLAGS_RELWITHDEBINFO_INIT + \ CMAKE_ASM_HOST_COMPILER + \ CMAKE_ASM_HOST_COMPILER_ID + \ CMAKE_ASM_HOST_COMPILER_VERSION + \ CMAKE_ASM_ICSTAT \ CMAKE_ASM_IGNORE_EXTENSIONS \ CMAKE_ASM_IMPLICIT_INCLUDE_DIRECTORIES \ CMAKE_ASM_IMPLICIT_LINK_DIRECTORIES @@ -607,18 +665,23 @@ \ CMAKE_ASM_LINKER_PREFERENCE_PROPAGATES \ CMAKE_ASM_LINKER_WRAPPER_FLAG \ CMAKE_ASM_LINKER_WRAPPER_FLAG_SEP + \ CMAKE_ASM_LINK_DEF_FILE_FLAG \ CMAKE_ASM_LINK_EXECUTABLE \ CMAKE_ASM_LINK_LIBRARY_FILE_FLAG \ CMAKE_ASM_LINK_LIBRARY_FLAG \ CMAKE_ASM_LINK_LIBRARY_SUFFIX + \ CMAKE_ASM_LINK_MODE \ CMAKE_ASM_LINK_WHAT_YOU_USE_FLAG \ CMAKE_ASM_MASM \ CMAKE_ASM_MASM_ANDROID_TOOLCHAIN_MACHINE \ CMAKE_ASM_MASM_ANDROID_TOOLCHAIN_PREFIX \ CMAKE_ASM_MASM_ANDROID_TOOLCHAIN_SUFFIX + \ CMAKE_ASM_MASM_ARCHIVER_WRAPPER_FLAG + \ CMAKE_ASM_MASM_ARCHIVER_WRAPPER_FLAG_SEP \ CMAKE_ASM_MASM_ARCHIVE_APPEND \ CMAKE_ASM_MASM_ARCHIVE_CREATE \ CMAKE_ASM_MASM_ARCHIVE_FINISH + \ CMAKE_ASM_MASM_ATTRIBUTES \ CMAKE_ASM_MASM_BYTE_ORDER \ CMAKE_ASM_MASM_CLANG_TIDY \ CMAKE_ASM_MASM_CLANG_TIDY_EXPORT_FIXES_DIR @@ -630,6 +693,10 @@ \ CMAKE_ASM_MASM_COMPILER_FRONTEND_VARIANT \ CMAKE_ASM_MASM_COMPILER_ID \ CMAKE_ASM_MASM_COMPILER_LAUNCHER + \ CMAKE_ASM_MASM_COMPILER_LINKER + \ CMAKE_ASM_MASM_COMPILER_LINKER_FRONTEND_VARIANT + \ CMAKE_ASM_MASM_COMPILER_LINKER_ID + \ CMAKE_ASM_MASM_COMPILER_LINKER_VERSION \ CMAKE_ASM_MASM_COMPILER_LOADED \ CMAKE_ASM_MASM_COMPILER_PREDEFINES_COMMAND \ CMAKE_ASM_MASM_COMPILER_RANLIB @@ -640,8 +707,10 @@ \ CMAKE_ASM_MASM_CPPCHECK \ CMAKE_ASM_MASM_CPPLINT \ CMAKE_ASM_MASM_CREATE_SHARED_LIBRARY + \ CMAKE_ASM_MASM_CREATE_SHARED_LIBRARY_ARCHIVE \ CMAKE_ASM_MASM_CREATE_SHARED_MODULE \ CMAKE_ASM_MASM_CREATE_STATIC_LIBRARY + \ CMAKE_ASM_MASM_DEVICE_LINK_MODE \ CMAKE_ASM_MASM_EXTENSIONS \ CMAKE_ASM_MASM_EXTENSIONS_DEFAULT \ CMAKE_ASM_MASM_FLAGS @@ -654,6 +723,10 @@ \ CMAKE_ASM_MASM_FLAGS_RELEASE_INIT \ CMAKE_ASM_MASM_FLAGS_RELWITHDEBINFO \ CMAKE_ASM_MASM_FLAGS_RELWITHDEBINFO_INIT + \ CMAKE_ASM_MASM_HOST_COMPILER + \ CMAKE_ASM_MASM_HOST_COMPILER_ID + \ CMAKE_ASM_MASM_HOST_COMPILER_VERSION + \ CMAKE_ASM_MASM_ICSTAT \ CMAKE_ASM_MASM_IGNORE_EXTENSIONS \ CMAKE_ASM_MASM_IMPLICIT_INCLUDE_DIRECTORIES \ CMAKE_ASM_MASM_IMPLICIT_LINK_DIRECTORIES @@ -667,10 +740,12 @@ \ CMAKE_ASM_MASM_LINKER_PREFERENCE_PROPAGATES \ CMAKE_ASM_MASM_LINKER_WRAPPER_FLAG \ CMAKE_ASM_MASM_LINKER_WRAPPER_FLAG_SEP + \ CMAKE_ASM_MASM_LINK_DEF_FILE_FLAG \ CMAKE_ASM_MASM_LINK_EXECUTABLE \ CMAKE_ASM_MASM_LINK_LIBRARY_FILE_FLAG \ CMAKE_ASM_MASM_LINK_LIBRARY_FLAG \ CMAKE_ASM_MASM_LINK_LIBRARY_SUFFIX + \ CMAKE_ASM_MASM_LINK_MODE \ CMAKE_ASM_MASM_LINK_WHAT_YOU_USE_FLAG \ CMAKE_ASM_MASM_OUTPUT_EXTENSION \ CMAKE_ASM_MASM_PLATFORM_ID @@ -681,17 +756,23 @@ \ CMAKE_ASM_MASM_STANDARD \ CMAKE_ASM_MASM_STANDARD_DEFAULT \ CMAKE_ASM_MASM_STANDARD_INCLUDE_DIRECTORIES + \ CMAKE_ASM_MASM_STANDARD_LATEST \ CMAKE_ASM_MASM_STANDARD_LIBRARIES + \ CMAKE_ASM_MASM_STANDARD_LINK_DIRECTORIES \ CMAKE_ASM_MASM_STANDARD_REQUIRED \ CMAKE_ASM_MASM_SUPPORTED + \ CMAKE_ASM_MASM_USING_LINKER_MODE \ CMAKE_ASM_MASM_VISIBILITY_PRESET \ CMAKE_ASM_NASM \ CMAKE_ASM_NASM_ANDROID_TOOLCHAIN_MACHINE \ CMAKE_ASM_NASM_ANDROID_TOOLCHAIN_PREFIX \ CMAKE_ASM_NASM_ANDROID_TOOLCHAIN_SUFFIX + \ CMAKE_ASM_NASM_ARCHIVER_WRAPPER_FLAG + \ CMAKE_ASM_NASM_ARCHIVER_WRAPPER_FLAG_SEP \ CMAKE_ASM_NASM_ARCHIVE_APPEND \ CMAKE_ASM_NASM_ARCHIVE_CREATE \ CMAKE_ASM_NASM_ARCHIVE_FINISH + \ CMAKE_ASM_NASM_ATTRIBUTES \ CMAKE_ASM_NASM_BYTE_ORDER \ CMAKE_ASM_NASM_CLANG_TIDY \ CMAKE_ASM_NASM_CLANG_TIDY_EXPORT_FIXES_DIR @@ -703,6 +784,10 @@ \ CMAKE_ASM_NASM_COMPILER_FRONTEND_VARIANT \ CMAKE_ASM_NASM_COMPILER_ID \ CMAKE_ASM_NASM_COMPILER_LAUNCHER + \ CMAKE_ASM_NASM_COMPILER_LINKER + \ CMAKE_ASM_NASM_COMPILER_LINKER_FRONTEND_VARIANT + \ CMAKE_ASM_NASM_COMPILER_LINKER_ID + \ CMAKE_ASM_NASM_COMPILER_LINKER_VERSION \ CMAKE_ASM_NASM_COMPILER_LOADED \ CMAKE_ASM_NASM_COMPILER_PREDEFINES_COMMAND \ CMAKE_ASM_NASM_COMPILER_RANLIB @@ -713,8 +798,10 @@ \ CMAKE_ASM_NASM_CPPCHECK \ CMAKE_ASM_NASM_CPPLINT \ CMAKE_ASM_NASM_CREATE_SHARED_LIBRARY + \ CMAKE_ASM_NASM_CREATE_SHARED_LIBRARY_ARCHIVE \ CMAKE_ASM_NASM_CREATE_SHARED_MODULE \ CMAKE_ASM_NASM_CREATE_STATIC_LIBRARY + \ CMAKE_ASM_NASM_DEVICE_LINK_MODE \ CMAKE_ASM_NASM_EXTENSIONS \ CMAKE_ASM_NASM_EXTENSIONS_DEFAULT \ CMAKE_ASM_NASM_FLAGS @@ -727,6 +814,10 @@ \ CMAKE_ASM_NASM_FLAGS_RELEASE_INIT \ CMAKE_ASM_NASM_FLAGS_RELWITHDEBINFO \ CMAKE_ASM_NASM_FLAGS_RELWITHDEBINFO_INIT + \ CMAKE_ASM_NASM_HOST_COMPILER + \ CMAKE_ASM_NASM_HOST_COMPILER_ID + \ CMAKE_ASM_NASM_HOST_COMPILER_VERSION + \ CMAKE_ASM_NASM_ICSTAT \ CMAKE_ASM_NASM_IGNORE_EXTENSIONS \ CMAKE_ASM_NASM_IMPLICIT_INCLUDE_DIRECTORIES \ CMAKE_ASM_NASM_IMPLICIT_LINK_DIRECTORIES @@ -740,10 +831,12 @@ \ CMAKE_ASM_NASM_LINKER_PREFERENCE_PROPAGATES \ CMAKE_ASM_NASM_LINKER_WRAPPER_FLAG \ CMAKE_ASM_NASM_LINKER_WRAPPER_FLAG_SEP + \ CMAKE_ASM_NASM_LINK_DEF_FILE_FLAG \ CMAKE_ASM_NASM_LINK_EXECUTABLE \ CMAKE_ASM_NASM_LINK_LIBRARY_FILE_FLAG \ CMAKE_ASM_NASM_LINK_LIBRARY_FLAG \ CMAKE_ASM_NASM_LINK_LIBRARY_SUFFIX + \ CMAKE_ASM_NASM_LINK_MODE \ CMAKE_ASM_NASM_LINK_WHAT_YOU_USE_FLAG \ CMAKE_ASM_NASM_OUTPUT_EXTENSION \ CMAKE_ASM_NASM_PLATFORM_ID @@ -754,9 +847,12 @@ \ CMAKE_ASM_NASM_STANDARD \ CMAKE_ASM_NASM_STANDARD_DEFAULT \ CMAKE_ASM_NASM_STANDARD_INCLUDE_DIRECTORIES + \ CMAKE_ASM_NASM_STANDARD_LATEST \ CMAKE_ASM_NASM_STANDARD_LIBRARIES + \ CMAKE_ASM_NASM_STANDARD_LINK_DIRECTORIES \ CMAKE_ASM_NASM_STANDARD_REQUIRED \ CMAKE_ASM_NASM_SUPPORTED + \ CMAKE_ASM_NASM_USING_LINKER_MODE \ CMAKE_ASM_NASM_VISIBILITY_PRESET \ CMAKE_ASM_OUTPUT_EXTENSION \ CMAKE_ASM_PLATFORM_ID @@ -767,9 +863,12 @@ \ CMAKE_ASM_STANDARD \ CMAKE_ASM_STANDARD_DEFAULT \ CMAKE_ASM_STANDARD_INCLUDE_DIRECTORIES + \ CMAKE_ASM_STANDARD_LATEST \ CMAKE_ASM_STANDARD_LIBRARIES + \ CMAKE_ASM_STANDARD_LINK_DIRECTORIES \ CMAKE_ASM_STANDARD_REQUIRED \ CMAKE_ASM_SUPPORTED + \ CMAKE_ASM_USING_LINKER_MODE \ CMAKE_ASM_VISIBILITY_PRESET \ CMAKE_AUTOGEN_BETTER_GRAPH_MULTI_CONFIG \ CMAKE_AUTOGEN_COMMAND_LINE_LENGTH_MAX @@ -781,20 +880,18 @@ \ CMAKE_AUTOMOC_COMPILER_PREDEFINES \ CMAKE_AUTOMOC_DEPEND_FILTERS \ CMAKE_AUTOMOC_EXECUTABLE + \ CMAKE_AUTOMOC_INCLUDE_DIRECTORIES \ CMAKE_AUTOMOC_MACRO_NAMES \ CMAKE_AUTOMOC_MOC_OPTIONS \ CMAKE_AUTOMOC_PATH_PREFIX \ CMAKE_AUTOMOC_RELAXED_MODE - \ CMAKE_AUTOMOC_EXECUTABLE \ CMAKE_AUTORCC \ CMAKE_AUTORCC_EXECUTABLE \ CMAKE_AUTORCC_OPTIONS - \ CMAKE_AUTORCC_EXECUTABLE \ CMAKE_AUTOUIC \ CMAKE_AUTOUIC_EXECUTABLE \ CMAKE_AUTOUIC_OPTIONS \ CMAKE_AUTOUIC_SEARCH_PATHS - \ CMAKE_AUTOUIC_EXECUTABLE \ CMAKE_BACKWARDS_COMPATIBILITY \ CMAKE_BINARY_DIR \ CMAKE_BUILD_RPATH @@ -832,9 +929,12 @@ \ CMAKE_CSharp_ANDROID_TOOLCHAIN_MACHINE \ CMAKE_CSharp_ANDROID_TOOLCHAIN_PREFIX \ CMAKE_CSharp_ANDROID_TOOLCHAIN_SUFFIX + \ CMAKE_CSharp_ARCHIVER_WRAPPER_FLAG + \ CMAKE_CSharp_ARCHIVER_WRAPPER_FLAG_SEP \ CMAKE_CSharp_ARCHIVE_APPEND \ CMAKE_CSharp_ARCHIVE_CREATE \ CMAKE_CSharp_ARCHIVE_FINISH + \ CMAKE_CSharp_ATTRIBUTES \ CMAKE_CSharp_BYTE_ORDER \ CMAKE_CSharp_CLANG_TIDY \ CMAKE_CSharp_CLANG_TIDY_EXPORT_FIXES_DIR @@ -846,6 +946,10 @@ \ CMAKE_CSharp_COMPILER_FRONTEND_VARIANT \ CMAKE_CSharp_COMPILER_ID \ CMAKE_CSharp_COMPILER_LAUNCHER + \ CMAKE_CSharp_COMPILER_LINKER + \ CMAKE_CSharp_COMPILER_LINKER_FRONTEND_VARIANT + \ CMAKE_CSharp_COMPILER_LINKER_ID + \ CMAKE_CSharp_COMPILER_LINKER_VERSION \ CMAKE_CSharp_COMPILER_LOADED \ CMAKE_CSharp_COMPILER_PREDEFINES_COMMAND \ CMAKE_CSharp_COMPILER_RANLIB @@ -856,8 +960,10 @@ \ CMAKE_CSharp_CPPCHECK \ CMAKE_CSharp_CPPLINT \ CMAKE_CSharp_CREATE_SHARED_LIBRARY + \ CMAKE_CSharp_CREATE_SHARED_LIBRARY_ARCHIVE \ CMAKE_CSharp_CREATE_SHARED_MODULE \ CMAKE_CSharp_CREATE_STATIC_LIBRARY + \ CMAKE_CSharp_DEVICE_LINK_MODE \ CMAKE_CSharp_EXTENSIONS \ CMAKE_CSharp_EXTENSIONS_DEFAULT \ CMAKE_CSharp_FLAGS @@ -870,6 +976,10 @@ \ CMAKE_CSharp_FLAGS_RELEASE_INIT \ CMAKE_CSharp_FLAGS_RELWITHDEBINFO \ CMAKE_CSharp_FLAGS_RELWITHDEBINFO_INIT + \ CMAKE_CSharp_HOST_COMPILER + \ CMAKE_CSharp_HOST_COMPILER_ID + \ CMAKE_CSharp_HOST_COMPILER_VERSION + \ CMAKE_CSharp_ICSTAT \ CMAKE_CSharp_IGNORE_EXTENSIONS \ CMAKE_CSharp_IMPLICIT_INCLUDE_DIRECTORIES \ CMAKE_CSharp_IMPLICIT_LINK_DIRECTORIES @@ -883,10 +993,12 @@ \ CMAKE_CSharp_LINKER_PREFERENCE_PROPAGATES \ CMAKE_CSharp_LINKER_WRAPPER_FLAG \ CMAKE_CSharp_LINKER_WRAPPER_FLAG_SEP + \ CMAKE_CSharp_LINK_DEF_FILE_FLAG \ CMAKE_CSharp_LINK_EXECUTABLE \ CMAKE_CSharp_LINK_LIBRARY_FILE_FLAG \ CMAKE_CSharp_LINK_LIBRARY_FLAG \ CMAKE_CSharp_LINK_LIBRARY_SUFFIX + \ CMAKE_CSharp_LINK_MODE \ CMAKE_CSharp_LINK_WHAT_YOU_USE_FLAG \ CMAKE_CSharp_OUTPUT_EXTENSION \ CMAKE_CSharp_PLATFORM_ID @@ -897,9 +1009,12 @@ \ CMAKE_CSharp_STANDARD \ CMAKE_CSharp_STANDARD_DEFAULT \ CMAKE_CSharp_STANDARD_INCLUDE_DIRECTORIES + \ CMAKE_CSharp_STANDARD_LATEST \ CMAKE_CSharp_STANDARD_LIBRARIES + \ CMAKE_CSharp_STANDARD_LINK_DIRECTORIES \ CMAKE_CSharp_STANDARD_REQUIRED \ CMAKE_CSharp_SUPPORTED + \ CMAKE_CSharp_USING_LINKER_MODE \ CMAKE_CSharp_VISIBILITY_PRESET \ CMAKE_CTEST_ARGUMENTS \ CMAKE_CTEST_COMMAND @@ -908,9 +1023,12 @@ \ CMAKE_CUDA_ANDROID_TOOLCHAIN_PREFIX \ CMAKE_CUDA_ANDROID_TOOLCHAIN_SUFFIX \ CMAKE_CUDA_ARCHITECTURES + \ CMAKE_CUDA_ARCHIVER_WRAPPER_FLAG + \ CMAKE_CUDA_ARCHIVER_WRAPPER_FLAG_SEP \ CMAKE_CUDA_ARCHIVE_APPEND \ CMAKE_CUDA_ARCHIVE_CREATE \ CMAKE_CUDA_ARCHIVE_FINISH + \ CMAKE_CUDA_ATTRIBUTES \ CMAKE_CUDA_BYTE_ORDER \ CMAKE_CUDA_CLANG_TIDY \ CMAKE_CUDA_CLANG_TIDY_EXPORT_FIXES_DIR @@ -922,6 +1040,10 @@ \ CMAKE_CUDA_COMPILER_FRONTEND_VARIANT \ CMAKE_CUDA_COMPILER_ID \ CMAKE_CUDA_COMPILER_LAUNCHER + \ CMAKE_CUDA_COMPILER_LINKER + \ CMAKE_CUDA_COMPILER_LINKER_FRONTEND_VARIANT + \ CMAKE_CUDA_COMPILER_LINKER_ID + \ CMAKE_CUDA_COMPILER_LINKER_VERSION \ CMAKE_CUDA_COMPILER_LOADED \ CMAKE_CUDA_COMPILER_PREDEFINES_COMMAND \ CMAKE_CUDA_COMPILER_RANLIB @@ -933,8 +1055,10 @@ \ CMAKE_CUDA_CPPCHECK \ CMAKE_CUDA_CPPLINT \ CMAKE_CUDA_CREATE_SHARED_LIBRARY + \ CMAKE_CUDA_CREATE_SHARED_LIBRARY_ARCHIVE \ CMAKE_CUDA_CREATE_SHARED_MODULE \ CMAKE_CUDA_CREATE_STATIC_LIBRARY + \ CMAKE_CUDA_DEVICE_LINK_MODE \ CMAKE_CUDA_EXTENSIONS \ CMAKE_CUDA_EXTENSIONS_DEFAULT \ CMAKE_CUDA_FLAGS @@ -948,6 +1072,9 @@ \ CMAKE_CUDA_FLAGS_RELWITHDEBINFO \ CMAKE_CUDA_FLAGS_RELWITHDEBINFO_INIT \ CMAKE_CUDA_HOST_COMPILER + \ CMAKE_CUDA_HOST_COMPILER_ID + \ CMAKE_CUDA_HOST_COMPILER_VERSION + \ CMAKE_CUDA_ICSTAT \ CMAKE_CUDA_IGNORE_EXTENSIONS \ CMAKE_CUDA_IMPLICIT_INCLUDE_DIRECTORIES \ CMAKE_CUDA_IMPLICIT_LINK_DIRECTORIES @@ -961,10 +1088,12 @@ \ CMAKE_CUDA_LINKER_PREFERENCE_PROPAGATES \ CMAKE_CUDA_LINKER_WRAPPER_FLAG \ CMAKE_CUDA_LINKER_WRAPPER_FLAG_SEP + \ CMAKE_CUDA_LINK_DEF_FILE_FLAG \ CMAKE_CUDA_LINK_EXECUTABLE \ CMAKE_CUDA_LINK_LIBRARY_FILE_FLAG \ CMAKE_CUDA_LINK_LIBRARY_FLAG \ CMAKE_CUDA_LINK_LIBRARY_SUFFIX + \ CMAKE_CUDA_LINK_MODE \ CMAKE_CUDA_LINK_WHAT_YOU_USE_FLAG \ CMAKE_CUDA_OUTPUT_EXTENSION \ CMAKE_CUDA_PLATFORM_ID @@ -978,10 +1107,13 @@ \ CMAKE_CUDA_STANDARD \ CMAKE_CUDA_STANDARD_DEFAULT \ CMAKE_CUDA_STANDARD_INCLUDE_DIRECTORIES + \ CMAKE_CUDA_STANDARD_LATEST \ CMAKE_CUDA_STANDARD_LIBRARIES + \ CMAKE_CUDA_STANDARD_LINK_DIRECTORIES \ CMAKE_CUDA_STANDARD_REQUIRED \ CMAKE_CUDA_SUPPORTED \ CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES + \ CMAKE_CUDA_USING_LINKER_MODE \ CMAKE_CUDA_VISIBILITY_PRESET \ CMAKE_CURRENT_BINARY_DIR \ CMAKE_CURRENT_FUNCTION @@ -996,9 +1128,12 @@ \ CMAKE_CXX_ANDROID_TOOLCHAIN_MACHINE \ CMAKE_CXX_ANDROID_TOOLCHAIN_PREFIX \ CMAKE_CXX_ANDROID_TOOLCHAIN_SUFFIX + \ CMAKE_CXX_ARCHIVER_WRAPPER_FLAG + \ CMAKE_CXX_ARCHIVER_WRAPPER_FLAG_SEP \ CMAKE_CXX_ARCHIVE_APPEND \ CMAKE_CXX_ARCHIVE_CREATE \ CMAKE_CXX_ARCHIVE_FINISH + \ CMAKE_CXX_ATTRIBUTES \ CMAKE_CXX_BYTE_ORDER \ CMAKE_CXX_CLANG_TIDY \ CMAKE_CXX_CLANG_TIDY_EXPORT_FIXES_DIR @@ -1009,7 +1144,12 @@ \ CMAKE_CXX_COMPILER_EXTERNAL_TOOLCHAIN \ CMAKE_CXX_COMPILER_FRONTEND_VARIANT \ CMAKE_CXX_COMPILER_ID + \ CMAKE_CXX_COMPILER_IMPORT_STD \ CMAKE_CXX_COMPILER_LAUNCHER + \ CMAKE_CXX_COMPILER_LINKER + \ CMAKE_CXX_COMPILER_LINKER_FRONTEND_VARIANT + \ CMAKE_CXX_COMPILER_LINKER_ID + \ CMAKE_CXX_COMPILER_LINKER_VERSION \ CMAKE_CXX_COMPILER_LOADED \ CMAKE_CXX_COMPILER_PREDEFINES_COMMAND \ CMAKE_CXX_COMPILER_RANLIB @@ -1021,8 +1161,10 @@ \ CMAKE_CXX_CPPCHECK \ CMAKE_CXX_CPPLINT \ CMAKE_CXX_CREATE_SHARED_LIBRARY + \ CMAKE_CXX_CREATE_SHARED_LIBRARY_ARCHIVE \ CMAKE_CXX_CREATE_SHARED_MODULE \ CMAKE_CXX_CREATE_STATIC_LIBRARY + \ CMAKE_CXX_DEVICE_LINK_MODE \ CMAKE_CXX_EXTENSIONS \ CMAKE_CXX_EXTENSIONS_DEFAULT \ CMAKE_CXX_FLAGS @@ -1035,6 +1177,10 @@ \ CMAKE_CXX_FLAGS_RELEASE_INIT \ CMAKE_CXX_FLAGS_RELWITHDEBINFO \ CMAKE_CXX_FLAGS_RELWITHDEBINFO_INIT + \ CMAKE_CXX_HOST_COMPILER + \ CMAKE_CXX_HOST_COMPILER_ID + \ CMAKE_CXX_HOST_COMPILER_VERSION + \ CMAKE_CXX_ICSTAT \ CMAKE_CXX_IGNORE_EXTENSIONS \ CMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES \ CMAKE_CXX_IMPLICIT_LINK_DIRECTORIES @@ -1048,11 +1194,14 @@ \ CMAKE_CXX_LINKER_PREFERENCE_PROPAGATES \ CMAKE_CXX_LINKER_WRAPPER_FLAG \ CMAKE_CXX_LINKER_WRAPPER_FLAG_SEP + \ CMAKE_CXX_LINK_DEF_FILE_FLAG \ CMAKE_CXX_LINK_EXECUTABLE \ CMAKE_CXX_LINK_LIBRARY_FILE_FLAG \ CMAKE_CXX_LINK_LIBRARY_FLAG \ CMAKE_CXX_LINK_LIBRARY_SUFFIX + \ CMAKE_CXX_LINK_MODE \ CMAKE_CXX_LINK_WHAT_YOU_USE_FLAG + \ CMAKE_CXX_MODULE_STD \ CMAKE_CXX_OUTPUT_EXTENSION \ CMAKE_CXX_PLATFORM_ID \ CMAKE_CXX_SCAN_FOR_MODULES @@ -1063,16 +1212,22 @@ \ CMAKE_CXX_STANDARD \ CMAKE_CXX_STANDARD_DEFAULT \ CMAKE_CXX_STANDARD_INCLUDE_DIRECTORIES + \ CMAKE_CXX_STANDARD_LATEST \ CMAKE_CXX_STANDARD_LIBRARIES + \ CMAKE_CXX_STANDARD_LINK_DIRECTORIES \ CMAKE_CXX_STANDARD_REQUIRED \ CMAKE_CXX_SUPPORTED + \ CMAKE_CXX_USING_LINKER_MODE \ CMAKE_CXX_VISIBILITY_PRESET \ CMAKE_C_ANDROID_TOOLCHAIN_MACHINE \ CMAKE_C_ANDROID_TOOLCHAIN_PREFIX \ CMAKE_C_ANDROID_TOOLCHAIN_SUFFIX + \ CMAKE_C_ARCHIVER_WRAPPER_FLAG + \ CMAKE_C_ARCHIVER_WRAPPER_FLAG_SEP \ CMAKE_C_ARCHIVE_APPEND \ CMAKE_C_ARCHIVE_CREATE \ CMAKE_C_ARCHIVE_FINISH + \ CMAKE_C_ATTRIBUTES \ CMAKE_C_BYTE_ORDER \ CMAKE_C_CLANG_TIDY \ CMAKE_C_CLANG_TIDY_EXPORT_FIXES_DIR @@ -1084,6 +1239,10 @@ \ CMAKE_C_COMPILER_FRONTEND_VARIANT \ CMAKE_C_COMPILER_ID \ CMAKE_C_COMPILER_LAUNCHER + \ CMAKE_C_COMPILER_LINKER + \ CMAKE_C_COMPILER_LINKER_FRONTEND_VARIANT + \ CMAKE_C_COMPILER_LINKER_ID + \ CMAKE_C_COMPILER_LINKER_VERSION \ CMAKE_C_COMPILER_LOADED \ CMAKE_C_COMPILER_PREDEFINES_COMMAND \ CMAKE_C_COMPILER_RANLIB @@ -1095,8 +1254,10 @@ \ CMAKE_C_CPPCHECK \ CMAKE_C_CPPLINT \ CMAKE_C_CREATE_SHARED_LIBRARY + \ CMAKE_C_CREATE_SHARED_LIBRARY_ARCHIVE \ CMAKE_C_CREATE_SHARED_MODULE \ CMAKE_C_CREATE_STATIC_LIBRARY + \ CMAKE_C_DEVICE_LINK_MODE \ CMAKE_C_EXTENSIONS \ CMAKE_C_EXTENSIONS_DEFAULT \ CMAKE_C_FLAGS @@ -1109,6 +1270,10 @@ \ CMAKE_C_FLAGS_RELEASE_INIT \ CMAKE_C_FLAGS_RELWITHDEBINFO \ CMAKE_C_FLAGS_RELWITHDEBINFO_INIT + \ CMAKE_C_HOST_COMPILER + \ CMAKE_C_HOST_COMPILER_ID + \ CMAKE_C_HOST_COMPILER_VERSION + \ CMAKE_C_ICSTAT \ CMAKE_C_IGNORE_EXTENSIONS \ CMAKE_C_IMPLICIT_INCLUDE_DIRECTORIES \ CMAKE_C_IMPLICIT_LINK_DIRECTORIES @@ -1122,10 +1287,12 @@ \ CMAKE_C_LINKER_PREFERENCE_PROPAGATES \ CMAKE_C_LINKER_WRAPPER_FLAG \ CMAKE_C_LINKER_WRAPPER_FLAG_SEP + \ CMAKE_C_LINK_DEF_FILE_FLAG \ CMAKE_C_LINK_EXECUTABLE \ CMAKE_C_LINK_LIBRARY_FILE_FLAG \ CMAKE_C_LINK_LIBRARY_FLAG \ CMAKE_C_LINK_LIBRARY_SUFFIX + \ CMAKE_C_LINK_MODE \ CMAKE_C_LINK_WHAT_YOU_USE_FLAG \ CMAKE_C_OUTPUT_EXTENSION \ CMAKE_C_PLATFORM_ID @@ -1136,13 +1303,16 @@ \ CMAKE_C_STANDARD \ CMAKE_C_STANDARD_DEFAULT \ CMAKE_C_STANDARD_INCLUDE_DIRECTORIES + \ CMAKE_C_STANDARD_LATEST \ CMAKE_C_STANDARD_LIBRARIES + \ CMAKE_C_STANDARD_LINK_DIRECTORIES \ CMAKE_C_STANDARD_REQUIRED \ CMAKE_C_SUPPORTED + \ CMAKE_C_USING_LINKER_MODE \ CMAKE_C_VISIBILITY_PRESET + \ CMAKE_DEBUGGER_WORKING_DIRECTORY \ CMAKE_DEBUG_POSTFIX \ CMAKE_DEBUG_TARGET_PROPERTIES - \ CMAKE_DEBUGGER_WORKING_DIRECTORY \ CMAKE_DEFAULT_BUILD_TYPE \ CMAKE_DEFAULT_CONFIGS \ CMAKE_DEPENDS_IN_PROJECT_ONLY @@ -1178,16 +1348,20 @@ \ CMAKE_EXECUTABLE_SUFFIX_RC \ CMAKE_EXECUTABLE_SUFFIX_Swift \ CMAKE_EXECUTE_PROCESS_COMMAND_ECHO + \ CMAKE_EXECUTE_PROCESS_COMMAND_ERROR_IS_FATAL \ CMAKE_EXE_LINKER_FLAGS \ CMAKE_EXE_LINKER_FLAGS_INIT + \ CMAKE_EXPORT_BUILD_DATABASE \ CMAKE_EXPORT_COMPILE_COMMANDS - \ CMAKE_EXPORT_SARIF + \ CMAKE_EXPORT_FIND_PACKAGE_NAME \ CMAKE_EXPORT_NO_PACKAGE_REGISTRY \ CMAKE_EXPORT_PACKAGE_REGISTRY + \ CMAKE_EXPORT_SARIF \ CMAKE_EXTRA_GENERATOR \ CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES \ CMAKE_FIND_APPBUNDLE \ CMAKE_FIND_DEBUG_MODE + \ CMAKE_FIND_DEBUG_MODE_NO_IMPLICIT_CONFIGURE_LOG \ CMAKE_FIND_FRAMEWORK \ CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX \ CMAKE_FIND_LIBRARY_PREFIXES @@ -1203,13 +1377,13 @@ \ CMAKE_FIND_PACKAGE_SORT_ORDER \ CMAKE_FIND_PACKAGE_TARGETS_GLOBAL \ CMAKE_FIND_PACKAGE_WARN_NO_MODULE + \ CMAKE_FIND_REQUIRED \ CMAKE_FIND_ROOT_PATH \ CMAKE_FIND_ROOT_PATH_MODE_INCLUDE \ CMAKE_FIND_ROOT_PATH_MODE_LIBRARY \ CMAKE_FIND_ROOT_PATH_MODE_PACKAGE \ CMAKE_FIND_ROOT_PATH_MODE_PROGRAM \ CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH - \ CMAKE_FIND_USE_INSTALL_PREFIX \ CMAKE_FIND_USE_CMAKE_PATH \ CMAKE_FIND_USE_CMAKE_SYSTEM_PATH \ CMAKE_FIND_USE_INSTALL_PREFIX @@ -1224,9 +1398,12 @@ \ CMAKE_Fortran_ANDROID_TOOLCHAIN_MACHINE \ CMAKE_Fortran_ANDROID_TOOLCHAIN_PREFIX \ CMAKE_Fortran_ANDROID_TOOLCHAIN_SUFFIX + \ CMAKE_Fortran_ARCHIVER_WRAPPER_FLAG + \ CMAKE_Fortran_ARCHIVER_WRAPPER_FLAG_SEP \ CMAKE_Fortran_ARCHIVE_APPEND \ CMAKE_Fortran_ARCHIVE_CREATE \ CMAKE_Fortran_ARCHIVE_FINISH + \ CMAKE_Fortran_ATTRIBUTES \ CMAKE_Fortran_BYTE_ORDER \ CMAKE_Fortran_CLANG_TIDY \ CMAKE_Fortran_CLANG_TIDY_EXPORT_FIXES_DIR @@ -1238,6 +1415,10 @@ \ CMAKE_Fortran_COMPILER_FRONTEND_VARIANT \ CMAKE_Fortran_COMPILER_ID \ CMAKE_Fortran_COMPILER_LAUNCHER + \ CMAKE_Fortran_COMPILER_LINKER + \ CMAKE_Fortran_COMPILER_LINKER_FRONTEND_VARIANT + \ CMAKE_Fortran_COMPILER_LINKER_ID + \ CMAKE_Fortran_COMPILER_LINKER_VERSION \ CMAKE_Fortran_COMPILER_LOADED \ CMAKE_Fortran_COMPILER_PREDEFINES_COMMAND \ CMAKE_Fortran_COMPILER_RANLIB @@ -1248,8 +1429,10 @@ \ CMAKE_Fortran_CPPCHECK \ CMAKE_Fortran_CPPLINT \ CMAKE_Fortran_CREATE_SHARED_LIBRARY + \ CMAKE_Fortran_CREATE_SHARED_LIBRARY_ARCHIVE \ CMAKE_Fortran_CREATE_SHARED_MODULE \ CMAKE_Fortran_CREATE_STATIC_LIBRARY + \ CMAKE_Fortran_DEVICE_LINK_MODE \ CMAKE_Fortran_EXTENSIONS \ CMAKE_Fortran_EXTENSIONS_DEFAULT \ CMAKE_Fortran_FLAGS @@ -1263,6 +1446,10 @@ \ CMAKE_Fortran_FLAGS_RELWITHDEBINFO \ CMAKE_Fortran_FLAGS_RELWITHDEBINFO_INIT \ CMAKE_Fortran_FORMAT + \ CMAKE_Fortran_HOST_COMPILER + \ CMAKE_Fortran_HOST_COMPILER_ID + \ CMAKE_Fortran_HOST_COMPILER_VERSION + \ CMAKE_Fortran_ICSTAT \ CMAKE_Fortran_IGNORE_EXTENSIONS \ CMAKE_Fortran_IMPLICIT_INCLUDE_DIRECTORIES \ CMAKE_Fortran_IMPLICIT_LINK_DIRECTORIES @@ -1276,10 +1463,12 @@ \ CMAKE_Fortran_LINKER_PREFERENCE_PROPAGATES \ CMAKE_Fortran_LINKER_WRAPPER_FLAG \ CMAKE_Fortran_LINKER_WRAPPER_FLAG_SEP + \ CMAKE_Fortran_LINK_DEF_FILE_FLAG \ CMAKE_Fortran_LINK_EXECUTABLE \ CMAKE_Fortran_LINK_LIBRARY_FILE_FLAG \ CMAKE_Fortran_LINK_LIBRARY_FLAG \ CMAKE_Fortran_LINK_LIBRARY_SUFFIX + \ CMAKE_Fortran_LINK_MODE \ CMAKE_Fortran_LINK_WHAT_YOU_USE_FLAG \ CMAKE_Fortran_MODDIR_DEFAULT \ CMAKE_Fortran_MODDIR_FLAG @@ -1295,9 +1484,12 @@ \ CMAKE_Fortran_STANDARD \ CMAKE_Fortran_STANDARD_DEFAULT \ CMAKE_Fortran_STANDARD_INCLUDE_DIRECTORIES + \ CMAKE_Fortran_STANDARD_LATEST \ CMAKE_Fortran_STANDARD_LIBRARIES + \ CMAKE_Fortran_STANDARD_LINK_DIRECTORIES \ CMAKE_Fortran_STANDARD_REQUIRED \ CMAKE_Fortran_SUPPORTED + \ CMAKE_Fortran_USING_LINKER_MODE \ CMAKE_Fortran_VISIBILITY_PRESET \ CMAKE_GENERATOR \ CMAKE_GENERATOR_INSTANCE @@ -1314,9 +1506,12 @@ \ CMAKE_HIP_ANDROID_TOOLCHAIN_PREFIX \ CMAKE_HIP_ANDROID_TOOLCHAIN_SUFFIX \ CMAKE_HIP_ARCHITECTURES + \ CMAKE_HIP_ARCHIVER_WRAPPER_FLAG + \ CMAKE_HIP_ARCHIVER_WRAPPER_FLAG_SEP \ CMAKE_HIP_ARCHIVE_APPEND \ CMAKE_HIP_ARCHIVE_CREATE \ CMAKE_HIP_ARCHIVE_FINISH + \ CMAKE_HIP_ATTRIBUTES \ CMAKE_HIP_BYTE_ORDER \ CMAKE_HIP_CLANG_TIDY \ CMAKE_HIP_CLANG_TIDY_EXPORT_FIXES_DIR @@ -1328,6 +1523,10 @@ \ CMAKE_HIP_COMPILER_FRONTEND_VARIANT \ CMAKE_HIP_COMPILER_ID \ CMAKE_HIP_COMPILER_LAUNCHER + \ CMAKE_HIP_COMPILER_LINKER + \ CMAKE_HIP_COMPILER_LINKER_FRONTEND_VARIANT + \ CMAKE_HIP_COMPILER_LINKER_ID + \ CMAKE_HIP_COMPILER_LINKER_VERSION \ CMAKE_HIP_COMPILER_LOADED \ CMAKE_HIP_COMPILER_PREDEFINES_COMMAND \ CMAKE_HIP_COMPILER_RANLIB @@ -1339,8 +1538,10 @@ \ CMAKE_HIP_CPPCHECK \ CMAKE_HIP_CPPLINT \ CMAKE_HIP_CREATE_SHARED_LIBRARY + \ CMAKE_HIP_CREATE_SHARED_LIBRARY_ARCHIVE \ CMAKE_HIP_CREATE_SHARED_MODULE \ CMAKE_HIP_CREATE_STATIC_LIBRARY + \ CMAKE_HIP_DEVICE_LINK_MODE \ CMAKE_HIP_EXTENSIONS \ CMAKE_HIP_EXTENSIONS_DEFAULT \ CMAKE_HIP_FLAGS @@ -1353,6 +1554,10 @@ \ CMAKE_HIP_FLAGS_RELEASE_INIT \ CMAKE_HIP_FLAGS_RELWITHDEBINFO \ CMAKE_HIP_FLAGS_RELWITHDEBINFO_INIT + \ CMAKE_HIP_HOST_COMPILER + \ CMAKE_HIP_HOST_COMPILER_ID + \ CMAKE_HIP_HOST_COMPILER_VERSION + \ CMAKE_HIP_ICSTAT \ CMAKE_HIP_IGNORE_EXTENSIONS \ CMAKE_HIP_IMPLICIT_INCLUDE_DIRECTORIES \ CMAKE_HIP_IMPLICIT_LINK_DIRECTORIES @@ -1366,12 +1571,15 @@ \ CMAKE_HIP_LINKER_PREFERENCE_PROPAGATES \ CMAKE_HIP_LINKER_WRAPPER_FLAG \ CMAKE_HIP_LINKER_WRAPPER_FLAG_SEP + \ CMAKE_HIP_LINK_DEF_FILE_FLAG \ CMAKE_HIP_LINK_EXECUTABLE \ CMAKE_HIP_LINK_LIBRARY_FILE_FLAG \ CMAKE_HIP_LINK_LIBRARY_FLAG \ CMAKE_HIP_LINK_LIBRARY_SUFFIX + \ CMAKE_HIP_LINK_MODE \ CMAKE_HIP_LINK_WHAT_YOU_USE_FLAG \ CMAKE_HIP_OUTPUT_EXTENSION + \ CMAKE_HIP_PLATFORM \ CMAKE_HIP_PLATFORM_ID \ CMAKE_HIP_SIMULATE_ID \ CMAKE_HIP_SIMULATE_VERSION @@ -1380,13 +1588,18 @@ \ CMAKE_HIP_STANDARD \ CMAKE_HIP_STANDARD_DEFAULT \ CMAKE_HIP_STANDARD_INCLUDE_DIRECTORIES + \ CMAKE_HIP_STANDARD_LATEST \ CMAKE_HIP_STANDARD_LIBRARIES + \ CMAKE_HIP_STANDARD_LINK_DIRECTORIES \ CMAKE_HIP_STANDARD_REQUIRED \ CMAKE_HIP_SUPPORTED + \ CMAKE_HIP_USING_LINKER_MODE \ CMAKE_HIP_VISIBILITY_PRESET \ CMAKE_HOME_DIRECTORY + \ CMAKE_HOST_AIX \ CMAKE_HOST_APPLE \ CMAKE_HOST_BSD + \ CMAKE_HOST_EXECUTABLE_SUFFIX \ CMAKE_HOST_LINUX \ CMAKE_HOST_SOLARIS \ CMAKE_HOST_SYSTEM @@ -1427,9 +1640,12 @@ \ CMAKE_Java_ANDROID_TOOLCHAIN_MACHINE \ CMAKE_Java_ANDROID_TOOLCHAIN_PREFIX \ CMAKE_Java_ANDROID_TOOLCHAIN_SUFFIX + \ CMAKE_Java_ARCHIVER_WRAPPER_FLAG + \ CMAKE_Java_ARCHIVER_WRAPPER_FLAG_SEP \ CMAKE_Java_ARCHIVE_APPEND \ CMAKE_Java_ARCHIVE_CREATE \ CMAKE_Java_ARCHIVE_FINISH + \ CMAKE_Java_ATTRIBUTES \ CMAKE_Java_BYTE_ORDER \ CMAKE_Java_CLANG_TIDY \ CMAKE_Java_CLANG_TIDY_EXPORT_FIXES_DIR @@ -1441,6 +1657,10 @@ \ CMAKE_Java_COMPILER_FRONTEND_VARIANT \ CMAKE_Java_COMPILER_ID \ CMAKE_Java_COMPILER_LAUNCHER + \ CMAKE_Java_COMPILER_LINKER + \ CMAKE_Java_COMPILER_LINKER_FRONTEND_VARIANT + \ CMAKE_Java_COMPILER_LINKER_ID + \ CMAKE_Java_COMPILER_LINKER_VERSION \ CMAKE_Java_COMPILER_LOADED \ CMAKE_Java_COMPILER_PREDEFINES_COMMAND \ CMAKE_Java_COMPILER_RANLIB @@ -1451,8 +1671,10 @@ \ CMAKE_Java_CPPCHECK \ CMAKE_Java_CPPLINT \ CMAKE_Java_CREATE_SHARED_LIBRARY + \ CMAKE_Java_CREATE_SHARED_LIBRARY_ARCHIVE \ CMAKE_Java_CREATE_SHARED_MODULE \ CMAKE_Java_CREATE_STATIC_LIBRARY + \ CMAKE_Java_DEVICE_LINK_MODE \ CMAKE_Java_EXTENSIONS \ CMAKE_Java_EXTENSIONS_DEFAULT \ CMAKE_Java_FLAGS @@ -1465,6 +1687,10 @@ \ CMAKE_Java_FLAGS_RELEASE_INIT \ CMAKE_Java_FLAGS_RELWITHDEBINFO \ CMAKE_Java_FLAGS_RELWITHDEBINFO_INIT + \ CMAKE_Java_HOST_COMPILER + \ CMAKE_Java_HOST_COMPILER_ID + \ CMAKE_Java_HOST_COMPILER_VERSION + \ CMAKE_Java_ICSTAT \ CMAKE_Java_IGNORE_EXTENSIONS \ CMAKE_Java_IMPLICIT_INCLUDE_DIRECTORIES \ CMAKE_Java_IMPLICIT_LINK_DIRECTORIES @@ -1478,10 +1704,12 @@ \ CMAKE_Java_LINKER_PREFERENCE_PROPAGATES \ CMAKE_Java_LINKER_WRAPPER_FLAG \ CMAKE_Java_LINKER_WRAPPER_FLAG_SEP + \ CMAKE_Java_LINK_DEF_FILE_FLAG \ CMAKE_Java_LINK_EXECUTABLE \ CMAKE_Java_LINK_LIBRARY_FILE_FLAG \ CMAKE_Java_LINK_LIBRARY_FLAG \ CMAKE_Java_LINK_LIBRARY_SUFFIX + \ CMAKE_Java_LINK_MODE \ CMAKE_Java_LINK_WHAT_YOU_USE_FLAG \ CMAKE_Java_OUTPUT_EXTENSION \ CMAKE_Java_PLATFORM_ID @@ -1492,9 +1720,12 @@ \ CMAKE_Java_STANDARD \ CMAKE_Java_STANDARD_DEFAULT \ CMAKE_Java_STANDARD_INCLUDE_DIRECTORIES + \ CMAKE_Java_STANDARD_LATEST \ CMAKE_Java_STANDARD_LIBRARIES + \ CMAKE_Java_STANDARD_LINK_DIRECTORIES \ CMAKE_Java_STANDARD_REQUIRED \ CMAKE_Java_SUPPORTED + \ CMAKE_Java_USING_LINKER_MODE \ CMAKE_Java_VISIBILITY_PRESET \ CMAKE_KATE_FILES_MODE \ CMAKE_KATE_MAKE_ARGUMENTS @@ -1503,19 +1734,23 @@ \ CMAKE_LIBRARY_OUTPUT_DIRECTORY \ CMAKE_LIBRARY_PATH \ CMAKE_LIBRARY_PATH_FLAG + \ CMAKE_LINKER_TYPE \ CMAKE_LINK_DEF_FILE_FLAG \ CMAKE_LINK_DEPENDS_NO_SHARED \ CMAKE_LINK_DEPENDS_USE_LINKER \ CMAKE_LINK_DIRECTORIES_BEFORE \ CMAKE_LINK_INTERFACE_LIBRARIES \ CMAKE_LINK_LIBRARIES_ONLY_TARGETS + \ CMAKE_LINK_LIBRARIES_STRATEGY \ CMAKE_LINK_LIBRARY_FILE_FLAG \ CMAKE_LINK_LIBRARY_FLAG \ CMAKE_LINK_LIBRARY_SUFFIX \ CMAKE_LINK_SEARCH_END_STATIC \ CMAKE_LINK_SEARCH_START_STATIC + \ CMAKE_LINK_WARNING_AS_ERROR \ CMAKE_LINK_WHAT_YOU_USE \ CMAKE_LINK_WHAT_YOU_USE_CHECK + \ CMAKE_LIST_FILE_NAME \ CMAKE_MACOSX_BUNDLE \ CMAKE_MACOSX_RPATH \ CMAKE_MAJOR_VERSION @@ -1552,6 +1787,7 @@ \ CMAKE_OBJC_LINKER_LAUNCHER \ CMAKE_OBJC_STANDARD \ CMAKE_OBJC_STANDARD_REQUIRED + \ CMAKE_OBJDUMP \ CMAKE_OBJECT_PATH_MAX \ CMAKE_OPTIMIZE_DEPENDENCIES \ CMAKE_OSX_ARCHITECTURES @@ -1562,15 +1798,23 @@ \ CMAKE_PCH_INSTANTIATE_TEMPLATES \ CMAKE_PCH_WARN_INVALID \ CMAKE_PDB_OUTPUT_DIRECTORY + \ CMAKE_PKG_CONFIG_DISABLE_UNINSTALLED + \ CMAKE_PKG_CONFIG_PC_LIB_DIRS + \ CMAKE_PKG_CONFIG_PC_PATH + \ CMAKE_PKG_CONFIG_SYSROOT_DIR + \ CMAKE_PKG_CONFIG_TOP_BUILD_DIR \ CMAKE_PLATFORM_NO_VERSIONED_SONAME + \ CMAKE_POLICY_VERSION_MINIMUM \ CMAKE_POSITION_INDEPENDENT_CODE \ CMAKE_PREFIX_PATH \ CMAKE_PROGRAM_PATH + \ CMAKE_PROJECT_COMPAT_VERSION \ CMAKE_PROJECT_DESCRIPTION \ CMAKE_PROJECT_HOMEPAGE_URL \ CMAKE_PROJECT_INCLUDE \ CMAKE_PROJECT_INCLUDE_BEFORE \ CMAKE_PROJECT_NAME + \ CMAKE_PROJECT_SPDX_LICENSE \ CMAKE_PROJECT_TOP_LEVEL_INCLUDES \ CMAKE_PROJECT_VERSION \ CMAKE_PROJECT_VERSION_MAJOR @@ -1582,9 +1826,12 @@ \ CMAKE_RC_ANDROID_TOOLCHAIN_MACHINE \ CMAKE_RC_ANDROID_TOOLCHAIN_PREFIX \ CMAKE_RC_ANDROID_TOOLCHAIN_SUFFIX + \ CMAKE_RC_ARCHIVER_WRAPPER_FLAG + \ CMAKE_RC_ARCHIVER_WRAPPER_FLAG_SEP \ CMAKE_RC_ARCHIVE_APPEND \ CMAKE_RC_ARCHIVE_CREATE \ CMAKE_RC_ARCHIVE_FINISH + \ CMAKE_RC_ATTRIBUTES \ CMAKE_RC_BYTE_ORDER \ CMAKE_RC_CLANG_TIDY \ CMAKE_RC_CLANG_TIDY_EXPORT_FIXES_DIR @@ -1596,6 +1843,10 @@ \ CMAKE_RC_COMPILER_FRONTEND_VARIANT \ CMAKE_RC_COMPILER_ID \ CMAKE_RC_COMPILER_LAUNCHER + \ CMAKE_RC_COMPILER_LINKER + \ CMAKE_RC_COMPILER_LINKER_FRONTEND_VARIANT + \ CMAKE_RC_COMPILER_LINKER_ID + \ CMAKE_RC_COMPILER_LINKER_VERSION \ CMAKE_RC_COMPILER_LOADED \ CMAKE_RC_COMPILER_PREDEFINES_COMMAND \ CMAKE_RC_COMPILER_RANLIB @@ -1606,8 +1857,10 @@ \ CMAKE_RC_CPPCHECK \ CMAKE_RC_CPPLINT \ CMAKE_RC_CREATE_SHARED_LIBRARY + \ CMAKE_RC_CREATE_SHARED_LIBRARY_ARCHIVE \ CMAKE_RC_CREATE_SHARED_MODULE \ CMAKE_RC_CREATE_STATIC_LIBRARY + \ CMAKE_RC_DEVICE_LINK_MODE \ CMAKE_RC_EXTENSIONS \ CMAKE_RC_EXTENSIONS_DEFAULT \ CMAKE_RC_FLAGS @@ -1620,6 +1873,10 @@ \ CMAKE_RC_FLAGS_RELEASE_INIT \ CMAKE_RC_FLAGS_RELWITHDEBINFO \ CMAKE_RC_FLAGS_RELWITHDEBINFO_INIT + \ CMAKE_RC_HOST_COMPILER + \ CMAKE_RC_HOST_COMPILER_ID + \ CMAKE_RC_HOST_COMPILER_VERSION + \ CMAKE_RC_ICSTAT \ CMAKE_RC_IGNORE_EXTENSIONS \ CMAKE_RC_IMPLICIT_INCLUDE_DIRECTORIES \ CMAKE_RC_IMPLICIT_LINK_DIRECTORIES @@ -1633,10 +1890,12 @@ \ CMAKE_RC_LINKER_PREFERENCE_PROPAGATES \ CMAKE_RC_LINKER_WRAPPER_FLAG \ CMAKE_RC_LINKER_WRAPPER_FLAG_SEP + \ CMAKE_RC_LINK_DEF_FILE_FLAG \ CMAKE_RC_LINK_EXECUTABLE \ CMAKE_RC_LINK_LIBRARY_FILE_FLAG \ CMAKE_RC_LINK_LIBRARY_FLAG \ CMAKE_RC_LINK_LIBRARY_SUFFIX + \ CMAKE_RC_LINK_MODE \ CMAKE_RC_LINK_WHAT_YOU_USE_FLAG \ CMAKE_RC_OUTPUT_EXTENSION \ CMAKE_RC_PLATFORM_ID @@ -1647,14 +1906,18 @@ \ CMAKE_RC_STANDARD \ CMAKE_RC_STANDARD_DEFAULT \ CMAKE_RC_STANDARD_INCLUDE_DIRECTORIES + \ CMAKE_RC_STANDARD_LATEST \ CMAKE_RC_STANDARD_LIBRARIES + \ CMAKE_RC_STANDARD_LINK_DIRECTORIES \ CMAKE_RC_STANDARD_REQUIRED \ CMAKE_RC_SUPPORTED + \ CMAKE_RC_USING_LINKER_MODE \ CMAKE_RC_VISIBILITY_PRESET \ CMAKE_ROOT \ CMAKE_RULE_MESSAGES \ CMAKE_RUNTIME_OUTPUT_DIRECTORY \ CMAKE_SCRIPT_MODE_FILE + \ CMAKE_SHARED_LIBRARY_ARCHIVE_SUFFIX \ CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS \ CMAKE_SHARED_LIBRARY_PREFIX \ CMAKE_SHARED_LIBRARY_SUFFIX @@ -1697,12 +1960,16 @@ \ CMAKE_Swift_ANDROID_TOOLCHAIN_MACHINE \ CMAKE_Swift_ANDROID_TOOLCHAIN_PREFIX \ CMAKE_Swift_ANDROID_TOOLCHAIN_SUFFIX + \ CMAKE_Swift_ARCHIVER_WRAPPER_FLAG + \ CMAKE_Swift_ARCHIVER_WRAPPER_FLAG_SEP \ CMAKE_Swift_ARCHIVE_APPEND \ CMAKE_Swift_ARCHIVE_CREATE \ CMAKE_Swift_ARCHIVE_FINISH + \ CMAKE_Swift_ATTRIBUTES \ CMAKE_Swift_BYTE_ORDER \ CMAKE_Swift_CLANG_TIDY \ CMAKE_Swift_CLANG_TIDY_EXPORT_FIXES_DIR + \ CMAKE_Swift_COMPILATION_MODE \ CMAKE_Swift_COMPILER \ CMAKE_Swift_COMPILER_ABI \ CMAKE_Swift_COMPILER_AR @@ -1711,6 +1978,10 @@ \ CMAKE_Swift_COMPILER_FRONTEND_VARIANT \ CMAKE_Swift_COMPILER_ID \ CMAKE_Swift_COMPILER_LAUNCHER + \ CMAKE_Swift_COMPILER_LINKER + \ CMAKE_Swift_COMPILER_LINKER_FRONTEND_VARIANT + \ CMAKE_Swift_COMPILER_LINKER_ID + \ CMAKE_Swift_COMPILER_LINKER_VERSION \ CMAKE_Swift_COMPILER_LOADED \ CMAKE_Swift_COMPILER_PREDEFINES_COMMAND \ CMAKE_Swift_COMPILER_RANLIB @@ -1721,8 +1992,10 @@ \ CMAKE_Swift_CPPCHECK \ CMAKE_Swift_CPPLINT \ CMAKE_Swift_CREATE_SHARED_LIBRARY + \ CMAKE_Swift_CREATE_SHARED_LIBRARY_ARCHIVE \ CMAKE_Swift_CREATE_SHARED_MODULE \ CMAKE_Swift_CREATE_STATIC_LIBRARY + \ CMAKE_Swift_DEVICE_LINK_MODE \ CMAKE_Swift_EXTENSIONS \ CMAKE_Swift_EXTENSIONS_DEFAULT \ CMAKE_Swift_FLAGS @@ -1735,6 +2008,10 @@ \ CMAKE_Swift_FLAGS_RELEASE_INIT \ CMAKE_Swift_FLAGS_RELWITHDEBINFO \ CMAKE_Swift_FLAGS_RELWITHDEBINFO_INIT + \ CMAKE_Swift_HOST_COMPILER + \ CMAKE_Swift_HOST_COMPILER_ID + \ CMAKE_Swift_HOST_COMPILER_VERSION + \ CMAKE_Swift_ICSTAT \ CMAKE_Swift_IGNORE_EXTENSIONS \ CMAKE_Swift_IMPLICIT_INCLUDE_DIRECTORIES \ CMAKE_Swift_IMPLICIT_LINK_DIRECTORIES @@ -1749,10 +2026,12 @@ \ CMAKE_Swift_LINKER_PREFERENCE_PROPAGATES \ CMAKE_Swift_LINKER_WRAPPER_FLAG \ CMAKE_Swift_LINKER_WRAPPER_FLAG_SEP + \ CMAKE_Swift_LINK_DEF_FILE_FLAG \ CMAKE_Swift_LINK_EXECUTABLE \ CMAKE_Swift_LINK_LIBRARY_FILE_FLAG \ CMAKE_Swift_LINK_LIBRARY_FLAG \ CMAKE_Swift_LINK_LIBRARY_SUFFIX + \ CMAKE_Swift_LINK_MODE \ CMAKE_Swift_LINK_WHAT_YOU_USE_FLAG \ CMAKE_Swift_MODULE_DIRECTORY \ CMAKE_Swift_NUM_THREADS @@ -1765,13 +2044,18 @@ \ CMAKE_Swift_STANDARD \ CMAKE_Swift_STANDARD_DEFAULT \ CMAKE_Swift_STANDARD_INCLUDE_DIRECTORIES + \ CMAKE_Swift_STANDARD_LATEST \ CMAKE_Swift_STANDARD_LIBRARIES + \ CMAKE_Swift_STANDARD_LINK_DIRECTORIES \ CMAKE_Swift_STANDARD_REQUIRED \ CMAKE_Swift_SUPPORTED + \ CMAKE_Swift_USING_LINKER_MODE \ CMAKE_Swift_VISIBILITY_PRESET \ CMAKE_TASKING_TOOLSET + \ CMAKE_TEST_LAUNCHER \ CMAKE_TLS_CAINFO \ CMAKE_TLS_VERIFY + \ CMAKE_TLS_VERSION \ CMAKE_TOOLCHAIN_FILE \ CMAKE_TRY_COMPILE_CONFIGURATION \ CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES @@ -1780,6 +2064,7 @@ \ CMAKE_TWEAK_VERSION \ CMAKE_UNITY_BUILD \ CMAKE_UNITY_BUILD_BATCH_SIZE + \ CMAKE_UNITY_BUILD_RELOCATABLE \ CMAKE_UNITY_BUILD_UNIQUE_ID \ CMAKE_USER_MAKE_RULES_OVERRIDE \ CMAKE_USER_MAKE_RULES_OVERRIDE_ASM @@ -1818,6 +2103,7 @@ \ CMAKE_VS_PLATFORM_TOOLSET \ CMAKE_VS_PLATFORM_TOOLSET_CUDA \ CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR + \ CMAKE_VS_PLATFORM_TOOLSET_FORTRAN \ CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE \ CMAKE_VS_PLATFORM_TOOLSET_VERSION \ CMAKE_VS_SDK_EXCLUDE_DIRECTORIES @@ -1830,6 +2116,7 @@ \ CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER \ CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION \ CMAKE_VS_TARGET_FRAMEWORK_VERSION + \ CMAKE_VS_USE_DEBUG_LIBRARIES \ CMAKE_VS_VERSION_BUILD_NUMBER \ CMAKE_VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION \ CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION @@ -1840,6 +2127,7 @@ \ CMAKE_WATCOM_RUNTIME_LIBRARY \ CMAKE_WIN32_EXECUTABLE \ CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS + \ CMAKE_WINDOWS_KMDF_VERSION \ CMAKE_XCODE_BUILD_SYSTEM \ CMAKE_XCODE_GENERATE_SCHEME \ CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY @@ -1848,28 +2136,26 @@ \ CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER \ CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN \ CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING - \ CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE \ CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER \ CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS \ CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE \ CMAKE_XCODE_SCHEME_ENABLE_GPU_API_VALIDATION + \ CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE \ CMAKE_XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION \ CMAKE_XCODE_SCHEME_ENVIRONMENT \ CMAKE_XCODE_SCHEME_GUARD_MALLOC + \ CMAKE_XCODE_SCHEME_LAUNCH_CONFIGURATION \ CMAKE_XCODE_SCHEME_LAUNCH_MODE \ CMAKE_XCODE_SCHEME_LLDB_INIT_FILE \ CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP \ CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES \ CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE \ CMAKE_XCODE_SCHEME_MALLOC_STACK + \ CMAKE_XCODE_SCHEME_TEST_CONFIGURATION \ CMAKE_XCODE_SCHEME_THREAD_SANITIZER \ CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP \ CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER \ CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP - \ CMAKE_XCODE_SCHEME_ENABLE_GPU_API_VALIDATION - \ CMAKE_XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION - \ CMAKE_XCODE_SCHEME_LAUNCH_CONFIGURATION - \ CMAKE_XCODE_SCHEME_TEST_CONFIGURATION \ CMAKE_XCODE_SCHEME_WORKING_DIRECTORY \ CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS \ CMAKE_XCODE_XCCONFIG @@ -1903,7 +2189,6 @@ \ CTEST_CUSTOM_MAXIMUM_NUMBER_OF_ERRORS \ CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS \ CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE - \ CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION \ CTEST_CUSTOM_MEMCHECK_IGNORE \ CTEST_CUSTOM_POST_MEMCHECK \ CTEST_CUSTOM_POST_TEST @@ -1923,6 +2208,7 @@ \ CTEST_DROP_SITE_PASSWORD \ CTEST_DROP_SITE_USER \ CTEST_EXTRA_COVERAGE_GLOB + \ CTEST_EXTRA_SUBMIT_FILES \ CTEST_GIT_COMMAND \ CTEST_GIT_INIT_SUBMODULES \ CTEST_GIT_UPDATE_CUSTOM @@ -1936,6 +2222,7 @@ \ CTEST_MEMORYCHECK_SUPPRESSIONS_FILE \ CTEST_MEMORYCHECK_TYPE \ CTEST_NIGHTLY_START_TIME + \ CTEST_NOTES_FILES \ CTEST_P4_CLIENT \ CTEST_P4_COMMAND \ CTEST_P4_OPTIONS @@ -1953,6 +2240,8 @@ \ CTEST_SVN_UPDATE_OPTIONS \ CTEST_TEST_LOAD \ CTEST_TEST_TIMEOUT + \ CTEST_TLS_VERIFY + \ CTEST_TLS_VERSION \ CTEST_TRIGGER_SITE \ CTEST_UPDATE_COMMAND \ CTEST_UPDATE_OPTIONS @@ -2226,6 +2515,7 @@ \ DOXYGEN_USE_PDFLATEX \ DOXYGEN_VERBATIM_HEADERS \ DOXYGEN_VERBATIM_VARS + \ Doxygen_VERSION \ DOXYGEN_VERSION \ DOXYGEN_WARNINGS \ DOXYGEN_WARN_AS_ERROR @@ -2259,17 +2549,20 @@ \ MSVC_VERSION \ MSYS \ PROJECT_BINARY_DIR + \ PROJECT_COMPAT_VERSION \ PROJECT_DESCRIPTION \ PROJECT_HOMEPAGE_URL \ PROJECT_IS_TOP_LEVEL \ PROJECT_NAME \ PROJECT_SOURCE_DIR + \ PROJECT_SPDX_LICENSE \ PROJECT_VERSION \ PROJECT_VERSION_MAJOR \ PROJECT_VERSION_MINOR \ PROJECT_VERSION_PATCH \ PROJECT_VERSION_TWEAK \ UNIX + \ WASI \ WIN32 \ WINCE \ WINDOWS_PHONE @@ -2287,7 +2580,9 @@ \ BUILD_ALWAYS \ BUILD_BYPRODUCTS \ BUILD_COMMAND + \ BUILD_ENVIRONMENT_MODIFICATION \ BUILD_IN_SOURCE + \ BUILD_JOB_SERVER_AWARE \ CHECKOUT \ CMAKE_ARGS \ CMAKE_CACHE_ARGS @@ -2296,12 +2591,14 @@ \ CMAKE_INSTALL_MODE \ COMMENT \ CONFIGURE_COMMAND + \ CONFIGURE_ENVIRONMENT_MODIFICATION \ CONFIGURE_HANDLED_BY_BUILD \ CVS \ CVSROOT \ CVS_MODULE \ CVS_REPOSITORY \ CVS_TAG + \ DCMAKE_PREFIX_PATH \ DEPENDEES \ DEPENDERS \ DEPENDS @@ -2341,7 +2638,8 @@ \ INSTALL_BYPRODUCTS \ INSTALL_COMMAND \ INSTALL_DIR - \ JOB_POOLS + \ INSTALL_ENVIRONMENT_MODIFICATION + \ INSTALL_JOB_SERVER_AWARE \ LIST_SEPARATOR \ LOG_BUILD \ LOG_CONFIGURE @@ -2380,10 +2678,12 @@ \ TEST_AFTER_INSTALL \ TEST_BEFORE_INSTALL \ TEST_COMMAND + \ TEST_ENVIRONMENT_MODIFICATION \ TEST_EXCLUDE_FROM_MAIN \ TIMEOUT \ TLS_CAINFO \ TLS_VERIFY + \ TLS_VERSION \ TMP_DIR \ TRUE \ UPDATE_COMMAND @@ -2407,11 +2707,10 @@ \ BYPASS_PROVIDER \ CMAKE_PROJECT_ \ CONFIGURE_COMMAND - \ COPY \ CORRECT \ DCMAKE_TOOLCHAIN_FILE - \ DESTINATION \ DOWNLOAD_NO_EXTRACT + \ EXCLUDE_FROM_ALL \ EXISTS \ FETCHCONTENT_BASE_DIR \ FETCHCONTENT_FULLY_DISCONNECTED @@ -2433,6 +2732,7 @@ \ NAME \ NAMES \ NEVER + \ NOT \ NOTE \ OFF \ OPTIONAL @@ -2441,6 +2741,7 @@ \ PACKAGE_VERSION_COMPATIBLE \ PACKAGE_VERSION_EXACT \ QUIET + \ REQUIRED \ SOURCE_SUBDIR \ STREQUAL \ SUBBUILD_DIR @@ -2449,10 +2750,10 @@ \ SYSTEM \ TARGET \ TEST_COMMAND - \ TRUE \ URL \ URL_HASH \ VERIFY_INTERFACE_HEADER_SETS + \ WARNING \ WRITE \ WRONG \ _BINARY_DIR @@ -2475,11 +2776,13 @@ \ _FLAGS_ syn keyword cmakeKWadd_custom_command contained + \ ALIAS \ APPEND \ ARGS \ BNF \ BYPRODUCTS \ CC + \ CODEGEN \ COMMAND \ COMMAND_EXPAND_LISTS \ COMMENT @@ -2493,11 +2796,14 @@ \ INCLUDE_DIRECTORIES \ JOB_POOL \ JOB_POOLS + \ JOB_SERVER_AWARE \ JOIN \ MAIN_DEPENDENCY \ MODULE \ NOT + \ OPTIMIZE_DEPENDENCIES \ OUTPUT + \ OUTPUTS \ PATH \ POST_BUILD \ PRE_BUILD @@ -2525,6 +2831,7 @@ \ INCLUDE_DIRECTORIES \ JOB_POOL \ JOB_POOLS + \ JOB_SERVER_AWARE \ JOIN \ PATH \ SOURCES @@ -2542,6 +2849,7 @@ syn keyword cmakeKWadd_dependencies contained \ DEPENDS + \ MANUALLY_ADDED_DEPENDENCIES \ OBJECT_DEPENDS syn keyword cmakeKWadd_executable contained @@ -2573,7 +2881,6 @@ \ HEADER_FILE_ONLY \ HEADER_SETS \ IMPORTED - \ IMPORTED_ \ IMPORTED_IMPLIB \ IMPORTED_IMPLIB_ \ IMPORTED_LOCATION @@ -2589,7 +2896,6 @@ \ LIBRARY_OUTPUT_DIRECTORY \ MODULE \ OBJECT - \ ON \ OUTPUT_NAME \ POSITION_INDEPENDENT_CODE \ POST_BUILD @@ -2631,22 +2937,25 @@ \ SYSTEM syn keyword cmakeKWadd_test contained - \ BUILD_TESTING \ COMMAND \ COMMAND_EXPAND_LISTS \ CONFIGURATIONS + \ CROSSCOMPILING_EMULATOR \ FAIL_REGULAR_EXPRESSION \ NAME \ OFF \ PASS_REGULAR_EXPRESSION \ SKIP_REGULAR_EXPRESSION \ TARGET_FILE + \ TEST + \ TEST_LAUNCHER \ WILL_FAIL \ WORKING_DIRECTORY syn keyword cmakeKWblock contained \ PARENT_SCOPE \ POLICIES + \ POP \ PROPAGATE \ PUSH \ SCOPE_FOR @@ -2723,6 +3032,7 @@ \ LISTS \ LTS \ MATCHES + \ MSYSTEM_PREFIX \ NNN \ NOT \ NUMBER_OF_LOGICAL_CORES @@ -2755,6 +3065,16 @@ \ VIEW \ WINDOWS_REGISTRY +syn keyword cmakeKWcmake_instrumentation contained + \ API + \ API_VERSION + \ CALLBACK + \ CMAKE_EXPERIMENTAL_INSTRUMENTATION + \ DATA_VERSION + \ HOOKS + \ JSON + \ QUERIES + syn keyword cmakeKWcmake_language contained \ AND \ ANY @@ -2771,6 +3091,7 @@ \ DEFER \ DIRECTORY \ EVAL + \ EXIT \ FALSE \ FETCHCONTENT_MAKEAVAILABLE_SERIAL \ FETCHCONTENT_SOURCE_DIR_ @@ -2790,6 +3111,7 @@ \ OVERRIDE_FIND_PACKAGE \ PATH \ POP_BACK + \ PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE \ QUIET \ SET_DEPENDENCY_PROVIDER \ SOURCE_DIR @@ -2803,7 +3125,9 @@ \ _PATH syn keyword cmakeKWcmake_minimum_required contained + \ CMAKE_POLICY_DEFAULT_CMP \ FATAL_ERROR + \ NNNN \ VERSION syn keyword cmakeKWcmake_parse_arguments contained @@ -2813,21 +3137,13 @@ \ FALSE \ FAST \ FILES - \ MY_INSTALL - \ MY_INSTALL_CONFIGURATIONS - \ MY_INSTALL_DESTINATION - \ MY_INSTALL_FAST - \ MY_INSTALL_KEYWORDS_MISSING_VALUES - \ MY_INSTALL_OPTIONAL - \ MY_INSTALL_RENAME - \ MY_INSTALL_TARGETS - \ MY_INSTALL_UNPARSED_ARGUMENTS + \ NOTE \ OPTIONAL \ PARSE_ARGV \ RENAME \ TARGETS \ TRUE - \ UNDEFINED + \ UNSET \ _KEYWORDS_MISSING_VALUES \ _UNPARSED_ARGUMENTS @@ -2893,6 +3209,72 @@ \ TRUE \ XOR +syn keyword cmakeKWcmake_pkg_config contained + \ ALLOW_SYSTEM_INCLUDES + \ ALLOW_SYSTEM_LIBS + \ BEST_EFFORT + \ BIND_PC_REQUIRES + \ CMAKE_PKG_CONFIG_ALLOW_SYS_INCLUDES + \ CMAKE_PKG_CONFIG_ALLOW_SYS_LIBS + \ CMAKE_PKG_CONFIG_CFLAGS + \ CMAKE_PKG_CONFIG_COMPILE_OPTIONS + \ CMAKE_PKG_CONFIG_CONFLICTS + \ CMAKE_PKG_CONFIG_DESCRIPTION + \ CMAKE_PKG_CONFIG_INCLUDES + \ CMAKE_PKG_CONFIG_LIBDIRS + \ CMAKE_PKG_CONFIG_LIBNAMES + \ CMAKE_PKG_CONFIG_LIBS + \ CMAKE_PKG_CONFIG_LINK_OPTIONS + \ CMAKE_PKG_CONFIG_NAME + \ CMAKE_PKG_CONFIG_PKGCONF_INCLUDES + \ CMAKE_PKG_CONFIG_PKGCONF_LIB_DIRS + \ CMAKE_PKG_CONFIG_PROVIDES + \ CMAKE_PKG_CONFIG_REQUIRES + \ CMAKE_PKG_CONFIG_SYS_INCLUDE_DIRS + \ CMAKE_PKG_CONFIG_SYS_LIB_DIRS + \ CMAKE_PKG_CONFIG_VERSION + \ CPATH + \ CPLUS_INCLUDE_PATH + \ C_INCLUDE_PATH + \ DISABLE_UNINSTALLED + \ ENV_MODE + \ EXACT + \ EXTRACT + \ FDO + \ IGNORE + \ IMPORT + \ IMPORTED + \ INTERFACE_LINK_LIBRARIES + \ OBJC_INCLUDE_PATH + \ PC_LIBDIR + \ PC_PATH + \ PC_SYSROOT_DIR + \ PERMISSIVE + \ PKGCONF + \ PKGCONFIG_ + \ PKG_CONFIG_ + \ PKG_CONFIG_ALLOW_ + \ PKG_CONFIG_ALLOW_SYSTEM_CFLAGS + \ PKG_CONFIG_ALLOW_SYSTEM_LIBS + \ PKG_CONFIG_DISABLE_UNINSTALLED + \ PKG_CONFIG_LIBDIR + \ PKG_CONFIG_PATH + \ PKG_CONFIG_SYSROOT_DIR + \ PKG_CONFIG_SYSROOT_PATH + \ PKG_CONFIG_SYSTEM_INCLUDE_PATH + \ PKG_CONFIG_SYSTEM_LIBRARY_PATH + \ PKG_CONFIG_TOP_BUILD_DIR + \ POPULATE + \ PREFIX + \ QUIET + \ REQUIRED + \ STRICTNESS + \ SYSTEM_INCLUDE_DIRS + \ SYSTEM_LIBRARY_DIRS + \ TOP_BUILD_DIR + \ _FOUND + \ _PRIVATE + syn keyword cmakeKWcmake_policy contained \ CMAKE_POLICY_DEFAULT_CMP \ CMP @@ -3011,8 +3393,6 @@ \ CAPTURE_CMAKE_ERROR \ CDASH_UPLOAD \ CDASH_UPLOAD_TYPE - \ CTEST_EXTRA_SUBMIT_FILES - \ CTEST_NOTES_FILES \ FILES \ HTTPHEADER \ PARTS @@ -3034,10 +3414,13 @@ \ EXCLUDE_FIXTURE \ EXCLUDE_FIXTURE_CLEANUP \ EXCLUDE_FIXTURE_SETUP + \ EXCLUDE_FROM_FILE \ EXCLUDE_LABEL \ INCLUDE + \ INCLUDE_FROM_FILE \ INCLUDE_LABEL \ LABELS + \ NOT \ OFF \ ON \ OUTPUT_JUNIT @@ -3074,11 +3457,14 @@ \ BRIEF_DOCS \ CACHED_VARIABLE \ CMAKE_ + \ DEFINED \ DIRECTORY \ FULL_DOCS \ GLOBAL \ INHERITED \ INITIALIZE_FROM_VARIABLE + \ MY_NEW_PROP + \ NONE \ PROPERTY \ SOURCE \ TARGET @@ -3105,13 +3491,15 @@ \ OBJCXX \ OPTIONAL -syn keyword cmakeKWenable_testing contained - \ BUILD_TESTING - syn keyword cmakeKWexec_program contained \ ARGS + \ COMMAND + \ ERROR_VARIABLE + \ OUTPUT_STRIP_TRAILING_WHITESPACE \ OUTPUT_VARIABLE + \ RESULT_VARIABLE \ RETURN_VALUE + \ WORKING_DIRECTORY syn keyword cmakeKWexecute_process contained \ ANSI @@ -3148,17 +3536,42 @@ syn keyword cmakeKWexport contained \ ANDROID_MK \ APPEND + \ APPENDIX + \ AUTO + \ CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_DEPENDENCIES + \ CMAKE_MAP_IMPORTED_CONFIG_ + \ COMPAT_VERSION \ CONFIG + \ CPS \ CXX_MODULES_DIRECTORY + \ DEFAULT_CONFIGURATIONS + \ DEFAULT_LICENSE + \ DEFAULT_TARGETS + \ DESCRIPTION + \ ENABLED \ EXPORT \ EXPORT_LINK_INTERFACE_LIBRARIES + \ EXPORT_PACKAGE_DEPENDENCIES + \ EXTRA_ARGS \ FILE + \ HOMEPAGE_URL \ IMPORTED_ + \ LICENSE + \ LOWER_CASE_FILE \ NAMESPACE \ NDK + \ NO_PROJECT_METADATA \ OLD \ PACKAGE + \ PACKAGE_DEPENDENCY + \ PACKAGE_INFO + \ PROJECT + \ REQUIRED + \ SETUP \ TARGETS + \ VERSION + \ VERSION_SCHEMA + \ XCFRAMEWORK_LOCATION syn keyword cmakeKWexport_library_dependencies contained \ APPEND @@ -3180,7 +3593,7 @@ \ CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM \ CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL \ CMAKE_INSTALL_MODE - \ CMAKE_OBJDUMP + \ CMAKE_MATCH_ \ CODE \ COMPILE_FEATURES \ COMPRESSION @@ -3197,13 +3610,14 @@ \ CREATE_LINK \ CRLF \ DESTINATION - \ DIRECTORIES \ DIRECTORY_PERMISSIONS \ DLL \ DOS \ DOWNLOAD + \ ELF \ ENCODING \ ESCAPE_QUOTES + \ EXCLUDE \ EXECUTABLES \ EXPAND_TILDE \ EXPECTED_HASH @@ -3244,6 +3658,7 @@ \ LOCK \ LOG \ MAKE_DIRECTORY + \ MATCHALL \ MODULES \ MTIME \ MYLIBRARY @@ -3309,6 +3724,7 @@ \ TIMESTAMP \ TLS_CAINFO \ TLS_VERIFY + \ TLS_VERSION \ TOUCH \ TOUCH_NOCREATE \ TO_CMAKE_PATH @@ -3323,7 +3739,9 @@ \ USE_SOURCE_PERMISSIONS \ UTC \ UTF + \ VAR \ VERBOSE + \ WORKING_DIRECTORY \ WORLD_EXECUTE \ WORLD_READ \ WORLD_WRITE @@ -3339,7 +3757,9 @@ \ DOC \ DVAR \ FALSE + \ FIND_XXX_ORDER \ FIND_XXX_REGISTRY_VIEW + \ FIND_XXX_ROOT \ HINTS \ HOST \ INCLUDE @@ -3356,6 +3776,7 @@ \ NO_PACKAGE_ROOT_PATH \ NO_SYSTEM_ENVIRONMENT_PATH \ ONLY_CMAKE_FIND_ROOT_PATH + \ OPTIONAL \ PACKAGENAME \ PARENT_SCOPE \ PATHS @@ -3374,7 +3795,9 @@ \ DOC \ DVAR \ FALSE + \ FIND_XXX_ORDER \ FIND_XXX_REGISTRY_VIEW + \ FIND_XXX_ROOT \ HINTS \ HOST \ LIB @@ -3392,6 +3815,7 @@ \ NO_PACKAGE_ROOT_PATH \ NO_SYSTEM_ENVIRONMENT_PATH \ ONLY_CMAKE_FIND_ROOT_PATH + \ OPTIONAL \ PACKAGENAME \ PARENT_SCOPE \ PATHS @@ -3404,17 +3828,16 @@ syn keyword cmakeKWfind_package contained \ ABI + \ ASC \ BOTH \ BUNDLE \ BYPASS_PROVIDER \ CATEGORY \ CMAKE_DISABLE_FIND_PACKAGE_ - \ CMAKE_REQUIRE_FIND_PACKAGE_ \ CMAKE_FIND_ROOT_PATH_BOTH \ CMAKE_FIND_USE_ \ CMAKE_REQUIRE_FIND_PACKAGE_ \ COMPONENTS - \ CONFIG \ CONFIGS \ DEC \ DVAR @@ -3422,6 +3845,7 @@ \ EXCLUDE \ FALSE \ FIND_PACKAGE_VERSION_FORMAT + \ FIND_XXX_REGISTRY_VIEW \ FRAMEWORK \ GLOBAL \ HINTS @@ -3430,6 +3854,7 @@ \ MODULE \ NAMES \ NATURAL + \ NONE \ NO_CMAKE_BUILDS_PATH \ NO_CMAKE_ENVIRONMENT_PATH \ NO_CMAKE_FIND_ROOT_PATH @@ -3443,8 +3868,8 @@ \ NO_PACKAGE_ROOT_PATH \ NO_POLICY_SCOPE \ NO_SYSTEM_ENVIRONMENT_PATH - \ OLD \ ONLY_CMAKE_FIND_ROOT_PATH + \ OPTIONAL \ OPTIONAL_COMPONENTS \ PACKAGENAME \ PACKAGE_FIND_NAME @@ -3477,7 +3902,6 @@ \ QUIET \ REGISTRY_VIEW \ REQUIRED - \ SET \ TARGET \ TRUE \ VALUE @@ -3501,7 +3925,9 @@ \ DOC \ DVAR \ FALSE + \ FIND_XXX_ORDER \ FIND_XXX_REGISTRY_VIEW + \ FIND_XXX_ROOT \ HINTS \ HOST \ INCLUDE @@ -3518,6 +3944,7 @@ \ NO_PACKAGE_ROOT_PATH \ NO_SYSTEM_ENVIRONMENT_PATH \ ONLY_CMAKE_FIND_ROOT_PATH + \ OPTIONAL \ PACKAGENAME \ PARENT_SCOPE \ PATHS @@ -3536,10 +3963,13 @@ \ DOC \ DVAR \ FALSE + \ FIND_XXX_ORDER \ FIND_XXX_REGISTRY_VIEW + \ FIND_XXX_ROOT \ HINTS \ HOST \ MATCHES + \ MY_SCRIPT \ NAMES \ NAMES_PER_DIR \ NOT @@ -3553,6 +3983,7 @@ \ NO_PACKAGE_ROOT_PATH \ NO_SYSTEM_ENVIRONMENT_PATH \ ONLY_CMAKE_FIND_ROOT_PATH + \ OPTIONAL \ PACKAGENAME \ PARENT_SCOPE \ PATHS @@ -3635,11 +4066,10 @@ syn keyword cmakeKWget_target_property contained \ INHERITED - \ VAR syn keyword cmakeKWget_test_property contained + \ DIRECTORY \ INHERITED - \ VAR syn keyword cmakeKWif contained \ CMAKE_MATCH_ @@ -3656,15 +4086,17 @@ \ IN_LIST \ IS_ABSOLUTE \ IS_DIRECTORY + \ IS_EXECUTABLE \ IS_NEWER_THAN + \ IS_READABLE \ IS_SYMLINK + \ IS_WRITABLE \ LESS \ LESS_EQUAL \ MATCHES \ NNNN \ NOT \ OFF - \ OR \ PATH_EQUAL \ POLICY \ STREQUAL @@ -3708,15 +4140,13 @@ \ __CURRENT_FILE_VAR__ syn keyword cmakeKWinstall contained - \ AFTER - \ AIX \ ALL_COMPONENTS + \ APPENDIX \ APT \ ARCHIVE - \ BEFORE \ BUILD_TYPE - \ BUNDLE \ BUNDLE_EXECUTABLE + \ CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_DEPENDENCIES \ CMAKE_INSTALL_BINDIR \ CMAKE_INSTALL_DATADIR \ CMAKE_INSTALL_DATAROOTDIR @@ -3724,6 +4154,7 @@ \ CMAKE_INSTALL_INCLUDEDIR \ CMAKE_INSTALL_INFODIR \ CMAKE_INSTALL_LIBDIR + \ CMAKE_INSTALL_LIBEXECDIR \ CMAKE_INSTALL_LOCALEDIR \ CMAKE_INSTALL_LOCALSTATEDIR \ CMAKE_INSTALL_MANDIR @@ -3732,9 +4163,12 @@ \ CMAKE_INSTALL_SBINDIR \ CMAKE_INSTALL_SHARESTATEDIR \ CMAKE_INSTALL_SYSCONFDIR + \ CMAKE_MAP_IMPORTED_CONFIG_ \ CODE + \ COMPAT_VERSION \ COMPONENT \ CONFIGURATIONS + \ CPS \ CVS \ CXX_MODULES_BMI \ CXX_MODULES_DIRECTORY @@ -3742,19 +4176,28 @@ \ DATAROOT \ DBUILD_TYPE \ DCOMPONENT + \ DEFAULT_CONFIGURATIONS + \ DEFAULT_LICENSE + \ DEFAULT_TARGETS + \ DESCRIPTION \ DESTDIR \ DESTINATION \ DIRECTORY \ DIRECTORY_PERMISSIONS \ DLL \ DOC + \ ENABLED \ ENABLE_EXPORTS + \ EXCLUDE_EMPTY_DIRECTORIES \ EXCLUDE_FROM_ALL \ EXECUTABLES \ EXPORT \ EXPORT_ANDROID_MK + \ EXPORT_FIND_PACKAGE_NAME \ EXPORT_LINK_INTERFACE_LIBRARIES \ EXPORT_NAME + \ EXPORT_PACKAGE_DEPENDENCIES + \ EXTRA_ARGS \ FILES \ FILES_MATCHING \ FILE_PERMISSIONS @@ -3765,15 +4208,19 @@ \ GROUP_READ \ GROUP_WRITE \ HEADERS + \ HOMEPAGE_URL \ IMPORTED_RUNTIME_ARTIFACTS \ INCLUDES - \ INFO + \ INSTALL_PARALLEL \ INSTALL_PREFIX \ INTERFACE \ INTERFACE_INCLUDE_DIRECTORIES + \ LIBEXEC \ LIBRARY + \ LICENSE \ LOCALE \ LOCALSTATE + \ LOWER_CASE_FILE \ MACOSX_BUNDLE \ MAN \ MESSAGE_NEVER @@ -3782,11 +4229,14 @@ \ NAMELINK_SKIP \ NAMESPACE \ NDK + \ NO_PROJECT_METADATA \ OBJECTS + \ OFF \ OPTIONAL \ OWNER_EXECUTE \ OWNER_READ \ OWNER_WRITE + \ PACKAGE_INFO \ PATTERN \ PERMISSIONS \ POST_EXCLUDE_FILES @@ -3799,9 +4249,12 @@ \ PRE_INSTALL_SCRIPT \ PRIVATE_HEADER \ PROGRAMS + \ PROJECT \ PROPERTIES + \ PROPERTY \ PUBLIC_HEADER \ RENAME + \ REQUIRED \ RESOURCE \ RPM \ RUNSTATE @@ -3811,8 +4264,11 @@ \ SCRIPT \ SETGID \ SETUID + \ SETUP \ SHAREDSTATE \ SOVERSION + \ SPDX + \ SPDX_LICENSE \ STATIC \ SYSCONF \ TARGETS @@ -3820,6 +4276,7 @@ \ TYPE \ USE_SOURCE_PERMISSIONS \ VERSION + \ VERSION_SCHEMA \ WORLD_EXECUTE \ WORLD_READ \ WORLD_WRITE @@ -3896,7 +4353,9 @@ syn keyword cmakeKWload_cache contained \ EXCLUDE \ INCLUDE_INTERNALS + \ OTHER_PROJECT_INTERNAL_CACHE_VAR \ READ_WITH_PREFIX + \ STATUS syn keyword cmakeKWload_command contained \ CMAKE_LOADED_COMMAND_ @@ -3956,6 +4415,8 @@ \ ASM_NASM \ ATT \ CMAKE_PROJECT_ + \ COMPAT_VERSION + \ CPS \ CUDA \ DESCRIPTION \ HIP @@ -3967,14 +4428,16 @@ \ OBJC \ OBJCXX \ PROJECT + \ SPDX_LICENSE \ VERSION \ _BINARY_DIR + \ _COMPAT_VERSION \ _DESCRIPTION \ _HOMEPAGE_URL \ _INCLUDE_BEFORE \ _IS_TOP_LEVEL \ _SOURCE_DIR - \ _VERSION + \ _SPDX_LICENSE \ _VERSION_MAJOR \ _VERSION_MINOR \ _VERSION_PATCH @@ -4051,6 +4514,7 @@ \ PROPERTIES syn keyword cmakeKWset_tests_properties contained + \ DIRECTORY \ NAME \ PROPERTIES @@ -4195,28 +4659,35 @@ syn keyword cmakeKWtarget_link_libraries contained \ ALIAS + \ CMAKE_ \ DA \ DAG \ DEBUG_CONFIGURATIONS \ DOBJ + \ GCC \ IMPORTED + \ IMPORTED_CONFIGURATIONS \ IMPORTED_NO_SONAME \ INTERFACE \ INTERFACE_LINK_LIBRARIES + \ LANG + \ LINKER \ LINK_FLAGS \ LINK_INTERFACE_LIBRARIES - \ LINK_INTERFACE_LIBRARIES_DEBUG \ LINK_INTERFACE_MULTIPLICITY + \ LINK_LIBRARIES_STRATEGY \ LINK_OPTIONS \ LINK_PRIVATE \ LINK_PUBLIC \ OBJECT - \ OLD \ PRIVATE \ PUBLIC \ SHARED + \ SHELL \ STATIC \ TARGET_OBJECTS + \ _LINKER_WRAPPER_FLAG + \ _LINKER_WRAPPER_FLAG_SEP syn keyword cmakeKWtarget_link_options contained \ ALIAS @@ -4250,7 +4721,6 @@ \ BUILD_INTERFACE \ COMPILE_LANGUAGE \ DISABLE_PRECOMPILE_HEADERS - \ EXPORT \ FI \ GCC \ IMPORTED @@ -4312,27 +4782,29 @@ \ CUDA_STANDARD \ CUDA_STANDARD_REQUIRED \ CXX_EXTENSIONS + \ CXX_MODULE + \ CXX_MODULES \ CXX_STANDARD \ CXX_STANDARD_REQUIRED \ C_EXTENSIONS \ C_STANDARD \ C_STANDARD_REQUIRED + \ DCOMPILE_DEFINITIONS \ DEFINED \ DLINK_LIBRARIES \ DVAR \ EXECUTABLE \ FALSE + \ FILE_SET \ GHS - \ HIP_EXTENSIONS - \ HIP_STANDARD - \ HIP_STANDARD_REQUIRED \ INCLUDE_DIRECTORIES - \ LANG + \ LINKER_LANGUAGE \ LINK_DIRECTORIES \ LINK_LIBRARIES \ LINK_OPTIONS \ LOG_DESCRIPTION \ MULTI + \ NORMAL \ NOT \ NO_CACHE \ NO_LOG @@ -4345,8 +4817,9 @@ \ OUTPUT_VARIABLE \ PRIVATE \ PROJECT + \ PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE \ RESULTVAR - \ SOURCES + \ SOURCES_TYPE \ SOURCE_DIR \ SOURCE_FROM_CONTENT \ SOURCE_FROM_FILE @@ -4355,7 +4828,6 @@ \ STATIC_LIBRARY_OPTIONS \ TARGET \ TRUE - \ TYPE \ VALUE \ _EXTENSIONS \ _STANDARD @@ -4369,8 +4841,8 @@ \ COPY_FILE \ COPY_FILE_ERROR \ FAILED_TO_RUN - \ FALSE \ LANG + \ LINKER_LANGUAGE \ LINK_LIBRARIES \ LINK_OPTIONS \ LOG_DESCRIPTION @@ -4379,11 +4851,10 @@ \ RUN_OUTPUT_STDERR_VARIABLE \ RUN_OUTPUT_STDOUT_VARIABLE \ RUN_OUTPUT_VARIABLE - \ SOURCES + \ SOURCES_TYPE \ SOURCE_FROM_CONTENT \ SOURCE_FROM_FILE \ SOURCE_FROM_VAR - \ TRUE \ WORKING_DIRECTORY \ _EXTENSIONS \ _STANDARD @@ -4423,7 +4894,6 @@ syn keyword cmakeGeneratorExpressions contained \ ABSOLUTE_PATH \ ACTION - \ AIX \ ANGLE \ APPEND \ ARCHIVE_OUTPUT_NAME @@ -4440,6 +4910,7 @@ \ COMMAND_CONFIG \ COMMAND_EXPAND_LISTS \ COMPARE + \ COMPATIBLE_INTERFACE_ \ COMPILE_DEFINITIONS \ COMPILE_FEATURES \ COMPILE_LANGUAGE @@ -4453,16 +4924,25 @@ \ CONFIG \ CONFIGURATION \ CONTENT + \ CUDA_COMPILER_FRONTEND_VARIANT \ CUDA_COMPILER_ID + \ CUDA_COMPILER_LINKER_FRONTEND_VARIANT + \ CUDA_COMPILER_LINKER_ID \ CUDA_COMPILER_VERSION \ CUDA_RESOLVE_DEVICE_SYMBOLS \ CUDA_SEPARABLE_COMPILATION \ CUSTOM_KEYS + \ CXX_COMPILER_FRONTEND_VARIANT \ CXX_COMPILER_ID + \ CXX_COMPILER_LINKER_FRONTEND_VARIANT + \ CXX_COMPILER_LINKER_ID \ CXX_COMPILER_VERSION \ CXX_CONFIG \ CXX_STANDARD + \ C_COMPILER_FRONTEND_VARIANT \ C_COMPILER_ID + \ C_COMPILER_LINKER_FRONTEND_VARIANT + \ C_COMPILER_LINKER_ID \ C_COMPILER_VERSION \ C_STANDARD \ DEBUG_MODE @@ -4501,9 +4981,11 @@ \ HAS_ROOT_PATH \ HAS_STEM \ HAVE_SOME_FEATURE + \ HIP_COMPILER_FRONTEND_VARIANT \ HIP_COMPILER_ID + \ HIP_COMPILER_LINKER_FRONTEND_VARIANT + \ HIP_COMPILER_LINKER_ID \ HIP_COMPILER_VERSION - \ HIP_STANDARD \ HOST_LINK \ IF \ IGNORE @@ -4519,7 +5001,9 @@ \ INSTALL_RPATH \ INTERFACE_LINK_LIBRARIES \ INTERFACE_LINK_LIBRARIES_DIRECT + \ INTERFACE_PROP \ IN_LIST + \ ISPC_COMPILER_FRONTEND_VARIANT \ ISPC_COMPILER_ID \ ISPC_COMPILER_VERSION \ IS_ABSOLUTE @@ -4546,14 +5030,21 @@ \ MAKE_C_IDENTIFIER \ MAP_IMPORTED_CONFIG_ \ MODULE + \ NATIVE_PATH \ NATURAL \ NO \ NORMALIZE \ NORMAL_PATH \ NOT + \ OBJCXX_COMPILER_FRONTEND_VARIANT \ OBJCXX_COMPILER_ID + \ OBJCXX_COMPILER_LINKER_FRONTEND_VARIANT + \ OBJCXX_COMPILER_LINKER_ID \ OBJCXX_COMPILER_VERSION + \ OBJC_COMPILER_FRONTEND_VARIANT \ OBJC_COMPILER_ID + \ OBJC_COMPILER_LINKER_FRONTEND_VARIANT + \ OBJC_COMPILER_LINKER_ID \ OBJC_COMPILER_VERSION \ OBJECT \ OFF @@ -4577,6 +5068,7 @@ \ PREPEND \ PRIVATE \ PUBLIC + \ QUOTE \ REGEX \ RELATIVE_PATH \ REMOVE_AT @@ -4665,6 +5157,8 @@ \ TRANSFORM_REPLACE \ TRANSFORM_STRIP \ TRANSFORM_TOLOWER + \ TRANSITIVE_COMPILE_PROPERTIES + \ TRANSITIVE_LINK_PROPERTIES \ UNKNOWN \ UPPER_CASE \ VERBATIM @@ -4674,6 +5168,9 @@ \ VERSION_LESS_EQUAL \ WHOLE_ARCHIVE \ WRONG + \ _COMPILER_FRONTEND_VARIANT + \ _COMPILER_LINKER_FRONTEND_VARIANT + \ _COMPILER_LINKER_ID \ _LINK_GROUP_USING_ \ _LINK_LIBRARY_USING_ \ _POSTFIX @@ -4694,15 +5191,16 @@ \ add_subdirectory \ add_test \ aux_source_directory - \ block \ break \ build_command \ cmake_file_api \ cmake_host_system_information + \ cmake_instrumentation \ cmake_language \ cmake_minimum_required \ cmake_parse_arguments \ cmake_path + \ cmake_pkg_config \ cmake_policy \ configure_file \ continue @@ -4723,9 +5221,6 @@ \ define_property \ enable_language \ enable_testing - \ endblock - \ endfunction - \ endmacro \ execute_process \ export \ file @@ -4735,7 +5230,6 @@ \ find_path \ find_program \ fltk_wrap_ui - \ function \ get_cmake_property \ get_directory_property \ get_filename_component @@ -4753,7 +5247,6 @@ \ list \ load_cache \ load_command - \ macro \ mark_as_advanced \ math \ message @@ -4788,20 +5281,6 @@ \ variable_watch \ nextgroup=cmakeArguments -syn keyword cmakeCommandConditional - \ else - \ elseif - \ endif - \ if - \ nextgroup=cmakeArguments - -syn keyword cmakeCommandRepeat - \ endforeach - \ endwhile - \ foreach - \ while - \ nextgroup=cmakeArguments - syn keyword cmakeCommandDeprecated \ build_name \ exec_program @@ -4830,14 +5309,14 @@ hi def link cmakeBracketArgument String hi def link cmakeBracketComment Comment hi def link cmakeCommand Function -hi def link cmakeCommandConditional Conditional hi def link cmakeCommandDeprecated WarningMsg -hi def link cmakeCommandRepeat Repeat hi def link cmakeComment Comment +hi def link cmakeElse Conditional hi def link cmakeEnvironment Special hi def link cmakeEscaped Special hi def link cmakeGeneratorExpression WarningMsg hi def link cmakeGeneratorExpressions Constant +hi def link cmakeKeyword Conditional hi def link cmakeModule Include hi def link cmakeProperty Constant hi def link cmakeRegistry Underlined @@ -4863,10 +5342,12 @@ hi def link cmakeKWbuild_command ModeMsg hi def link cmakeKWcmake_file_api ModeMsg hi def link cmakeKWcmake_host_system_information ModeMsg +hi def link cmakeKWcmake_instrumentation ModeMsg hi def link cmakeKWcmake_language ModeMsg hi def link cmakeKWcmake_minimum_required ModeMsg hi def link cmakeKWcmake_parse_arguments ModeMsg hi def link cmakeKWcmake_path ModeMsg +hi def link cmakeKWcmake_pkg_config ModeMsg hi def link cmakeKWcmake_policy ModeMsg hi def link cmakeKWconfigure_file ModeMsg hi def link cmakeKWcreate_test_sourcelist ModeMsg @@ -4883,7 +5364,6 @@ hi def link cmakeKWdefine_property ModeMsg hi def link cmakeKWdoxygen_add_docs ModeMsg hi def link cmakeKWenable_language ModeMsg -hi def link cmakeKWenable_testing ModeMsg hi def link cmakeKWexec_program ModeMsg hi def link cmakeKWexecute_process ModeMsg hi def link cmakeKWexport ModeMsg
diff --git a/CMakeCPack.cmake b/CMakeCPack.cmake index 3ac6030..b0e5848 100644 --- a/CMakeCPack.cmake +++ b/CMakeCPack.cmake
@@ -11,7 +11,7 @@ endif() if(CMake_INSTALL_DEPENDENCIES) - include(${CMake_SOURCE_DIR}/Modules/InstallRequiredSystemLibraries.cmake) + include(InstallRequiredSystemLibraries) endif() set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_BINARY_DIR}/CMakeFiles/LICENSE.txt") @@ -52,7 +52,7 @@ endif() # Command for configure IFW script templates -include(${CMake_SOURCE_DIR}/Modules/CPackIFWConfigureFile.cmake) +include(CPackIFWConfigureFile) # Advanced IFW configuration set(_cpifwrc CPACK_IFW_COMPONENT_GROUP_CMAKE_) @@ -177,7 +177,7 @@ endif() endif() install(FILES "${CMake_SOURCE_DIR}/Source/QtIFW/cmake.org.html" - DESTINATION "${CMAKE_DOC_DIR}" + DESTINATION "${CMake_INSTALL_DOC_DIR}" ) endif() @@ -220,7 +220,7 @@ set(CPACK_PACKAGE_CONTACT "cmake+development@discourse.cmake.org") if(UNIX) - set(CPACK_STRIP_FILES "${CMAKE_BIN_DIR}/ccmake;${CMAKE_BIN_DIR}/cmake;${CMAKE_BIN_DIR}/cpack;${CMAKE_BIN_DIR}/ctest") + set(CPACK_STRIP_FILES "${CMake_INSTALL_BIN_DIR}/ccmake;${CMake_INSTALL_BIN_DIR}/cmake;${CMake_INSTALL_BIN_DIR}/cpack;${CMake_INSTALL_BIN_DIR}/ctest") set(CPACK_SOURCE_STRIP_FILES "") set(CPACK_PACKAGE_EXECUTABLES "ccmake" "CMake") endif()
diff --git a/CMakeCPackOptions.cmake.in b/CMakeCPackOptions.cmake.in index 65f266e..fe7cab2 100644 --- a/CMakeCPackOptions.cmake.in +++ b/CMakeCPackOptions.cmake.in
@@ -13,7 +13,7 @@ set(CPACK_PACKAGE_ICON "@CMake_SOURCE_DIR@/Utilities/Release\\CMakeInstall.bmp") # tell cpack to create links to the doc files set(CPACK_NSIS_MENU_LINKS - "@CMAKE_DOC_DIR@/html/index.html" "CMake Documentation" + "@CMake_INSTALL_DOC_DIR@/html/index.html" "CMake Documentation" "https://cmake.org" "CMake Web Site" ) # Use the icon from cmake-gui for add-remove programs @@ -241,7 +241,7 @@ "@CMake_SOURCE_DIR@/Utilities/Release/CMakeLogo.ico" ) - set_property(INSTALL "@CMAKE_DOC_DIR@/html/index.html" PROPERTY + set_property(INSTALL "@CMake_INSTALL_DOC_DIR@/html/index.html" PROPERTY CPACK_START_MENU_SHORTCUTS "CMake Documentation" )
diff --git a/CMakeLists.txt b/CMakeLists.txt index ef6e301..8252775 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt
@@ -1,7 +1,7 @@ # Distributed under the OSI-approved BSD 3-Clause License. See accompanying # file LICENSE.rst or https://cmake.org/licensing for details. -cmake_minimum_required(VERSION 3.13...3.31 FATAL_ERROR) +cmake_minimum_required(VERSION 3.13...4.1 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) @@ -111,12 +111,32 @@ # Avoid messaging about curl-only dependencies. list(REMOVE_ITEM UTILITIES NGHTTP2) endif() + + set(DEPS_SYSTEM "") + set(DEPS_BUNDLED "") foreach(util IN LISTS UTILITIES ITEMS KWIML) if(CMAKE_USE_SYSTEM_${util}) - message(STATUS "Using system-installed ${util}") + string(APPEND DEPS_SYSTEM " ${util}") + else() + string(APPEND DEPS_BUNDLED " ${util}") endif() endforeach() + # OpenSSL is not included in the UTILITIES list, + # but it is a system dependency, if used + if(CMAKE_USE_OPENSSL) + string(APPEND DEPS_SYSTEM " OPENSSL") + endif() + + if(DEPS_SYSTEM) + message(STATUS "Using system-installed:${DEPS_SYSTEM}") + endif() + if(DEPS_BUNDLED) + message(STATUS "Using bundled:${DEPS_BUNDLED}") + endif() + unset(DEPS_SYSTEM) + unset(DEPS_BUNDLED) + # Inform utility library header wrappers whether to use system versions. configure_file(Utilities/cmThirdParty.h.in Utilities/cmThirdParty.h @ONLY) endif() @@ -167,6 +187,14 @@ if(NOT CMake_HAVE_CXX_UNIQUE_PTR) message(FATAL_ERROR "The C++ compiler does not support C++11 (e.g. std::unique_ptr).") endif() + + if(CMake_ENABLE_INSTRUMENTATION) + cmake_instrumentation( + API_VERSION 1 + DATA_VERSION 1 + OPTIONS cdashSubmit cdashVerbose trace + ) + endif() endif() # Inform STL library header wrappers whether to use system versions. @@ -211,6 +239,9 @@ option(CMake_BUILD_PCH "Compile CMake with precompiled headers" OFF) +option(CMake_BUILD_FUZZING "Build fuzz testing targets" OFF) +mark_as_advanced(CMake_BUILD_FUZZING) + # Check whether to build support for the debugger mode. if(NOT CMake_TEST_EXTERNAL_CMAKE) if(NOT DEFINED CMake_ENABLE_DEBUGGER) @@ -443,19 +474,6 @@ # build the utilities include(CMakeBuildUtilities) - if(BUILD_QtDialog) - if(APPLE) - set(CMAKE_BUNDLE_VERSION - "${CMake_VERSION_MAJOR}.${CMake_VERSION_MINOR}.${CMake_VERSION_PATCH}") - set(CMAKE_BUNDLE_LOCATION "${CMAKE_INSTALL_PREFIX}") - # make sure CMAKE_INSTALL_PREFIX ends in / - if(NOT CMAKE_INSTALL_PREFIX MATCHES "/$") - string(APPEND CMAKE_INSTALL_PREFIX "/") - endif() - string(APPEND CMAKE_INSTALL_PREFIX "CMake.app/Contents") - endif() - endif() - if(UNIX) # Install executables with the RPATH set for libraries outside the build tree. # This is also suitable for binaries in the build tree. Avoid re-link on install. @@ -485,13 +503,21 @@ NOT "x${CMAKE_C_SIMULATE_ID}" STREQUAL "xMSVC") OR CMAKE_C_COMPILER_ID STREQUAL "AppleClang" OR CMAKE_C_COMPILER_ID STREQUAL "LCC") - set(C_FLAGS_LIST -Wcast-align -Werror-implicit-function-declaration -Wchar-subscripts + set(C_FLAGS_LIST -Wcast-align -Wchar-subscripts -Wall -W -Wpointer-arith -Wwrite-strings -Wformat-security -Wmissing-format-attribute -fno-common -Wundef + -Werror=implicit-function-declaration + -Wstrict-prototypes ) set(CXX_FLAGS_LIST -Wnon-virtual-dtor -Wcast-align -Wchar-subscripts -Wall -W -Wshadow -Wpointer-arith -Wformat-security -Wundef ) + if(CMAKE_CXX_COMPILER_ID MATCHES "Clang" AND + NOT (CMAKE_CXX_COMPILER_ID STREQUAL "AppleClang" AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS 11)) + list(APPEND CXX_FLAGS_LIST + -Wundefined-func-template + ) + endif() foreach(FLAG_LANG IN ITEMS C CXX) foreach(FLAG IN LISTS ${FLAG_LANG}_FLAGS_LIST) @@ -533,12 +559,12 @@ install(FILES "${CMake_LICENSE_FILE}" "${CMake_SOURCE_DIR}/CONTRIBUTORS.rst" - DESTINATION ${CMAKE_DOC_DIR}) + DESTINATION ${CMake_INSTALL_DOC_DIR}) # Install script directories. install( DIRECTORY Help Modules Templates - DESTINATION ${CMAKE_DATA_DIR} + DESTINATION ${CMake_INSTALL_DATA_DIR} FILE_PERMISSIONS OWNER_READ OWNER_WRITE GROUP_READ WORLD_READ DIRECTORY_PERMISSIONS OWNER_READ OWNER_EXECUTE OWNER_WRITE GROUP_READ GROUP_EXECUTE
diff --git a/CMakeLogo.gif b/CMakeLogo.gif deleted file mode 100644 index 8426402..0000000 --- a/CMakeLogo.gif +++ /dev/null Binary files differ
diff --git a/CONTRIBUTORS.rst b/CONTRIBUTORS.rst index 76cd4ba..d4d030e 100644 --- a/CONTRIBUTORS.rst +++ b/CONTRIBUTORS.rst
@@ -3,84 +3,85 @@ The following individuals and institutions are among the contributors: -* `Aaron C. Meadows <mailto:cmake@shadowguarddev.com>`_ -* `Adriaan de Groot <mailto:groot@kde.org>`_ -* `Aleksey Avdeev <mailto:solo@altlinux.ru>`_ -* `Alexander Neundorf <mailto:neundorf@kde.org>`_ -* `Alexander Smorkalov <mailto:alexander.smorkalov@itseez.com>`_ -* `Alexey Sokolov <mailto:sokolov@google.com>`_ -* `Alex Merry <mailto:alex.merry@kde.org>`_ -* `Alex Turbov <mailto:i.zaufi@gmail.com>`_ -* `Andreas Pakulat <mailto:apaku@gmx.de>`_ -* `Andreas Schneider <mailto:asn@cryptomilk.org>`_ -* `André Rigland Brodtkorb <mailto:Andre.Brodtkorb@ifi.uio.no>`_ +* `Aaron C. Meadows <mailto:cmake@shadowguarddev.com>`__ +* `Adriaan de Groot <mailto:groot@kde.org>`__ +* `Aleksey Avdeev <mailto:solo@altlinux.ru>`__ +* `Alexander Neundorf <mailto:neundorf@kde.org>`__ +* `Alexander Smorkalov <mailto:alexander.smorkalov@itseez.com>`__ +* `Alexey Sokolov <mailto:sokolov@google.com>`__ +* `Alex Merry <mailto:alex.merry@kde.org>`__ +* `Alex Turbov <mailto:i.zaufi@gmail.com>`__ +* `Andreas Pakulat <mailto:apaku@gmx.de>`__ +* `Andreas Schneider <mailto:asn@cryptomilk.org>`__ +* `André Rigland Brodtkorb <mailto:Andre.Brodtkorb@ifi.uio.no>`__ * Axel Huebl, Helmholtz-Zentrum Dresden - Rossendorf * Benjamin Eikel -* `Bjoern Ricks <mailto:bjoern.ricks@gmail.com>`_ -* `Brad Hards <mailto:bradh@kde.org>`_ +* `Bjoern Ricks <mailto:bjoern.ricks@gmail.com>`__ +* `Brad Hards <mailto:bradh@kde.org>`__ * Christopher Harvey -* `Christoph Grüninger <mailto:foss@grueninger.de>`_ -* `Clement Creusot <mailto:creusot@cs.york.ac.uk>`_ -* `Daniel Blezek <mailto:blezek@gmail.com>`_ -* `Daniel Pfeifer <mailto:daniel@pfeifer-mail.de>`_ -* `Dawid Wróbel <mailto:me@dawidwrobel.com>`_ -* `Enrico Scholz <mailto:enrico.scholz@informatik.tu-chemnitz.de>`_ -* `Eran Ifrah <mailto:eran.ifrah@gmail.com>`_ +* `Christoph Grüninger <mailto:foss@grueninger.de>`__ +* `Clement Creusot <mailto:creusot@cs.york.ac.uk>`__ +* `Daniel Blezek <mailto:blezek@gmail.com>`__ +* `Daniel Pfeifer <mailto:daniel@pfeifer-mail.de>`__ +* `Dawid Wróbel <mailto:me@dawidwrobel.com>`__ +* `Enrico Scholz <mailto:enrico.scholz@informatik.tu-chemnitz.de>`__ +* `Eran Ifrah <mailto:eran.ifrah@gmail.com>`__ * Esben Mose Hansen, Ange Optimization ApS -* `Geoffrey Viola <mailto:geoffrey.viola@asirobots.com>`_ -* `Google Inc <https://www.google.com/>`_ +* `Geoffrey Viola <mailto:geoffrey.viola@asirobots.com>`__ +* `Georg Brandl <mailto:georg@python.org>`__ +* `Google Inc <https://www.google.com/>`__ * Gregor Jasny -* `Helio Chissini de Castro <mailto:helio@kde.org>`_ -* `Ilya Lavrenov <mailto:ilya.lavrenov@itseez.com>`_ -* `Insight Software Consortium <https://insightsoftwareconsortium.org/>`_ -* `Intel Corporation <https://www.intel.com/>`_ +* `Helio Chissini de Castro <mailto:helio@kde.org>`__ +* `Ilya Lavrenov <mailto:ilya.lavrenov@itseez.com>`__ +* `Insight Software Consortium <https://insightsoftwareconsortium.org/>`__ +* `Intel Corporation <https://www.intel.com/>`__ * Jan Woetzel -* `Jordan Williams <mailto:jordan@jwillikers.com>`_ +* `Jordan Williams <mailto:jordan@jwillikers.com>`__ * Julien Schueller -* `Kelly Thompson <mailto:kgt@lanl.gov>`_ -* `Konstantin Podsvirov <mailto:konstantin@podsvirov.su>`_ -* `Laurent Montel <mailto:montel@kde.org>`_ -* `Mario Bensi <mailto:mbensi@ipsquad.net>`_ -* `Martin Gräßlin <mailto:mgraesslin@kde.org>`_ -* `Mathieu Malaterre <mailto:mathieu.malaterre@gmail.com>`_ +* `Kelly Thompson <mailto:kgt@lanl.gov>`__ +* `Konstantin Podsvirov <mailto:konstantin@podsvirov.su>`__ +* `Laurent Montel <mailto:montel@kde.org>`__ +* `Mario Bensi <mailto:mbensi@ipsquad.net>`__ +* `Martin Gräßlin <mailto:mgraesslin@kde.org>`__ +* `Mathieu Malaterre <mailto:mathieu.malaterre@gmail.com>`__ * Matthaeus G. Chajdas -* `Matthias Kretz <mailto:kretz@kde.org>`_ -* `Matthias Maennich <mailto:matthias@maennich.net>`_ -* `Michael Hirsch, Ph.D. <https://www.scivision.dev/>`_ +* `Matthias Kretz <mailto:kretz@kde.org>`__ +* `Matthias Maennich <mailto:matthias@maennich.net>`__ +* `Michael Hirsch, Ph.D. <https://www.scivision.dev/>`__ * Michael Stürmer * Miguel A. Figueroa-Villanueva -* `Mike Durso <mailto:rbprogrammer@gmail.com>`_ +* `Mike Durso <mailto:rbprogrammer@gmail.com>`__ * Mike Jackson -* `Mike McQuaid <mailto:mike@mikemcquaid.com>`_ -* `Nicolas Bock <mailto:nicolasbock@gmail.com>`_ -* `Nicolas Despres <mailto:nicolas.despres@gmail.com>`_ -* `Nikita Krupen'ko <mailto:krnekit@gmail.com>`_ -* `NVIDIA Corporation <https://www.nvidia.com/>`_ -* `OpenGamma Ltd. <https://opengamma.com/>`_ -* `Patrick Stotko <mailto:stotko@cs.uni-bonn.de>`_ -* `Per Øyvind Karlsen <mailto:peroyvind@mandriva.org>`_ -* `Peter Collingbourne <mailto:peter@pcc.me.uk>`_ -* `Petr Gotthard <mailto:gotthard@honeywell.com>`_ -* `Philip Lowman <mailto:philip@yhbt.com>`_ -* `Philippe Proulx <mailto:pproulx@efficios.com>`_ +* `Mike McQuaid <mailto:mike@mikemcquaid.com>`__ +* `Nicolas Bock <mailto:nicolasbock@gmail.com>`__ +* `Nicolas Despres <mailto:nicolas.despres@gmail.com>`__ +* `Nikita Krupen'ko <mailto:krnekit@gmail.com>`__ +* `NVIDIA Corporation <https://www.nvidia.com/>`__ +* `OpenGamma Ltd. <https://opengamma.com/>`__ +* `Patrick Stotko <mailto:stotko@cs.uni-bonn.de>`__ +* `Per Øyvind Karlsen <mailto:peroyvind@mandriva.org>`__ +* `Peter Collingbourne <mailto:peter@pcc.me.uk>`__ +* `Petr Gotthard <mailto:gotthard@honeywell.com>`__ +* `Philip Lowman <mailto:philip@yhbt.com>`__ +* `Philippe Proulx <mailto:pproulx@efficios.com>`__ * Raffi Enficiaud, Max Planck Society * Raumfeld -* `Roger Leigh <mailto:rleigh@codelibre.net>`_ -* `Rolf Eike Beer <mailto:eike@sf-mail.de>`_ -* `Roman Donchenko <mailto:roman.donchenko@itseez.com>`_ -* `Roman Kharitonov <mailto:roman.kharitonov@itseez.com>`_ +* `Roger Leigh <mailto:rleigh@codelibre.net>`__ +* `Rolf Eike Beer <mailto:eike@sf-mail.de>`__ +* `Roman Donchenko <mailto:roman.donchenko@itseez.com>`__ +* `Roman Kharitonov <mailto:roman.kharitonov@itseez.com>`__ * Ruslan Baratov -* `Sebastian Holtermann <mailto:sebholt@xwmw.org>`_ -* `Stephen Kelly <mailto:steveire@gmail.com>`_ -* `Sylvain Joubert <mailto:joubert.sy@gmail.com>`_ -* `The Qt Company Ltd. <https://www.qt.io/>`_ -* `Thomas Sondergaard <mailto:ts@medical-insight.com>`_ -* `Tobias Hunger <mailto:tobias.hunger@qt.io>`_ -* `Todd Gamblin <mailto:tgamblin@llnl.gov>`_ +* `Sebastian Holtermann <mailto:sebholt@xwmw.org>`__ +* `Stephen Kelly <mailto:steveire@gmail.com>`__ +* `Sylvain Joubert <mailto:joubert.sy@gmail.com>`__ +* `The Qt Company Ltd. <https://www.qt.io/>`__ +* `Thomas Sondergaard <mailto:ts@medical-insight.com>`__ +* `Tobias Hunger <mailto:tobias.hunger@qt.io>`__ +* `Todd Gamblin <mailto:tgamblin@llnl.gov>`__ * Tristan Carel -* `University of Dundee <https://www.dundee.ac.uk/>`_ +* `University of Dundee <https://www.dundee.ac.uk/>`__ * Vadim Zhukov -* `Will Dicharry <mailto:wdicharry@stellarscience.com>`_ +* `Will Dicharry <mailto:wdicharry@stellarscience.com>`__ See version control history for details of individual contributions.
diff --git a/CTestCustom.cmake.in b/CTestCustom.cmake.in index 19695c7..75642c9 100644 --- a/CTestCustom.cmake.in +++ b/CTestCustom.cmake.in
@@ -126,6 +126,9 @@ # Exclude Qt source files from coverage results: "[A-Za-z]./[Qq]t/qt-.+-opensource-src" + + # Exclude coverage results from coverage test directories. + "/Testing/.*Coverage/" ) list(APPEND CTEST_CUSTOM_MEMCHECK_IGNORE
diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index 31565b5..cb18bcc 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst
@@ -3,478 +3,494 @@ Add a custom build rule to the generated build system. -There are two main signatures for ``add_custom_command``. +Synopsis +^^^^^^^^ -.. _`add_custom_command(OUTPUT)`: +.. parsed-literal:: + `Generating Files`_ + add_custom_command(`OUTPUT`_ <output1> [<output2> ...] + COMMAND <command1> [ARGS] [<args1>...] + [...]) + + `Build Events`_ + add_custom_command(`TARGET`_ <target> + PRE_BUILD | PRE_LINK | POST_BUILD + [...]) Generating Files ^^^^^^^^^^^^^^^^ -The first signature is for adding a custom command to produce an output: +.. signature:: + add_custom_command(OUTPUT <output1> [<output2> ...] + COMMAND <command1> [ARGS] [<args1>...] + [...]) -.. code-block:: cmake + Add a custom command to produce an output: - add_custom_command(OUTPUT output1 [output2 ...] - COMMAND command1 [ARGS] [args1...] - [COMMAND command2 [ARGS] [args2...] ...] - [MAIN_DEPENDENCY depend] - [DEPENDS [depends...]] - [BYPRODUCTS [files...]] - [IMPLICIT_DEPENDS <lang1> depend1 - [<lang2> depend2] ...] - [WORKING_DIRECTORY dir] - [COMMENT comment] - [DEPFILE depfile] - [JOB_POOL job_pool] - [JOB_SERVER_AWARE <bool>] - [VERBATIM] [APPEND] [USES_TERMINAL] - [CODEGEN] - [COMMAND_EXPAND_LISTS] - [DEPENDS_EXPLICIT_ONLY]) + .. code-block:: cmake -This defines a command to generate specified ``OUTPUT`` file(s). -A target created in the same directory (``CMakeLists.txt`` file) -that specifies any output of the custom command as a source file -is given a rule to generate the file using the command at build time. + add_custom_command(OUTPUT <output1> [<output2> ...] + COMMAND <command1> [ARGS] [<args1>...] + [COMMAND <command2> [ARGS] [<args2>...]] ... + [MAIN_DEPENDENCY depend] + [DEPENDS <depends>...] + [BYPRODUCTS <files>...] + [IMPLICIT_DEPENDS <lang1> <depend1> + [<lang2> <depend2>] ...] + [WORKING_DIRECTORY <dir>] + [COMMENT <comment>] + [DEPFILE <depfile>] + [JOB_POOL <job_pool>] + [JOB_SERVER_AWARE <bool>] + [VERBATIM] [APPEND] [USES_TERMINAL] + [CODEGEN] + [COMMAND_EXPAND_LISTS] + [DEPENDS_EXPLICIT_ONLY]) -Do not list the output in more than one independent target that -may build in parallel or the instances of the rule may conflict. -Instead, use the :command:`add_custom_target` command to drive the -command and make the other targets depend on that one. See the -`Example: Generating Files for Multiple Targets`_ below. + This defines a command to generate specified ``OUTPUT`` file(s). + A target created in the same directory (``CMakeLists.txt`` file) + that specifies any output of the custom command as a source file + is given a rule to generate the file using the command at build time. -The options are: + Do not list the output in more than one independent target that + may build in parallel or the instances of the rule may conflict. + Instead, use the :command:`add_custom_target` command to drive the + command and make the other targets depend on that one. See the + `Example: Generating Files for Multiple Targets`_ below. -``APPEND`` - Append the ``COMMAND`` and ``DEPENDS`` option values to the custom - command for the first output specified. There must have already - been a previous call to this command with the same output. + The options are: - If the previous call specified the output via a generator expression, - the output specified by the current call must match in at least one - configuration after evaluating generator expressions. In this case, - the appended commands and dependencies apply to all configurations. + ``APPEND`` + Append the ``COMMAND`` and ``DEPENDS`` option values to the custom + command for the first output specified. There must have already + been a previous call to this command with the same output. - The ``COMMENT``, ``MAIN_DEPENDENCY``, and ``WORKING_DIRECTORY`` - options are currently ignored when ``APPEND`` is given, but may be - used in the future. + If the previous call specified the output via a generator expression, + the output specified by the current call must match in at least one + configuration after evaluating generator expressions. In this case, + the appended commands and dependencies apply to all configurations. -``BYPRODUCTS`` - .. versionadded:: 3.2 + The ``COMMENT``, ``MAIN_DEPENDENCY``, and ``WORKING_DIRECTORY`` + options are currently ignored when ``APPEND`` is given, but may be + used in the future. - Specify the files the command is expected to produce but whose - modification time may or may not be newer than the dependencies. - If a byproduct name is a relative path it will be interpreted - relative to the build tree directory corresponding to the - current source directory. - Each byproduct file will be marked with the :prop_sf:`GENERATED` - source file property automatically. + ``BYPRODUCTS`` + .. versionadded:: 3.2 - *See policy* :policy:`CMP0058` *for the motivation behind this feature.* + Specify the files the command is expected to produce but whose + modification time may or may not be newer than the dependencies. + If a byproduct name is a relative path it will be interpreted + relative to the build tree directory corresponding to the + current source directory. + Each byproduct file will be marked with the :prop_sf:`GENERATED` + source file property automatically. - Explicit specification of byproducts is supported by the - :generator:`Ninja` generator to tell the ``ninja`` build tool - how to regenerate byproducts when they are missing. It is - also useful when other build rules (e.g. custom commands) - depend on the byproducts. Ninja requires a build rule for any - generated file on which another rule depends even if there are - order-only dependencies to ensure the byproducts will be - available before their dependents build. + *See policy* :policy:`CMP0058` *for the motivation behind this feature.* - The :ref:`Makefile Generators` will remove ``BYPRODUCTS`` and other - :prop_sf:`GENERATED` files during ``make clean``. + Explicit specification of byproducts is supported by the + :generator:`Ninja` generator to tell the ``ninja`` build tool + how to regenerate byproducts when they are missing. It is + also useful when other build rules (e.g. custom commands) + depend on the byproducts. Ninja requires a build rule for any + generated file on which another rule depends even if there are + order-only dependencies to ensure the byproducts will be + available before their dependents build. - This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`). - All byproducts must be set in the first call to - ``add_custom_command(OUTPUT...)`` for the output files. + The :ref:`Makefile Generators` will remove ``BYPRODUCTS`` and other + :prop_sf:`GENERATED` files during ``make clean``. - .. versionadded:: 3.20 - Arguments to ``BYPRODUCTS`` may use a restricted set of + This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`). + All byproducts must be set in the first call to + ``add_custom_command(OUTPUT...)`` for the output files. + + .. versionadded:: 3.20 + Arguments to ``BYPRODUCTS`` may use a restricted set of + :manual:`generator expressions <cmake-generator-expressions(7)>`. + :ref:`Target-dependent expressions <Target-Dependent Expressions>` + are not permitted. + + .. versionchanged:: 3.28 + In targets using :ref:`file sets`, custom command byproducts are now + considered private unless they are listed in a non-private file set. + See policy :policy:`CMP0154`. + + ``COMMAND`` + Specify the command-line(s) to execute at build time. + At least one ``COMMAND`` would normally be given, but certain patterns + may omit it, such as adding commands in separate calls using ``APPEND``. + + If more than one ``COMMAND`` is specified, they will be executed in order, + but *not* necessarily composed into a stateful shell or batch script. + To run a full script, use the :command:`configure_file` command or the + :command:`file(GENERATE)` command to create it, and then specify + a ``COMMAND`` to launch it. + + The optional ``ARGS`` argument is for backward compatibility and + will be ignored. + + If ``COMMAND`` specifies an executable target name (created by the + :command:`add_executable` command), it will automatically be replaced + by the location of the executable created at build time if either of + the following is true: + + * The target is not being cross-compiled (i.e. the + :variable:`CMAKE_CROSSCOMPILING` variable is not set to true). + * .. versionadded:: 3.6 + The target is being cross-compiled and an emulator is provided (i.e. + its :prop_tgt:`CROSSCOMPILING_EMULATOR` target property is set). + In this case, the contents of :prop_tgt:`CROSSCOMPILING_EMULATOR` will be + prepended to the command before the location of the target executable. + + If neither of the above conditions are met, it is assumed that the + command name is a program to be found on the ``PATH`` at build time. + + Arguments to ``COMMAND`` may use :manual:`generator expressions <cmake-generator-expressions(7)>`. - :ref:`Target-dependent expressions <Target-Dependent Expressions>` - are not permitted. + Use the :genex:`TARGET_FILE` generator expression to refer to the location + of a target later in the command line (i.e. as a command argument rather + than as the command to execute). - .. versionchanged:: 3.28 - In targets using :ref:`file sets`, custom command byproducts are now - considered private unless they are listed in a non-private file set. - See policy :policy:`CMP0154`. + Whenever one of the following target based generator expressions are used as + a command to execute or is mentioned in a command argument, a target-level + dependency will be added automatically so that the mentioned target will be + built before any target using this custom command + (see policy :policy:`CMP0112`). -``COMMAND`` - Specify the command-line(s) to execute at build time. - At least one ``COMMAND`` would normally be given, but certain patterns - may omit it, such as adding commands in separate calls using ``APPEND``. + * ``TARGET_FILE`` + * ``TARGET_LINKER_FILE`` + * ``TARGET_SONAME_FILE`` + * ``TARGET_PDB_FILE`` - If more than one ``COMMAND`` is specified, they will be executed in order, - but *not* necessarily composed into a stateful shell or batch script. - To run a full script, use the :command:`configure_file` command or the - :command:`file(GENERATE)` command to create it, and then specify - a ``COMMAND`` to launch it. + This target-level dependency does NOT add a file-level dependency that would + cause the custom command to re-run whenever the executable is recompiled. + List target names with the ``DEPENDS`` option to add such file-level + dependencies. - The optional ``ARGS`` argument is for backward compatibility and - will be ignored. + ``COMMENT`` + Display the given message before the commands are executed at + build time. This will be ignored if ``APPEND`` is given, although a future + version may use it. - If ``COMMAND`` specifies an executable target name (created by the - :command:`add_executable` command), it will automatically be replaced - by the location of the executable created at build time if either of - the following is true: + .. versionadded:: 3.26 + Arguments to ``COMMENT`` may use + :manual:`generator expressions <cmake-generator-expressions(7)>`. - * The target is not being cross-compiled (i.e. the - :variable:`CMAKE_CROSSCOMPILING` variable is not set to true). - * .. versionadded:: 3.6 - The target is being cross-compiled and an emulator is provided (i.e. - its :prop_tgt:`CROSSCOMPILING_EMULATOR` target property is set). - In this case, the contents of :prop_tgt:`CROSSCOMPILING_EMULATOR` will be - prepended to the command before the location of the target executable. + ``DEPENDS`` + Specify files on which the command depends. Each argument is converted + to a dependency as follows: - If neither of the above conditions are met, it is assumed that the - command name is a program to be found on the ``PATH`` at build time. + 1. If the argument is the name of a target (created by the + :command:`add_custom_target`, :command:`add_executable`, or + :command:`add_library` command) a target-level dependency is + created to make sure the target is built before any target + using this custom command. Additionally, if the target is an + executable or library, a file-level dependency is created to + cause the custom command to re-run whenever the target is + recompiled. - Arguments to ``COMMAND`` may use - :manual:`generator expressions <cmake-generator-expressions(7)>`. - Use the :genex:`TARGET_FILE` generator expression to refer to the location - of a target later in the command line (i.e. as a command argument rather - than as the command to execute). + 2. If the argument is an absolute path, a file-level dependency + is created on that path. - Whenever one of the following target based generator expressions are used as - a command to execute or is mentioned in a command argument, a target-level - dependency will be added automatically so that the mentioned target will be - built before any target using this custom command - (see policy :policy:`CMP0112`). + 3. If the argument is the name of a source file that has been + added to a target or on which a source file property has been set, + a file-level dependency is created on that source file. - * ``TARGET_FILE`` - * ``TARGET_LINKER_FILE`` - * ``TARGET_SONAME_FILE`` - * ``TARGET_PDB_FILE`` + 4. If the argument is a relative path and it exists in the current + source directory, a file-level dependency is created on that + file in the current source directory. - This target-level dependency does NOT add a file-level dependency that would - cause the custom command to re-run whenever the executable is recompiled. - List target names with the ``DEPENDS`` option to add such file-level - dependencies. + 5. Otherwise, a file-level dependency is created on that path relative + to the current binary directory. -``COMMENT`` - Display the given message before the commands are executed at - build time. This will be ignored if ``APPEND`` is given, although a future - version may use it. + If any dependency is an ``OUTPUT`` of another custom command in the same + directory (``CMakeLists.txt`` file), CMake automatically brings the other + custom command into the target in which this command is built. - .. versionadded:: 3.26 - Arguments to ``COMMENT`` may use - :manual:`generator expressions <cmake-generator-expressions(7)>`. + .. versionadded:: 3.16 + A target-level dependency is added if any dependency is listed as + ``BYPRODUCTS`` of a target or any of its build events in the same + directory to ensure the byproducts will be available. -``DEPENDS`` - Specify files on which the command depends. Each argument is converted - to a dependency as follows: + If ``DEPENDS`` is not specified, the command will run whenever + the ``OUTPUT`` is missing; if the command does not actually + create the ``OUTPUT``, the rule will always run. - 1. If the argument is the name of a target (created by the - :command:`add_custom_target`, :command:`add_executable`, or - :command:`add_library` command) a target-level dependency is - created to make sure the target is built before any target - using this custom command. Additionally, if the target is an - executable or library, a file-level dependency is created to - cause the custom command to re-run whenever the target is - recompiled. + .. versionadded:: 3.1 + Arguments to ``DEPENDS`` may use + :manual:`generator expressions <cmake-generator-expressions(7)>`. - 2. If the argument is an absolute path, a file-level dependency - is created on that path. + ``COMMAND_EXPAND_LISTS`` + .. versionadded:: 3.8 - 3. If the argument is the name of a source file that has been - added to a target or on which a source file property has been set, - a file-level dependency is created on that source file. + Lists in ``COMMAND`` arguments will be expanded, including those + created with + :manual:`generator expressions <cmake-generator-expressions(7)>`, + allowing ``COMMAND`` arguments such as + ``${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc`` + to be properly expanded. - 4. If the argument is a relative path and it exists in the current - source directory, a file-level dependency is created on that - file in the current source directory. + This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`). + If the appended commands need this option to be set, it must be set on the + first call to ``add_custom_command(OUTPUT...)`` for the output files. - 5. Otherwise, a file-level dependency is created on that path relative - to the current binary directory. + ``CODEGEN`` + .. versionadded:: 3.31 - If any dependency is an ``OUTPUT`` of another custom command in the same - directory (``CMakeLists.txt`` file), CMake automatically brings the other - custom command into the target in which this command is built. + Adds the custom command to a global ``codegen`` target that can be + used to execute the custom command while avoiding the majority of the + build graph. - .. versionadded:: 3.16 - A target-level dependency is added if any dependency is listed as - ``BYPRODUCTS`` of a target or any of its build events in the same - directory to ensure the byproducts will be available. + This option is supported only by :ref:`Ninja Generators` and + :ref:`Makefile Generators`, and is ignored by other generators. + Furthermore, this option is allowed only if policy :policy:`CMP0171` + is set to ``NEW``. - If ``DEPENDS`` is not specified, the command will run whenever - the ``OUTPUT`` is missing; if the command does not actually - create the ``OUTPUT``, the rule will always run. + This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`). + It can only be set on the first call to ``add_custom_command(OUTPUT...)`` + for the output files. - .. versionadded:: 3.1 - Arguments to ``DEPENDS`` may use - :manual:`generator expressions <cmake-generator-expressions(7)>`. - -``COMMAND_EXPAND_LISTS`` - .. versionadded:: 3.8 - - Lists in ``COMMAND`` arguments will be expanded, including those - created with - :manual:`generator expressions <cmake-generator-expressions(7)>`, - allowing ``COMMAND`` arguments such as - ``${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc`` - to be properly expanded. - - This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`). - If the appended commands need this option to be set, it must be set on the - first call to ``add_custom_command(OUTPUT...)`` for the output files. - -``CODEGEN`` - .. versionadded:: 3.31 - - Adds the custom command to a global ``codegen`` target that can be - used to execute the custom command while avoiding the majority of the - build graph. - - This option is supported only by :ref:`Ninja Generators` and - :ref:`Makefile Generators`, and is ignored by other generators. - Furthermore, this option is allowed only if policy :policy:`CMP0171` - is set to ``NEW``. - - This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`). - It can only be set on the first call to ``add_custom_command(OUTPUT...)`` - for the output files. - -``IMPLICIT_DEPENDS`` - Request scanning of implicit dependencies of an input file. - The language given specifies the programming language whose - corresponding dependency scanner should be used. - Currently only ``C`` and ``CXX`` language scanners are supported. - The language has to be specified for every file in the - ``IMPLICIT_DEPENDS`` list. Dependencies discovered from the - scanning are added to those of the custom command at build time. - Note that the ``IMPLICIT_DEPENDS`` option is currently supported - only for Makefile generators and will be ignored by other generators. - - .. note:: - - This option cannot be specified at the same time as ``DEPFILE`` option. - -``JOB_POOL`` - .. versionadded:: 3.15 - - Specify a :prop_gbl:`pool <JOB_POOLS>` for the :generator:`Ninja` - generator. Incompatible with ``USES_TERMINAL``, which implies - the ``console`` pool. - Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes - an error by ninja at build time. - - This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`). - Job pools can only be specified in the first call to - ``add_custom_command(OUTPUT...)`` for the output files. - -``JOB_SERVER_AWARE`` - .. versionadded:: 3.28 - - Specify that the command is GNU Make job server aware. - - For the :generator:`Unix Makefiles`, :generator:`MSYS Makefiles`, and - :generator:`MinGW Makefiles` generators this will add the ``+`` prefix to the - recipe line. See the `GNU Make Documentation`_ for more information. - - This option is silently ignored by other generators. - - This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`). - Job server awareness can only be specified in the first call to - ``add_custom_command(OUTPUT...)`` for the output files. - -.. _`GNU Make Documentation`: https://www.gnu.org/software/make/manual/html_node/MAKE-Variable.html - -``MAIN_DEPENDENCY`` - Specify the primary input source file to the command. This is - treated just like any value given to the ``DEPENDS`` option - but also suggests to :ref:`Visual Studio Generators` where to hang - the custom command. Each source file may have at most one command - specifying it as its main dependency. A compile command (i.e. for a - library or an executable) counts as an implicit main dependency which - gets silently overwritten by a custom command specification. - - This option is currently ignored if ``APPEND`` is given, but a future - version may use it. - -``OUTPUT`` - Specify the output files the command is expected to produce. - Each output file will be marked with the :prop_sf:`GENERATED` - source file property automatically. - If the output of the custom command is not actually created - as a file on disk it should be marked with the :prop_sf:`SYMBOLIC` - source file property. - - If an output file name is a relative path, its absolute path is - determined by interpreting it relative to: - - 1. the build directory corresponding to the current source directory - (:variable:`CMAKE_CURRENT_BINARY_DIR`), or - - 2. the current source directory (:variable:`CMAKE_CURRENT_SOURCE_DIR`). - - The path in the build directory is preferred unless the path in the - source tree is mentioned as an absolute source file path elsewhere - in the current directory. - - The output file path may not contain ``<`` or ``>`` characters. - - .. versionadded:: 3.20 - Arguments to ``OUTPUT`` may use a restricted set of - :manual:`generator expressions <cmake-generator-expressions(7)>`. - :ref:`Target-dependent expressions <Target-Dependent Expressions>` - are not permitted. - - .. versionchanged:: 3.28 - In targets using :ref:`file sets`, custom command outputs are now - considered private unless they are listed in a non-private file set. - See policy :policy:`CMP0154`. - - .. versionchanged:: 3.30 - The output file path may now use ``#`` characters, except - when using the :generator:`Borland Makefiles` generator. - -``USES_TERMINAL`` - .. versionadded:: 3.2 - - The command will be given direct access to the terminal if possible. - With the :generator:`Ninja` generator, this places the command in - the ``console`` :prop_gbl:`pool <JOB_POOLS>`. - - This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`). - If the appended commands need access to the terminal, it must be set on - the first call to ``add_custom_command(OUTPUT...)`` for the output files. - -``VERBATIM`` - All arguments to the commands will be escaped properly for the - build tool so that the invoked command receives each argument - unchanged. Note that one level of escapes is still used by the - CMake language processor before add_custom_command even sees the - arguments. Use of ``VERBATIM`` is recommended as it enables - correct behavior. When ``VERBATIM`` is not given the behavior - is platform specific because there is no protection of - tool-specific special characters. - - This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`). - If the appended commands need to be treated as ``VERBATIM``, it must be set - on the first call to ``add_custom_command(OUTPUT...)`` for the output files. - -``WORKING_DIRECTORY`` - Execute the command with the given current working directory. - If it is a relative path, it will be interpreted relative to the - build tree directory corresponding to the current source directory. - - This option is currently ignored if ``APPEND`` is given, but a future - version may use it. - - .. versionadded:: 3.13 - Arguments to ``WORKING_DIRECTORY`` may use - :manual:`generator expressions <cmake-generator-expressions(7)>`. - -``DEPFILE`` - .. versionadded:: 3.7 - - Specify a 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. - - The expected format, compatible with what is generated by ``gcc`` with the - option ``-M``, is independent of the generator or platform. - - The formal syntax, as specified using - `BNF <https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form>`_ notation with - the regular extensions, is the following: - - .. raw:: latex - - \begin{small} - - .. productionlist:: depfile - depfile: `rule`* - rule: `targets` (':' (`separator` `dependencies`?)?)? `eol` - targets: `target` (`separator` `target`)* `separator`* - target: `pathname` - dependencies: `dependency` (`separator` `dependency`)* `separator`* - dependency: `pathname` - separator: (`space` | `line_continue`)+ - line_continue: '\' `eol` - space: ' ' | '\t' - pathname: `character`+ - character: `std_character` | `dollar` | `hash` | `whitespace` - std_character: <any character except '$', '#' or ' '> - dollar: '$$' - hash: '\#' - whitespace: '\ ' - eol: '\r'? '\n' - - .. raw:: latex - - \end{small} - - .. note:: - - As part of ``pathname``, any slash and backslash is interpreted as - a directory separator. - - .. 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 support for :ref:`Makefile Generators`. + ``IMPLICIT_DEPENDS`` + Request scanning of implicit dependencies of an input file. + The language given specifies the programming language whose + corresponding dependency scanner should be used. + Currently only ``C`` and ``CXX`` language scanners are supported. + The language has to be specified for every file in the + ``IMPLICIT_DEPENDS`` list. Dependencies discovered from the + scanning are added to those of the custom command at build time. + Note that the ``IMPLICIT_DEPENDS`` option is currently supported + only for Makefile generators and will be ignored by other generators. .. note:: - ``DEPFILE`` cannot be specified at the same time as the - ``IMPLICIT_DEPENDS`` option for :ref:`Makefile Generators`. + This option cannot be specified at the same time as ``DEPFILE`` 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 <cmake-generator-expressions(7)>` was also - added. + ``JOB_POOL`` + .. versionadded:: 3.15 - .. versionadded:: 3.29 - The :ref:`Ninja Generators` will now incorporate the dependencies into its - "deps log" database if the file is not listed in ``OUTPUTS`` or - ``BYPRODUCTS``. + Specify a :prop_gbl:`pool <JOB_POOLS>` for the :generator:`Ninja` + generator. Incompatible with ``USES_TERMINAL``, which implies + the ``console`` pool. + Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes + an error by ninja at build time. - Using ``DEPFILE`` with generators other than those listed above is an error. + This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`). + Job pools can only be specified in the first call to + ``add_custom_command(OUTPUT...)`` for the output files. - 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. + ``JOB_SERVER_AWARE`` + .. versionadded:: 3.28 - This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`). - Depfiles can only be set on the first call to - ``add_custom_command(OUTPUT...)`` for the output files. + Specify that the command is GNU Make job server aware. -``DEPENDS_EXPLICIT_ONLY`` + For the :generator:`Unix Makefiles`, :generator:`MSYS Makefiles`, and + :generator:`MinGW Makefiles` generators this will add the ``+`` prefix to the + recipe line. See the `GNU Make Documentation`_ for more information. - .. versionadded:: 3.27 + This option is silently ignored by other generators. - Indicates that the command's ``DEPENDS`` argument represents all files - required by the command and implicit dependencies are not required. + This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`). + Job server awareness can only be specified in the first call to + ``add_custom_command(OUTPUT...)`` for the output files. - Without this option, if any target uses the output of the custom command, - CMake will consider that target's dependencies as implicit dependencies for - the custom command in case this custom command requires files implicitly - created by those targets. + .. _`GNU Make Documentation`: https://www.gnu.org/software/make/manual/html_node/MAKE-Variable.html - This option can be enabled on all custom commands by setting - :variable:`CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY` to ``ON``. + ``MAIN_DEPENDENCY`` + Specify the primary input source file to the command. This is + treated just like any value given to the ``DEPENDS`` option + but also suggests to :ref:`Visual Studio Generators` where to hang + the custom command. Each source file may have at most one command + specifying it as its main dependency. A compile command (i.e. for a + library or an executable) counts as an implicit main dependency which + gets silently overwritten by a custom command specification. - This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`). - It can only be set on the first call to ``add_custom_command(OUTPUT...)`` - for the output files. + This option is currently ignored if ``APPEND`` is given, but a future + version may use it. - Only the :ref:`Ninja Generators` actually use this information to remove - unnecessary implicit dependencies. + ``OUTPUT`` + Specify the output files the command is expected to produce. + Each output file will be marked with the :prop_sf:`GENERATED` + source file property automatically. + If the output of the custom command is not actually created + as a file on disk it should be marked with the :prop_sf:`SYMBOLIC` + source file property. - See also the :prop_tgt:`OPTIMIZE_DEPENDENCIES` target property, which may - provide another way for reducing the impact of target dependencies in some - scenarios. + If an output file name is a relative path, its absolute path is + determined by interpreting it relative to: + + 1. the build directory corresponding to the current source directory + (:variable:`CMAKE_CURRENT_BINARY_DIR`), or + + 2. the current source directory (:variable:`CMAKE_CURRENT_SOURCE_DIR`). + + The path in the build directory is preferred unless the path in the + source tree is mentioned as an absolute source file path elsewhere + in the current directory. + + The output file path may not contain ``<`` or ``>`` characters. + + .. versionadded:: 3.20 + Arguments to ``OUTPUT`` may use a restricted set of + :manual:`generator expressions <cmake-generator-expressions(7)>`. + :ref:`Target-dependent expressions <Target-Dependent Expressions>` + are not permitted. + + .. versionchanged:: 3.28 + In targets using :ref:`file sets`, custom command outputs are now + considered private unless they are listed in a non-private file set. + See policy :policy:`CMP0154`. + + .. versionchanged:: 3.30 + The output file path may now use ``#`` characters, except + when using the :generator:`Borland Makefiles` generator. + + ``USES_TERMINAL`` + .. versionadded:: 3.2 + + The command will be given direct access to the terminal if possible. + With the :generator:`Ninja` generator, this places the command in + the ``console`` :prop_gbl:`pool <JOB_POOLS>`. + + This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`). + If the appended commands need access to the terminal, it must be set on + the first call to ``add_custom_command(OUTPUT...)`` for the output files. + + ``VERBATIM`` + All arguments to the commands will be escaped properly for the + build tool so that the invoked command receives each argument + unchanged. Note that one level of escapes is still used by the + CMake language processor before add_custom_command even sees the + arguments. Use of ``VERBATIM`` is recommended as it enables + correct behavior. When ``VERBATIM`` is not given the behavior + is platform specific because there is no protection of + tool-specific special characters. + + This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`). + If the appended commands need to be treated as ``VERBATIM``, it must be set + on the first call to ``add_custom_command(OUTPUT...)`` for the output files. + + ``WORKING_DIRECTORY`` + Execute the command with the given current working directory. + If it is a relative path, it will be interpreted relative to the + build tree directory corresponding to the current source directory. + If not specified, set to :variable:`CMAKE_CURRENT_BINARY_DIR`. + + This option is currently ignored if ``APPEND`` is given, but a future + version may use it. + + .. versionadded:: 3.13 + Arguments to ``WORKING_DIRECTORY`` may use + :manual:`generator expressions <cmake-generator-expressions(7)>`. + + ``DEPFILE`` + .. versionadded:: 3.7 + + Specify a 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. + + The expected format, compatible with what is generated by ``gcc`` with the + option ``-M``, is independent of the generator or platform. + + The formal syntax, as specified using + `BNF <https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form>`_ notation with + the regular extensions, is the following: + + .. raw:: latex + + \begin{small} + + .. productionlist:: depfile + depfile: `rule`* + rule: `targets` (':' (`separator` `dependencies`?)?)? `eol` + targets: `target` (`separator` `target`)* `separator`* + target: `pathname` + dependencies: `dependency` (`separator` `dependency`)* `separator`* + dependency: `pathname` + separator: (`space` | `line_continue`)+ + line_continue: '\' `eol` + space: ' ' | '\t' + pathname: `character`+ + character: `std_character` | `dollar` | `hash` | `whitespace` + std_character: <any character except '$', '#' or ' '> + dollar: '$$' + hash: '\#' + whitespace: '\ ' + eol: '\r'? '\n' + + .. raw:: latex + + \end{small} + + .. note:: + + As part of ``pathname``, any slash and backslash is interpreted as + a directory separator. + + .. 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 support for :ref:`Makefile Generators`. + + .. note:: + + ``DEPFILE`` cannot be specified at the same time as the + ``IMPLICIT_DEPENDS`` option for :ref:`Makefile Generators`. + + .. 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 <cmake-generator-expressions(7)>` was also + added. + + .. versionadded:: 3.29 + The :ref:`Ninja Generators` will now incorporate the dependencies into its + "deps log" database if the file is not listed in ``OUTPUTS`` or + ``BYPRODUCTS``. + + 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. + + This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`). + Depfiles can only be set on the first call to + ``add_custom_command(OUTPUT...)`` for the output files. + + ``DEPENDS_EXPLICIT_ONLY`` + + .. versionadded:: 3.27 + + Indicates that the command's ``DEPENDS`` argument represents all files + required by the command and implicit dependencies are not required. + + Without this option, if any target uses the output of the custom command, + CMake will consider that target's dependencies as implicit dependencies for + the custom command in case this custom command requires files implicitly + created by those targets. + + This option can be enabled on all custom commands by setting + :variable:`CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY` to ``ON``. + + This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`). + It can only be set on the first call to ``add_custom_command(OUTPUT...)`` + for the output files. + + Only the :ref:`Ninja Generators` actually use this information to remove + unnecessary implicit dependencies. + + See also the :prop_tgt:`OPTIMIZE_DEPENDENCIES` target property, which may + provide another way for reducing the impact of target dependencies in some + scenarios. Examples: Generating Files ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -577,58 +593,61 @@ ``foo`` and ``bar``, will not build until after target ``generate_table_csv`` is built. -.. _`add_custom_command(TARGET)`: - Build Events ^^^^^^^^^^^^ -The second signature adds a custom command to a target such as a -library or executable. This is useful for performing an operation -before or after building the target. The command becomes part of the -target and will only execute when the target itself is built. If the -target is already built, the command will not execute. - -.. code-block:: cmake - +.. signature:: add_custom_command(TARGET <target> PRE_BUILD | PRE_LINK | POST_BUILD - COMMAND command1 [ARGS] [args1...] - [COMMAND command2 [ARGS] [args2...] ...] - [BYPRODUCTS [files...]] - [WORKING_DIRECTORY dir] - [COMMENT comment] - [VERBATIM] - [COMMAND_EXPAND_LISTS] - [USES_TERMINAL]) + [...]) -This defines a new command that will be associated with building the -specified ``<target>``. The ``<target>`` must be defined in the current -directory; targets defined in other directories may not be specified. + Add a build event to a target such as a + library or executable. This is useful for performing an operation + before or after building the target. The command becomes part of the + target and will only execute when the target itself is built. If the + target is already built, the command will not execute. -When the command will happen is determined by which -of the following is specified: + .. code-block:: cmake -``PRE_BUILD`` - This option has unique behavior for the :ref:`Visual Studio Generators`. - When using one of the Visual Studio generators, the command will run before - any other rules are executed within the target. With all other generators, - this option behaves the same as ``PRE_LINK`` instead. Because of this, - it is recommended to avoid using ``PRE_BUILD`` except when it is known that - a Visual Studio generator is being used. -``PRE_LINK`` - Run after sources have been compiled but before linking the binary - or running the librarian or archiver tool of a static library. - This is not defined for targets created by the - :command:`add_custom_target` command. -``POST_BUILD`` - Run after all other rules within the target have been executed. + add_custom_command(TARGET <target> + PRE_BUILD | PRE_LINK | POST_BUILD + COMMAND <command1> [ARGS] [<args1>...] + [COMMAND <command2> [ARGS] [<args2>...]] ... + [BYPRODUCTS <files>...] + [WORKING_DIRECTORY <dir>] + [COMMENT <comment>] + [VERBATIM] + [COMMAND_EXPAND_LISTS] + [USES_TERMINAL]) -Projects should always specify one of the above three keywords when using -the ``TARGET`` form. See policy :policy:`CMP0175`. + This defines a new command that will be associated with building the + specified ``<target>``. The ``<target>`` must be defined in the current + directory; targets defined in other directories may not be specified. -All other keywords shown in the signature above have the same meaning as they -do for the :command:`add_custom_command(OUTPUT)` form of the command. -At least one ``COMMAND`` must be given, see policy :policy:`CMP0175`. + When the command will happen is determined by which + of the following is specified: + + ``PRE_BUILD`` + This option has unique behavior for the :ref:`Visual Studio Generators`. + When using one of the Visual Studio generators, the command will run before + any other rules are executed within the target. With all other generators, + this option behaves the same as ``PRE_LINK`` instead. Because of this, + it is recommended to avoid using ``PRE_BUILD`` except when it is known that + a Visual Studio generator is being used. + ``PRE_LINK`` + Run after sources have been compiled but before linking the binary + or running the librarian or archiver tool of a static library. + This is not defined for targets created by the + :command:`add_custom_target` command. + ``POST_BUILD`` + Run after all other rules within the target have been executed. + + Projects should always specify one of the above three keywords when using + the ``TARGET`` form. See policy :policy:`CMP0175`. + + All other keywords shown in the signature above have the same meaning as they + do for the :command:`add_custom_command(OUTPUT)` form of the command. + At least one ``COMMAND`` must be given, see policy :policy:`CMP0175`. .. note:: Because generator expressions can be used in custom commands,
diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst index b574cba..fd38729 100644 --- a/Help/command/add_custom_target.rst +++ b/Help/command/add_custom_target.rst
@@ -5,17 +5,17 @@ .. code-block:: cmake - add_custom_target(Name [ALL] [command1 [args1...]] - [COMMAND command2 [args2...] ...] - [DEPENDS depend depend depend ...] - [BYPRODUCTS [files...]] - [WORKING_DIRECTORY dir] - [COMMENT comment] - [JOB_POOL job_pool] + add_custom_target(Name [ALL] [command1 [<args1>...]] + [COMMAND command2 [<args2>...]] ... + [DEPENDS <depend>...] + [BYPRODUCTS <file>...] + [WORKING_DIRECTORY <dir>] + [COMMENT <comment>] + [JOB_POOL <job_pool>] [JOB_SERVER_AWARE <bool>] [VERBATIM] [USES_TERMINAL] [COMMAND_EXPAND_LISTS] - [SOURCES src1 [src2...]]) + [SOURCES <source>...]) Adds a target with the given name that executes the given commands. The target has no output file and is *always considered out of date* @@ -191,6 +191,7 @@ Execute the command with the given current working directory. If it is a relative path it will be interpreted relative to the build tree directory corresponding to the current source directory. + If not specified, set to :variable:`CMAKE_CURRENT_BINARY_DIR`. .. versionadded:: 3.13 Arguments to ``WORKING_DIRECTORY`` may use
diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index 50cb0bc..66ce327 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst
@@ -196,6 +196,30 @@ call are ``PRIVATE`` to the interface library and do not appear in its :prop_tgt:`INTERFACE_SOURCES` target property. +.. signature:: + add_library(<name> INTERFACE SYMBOLIC) + :target: INTERFACE-SYMBOLIC + + .. versionadded:: 4.2 + + Add a symbolic :ref:`Interface Library <Interface Libraries>` target. + Symbolic interface libraries are useful for representing optional components + or features in a package. They have no usage requirements, do not compile + sources, and do not produce a library artifact on disk, but they may be + exported and installed. They can also be tested for existence with the + regular :command:`if(TARGET)` subcommand. + + A symbolic interface library may be used as a linkable target to enforce the + presence of optional components in a dependency. For example, if a library + ``libgui`` may or may not provide a feature ``widget``, a consumer package + can link against ``widget`` to express that it requires this component to be + available. This allows :command:`find_package` calls that declare required + components to be validated by linking against the corresponding symbolic + targets. + + A symbolic interface library has the :prop_tgt:`SYMBOLIC` target property + set to true. + .. _`add_library imported libraries`: Imported Libraries
diff --git a/Help/command/add_link_options.rst b/Help/command/add_link_options.rst index 419ee56..462fee9 100644 --- a/Help/command/add_link_options.rst +++ b/Help/command/add_link_options.rst
@@ -42,3 +42,8 @@ * :variable:`CMAKE_<LANG>_FLAGS` and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` add language-wide flags passed to all invocations of the compiler. This includes invocations that drive compiling and those that drive linking. + +* .. versionadded:: 4.3 + :variable:`CMAKE_<LANG>_LINK_FLAGS` and + :variable:`CMAKE_<LANG>_LINK_FLAGS_<CONFIG>` add language-wide flags passed + to all invocations of the compiler which drive linking.
diff --git a/Help/command/add_test.rst b/Help/command/add_test.rst index dbaa4fb..bbfcca2 100644 --- a/Help/command/add_test.rst +++ b/Help/command/add_test.rst
@@ -114,4 +114,5 @@ Unlike the above ``NAME`` signature, target names are not supported in the command-line. Furthermore, tests added with this signature do not support :manual:`generator expressions <cmake-generator-expressions(7)>` -in the command-line or test properties. +in the command-line or test properties, and the :prop_tgt:`TEST_LAUNCHER` +and :prop_tgt:`CROSSCOMPILING_EMULATOR` target properties are not supported.
diff --git a/Help/command/cmake_host_system_information.rst b/Help/command/cmake_host_system_information.rst index 4e72749..35360c2 100644 --- a/Help/command/cmake_host_system_information.rst +++ b/Help/command/cmake_host_system_information.rst
@@ -9,17 +9,18 @@ .. parsed-literal:: `Query host system specific information`_ - cmake_host_system_information(RESULT <variable> QUERY <key> ...) + cmake_host_system_information(RESULT <variable> `QUERY`_ <key> ...) - `Query Windows registry`_ - cmake_host_system_information(RESULT <variable> QUERY WINDOWS_REGISTRY <key> ...) + `Query the Windows registry`_ + cmake_host_system_information(RESULT <variable> `QUERY WINDOWS_REGISTRY`_ <key> ...) Query host system specific information ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. code-block:: cmake - +.. signature:: cmake_host_system_information(RESULT <variable> QUERY <key> ...) + :target: + QUERY Queries system information of the host system on which cmake runs. One or more ``<key>`` can be provided to select the information to be @@ -111,6 +112,16 @@ One if processor has serial number +``HAS_APIC`` + .. versionadded:: 4.3 + + One if processor supports APIC + +``HAS_L1_CACHE`` + .. versionadded:: 4.3 + + One if processor has L1 cache + ``PROCESSOR_SERIAL_NUMBER`` .. versionadded:: 3.10 @@ -126,6 +137,17 @@ Human readable full processor description +``LOCALE_CHARSET`` + .. versionadded:: 4.3 + + The locale's character set, if known, otherwise empty. + + This is the :ref:`encoding <CMake Language Encoding>` expected + in :manual:`cmake-language(7)` files and scripts: + + * On Windows, this is always ``UTF-8``. + * On UNIX and macOS, this is based on the current locale. + ``OS_NAME`` .. versionadded:: 3.10 @@ -161,6 +183,46 @@ environment that sets the ``MSYSTEM`` environment variable, this is its installation prefix. Otherwise, this is the empty string. +``FAMILY_ID`` + .. versionadded:: 4.3 + + The processor family name + +``MODEL_ID`` + .. versionadded:: 4.3 + + The processor model ID + +``MODEL_NAME`` + .. versionadded:: 4.3 + + The processor model name + +``PROCESSOR_APIC_ID`` + .. versionadded:: 4.3 + + The processor APIC ID + +``PROCESSOR_CACHE_SIZE`` + .. versionadded:: 4.3 + + The processor L1 cache size + +``PROCESSOR_CLOCK_FREQUENCY`` + .. versionadded:: 4.3 + + The processor clock frequency + +``VENDOR_ID`` + .. versionadded:: 4.3 + + The processor vendor ID + +``VENDOR_STRING`` + .. versionadded:: 4.3 + + The processor vendor string + ``DISTRIB_INFO`` .. versionadded:: 3.22 @@ -290,20 +352,19 @@ .. _man 5 os-release: https://www.freedesktop.org/software/systemd/man/latest/os-release.html .. _various distribution-specific files: http://linuxmafia.com/faq/Admin/release-files.html -.. _Query Windows registry: - -Query Windows registry -^^^^^^^^^^^^^^^^^^^^^^ +Query the Windows registry +^^^^^^^^^^^^^^^^^^^^^^^^^^ .. versionadded:: 3.24 -.. code-block:: cmake - +.. signature:: cmake_host_system_information(RESULT <variable> QUERY WINDOWS_REGISTRY <key> [VALUE_NAMES|SUBKEYS|VALUE <name>] [VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)] [SEPARATOR <separator>] [ERROR_VARIABLE <result>]) + :target: + QUERY WINDOWS_REGISTRY Performs query operations on local computer registry subkey. Returns a list of subkeys or value names that are located under the specified subkey in the
diff --git a/Help/command/cmake_instrumentation.rst b/Help/command/cmake_instrumentation.rst index 22e77ea..4e2aa43 100644 --- a/Help/command/cmake_instrumentation.rst +++ b/Help/command/cmake_instrumentation.rst
@@ -1,12 +1,7 @@ cmake_instrumentation --------------------- -.. versionadded:: 4.0 - -.. note:: - - This command is only available when experimental support for instrumentation - has been enabled by the ``CMAKE_EXPERIMENTAL_INSTRUMENTATION`` gate. +.. versionadded:: 4.3 Enables interacting with the :manual:`CMake Instrumentation API <cmake-instrumentation(7)>`. @@ -19,8 +14,9 @@ API_VERSION <version> DATA_VERSION <version> [HOOKS <hooks>...] - [QUERIES <queries>...] + [OPTIONS <options>...] [CALLBACK <callback>] + [CUSTOM_CONTENT <name> <type> <content>] ) The ``API_VERSION`` and ``DATA_VERSION`` must always be given. Currently, the @@ -28,7 +24,7 @@ for details of the ``API_VERSION`` and :ref:`cmake-instrumentation Data v1` for details of the ``DATA_VERSION``. -Each of the optional keywords ``HOOKS``, ``QUERIES``, and ``CALLBACK`` +Each of the optional keywords ``HOOKS``, ``OPTIONS``, and ``CALLBACK`` correspond to one of the parameters to the :ref:`cmake-instrumentation v1 Query Files`. The ``CALLBACK`` keyword can be provided multiple times to create multiple callbacks. @@ -36,6 +32,34 @@ ``<build>/.cmake/instrumentation/v1/query/generated`` to enable instrumentation with the provided arguments. +.. _`cmake_instrumentation CUSTOM_CONTENT`: + +Custom CMake Content +^^^^^^^^^^^^^^^^^^^^ + +The ``CUSTOM_CONTENT`` argument specifies certain data from configure time to +include in each :ref:`cmake-instrumentation v1 CMake Content File`. This +may be used to associate instrumentation data with certain information about its +configuration, such as the optimization level or whether it is part of a +coverage build. + +``CUSTOM_CONTENT`` expects ``name``, ``type`` and ``content`` arguments. + +``name`` is a specifier to identify the content being reported. + +``type`` specifies how the content should be interpreted. Supported values are: + * ``STRING`` the content is a string. + * ``BOOL`` the content should be interpreted as a boolean. It will be ``true`` + under the same conditions that ``if()`` would be true for the given value. + * ``LIST`` the content is a CMake ``;`` separated list that should be parsed. + * ``JSON`` the content should be parsed as a JSON string. This can be a + number such as ``1`` or ``5.0``, a quoted string such as ``\"string\"``, + a boolean value ``true``/``false``, or a JSON object such as + ``{ \"key\" : \"value\" }`` that may be constructed using + ``string(JSON ...)`` commands. + +``content`` is the actual content to report. + Example ^^^^^^^ @@ -48,9 +72,12 @@ API_VERSION 1 DATA_VERSION 1 HOOKS postGenerate preCMakeBuild postCMakeBuild - QUERIES staticSystemInformation dynamicSystemInformation + OPTIONS staticSystemInformation dynamicSystemInformation trace CALLBACK ${CMAKE_COMMAND} -P /path/to/handle_data.cmake CALLBACK ${CMAKE_COMMAND} -P /path/to/handle_data_2.cmake + CUSTOM_CONTENT myString STRING string + CUSTOM_CONTENT myList LIST "item1;item2" + CUSTOM_CONTENT myObject JSON "{ \"key\" : \"value\" }" ) .. code-block:: json @@ -60,11 +87,26 @@ "hooks": [ "postGenerate", "preCMakeBuild", "postCMakeBuild" ], - "queries": [ - "staticSystemInformation", "dynamicSystemInformation" + "options": [ + "staticSystemInformation", "dynamicSystemInformation", "trace" ], "callbacks": [ "/path/to/cmake -P /path/to/handle_data.cmake" "/path/to/cmake -P /path/to/handle_data_2.cmake" ] } + +This will also result in the following content included in each +:ref:`cmake-instrumentation v1 CMake Content File`: + +.. code-block:: json + + "custom": { + "myString": "string", + "myList": [ + "item1", "item2" + ], + "myObject": { + "key": "value" + } + }
diff --git a/Help/command/cmake_language.rst b/Help/command/cmake_language.rst index a9c7653..e3a30fa 100644 --- a/Help/command/cmake_language.rst +++ b/Help/command/cmake_language.rst
@@ -16,6 +16,7 @@ cmake_language(`SET_DEPENDENCY_PROVIDER`_ <command> SUPPORTED_METHODS <methods>...) cmake_language(`GET_MESSAGE_LOG_LEVEL`_ <out-var>) cmake_language(`EXIT`_ <exit-code>) + cmake_language(`TRACE`_ <boolean> ...) Introduction ^^^^^^^^^^^^ @@ -534,3 +535,28 @@ shell or platform, and some shells may interpret values above 125 specially. Therefore, it is advisable to only specify an ``<exit-code>`` in the range 0 to 125. + +Trace Control +^^^^^^^^^^^^^ + +.. versionadded:: 4.2 + +.. signature:: + cmake_language(TRACE ON [EXPAND]) + cmake_language(TRACE OFF) + :target: + TRACE + TRACE-OFF + + The TRACE subcommand controls runtime tracing of executed CMake commands and + macros within the current process. When enabled, trace output is written + in the same format as if CMake had been started with the + :option:`cmake --trace` or :option:`cmake --trace-expand` command line options. + + Tracing scopes are nestable. Multiple ``TRACE ON`` calls may be active at the + same time, and each ``TRACE OFF`` deactivates one nesting level. + + If CMake is run with :option:`cmake --trace` or :option:`cmake --trace-expand`, + those options override and force tracing globally, regardless of + ``cmake_language(TRACE OFF)`` calls. In such cases, the command may still + be invoked but has no effect on the trace state.
diff --git a/Help/command/cmake_minimum_required.rst b/Help/command/cmake_minimum_required.rst index 98861f9..1eaba0c 100644 --- a/Help/command/cmake_minimum_required.rst +++ b/Help/command/cmake_minimum_required.rst
@@ -22,8 +22,8 @@ ``<min>`` version and sets the `Policy Version`_. If the running version of CMake is older than 3.12, the extra ``...`` dots will be seen as version component separators, resulting in the -``...<max>`` part being ignored and preserving the pre-3.12 behavior -of basing policies on ``<min>``. +``...<policy_max>`` part being ignored and preserving the pre-3.12 +behavior of basing policies on ``<min>``. This command will set the value of the :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable to ``<min>``. @@ -53,11 +53,12 @@ Policy Version ^^^^^^^^^^^^^^ -``cmake_minimum_required(VERSION <min>[...<max>])`` implicitly invokes +``cmake_minimum_required(VERSION <min>[...<policy_max>])`` implicitly +invokes .. code-block:: cmake - cmake_policy(VERSION <min>[...<max>]) + cmake_policy(VERSION <min>[...<policy_max>]) .. include:: include/POLICY_VERSION.rst
diff --git a/Help/command/cmake_path.rst b/Help/command/cmake_path.rst index 3094ad6..5fb0ef1 100644 --- a/Help/command/cmake_path.rst +++ b/Help/command/cmake_path.rst
@@ -30,14 +30,14 @@ `Normalization`_ `Decomposition`_ - cmake_path(`GET`_ <path-var> :ref:`ROOT_NAME <GET_ROOT_NAME>` <out-var>) - cmake_path(`GET`_ <path-var> :ref:`ROOT_DIRECTORY <GET_ROOT_DIRECTORY>` <out-var>) - cmake_path(`GET`_ <path-var> :ref:`ROOT_PATH <GET_ROOT_PATH>` <out-var>) - cmake_path(`GET`_ <path-var> :ref:`FILENAME <GET_FILENAME>` <out-var>) - cmake_path(`GET`_ <path-var> :ref:`EXTENSION <GET_EXTENSION>` [LAST_ONLY] <out-var>) - cmake_path(`GET`_ <path-var> :ref:`STEM <GET_STEM>` [LAST_ONLY] <out-var>) - cmake_path(`GET`_ <path-var> :ref:`RELATIVE_PART <GET_RELATIVE_PART>` <out-var>) - cmake_path(`GET`_ <path-var> :ref:`PARENT_PATH <GET_PARENT_PATH>` <out-var>) + cmake_path(`GET`_ <path-var> `ROOT_NAME <GET ... ROOT_NAME_>`_ <out-var>) + cmake_path(`GET`_ <path-var> `ROOT_DIRECTORY <GET ... ROOT_DIRECTORY_>`_ <out-var>) + cmake_path(`GET`_ <path-var> `ROOT_PATH <GET ... ROOT_PATH_>`_ <out-var>) + cmake_path(`GET`_ <path-var> `FILENAME <GET ... FILENAME_>`_ <out-var>) + cmake_path(`GET`_ <path-var> `EXTENSION <GET ... EXTENSION_>`_ [LAST_ONLY] <out-var>) + cmake_path(`GET`_ <path-var> `STEM <GET ... STEM_>`_ [LAST_ONLY] <out-var>) + cmake_path(`GET`_ <path-var> `RELATIVE_PART <GET ... RELATIVE_PART_>`_ <out-var>) + cmake_path(`GET`_ <path-var> `PARENT_PATH <GET ... PARENT_PATH_>`_ <out-var>) `Query`_ cmake_path(`HAS_ROOT_NAME`_ <path-var> <out-var>) @@ -51,10 +51,12 @@ cmake_path(`IS_ABSOLUTE`_ <path-var> <out-var>) cmake_path(`IS_RELATIVE`_ <path-var> <out-var>) cmake_path(`IS_PREFIX`_ <path-var> <input> [NORMALIZE] <out-var>) - cmake_path(`COMPARE`_ <input1> <OP> <input2> <out-var>) + + `Comparison`_ + cmake_path(`COMPARE`_ <input1> <op> <input2> <out-var>) `Modification`_ - cmake_path(:ref:`SET <cmake_path-SET>` <path-var> [NORMALIZE] <input>) + cmake_path(`SET`_ <path-var> [NORMALIZE] <input>) cmake_path(`APPEND`_ <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>]) cmake_path(`APPEND_STRING`_ <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>]) cmake_path(`REMOVE_FILENAME`_ <path-var> [OUTPUT_VARIABLE <out-var>]) @@ -69,8 +71,8 @@ `Native Conversion`_ cmake_path(`NATIVE_PATH`_ <path-var> [NORMALIZE] <out-var>) - cmake_path(`CONVERT`_ <input> `TO_CMAKE_PATH_LIST`_ <out-var> [NORMALIZE]) - cmake_path(`CONVERT`_ <input> `TO_NATIVE_PATH_LIST`_ <out-var> [NORMALIZE]) + cmake_path(`CONVERT`_ <input> `TO_CMAKE_PATH_LIST <CONVERT ... TO_CMAKE_PATH_LIST_>`_ <out-var> [NORMALIZE]) + cmake_path(`CONVERT`_ <input> `TO_NATIVE_PATH_LIST <CONVERT ... TO_NATIVE_PATH_LIST_>`_ <out-var> [NORMALIZE]) `Hashing`_ cmake_path(`HASH`_ <path-var> <out-var>) @@ -167,17 +169,17 @@ be empty. A ``relative-part`` refers to the full path with any ``root-path`` removed. +.. _Creating a Path Variable: Creating A Path Variable ^^^^^^^^^^^^^^^^^^^^^^^^ While a path can be created with care using an ordinary :command:`set` -command, it is recommended to use :ref:`cmake_path(SET) <cmake_path-SET>` -instead, as it automatically converts the path to the required form where -required. The :ref:`cmake_path(APPEND) <APPEND>` subcommand may -be another suitable alternative where a path needs to be constructed by -joining fragments. The following example compares the three methods for -constructing the same path: +command, it is recommended to use :command:`cmake_path(SET)` instead, as it +automatically converts the path to the required form where required. The +:command:`cmake_path(APPEND)` subcommand may be another suitable alternative +where a path needs to be constructed by joining fragments. The following +example compares the three methods for constructing the same path: .. code-block:: cmake @@ -192,6 +194,16 @@ keyword. All other sub-commands store the result in a mandatory ``<out-var>`` variable. +.. note:: + + The ``cmake_path`` command can be used directly with variables provided by + CMake representing paths (e.g., :variable:`CMAKE_SOURCE_DIR`). However, since + the command can modify these variables, and many of them have undefined + behavior when modified, they should never be specified as an ``<out-var>``, + and only as the ``<path-var>`` when a separate ``<out-var>`` is specified. + See :manual:`cmake-variables(7)` for the list of CMake variables and + identifiers reserved by CMake. + .. _Normalization: Normalization @@ -224,21 +236,12 @@ ^^^^^^^^^^^^^ .. _GET: -.. _GET_ROOT_NAME: -.. _GET_ROOT_DIRECTORY: -.. _GET_ROOT_PATH: -.. _GET_FILENAME: -.. _GET_EXTENSION: -.. _GET_STEM: -.. _GET_RELATIVE_PART: -.. _GET_PARENT_PATH: The following forms of the ``GET`` subcommand each retrieve a different component or group of components from a path. See `Path Structure And Terminology`_ for the meaning of each path component. -.. code-block:: cmake - +.. signature:: cmake_path(GET <path-var> ROOT_NAME <out-var>) cmake_path(GET <path-var> ROOT_DIRECTORY <out-var>) cmake_path(GET <path-var> ROOT_PATH <out-var>) @@ -247,17 +250,26 @@ cmake_path(GET <path-var> STEM [LAST_ONLY] <out-var>) cmake_path(GET <path-var> RELATIVE_PART <out-var>) cmake_path(GET <path-var> PARENT_PATH <out-var>) + :target: + GET ... ROOT_NAME + GET ... ROOT_DIRECTORY + GET ... ROOT_PATH + GET ... FILENAME + GET ... EXTENSION + GET ... STEM + GET ... RELATIVE_PART + GET ... PARENT_PATH -If a requested component is not present in the path, an empty string will be -stored in ``<out-var>``. For example, only Windows systems have the concept -of a ``root-name``, so when the host machine is non-Windows, the ``ROOT_NAME`` -subcommand will always return an empty string. + If a requested component is not present in the path, an empty string will be + stored in ``<out-var>``. For example, only Windows systems have the concept + of a ``root-name``, so when the host machine is non-Windows, the ``ROOT_NAME`` + subcommand will always return an empty string. -For ``PARENT_PATH``, if the `HAS_RELATIVE_PART`_ subcommand returns false, -the result is a copy of ``<path-var>``. Note that this implies that a root -directory is considered to have a parent, with that parent being itself. -Where `HAS_RELATIVE_PART`_ returns true, the result will essentially be -``<path-var>`` with one less element. + For ``PARENT_PATH``, if the :cref:`HAS_RELATIVE_PART` sub-command returns + false, the result is a copy of ``<path-var>``. Note that this implies that a + root directory is considered to have a parent, with that parent being itself. + Where :cref:`HAS_RELATIVE_PART` returns true, the result will essentially be + ``<path-var>`` with one less element. Root examples """"""""""""" @@ -394,22 +406,12 @@ Query ^^^^^ -Each of the ``GET`` subcommands has a corresponding ``HAS_...`` -subcommand which can be used to discover whether a particular path +Each of the :cref:`GET` subcommands has a corresponding +``HAS_...`` subcommand which can be used to discover whether a particular path component is present. See `Path Structure And Terminology`_ for the meaning of each path component. -.. _HAS_ROOT_NAME: -.. _HAS_ROOT_DIRECTORY: -.. _HAS_ROOT_PATH: -.. _HAS_FILENAME: -.. _HAS_EXTENSION: -.. _HAS_STEM: -.. _HAS_RELATIVE_PART: -.. _HAS_PARENT_PATH: - -.. code-block:: cmake - +.. signature:: cmake_path(HAS_ROOT_NAME <path-var> <out-var>) cmake_path(HAS_ROOT_DIRECTORY <path-var> <out-var>) cmake_path(HAS_ROOT_PATH <path-var> <out-var>) @@ -419,88 +421,85 @@ cmake_path(HAS_RELATIVE_PART <path-var> <out-var>) cmake_path(HAS_PARENT_PATH <path-var> <out-var>) -Each of the above follows the predictable pattern of setting ``<out-var>`` -to true if the path has the associated component, or false otherwise. -Note the following special cases: + Each of the above follows the predictable pattern of setting ``<out-var>`` + to true if the path has the associated component, or false otherwise. + Note the following special cases: -* For ``HAS_ROOT_PATH``, a true result will only be returned if at least one - of ``root-name`` or ``root-directory`` is non-empty. + * For ``HAS_ROOT_PATH``, a true result will only be returned if at least one + of ``root-name`` or ``root-directory`` is non-empty. -* For ``HAS_PARENT_PATH``, the root directory is also considered to have a - parent, which will be itself. The result is true except if the path - consists of just a :ref:`filename <FILENAME_DEF>`. + * For ``HAS_PARENT_PATH``, the root directory is also considered to have a + parent, which will be itself. The result is true except if the path + consists of just a :ref:`filename <FILENAME_DEF>`. -.. _IS_ABSOLUTE: - -.. code-block:: cmake - +.. signature:: cmake_path(IS_ABSOLUTE <path-var> <out-var>) -Sets ``<out-var>`` to true if ``<path-var>`` is absolute. An absolute path -is a path that unambiguously identifies the location of a file without -reference to an additional starting location. On Windows, this means the -path must have both a ``root-name`` and a ``root-directory-separator`` to be -considered absolute. On other platforms, just a ``root-directory-separator`` -is sufficient. Note that this means on Windows, ``IS_ABSOLUTE`` can be -false while ``HAS_ROOT_DIRECTORY`` can be true. + Sets ``<out-var>`` to true if ``<path-var>`` is absolute. An absolute path + is a path that unambiguously identifies the location of a file without + reference to an additional starting location. On Windows, this means the + path must have both a ``root-name`` and a ``root-directory-separator`` to be + considered absolute. On other platforms, just a ``root-directory-separator`` + is sufficient. Note that this means on Windows, ``IS_ABSOLUTE`` can be + false while :cref:`HAS_ROOT_DIRECTORY` can be true. -.. _IS_RELATIVE: - -.. code-block:: cmake - +.. signature:: cmake_path(IS_RELATIVE <path-var> <out-var>) -This will store the opposite of ``IS_ABSOLUTE`` in ``<out-var>``. + This will store the opposite of :cref:`IS_ABSOLUTE` in ``<out-var>``. -.. _IS_PREFIX: - -.. code-block:: cmake - +.. signature:: cmake_path(IS_PREFIX <path-var> <input> [NORMALIZE] <out-var>) -Checks if ``<path-var>`` is the prefix of ``<input>``. + Checks if ``<path-var>`` is the prefix of ``<input>``. -When the ``NORMALIZE`` option is specified, ``<path-var>`` and ``<input>`` -are :ref:`normalized <Normalization>` before the check. + When the ``NORMALIZE`` option is specified, ``<path-var>`` and ``<input>`` + are :ref:`normalized <Normalization>` before the check. -.. code-block:: cmake + .. code-block:: cmake - 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/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 + set(path "/a/b") + cmake_path(IS_PREFIX path "/a/c/../b" NORMALIZE result) # result = true -.. _Path COMPARE: +.. _Path Comparison: + +Comparison +^^^^^^^^^^ + .. _COMPARE: -.. code-block:: cmake - +.. signature:: cmake_path(COMPARE <input1> EQUAL <input2> <out-var>) cmake_path(COMPARE <input1> NOT_EQUAL <input2> <out-var>) + :target: + COMPARE ... EQUAL + COMPARE ... NOT_EQUAL -Compares the lexical representations of two paths provided as string literals. -No normalization is performed on either path, except multiple consecutive -directory separators are effectively collapsed into a single separator. -Equality is determined according to the following pseudo-code logic: + Compares the lexical representations of two paths provided as string literals. + No normalization is performed on either path, except multiple consecutive + directory separators are effectively collapsed into a single separator. + Equality is determined according to the following pseudo-code logic: -:: + :: - if(NOT <input1>.root_name() STREQUAL <input2>.root_name()) - return FALSE + if(NOT <input1>.root_name() STREQUAL <input2>.root_name()) + return FALSE - if(<input1>.has_root_directory() XOR <input2>.has_root_directory()) - return FALSE + if(<input1>.has_root_directory() XOR <input2>.has_root_directory()) + return FALSE - Return FALSE if a relative portion of <input1> is not lexicographically - equal to the relative portion of <input2>. This comparison is performed path - component-wise. If all of the components compare equal, then return TRUE. + Return FALSE if a relative portion of <input1> is not lexicographically + equal to the relative portion of <input2>. This comparison is performed path + component-wise. If all of the components compare equal, then return TRUE. -.. note:: - Unlike most other ``cmake_path()`` subcommands, the ``COMPARE`` subcommand - takes literal strings as input, not the names of variables. + .. note:: + Unlike most other ``cmake_path()`` subcommands, the ``COMPARE`` subcommand + takes literal strings as input, not the names of variables. .. _Path Modification: @@ -508,150 +507,141 @@ Modification ^^^^^^^^^^^^ -.. _cmake_path-SET: - -.. code-block:: cmake - +.. signature:: cmake_path(SET <path-var> [NORMALIZE] <input>) -Assign the ``<input>`` path to ``<path-var>``. If ``<input>`` is a native -path, it is converted into a cmake-style path with forward-slashes -(``/``). On Windows, the long filename marker is taken into account. + Assigns the ``<input>`` path to ``<path-var>``. If ``<input>`` is a native + path, it is converted into a CMake-style path with forward-slashes + (``/``). On Windows, the long filename marker is taken into account. -When the ``NORMALIZE`` option is specified, the path is :ref:`normalized -<Normalization>` after the conversion. + When the ``NORMALIZE`` option is specified, the path is :ref:`normalized + <Normalization>` after the conversion. -For example: + For example: -.. code-block:: cmake + .. code-block:: cmake - set(native_path "c:\\a\\b/..\\c") - cmake_path(SET path "${native_path}") - message("CMake path is \"${path}\"") + set(native_path "c:\\a\\b/..\\c") + cmake_path(SET path "${native_path}") + message("CMake path is \"${path}\"") - cmake_path(SET path NORMALIZE "${native_path}") - message("Normalized CMake path is \"${path}\"") + cmake_path(SET path NORMALIZE "${native_path}") + message("Normalized CMake path is \"${path}\"") -Output:: + Output:: - CMake path is "c:/a/b/../c" - Normalized CMake path is "c:/a/c" + CMake path is "c:/a/b/../c" + Normalized CMake path is "c:/a/c" -.. _APPEND: - -.. code-block:: cmake - +.. signature:: cmake_path(APPEND <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>]) -Append all the ``<input>`` arguments to the ``<path-var>`` using ``/`` as -the ``directory-separator``. Depending on the ``<input>``, the previous -contents of ``<path-var>`` may be discarded. For each ``<input>`` argument, -the following algorithm (pseudo-code) applies: + Appends all the ``<input>`` arguments to the ``<path-var>`` using ``/`` as + the ``directory-separator``. Depending on the ``<input>``, the previous + contents of ``<path-var>`` may be discarded. For each ``<input>`` argument, + the following algorithm (pseudo-code) applies: -:: + :: - # <path> is the contents of <path-var> + # <path> is the contents of <path-var> - if(<input>.is_absolute() OR - (<input>.has_root_name() AND - NOT <input>.root_name() STREQUAL <path>.root_name())) - replace <path> with <input> - return() - endif() + if(<input>.is_absolute() OR + (<input>.has_root_name() AND + NOT <input>.root_name() STREQUAL <path>.root_name())) + replace <path> with <input> + return() + endif() - if(<input>.has_root_directory()) - remove any root-directory and the entire relative path from <path> - elseif(<path>.has_filename() OR - (NOT <path-var>.has_root_directory() OR <path>.is_absolute())) - append directory-separator to <path> - endif() + if(<input>.has_root_directory()) + remove any root-directory and the entire relative path from <path> + elseif(<path>.has_filename() OR + (NOT <path-var>.has_root_directory() OR <path>.is_absolute())) + append directory-separator to <path> + endif() - append <input> omitting any root-name to <path> + append <input> omitting any root-name to <path> -.. _APPEND_STRING: + See :ref:`Creating a Path Variable` for details on the output variable. -.. code-block:: cmake - +.. signature:: cmake_path(APPEND_STRING <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>]) -Append all the ``<input>`` arguments to the ``<path-var>`` without adding any -``directory-separator``. + Appends all the ``<input>`` arguments to the ``<path-var>`` without adding any + ``directory-separator``. -.. _REMOVE_FILENAME: + See :ref:`Creating a Path Variable` for details on the output variable. -.. code-block:: cmake - +.. signature:: cmake_path(REMOVE_FILENAME <path-var> [OUTPUT_VARIABLE <out-var>]) -Removes the :ref:`filename <FILENAME_DEF>` component (as returned by -:ref:`GET ... FILENAME <GET_FILENAME>`) from ``<path-var>``. After removal, -any trailing ``directory-separator`` is left alone, if present. + Removes the :ref:`filename <FILENAME_DEF>` component (as returned by + :cref:`GET ... FILENAME`) from ``<path-var>``. After removal, any trailing + ``directory-separator`` is left alone, if present. -If ``OUTPUT_VARIABLE`` is not given, then after this function returns, -`HAS_FILENAME`_ returns false for ``<path-var>``. + :cref:`HAS_FILENAME` will return false for the result, whether stored in + ``<out-var>`` or ``<path-var>``. -For example: + For example: -.. code-block:: cmake + .. code-block:: cmake - set(path "/a/b") - cmake_path(REMOVE_FILENAME path) - message("First path is \"${path}\"") + set(path "/a/b") + cmake_path(REMOVE_FILENAME path) + message("First path is \"${path}\"") - # filename is now already empty, the following removes nothing - cmake_path(REMOVE_FILENAME path) - message("Second path is \"${path}\"") + # filename is now already empty, the following removes nothing + cmake_path(REMOVE_FILENAME path) + message("Second path is \"${path}\"") -Output:: + Output:: - First path is "/a/" - Second path is "/a/" + First path is "/a/" + Second path is "/a/" -.. _REPLACE_FILENAME: + See :ref:`Creating a Path Variable` for details on the output variable. -.. code-block:: cmake - +.. signature:: cmake_path(REPLACE_FILENAME <path-var> <input> [OUTPUT_VARIABLE <out-var>]) -Replaces the :ref:`filename <FILENAME_DEF>` component from ``<path-var>`` -with ``<input>``. If ``<path-var>`` has no filename component (i.e. -`HAS_FILENAME`_ returns false), the path is unchanged. The operation is -equivalent to the following: + Replaces the :ref:`filename <FILENAME_DEF>` component from ``<path-var>`` + with ``<input>``. If ``<path-var>`` has no filename component (i.e. + :cref:`HAS_FILENAME` returns false), the path is unchanged. The operation is + equivalent to the following: -.. code-block:: cmake + .. code-block:: cmake - cmake_path(HAS_FILENAME path has_filename) - if(has_filename) - cmake_path(REMOVE_FILENAME path) - cmake_path(APPEND path "${input}") - endif() + cmake_path(HAS_FILENAME path has_filename) + if(has_filename) + cmake_path(REMOVE_FILENAME path) + cmake_path(APPEND path "${input}") + endif() -.. _REMOVE_EXTENSION: + See :ref:`Creating a Path Variable` for details on the output variable. -.. code-block:: cmake - +.. signature:: cmake_path(REMOVE_EXTENSION <path-var> [LAST_ONLY] [OUTPUT_VARIABLE <out-var>]) -Removes the :ref:`extension <EXTENSION_DEF>`, if any, from ``<path-var>``. + Removes the :ref:`extension <EXTENSION_DEF>`, if any, from ``<path-var>``. -.. _REPLACE_EXTENSION: + See :ref:`Creating a Path Variable` for details on the output variable. -.. code-block:: cmake - +.. signature:: cmake_path(REPLACE_EXTENSION <path-var> [LAST_ONLY] <input> [OUTPUT_VARIABLE <out-var>]) -Replaces the :ref:`extension <EXTENSION_DEF>` with ``<input>``. Its effect -is equivalent to the following: + Replaces the :ref:`extension <EXTENSION_DEF>` with ``<input>``. Its effect + is equivalent to the following: -.. code-block:: cmake + .. code-block:: cmake - cmake_path(REMOVE_EXTENSION path) - if(NOT input MATCHES "^\\.") - cmake_path(APPEND_STRING path ".") - endif() - cmake_path(APPEND_STRING path "${input}") + cmake_path(REMOVE_EXTENSION path) + if(NOT input MATCHES "^\\.") + cmake_path(APPEND_STRING path ".") + endif() + cmake_path(APPEND_STRING path "${input}") + + See :ref:`Creating a Path Variable` for details on the output variable. .. _Path Generation: @@ -659,50 +649,47 @@ Generation ^^^^^^^^^^ -.. _NORMAL_PATH: - -.. code-block:: cmake - +.. signature:: cmake_path(NORMAL_PATH <path-var> [OUTPUT_VARIABLE <out-var>]) -Normalize ``<path-var>`` according the steps described in :ref:`Normalization`. + Normalizes ``<path-var>`` according the steps described in + :ref:`Normalization`. -.. _cmake_path-RELATIVE_PATH: -.. _RELATIVE_PATH: + See :ref:`Creating a Path Variable` for details on the output variable. -.. code-block:: cmake - +.. signature:: cmake_path(RELATIVE_PATH <path-var> [BASE_DIRECTORY <input>] [OUTPUT_VARIABLE <out-var>]) -Modifies ``<path-var>`` to make it relative to the ``BASE_DIRECTORY`` argument. -If ``BASE_DIRECTORY`` is not specified, the default base directory will be -:variable:`CMAKE_CURRENT_SOURCE_DIR`. + Modifies ``<path-var>`` to make it relative to the ``BASE_DIRECTORY`` argument. + If ``BASE_DIRECTORY`` is not specified, the default base directory will be + :variable:`CMAKE_CURRENT_SOURCE_DIR`. -For reference, the algorithm used to compute the relative path is the same -as that used by C++ -`std::filesystem::path::lexically_relative -<https://en.cppreference.com/w/cpp/filesystem/path/lexically_normal>`_. + For reference, the algorithm used to compute the relative path is the same + as that used by C++ + `std::filesystem::path::lexically_relative + <https://en.cppreference.com/w/cpp/filesystem/path/lexically_normal>`_. -.. _ABSOLUTE_PATH: + See :ref:`Creating a Path Variable` for details on the output variable. -.. code-block:: cmake - +.. signature:: cmake_path(ABSOLUTE_PATH <path-var> [BASE_DIRECTORY <input>] [NORMALIZE] [OUTPUT_VARIABLE <out-var>]) -If ``<path-var>`` is a relative path (`IS_RELATIVE`_ is true), it is evaluated -relative to the given base directory specified by ``BASE_DIRECTORY`` option. -If ``BASE_DIRECTORY`` is not specified, the default base directory will be -:variable:`CMAKE_CURRENT_SOURCE_DIR`. + If ``<path-var>`` is a relative path (:cref:`IS_RELATIVE` is true), it is + evaluated relative to the given base directory specified by ``BASE_DIRECTORY`` + option. If ``BASE_DIRECTORY`` is not specified, the default base directory + will be :variable:`CMAKE_CURRENT_SOURCE_DIR`. -When the ``NORMALIZE`` option is specified, the path is :ref:`normalized -<Normalization>` after the path computation. + When the ``NORMALIZE`` option is specified, the path is :ref:`normalized + <Normalization>` after the path computation. -Because ``cmake_path()`` does not access the filesystem, symbolic links are -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. + Because ``cmake_path()`` does not access the filesystem, symbolic links are + 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. + + See :ref:`Creating a Path Variable` for details on the output variable. Native Conversion ^^^^^^^^^^^^^^^^^ @@ -710,89 +697,88 @@ For commands in this section, *native* refers to the host platform, not the target platform when cross-compiling. -.. _cmake_path-NATIVE_PATH: -.. _NATIVE_PATH: - -.. code-block:: cmake - +.. signature:: cmake_path(NATIVE_PATH <path-var> [NORMALIZE] <out-var>) -Converts a cmake-style ``<path-var>`` into a native path with -platform-specific slashes (``\`` on Windows hosts and ``/`` elsewhere). + Converts a CMake-style ``<path-var>`` into a native path with + platform-specific slashes (``\`` on Windows hosts and ``/`` elsewhere). -When the ``NORMALIZE`` option is specified, the path is :ref:`normalized -<Normalization>` before the conversion. + When the ``NORMALIZE`` option is specified, the path is :ref:`normalized + <Normalization>` before the conversion. + + See :ref:`Creating a Path Variable` for details on the output variable. .. _CONVERT: -.. _cmake_path-TO_CMAKE_PATH_LIST: -.. _TO_CMAKE_PATH_LIST: -.. code-block:: cmake - +.. signature:: cmake_path(CONVERT <input> TO_CMAKE_PATH_LIST <out-var> [NORMALIZE]) + :target: + CONVERT ... TO_CMAKE_PATH_LIST -Converts a native ``<input>`` path into a cmake-style path with forward -slashes (``/``). On Windows hosts, the long filename marker is taken into -account. The input can be a single path or a system search path like -``$ENV{PATH}``. A search path will be converted to a cmake-style list -separated by ``;`` characters (on non-Windows platforms, this essentially -means ``:`` separators are replaced with ``;``). The result of the -conversion is stored in the ``<out-var>`` variable. + Converts a native ``<input>`` path into a CMake-style path with forward + slashes (``/``). -When the ``NORMALIZE`` option is specified, the path is :ref:`normalized -<Normalization>` before the conversion. + On Windows hosts, the long filename marker is taken into + account. The input can be a single path or a system search path like + ``$ENV{PATH}``. A search path will be converted to a + :ref:`semicolon-separated list <CMake Language Lists>` (on non-Windows + platforms, this essentially means ``:`` separators are replaced with ``;``). -.. note:: - Unlike most other ``cmake_path()`` subcommands, the ``CONVERT`` subcommand - takes a literal string as input, not the name of a variable. + When the ``NORMALIZE`` option is specified, the path is :ref:`normalized + <Normalization>` before the conversion. -.. _cmake_path-TO_NATIVE_PATH_LIST: -.. _TO_NATIVE_PATH_LIST: + See :ref:`Creating a Path Variable` for details on the output variable. -.. code-block:: cmake + .. note:: + Unlike most other ``cmake_path()`` subcommands, the ``CONVERT`` subcommand + takes a literal string as input, not the name of a variable. +.. signature:: cmake_path(CONVERT <input> TO_NATIVE_PATH_LIST <out-var> [NORMALIZE]) + :target: + CONVERT ... TO_NATIVE_PATH_LIST -Converts a cmake-style ``<input>`` path into a native path with -platform-specific slashes (``\`` on Windows hosts and ``/`` elsewhere). -The input can be a single path or a cmake-style list. A list will be -converted into a native search path (``;``-separated on Windows, -``:``-separated on other platforms). The result of the conversion is -stored in the ``<out-var>`` variable. + Converts a CMake-style ``<input>`` path into a native path with + platform-specific slashes (``\`` on Windows hosts and ``/`` elsewhere). -When the ``NORMALIZE`` option is specified, the path is :ref:`normalized -<Normalization>` before the conversion. + The input can be a single path or a :ref:`semicolon-separated list + <CMake Language Lists>`. A list will be converted into a native search path + (``;``-separated on Windows, ``:``-separated on other platforms). -.. note:: - Unlike most other ``cmake_path()`` subcommands, the ``CONVERT`` subcommand - takes a literal string as input, not the name of a variable. + When the ``NORMALIZE`` option is specified, the path is :ref:`normalized + <Normalization>` before the conversion. -For example: + See :ref:`Creating a Path Variable` for details on the output variable. -.. code-block:: cmake + .. note:: + Unlike most other ``cmake_path()`` subcommands, the ``CONVERT`` subcommand + takes a literal string as input, not the name of a variable. - set(paths "/a/b/c" "/x/y/z") - cmake_path(CONVERT "${paths}" TO_NATIVE_PATH_LIST native_paths) - message("Native path list is \"${native_paths}\"") + For example: -Output on Windows:: + .. code-block:: cmake - Native path list is "\a\b\c;\x\y\z" + set(paths "/a/b/c" "/x/y/z") + cmake_path(CONVERT "${paths}" TO_NATIVE_PATH_LIST native_paths) + message("Native path list is \"${native_paths}\"") -Output on all other platforms:: + Output on Windows:: - Native path list is "/a/b/c:/x/y/z" + Native path list is "\a\b\c;\x\y\z" + + Output on all other platforms:: + + Native path list is "/a/b/c:/x/y/z" Hashing ^^^^^^^ -.. _HASH: +.. signature:: + cmake_path(HASH <path-var> <out-var>) -.. code-block:: cmake + Computes a hash value of ``<path-var>`` such that for two paths ``p1`` and + ``p2`` that compare equal (:cref:`COMPARE ... EQUAL`), the hash value of + ``p1`` is equal to the hash value of ``p2``. The path is always + :ref:`normalized <Normalization>` before the hash is computed. - cmake_path(HASH <path-var> <out-var>) - -Compute a hash value of ``<path-var>`` such that for two paths ``p1`` and -``p2`` that compare equal (:ref:`COMPARE ... EQUAL <COMPARE>`), the hash -value of ``p1`` is equal to the hash value of ``p2``. The path is always -:ref:`normalized <Normalization>` before the hash is computed. + See :ref:`Creating a Path Variable` for details on the output variable.
diff --git a/Help/command/cmake_policy.rst b/Help/command/cmake_policy.rst index bbec8e6..5be074c 100644 --- a/Help/command/cmake_policy.rst +++ b/Help/command/cmake_policy.rst
@@ -24,20 +24,21 @@ behavior. While setting policies individually is supported, we encourage projects to set policies based on CMake versions: -.. signature:: cmake_policy(VERSION <min>[...<max>]) +.. signature:: cmake_policy(VERSION <min>[...<policy_max>]) :target: VERSION .. versionadded:: 3.12 - The optional ``<max>`` version. + The optional ``<policy_max>`` version. -``<min>`` and the optional ``<max>`` are each CMake versions of the form -``major.minor[.patch[.tweak]]``, and the ``...`` is literal. The ``<min>`` -version must be at least ``2.4`` and at most the running version of CMake. -The ``<max>`` version, if specified, must be at least the ``<min>`` version -but may exceed the running version of CMake. If the running version of -CMake is older than 3.12, the extra ``...`` dots will be seen as version -component separators, resulting in the ``...<max>`` part being ignored and -preserving the pre-3.12 behavior of basing policies on ``<min>``. +``<min>`` and the optional ``<policy_max>`` are each CMake versions of the +form ``major.minor[.patch[.tweak]]``, and the ``...`` is literal. +The ``<min>`` version must be at least ``2.4`` and at most the running +version of CMake. The ``<policy_max>`` version, if specified, must be at +least the ``<min>`` version but may exceed the running version of CMake. +If the running version of CMake is older than 3.12, the extra ``...`` +dots will be seen as version component separators, resulting in the +``...<policy_max>`` part being ignored and preserving the pre-3.12 behavior +of basing policies on ``<min>``. .. include:: include/POLICY_VERSION.rst
diff --git a/Help/command/configure_file.rst b/Help/command/configure_file.rst index 546f9ce..956400c 100644 --- a/Help/command/configure_file.rst +++ b/Help/command/configure_file.rst
@@ -193,7 +193,7 @@ .. code-block:: cmake - target_include_directories(<target> [SYSTEM] <INTERFACE|PUBLIC|PRIVATE> "${CMAKE_CURRENT_BINARY_DIR}") + target_include_directories(<target> [SYSTEM] {INTERFACE|PUBLIC|PRIVATE} "${CMAKE_CURRENT_BINARY_DIR}") so that sources may include the header as ``#include <foo.h>``.
diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst index c1862df..8cf7134 100644 --- a/Help/command/ctest_test.rst +++ b/Help/command/ctest_test.rst
@@ -213,7 +213,7 @@ <https://github.com/Kitware/CDash/blob/master/docs/test_measurements.md>`_ for more information on the types of test measurements that CDash recognizes. -.. versionadded: 3.22 +.. versionadded:: 3.22 CTest can parse custom measurements from tags named ``<CTestMeasurement>`` or ``<CTestMeasurementFile>``. The older names ``<DartMeasurement>`` and ``<DartMeasurementFile>`` are still supported.
diff --git a/Help/command/define_property.rst b/Help/command/define_property.rst index 3dccca9..8952f1f 100644 --- a/Help/command/define_property.rst +++ b/Help/command/define_property.rst
@@ -8,8 +8,8 @@ define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE | TEST | VARIABLE | CACHED_VARIABLE> PROPERTY <name> [INHERITED] - [BRIEF_DOCS <brief-doc> [docs...]] - [FULL_DOCS <full-doc> [docs...]] + [BRIEF_DOCS <brief-doc> [<docs>...]] + [FULL_DOCS <full-doc> [<docs>...]] [INITIALIZE_FROM_VARIABLE <variable>]) Defines one property in a scope for use with the :command:`set_property` and
diff --git a/Help/command/enable_language.rst b/Help/command/enable_language.rst index 1bffef6..7584e35 100644 --- a/Help/command/enable_language.rst +++ b/Help/command/enable_language.rst
@@ -15,7 +15,8 @@ The following restrictions apply to where ``enable_language()`` may be called: -* It must be called in file scope, not in a function call. +* It must be called in file scope, not in a :command:`function` call + nor inside a :command:`block()`. * It must not be called before the first call to :command:`project`. See policy :policy:`CMP0165`. * It must be called in the highest directory common to all targets
diff --git a/Help/command/enable_testing.rst b/Help/command/enable_testing.rst index 7bae5c0..4a45aac 100644 --- a/Help/command/enable_testing.rst +++ b/Help/command/enable_testing.rst
@@ -1,20 +1,51 @@ enable_testing -------------- -Enable testing for current directory and below. +Enables testing for the current directory and below: .. code-block:: cmake enable_testing() -Enables testing for this directory and below. - -This command should be in the top-level source directory because +This command should be invoked in the top-level source directory because :manual:`ctest(1)` expects to find a test file in the top-level build directory. -This command is automatically invoked when the :module:`CTest` +This command is also automatically invoked when the :module:`CTest` module is included, except if the :variable:`BUILD_TESTING` option is turned off. -See also the :command:`add_test` command. +The following restrictions apply to where ``enable_testing()`` may be called: + +* It must be called in file scope, not in a :command:`function` call nor inside + a :command:`block`. + +Examples +^^^^^^^^ + +In the following example, this command is conditionally called depending on how +the project is used. For instance, when the Example project is added via the +:module:`FetchContent` module as a subdirectory of a parent project that defines +its own tests, testing for the Example project is disabled. + +.. code-block:: cmake + :caption: ``CMakeLists.txt`` + + project(Example) + + option(Example_ENABLE_TESTING "Enable testing" ${PROJECT_IS_TOP_LEVEL}) + + if(Example_ENABLE_TESTING) + enable_testing() + endif() + + # ... + + if(Example_ENABLE_TESTING) + add_test(...) + endif() + +See Also +^^^^^^^^ + +* The :command:`add_test` command.
diff --git a/Help/command/execute_process.rst b/Help/command/execute_process.rst index a2f9036..37f2b42 100644 --- a/Help/command/execute_process.rst +++ b/Help/command/execute_process.rst
@@ -75,7 +75,8 @@ ``WORKING_DIRECTORY`` The named directory will be set as the current working directory of - the child processes. + the child processes. If not given, the child processes' working directory is + unspecified. ``TIMEOUT`` After the specified number of seconds (fractions allowed), all unfinished
diff --git a/Help/command/export.rst b/Help/command/export.rst index 6668e97..0ecdbd9 100644 --- a/Help/command/export.rst +++ b/Help/command/export.rst
@@ -16,6 +16,8 @@ export(`EXPORT`_ <export-name> [...]) export(`PACKAGE`_ <PackageName>) export(`SETUP`_ <export-name> [...]) + export(`PACKAGE_INFO`_ <package-name> [...]) + export(`SBOM`_ <sbom-name> [...]) Exporting Targets ^^^^^^^^^^^^^^^^^ @@ -130,9 +132,12 @@ Exporting Targets to the |CPS| """""""""""""""""""""""""""""" +.. signature:: + export(PACKAGE_INFO <package-name> [...]) + .. code-block:: cmake - export(EXPORT <export-name> PACKAGE_INFO <package-name> + export(PACKAGE_INFO <package-name> EXPORT <export-name> [PROJECT <project-name>|NO_PROJECT_METADATA] [APPENDIX <appendix-name>] [LOWER_CASE_FILE] @@ -141,13 +146,13 @@ [VERSION_SCHEMA <string>]] [DEFAULT_TARGETS <target>...] [DEFAULT_CONFIGURATIONS <config>...] - [DESCRIPTION <project-description-string>] - [HOMEPAGE_URL <url-string>]) + [LICENSE <license-string>] + [DEFAULT_LICENSE <license-string>] + [DESCRIPTION <description-string>] + [HOMEPAGE_URL <url-string>] + [CXX_MODULES_DIRECTORY <directory>]) -.. versionadded:: 4.1 -.. note:: - - Experimental. Gated by ``CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_INFO``. +.. versionadded:: 4.3 Creates a file in the |CPS|_ that may be included by outside projects to import targets named by ``<target>...`` from the current project's build tree. See @@ -160,6 +165,34 @@ See :command:`install(PACKAGE_INFO)` for a description of the other options. +Exporting Software Bill of Materials (SBOM) Documents +""""""""""""""""""""""""""""""""""""""""""""""""""""" + +.. signature:: + export(SBOM <sbom-name> [...]) + +.. code-block:: cmake + + export(SBOM <sbom-name> EXPORT <export-name> + [FORMAT <string>] + [PROJECT <project-name>|NO_PROJECT_METADATA] + [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]] + [LICENSE <license-string>] + [DESCRIPTION <description-string>] + [HOMEPAGE_URL <url-string>] + [PACKAGE_URL <url-string>]) + +.. versionadded:: 4.3 +.. note:: + + Experimental. Gated by ``CMAKE_EXPERIMENTAL_GENERATE_SBOM``. + +Generates a software bill of materials (SBOM) document describing the targets +in the export ``<export-name>`` and their dependencies in the build tree + +See :command:`install(SBOM)` for details about the supported SBOM formats and a +description of the other options. + Exporting Packages ^^^^^^^^^^^^^^^^^^
diff --git a/Help/command/file.rst b/Help/command/file.rst index 8a9f6e9..5bc7b3c 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst
@@ -6,17 +6,17 @@ This command is dedicated to file and path manipulation requiring access to the filesystem. -For other path manipulation, handling only syntactic aspects, have a look at +For other path manipulation, handling only syntactic aspects, see the :command:`cmake_path` command. .. note:: - The sub-commands `RELATIVE_PATH`_, `TO_CMAKE_PATH`_ and `TO_NATIVE_PATH`_ has - been superseded, respectively, by sub-commands - :ref:`RELATIVE_PATH <cmake_path-RELATIVE_PATH>`, - :ref:`CONVERT ... TO_CMAKE_PATH_LIST <cmake_path-TO_CMAKE_PATH_LIST>` and - :ref:`CONVERT ... TO_NATIVE_PATH_LIST <cmake_path-TO_NATIVE_PATH_LIST>` of - :command:`cmake_path` command. + The sub-commands :command:`file(RELATIVE_PATH)`, + :command:`file(TO_CMAKE_PATH)`, and :command:`file(TO_NATIVE_PATH)` + have been superseded, respectively, by the sub-commands + :command:`cmake_path(RELATIVE_PATH)`, + :command:`cmake_path(CONVERT ... TO_CMAKE_PATH_LIST)`, and + :command:`cmake_path(CONVERT ... TO_NATIVE_PATH_LIST)`. Synopsis ^^^^^^^^ @@ -606,7 +606,7 @@ Create a link ``<linkname>`` that points to ``<original>``. It will be a hard link by default, but providing the ``SYMBOLIC`` option - results in a symbolic link instead. Hard links require that ``original`` + results in a symbolic link instead. Hard links require that ``<original>`` exists and is a file, not a directory. If ``<linkname>`` already exists, it will be overwritten. @@ -620,6 +620,13 @@ ``<original>`` and ``<linkname>`` being on different drives or mount points, which would make them unable to support a hard link. + .. versionchanged:: 4.3 + + If the source is a directory, CMake versions prior to 4.3 will create the + destination directory if it does not exist, but not copy any files. + With CMake 4.3 and above, the contents of the source directory will be + copied recursively to the destination. See policy :policy:`CMP0205`. + .. signature:: file(CHMOD <files>... <directories>... [PERMISSIONS <permissions>...] @@ -707,12 +714,12 @@ file(TO_CMAKE_PATH "<path>" <variable>) file(TO_NATIVE_PATH "<path>" <variable>) - The ``TO_CMAKE_PATH`` mode converts a native ``<path>`` into a cmake-style + The ``TO_CMAKE_PATH`` mode converts a native ``<path>`` into a CMake-style path with forward-slashes (``/``). The input can be a single path or a system search path like ``$ENV{PATH}``. A search path will be converted - to a cmake-style list separated by ``;`` characters. + to a :ref:`semicolon-separated list <CMake Language Lists>`. - The ``TO_NATIVE_PATH`` mode converts a cmake-style ``<path>`` into a native + The ``TO_NATIVE_PATH`` mode converts a CMake-style ``<path>`` into a native path with platform-specific slashes (``\`` on Windows hosts and ``/`` elsewhere). @@ -913,6 +920,7 @@ [COMPRESSION <compression> [COMPRESSION_LEVEL <compression-level>]] [MTIME <mtime>] + [THREADS <number>] [WORKING_DIRECTORY <dir>] [VERBOSE]) :target: ARCHIVE_CREATE @@ -931,17 +939,55 @@ ``7zip``, ``gnutar``, ``pax``, ``paxr``, ``raw`` and ``zip``. If ``FORMAT`` is not given, the default format is ``paxr``. + The default compression method depends on the format: + + * ``7zip`` uses ``LZMA`` compression + * ``zip`` uses ``Deflate`` compression + * others uses no compression by default + ``COMPRESSION <compression>`` Some archive formats allow the type of compression to be specified. The ``7zip`` and ``zip`` archive formats already imply a specific type of compression. The other formats use no compression by default, but can be directed to do so with the ``COMPRESSION`` option. Valid values for - ``<compression>`` are ``None``, ``BZip2``, ``GZip``, ``XZ``, and ``Zstd``. + ``<compression>`` are: + + * ``None`` + * ``BZip2`` + * ``Deflate`` + + .. versionadded:: 4.3 + + This is an alias for ``GZip``. + + * ``GZip`` + * ``LZMA`` + + .. versionadded:: 4.3 + + * ``LZMA2`` + + .. versionadded:: 4.3 + + This is an alias for ``XZ``. + + * ``PPMd`` + + .. versionadded:: 4.3 + + This compression method is only supported by the ``7zip`` archive format. + + * ``XZ`` + * ``Zstd`` .. note:: With ``FORMAT`` set to ``raw``, only one file will be compressed with the compression type specified by ``COMPRESSION``. + .. versionadded:: 4.3 + + The ``7zip`` and ``zip`` formats support changing the default compression. + ``COMPRESSION_LEVEL <compression-level>`` .. versionadded:: 3.19 @@ -950,13 +996,31 @@ default being 0. The ``COMPRESSION`` option must be present when ``COMPRESSION_LEVEL`` is given. + The value ``0`` is used to specify the default compression level. + It is selected automatically by the archive library backend and + not directly set by CMake itself. The default compression level + may vary between archive formats, platforms, etc. + .. versionadded:: 3.26 The ``<compression-level>`` of the ``Zstd`` algorithm can be set between 0-19. + .. versionadded:: 4.3 + The ``<compression-level>`` can be specified for the ``7zip`` and ``zip`` + formats too. The ``Zstd`` algorithm compression level can be set + between 0-19, except for ``zip`` format. + ``MTIME <mtime>`` Specify the modification time recorded in tarball entries. + ``THREADS <number>`` + .. versionadded:: 4.3 + + Use the ``<number>`` threads to operate on the archive. + + The number of available cores on the machine will be used if set to ``0``. + Note that not all compression modes support threading in all environments. + ``WORKING_DIRECTORY <dir>`` .. versionadded:: 3.31 @@ -1007,6 +1071,10 @@ ``VERBOSE`` Enable verbose output from the extraction operation. + .. versionchanged:: 4.3 + Archive entries containing path traversal sequences (``..``), or + absolute paths, are rejected for security. + .. note:: The working directory for this subcommand is the ``DESTINATION`` directory (provided or computed) except when ``LIST_ONLY`` is specified. Therefore, @@ -1120,6 +1188,8 @@ The following arguments specify filters for including or excluding libraries to be resolved. See below for a full description of how they work. + Directory separators in file paths may be matched using forward + slashes unless policy :policy:`CMP0207` is not set to ``NEW``. ``PRE_INCLUDE_REGEXES <regexes>...`` List of pre-include regexes through which to filter the names of
diff --git a/Help/command/find_file.rst b/Help/command/find_file.rst index 9695ddf..13aae97 100644 --- a/Help/command/find_file.rst +++ b/Help/command/find_file.rst
@@ -2,9 +2,9 @@ --------- .. |FIND_XXX| replace:: find_file -.. |NAMES| replace:: NAMES name1 [name2 ...] +.. |NAMES| replace:: NAMES <name>... .. |SEARCH_XXX| replace:: full path to a file -.. |SEARCH_XXX_DESC| replace:: full path to named file +.. |SEARCH_XXX_DESC| replace:: full path to a named file .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include`` .. |entry_XXX_SUBDIR| replace:: ``<entry>/include``
diff --git a/Help/command/find_library.rst b/Help/command/find_library.rst index b150818..54f7a8e 100644 --- a/Help/command/find_library.rst +++ b/Help/command/find_library.rst
@@ -2,7 +2,7 @@ ------------ .. |FIND_XXX| replace:: find_library -.. |NAMES| replace:: NAMES name1 [name2 ...] [NAMES_PER_DIR] +.. |NAMES| replace:: NAMES <name>... [NAMES_PER_DIR] .. |SEARCH_XXX| replace:: library .. |SEARCH_XXX_DESC| replace:: library .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/lib``
diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 4dc9696..d757263 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst
@@ -75,23 +75,25 @@ .. _`Config mode`: **Config mode** - In this mode, CMake searches for a file called - ``<lowercasePackageName>-config.cmake`` or ``<PackageName>Config.cmake``. - It will also look for ``<lowercasePackageName>-config-version.cmake`` or + In this mode, CMake searches for a file matching any of: + + * ``<PackageName>.cps`` + * ``<lowercasePackageName>.cps`` + * ``<lowercasePackageName>-config.cmake`` + * ``<PackageName>Config.cmake`` + + If one of the latter two is found, CMake will also look respectively, for + ``<lowercasePackageName>-config-version.cmake`` or ``<PackageName>ConfigVersion.cmake`` if version details were specified (see :ref:`version selection` for an explanation of how these separate - version files are used). + version files are used). The latter two options are CMake-script package + descriptions. The first two are |CPS|_ (CPS) package descriptions, which + are more portable and include version information in the 'base' file. Aside + from any explicitly noted exceptions, any references to "config files", + "config mode", "package configuration files", and so forth refer equally to + both CPS and CMake-script files. .. note:: - If the experimental ``CMAKE_EXPERIMENTAL_FIND_CPS_PACKAGES`` is enabled, - files named ``<PackageName>.cps`` and ``<lowercasePackageName>.cps`` are - also considered. These files provide package information according to the - |CPS|_ (CPS), which is more portable than CMake script. Aside from any - explicitly noted exceptions, any references to "config files", "config - mode", "package configuration files", and so forth refer equally to both - CPS and CMake-script files. This functionality is a work in progress, and - some features may be missing. - Search is implemented in a manner that will tend to prefer |CPS| files over CMake-script config files in most cases. Specifying ``CONFIGS`` suppresses consideration of CPS files. @@ -135,13 +137,14 @@ .. code-block:: cmake - find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE] - [REQUIRED|OPTIONAL] [[COMPONENTS] [components...]] - [OPTIONAL_COMPONENTS components...] - [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)] + find_package(<PackageName> [<version>] [EXACT] [QUIET] [MODULE] + [REQUIRED|OPTIONAL] [[COMPONENTS] <component>...] + [OPTIONAL_COMPONENTS <component>...] + [REGISTRY_VIEW {64|32|64_32|32_64|HOST|TARGET|BOTH}] [GLOBAL] [NO_POLICY_SCOPE] - [BYPASS_PROVIDER]) + [BYPASS_PROVIDER] + [UNWIND_INCLUDE]) The basic signature is supported by both Module and Config modes. The ``MODULE`` keyword implies that only Module mode can be used to find @@ -208,7 +211,7 @@ .. _FIND_PACKAGE_VERSION_FORMAT: -The ``[version]`` argument requests a version with which the package found +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: @@ -233,10 +236,10 @@ The ``EXACT`` option requests that the version be matched exactly. This option is incompatible with the specification of a version range. -If no ``[version]`` and/or component list is given to a recursive invocation +If no ``<version>`` and/or component list is given to a recursive invocation inside a find-module, the corresponding arguments are forwarded automatically from the outer call (including the ``EXACT`` flag for -``[version]``). +``<version>``). See the :command:`cmake_policy` command documentation for discussion of the ``NO_POLICY_SCOPE`` option. @@ -249,6 +252,21 @@ itself. Future versions of CMake may detect attempts to use this keyword from places other than a dependency provider and halt with a fatal error. +.. versionadded:: 4.2 + The ``UNWIND_INCLUDE`` keyword is only allowed when ``find_package()`` is + being called within a parent call to ``find_package()``. When a call to + ``find_package(UNWIND_INCLUDE)`` fails to find the desired package, it begins + an "unwind" state. In this state further calls to ``find_package()`` and + :command:`include()` are forbidden, and all parent :command:`include()` + commands will immediately invoke :command:`return()` when their scope is + reached. This "unwinding" will continue until the parent ``find_package()`` + is returned to. + + ``UNWIND_INCLUDE`` is only intended to be used by calls to ``find_package()`` + generated by :command:`install(EXPORT_PACKAGE_DEPENDENCIES)`, but may be + useful to those who wish to manually manage their dependencies in a similar + manner. + .. _`full signature`: Full Signature @@ -257,18 +275,18 @@ .. code-block:: cmake find_package(<PackageName> [version] [EXACT] [QUIET] - [REQUIRED|OPTIONAL] [[COMPONENTS] [components...]] - [OPTIONAL_COMPONENTS components...] + [REQUIRED|OPTIONAL] [[COMPONENTS] <component>...] + [OPTIONAL_COMPONENTS <component>...] [CONFIG|NO_MODULE] [GLOBAL] [NO_POLICY_SCOPE] [BYPASS_PROVIDER] - [NAMES name1 [name2 ...]] - [CONFIGS config1 [config2 ...]] - [HINTS path1 [path2 ...]] - [PATHS path1 [path2 ...]] - [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)] - [PATH_SUFFIXES suffix1 [suffix2 ...]] + [NAMES <name>...] + [CONFIGS <config>...] + [HINTS <path>...] + [PATHS <path>...] + [REGISTRY_VIEW {64|32|64_32|32_64|HOST|TARGET|BOTH}] + [PATH_SUFFIXES <suffix>...] [NO_DEFAULT_PATH] [NO_PACKAGE_ROOT_PATH] [NO_CMAKE_PATH] @@ -296,8 +314,14 @@ also considered when determining whether to redirect the call to a package provided by :module:`FetchContent`. -The command searches for a file called ``<PackageName>Config.cmake`` or -``<lowercasePackageName>-config.cmake`` for each name specified. +The command searches for a file whose name, for each package name specified, +matches any of: + +* ``<PackageName>Config.cmake`` +* ``<lowercasePackageName>-config.cmake`` +* ``<PackageName>.cps`` +* ``<lowercasePackageName>.cps`` + A replacement set of possible configuration file names may be given using the ``CONFIGS`` option. The :ref:`search procedure` is specified below. Once found, any :ref:`version constraint <version selection>` is checked, @@ -308,9 +332,8 @@ .. note:: - If the experimental ``CMAKE_EXPERIMENTAL_FIND_CPS_PACKAGES`` is enabled, - files named ``<PackageName>.cps`` and ``<lowercasePackageName>.cps`` are - also considered, unless ``CONFIGS`` is given. + Because CPS files are not permitted to have names that do *not* match the + package name, specifying ``CONFIGS`` will suppress searcing for CPS files. All configuration files which have been considered by CMake while searching for the package with an appropriate version are stored in the @@ -322,7 +345,9 @@ specified. If ``REQUIRED`` is specified and the package is not found, a fatal error is generated and the configure step stops executing. If ``<PackageName>_DIR`` has been set to a directory not containing a -configuration file, CMake will ignore it and search from scratch. +configuration file, or if the requested version is not compatible +with the package found in that directory (see :ref:`version selection`), +CMake will ignore it and search from scratch. Package maintainers providing package configuration files are encouraged to name and install them such that the :ref:`search procedure` outlined below @@ -378,7 +403,7 @@ .. [#p1] .. versionadded:: 3.25 -.. [#p2] .. versionadded:: 4.0 +.. [#p2] .. versionadded:: 4.3 On systems supporting macOS :prop_tgt:`FRAMEWORK` and :prop_tgt:`BUNDLE`, the following directories are searched for Frameworks or Application Bundles @@ -398,7 +423,7 @@ ``<prefix>/<name>.app/Contents/Resources/CMake/`` A =============================================================== ========== -.. [#p3] .. versionadded:: 4.0 +.. [#p3] .. versionadded:: 4.3 When searching the above paths, ``find_package`` will only look for ``.cps`` files in search paths which contain ``/cps/``, and will only look for @@ -581,12 +606,12 @@ configuration file found is used, even if a newer version of the package resides later in the list of search paths. -For search paths which contain glob expressions (``*``), the order in which -directories matching the glob are searched is unspecified unless the -:variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` variable is set. This variable, -along with the :variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION` variable, -determines the order in which CMake considers glob matches. For example, if -the file system contains the package configuration files +For search paths which contain glob expressions (``*``), directories matching +the glob are searched in natural, descending order by default. This behavior +can be overridden by setting variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` +and :variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION` accordingly. Those variables +determine the order in which CMake considers glob matches. For example, if the +file system contains the package configuration files :: @@ -594,21 +619,21 @@ <prefix>/example-1.10/example-config.cmake <prefix>/share/example-2.0/example-config.cmake -it is unspecified (when the aforementioned variables are unset) whether -``find_package(example)`` will find ``example-1.2`` or ``example-1.10`` -(assuming that both are viable), but ``find_package`` will *not* find -``example-2.0``, because one of the other two will be found first. +then ``find_package(example)`` will (when the aforementioned variables are +unset) pick ``example-1.10`` (assuming both ``example-1.2`` and ``example-1.10`` +are viable). Note however that ``find_package`` will *not* find ``example-2.0``, +because one of the other two will be found first. To control the order in which ``find_package`` searches directories that match a glob expression, use :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and :variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`. -For instance, to cause the above example to select ``example-1.10``, +For instance, to cause the above example to select ``example-1.2``, one can set .. code-block:: cmake set(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL) - set(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC) + set(CMAKE_FIND_PACKAGE_SORT_DIRECTION ASC) before calling ``find_package``. @@ -624,6 +649,15 @@ and ``<prefix>/<name>.framework/Versions/*/Resources/CMake``. In previous versions of CMake, this order was unspecified. +.. versionchanged:: 4.2 + When encountering multiple viable matches, ``find_package`` now picks the + one with the most recent version by default. In previous versions of CMake, + the result was unspecified. Accordingly, the default of + :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` has changed from ``NONE`` to + ``NATURAL`` and :variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION` + now defaults to ``DEC`` (descending) instead of ``ASC`` (ascending). + + .. include:: include/FIND_XXX_ROOT.rst .. include:: include/FIND_XXX_ORDER.rst @@ -656,7 +690,7 @@ regardless of whether the :ref:`full <full signature>` or :ref:`basic <basic signature>` signature was given. -When the ``[version]`` argument is given, Config mode will only find a +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 <FIND_PACKAGE_VERSION_FORMAT>`). If the ``EXACT`` option is given, only a version of the package claiming an exact @@ -953,21 +987,12 @@ In Module mode the loaded find module is responsible to honor the request detailed by these variables; see the find module for details. In Config mode ``find_package`` handles ``REQUIRED``, ``QUIET``, and -``[version]`` options automatically but leaves it to the package +``<version>`` options automatically but leaves it to the package configuration file to handle components in a way that makes sense for the package. The package configuration file may set ``<PackageName>_FOUND`` to false to tell ``find_package`` that component requirements are not satisfied. -.. _CPS: https://cps-org.github.io/cps/ -.. |CPS| replace:: Common Package Specification - -.. _cps-compat_version: https://cps-org.github.io/cps/schema.html#compat-version -.. |cps-compat_version| replace:: ``compat_version`` - -.. _cps-version_schema: https://cps-org.github.io/cps/schema.html#version-schema -.. |cps-version_schema| replace:: ``version_schema`` - CPS Transitive Requirements ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1001,3 +1026,12 @@ targets. Those targets must be named ``<PackageName>::<ComponentName>``, in conformance with CPS convention, or the check will consider the package not found. + +.. _CPS: https://cps-org.github.io/cps/ +.. |CPS| replace:: Common Package Specification + +.. _cps-compat_version: https://cps-org.github.io/cps/schema.html#compat-version +.. |cps-compat_version| replace:: ``compat_version`` + +.. _cps-version_schema: https://cps-org.github.io/cps/schema.html#version-schema +.. |cps-version_schema| replace:: ``version_schema``
diff --git a/Help/command/find_path.rst b/Help/command/find_path.rst index ab44e32..7ac9024 100644 --- a/Help/command/find_path.rst +++ b/Help/command/find_path.rst
@@ -2,7 +2,7 @@ --------- .. |FIND_XXX| replace:: find_path -.. |NAMES| replace:: NAMES name1 [name2 ...] +.. |NAMES| replace:: NAMES <name>... .. |SEARCH_XXX| replace:: file in a directory .. |SEARCH_XXX_DESC| replace:: directory containing the named file .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include``
diff --git a/Help/command/find_program.rst b/Help/command/find_program.rst index bde5289..e314f9e 100644 --- a/Help/command/find_program.rst +++ b/Help/command/find_program.rst
@@ -2,7 +2,7 @@ ------------ .. |FIND_XXX| replace:: find_program -.. |NAMES| replace:: NAMES name1 [name2 ...] [NAMES_PER_DIR] +.. |NAMES| replace:: NAMES <name>... [NAMES_PER_DIR] .. |SEARCH_XXX| replace:: program .. |SEARCH_XXX_DESC| replace:: program .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/[s]bin``
diff --git a/Help/command/foreach.rst b/Help/command/foreach.rst index 52ce7f4..5984117 100644 --- a/Help/command/foreach.rst +++ b/Help/command/foreach.rst
@@ -58,7 +58,8 @@ The ``<items>`` following the ``ITEMS`` keyword are processed as in the first variant of the ``foreach`` command. The forms ``LISTS A`` and ``ITEMS ${A}`` are -equivalent. +equivalent. If no ``<lists>`` or ``<items>`` are given, the body +of the loop will never be executed (i.e., it is processed as empty). The following example shows how the ``LISTS`` option is processed: @@ -97,13 +98,18 @@ command iterates over each list simultaneously setting the iteration variables as follows: -- if the only ``loop_var`` given, then it sets a series of +- if a single ``loop_var`` is given, then it sets a series of ``loop_var_N`` variables to the current item from the corresponding list; -- if multiple variable names passed, their count should match - the lists variables count; -- if any of the lists are shorter, the corresponding iteration - variable is not defined for the current iteration. +- if multiple variable names are passed, it sets each variable to the + current item from the corresponding list. The number of iteration + variables must match the number of list variables. + +If no ``<lists>`` are given, the body of the loop will never be executed +(i.e., it is processed as empty). + +The following example shows how the ``ZIP_LISTS`` option is +processed: .. noqa: spellcheck off
diff --git a/Help/command/get_filename_component.rst b/Help/command/get_filename_component.rst index 87ed6bc..2bdad98 100644 --- a/Help/command/get_filename_component.rst +++ b/Help/command/get_filename_component.rst
@@ -10,9 +10,8 @@ .. versionchanged:: 3.24 The undocumented feature offering the capability to query the ``Windows`` - registry is superseded by - :ref:`cmake_host_system_information(QUERY WINDOWS_REGISTRY)<Query Windows registry>` - command. + registry is superseded by the + :command:`cmake_host_system_information(QUERY WINDOWS_REGISTRY)` command. .. code-block:: cmake
diff --git a/Help/command/get_property.rst b/Help/command/get_property.rst index 202bfd9..5ce9e83 100644 --- a/Help/command/get_property.rst +++ b/Help/command/get_property.rst
@@ -6,16 +6,17 @@ .. code-block:: cmake get_property(<variable> - <GLOBAL | - DIRECTORY [<dir>] | - TARGET <target> | + <GLOBAL | + DIRECTORY [<dir>] | + TARGET <target> | + FILE_SET <file_set> TARGET <target> | SOURCE <source> [DIRECTORY <dir> | TARGET_DIRECTORY <target>] | - INSTALL <file> | + INSTALL <file> | TEST <test> - [DIRECTORY <dir>] | - CACHE <entry> | - VARIABLE > + [DIRECTORY <dir>] | + CACHE <entry> | + VARIABLE> PROPERTY <name> [SET | DEFINED | BRIEF_DOCS | FULL_DOCS]) @@ -42,6 +43,16 @@ Scope must name one existing target. See also the :command:`get_target_property` command. +``FILE_SET`` + .. versionadded:: 4.3 + + Scope must name one existing file set. + + The following option is required: + + ``TARGET <target>`` + The target to which the file set is attached. + ``SOURCE`` Scope must name one source file. By default, the source file's property will be read from the current source directory's scope.
diff --git a/Help/command/if.rst b/Help/command/if.rst index 4fed570..c12ec12 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst
@@ -264,7 +264,7 @@ True if the given string or variable's value matches the given regular expression. See :ref:`Regex Specification` for regex format. - .. versionadded:: 3.9 + .. versionadded:: 2.6 ``()`` groups are captured in :variable:`CMAKE_MATCH_<n>` variables. .. signature:: if(<variable|string> LESS <variable|string>) @@ -415,7 +415,7 @@ ... endif() - See :ref:`cmake_path(COMPARE) <Path COMPARE>` for more details. + See :ref:`cmake_path(COMPARE) <Path Comparison>` for more details. Variable Expansion ^^^^^^^^^^^^^^^^^^
diff --git a/Help/command/include/DEPRECATED_POLICY_VERSIONS.rst b/Help/command/include/DEPRECATED_POLICY_VERSIONS.rst index 1b9f0d4..dd4a104 100644 --- a/Help/command/include/DEPRECATED_POLICY_VERSIONS.rst +++ b/Help/command/include/DEPRECATED_POLICY_VERSIONS.rst
@@ -3,7 +3,7 @@ Compatibility with versions of CMake older than 3.5 is removed. Calls to :command:`cmake_minimum_required(VERSION)` or :command:`cmake_policy(VERSION)` that do not specify at least - 3.5 as their policy version (optionally via ``...<max>``) + 3.5 as their policy version (optionally via ``...<policy_max>``) will produce an error in CMake 4.0 and above. .. versionchanged:: 3.31 @@ -11,7 +11,7 @@ Compatibility with versions of CMake older than 3.10 is deprecated. Calls to :command:`cmake_minimum_required(VERSION)` or :command:`cmake_policy(VERSION)` that do not specify at least - 3.10 as their policy version (optionally via ``...<max>``) + 3.10 as their policy version (optionally via ``...<policy_max>``) will produce a deprecation warning in CMake 3.31 and above. .. versionchanged:: 3.27 @@ -19,7 +19,7 @@ Compatibility with versions of CMake older than 3.5 is deprecated. Calls to :command:`cmake_minimum_required(VERSION)` or :command:`cmake_policy(VERSION)` that do not specify at least - 3.5 as their policy version (optionally via ``...<max>``) + 3.5 as their policy version (optionally via ``...<policy_max>``) will produce a deprecation warning in CMake 3.27 and above. .. versionchanged:: 3.19 @@ -27,5 +27,5 @@ Compatibility with versions of CMake older than 2.8.12 is deprecated. Calls to :command:`cmake_minimum_required(VERSION)` or :command:`cmake_policy(VERSION)` that do not specify at least - 2.8.12 as their policy version (optionally via ``...<max>``) + 2.8.12 as their policy version (optionally via ``...<policy_max>``) will produce a deprecation warning in CMake 3.19 and above.
diff --git a/Help/command/include/FIND_XXX.rst b/Help/command/include/FIND_XXX.rst index 9d063ad..ce3ed64 100644 --- a/Help/command/include/FIND_XXX.rst +++ b/Help/command/include/FIND_XXX.rst
@@ -2,7 +2,7 @@ .. parsed-literal:: - |FIND_XXX| (<VAR> name1 [path1 path2 ...]) + |FIND_XXX| (<VAR> <name> [<path>...]) The general signature is: @@ -10,12 +10,12 @@ |FIND_XXX| ( <VAR> - name | |NAMES| - [HINTS [path | ENV var]...] - [PATHS [path | ENV var]...] - [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)] - [PATH_SUFFIXES suffix1 [suffix2 ...]] - [VALIDATOR function] + {<name> | |NAMES|} + [HINTS {<path> | ENV <var>}...] + [PATHS {<path> | ENV <var>}...] + [REGISTRY_VIEW {64|32|64_32|32_64|HOST|TARGET|BOTH}] + [PATH_SUFFIXES <suffix>...] + [VALIDATOR <function>] [DOC "cache documentation string"] [NO_CACHE] [REQUIRED|OPTIONAL] @@ -32,11 +32,27 @@ ) This command is used to find a |SEARCH_XXX_DESC|. -A cache entry, or a normal variable if ``NO_CACHE`` is specified, -named by ``<VAR>`` is created to store the result of this command. -If the |SEARCH_XXX| is found the result is stored in the variable -and the search will not be repeated unless the variable is cleared. -If nothing is found, the result will be ``<VAR>-NOTFOUND``. + +Prior to searching, |FIND_XXX| checks if variable ``<VAR>`` is defined. If +the variable is not defined, the search will be performed. If the variable is +defined and its value is ``NOTFOUND``, or ends in ``-NOTFOUND``, the search +will be performed. If the variable contains any other value the search is not +performed. + + .. note:: + ``VAR`` is considered defined if it is available in the current scope. See + the :ref:`cmake-language(7) variables <CMake Language Variables>` + documentation for details on scopes, and the interaction of normal + variables and cache entries. + +The results of the search will be stored in a cache entry named ``<VAR>``. +Future calls to |FIND_XXX| will inspect this cache entry when specifying the +same ``<VAR>``. This optimization ensures successful searches will not be +repeated unless the cache entry is :command:`unset`. + +If the |SEARCH_XXX| is found the recorded value in cache entry ``<VAR>`` will +be the result of the search. If nothing is found, the recorded value will be +``<VAR>-NOTFOUND``. Options include: @@ -103,8 +119,9 @@ .. note:: - If the variable is already set before the call (as a normal or cache - variable) then the search will not occur. + |FIND_XXX| will still check for ``<VAR>`` as usual, checking first for a + variable, and then a cache entry. If either indicate a previous successful + search, the search will not be performed. .. warning::
diff --git a/Help/command/include/FIND_XXX_ORDER.rst b/Help/command/include/FIND_XXX_ORDER.rst index bac2419..6dfae54 100644 --- a/Help/command/include/FIND_XXX_ORDER.rst +++ b/Help/command/include/FIND_XXX_ORDER.rst
@@ -5,7 +5,7 @@ .. parsed-literal:: - |FIND_XXX| (|FIND_ARGS_XXX| PATHS paths... NO_DEFAULT_PATH) + |FIND_XXX| (|FIND_ARGS_XXX| PATHS <paths>... NO_DEFAULT_PATH) |FIND_XXX| (|FIND_ARGS_XXX|) Once one of the calls succeeds the result variable will be set
diff --git a/Help/command/include/POLICY_VERSION.rst b/Help/command/include/POLICY_VERSION.rst index 424849d..c180dce 100644 --- a/Help/command/include/POLICY_VERSION.rst +++ b/Help/command/include/POLICY_VERSION.rst
@@ -1,7 +1,7 @@ This specifies that the current CMake code is written for the given range of -CMake versions, ``<min>[...<max>]``. It sets the "policy version" to: +CMake versions, ``<min>[...<policy_max>]``. It sets the "policy version" to: -* the range's ``<max>`` version, if specified, or to +* the range's ``<policy_max>`` version, if specified, or to * the ``<min>`` version, or to * the value of the :variable:`CMAKE_POLICY_VERSION_MINIMUM` variable if it is higher than the other two versions. @@ -9,8 +9,12 @@ The policy version effectively requests behavior preferred as of a given CMake version and tells newer CMake versions to warn about their new policies. All policies known to the running version of CMake and introduced -in that version or earlier will be set to use ``NEW`` behavior. +in the policy version or earlier will be set to use ``NEW`` behavior. All policies introduced in later versions will be unset (unless the :variable:`CMAKE_POLICY_DEFAULT_CMP<NNNN>` variable sets a default). -This effectively requests behavior preferred as of a given CMake -version and tells newer CMake versions to warn about their new policies. + +.. note:: + + ``...<policy_max>`` does *not* signify that later CMake versions are + forbidden. It merely specifies the highest CMake version for which + the project or module has been actively updated and maintained.
diff --git a/Help/command/install.rst b/Help/command/install.rst index 033c5c6..f7fcb94 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst
@@ -21,6 +21,7 @@ install(`EXPORT`_ <export-name> [...]) install(`PACKAGE_INFO`_ <package-name> [...]) install(`RUNTIME_DEPENDENCY_SET`_ <set-name> [...]) + install(`SBOM`_ <sbom-name> [...]) Introduction ^^^^^^^^^^^^ @@ -497,7 +498,7 @@ [CONFIGURATIONS <config>...] [COMPONENT <component>] [OPTIONAL] [EXCLUDE_FROM_ALL] - ] [...] + ]... ) The ``IMPORTED_RUNTIME_ARTIFACTS`` form specifies rules for installing the @@ -550,7 +551,7 @@ programs that are not targets, such as shell scripts. Use the ``TARGETS`` form to install targets built within the project. - The list of ``files...`` given to ``FILES`` or ``PROGRAMS`` may use + The list of files given to ``FILES`` or ``PROGRAMS`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. However, if any item begins in a generator expression it must evaluate @@ -791,7 +792,7 @@ Exclude the matched file or directory from installation. ``PERMISSIONS <permission>...`` - Ovrerride the permissions setting for the matched file or directory. + Override the permissions setting for the matched file or directory. For example, the code @@ -818,7 +819,7 @@ install([[SCRIPT <file>] [CODE <code>]] [ALL_COMPONENTS | COMPONENT <component>] - [EXCLUDE_FROM_ALL] [...]) + [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 @@ -974,12 +975,9 @@ .. signature:: install(PACKAGE_INFO <package-name> [...]) - .. versionadded:: 3.31 - .. note:: + .. versionadded:: 4.3 - Experimental. Gated by ``CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_INFO``. - - Installs a |CPS|_ file exporting targets for dependent projects: + Installs a |CPS|_ ("CPS") file exporting targets for dependent projects: .. code-block:: cmake @@ -993,10 +991,13 @@ [VERSION_SCHEMA <string>]] [DEFAULT_TARGETS <target>...] [DEFAULT_CONFIGURATIONS <config>...] - [DESCRIPTION <project-description-string>] + [LICENSE <license-string>] + [DEFAULT_LICENSE <license-string>] + [DESCRIPTION <description-string>] [HOMEPAGE_URL <url-string>] [PERMISSIONS <permission>...] [CONFIGURATIONS <config>...] + [CXX_MODULES_DIRECTORY <directory>] [COMPONENT <component>] [EXCLUDE_FROM_ALL]) @@ -1051,7 +1052,25 @@ configurations exists. If not specified, CMake will fall back to the package's available configurations in an unspecified order. - ``DESCRIPTION <project-description-string>`` + ``LICENSE <license-string>`` + .. versionadded:: 4.2 + + A |SPDX|_ (SPDX) `License Expression`_ that describes the license(s) of the + project as a whole, including documentation, resources, or other materials + distributed with the project, in addition to software artifacts. See the + SPDX `License List`_ for a list of commonly used licenses and their + identifiers. + + The license of individual components is taken from the + :prop_tgt:`SPDX_LICENSE` property of their respective targets. + + ``DEFAULT_LICENSE <license-string>`` + .. versionadded:: 4.2 + + A |SPDX|_ (SPDX) `License Expression`_ that describes the license(s) of any + components which do not otherwise specify their license(s). + + ``DESCRIPTION <description-string>`` .. versionadded:: 4.1 An informational description of the project. It is recommended that this @@ -1085,6 +1104,20 @@ use of ``LOWER_CASE_FILE`` should be consistent between the main package and any appendices. + .. note:: + Because it is intended to be portable across multiple build tools, CPS + may not support all features that are allowed in CMake-script exports. In + particular, support for generator expressions in interface properties is + limited at this time to configuration-dependent expressions. + + .. note:: + This is the recommended way to generate |CPS| package information for a + project. For distributors whose users may require CPS package information + when making changes to the project's build files is not practical, the + :variable:`CMAKE_INSTALL_EXPORTS_AS_PACKAGE_INFO` variable may be used to + generate ``.cps`` files from :command:`install(EXPORT)` calls. Refer to + the variable's documentation for usage and caveats. + .. signature:: install(RUNTIME_DEPENDENCY_SET <set-name> [...]) @@ -1102,7 +1135,7 @@ [COMPONENT <component>] [NAMELINK_COMPONENT <component>] [OPTIONAL] [EXCLUDE_FROM_ALL] - ] [...] + ]... [PRE_INCLUDE_REGEXES <regex>...] [PRE_EXCLUDE_REGEXES <regex>...] [POST_INCLUDE_REGEXES <regex>...] @@ -1158,6 +1191,92 @@ :command:`install_files`, and :command:`install_programs` commands is not defined. +.. signature:: + install(SBOM <sbom-name> [...]) + + .. versionadded:: 4.3 + .. note:: + + Experimental. Gated by ``CMAKE_EXPERIMENTAL_GENERATE_SBOM``. + + Installs a |SBOM| or "SBOM" which describes the project: + + .. code-block:: cmake + + install(SBOM <sbom-name> EXPORT <export-name> + [PROJECT <project-name>|NO_PROJECT_METADATA] + [DESTINATION <dir>] + [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]] + [LICENSE <license-string>] + [DESCRIPTION <description-string>] + [HOMEPAGE_URL <url-string>] + [PACKAGE_URL <url-string>] + [FORMAT <string>]) + + The ``SBOM`` form generates a |SBOM| or "SBOM" file for a given project + and installs it as part of the project installation. A |SBOM| is a + machine-readable description of the project's targets, linked libraries, + and related metadata, such as versions and license information. CMake + currently generates SBOM files using the |SPDX|_ 3.0 specification in + its JSON-LD representation, as selected by the ``FORMAT`` option, but + the interface is designed to allow additional SBOM formats or schema + versions to be supported in future CMake releases. + + Target installations are associated with the export ``<export-name>`` + using the ``EXPORT`` option of the :command:`install(TARGETS)` signature + documented above. If ``DESTINATION`` is not specified, a platform-specific + default is used. + + Several options may be used to specify package metadata: + + ``VERSION <version>`` + The package version, specified as a series of non-negative integer components, + i.e. <major>[.<minor>[.<patch>[.<tweak>]]]. See :command:`project(VERSION)` for + more information. + + ``FORMAT <string>`` + The format in which the SBOM should be exported, which must be an expression of + the form ``<format>[-<version>][+<representation>]``. CMake currently supports + the JSON-LD serialization of |SPDX|_ v3.0.1 (``spdx`` or ``spdx-3.0.1+json``), + which is also the default if ``FORMAT`` is not specified. + + ``HOMEPAGE_URL <url-string>`` + + An informational canonical home URL for the project. + + ``PACKAGE_URL <url-string>`` + + An informational canonical package URL for the project. + + ``LICENSE <license-string>`` + + A |SPDX|_ (SPDX) `License Expression`_ that describes the license(s) of the + project as a whole, including documentation, resources, or other materials + distributed with the project, in addition to software artifacts. See the + SPDX `License List`_ for a list of commonly used licenses and their + identifiers. + + The license of individual components is taken from the + :prop_tgt:`SPDX_LICENSE` property of their respective targets. + + ``DESCRIPTION <description-string>`` + + An informational description of the project. It is recommended that this + description is a relatively short string, usually no more than a few words. + + By default, if the specified ``<sbom-name>`` matches the current CMake + :variable:`PROJECT_NAME`, sbom metadata will be inherited from the + project. The ``PROJECT <project-name>`` option may be used to specify a + different project from which to inherit metadata. If ``NO_PROJECT_METADATA`` + is specified, automatic inheritance of sbom metadata will be disabled. + In any case, any metadata values specified in the ``install`` command will + take precedence. + + Note that an SBOM file cannot be generated for targets with generator + expressions contained in their :prop_tgt:`LINK_LIBRARIES` or + :prop_tgt:`INTERFACE_LINK_LIBRARIES` properties, unless the generator + expressions are guarded by :genex:`LINK_ONLY`. + Examples ^^^^^^^^ @@ -1283,3 +1402,11 @@ .. _cps-version_schema: https://cps-org.github.io/cps/schema.html#version-schema .. |cps-version_schema| replace:: ``version_schema`` + +.. _SPDX: https://spdx.dev/ +.. |SPDX| replace:: System Package Data Exchange + +.. _License Expression: https://spdx.github.io/spdx-spec/v3.0.1/annexes/spdx-license-expressions/ +.. _License List: https://spdx.org/licenses/ + +.. |SBOM| replace:: Software Bill of Material
diff --git a/Help/command/macro.rst b/Help/command/macro.rst index 978f7d6..3faa3db 100644 --- a/Help/command/macro.rst +++ b/Help/command/macro.rst
@@ -55,9 +55,10 @@ Arguments ^^^^^^^^^ -When a macro is invoked, the commands recorded in the macro are -first modified by replacing formal parameters (``${arg1}``, ...) -with the arguments passed, and then invoked as normal commands. +When a macro is invoked, first all commands recorded in the macro are +modified by replacing formal parameters (``${arg1}``, ...) +with the arguments passed. Then all modified commands are invoked as +normal commands. In addition to referencing the formal parameters you can reference the values ``${ARGC}`` which will be set to the number of arguments passed
diff --git a/Help/command/project.rst b/Help/command/project.rst index bf0f171..ad4f32e 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst
@@ -12,7 +12,8 @@ project(<PROJECT-NAME> [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]] [COMPAT_VERSION <major>[.<minor>[.<patch>[.<tweak>]]]] - [DESCRIPTION <project-description-string>] + [SPDX_LICENSE <license-string>] + [DESCRIPTION <description-string>] [HOMEPAGE_URL <url-string>] [LANGUAGES <language-name>...]) @@ -88,10 +89,7 @@ :variable:`CMAKE_PROJECT_VERSION`. ``COMPAT_VERSION <version>`` - .. versionadded:: 4.1 - .. note:: - - Experimental. Gated by ``CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_INFO``. + .. versionadded:: 4.3 Optional; requires ``VERSION`` also be set. @@ -100,13 +98,47 @@ and sets the variables * :variable:`PROJECT_COMPAT_VERSION`, - :variable:`<PROJECT-NAME>_COMPAT_VERSION` + :variable:`<PROJECT-NAME>_COMPAT_VERSION`. - When the ``project()`` command is called from the top-level - ``CMakeLists.txt``, then the compatibility version is also stored in the - variable :variable:`CMAKE_PROJECT_COMPAT_VERSION`. + When the ``project()`` command is called from the top-level + ``CMakeLists.txt``, then the compatibility version is also stored in the + variable :variable:`CMAKE_PROJECT_COMPAT_VERSION`. -``DESCRIPTION <project-description-string>`` +``SPDX_LICENSE <license-string>`` + .. versionadded:: 4.3 + + Optional. + Sets the variables + + * :variable:`PROJECT_SPDX_LICENSE`, + :variable:`<PROJECT-NAME>_SPDX_LICENSE` + + to ``<license-string>``, which shall be a |SPDX|_ (SPDX) + `License Expression`_ that describes the license(s) of the project as a + whole, including documentation, resources, or other materials distributed + with the project, in addition to software artifacts. See the SPDX + `License List`_ for a list of commonly used licenses and their identifiers. + See the :prop_tgt:`SPDX_LICENSE` property for specifying the license(s) on + individual software artifacts. + + .. note:: + The project license is *not* used to initialize the + :prop_tgt:`SPDX_LICENSE` property of individual targets. This allows the + package license and default component license, which are specified when + exporting package information, to be meaningful. Only |CPS| exports make + use of this information. + + The project license *is* inherited as the package license in some cases. + Refer to the ``PROJECT`` option and related documentation of the + :command:`export` and :command:`install` commands for more information. + +.. _SPDX: https://spdx.dev/ +.. |SPDX| replace:: System Package Data Exchange + +.. _License Expression: https://spdx.github.io/spdx-spec/v3.0.1/annexes/spdx-license-expressions/ +.. _License List: https://spdx.org/licenses/ + +``DESCRIPTION <description-string>`` .. versionadded:: 3.9 Optional. @@ -114,7 +146,7 @@ * :variable:`PROJECT_DESCRIPTION`, :variable:`<PROJECT-NAME>_DESCRIPTION` - to ``<project-description-string>``. + to ``<description-string>``. It is recommended that this description is a relatively short string, usually no more than a few words. @@ -149,12 +181,11 @@ Specify language ``NONE``, or use the ``LANGUAGES`` keyword and list no languages, to skip enabling any languages. -The variables set through the ``VERSION``, ``COMPAT_VERSION``, ``DESCRIPTION`` -and ``HOMEPAGE_URL`` options are intended for use as default values in package -metadata and documentation. The :command:`export` and :command:`install` -commands use these accordingly when generating |CPS| package descriptions. - -.. |CPS| replace:: Common Package Specification +The variables set through the ``VERSION``, ``COMPAT_VERSION``, +``SPDX_LICENSE``, ``DESCRIPTION`` and ``HOMEPAGE_URL`` options are +intended for use as default values in package metadata and documentation. +The :command:`export` and :command:`install` commands use these accordingly +when generating |CPS| package descriptions. .. _`Code Injection`: @@ -224,3 +255,5 @@ other commands whose behavior they may affect and for this reason the ``project()`` command will issue a warning if this order is not kept. See also policy :policy:`CMP0000`. + +.. |CPS| replace:: Common Package Specification
diff --git a/Help/command/remove_definitions.rst b/Help/command/remove_definitions.rst index faad16d..74730e5 100644 --- a/Help/command/remove_definitions.rst +++ b/Help/command/remove_definitions.rst
@@ -1,11 +1,32 @@ remove_definitions ------------------ -Remove -D define flags added by :command:`add_definitions`. +Removes compile definitions added by :command:`add_compile_definitions`, or +:command:`add_definitions`: .. code-block:: cmake - remove_definitions(-DFOO -DBAR ...) + remove_definitions([<definitions>...]) -Removes flags (added by :command:`add_definitions`) from the compiler -command line for sources in the current directory and below. +The arguments are: + +``<definitions>...`` + Zero or more compile definitions. + +This command can be also used to remove any flags added by +:command:`add_definitions`, but it is intended to remove preprocessor +definitions passed with ``-D``, or ``/D``. + +Examples +^^^^^^^^ + +In the following example targets of the current directory scope will have +only ``BAZ`` and ``QUUX`` compile definitions: + +.. code-block:: cmake + + add_compile_definitions(FOO BAR BAZ -DQUUX) + + # ... + + remove_definitions(-DFOO -DBAR)
diff --git a/Help/command/set.rst b/Help/command/set.rst index 6c1af47..12413f9 100644 --- a/Help/command/set.rst +++ b/Help/command/set.rst
@@ -44,15 +44,16 @@ ^^^^^^^^^^^^^^^ .. signature:: - set(<variable> <value>... CACHE <type> <docstring> [FORCE]) + set(CACHE{<variable>} [TYPE <type>] [HELP <helpstring>...] [FORCE] + VALUE [<value>...]) :target: CACHE - Sets the given cache ``<variable>`` (cache entry). Since cache entries - are meant to provide user-settable values this does not overwrite - existing cache entries by default. Use the ``FORCE`` option to - overwrite existing entries. + .. versionadded:: 4.2 - The ``<type>`` must be specified as one of: + Sets the given cache ``<variable>`` (cache entry). The options are: + + ``TYPE <type>`` + Specify the type of the cache entry. The ``<type>`` must be one of: ``BOOL`` Boolean ``ON/OFF`` value. @@ -77,9 +78,26 @@ They may be used to store variables persistently across runs. Use of this type implies ``FORCE``. - The ``<docstring>`` must be specified as a line of text - providing a quick summary of the option - for presentation to :manual:`cmake-gui(1)` users. + If ``TYPE`` is not specified, if the cache variable already exist and its + type is not ``UNINITIALIZED``, the type previously specified will be kept + otherwise, ``STRING`` will be used. + + ``HELP <helpstring>...`` + The ``<helpstring>`` must be specified as a line of text providing a quick + summary of the option for presentation to :manual:`cmake-gui(1)` users. If + more than one string is given, they are concatenated into a single string + with no separator between them. + + If ``HELP`` is not specified, an empty string will be used. + + ``FORCE`` + Since cache entries are meant to provide user-settable values this does not + overwrite existing cache entries by default. Use the ``FORCE`` option to + overwrite existing entries. + + ``VALUE <value>...`` + List of values to be set to the cache ``<variable>``. This argument must be + always the last one. 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. @@ -101,6 +119,13 @@ then the ``set`` command will treat the path as relative to the current working directory and convert it to an absolute path. +.. signature:: + set(<variable> <value>... CACHE <type> <docstring> [FORCE]) + :target: CACHE_legacy + + This signature is supported for compatibility purpose. Use preferably the + other one. + Set Environment Variable ^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst index f14b63d..e560f18 100644 --- a/Help/command/set_property.rst +++ b/Help/command/set_property.rst
@@ -5,18 +5,19 @@ .. code-block:: cmake - set_property(<GLOBAL | - DIRECTORY [<dir>] | - TARGET [<target1> ...] | - SOURCE [<src1> ...] + set_property({GLOBAL | + DIRECTORY [<dir>] | + TARGET <target>... | + FILE_SET <file_set>... TARGET <target> | + SOURCE <source>... [DIRECTORY <dirs> ...] - [TARGET_DIRECTORY <targets> ...] | - INSTALL [<file1> ...] | - TEST [<test1> ...] - [DIRECTORY <dir>] | - CACHE [<entry1> ...] > + [TARGET_DIRECTORY <targets>...] | + INSTALL <file>... | + TEST <test>... + [DIRECTORY <dir>] | + CACHE <entry>...} [APPEND] [APPEND_STRING] - PROPERTY <name> [<value1> ...]) + PROPERTY <name> [<value>...]) Sets one property on zero or more objects of a scope. @@ -41,6 +42,16 @@ :ref:`Alias Targets` do not support setting target properties. +``FILE_SET`` + .. versionadded:: 4.3 + + Scope may name zero or more existing file sets. + + The following option is required: + + ``TARGET <target>`` + The target to which the file set is attached. + ``SOURCE`` Scope may name zero or more source files. By default, source file properties are only visible to targets added in the same directory (``CMakeLists.txt``).
diff --git a/Help/command/source_group.rst b/Help/command/source_group.rst index 83ae286..130beca 100644 --- a/Help/command/source_group.rst +++ b/Help/command/source_group.rst
@@ -36,6 +36,10 @@ ``<name>``. Relative paths are interpreted with respect to the current source directory. + .. versionadded:: 4.3 + Arguments to ``FILES`` may use + :manual:`generator expressions <cmake-generator-expressions(7)>`. + ``REGULAR_EXPRESSION`` Any source file whose name matches the regular expression will be placed in group ``<name>``.
diff --git a/Help/command/string.rst b/Help/command/string.rst index f540e1c..b7ed69a 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst
@@ -27,6 +27,7 @@ string(`STRIP`_ <string> <out-var>) string(`GENEX_STRIP`_ <string> <out-var>) string(`REPEAT`_ <string> <count> <out-var>) + string(`REGEX QUOTE`_ <out-var> <input>...) `Comparison`_ string(`COMPARE`_ <op> <string1> <string2> <out-var>) @@ -45,7 +46,10 @@ `JSON`_ string(JSON <out-var> [ERROR_VARIABLE <error-var>] - {`GET <JSON-GET_>`__ | `TYPE <JSON-TYPE_>`__ | `LENGTH <JSON-LENGTH_>`__ | `REMOVE <JSON-REMOVE_>`__} + {`GET <JSON-GET_>`__ | `GET_RAW <JSON-GET-RAW_>`__ | `TYPE <JSON-TYPE_>`__ | `LENGTH <JSON-LENGTH_>`__} + <json-string> [<member|index> ...]) + string(JSON <out-var> [ERROR_VARIABLE <error-var>] + `REMOVE <JSON-REMOVE_>`__ <json-string> <member|index> [<member|index> ...]) string(JSON <out-var> [ERROR_VARIABLE <error-var>] `MEMBER <JSON-MEMBER_>`__ <json-string> @@ -55,6 +59,8 @@ <member|index> [<member|index> ...] <value>) string(JSON <out-var> [ERROR_VARIABLE <error-var>] `EQUAL <JSON-EQUAL_>`__ <json-string1> <json-string2>) + string(JSON <out-var> [ERROR_VARIABLE <error-var>] + `STRING_ENCODE <STRING-ENCODE_>`__ <string>) Search and Replace ^^^^^^^^^^^^^^^^^^ @@ -290,6 +296,16 @@ Produce the output string as the input ``<string>`` repeated ``<count>`` times. +.. signature:: + string(REGEX QUOTE <out-var> <input>...) + + .. versionadded:: 4.2 + + Store in an ``<out-var>`` a regular expression matching the ``<input>``. + All characters that have special meaning in a regular expression are + escaped, such that the output string can be used as part of a regular + expression to match the input literally. + Comparison ^^^^^^^^^^ @@ -538,7 +554,7 @@ .. signature:: string(JSON <out-var> [ERROR_VARIABLE <error-variable>] - GET <json-string> <member|index> [<member|index> ...]) + GET <json-string> [<member|index> ...]) :target: JSON-GET Get an element from ``<json-string>`` at the location given @@ -550,7 +566,19 @@ .. signature:: string(JSON <out-var> [ERROR_VARIABLE <error-variable>] - TYPE <json-string> <member|index> [<member|index> ...]) + GET_RAW <json-string> [<member|index> ...]) + :target: JSON-GET-RAW + + .. versionadded:: 4.3 + + Get an element from ``<json-string>`` at the location given + by the list of ``<member|index>`` arguments. Similar to + :cref:`GET <JSON-GET_>`, but does not convert number, string, + boolean, or null elements. + +.. signature:: + string(JSON <out-var> [ERROR_VARIABLE <error-variable>] + TYPE <json-string> [<member|index> ...]) :target: JSON-TYPE Get the type of an element in ``<json-string>`` at the location @@ -608,3 +636,13 @@ and ``<json-string2>`` should be valid JSON. The ``<out-var>`` will be set to a true value if the JSON objects are considered equal, or a false value otherwise. + +.. signature:: + string(JSON <out-var> [ERROR_VARIABLE <error-var>] + STRING_ENCODE <string>) + :target: STRING-ENCODE + + .. versionadded:: 4.3 + + Turn a raw string into a JSON string surrounded by quotes. Special characters + will be properly escaped inside the JSON string.
diff --git a/Help/command/target_compile_definitions.rst b/Help/command/target_compile_definitions.rst index 61cfb19..cb2629e 100644 --- a/Help/command/target_compile_definitions.rst +++ b/Help/command/target_compile_definitions.rst
@@ -6,8 +6,8 @@ .. code-block:: cmake target_compile_definitions(<target> - <INTERFACE|PUBLIC|PRIVATE> [items1...] - [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) + <INTERFACE|PUBLIC|PRIVATE> <definition>... + [<INTERFACE|PUBLIC|PRIVATE> <definition>... ...]) Specifies compile definitions to use when compiling a given ``<target>``. The named ``<target>`` must have been created by a command such as
diff --git a/Help/command/target_compile_features.rst b/Help/command/target_compile_features.rst index 2d569e9..f63a56c 100644 --- a/Help/command/target_compile_features.rst +++ b/Help/command/target_compile_features.rst
@@ -7,7 +7,9 @@ .. code-block:: cmake - target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...]) + target_compile_features(<target> + {INTERFACE|PUBLIC|PRIVATE} <feature>... + [{INTERFACE|PUBLIC|PRIVATE} <feature>...]...) Specifies compiler features required when compiling a given target. If the feature is not listed in the :variable:`CMAKE_C_COMPILE_FEATURES`,
diff --git a/Help/command/target_compile_options.rst b/Help/command/target_compile_options.rst index 6fb86cd..a16e55b 100644 --- a/Help/command/target_compile_options.rst +++ b/Help/command/target_compile_options.rst
@@ -6,8 +6,8 @@ .. code-block:: cmake target_compile_options(<target> [BEFORE] - <INTERFACE|PUBLIC|PRIVATE> [items1...] - [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) + {INTERFACE|PUBLIC|PRIVATE} <item>... + [{INTERFACE|PUBLIC|PRIVATE} <item>...]...) Adds options to the :prop_tgt:`COMPILE_OPTIONS` or :prop_tgt:`INTERFACE_COMPILE_OPTIONS` target properties. These options
diff --git a/Help/command/target_include_directories.rst b/Help/command/target_include_directories.rst index 38bf581..59d0cd5 100644 --- a/Help/command/target_include_directories.rst +++ b/Help/command/target_include_directories.rst
@@ -6,8 +6,8 @@ .. code-block:: cmake target_include_directories(<target> [SYSTEM] [AFTER|BEFORE] - <INTERFACE|PUBLIC|PRIVATE> [items1...] - [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) + {INTERFACE|PUBLIC|PRIVATE} <dir... + [{INTERFACE|PUBLIC|PRIVATE} <dir>...]...) Specifies include directories to use when compiling a given target. The named ``<target>`` must have been created by a command such
diff --git a/Help/command/target_link_directories.rst b/Help/command/target_link_directories.rst index af7a506..91c1feb 100644 --- a/Help/command/target_link_directories.rst +++ b/Help/command/target_link_directories.rst
@@ -8,8 +8,8 @@ .. code-block:: cmake target_link_directories(<target> [BEFORE] - <INTERFACE|PUBLIC|PRIVATE> [items1...] - [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) + {INTERFACE|PUBLIC|PRIVATE} <dir>... + [{INTERFACE|PUBLIC|PRIVATE} <dir>...]...) Specifies the paths in which the linker should search for libraries when linking a given target. Each item can be an absolute or relative path,
diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index a8ba92c..4d964f4 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst
@@ -158,8 +158,8 @@ .. code-block:: cmake target_link_libraries(<target> - <PRIVATE|PUBLIC|INTERFACE> <item>... - [<PRIVATE|PUBLIC|INTERFACE> <item>...]...) + {INTERFACE|PUBLIC|PRIVATE} <item>... + [{INTERFACE|PUBLIC|PRIVATE} <item>...]...) The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` :ref:`scope <Target Command Scope>` keywords can be used to
diff --git a/Help/command/target_link_options.rst b/Help/command/target_link_options.rst index cbbd720..9e55e9d 100644 --- a/Help/command/target_link_options.rst +++ b/Help/command/target_link_options.rst
@@ -9,8 +9,8 @@ .. code-block:: cmake target_link_options(<target> [BEFORE] - <INTERFACE|PUBLIC|PRIVATE> [items1...] - [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) + {INTERFACE|PUBLIC|PRIVATE} <item>... + [{INTERFACE|PUBLIC|PRIVATE} <item>...]...) The named ``<target>`` must have been created by a command such as :command:`add_executable` or :command:`add_library` and must not be an @@ -67,5 +67,10 @@ add language-wide flags passed to all invocations of the compiler. This includes invocations that drive compiling and those that drive linking. +* .. versionadded:: 4.3 + :variable:`CMAKE_<LANG>_LINK_FLAGS` and + :variable:`CMAKE_<LANG>_LINK_FLAGS_<CONFIG>` add language-wide flags passed + to all invocations of the compiler which drive linking. + * The :module:`CheckLinkerFlag` module to check whether a linker flag is supported by the compiler.
diff --git a/Help/command/target_precompile_headers.rst b/Help/command/target_precompile_headers.rst index acd83a8..7089582 100644 --- a/Help/command/target_precompile_headers.rst +++ b/Help/command/target_precompile_headers.rst
@@ -15,8 +15,8 @@ .. code-block:: cmake target_precompile_headers(<target> - <INTERFACE|PUBLIC|PRIVATE> [header1...] - [<INTERFACE|PUBLIC|PRIVATE> [header2...] ...]) + {INTERFACE|PUBLIC|PRIVATE} <header>... + [{INTERFACE|PUBLIC|PRIVATE} <header>...]...) The command adds header files to the :prop_tgt:`PRECOMPILE_HEADERS` and/or :prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` target properties of ``<target>``.
diff --git a/Help/command/target_sources.rst b/Help/command/target_sources.rst index 0d31f8c..5fa4ef1 100644 --- a/Help/command/target_sources.rst +++ b/Help/command/target_sources.rst
@@ -8,8 +8,8 @@ .. code-block:: cmake target_sources(<target> - <INTERFACE|PUBLIC|PRIVATE> [items1...] - [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) + {INTERFACE|PUBLIC|PRIVATE} <source>... + [{INTERFACE|PUBLIC|PRIVATE} <source>...]...) Specifies sources to use when building a target and/or its dependents. The named ``<target>`` must have been created by a command such as @@ -70,7 +70,7 @@ .. code-block:: cmake target_sources(<target> - [<INTERFACE|PUBLIC|PRIVATE> + [{INTERFACE|PUBLIC|PRIVATE} [FILE_SET <set> [TYPE <type>] [BASE_DIRS <dirs>...] [FILES <files>...]]... ]...)
diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index 181e850..dc6ec44 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst
@@ -71,10 +71,10 @@ try_compile(<compileResultVar> [SOURCES_TYPE <type>] - <SOURCES <srcfile...> | + {SOURCES <srcfile>... | SOURCE_FROM_CONTENT <name> <content> | SOURCE_FROM_VAR <name> <var> | - SOURCE_FROM_FILE <name> <path> >... + SOURCE_FROM_FILE <name> <path> }... [LOG_DESCRIPTION <text>] [NO_CACHE] [NO_LOG] @@ -130,7 +130,7 @@ .. code-block:: cmake - try_compile(<compileResultVar> <bindir> <srcfile|SOURCES srcfile...> + try_compile(<compileResultVar> <bindir> {<srcfile>|SOURCES <srcfile>...} [CMAKE_FLAGS <flags>...] [COMPILE_DEFINITIONS <defs>...] [LINK_OPTIONS <options>...] @@ -320,8 +320,12 @@ * :variable:`CMAKE_CUDA_RUNTIME_LIBRARY` * :variable:`CMAKE_ENABLE_EXPORTS` + * :variable:`CMAKE_EXECUTABLE_ENABLE_EXPORTS` + * :variable:`CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS` * :variable:`CMAKE_EXE_LINKER_FLAGS`, unless using CMake versions prior to 4.0 without policy :policy:`CMP0056` set to ``NEW`` + * :variable:`CMAKE_<LANG>_LINK_FLAGS`, unless using CMake versions + prior to 4.3 without policy :policy:`CMP0210` set to ``NEW`` * :variable:`CMAKE_LINK_SEARCH_START_STATIC` * :variable:`CMAKE_LINK_SEARCH_END_STATIC` * :variable:`CMAKE_MSVC_RUNTIME_LIBRARY` @@ -350,10 +354,7 @@ * :policy:`CMP0157` * :policy:`CMP0181` * :policy:`CMP0184` - -.. versionadded:: 4.0 - The current setting of :policy:`CMP0181` policy is propagated through to the - generated test project. +* :policy:`CMP0210` Set variable :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` to choose a build configuration: @@ -423,6 +424,11 @@ :variable:`CMAKE_MSVC_RUNTIME_CHECKS` to specify the enabled MSVC runtime checks. +.. versionadded:: 4.3 + If :policy:`CMP0210` is set to ``NEW``, :variable:`CMAKE_<LANG>_LINK_FLAGS` + and :variable:`CMAKE_<LANG>_LINK_FLAGS_<CONFIG>` are propagated into the + test project's build configuration. + See Also ^^^^^^^^
diff --git a/Help/command/try_run.rst b/Help/command/try_run.rst index f14a5c2..2cae17b 100644 --- a/Help/command/try_run.rst +++ b/Help/command/try_run.rst
@@ -14,10 +14,10 @@ try_run(<runResultVar> <compileResultVar> [SOURCES_TYPE <type>] - <SOURCES <srcfile...> | + {SOURCES <srcfile>... | SOURCE_FROM_CONTENT <name> <content> | SOURCE_FROM_VAR <name> <var> | - SOURCE_FROM_FILE <name> <path> >... + SOURCE_FROM_FILE <name> <path> }... [LOG_DESCRIPTION <text>] [NO_CACHE] [NO_LOG] @@ -63,7 +63,7 @@ .. code-block:: cmake try_run(<runResultVar> <compileResultVar> - <bindir> <srcfile|SOURCES srcfile...> + <bindir> {<srcfile>|SOURCES <srcfile>...} [CMAKE_FLAGS <flags>...] [COMPILE_DEFINITIONS <defs>...] [LINK_OPTIONS <options>...] @@ -155,6 +155,20 @@ the target platform. This is created only if the ``RUN_OUTPUT_VARIABLE`` or ``OUTPUT_VARIABLE`` option was used. +``<runResultVar>__TRYRUN_OUTPUT_STDOUT`` + .. versionadded:: 3.25 + + Output from stdout if the executable were to be run on the target + platform. This is created only if the ``RUN_OUTPUT_STDOUT_VARIABLE`` + or ``RUN_OUTPUT_STDERR_VARIABLE`` option was used. + +``<runResultVar>__TRYRUN_OUTPUT_STDERR`` + .. versionadded:: 3.25 + + Output from stderr if the executable were to be run on the target + platform. This is created only if the ``RUN_OUTPUT_STDOUT_VARIABLE`` + or ``RUN_OUTPUT_STDERR_VARIABLE`` option was used. + In order to make cross compiling your project easier, use ``try_run`` only if really required. If you use ``try_run``, use the ``RUN_OUTPUT_STDOUT_VARIABLE``, ``RUN_OUTPUT_STDERR_VARIABLE``,
diff --git a/Help/command/unset.rst b/Help/command/unset.rst index f78d01f..8512246 100644 --- a/Help/command/unset.rst +++ b/Help/command/unset.rst
@@ -3,37 +3,54 @@ Unset a variable, cache variable, or environment variable. -Unset Normal Variable or Cache Entry -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Unset Normal Variable +^^^^^^^^^^^^^^^^^^^^^ -.. code-block:: cmake +.. signature:: + unset(<variable> [PARENT_SCOPE]) + :target: normal - unset(<variable> [CACHE | PARENT_SCOPE]) + Removes a normal variable from the current scope, causing it + to become undefined. -Removes a normal variable from the current scope, causing it -to become undefined. If ``CACHE`` is present, then a cache variable -is removed instead of a normal variable. - -If ``PARENT_SCOPE`` is present then the variable is removed from the scope -above the current scope. See the same option in the :command:`set` command -for further details. + If ``PARENT_SCOPE`` is present then the variable is removed from the scope + above the current scope. See the same option in the :command:`set` command + for further details. .. include:: include/UNSET_NOTE.rst +Unset Cache Entry +^^^^^^^^^^^^^^^^^ + +.. signature:: + unset(CACHE{<variable>}) + :target: CACHE + + .. versionadded:: 4.2 + + Removes ``<variable>`` from the cache, causing it to become undefined. + +.. signature:: + unset(<variable> CACHE) + :target: CACHE_legacy + + This signature is supported for compatibility purpose. Use preferably the + other one. + Unset Environment Variable ^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. code-block:: cmake - +.. signature:: unset(ENV{<variable>}) + :target: ENV -Removes ``<variable>`` from the currently available -:manual:`Environment Variables <cmake-env-variables(7)>`. -Subsequent calls of ``$ENV{<variable>}`` will return the empty string. + Removes ``<variable>`` from the currently available + :manual:`Environment Variables <cmake-env-variables(7)>`. + Subsequent calls of ``$ENV{<variable>}`` will return the empty string. -This command affects only the current CMake process, not the process -from which CMake was called, nor the system environment at large, -nor the environment of subsequent build or test processes. + This command affects only the current CMake process, not the process + from which CMake was called, nor the system environment at large, + nor the environment of subsequent build or test processes. See Also ^^^^^^^^
diff --git a/Help/cpack_gen/appimage.rst b/Help/cpack_gen/appimage.rst new file mode 100644 index 0000000..42dec8e --- /dev/null +++ b/Help/cpack_gen/appimage.rst
@@ -0,0 +1,155 @@ +CPack AppImage Generator +------------------------ + +.. versionadded:: 4.2 + +The CPack `AppImage`_ generator enables bundling an application into the +AppImage format. It uses ``appimagetool`` to pack the application +and ``patchelf`` to set the application ``RPATH`` to a relative path +based on where the AppImage will be mounted. + +.. _`AppImage`: https://appimage.org + +The ``appimagetool`` does not scan for libraries dependencies. It only +packs the installed content and checks if the provided ``.desktop`` file +was properly created. For best compatibility, it's recommended to build on +an old LTS distribution and to include any dependencies in the generated file. + +The snippet below can be added to your ``CMakeLists.txt`` file. +Replace ``my_application_target`` with your application target. +The example will do a best effort to identify the libraries your +application links to and copy them to the install location. + +.. code-block:: cmake + + install(CODE [[ + file(GET_RUNTIME_DEPENDENCIES + EXECUTABLES $<TARGET_FILE:my_application_target> + RESOLVED_DEPENDENCIES_VAR resolved_deps + ) + + foreach(dep ${resolved_deps}) + # copy the symlink + file(COPY ${dep} DESTINATION ${CMAKE_INSTALL_PREFIX}/lib) + + # Resolve the real path of the dependency (follows symlinks) + file(REAL_PATH ${dep} resolved_dep_path) + + # Copy the resolved file to the destination + file(COPY ${resolved_dep_path} DESTINATION ${CMAKE_INSTALL_PREFIX}/lib) + endforeach() + ]]) + +The CPack AppImage generator will generate a default `AppRun`_ based on the +provided ``.desktop`` entry. Alternatively, if a custom ``AppRun`` is +installed, e.g., via the :command:`install` command, it will be used instead +of the generated one. + +.. _`AppRun`: https://docs.appimage.org/introduction/software-overview.html#apprun + +For Qt-based projects, it is recommended to call +``qt_generate_deploy_app_script()`` or ``qt_generate_deploy_qml_app_script()`` +and install the files generated by the script. This will install the +Qt plugins. + +You must also set :variable:`CPACK_PACKAGE_ICON` with the same value +listed in the Desktop file. + +Variables Specific to CPack AppImage Generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. variable:: CPACK_APPIMAGE_TOOL_EXECUTABLE + + Name of the ``appimagetool`` executable. If not given as an absolute path, + logic based on :command:`find_program` will be used internally with this + value to find the executable. + + :Default: ``appimagetool`` + +.. variable:: CPACK_APPIMAGE_PATCHELF_EXECUTABLE + + Name of the ``patchelf`` executable. If not given as an absolute path, + logic based on :command:`find_program` will be used internally with this + value to find the executable. + + :Default: ``patchelf`` + +.. variable:: CPACK_APPIMAGE_DESKTOP_FILE + + Name of the freedesktop.org desktop file to be installed. If not specified, + the first ``.desktop`` file found in the list of files to be installed will + be used. There must be a valid ``.desktop`` file for the package, and it + must include an ``Icon`` entry that matches :variable:`CPACK_PACKAGE_ICON` + without the file extension. The actual installed location of the icon + should follow the freedesktop.org specification. + + :Default: Unset + +.. variable:: CPACK_APPIMAGE_UPDATE_INFORMATION + + Embed the value of this variable as the update information. See the + ``appimagetool`` source code for the supported values and formats of the + ``--updateinformation`` option. It is highly recommended to have + the ``zsyncmake`` tool installed if using ``zsync`` update information. + + :Default: Unset + +.. variable:: CPACK_APPIMAGE_GUESS_UPDATE_INFORMATION + + When this variable is true, add the ``--guess`` option to the + ``appimagetool`` invocation. This directs the tool to try to guess + appropriate update information based on GitHub or GitLab environment + variables. + + :Default: Unset + +.. variable:: CPACK_APPIMAGE_COMPRESSOR + + Override the ``appimagetool``'s default type of squashfs compression (zstd). + This corresponds to the ``appimagetool --comp`` option. + + :Default: Unset + +.. variable:: CPACK_APPIMAGE_MKSQUASHFS_OPTIONS + + List of arguments to pass through to ``mksquashfs``. Each of these will be + preceded by ``--mksquashfs-opt`` on the ``appimagetool`` command line. + + :Default: Unset + +.. variable:: CPACK_APPIMAGE_NO_APPSTREAM + + If set to true, do not check AppStream metadata. This passes the + ``--no-appstream`` option to ``appimagetool``. + + :Default: Unset + +.. variable:: CPACK_APPIMAGE_EXCLUDE_FILE + + Use the specified file as an exclude file for ``mksquashfs``, + in addition to ``.appimageignore``. This uses the ``--exclude-file`` + option to ``appimagetool``. + + :Default: Unset + +.. variable:: CPACK_APPIMAGE_RUNTIME_FILE + + Specify a runtime file to use instead of letting the ``appimagetool`` + download a runtime to embed in the generated AppImage. + + :Default: Unset + +.. variable:: CPACK_APPIMAGE_SIGN + + When set to true, sign the generated AppImage with gpg[2]. + :variable:`CPACK_APPIMAGE_SIGN_KEY` should also be specified if using this + option. + + :Default: Unset + +.. variable:: CPACK_APPIMAGE_SIGN_KEY + + Key ID to use for gpg[2] signatures when signing is enabled with + :variable:`CPACK_APPIMAGE_SIGN`. + + :Default: Unset
diff --git a/Help/cpack_gen/archive.rst b/Help/cpack_gen/archive.rst index 81da98b..21e67ce 100644 --- a/Help/cpack_gen/archive.rst +++ b/Help/cpack_gen/archive.rst
@@ -4,29 +4,85 @@ CPack generator for packaging files into an archive, which can have any of the following formats: -- 7Z - 7zip - (``.7z``) +- 7Z - 7zip - (``.7z``) - LZMA compressed .. versionadded:: 3.1 -- TAR (``.tar``) + This is an alias for ``7Z_LZMA`` + +- 7Z_BZ2 - 7zip - (``.7z``) - BZip2 compressed + + .. versionadded:: 4.3 + +- 7Z_DEFLATE - 7zip - (``.7z``) - Deflate compressed + + .. versionadded:: 4.3 + +- 7Z_LZMA - 7zip - (``.7z``) - LZMA compressed + + .. versionadded:: 4.3 + +- 7Z_LZMA2 - 7zip - (``.7z``) - LZMA2 compressed + + .. versionadded:: 4.3 + +- 7Z_PPMD - 7zip - (``.7z``) - PPMd compressed + + .. versionadded:: 4.3 + +- 7Z_STORE - 7zip - (``.7z``) - no compression is used + + .. versionadded:: 4.3 + +- 7Z_ZSTD - 7zip - (``.7z``) - Zstandard compressed + + .. versionadded:: 4.3 + +- TAR (``.tar``) - no compression is used .. versionadded:: 4.0 -- TBZ2 (``.tar.bz2``) +- TBZ2 (``.tar.bz2``) - BZip2 compressed -- TGZ (``.tar.gz``) +- TGZ (``.tar.gz``) - Deflate compressed -- TXZ (``.tar.xz``) +- TXZ (``.tar.xz``) - LZMA2 compressed .. versionadded:: 3.1 -- TZ (``.tar.Z``) +- TZ (``.tar.Z``) - LZW compressed -- TZST (``.tar.zst``) +- TZST (``.tar.zst``) - Zstandard compressed .. versionadded:: 3.16 -- ZIP (``.zip``) +- ZIP (``.zip``) - Deflate compressed + + This is an alias for ``ZIP_DEFLATE`` + +- ZIP_BZ2 (``.zip``) - BZip2 compressed + + .. versionadded:: 4.3 + +- ZIP_DEFLATE (``.zip``) - Deflate compressed + + .. versionadded:: 4.3 + +- ZIP_LZMA (``.zip``) - LZMA compressed + + .. versionadded:: 4.3 + +- ZIP_LZMA2 (``.zip``) - LZMA2 compressed + + .. versionadded:: 4.3 + +- ZIP_STORE (``.zip``) - no compression is used + + .. versionadded:: 4.3 + +- ZIP_ZSTD (``.zip``) - Zstandard compressed + + .. versionadded:: 4.3 When this generator is called from ``CPackSourceConfig.cmake`` (or through the ``package_source`` target), then the generated archive will contain all @@ -100,6 +156,24 @@ If enabled (``ON``) multiple packages are generated. By default a single package containing files of all components is generated. +.. variable:: CPACK_ARCHIVE_UID + + .. versionadded: 4.3 + + Set the UID of entries contained in the archive. + Specify ``-1`` to use the UID of the current user. + + :Default: ``0`` (see policy :policy:`CMP0206`) + +.. variable:: CPACK_ARCHIVE_GID + + .. versionadded: 4.3 + + Set the GID of entries contained in the archive. + Specify ``-1`` to use the GID of the current user. + + :Default: ``0`` (see policy :policy:`CMP0206`) + Variables used by CPack Archive generator ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -125,3 +199,21 @@ Official CMake binaries available on ``cmake.org`` now ship with a ``liblzma`` that supports parallel compression. Older versions did not. + +.. variable:: CPACK_ARCHIVE_COMPRESSION_LEVEL + + .. versionadded:: 4.3 + + The compression level to use when compressing the archive. + + :Default: value of :variable:`CPACK_COMPRESSION_LEVEL` + + The compression level should be between ``0`` and ``9``. + + The compression level of the Zstandard-based algorithm can be set + between ``0`` and ``19``, except for the ``ZIP_ZSTD`` mode. + + The value ``0`` is used to specify the default compression level. + It is selected automatically by the archive library backend and + not directly set by CMake itself. The default compression level + may vary between archive formats, platforms, etc.
diff --git a/Help/cpack_gen/deb.rst b/Help/cpack_gen/deb.rst index ce7a3e8..d738804 100644 --- a/Help/cpack_gen/deb.rst +++ b/Help/cpack_gen/deb.rst
@@ -293,19 +293,50 @@ Lempel–Ziv–Markov chain algorithm ``xz`` - XZ Utils compression + XZ Utils LZMA2 (Lempel–Ziv–Markov chain algorithm, version 2) compression ``bzip2`` bzip2 Burrows–Wheeler algorithm ``gzip`` - GNU Gzip compression + GNU Gzip Deflate compression ``zstd`` .. versionadded:: 3.22 Zstandard compression +.. variable:: CPACK_DEBIAN_COMPRESSION_LEVEL + + .. versionadded:: 4.3 + + The compression level used for creating the Debian package. + + :Mandatory: No + :Default: value of :variable:`CPACK_COMPRESSION_LEVEL` + + This variable allows fine-tuning of the compression ratio and speed for the + Debian package archive. It controls the numeric compression level passed to + the compressor defined by :variable:`CPACK_DEBIAN_COMPRESSION_TYPE`. + If ``CPACK_DEBIAN_COMPRESSION_LEVEL`` is not set, or is set to ``0``, + the default value will be used. + + The valid range and interpretation depend on the selected compression type: + + - ``gzip`` – level 1–9 + - ``bzip2`` – level 1–9 + - ``xz`` – level 1–9 + - ``lzma`` – level 1–9 + - ``zstd`` – level 1–19 + + Example usage: + + .. code-block:: cmake + + set(CPACK_DEBIAN_COMPRESSION_TYPE "xz") + set(CPACK_DEBIAN_COMPRESSION_LEVEL 9) + + include(CPack) .. variable:: CPACK_DEBIAN_PACKAGE_PRIORITY CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY
diff --git a/Help/cpack_gen/dmg.rst b/Help/cpack_gen/dmg.rst index 0bd52ec..1307047 100644 --- a/Help/cpack_gen/dmg.rst +++ b/Help/cpack_gen/dmg.rst
@@ -160,3 +160,11 @@ Path to the ``Rez(1)`` command used to compile resources on macOS. This variable can be used to override the automatically detected command (or specify its location if the auto-detection fails to find it). + +.. variable:: CPACK_COMMAND_SYNC + + .. versionadded:: 4.2 + + Path to the ``sync(8)`` command used to force completion of pending disk writes + on macOS. This variable can be used to override the automatically detected + command (or specify its location if the auto-detection fails to find it).
diff --git a/Help/cpack_gen/ifw.rst b/Help/cpack_gen/ifw.rst index 9687281..e22aa91 100644 --- a/Help/cpack_gen/ifw.rst +++ b/Help/cpack_gen/ifw.rst
@@ -469,7 +469,7 @@ The ``DOWNLOADED`` option in the :command:`cpack_add_component` command specifies that a component is to be downloaded. Alternatively, the ``ALL`` option in the :command:`cpack_configure_downloads` command specifies that -``all`` components are to be be downloaded. +``all`` components are to be downloaded. The :command:`cpack_ifw_add_repository` command and the :variable:`CPACK_IFW_DOWNLOAD_ALL` variable allow for more specific
diff --git a/Help/cpack_gen/nsis.rst b/Help/cpack_gen/nsis.rst index 458ed93..53b1e9b 100644 --- a/Help/cpack_gen/nsis.rst +++ b/Help/cpack_gen/nsis.rst
@@ -240,3 +240,12 @@ where ``<preArgs>...`` is constructed from ``CPACK_NSIS_EXECUTABLE_PRE_ARGUMENTS`` and ``<postArgs>...`` is constructed from ``CPACK_NSIS_EXECUTABLE_POST_ARGUMENTS``. + +.. variable:: CPACK_NSIS_CRC_CHECK + + .. versionadded:: 4.2 + + Specifies whether or not the installer will perform a CRC on itself before + allowing an install. + Allowed values for this variable are ``on``, ``off``, and ``force``. + If not specified, the default behavior is ``on``.
diff --git a/Help/cpack_gen/rpm.rst b/Help/cpack_gen/rpm.rst index 3583765..b25b822 100644 --- a/Help/cpack_gen/rpm.rst +++ b/Help/cpack_gen/rpm.rst
@@ -255,13 +255,13 @@ Lempel–Ziv–Markov chain algorithm ``xz`` - XZ Utils compression + XZ Utils LZMA2 (Lempel–Ziv–Markov chain algorithm, version 2) compression ``bzip2`` bzip2 Burrows–Wheeler algorithm ``gzip`` - GNU Gzip compression + GNU Gzip Deflate compression ``zstd`` .. versionadded:: 3.31
diff --git a/Help/cpack_gen/wix.rst b/Help/cpack_gen/wix.rst index e2003ca..738ee7c 100644 --- a/Help/cpack_gen/wix.rst +++ b/Help/cpack_gen/wix.rst
@@ -408,8 +408,9 @@ In 32-bit builds the token will expand empty while in 64-bit builds it will expand to ``64``. - When unset generated installers will default installing to - ``ProgramFiles<64>Folder``. + When unset generated installers will install to + ``LocalAppDataFolder`` if :variable:`CPACK_WIX_INSTALL_SCOPE` is ``perUser``, + and to ``ProgramFiles<64>Folder`` otherwise. .. variable:: CPACK_WIX_ROOT @@ -451,7 +452,7 @@ .. versionadded:: 3.29 This variable can be optionally set to specify the ``InstallScope`` - of the installer: + of the installer (see https://docs.firegiant.com/wix3/xsd/wix/package/): ``perMachine`` Create an installer that installs for all users and requires @@ -461,7 +462,20 @@ This is the default. See policy :policy:`CMP0172`. ``perUser`` - Not yet supported. This is reserved for future use. + Create an installer that installs only for the current user + and does not require administrative privileges. Start menu entries created + by the installer are visible only to the current user. + + To enable per-user installation, the installer has to generate some + additional registry entries to serve as "key paths" for installed + components (see https://learn.microsoft.com/en-us/windows/win32/msi/ice38). + These registry entries are created under ``HKEY_CURRENT_USER``, using the + path specified by the :variable:`CPACK_WIX_COMPONENT_KEYS_REGISTRY_PATH` + variable. + + .. versionchanged:: 4.3 + + Before CMake 4.3, this value was reserved for future use and not supported. ``NONE`` Create an installer without any ``InstallScope`` attribute. @@ -477,13 +491,37 @@ but the start menu entry and uninstaller registration are created only for the current user. - .. warning:: + .. warning:: + Installations performed by installers created with different + ``InstallScope`` values cannot be cleanly updated or replaced by each other. + For example, to transition a project's installers from ``NONE`` to + ``perMachine``, or from ``perMachine`` to ``perUser``, the latter installer + should be distributed with instructions to first manually uninstall + any older version. - An installation performed by an installer created without any - ``InstallScope`` cannot be cleanly updated or replaced by an - installer with an ``InstallScope``. In order to transition - a project's installers from ``NONE`` to ``perMachine``, the - latter installer should be distributed with instructions to - first manually uninstall any older version. +.. variable:: CPACK_WIX_COMPONENT_KEYS_REGISTRY_PATH - See https://docs.firegiant.com/wix3/xsd/wix/package/ + .. versionadded:: 4.3 + + This variable determines the registry path under ``HKEY_CURRENT_USER`` + where the installer will create registry entries to serve as "key paths" + for components if :variable:`CPACK_WIX_INSTALL_SCOPE` is set to ``perUser``. + + Use forward slashes (``/``) as path separators to avoid issues with escapes; + they will be converted to backslashes (``\``) by the WIX generator. + + Default value is ``Software/<Vendor>/<PackageName>/Components``, + where ``<Vendor>`` is taken from :variable:`CPACK_PACKAGE_VENDOR`, + and ``<PackageName>`` is taken from :variable:`CPACK_PACKAGE_NAME`. + + Example: ``Software/MyCompany/MyProduct/Components`` + +.. variable:: CPACK_WIX_CAB_PER_COMPONENT + + .. versionadded:: 4.2 + + If this variable is set to true one ``.cab`` file per component is created. + The default is to create a single ``.cab`` file for all files in the installer. + + WiX creates ``.cab`` files in parallel so multiple ``.cab`` files may be + desirable for faster packaging.
diff --git a/Help/dev/README.rst b/Help/dev/README.rst index 2a2d32d..84766a6 100644 --- a/Help/dev/README.rst +++ b/Help/dev/README.rst
@@ -40,11 +40,13 @@ * The `CMake Documentation Guide`_. * The `CMake Testing Guide`_. * The `CMake Experimental Features Guide`_. +* The `CMake Debugging Guide`_. .. _`CMake Source Code Guide`: source.rst .. _`CMake Documentation Guide`: documentation.rst .. _`CMake Testing Guide`: testing.rst .. _`CMake Experimental Features Guide`: experimental.rst +.. _`CMake Debugging Guide`: debug.rst Maintainer Documentation ========================
diff --git a/Help/dev/debug.rst b/Help/dev/debug.rst new file mode 100644 index 0000000..ded270f --- /dev/null +++ b/Help/dev/debug.rst
@@ -0,0 +1,197 @@ +CMake Debugging Guide +********************* + +This guide explains how to attach a debugger to CMake's unit testing framework. +We'll focus on using **GDB** on Linux for both command-line and IDE debugging. +See documentation on `CMake Development`_ for more information. + +.. _`CMake Development`: README.rst + +Linux: Using GDB +================ + +On Linux, the GNU Debugger (**GDB**) is the standard tool for debugging the +CMake test suite. The core process involves launching the ``cmake`` executable +from within GDB with a specific set of arguments that configure and run the +desired test. + +GDB Configuration +----------------- + +For effective debugging, GDB must be configured to handle child processes +correctly, which CMake tests often create. A good practice is to use a local +``.gdbinit`` file in your build directory. This keeps CMake-specific settings +separate from your global configuration. + +**1. Enable Local .gdbinit Files (One-Time Setup)** + +To allow GDB to automatically load configuration from your build directory, +add the following line to your global GDB initialization file at +``$HOME/.gdbinit``. This is a one-time setup that makes future projects easier +to manage. + +.. code-block:: text + + set auto-load local-gdbinit on + +**2. Create a Project-Specific .gdbinit** + +Next, create a ``.gdbinit`` file inside your CMake **build directory**. +This file will contain settings specific to debugging CMake. +To make this easier, you can symlink the template file provided in the CMake +source tree: + +.. code-block:: bash + + # Navigate to your build directory + cd /path/to/your/cmake/build + + # Create a symlink to the template + ln -s $cmake_srcdir/Utilities/gdb/gdbinit-template .gdbinit + +The template contains the essential settings for debugging CMake tests: + +.. code-block:: gdb + + # Allows GDB to follow child processes + set follow-fork-mode child + + # Allows the parent process continue in parallel + set non-stop on + +Debugging from the Command Line +------------------------------- + +To start debugging, first cd to the build directory. Then, launch the +``cmake`` executable using ``gdb --args``, which passes the necessary test +configuration arguments directly to CMake. + +.. note:: + + To get the launch command, run ``ctest -R "RunCMake.$TESTNAME" -VV -N`` + + +The following example runs the ``InstallPackageInfo`` test. + +.. code-block:: bash + + # Define paths to your CMake source and build directories + CMAKE_SOURCE_DIR="$HOME/cmake" + CMAKE_BUILD_DIR="$CMAKE_SOURCE_DIR/build" + + # Define the specific test to run + TEST_NAME="InstallPackageInfo" + + # Navigate to the build directory + cd "$CMAKE_BUILD_DIR" + + # Launch GDB with the appropriate arguments for the test + gdb --args ./bin/cmake \ + "-DCMAKE_MODULE_PATH=$CMAKE_SOURCE_DIR/Tests/RunCMake" \ + "-DRunCMake_GENERATOR=Ninja" \ + "-DRunCMake_SOURCE_DIR=$CMAKE_SOURCE_DIR/Tests/RunCMake/$TEST_NAME" \ + "-DRunCMake_BINARY_DIR=$CMAKE_BUILD_DIR/Tests/RunCMake/$TEST_NAME" \ + "-P" "$CMAKE_SOURCE_DIR/Tests/RunCMake/RunCMakeTest.cmake" + +Once GDB loads, you may set breakpoints (e.g., ``b cmInstallCommand``) and +then start the test by typing ``run``. + +Filtering Tests +--------------- + +Some test suites contain multiple sub-tests. To run only a specific one, +you can use the ``RunCMake_TEST_FILTER`` environment variable. + +For example, to run only the "Metadata" test within the ``InstallPackageInfo`` +suite, you can set the variable before launching GDB: + +.. code-block:: bash + + RunCMake_TEST_FILTER="Metadata" gdb --args ... + +Alternatively, you can set the environment variable from within the +GDB session before running the test: + +.. code-block:: gdb-prompt + + (gdb) set environment RunCMake_TEST_FILTER Metadata + (gdb) run + + +IDE Integration +--------------- + +You can also debug CMake tests directly from your IDE. + +CLion +===== + +If you have configured GDB to auto-load local ``.gdbinit`` files as described +above, CLion will automatically pick up the necessary settings. + +A simple way to debug a test is to modify its ``CTest`` run configuration: + +#. **Select the Test**: In the "Run/Debug Configurations" dialog, find the + ``CTest`` entry for your test (e.g., ``RunCMake.InstallPackageInfo``). +#. **Add CTest Arguments**: In the "CTest arguments" field, add + ``--extra-verbose``. This is helpful for debugging because it prints the + exact command ``CTest`` uses to run the test. +#. **Set Working Directory**: Ensure the "Working Directory" field is set to + ``$CMakeCurrentLocalGenerationDir$``. + +You can now set breakpoints in your code and debug this configuration. + +Visual Studio Code +================== + +Create a ``launch.json`` file in the ``.vscode`` directory of your +CMake **source folder** with the following configuration. This configuration +hardcodes the necessary GDB settings, so it does not depend on an external +``.gdbinit`` file. + +.. code-block:: json + + { + "version": "0.2.0", + "configurations": [ + { + "name": "Debug CMake Test", + "type": "cppdbg", + "request": "launch", + "program": "${workspaceFolder}/build/bin/cmake", + "args": [ + "-DCMAKE_MODULE_PATH=${workspaceFolder}/Tests/RunCMake", + "-DRunCMake_GENERATOR=Ninja", + "-DRunCMake_SOURCE_DIR=${workspaceFolder}/Tests/RunCMake/InstallPackageInfo", + "-DRunCMake_BINARY_DIR=${workspaceFolder}/build/Tests/RunCMake/InstallPackageInfo", + "-P", + "${workspaceFolder}/Tests/RunCMake/RunCMakeTest.cmake" + ], + "stopAtEntry": false, + "cwd": "${workspaceFolder}/build", + "environment": [], + "MIMode": "gdb", + "setupCommands": [ + { + "description": "Enable pretty-printing for gdb", + "text": "-enable-pretty-printing", + "ignoreFailures": true + }, + { + "description": "Follow child processes", + "text": "set follow-fork-mode child", + "ignoreFailures": true + }, + { + "description": "Don't stop the parent process", + "text": "set non-stop on", + "ignoreFailures": true + } + ] + } + ] + } + +.. note:: + + Remember to change the test name (``InstallPackageInfo``) in the ``"args"`` section to the specific test you want to debug.
diff --git a/Help/dev/experimental.rst b/Help/dev/experimental.rst index 81ddc8c..3d52871 100644 --- a/Help/dev/experimental.rst +++ b/Help/dev/experimental.rst
@@ -39,40 +39,25 @@ using the ``CMAKE_EXPORT_FIND_PACKAGE_NAME`` variable and/or ``EXPORT_FIND_PACKAGE_NAME`` target property. -Export |CPS| Package Information -================================ +Export |CPS| Package Information for ``install(EXPORT)`` +======================================================== In order to activate support for this experimental feature, set -* variable ``CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_INFO`` to -* value ``b80be207-778e-46ba-8080-b23bba22639e``. +* variable ``CMAKE_EXPERIMENTAL_MAPPED_PACKAGE_INFO`` to +* value ``ababa1b5-7099-495f-a9cd-e22d38f274f2``. -This UUID may change in future versions of CMake. Be sure to use the value +These UUIDs may change in future versions of CMake. Be sure to use the values documented here by the source tree of the version of CMake with which you are experimenting. When activated, this experimental feature provides the following: -* The experimental ``install(PACKAGE_INFO)`` command is available to export - package information in the |CPS|_ format. +* Setting ``CMAKE_INSTALL_EXPORTS_AS_PACKAGE_INFO`` enables generation of + package information in the |CPS|_ format via the ``install(EXPORT)`` command. -Find/Import |CPS| Packages -========================== - -In order to activate support for this experimental feature, set - -* variable ``CMAKE_EXPERIMENTAL_FIND_CPS_PACKAGES`` to -* value ``e82e467b-f997-4464-8ace-b00808fff261``. - -This UUID may change in future versions of CMake. Be sure to use the value -documented here by the source tree of the version of CMake with which you are -experimenting. - -When activated, this experimental feature provides the following: - -* The :command:`find_package` command will also search for packages which are - described using |CPS|_. Refer to the :command:`find_package` documentation - for details. +.. _CPS: https://cps-org.github.io/cps/ +.. |CPS| replace:: Common Package Specification C++ ``import std`` support ========================== @@ -81,24 +66,21 @@ set * variable ``CMAKE_EXPERIMENTAL_CXX_IMPORT_STD`` to -* value ``d0edc3af-4c50-42ea-a356-e2862fe7a444``. +* value ``451f2fe2-a8a2-47c3-bc32-94786d8fc91b``. This UUID may change in future versions of CMake. Be sure to use the value documented here by the source tree of the version of CMake with which you are experimenting. It must be set before the ``CXX`` toolchain is discovered by -CMake, usually as part of a :command:`project` call. +CMake, usually as part of a ``project()`` call. When activated, this experimental feature provides the following: -* The :prop_tgt:`CXX_MODULE_STD` target property and its initializing variable - :variable:`CMAKE_CXX_MODULE_STD`. +* The ``CXX_MODULE_STD`` target property and its initializing variable + ``CMAKE_CXX_MODULE_STD``. * Targets with the property set to a true value and at least ``cxx_std_23`` may use ``import std;`` in any scanned C++ source file. -.. _CPS: https://cps-org.github.io/cps/ -.. |CPS| replace:: Common Package Specification - Build database support ====================== @@ -120,22 +102,33 @@ * Targets with the property set to a true value will have their C++ build information exported to the build database. -Instrumentation -=============== +Software Bill Of Materials |SBOM| +================================= -In order to activate support for the :command:`cmake_instrumentation` command, +In order to activate support for the :command:`install(SBOM)` command, set -* variable ``CMAKE_EXPERIMENTAL_INSTRUMENTATION`` to -* value ``a37d1069-1972-4901-b9c9-f194aaf2b6e0``. +* variable ``CMAKE_EXPERIMENTAL_GENERATE_SBOM`` to +* value ``ca494ed3-b261-4205-a01f-603c95e4cae0``. -To enable instrumentation at the user-level, files should be placed under -either -``<CMAKE_CONFIG_DIR>/instrumentation-a37d1069-1972-4901-b9c9-f194aaf2b6e0`` or -``<CMAKE_BINARY_DIR>/.cmake/instrumentation-a37d1069-1972-4901-b9c9-f194aaf2b6e0``. +This UUID may change in future versions of CMake. Be sure to use the value +documented here by the source tree of the version of CMake with which you are +experimenting. -To include instrumentation data in CTest XML files (for submission to CDash), -you need to set the following environment variables: +When activated, this experimental feature provides the following: -* ``CTEST_USE_INSTRUMENTATION=1`` -* ``CTEST_EXPERIMENTAL_INSTRUMENTATION=a37d1069-1972-4901-b9c9-f194aaf2b6e0`` +* The experimental ``export(SBOM)`` and ``install(SBOM)`` commands are + available to generate a Software Bill of Materials or "SBOM" for the current + project. See :command:`install(SBOM)` for a complete overview of the command. + +Rust Support +============ + +In order to activate support for Rust, set + +* variable ``CMAKE_EXPERIMENTAL_RUST`` to +* value ``3cc9b32c-47d3-4056-8953-d74e69fc0d6c``. + +This UUID may change in future versions of CMake. Be sure to use the value +documented here by the source tree of the version of CMake with which you are +experimenting.
diff --git a/Help/dev/maint.rst b/Help/dev/maint.rst index 24ddb9a..787cd23 100644 --- a/Help/dev/maint.rst +++ b/Help/dev/maint.rst
@@ -263,12 +263,12 @@ set(CMake_VERSION_PATCH 0) set(CMake_VERSION_RC 0) -Replace uses of ``DEVEL_CMAKE_VERSION`` in the source tree with +Replace uses of ``CMake_VERSION_DEVEL`` in the source tree with the literal release version number string ``"$major.$minor.0"``: .. code-block:: shell - $EDITOR $(git grep -l DEVEL_CMAKE_VERSION) + $EDITOR $(git grep -l CMake_VERSION_DEVEL) Commit with a message such as:: @@ -302,7 +302,7 @@ set(CMake_VERSION_PATCH $date) #set(CMake_VERSION_RC 0) -Update ``Help/manual/cmake-policies.7.rst`` to set the ``...<max>`` +Update ``Help/manual/cmake-policies.7.rst`` to set the ``...<policy_max>`` example to ``...$major.$minor``: .. code-block:: cmake
diff --git a/Help/dev/source.rst b/Help/dev/source.rst index fd8597d..3aad194 100644 --- a/Help/dev/source.rst +++ b/Help/dev/source.rst
@@ -61,6 +61,11 @@ be used in place of the standard ones when extended features are needed. For example ``<cm/memory>`` can be used in place of ``<memory>``. +The class ``cm::filesystem::path``, from the ``<cm/filesystem>`` header, is +fully compatible with the class ``std::filesystem::path`` regarding the API but +is a specific implementation (derived from the ``std::filesystem::path`` class) +to ensure a behavior independent of the current locale. + Available features are: * From ``C++14``: @@ -111,7 +116,8 @@ ``cm::shared_lock`` * ``<cm/type_traits>``: - ``cm::enable_if_t`` + ``cm::conditional_t``, ``cm::decay_t``, ``cm::enable_if_t``, + ``cm::remove_cv_t``, ``cm::remove_reference_t`` * ``<cm/unordered_map>``: ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``, @@ -169,7 +175,7 @@ * ``<cm/type_traits>``: ``cm::bool_constant``, ``cm::invoke_result_t``, ``cm::invoke_result``, - ``cm::void_t`` + ``cm::is_same_v``, ``cm::void_t`` * ``<cm/unordered_map>``: ``cm::size``, ``cm::empty``, ``cm::data`` @@ -245,7 +251,7 @@ * ``<cmext/iterator>``: - * ``cm::is_terator``: + * ``cm::is_iterator``: Checks if a type is an iterator type. * ``cm::is_input_iterator``:
diff --git a/Help/envvar/CMAKE_AUTOGEN_INTERMEDIATE_DIR_STRATEGY.rst b/Help/envvar/CMAKE_AUTOGEN_INTERMEDIATE_DIR_STRATEGY.rst new file mode 100644 index 0000000..1aab196 --- /dev/null +++ b/Help/envvar/CMAKE_AUTOGEN_INTERMEDIATE_DIR_STRATEGY.rst
@@ -0,0 +1,10 @@ +CMAKE_AUTOGEN_INTERMEDIATE_DIR_STRATEGY +--------------------------------------- + +.. versionadded:: 4.2 + +.. include:: include/ENV_VAR.rst + +``CMAKE_AUTOGEN_INTERMEDIATE_DIR_STRATEGY`` is a string specifying the +strategy to use for autogen-related target intermediate directories. It +initializes the :variable:`CMAKE_AUTOGEN_INTERMEDIATE_DIR_STRATEGY` variable.
diff --git a/Help/envvar/CMAKE_CONFIG_DIR.rst b/Help/envvar/CMAKE_CONFIG_DIR.rst index 8f93a56..ce812db 100644 --- a/Help/envvar/CMAKE_CONFIG_DIR.rst +++ b/Help/envvar/CMAKE_CONFIG_DIR.rst
@@ -6,7 +6,7 @@ .. include:: include/ENV_VAR.rst Specify a CMake user-wide configuration directory for -:manual:`cmake-file-api(7)` queries. +:manual:`cmake-file-api(7)` and :manual:`cmake-instrumentation(7)` queries. If this environment variable is not set, the default user-wide configuration directory is platform-specific:
diff --git a/Help/envvar/CMAKE_FASTBUILD_VERBOSE_GENERATOR.rst b/Help/envvar/CMAKE_FASTBUILD_VERBOSE_GENERATOR.rst new file mode 100644 index 0000000..4017e59 --- /dev/null +++ b/Help/envvar/CMAKE_FASTBUILD_VERBOSE_GENERATOR.rst
@@ -0,0 +1,10 @@ +CMAKE_FASTBUILD_VERBOSE_GENERATOR +--------------------------------- + +.. versionadded:: 4.2 + +.. include:: include/ENV_VAR.rst + +The ``CMAKE_FASTBUILD_VERBOSE_GENERATOR`` environment variable specifies a custom default +value for the :variable:`CMAKE_FASTBUILD_VERBOSE_GENERATOR` variable in place of the +default values specified by CMake itself.
diff --git a/Help/envvar/CMAKE_INTERMEDIATE_DIR_STRATEGY.rst b/Help/envvar/CMAKE_INTERMEDIATE_DIR_STRATEGY.rst new file mode 100644 index 0000000..a3a01a7 --- /dev/null +++ b/Help/envvar/CMAKE_INTERMEDIATE_DIR_STRATEGY.rst
@@ -0,0 +1,10 @@ +CMAKE_INTERMEDIATE_DIR_STRATEGY +------------------------------- + +.. versionadded:: 4.2 + +.. include:: include/ENV_VAR.rst + +``CMAKE_INTERMEDIATE_DIR_STRATEGY`` is a string specifying the strategy to use +for target intermediate directories. It initializes the +:variable:`CMAKE_INTERMEDIATE_DIR_STRATEGY` variable.
diff --git a/Help/envvar/CTEST_PARALLEL_LEVEL.rst b/Help/envvar/CTEST_PARALLEL_LEVEL.rst index 798c79b..ba8ae4f 100644 --- a/Help/envvar/CTEST_PARALLEL_LEVEL.rst +++ b/Help/envvar/CTEST_PARALLEL_LEVEL.rst
@@ -14,7 +14,6 @@ parallelism, or unbounded parallelism, respectively, as documented by the :option:`ctest --parallel` option. - On Windows, environment variables cannot be set to an empty string. CTest will interpret a whitespace-only string as empty. In CMake 3.28 and earlier, an empty or ``0`` value was equivalent to ``1``.
diff --git a/Help/envvar/CTEST_USE_INSTRUMENTATION.rst b/Help/envvar/CTEST_USE_INSTRUMENTATION.rst index 6e33845..5ee3785 100644 --- a/Help/envvar/CTEST_USE_INSTRUMENTATION.rst +++ b/Help/envvar/CTEST_USE_INSTRUMENTATION.rst
@@ -1,15 +1,10 @@ CTEST_USE_INSTRUMENTATION ------------------------- -.. versionadded:: 4.0 +.. versionadded:: 4.3 .. include:: include/ENV_VAR.rst -.. note:: - - This feature is only available when experimental support for instrumentation - has been enabled by the ``CMAKE_EXPERIMENTAL_INSTRUMENTATION`` gate. - -Setting this environment variable enables +Setting this environment variable to ``1``, ``True``, or ``ON`` enables :manual:`instrumentation <cmake-instrumentation(7)>` for CTest in :ref:`Dashboard Client` mode.
diff --git a/Help/envvar/CTEST_USE_VERBOSE_INSTRUMENTATION.rst b/Help/envvar/CTEST_USE_VERBOSE_INSTRUMENTATION.rst index 95053e4..a1dd5c7 100644 --- a/Help/envvar/CTEST_USE_VERBOSE_INSTRUMENTATION.rst +++ b/Help/envvar/CTEST_USE_VERBOSE_INSTRUMENTATION.rst
@@ -1,17 +1,13 @@ CTEST_USE_VERBOSE_INSTRUMENTATION --------------------------------- -.. versionadded:: 4.0 +.. versionadded:: 4.3 .. include:: include/ENV_VAR.rst -.. note:: - - This feature is only available when experimental support for instrumentation - has been enabled by the ``CMAKE_EXPERIMENTAL_INSTRUMENTATION`` gate. - -Setting this environment variable causes CTest to report the full -command line (including arguments) to CDash for each instrumented command. -By default, CTest truncates the command line at the first space. +Setting this environment variable to ``1``, ``True``, or ``ON`` causes CTest to +report the full command line (including arguments) to CDash for each +instrumented command. By default, CTest truncates the command line at the first +space. See also :envvar:`CTEST_USE_INSTRUMENTATION`
diff --git a/Help/generator/FASTBuild.rst b/Help/generator/FASTBuild.rst new file mode 100644 index 0000000..f16b166 --- /dev/null +++ b/Help/generator/FASTBuild.rst
@@ -0,0 +1,111 @@ +FASTBuild +========= + +.. versionadded:: 4.2 + +Generates a ``fbuild.bff`` file, which can be used to build the project with +`FASTBuild <https://www.fastbuild.org/docs/home.html>`_. + +Usage +----- + +Specify the generator when invoking :manual:`cmake(1)`: + +.. code-block:: shell + + cmake [<options>] -G FASTBuild -B <path-to-build> [-S <path-to-source>] + +This writes a FASTBuild configuration file named ``fbuild.bff`` into +``<path-to-build>``. + +.. note:: + + This generator also produces IDE project files for Visual Studio and Xcode, + which are placed under: + + * ``<path-to-build>/VisualStudio`` – Visual Studio solution and projects + * ``<path-to-build>/XCode`` – Xcode workspace and projects + + These IDE files can be generated by building ``xcode`` or ``solution`` targets + and will build using FASTBuild as the backend. + +Caching +------- + +To enable FASTBuild caching, set the cache path using the +:variable:`CMAKE_FASTBUILD_CACHE_PATH` variable or the +``FASTBUILD_CACHE_PATH`` environment variable. + +Then build with the ``-cache`` flag: + +.. code-block:: console + + cmake --build <path-to-build> -- -cache + +Compiler Behavior Variables +--------------------------- + +The following variables control how compiler nodes are emitted in the generated +``fbuild.bff``. These settings may affect build determinism, debug info paths, +include handling, and compiler argument formatting: + +* :variable:`CMAKE_FASTBUILD_ALLOW_RESPONSE_FILE` +* :variable:`CMAKE_FASTBUILD_CLANG_GCC_UPDATE_XLANG_ARG` +* :variable:`CMAKE_FASTBUILD_CLANG_REWRITE_INCLUDES` +* :variable:`CMAKE_FASTBUILD_COMPILER_EXTRA_FILES` +* :variable:`CMAKE_FASTBUILD_FORCE_RESPONSE_FILE` +* :variable:`CMAKE_FASTBUILD_SOURCE_MAPPING` +* :variable:`CMAKE_FASTBUILD_USE_DETERMINISTIC_PATHS` +* :variable:`CMAKE_FASTBUILD_USE_LIGHTCACHE` +* :variable:`CMAKE_FASTBUILD_USE_RELATIVE_PATHS` + +Configuration Variables +----------------------- + +The following variables can be used to configure this generator: + +* :variable:`CMAKE_FASTBUILD_CACHE_PATH` +* :variable:`CMAKE_FASTBUILD_CAPTURE_SYSTEM_ENV` +* :variable:`CMAKE_FASTBUILD_ENV_OVERRIDES` +* :variable:`CMAKE_FASTBUILD_IDE_ARGS` +* :variable:`CMAKE_FASTBUILD_TRACK_BYPRODUCTS_AS_OUTPUT` +* :variable:`CMAKE_FASTBUILD_VERBOSE_GENERATOR` + +Target Properties +----------------- + +The following target properties can be used to fine-tune behavior on a +per-target basis: + +* :prop_tgt:`FASTBUILD_CACHING` – + disables caching for a specific target. +* :prop_tgt:`FASTBUILD_DISTRIBUTION` – + disables distributed compilation for a specific target. + +Notes +----- + +* This generator does not support directories as outputs of custom commands. + If you do specify a directory as an output, it should be marked with the + ``SYMBOLIC`` property to avoid incorrect behavior. +* It is highly advised to use custom commands with only one output. + If multiple outputs are specified, the generator will emit an additional + rule to check the outputs at build time. This adds overhead and is necessary + because FASTBuild natively supports only a single output per custom step. + +Example +------- + +.. code-block:: shell + + cmake [<options>] -G FASTBuild -B <path-to-build> -DCMAKE_BUILD_TYPE=Release + cmake --build <path-to-build> --target my_app + +This generates ``fbuild.bff`` in ``<path-to-build>`` and uses FASTBuild +to build the ``my_app`` target. + +See Also +-------- + +* :manual:`cmake-generators(7)` +* `FASTBuild Documentation <https://www.fastbuild.org/docs/documentation.html>`_
diff --git a/Help/generator/Visual Studio 10 2010.rst b/Help/generator/Visual Studio 10 2010.rst index 8b7e31d..08940d2 100644 --- a/Help/generator/Visual Studio 10 2010.rst +++ b/Help/generator/Visual Studio 10 2010.rst
@@ -3,7 +3,7 @@ Removed. This once generated Visual Studio 10 2010 project files, but the generator has been removed since CMake 3.25. It is still possible -to build with the VS 10 2010 toolset by also installing VS 2015 (or above) -and using the :generator:`Visual Studio 14 2015` (or above) generator with +to build with the VS 10 2010 toolset by also installing VS 2017 (or above) +and using the :generator:`Visual Studio 15 2017` (or above) generator with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v100``, or by using the :generator:`NMake Makefiles` generator.
diff --git a/Help/generator/Visual Studio 11 2012.rst b/Help/generator/Visual Studio 11 2012.rst index 99048bd..8c0f37c 100644 --- a/Help/generator/Visual Studio 11 2012.rst +++ b/Help/generator/Visual Studio 11 2012.rst
@@ -3,7 +3,7 @@ Removed. This once generated Visual Studio 11 2012 project files, but the generator has been removed since CMake 3.28. It is still possible -to build with the VS 11 2012 toolset by also installing VS 2015 (or above) -and using the :generator:`Visual Studio 14 2015` (or above) generator with +to build with the VS 11 2012 toolset by also installing VS 2017 (or above) +and using the :generator:`Visual Studio 15 2017` (or above) generator with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v110``, or by using the :generator:`NMake Makefiles` generator.
diff --git a/Help/generator/Visual Studio 12 2013.rst b/Help/generator/Visual Studio 12 2013.rst index 6589072..1724c0c 100644 --- a/Help/generator/Visual Studio 12 2013.rst +++ b/Help/generator/Visual Studio 12 2013.rst
@@ -3,7 +3,7 @@ Removed. This once generated Visual Studio 12 2013 project files, but the generator has been removed since CMake 3.31. It is still possible -to build with the VS 12 2013 toolset by also installing VS 2015 (or above) -and using the :generator:`Visual Studio 14 2015` (or above) generator with +to build with the VS 12 2013 toolset by also installing VS 2017 (or above) +and using the :generator:`Visual Studio 15 2017` (or above) generator with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v120``, or by using the :generator:`NMake Makefiles` generator.
diff --git a/Help/generator/Visual Studio 14 2015.rst b/Help/generator/Visual Studio 14 2015.rst index a491193..7e9035d 100644 --- a/Help/generator/Visual Studio 14 2015.rst +++ b/Help/generator/Visual Studio 14 2015.rst
@@ -1,6 +1,14 @@ Visual Studio 14 2015 --------------------- +.. deprecated:: 4.2 + + This generator is deprecated and will be removed in a future version + of CMake. It will still be possible to build with VS 14 2015 tools + using the :generator:`Visual Studio 15 2017` (or above) generator + with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v140``, or by + using the :generator:`NMake Makefiles` generator. + .. versionadded:: 3.1 Generates Visual Studio 14 (VS 2015) project files.
diff --git a/Help/generator/Visual Studio 18 2026.rst b/Help/generator/Visual Studio 18 2026.rst new file mode 100644 index 0000000..80127d0 --- /dev/null +++ b/Help/generator/Visual Studio 18 2026.rst
@@ -0,0 +1,47 @@ +Visual Studio 18 2026 +--------------------- + +.. versionadded:: 4.2 + +Generates Visual Studio 18 (VS 2026) 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 2026 supports multiple installations on the same machine. The +:variable:`CMAKE_GENERATOR_INSTANCE` variable may be used to select one. + +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 :option:`cmake -A` option, to specify a target platform +name (architecture). For example: + +* ``cmake -G "Visual Studio 18 2026" -A Win32`` +* ``cmake -G "Visual Studio 18 2026" -A x64`` +* ``cmake -G "Visual Studio 18 2026" -A ARM`` +* ``cmake -G "Visual Studio 18 2026" -A ARM64`` + +Toolset Selection +^^^^^^^^^^^^^^^^^ + +The ``v145`` toolset that comes with VS 18 2026 is selected by default. +The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps +via the :option:`cmake -T` option, to specify another toolset. + +.. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace:: + By default this generator uses the 64-bit variant on x64 hosts and + the 32-bit variant otherwise. + +.. include:: include/VS_TOOLSET_HOST_ARCH.rst
diff --git a/Help/generator/Visual Studio 9 2008.rst b/Help/generator/Visual Studio 9 2008.rst index a5d953a..1e2730c 100644 --- a/Help/generator/Visual Studio 9 2008.rst +++ b/Help/generator/Visual Studio 9 2008.rst
@@ -4,6 +4,6 @@ Removed. This once generated Visual Studio 9 2008 project files, but the generator has been removed since CMake 3.30. It is still possible to build with the VS 9 2008 toolset by also installing VS 10 2010 and -VS 2015 (or above) and using the :generator:`Visual Studio 14 2015` +VS 2017 (or above) and using the :generator:`Visual Studio 15 2017` generator (or above) with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v90``, or by using the :generator:`NMake Makefiles` generator.
diff --git a/Help/guide/ide-integration/index.rst b/Help/guide/ide-integration/index.rst index 04ae7f9..f335e1f 100644 --- a/Help/guide/ide-integration/index.rst +++ b/Help/guide/ide-integration/index.rst
@@ -147,7 +147,7 @@ .. _CLion: https://www.jetbrains.com/clion/ .. _KDevelop: https://kdevelop.org/ -.. _QtCreator: https://www.qt.io/product/development-tools +.. _QtCreator: https://www.qt.io/development/tools .. _Vim: https://www.vim.org/ .. _Visual Studio: https://visualstudio.microsoft.com/ .. _VSCode: https://code.visualstudio.com/
diff --git a/Help/guide/tutorial/A Basic Starting Point.rst b/Help/guide/tutorial/A Basic Starting Point.rst index b36e2e7..674bf52 100644 --- a/Help/guide/tutorial/A Basic Starting Point.rst +++ b/Help/guide/tutorial/A Basic Starting Point.rst
@@ -1,473 +1,10 @@ Step 1: A Basic Starting Point ============================== -Where do I start with CMake? This step will provide an introduction to some of -CMake's basic syntax, commands, and variables. As these concepts are -introduced, we will work through three exercises and create a simple CMake -project. +This page was once part of an older version of the CMake tutorial which +last appeared in CMake 4.1. See the current tutorial version :guide:`here <CMake Tutorial>`. -Each exercise in this step will start with some background information. Then, a -goal and list of helpful resources are provided. Each file in the -``Files to Edit`` section is in the ``Step1`` directory and contains one or -more ``TODO`` comments. Each ``TODO`` represents a line or two of code to -change or add. The ``TODO`` s are intended to be completed in numerical order, -first complete ``TODO 1`` then ``TODO 2``, etc. The ``Getting Started`` -section will give some helpful hints and guide you through the exercise. Then -the ``Build and Run`` section will walk step-by-step through how to build and -test the exercise. Finally, at the end of each exercise the intended solution -is discussed. +.. only:: cmakeorg -Also note that each step in the tutorial builds on the previous. For example, -the starting code for ``Step2`` is the complete solution to ``Step1``. - -Exercise 1 - Building a Basic Project -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The most basic CMake project is an executable built from a single source code -file. For simple projects like this, a ``CMakeLists.txt`` file with three -commands is all that is required. - -**Note:** Although upper, lower and mixed case commands are supported by CMake, -lower case commands are preferred and will be used throughout the tutorial. - -Any project's top most CMakeLists.txt must start by specifying a minimum CMake -version using the :command:`cmake_minimum_required` command. This establishes -policy settings and ensures that the following CMake functions are run with a -compatible version of CMake. - -To start a project, we use the :command:`project` command to set the project -name. This call is required with every project and should be called soon after -:command:`cmake_minimum_required`. As we will see later, this command can -also be used to specify other project level information such as the language -or version number. - -Finally, the :command:`add_executable` command tells CMake to create an -executable using the specified source code files. - -Goal ----- - -Understand how to create a simple CMake project. - -Helpful Resources ------------------ - -* :command:`add_executable` -* :command:`cmake_minimum_required` -* :command:`project` - -Files to Edit -------------- - -* ``CMakeLists.txt`` - -Getting Started ----------------- - -The source code for ``tutorial.cxx`` is provided in the -``Help/guide/tutorial/Step1`` directory and can be used to compute the square -root of a number. This file does not need to be edited in this step. - -In the same directory is a ``CMakeLists.txt`` file which you will complete. -Start with ``TODO 1`` and work through ``TODO 3``. - -Build and Run -------------- - -Once ``TODO 1`` through ``TODO 3`` have been completed, we are ready to build -and run our project! First, run the :manual:`cmake <cmake(1)>` executable or the -:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it -with your chosen build tool. - -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 that build directory and run -:manual:`cmake <cmake(1)>` 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 . - -For multi-config generators (e.g. Visual Studio), first navigate to the -appropriate subdirectory, for example: - -.. code-block:: console - - cd Debug - -Finally, try to use the newly built ``Tutorial``: - -.. code-block:: console - - Tutorial 4294967296 - Tutorial 10 - Tutorial - - -**Note:** Depending on the shell, the correct syntax may be ``Tutorial``, -``./Tutorial`` or ``.\Tutorial``. For simplicity, the exercises will use -``Tutorial`` throughout. - -Solution --------- - -As mentioned above, a three line ``CMakeLists.txt`` is all that we need to get -up and running. The first line is to use :command:`cmake_minimum_required` to -set the CMake version as follows: - -.. raw:: html - - <details><summary>TODO 1: Click to show/hide answer</summary> - -.. literalinclude:: Step2/CMakeLists.txt - :caption: TODO 1: CMakeLists.txt - :name: CMakeLists.txt-cmake_minimum_required - :language: cmake - :end-before: # set the project name and version - -.. raw:: html - - </details> - -The next step to make a basic project is to use the :command:`project` -command as follows to set the project name: - -.. raw:: html - - <details><summary>TODO 2: Click to show/hide answer</summary> - -.. code-block:: cmake - :caption: TODO 2: CMakeLists.txt - :name: CMakeLists.txt-project - - project(Tutorial) - -.. raw:: html - - </details> - -The last command to call for a basic project is -:command:`add_executable`. We call it as follows: - -.. raw:: html - - <details><summary>TODO 3: Click to show/hide answer</summary> - -.. literalinclude:: Step2/CMakeLists.txt - :caption: TODO 3: CMakeLists.txt - :name: CMakeLists.txt-add_executable - :language: cmake - :start-after: # add the executable - :end-before: # TODO 3: - -.. raw:: html - - </details> - -Exercise 2 - Specifying the C++ Standard -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -CMake has some special variables that are either created behind the scenes or -have meaning to CMake when set by project code. Many of these variables start -with ``CMAKE_``. Avoid this naming convention when creating variables for your -projects. Two of these special user settable variables are -:variable:`CMAKE_CXX_STANDARD` and :variable:`CMAKE_CXX_STANDARD_REQUIRED`. -These may be used together to specify the C++ standard needed to build the -project. - -Goal ----- - -Add a feature that requires C++11. - -Helpful Resources ------------------ - -* :variable:`CMAKE_CXX_STANDARD` -* :variable:`CMAKE_CXX_STANDARD_REQUIRED` -* :command:`set` - -Files to Edit -------------- - -* ``CMakeLists.txt`` -* ``tutorial.cxx`` - -Getting Started ---------------- - -Continue editing files in the ``Step1`` directory. Start with ``TODO 4`` and -complete through ``TODO 6``. - -First, edit ``tutorial.cxx`` by adding a feature that requires C++11. Then -update ``CMakeLists.txt`` to require C++11. - -Build and Run -------------- - -Let's build our project again. Since we already created a build directory and -ran CMake for Exercise 1, we can skip to the build step: - -.. code-block:: console - - cd Step1_build - cmake --build . - -Now we can try to use the newly built ``Tutorial`` with same commands as -before: - -.. code-block:: console - - Tutorial 4294967296 - Tutorial 10 - Tutorial - -Solution --------- - -We start by adding some C++11 features to our project by replacing -``atof`` with ``std::stod`` in ``tutorial.cxx``. This looks like -the following: - -.. raw:: html - - <details><summary>TODO 4: Click to show/hide answer</summary> - -.. literalinclude:: Step2/tutorial.cxx - :caption: TODO 4: tutorial.cxx - :name: tutorial.cxx-cxx11 - :language: c++ - :start-after: // convert input to double - :end-before: // TODO 6: - -.. raw:: html - - </details> - -To complete ``TODO 5``, simply remove ``#include <cstdlib>``. - -We will need to explicitly state in the CMake code that it should use the -correct flags. One way to enable support for a specific C++ standard in CMake -is by using the :variable:`CMAKE_CXX_STANDARD` variable. For this tutorial, set -the :variable:`CMAKE_CXX_STANDARD` variable in the ``CMakeLists.txt`` file to -``11`` and :variable:`CMAKE_CXX_STANDARD_REQUIRED` to ``True``. Make sure to -add the :variable:`CMAKE_CXX_STANDARD` declarations above the call to -:command:`add_executable`. - -.. raw:: html - - <details><summary>TODO 6: Click to show/hide answer</summary> - -.. literalinclude:: Step2/CMakeLists.txt - :caption: TODO 6: CMakeLists.txt - :name: CMakeLists.txt-CXX_STANDARD - :language: cmake - :start-after: # specify the C++ standard - :end-before: # configure a header file - -.. raw:: html - - </details> - -Exercise 3 - Adding a Version Number and Configured Header File -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Sometimes it may be useful to have a variable that is defined in your -``CMakelists.txt`` file also be available in your source code. In this case, we -would like to print the project version. - -One way to accomplish this is by using a configured header file. We create an -input file with one or more variables to replace. These variables have special -syntax which looks like ``@VAR@``. -Then, we use the :command:`configure_file` command to copy the input file to a -given output file and replace these variables with the current value of ``VAR`` -in the ``CMakelists.txt`` file. - -While we could edit the version directly in the source code, using this -feature is preferred since it creates a single source of truth and avoids -duplication. - -Goal ----- - -Define and report the project's version number. - -Helpful Resources ------------------ - -* :variable:`<PROJECT-NAME>_VERSION_MAJOR` -* :variable:`<PROJECT-NAME>_VERSION_MINOR` -* :command:`configure_file` -* :command:`target_include_directories` - -Files to Edit -------------- - -* ``CMakeLists.txt`` -* ``tutorial.cxx`` -* ``TutorialConfig.h.in`` - -Getting Started ---------------- - -Continue to edit files from ``Step1``. Start on ``TODO 7`` and complete through -``TODO 12``. In this exercise, we start by adding a project version number in -``CMakeLists.txt``. In that same file, use :command:`configure_file` to copy a -given input file to an output file and substitute some variable values in the -input file content. - -Next, create an input header file ``TutorialConfig.h.in`` defining version -numbers which will accept variables passed from :command:`configure_file`. - -Finally, update ``tutorial.cxx`` to print out its version number. - -Build and Run -------------- - -Let's build our project again. As before, we already created a build directory -and ran CMake so we can skip to the build step: - -.. code-block:: console - - cd Step1_build - cmake --build . - -Verify that the version number is now reported when running the executable -without any arguments. - -Solution --------- - -In this exercise, we improve our executable by printing a version number. -While we could do this exclusively in the source code, using ``CMakeLists.txt`` -lets us maintain a single source of data for the version number. - -First, we modify the ``CMakeLists.txt`` file to use the -:command:`project` command to set both the project name and version number. -When the :command:`project` command is called, CMake defines -``Tutorial_VERSION_MAJOR`` and ``Tutorial_VERSION_MINOR`` behind the scenes. - -.. raw:: html - - <details><summary>TODO 7: Click to show/hide answer</summary> - -.. literalinclude:: Step2/CMakeLists.txt - :caption: TODO 7: CMakeLists.txt - :name: CMakeLists.txt-project-VERSION - :language: cmake - :start-after: # set the project name and version - :end-before: # specify the C++ standard - -.. raw:: html - - </details> - -Then we used :command:`configure_file` to copy the input file with the -specified CMake variables replaced: - -.. raw:: html - - <details><summary>TODO 8: Click to show/hide answer</summary> - -.. literalinclude:: Step2/CMakeLists.txt - :caption: TODO 8: CMakeLists.txt - :name: CMakeLists.txt-configure_file - :language: cmake - :start-after: # to the source code - :end-before: # TODO 2: - -.. raw:: html - - </details> - -Since the configured file will be written into the project binary -directory, we must add that directory to the list of paths to search for -include files. - -**Note:** Throughout this tutorial, we will refer to the project build and -the project binary directory interchangeably. These are the same and are not -meant to refer to a ``bin/`` directory. - -We used :command:`target_include_directories` to specify -where the executable target should look for include files. - -.. raw:: html - - <details><summary>TODO 9: Click to show/hide answer</summary> - -.. literalinclude:: Step2/CMakeLists.txt - :caption: TODO 9: CMakeLists.txt - :name: CMakeLists.txt-target_include_directories - :language: cmake - :start-after: # so that we will find TutorialConfig.h - -.. raw:: html - - </details> - -``TutorialConfig.h.in`` is the input header file to be configured. -When :command:`configure_file` is called from our ``CMakeLists.txt``, the -values for ``@Tutorial_VERSION_MAJOR@`` and ``@Tutorial_VERSION_MINOR@`` will -be replaced with the corresponding version numbers from the project in -``TutorialConfig.h``. - -.. raw:: html - - <details><summary>TODO 10: Click to show/hide answer</summary> - -.. literalinclude:: Step2/TutorialConfig.h.in - :caption: TODO 10: TutorialConfig.h.in - :name: TutorialConfig.h.in - :language: c++ - -.. raw:: html - - </details> - -Next, we need to modify ``tutorial.cxx`` to include the configured header file, -``TutorialConfig.h``. - -.. raw:: html - - <details><summary>TODO 11: Click to show/hide answer</summary> - -.. code-block:: c++ - :caption: TODO 11: tutorial.cxx - - #include "TutorialConfig.h" - -.. raw:: html - - </details> - -Finally, we print out the executable name and version number by updating -``tutorial.cxx`` as follows: - -.. raw:: html - - <details><summary>TODO 12: Click to show/hide answer</summary> - -.. literalinclude:: Step2/tutorial.cxx - :caption: TODO 12 : tutorial.cxx - :name: tutorial.cxx-print-version - :language: c++ - :start-after: { - :end-before: // convert input to double - -.. raw:: html - - </details> + To see the older version, follow `this link <https://cmake.org/cmake/help/v4.1/guide/tutorial/A%20Basic%20Starting%20Point.html>`_ + or select the drop-down in the page header.
diff --git a/Help/guide/tutorial/Adding Export Configuration.rst b/Help/guide/tutorial/Adding Export Configuration.rst index c4ab476..2708846 100644 --- a/Help/guide/tutorial/Adding Export Configuration.rst +++ b/Help/guide/tutorial/Adding Export Configuration.rst
@@ -1,140 +1,10 @@ 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. +This page was once part of an older version of the CMake tutorial which +last appeared in CMake 4.1. See the current tutorial version :guide:`here <CMake Tutorial>`. -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. +.. only:: cmakeorg -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 libs - -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. - -CMake is telling you that during the generation of 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 :command:`find_package`, documenting 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 ``MathFunctionsTargets.cmake``, allowing the -configured ``MathFunctionsConfig.cmake`` in the build directory to be used by -other projects, without needing it to be installed. + To see the older version, follow `this link <https://cmake.org/cmake/help/v4.1/guide/tutorial/Adding%20Export%20Configuration.html>`_ + or select the drop-down in the page header.
diff --git a/Help/guide/tutorial/Adding Generator Expressions.rst b/Help/guide/tutorial/Adding Generator Expressions.rst index d2dddf7..f36f5b9 100644 --- a/Help/guide/tutorial/Adding Generator Expressions.rst +++ b/Help/guide/tutorial/Adding Generator Expressions.rst
@@ -1,168 +1,10 @@ Step 4: Adding Generator Expressions -===================================== +==================================== -:manual:`Generator expressions <cmake-generator-expressions(7)>` are evaluated -during build system generation to produce information specific to each build -configuration. +This page was once part of an older version of the CMake tutorial which +last appeared in CMake 4.1. See the current tutorial version :guide:`here <CMake Tutorial>`. -:manual:`Generator expressions <cmake-generator-expressions(7)>` are allowed in -the context of many target properties, such as :prop_tgt:`LINK_LIBRARIES`, -:prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_DEFINITIONS` and others. -They may also be used when using commands to populate those properties, such as -:command:`target_link_libraries`, :command:`target_include_directories`, -:command:`target_compile_definitions` and others. +.. only:: cmakeorg -:manual:`Generator expressions <cmake-generator-expressions(7)>` may be used -to enable conditional linking, conditional definitions used when compiling, -conditional include directories and more. The conditions may be based on the -build configuration, target properties, platform information or any other -queryable information. - -There are different types of -:manual:`generator expressions <cmake-generator-expressions(7)>` including -Logical, Informational, and Output expressions. - -Logical expressions are used to create conditional output. The basic -expressions are the ``0`` and ``1`` expressions. A ``$<0:...>`` results in the -empty string, and ``$<1:...>`` results in the content of ``...``. They can also -be nested. - -Exercise 1 - Adding Compiler Warning Flags with Generator Expressions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -A common usage of -:manual:`generator expressions <cmake-generator-expressions(7)>` is to -conditionally add compiler flags, such as those for language levels or -warnings. A nice pattern is to associate this information to an ``INTERFACE`` -target allowing this information to propagate. - -Goal ----- - -Add compiler warning flags when building but not for installed versions. - -Helpful Resources ------------------ - -* :manual:`cmake-generator-expressions(7)` -* :command:`cmake_minimum_required` -* :command:`set` -* :command:`target_compile_options` - -Files to Edit -------------- - -* ``CMakeLists.txt`` - -Getting Started ---------------- - -Open the file ``Step4/CMakeLists.txt`` and complete ``TODO 1`` through -``TODO 4``. - -First, in the top level ``CMakeLists.txt`` file, we need to set the -:command:`cmake_minimum_required` to ``3.15``. In this exercise we are going -to use a generator expression which was introduced in CMake 3.15. - -Next we add the desired compiler warning flags that we want for our project. -As warning flags vary based on the compiler, we use the -``COMPILE_LANG_AND_ID`` generator expression to control which flags to apply -given a language and a set of compiler ids. - -Build and Run -------------- - -Make a new directory called ``Step4_build``, run the :manual:`cmake <cmake(1)>` -executable or the :manual:`cmake-gui <cmake-gui(1)>` to configure the project -and then build it with your chosen build tool or by using ``cmake --build .`` -from the build directory. - -.. code-block:: console - - mkdir Step4_build - cd Step4_build - cmake ../Step4 - cmake --build . - -Solution --------- - -Update the :command:`cmake_minimum_required` to require at least CMake -version ``3.15``: - -.. raw:: html - - <details><summary>TODO 1: Click to show/hide answer</summary> - -.. literalinclude:: Step5/CMakeLists.txt - :caption: TODO 1: CMakeLists.txt - :name: MathFunctions-CMakeLists.txt-minimum-required-step4 - :language: cmake - :end-before: # set the project name and version - -.. raw:: html - - </details> - -Next we determine which compiler our system is currently using to build -since warning flags vary based on the compiler we use. This is done with -the ``COMPILE_LANG_AND_ID`` generator expression. We set the result in the -variables ``gcc_like_cxx`` and ``msvc_cxx`` as follows: - -.. raw:: html - - <details><summary>TODO 2: Click to show/hide answer</summary> - -.. literalinclude:: Step5/CMakeLists.txt - :caption: TODO 2: CMakeLists.txt - :name: CMakeLists.txt-compile_lang_and_id - :language: cmake - :start-after: # the BUILD_INTERFACE genex - :end-before: target_compile_options(tutorial_compiler_flags INTERFACE - -.. raw:: html - - </details> - -Next we add the desired compiler warning flags that we want for our project. -Using our variables ``gcc_like_cxx`` and ``msvc_cxx``, we can use another -generator expression to apply the respective flags only when the variables are -true. We use :command:`target_compile_options` to apply these flags to our -interface library. - -.. raw:: html - - <details><summary>TODO 3: Click to show/hide answer</summary> - -.. code-block:: cmake - :caption: TODO 3: CMakeLists.txt - :name: CMakeLists.txt-compile_flags - - target_compile_options(tutorial_compiler_flags INTERFACE - "$<${gcc_like_cxx}:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>" - "$<${msvc_cxx}:-W3>" - ) - -.. raw:: html - - </details> - -Lastly, we only want these warning flags to be used during builds. Consumers -of our installed project should not inherit our warning flags. To specify -this, we wrap our flags from TODO 3 in a generator expression using the -``BUILD_INTERFACE`` condition. The resulting full code looks like the following: - -.. raw:: html - - <details><summary>TODO 4: Click to show/hide answer</summary> - -.. literalinclude:: Step5/CMakeLists.txt - :caption: TODO 4: CMakeLists.txt - :name: CMakeLists.txt-target_compile_options-genex - :language: cmake - :start-after: set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") - :end-before: # configure a header file to pass some of the CMake settings - -.. raw:: html - - </details> + To see the older version, follow `this link <https://cmake.org/cmake/help/v4.1/guide/tutorial/Adding%20Generator%20Expressions.html>`_ + or select the drop-down in the page header.
diff --git a/Help/guide/tutorial/Adding Support for a Testing Dashboard.rst b/Help/guide/tutorial/Adding Support for a Testing Dashboard.rst index e91aa6a..e825a3b 100644 --- a/Help/guide/tutorial/Adding Support for a Testing Dashboard.rst +++ b/Help/guide/tutorial/Adding Support for a Testing Dashboard.rst
@@ -1,108 +1,10 @@ Step 6: 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 <Tutorial Testing Support>`. Now we just have to run -those tests and submit them to CDash. +This page was once part of an older version of the CMake tutorial which +last appeared in CMake 4.1. See the current tutorial version :guide:`here <CMake Tutorial>`. +.. only:: cmakeorg -Exercise 1 - Send Results to a Testing Dashboard -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Goal ----- - -Display our CTest results with CDash. - -Helpful Resources ------------------ - -* :manual:`ctest(1)` -* :command:`include` -* :module:`CTest` - -Files to Edit -------------- - -* ``CMakeLists.txt`` - -Getting Started ---------------- - -For this exercise, complete ``TODO 1`` in the top-level ``CMakeLists.txt`` by -including the :module:`CTest` module. This will enable testing with CTest as -well as dashboard submissions to CDash, so we can safely remove the call to -:command:`enable_testing`. - -We will also need to acquire a ``CTestConfig.cmake`` file to be placed in the -top-level directory. When run, the :manual:`ctest <ctest(1)>` executable will -read this file to gather information about the testing dashboard. It contains: - -* 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 - -For this tutorial, a public dashboard server is used and its corresponding -``CTestConfig.cmake`` file is provided for you in this step's root directory. -In practice, this file would be downloaded from a project's ``Settings`` page -on the CDash instance intended to host the test results. Once downloaded from -CDash, the file should not be modified locally. - -.. literalinclude:: Step7/CTestConfig.cmake - :caption: CTestConfig.cmake - :name: CTestConfig.cmake - :language: cmake - - -Build and Run -------------- - -Note that as part of the CDash submission some information about your -development system (e.g. site name or full pathnames) may displayed publicly. - -To create a simple test dashboard, run the :manual:`cmake <cmake(1)>` -executable or the :manual:`cmake-gui <cmake-gui(1)>` to configure the project -but do not build it yet. Instead, navigate to the build directory and 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 <ctest(1)>` executable will build the project, run any -tests, and submit the results to Kitware's public dashboard: -https://my.cdash.org/index.php?project=CMakeTutorial. - -Solution --------- - -The only CMake code changed needed in this step was to enable dashboard -submissions to CDash by including the :module:`CTest` module in our top-level -``CMakeLists.txt``: - -.. raw:: html - - <details><summary>TODO 1: Click to show/hide answer</summary> - -.. literalinclude:: Step7/CMakeLists.txt - :caption: TODO 1: CMakeLists.txt - :name: CMakeLists.txt-include-CTest - :language: cmake - :start-after: # enable testing - :end-before: # does the application run - -.. raw:: html - - </details> + To see the older version, follow `this link <https://cmake.org/cmake/help/v4.1/guide/tutorial/Adding%20Support%20for%20a%20Testing%20Dashboard.html>`_ + or select the drop-down in the page header.
diff --git a/Help/guide/tutorial/Adding System Introspection.rst b/Help/guide/tutorial/Adding System Introspection.rst index 87070ed..b61dfba 100644 --- a/Help/guide/tutorial/Adding System Introspection.rst +++ b/Help/guide/tutorial/Adding System Introspection.rst
@@ -1,163 +1,10 @@ Step 7: 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. +This page was once part of an older version of the CMake tutorial which +last appeared in CMake 4.1. See the current tutorial version :guide:`here <CMake Tutorial>`. -Exercise 1 - Assessing Dependency Availability -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. only:: cmakeorg -Goal ----- - -Change implementation based on available system dependencies. - -Helpful Resources ------------------ - -* :module:`CheckCXXSourceCompiles` -* :command:`target_compile_definitions` - -Files to Edit -------------- - -* ``MathFunctions/CMakeLists.txt`` -* ``MathFunctions/mysqrt.cxx`` - -Getting Started ---------------- - -The starting source code is provided in the ``Step7`` directory. In this -exercise, complete ``TODO 1`` through ``TODO 5``. - -Start by editing ``MathFunctions/CMakeLists.txt``. Include the -:module:`CheckCXXSourceCompiles` module. Then, use -``check_cxx_source_compiles()`` to determine whether ``log`` and ``exp`` are -available from ``cmath``. If they are available, use -:command:`target_compile_definitions` to specify ``HAVE_LOG`` and ``HAVE_EXP`` -as compile definitions. - -In the ``MathFunctions/mysqrt.cxx``, include ``cmath``. Then, if the system has -``log`` and ``exp``, use them to compute the square root. - -Build and Run -------------- - -Make a new directory called ``Step7_build``. Run the -:manual:`cmake <cmake(1)>` executable or the -:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it -with your chosen build tool and run the ``Tutorial`` executable. - -This can look like the following: - -.. code-block:: console - - mkdir Step7_build - cd Step7_build - cmake ../Step7 - cmake --build . - -Which function gives better results now, ``sqrt`` or ``mysqrt``? - -Solution --------- - -In this exercise we will use functions from the -:module:`CheckCXXSourceCompiles` module so first we must include it in -``MathFunctions/CMakeLists.txt``. - -.. raw:: html - - <details><summary>TODO 1: Click to show/hide answer</summary> - -.. literalinclude:: Step8/MathFunctions/CMakeLists.txt - :caption: TODO 1: MathFunctions/CMakeLists.txt - :name: MathFunctions/CMakeLists.txt-include-check_cxx_source_compiles - :language: cmake - :start-after: # does this system provide the log and exp functions? - :end-before: check_cxx_source_compiles - -.. raw:: html - - </details> - -Then test for the availability of -``log`` and ``exp`` using ``check_cxx_compiles_source``. This function -lets us try compiling simple code with the required dependency prior to -the true source code compilation. The resulting variables ``HAVE_LOG`` -and ``HAVE_EXP`` represent whether those dependencies are available. - -.. raw:: html - - <details><summary>TODO 2: Click to show/hide answer</summary> - -.. literalinclude:: Step8/MathFunctions/CMakeLists.txt - :caption: TODO 2: MathFunctions/CMakeLists.txt - :name: MathFunctions/CMakeLists.txt-check_cxx_source_compiles - :language: cmake - :start-after: include(CheckCXXSourceCompiles) - :end-before: # add compile definitions - -.. raw:: html - - </details> - -Next, we need to pass these CMake variables to our source code. This way, -our source code can tell what resources are available. If both ``log`` and -``exp`` are available, use :command:`target_compile_definitions` to specify -``HAVE_LOG`` and ``HAVE_EXP`` as ``PRIVATE`` compile definitions. - -.. raw:: html - - <details><summary>TODO 3: Click to show/hide answer</summary> - -.. literalinclude:: Step8/MathFunctions/CMakeLists.txt - :caption: TODO 3: MathFunctions/CMakeLists.txt - :name: MathFunctions/CMakeLists.txt-target_compile_definitions - :language: cmake - :start-after: # add compile definitions - :end-before: # state - -.. raw:: html - - </details> - -Since we may be using ``log`` and ``exp``, we need to modify -``mysqrt.cxx`` to include ``cmath``. - -.. raw:: html - - <details><summary>TODO 4: Click to show/hide answer</summary> - -.. literalinclude:: Step8/MathFunctions/mysqrt.cxx - :caption: TODO 4: MathFunctions/mysqrt.cxx - :name: MathFunctions/mysqrt.cxx-include-cmath - :language: c++ - :start-after: #include "mysqrt.h" - :end-before: include <iostream> - -.. raw:: html - - </details> - -If ``log`` and ``exp`` are available on the system, then use them to -compute the square root in the ``mysqrt`` function. The ``mysqrt`` function in -``MathFunctions/mysqrt.cxx`` will look as follows: - -.. raw:: html - - <details><summary>TODO 5: Click to show/hide answer</summary> - -.. literalinclude:: Step8/MathFunctions/mysqrt.cxx - :caption: TODO 5: MathFunctions/mysqrt.cxx - :name: MathFunctions/mysqrt.cxx-ifdef - :language: c++ - :start-after: // if we have both log and exp then use them - :end-before: return result; - -.. raw:: html - - </details> + To see the older version, follow `this link <https://cmake.org/cmake/help/v4.1/guide/tutorial/Adding%20System%20Introspection.html>`_ + or select the drop-down in the page header.
diff --git a/Help/guide/tutorial/Adding Usage Requirements for a Library.rst b/Help/guide/tutorial/Adding Usage Requirements for a Library.rst index e7aff9c..81e8445 100644 --- a/Help/guide/tutorial/Adding Usage Requirements for a Library.rst +++ b/Help/guide/tutorial/Adding Usage Requirements for a Library.rst
@@ -1,304 +1,10 @@ Step 3: Adding Usage Requirements for a Library =============================================== -Exercise 1 - Adding Usage Requirements for a Library -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This page was once part of an older version of the CMake tutorial which +last appeared in CMake 4.1. See the current tutorial version :guide:`here <CMake Tutorial>`. -:ref:`Usage requirements <Target Usage Requirements>` of a target parameters -allow for far better control over a library or executable's link and include -line while also giving more control over the transitive property of targets -inside CMake. The primary commands that -leverage usage requirements are: +.. only:: cmakeorg -* :command:`target_compile_definitions` -* :command:`target_compile_options` -* :command:`target_include_directories` -* :command:`target_link_directories` -* :command:`target_link_options` -* :command:`target_precompile_headers` -* :command:`target_sources` - - -Goal ----- - -Add usage requirements for a library. - -Helpful Materials ------------------ - -* :variable:`CMAKE_CURRENT_SOURCE_DIR` - -Files to Edit -------------- - -* ``MathFunctions/CMakeLists.txt`` -* ``CMakeLists.txt`` - -Getting Started ---------------- - -In this exercise, we will refactor our code from -:guide:`tutorial/Adding a Library` to use the modern CMake approach. We will -let our library define its own usage requirements so they are passed -transitively to other targets as necessary. In this case, ``MathFunctions`` -will specify any needed include directories itself. Then, the consuming target -``Tutorial`` simply needs to link to ``MathFunctions`` and not worry about -any additional include directories. - -The starting source code is provided in the ``Step3`` directory. In this -exercise, complete ``TODO 1`` through ``TODO 3``. - -First, add a call to :command:`target_include_directories` in -``MathFunctions/CMakeLists``. Remember that -:variable:`CMAKE_CURRENT_SOURCE_DIR` is the path to the source directory -currently being processed. - -Then, update (and simplify!) the call to -:command:`target_include_directories` in the top-level ``CMakeLists.txt``. - -Build and Run -------------- - -Make a new directory called ``Step3_build``, run the :manual:`cmake -<cmake(1)>` executable or the :manual:`cmake-gui <cmake-gui(1)>` to -configure the project and then build it with your chosen build tool or by -using :option:`cmake --build . <cmake --build>` from the build directory. -Here's a refresher of what that looks like from the command line: - -.. code-block:: console - - mkdir Step3_build - cd Step3_build - cmake ../Step3 - cmake --build . - -Next, use the newly built ``Tutorial`` and verify that it is working as -expected. - -Solution --------- - -Let's update the code from the previous step to use the modern CMake -approach of usage requirements. - -We want to state that anybody linking to ``MathFunctions`` needs to include -the current source directory, while ``MathFunctions`` itself doesn't. This -can be expressed with an ``INTERFACE`` usage requirement. Remember -``INTERFACE`` means things that consumers require but the producer doesn't. - -At the end of ``MathFunctions/CMakeLists.txt``, use -:command:`target_include_directories` with the ``INTERFACE`` keyword, as -follows: - -.. raw:: html - - <details><summary>TODO 1: Click to show/hide answer</summary> - -.. literalinclude:: Step4/MathFunctions/CMakeLists.txt - :caption: TODO 1: MathFunctions/CMakeLists.txt - :name: MathFunctions/CMakeLists.txt-target_include_directories-INTERFACE - :language: cmake - :start-after: # to find MathFunctions.h - :end-before: # should we use our own - -.. raw:: html - - </details> - -Now that we've specified usage requirements for ``MathFunctions`` we can -safely remove our uses of the ``EXTRA_INCLUDES`` variable from the top-level -``CMakeLists.txt``. - -Remove this line: - -.. raw:: html - - <details><summary>TODO 2: Click to show/hide answer</summary> - -.. literalinclude:: Step3/CMakeLists.txt - :caption: TODO 2: CMakeLists.txt - :name: CMakeLists.txt-remove-EXTRA_INCLUDES - :language: cmake - :start-after: add_subdirectory(MathFunctions) - :end-before: # add the executable - -.. raw:: html - - </details> - -And remove ``EXTRA_INCLUDES`` from ``target_include_directories``: - -.. raw:: html - - <details><summary>TODO 3: Click to show/hide answer</summary> - -.. literalinclude:: Step4/CMakeLists.txt - :caption: TODO 3: CMakeLists.txt - :name: CMakeLists.txt-target_include_directories-remove-EXTRA_INCLUDES - :language: cmake - :start-after: # so that we will find TutorialConfig.h - -.. raw:: html - - </details> - -Notice that with this technique, the only thing our executable target does to -use our library is call :command:`target_link_libraries` with the name -of the library target. In larger projects, the classic method of specifying -library dependencies manually becomes very complicated very quickly. - -Exercise 2 - Setting the C++ Standard with Interface Libraries -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Now that we have switched our code to a more modern approach, let's demonstrate -a modern technique to set properties to multiple targets. - -Let's refactor our existing code to use an ``INTERFACE`` library. We will -use that library in the next step to demonstrate a common use for -:manual:`generator expressions <cmake-generator-expressions(7)>`. - -Goal ----- - -Add an ``INTERFACE`` library target to specify the required C++ standard. - -Helpful Resources ------------------ - -* :command:`add_library` -* :command:`target_compile_features` -* :command:`target_link_libraries` - -Files to Edit -------------- - -* ``CMakeLists.txt`` -* ``MathFunctions/CMakeLists.txt`` - -Getting Started ---------------- - -In this exercise, we will refactor our code to use an ``INTERFACE`` library to -specify the C++ standard. - -Start this exercise from what we left at the end of Step3 exercise 1. You will -have to complete ``TODO 4`` through ``TODO 7``. - -Start by editing the top level ``CMakeLists.txt`` file. Construct an -``INTERFACE`` library target called ``tutorial_compiler_flags`` and -specify ``cxx_std_11`` as a target compiler feature. - -Modify ``CMakeLists.txt`` and ``MathFunctions/CMakeLists.txt`` so that all -targets have a :command:`target_link_libraries` call to -``tutorial_compiler_flags``. - -Build and Run -------------- - -Since we have our build directory already configured from Exercise 1, simply -rebuild our code by calling the following: - -.. code-block:: console - - cd Step3_build - cmake --build . - -Next, use the newly built ``Tutorial`` and verify that it is working as -expected. - -Solution --------- - -Let's update our code from the previous step to use interface libraries -to set our C++ requirements. - -To start, we need to remove the two :command:`set` calls on the variables -:variable:`CMAKE_CXX_STANDARD` and :variable:`CMAKE_CXX_STANDARD_REQUIRED`. -The specific lines to remove are as follows: - -.. literalinclude:: Step3/CMakeLists.txt - :caption: CMakeLists.txt - :name: CMakeLists.txt-CXX_STANDARD-variable-remove - :language: cmake - :start-after: # specify the C++ standard - :end-before: # configure a header file - -Next, we need to create an interface library, ``tutorial_compiler_flags``. And -then use :command:`target_compile_features` to add the compiler feature -``cxx_std_11``. - - -.. raw:: html - - <details><summary>TODO 4: Click to show/hide answer</summary> - -.. literalinclude:: Step4/CMakeLists.txt - :caption: TODO 4: CMakeLists.txt - :name: CMakeLists.txt-cxx_std-feature - :language: cmake - :start-after: # specify the C++ standard - :end-before: # TODO 2: Create helper - -.. raw:: html - - </details> - -Finally, with our interface library set up, we need to link our -executable ``Tutorial``, our ``SqrtLibrary`` library and our ``MathFunctions`` -library to our new ``tutorial_compiler_flags`` library. Respectively, the code -will look like this: - -.. raw:: html - - <details><summary>TODO 5: Click to show/hide answer</summary> - -.. literalinclude:: Step4/CMakeLists.txt - :caption: TODO 5: CMakeLists.txt - :name: CMakeLists.txt-target_link_libraries-step4 - :language: cmake - :start-after: add_executable(Tutorial tutorial.cxx) - :end-before: # add the binary tree to the search path for include file - -.. raw:: html - - </details> - -this: - -.. raw:: html - - <details><summary>TODO 6: Click to show/hide answer</summary> - -.. literalinclude:: Step4/MathFunctions/CMakeLists.txt - :caption: TODO 6: MathFunctions/CMakeLists.txt - :name: MathFunctions-CMakeLists.txt-target_link_libraries-step4 - :language: cmake - :start-after: # link SqrtLibrary to tutorial_compiler_flags - :end-before: target_link_libraries(MathFunctions - -.. raw:: html - - </details> - -and this: - -.. raw:: html - - <details><summary>TODO 7: Click to show/hide answer</summary> - -.. literalinclude:: Step4/MathFunctions/CMakeLists.txt - :caption: TODO 7: MathFunctions/CMakeLists.txt - :name: MathFunctions-SqrtLibrary-target_link_libraries-step4 - :language: cmake - :start-after: # link MathFunctions to tutorial_compiler_flags - -.. raw:: html - - </details> - - -With this, all of our code still requires C++ 11 to build. Notice -though that with this method, it gives us the ability to be specific about -which targets get specific requirements. In addition, we create a single -source of truth in our interface library. + To see the older version, follow `this link <https://cmake.org/cmake/help/v4.1/guide/tutorial/Adding%20Usage%20Requirements%20for%20a%20Library.html>`_ + or select the drop-down in the page header.
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 index c71a889..00d079d 100644 --- a/Help/guide/tutorial/Adding a Custom Command and Generated File.rst +++ b/Help/guide/tutorial/Adding a Custom Command and Generated File.rst
@@ -1,103 +1,10 @@ Step 8: 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. +This page was once part of an older version of the CMake tutorial which +last appeared in CMake 4.1. See the current tutorial version :guide:`here <CMake Tutorial>`. -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 <cmath>`. +.. only:: cmakeorg -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 create ``MathFunctions/MakeTable.cmake``. Then, add the -appropriate commands to the 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, we add an executable for ``MakeTable``. - -.. literalinclude:: Step9/MathFunctions/MakeTable.cmake - :caption: MathFunctions/MakeTable.cmake - :name: MathFunctions/MakeTable.cmake-add_executable-MakeTable - :language: cmake - :start-after: # first we add the executable that generates the table - :end-before: target_link_libraries - -After creating the executable, we add the ``tutorial_compiler_flags`` to our -executable using :command:`target_link_libraries`. - -.. literalinclude:: Step9/MathFunctions/MakeTable.cmake - :caption: MathFunctions/MakeTable.cmake - :name: MathFunctions/MakeTable.cmake-link-tutorial-compiler-flags - :language: cmake - :start-after: add_executable - :end-before: # add the command to generate - -Then we add a custom command that specifies how to produce ``Table.h`` -by running MakeTable. - -.. literalinclude:: Step9/MathFunctions/MakeTable.cmake - :caption: MathFunctions/MakeTable.cmake - :name: MathFunctions/MakeTable.cmake-add_custom_command-Table.h - :language: cmake - :start-after: # add the command to generate the source code - -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 ``SqrtLibrary``. - -.. literalinclude:: Step9/MathFunctions/CMakeLists.txt - :caption: MathFunctions/CMakeLists.txt - :name: MathFunctions/CMakeLists.txt-add_library-Table.h - :language: cmake - :start-after: # library that just does sqrt - :end-before: # state that we depend on - -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:: Step9/MathFunctions/CMakeLists.txt - :caption: MathFunctions/CMakeLists.txt - :name: MathFunctions/CMakeLists.txt-target_include_directories-Table.h - :language: cmake - :start-after: # state that we depend on our bin - :end-before: target_link_libraries - -As the last step, we need to include -``MakeTable.cmake`` at the top of the ``MathFunctions/CMakeLists.txt``. - -.. literalinclude:: Step9/MathFunctions/CMakeLists.txt - :caption: MathFunctions/CMakeLists.txt - :name: MathFunctions/CMakeLists.txt-include-MakeTable.cmake - :language: cmake - :start-after: # generate Table.h - :end-before: # library that just does sqrt - -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:: Step9/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 <cmake(1)>` executable or the -:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it -with your chosen build tool. - -When this project is built it will first build the ``MakeTable`` executable. -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. + To see the older version, follow `this link <https://cmake.org/cmake/help/v4.1/guide/tutorial/Adding%20a%20Custom%20Command%20and%20Generated%20File.html>`_ + or select the drop-down in the page header.
diff --git a/Help/guide/tutorial/Adding a Library.rst b/Help/guide/tutorial/Adding a Library.rst index 8f39da3..dffe081 100644 --- a/Help/guide/tutorial/Adding a Library.rst +++ b/Help/guide/tutorial/Adding a Library.rst
@@ -1,455 +1,10 @@ Step 2: Adding a Library ======================== -At this point, we have seen how to create a basic project using CMake. In this -step, we will learn how to create and use a library in our project. We will -also see how to make the use of our library optional. +This page was once part of an older version of the CMake tutorial which +last appeared in CMake 4.1. See the current tutorial version :guide:`here <CMake Tutorial>`. -Exercise 1 - Creating a Library -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. only:: cmakeorg -To add a library in CMake, use the :command:`add_library` command and specify -which source files should make up the library. - -Rather than placing all of the source files in one directory, we can organize -our project with one or more subdirectories. In this case, we will create a -subdirectory specifically for our library. Here, we can add a new -``CMakeLists.txt`` file and one or more source files. In the top level -``CMakeLists.txt`` file, we will use the :command:`add_subdirectory` command -to add the subdirectory to the build. - -Once the library is created, it is connected to our executable target with -:command:`target_include_directories` and :command:`target_link_libraries`. - -Goal ----- - -Add and use a library. - -Helpful Resources ------------------ - -* :command:`add_library` -* :command:`add_subdirectory` -* :command:`target_include_directories` -* :command:`target_link_libraries` -* :variable:`PROJECT_SOURCE_DIR` - -Files to Edit -------------- - -* ``CMakeLists.txt`` -* ``tutorial.cxx`` -* ``MathFunctions/CMakeLists.txt`` - -Getting Started ---------------- - -In this exercise, we will add a library to our project that contains our own -implementation for computing the square root of a number. The executable can -then use this library instead of the standard square root function provided by -the compiler. - -For this tutorial we will put the library into a subdirectory called -``MathFunctions``. This directory already contains the header files -``MathFunctions.h`` and ``mysqrt.h``. Their respective source files -``MathFunctions.cxx`` and ``mysqrt.cxx`` are also provided. We will not need -to modify any of these files. ``mysqrt.cxx`` has one function called -``mysqrt`` that provides similar functionality to the compiler's ``sqrt`` -function. ``MathFunctions.cxx`` contains one function ``sqrt`` which serves -to hide the implementation details of ``sqrt``. - -From the ``Help/guide/tutorial/Step2`` directory, start with ``TODO 1`` and -complete through ``TODO 6``. - -First, fill in the one line ``CMakeLists.txt`` in the ``MathFunctions`` -subdirectory. - -Next, edit the top level ``CMakeLists.txt``. - -Finally, use the newly created ``MathFunctions`` library in ``tutorial.cxx`` - -Build and Run -------------- - -Run the :manual:`cmake <cmake(1)>` executable or the -:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it -with your chosen build tool. - -Below is a refresher of what that looks like from the command line: - -.. code-block:: console - - mkdir Step2_build - cd Step2_build - cmake ../Step2 - cmake --build . - -Try to use the newly built ``Tutorial`` and ensure that it is still -producing accurate square root values. - -Solution --------- - -In the ``CMakeLists.txt`` file in the ``MathFunctions`` directory, we create -a library target called ``MathFunctions`` with :command:`add_library`. The -source files for the library are passed as an argument to -:command:`add_library`. This looks like the following line: - -.. raw:: html - - <details><summary>TODO 1: Click to show/hide answer</summary> - -.. code-block:: cmake - :caption: TODO 1: MathFunctions/CMakeLists.txt - :name: MathFunctions/CMakeLists.txt-add_library - - add_library(MathFunctions MathFunctions.cxx mysqrt.cxx) - -.. raw:: html - - </details> - -To make use of the new library we will add an :command:`add_subdirectory` -call in the top-level ``CMakeLists.txt`` file so that the library will get -built. - -.. raw:: html - - <details><summary>TODO 2: Click to show/hide answer</summary> - -.. code-block:: cmake - :caption: TODO 2: CMakeLists.txt - :name: CMakeLists.txt-add_subdirectory - - add_subdirectory(MathFunctions) - -.. raw:: html - - </details> - -Next, the new library target is linked to the executable target using -:command:`target_link_libraries`. - -.. raw:: html - - <details><summary>TODO 3: Click to show/hide answer</summary> - -.. code-block:: cmake - :caption: TODO 3: CMakeLists.txt - :name: CMakeLists.txt-target_link_libraries - - target_link_libraries(Tutorial PUBLIC MathFunctions) - -.. raw:: html - - </details> - -Finally we need to specify the library's header file location. -Modify the existing :command:`target_include_directories` call -to add the ``MathFunctions`` subdirectory as an include directory -so that the ``MathFunctions.h`` header file can be found. - -.. raw:: html - - <details><summary>TODO 4: Click to show/hide answer</summary> - -.. code-block:: cmake - :caption: TODO 4: CMakeLists.txt - :name: CMakeLists.txt-target_include_directories-step2 - - target_include_directories(Tutorial PUBLIC - "${PROJECT_BINARY_DIR}" - "${PROJECT_SOURCE_DIR}/MathFunctions" - ) - -.. raw:: html - - </details> - -Now let's use our library. In ``tutorial.cxx``, include ``MathFunctions.h``: - -.. raw:: html - - <details><summary>TODO 5: Click to show/hide answer</summary> - -.. literalinclude:: Step3/tutorial.cxx - :caption: TODO 5: tutorial.cxx - :name: CMakeLists.txt-include-MathFunctions.h - :language: cmake - :start-after: #include <string> - :end-before: #include "TutorialConfig.h" - -.. raw:: html - - </details> - -Lastly, replace ``sqrt`` with the wrapper function ``mathfunctions::sqrt``. - -.. raw:: html - - <details><summary>TODO 6: Click to show/hide answer</summary> - -.. literalinclude:: Step3/tutorial.cxx - :caption: TODO 6: tutorial.cxx - :name: CMakeLists.txt-option - :language: cmake - :start-after: double const inputValue = std::stod(argv[1]); - :end-before: std::cout - -.. raw:: html - - </details> - -Exercise 2 - Adding an Option -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Now let us add an option in the MathFunctions library to allow developers to -select either the custom square root implementation or the built in standard -implementation. While for the tutorial -there really isn't any need to do so, for larger projects this is a common -occurrence. - -CMake can do this using the :command:`option` command. This gives users a -variable which they can change when configuring their cmake build. This -setting will be stored in the cache so that the user does not need to set -the value each time they run CMake on a build directory. - -Goal ----- - -Add the option to build without ``MathFunctions``. - - -Helpful Resources ------------------ - -* :command:`if` -* :command:`option` -* :command:`target_compile_definitions` - -Files to Edit -------------- - -* ``MathFunctions/CMakeLists.txt`` -* ``MathFunctions/MathFunctions.cxx`` - -Getting Started ---------------- - -Start with the resulting files from Exercise 1. Complete ``TODO 7`` through -``TODO 14``. - -First create a variable ``USE_MYMATH`` using the :command:`option` command -in ``MathFunctions/CMakeLists.txt``. In that same file, use that option -to pass a compile definition to the ``MathFunctions`` library. - -Then, update ``MathFunctions.cxx`` to redirect compilation based on -``USE_MYMATH``. - -Lastly, prevent ``mysqrt.cxx`` from being compiled when ``USE_MYMATH`` is on -by making it its own library inside of the ``USE_MYMATH`` block of -``MathFunctions/CMakeLists.txt``. - -Build and Run -------------- - -Since we have our build directory already configured from Exercise 1, we can -rebuild by simply calling the following: - -.. code-block:: console - - cd ../Step2_build - cmake --build . - -Next, run the ``Tutorial`` executable on a few numbers to verify that it's -still correct. - -Now let's update the value of ``USE_MYMATH`` to ``OFF``. The easiest way is to -use the :manual:`cmake-gui <cmake-gui(1)>` or :manual:`ccmake <ccmake(1)>` -if you're in the terminal. Or, alternatively, if you want to change the -option from the command-line, try: - -.. code-block:: console - - cmake ../Step2 -DUSE_MYMATH=OFF - -Now, rebuild the code with the following: - -.. code-block:: console - - cmake --build . - -Then, run the executable again to ensure that it still works with -``USE_MYMATH`` set to ``OFF``. Which function gives better results, ``sqrt`` -or ``mysqrt``? - -Solution --------- - -The first step is to add an option to ``MathFunctions/CMakeLists.txt``. -This option will be displayed in the :manual:`cmake-gui <cmake-gui(1)>` and -:manual:`ccmake <ccmake(1)>` with a default value of ``ON`` that can be -changed by the user. - -.. raw:: html - - <details><summary>TODO 7: Click to show/hide answer</summary> - -.. literalinclude:: Step3/MathFunctions/CMakeLists.txt - :caption: TODO 7: MathFunctions/CMakeLists.txt - :name: CMakeLists.txt-option-library-level - :language: cmake - :start-after: # should we use our own math functions - :end-before: if (USE_MYMATH) - -.. raw:: html - - </details> - -Next, make building and linking our library with ``mysqrt`` function -conditional using this new option. - -Create an :command:`if` statement which checks the value of -``USE_MYMATH``. Inside the :command:`if` block, put the -:command:`target_compile_definitions` command with the compile -definition ``USE_MYMATH``. - -.. raw:: html - - <details><summary>TODO 8: Click to show/hide answer</summary> - -.. code-block:: cmake - :caption: TODO 8: MathFunctions/CMakeLists.txt - :name: CMakeLists.txt-USE_MYMATH - - if (USE_MYMATH) - target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") - endif() - -.. raw:: html - - </details> - -When ``USE_MYMATH`` is ``ON``, the compile definition ``USE_MYMATH`` will -be set. We can then use this compile definition to enable or disable -sections of our source code. - -The corresponding changes to the source code are fairly straightforward. -In ``MathFunctions.cxx``, we make ``USE_MYMATH`` control which square root -function is used: - -.. raw:: html - - <details><summary>TODO 9: Click to show/hide answer</summary> - -.. literalinclude:: Step3/MathFunctions/MathFunctions.cxx - :caption: TODO 9: MathFunctions/MathFunctions.cxx - :name: MathFunctions-USE_MYMATH-if - :language: c++ - :start-after: which square root function should we use? - :end-before: } - -.. raw:: html - - </details> - -Next, we need to include ``mysqrt.h`` if ``USE_MYMATH`` is defined. - -.. raw:: html - - <details><summary>TODO 10: Click to show/hide answer</summary> - -.. literalinclude:: Step3/MathFunctions/MathFunctions.cxx - :caption: TODO 10: MathFunctions/MathFunctions.cxx - :name: MathFunctions-USE_MYMATH-if-include - :language: c++ - :start-after: include <cmath> - :end-before: namespace mathfunctions - -.. raw:: html - - </details> - -Finally, we need to include ``cmath`` now that we are using ``std::sqrt``. - -.. raw:: html - - <details><summary>TODO 11: Click to show/hide answer</summary> - -.. code-block:: c++ - :caption: TODO 11 : MathFunctions/MathFunctions.cxx - :name: tutorial.cxx-include_cmath - - #include <cmath> - -.. raw:: html - - </details> - -At this point, if ``USE_MYMATH`` is ``OFF``, ``mysqrt.cxx`` would not be used -but it will still be compiled because the ``MathFunctions`` target has -``mysqrt.cxx`` listed under sources. - -There are a few ways to fix this. The first option is to use -:command:`target_sources` to add ``mysqrt.cxx`` from within the ``USE_MYMATH`` -block. Another option is to create an additional library within the -``USE_MYMATH`` block which is responsible for compiling ``mysqrt.cxx``. For -the sake of this tutorial, we are going to create an additional library. - -First, from within ``USE_MYMATH`` create a library called ``SqrtLibrary`` -that has sources ``mysqrt.cxx``. - -.. raw:: html - - <details><summary>TODO 12: Click to show/hide answer</summary> - -.. literalinclude:: Step3/MathFunctions/CMakeLists.txt - :caption: TODO 12 : MathFunctions/CMakeLists.txt - :name: MathFunctions/CMakeLists.txt-add_library-SqrtLibrary - :language: cmake - :start-after: # library that just does sqrt - :end-before: # TODO 7: Link - -.. raw:: html - - </details> - -Next, we link ``SqrtLibrary`` onto ``MathFunctions`` when ``USE_MYMATH`` is -enabled. - -.. raw:: html - - <details><summary>TODO 13: Click to show/hide answer</summary> - -.. literalinclude:: Step3/MathFunctions/CMakeLists.txt - :caption: TODO 13 : MathFunctions/CMakeLists.txt - :name: MathFunctions/CMakeLists.txt-target_link_libraries-SqrtLibrary - :language: cmake - :start-after: to tutorial_compiler_flags - :end-before: endif() - -.. raw:: html - - </details> - -Finally, we can remove ``mysqrt.cxx`` from our ``MathFunctions`` library -source list because it will be pulled in when ``SqrtLibrary`` is included. - -.. raw:: html - - <details><summary>TODO 14: Click to show/hide answer</summary> - -.. literalinclude:: Step3/MathFunctions/CMakeLists.txt - :caption: TODO 14 : MathFunctions/CMakeLists.txt - :name: MathFunctions/CMakeLists.txt-remove-mysqrt.cxx-MathFunctions - :language: cmake - :end-before: # TODO 1: - -.. raw:: html - - </details> - -With these changes, the ``mysqrt`` function is now completely optional to -whoever is building and using the ``MathFunctions`` library. Users can toggle -``USE_MYMATH`` to manipulate what library is used in the build. + To see the older version, follow `this link <https://cmake.org/cmake/help/v4.1/guide/tutorial/Adding%20a%20Library.html>`_ + or select the drop-down in the page header.
diff --git a/Help/guide/tutorial/Before You Begin.rst b/Help/guide/tutorial/Before You Begin.rst new file mode 100644 index 0000000..d3d3a5b --- /dev/null +++ b/Help/guide/tutorial/Before You Begin.rst
@@ -0,0 +1,250 @@ +Step 0: Before You Begin +======================== + +The CMake tutorial consists of hands-on exercises writing and building a +C++ project; solving progressively more complex build requirements such +as libraries, code generators, tests, and external dependencies. Before we +are ready to even begin the first step of that journey, we need to ensure we +have the correct tools at hand and understand how to use them. + +.. note:: + The tutorial material assumes the user has a C++20 compiler and toolchain + available, and at least a beginner understanding of the C++ language. It + is impossible to cover here all the possible ways one might acquire these + prerequisites. + +This prerequisite step provides recommendations for how to acquire and +run CMake itself in order to carry out the rest of the tutorial. If you're +already familiar with the basics of how to run CMake, you can feel free to move +on to the rest of the tutorial. + +Getting the Tutorial Exercises +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. include:: include/source.rst + +|tutorial_source| +Each step of the tutorial has a corresponding subfolder, which serves as the +starting point for that step's exercises. + +Getting CMake +^^^^^^^^^^^^^ + +The most obvious way to get your hands on CMake is to download it from the +CMake website. `The website's "Download" section <https://cmake.org/download/>`_ +contains the latest builds of CMake for all common (and some uncommon) desktop +platforms. + +However, it is preferable to acquire CMake via the usual delivery mechanism for +developer tools on your platform. CMake is available in most packaging +repositories, as a Visual Studio component, and can even be installed from the +Python package index. Additionally, CMake is often available as part of the base +image of most CI/CD runners targeting C/C++. You should consult the documentation +for your software build environment to see if CMake is already available. + +CMake can also be compiled from source using the instructions described by +``README.rst``, found in the root of the CMake source tree. + +CMake, like any program, needs to be available in ``PATH`` in order to be run +from a shell. You can verify CMake is available by running any CMake command. + +.. code-block:: shell + + $ cmake --version + cmake version 3.23.5 + + CMake suite maintained and supported by Kitware (kitware.com/cmake). + + +.. note:: + If using a Visual Studio-provided development environment, it is best to run + CMake from inside a Developer Command Prompt or Developer Powershell. This + ensures CMake has access to all the required developer tooling and + environment variables. + +CMake Generators +^^^^^^^^^^^^^^^^ + +CMake is a configuration program, sometimes called a "meta" build system. As +with other configuration systems, CMake is not ultimately responsible for +running the commands which produce the software build. Instead, CMake generates +a build system based on project, environment, and user-provided configuration +information. + +CMake supports multiple build systems as the output of this configuration +process. These output backends are called "generators", because they generate +the build system. CMake supports many generators, the documentation for +which can be found at :manual:`cmake-generators(7)`. Information about +supported generators for your particular CMake installation can be found +via :option:`cmake --help` under the "Generators" heading. + +Using CMake thus requires one of the build programs which consumes this +generator output be available. The ``Unix Makefiles``, ``Ninja``, and +``Visual Studio`` generators require a compatible ``make``, ``ninja``, and +``Visual Studio`` installation respectively. + +.. note:: + The default generator on Windows is typically the newest available Visual + Studio version on the machine running CMake, everywhere else it is + ``Unix Makefiles``. + +Which generator is used can be controlled via the :envvar:`CMAKE_GENERATOR` +environment variable, or the :option:`cmake -G` option. + +Single and Multi-Configuration Generators +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In many cases, it is possible to treat the underlying build system as an +implementation detail and not differentiate between, for example, ``ninja`` +and ``make`` when using CMake. However, there is one significant property +of a given generator which we need to be aware of for even trivial workflows: +if the generator supports single configuration builds, or if it supports +multi-configuration builds. + +Software builds often have several variants which we might be interested in. +These variants have names like ``Debug``, ``Release``, ``RelWithDebInfo``, and +``MinSizeRel``, with properties corresponding to the name of the given variant. + +A single-configuration build system always builds the software the same way, if +it is generated to produce ``Debug`` builds it will always produce +a ``Debug`` build. A multi-configuration build system can produce different +outputs depending on the configuration specified at build time. + +.. note:: + The terms **build configuration** and **build type** are synonymous. When + dealing with single-configuration generators, which only support a single + variant, the generated variant is usually called the "build type". + + When dealing with multi-configuration generators, the available variants are + usually called the "build configurations". Selecting a variant at build + time is usually called "selecting a configuration" and referred to by flags + and variables as the "config". + + However, this convention is not universal. Both technical and colloquial + documentation often mix the two terms. *Configuration* and *config* are + considered the more correct in contexts which generically address both single + and multi-configuration generators. + +The commonly used generators are as follows: + ++-----------------------------+---------------------------------+ +| Single-Configuration | Multi-Configuration | ++=============================+=================================+ +| :generator:`Ninja` | :generator:`Ninja Multi-Config` | ++-----------------------------+---------------------------------+ +| :generator:`Unix Makefiles` | Visual Studio (all versions) | ++-----------------------------+---------------------------------+ +| :generator:`FASTBuild` | :generator:`Xcode` | ++-----------------------------+---------------------------------+ + +When using a single-configuration generator, the build type is selected based on +the :envvar:`CMAKE_BUILD_TYPE` environment variable, or can be specified +directly when invoking CMake via ``cmake -DCMAKE_BUILD_TYPE=<config>``. + +.. note:: + For the purpose of the tutorial, it is generally unnecessary to specify a + build type when working with single-configuration generators. The + platform-specific default behavior will work for all exercises. + +When using a multi-configuration generator, the build configuration is specified +at build time using either a build-system specific mechanism, or via the +:option:`cmake --build --config <cmake--build --config>` option. + +Other Usage Basics +^^^^^^^^^^^^^^^^^^ + +The rest of the tutorial will cover the remaining usage basics in greater depth, +but for the purpose of ensuring we have a working development environment a few +more CMake option flags will be enumerated here. + + + :option:`cmake -S \<dir\> <cmake -S>` + Specifies the project root directory, where CMake will find the project + to be built. This contains the root ``CMakeLists.txt`` file which will + be discussed in Step 1 of the tutorial. + + When unspecified, defaults to the current working directory. + + :option:`cmake -B \<dir\> <cmake -B>` + Specifies the build directory, where CMake will output the files for the + generated build system, as well as artifacts of the build itself when + the build system is run. + + When unspecified, defaults to the current working directory. + + :option:`cmake --build \<dir\> <cmake --build>` + Runs the build system in the specified build directory. This is a generic + command for all generators. For multi-configuration generators, the desired + configuration can be requested via: + + ``cmake --build <dir> --config <cfg>`` + +Try It Out +^^^^^^^^^^ + +The ``Help/guide/tutorial/Step0`` directory contains a simple "Hello World" +C++ project. The specifics of how CMake configures this project will be +discussed in Step 1 of the tutorial, we need only concern ourselves with +running the CMake program itself. + +As described above, there are many possible ways we could run CMake depending +on which generator we want to use for the build. If we navigate to the +``Help/guide/tutorial/Step0`` directory and run: + +.. code-block:: shell + + cmake -B build + +CMake will generate a build system for the Step0 project into +``Help/guide/tutorial/Step0/build`` using the default generator for the +platform. Alternatively we can specify a specific generator, ``Ninja`` for +example, with: + +.. code-block:: shell + + cmake -G Ninja -B build + +The effect is similar, but will use the ``Ninja`` generator instead of the +platform default. + +.. note:: + We can't reuse the build directory with different generators. It is necessary + to delete the build directory between CMake runs if you want to switch to a + different generator using the same build directory. + +How we build and run the project after generating the build system depends on +the kind of generator we're using. If it is a single-configuration generator on +a non-Windows platform, we can simply do: + +.. code-block:: shell + + cmake --build build + ./build/hello + +.. note:: + On Windows we might need to specify the file extension depending on which + shell is in use, ie ``./build/hello.exe`` + +If we're using a multi-configuration generator, we will want to specify the +build configuration. The default configurations are ``Debug``, ``Release``, +``RelWithDebInfo``, and ``MinRelSize``. The result of the build will be stored +in a configuration-specific subdirectory of the build folder. So for example we +could run: + +.. code-block:: shell + + cmake --build build --config Debug + ./build/Debug/hello + +Getting Help and Additional Resources +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For help from the CMake community, you can reach out on +`the CMake Discourse Forums <https://discourse.cmake.org/>`_. + +.. only:: cmakeorg + + For professional training related to CMake, please see + `the CMake training landing page <https://www.kitware.com/courses/cmake-training/>`_. + For other professional CMake services, + `please reach out to us using our contact form <https://www.kitware.com/contact/>`_.
diff --git a/Help/guide/tutorial/CMake Language Fundamentals.rst b/Help/guide/tutorial/CMake Language Fundamentals.rst new file mode 100644 index 0000000..e5dc68d --- /dev/null +++ b/Help/guide/tutorial/CMake Language Fundamentals.rst
@@ -0,0 +1,583 @@ +Step 2: CMake Language Fundamentals +=================================== + +In the previous step we rushed through and handwaved several aspects of the +CMake language which is used within ``CMakeLists.txt`` in order to get useful, +building programs as soon as possible. However, in the wild we encounter +a great deal more complexity than simply describing lists of source and +header files. + +To deal with this complexity CMake provides a Turing-complete domain-specific +language for describing the process of building software. Understanding the +fundamentals of this language will be necessary as we write more complex +CMLs and other CMake files. The language is formally known as +":manual:`CMake Language <cmake-language(7)>`", or more colloquially as CMakeLang. + +.. note:: + The CMake Language is not well suited to describing things which are not + related to building software. While it has some features for general purpose + use, developers should use caution when solving problems not directly related + to their build in CMake Language. + + Oftentimes the correct answer is to write a tool in a general purpose + programming language which solves the problem, and teach CMake how to invoke + that tool as part of the build process. Code generation, cryptographic + signature utilities, and even ray-tracers have been written in CMake Language, + but this is not a recommended practice. + +Because we want to fully explore the language features, this step is an +exception to the tutorial sequencing. It neither builds on ``Step1``, nor is the +starting point for ``Step3``. This will be a sandbox to explore language +features without building any software. We'll pick back up with the Tutorial +program in ``Step3``. + +.. note:: + This tutorial endeavors to demonstrate best practices and solutions to real + problems. However, for this one step we're going to be re-implementing some + built-in CMake functions. In "real life", do not write your own + :command:`list(APPEND)`. + +Background +^^^^^^^^^^ + +The only fundamental types in CMakeLang are strings and lists. Every object in +CMake is a string, and lists are themselves strings which contain semicolons +as separators. Any command which appears to operate on something other than a +string, whether they be booleans, numbers, JSON objects, or otherwise, is in +fact consuming a string, doing some internal conversion logic (in a language +other than CMakeLang), and then converting back to a string for any potential +output. + +We can create a variable, which is to say a name for a string, using the +:command:`set` command. + +.. code-block:: cmake + + set(var "World!") + +A variable's value can be accessed using brace expansion, for example if we want +to use the :command:`message` command to print the string named by ``var``. + +.. code-block:: cmake + + set(var "World!") + message("Hello ${var}") + +.. code-block:: console + + $ cmake -P CMakeLists.txt + Hello World! + +.. note:: + :option:`cmake -P` is called "script mode", it informs CMake this file is not + intended to have a :command:`project` command. We're not building any + software, instead using CMake only as a command interpreter. + +Because CMakeLang has only strings, conditionals are entirely by convention of +which strings are considered true and which are considered false. These are +*supposed* to be intuitive, "True", "On", "Yes", and (strings representing) +non-zero numbers are truthy, while "False" "Off", "No", "0", "Ignore", +"NotFound", and the empty string are all considered false. + +However, some of the rules are more complex than that, so taking some time +to consult the :command:`if` documentation on expressions is worthwhile. It's +recommended to stick to a single pair for a given context, such as +"True"/"False" or "On"/"Off". + +As mentioned, lists are strings containing semicolons. The :command:`list` +command is useful for manipulating these, and many structures within CMake +expect to operate with this convention. As an example, we can use the +:command:`foreach` command to iterate over a list. + +.. code-block:: cmake + + set(stooges "Moe;Larry") + list(APPEND stooges "Curly") + + message("Stooges contains: ${stooges}") + + foreach(stooge IN LISTS stooges) + message("Hello, ${stooge}") + endforeach() + +.. code-block:: console + + $ cmake -P CMakeLists.txt + Stooges contains: Moe;Larry;Curly + Hello, Moe + Hello, Larry + Hello, Curly + +Exercise 1 - Macros, Functions, and Lists +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +CMake allows us to craft our own functions and macros. This can be very helpful +when constructing lots of similar targets, like tests, for which we will want +to call similar sets of commands over and over again. We do so with +:command:`function` and :command:`macro`. + +.. code-block:: cmake + + macro(MyMacro MacroArgument) + message("${MacroArgument}\n\t\tFrom Macro") + endmacro() + + function(MyFunc FuncArgument) + MyMacro("${FuncArgument}\n\tFrom Function") + endfunction() + + MyFunc("From TopLevel") + +.. code-block:: console + + $ cmake -P CMakeLists.txt + From TopLevel + From Function + From Macro + +Like with many languages, the difference between functions and macros is one +of scope. In CMakeLang, both :command:`function` and :command:`macro` can "see" +all the variables created in all the frames above them. However, a +:command:`macro` acts semantically like a text replacement, similar to C/C++ +macros, so any side effects the macro creates are visible in their calling +context. If we create or change a variable in a macro, the caller will see the +change. + +:command:`function` creates its own variable scope, so side effects are not +visible to the caller. In order to propagate changes to the parent which called +the function, we must use ``set(<var> <value> PARENT_SCOPE)``, which works the +same as :command:`set` but for variables belonging to the caller's context. + +.. note:: + In CMake 3.25, the :command:`return(PROPAGATE)` option was added, which + works the same as :command:`set(PARENT_SCOPE)` but provides slightly better + ergonomics. + +While not necessary for this exercise, it bears mentioning that :command:`macro` +and :command:`function` both support variadic arguments via the ``ARGV`` +variable, a list containing all arguments passed to the command, and the +``ARGN`` variable, containing all arguments past the last expected argument. + +We're not going to build any targets in this exercise, so instead we'll +construct our own version of :command:`list(APPEND)`, which adds a value to a +list. + +Goal +---- + +Implement a macro and a function which append a value to a list, without using +the :command:`list(APPEND)` command. + +The desired usage of these commands is as follows: + +.. code-block:: cmake + + set(Letters "Alpha;Beta") + MacroAppend(Letters "Gamma") + message("Letters contains: ${Letters}") + +.. code-block:: console + + $ cmake -P Exercise1.cmake + Letters contains: Alpha;Beta;Gamma + +.. note:: + The extension for these exercises is ``.cmake``, that's the standard extension + for CMakeLang files when not contained in a ``CMakeLists.txt`` + +Helpful Resources +----------------- + +* :command:`macro` +* :command:`function` +* :command:`set` +* :command:`if` + +Files to Edit +------------- + +* ``Exercise1.cmake`` + +Getting Started +---------------- + +The source code for ``Exercise1.cmake`` is provided in the +``Help/guide/tutorial/Step2`` directory. It contains tests to verify the +append behavior described above. + +.. note:: + You're not expected to handle the case of an empty or undefined list to + append to. However, as a bonus, the case is tested if you want to try out + your understanding of CMakeLang conditionals. + +Complete ``TODO 1`` and ``TODO 2``. + +Build and Run +------------- + +We're going to use script mode to run these exercises. First navigate to the +``Help/guide/tutorial/Step2`` folder then you can run the code with: + +.. code-block:: console + + cmake -P Exercise1.cmake + +The script will report if the commands were implemented correctly. + +Solution +-------- + +This problem relies on an understanding of the mechanisms of CMake variables. +CMake variables are names for strings; or put another way, a CMake variable +is itself a string which can brace expand into a different string. + +This leads to a common pattern in CMake code where functions and macros aren't +passed values, but rather, they are passed the names of variables which contain +those values. Thus ``ListVar`` does not contain the *value* of the list we need +to append to, it contains the *name* of a list, which contains the value we +need to append to. + +When expanding the variable with ``${ListVar}``, we will get the name of the +list. If we expand that name with ``${${ListVar}}``, we will get the values +the list contains. + +To implement ``MacroAppend``, we need only combine this understanding of +``ListVar`` with our knowledge of the :command:`set` command. + +.. raw:: html + + <details><summary>TODO 1: Click to show/hide answer</summary> + +.. code-block:: cmake + :caption: TODO 1: Exercise1.cmake + :name: Exercise1.cmake-MacroAppend + + macro(MacroAppend ListVar Value) + set(${ListVar} "${${ListVar}};${Value}") + endmacro() + +.. raw:: html + + </details> + +We don't need to worry about scope here, because a macro operates in the same +scope as its parent. + +``FuncAppend`` is almost identical, in fact it could be implemented in the +same one liner but with an added ``PARENT_SCOPE``, but the instructions ask +us to implement it in terms of ``MacroAppend``. + +.. raw:: html + + <details><summary>TODO 2: Click to show/hide answer</summary> + +.. code-block:: cmake + :caption: TODO 2: Exercise1.cmake + :name: Exercise1.cmake-FuncAppend + + function(FuncAppend ListVar Value) + MacroAppend(${ListVar} ${Value}) + set(${ListVar} "${${ListVar}}" PARENT_SCOPE) + endfunction() + +.. raw:: html + + </details> + +``MacroAppend`` transforms ``ListVar`` for us, but it won't propagate the result +to the parent scope. Because this is a function, we need to do so ourselves +with :command:`set(PARENT_SCOPE)`. + +Exercise 2 - Conditionals and Loops +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The two most common flow control elements in any structured programming +language are conditionals and their close sibling loops. CMakeLang is no +different. As previously mentioned, the truthiness of a given CMake string is a +convention established by the :command:`if` command. + +When given a string, :command:`if` will first check if it is one of the known +constant values previously discussed. If the string isn't one of those values +the command assumes it is a variable, and checks the brace-expanded contents of +that variable to determine the result of the conditional. + +.. code-block:: cmake + + if(True) + message("Constant Value: True") + else() + message("Constant Value: False") + endif() + + if(ConditionalValue) + message("Undefined Variable: True") + else() + message("Undefined Variable: False") + endif() + + set(ConditionalValue True) + + if(ConditionalValue) + message("Defined Variable: True") + else() + message("Defined Variable: False") + endif() + +.. code-block:: console + + $ cmake -P ConditionalValue.cmake + Constant Value: True + Undefined Variable: False + Defined Variable: True + +.. note:: + This is a good a time as any to discuss quoting in CMake. All objects in + CMake are strings, thus the double quote, ``"``, is often unnecessary. + CMake knows the object is a string, everything is a string. + + However, it is needed in some contexts. Strings containing whitespace require + double quotes, else they are treated like lists; CMake will concatenate the + elements together with semicolons. The reverse is also true, when + brace-expanding lists it is necessary to do so inside quotes if we want to + *preserve* the semicolons. Otherwise CMake will expand the list items into + space-separate strings. + + A handful of commands, such as :command:`if`, recognize the difference + between quoted and unquoted strings. :command:`if` will only check that the + given string represents a variable when the string is unquoted. + +Finally, :command:`if` provides several useful comparison modes such as +``STREQUAL`` for string matching, ``DEFINED`` for checking the existence of +a variable, and ``MATCHES`` for regular expression checks. It also supports the +typical logical operators, ``NOT``, ``AND``, and ``OR``. + +In addition to conditionals CMake provides two loop structures, +:command:`while`, which follows the same rules as :command:`if` for checking a +loop variable, and the more useful :command:`foreach`, which iterates over lists +of strings and was demonstrated in the `Background`_ section. + +For this exercise, we're going to use loops and conditionals to solve some +simple problems. We'll be using the aforementioned ``ARGN`` variable from +:command:`function` as the list to operate on. + +Goal +---- + +Loop over a list, and return all the strings containing the string ``Foo``. + +.. note:: + Those who read the command documentation will be aware that this is + :command:`list(FILTER)`, resist the temptation to use it. + +Helpful Resources +----------------- + +* :command:`function` +* :command:`foreach` +* :command:`if` +* :command:`list` + +Files to Edit +------------- + +* ``Exercise2.cmake`` + +Getting Started +---------------- + +The source code for ``Exercise2.cmake`` is provided in the ``Help/guide/tutorial/Step2`` +directory. It contains tests to verify the append behavior described above. + +.. note:: + You should use the :command:`list(APPEND)` command this time to collect your + final result into a list. The input can be consumed from the ``ARGN`` variable + of the provided function. + +Complete ``TODO 3``. + +Build and Run +------------- + +Navigate to the ``Help/guide/tutorial/Step2`` folder then you can run the code with: + +.. code-block:: console + + cmake -P Exercise2.cmake + +The script will report if the ``FilterFoo`` function was implemented correctly. + +Solution +-------- + +We need to do three things, loop over the ``ARGN`` list, check if a given +item in that list matches ``"Foo"``, and if so append it to the ``OutVar`` +list. + +While there are a couple ways we could invoke :command:`foreach`, the +recommended way is to allow the command to do the variable expansion for us +via ``IN LISTS`` to access the ``ARGN`` list items. + +The :command:`if` comparison we need is ``MATCHES`` which will check if +``"FOO"`` exists in the item. All that remains is to append the item to the +``OutVar`` list. The trickiest part is remembering that ``OutVar`` *names* a +list, it is not the list itself, so we need to access it via ``${OutVar}``. + +.. raw:: html + + <details><summary>TODO 3: Click to show/hide answer</summary> + +.. code-block:: cmake + :caption: TODO 3: Exercise2.cmake + :name: Exercise2.cmake-FilterFoo + + function(FilterFoo OutVar) + + foreach(item IN LISTS ARGN) + if(item MATCHES Foo) + list(APPEND ${OutVar} ${item}) + endif() + endforeach() + + set(${OutVar} ${${OutVar}} PARENT_SCOPE) + endfunction() + +.. raw:: html + + </details> + +Exercise 3 - Organizing with Include +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +We have already discussed how to incorporate subdirectories containing their +own CMLs with :command:`add_subdirectory`. In later steps we will explore +the various way CMake code can be packaged and shared across projects. + +However for small CMake functions and utilities, it is often beneficial for them +to live in their own ``.cmake`` files outside the project CMLs and separate +from the rest of the build system. This allows for separation of concerns, +removing the project-specific elements from the utilities we are using to +describe them. + +To incorporate these separate ``.cmake`` files into our project, we use the +:command:`include` command. This command immediately begins interpreting the +contents of the :command:`include`'d file in the scope of the parent CML. It +is as if the entire file were being called as a macro. + +Traditionally, these kinds of ``.cmake`` files live in a folder named "cmake" +inside the project root. For this exercise, we'll use the ``Step2`` folder instead. + +Goal +---- + +Use the functions from Exercises 1 and 2 to build and filter our own list of items. + +Helpful Resources +----------------- + +* :command:`include` + +Files to Edit +------------- + +* ``Exercise3.cmake`` + +Getting Started +---------------- + +The source code for ``Exercise3.cmake`` is provided in the ``Help/guide/tutorial/Step2`` +directory. It contains tests to verify the correct usage of our functions +from the previous two exercises. + +.. note:: + Actually it reuses tests from Exercise2.cmake, reusable code is good for + everyone. + +Complete ``TODO 4`` through ``TODO 7``. + +Build and Run +------------- + +Navigate to the ``Help/guide/tutorial/Step2`` folder then you can run the code with: + +.. code-block:: console + + cmake -P Exercise3.cmake + +The script will report if the functions were invoked and composed correctly. + +Solution +-------- + +The :command:`include` command will interpret the included file completely, +including the tests from the first two exercises. We don't want to run these +tests again. Thanks to some forethought, these files check a variable called +``SKIP_TESTS`` prior to running their tests, setting this to ``True`` will +get us the behavior we want. + +.. raw:: html + + <details><summary>TODO 4: Click to show/hide answer</summary> + +.. code-block:: cmake + :caption: TODO 4: Exercise3.cmake + :name: Exercise3.cmake-SKIP_TESTS + + set(SKIP_TESTS True) + +.. raw:: html + + </details> + +Now we're ready to :command:`include` the previous exercises to grab their +functions. + +.. raw:: html + + <details><summary>TODO 5: Click to show/hide answer</summary> + +.. code-block:: cmake + :caption: TODO 5: Exercise3.cmake + :name: Exercise3.cmake-include + + include(Exercise1.cmake) + include(Exercise2.cmake) + +.. raw:: html + + </details> + +Now that ``FuncAppend`` is available to us, we can use it to append new elements +to the ``InList``. + +.. raw:: html + + <details><summary>TODO 6: Click to show/hide answer</summary> + +.. code-block:: cmake + :caption: TODO 6: Exercise3.cmake + :name: Exercise3.cmake-FuncAppend + + FuncAppend(InList FooBaz) + FuncAppend(InList QuxBaz) + +.. raw:: html + + </details> + +Finally, we can use ``FilterFoo`` to filter the full list. The tricky part to +remember here is that our ``FilterFoo`` wants to operate on list values via +``ARGN``, so we need to expand the ``InList`` when we call ``FilterFoo``. + +.. raw:: html + + <details><summary>TODO 7: Click to show/hide answer</summary> + +.. code-block:: cmake + :caption: TODO 7: Exercise3.cmake + :name: Exercise3.cmake-FilterFoo + + FilterFoo(OutList ${InList}) + +.. raw:: html + + </details>
diff --git a/Help/guide/tutorial/Complete/CMakeLists.txt b/Help/guide/tutorial/Complete/CMakeLists.txt deleted file mode 100644 index 181c25e..0000000 --- a/Help/guide/tutorial/Complete/CMakeLists.txt +++ /dev/null
@@ -1,127 +0,0 @@ -cmake_minimum_required(VERSION 3.15) - -# set the project name and version -project(Tutorial VERSION 1.0) - -set(CMAKE_DEBUG_POSTFIX d) - -add_library(tutorial_compiler_flags INTERFACE) -target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) - -# add compiler warning flags just when building this project via -# the BUILD_INTERFACE genex -set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>") -set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") -target_compile_options(tutorial_compiler_flags INTERFACE - "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>" - "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" -) - -# control where the static and shared libraries are built so that on windows -# we don't need to tinker with the path to run the executable -set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") -set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") -set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") - -option(BUILD_SHARED_LIBS "Build using shared libraries" ON) - -if(APPLE) - set(CMAKE_INSTALL_RPATH "@executable_path/../lib") -elseif(UNIX) - set(CMAKE_INSTALL_RPATH "$ORIGIN/../lib") -endif() - -# configure a header file to pass the version number only -configure_file(TutorialConfig.h.in TutorialConfig.h) - -# add the MathFunctions library -add_subdirectory(MathFunctions) - -# add the executable -add_executable(Tutorial tutorial.cxx) -set_target_properties(Tutorial PROPERTIES DEBUG_POSTFIX ${CMAKE_DEBUG_POSTFIX}) - -target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags) - -# 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}" - ) - -# add the install targets -install(TARGETS Tutorial DESTINATION bin) -install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" - DESTINATION include - ) - -# enable testing -enable_testing() - -# does the application run -add_test(NAME Runs COMMAND Tutorial 25) - -# does the usage message work? -add_test(NAME Usage COMMAND Tutorial) -set_tests_properties(Usage - PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" - ) - -# define a function to simplify adding tests -function(do_test target arg result) - add_test(NAME Comp${arg} COMMAND ${target} ${arg}) - set_tests_properties(Comp${arg} - PROPERTIES PASS_REGULAR_EXPRESSION ${result} - ) -endfunction() - -# do a bunch of result based tests -do_test(Tutorial 4 "4 is 2") -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 0.0001 "0.0001 is 0.01") - -# setup installer -include(InstallRequiredSystemLibraries) -set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") -set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") -set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") -set(CPACK_GENERATOR "TGZ") -set(CPACK_SOURCE_GENERATOR "TGZ") -include(CPack) - -# install the configuration targets -install(EXPORT MathFunctionsTargets - FILE MathFunctionsTargets.cmake - DESTINATION lib/cmake/MathFunctions -) - -include(CMakePackageConfigHelpers) -# generate the config file that is includes the exports -configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in - "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake" - INSTALL_DESTINATION "lib/cmake/example" - NO_SET_AND_CHECK_MACRO - NO_CHECK_REQUIRED_COMPONENTS_MACRO - ) -# generate the version file for the config file -write_basic_package_version_file( - "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake" - VERSION "${Tutorial_VERSION_MAJOR}.${Tutorial_VERSION_MINOR}" - COMPATIBILITY AnyNewerVersion -) - -# install the configuration file -install(FILES - ${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake - DESTINATION lib/cmake/MathFunctions - ) - -# generate the export targets for the build tree -# needs to be after the install(TARGETS) command -export(EXPORT MathFunctionsTargets - FILE "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsTargets.cmake" -)
diff --git a/Help/guide/tutorial/Complete/CTestConfig.cmake b/Help/guide/tutorial/Complete/CTestConfig.cmake deleted file mode 100644 index b2922fe..0000000 --- a/Help/guide/tutorial/Complete/CTestConfig.cmake +++ /dev/null
@@ -1,3 +0,0 @@ -set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") - -set(CTEST_SUBMIT_URL "https://my.cdash.org/submit.php?project=CMakeTutorial")
diff --git a/Help/guide/tutorial/Complete/Config.cmake.in b/Help/guide/tutorial/Complete/Config.cmake.in deleted file mode 100644 index 17cbabd..0000000 --- a/Help/guide/tutorial/Complete/Config.cmake.in +++ /dev/null
@@ -1,4 +0,0 @@ - -@PACKAGE_INIT@ - -include ( "${CMAKE_CURRENT_LIST_DIR}/MathFunctionsTargets.cmake" )
diff --git a/Help/guide/tutorial/Complete/License.txt b/Help/guide/tutorial/Complete/License.txt deleted file mode 100644 index 85760e5..0000000 --- a/Help/guide/tutorial/Complete/License.txt +++ /dev/null
@@ -1,2 +0,0 @@ -This is the open source License.txt file introduced in -CMake/Tutorial/Step9...
diff --git a/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt deleted file mode 100644 index 1654564..0000000 --- a/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt +++ /dev/null
@@ -1,62 +0,0 @@ -# add the library that runs -add_library(MathFunctions MathFunctions.cxx) - -# state that anybody linking to us needs to include the current source dir -# to find MathFunctions.h, while we don't. -target_include_directories(MathFunctions - INTERFACE - $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}> - $<INSTALL_INTERFACE:include> - ) - -# should we use our own math functions -option(USE_MYMATH "Use tutorial provided math implementation" ON) -if(USE_MYMATH) - - target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") - - include(MakeTable.cmake) # generates Table.h - - # library that just does sqrt - add_library(SqrtLibrary STATIC - mysqrt.cxx - ${CMAKE_CURRENT_BINARY_DIR}/Table.h - ) - - # state that we depend on our binary dir to find Table.h - target_include_directories(SqrtLibrary PRIVATE - ${CMAKE_CURRENT_BINARY_DIR} - ) - - # state that SqrtLibrary need PIC when the default is shared libraries - set_target_properties(SqrtLibrary PROPERTIES - POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS} - ) - - # link SqrtLibrary to tutorial_compiler_flags - target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) - - target_link_libraries(MathFunctions PRIVATE SqrtLibrary) -endif() - -# link MathFunctions to tutorial_compiler_flags -target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) - -# define the symbol stating we are using the declspec(dllexport) when -# building on windows -target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH") - -# setup the version numbering -set_property(TARGET MathFunctions PROPERTY VERSION "1.0.0") -set_property(TARGET MathFunctions PROPERTY SOVERSION "1") - -# install libs -set(installable_libs MathFunctions tutorial_compiler_flags) -if(TARGET SqrtLibrary) - list(APPEND installable_libs SqrtLibrary) -endif() -install(TARGETS ${installable_libs} - EXPORT MathFunctionsTargets - DESTINATION lib) -# install include headers -install(FILES MathFunctions.h DESTINATION include)
diff --git a/Help/guide/tutorial/Complete/MathFunctions/MakeTable.cmake b/Help/guide/tutorial/Complete/MathFunctions/MakeTable.cmake deleted file mode 100644 index 12865a9..0000000 --- a/Help/guide/tutorial/Complete/MathFunctions/MakeTable.cmake +++ /dev/null
@@ -1,10 +0,0 @@ -# first we add the executable that generates the table -add_executable(MakeTable MakeTable.cxx) -target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags) - -# add the command to generate the source code -add_custom_command( - OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h - COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h - DEPENDS MakeTable - )
diff --git a/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.cxx deleted file mode 100644 index c0991b9..0000000 --- a/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.cxx +++ /dev/null
@@ -1,20 +0,0 @@ - -#include "MathFunctions.h" - -#include <cmath> - -#ifdef USE_MYMATH -# include "mysqrt.h" -#endif - -namespace mathfunctions { -double sqrt(double x) -{ -// which square root function should we use? -#ifdef USE_MYMATH - return detail::mysqrt(x); -#else - return std::sqrt(x); -#endif -} -}
diff --git a/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.h deleted file mode 100644 index 3fb547b..0000000 --- a/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.h +++ /dev/null
@@ -1,14 +0,0 @@ - -#if defined(_WIN32) -# if defined(EXPORTING_MYMATH) -# define DECLSPEC __declspec(dllexport) -# else -# define DECLSPEC __declspec(dllimport) -# endif -#else // non windows -# define DECLSPEC -#endif - -namespace mathfunctions { -double DECLSPEC sqrt(double x); -}
diff --git a/Help/guide/tutorial/Complete/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Complete/MathFunctions/mysqrt.cxx deleted file mode 100644 index 8153f18..0000000 --- a/Help/guide/tutorial/Complete/MathFunctions/mysqrt.cxx +++ /dev/null
@@ -1,37 +0,0 @@ -#include <iostream> - -#include "MathFunctions.h" - -// include the generated table -#include "Table.h" - -namespace mathfunctions { -namespace detail { -// a hack square root calculation using simple operations -double mysqrt(double x) -{ - if (x <= 0) { - return 0; - } - - // use the table to help find an initial value - double result = x; - if (x >= 1 && x < 10) { - std::cout << "Use the table to help find an initial value " << std::endl; - result = sqrtTable[static_cast<int>(x)]; - } - - // do ten iterations - for (int i = 0; i < 10; ++i) { - if (result <= 0) { - result = 0.1; - } - double delta = x - (result * result); - result = result + 0.5 * delta / result; - std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; - } - - return result; -} -} -}
diff --git a/Help/guide/tutorial/Complete/MathFunctions/mysqrt.h b/Help/guide/tutorial/Complete/MathFunctions/mysqrt.h deleted file mode 100644 index e1c42ef..0000000 --- a/Help/guide/tutorial/Complete/MathFunctions/mysqrt.h +++ /dev/null
@@ -1,6 +0,0 @@ - -namespace mathfunctions { -namespace detail { -double mysqrt(double x); -} -}
diff --git a/Help/guide/tutorial/Complete/MultiCPackConfig.cmake b/Help/guide/tutorial/Complete/MultiCPackConfig.cmake deleted file mode 100644 index c2583df..0000000 --- a/Help/guide/tutorial/Complete/MultiCPackConfig.cmake +++ /dev/null
@@ -1,6 +0,0 @@ -include("release/CPackConfig.cmake") - -set(CPACK_INSTALL_CMAKE_PROJECTS - "debug;Tutorial;ALL;/" - "release;Tutorial;ALL;/" - )
diff --git a/Help/guide/tutorial/Complete/SimpleTest/CMakeLists.txt b/Help/guide/tutorial/Complete/SimpleTest/CMakeLists.txt new file mode 100644 index 0000000..96ad781 --- /dev/null +++ b/Help/guide/tutorial/Complete/SimpleTest/CMakeLists.txt
@@ -0,0 +1,53 @@ +# A very simple test framework for demonstrating how dependencies work +cmake_minimum_required(VERSION 3.23) + +project(SimpleTest + VERSION 0.0.1 +) + +add_library(SimpleTest INTERFACE) +target_sources(SimpleTest + INTERFACE + FILE_SET HEADERS + FILES + SimpleTest.h +) +target_compile_features(SimpleTest INTERFACE cxx_std_20) + +target_compile_definitions(SimpleTest INTERFACE "SIMPLETEST_CONFIG=$<CONFIG>") + +find_package(TransitiveDep REQUIRED) +target_link_libraries(SimpleTest + INTERFACE + TransitiveDep::TransitiveDep +) + +include(GNUInstallDirs) +include(CMakePackageConfigHelpers) + +install( + TARGETS SimpleTest + EXPORT SimpleTestTargets + FILE_SET HEADERS +) + +install( + EXPORT SimpleTestTargets + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/SimpleTest + NAMESPACE SimpleTest:: +) + +write_basic_package_version_file( + ${CMAKE_CURRENT_BINARY_DIR}/SimpleTestConfigVersion.cmake + COMPATIBILITY ExactVersion + ARCH_INDEPENDENT +) + +install( + FILES + cmake/simpletest_discover_impl.cmake + cmake/simpletest_discover_tests.cmake + cmake/SimpleTestConfig.cmake + ${CMAKE_CURRENT_BINARY_DIR}/SimpleTestConfigVersion.cmake + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/SimpleTest +)
diff --git a/Help/guide/tutorial/Complete/SimpleTest/CMakePresets.json b/Help/guide/tutorial/Complete/SimpleTest/CMakePresets.json new file mode 100644 index 0000000..816d8a3 --- /dev/null +++ b/Help/guide/tutorial/Complete/SimpleTest/CMakePresets.json
@@ -0,0 +1,16 @@ +{ + "version": 4, + "configurePresets": [ + { + "name": "tutorial", + "displayName": "SimpleTest Preset", + "description": "Preset to use with the tutorial's SimpleTest library", + "binaryDir": "${sourceDir}/build", + "installDir": "${sourceParentDir}/install", + "cacheVariables": { + "CMAKE_CXX_STANDARD": "20", + "CMAKE_PREFIX_PATH": "${sourceParentDir}/install" + } + } + ] +}
diff --git a/Help/guide/tutorial/Complete/SimpleTest/SimpleTest.h b/Help/guide/tutorial/Complete/SimpleTest/SimpleTest.h new file mode 100644 index 0000000..ced6562 --- /dev/null +++ b/Help/guide/tutorial/Complete/SimpleTest/SimpleTest.h
@@ -0,0 +1,155 @@ +#pragma once + +#include <cstdio> +#include <map> +#include <string_view> + +namespace SimpleTest { + +using TestFunc = void (*)(); + +using Registry = std::map<std::string_view, TestFunc, std::less<>>; +inline Registry g_registry; + +inline Registry& registry() +{ + return g_registry; +} + +struct failure +{ + char const* file; + int line; + char const* expr; +}; + +struct Registrar +{ + template <std::size_t N> + Registrar(char const (&name)[N], TestFunc f) + { + auto [it, inserted] = + registry().emplace(std::string_view{ name, N ? (N - 1) : 0 }, f); + if (!inserted) { + std::printf("[ WARN ] duplicate test name: %.*s\n", + int(it->first.size()), it->first.data()); + } + } +}; + +inline Registry const& all() +{ + return registry(); +} +inline TestFunc find(std::string_view name) +{ + auto it = registry().find(name); + return it == registry().end() ? nullptr : it->second; +} + +} + +#define SIMPLETEST_STRINGIFY(a) #a +#define SIMPLETEST_XSTRINGIFY(a) SIMPLETEST_STRINGIFY(a) +#define SIMPLETEST_CONCAT_(a, b) a##b +#define SIMPLETEST_CONCAT(a, b) SIMPLETEST_CONCAT_(a, b) + +#define TEST(name_literal) \ + static void SIMPLETEST_CONCAT(_simpletest_fn_, __LINE__)(); \ + static ::SimpleTest::Registrar SIMPLETEST_CONCAT(_simpletest_reg_, \ + __LINE__)( \ + name_literal, &SIMPLETEST_CONCAT(_simpletest_fn_, __LINE__)); \ + static void SIMPLETEST_CONCAT(_simpletest_fn_, __LINE__)() + +// Minimal assertion +#define REQUIRE(expr) \ + do { \ + if (!(expr)) \ + throw ::SimpleTest::failure{ __FILE__, __LINE__, #expr }; \ + } while (0) + +int main(int argc, char** argv) +{ + using namespace ::SimpleTest; + + std::string_view arg1 = + (argc >= 2) ? std::string_view{ argv[1] } : std::string_view{}; + + if (arg1 == "--list") { + bool first = true; + for (auto const& [name, _] : registry()) { + if (!first) + std::printf(","); + std::printf("%.*s", int(name.size()), name.data()); + first = false; + } + std::printf("\n"); + return 0; + } + + if (arg1 == "--test") { + if (argc < 3) { + std::printf("usage: %s [--list] [--test <name>]\n", argv[0]); + return 2; + } + +#ifdef SIMPLETEST_CONFIG + std::printf("SimpleTest built with config: " SIMPLETEST_XSTRINGIFY( + SIMPLETEST_CONFIG) "\n"); +#endif + + std::string_view name{ argv[2] }; + auto it = registry().find(name); + if (it == registry().end()) { + std::printf("[ NOTFOUND ] %s\n", argv[2]); + return 2; + } + + int failed = 0; + std::printf("[ RUN ] %.*s\n", int(it->first.size()), + it->first.data()); + try { + it->second(); + std::printf("[ OK] %.*s\n", int(it->first.size()), + it->first.data()); + } catch (failure const& f) { + std::printf("[ FAILED ] %.*s at %s:%d : %s\n", int(it->first.size()), + it->first.data(), f.file, f.line, f.expr); + failed = 1; + } catch (...) { + std::printf("[ FAILED ] %.*s : unknown exception\n", + int(it->first.size()), it->first.data()); + failed = 1; + } + return failed; + } + + if (argc > 1) { + std::printf("usage: %s [--list] [--test <name>]\n", argv[0]); + return 2; + } + +#ifdef SIMPLETEST_CONFIG + std::printf("SimpleTest built with config: " SIMPLETEST_XSTRINGIFY( + SIMPLETEST_CONFIG) "\n"); +#endif + + // Default: run all tests. + int failed = 0; + for (auto const& [name, func] : all()) { + std::printf("[ RUN ] %.*s\n", int(name.size()), name.data()); + try { + func(); + std::printf("[ OK ] %.*s\n", int(name.size()), name.data()); + } catch (failure const& f) { + std::printf("[ FAILED ] %.*s at %s:%d : %s\n", int(name.size()), + name.data(), f.file, f.line, f.expr); + failed = 1; + } catch (...) { + std::printf("[ FAILED ] %.*s : unknown exception\n", int(name.size()), + name.data()); + failed = 1; + } + } + return failed; +}
diff --git a/Help/guide/tutorial/Complete/SimpleTest/cmake/SimpleTestConfig.cmake b/Help/guide/tutorial/Complete/SimpleTest/cmake/SimpleTestConfig.cmake new file mode 100644 index 0000000..6c7ffb5 --- /dev/null +++ b/Help/guide/tutorial/Complete/SimpleTest/cmake/SimpleTestConfig.cmake
@@ -0,0 +1,5 @@ +include(CMakeFindDependencyMacro) +find_dependency(TransitiveDep) + +include(${CMAKE_CURRENT_LIST_DIR}/SimpleTestTargets.cmake) +include(${CMAKE_CURRENT_LIST_DIR}/simpletest_discover_tests.cmake)
diff --git a/Help/guide/tutorial/Complete/SimpleTest/cmake/simpletest_discover_impl.cmake b/Help/guide/tutorial/Complete/SimpleTest/cmake/simpletest_discover_impl.cmake new file mode 100644 index 0000000..7d3a22b --- /dev/null +++ b/Help/guide/tutorial/Complete/SimpleTest/cmake/simpletest_discover_impl.cmake
@@ -0,0 +1,32 @@ +if(NOT DEFINED TEST_EXE OR NOT DEFINED OUT_FILE) +# noqa: spellcheck off + message(FATAL_ERROR "simpletest_discover: need -DTEST_EXE and -DOUT_FILE") +# noqa: spellcheck on +endif() + +execute_process( + COMMAND ${TEST_EXE} --list + RESULT_VARIABLE _rc + OUTPUT_VARIABLE _out + ERROR_VARIABLE _err + OUTPUT_STRIP_TRAILING_WHITESPACE +) + +if(NOT _rc EQUAL 0) + file(WRITE ${OUT_FILE} "# simpletest: --list failed (rc=${_rc})\n") + message(FATAL_ERROR "simpletest_discover: '${TEST_EXE} --list' failed (${_rc})\n${_err}") +endif() + +if(_out STREQUAL "") + file(WRITE ${OUT_FILE} "# simpletest: no tests\n") + return() +endif() + +string(REPLACE "," ";" _names "${_out}") + +file(WRITE ${OUT_FILE} "# Auto-generated by simpletest_discover_impl.cmake\n") +foreach(_name IN LISTS _names) + file(APPEND ${OUT_FILE} + "add_test([=[${_name}]=] \"${TEST_EXE}\" \"--test\" \"${_name}\")\n" + ) +endforeach()
diff --git a/Help/guide/tutorial/Complete/SimpleTest/cmake/simpletest_discover_tests.cmake b/Help/guide/tutorial/Complete/SimpleTest/cmake/simpletest_discover_tests.cmake new file mode 100644 index 0000000..e5cf059 --- /dev/null +++ b/Help/guide/tutorial/Complete/SimpleTest/cmake/simpletest_discover_tests.cmake
@@ -0,0 +1,27 @@ +set(_simpletest_impl_script ${CMAKE_CURRENT_LIST_DIR}/simpletest_discover_impl.cmake) + +function(simpletest_discover_tests target) + if(NOT TARGET ${target}) + message(FATAL_ERROR "simpletest_discover_tests: no such target '${target}'") + endif() + + set(_out ${CMAKE_CURRENT_BINARY_DIR}/${target}_ctests.cmake) + + if(NOT EXISTS ${_out}) + file(WRITE ${_out} "# Populated after building ${target}\n") + endif() + +# noqa: spellcheck off + add_custom_command(TARGET ${target} POST_BUILD + COMMAND ${CMAKE_COMMAND} + -DTEST_EXE=$<TARGET_FILE:${target}> + -DOUT_FILE=${_out} + -P ${_simpletest_impl_script} + BYPRODUCTS ${_out} + COMMENT "SimpleTest: Discovering tests in ${target}" + VERBATIM + ) +# noqa: spellcheck on + + set_property(DIRECTORY APPEND PROPERTY TEST_INCLUDE_FILES ${_out}) +endfunction()
diff --git a/Help/guide/tutorial/Complete/TutorialConfig.h.in b/Help/guide/tutorial/Complete/TutorialConfig.h.in deleted file mode 100644 index 7e4d7fa..0000000 --- a/Help/guide/tutorial/Complete/TutorialConfig.h.in +++ /dev/null
@@ -1,3 +0,0 @@ -// the configured options and settings for Tutorial -#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ -#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@
diff --git a/Help/guide/tutorial/Complete/TutorialProject/CMakeLists.txt b/Help/guide/tutorial/Complete/TutorialProject/CMakeLists.txt new file mode 100644 index 0000000..4091638 --- /dev/null +++ b/Help/guide/tutorial/Complete/TutorialProject/CMakeLists.txt
@@ -0,0 +1,60 @@ +cmake_minimum_required(VERSION 3.23) + +project(Tutorial + VERSION 1.0.0 +) + +option(TUTORIAL_BUILD_UTILITIES "Build the Tutorial executable" ON) +option(TUTORIAL_USE_STD_SQRT "Use std::sqrt" OFF) +option(TUTORIAL_ENABLE_IPO "Check for and use IPO support" ON) +option(BUILD_TESTING "Enable testing and build tests" ON) + +if(TUTORIAL_ENABLE_IPO) + include(CheckIPOSupported) + check_ipo_supported(RESULT result OUTPUT output) + if(result) + message("IPO is supported, enabling IPO") + set(CMAKE_INTERPROCEDURAL_OPTIMIZATION ON) + else() + message(WARNING "IPO is not supported: ${output}") + endif() +endif() + +if(TUTORIAL_BUILD_UTILITIES) + add_subdirectory(Tutorial) +endif() + +if(BUILD_TESTING) + enable_testing() + add_subdirectory(Tests) +endif() + +add_subdirectory(MathFunctions) + +include(GNUInstallDirs) + +install( + TARGETS MathFunctions OpAdd OpMul OpSub MathLogger SqrtTable + EXPORT TutorialTargets + FILE_SET HEADERS +) + +install( + EXPORT TutorialTargets + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/Tutorial + NAMESPACE Tutorial:: +) + +include(CMakePackageConfigHelpers) + +write_basic_package_version_file( + ${CMAKE_CURRENT_BINARY_DIR}/TutorialConfigVersion.cmake + COMPATIBILITY ExactVersion +) + +install( + FILES + cmake/TutorialConfig.cmake + ${CMAKE_CURRENT_BINARY_DIR}/TutorialConfigVersion.cmake + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/Tutorial +)
diff --git a/Help/guide/tutorial/Complete/TutorialProject/CMakePresets.json b/Help/guide/tutorial/Complete/TutorialProject/CMakePresets.json new file mode 100644 index 0000000..fee177b --- /dev/null +++ b/Help/guide/tutorial/Complete/TutorialProject/CMakePresets.json
@@ -0,0 +1,16 @@ +{ + "version": 4, + "configurePresets": [ + { + "name": "tutorial", + "displayName": "Tutorial Preset", + "description": "Preset to use with the tutorial", + "binaryDir": "${sourceDir}/build", + "cacheVariables": { + "CMAKE_PREFIX_PATH": "${sourceParentDir}/install", + "TUTORIAL_USE_STD_SQRT": "OFF", + "TUTORIAL_ENABLE_IPO": "OFF" + } + } + ] +}
diff --git a/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..e0f3ba2 --- /dev/null +++ b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/CMakeLists.txt
@@ -0,0 +1,55 @@ +add_library(MathFunctions) +add_library(Tutorial::MathFunctions ALIAS MathFunctions) + +target_sources(MathFunctions + PRIVATE + MathFunctions.cxx + + PUBLIC + FILE_SET HEADERS + FILES + MathFunctions.h +) + +target_link_libraries(MathFunctions + PRIVATE + MathLogger + SqrtTable + + PUBLIC + OpAdd + OpMul + OpSub +) + +target_compile_features(MathFunctions PRIVATE cxx_std_20) + +if(TUTORIAL_USE_STD_SQRT) + target_compile_definitions(MathFunctions PRIVATE TUTORIAL_USE_STD_SQRT) +endif() + +include(CheckIncludeFiles) +check_include_files(emmintrin.h HAS_EMMINTRIN LANGUAGE CXX) + +if(HAS_EMMINTRIN) + target_compile_definitions(MathFunctions PRIVATE TUTORIAL_USE_SSE2) +endif() + +include(CheckSourceCompiles) +check_source_compiles(CXX + [=[ + typedef double v2df __attribute__((vector_size(16))); + int main() { + __builtin_ia32_sqrtsd(v2df{}); + } + ]=] + HAS_GNU_BUILTIN +) + +if(HAS_GNU_BUILTIN) + target_compile_definitions(MathFunctions PRIVATE TUTORIAL_USE_GNU_BUILTIN) +endif() + +add_subdirectory(MathLogger) +add_subdirectory(MathExtensions) +add_subdirectory(MakeTable)
diff --git a/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MakeTable/CMakeLists.txt b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MakeTable/CMakeLists.txt new file mode 100644 index 0000000..6aa2a32 --- /dev/null +++ b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MakeTable/CMakeLists.txt
@@ -0,0 +1,28 @@ +add_executable(MakeTable) + +target_sources(MakeTable + PRIVATE + MakeTable.cxx +) + +add_custom_command( + OUTPUT SqrtTable.h + COMMAND MakeTable SqrtTable.h + DEPENDS MakeTable + VERBATIM +) + +add_custom_target(RunMakeTable DEPENDS SqrtTable.h) + +add_library(SqrtTable INTERFACE) + +target_sources(SqrtTable + INTERFACE + FILE_SET HEADERS + BASE_DIRS + ${CMAKE_CURRENT_BINARY_DIR} + FILES + ${CMAKE_CURRENT_BINARY_DIR}/SqrtTable.h +) + +add_dependencies(SqrtTable RunMakeTable)
diff --git a/Help/guide/tutorial/Complete/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MakeTable/MakeTable.cxx similarity index 100% rename from Help/guide/tutorial/Complete/MathFunctions/MakeTable.cxx rename to Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MakeTable/MakeTable.cxx
diff --git a/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/CMakeLists.txt b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/CMakeLists.txt new file mode 100644 index 0000000..b113786 --- /dev/null +++ b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/CMakeLists.txt
@@ -0,0 +1,3 @@ +add_subdirectory(OpAdd) +add_subdirectory(OpMul) +add_subdirectory(OpSub)
diff --git a/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpAdd/CMakeLists.txt b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpAdd/CMakeLists.txt new file mode 100644 index 0000000..f35da81 --- /dev/null +++ b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpAdd/CMakeLists.txt
@@ -0,0 +1,11 @@ +add_library(OpAdd OBJECT) + +target_sources(OpAdd + PRIVATE + OpAdd.cxx + + INTERFACE + FILE_SET HEADERS + FILES + OpAdd.h +)
diff --git a/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpAdd/OpAdd.cxx b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpAdd/OpAdd.cxx new file mode 100644 index 0000000..ea11496 --- /dev/null +++ b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpAdd/OpAdd.cxx
@@ -0,0 +1,6 @@ +namespace mathfunctions { +double OpAdd(double a, double b) +{ + return a + b; +} +}
diff --git a/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpAdd/OpAdd.h b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpAdd/OpAdd.h new file mode 100644 index 0000000..9c9efc3 --- /dev/null +++ b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpAdd/OpAdd.h
@@ -0,0 +1,5 @@ +#pragma once + +namespace mathfunctions { +double OpAdd(double a, double b); +}
diff --git a/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpMul/CMakeLists.txt b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpMul/CMakeLists.txt new file mode 100644 index 0000000..f494fc6 --- /dev/null +++ b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpMul/CMakeLists.txt
@@ -0,0 +1,11 @@ +add_library(OpMul OBJECT) + +target_sources(OpMul + PRIVATE + OpMul.cxx + + INTERFACE + FILE_SET HEADERS + FILES + OpMul.h +)
diff --git a/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpMul/OpMul.cxx b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpMul/OpMul.cxx new file mode 100644 index 0000000..c8eb016 --- /dev/null +++ b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpMul/OpMul.cxx
@@ -0,0 +1,6 @@ +namespace mathfunctions { +double OpMul(double a, double b) +{ + return a * b; +} +}
diff --git a/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpMul/OpMul.h b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpMul/OpMul.h new file mode 100644 index 0000000..52b467b --- /dev/null +++ b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpMul/OpMul.h
@@ -0,0 +1,5 @@ +#pragma once + +namespace mathfunctions { +double OpMul(double a, double b); +}
diff --git a/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpSub/CMakeLists.txt b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpSub/CMakeLists.txt new file mode 100644 index 0000000..1a108fd --- /dev/null +++ b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpSub/CMakeLists.txt
@@ -0,0 +1,11 @@ +add_library(OpSub OBJECT) + +target_sources(OpSub + PRIVATE + OpSub.cxx + + INTERFACE + FILE_SET HEADERS + FILES + OpSub.h +)
diff --git a/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpSub/OpSub.cxx b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpSub/OpSub.cxx new file mode 100644 index 0000000..b7b35da --- /dev/null +++ b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpSub/OpSub.cxx
@@ -0,0 +1,6 @@ +namespace mathfunctions { +double OpSub(double a, double b) +{ + return a - b; +} +}
diff --git a/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpSub/OpSub.h b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpSub/OpSub.h new file mode 100644 index 0000000..1406733 --- /dev/null +++ b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathExtensions/OpSub/OpSub.h
@@ -0,0 +1,5 @@ +#pragma once + +namespace mathfunctions { +double OpSub(double a, double b); +}
diff --git a/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000..4bf8051 --- /dev/null +++ b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathFunctions.cxx
@@ -0,0 +1,101 @@ +#include <cmath> +#include <format> + +#include <MathLogger.h> + +#ifdef TUTORIAL_USE_SSE2 +# include <emmintrin.h> +#endif + +namespace { + +mathlogger::Logger Logger; + +#if defined(TUTORIAL_USE_GNU_BUILTIN) +typedef double v2df __attribute__((vector_size(16))); + +double gnu_mysqrt(double x) +{ + v2df root = __builtin_ia32_sqrtsd(v2df{ x, 0.0 }); + double result = root[0]; + Logger.Log(std::format("Computed sqrt of {} to be {} with GNU-builtins\n", x, + result)); + return result; +} +#elif defined(TUTORIAL_USE_SSE2) +double sse2_mysqrt(double x) +{ + __m128d root = _mm_sqrt_sd(_mm_setzero_pd(), _mm_set_sd(x)); + double result = _mm_cvtsd_f64(root); + Logger.Log( + std::format("Computed sqrt of {} to be {} with SSE2\n", x, result)); + return result; +} +#endif + +// a hack square root calculation using simple operations +double fallback_mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + double result = x; + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + + Logger.Log(std::format("Computing sqrt of {} to be {}\n", x, result)); + } + return result; +} + +#include <SqrtTable.h> + +double table_sqrt(double x) +{ + double result = sqrtTable[static_cast<int>(x)]; + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + } + Logger.Log( + std::format("Computed sqrt of {} to be {} with TableSqrt\n", x, result)); + return result; +} + +double mysqrt(double x) +{ + if (x >= 1 && x < 10) { + return table_sqrt(x); + } + +#if defined(TUTORIAL_USE_GNU_BUILTIN) + return gnu_mysqrt(x); +#elif defined(TUTORIAL_USE_SSE2) + return sse2_mysqrt(x); +#else + return fallback_mysqrt(x); +#endif +} +} + +namespace mathfunctions { +double sqrt(double x) +{ +#ifdef TUTORIAL_USE_STD_SQRT + return std::sqrt(x); +#else + return mysqrt(x); +#endif +} +}
diff --git a/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..91cb176 --- /dev/null +++ b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathFunctions.h
@@ -0,0 +1,9 @@ +#pragma once + +#include <OpAdd.h> +#include <OpMul.h> +#include <OpSub.h> + +namespace mathfunctions { +double sqrt(double x); +}
diff --git a/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathLogger/CMakeLists.txt b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathLogger/CMakeLists.txt new file mode 100644 index 0000000..b20151f --- /dev/null +++ b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathLogger/CMakeLists.txt
@@ -0,0 +1,6 @@ +add_library(MathLogger INTERFACE) + +target_sources(MathLogger + INTERFACE + FILE_SET HEADERS +)
diff --git a/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathLogger/MathFormatting.h b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathLogger/MathFormatting.h new file mode 100644 index 0000000..3b6d61c --- /dev/null +++ b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathLogger/MathFormatting.h
@@ -0,0 +1,27 @@ +#pragma once + +#include <string> + +namespace mathlogger { + +enum LogLevel +{ + INFO, + WARN, + ERROR, +}; + +inline std::string FormatLog(LogLevel level, std::string const& message) +{ + switch (level) { + case INFO: + return "INFO: " + message; + case WARN: + return "WARN: " + message; + case ERROR: + return "ERROR: " + message; + } + return "UNKNOWN: " + message; +} + +}
diff --git a/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathLogger/MathLogger.h b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathLogger/MathLogger.h new file mode 100644 index 0000000..ef7b31a --- /dev/null +++ b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathLogger/MathLogger.h
@@ -0,0 +1,22 @@ +#pragma once + +#include <string> + +#include "MathFormatting.h" +#include "MathOutput.h" + +namespace mathlogger { + +struct Logger +{ + LogLevel level = INFO; + + void SetLevel(LogLevel new_level) { level = new_level; } + void Log(std::string const& message) + { + std::string formatted = FormatLog(level, message); + WriteLog(formatted); + } +}; + +}
diff --git a/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathLogger/MathOutput.h b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathLogger/MathOutput.h new file mode 100644 index 0000000..63f0aeb --- /dev/null +++ b/Help/guide/tutorial/Complete/TutorialProject/MathFunctions/MathLogger/MathOutput.h
@@ -0,0 +1,11 @@ +#pragma once + +#include <iostream> +#include <string> + +namespace mathlogger { +inline void WriteLog(std::string const& msg) +{ + std::cout << msg; +} +}
diff --git a/Help/guide/tutorial/Complete/TutorialProject/Tests/CMakeLists.txt b/Help/guide/tutorial/Complete/TutorialProject/Tests/CMakeLists.txt new file mode 100644 index 0000000..9b5bcd1 --- /dev/null +++ b/Help/guide/tutorial/Complete/TutorialProject/Tests/CMakeLists.txt
@@ -0,0 +1,16 @@ +add_executable(TestMathFunctions) + +target_sources(TestMathFunctions + PRIVATE + TestMathFunctions.cxx +) + +find_package(SimpleTest REQUIRED) + +target_link_libraries(TestMathFunctions + PRIVATE + MathFunctions + SimpleTest::SimpleTest +) + +simpletest_discover_tests(TestMathFunctions)
diff --git a/Help/guide/tutorial/Complete/TutorialProject/Tests/TestMathFunctions.cxx b/Help/guide/tutorial/Complete/TutorialProject/Tests/TestMathFunctions.cxx new file mode 100644 index 0000000..166fd5d --- /dev/null +++ b/Help/guide/tutorial/Complete/TutorialProject/Tests/TestMathFunctions.cxx
@@ -0,0 +1,22 @@ +#include <MathFunctions.h> +#include <SimpleTest.h> + +TEST("add") +{ + REQUIRE(mathfunctions::OpAdd(2.0, 2.0) == 4.0); +} + +TEST("sub") +{ + REQUIRE(mathfunctions::OpSub(4.0, 2.0) == 2.0); +} + +TEST("mul") +{ + REQUIRE(mathfunctions::OpMul(5.0, 5.0) == 25.0); +} + +TEST("sqrt") +{ + REQUIRE(mathfunctions::sqrt(25.0) == 5.0); +}
diff --git a/Help/guide/tutorial/Complete/TutorialProject/Tutorial/CMakeLists.txt b/Help/guide/tutorial/Complete/TutorialProject/Tutorial/CMakeLists.txt new file mode 100644 index 0000000..79b232b --- /dev/null +++ b/Help/guide/tutorial/Complete/TutorialProject/Tutorial/CMakeLists.txt
@@ -0,0 +1,39 @@ +add_executable(Tutorial) + +target_sources(Tutorial + PRIVATE + Tutorial.cxx +) + +target_link_libraries(Tutorial + PRIVATE + MathFunctions +) + +target_compile_features(Tutorial PRIVATE cxx_std_20) + +if( + (CMAKE_CXX_COMPILER_ID STREQUAL "MSVC") OR + (CMAKE_CXX_COMPILER_FRONTEND_VARIANT STREQUAL "MSVC") +) + + target_compile_options(Tutorial PRIVATE /W3) + +elseif( + (CMAKE_CXX_COMPILER_ID STREQUAL "GNU") OR + (CMAKE_CXX_COMPILER_ID MATCHES "Clang") +) + + target_compile_options(Tutorial PRIVATE -Wall) + +endif() + +find_path(UnpackagedIncludeFolder Unpackaged.h REQUIRED + PATH_SUFFIXES + Unpackaged +) + +target_include_directories(Tutorial + PRIVATE + ${UnpackagedIncludeFolder} +)
diff --git a/Help/guide/tutorial/Complete/TutorialProject/Tutorial/Tutorial.cxx b/Help/guide/tutorial/Complete/TutorialProject/Tutorial/Tutorial.cxx new file mode 100644 index 0000000..ac133d4 --- /dev/null +++ b/Help/guide/tutorial/Complete/TutorialProject/Tutorial/Tutorial.cxx
@@ -0,0 +1,27 @@ +// A simple program that computes the square root of a number +#include <format> +#include <iostream> +#include <string> + +#include <MathFunctions.h> +#include <Unpackaged.h> + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + std::cout << std::format("Usage: {} number\n", argv[0]); + return 1; + } + + // convert input to double + double const inputValue = std::stod(argv[1]); + + // calculate square root + double const outputValue = mathfunctions::sqrt(inputValue); + std::cout << std::format("The square root of {} is {}\n", inputValue, + outputValue); + + double const checkValue = mathfunctions::OpMul(outputValue, outputValue); + std::cout << std::format("The square of {} is {}\n", outputValue, + checkValue); +}
diff --git a/Help/guide/tutorial/Complete/TutorialProject/cmake/TutorialConfig.cmake b/Help/guide/tutorial/Complete/TutorialProject/cmake/TutorialConfig.cmake new file mode 100644 index 0000000..d13caa4 --- /dev/null +++ b/Help/guide/tutorial/Complete/TutorialProject/cmake/TutorialConfig.cmake
@@ -0,0 +1 @@ +include(${CMAKE_CURRENT_LIST_DIR}/TutorialTargets.cmake)
diff --git a/Help/guide/tutorial/Complete/install/include/Unpackaged/Unpackaged.h b/Help/guide/tutorial/Complete/install/include/Unpackaged/Unpackaged.h new file mode 100644 index 0000000..9782b0a --- /dev/null +++ b/Help/guide/tutorial/Complete/install/include/Unpackaged/Unpackaged.h
@@ -0,0 +1,3 @@ +#pragma once + +#define UNPACKAGED_HEADER_FOUND
diff --git a/Help/guide/tutorial/Complete/install/lib/cmake/TransitiveDep/TransitiveDepConfig.cmake b/Help/guide/tutorial/Complete/install/lib/cmake/TransitiveDep/TransitiveDepConfig.cmake new file mode 100644 index 0000000..ef51145 --- /dev/null +++ b/Help/guide/tutorial/Complete/install/lib/cmake/TransitiveDep/TransitiveDepConfig.cmake
@@ -0,0 +1,50 @@ +# Abridged import written for the Tutorial + +if("${CMAKE_MAJOR_VERSION}.${CMAKE_MINOR_VERSION}" LESS 2.8) + message(FATAL_ERROR "CMake >= 3.0.0 required") +endif() +if(CMAKE_VERSION VERSION_LESS "3.0.0") + message(FATAL_ERROR "CMake >= 3.0.0 required") +endif() +cmake_policy(PUSH) +cmake_policy(VERSION 3.0.0...3.30) + +# Commands may need to know the format version. +set(CMAKE_IMPORT_FILE_VERSION 1) + +# Protect against multiple inclusion, which would fail when already imported targets are added once more. +set(_cmake_targets_defined "") +set(_cmake_targets_not_defined "") +set(_cmake_expected_targets "") +foreach(_cmake_expected_target IN ITEMS TransitiveDep::TransitiveDep) + list(APPEND _cmake_expected_targets "${_cmake_expected_target}") + if(TARGET "${_cmake_expected_target}") + list(APPEND _cmake_targets_defined "${_cmake_expected_target}") + else() + list(APPEND _cmake_targets_not_defined "${_cmake_expected_target}") + endif() +endforeach() +unset(_cmake_expected_target) +if(_cmake_targets_defined STREQUAL _cmake_expected_targets) + unset(_cmake_targets_defined) + unset(_cmake_targets_not_defined) + unset(_cmake_expected_targets) + unset(CMAKE_IMPORT_FILE_VERSION) + cmake_policy(POP) + return() +endif() +if(NOT _cmake_targets_defined STREQUAL "") + string(REPLACE ";" ", " _cmake_targets_defined_text "${_cmake_targets_defined}") + string(REPLACE ";" ", " _cmake_targets_not_defined_text "${_cmake_targets_not_defined}") + message(FATAL_ERROR "Some (but not all) targets in this export set were already defined.\nTargets Defined: ${_cmake_targets_defined_text}\nTargets not yet defined: ${_cmake_targets_not_defined_text}\n") +endif() +unset(_cmake_targets_defined) +unset(_cmake_targets_not_defined) +unset(_cmake_expected_targets) + +# Create imported target TransitiveDep::TransitiveDep +add_library(TransitiveDep::TransitiveDep INTERFACE IMPORTED) + +# Commands beyond this point should not need to know the version. +set(CMAKE_IMPORT_FILE_VERSION) +cmake_policy(POP)
diff --git a/Help/guide/tutorial/Complete/tutorial.cxx b/Help/guide/tutorial/Complete/tutorial.cxx deleted file mode 100644 index 78641b1..0000000 --- a/Help/guide/tutorial/Complete/tutorial.cxx +++ /dev/null
@@ -1,26 +0,0 @@ -// A simple program that computes the square root of a number -#include <iostream> -#include <string> - -#include "MathFunctions.h" -#include "TutorialConfig.h" - -int main(int argc, char* argv[]) -{ - if (argc < 2) { - // report version - std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." - << Tutorial_VERSION_MINOR << std::endl; - std::cout << "Usage: " << argv[0] << " number" << std::endl; - return 1; - } - - // convert input to double - double const inputValue = std::stod(argv[1]); - - double const outputValue = mathfunctions::sqrt(inputValue); - - std::cout << "The square root of " << inputValue << " is " << outputValue - << std::endl; - return 0; -}
diff --git a/Help/guide/tutorial/Configuration and Cache Variables.rst b/Help/guide/tutorial/Configuration and Cache Variables.rst new file mode 100644 index 0000000..250748b --- /dev/null +++ b/Help/guide/tutorial/Configuration and Cache Variables.rst
@@ -0,0 +1,606 @@ +Step 3: Configuration and Cache Variables +========================================= + +CMake projects often have some project-specific configuration variables which +users and packagers are interested in. CMake has many ways that an invoking +user or process can communicate these configuration choices, but the most +fundamental of them are :option:`-D <cmake -D>` flags. + +In this step we'll explore the ins and out of how to provide project +configuration options from within a CML, and how to invoke CMake to take +advantage of configuration options provided by both CMake and individual +projects. + +Background +^^^^^^^^^^ + +If we had a CMake project for compression software which supported multiple +compression algorithms, we might want to let the packager of the project decide +which algorithms to enable when they build our software. We can do so by +consuming variables set via :option:`-D <cmake -D>` flags. + +.. code-block:: cmake + + if(COMPRESSION_SOFTWARE_USE_ZLIB) + message("I will use Zlib!") + # ... + endif() + + if(COMPRESSION_SOFTWARE_USE_ZSTD) + message("I will use Zstd!") + # ... + endif() + +.. code-block:: console + + $ cmake -B build \ + -DCOMPRESSION_SOFTWARE_USE_ZLIB=ON \ + -DCOMPRESSION_SOFTWARE_USE_ZSTD=OFF + ... + I will use Zlib! + +Of course, we will want to provide reasonable defaults for these configuration +choices, and a way to communicate the purpose of a given option. This function +is provided by the :command:`option` command. + +.. code-block:: cmake + + option(COMPRESSION_SOFTWARE_USE_ZLIB "Support Zlib compression" ON) + option(COMPRESSION_SOFTWARE_USE_ZSTD "Support Zstd compression" ON) + + if(COMPRESSION_SOFTWARE_USE_ZLIB) + # Same as before + # ... + +.. code-block:: console + + $ cmake -B build \ + -DCOMPRESSION_SOFTWARE_USE_ZLIB=OFF + ... + I will use Zstd! + +The names created by :option:`-D <cmake -D>` flags and :command:`option` are +not normal variables, they are **cache** variables. Cache variables are globally +visible variables which are *sticky*, their value is difficult to change after +it is initially set. In fact they are so sticky that, in project mode, CMake +will save and restore cache variables across multiple configurations. If a +cache variable is set once, it will remain until another :option:`-D <cmake -D>` +flag preempts the saved variable. + +.. note:: + CMake itself has dozens of normal and cache variables used for configuration. + These are documented at :manual:`cmake-variables(7)` and operate in the same + manner as project-provided variables for configuration. + +:command:`set` can also be used to manipulate cache variables, but will not +change a variable which has already been created. + +.. code-block:: cmake + + set(StickyCacheVariable "I will not change" CACHE STRING "") + set(StickyCacheVariable "Overwrite StickyCache" CACHE STRING "") + + message("StickyCacheVariable: ${StickyCacheVariable}") + +.. code-block:: console + + $ cmake -P StickyCacheVariable.cmake + StickyCacheVariable: I will not change + +Because :option:`-D <cmake -D>` flags are processed before any other commands, +they take precedence for setting the value of a cache variable. + +.. code-block:: console + + $ cmake \ + -DStickyCacheVariable="Commandline always wins" \ + -P StickyCacheVariable.cmake + StickyCacheVariable: Commandline always wins + +While cache variables cannot ordinarily be changed, they can be *shadowed* by +normal variables. We can observe this by :command:`set`'ing a variable to have +the same name as a cache variable, and then using :command:`unset` to remove +the normal variable. + +.. code-block:: cmake + + set(ShadowVariable "In the shadows" CACHE STRING "") + set(ShadowVariable "Hiding the cache variable") + message("ShadowVariable: ${ShadowVariable}") + + unset(ShadowVariable) + message("ShadowVariable: ${ShadowVariable}") + +.. code-block:: console + + $ cmake -P ShadowVariable.cmake + ShadowVariable: Hiding the cache variable + ShadowVariable: In the shadows + +Exercise 1 - Using Options +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +We can imagine a scenario where consumers really want our ``MathFunctions`` +library, and the ``Tutorial`` utility is a "take it or leave it" add-on. In +that case, we might want to add an option to allow consumers to disable +building our ``Tutorial`` binary, building only the ``MathFunctions`` library. + +With our knowledge of options, conditionals, and cache variables we have all +the pieces we need to make this configuration available. + +Goal +---- + +Add an option named ``TUTORIAL_BUILD_UTILITIES`` to control if the ``Tutorial`` +binary is configured and built. + +.. note:: + CMake allows us to determine which targets are built after configuration. Our + users could ask for the ``MathFunctions`` library alone without ``Tutorial``. + CMake also has mechanisms to exclude targets from ``ALL``, the default target + which builds all the other available targets. + + However, options which completely exclude targets from the configuration are + convenient and popular, especially if configuring those targets involves + heavy-weight steps which might take some time. + + It also simplifies :command:`install()` logic, which we'll discuss in later + steps, if targets the packager is uninterested in are completely excluded. + +Helpful Resources +----------------- + +* :command:`option` +* :command:`if` + +Files to Edit +------------- + +* ``CMakeLists.txt`` + +Getting Started +--------------- + +The ``Help/guide/tutorial/Step3`` folder contains the complete, recommended +solution to ``Step1`` and the relevant ``TODOs`` for this step. Take a minute +to review and refamiliarize yourself with the ``Tutorial`` project. + +When you feel you have an understanding of the current code, start with +``TODO 1`` and complete through ``TODO 2``. + +Build and Run +------------- + +We can now reconfigure our project. However, this time we want to control the +configuration via :option:`-D <cmake -D>` flags. We again start by navigating +to ``Help/guide/tutorial/Step3`` and invoking CMake, but this time with our +configuration options. + +.. code-block:: console + + cmake -B build -DTUTORIAL_BUILD_UTILITIES=OFF + +We can now build as usual. + +.. code-block:: console + + cmake --build build + +After the build we should observe no Tutorial executable is produced. Because +cache variables are sticky even a reconfigure shouldn't change this, despite +the default-``ON`` option. + +.. code-block:: console + + cmake -B build + cmake --build build + +Will not produce the Tutorial executable, the cache variables are "locked in". +To change this we have two options. First, we can edit the file which stores +the cache variables between CMake configuration runs, the "CMake Cache". This +file is ``build/CMakeCache.txt``, in it we can find the option cache variable. + +.. code-block:: text + + //Build the Tutorial executable + TUTORIAL_BUILD_UTILITIES:BOOL=OFF + +We can change this from ``OFF`` to ``ON``, rerun the build, and we will get +our ``Tutorial`` executable. + +.. note:: + ``CMakeCache.txt`` entries are of the form ``<Name>:<Type>=<Value>``, however + the "type" is only a hint. All objects in CMake are strings, regardless of + what the cache says. + +Alternatively, we can change the value of the cache variable on the command +line, because the command line runs before ``CMakeCache.txt`` is loaded its +value take precedence over those in the cache file. + +.. code-block:: console + + cmake -B build -DTUTORIAL_BUILD_UTILITIES=ON + cmake --build build + +Doing so we observe the value in ``CMakeCache.txt`` has flipped from ``OFF`` +to ``ON``, and that the ``Tutorial`` executable is built. + +Solution +-------- + +First we create our :command:`option` to provide our cache variable with a +reasonable default value. + +.. raw:: html + + <details><summary>TODO 1: Click to show/hide answer</summary> + +.. literalinclude:: Step4/CMakeLists.txt + :caption: TODO 1: CMakeLists.txt + :name: CMakeLists.txt-option-TUTORIAL_BUILD_UTILITIES + :language: cmake + :start-at: option(TUTORIAL_BUILD_UTILITIES + :end-at: option(TUTORIAL_BUILD_UTILITIES + +.. raw:: html + + </details> + +Then we can check the cache variable to conditionally enable the ``Tutorial`` +executable (by way of adding its subdirectory). + +.. raw:: html + + <details><summary>TODO 2: Click to show/hide answer</summary> + +.. literalinclude:: Step4/CMakeLists.txt + :caption: TODO 2: CMakeLists.txt + :name: CMakeLists.txt-if-TUTORIAL_BUILD_UTILITIES + :language: cmake + :start-at: if(TUTORIAL_BUILD_UTILITIES) + :end-at: endif() + +.. raw:: html + + </details> + +Exercise 2 - ``CMAKE`` Variables +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +CMake has several important normal and cache variables provided to allow +packagers to control the build. Decisions such as compilers, default flags, +search locations for packages, and much more are all controlled by CMake's +own configuration variables. + +Among the most important are language standards. As the language standard can +have significant impact on the ABI presented by a given package. For example, +it's quite common for libraries to use standard C++ templates on later +standards, and provide polyfills on earlier standards. If a library is consumed +under different standards then ABI incompatibilities between the standard +templates and the polyfills can result in incomprehensible errors and runtime +crashes. + +Ensuring all of our targets are built under the same language standard is +achieved with the :variable:`CMAKE_<LANG>_STANDARD` cache variables. For C++, +this is ``CMAKE_CXX_STANDARD``. + +.. note:: + Because these variables are so important, it is equally important that + developers not override or shadow them in their CMLs. Shadowing + :variable:`CMAKE_<LANG>_STANDARD` in a CML because the library wants C++20, + when the packager has decided to build the rest of their libraries and + applications with C++23, can lead to the aforementioned terrible, + incomprehensible errors. + + Do not :command:`set` ``CMAKE_`` globals without very strong reasons for + doing so. We'll discuss better methods for targets to communicate + requirements like definitions and minimum standards in later steps. + +In this exercise, we'll introduce some C++20 code into our library and +executable and build them with C++20 by setting the appropriate cache variable. + +Goal +---- + +Use ``std::format`` to format printed strings instead of stream operators. To +ensure availability of ``std::format``, configure CMake to use the C++20 +standard for C++ targets. + +Helpful Resources +----------------- + +* :option:`cmake -D` +* :variable:`CMAKE_<LANG>_STANDARD` +* :variable:`CMAKE_CXX_STANDARD` +* :prop_tgt:`CXX_STANDARD` +* `cppreference \<format\> <https://en.cppreference.com/w/cpp/utility/format/format.html>`_ + +Files to Edit +------------- + +* ``Tutorial/Tutorial.cxx`` +* ``MathFunctions/MathFunctions.cxx`` + +Getting Started +--------------- + +Continue to edit files from ``Step3``. Complete ``TODO 3`` through ``TODO 7``. +We'll be modifying our prints to use ``std::format`` instead of stream +operators. + +Ensure your cache variables are set such that the Tutorial executable will be +built, using any of the methods discussed in the previous exercise. + +Build and Run +------------- + +We need to reconfigure our project with the new standard, we can do this +using the same method as our ``TUTORIAL_BUILD_UTILITIES`` cache variable. + +.. code-block:: console + + cmake -B build -DCMAKE_CXX_STANDARD=20 + +.. note:: + Configuration variables are, by convention, prefixed with the provider of the + variable. CMake configuration variables are prefixed with ``CMAKE_``, while + projects should prefix their variables with ``<PROJECT>_``. + + The tutorial configuration variables follow this convention, and are prefixed + with ``TUTORIAL_``. + +Now that we've configured with C++20, we can build as usual. + +.. code-block:: console + + cmake --build build + +Solution +-------- + +We need to include ``<format>`` and then use it. + +.. raw:: html + + <details><summary>TODO 3-5: Click to show/hide answer</summary> + +.. literalinclude:: Step4/Tutorial/Tutorial.cxx + :caption: TODO 3: Tutorial/Tutorial.cxx + :name: Tutorial/Tutorial.cxx-include-format + :language: c++ + :start-at: #include <format> + :end-at: #include <string> + +.. literalinclude:: Step4/Tutorial/Tutorial.cxx + :caption: TODO 4: Tutorial/Tutorial.cxx + :name: Tutorial/Tutorial.cxx-format1 + :language: c++ + :start-at: if (argc < 2) { + :end-at: return 1; + :append: } + :dedent: 2 + +.. literalinclude:: Step4/Tutorial/Tutorial.cxx + :caption: TODO 5: Tutorial/Tutorial.cxx + :name: Tutorial/Tutorial.cxx-format3 + :language: c++ + :start-at: // calculate square root + :end-at: outputValue); + :dedent: 2 + +.. raw:: html + + </details> + +And again for the ``MathFunctions`` library. + +.. raw:: html + + <details><summary>TODO 6-7: Click to show/hide answer</summary> + +.. literalinclude:: Step4/MathFunctions/MathFunctions.cxx + :caption: TODO 6: MathFunctions.cxx + :name: MathFunctions/MathFunctions.cxx-include-format + :language: c++ + :start-at: #include <format> + :end-at: #include <iostream> + +.. literalinclude:: Step4/MathFunctions/MathFunctions.cxx + :caption: TODO 7: MathFunctions.cxx + :name: MathFunctions/MathFunctions.cxx-format + :language: c++ + :start-at: double delta + :end-at: std::format + :dedent: 4 + +.. raw:: html + + </details> + +Exercise 3 - CMakePresets.json +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Managing these configuration values can quickly become overwhelming. In CI +systems it is appropriate to record these as part of a given CI step. For +example in a Github Actions CI step we might see something akin to the +following: + +.. code-block:: yaml + + - name: Configure and Build + run: | + cmake \ + -B build \ + -DCMAKE_BUILD_TYPE=Release \ + -DCMAKE_CXX_STANDARD=20 \ + -DCMAKE_CXX_EXTENSIONS=ON \ + -DTUTORIAL_BUILD_UTILITIES=OFF \ + # Possibly many more options + # ... + + cmake --build build + +When developing code locally, typing all these options even once might be error +prone. If a fresh configuration is needed for any reason, doing so multiple +times could be exhausting. + +There are many and varied solutions to this problem, and your choice is +ultimately up to your preferences as a developer. CLI-oriented developers +commonly use task runners to invoke CMake with their desired options for a +project. Most IDEs also have a custom mechanism for controlling CMake +configuration. + +It would be impossible to fully enumerate every possible configuration workflow +here. Instead we will explore CMake's built-in solution, known as +:manual:`CMake Presets <cmake-presets(7)>`. Presets give us a format to name +and express collections of CMake configuration options. + +.. note:: + Presets are capable of expressing entire CMake workflows, from + configuration, through building, all the way to installing the software + package. + + They are far more flexible than can we have room for here. We'll limit + ourselves to using them for configuration. + +CMake Presets come in two standard files, ``CMakePresets.json``, which is +intended to be a part of the project and tracked in source control; and +``CMakeUserPresets.json``, which is intended for local user configuration +and should not be tracked in source control. + +The simplest preset which would be of use to a developer does nothing more +than configure variables. + +.. code-block:: json + + { + "version": 4, + "configurePresets": [ + { + "name": "example-preset", + "cacheVariables": { + "EXAMPLE_FOO": "Bar", + "EXAMPLE_QUX": "Baz" + } + } + ] + } + +When invoking CMake, where previously we would have done: + +.. code-block:: console + + cmake -B build -DEXAMPLE_FOO=Bar -DEXAMPLE_QUX=Baz + +We can now use the preset: + +.. code-block:: console + + cmake -B build --preset example-preset + +CMake will search for files named ``CMakePresets.json`` and +``CMakeUserPresets.json``, and load the named configuration from them if +available. + +.. note:: + Command line flags can be mixed with presets. Command line flags have + precedence over values found in a preset. + +Presets also support limited macros, variables that can be brace-expanded +inside the preset. The only one of interest to us is the ``${sourceDir}`` macro, +which expands to the root directory of the project. We can use this to set our +build directory, skipping the :option:`-B <cmake -B>` flag when configuring +the project. + +.. code-block:: json + + { + "name": "example-preset", + "binaryDir": "${sourceDir}/build" + } + +Goal +---- + +Configure and build the tutorial using a CMake Preset instead of command line +flags. + +Helpful Resources +----------------- + +* :manual:`cmake-presets(7)` + +Files to Edit +------------- + +* ``CMakePresets.json`` + +Getting Started +--------------- + +Continue to edit files from ``Step3``. Complete ``TODO 8`` and ``TODO 9``. + +.. note:: + ``TODOs`` inside ``CMakePresets.json`` need to be *replaced*. There should + be no ``TODO`` keys left inside the file when you have completed the exercise. + +You can verify the preset is working correctly by deleting the existing build +folder before you configure, this will ensure you're not reusing the existing +CMake Cache for configuration. + +.. note:: + On CMake 3.24 and newer, the same effect can be achieved by configuring with + :option:`cmake --fresh`. + +All future configuration changes will be via the ``CMakePresets.json`` file. + +Build and Run +------------- + +We can now use the preset file to manage our configuration. + +.. code-block:: console + + cmake --preset tutorial + +Presets are capable of running the build step for us, but for this tutorial +we'll continue to run the build ourselves. + +.. code-block:: console + + cmake --build build + +Solution +-------- + +There are two changes we need to make, first we want to set the build +directory (also called the "binary directory") to the ``build`` subdirectory +of our project folder, and second we need to set the ``CMAKE_CXX_STANDARD`` to +``20``. + +.. raw:: html + + <details><summary>TODO 8-9: Click to show/hide answer</summary> + +.. code-block:: json + :caption: TODO 8-9: CMakePresets.json + :name: CMakePresets.json-initial + + { + "version": 4, + "configurePresets": [ + { + "name": "tutorial", + "displayName": "Tutorial Preset", + "description": "Preset to use with the tutorial", + "binaryDir": "${sourceDir}/build", + "cacheVariables": { + "CMAKE_CXX_STANDARD": "20" + } + } + ] + } + +.. raw:: html + + </details>
diff --git a/Help/guide/tutorial/Custom Commands and Generated Files.rst b/Help/guide/tutorial/Custom Commands and Generated Files.rst new file mode 100644 index 0000000..49c6c07 --- /dev/null +++ b/Help/guide/tutorial/Custom Commands and Generated Files.rst
@@ -0,0 +1,279 @@ +Step 7: Custom Commands and Generated Files +=========================================== + +Code generation is a ubiquitous mechanism for extending programming languages +beyond the bounds of their language model. CMake has first-class support for +Qt's Meta-Object Compiler, but very few other code generators are notable +enough to warrant that kind of effort. + +Instead, code generators tend to be bespoke and usage specific. CMake provides +facilities for describing the usage of a code generator, so projects can +add support for their individual needs. + +In this step, we will use :command:`add_custom_command` to add support for a +code generator within the tutorial project. + +Background +^^^^^^^^^^ + +Any step in the build process can generally be described in terms of its inputs +and outputs. CMake assumes that code generators and other custom processes +operate on the same principle. In this way, the code generator acts identically +to compilers, linkers, and other elements of the toolchain; when the inputs are +newer than the outputs (or the outputs don't exist), a user-specified command +will be run to update the outputs. + +.. note:: + This model assumes the outputs of a process are known before it is run. CMake + lacks the ability to describe code generators where the name and location of + the outputs depends on the *content* of the input. Various hacks exist to + shim this functionality into CMake, but they are outside the scope of this + tutorial. + +Describing a code generator (or any custom process) is usually performed in +two parts. First, the inputs and outputs are described independently of the +CMake target model, concerned only with the generation process itself. Second, +the outputs are associated with a CMake target to insert them into the CMake +target model. + +For sources, this is as simple as adding the generated files to the source list +of a ``STATIC``, ``SHARED``, or ``OBJECT`` library. For header-only generators, +it's often necessary to use an intermediary target created via +:command:`add_custom_target` to add the header file generation to the +build stage (because ``INTERFACE`` libraries have no build step). + +Exercise 1 - Using a Code Generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The primary mechanism for describing a code generator is the +:command:`add_custom_command` command. A "command", for the purpose of +:command:`add_custom_command` is either an executable available in the build +environment or a CMake executable target name. + +.. code-block:: cmake + + add_executable(Tool) + # ... + add_custom_command( + OUTPUT Generated.cxx + COMMAND Tool -i input.txt -o Generated.cxx + DEPENDS Tool input.txt + VERBATIM + ) + # ... + add_library(GeneratedObject OBJECT) + target_sources(GeneratedObject + PRIVATE + Generated.cxx + ) + +Most of the keywords are self-explanatory, with the exception of ``VERBATIM``. +This argument is effectively mandatory for legacy reasons that are uninteresting +to explain in a modern context. The curious should consult the +:command:`add_custom_command` documentation for additional details. + +The ``Tool`` executable target appears both in the ``COMMAND`` and ``DEPENDS`` +parameters. While ``COMMAND`` is sufficient for the code to build correctly, +adding the ``Tool`` itself as a dependency of the custom command ensure that +if ``Tool`` is updated, the custom command will be rerun. + +For header-only file generation, additional commands are necessary because the +library itself has no build step. We can use :command:`add_custom_target` to +create an "artificial" build step for the library. We then force the custom +target to be run before any targets which link the library with the command +:command:`add_dependencies`. + +.. code-block:: cmake + + add_custom_target(RunGenerator DEPENDS Generated.h) + + add_library(GeneratedLib INTERFACE) + target_sources(GeneratedLib + INTERFACE + FILE_SET HEADERS + BASE_DIRS + ${CMAKE_CURRENT_BINARY_DIR} + FILES + ${CMAKE_CURRENT_BINARY_DIR}/Generated.h + ) + + add_dependencies(GeneratedLib RunGenerator) + +.. note:: + We add the :variable:`CMAKE_CURRENT_BINARY_DIR`, a variable which names the + current location in the build tree where our artifacts are being placed, to + the base directories because that's the working directory our code generator + will be run inside of. Listing the ``FILES`` is unnecessary for the build and + done so here only for clarity. + +Goal +---- + +Add a generated table of pre-computed square roots to the ``MathFunctions`` +library. + +Helpful Resources +----------------- + +* :command:`add_executable` +* :command:`add_library` +* :command:`target_sources` +* :command:`add_custom_command` +* :command:`add_custom_target` +* :command:`add_dependencies` + +Files to Edit +------------- + +* ``MathFunctions/CMakeLists.txt`` +* ``MathFunctions/MakeTable/CMakeLists.txt`` +* ``MathFunctions/MathFunctions.cxx`` + +Getting Started +--------------- + +The ``MathFunctions`` library has been edited to use a pre-computed table when +given a number less than 10. However, the hardcoded table is not particularly +accurate, containing only the nearest truncated integer value. + +The ``MakeTable.cxx`` source file describes a program which will generate a +better table. It takes a single argument as input, the file name of the table +to be generated. + +Complete ``TODO 1`` through ``TODO 10``. + +Build and Run +------------- + +No special configuration is needed, configure and build as usual. Note that +the ``MakeTable`` executable is sequenced before ``MathFunctions``. + +.. code-block:: console + + cmake --preset tutorial + cmake --build build + +Verify the output of ``Tutorial`` now uses the pre-computed table for values +less than 10. + +Solution +-------- + +First we add a new executable to generate the tables, adding the +``MakeTable.cxx`` file as a source. + +.. raw:: html + + <details><summary>TODO 1-2: Click to show/hide answer</summary> + +.. literalinclude:: Step8/MathFunctions/MakeTable/CMakeLists.txt + :caption: TODO 1-2: MathFunctions/MakeTable/CMakeLists.txt + :name: MathFunctions/MakeTable/CMakeLists.txt-add_executable + :language: cmake + :start-at: add_executable + :end-at: MakeTable.cxx + :append: ) + +.. raw:: html + + </details> + +Then we add a custom command which produces the table, and custom target which +depends on the table. + +.. raw:: html + + <details><summary>TODO 3-4: Click to show/hide answer</summary> + +.. literalinclude:: Step8/MathFunctions/MakeTable/CMakeLists.txt + :caption: TODO 3-4: MathFunctions/MakeTable/CMakeLists.txt + :name: MathFunctions/MakeTable/CMakeLists.txt-add_custom_command + :language: cmake + :start-at: add_custom_command + :end-at: add_custom_target + +.. raw:: html + + </details> + +We need to add an interface library which describes the output which will +appear in :variable:`CMAKE_CURRENT_BINARY_DIR`. The ``FILES`` parameter is +optional. + +.. raw:: html + + <details><summary>TODO 5-6: Click to show/hide answer</summary> + +.. literalinclude:: Step8/MathFunctions/MakeTable/CMakeLists.txt + :caption: TODO 5-6: MathFunctions/MakeTable/CMakeLists.txt + :name: MathFunctions/MakeTable/CMakeLists.txt-add_library + :language: cmake + :start-at: add_library + :end-at: SqrtTable.h + :append: ) + +.. raw:: html + + </details> + +Now that all the targets are described, we can force the custom target to run +before any dependents of the interface library by associating them with +:command:`add_dependencies`. + +.. raw:: html + + <details><summary>TODO 7: Click to show/hide answer</summary> + +.. literalinclude:: Step8/MathFunctions/MakeTable/CMakeLists.txt + :caption: TODO 7: MathFunctions/MakeTable/CMakeLists.txt + :name: MathFunctions/MakeTable/CMakeLists.txt-add_dependencies + :language: cmake + :start-at: add_dependencies + :end-at: add_dependencies + +.. raw:: html + + </details> + +We are ready to add the interface library to the linked libraries of +``MathFunctions``, and add the entire ``MakeTable`` folder to the project. + +.. raw:: html + + <details><summary>TODO 8-9: Click to show/hide answer</summary> + +.. literalinclude:: Step8/MathFunctions/CMakeLists.txt + :caption: TODO 8: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-link-sqrttable + :language: cmake + :start-at: target_link_libraries(MathFunctions + :end-at: ) + +.. literalinclude:: Step8/MathFunctions/CMakeLists.txt + :caption: TODO 9: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-add-maketable + :language: cmake + :start-at: add_subdirectory(MakeTable + :end-at: add_subdirectory(MakeTable + +.. raw:: html + + </details> + +Finally, we update the ``MathFunctions`` library itself to take advantage of +the generated table. + +.. raw:: html + + <details><summary>TODO 10: Click to show/hide answer</summary> + +.. literalinclude:: Step8/MathFunctions/MathFunctions.cxx + :caption: TODO 10: MathFunctions/MathFunctions.cxx + :name: MathFunctions/MathFunctions.cxx-include-sqrttable + :language: c++ + :start-at: #include <SqrtTable.h> + :end-at: { + +.. raw:: html + + </details>
diff --git a/Help/guide/tutorial/Finding Dependencies.rst b/Help/guide/tutorial/Finding Dependencies.rst new file mode 100644 index 0000000..0ad3abc --- /dev/null +++ b/Help/guide/tutorial/Finding Dependencies.rst
@@ -0,0 +1,529 @@ +Step 10: Finding Dependencies +============================= + +In C/C++ software development, managing build dependencies is consistently +one of the highest ranked challenges facing modern developers. CMake provides +an extensive toolset for discovering and validating dependencies of different +kinds. + +However, for correctly packaged projects there is no need to use these advanced +tools. Many popular library and utility projects today produce correct install +trees, like the one we set up in ``Step 9``, which are easy is to integrate +into CMake. + +In this best-case scenario, we only need the :command:`find_package` to +import dependencies into our project. + +Background +^^^^^^^^^^ + +There are five principle commands used for discovering dependencies with +CMake, the first four are: + + :command:`find_file` + Finds and reports the full path to a named file, this tends to be the + most flexible of the ``find`` commands. + + :command:`find_library` + Finds and reports the full path to a static archive or shared object + suitable for use with :command:`target_link_libraries`. + + :command:`find_path` + Finds and reports the full path to a directory *containing* a file. This + is most commonly used for headers in combination with + :command:`target_include_directories`. + + :command:`find_program` + Finds and reports and invocable name or path for a program. Often used in + combination with :command:`execute_process` or :command:`add_custom_command`. + +These commands should be considered "backup", used when the primary find command +is unsuitable. The primary find command is :command:`find_package`. It uses +comprehensive built-in heuristics and upstream-provided packaging files to +provide the best interface to the requested dependency. + +Exercise 1 - Using ``find_package()`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The search paths and behaviors used by :command:`find_package` are fully +described in its documentation, but much too verbose to replicate here. Suffice +to say it searches well known, lesser known, obscure, and user-provided +locations attempting to find a package which meets the requirements given to it. + +.. code-block:: cmake + + find_package(ForeignLibrary) + +The best way to use :command:`find_package` is to ensure all dependencies have +been installed to a single install tree prior to the build, and then make the +location of that install tree known to :command:`find_package` via the +:variable:`CMAKE_PREFIX_PATH` variable. + +.. note:: + Building and installing dependencies can itself be an immense amount of labor. + While this tutorial will do so for illustration purposes, it is **extremely** + recommended that a package manager be used for project-local dependency + management. + +:command:`find_package` accepts several parameters besides the package to be +found. The most notable are: + +* A positional ``<version>`` argument, for describing a version to be checked + against the package's config version file. This should be used sparingly, + it is better to control the version of the dependency being installed via + a package manager than possibly break the build on otherwise innocuous + version updates. + + If the package is known to rely on an older version of a dependency, it + may be appropriate to use a version requirement. + +* ``REQUIRED`` for non-optional dependencies which should abort the build + if not found. + +* ``QUIET`` for optional dependencies which should not report anything to + users when not found. + +:command:`find_package` reports its results via ``<PackageName>_FOUND`` +variables, which will be set to a true or false value for found and not found +packages respectively. + +Goal +---- + +Integrate an externally installed test framework into the Tutorial project. + +Helpful Resources +----------------- + +* :command:`find_package` +* :command:`target_link_libraries` + +Files to Edit +------------- + +* ``TutorialProject/CMakePresets.json`` +* ``TutorialProject/Tests/CMakeLists.txt`` +* ``TutorialProject/Tests/TestMathFunctions.cxx`` + +Getting Started +--------------- + +The ``Step10`` folder is organized differently than previous steps. The tutorial +project we need to edit is under ``Step10/TutorialProject``. Another project +is now present, ``SimpleTest``, as well as a partially populated install tree +which we will use in later exercises. You do not need to edit anything in these +other directories for this exercise, all ``TODOs`` and solution steps are for +``TutorialProject``. + +The ``SimpleTest`` package provides two useful constructs, the +``SimpleTest::SimpleTest`` target to be linked into a test binary, and the +``simpletest_discover_tests`` function for automatically adding tests to +CTest. + +Similar to other test frameworks, ``simpletest_discover_tests`` only needs +to be passed the name of the executable target containing the tests. + +.. code-block:: cmake + + simpletest_discover_tests(MyTestExe) + +The ``TestMathFunctions.cxx`` file has been updated to use the ``SimpleTest`` +framework in the vein of GoogleTest or Catch2. Perform ``TODO 1`` through +``TODO 5`` in order to use the new test framework. + +.. note:: + It may go without saying, but ``SimpleTest`` is a very poor test framework + which only facially resembles a functional testing library. While much of + the CMake code in this tutorial could be used unaltered in other projects, + you should not use ``SimpleTest`` outside this tutorial, or try to learn from + the CMake code it provides. + +Build and Run +------------- + +First we must install the ``SimpleTest`` framework. Navigate to the +``Help/guide/Step10/SimpleTest`` directory and run the following commands + +.. code-block:: console + + cmake --preset tutorial + cmake --install build + +.. note:: + The ``SimpleTest`` preset sets up everything needed to install ``SimpleTest`` + for the tutorial. For reasons that are beyond the scope of this tutorial, + there is no need to build or provide any other configuration for + ``SimpleTest``. + +We can observe that the ``Step10/install`` directory has now been populated by +the ``SimpleTest`` header and package files. + +Now we can configure and build the Tutorial project as per usual, navigating to +the ``Help/guide/Step10/TutorialProject`` and running: + +.. code-block:: console + + cmake --preset tutorial + cmake --build build + +Verify that the ``SimpleTest`` framework has been consumed correctly by running +the tests with CTest. + +Solution +-------- + +First we call :command:`find_package` to discover the ``SimpleTest`` package. +We do this with ``REQUIRED`` because the tests cannot build without +``SimpleTest``. + +.. raw:: html + + <details><summary>TODO 1 Click to show/hide answer</summary> + +.. literalinclude:: Step11/TutorialProject/Tests/CMakeLists.txt + :caption: TODO 1: TutorialProject/Tests/CMakeLists.txt + :name: TutorialProject/Tests/CMakeLists.txt-find_package + :language: cmake + :start-at: find_package + :end-at: find_package + +.. raw:: html + + </details> + +Next we add the ``SimpleTest::SimpleTest`` target to ``TestMathFunctions`` + +.. raw:: html + + <details><summary>TODO 2 Click to show/hide answer</summary> + +.. literalinclude:: Step11/TutorialProject/Tests/CMakeLists.txt + :caption: TODO 2: TutorialProject/Tests/CMakeLists.txt + :name: TutorialProject/Tests/CMakeLists.txt-link-simple-test + :language: cmake + :start-at: target_link_libraries(TestMathFunctions + :end-at: ) + +.. raw:: html + + </details> + +Now we can replace our test description code with a call to +``simpletest_discover_tests``. + +.. raw:: html + + <details><summary>TODO 3 Click to show/hide answer</summary> + +.. literalinclude:: Step11/TutorialProject/Tests/CMakeLists.txt + :caption: TODO 3: TutorialProject/Tests/CMakeLists.txt + :name: TutorialProject/Tests/CMakeLists.txt-simpletest_discover_tests + :language: cmake + :start-at: simpletest_discover_tests + :end-at: simpletest_discover_tests + +.. raw:: html + + </details> + +We ensure :command:`find_package` can discover ``SimpleTest`` by +adding the install tree to :variable:`CMAKE_PREFIX_PATH`. + +.. raw:: html + + <details><summary>TODO 4 Click to show/hide answer</summary> + +.. literalinclude:: Step11/TutorialProject/CMakePresets.json + :caption: TODO 4: TutorialProject/CMakePresets.json + :name: TutorialProject/CMakePresets.json-CMAKE_PREFIX_PATH + :language: json + :start-at: cacheVariables + :end-at: TUTORIAL_ENABLE_IPO + :dedent: 6 + :append: } + +.. raw:: html + + </details> + +Finally, we update the tests to use the macros provided by ``SimpleTest`` by +removing the placeholders and including the appropriate header. + +.. raw:: html + + <details><summary>TODO 5 Click to show/hide answer</summary> + +.. literalinclude:: Step11/TutorialProject/Tests/TestMathFunctions.cxx + :caption: TODO 5: TutorialProject/Tests/TestMathFunctions.cxx + :name: TutorialProject/Tests/TestMathFunctions.cxx-simpletest + :language: c++ + :start-at: #include <MathFunctions.h> + :end-at: { + +.. raw:: html + + </details> + +Exercise 2 - Transitive Dependencies +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Libraries often build on one another. A multimedia application may depend on a +library which provides support for various container formats, which may in turn +rely on one or more other libraries for compression algorithms. + +We need to express these transitive requirements inside the package config +files we place in the install tree. We do so with the +:module:`CMakeFindDependencyMacro` module, which provides a safe mechanism for +installed packages to recursively discover one another. + +.. code-block:: cmake + + include(CMakeFindDependencyMacro) + find_dependency(zlib) + +:module:`find_dependency() <CMakeFindDependencyMacro>` also forwards arguments +from the top-level :command:`find_package` call. If :command:`find_package` is +called with ``QUIET`` or ``REQUIRED``, +:module:`find_dependency() <CMakeFindDependencyMacro>` will also use ``QUIET`` +and/or ``REQUIRED``. + +Goal +---- + +Add a dependency to ``SimpleTest`` and ensure that packages which rely on +``SimpleTest`` also discover this transitive dependency. + +Helpful Resources +----------------- + +* :module:`CMakeFindDependencyMacro` +* :command:`find_package` +* :command:`target_link_libraries` + +Files to Edit +------------- + +* ``SimpleTest/CMakeLists.txt`` +* ``SimpleTest/cmake/SimpleTestConfig.cmake`` + +Getting Started +--------------- + +For this step we will only be editing the ``SimpleTest`` project. The transitive +dependency, ``TransitiveDep``, is a dummy dependency which provides no behavior. +However CMake doesn't know this and the ``TutorialProject`` tests will fail to +configure and build if CMake cannot find all required dependencies. + +The ``TransitiveDep`` package has already been installed to the +``Step10/install`` tree. We do not need to install it as we did with +``SimpleTest``. + +Complete ``TODO 6`` through ``TODO 8``. + +Build and Run +------------- + +We need to reinstall the SimpleTest framework. Navigate to the +``Help/guide/Step10/SimpleTest`` directory and run the same commands as before. + +.. code-block:: console + + cmake --preset tutorial + cmake --install build + +Now we can reconfigure and rebuild the ``TutorialProject``, navigate to +``Help/guide/Step10/TutorialProject`` and perform the usual steps to do so. + +.. code-block:: console + + cmake --preset tutorial + cmake --build build + +If the build passed we have likely successfully propagated the transitive +dependency. Verify this by searching the ``CMakeCache.txt`` of +``TutorialProject`` for an entry named ``TransitiveDep_DIR``. This demonstrates +the ``TutorialProject`` searched for an found ``TransitiveDep`` even though it +has no direct requirement for it. + +Solution +-------- + +First we call :command:`find_package` to discover the ``TransitiveDep`` package. +We use ``REQUIRED`` to verify we have found ``TransitiveDep``. + +.. raw:: html + + <details><summary>TODO 6 Click to show/hide answer</summary> + +.. literalinclude:: Step11/SimpleTest/CMakeLists.txt + :caption: TODO 6: SimpleTest/CMakeLists.txt + :name: SimpleTest/CMakeLists.txt-find_package + :language: cmake + :start-at: find_package + :end-at: find_package + +.. raw:: html + + </details> + +Next we add the ``TransitiveDep::TransitiveDep`` target to ``SimpleTest``. + +.. raw:: html + + <details><summary>TODO 7 Click to show/hide answer</summary> + +.. literalinclude:: Step11/SimpleTest/CMakeLists.txt + :caption: TODO 7: SimpleTest/CMakeLists.txt + :name: SimpleTest/CMakeLists.txt-link-transitive-dep + :language: cmake + :start-at: target_link_libraries(SimpleTest + :end-at: ) + +.. raw:: html + + </details> + +.. note:: + If we built ``TutorialProject`` at this point, we would expect the + configuration to fail due to the ``TransitiveDep::TransitiveDep`` target + being unavailable inside that project. + +Finally, we include the :module:`CMakeFindDependencyMacro` and call +:module:`find_dependency() <CMakeFindDependencyMacro>` inside the ``SimpleTest`` +package config file to propagate the transitive dependency. + +.. raw:: html + + <details><summary>TODO 8 Click to show/hide answer</summary> + +.. literalinclude:: Step11/SimpleTest/cmake/SimpleTestConfig.cmake + :caption: TODO 8: SimpleTest/cmake/SimpleTestConfig.cmake + :name: SimpleTest/cmake/SimpleTestConfig.cmake-find_dependency + :language: cmake + :start-at: include + :end-at: find_dependency + +.. raw:: html + + </details> + + </details> + +Exercise 3 - Finding Other Kinds of Files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In a perfect world every dependency we care about would be packaged correctly, +or at least some other developer would have written a module that discovers it +for us. We do not live in a perfect world, and sometimes we will have to get +our hands dirty and discover build requirements manually. + +For this we have the other find commands enumerated earlier in the step, such +as :command:`find_path`. + +.. code-block:: cmake + + find_path(PackageIncludeFolder Package.h REQUIRED + PATH_SUFFIXES + Package + ) + target_include_directories(MyApp + PRIVATE + ${PackageIncludeFolder} + ) + +Goal +---- + +Add an unpackaged header to the ``Tutorial`` executable of the +``TutorialProject``. + +Helpful Resources +----------------- + +* :command:`find_path` +* :command:`target_include_directories` + +Files to Edit +------------- + +* ``TutorialProject/Tutorial/CMakeLists.txt`` +* ``TutorialProject/Tutorial/Tutorial.cxx`` + +Getting Started +--------------- + +For this step we will only be editing the ``TutorialProject`` project. The +unpackaged header, ``Unpackaged/Unpackaged.h`` has already been installed to the +``Step10/install`` tree. + +Complete ``TODO 9`` through ``TODO 11``. + +Build and Run +------------- + +There are no special build steps for this exercise, navigate to +``Help/guide/Step10/TutorialProject`` and perform the usual build. + +.. code-block:: console + + cmake --build build + +If the build passed we have successfully added the ``Unpackaged`` include +directory to the project. + +Solution +-------- + +First we call :command:`find_path` to discover the ``Unpackaged`` include +directory. We use ``REQUIRED`` because building ``Tutorial`` will fail if +we cannot locate the ``Unpackaged.h`` header. + +.. raw:: html + + <details><summary>TODO 9 Click to show/hide answer</summary> + +.. literalinclude:: Step11/TutorialProject/Tutorial/CMakeLists.txt + :caption: TODO 9: TutorialProject/Tutorial/CMakeLists.txt + :name: TutorialProject/Tutorial/CMakeLists.txt-find_path + :language: cmake + :start-at: find_path + :end-at: ) + +.. raw:: html + + </details> + +Next we add the discovered path to ``Tutorial`` using +:command:`target_include_directories`. + +.. raw:: html + + <details><summary>TODO 10 Click to show/hide answer</summary> + +.. literalinclude:: Step11/TutorialProject/Tutorial/CMakeLists.txt + :caption: TODO 10: TutorialProject/Tutorial/CMakeLists.txt + :name: TutorialProject/Tutorial/CMakeLists.txt-target_include_directories + :language: cmake + :start-at: target_include_directories + :end-at: ) + +.. raw:: html + + </details> + +Finally, we edit ``Tutorial.cxx`` to include the discovered header. + +.. raw:: html + + <details><summary>TODO 11 Click to show/hide answer</summary> + +.. literalinclude:: Step11/TutorialProject/Tutorial/Tutorial.cxx + :caption: TODO 11: TutorialProject/Tutorial/Tutorial.cxx + :name: TutorialProject/Tutorial/Tutorial.cxx-include-unpackaged + :language: c++ + :start-at: #include <MathFunctions.h> + :end-at: #include <Unpackaged.h> + +.. raw:: html + + </details>
diff --git a/Help/guide/tutorial/Getting Started with CMake.rst b/Help/guide/tutorial/Getting Started with CMake.rst new file mode 100644 index 0000000..19c811d --- /dev/null +++ b/Help/guide/tutorial/Getting Started with CMake.rst
@@ -0,0 +1,805 @@ +Step 1: Getting Started with CMake +================================== + +This first step in the CMake tutorial is intended as a quick-start into writing +useful builds for small projects with CMake. By the end, you will be able to +describe executables, libraries, source and header files, and the linkage +relationships between them using CMake. + +Each exercise in this step will start with a discussion of the concepts and +commands needed for the exercise. Then, a goal and list of helpful resources are +provided. Each file in the ``Files to Edit`` section is in the ``Step1`` +directory and contains one or more ``TODO`` comments. Each ``TODO`` represents +a line or two of code to change or add. The ``TODOs`` are intended to be +completed in numerical order, first complete ``TODO 1`` then ``TODO 2``, etc. + +.. note:: + Each step in the tutorial builds on the previous, but the steps are not + strictly contiguous. Code not relevant to learning CMake, such as C++ + function implementations or CMake code outside the scope of the tutorial, + will sometimes be added between steps. + +The ``Getting Started`` section will give some helpful hints and guide you +through the exercise. Then the ``Build and Run`` section will walk step-by-step +through how to build and test the exercise. Finally, at the end of each exercise +the intended solution is reviewed. + +Background +^^^^^^^^^^ + +Typical usage of CMake revolves around one or more files named +``CMakeLists.txt``. This file is sometimes referred to as a "lists file" or +"CML". Within a given software project, a ``CMakeLists.txt`` will exist within +any directory where we want to provide instructions to CMake on how to handle +files and operations local to that directory or subdirectories. Each consists of +a set of commands which describe some information or actions relevant to +building the software project. + +Not every directory in a software project needs a CML, but it's strongly +recommended that the project root contains one. This will serve as the entry +point for CMake for its initial setup during configuration. This *root* CML +should always contain the same two commands at or near the top the file. + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.23) + + project(MyProjectName) + +The :command:`cmake_minimum_required` is a compatibility guarantee provided by +CMake to the project developer. When called, it ensures that CMake will adopt +the behavior of the listed version. If a later version of CMake is invoked on a +CML containing the above code, it will act exactly as if it were CMake 3.23. + +The :command:`project` command is a conceptually simple command which provides a +complex function. It informs CMake that what follows is the description of a +distinct software project of a given name (as opposed to a shell-like script). +When CMake sees the :command:`project` command it performs various checks to +ensure the environment is suitable for building software; such as checking for +compilers and other build tooling, and discovering properties like the +endianness of the host and target machines. + +.. note:: + While links to complete documentation are provided for every command, it is + not intended the reader understand the full semantics of each CMake command + they use. Effectively learning CMake, like any piece of software, is an + incremental process. + +The rest of this tutorial step will be chiefly concerned with the usage of four +more commands. The :command:`add_executable` and :command:`add_library` commands +for describing output artifacts the software project wants to produce, the +:command:`target_sources` command for associating input files with their +respective output artifacts, and the :command:`target_link_libraries` command +for associating output artifacts with one another. + +These four commands are the backbone of most CMake usage. As we'll learn, they +are sufficient for describing the majority of a typical project's requirements. + +Exercise 1 - Building an Executable +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The most basic CMake project is an executable built from a single source code +file. For simple projects like this, a ``CMakeLists.txt`` file with only +four commands is needed. + +.. note:: + Although upper, lower and mixed case commands are supported by CMake, + lower case commands are preferred and will be used throughout the tutorial. + +The first two commands we have already introduced, :command:`cmake_minimum_required` +and :command:`project`. There is no usage of CMake where the first command in a +root CML will be anything other than :command:`cmake_minimum_required`. There +are some advanced usages where :command:`project` might not be the second +command in a CML, but for our purposes it always will be. + +The next command we need is :command:`add_executable`. +This command creates a *target*. In CMake lingo, a target is a name the +developer gives to a collection of properties. + +Some examples of properties a target might want to keep track of are: + - The artifact kind (executable, library, header collection, etc) + - Source files + - Include directories + - Output name of an executable or library + - Dependencies + - Compiler and linker flags + +The mechanisms of CMake are often best understood as describing and manipulating +targets and their properties. There are many more properties than those listed +here. Documentation of CMake commands will often discuss their function in terms +of the target properties they operate on. + +Targets themselves are simply names, a handle to this collection of properties. +Using the :command:`add_executable` command is as easy as specifying the name +we want to use for the target. + +.. code-block:: cmake + + add_executable(MyProgram) + +Now that we have a name for our target, we can start associating properties +with it like source files we want to build and link. The primary command for +this is :command:`target_sources`, which takes as arguments a target name +followed by one or more collections of files. + +.. code-block:: cmake + + target_sources(MyProgram + PRIVATE + main.cxx + ) + +.. note:: + Paths in CMake are generally either absolute, or relative to the + :variable:`CMAKE_CURRENT_SOURCE_DIR`. We haven't talked about variables like + that yet, so you can read this as "relative to the location of the current + CML". + +Each collection of files is prefixed by a :ref:`scope keyword <Target Command Scope>`. +We'll discuss the complete semantics of these keywords when we talk about +linking targets together, but the quick explanation is these describe how a +property should be inherited by dependents of our target. + +Typically, nothing depends on an executable. Other programs and libraries don't +need to link to an executable, or inherit headers, or anything of that nature. +So the appropriate scope to use here is ``PRIVATE``, which informs CMake that +this property only belongs to ``MyProgram`` and is not inheritable. + +.. note:: + This rule is true almost everywhere. Outside advanced and esoteric usages, + the scope keyword for executables should *always* be ``PRIVATE``. The same + holds for implementation files generally, regardless of whether the target + is an executable or a library. The only target which needs to "see" the + ``.cxx`` files is the target building them. + +Goal +---- + +Understand how to create a simple CMake project with a single executable. + +Helpful Resources +----------------- + +* :command:`project` +* :command:`cmake_minimum_required` +* :command:`add_executable` +* :command:`target_sources` + +Files to Edit +------------- + +* ``CMakeLists.txt`` + +Getting Started +---------------- + +The source code for ``Tutorial.cxx`` is provided in the +``Help/guide/tutorial/Step1/Tutorial`` directory and can be used to compute the +square root of a number. This file does not need to be edited in this exercise. + +In the parent directory, ``Help/guide/tutorial/Step1``, is a ``CMakeLists.txt`` +file which you will complete. Start with ``TODO 1`` and work through ``TODO 4``. + +Build and Run +------------- + +Once ``TODO 1`` through ``TODO 4`` have been completed, we are ready to build +and run our project! First, run the :manual:`cmake <cmake(1)>` executable or the +:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it +with your chosen build tool. + +For example, from the command line we could navigate to the +``Help/guide/tutorial/Step1`` directory and invoke CMake for configuration +as follows: + +.. code-block:: console + + cmake -B build + +The :option:`-B <cmake -B>` flag tells CMake to use the given relative +path as the location to generate files and store artifacts during the build +process. If it is omitted, the current working directory is used. It is +generally considered bad practice to do "in-source" builds, placing these +generated files in the source tree itself. + +Next, tell CMake to build the project with +:option:`cmake --build <cmake --build>`, passing it the same relative path +we did with the :option:`-B <cmake -B>` flag. + +.. code-block:: console + + cmake --build build + +The ``Tutorial`` executable will be built into the ``build`` directory. For +multi-config generators (e.g. Visual Studio), it might be placed in a +subdirectory such as ``build/Debug``. + +Finally, try to use the newly built ``Tutorial``: + +.. code-block:: console + + Tutorial 4294967296 + Tutorial 10 + Tutorial + +.. note:: + Depending on the shell, the correct syntax may be ``Tutorial``, + ``./Tutorial``, ``.\Tutorial``, or even ``.\Tutorial.exe``. For simplicity, + the exercises will use ``Tutorial`` throughout. + +Solution +-------- + +As mentioned above, a four command ``CMakeLists.txt`` is all that we need to get +up and running. The first line should be :command:`cmake_minimum_required`, to +set the CMake version as follows: + +.. raw:: html + + <details><summary>TODO 1: Click to show/hide answer</summary> + +.. literalinclude:: Step3/CMakeLists.txt + :caption: TODO 1: CMakeLists.txt + :name: CMakeLists.txt-cmake_minimum_required + :language: cmake + :start-at: cmake_minimum_required + :end-at: cmake_minimum_required + +.. raw:: html + + </details> + +The next step to make a basic project is to use the :command:`project` +command as follows to set the project name and inform CMake we intend to build +software with this ``CMakeLists.txt``. + +.. raw:: html + + <details><summary>TODO 2: Click to show/hide answer</summary> + +.. literalinclude:: Step3/CMakeLists.txt + :caption: TODO 2: CMakeLists.txt + :name: CMakeLists.txt-project + :language: cmake + :start-at: project + :end-at: project + +.. raw:: html + + </details> + +Now we can setup our executable target for the Tutorial with :command:`add_executable`. + +.. raw:: html + + <details><summary>TODO 3: Click to show/hide answer</summary> + +.. literalinclude:: Step3/Tutorial/CMakeLists.txt + :caption: TODO 3: CMakeLists.txt + :name: CMakeLists.txt-add_executable + :language: cmake + :start-at: add_executable + :end-at: add_executable + +.. raw:: html + + </details> + +Finally, we can associate our source file with the Tutorial executable target +using :command:`target_sources`. + +.. raw:: html + + <details><summary>TODO 4: Click to show/hide answer</summary> + +.. code-block:: cmake + :caption: TODO 4: CMakeLists.txt + :name: CMakeLists.txt-target_sources + + target_sources(Tutorial + PRIVATE + Tutorial/Tutorial.cxx + ) + + +.. raw:: html + + </details> + +Exercise 2 - Building a Library +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +We only need to introduce one more command to build a library, +:command:`add_library`. This works exactly like :command:`add_executable`, but +for libraries. + +.. code-block:: cmake + + add_library(MyLibrary) + +However, now is a good time to introduce header files. Header files are not +directly built as translation units, which is to say they are not a *build* +requirement. They are a *usage* requirement. We need to know about header files +in order to build other parts of a given target. + +As such, header files are described slightly differently than implementation +files like ``tutorial.cxx``. They're also going to need different +:ref:`scope keywords <Target Command Scope>` than the ``PRIVATE`` keyword we +have used so far. + +To describe a collection of header files, we're going to use what's known as a +``FILE_SET``. + +.. code-block:: cmake + + target_sources(MyLibrary + PRIVATE + library_implementation.cxx + + PUBLIC + FILE_SET myHeaders + TYPE HEADERS + BASE_DIRS + include + FILES + include/library_header.h + ) + +This is a lot of complexity, but we'll go through it point by point. First, +note that we have our implementation file as a ``PRIVATE`` source, same as +with the executable previously. However, we now use ``PUBLIC`` for our +header file. This allows consumers of our library to "see" the library's +header files. + +.. note:: + We're not quite ready to discuss the full semantics of scope keywords. We'll + cover them more completely in Exercise 3. + +Following the scope keyword is a ``FILE_SET``, a collection of files to be +described as a single unit. A ``FILE_SET`` consists of the following parts: + +* ``FILE_SET <name>`` is the name of the ``FILE_SET``. This is a handle which + we can use to describe the collection in other contexts. + +* ``TYPE <type>`` is the kind of files we are describing. Most commonly this + will be headers, but newer versions of CMake support other types like C++20 + modules. + +* ``BASE_DIRS`` is the "base" locations for the files. This can be most easily + understood as the locations that will be described to compilers for header + discovery via ``-I`` flags. + +* ``FILES`` is the list of files, same as with the implementation sources list + earlier. + +This is a lot of information to describe, so there are some useful shortcuts +we can take. Notably, if the ``FILE_SET`` name is the same as the type, we +don't need to provide the ``TYPE`` field. + +.. code-block:: cmake + + target_sources(MyLibrary + PRIVATE + library_implementation.cxx + + PUBLIC + FILE_SET HEADERS + BASE_DIRS + include + FILES + include/library_header.h + ) + +There are other shortcuts we can take, but we'll discuss those more in later +steps. + +Goal +---- + +Build a library. + +Helpful Resources +----------------- + +* :command:`add_library` +* :command:`target_sources` + +Files to Edit +------------- + +* ``CMakeLists.txt`` + +Getting Started +--------------- + +Continue editing files in the ``Step1`` directory. Start with ``TODO 5`` and +complete through ``TODO 6``. + +Build and Run +------------- + +Let's build our project again. Since we already created a build directory and +ran CMake for Exercise 1, we can skip to the build step: + +.. code-block:: console + + cmake --build build + +We should be able to see our library created alongside the Tutorial executable. + +Solution +-------- + +We start by adding the library target in the same manner as the Tutorial +executable. + +.. raw:: html + + <details><summary>TODO 5: Click to show/hide answer</summary> + +.. literalinclude:: Step3/MathFunctions/CMakeLists.txt + :caption: TODO 5: CMakeLists.txt + :name: CMakeLists.txt-add_library + :language: cmake + :start-at: add_library + :end-at: add_library + +.. raw:: html + + </details> + +Next we need to describe the source files. For the implementation file, +``MathFunctions.cxx``, this is straight-forward; for the header file +``MathFunctions.h`` we will need to use a ``FILE_SET``. + +We can either give this ``FILE_SET`` its own name, or use the shortcut of naming +it ``HEADERS``. For this tutorial, we'll be using the shortcut, but either +solution is valid. + +For ``BASE_DIRS`` we need to determine the directory which will allow for the +desired ``#include <MathFunctions.h>`` directive. To achieve this, the +``MathFunctions`` folder itself will be a base directory. We would make a +different choice if the desired include directive were +``#include <MathFunctions/MathFunctions.h>`` or similar. + +.. raw:: html + + <details><summary>TODO 6: Click to show/hide answer</summary> + +.. code-block:: cmake + :caption: TODO 6: CMakeLists.txt + :name: CMakeLists.txt-library_sources + + target_sources(MathFunctions + PRIVATE + MathFunctions/MathFunctions.cxx + + PUBLIC + FILE_SET HEADERS + BASE_DIRS + MathFunctions + FILES + MathFunctions/MathFunctions.h + ) + +.. raw:: html + + </details> + +Exercise 3 - Linking Together Libraries and Executables +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +We're ready to combine our library with our executable, for this we must +introduce a new command, :command:`target_link_libraries`. The name of this +command can be somewhat misleading, as it does a great deal more than just +invoke linkers. It describes relationships between targets generally. + +.. code-block:: cmake + + target_link_libraries(MyProgram + PRIVATE + MyLibrary + ) + +We're finally ready to discuss the :ref:`scope keywords <Target Command Scope>`. +There are three of them, ``PRIVATE``, ``INTERFACE``, and ``PUBLIC``. These +describe how properties are made available to targets. + +* A ``PRIVATE`` property (also called a "non-interface" property) is only + available to the target which owns it, for example ``PRIVATE`` headers will + only be visible to the target they're attached to. + +* An ``INTERFACE`` property is only available to targets *which link* the + owning target. The owning target does not have access to these properties. A + header-only library is an example of a collection of ``INTERFACE`` properties, + as header-only libraries do not build anything themselves and do not need to + access their own files. + +* ``PUBLIC`` is not a distinct kind of property, but rather is the union of the + ``PRIVATE`` and ``INTERFACE`` properties. Thus requirements described with + ``PUBLIC`` are available to both the owning target and consuming targets. + +Consider the following concrete example: + +.. code-block:: cmake + + target_sources(MyLibrary + PRIVATE + FILE_SET internalOnlyHeaders + TYPE HEADERS + FILES + InternalOnlyHeader.h + + INTERFACE + FILE_SET consumerOnlyHeaders + TYPE HEADERS + FILES + ConsumerOnlyHeader.h + + PUBLIC + FILE_SET publicHeaders + TYPE HEADERS + FILES + PublicHeader.h + ) + +.. note:: + We excluded ``BASE_DIRS`` for each file set here, that's another shortcut. + When excluded, ``BASE_DIRS`` defaults to the current source directory. + +The ``MyLibrary`` target has several properties which will be modified by this +call to :command:`target_sources`. Until now we've used the term "properties" +generically, but properties are themselves named values we can reason about. +Two specific properties which will be modified here are :prop_tgt:`HEADER_SETS` +and :prop_tgt:`INTERFACE_HEADER_SETS`, which both contain lists of header file +sets added via :command:`target_sources`. + +The value ``internalOnlyHeaders`` will be added to :prop_tgt:`HEADER_SETS`, +``consumerOnlyHeaders`` to :prop_tgt:`INTERFACE_HEADER_SETS`, and +``publicHeaders`` will be added to both. + +When a given target is being built, it will use its own *non-interface* +properties (eg, :prop_tgt:`HEADER_SETS`), combined with the *interface* +properties of any targets it links to (eg, :prop_tgt:`INTERFACE_HEADER_SETS`). + +.. note:: + **It is not necessary to reason about CMake properties at this level of + detail.** The above is described for completeness. Most of the time you don't + need to be concerned with the specific properties a command is modifying. + + Scope keywords have a simple intuition associated with them, when considering + a command from the point of view of the target it is being applied to: + **PRIVATE** is for me, **INTERFACE** is for others, **PUBLIC** is for all of + us. + +Goal +---- + +In the Tutorial executable, use the ``sqrt()`` function provided by the +``MathFunctions`` library. + +Helpful Resources +----------------- + +* :command:`target_link_libraries` + +Files to Edit +------------- + +* ``CMakeLists.txt`` +* ``Tutorial/Tutorial.cxx`` + +Getting Started +--------------- + +Continue to edit files from ``Step1``. Start on ``TODO 7`` and complete through +``TODO 9``. In this exercise, we need to add the ``MathFunctions`` target to +the ``Tutorial`` target's linked libraries using :command:`target_link_libraries`. + +After modifying the CML, update ``tutorial.cxx`` to use the +``mathfunctions::sqrt()`` function instead of ``std::sqrt``. + +Build and Run +------------- + +Let's build our project again. As before, we already created a build directory +and ran CMake so we can skip to the build step: + +.. code-block:: console + + cmake --build build + +Verify that the output matches what you would expect from the ``MathFunctions`` +library. + +Solution +-------- + +In this exercise, we are describing the ``Tutorial`` executable as a consumer +of the ``MathFunctions`` target by adding ``MathFunctions`` to the linked +libraries of the ``Tutorial``. + +To achieve this, we modify ``CMakeLists.txt`` file to use the +:command:`target_link_libraries` command, using ``Tutorial`` as the target to +be modified and ``MathFunctions`` as the library we want to add. + +.. raw:: html + + <details><summary>TODO 7: Click to show/hide answer</summary> + +.. literalinclude:: Step3/Tutorial/CMakeLists.txt + :caption: TODO 7: CMakeLists.txt + :name: CMakeLists.txt-target_link_libraries + :language: cmake + :start-at: target_link_libraries(Tutorial + :end-at: ) + +.. raw:: html + + </details> + +.. note:: + The order here is only loosely relevant. That we call + :command:`target_link_libraries` prior to defining ``MathFunctions`` with + :command:`add_library` doesn't matter to CMake. We are recording that + ``Tutorial`` has a dependency on something named ``MathFunctions``, but what + ``MathFunctions`` means isn't resolved at this stage. + + The only target which needs to be defined when calling a CMake command like + :command:`target_sources` or :command:`target_link_libraries` is the target + being modified. + +Finally, all that's left to do is modify ``Tutorial.cxx`` to use the newly +provided ``mathfunctions::sqrt`` function. That means adding the appropriate +header file and modifying our ``sqrt()`` call. + +.. raw:: html + + <details><summary>TODO 8-9: Click to show/hide answer</summary> + +.. literalinclude:: Step3/Tutorial/Tutorial.cxx + :caption: TODO 8: Tutorial/Tutorial.cxx + :name: Tutorial/Tutorial.cxx-MathFunctions-headers + :language: c++ + :start-at: iostream + :end-at: MathFunctions.h + +.. literalinclude:: Step3/Tutorial/Tutorial.cxx + :caption: TODO 9: Tutorial/Tutorial.cxx + :name: Tutorial/Tutorial.cxx-MathFunctions-code + :language: c++ + :start-at: calculate square root + :end-at: mathfunctions::sqrt + :dedent: 2 + +.. raw:: html + + </details> + +Exercise 4 - Subdirectories +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +As we move through the tutorial, we will be adding more commands to manipulate +the ``Tutorial`` executable and the ``MathFunctions`` library. We want to make +sure we keep commands local to the files they are dealing with. While not a +major concern for a small project like this, it can be very useful for large +projects with many targets and thousands of files. + +The :command:`add_subdirectory` command allows us to incorporate CMLs located +in subdirectories of the project. + +.. code-block:: cmake + + add_subdirectory(SubdirectoryName) + +When a ``CMakeLists.txt`` in a subdirectory is being processed by CMake all +relative paths described in the subdirectory CML are relative to that +subdirectory, not the top-level CML. + +Goal +---- + +Use :command:`add_subdirectory` to organize the project. + +Helpful Resources +----------------- + +* :command:`add_subdirectory` + +Files to Edit +------------- + +* ``CMakeLists.txt`` +* ``Tutorial/CMakeLists.txt`` +* ``MathFunctions/CMakeLists.txt`` + +Getting Started +--------------- + +The ``TODOs`` for this step are spread across three ``CMakeLists.txt`` files. +Be sure to pay attention to the path changes necessary when moving the +:command:`target_sources` commands into subdirectories. + +.. note:: + Previously we said that ``BASE_DIRS`` defaults to the current source + directory. As the desired include directory for ``MathFunctions`` will now be + the same directory as the CML calling :command:`target_sources`, we should + remove the ``BASE_DIRS`` keyword and argument entirely. + +Complete ``TODO 10`` through ``TODO 13``. + +Build and Run +------------- + +Because of the reorganization, we'll need to clean the original build +directory prior to rebuilding (otherwise our new ``Target`` build folder would +conflict with our previously created ``Target`` executable). We can achieve +this with the :option:`--clean-first <cmake--build --clean-first>` flag. + +There's no need for a reconfiguration. CMake will automatically +re-configure itself due to the changes in the CMLs. + +.. code-block:: console + + cmake --build build --clean-first + +.. note:: + Our executable and library will be output to a new location in the build tree. + A subdirectory which mirrors where :command:`add_executable` and + :command:`add_library` were called in the source tree. You will need to + navigate to this subdirectory in the build tree to run the tutorial + executable in future steps. + + You can verify this behavior by deleting the old ``Tutorial`` executable, + and observing that the new one is produced at ``Tutorial/Tutorial``. + +Solution +-------- + +We need to move all the commands concerning the ``Tutorial`` executable into +``Tutorial/CMakeLists.txt``, and replace them with an +:command:`add_subdirectory` command. We also need to update the path for +``Tutorial.cxx``. + +.. raw:: html + + <details><summary>TODO 10-11: Click to show/hide answer</summary> + +.. literalinclude:: Step3/Tutorial/CMakeLists.txt + :caption: TODO 10: Tutorial/CMakeLists.txt + :name: Tutorial/CMakeLists.txt-moved + :language: cmake + +.. code-block:: cmake + :caption: TODO 11: CMakeLists.txt + :name: CMakeLists.txt-add_subdirectory-Tutorial + + add_subdirectory(Tutorial) + +.. raw:: html + + </details> + +We need to do the same with the commands for ``MathFunctions``, changing the +relative paths as appropriate and removing ``BASE_DIRS`` as it is no longer +necessary, the default value will work. + +.. raw:: html + + <details><summary>TODO 12-13: Click to show/hide answer</summary> + +.. literalinclude:: Step3/MathFunctions/CMakeLists.txt + :caption: TODO 12: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-moved + :language: cmake + +.. literalinclude:: Step3/CMakeLists.txt + :caption: TODO 13: CMakeLists.txt + :name: CMakeLists.txt-add_subdirectory-MathFunctions + :language: cmake + :start-at: add_subdirectory(MathFunctions + :end-at: add_subdirectory(MathFunctions + +.. raw:: html + + </details>
diff --git a/Help/guide/tutorial/In-Depth CMake Library Concepts.rst b/Help/guide/tutorial/In-Depth CMake Library Concepts.rst new file mode 100644 index 0000000..6181cf7 --- /dev/null +++ b/Help/guide/tutorial/In-Depth CMake Library Concepts.rst
@@ -0,0 +1,446 @@ +Step 5: In-Depth CMake Library Concepts +======================================= + +While executables are mostly one-size-fits-all, libraries come in many +different forms. There are static archives, shared objects, modules, +object libraries, header-only libraries, and libraries which describe advanced +CMake properties to be inherited by other targets, just to name a few. + +In this step you will learn about some of the most common kinds of libraries +that CMake can describe. This will cover most of the in-project uses of +:command:`add_library`. Libraries which are imported from dependencies (or +exported by the project to be consumed as a dependency) will be covered in +later steps. + +Background +^^^^^^^^^^ + +As we learned in ``Step1``, the :command:`add_library` command accepts the name +of the library target to be created as its first argument. The second +argument is an optional ``<type>`` for which the following values are valid: + + ``STATIC`` + A :ref:`Static Library <Static Libraries>`: + an archive of object files for use when linking other targets. + + ``SHARED`` + A :ref:`Shared Library <Shared Libraries>`: + a dynamic library that may be linked by other targets and loaded + at runtime. + + ``MODULE`` + A :ref:`Module Library <Module Libraries>`: + a plugin that may not be linked by other targets, but may be + dynamically loaded at runtime using dlopen-like functionality. + + ``OBJECT`` + An :ref:`Object Library <Object Libraries>`: + a collection of object files which have not been archived or linked + into a library. + + ``INTERFACE`` + An :ref:`Interface Library <Interface Libraries>`: + a library target which specifies usage requirements for dependents but + does not compile sources and does not produce a library artifact on disk. + +In addition, there are ``IMPORTED`` libraries which describe library targets +from foreign projects or modules, imported into the current project. We will +cover these briefly in later steps. + +``MODULE`` libraries are most commonly found in plugin systems, or as extensions +to runtime-loading languages like Python or Javascript. They act very similar to +normal shared libraries, except they cannot be directly linked by other targets. +They are sufficiently similar that we won't cover them in further depth here. + +Exercise 1 - Static and Shared +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +While the :command:`add_library` command supports explicitly setting ``STATIC`` +or ``SHARED``, and this is sometimes necessary, it is best to leave the second +argument empty for most "normal" libraries which can operate as either. + +When not given a type, :command:`add_library` will create either a ``STATIC`` +or ``SHARED`` library depending on the value of :variable:`BUILD_SHARED_LIBS`. +If :variable:`BUILD_SHARED_LIBS` is true, a ``SHARED`` library will be created, +otherwise it will be ``STATIC``. + +.. code-block:: cmake + + add_library(MyLib-static STATIC) + add_library(MyLib-shared SHARED) + + # Depends on BUILD_SHARED_LIBS + add_library(MyLib) + +This is desirable behavior, as it allows packagers to determine what kind of +library will be produced, and ensure dependents link to that version of the +library without needing to modify their source code. In some contexts, fully +static builds are appropriate, and in others shared libraries are desirable. + +.. note:: + CMake does not define the :variable:`BUILD_SHARED_LIBS` variable by default, + meaning without project or user intervention :command:`add_library` will + produce ``STATIC`` libraries. + +By leaving the second argument to :command:`add_library()` blank, projects +provide additional flexibility to their packagers and downstream dependents. + +Goal +---- + +Build ``MathFunctions`` as a shared library. + +.. note:: + On Windows, you might see warnings about an empty DLL, as ``MathFunctions`` + doesn't export any symbols. + +Helpful Resources +----------------- + +* :variable:`BUILD_SHARED_LIBS` + +Files to Edit +------------- + +There are no files to edit. + +Getting Started +--------------- + +The ``Help/guide/tutorial/Step5`` directory contains the complete, recommended +solution to ``Step4``. This step is about building the ``MathFunctions`` +library, there are no ``TODOs`` necessary. You can proceed directly to the +build step. + +Build and Run +------------- + +We can configure using our preset, turning on :variable:`BUILD_SHARED_LIBS` with +a :option:`-D <cmake -D>` flag. + +.. code-block:: console + + cmake --preset tutorial -DBUILD_SHARED_LIBS=ON + +Then we can build only the ``MathFunctions`` library with +:option:`-t <cmake--build -t>`. + +.. code-block:: console + + cmake --build build -t MathFunctions + +Verify a shared library is produced for ``MathFunctions`` then reset +:variable:`BUILD_SHARED_LIBS`, either by reconfiguring with +``-DBUILD_SHARED_LIBS=OFF`` or deleting the ``CMakeCache.txt``. + +Solution +-------- + +There are no changes to the project for this exercise. + +Exercise 2 - Interface Libraries +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Interface libraries are those which only communicate usage requirements for +other targets, they do not build or produce any artifacts of their own. As such +all the properties of an interface library must themselves be interface +properties, specified with the ``INTERFACE`` :ref:`scope keywords <Target Command Scope>`. + +.. code-block:: cmake + + add_library(MyInterface INTERFACE) + target_compile_definitions(MyInterface INTERFACE MYINTERFACE_COMPILE_DEF) + +The most common kind of interface library in C++ development is a header-only +library. Such libraries do not build anything, only providing the flags +necessary to discover their headers. + +Goal +---- + +Add a header-only library to the tutorial project, and use it inside the +``Tutorial`` executable. + +Helpful Resources +----------------- + +* :command:`add_library` +* :command:`target_sources` + +Files to Edit +------------- + +* ``MathFunctions/MathLogger/CMakeLists.txt`` +* ``MathFunctions/CMakeLists.txt`` +* ``MathFunctions/MathFunctions.cxx`` + +Getting Started +--------------- + +In our previous discussions of :command:`target_sources(FILE_SET)`, we noted +we can omit the ``TYPE`` parameter if the file set's name is the same as the +file set's type. We also said we can omit the ``BASE_DIRS`` parameter if +we want to use the current source directory as the only base directory. + +We're ready to introduce a third shortcut, we only need to include the ``FILES`` +parameter if the headers are intended to be installed, such as public headers +of a library. + +The ``MathLogger`` headers in this exercise are only used internally by the +``MathFunctions`` implementation. They will not be installed. This should +make for a very abbreviated call to :command:`target_sources(FILE_SET)`. + +.. note:: + The headers will be discovered by the compiler's dependency scanner to ensure + correct incremental builds. It can be useful to list header files in these + contexts anyway, as the list can be used to generate metadata some IDEs + rely on. + +You can begin editing the ``Step5`` directory. Complete ``TODO 1`` through +``TODO 7``. + +Build and Run +------------- + +The preset has already been updated to use ``mathfunctions::sqrt`` instead of +``std::sqrt``. We can build and configure as usual. + +.. code-block:: console + + cmake --preset tutorial + cmake --build build + +Verify that the ``Tutorial`` output now uses the logging framework. + +Solution +-------- + +First we add a new ``INTERFACE`` library named ``MathLogger``. + +.. raw:: html + + <details><summary>TODO 1: Click to show/hide answer</summary> + +.. literalinclude:: Step6/MathFunctions/MathLogger/CMakeLists.txt + :caption: TODO 1: MathFunctions/MathLogger/CMakeLists.txt + :name: MathFunctions/MathLogger/CMakeLists.txt-add_library + :language: cmake + :start-at: add_library + :end-at: add_library + +.. raw:: html + + </details> + +Then we add the appropriate :command:`target_sources` call to capture the +header information. We give this file set the name ``HEADERS`` so we can +omit the ``TYPE``, we don't need ``BASE_DIRS`` as we will use the default +of the current source directory, and we can exclude the ``FILES`` list because +we don't intend to install the library. + +.. raw:: html + + <details><summary>TODO 2: Click to show/hide answer</summary> + +.. literalinclude:: Step6/MathFunctions/MathLogger/CMakeLists.txt + :caption: TODO 2: MathFunctions/MathLogger/CMakeLists.txt + :name: MathFunctions/MathLogger/CMakeLists.txt-target_sources + :language: cmake + :start-at: target_sources( + :end-at: ) + +.. raw:: html + + </details> + +Now we can add the ``MathLogger`` library to the ``MathFunctions`` linked +libraries, and at the ``MathLogger`` folder to the project. + +.. raw:: html + + <details><summary>TODO 3-4: Click to show/hide answer</summary> + +.. literalinclude:: Step6/MathFunctions/CMakeLists.txt + :caption: TODO 3: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-link-mathlogger + :language: cmake + :start-at: target_link_libraries( + :end-at: MathLogger + :append: ) + +.. literalinclude:: Step6/MathFunctions/CMakeLists.txt + :caption: TODO 4: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-add-mathlogger + :language: cmake + :start-at: add_subdirectory(MathLogger + :end-at: add_subdirectory(MathLogger + +.. raw:: html + + </details> + +Finally we can update ``MathFunctions.cxx`` to take advantage of the new logger. + +.. raw:: html + + <details><summary>TODO 5-7: Click to show/hide answer</summary> + +.. literalinclude:: Step6/MathFunctions/MathFunctions.cxx + :caption: TODO 5: MathFunctions/MathFunctions.cxx + :name: MathFunctions/MathFunctions.cxx-mathlogger-header + :language: c++ + :start-at: cmath + :end-at: MathLogger + +.. literalinclude:: Step6/MathFunctions/MathFunctions.cxx + :caption: TODO 6: MathFunctions/MathFunctions.cxx + :name: MathFunctions/MathFunctions.cxx-mathlogger-logger + :language: c++ + :start-at: mathlogger::Logger Logger + :end-at: mathlogger::Logger Logger + +.. literalinclude:: Step6/MathFunctions/MathFunctions.cxx + :caption: TODO 7: MathFunctions/MathFunctions.cxx + :name: MathFunctions/MathFunctions.cxx-mathlogger-code + :language: c++ + :start-at: Logger.Log(std::format("Computing sqrt of {} to be {}\n" + :end-at: std::format + :dedent: 4 + +.. raw:: html + + </details> + +Exercise 3 - Object Libraries +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Object libraries have several advanced uses, but also tricky nuances which +are difficult to fully enumerate in the scope of this tutorial. + +.. code-block:: cmake + + add_library(MyObjects OBJECT) + +The most obvious drawback to object libraries is the objects themselves cannot +be transitively linked. If an object library appears in the +:prop_tgt:`INTERFACE_LINK_LIBRARIES` of a target, the dependents which link that +target will not "see" the objects. The object library will act like an +``INTERFACE`` library in such contexts. In the general case, object libraries +are only suitable for ``PRIVATE`` or ``PUBLIC`` consumption via +:command:`target_link_libraries`. + +A common use case for object libraries is coalescing several library targets +into a single archive or shared library object. Even within a single project +libraries may be maintained as different targets for a variety of reasons, such +as belonging to different teams within an organization. However, it may be +desirable to distribute these as a single consumer-facing binary. Object +libraries make this possible. + +Goal +---- + +Add several object libraries to the ``MathFunctions`` library. + +Helpful Resources +----------------- + +* :command:`target_link_libraries` +* :command:`add_subdirectory` + +Files to Edit +------------- + +* ``MathFunctions/CMakeLists.txt`` +* ``MathFunctions/MathFunctions.h`` +* ``Tutorial/Tutorial.cxx`` + +Getting Started +--------------- + +Several extensions for our ``MathFunctions`` library have been made available +(we can imagine these coming from other teams in our organization). Take +a minute to look at the targets made available in ``MathFunctions/MathExtensions``. +Then complete ``TODO 8`` through ``TODO 11``. + +Build and Run +------------- + +There's no reconfiguration needed, we can build as usual. + +.. code-block:: console + + cmake --build build + +Verify the output of ``Tutorial`` now includes the verification message. Also +take a minute to inspect the build directory under +``build/MathFunctions/MathExtensions``. You should find that, unlike +``MathFunctions``, no archives are produced for any of the object libraries. + +Solution +-------- + +First we will add links for all the object libraries to ``MathFunctions``. +These are ``PUBLIC``, because we want the objects to be added to the +``MathFunctions`` library as part of its own build step, and we want the +headers to be available to consumers of the library. + +Then we add the ``MathExtensions`` subdirectory to the project. + +.. raw:: html + + <details><summary>TODO 8-9: Click to show/hide answer</summary> + +.. literalinclude:: Step6/MathFunctions/CMakeLists.txt + :caption: TODO 8: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-link-objects + :language: cmake + :start-at: target_link_libraries( + :end-at: ) + +.. literalinclude:: Step6/MathFunctions/CMakeLists.txt + :caption: TODO 9: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-add-objs + :language: cmake + :start-at: add_subdirectory(MathExtensions + :end-at: add_subdirectory(MathExtensions + +.. raw:: html + + </details> + + +To make the extensions available to consumers, we include their headers in the +``MathFunctions.h`` header. + +.. raw:: html + + <details><summary>TODO 10: Click to show/hide answer</summary> + +.. literalinclude:: Step6/MathFunctions/MathFunctions.h + :caption: TODO 10: MathFunctions/MathFunctions.h + :name: MathFunctions/MathFunctions.h-include-objects + :language: c++ + :start-at: OpAdd + :end-at: OpSub + +.. raw:: html + + </details> + +Finally we can take advantage of the extensions in the ``Tutorial`` program. + +.. raw:: html + + <details><summary>TODO 11: Click to show/hide answer</summary> + +.. literalinclude:: Step6/Tutorial/Tutorial.cxx + :caption: TODO 11: Tutorial/Tutorial.cxx + :name: Tutorial/Tutorial.cxx-use-objects + :language: c++ + :start-at: OpMul + :end-at: checkValue); + :dedent: 2 + +.. raw:: html + + </details>
diff --git a/Help/guide/tutorial/In-Depth CMake Target Commands.rst b/Help/guide/tutorial/In-Depth CMake Target Commands.rst new file mode 100644 index 0000000..c4f6465 --- /dev/null +++ b/Help/guide/tutorial/In-Depth CMake Target Commands.rst
@@ -0,0 +1,545 @@ +Step 4: In-Depth CMake Target Commands +====================================== + +There are several target commands within CMake we can use to describe +requirements. As a reminder, a target command is one which modifies the +properties of the target it is applied to. These properties describe +requirements needed to build the software, such as sources, compile flags, +and output names; or properties necessary to consume the target, such as header +includes, library directories, and linkage rules. + +.. note:: + As discussed in ``Step1``, properties required to build a target should be + described with the ``PRIVATE`` :ref:`scope keyword <Target Command Scope>`, + those required to consume the target with ``INTERFACE``, and properties needed + for both are described with ``PUBLIC``. + +In this step we will go over all the available target commands in CMake. Not all +target commands are created equal. We have already discussed the two most +important target commands, :command:`target_sources` and +:command:`target_link_libraries`. Of the remaining commands, some are almost +as common as these two, others have more advanced applications, and a couple +should only be used as a last resort when other options are not available. + +Background +^^^^^^^^^^ + +Before going any further, let's name all of the CMake target commands. We'll +split these into three groups: the recommended and generally useful commands, +the advanced and cautionary commands, and the "footgun" commands which should +be avoided unless necessary. + ++-----------------------------------------+--------------------------------------+---------------------------------------+ +| Common/Recommended | Advanced/Caution | Esoteric/Footguns | ++=========================================+======================================+=======================================+ +| :command:`target_compile_definitions` | :command:`get_target_property` | :command:`target_include_directories` | +| :command:`target_compile_features` | :command:`set_target_properties` | :command:`target_link_directories` | +| :command:`target_link_libraries` | :command:`target_compile_options` | | +| :command:`target_sources` | :command:`target_link_options` | | +| | :command:`target_precompile_headers` | | ++-----------------------------------------+--------------------------------------+---------------------------------------+ + +.. note:: + There's no such thing as a "bad" CMake target command. They all have valid + use cases. This categorization is provided to give newcomers a simple + intuition about which commands they should consider first when tackling + a problem. + +We'll demonstrate most of these in the following exercises. The three we won't +be using are :command:`get_target_property`, :command:`set_target_properties` +and :command:`target_precompile_headers`, so we will briefly discuss their +purpose here. + +The :command:`get_target_property` and :command:`set_target_properties` commands +give direct access to a target's properties by name. They can even be used +to attach arbitrary property names to a target. + +.. code-block:: cmake + + add_library(Example) + set_target_properties(Example + PROPERTIES + Key Value + Hello World + ) + + get_target_property(KeyVar Example Key) + get_target_property(HelloVar Example Hello) + + message("Key: ${KeyVar}") + message("Hello: ${HelloVar}") + +.. code-block:: console + + $ cmake -B build + ... + Key: Value + Hello: World + +The full list of target properties which are semantically meaningful to CMake +are documented at :manual:`cmake-properties(7)`, however most of these should +be modified with their dedicated commands. For example, it is unnecessary to +directly manipulate ``LINK_LIBRARIES`` and ``INTERFACE_LINK_LIBRARIES``, as +these are handled by :command:`target_link_libraries`. + +Conversely, some lesser-used properties are only accessible via these commands. +The :prop_tgt:`DEPRECATION` property, used to attach deprecation notices to +targets, can only be set via :command:`set_target_properties`; as can the +:prop_tgt:`ADDITIONAL_CLEAN_FILES`, for describing additional files to be +removed by CMake's ``clean`` target; and other properties of this sort. + +The :command:`target_precompile_headers` command takes a list of header files, +similar to :command:`target_sources`, and creates a precompiled header from +them. This precompiled header is then force included into all translation +units in the target. This can be useful for build performance. + +Exercise 1 - Features and Definitions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In earlier steps we cautioned against globally setting +:variable:`CMAKE_<LANG>_STANDARD` and overriding packagers' decision concerning +which language standard to use. On the other hand, many libraries have a +minimum required feature set they need in order to build, and for these it +is appropriate to use the :command:`target_compile_features` command to +communicate those requirements. + +.. code-block:: cmake + + target_compile_features(MyApp PRIVATE cxx_std_20) + +The :command:`target_compile_features` command describes a minimum language +standard as a target property. If the :variable:`CMAKE_<LANG>_STANDARD` is above +this version, or the compiler default already provides this language standard, +no action is taken. If additional flags are necessary to enable the standard, +these will be added by CMake. + +.. note:: + :command:`target_compile_features` manipulates the same style of interface and + non-interface properties as the other target commands. This means it is + possible to *inherit* a language standard requirement specified with + ``INTERFACE`` or ``PUBLIC`` scope keywords. + + If language features are used only in implementation files, then the + respective compile features should be ``PRIVATE``. If the target's headers + use the features, then ``PUBLIC`` or ``INTERFACE`` should be used. + +For C++, the compile features are of the form ``cxx_std_YY`` where ``YY`` is +the standardization year, e.g. ``14``, ``17``, ``20``, etc. + +The :command:`target_compile_definitions` command describes compile definitions +as target properties. It is the most common mechanism for communicating build +configuration information to the source code itself. As with all properties, +the scope keywords apply as we have discussed. + +.. code-block:: cmake + + target_compile_definitions(MyLibrary + PRIVATE + MYLIBRARY_USE_EXPERIMENTAL_IMPLEMENTATION + + PUBLIC + MYLIBRARY_EXCLUDE_DEPRECATED_FUNCTIONS + ) + +It is neither required nor desired that we attach ``-D`` prefixes to compile +definitions described with :command:`target_compile_definitions`. CMake will +determine the correct flag for the current compiler. + +Goal +---- + +Use :command:`target_compile_features` and :command:`target_compile_definitions` +to communicate language standard and compile definition requirements. + +Helpful Resources +----------------- + +* :command:`target_compile_features` +* :command:`target_compile_definitions` +* :command:`option` +* :command:`if` + +Files to Edit +------------- + +* ``CMakeLists.txt`` +* ``Tutorial/CMakeLists.txt`` +* ``MathFunctions/CMakeLists.txt`` +* ``MathFunctions/MathFunctions.cxx`` +* ``CMakePresets.json`` + +Getting Started +--------------- + +The ``Help/guide/tutorial/Step4`` directory contains the complete, recommended +solution to ``Step3`` and relevant ``TODOs`` for this step. Complete ``TODO 1`` +through ``TODO 8``. + +Build and Run +------------- + +We can run CMake using our ``tutorial`` preset, and then build as usual. + +.. code-block:: console + + cmake --preset tutorial + cmake --build build + +Verify that the output of ``Tutorial`` is what we would expect for ``std::sqrt``. + +Solution +-------- + +First we add a new option to the top-level CML. + +.. raw:: html + + <details><summary>TODO 1: Click to show/hide answer</summary> + +.. literalinclude:: Step5/CMakeLists.txt + :caption: TODO 1: CMakeLists.txt + :name: CMakeLists.txt-TUTORIAL_USE_STD_SQRT + :language: cmake + :start-at: option(TUTORIAL_BUILD_UTILITIES + :end-at: option(TUTORIAL_USE_STD_SQRT + +.. raw:: html + + </details> + +Then we add the compile feature and definitions to ``MathFunctions``. + +.. raw:: html + + <details><summary>TODO 2-3: Click to show/hide answer</summary> + +.. literalinclude:: Step5/MathFunctions/CMakeLists.txt + :caption: TODO 2-3: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-target_compile_features + :language: cmake + :start-at: target_compile_features + :end-at: endif() + +.. raw:: html + + </details> + +And the compile feature for ``Tutorial``. + +.. raw:: html + + <details><summary>TODO 4: Click to show/hide answer</summary> + +.. literalinclude:: Step5/Tutorial/CMakeLists.txt + :caption: TODO 4: Tutorial/CMakeLists.txt + :name: Tutorial/CMakeLists.txt-target_compile_features + :language: cmake + :start-at: target_compile_features + :end-at: target_compile_features + +.. raw:: html + + </details> + +Now we can modify ``MathFunctions`` to take advantage of the new definition. + +.. raw:: html + + <details><summary>TODO 5-6: Click to show/hide answer</summary> + +.. literalinclude:: Step5/MathFunctions/MathFunctions.cxx + :caption: TODO 5: MathFunctions/MathFunctions.cxx + :name: MathFunctions/MathFunctions.cxx-cmath + :language: c++ + :start-at: cmath + :end-at: format + :append: #include <iostream> + +.. literalinclude:: Step5/MathFunctions/MathFunctions.cxx + :caption: TODO 6: MathFunctions/MathFunctions.cxx + :name: MathFunctions/MathFunctions.cxx-std-sqrt + :language: c++ + :start-at: double sqrt(double x) + :end-at: } + +.. raw:: html + + </details> + +Finally we can update our ``CMakePresets.json``. We don't need to set +``CMAKE_CXX_STANDARD`` anymore, but we do want to try out our new +compile definition. + +.. raw:: html + + <details><summary>TODO 7-8: Click to show/hide answer</summary> + +.. code-block:: json + :caption: TODO 7-8: CMakePresets.json + :name: CMakePresets.json-std-sqrt + + "cacheVariables": { + "TUTORIAL_USE_STD_SQRT": "ON" + } + +.. raw:: html + + </details> + +Exercise 2 - Compile and Link Options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Sometimes, we need to exercise specific control over the exact options being +passed on the compile and link line. These situations are addressed by +:command:`target_compile_options` and :command:`target_link_options`. + +.. code:: cmake + + target_compile_options(MyApp PRIVATE -Wall -Werror) + target_link_options(MyApp PRIVATE -T LinksScript.ld) + +There are several problems with unconditionally calling +:command:`target_compile_options` or :command:`target_link_options`. The primary +problem is compiler flags are specific to the compiler frontend being used. In +order to ensure that our project supports multiple compiler frontends, we must +only pass compatible flags to the compiler. + +We can achieve this by checking the :variable:`CMAKE_<LANG>_COMPILER_FRONTEND_VARIANT` +variable which tells us the style of flags supported by the compiler frontend. + +.. note:: + Prior to CMake 3.26, :variable:`CMAKE_<LANG>_COMPILER_FRONTEND_VARIANT` was + only set for compilers with multiple frontend variants. In versions after + CMake 3.26 checking this variable alone is sufficient. + + However this tutorial targets CMake 3.23. As such, the logic is more + complicated than we have time for here. This tutorial step already includes + correct logic for checking the compiler variant for MSVC, GCC, Clang, and + AppleClang on CMake 3.23. + +Even if a compiler accepts the flags we pass, the semantics of compiler flags +change over time. This is especially true with regards to warnings. Projects +should not turn warnings-as-error flags by default, as this can break their +build on otherwise innocuous compiler warnings included in later releases. + +.. note:: + For errors and warnings, consider placing flags in :variable:`CMAKE_<LANG>_FLAGS` + for local development builds and during CI runs (via preset or + :option:`-D <cmake -D>` flags). We know exactly which compiler and + toolchain are being used in these contexts, so we can customize the behavior + precisely without risking build breakages on other platforms. + +Goal +---- + +Add appropriate warning flags to the ``Tutorial`` executable for MSVC-style and +GNU-style compiler frontends. + +Helpful Resources +----------------- + +* :command:`target_compile_options` + +Files to Edit +------------- + +* ``Tutorial/CMakeLists.txt`` + +Getting Started +--------------- + +Continue editing files in the ``Step4`` directory. The conditional for checking +the frontend variant has already been written. Complete ``TODO 9`` and +``TODO 10`` to add warning flags to ``Tutorial``. + +Build and Run +------------- + +Since we have already configured for this step, we can build with the usual +command. + +.. code-block:: cmake + + cmake --build build + +This should reveal a simple warning in the build. You can go ahead and fix it. + +Solution +-------- + +We need to add two compile options to ``Tutorial``, one MSVC-style flag and +one GNU-style flag. + +.. raw:: html + + <details><summary>TODO 9-10: Click to show/hide answer</summary> + +.. literalinclude:: Step5/Tutorial/CMakeLists.txt + :caption: TODO 9-10: Tutorial/CMakeLists.txt + :name: Tutorial/CMakeLists.txt-target_compile_options + :language: cmake + :start-at: if( + :end-at: endif() + +.. raw:: html + + </details> + +Exercise 3 - Include and Link Directories +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. note:: + This exercise requires building an archive using a compiler directly on the + command line. It is not used in later steps. It is included only to + demonstrate a use case for :command:`target_include_directories` and + :command:`target_link_directories`. + + If you cannot complete this exercise for whatever reason feel free to treat + it as informational-only, or skip it entirely. + +It is generally unnecessary to directly describe include and link directories, +as these requirements are inherited when linking together targets generated +within CMake, or from external dependencies imported into CMake with commands +we will cover in later steps. + +If we happen to have some libraries or header files which are not described +by a CMake target which we need to bring into the build, perhaps pre-compiled +binaries provided by a vendor, we can incorporate with the +:command:`target_link_directories` and :command:`target_include_directories` +commands. + +.. code-block:: cmake + + target_link_directories(MyApp PRIVATE Vendor/lib) + target_include_directories(MyApp PRIVATE Vendor/include) + + +These commands use properties which map to the ``-L`` and ``-I`` compiler flags +(or whatever flags the compiler uses for link and include directories). + +Of course, passing a link directory doesn't tell the compiler to link anything +into the build. For that we need :command:`target_link_libraries`. When +:command:`target_link_libraries` is given an argument which does not map to +a target name, it will add the string directly to the link line as a library +to be linked into the build (prepending any appropriate flags, such a ``-l``). + +Goal +---- + +Describe a pre-compiled, vendored, static library and its headers inside a +project using :command:`target_link_directories` and +:command:`target_include_directories`. + +Helpful Resources +----------------- + +* :command:`target_link_directories` +* :command:`target_include_directories` +* :command:`target_link_libraries` + +Files to Edit +------------- + +* ``Vendor/CMakeLists.txt`` +* ``Tutorial/CMakeLists.txt`` + +Getting Started +--------------- + +You will need to build the vendor library into a static archive to complete this +exercise. Navigate to the ``Help/guide/tutorial/Step4/Vendor/lib`` directory +and build the code as appropriate for your platform. + +Typical commands for a GCC toolchain on Unix-like systems are: + +.. code-block:: console + + g++ -c Vendor.cxx + ar rvs libVendor.a Vendor.o + +Likewise, sample commands for an MSVC toolchain on Windows are: + +.. code-block:: console + + cl -c Vendor.cxx + lib -out:Vendor.lib Vendor.obj + +Here, since you're directly invoking ``cl`` and ``lib``, make sure to use a +Developer Command Prompt for your version of Visual Studio with the same +target architecture used by this CMake project. + +Then complete ``TODO 11`` through ``TODO 14``. + +.. note:: + ``VendorLib`` is an ``INTERFACE`` library, meaning it has no build requirements + (because it has already been built). All of its properties should also be + interface properties. + + We'll discuss ``INTERFACE`` libraries in greater depth during the next step. + + +Build and Run +------------- + +If you have successfully built ``libVendor``, you can rebuild ``Tutorial`` +using the normal command. + +.. code-block:: console + + cmake --build build + +Running ``Tutorial`` should now output a message about the acceptability of the +result to the vendor. + +Solution +-------- + +We need to use the target link and include commands to describe the archive +and its headers as ``INTERFACE`` requirements of ``VendorLib``. + +.. raw:: html + + <details><summary>TODO 11-13: Click to show/hide answer</summary> + +.. code-block:: cmake + :caption: TODO 11-13: Vendor/CMakeLists.txt + :name: Vendor/CMakeLists.txt + + target_include_directories(VendorLib + INTERFACE + include + ) + + target_link_directories(VendorLib + INTERFACE + lib + ) + + target_link_libraries(VendorLib + INTERFACE + Vendor + ) + +.. raw:: html + + </details> + +Then we can add ``VendorLib`` to ``Tutorial``'s linked libraries. + +.. raw:: html + + <details><summary>TODO 14: Click to show/hide answer</summary> + +.. code-block:: cmake + :caption: TODO 14: Tutorial/CMakeLists.txt + :name: Tutorial/CMakeLists.txt-VendorLib + + target_link_libraries(Tutorial + PRIVATE + MathFunctions + VendorLib + ) + +.. raw:: html + + </details>
diff --git a/Help/guide/tutorial/In-Depth System Introspection.rst b/Help/guide/tutorial/In-Depth System Introspection.rst new file mode 100644 index 0000000..463d887 --- /dev/null +++ b/Help/guide/tutorial/In-Depth System Introspection.rst
@@ -0,0 +1,418 @@ +Step 6: In-Depth System Introspection +===================================== + +In order to discover information about the system environment and the toolchain, +CMake will often compile small test programs to verify the availability of +compiler flags, headers, and builtins or other language constructs. + +In this step, we will take advantage of the same test program mechanisms that +CMake uses in our own project code. + +Background +^^^^^^^^^^ + +An old trick going back to the oldest days of configuration and build systems +is to verify the availability of some feature by compiling a small program +which uses that feature. + +CMake makes this unnecessary for many contexts. As we will address in later +steps, if CMake can find a library dependency, we can rely on it having all +the facilities (headers, code generators, test utilities, etc) we expect it to +have. Conversely, if CMake can't find a dependency, attempting to use the +dependency anyway will almost certainly fail. + +However, there are other kinds of information about the toolchain which CMake +doesn't communicate readily. For these advanced cases, we can write our own +test programs and compile commands to check for availability. + +CMake provides modules to simplify these checks. These are documented at +:manual:`cmake-modules(7)`. Any module that begins with ``Check`` is a system +introspection module we can use to interrogate the toolchain and system +environment. Some notable ones include: + + ``CheckIncludeFiles`` + Check one or more C/C++ header files. + + ``CheckCompilerFlag`` + Check whether the compiler supports a given flag. + + ``CheckSourceCompiles`` + Checks whether source code can be built for a given language. + + ``CheckIPOSupported`` + Check whether the compiler supports interprocedural optimization (IPO/LTO). + + +Exercise 1 - Check Include File +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A fast and easy check to perform is if a given header file is available on +a certain platform, for which CMake provides :module:`CheckIncludeFiles`. This +is most appropriate for system and intrinsic headers, which may not be provided +by a specific package yet are expected to be available in many build environments. + +.. code-block:: cmake + + include(CheckIncludeFiles) + check_include_files(sys/socket.h HAVE_SYS_SOCKET_H LANGUAGE CXX) + +.. note:: + These functions are not immediately available in CMake, they must be added via + :command:`include`'ing their associated module (aka, a CMakeLang file). Many + modules live inside CMake's own ``Modules`` folder. This built-in ``Modules`` + folder is one of the places CMake searches when evaluating an :command:`include` + command. You can think of these modules like standard library headers, they're + expected to be available. + +Once a header file is known to exist, we can communicate that to our code using +the same mechanisms of conditionals and target commands already covered. + +Goal +---- + +Check if the x86 SSE2 intrinsic header is available, and if so use it to +improve ``mathfunctions::sqrt``. + +Helpful Resources +----------------- + +* :module:`CheckIncludeFiles` +* :command:`target_compile_definitions` + +Files to Edit +------------- + +* ``MathFunctions/CMakeLists.txt`` +* ``MathFunctions/MathFunctions.cxx`` + +Getting Started +--------------- + +The ``Help/guide/tutorial/Step6`` directory contains the complete, recommended +solution to ``Step5`` and relevant ``TODOs`` for this step. It also contains +specialized implementations of the ``sqrt`` function for various conditions, +which you will find in ``MathFunctions/MathFunctions.cxx``. + +Complete ``TODO 1`` through ``TODO 3``. Note that some ``#ifdef`` directives +have already been added to the library, which will change its operation as we +work through the step. + +Build and Run +------------- + +We can use our usual commands to configure. + +.. code-block:: console + + cmake --preset tutorial + cmake --build build + +In the output of the configuration step we should observe CMake checking for +the ``emmintrin.h`` header. + +.. code-block:: console + + -- Looking for include file emmintrin.h + -- Looking for include file emmintrin.h - found + +If the header is available on your system, verify the ``Tutorial`` output +contains the message about using SSE2. Conversely, if the header is not +available you should see the usual behavior from ``Tutorial``. + +Solution +-------- + +First we include and use the ``CheckIncludeFiles`` module, verifying the +``emmintrin.h`` header is available. + +.. raw:: html + + <details><summary>TODO 1: Click to show/hide answer</summary> + +.. literalinclude:: Step7/MathFunctions/CMakeLists.txt + :caption: TODO 1: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-check-include-files + :language: cmake + :start-at: include(CheckIncludeFiles + :end-at: check_include_files( + +.. raw:: html + + </details> + +Then we use the result of the check to conditionally set a compile definition +on ``MathFunctions``. + +.. raw:: html + + <details><summary>TODO 2: Click to show/hide answer</summary> + +.. literalinclude:: Step7/MathFunctions/CMakeLists.txt + :caption: TODO 2: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-define-use-sse2 + :language: cmake + :start-at: if(HAS_EMMINTRIN) + :end-at: endif() + +.. raw:: html + + </details> + +Finally we can conditionally include the header in the ``MathFunctions`` library. + +.. raw:: html + + <details><summary>TODO 3: Click to show/hide answer</summary> + +.. literalinclude:: Step7/MathFunctions/MathFunctions.cxx + :caption: TODO 3: MathFunctions/MathFunctions.cxx + :name: MathFunctions/MathFunctions.cxx-include-sse2 + :language: c++ + :start-at: #ifdef TUTORIAL_USE_SSE2 + :end-at: #endif + +.. raw:: html + + </details> + + +Exercise 2 - Check Source Compiles +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Sometimes it is insufficient to merely check for a header. This is especially +true when no header is available to check, such is the case with +compiler-builtins. For these scenarios we have :module:`CheckSourceCompiles`. + +.. code-block:: cmake + + include(CheckSourceCompiles) + check_source_compiles(CXX + " + int main() { + int a, b, c; + __builtin_add_overflow(a, b, &c); + } + " + HAS_CHECKED_ADDITION + ) + +.. note:: + By default :module:`CheckSourceCompiles` builds and links an executable. The + code to be check must provide a valid ``int main()`` in order to succeed. + +After performing the check, this system introspection can be applied identically +to how we discussed with header files. + +Goal +---- + +Check if the GNU SSE2 builtins are available, and if so use them to improve +``mathfunctions::sqrt``. + +Helpful Resources +----------------- + +* :module:`CheckSourceCompiles` +* :command:`target_compile_definitions` + +Files to Edit +------------- + +* ``MathFunctions/CMakeLists.txt`` + +Getting Started +--------------- + +Complete ``TODO 4`` and ``TODO 5``. No code changes to the ``MathFunctions`` +implementation are necessary, as these have already been provided. + +Build and Run +------------- + +We need only rebuild the tutorial. + +.. code-block:: console + + cmake --build build + +.. note:: + If a check fails and you think it should succeed, you will need to clear the + CMake Cache by deleting the ``CMakeCache.txt`` file. CMake will not rerun + compile checks on subsequent runs if it has a cached result. + +In the output of the configuration step we should observe CMake checking if the +provided source code compiles, which will be reported under the variable name +we provided to ``check_source_compiles()``. + +.. code-block:: console + + -- Performing Test HAS_GNU_BUILTIN + -- Performing Test HAS_GNU_BUILTIN - Success + +If the builtins are available on your compiler, verify the ``Tutorial`` output +contains the message about using GNU-builting. Conversely, if the builtins are +not available you should see the previous behavior from ``Tutorial``. + +Solution +-------- + +First we include and use the ``CheckSourceCompiles`` module, verifying the +provided source code can be built. + +.. + pygments doesn't like the [=[ <string> ]=] literals in the following + literalinclude, so use :language: none + +.. raw:: html + + <details><summary>TODO 4: Click to show/hide answer</summary> + +.. literalinclude:: Step7/MathFunctions/CMakeLists.txt + :caption: TODO 4: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-check-source-compiles + :language: none + :start-at: include(CheckSourceCompiles + :end-at: HAS_GNU_BUILTIN + :append: ) + +.. raw:: html + + </details> + +Then we use the result of the check to conditionally set a compile definition +on ``MathFunctions``. + +.. raw:: html + + <details><summary>TODO 5: Click to show/hide answer</summary> + +.. literalinclude:: Step7/MathFunctions/CMakeLists.txt + :caption: TODO 5: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-define-use-gnu-builtin + :language: cmake + :start-at: if(HAS_GNU_BUILTIN) + :end-at: endif() + +.. raw:: html + + </details> + +Exercise 3 - Check Interprocedural Optimization +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Interprocedural and link time optimizations can provide significant performance +improvements to some software. CMake has the capacity to check for the +availability of IPO flags via :module:`CheckIPOSupported`. + +.. code-block:: cmake + + include(CheckIPOSupported) + check_ipo_supported() # fatal error if IPO is not supported + set_target_properties(MyApp + PROPERTIES + INTERPROCEDURAL_OPTIMIZATION TRUE + ) + +.. note:: + There a couple important caveats with regard to in-project IPO configuration: + + * CMake does not know about every IPO/LTO flag on every compiler, better + results can often be achieved with individual tuning for a known toolchain. + * Setting the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` property on a target + does not alter any of the targets it links to, or dependencies from other + projects. IPO can only "see" into other targets which are also compiled + appropriately. + + For these reasons, serious consideration should be given to manually setting + up IPO/LTO flags across all projects in the dependency tree via external + mechanisms (presets, :option:`-D <cmake -D>` flags, + :manual:`toolchain files <cmake-toolchains(7)>`, etc) instead of in-project + control. + +However, especially for extremely large projects, it can be useful to have +an in-project mechanism to use IPO whenever it is available. + +Goal +---- + +Enable IPO for the entire tutorial project when it is available from the +toolchain. + +Helpful Resources +----------------- + +* :module:`CheckIPOSupported` +* :variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION` + +Files to Edit +------------- + +* ``CMakeLists.txt`` + +Getting Started +--------------- + +Continue editing the files in ``Step6``. Complete ``TODO 6`` and ``TODO 7``. + +Build and Run +------------- + +We need only rebuild the tutorial. + +.. code-block:: console + + cmake --build build + +If IPO is unavailable, we will see an error message during configuration. +Otherwise nothing will change. + +.. note:: + Regardless of the result of the IPO check, we shouldn't expect any change + in behavior from ``Tutorial`` or ``MathFunctions``. + +Solution +-------- + +The first ``TODO`` is easy, we add another option to our project. + +.. raw:: html + + <details><summary>TODO 6: Click to show/hide answer</summary> + +.. literalinclude:: Step7/CMakeLists.txt + :caption: TODO 6: CMakeLists.txt + :name: CMakeLists.txt-enable-ipo + :language: cmake + :start-at: option(TUTORIAL_ENABLE_IPO + :end-at: option(TUTORIAL_ENABLE_IPO + +.. raw:: html + + </details> + +The next step is involved, however the documentation for :module:`CheckIPOSupported` +has an almost complete example of what we need to do. The only difference is +we are going to enable IPO project-wide instead of for a single target. + +.. raw:: html + + <details><summary>TODO 7: Click to show/hide answer</summary> + +.. literalinclude:: Step7/CMakeLists.txt + :caption: TODO 7: CMakeLists.txt + :name: CMakeLists.txt-check-ipo + :language: cmake + :start-at: if(TUTORIAL_ENABLE_IPO) + :end-at: endif() + :append: endif() + +.. raw:: html + + </details> + +.. note:: + Normally we have discouraged setting ``CMAKE_`` variables inside the project. + Here, we are controlling that behavior with an :command:`option()`. This + allows packagers to opt-out of our override. This is an imperfect, but + acceptable solution to situations where we want to provide options to control + project-wide behavior controlled by ``CMAKE_`` variables.
diff --git a/Help/guide/tutorial/Installation Commands and Concepts.rst b/Help/guide/tutorial/Installation Commands and Concepts.rst new file mode 100644 index 0000000..c2422a5 --- /dev/null +++ b/Help/guide/tutorial/Installation Commands and Concepts.rst
@@ -0,0 +1,596 @@ +Step 9: Installation Commands and Concepts +========================================== + +Projects need to do more than build and test their code, they need to make it +available to consumers. The layout of files in the build tree is unsuitable +for consumption by other projects, binaries are in unexpected places, header +files are located far away in the source tree, and there's no clear way +to discover what targets are provided or how to use them. + +This translation, moving artifacts from the source and build trees into a final +layout suitable for consumption, is known as installation. CMake supports a +complete installation workflow as part of the project description, controlling +both the layout of artifacts in the install tree, and reconstructing targets +for other CMake projects which want to consume the libraries provided by the +install tree. + +Background +^^^^^^^^^^ + +All CMake installation goes through a single command, :command:`install`, which +is split into many subcommands responsible for various aspects of the +installation process. For target-based CMake workflows, it is mostly sufficient +to rely on installing targets themselves with :command:`install(TARGETS)` +instead of resorting to manually moving files with :command:`install(FILES)` +or :command:`install(DIRECTORY)`. + +.. note:: + This is why we need to add ``FILES`` to header sets which are intended to be + installed. CMake needs to be able to locate the files when their associated + target is installed. + +CMake divides target-based installation into various artifact kinds. The +available artifact kinds (in CMake 3.23) are: + + ``ARCHIVE`` + Static libraries (``.a`` / ``.lib``), DLL import libraries (``.lib``), and + a handful of other "archive-like" objects. + + ``LIBRARY`` + Shared libraries (``.so``), modules, and other dynamically loadable + objects. **Not** Window's DLL files (``.dll``) or MacOS frameworks. + + ``RUNTIME`` + Executables of all kinds except MacOS bundles; and Window's DLLs (``.dll``). + + ``OBJECT`` + Objects from ``OBJECT`` libraries. + + ``FRAMEWORK`` + Both static and shared MacOS frameworks + + ``BUNDLE`` + MacOS bundle executables + + ``PUBLIC_HEADER`` / ``PRIVATE_HEADER`` / ``RESOURCE`` + Files described by the :prop_tgt:`PUBLIC_HEADER`, :prop_tgt:`PRIVATE_HEADER` + and :prop_tgt:`RESOURCE` target properties, typically used with MacOS + frameworks + + ``FILE_SET <set-name>`` + A file set associated with the target. This is how headers are typically + installed. + +Most important artifact kinds have known destinations which CMake will default +to unless instructed to do otherwise. For example, ``RUNTIME`` will be installed +to the location named by :module:`CMAKE_INSTALL_BINDIR <GNUInstallDirs>`, if +the variable is available, otherwise they default to ``bin``. + +The full list of artifact kind default destinations is described in the +following table. + +=============================== =============================== ====================== + Target Type Variable Built-In Default +=============================== =============================== ====================== +``RUNTIME`` ``${CMAKE_INSTALL_BINDIR}`` ``bin`` +``LIBRARY`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib`` +``ARCHIVE`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib`` +``PRIVATE_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include`` +``PUBLIC_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include`` +``FILE_SET`` (type ``HEADERS``) ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include`` +=============================== =============================== ====================== + +For the most part, projects should leave the defaults alone unless they need to +install to a specific subdirectory of a default location. + +CMake does not define the ``CMAKE_INSTALL_<dir>`` variables by default. If a +project wishes to dictate installing to a subdirectory of one of these +locations, it is necessary to include the :module:`GNUInstallDirs` module, which +will provide values for all ``CMAKE_INSTALL_<dir>`` variables that have not +already been defined. + +Exercise 1 - Installing Artifacts +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For modern, target-based CMake projects installation of artifacts is trivial +and consists of a single call to :command:`install(targets)`. + +.. code-block:: cmake + + install( + TARGETS MyApp MyLib + + FILE_SET HEADERS + FILE_SET anotherHeaderFileSet + ) + +Most artifact kinds are installed by default and do not need to be listed in +the :command:`install` command. However, ``FILE_SET``\ s must be named to let +CMake know you want to install. In the above example we install two file +sets, one named ``HEADERS`` and another named ``anotherHeaderFileSet``. + +When named, an artifact kind can be given various options, such as a destination. + +.. code-block:: cmake + + include(GNUInstallDirs) + + install( + TARGETS MyApp MyLib + + RUNTIME + DESTINATION ${CMAKE_INSTALL_BINDIR}/Subfolder + + FILE_SET HEADERS + ) + +This will install the ``MyApp`` target to ``bin/Subfolder`` (if the packager +hasn't changed :module:`CMAKE_INSTALL_BINDIR <GNUInstallDirs>`). + +Importantly, if the ``OBJECT`` artifact kind is never given a destination, it +will act like an ``INTERFACE`` library, only installing its headers. + +Goal +---- + +Install the artifacts for the libraries and executables (except tests) described +in the tutorial project. + +Helpful Resources +----------------- + +* :command:`install` + +Files to Edit +------------- + +* ``CMakeLists.txt`` + +Getting Started +--------------- + +The ``Help/guide/tutorial/Step9`` directory contains the complete, recommended +solution to ``Step8``. Complete ``TODO 1`` and ``TODO 2``. + +Build and Run +------------- + +No special configuration is needed, configure and build as usual. + +.. code-block:: console + + cmake --preset tutorial + cmake --build build + +We can verify the installation is correct with :option:`cmake --install`. + +.. code-block:: console + + cmake --install build --prefix install + +The ``install`` folder should be populated correctly for our artifacts. + +Solution +-------- + +First we add an :command:`install(TARGETS)` for the conditionally built, +thus conditionally installed, ``Tutorial`` executable. + +.. raw:: html + + <details><summary>TODO 1 Click to show/hide answer</summary> + +.. code-block:: cmake + :caption: TODO 1: CMakeLists.txt + :name: CMakeLists.txt-install-tutorial + + if(TUTORIAL_BUILD_UTILITIES) + add_subdirectory(Tutorial) + install( + TARGETS Tutorial + ) + endif() + +.. raw:: html + + </details> + +Then we can install the rest of the targets. + +.. raw:: html + + <details><summary>TODO 2 Click to show/hide answer</summary> + +.. code-block:: cmake + :caption: TODO 2: CMakeLists.txt + :name: CMakeLists.txt-install-libs + + install( + TARGETS MathFunctions OpAdd OpMul OpSub MathLogger SqrtTable + FILE_SET HEADERS + ) + +.. raw:: html + + </details> + +.. note:: + We could add :command:`install(TARGETS)` commands locally to each subfolder + where the targets are defined. This would be typical in very large projects + where keeping track of all the installable targets is difficult. + +It might seem unnecessary to install the ``SqrtTable`` and ``MathLogger``, +and it is at this stage. Due to how CMake models target relationships, when we +reconstruct the target model in the next exercise we will need these targets to +be available. + +Exercise 2 - Exporting Targets +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This raw collection of installed files is a good start, but we lose the CMake +target model. These are effectively no better than the pre-compiled vendored +libraries we discussed in ``Step 4``. We need some way for other projects to +reconstruct our targets from what we have provided in the install tree. + +The mechanism CMake provides to solve this is a CMakeLang file known as a +"target export file". It is created by the :command:`install(EXPORT)` +command. + +.. code-block:: cmake + + install( + TARGETS MyApp MyLib + EXPORT MyProjectTargets + ) + + include(GNUInstallDirs) + + install( + EXPORT MyProjectTargets + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MyProject + NAMESPACE MyProject:: + ) + +There are several parts to the above example. Firstly the +:command:`install(TARGETS)` command takes an export name, basically a list to +add the installed targets to. + +Later, the :command:`install(EXPORT)` command consumes this list of targets +to generate the target export file. This will be a file named +``<ExportName>.cmake`` located in the provided ``DESTINATION``. The +``DESTINATION`` provided in this example is the conventional one, but any +location searched by the :command:`find_package` command is valid. + +Finally, the targets created by the target export file will be prefixed with the +``NAMESPACE`` string, ie they will be of the form ``<NAMESPACE><TargetName>``. +It is conventional for this to be the project name followed by two colons. + +For reasons that will become more obvious in future steps, we typically don't +consume this file directly. Instead we have a file named +``<ProjectName>Config.cmake`` consume it via :command:`include()`. + +.. code-block:: cmake + + include(${CMAKE_CURRENT_LIST_DIR}/MyProjectTargets.cmake) + +.. note:: + The :variable:`CMAKE_CURRENT_LIST_DIR` variable names the directory that the + currently running CMake Language file is inside of, regardless of how that + file was included or launched. + +Then this file is installed alongside the target export with +:command:`install(FILES)`. + +.. code-block:: cmake + + install( + FILES + cmake/MyProjectConfig.cmake + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MyProject + ) + +.. note:: + The name of this file and its location are dictated by the discovery + semantics of the :command:`find_package` command, which we will discuss more + in the next step. + +Goal +---- + +Export the Tutorial project targets so other projects may consume them. + +Helpful Resources +----------------- + +* :command:`install` +* :module:`GNUInstallDirs` +* :variable:`CMAKE_CURRENT_LIST_DIR` + +Files to Edit +------------- + +* ``CMakeLists.txt`` +* ``cmake/TutorialConfig.cmake`` + +Getting Started +--------------- + +Continue editing the files in the ``Help/guide/tutorial/Step9`` directory. +Complete ``TODO 3`` through ``TODO 8``. + +Build and Run +------------- + +The build command is sufficient to reconfigure the project. + +.. code-block:: console + + cmake --build build + +We can verify the installation is correct with :option:`cmake --install`. + +.. note:: + + As with CTest, when using multi-config generator, eg Visual Studio, it will be + necessary to specify a configuration with + ``cmake --install --config <config> <remaining flags>``, where + ``<config>`` is a value like ``Debug`` or ``Release``. This is true whenever + using a multi-config generator, and won't be called out specifically in + future commands. + +.. code-block:: console + + cmake --install build --prefix install + +.. note:: + CMake won't update files which have not changed, only installing new or + updated files from the build and source trees. + +The ``install`` folder should be populated correctly for our artifacts and +export files. We'll demonstrate how to use these files in the next step. + +Solution +-------- + +First we add the ``Tutorial`` target to the ``TutorialTargets`` export. + +.. raw:: html + + <details><summary>TODO 3 Click to show/hide answer</summary> + +.. literalinclude:: Step10/TutorialProject/CMakeLists.txt + :caption: TODO 3: CMakeLists.txt + :name: CMakeLists.txt-install-tutorial-export + :language: cmake + :start-at: install( + :end-at: ) + +.. raw:: html + + </details> + +Soon we will need access to the ``CMAKE_INSTALL_<dir>`` variables, so next +we include the :module:`GNUInstallDirs` module. + +.. raw:: html + + <details><summary>TODO 4 Click to show/hide answer</summary> + +.. literalinclude:: Step10/TutorialProject/CMakeLists.txt + :caption: TODO 4: CMakeLists.txt + :name: CMakeLists.txt-gnuinstalldirss + :language: cmake + :start-at: include(GNUInstallDirs) + :end-at: include(GNUInstallDirs) + +.. raw:: html + + </details> + +Now we add the rest of our targets to the ``TutorialTargets`` export. + +.. raw:: html + + <details><summary>TODO 5 Click to show/hide answer</summary> + +.. literalinclude:: Step10/TutorialProject/CMakeLists.txt + :caption: TODO 5: CMakeLists.txt + :name: CMakeLists.txt-install-libs-export + :language: cmake + :start-at: TARGETS MathFunctions + :end-at: ) + :prepend: install( + +.. raw:: html + + </details> + +Next we install the export itself, to generate our target export file. + +.. raw:: html + + <details><summary>TODO 6 Click to show/hide answer</summary> + +.. code-block:: cmake + :caption: TODO 6: CMakeLists.txt + :name: CMakeLists.txt-install-export + + install( + EXPORT TutorialTargets + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/Tutorial + NAMESPACE Tutorial:: + ) + +.. raw:: html + + </details> + +And then we install our "config" file, which we will use to include our target +export file. + +.. raw:: html + + <details><summary>TODO 7 Click to show/hide answer</summary> + +.. code-block:: cmake + :caption: TODO 7: CMakeLists.txt + :name: CMakeLists.txt-install-config + + install( + FILES + cmake/TutorialConfig.cmake + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/Tutorial + ) + +.. raw:: html + + </details> + +Finally we can add the necessary :command:`include` command to the config file. + +.. raw:: html + + <details><summary>TODO 8 Click to show/hide answer</summary> + +.. literalinclude:: Step10/TutorialProject/cmake/TutorialConfig.cmake + :caption: TODO 8: cmake/TutorialConfig.cmake + :name: cmake/TutorialConfig.cmake + :language: cmake + :start-at: include + :end-at: include + +.. raw:: html + + </details> + +Exercise 3 - Exporting a Version File +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When importing CMake targets from a target export file, there is no way to +"bail out" or "undo" the operation. If it turns out a package is a wrong or +incompatible version for the one we requested, we'll be stuck with any +side-effects incurred while we learned that version information. + +The answer CMake provides for this problem is a light-weight version file which +only describes this version compatibility information, which can be checked +before CMake commits to fully importing the file. + +CMake provides helper modules and scripts for generating these version files, +namely the :module:`CMakePackageConfigHelpers` module. + +.. code-block:: cmake + + include(CMakePackageConfigHelpers) + + write_basic_package_version_file( + ${CMAKE_CURRENT_BINARY_DIR}/MyProjectConfigVersion.cmake + COMPATIBILITY ExactVersion + ) + +The available versions are: + +* ``AnyNewerVersion`` +* ``SameMajorVersion`` +* ``SameMinorVersion`` +* ``ExactVersion`` + +Additionally packages can mark themselves as ``ARCH_INDEPENDENT``, intended for +packages which ship no binaries which would tie them to a specific machine +architecture. + +By default, the ``VERSION`` used by ``write_basic_package_version_file()`` is +the ``VERSION`` number given to the :command:`project` command. + +Goal +---- + +Export a version file for the Tutorial project. + +Helpful Resources +----------------- + +* :command:`project` +* :command:`install` +* :module:`CMakePackageConfigHelpers` +* :variable:`PROJECT_VERSION` + +Files to Edit +------------- + +* ``CMakeLists.txt`` + +Getting Started +--------------- + +Continue editing the files in the ``Help/guide/tutorial/Step9`` directory. +Complete ``TODO 9`` through ``TODO 12``. + +Build and Run +------------- + +Rebuild and install as done previously. + +.. code-block:: console + + cmake --build build + cmake --install build --prefix install + +The ``install`` folder should be populated correctly with our newly generated +and installed version file. + +Solution +-------- + +First we add a ``VERSION`` parameter to the :command:`project` command. + +.. raw:: html + + <details><summary>TODO 9 Click to show/hide answer</summary> + +.. literalinclude:: Step10/TutorialProject/CMakeLists.txt + :caption: TODO 9: CMakeLists.txt + :name: CMakeLists.txt-project-version + :language: cmake + :start-at: project( + :end-at: ) + +.. raw:: html + + </details> + +Next we include the :module:`CMakePackageConfigHelpers` modules and use it +to generate the config version file. + +.. raw:: html + + <details><summary>TODO 10-11 Click to show/hide answer</summary> + +.. literalinclude:: Step10/TutorialProject/CMakeLists.txt + :caption: TODO 10-11: CMakeLists.txt + :name: CMakeLists.txt-write_basic_package_version_file + :language: cmake + :start-at: include(CMakePackageConfigHelpers + :end-at: COMPATIBILITY ExactVersion + :append: ) + +.. raw:: html + + </details> + +Finally we add the config version file to the list of files to be installed. + +.. raw:: html + + <details><summary>TODO 12 Click to show/hide answer</summary> + +.. literalinclude:: Step10/TutorialProject/CMakeLists.txt + :caption: TODO 12: CMakeLists.txt + :name: CMakeLists.txt-install-version-config + :language: cmake + :start-at: FILES + :end-at: ) + :prepend: install( + +.. raw:: html + + </details>
diff --git a/Help/guide/tutorial/Installing and Testing.rst b/Help/guide/tutorial/Installing and Testing.rst index 7a59fcb..0adf131 100644 --- a/Help/guide/tutorial/Installing and Testing.rst +++ b/Help/guide/tutorial/Installing and Testing.rst
@@ -1,311 +1,10 @@ Step 5: Installing and Testing ============================== -Exercise 1 - Install Rules -^^^^^^^^^^^^^^^^^^^^^^^^^^ +This page was once part of an older version of the CMake tutorial which +last appeared in CMake 4.1. See the current tutorial version :guide:`here <CMake Tutorial>`. -Often, it is not enough to only build an executable, it should also be -installable. With CMake, we can specify install rules using the -:command:`install` command. Supporting local installations for your builds in -CMake is often as simple as specifying an install location and the targets and -files to be installed. +.. only:: cmakeorg -Goal ----- - -Install the ``Tutorial`` executable and the ``MathFunctions`` library. - -Helpful Materials ------------------ - -* :command:`install` - -Files to Edit -------------- - -* ``MathFunctions/CMakeLists.txt`` -* ``CMakeLists.txt`` - -Getting Started ---------------- - -The starting code is provided in the ``Step5`` directory. In this -exercise, complete ``TODO 1`` through ``TODO 4``. - -First, update ``MathFunctions/CMakeLists.txt`` to install the -``MathFunctions`` and ``tutorial_compiler_flags`` libraries to the ``lib`` -directory. In that same file, specify the install rules needed to install -``MathFunctions.h`` to the ``include`` directory. - -Then, update the top level ``CMakeLists.txt`` to install -the ``Tutorial`` executable to the ``bin`` directory. Lastly, any header files -should be installed to the ``include`` directory. Remember that -``TutorialConfig.h`` is in the :variable:`PROJECT_BINARY_DIR`. - -Build and Run -------------- - -Make a new directory called ``Step5_build``. Run the -:manual:`cmake <cmake(1)>` executable or the -:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it -with your chosen build tool. - -Then, run the install step by using the :option:`--install <cmake --install>` -option of the :manual:`cmake <cmake(1)>` command (introduced in 3.15, older -versions of CMake must use ``make install``) from the command line. This step -will install the appropriate header files, libraries, and executables. -For example: - -.. code-block:: console - - cmake --install . - -For multi-configuration tools, don't forget to use the -:option:`--config <cmake--build --config>` argument to specify the configuration. - -.. code-block:: console - - cmake --install . --config Release - -If using an IDE, simply build the ``INSTALL`` target. You can build the same -install target from the command line like the following: - -.. code-block:: console - - cmake --build . --target install --config Debug - -The CMake variable :variable:`CMAKE_INSTALL_PREFIX` is used to determine the -root of where the files will be installed. If using the :option:`cmake --install` -command, the installation prefix can be overridden via the -:option:`--prefix <cmake--install --prefix>` argument. For example: - -.. code-block:: console - - cmake --install . --prefix "/home/myuser/installdir" - -Navigate to the install directory and verify that the installed ``Tutorial`` -runs. - -Solution --------- - -The install rules for our project are fairly simple: - -* For ``MathFunctions``, we want to install the libraries and header file to - the ``lib`` and ``include`` directories respectively. - -* For the ``Tutorial`` executable, we want to install the executable and - configured header file to the ``bin`` and ``include`` directories - respectively. - -So to the end of ``MathFunctions/CMakeLists.txt`` we add: - -.. raw:: html - - <details><summary>TODO 1: Click to show/hide answer</summary> - -.. literalinclude:: Step6/MathFunctions/CMakeLists.txt - :caption: TODO 1: MathFunctions/CMakeLists.txt - :name: MathFunctions/CMakeLists.txt-install-TARGETS - :language: cmake - :start-after: # install libs - :end-before: # install include headers - -.. raw:: html - - </details> - -and - -.. raw:: html - - <details><summary>TODO 2: Click to show/hide answer</summary> - -.. literalinclude:: Step6/MathFunctions/CMakeLists.txt - :caption: TODO 2: MathFunctions/CMakeLists.txt - :name: MathFunctions/CMakeLists.txt-install-headers - :language: cmake - :start-after: # install include headers - -.. raw:: html - - </details> - -The install rules for the ``Tutorial`` executable and configured header file -are similar. To the end of the top-level ``CMakeLists.txt`` we add: - -.. raw:: html - - <details><summary>TODO 3,4: Click to show/hide answer</summary> - -.. literalinclude:: Step6/CMakeLists.txt - :caption: CMakeLists.txt - :name: TODO 3,4: CMakeLists.txt-install-TARGETS - :language: cmake - :start-after: # add the install targets - :end-before: # TODO 1: Replace enable_testing() with include(CTest) - -.. raw:: html - - </details> - -That is all that is needed to create a basic local -install of the tutorial. - -.. _`Tutorial Testing Support`: - -Exercise 2 - Testing Support -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -CTest offers a way to easily manage tests for your project. Tests can be -added through the :command:`add_test` command. Although it is not -explicitly covered in this tutorial, there is a lot of compatibility -between CTest and other testing frameworks such as :module:`GoogleTest`. - -Goal ----- - -Create unit tests for our executable using CTest. - -Helpful Materials ------------------ - -* :command:`enable_testing` -* :command:`add_test` -* :command:`function` -* :command:`set_tests_properties` -* :manual:`ctest <ctest(1)>` - -Files to Edit -------------- - -* ``CMakeLists.txt`` - -Getting Started ---------------- - -The starting source code is provided in the ``Step5`` directory. In this -exercise, complete ``TODO 5`` through ``TODO 9``. - -First, we need to enable testing. Next, begin adding tests to our project -using :command:`add_test`. We will work through adding 3 simple tests and -then you can add additional testing as you see fit. - -Build and Run -------------- - -Navigate to the build directory and rebuild the application. Then, run the -:program:`ctest` executable: :option:`ctest -N` and :option:`ctest -VV`. For -multi-config generators (e.g. Visual Studio), the configuration type must be -specified with the :option:`-C \<mode\> <ctest -C>` flag. For example, to run tests in Debug -mode use ``ctest -C Debug -VV`` from the build directory -(not the Debug subdirectory!). Release mode would be executed from the same -location but with a ``-C Release``. Alternatively, build the ``RUN_TESTS`` -target from the IDE. - -Solution --------- - -Let's test our application. At the end of the top-level ``CMakeLists.txt`` -file we first need to enable testing with the -:command:`enable_testing` command. - -.. raw:: html - - <details><summary>TODO 5: Click to show/hide answer</summary> - -.. literalinclude:: Step6/CMakeLists.txt - :caption: TODO 5: CMakeLists.txt - :name: CMakeLists.txt-enable_testing - :language: cmake - :start-after: # enable testing - :end-before: # does the application run - -.. raw:: html - - </details> - -With testing enabled, we will add a number of basic tests to verify -that the application is working correctly. First, we create a test using -:command:`add_test` which runs the ``Tutorial`` executable with the -parameter 25 passed in. For this test, we are not going to check the -executable's computed answer. This test will verify that -application runs, does not segfault or otherwise crash, and has a zero -return value. This is the basic form of a CTest test. - -.. raw:: html - - <details><summary>TODO 6: Click to show/hide answer</summary> - -.. literalinclude:: Step6/CMakeLists.txt - :caption: TODO 6: CMakeLists.txt - :name: CMakeLists.txt-test-runs - :language: cmake - :start-after: # does the application run - :end-before: # does the usage message work - -.. raw:: html - - </details> - -Next, let's use the :prop_test:`PASS_REGULAR_EXPRESSION` test property to -verify that the output of the test contains certain strings. In this case, -verifying that the usage message is printed when an incorrect number of -arguments are provided. - -.. raw:: html - - <details><summary>TODO 7: Click to show/hide answer</summary> - -.. literalinclude:: Step6/CMakeLists.txt - :caption: TODO 7: CMakeLists.txt - :name: CMakeLists.txt-test-usage - :language: cmake - :start-after: # does the usage message work? - :end-before: # define a function to simplify adding tests - -.. raw:: html - - </details> - -The next test we will add verifies the computed value is truly the -square root. - -.. raw:: html - - <details><summary>TODO 8: Click to show/hide answer</summary> - -.. code-block:: cmake - :caption: TODO 8: CMakeLists.txt - :name: CMakeLists.txt-test-standard - - add_test(NAME StandardUse COMMAND Tutorial 4) - set_tests_properties(StandardUse - PROPERTIES PASS_REGULAR_EXPRESSION "4 is 2" - ) - -.. raw:: html - - </details> - -This one test is not enough to give us confidence that it will -work for all values passed in. We should add more tests to verify this. -To easily add more tests, we make a function called ``do_test`` that runs the -application and verifies that the computed square root is correct for -given input. For each invocation of ``do_test``, another test is added to -the project with a name, input, and expected results based on the passed -arguments. - -.. raw:: html - - <details><summary>TODO 9: Click to show/hide answer</summary> - -.. literalinclude:: Step6/CMakeLists.txt - :caption: TODO 9: CMakeLists.txt - :name: CMakeLists.txt-generalized-tests - :language: cmake - :start-after: # define a function to simplify adding tests - -.. raw:: html - - </details> + To see the older version, follow `this link <https://cmake.org/cmake/help/v4.1/guide/tutorial/Installing%20and%20Testing.html>`_ + or select the drop-down in the page header.
diff --git a/Help/guide/tutorial/Miscellaneous Features.rst b/Help/guide/tutorial/Miscellaneous Features.rst new file mode 100644 index 0000000..51fbe8e --- /dev/null +++ b/Help/guide/tutorial/Miscellaneous Features.rst
@@ -0,0 +1,188 @@ +Step 11: Miscellaneous Features +=============================== + +Some features don't fit well or aren't important enough to receive attention +in the main tutorial, but deserve mention. These exercises collect some of those +features. They should be considered "bonuses". + +There are many CMake features that are not covered by the tutorial, some of +which are considered essential to the projects which use them. Others are +in common use by packagers but see little discussion among software developers +producing local builds. + +This list is not an exhaustive discussion of what remains of CMake's +capabilities. It may grow or shrink with time and relevance. + +Exercise 1: Target Aliases +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This tutorial focuses on installing dependencies and consuming them from an +install tree. It also recommends the use of package managers to facilitate +this process. However, for a variety of reasons both historical and +contemporary this is not always how CMake projects are consumed. + +It is possible to vendor a dependency's source code entirely in a parent project +and consume it with :command:`add_subdirectory`. When performed, the target +names exposed are those used within the project, not those exported via +:command:`install(EXPORT)`. The target names will not have the namespace string +that command prefixes to targets. + +Some projects wish to support this workflow with an interface consistent with +the one presented to :command:`find_package` consumers. CMake supports this via +:command:`add_library(ALIAS)` and :command:`add_executable(ALIAS)`. + +.. code-block:: cmake + + add_library(MyLib INTERFACE) + add_library(MyProject::MyLib ALIAS MyLib) + +Goal +---- + +Add a library alias for the ``MathFunctions`` library. + +Helpful Resources +----------------- + +* :command:`add_library` + +Files to Edit +------------- + +* ``TutorialProject/MathFunctions/CMakeLists.txt`` + +Getting Started +--------------- + +For this step we will only be editing the ``TutorialProject`` project in the +``Step11`` folder. Complete ``TODO 1``. + +Build and Run +------------- + +To build the project we first need configure and install ``SimpleTest``. +Navigate to ``Help/guide/Step11/SimpleTest`` and run the appropriate commands. + +.. code-block:: console + + cmake --preset tutorial + cmake --install build + +Then navigate to ``Help/guide/Step11/TutorialProject`` and perform the usual build. + +.. code-block:: console + + cmake --preset tutorial + cmake --build build + +There should be no observable change in behavior from adding the alias. + +Solution +-------- + +We add a single line to the ``MathFunctions`` CML. + +.. raw:: html + + <details><summary>TODO 1 Click to show/hide answer</summary> + +.. literalinclude:: Complete/TutorialProject/MathFunctions/CMakeLists.txt + :caption: TODO 1: TutorialProject/MathFunctions/CMakeLists.txt + :name: TutorialProject/MathFunctions/CMakeLists.txt-alias + :language: cmake + :start-at: ALIAS + :end-at: ALIAS + +.. raw:: html + + </details> + +Exercise 2: Generator Expressions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:manual:`Generator expressions <cmake-generator-expressions(7)>` are a +complicated domain-specific language supported in some contexts within CMake. +They are most easily understood as deferred-evaluation conditionals, they +express requirements where the inputs to determine the correct behavior are not +known during the CMake configuration stage. + +.. note:: + This is where generator expressions get their name, they are evaluated when + the underlying build system is being generated. + +Generator expressions were commonly used in combination with +:command:`target_include_directories` to express include directory requirements +across the build and install tree, but file sets have superseded this use case. +Their most common applications now are in multi-config generators and +intricate dependency injection systems. + +.. code-block:: cmake + + target_compile_definitions(MyApp PRIVATE "MYAPP_BUILD_CONFIG=$<CONFIG>") + +Goal +---- + +Add a generator expression to ``SimpleTest`` that checks the build configuration +inside a compile definition. + +Helpful Resources +----------------- + +* :command:`target_compile_definitions` +* :manual:`cmake-generator-expressions(7)` + +Files to Edit +------------- + +* ``SimpleTest/CMakeLists.txt`` + +Getting Started +--------------- + +For this step we will only be editing the ``SimpleTest`` project in the +``Step11`` folder. Complete ``TODO 2``. + +Build and Run +------------- + +To build the project we first need configure and install ``SimpleTest``. +Navigate to ``Help/guide/Step11/SimpleTest`` and run the appropriate commands. + +.. code-block:: console + + cmake --preset tutorial + cmake --install build + +Then navigate to ``Help/guide/Step11/TutorialProject`` and perform the usual build. + +.. code-block:: console + + cmake --preset tutorial + cmake --build build + +When running the ``TestMathFunctions`` binary directly, we should a message +naming the build configuration used to build the executable (not necessarily the +same as configuration used to configure ``SimpleTest``). On single configuration +generators, the build configuration can be changed by setting +:variable:`CMAKE_BUILD_TYPE`. + +Solution +-------- + +We add a single line to the ``SimpleTest`` CML. + +.. raw:: html + + <details><summary>TODO 2 Click to show/hide answer</summary> + +.. literalinclude:: Complete/SimpleTest/CMakeLists.txt + :caption: TODO 2: SimpleTest/CMakeLists.txt + :name: SimpleTest/CMakeLists.txt-target_compile_definitions + :language: cmake + :start-at: target_compile_definitions + :end-at: target_compile_definitions + +.. raw:: html + + </details>
diff --git a/Help/guide/tutorial/Packaging Debug and Release.rst b/Help/guide/tutorial/Packaging Debug and Release.rst index 6036969..c6bfdf5 100644 --- a/Help/guide/tutorial/Packaging Debug and Release.rst +++ b/Help/guide/tutorial/Packaging Debug and Release.rst
@@ -1,86 +1,10 @@ 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). +This page was once part of an older version of the CMake tutorial which +last appeared in CMake 4.1. See the current tutorial version :guide:`here <CMake Tutorial>`. -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. +.. only:: cmakeorg -First, we want to ensure that the debug and release builds use different names -for the libraries that will be installed. Let's use ``d`` as the -postfix for the debug libraries. - -Set :variable:`CMAKE_DEBUG_POSTFIX` near the beginning of the top-level -``CMakeLists.txt`` file: - -.. 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 libs - -From the ``Step12`` directory, create ``debug`` and ``release`` -subdirectories. 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 <cmake(1)>` 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 <cpack(1)>` specifying our -custom configuration file with the ``config`` option: - -.. code-block:: console - - cpack --config MultiCPackConfig.cmake + To see the older version, follow `this link <https://cmake.org/cmake/help/v4.1/guide/tutorial/Packaging%20Debug%20and%20Release.html>`_ + or select the drop-down in the page header.
diff --git a/Help/guide/tutorial/Packaging an Installer.rst b/Help/guide/tutorial/Packaging an Installer.rst index 4cca679..82c8a72 100644 --- a/Help/guide/tutorial/Packaging an Installer.rst +++ b/Help/guide/tutorial/Packaging an Installer.rst
@@ -1,64 +1,10 @@ Step 9: 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. +This page was once part of an older version of the CMake tutorial which +last appeared in CMake 4.1. See the current tutorial version :guide:`here <CMake Tutorial>`. -.. literalinclude:: Step10/CMakeLists.txt - :caption: CMakeLists.txt - :name: CMakeLists.txt-include-CPack - :language: cmake - :start-after: # setup installer +.. only:: cmakeorg -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. The :variable:`CPACK_GENERATOR` and -:variable:`CPACK_SOURCE_GENERATOR` variables select the generators used for -binary and source installations, respectively. - -Finally we include the :module:`CPack module <CPack>` which will use these -variables and some other properties of the current system to setup an -installer. - -The next step is to build the project in the usual manner and then run the -:manual:`cpack <cpack(1)>` executable. To build a binary distribution, from the -binary directory run: - -.. code-block:: console - - cpack - -To specify the binary generator, use the :option:`-G <cpack -G>` option. For -multi-config builds, use :option:`-C <cpack -C>` to specify the configuration. -For example: - -.. code-block:: console - - cpack -G ZIP -C Debug - -For a list of available generators, see :manual:`cpack-generators(7)` or call -:option:`cpack --help`. An :cpack_gen:`archive generator <CPack Archive Generator>` -like ZIP creates a compressed archive of all *installed* files. - -To create an archive of the *full* source tree you would type: - -.. 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. + To see the older version, follow `this link <https://cmake.org/cmake/help/v4.1/guide/tutorial/Packaging%20an%20Installer.html>`_ + or select the drop-down in the page header.
diff --git a/Help/guide/tutorial/Selecting Static or Shared Libraries.rst b/Help/guide/tutorial/Selecting Static or Shared Libraries.rst index a2f5e2a..738b572 100644 --- a/Help/guide/tutorial/Selecting Static or Shared Libraries.rst +++ b/Help/guide/tutorial/Selecting Static or Shared Libraries.rst
@@ -1,61 +1,10 @@ Step 10: Selecting Static or Shared Libraries ============================================= -In this section we will show how the :variable:`BUILD_SHARED_LIBS` variable can -be used to control the default behavior of :command:`add_library`, -and allow control over how libraries without an explicit type (``STATIC``, -``SHARED``, ``MODULE`` or ``OBJECT``) are built. +This page was once part of an older version of the CMake tutorial which +last appeared in CMake 4.1. See the current tutorial version :guide:`here <CMake Tutorial>`. -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``. +.. only:: cmakeorg -.. literalinclude:: Step11/CMakeLists.txt - :caption: CMakeLists.txt - :name: CMakeLists.txt-option-BUILD_SHARED_LIBS - :language: cmake - :start-after: set(CMAKE_RUNTIME_OUTPUT_DIRECTORY - :end-before: # configure a header file to pass the version number only - -Next, we need to specify output directories for our static and shared -libraries. - -.. literalinclude:: Step11/CMakeLists.txt - :caption: CMakeLists.txt - :name: CMakeLists.txt-cmake-output-directories - :language: cmake - :start-after: # we don't need to tinker with the path to run the executable - :end-before: # configure a header file to pass the version number only - -Finally, update ``MathFunctions/MathFunctions.h`` to use dll export defines: - -.. literalinclude:: Step11/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`` when building shared libraries. - -.. literalinclude:: Step11/MathFunctions/CMakeLists.txt - :caption: MathFunctions/CMakeLists.txt - :name: MathFunctions/CMakeLists.txt-POSITION_INDEPENDENT_CODE - :language: cmake - :start-at: # state that SqrtLibrary need PIC when the default is shared libraries - :end-at: ) - -Define ``EXPORTING_MYMATH`` stating we are using ``declspec(dllexport)`` when -building on Windows. - -.. literalinclude:: Step11/MathFunctions/CMakeLists.txt - :caption: MathFunctions/CMakeLists.txt - :name: MathFunctions/CMakeLists.txt-dll-export - :language: cmake - :start-at: # define the symbol stating we are using the declspec(dllexport) when - :end-at: target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH") - -**Exercise**: We modified ``MathFunctions.h`` to use dll export defines. -Using CMake documentation can you find a helper module to simplify this? + To see the older version, follow `this link <https://cmake.org/cmake/help/v4.1/guide/tutorial/Selecting%20Static%20or%20Shared%20Libraries.html>`_ + or select the drop-down in the page header.
diff --git a/Help/guide/tutorial/Step0/CMakeLists.txt b/Help/guide/tutorial/Step0/CMakeLists.txt new file mode 100644 index 0000000..35c4cbc --- /dev/null +++ b/Help/guide/tutorial/Step0/CMakeLists.txt
@@ -0,0 +1,9 @@ +cmake_minimum_required(VERSION 3.23) + +project(Tutorial) + +add_executable(hello) +target_sources(hello + PRIVATE + HelloWorld.cxx +)
diff --git a/Help/guide/tutorial/Step0/HelloWorld.cxx b/Help/guide/tutorial/Step0/HelloWorld.cxx new file mode 100644 index 0000000..b936ae8 --- /dev/null +++ b/Help/guide/tutorial/Step0/HelloWorld.cxx
@@ -0,0 +1,6 @@ +#include <cstdio> + +int main() +{ + std::printf("Hello World\n"); +}
diff --git a/Help/guide/tutorial/Step1/CMakeLists.txt b/Help/guide/tutorial/Step1/CMakeLists.txt index 6fcce90..19020c2 100644 --- a/Help/guide/tutorial/Step1/CMakeLists.txt +++ b/Help/guide/tutorial/Step1/CMakeLists.txt
@@ -1,16 +1,21 @@ -# TODO 1: Set the minimum required version of CMake to be 3.10 +# TODO1: Set the minimum required version of CMake to be 3.23 -# TODO 2: Create a project named Tutorial +# TODO2: Create a project named Tutorial -# TODO 7: Set the project version number as 1.0 in the above project command +# TODO3: Add an executable target called Tutorial to the project -# TODO 6: Set the variable CMAKE_CXX_STANDARD to 11 -# and the variable CMAKE_CXX_STANDARD_REQUIRED to True +# TODO4: Add the Tutorial/Tutorial.cxx source file to the Tutorial target -# TODO 8: Use configure_file to configure and copy TutorialConfig.h.in to -# TutorialConfig.h +# TODO7: Add the MathFunctions library as a linked dependency +# to the Tutorial target -# TODO 3: Add an executable called Tutorial to the project -# Hint: Be sure to specify the source file as tutorial.cxx +# TODO11: Add the Tutorial subdirectory to the project -# TODO 9: Use target_include_directories to include ${PROJECT_BINARY_DIR} +# TODO5: Add a library target called MathFunctions to the project + +# TODO6: Add the source and header file located in Step1/MathFunctions to the +# MathFunctions target, note that the intended way to include the +# MathFunctions header is: +# #include <MathFunctions.h> + +# TODO13: Add the MathFunctions subdirectory to the project
diff --git a/Help/guide/tutorial/Step1/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step1/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..0816408 --- /dev/null +++ b/Help/guide/tutorial/Step1/MathFunctions/CMakeLists.txt
@@ -0,0 +1,2 @@ +# TODO12: Move all the MathFunctions target commands to this CMakeLists.txt. +# Ensure that all paths are updated to be relative to this new location.
diff --git a/Help/guide/tutorial/Step1/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step1/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000..4bce912 --- /dev/null +++ b/Help/guide/tutorial/Step1/MathFunctions/MathFunctions.cxx
@@ -0,0 +1,31 @@ +#include <iostream> + +namespace { +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + double result = x; + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + return result; +} +} + +namespace mathfunctions { +double sqrt(double x) +{ + return mysqrt(x); +} +}
diff --git a/Help/guide/tutorial/Step2/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step1/MathFunctions/MathFunctions.h similarity index 100% rename from Help/guide/tutorial/Step2/MathFunctions/MathFunctions.h rename to Help/guide/tutorial/Step1/MathFunctions/MathFunctions.h
diff --git a/Help/guide/tutorial/Step1/Tutorial/CMakeLists.txt b/Help/guide/tutorial/Step1/Tutorial/CMakeLists.txt new file mode 100644 index 0000000..93d5b5f --- /dev/null +++ b/Help/guide/tutorial/Step1/Tutorial/CMakeLists.txt
@@ -0,0 +1,2 @@ +# TODO10: Move all the Tutorial target commands to this CMakeLists.txt. Ensure +# that all paths are updated to be relative to this new location.
diff --git a/Help/guide/tutorial/Step1/Tutorial/Tutorial.cxx b/Help/guide/tutorial/Step1/Tutorial/Tutorial.cxx new file mode 100644 index 0000000..8cc0f2a --- /dev/null +++ b/Help/guide/tutorial/Step1/Tutorial/Tutorial.cxx
@@ -0,0 +1,23 @@ +// A simple program that computes the square root of a number +#include <cmath> +#include <iostream> +#include <string> + +// TODO8: Include the MathFunctions header + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + double const inputValue = std::stod(argv[1]); + + // TODO9: Use the mathfunctions::sqrt function + // calculate square root + double const outputValue = std::sqrt(inputValue); + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; +}
diff --git a/Help/guide/tutorial/Step1/TutorialConfig.h.in b/Help/guide/tutorial/Step1/TutorialConfig.h.in deleted file mode 100644 index 990bfbd..0000000 --- a/Help/guide/tutorial/Step1/TutorialConfig.h.in +++ /dev/null
@@ -1,2 +0,0 @@ -// the configured options and settings for Tutorial -// TODO 10: Define Tutorial_VERSION_MAJOR and Tutorial_VERSION_MINOR
diff --git a/Help/guide/tutorial/Step1/tutorial.cxx b/Help/guide/tutorial/Step1/tutorial.cxx deleted file mode 100644 index 18077b6..0000000 --- a/Help/guide/tutorial/Step1/tutorial.cxx +++ /dev/null
@@ -1,27 +0,0 @@ -// A simple program that computes the square root of a number -#include <cmath> -#include <cstdlib> // TODO 5: Remove this line -#include <iostream> -#include <string> - -// TODO 11: Include TutorialConfig.h - -int main(int argc, char* argv[]) -{ - if (argc < 2) { - // TODO 12: Create a print statement using Tutorial_VERSION_MAJOR - // and Tutorial_VERSION_MINOR - std::cout << "Usage: " << argv[0] << " number" << std::endl; - return 1; - } - - // convert input to double - // TODO 4: Replace atof(argv[1]) with std::stod(argv[1]) - double const inputValue = atof(argv[1]); - - // calculate square root - double const outputValue = sqrt(inputValue); - std::cout << "The square root of " << inputValue << " is " << outputValue - << std::endl; - return 0; -}
diff --git a/Help/guide/tutorial/Step10/CMakeLists.txt b/Help/guide/tutorial/Step10/CMakeLists.txt deleted file mode 100644 index 40fee8d..0000000 --- a/Help/guide/tutorial/Step10/CMakeLists.txt +++ /dev/null
@@ -1,77 +0,0 @@ -cmake_minimum_required(VERSION 3.15) - -# set the project name and version -project(Tutorial VERSION 1.0) - -# specify the C++ standard -add_library(tutorial_compiler_flags INTERFACE) -target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) - -# add compiler warning flags just when building this project via -# the BUILD_INTERFACE genex -set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>") -set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") -target_compile_options(tutorial_compiler_flags INTERFACE - "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>" - "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" -) - -# configure a header file to pass the version number only -configure_file(TutorialConfig.h.in TutorialConfig.h) - -# add the MathFunctions library -add_subdirectory(MathFunctions) - -# add the executable -add_executable(Tutorial tutorial.cxx) -target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags) - -# add the binary tree to the search path for include files -# so that we will find TutorialConfig.h -target_include_directories(Tutorial PUBLIC - "${PROJECT_BINARY_DIR}" - ) - -# add the install targets -install(TARGETS Tutorial DESTINATION bin) -install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" - DESTINATION include - ) - -# enable testing -include(CTest) - -# does the application run -add_test(NAME Runs COMMAND Tutorial 25) - -# does the usage message work? -add_test(NAME Usage COMMAND Tutorial) -set_tests_properties(Usage - PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" - ) - -# define a function to simplify adding tests -function(do_test target arg result) - add_test(NAME Comp${arg} COMMAND ${target} ${arg}) - set_tests_properties(Comp${arg} - PROPERTIES PASS_REGULAR_EXPRESSION ${result} - ) -endfunction() - -# do a bunch of result based tests -do_test(Tutorial 4 "4 is 2") -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 0.0001 "0.0001 is 0.01") - -# setup installer -include(InstallRequiredSystemLibraries) -set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") -set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") -set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") -set(CPACK_GENERATOR "TGZ") -set(CPACK_SOURCE_GENERATOR "TGZ") -include(CPack)
diff --git a/Help/guide/tutorial/Step10/CTestConfig.cmake b/Help/guide/tutorial/Step10/CTestConfig.cmake deleted file mode 100644 index b2922fe..0000000 --- a/Help/guide/tutorial/Step10/CTestConfig.cmake +++ /dev/null
@@ -1,3 +0,0 @@ -set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") - -set(CTEST_SUBMIT_URL "https://my.cdash.org/submit.php?project=CMakeTutorial")
diff --git a/Help/guide/tutorial/Step10/License.txt b/Help/guide/tutorial/Step10/License.txt deleted file mode 100644 index 85760e5..0000000 --- a/Help/guide/tutorial/Step10/License.txt +++ /dev/null
@@ -1,2 +0,0 @@ -This is the open source License.txt file introduced in -CMake/Tutorial/Step9...
diff --git a/Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt deleted file mode 100644 index 210563a..0000000 --- a/Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt +++ /dev/null
@@ -1,45 +0,0 @@ -# add the library that runs -add_library(MathFunctions MathFunctions.cxx) - -# state that anybody linking to us needs to include the current source dir -# to find MathFunctions.h, while we don't. -target_include_directories(MathFunctions - INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} - ) - -# should we use our own math functions -option(USE_MYMATH "Use tutorial provided math implementation" ON) -if(USE_MYMATH) - - target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") - - include(MakeTable.cmake) # generates Table.h - - # library that just does sqrt - add_library(SqrtLibrary STATIC - mysqrt.cxx - ${CMAKE_CURRENT_BINARY_DIR}/Table.h - ) - - # state that we depend on our binary dir to find Table.h - target_include_directories(SqrtLibrary PRIVATE - ${CMAKE_CURRENT_BINARY_DIR} - ) - - # link SqrtLibrary to tutorial_compiler_flags - target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) - - target_link_libraries(MathFunctions PRIVATE SqrtLibrary) -endif() - -# link MathFunctions to tutorial_compiler_flags -target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) - -# install libs -set(installable_libs MathFunctions tutorial_compiler_flags) -if(TARGET SqrtLibrary) - list(APPEND installable_libs SqrtLibrary) -endif() -install(TARGETS ${installable_libs} DESTINATION lib) -# install include headers -install(FILES MathFunctions.h DESTINATION include)
diff --git a/Help/guide/tutorial/Step10/MathFunctions/MakeTable.cmake b/Help/guide/tutorial/Step10/MathFunctions/MakeTable.cmake deleted file mode 100644 index 12865a9..0000000 --- a/Help/guide/tutorial/Step10/MathFunctions/MakeTable.cmake +++ /dev/null
@@ -1,10 +0,0 @@ -# first we add the executable that generates the table -add_executable(MakeTable MakeTable.cxx) -target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags) - -# add the command to generate the source code -add_custom_command( - OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h - COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h - DEPENDS MakeTable - )
diff --git a/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.cxx deleted file mode 100644 index c0991b9..0000000 --- a/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.cxx +++ /dev/null
@@ -1,20 +0,0 @@ - -#include "MathFunctions.h" - -#include <cmath> - -#ifdef USE_MYMATH -# include "mysqrt.h" -#endif - -namespace mathfunctions { -double sqrt(double x) -{ -// which square root function should we use? -#ifdef USE_MYMATH - return detail::mysqrt(x); -#else - return std::sqrt(x); -#endif -} -}
diff --git a/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.h deleted file mode 100644 index 1e916e1..0000000 --- a/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.h +++ /dev/null
@@ -1,3 +0,0 @@ -namespace mathfunctions { -double sqrt(double x); -}
diff --git a/Help/guide/tutorial/Step10/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step10/MathFunctions/mysqrt.cxx deleted file mode 100644 index 8153f18..0000000 --- a/Help/guide/tutorial/Step10/MathFunctions/mysqrt.cxx +++ /dev/null
@@ -1,37 +0,0 @@ -#include <iostream> - -#include "MathFunctions.h" - -// include the generated table -#include "Table.h" - -namespace mathfunctions { -namespace detail { -// a hack square root calculation using simple operations -double mysqrt(double x) -{ - if (x <= 0) { - return 0; - } - - // use the table to help find an initial value - double result = x; - if (x >= 1 && x < 10) { - std::cout << "Use the table to help find an initial value " << std::endl; - result = sqrtTable[static_cast<int>(x)]; - } - - // do ten iterations - for (int i = 0; i < 10; ++i) { - if (result <= 0) { - result = 0.1; - } - double delta = x - (result * result); - result = result + 0.5 * delta / result; - std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; - } - - return result; -} -} -}
diff --git a/Help/guide/tutorial/Step10/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step10/MathFunctions/mysqrt.h deleted file mode 100644 index e1c42ef..0000000 --- a/Help/guide/tutorial/Step10/MathFunctions/mysqrt.h +++ /dev/null
@@ -1,6 +0,0 @@ - -namespace mathfunctions { -namespace detail { -double mysqrt(double x); -} -}
diff --git a/Help/guide/tutorial/Step10/SimpleTest/CMakeLists.txt b/Help/guide/tutorial/Step10/SimpleTest/CMakeLists.txt new file mode 100644 index 0000000..6a73ff4 --- /dev/null +++ b/Help/guide/tutorial/Step10/SimpleTest/CMakeLists.txt
@@ -0,0 +1,52 @@ +# A very simple test framework for demonstrating how dependencies work +cmake_minimum_required(VERSION 3.23) + +project(SimpleTest + VERSION 0.0.1 +) + +add_library(SimpleTest INTERFACE) +target_sources(SimpleTest + INTERFACE + FILE_SET HEADERS + FILES + SimpleTest.h +) +target_compile_features(SimpleTest INTERFACE cxx_std_20) + +# TODO6: Find the TransitiveDep package with find_package. The SimpleTest +# build should fail if TransitiveDep cannot be found. + +# TODO7: Add the TransitiveDep::TransitiveDep target to the SimpleTest interface +# library's links. Remember that interface libraries can only have +# interface properties. + +include(GNUInstallDirs) +include(CMakePackageConfigHelpers) + +install( + TARGETS SimpleTest + EXPORT SimpleTestTargets + FILE_SET HEADERS +) + +install( + EXPORT SimpleTestTargets + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/SimpleTest + NAMESPACE SimpleTest:: +) + +write_basic_package_version_file( + ${CMAKE_CURRENT_BINARY_DIR}/SimpleTestConfigVersion.cmake + COMPATIBILITY ExactVersion + ARCH_INDEPENDENT +) + +install( + FILES + cmake/simpletest_discover_impl.cmake + cmake/simpletest_discover_tests.cmake + cmake/SimpleTestConfig.cmake + ${CMAKE_CURRENT_BINARY_DIR}/SimpleTestConfigVersion.cmake + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/SimpleTest +)
diff --git a/Help/guide/tutorial/Step10/SimpleTest/CMakePresets.json b/Help/guide/tutorial/Step10/SimpleTest/CMakePresets.json new file mode 100644 index 0000000..816d8a3 --- /dev/null +++ b/Help/guide/tutorial/Step10/SimpleTest/CMakePresets.json
@@ -0,0 +1,16 @@ +{ + "version": 4, + "configurePresets": [ + { + "name": "tutorial", + "displayName": "SimpleTest Preset", + "description": "Preset to use with the tutorial's SimpleTest library", + "binaryDir": "${sourceDir}/build", + "installDir": "${sourceParentDir}/install", + "cacheVariables": { + "CMAKE_CXX_STANDARD": "20", + "CMAKE_PREFIX_PATH": "${sourceParentDir}/install" + } + } + ] +}
diff --git a/Help/guide/tutorial/Step10/SimpleTest/SimpleTest.h b/Help/guide/tutorial/Step10/SimpleTest/SimpleTest.h new file mode 100644 index 0000000..ca290d3 --- /dev/null +++ b/Help/guide/tutorial/Step10/SimpleTest/SimpleTest.h
@@ -0,0 +1,151 @@ +#pragma once + +#include <cstdio> +#include <map> +#include <string_view> + +namespace SimpleTest { + +using TestFunc = void (*)(); + +using Registry = std::map<std::string_view, TestFunc, std::less<>>; +inline Registry g_registry; + +inline Registry& registry() +{ + return g_registry; +} + +struct failure +{ + char const* file; + int line; + char const* expr; +}; + +struct Registrar +{ + template <std::size_t N> + Registrar(char const (&name)[N], TestFunc f) + { + auto [it, inserted] = + registry().emplace(std::string_view{ name, N ? (N - 1) : 0 }, f); + if (!inserted) { + std::printf("[ WARN ] duplicate test name: %.*s\n", + int(it->first.size()), it->first.data()); + } + } +}; + +inline Registry const& all() +{ + return registry(); +} +inline TestFunc find(std::string_view name) +{ + auto it = registry().find(name); + return it == registry().end() ? nullptr : it->second; +} + +} + +#define SIMPLETEST_CONCAT_(a, b) a##b +#define SIMPLETEST_CONCAT(a, b) SIMPLETEST_CONCAT_(a, b) + +#define TEST(name_literal) \ + static void SIMPLETEST_CONCAT(_simpletest_fn_, __LINE__)(); \ + static ::SimpleTest::Registrar SIMPLETEST_CONCAT(_simpletest_reg_, \ + __LINE__)( \ + name_literal, &SIMPLETEST_CONCAT(_simpletest_fn_, __LINE__)); \ + static void SIMPLETEST_CONCAT(_simpletest_fn_, __LINE__)() + +// Minimal assertion +#define REQUIRE(expr) \ + do { \ + if (!(expr)) \ + throw ::SimpleTest::failure{ __FILE__, __LINE__, #expr }; \ + } while (0) + +int main(int argc, char** argv) +{ + using namespace ::SimpleTest; + + std::string_view arg1 = + (argc >= 2) ? std::string_view{ argv[1] } : std::string_view{}; + + if (arg1 == "--list") { + bool first = true; + for (auto const& [name, _] : registry()) { + if (!first) + std::printf(","); + std::printf("%.*s", int(name.size()), name.data()); + first = false; + } + std::printf("\n"); + return 0; + } + + if (arg1 == "--test") { + if (argc < 3) { + std::printf("usage: %s [--list] [--test <name>]\n", argv[0]); + return 2; + } + +#ifdef SIMPLETEST_CONFIG + std::printf("SimpleTest built with config: %s\n", SIMPLETEST_CONFIG); +#endif + + std::string_view name{ argv[2] }; + auto it = registry().find(name); + if (it == registry().end()) { + std::printf("[ NOTFOUND ] %s\n", argv[2]); + return 2; + } + + int failed = 0; + std::printf("[ RUN ] %.*s\n", int(it->first.size()), + it->first.data()); + try { + it->second(); + std::printf("[ OK] %.*s\n", int(it->first.size()), + it->first.data()); + } catch (failure const& f) { + std::printf("[ FAILED ] %.*s at %s:%d : %s\n", int(it->first.size()), + it->first.data(), f.file, f.line, f.expr); + failed = 1; + } catch (...) { + std::printf("[ FAILED ] %.*s : unknown exception\n", + int(it->first.size()), it->first.data()); + failed = 1; + } + return failed; + } + + if (argc > 1) { + std::printf("usage: %s [--list] [--test <name>]\n", argv[0]); + return 2; + } + +#ifdef SIMPLETEST_CONFIG + std::printf("SimpleTest built with config: %s\n", SIMPLETEST_CONFIG); +#endif + + // Default: run all tests. + int failed = 0; + for (auto const& [name, func] : all()) { + std::printf("[ RUN ] %.*s\n", int(name.size()), name.data()); + try { + func(); + std::printf("[ OK ] %.*s\n", int(name.size()), name.data()); + } catch (failure const& f) { + std::printf("[ FAILED ] %.*s at %s:%d : %s\n", int(name.size()), + name.data(), f.file, f.line, f.expr); + failed = 1; + } catch (...) { + std::printf("[ FAILED ] %.*s : unknown exception\n", int(name.size()), + name.data()); + failed = 1; + } + } + return failed; +}
diff --git a/Help/guide/tutorial/Step10/SimpleTest/cmake/SimpleTestConfig.cmake b/Help/guide/tutorial/Step10/SimpleTest/cmake/SimpleTestConfig.cmake new file mode 100644 index 0000000..aba0f75 --- /dev/null +++ b/Help/guide/tutorial/Step10/SimpleTest/cmake/SimpleTestConfig.cmake
@@ -0,0 +1,6 @@ +# TODO8: Include the CMakeFindDependencyMacro and use find_dependency to find +# the TransitiveDep package. + + +include(${CMAKE_CURRENT_LIST_DIR}/SimpleTestTargets.cmake) +include(${CMAKE_CURRENT_LIST_DIR}/simpletest_discover_tests.cmake)
diff --git a/Help/guide/tutorial/Step10/SimpleTest/cmake/simpletest_discover_impl.cmake b/Help/guide/tutorial/Step10/SimpleTest/cmake/simpletest_discover_impl.cmake new file mode 100644 index 0000000..7d3a22b --- /dev/null +++ b/Help/guide/tutorial/Step10/SimpleTest/cmake/simpletest_discover_impl.cmake
@@ -0,0 +1,32 @@ +if(NOT DEFINED TEST_EXE OR NOT DEFINED OUT_FILE) +# noqa: spellcheck off + message(FATAL_ERROR "simpletest_discover: need -DTEST_EXE and -DOUT_FILE") +# noqa: spellcheck on +endif() + +execute_process( + COMMAND ${TEST_EXE} --list + RESULT_VARIABLE _rc + OUTPUT_VARIABLE _out + ERROR_VARIABLE _err + OUTPUT_STRIP_TRAILING_WHITESPACE +) + +if(NOT _rc EQUAL 0) + file(WRITE ${OUT_FILE} "# simpletest: --list failed (rc=${_rc})\n") + message(FATAL_ERROR "simpletest_discover: '${TEST_EXE} --list' failed (${_rc})\n${_err}") +endif() + +if(_out STREQUAL "") + file(WRITE ${OUT_FILE} "# simpletest: no tests\n") + return() +endif() + +string(REPLACE "," ";" _names "${_out}") + +file(WRITE ${OUT_FILE} "# Auto-generated by simpletest_discover_impl.cmake\n") +foreach(_name IN LISTS _names) + file(APPEND ${OUT_FILE} + "add_test([=[${_name}]=] \"${TEST_EXE}\" \"--test\" \"${_name}\")\n" + ) +endforeach()
diff --git a/Help/guide/tutorial/Step10/SimpleTest/cmake/simpletest_discover_tests.cmake b/Help/guide/tutorial/Step10/SimpleTest/cmake/simpletest_discover_tests.cmake new file mode 100644 index 0000000..e5cf059 --- /dev/null +++ b/Help/guide/tutorial/Step10/SimpleTest/cmake/simpletest_discover_tests.cmake
@@ -0,0 +1,27 @@ +set(_simpletest_impl_script ${CMAKE_CURRENT_LIST_DIR}/simpletest_discover_impl.cmake) + +function(simpletest_discover_tests target) + if(NOT TARGET ${target}) + message(FATAL_ERROR "simpletest_discover_tests: no such target '${target}'") + endif() + + set(_out ${CMAKE_CURRENT_BINARY_DIR}/${target}_ctests.cmake) + + if(NOT EXISTS ${_out}) + file(WRITE ${_out} "# Populated after building ${target}\n") + endif() + +# noqa: spellcheck off + add_custom_command(TARGET ${target} POST_BUILD + COMMAND ${CMAKE_COMMAND} + -DTEST_EXE=$<TARGET_FILE:${target}> + -DOUT_FILE=${_out} + -P ${_simpletest_impl_script} + BYPRODUCTS ${_out} + COMMENT "SimpleTest: Discovering tests in ${target}" + VERBATIM + ) +# noqa: spellcheck on + + set_property(DIRECTORY APPEND PROPERTY TEST_INCLUDE_FILES ${_out}) +endfunction()
diff --git a/Help/guide/tutorial/Step10/TutorialConfig.h.in b/Help/guide/tutorial/Step10/TutorialConfig.h.in deleted file mode 100644 index 7e4d7fa..0000000 --- a/Help/guide/tutorial/Step10/TutorialConfig.h.in +++ /dev/null
@@ -1,3 +0,0 @@ -// the configured options and settings for Tutorial -#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ -#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@
diff --git a/Help/guide/tutorial/Step10/TutorialProject/CMakeLists.txt b/Help/guide/tutorial/Step10/TutorialProject/CMakeLists.txt new file mode 100644 index 0000000..d153893 --- /dev/null +++ b/Help/guide/tutorial/Step10/TutorialProject/CMakeLists.txt
@@ -0,0 +1,64 @@ +cmake_minimum_required(VERSION 3.23) + +project(Tutorial + VERSION 1.0.0 +) + +option(TUTORIAL_BUILD_UTILITIES "Build the Tutorial executable" ON) +option(TUTORIAL_USE_STD_SQRT "Use std::sqrt" OFF) +option(TUTORIAL_ENABLE_IPO "Check for and use IPO support" ON) +option(BUILD_TESTING "Enable testing and build tests" ON) + +if(TUTORIAL_ENABLE_IPO) + include(CheckIPOSupported) + check_ipo_supported(RESULT result OUTPUT output) + if(result) + message("IPO is supported, enabling IPO") + set(CMAKE_INTERPROCEDURAL_OPTIMIZATION ON) + else() + message(WARNING "IPO is not supported: ${output}") + endif() +endif() + +if(TUTORIAL_BUILD_UTILITIES) + add_subdirectory(Tutorial) + install( + TARGETS Tutorial + EXPORT TutorialTargets + ) +endif() + +if(BUILD_TESTING) + enable_testing() + add_subdirectory(Tests) +endif() + +add_subdirectory(MathFunctions) + +include(GNUInstallDirs) + +install( + TARGETS MathFunctions OpAdd OpMul OpSub MathLogger SqrtTable + EXPORT TutorialTargets + FILE_SET HEADERS +) + +install( + EXPORT TutorialTargets + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/Tutorial + NAMESPACE Tutorial:: +) + +include(CMakePackageConfigHelpers) + +write_basic_package_version_file( + ${CMAKE_CURRENT_BINARY_DIR}/TutorialConfigVersion.cmake + COMPATIBILITY ExactVersion +) + +install( + FILES + cmake/TutorialConfig.cmake + ${CMAKE_CURRENT_BINARY_DIR}/TutorialConfigVersion.cmake + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/Tutorial +)
diff --git a/Help/guide/tutorial/Step10/TutorialProject/CMakePresets.json b/Help/guide/tutorial/Step10/TutorialProject/CMakePresets.json new file mode 100644 index 0000000..3926cac --- /dev/null +++ b/Help/guide/tutorial/Step10/TutorialProject/CMakePresets.json
@@ -0,0 +1,16 @@ +{ + "version": 4, + "configurePresets": [ + { + "name": "tutorial", + "displayName": "Tutorial Preset", + "description": "Preset to use with the tutorial", + "binaryDir": "${sourceDir}/build", + "cacheVariables": { + "TODO4": "Add ${sourceParentDir}/install to CMAKE_PREFIX_PATH", + "TUTORIAL_USE_STD_SQRT": "OFF", + "TUTORIAL_ENABLE_IPO": "OFF" + } + } + ] +}
diff --git a/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..8673342 --- /dev/null +++ b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/CMakeLists.txt
@@ -0,0 +1,54 @@ +add_library(MathFunctions) + +target_sources(MathFunctions + PRIVATE + MathFunctions.cxx + + PUBLIC + FILE_SET HEADERS + FILES + MathFunctions.h +) + +target_link_libraries(MathFunctions + PRIVATE + MathLogger + SqrtTable + + PUBLIC + OpAdd + OpMul + OpSub +) + +target_compile_features(MathFunctions PRIVATE cxx_std_20) + +if(TUTORIAL_USE_STD_SQRT) + target_compile_definitions(MathFunctions PRIVATE TUTORIAL_USE_STD_SQRT) +endif() + +include(CheckIncludeFiles) +check_include_files(emmintrin.h HAS_EMMINTRIN LANGUAGE CXX) + +if(HAS_EMMINTRIN) + target_compile_definitions(MathFunctions PRIVATE TUTORIAL_USE_SSE2) +endif() + +include(CheckSourceCompiles) +check_source_compiles(CXX + [=[ + typedef double v2df __attribute__((vector_size(16))); + int main() { + __builtin_ia32_sqrtsd(v2df{}); + } + ]=] + HAS_GNU_BUILTIN +) + +if(HAS_GNU_BUILTIN) + target_compile_definitions(MathFunctions PRIVATE TUTORIAL_USE_GNU_BUILTIN) +endif() + +add_subdirectory(MathLogger) +add_subdirectory(MathExtensions) +add_subdirectory(MakeTable)
diff --git a/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MakeTable/CMakeLists.txt b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MakeTable/CMakeLists.txt new file mode 100644 index 0000000..6aa2a32 --- /dev/null +++ b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MakeTable/CMakeLists.txt
@@ -0,0 +1,28 @@ +add_executable(MakeTable) + +target_sources(MakeTable + PRIVATE + MakeTable.cxx +) + +add_custom_command( + OUTPUT SqrtTable.h + COMMAND MakeTable SqrtTable.h + DEPENDS MakeTable + VERBATIM +) + +add_custom_target(RunMakeTable DEPENDS SqrtTable.h) + +add_library(SqrtTable INTERFACE) + +target_sources(SqrtTable + INTERFACE + FILE_SET HEADERS + BASE_DIRS + ${CMAKE_CURRENT_BINARY_DIR} + FILES + ${CMAKE_CURRENT_BINARY_DIR}/SqrtTable.h +) + +add_dependencies(SqrtTable RunMakeTable)
diff --git a/Help/guide/tutorial/Step10/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MakeTable/MakeTable.cxx similarity index 100% copy from Help/guide/tutorial/Step10/MathFunctions/MakeTable.cxx copy to Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MakeTable/MakeTable.cxx
diff --git a/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/CMakeLists.txt b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/CMakeLists.txt new file mode 100644 index 0000000..b113786 --- /dev/null +++ b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/CMakeLists.txt
@@ -0,0 +1,3 @@ +add_subdirectory(OpAdd) +add_subdirectory(OpMul) +add_subdirectory(OpSub)
diff --git a/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/OpAdd/CMakeLists.txt b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/OpAdd/CMakeLists.txt new file mode 100644 index 0000000..f35da81 --- /dev/null +++ b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/OpAdd/CMakeLists.txt
@@ -0,0 +1,11 @@ +add_library(OpAdd OBJECT) + +target_sources(OpAdd + PRIVATE + OpAdd.cxx + + INTERFACE + FILE_SET HEADERS + FILES + OpAdd.h +)
diff --git a/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/OpAdd/OpAdd.cxx b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/OpAdd/OpAdd.cxx new file mode 100644 index 0000000..ea11496 --- /dev/null +++ b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/OpAdd/OpAdd.cxx
@@ -0,0 +1,6 @@ +namespace mathfunctions { +double OpAdd(double a, double b) +{ + return a + b; +} +}
diff --git a/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/OpAdd/OpAdd.h b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/OpAdd/OpAdd.h new file mode 100644 index 0000000..9c9efc3 --- /dev/null +++ b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/OpAdd/OpAdd.h
@@ -0,0 +1,5 @@ +#pragma once + +namespace mathfunctions { +double OpAdd(double a, double b); +}
diff --git a/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/OpMul/CMakeLists.txt b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/OpMul/CMakeLists.txt new file mode 100644 index 0000000..f494fc6 --- /dev/null +++ b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/OpMul/CMakeLists.txt
@@ -0,0 +1,11 @@ +add_library(OpMul OBJECT) + +target_sources(OpMul + PRIVATE + OpMul.cxx + + INTERFACE + FILE_SET HEADERS + FILES + OpMul.h +)
diff --git a/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/OpMul/OpMul.cxx b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/OpMul/OpMul.cxx new file mode 100644 index 0000000..c8eb016 --- /dev/null +++ b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/OpMul/OpMul.cxx
@@ -0,0 +1,6 @@ +namespace mathfunctions { +double OpMul(double a, double b) +{ + return a * b; +} +}
diff --git a/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/OpMul/OpMul.h b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/OpMul/OpMul.h new file mode 100644 index 0000000..52b467b --- /dev/null +++ b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/OpMul/OpMul.h
@@ -0,0 +1,5 @@ +#pragma once + +namespace mathfunctions { +double OpMul(double a, double b); +}
diff --git a/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/OpSub/CMakeLists.txt b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/OpSub/CMakeLists.txt new file mode 100644 index 0000000..1a108fd --- /dev/null +++ b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/OpSub/CMakeLists.txt
@@ -0,0 +1,11 @@ +add_library(OpSub OBJECT) + +target_sources(OpSub + PRIVATE + OpSub.cxx + + INTERFACE + FILE_SET HEADERS + FILES + OpSub.h +)
diff --git a/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/OpSub/OpSub.cxx b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/OpSub/OpSub.cxx new file mode 100644 index 0000000..b7b35da --- /dev/null +++ b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/OpSub/OpSub.cxx
@@ -0,0 +1,6 @@ +namespace mathfunctions { +double OpSub(double a, double b) +{ + return a - b; +} +}
diff --git a/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/OpSub/OpSub.h b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/OpSub/OpSub.h new file mode 100644 index 0000000..1406733 --- /dev/null +++ b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathExtensions/OpSub/OpSub.h
@@ -0,0 +1,5 @@ +#pragma once + +namespace mathfunctions { +double OpSub(double a, double b); +}
diff --git a/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000..4bf8051 --- /dev/null +++ b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathFunctions.cxx
@@ -0,0 +1,101 @@ +#include <cmath> +#include <format> + +#include <MathLogger.h> + +#ifdef TUTORIAL_USE_SSE2 +# include <emmintrin.h> +#endif + +namespace { + +mathlogger::Logger Logger; + +#if defined(TUTORIAL_USE_GNU_BUILTIN) +typedef double v2df __attribute__((vector_size(16))); + +double gnu_mysqrt(double x) +{ + v2df root = __builtin_ia32_sqrtsd(v2df{ x, 0.0 }); + double result = root[0]; + Logger.Log(std::format("Computed sqrt of {} to be {} with GNU-builtins\n", x, + result)); + return result; +} +#elif defined(TUTORIAL_USE_SSE2) +double sse2_mysqrt(double x) +{ + __m128d root = _mm_sqrt_sd(_mm_setzero_pd(), _mm_set_sd(x)); + double result = _mm_cvtsd_f64(root); + Logger.Log( + std::format("Computed sqrt of {} to be {} with SSE2\n", x, result)); + return result; +} +#endif + +// a hack square root calculation using simple operations +double fallback_mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + double result = x; + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + + Logger.Log(std::format("Computing sqrt of {} to be {}\n", x, result)); + } + return result; +} + +#include <SqrtTable.h> + +double table_sqrt(double x) +{ + double result = sqrtTable[static_cast<int>(x)]; + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + } + Logger.Log( + std::format("Computed sqrt of {} to be {} with TableSqrt\n", x, result)); + return result; +} + +double mysqrt(double x) +{ + if (x >= 1 && x < 10) { + return table_sqrt(x); + } + +#if defined(TUTORIAL_USE_GNU_BUILTIN) + return gnu_mysqrt(x); +#elif defined(TUTORIAL_USE_SSE2) + return sse2_mysqrt(x); +#else + return fallback_mysqrt(x); +#endif +} +} + +namespace mathfunctions { +double sqrt(double x) +{ +#ifdef TUTORIAL_USE_STD_SQRT + return std::sqrt(x); +#else + return mysqrt(x); +#endif +} +}
diff --git a/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..91cb176 --- /dev/null +++ b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathFunctions.h
@@ -0,0 +1,9 @@ +#pragma once + +#include <OpAdd.h> +#include <OpMul.h> +#include <OpSub.h> + +namespace mathfunctions { +double sqrt(double x); +}
diff --git a/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathLogger/CMakeLists.txt b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathLogger/CMakeLists.txt new file mode 100644 index 0000000..b20151f --- /dev/null +++ b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathLogger/CMakeLists.txt
@@ -0,0 +1,6 @@ +add_library(MathLogger INTERFACE) + +target_sources(MathLogger + INTERFACE + FILE_SET HEADERS +)
diff --git a/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathLogger/MathFormatting.h b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathLogger/MathFormatting.h new file mode 100644 index 0000000..3b6d61c --- /dev/null +++ b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathLogger/MathFormatting.h
@@ -0,0 +1,27 @@ +#pragma once + +#include <string> + +namespace mathlogger { + +enum LogLevel +{ + INFO, + WARN, + ERROR, +}; + +inline std::string FormatLog(LogLevel level, std::string const& message) +{ + switch (level) { + case INFO: + return "INFO: " + message; + case WARN: + return "WARN: " + message; + case ERROR: + return "ERROR: " + message; + } + return "UNKNOWN: " + message; +} + +}
diff --git a/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathLogger/MathLogger.h b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathLogger/MathLogger.h new file mode 100644 index 0000000..ef7b31a --- /dev/null +++ b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathLogger/MathLogger.h
@@ -0,0 +1,22 @@ +#pragma once + +#include <string> + +#include "MathFormatting.h" +#include "MathOutput.h" + +namespace mathlogger { + +struct Logger +{ + LogLevel level = INFO; + + void SetLevel(LogLevel new_level) { level = new_level; } + void Log(std::string const& message) + { + std::string formatted = FormatLog(level, message); + WriteLog(formatted); + } +}; + +}
diff --git a/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathLogger/MathOutput.h b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathLogger/MathOutput.h new file mode 100644 index 0000000..63f0aeb --- /dev/null +++ b/Help/guide/tutorial/Step10/TutorialProject/MathFunctions/MathLogger/MathOutput.h
@@ -0,0 +1,11 @@ +#pragma once + +#include <iostream> +#include <string> + +namespace mathlogger { +inline void WriteLog(std::string const& msg) +{ + std::cout << msg; +} +}
diff --git a/Help/guide/tutorial/Step10/TutorialProject/Tests/CMakeLists.txt b/Help/guide/tutorial/Step10/TutorialProject/Tests/CMakeLists.txt new file mode 100644 index 0000000..1f4482c --- /dev/null +++ b/Help/guide/tutorial/Step10/TutorialProject/Tests/CMakeLists.txt
@@ -0,0 +1,31 @@ +add_executable(TestMathFunctions) + +target_sources(TestMathFunctions + PRIVATE + TestMathFunctions.cxx +) + +# TODO1: Find the SimpleTest package. This should be a required dependency when +# building tests. + +# TODO2: Add the SimpleTest::SimpleTest target to Test MathFunctions + +target_link_libraries(TestMathFunctions + PRIVATE + MathFunctions +) + +# TODO3: Replace MathFunctionTest and all the calls to it with +# simpletest_discover_tests called on TestMathFunctions + +function(MathFunctionTest op) + add_test( + NAME ${op} + COMMAND TestMathFunctions ${op} + ) +endfunction() + +MathFunctionTest(add) +MathFunctionTest(mul) +MathFunctionTest(sqrt) +MathFunctionTest(sub)
diff --git a/Help/guide/tutorial/Step10/TutorialProject/Tests/TestMathFunctions.cxx b/Help/guide/tutorial/Step10/TutorialProject/Tests/TestMathFunctions.cxx new file mode 100644 index 0000000..68a3419 --- /dev/null +++ b/Help/guide/tutorial/Step10/TutorialProject/Tests/TestMathFunctions.cxx
@@ -0,0 +1,28 @@ +#include <MathFunctions.h> + +// TODO5: Replace the following 5 lines with #include <SimpleTest.h> +#define TEST(x) namespace +#define REQUIRE(x) +int main() +{ +} + +TEST("add") +{ + REQUIRE(mathfunctions::OpAdd(2.0, 2.0) == 4.0); +} + +TEST("sub") +{ + REQUIRE(mathfunctions::OpSub(4.0, 2.0) == 2.0); +} + +TEST("mul") +{ + REQUIRE(mathfunctions::OpMul(5.0, 5.0) == 25.0); +} + +TEST("sqrt") +{ + REQUIRE(mathfunctions::sqrt(25.0) == 5.0); +}
diff --git a/Help/guide/tutorial/Step10/TutorialProject/Tutorial/CMakeLists.txt b/Help/guide/tutorial/Step10/TutorialProject/Tutorial/CMakeLists.txt new file mode 100644 index 0000000..05eac5c --- /dev/null +++ b/Help/guide/tutorial/Step10/TutorialProject/Tutorial/CMakeLists.txt
@@ -0,0 +1,36 @@ +add_executable(Tutorial) + +target_sources(Tutorial + PRIVATE + Tutorial.cxx +) + +target_link_libraries(Tutorial + PRIVATE + MathFunctions +) + +target_compile_features(Tutorial PRIVATE cxx_std_20) + +if( + (CMAKE_CXX_COMPILER_ID STREQUAL "MSVC") OR + (CMAKE_CXX_COMPILER_FRONTEND_VARIANT STREQUAL "MSVC") +) + + target_compile_options(Tutorial PRIVATE /W3) + +elseif( + (CMAKE_CXX_COMPILER_ID STREQUAL "GNU") OR + (CMAKE_CXX_COMPILER_ID MATCHES "Clang") +) + + target_compile_options(Tutorial PRIVATE -Wall) + +endif() + +# TODO9: Find the path to the folder containing Unpackaged.h. The build should +# fail if this path is not discovered. Note that Unpackaged.h is stored +# in a subdirectory named "Unpackaged". + +# TODO10: Add the discovered path to the Tutorial executable target's +# include directories.
diff --git a/Help/guide/tutorial/Step10/TutorialProject/Tutorial/Tutorial.cxx b/Help/guide/tutorial/Step10/TutorialProject/Tutorial/Tutorial.cxx new file mode 100644 index 0000000..3b8f911 --- /dev/null +++ b/Help/guide/tutorial/Step10/TutorialProject/Tutorial/Tutorial.cxx
@@ -0,0 +1,28 @@ +// A simple program that computes the square root of a number +#include <format> +#include <iostream> +#include <string> + +#include <MathFunctions.h> + +// TODO11: Include the Unpackaged.h header + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + std::cout << std::format("Usage: {} number\n", argv[0]); + return 1; + } + + // convert input to double + double const inputValue = std::stod(argv[1]); + + // calculate square root + double const outputValue = mathfunctions::sqrt(inputValue); + std::cout << std::format("The square root of {} is {}\n", inputValue, + outputValue); + + double const checkValue = mathfunctions::OpMul(outputValue, outputValue); + std::cout << std::format("The square of {} is {}\n", outputValue, + checkValue); +}
diff --git a/Help/guide/tutorial/Step10/TutorialProject/cmake/TutorialConfig.cmake b/Help/guide/tutorial/Step10/TutorialProject/cmake/TutorialConfig.cmake new file mode 100644 index 0000000..d13caa4 --- /dev/null +++ b/Help/guide/tutorial/Step10/TutorialProject/cmake/TutorialConfig.cmake
@@ -0,0 +1 @@ +include(${CMAKE_CURRENT_LIST_DIR}/TutorialTargets.cmake)
diff --git a/Help/guide/tutorial/Step10/install/include/Unpackaged/Unpackaged.h b/Help/guide/tutorial/Step10/install/include/Unpackaged/Unpackaged.h new file mode 100644 index 0000000..9782b0a --- /dev/null +++ b/Help/guide/tutorial/Step10/install/include/Unpackaged/Unpackaged.h
@@ -0,0 +1,3 @@ +#pragma once + +#define UNPACKAGED_HEADER_FOUND
diff --git a/Help/guide/tutorial/Step10/install/lib/cmake/TransitiveDep/TransitiveDepConfig.cmake b/Help/guide/tutorial/Step10/install/lib/cmake/TransitiveDep/TransitiveDepConfig.cmake new file mode 100644 index 0000000..ef51145 --- /dev/null +++ b/Help/guide/tutorial/Step10/install/lib/cmake/TransitiveDep/TransitiveDepConfig.cmake
@@ -0,0 +1,50 @@ +# Abridged import written for the Tutorial + +if("${CMAKE_MAJOR_VERSION}.${CMAKE_MINOR_VERSION}" LESS 2.8) + message(FATAL_ERROR "CMake >= 3.0.0 required") +endif() +if(CMAKE_VERSION VERSION_LESS "3.0.0") + message(FATAL_ERROR "CMake >= 3.0.0 required") +endif() +cmake_policy(PUSH) +cmake_policy(VERSION 3.0.0...3.30) + +# Commands may need to know the format version. +set(CMAKE_IMPORT_FILE_VERSION 1) + +# Protect against multiple inclusion, which would fail when already imported targets are added once more. +set(_cmake_targets_defined "") +set(_cmake_targets_not_defined "") +set(_cmake_expected_targets "") +foreach(_cmake_expected_target IN ITEMS TransitiveDep::TransitiveDep) + list(APPEND _cmake_expected_targets "${_cmake_expected_target}") + if(TARGET "${_cmake_expected_target}") + list(APPEND _cmake_targets_defined "${_cmake_expected_target}") + else() + list(APPEND _cmake_targets_not_defined "${_cmake_expected_target}") + endif() +endforeach() +unset(_cmake_expected_target) +if(_cmake_targets_defined STREQUAL _cmake_expected_targets) + unset(_cmake_targets_defined) + unset(_cmake_targets_not_defined) + unset(_cmake_expected_targets) + unset(CMAKE_IMPORT_FILE_VERSION) + cmake_policy(POP) + return() +endif() +if(NOT _cmake_targets_defined STREQUAL "") + string(REPLACE ";" ", " _cmake_targets_defined_text "${_cmake_targets_defined}") + string(REPLACE ";" ", " _cmake_targets_not_defined_text "${_cmake_targets_not_defined}") + message(FATAL_ERROR "Some (but not all) targets in this export set were already defined.\nTargets Defined: ${_cmake_targets_defined_text}\nTargets not yet defined: ${_cmake_targets_not_defined_text}\n") +endif() +unset(_cmake_targets_defined) +unset(_cmake_targets_not_defined) +unset(_cmake_expected_targets) + +# Create imported target TransitiveDep::TransitiveDep +add_library(TransitiveDep::TransitiveDep INTERFACE IMPORTED) + +# Commands beyond this point should not need to know the version. +set(CMAKE_IMPORT_FILE_VERSION) +cmake_policy(POP)
diff --git a/Help/guide/tutorial/Step10/tutorial.cxx b/Help/guide/tutorial/Step10/tutorial.cxx deleted file mode 100644 index ca5110c..0000000 --- a/Help/guide/tutorial/Step10/tutorial.cxx +++ /dev/null
@@ -1,27 +0,0 @@ -// A simple program that computes the square root of a number -#include <iostream> -#include <sstream> -#include <string> - -#include "MathFunctions.h" -#include "TutorialConfig.h" - -int main(int argc, char* argv[]) -{ - if (argc < 2) { - // report version - std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." - << Tutorial_VERSION_MINOR << std::endl; - std::cout << "Usage: " << argv[0] << " number" << std::endl; - return 1; - } - - // convert input to double - double const inputValue = std::stod(argv[1]); - - double const outputValue = mathfunctions::sqrt(inputValue); - - std::cout << "The square root of " << inputValue << " is " << outputValue - << std::endl; - return 0; -}
diff --git a/Help/guide/tutorial/Step11/CMakeLists.txt b/Help/guide/tutorial/Step11/CMakeLists.txt deleted file mode 100644 index 9214c88..0000000 --- a/Help/guide/tutorial/Step11/CMakeLists.txt +++ /dev/null
@@ -1,85 +0,0 @@ -cmake_minimum_required(VERSION 3.15) - -# set the project name and version -project(Tutorial VERSION 1.0) - -# specify the C++ standard -add_library(tutorial_compiler_flags INTERFACE) -target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) - -# add compiler warning flags just when building this project via -# the BUILD_INTERFACE genex -set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>") -set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") -target_compile_options(tutorial_compiler_flags INTERFACE - "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>" - "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" -) - -# control where the static and shared libraries are built so that on windows -# we don't need to tinker with the path to run the executable -set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") -set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") -set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") - -option(BUILD_SHARED_LIBS "Build using shared libraries" ON) - -# configure a header file to pass the version number only -configure_file(TutorialConfig.h.in TutorialConfig.h) - -# add the MathFunctions library -add_subdirectory(MathFunctions) - -# add the executable -add_executable(Tutorial tutorial.cxx) -target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags) - -# add the binary tree to the search path for include files -# so that we will find TutorialConfig.h -target_include_directories(Tutorial PUBLIC - "${PROJECT_BINARY_DIR}" - ) - -# add the install targets -install(TARGETS Tutorial DESTINATION bin) -install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" - DESTINATION include - ) - -# enable testing -include(CTest) - -# does the application run -add_test(NAME Runs COMMAND Tutorial 25) - -# does the usage message work? -add_test(NAME Usage COMMAND Tutorial) -set_tests_properties(Usage - PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" - ) - -# define a function to simplify adding tests -function(do_test target arg result) - add_test(NAME Comp${arg} COMMAND ${target} ${arg}) - set_tests_properties(Comp${arg} - PROPERTIES PASS_REGULAR_EXPRESSION ${result} - ) -endfunction() - -# do a bunch of result based tests -do_test(Tutorial 4 "4 is 2") -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 0.0001 "0.0001 is 0.01") - -# setup installer -include(InstallRequiredSystemLibraries) -set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") -set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") -set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") -set(CPACK_GENERATOR "TGZ") -set(CPACK_SOURCE_GENERATOR "TGZ") -include(CPack)
diff --git a/Help/guide/tutorial/Step11/CTestConfig.cmake b/Help/guide/tutorial/Step11/CTestConfig.cmake deleted file mode 100644 index b2922fe..0000000 --- a/Help/guide/tutorial/Step11/CTestConfig.cmake +++ /dev/null
@@ -1,3 +0,0 @@ -set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") - -set(CTEST_SUBMIT_URL "https://my.cdash.org/submit.php?project=CMakeTutorial")
diff --git a/Help/guide/tutorial/Step11/License.txt b/Help/guide/tutorial/Step11/License.txt deleted file mode 100644 index 85760e5..0000000 --- a/Help/guide/tutorial/Step11/License.txt +++ /dev/null
@@ -1,2 +0,0 @@ -This is the open source License.txt file introduced in -CMake/Tutorial/Step9...
diff --git a/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt deleted file mode 100644 index eacc538..0000000 --- a/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt +++ /dev/null
@@ -1,54 +0,0 @@ -# add the library that runs -add_library(MathFunctions MathFunctions.cxx) - -# state that anybody linking to us needs to include the current source dir -# to find MathFunctions.h, while we don't. -target_include_directories(MathFunctions - INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} - ) - -# should we use our own math functions -option(USE_MYMATH "Use tutorial provided math implementation" ON) -if(USE_MYMATH) - - target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") - - include(MakeTable.cmake) # generates Table.h - - # library that just does sqrt - add_library(SqrtLibrary STATIC - mysqrt.cxx - ${CMAKE_CURRENT_BINARY_DIR}/Table.h - ) - - # state that we depend on our binary dir to find Table.h - target_include_directories(SqrtLibrary PRIVATE - ${CMAKE_CURRENT_BINARY_DIR} - ) - - # state that SqrtLibrary need PIC when the default is shared libraries - set_target_properties(SqrtLibrary PROPERTIES - POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS} - ) - - # link SqrtLibrary to tutorial_compiler_flags - target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) - - target_link_libraries(MathFunctions PRIVATE SqrtLibrary) -endif() - -# link MathFunctions to tutorial_compiler_flags -target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) - -# define the symbol stating we are using the declspec(dllexport) when -# building on windows -target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH") - -# install libs -set(installable_libs MathFunctions tutorial_compiler_flags) -if(TARGET SqrtLibrary) - list(APPEND installable_libs SqrtLibrary) -endif() -install(TARGETS ${installable_libs} DESTINATION lib) -# install include headers -install(FILES MathFunctions.h DESTINATION include)
diff --git a/Help/guide/tutorial/Step11/MathFunctions/MakeTable.cmake b/Help/guide/tutorial/Step11/MathFunctions/MakeTable.cmake deleted file mode 100644 index 12865a9..0000000 --- a/Help/guide/tutorial/Step11/MathFunctions/MakeTable.cmake +++ /dev/null
@@ -1,10 +0,0 @@ -# first we add the executable that generates the table -add_executable(MakeTable MakeTable.cxx) -target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags) - -# add the command to generate the source code -add_custom_command( - OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h - COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h - DEPENDS MakeTable - )
diff --git a/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.cxx deleted file mode 100644 index c0991b9..0000000 --- a/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.cxx +++ /dev/null
@@ -1,20 +0,0 @@ - -#include "MathFunctions.h" - -#include <cmath> - -#ifdef USE_MYMATH -# include "mysqrt.h" -#endif - -namespace mathfunctions { -double sqrt(double x) -{ -// which square root function should we use? -#ifdef USE_MYMATH - return detail::mysqrt(x); -#else - return std::sqrt(x); -#endif -} -}
diff --git a/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.h deleted file mode 100644 index 3fb547b..0000000 --- a/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.h +++ /dev/null
@@ -1,14 +0,0 @@ - -#if defined(_WIN32) -# if defined(EXPORTING_MYMATH) -# define DECLSPEC __declspec(dllexport) -# else -# define DECLSPEC __declspec(dllimport) -# endif -#else // non windows -# define DECLSPEC -#endif - -namespace mathfunctions { -double DECLSPEC sqrt(double x); -}
diff --git a/Help/guide/tutorial/Step11/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step11/MathFunctions/mysqrt.cxx deleted file mode 100644 index 8153f18..0000000 --- a/Help/guide/tutorial/Step11/MathFunctions/mysqrt.cxx +++ /dev/null
@@ -1,37 +0,0 @@ -#include <iostream> - -#include "MathFunctions.h" - -// include the generated table -#include "Table.h" - -namespace mathfunctions { -namespace detail { -// a hack square root calculation using simple operations -double mysqrt(double x) -{ - if (x <= 0) { - return 0; - } - - // use the table to help find an initial value - double result = x; - if (x >= 1 && x < 10) { - std::cout << "Use the table to help find an initial value " << std::endl; - result = sqrtTable[static_cast<int>(x)]; - } - - // do ten iterations - for (int i = 0; i < 10; ++i) { - if (result <= 0) { - result = 0.1; - } - double delta = x - (result * result); - result = result + 0.5 * delta / result; - std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; - } - - return result; -} -} -}
diff --git a/Help/guide/tutorial/Step11/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step11/MathFunctions/mysqrt.h deleted file mode 100644 index e1c42ef..0000000 --- a/Help/guide/tutorial/Step11/MathFunctions/mysqrt.h +++ /dev/null
@@ -1,6 +0,0 @@ - -namespace mathfunctions { -namespace detail { -double mysqrt(double x); -} -}
diff --git a/Help/guide/tutorial/Step11/SimpleTest/CMakeLists.txt b/Help/guide/tutorial/Step11/SimpleTest/CMakeLists.txt new file mode 100644 index 0000000..866640e --- /dev/null +++ b/Help/guide/tutorial/Step11/SimpleTest/CMakeLists.txt
@@ -0,0 +1,54 @@ +# A very simple test framework for demonstrating how dependencies work +cmake_minimum_required(VERSION 3.23) + +project(SimpleTest + VERSION 0.0.1 +) + +add_library(SimpleTest INTERFACE) +target_sources(SimpleTest + INTERFACE + FILE_SET HEADERS + FILES + SimpleTest.h +) +target_compile_features(SimpleTest INTERFACE cxx_std_20) + +# TODO2: Add a compile definition that sets SIMPLETEST_CONFIG=$<CONFIG> +# on the SimpleTest target + +find_package(TransitiveDep REQUIRED) +target_link_libraries(SimpleTest + INTERFACE + TransitiveDep::TransitiveDep +) + +include(GNUInstallDirs) +include(CMakePackageConfigHelpers) + +install( + TARGETS SimpleTest + EXPORT SimpleTestTargets + FILE_SET HEADERS +) + +install( + EXPORT SimpleTestTargets + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/SimpleTest + NAMESPACE SimpleTest:: +) + +write_basic_package_version_file( + ${CMAKE_CURRENT_BINARY_DIR}/SimpleTestConfigVersion.cmake + COMPATIBILITY ExactVersion + ARCH_INDEPENDENT +) + +install( + FILES + cmake/simpletest_discover_impl.cmake + cmake/simpletest_discover_tests.cmake + cmake/SimpleTestConfig.cmake + ${CMAKE_CURRENT_BINARY_DIR}/SimpleTestConfigVersion.cmake + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/SimpleTest +)
diff --git a/Help/guide/tutorial/Step11/SimpleTest/CMakePresets.json b/Help/guide/tutorial/Step11/SimpleTest/CMakePresets.json new file mode 100644 index 0000000..816d8a3 --- /dev/null +++ b/Help/guide/tutorial/Step11/SimpleTest/CMakePresets.json
@@ -0,0 +1,16 @@ +{ + "version": 4, + "configurePresets": [ + { + "name": "tutorial", + "displayName": "SimpleTest Preset", + "description": "Preset to use with the tutorial's SimpleTest library", + "binaryDir": "${sourceDir}/build", + "installDir": "${sourceParentDir}/install", + "cacheVariables": { + "CMAKE_CXX_STANDARD": "20", + "CMAKE_PREFIX_PATH": "${sourceParentDir}/install" + } + } + ] +}
diff --git a/Help/guide/tutorial/Step11/SimpleTest/SimpleTest.h b/Help/guide/tutorial/Step11/SimpleTest/SimpleTest.h new file mode 100644 index 0000000..ced6562 --- /dev/null +++ b/Help/guide/tutorial/Step11/SimpleTest/SimpleTest.h
@@ -0,0 +1,155 @@ +#pragma once + +#include <cstdio> +#include <map> +#include <string_view> + +namespace SimpleTest { + +using TestFunc = void (*)(); + +using Registry = std::map<std::string_view, TestFunc, std::less<>>; +inline Registry g_registry; + +inline Registry& registry() +{ + return g_registry; +} + +struct failure +{ + char const* file; + int line; + char const* expr; +}; + +struct Registrar +{ + template <std::size_t N> + Registrar(char const (&name)[N], TestFunc f) + { + auto [it, inserted] = + registry().emplace(std::string_view{ name, N ? (N - 1) : 0 }, f); + if (!inserted) { + std::printf("[ WARN ] duplicate test name: %.*s\n", + int(it->first.size()), it->first.data()); + } + } +}; + +inline Registry const& all() +{ + return registry(); +} +inline TestFunc find(std::string_view name) +{ + auto it = registry().find(name); + return it == registry().end() ? nullptr : it->second; +} + +} + +#define SIMPLETEST_STRINGIFY(a) #a +#define SIMPLETEST_XSTRINGIFY(a) SIMPLETEST_STRINGIFY(a) +#define SIMPLETEST_CONCAT_(a, b) a##b +#define SIMPLETEST_CONCAT(a, b) SIMPLETEST_CONCAT_(a, b) + +#define TEST(name_literal) \ + static void SIMPLETEST_CONCAT(_simpletest_fn_, __LINE__)(); \ + static ::SimpleTest::Registrar SIMPLETEST_CONCAT(_simpletest_reg_, \ + __LINE__)( \ + name_literal, &SIMPLETEST_CONCAT(_simpletest_fn_, __LINE__)); \ + static void SIMPLETEST_CONCAT(_simpletest_fn_, __LINE__)() + +// Minimal assertion +#define REQUIRE(expr) \ + do { \ + if (!(expr)) \ + throw ::SimpleTest::failure{ __FILE__, __LINE__, #expr }; \ + } while (0) + +int main(int argc, char** argv) +{ + using namespace ::SimpleTest; + + std::string_view arg1 = + (argc >= 2) ? std::string_view{ argv[1] } : std::string_view{}; + + if (arg1 == "--list") { + bool first = true; + for (auto const& [name, _] : registry()) { + if (!first) + std::printf(","); + std::printf("%.*s", int(name.size()), name.data()); + first = false; + } + std::printf("\n"); + return 0; + } + + if (arg1 == "--test") { + if (argc < 3) { + std::printf("usage: %s [--list] [--test <name>]\n", argv[0]); + return 2; + } + +#ifdef SIMPLETEST_CONFIG + std::printf("SimpleTest built with config: " SIMPLETEST_XSTRINGIFY( + SIMPLETEST_CONFIG) "\n"); +#endif + + std::string_view name{ argv[2] }; + auto it = registry().find(name); + if (it == registry().end()) { + std::printf("[ NOTFOUND ] %s\n", argv[2]); + return 2; + } + + int failed = 0; + std::printf("[ RUN ] %.*s\n", int(it->first.size()), + it->first.data()); + try { + it->second(); + std::printf("[ OK] %.*s\n", int(it->first.size()), + it->first.data()); + } catch (failure const& f) { + std::printf("[ FAILED ] %.*s at %s:%d : %s\n", int(it->first.size()), + it->first.data(), f.file, f.line, f.expr); + failed = 1; + } catch (...) { + std::printf("[ FAILED ] %.*s : unknown exception\n", + int(it->first.size()), it->first.data()); + failed = 1; + } + return failed; + } + + if (argc > 1) { + std::printf("usage: %s [--list] [--test <name>]\n", argv[0]); + return 2; + } + +#ifdef SIMPLETEST_CONFIG + std::printf("SimpleTest built with config: " SIMPLETEST_XSTRINGIFY( + SIMPLETEST_CONFIG) "\n"); +#endif + + // Default: run all tests. + int failed = 0; + for (auto const& [name, func] : all()) { + std::printf("[ RUN ] %.*s\n", int(name.size()), name.data()); + try { + func(); + std::printf("[ OK ] %.*s\n", int(name.size()), name.data()); + } catch (failure const& f) { + std::printf("[ FAILED ] %.*s at %s:%d : %s\n", int(name.size()), + name.data(), f.file, f.line, f.expr); + failed = 1; + } catch (...) { + std::printf("[ FAILED ] %.*s : unknown exception\n", int(name.size()), + name.data()); + failed = 1; + } + } + return failed; +}
diff --git a/Help/guide/tutorial/Step11/SimpleTest/cmake/SimpleTestConfig.cmake b/Help/guide/tutorial/Step11/SimpleTest/cmake/SimpleTestConfig.cmake new file mode 100644 index 0000000..6c7ffb5 --- /dev/null +++ b/Help/guide/tutorial/Step11/SimpleTest/cmake/SimpleTestConfig.cmake
@@ -0,0 +1,5 @@ +include(CMakeFindDependencyMacro) +find_dependency(TransitiveDep) + +include(${CMAKE_CURRENT_LIST_DIR}/SimpleTestTargets.cmake) +include(${CMAKE_CURRENT_LIST_DIR}/simpletest_discover_tests.cmake)
diff --git a/Help/guide/tutorial/Step11/SimpleTest/cmake/simpletest_discover_impl.cmake b/Help/guide/tutorial/Step11/SimpleTest/cmake/simpletest_discover_impl.cmake new file mode 100644 index 0000000..7d3a22b --- /dev/null +++ b/Help/guide/tutorial/Step11/SimpleTest/cmake/simpletest_discover_impl.cmake
@@ -0,0 +1,32 @@ +if(NOT DEFINED TEST_EXE OR NOT DEFINED OUT_FILE) +# noqa: spellcheck off + message(FATAL_ERROR "simpletest_discover: need -DTEST_EXE and -DOUT_FILE") +# noqa: spellcheck on +endif() + +execute_process( + COMMAND ${TEST_EXE} --list + RESULT_VARIABLE _rc + OUTPUT_VARIABLE _out + ERROR_VARIABLE _err + OUTPUT_STRIP_TRAILING_WHITESPACE +) + +if(NOT _rc EQUAL 0) + file(WRITE ${OUT_FILE} "# simpletest: --list failed (rc=${_rc})\n") + message(FATAL_ERROR "simpletest_discover: '${TEST_EXE} --list' failed (${_rc})\n${_err}") +endif() + +if(_out STREQUAL "") + file(WRITE ${OUT_FILE} "# simpletest: no tests\n") + return() +endif() + +string(REPLACE "," ";" _names "${_out}") + +file(WRITE ${OUT_FILE} "# Auto-generated by simpletest_discover_impl.cmake\n") +foreach(_name IN LISTS _names) + file(APPEND ${OUT_FILE} + "add_test([=[${_name}]=] \"${TEST_EXE}\" \"--test\" \"${_name}\")\n" + ) +endforeach()
diff --git a/Help/guide/tutorial/Step11/SimpleTest/cmake/simpletest_discover_tests.cmake b/Help/guide/tutorial/Step11/SimpleTest/cmake/simpletest_discover_tests.cmake new file mode 100644 index 0000000..e5cf059 --- /dev/null +++ b/Help/guide/tutorial/Step11/SimpleTest/cmake/simpletest_discover_tests.cmake
@@ -0,0 +1,27 @@ +set(_simpletest_impl_script ${CMAKE_CURRENT_LIST_DIR}/simpletest_discover_impl.cmake) + +function(simpletest_discover_tests target) + if(NOT TARGET ${target}) + message(FATAL_ERROR "simpletest_discover_tests: no such target '${target}'") + endif() + + set(_out ${CMAKE_CURRENT_BINARY_DIR}/${target}_ctests.cmake) + + if(NOT EXISTS ${_out}) + file(WRITE ${_out} "# Populated after building ${target}\n") + endif() + +# noqa: spellcheck off + add_custom_command(TARGET ${target} POST_BUILD + COMMAND ${CMAKE_COMMAND} + -DTEST_EXE=$<TARGET_FILE:${target}> + -DOUT_FILE=${_out} + -P ${_simpletest_impl_script} + BYPRODUCTS ${_out} + COMMENT "SimpleTest: Discovering tests in ${target}" + VERBATIM + ) +# noqa: spellcheck on + + set_property(DIRECTORY APPEND PROPERTY TEST_INCLUDE_FILES ${_out}) +endfunction()
diff --git a/Help/guide/tutorial/Step11/TutorialConfig.h.in b/Help/guide/tutorial/Step11/TutorialConfig.h.in deleted file mode 100644 index 7e4d7fa..0000000 --- a/Help/guide/tutorial/Step11/TutorialConfig.h.in +++ /dev/null
@@ -1,3 +0,0 @@ -// the configured options and settings for Tutorial -#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ -#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@
diff --git a/Help/guide/tutorial/Step11/TutorialProject/CMakeLists.txt b/Help/guide/tutorial/Step11/TutorialProject/CMakeLists.txt new file mode 100644 index 0000000..4091638 --- /dev/null +++ b/Help/guide/tutorial/Step11/TutorialProject/CMakeLists.txt
@@ -0,0 +1,60 @@ +cmake_minimum_required(VERSION 3.23) + +project(Tutorial + VERSION 1.0.0 +) + +option(TUTORIAL_BUILD_UTILITIES "Build the Tutorial executable" ON) +option(TUTORIAL_USE_STD_SQRT "Use std::sqrt" OFF) +option(TUTORIAL_ENABLE_IPO "Check for and use IPO support" ON) +option(BUILD_TESTING "Enable testing and build tests" ON) + +if(TUTORIAL_ENABLE_IPO) + include(CheckIPOSupported) + check_ipo_supported(RESULT result OUTPUT output) + if(result) + message("IPO is supported, enabling IPO") + set(CMAKE_INTERPROCEDURAL_OPTIMIZATION ON) + else() + message(WARNING "IPO is not supported: ${output}") + endif() +endif() + +if(TUTORIAL_BUILD_UTILITIES) + add_subdirectory(Tutorial) +endif() + +if(BUILD_TESTING) + enable_testing() + add_subdirectory(Tests) +endif() + +add_subdirectory(MathFunctions) + +include(GNUInstallDirs) + +install( + TARGETS MathFunctions OpAdd OpMul OpSub MathLogger SqrtTable + EXPORT TutorialTargets + FILE_SET HEADERS +) + +install( + EXPORT TutorialTargets + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/Tutorial + NAMESPACE Tutorial:: +) + +include(CMakePackageConfigHelpers) + +write_basic_package_version_file( + ${CMAKE_CURRENT_BINARY_DIR}/TutorialConfigVersion.cmake + COMPATIBILITY ExactVersion +) + +install( + FILES + cmake/TutorialConfig.cmake + ${CMAKE_CURRENT_BINARY_DIR}/TutorialConfigVersion.cmake + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/Tutorial +)
diff --git a/Help/guide/tutorial/Step11/TutorialProject/CMakePresets.json b/Help/guide/tutorial/Step11/TutorialProject/CMakePresets.json new file mode 100644 index 0000000..fee177b --- /dev/null +++ b/Help/guide/tutorial/Step11/TutorialProject/CMakePresets.json
@@ -0,0 +1,16 @@ +{ + "version": 4, + "configurePresets": [ + { + "name": "tutorial", + "displayName": "Tutorial Preset", + "description": "Preset to use with the tutorial", + "binaryDir": "${sourceDir}/build", + "cacheVariables": { + "CMAKE_PREFIX_PATH": "${sourceParentDir}/install", + "TUTORIAL_USE_STD_SQRT": "OFF", + "TUTORIAL_ENABLE_IPO": "OFF" + } + } + ] +}
diff --git a/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/CMakeLists.txt new file mode 100644 index 0000000..c3ea012 --- /dev/null +++ b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/CMakeLists.txt
@@ -0,0 +1,55 @@ +add_library(MathFunctions) +# TODO1: Add an alias for the MathFunctions library to match the exported target + +target_sources(MathFunctions + PRIVATE + MathFunctions.cxx + + PUBLIC + FILE_SET HEADERS + FILES + MathFunctions.h +) + +target_link_libraries(MathFunctions + PRIVATE + MathLogger + SqrtTable + + PUBLIC + OpAdd + OpMul + OpSub +) + +target_compile_features(MathFunctions PRIVATE cxx_std_20) + +if(TUTORIAL_USE_STD_SQRT) + target_compile_definitions(MathFunctions PRIVATE TUTORIAL_USE_STD_SQRT) +endif() + +include(CheckIncludeFiles) +check_include_files(emmintrin.h HAS_EMMINTRIN LANGUAGE CXX) + +if(HAS_EMMINTRIN) + target_compile_definitions(MathFunctions PRIVATE TUTORIAL_USE_SSE2) +endif() + +include(CheckSourceCompiles) +check_source_compiles(CXX + [=[ + typedef double v2df __attribute__((vector_size(16))); + int main() { + __builtin_ia32_sqrtsd(v2df{}); + } + ]=] + HAS_GNU_BUILTIN +) + +if(HAS_GNU_BUILTIN) + target_compile_definitions(MathFunctions PRIVATE TUTORIAL_USE_GNU_BUILTIN) +endif() + +add_subdirectory(MathLogger) +add_subdirectory(MathExtensions) +add_subdirectory(MakeTable)
diff --git a/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MakeTable/CMakeLists.txt b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MakeTable/CMakeLists.txt new file mode 100644 index 0000000..6aa2a32 --- /dev/null +++ b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MakeTable/CMakeLists.txt
@@ -0,0 +1,28 @@ +add_executable(MakeTable) + +target_sources(MakeTable + PRIVATE + MakeTable.cxx +) + +add_custom_command( + OUTPUT SqrtTable.h + COMMAND MakeTable SqrtTable.h + DEPENDS MakeTable + VERBATIM +) + +add_custom_target(RunMakeTable DEPENDS SqrtTable.h) + +add_library(SqrtTable INTERFACE) + +target_sources(SqrtTable + INTERFACE + FILE_SET HEADERS + BASE_DIRS + ${CMAKE_CURRENT_BINARY_DIR} + FILES + ${CMAKE_CURRENT_BINARY_DIR}/SqrtTable.h +) + +add_dependencies(SqrtTable RunMakeTable)
diff --git a/Help/guide/tutorial/Step11/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MakeTable/MakeTable.cxx similarity index 100% rename from Help/guide/tutorial/Step11/MathFunctions/MakeTable.cxx rename to Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MakeTable/MakeTable.cxx
diff --git a/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/CMakeLists.txt b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/CMakeLists.txt new file mode 100644 index 0000000..b113786 --- /dev/null +++ b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/CMakeLists.txt
@@ -0,0 +1,3 @@ +add_subdirectory(OpAdd) +add_subdirectory(OpMul) +add_subdirectory(OpSub)
diff --git a/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/OpAdd/CMakeLists.txt b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/OpAdd/CMakeLists.txt new file mode 100644 index 0000000..f35da81 --- /dev/null +++ b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/OpAdd/CMakeLists.txt
@@ -0,0 +1,11 @@ +add_library(OpAdd OBJECT) + +target_sources(OpAdd + PRIVATE + OpAdd.cxx + + INTERFACE + FILE_SET HEADERS + FILES + OpAdd.h +)
diff --git a/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/OpAdd/OpAdd.cxx b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/OpAdd/OpAdd.cxx new file mode 100644 index 0000000..ea11496 --- /dev/null +++ b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/OpAdd/OpAdd.cxx
@@ -0,0 +1,6 @@ +namespace mathfunctions { +double OpAdd(double a, double b) +{ + return a + b; +} +}
diff --git a/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/OpAdd/OpAdd.h b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/OpAdd/OpAdd.h new file mode 100644 index 0000000..9c9efc3 --- /dev/null +++ b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/OpAdd/OpAdd.h
@@ -0,0 +1,5 @@ +#pragma once + +namespace mathfunctions { +double OpAdd(double a, double b); +}
diff --git a/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/OpMul/CMakeLists.txt b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/OpMul/CMakeLists.txt new file mode 100644 index 0000000..f494fc6 --- /dev/null +++ b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/OpMul/CMakeLists.txt
@@ -0,0 +1,11 @@ +add_library(OpMul OBJECT) + +target_sources(OpMul + PRIVATE + OpMul.cxx + + INTERFACE + FILE_SET HEADERS + FILES + OpMul.h +)
diff --git a/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/OpMul/OpMul.cxx b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/OpMul/OpMul.cxx new file mode 100644 index 0000000..c8eb016 --- /dev/null +++ b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/OpMul/OpMul.cxx
@@ -0,0 +1,6 @@ +namespace mathfunctions { +double OpMul(double a, double b) +{ + return a * b; +} +}
diff --git a/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/OpMul/OpMul.h b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/OpMul/OpMul.h new file mode 100644 index 0000000..52b467b --- /dev/null +++ b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/OpMul/OpMul.h
@@ -0,0 +1,5 @@ +#pragma once + +namespace mathfunctions { +double OpMul(double a, double b); +}
diff --git a/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/OpSub/CMakeLists.txt b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/OpSub/CMakeLists.txt new file mode 100644 index 0000000..1a108fd --- /dev/null +++ b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/OpSub/CMakeLists.txt
@@ -0,0 +1,11 @@ +add_library(OpSub OBJECT) + +target_sources(OpSub + PRIVATE + OpSub.cxx + + INTERFACE + FILE_SET HEADERS + FILES + OpSub.h +)
diff --git a/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/OpSub/OpSub.cxx b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/OpSub/OpSub.cxx new file mode 100644 index 0000000..b7b35da --- /dev/null +++ b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/OpSub/OpSub.cxx
@@ -0,0 +1,6 @@ +namespace mathfunctions { +double OpSub(double a, double b) +{ + return a - b; +} +}
diff --git a/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/OpSub/OpSub.h b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/OpSub/OpSub.h new file mode 100644 index 0000000..1406733 --- /dev/null +++ b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathExtensions/OpSub/OpSub.h
@@ -0,0 +1,5 @@ +#pragma once + +namespace mathfunctions { +double OpSub(double a, double b); +}
diff --git a/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000..4bf8051 --- /dev/null +++ b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathFunctions.cxx
@@ -0,0 +1,101 @@ +#include <cmath> +#include <format> + +#include <MathLogger.h> + +#ifdef TUTORIAL_USE_SSE2 +# include <emmintrin.h> +#endif + +namespace { + +mathlogger::Logger Logger; + +#if defined(TUTORIAL_USE_GNU_BUILTIN) +typedef double v2df __attribute__((vector_size(16))); + +double gnu_mysqrt(double x) +{ + v2df root = __builtin_ia32_sqrtsd(v2df{ x, 0.0 }); + double result = root[0]; + Logger.Log(std::format("Computed sqrt of {} to be {} with GNU-builtins\n", x, + result)); + return result; +} +#elif defined(TUTORIAL_USE_SSE2) +double sse2_mysqrt(double x) +{ + __m128d root = _mm_sqrt_sd(_mm_setzero_pd(), _mm_set_sd(x)); + double result = _mm_cvtsd_f64(root); + Logger.Log( + std::format("Computed sqrt of {} to be {} with SSE2\n", x, result)); + return result; +} +#endif + +// a hack square root calculation using simple operations +double fallback_mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + double result = x; + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + + Logger.Log(std::format("Computing sqrt of {} to be {}\n", x, result)); + } + return result; +} + +#include <SqrtTable.h> + +double table_sqrt(double x) +{ + double result = sqrtTable[static_cast<int>(x)]; + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + } + Logger.Log( + std::format("Computed sqrt of {} to be {} with TableSqrt\n", x, result)); + return result; +} + +double mysqrt(double x) +{ + if (x >= 1 && x < 10) { + return table_sqrt(x); + } + +#if defined(TUTORIAL_USE_GNU_BUILTIN) + return gnu_mysqrt(x); +#elif defined(TUTORIAL_USE_SSE2) + return sse2_mysqrt(x); +#else + return fallback_mysqrt(x); +#endif +} +} + +namespace mathfunctions { +double sqrt(double x) +{ +#ifdef TUTORIAL_USE_STD_SQRT + return std::sqrt(x); +#else + return mysqrt(x); +#endif +} +}
diff --git a/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathFunctions.h new file mode 100644 index 0000000..91cb176 --- /dev/null +++ b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathFunctions.h
@@ -0,0 +1,9 @@ +#pragma once + +#include <OpAdd.h> +#include <OpMul.h> +#include <OpSub.h> + +namespace mathfunctions { +double sqrt(double x); +}
diff --git a/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathLogger/CMakeLists.txt b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathLogger/CMakeLists.txt new file mode 100644 index 0000000..b20151f --- /dev/null +++ b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathLogger/CMakeLists.txt
@@ -0,0 +1,6 @@ +add_library(MathLogger INTERFACE) + +target_sources(MathLogger + INTERFACE + FILE_SET HEADERS +)
diff --git a/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathLogger/MathFormatting.h b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathLogger/MathFormatting.h new file mode 100644 index 0000000..3b6d61c --- /dev/null +++ b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathLogger/MathFormatting.h
@@ -0,0 +1,27 @@ +#pragma once + +#include <string> + +namespace mathlogger { + +enum LogLevel +{ + INFO, + WARN, + ERROR, +}; + +inline std::string FormatLog(LogLevel level, std::string const& message) +{ + switch (level) { + case INFO: + return "INFO: " + message; + case WARN: + return "WARN: " + message; + case ERROR: + return "ERROR: " + message; + } + return "UNKNOWN: " + message; +} + +}
diff --git a/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathLogger/MathLogger.h b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathLogger/MathLogger.h new file mode 100644 index 0000000..ef7b31a --- /dev/null +++ b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathLogger/MathLogger.h
@@ -0,0 +1,22 @@ +#pragma once + +#include <string> + +#include "MathFormatting.h" +#include "MathOutput.h" + +namespace mathlogger { + +struct Logger +{ + LogLevel level = INFO; + + void SetLevel(LogLevel new_level) { level = new_level; } + void Log(std::string const& message) + { + std::string formatted = FormatLog(level, message); + WriteLog(formatted); + } +}; + +}
diff --git a/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathLogger/MathOutput.h b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathLogger/MathOutput.h new file mode 100644 index 0000000..63f0aeb --- /dev/null +++ b/Help/guide/tutorial/Step11/TutorialProject/MathFunctions/MathLogger/MathOutput.h
@@ -0,0 +1,11 @@ +#pragma once + +#include <iostream> +#include <string> + +namespace mathlogger { +inline void WriteLog(std::string const& msg) +{ + std::cout << msg; +} +}
diff --git a/Help/guide/tutorial/Step11/TutorialProject/Tests/CMakeLists.txt b/Help/guide/tutorial/Step11/TutorialProject/Tests/CMakeLists.txt new file mode 100644 index 0000000..9b5bcd1 --- /dev/null +++ b/Help/guide/tutorial/Step11/TutorialProject/Tests/CMakeLists.txt
@@ -0,0 +1,16 @@ +add_executable(TestMathFunctions) + +target_sources(TestMathFunctions + PRIVATE + TestMathFunctions.cxx +) + +find_package(SimpleTest REQUIRED) + +target_link_libraries(TestMathFunctions + PRIVATE + MathFunctions + SimpleTest::SimpleTest +) + +simpletest_discover_tests(TestMathFunctions)
diff --git a/Help/guide/tutorial/Step11/TutorialProject/Tests/TestMathFunctions.cxx b/Help/guide/tutorial/Step11/TutorialProject/Tests/TestMathFunctions.cxx new file mode 100644 index 0000000..166fd5d --- /dev/null +++ b/Help/guide/tutorial/Step11/TutorialProject/Tests/TestMathFunctions.cxx
@@ -0,0 +1,22 @@ +#include <MathFunctions.h> +#include <SimpleTest.h> + +TEST("add") +{ + REQUIRE(mathfunctions::OpAdd(2.0, 2.0) == 4.0); +} + +TEST("sub") +{ + REQUIRE(mathfunctions::OpSub(4.0, 2.0) == 2.0); +} + +TEST("mul") +{ + REQUIRE(mathfunctions::OpMul(5.0, 5.0) == 25.0); +} + +TEST("sqrt") +{ + REQUIRE(mathfunctions::sqrt(25.0) == 5.0); +}
diff --git a/Help/guide/tutorial/Step11/TutorialProject/Tutorial/CMakeLists.txt b/Help/guide/tutorial/Step11/TutorialProject/Tutorial/CMakeLists.txt new file mode 100644 index 0000000..79b232b --- /dev/null +++ b/Help/guide/tutorial/Step11/TutorialProject/Tutorial/CMakeLists.txt
@@ -0,0 +1,39 @@ +add_executable(Tutorial) + +target_sources(Tutorial + PRIVATE + Tutorial.cxx +) + +target_link_libraries(Tutorial + PRIVATE + MathFunctions +) + +target_compile_features(Tutorial PRIVATE cxx_std_20) + +if( + (CMAKE_CXX_COMPILER_ID STREQUAL "MSVC") OR + (CMAKE_CXX_COMPILER_FRONTEND_VARIANT STREQUAL "MSVC") +) + + target_compile_options(Tutorial PRIVATE /W3) + +elseif( + (CMAKE_CXX_COMPILER_ID STREQUAL "GNU") OR + (CMAKE_CXX_COMPILER_ID MATCHES "Clang") +) + + target_compile_options(Tutorial PRIVATE -Wall) + +endif() + +find_path(UnpackagedIncludeFolder Unpackaged.h REQUIRED + PATH_SUFFIXES + Unpackaged +) + +target_include_directories(Tutorial + PRIVATE + ${UnpackagedIncludeFolder} +)
diff --git a/Help/guide/tutorial/Step11/TutorialProject/Tutorial/Tutorial.cxx b/Help/guide/tutorial/Step11/TutorialProject/Tutorial/Tutorial.cxx new file mode 100644 index 0000000..ac133d4 --- /dev/null +++ b/Help/guide/tutorial/Step11/TutorialProject/Tutorial/Tutorial.cxx
@@ -0,0 +1,27 @@ +// A simple program that computes the square root of a number +#include <format> +#include <iostream> +#include <string> + +#include <MathFunctions.h> +#include <Unpackaged.h> + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + std::cout << std::format("Usage: {} number\n", argv[0]); + return 1; + } + + // convert input to double + double const inputValue = std::stod(argv[1]); + + // calculate square root + double const outputValue = mathfunctions::sqrt(inputValue); + std::cout << std::format("The square root of {} is {}\n", inputValue, + outputValue); + + double const checkValue = mathfunctions::OpMul(outputValue, outputValue); + std::cout << std::format("The square of {} is {}\n", outputValue, + checkValue); +}
diff --git a/Help/guide/tutorial/Step11/TutorialProject/cmake/TutorialConfig.cmake b/Help/guide/tutorial/Step11/TutorialProject/cmake/TutorialConfig.cmake new file mode 100644 index 0000000..d13caa4 --- /dev/null +++ b/Help/guide/tutorial/Step11/TutorialProject/cmake/TutorialConfig.cmake
@@ -0,0 +1 @@ +include(${CMAKE_CURRENT_LIST_DIR}/TutorialTargets.cmake)
diff --git a/Help/guide/tutorial/Step11/install/include/Unpackaged/Unpackaged.h b/Help/guide/tutorial/Step11/install/include/Unpackaged/Unpackaged.h new file mode 100644 index 0000000..9782b0a --- /dev/null +++ b/Help/guide/tutorial/Step11/install/include/Unpackaged/Unpackaged.h
@@ -0,0 +1,3 @@ +#pragma once + +#define UNPACKAGED_HEADER_FOUND
diff --git a/Help/guide/tutorial/Step11/install/lib/cmake/TransitiveDep/TransitiveDepConfig.cmake b/Help/guide/tutorial/Step11/install/lib/cmake/TransitiveDep/TransitiveDepConfig.cmake new file mode 100644 index 0000000..ef51145 --- /dev/null +++ b/Help/guide/tutorial/Step11/install/lib/cmake/TransitiveDep/TransitiveDepConfig.cmake
@@ -0,0 +1,50 @@ +# Abridged import written for the Tutorial + +if("${CMAKE_MAJOR_VERSION}.${CMAKE_MINOR_VERSION}" LESS 2.8) + message(FATAL_ERROR "CMake >= 3.0.0 required") +endif() +if(CMAKE_VERSION VERSION_LESS "3.0.0") + message(FATAL_ERROR "CMake >= 3.0.0 required") +endif() +cmake_policy(PUSH) +cmake_policy(VERSION 3.0.0...3.30) + +# Commands may need to know the format version. +set(CMAKE_IMPORT_FILE_VERSION 1) + +# Protect against multiple inclusion, which would fail when already imported targets are added once more. +set(_cmake_targets_defined "") +set(_cmake_targets_not_defined "") +set(_cmake_expected_targets "") +foreach(_cmake_expected_target IN ITEMS TransitiveDep::TransitiveDep) + list(APPEND _cmake_expected_targets "${_cmake_expected_target}") + if(TARGET "${_cmake_expected_target}") + list(APPEND _cmake_targets_defined "${_cmake_expected_target}") + else() + list(APPEND _cmake_targets_not_defined "${_cmake_expected_target}") + endif() +endforeach() +unset(_cmake_expected_target) +if(_cmake_targets_defined STREQUAL _cmake_expected_targets) + unset(_cmake_targets_defined) + unset(_cmake_targets_not_defined) + unset(_cmake_expected_targets) + unset(CMAKE_IMPORT_FILE_VERSION) + cmake_policy(POP) + return() +endif() +if(NOT _cmake_targets_defined STREQUAL "") + string(REPLACE ";" ", " _cmake_targets_defined_text "${_cmake_targets_defined}") + string(REPLACE ";" ", " _cmake_targets_not_defined_text "${_cmake_targets_not_defined}") + message(FATAL_ERROR "Some (but not all) targets in this export set were already defined.\nTargets Defined: ${_cmake_targets_defined_text}\nTargets not yet defined: ${_cmake_targets_not_defined_text}\n") +endif() +unset(_cmake_targets_defined) +unset(_cmake_targets_not_defined) +unset(_cmake_expected_targets) + +# Create imported target TransitiveDep::TransitiveDep +add_library(TransitiveDep::TransitiveDep INTERFACE IMPORTED) + +# Commands beyond this point should not need to know the version. +set(CMAKE_IMPORT_FILE_VERSION) +cmake_policy(POP)
diff --git a/Help/guide/tutorial/Step11/tutorial.cxx b/Help/guide/tutorial/Step11/tutorial.cxx deleted file mode 100644 index ca5110c..0000000 --- a/Help/guide/tutorial/Step11/tutorial.cxx +++ /dev/null
@@ -1,27 +0,0 @@ -// A simple program that computes the square root of a number -#include <iostream> -#include <sstream> -#include <string> - -#include "MathFunctions.h" -#include "TutorialConfig.h" - -int main(int argc, char* argv[]) -{ - if (argc < 2) { - // report version - std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." - << Tutorial_VERSION_MINOR << std::endl; - std::cout << "Usage: " << argv[0] << " number" << std::endl; - return 1; - } - - // convert input to double - double const inputValue = std::stod(argv[1]); - - double const outputValue = mathfunctions::sqrt(inputValue); - - std::cout << "The square root of " << inputValue << " is " << outputValue - << std::endl; - return 0; -}
diff --git a/Help/guide/tutorial/Step12/CMakeLists.txt b/Help/guide/tutorial/Step12/CMakeLists.txt deleted file mode 100644 index a84590f..0000000 --- a/Help/guide/tutorial/Step12/CMakeLists.txt +++ /dev/null
@@ -1,124 +0,0 @@ -cmake_minimum_required(VERSION 3.15) - -# set the project name and version -project(Tutorial VERSION 1.0) - -add_library(tutorial_compiler_flags INTERFACE) -target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) - -# add compiler warning flags just when building this project via -# the BUILD_INTERFACE genex -set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>") -set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") -target_compile_options(tutorial_compiler_flags INTERFACE - "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>" - "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" -) - -# control where the static and shared libraries are built so that on windows -# we don't need to tinker with the path to run the executable -set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") -set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") -set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}") - -option(BUILD_SHARED_LIBS "Build using shared libraries" ON) - -if(APPLE) - set(CMAKE_INSTALL_RPATH "@executable_path/../lib") -elseif(UNIX) - set(CMAKE_INSTALL_RPATH "$ORIGIN/../lib") -endif() - -# configure a header file to pass the version number only -configure_file(TutorialConfig.h.in TutorialConfig.h) - -# add the MathFunctions library -add_subdirectory(MathFunctions) - -# add the executable -add_executable(Tutorial tutorial.cxx) -target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags) - -# add the binary tree to the search path for include files -# so that we will find TutorialConfig.h -target_include_directories(Tutorial PUBLIC - "${PROJECT_BINARY_DIR}" - ) - -# add the install targets -install(TARGETS Tutorial DESTINATION bin) -install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" - DESTINATION include - ) - -# enable testing -enable_testing() - -# does the application run -add_test(NAME Runs COMMAND Tutorial 25) - -# does the usage message work? -add_test(NAME Usage COMMAND Tutorial) -set_tests_properties(Usage - PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" - ) - -# define a function to simplify adding tests -function(do_test target arg result) - add_test(NAME Comp${arg} COMMAND ${target} ${arg}) - set_tests_properties(Comp${arg} - PROPERTIES PASS_REGULAR_EXPRESSION ${result} - ) -endfunction() - -# do a bunch of result based tests -do_test(Tutorial 4 "4 is 2") -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 0.0001 "0.0001 is 0.01") - -# setup installer -include(InstallRequiredSystemLibraries) -set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") -set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") -set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") -set(CPACK_GENERATOR "TGZ") -set(CPACK_SOURCE_GENERATOR "TGZ") -include(CPack) - -# install the configuration targets -install(EXPORT MathFunctionsTargets - FILE MathFunctionsTargets.cmake - DESTINATION lib/cmake/MathFunctions -) - -include(CMakePackageConfigHelpers) -# generate the config file that includes the exports -configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in - "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake" - INSTALL_DESTINATION "lib/cmake/MathFunctions" - NO_SET_AND_CHECK_MACRO - NO_CHECK_REQUIRED_COMPONENTS_MACRO - ) -# generate the version file for the config file -write_basic_package_version_file( - "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake" - VERSION "${Tutorial_VERSION_MAJOR}.${Tutorial_VERSION_MINOR}" - COMPATIBILITY AnyNewerVersion -) - -# install the generated configuration files -install(FILES - ${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake - ${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake - DESTINATION lib/cmake/MathFunctions - ) - -# generate the export targets for the build tree -# needs to be after the install(TARGETS) command -export(EXPORT MathFunctionsTargets - FILE "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsTargets.cmake" -)
diff --git a/Help/guide/tutorial/Step12/CTestConfig.cmake b/Help/guide/tutorial/Step12/CTestConfig.cmake deleted file mode 100644 index b2922fe..0000000 --- a/Help/guide/tutorial/Step12/CTestConfig.cmake +++ /dev/null
@@ -1,3 +0,0 @@ -set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") - -set(CTEST_SUBMIT_URL "https://my.cdash.org/submit.php?project=CMakeTutorial")
diff --git a/Help/guide/tutorial/Step12/Config.cmake.in b/Help/guide/tutorial/Step12/Config.cmake.in deleted file mode 100644 index 17cbabd..0000000 --- a/Help/guide/tutorial/Step12/Config.cmake.in +++ /dev/null
@@ -1,4 +0,0 @@ - -@PACKAGE_INIT@ - -include ( "${CMAKE_CURRENT_LIST_DIR}/MathFunctionsTargets.cmake" )
diff --git a/Help/guide/tutorial/Step12/License.txt b/Help/guide/tutorial/Step12/License.txt deleted file mode 100644 index 85760e5..0000000 --- a/Help/guide/tutorial/Step12/License.txt +++ /dev/null
@@ -1,2 +0,0 @@ -This is the open source License.txt file introduced in -CMake/Tutorial/Step9...
diff --git a/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt deleted file mode 100644 index 8aa5904..0000000 --- a/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt +++ /dev/null
@@ -1,58 +0,0 @@ -# add the library that runs -add_library(MathFunctions MathFunctions.cxx) - -# state that anybody linking to us needs to include the current source dir -# to find MathFunctions.h, while we don't. -target_include_directories(MathFunctions - INTERFACE - $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}> - $<INSTALL_INTERFACE:include> - ) - -# should we use our own math functions -option(USE_MYMATH "Use tutorial provided math implementation" ON) -if(USE_MYMATH) - - target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") - - include(MakeTable.cmake) # generates Table.h - - # library that just does sqrt - add_library(SqrtLibrary STATIC - mysqrt.cxx - ${CMAKE_CURRENT_BINARY_DIR}/Table.h - ) - - # state that we depend on our binary dir to find Table.h - target_include_directories(SqrtLibrary PRIVATE - ${CMAKE_CURRENT_BINARY_DIR} - ) - - # state that SqrtLibrary need PIC when the default is shared libraries - set_target_properties(SqrtLibrary PROPERTIES - POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS} - ) - - # link SqrtLibrary to tutorial_compiler_flags - target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) - - target_link_libraries(MathFunctions PRIVATE SqrtLibrary) -endif() - -# link MathFunctions to tutorial_compiler_flags -target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) - -# define the symbol stating we are using the declspec(dllexport) when -# building on windows -target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH") - -# install libs -set(installable_libs MathFunctions tutorial_compiler_flags) -if(TARGET SqrtLibrary) - list(APPEND installable_libs SqrtLibrary) -endif() -install(TARGETS ${installable_libs} - EXPORT MathFunctionsTargets - DESTINATION lib) -# install include headers -install(FILES MathFunctions.h DESTINATION include)
diff --git a/Help/guide/tutorial/Step12/MathFunctions/MakeTable.cmake b/Help/guide/tutorial/Step12/MathFunctions/MakeTable.cmake deleted file mode 100644 index 12865a9..0000000 --- a/Help/guide/tutorial/Step12/MathFunctions/MakeTable.cmake +++ /dev/null
@@ -1,10 +0,0 @@ -# first we add the executable that generates the table -add_executable(MakeTable MakeTable.cxx) -target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags) - -# add the command to generate the source code -add_custom_command( - OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h - COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h - DEPENDS MakeTable - )
diff --git a/Help/guide/tutorial/Step12/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step12/MathFunctions/MakeTable.cxx deleted file mode 100644 index f85b278..0000000 --- a/Help/guide/tutorial/Step12/MathFunctions/MakeTable.cxx +++ /dev/null
@@ -1,25 +0,0 @@ -// A simple program that builds a sqrt table -#include <cmath> -#include <fstream> -#include <iostream> - -int main(int argc, char* argv[]) -{ - // make sure we have enough arguments - if (argc < 2) { - return 1; - } - - std::ofstream fout(argv[1], std::ios_base::out); - bool const fileOpen = fout.is_open(); - if (fileOpen) { - fout << "double sqrtTable[] = {" << std::endl; - for (int i = 0; i < 10; ++i) { - fout << sqrt(static_cast<double>(i)) << "," << std::endl; - } - // close the table with a zero - fout << "0};" << std::endl; - fout.close(); - } - return fileOpen ? 0 : 1; // return 0 if wrote the file -}
diff --git a/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.cxx deleted file mode 100644 index c0991b9..0000000 --- a/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.cxx +++ /dev/null
@@ -1,20 +0,0 @@ - -#include "MathFunctions.h" - -#include <cmath> - -#ifdef USE_MYMATH -# include "mysqrt.h" -#endif - -namespace mathfunctions { -double sqrt(double x) -{ -// which square root function should we use? -#ifdef USE_MYMATH - return detail::mysqrt(x); -#else - return std::sqrt(x); -#endif -} -}
diff --git a/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.h deleted file mode 100644 index 3fb547b..0000000 --- a/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.h +++ /dev/null
@@ -1,14 +0,0 @@ - -#if defined(_WIN32) -# if defined(EXPORTING_MYMATH) -# define DECLSPEC __declspec(dllexport) -# else -# define DECLSPEC __declspec(dllimport) -# endif -#else // non windows -# define DECLSPEC -#endif - -namespace mathfunctions { -double DECLSPEC sqrt(double x); -}
diff --git a/Help/guide/tutorial/Step12/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step12/MathFunctions/mysqrt.cxx deleted file mode 100644 index 8153f18..0000000 --- a/Help/guide/tutorial/Step12/MathFunctions/mysqrt.cxx +++ /dev/null
@@ -1,37 +0,0 @@ -#include <iostream> - -#include "MathFunctions.h" - -// include the generated table -#include "Table.h" - -namespace mathfunctions { -namespace detail { -// a hack square root calculation using simple operations -double mysqrt(double x) -{ - if (x <= 0) { - return 0; - } - - // use the table to help find an initial value - double result = x; - if (x >= 1 && x < 10) { - std::cout << "Use the table to help find an initial value " << std::endl; - result = sqrtTable[static_cast<int>(x)]; - } - - // do ten iterations - for (int i = 0; i < 10; ++i) { - if (result <= 0) { - result = 0.1; - } - double delta = x - (result * result); - result = result + 0.5 * delta / result; - std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; - } - - return result; -} -} -}
diff --git a/Help/guide/tutorial/Step12/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step12/MathFunctions/mysqrt.h deleted file mode 100644 index e1c42ef..0000000 --- a/Help/guide/tutorial/Step12/MathFunctions/mysqrt.h +++ /dev/null
@@ -1,6 +0,0 @@ - -namespace mathfunctions { -namespace detail { -double mysqrt(double x); -} -}
diff --git a/Help/guide/tutorial/Step12/TutorialConfig.h.in b/Help/guide/tutorial/Step12/TutorialConfig.h.in deleted file mode 100644 index 7e4d7fa..0000000 --- a/Help/guide/tutorial/Step12/TutorialConfig.h.in +++ /dev/null
@@ -1,3 +0,0 @@ -// the configured options and settings for Tutorial -#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ -#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@
diff --git a/Help/guide/tutorial/Step12/tutorial.cxx b/Help/guide/tutorial/Step12/tutorial.cxx deleted file mode 100644 index 78641b1..0000000 --- a/Help/guide/tutorial/Step12/tutorial.cxx +++ /dev/null
@@ -1,26 +0,0 @@ -// A simple program that computes the square root of a number -#include <iostream> -#include <string> - -#include "MathFunctions.h" -#include "TutorialConfig.h" - -int main(int argc, char* argv[]) -{ - if (argc < 2) { - // report version - std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." - << Tutorial_VERSION_MINOR << std::endl; - std::cout << "Usage: " << argv[0] << " number" << std::endl; - return 1; - } - - // convert input to double - double const inputValue = std::stod(argv[1]); - - double const outputValue = mathfunctions::sqrt(inputValue); - - std::cout << "The square root of " << inputValue << " is " << outputValue - << std::endl; - return 0; -}
diff --git a/Help/guide/tutorial/Step2/CMakeLists.txt b/Help/guide/tutorial/Step2/CMakeLists.txt deleted file mode 100644 index 0a06ed7..0000000 --- a/Help/guide/tutorial/Step2/CMakeLists.txt +++ /dev/null
@@ -1,28 +0,0 @@ -cmake_minimum_required(VERSION 3.10) - -# set the project name and version -project(Tutorial VERSION 1.0) - -# specify the C++ standard -set(CMAKE_CXX_STANDARD 11) -set(CMAKE_CXX_STANDARD_REQUIRED True) - -# configure a header file to pass some of the CMake settings -# to the source code -configure_file(TutorialConfig.h.in TutorialConfig.h) - -# TODO 2: Use add_subdirectory() to add MathFunctions to this project - -# add the executable -add_executable(Tutorial tutorial.cxx) - -# TODO 3: Use target_link_libraries to link the library to our executable - -# TODO 4: Add MathFunctions to Tutorial's target_include_directories() -# Hint: ${PROJECT_SOURCE_DIR} is a path to the project source. AKA This folder! - -# 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}" - )
diff --git a/Help/guide/tutorial/Step2/Exercise1.cmake b/Help/guide/tutorial/Step2/Exercise1.cmake new file mode 100644 index 0000000..3816de6 --- /dev/null +++ b/Help/guide/tutorial/Step2/Exercise1.cmake
@@ -0,0 +1,72 @@ +cmake_minimum_required(VERSION 3.23) + + +# TODO1: Implement MacroAppend +macro(MacroAppend ListVar Value) + +endmacro() + +# TODO2: Call MacroAppend, then return the value from FuncAppend +function(FuncAppend ListVar Value) + +endfunction() + + + +# Testing for the above, final expected value is "Alpha;Beta;Gamma;Delta" +if(SKIP_TESTS) + return() +endif() + +set(Original "Beta;Gamma") +set(Expected "Alpha;Beta;Gamma;Delta") + +set(BeginList ${Original}) +set(EndList "Alpha") + +MacroAppend(BeginList "Delta") +foreach(value IN LISTS BeginList) + MacroAppend(EndList ${value}) +endforeach() + +if(BeginList STREQUAL Original) + message("MacroAppend unimplemented or did nothing") +elseif(NOT EndList STREQUAL Expected) + message(WARNING "MacroAppend error, final value: ${EndList}") +else() + message("MacroAppend correct") +endif() + +set(BeginList ${Original}) +set(EndList "Alpha") + +FuncAppend(BeginList "Delta") +foreach(value IN LISTS BeginList) + FuncAppend(EndList ${value}) +endforeach() + +if(BeginList STREQUAL Original) + message("FuncAppend unimplemented or did nothing") +elseif(NOT EndList STREQUAL Expected) + message(WARNING "FuncAppend error, final value: ${EndList}") +else() + message("FuncAppend correct") +endif() + +# Bonus Tests + +FuncAppend(UndefinedList "Test") + +set(EmptyList "") +FuncAppend(EmptyList "Test") + +set(FalseList "False") +FuncAppend(FalseList "Test") + +if( + (UndefinedList STREQUAL "Test") AND + (EmptyList STREQUAL "Test") AND + (FalseList STREQUAL "False;Test") +) + message("You implemented the empty list case, well done!") +endif()
diff --git a/Help/guide/tutorial/Step2/Exercise2.cmake b/Help/guide/tutorial/Step2/Exercise2.cmake new file mode 100644 index 0000000..ee4e9e8 --- /dev/null +++ b/Help/guide/tutorial/Step2/Exercise2.cmake
@@ -0,0 +1,51 @@ +cmake_minimum_required(VERSION 3.23) + + +function(FilterFoo OutVar) +# TODO3: Search all the variables in the argument list passed to FilterFoo, +# and place those containing "Foo" into the list named by "OutVar" + + set(${OutVar} ${${OutVar}} PARENT_SCOPE) +endfunction() + + + +# Testing for the above +function(check_contains var) + if(NOT var IN_LIST OutList) + message(WARNING "OutList does not contain: ${var}") + set(Failed True PARENT_SCOPE) + endif() +endfunction() + +function(check_nonfoo) + list(FILTER ARGN EXCLUDE REGEX Foo) + if(NOT ARGN STREQUAL "") + message(WARNING "OutList contains extra item(s): ${ARGN}") + set(Failed True PARENT_SCOPE) + endif() +endfunction() + +if(SKIP_TESTS) + return() +endif() + +set(InList FooBar BarBaz FooBaz BazBar QuxFoo BazQux) + +FilterFoo(OutList ${InList}) + +if(NOT DEFINED OutList) + message("FilterFoo unimplemented or does nothing") + return() +endif() + +set(Failed False) + +check_contains(FooBar) +check_contains(FooBaz) +check_contains(QuxFoo) +check_nonfoo(${OutList}) + +if(NOT Failed) + message("Success!") +endif()
diff --git a/Help/guide/tutorial/Step2/Exercise3.cmake b/Help/guide/tutorial/Step2/Exercise3.cmake new file mode 100644 index 0000000..439aa25 --- /dev/null +++ b/Help/guide/tutorial/Step2/Exercise3.cmake
@@ -0,0 +1,30 @@ +cmake_minimum_required(VERSION 3.23) + + +# TODO4: Set the SKIP_TESTS variable to a true value, so that the tests from +# Exercise1 and Exercise2 are skipped + + +# TODO5: Include Exercise1.cmake and Exercise2.cmake + + +set(InList FooBar QuxBar) + +# TODO6: Append FooBaz and QuxBaz to InList with FuncAppend + + +if(NOT InList STREQUAL "FooBar;QuxBar;FooBaz;QuxBaz") + message(WARNING "Append failed, InList contains: ${InList}") +endif() + + +# TODO7: Filter InList with FilterFoo, use OutList as the output variable + + +check_contains(FooBar) +check_contains(FooBaz) +check_nonfoo(${OutList}) + +if(NOT Failed) + message("Success!") +endif()
diff --git a/Help/guide/tutorial/Step2/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step2/MathFunctions/CMakeLists.txt deleted file mode 100644 index c3cd806..0000000 --- a/Help/guide/tutorial/Step2/MathFunctions/CMakeLists.txt +++ /dev/null
@@ -1,15 +0,0 @@ -# TODO 14: Remove mysqrt.cxx from the list of sources - -# TODO 1: Add a library called MathFunctions with sources MathFunctions.cxx -# and mysqrt.cxx -# Hint: You will need the add_library command - -# TODO 7: Create a variable USE_MYMATH using option and set default to ON - -# TODO 8: If USE_MYMATH is ON, use target_compile_definitions to pass -# USE_MYMATH as a precompiled definition to our source files - -# TODO 12: When USE_MYMATH is ON, add a library for SqrtLibrary with -# source mysqrt.cxx - -# TODO 13: When USE_MYMATH is ON, link SqrtLibrary to the MathFunctions Library
diff --git a/Help/guide/tutorial/Step2/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step2/MathFunctions/MathFunctions.cxx deleted file mode 100644 index 781d0ec..0000000 --- a/Help/guide/tutorial/Step2/MathFunctions/MathFunctions.cxx +++ /dev/null
@@ -1,15 +0,0 @@ -#include "MathFunctions.h" - -// TODO 11: include cmath - -// TODO 10: Wrap the mysqrt include in a precompiled ifdef based on USE_MYMATH -#include "mysqrt.h" - -namespace mathfunctions { -double sqrt(double x) -{ - // TODO 9: If USE_MYMATH is defined, use detail::mysqrt. - // Otherwise, use std::sqrt. - return detail::mysqrt(x); -} -}
diff --git a/Help/guide/tutorial/Step2/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step2/MathFunctions/mysqrt.cxx deleted file mode 100644 index ba0ac64..0000000 --- a/Help/guide/tutorial/Step2/MathFunctions/mysqrt.cxx +++ /dev/null
@@ -1,28 +0,0 @@ -#include "mysqrt.h" - -#include <iostream> - -namespace mathfunctions { -namespace detail { -// a hack square root calculation using simple operations -double mysqrt(double x) -{ - if (x <= 0) { - return 0; - } - - double result = x; - - // do ten iterations - for (int i = 0; i < 10; ++i) { - if (result <= 0) { - result = 0.1; - } - double delta = x - (result * result); - result = result + 0.5 * delta / result; - std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; - } - return result; -} -} -}
diff --git a/Help/guide/tutorial/Step2/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step2/MathFunctions/mysqrt.h deleted file mode 100644 index 593d41e..0000000 --- a/Help/guide/tutorial/Step2/MathFunctions/mysqrt.h +++ /dev/null
@@ -1,7 +0,0 @@ -#pragma once - -namespace mathfunctions { -namespace detail { -double mysqrt(double x); -} -}
diff --git a/Help/guide/tutorial/Step2/TutorialConfig.h.in b/Help/guide/tutorial/Step2/TutorialConfig.h.in deleted file mode 100644 index 7e4d7fa..0000000 --- a/Help/guide/tutorial/Step2/TutorialConfig.h.in +++ /dev/null
@@ -1,3 +0,0 @@ -// the configured options and settings for Tutorial -#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ -#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@
diff --git a/Help/guide/tutorial/Step2/tutorial.cxx b/Help/guide/tutorial/Step2/tutorial.cxx deleted file mode 100644 index b4063c8..0000000 --- a/Help/guide/tutorial/Step2/tutorial.cxx +++ /dev/null
@@ -1,29 +0,0 @@ -// A simple program that computes the square root of a number -#include <cmath> -#include <iostream> -#include <string> - -// TODO 5: Include MathFunctions.h -#include "TutorialConfig.h" - -int main(int argc, char* argv[]) -{ - if (argc < 2) { - // report version - std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." - << Tutorial_VERSION_MINOR << std::endl; - std::cout << "Usage: " << argv[0] << " number" << std::endl; - return 1; - } - - // convert input to double - double const inputValue = std::stod(argv[1]); - - // TODO 6: Replace sqrt with mathfunctions::sqrt - - // calculate square root - double const outputValue = sqrt(inputValue); - std::cout << "The square root of " << inputValue << " is " << outputValue - << std::endl; - return 0; -}
diff --git a/Help/guide/tutorial/Step3/CMakeLists.txt b/Help/guide/tutorial/Step3/CMakeLists.txt index ac3e9f1..916ad08 100644 --- a/Help/guide/tutorial/Step3/CMakeLists.txt +++ b/Help/guide/tutorial/Step3/CMakeLists.txt
@@ -1,40 +1,18 @@ -cmake_minimum_required(VERSION 3.10) +cmake_minimum_required(VERSION 3.23) -# set the project name and version -project(Tutorial VERSION 1.0) +project(Tutorial) -# TODO 4: Replace the following code by: -# * Creating an interface library called tutorial_compiler_flags -# Hint: use add_library() with the INTERFACE signature -# * Add compiler feature cxx_std_11 to tutorial_compiler_flags -# Hint: Use target_compile_features() +# TODO1: Add a default ON option for a cache variable named: +# TUTORIAL_BUILD_UTILITIES. +# option() requires a doc string as its second argument, set this to +# something like: +# "Build the Tutorial executable" -# specify the C++ standard -set(CMAKE_CXX_STANDARD 11) -set(CMAKE_CXX_STANDARD_REQUIRED True) -# configure a header file to pass some of the CMake settings -# to the source code -configure_file(TutorialConfig.h.in TutorialConfig.h) +# TODO2: Add a conditional statement around add_subdirectory(Tutorial). Only +# build the Tutorial target if TUTORIAL_BUILD_UTILITIES is ON (or +# otherwise truthy). -# TODO 2: Remove EXTRA_INCLUDES list +add_subdirectory(Tutorial) -# add the MathFunctions library add_subdirectory(MathFunctions) -list(APPEND EXTRA_INCLUDES "${PROJECT_SOURCE_DIR}/MathFunctions") - -# add the executable -add_executable(Tutorial tutorial.cxx) - -# TODO 5: Link Tutorial to tutorial_compiler_flags - -target_link_libraries(Tutorial PUBLIC MathFunctions) - -# TODO 3: Remove use of EXTRA_INCLUDES - -# 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}" - ${EXTRA_INCLUDES} - )
diff --git a/Help/guide/tutorial/Step3/CMakePresets.json b/Help/guide/tutorial/Step3/CMakePresets.json new file mode 100644 index 0000000..33f5968 --- /dev/null +++ b/Help/guide/tutorial/Step3/CMakePresets.json
@@ -0,0 +1,14 @@ +{ + "version": 4, + "configurePresets": [ + { + "name": "tutorial", + "displayName": "Tutorial Preset", + "description": "Preset to use with the tutorial", + "TODO8": "Set the build directory", + "cacheVariables": { + "TODO9": "Set the C++ standard version" + } + } + ] +}
diff --git a/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt index 74c553f..dbc7f95 100644 --- a/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt
@@ -1,22 +1,11 @@ -add_library(MathFunctions MathFunctions.cxx) +add_library(MathFunctions) -# TODO 1: State that anybody linking to MathFunctions needs to include the -# current source directory, while MathFunctions itself doesn't. -# Hint: Use target_include_directories with the INTERFACE keyword +target_sources(MathFunctions + PRIVATE + MathFunctions.cxx -# should we use our own math functions -option(USE_MYMATH "Use tutorial provided math implementation" ON) -if (USE_MYMATH) - target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") - - # library that just does sqrt - add_library(SqrtLibrary STATIC - mysqrt.cxx - ) - - # TODO 6: Link SqrtLibrary to tutorial_compiler_flags - - target_link_libraries(MathFunctions PRIVATE SqrtLibrary) -endif() - -# TODO 7: Link MathFunctions to tutorial_compiler_flags + PUBLIC + FILE_SET HEADERS + FILES + MathFunctions.h +)
diff --git a/Help/guide/tutorial/Step3/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step3/MathFunctions/MathFunctions.cxx index dc28b4b..5f519b4 100644 --- a/Help/guide/tutorial/Step3/MathFunctions/MathFunctions.cxx +++ b/Help/guide/tutorial/Step3/MathFunctions/MathFunctions.cxx
@@ -1,19 +1,35 @@ -#include "MathFunctions.h" +#include <iostream> -#include <cmath> +// TODO6: Include <format> -#ifdef USE_MYMATH -# include "mysqrt.h" -#endif +namespace { +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + double result = x; + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + + // TODO7: Convert the print to use std::format + std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; + } + return result; +} +} namespace mathfunctions { double sqrt(double x) { -// which square root function should we use? -#ifdef USE_MYMATH - return detail::mysqrt(x); -#else - return std::sqrt(x); -#endif + return mysqrt(x); } }
diff --git a/Help/guide/tutorial/Step3/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step3/MathFunctions/mysqrt.cxx deleted file mode 100644 index ba0ac64..0000000 --- a/Help/guide/tutorial/Step3/MathFunctions/mysqrt.cxx +++ /dev/null
@@ -1,28 +0,0 @@ -#include "mysqrt.h" - -#include <iostream> - -namespace mathfunctions { -namespace detail { -// a hack square root calculation using simple operations -double mysqrt(double x) -{ - if (x <= 0) { - return 0; - } - - double result = x; - - // do ten iterations - for (int i = 0; i < 10; ++i) { - if (result <= 0) { - result = 0.1; - } - double delta = x - (result * result); - result = result + 0.5 * delta / result; - std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; - } - return result; -} -} -}
diff --git a/Help/guide/tutorial/Step3/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step3/MathFunctions/mysqrt.h deleted file mode 100644 index 593d41e..0000000 --- a/Help/guide/tutorial/Step3/MathFunctions/mysqrt.h +++ /dev/null
@@ -1,7 +0,0 @@ -#pragma once - -namespace mathfunctions { -namespace detail { -double mysqrt(double x); -} -}
diff --git a/Help/guide/tutorial/Step3/Tutorial/CMakeLists.txt b/Help/guide/tutorial/Step3/Tutorial/CMakeLists.txt new file mode 100644 index 0000000..0dc1f58 --- /dev/null +++ b/Help/guide/tutorial/Step3/Tutorial/CMakeLists.txt
@@ -0,0 +1,11 @@ +add_executable(Tutorial) + +target_sources(Tutorial + PRIVATE + Tutorial.cxx +) + +target_link_libraries(Tutorial + PRIVATE + MathFunctions +)
diff --git a/Help/guide/tutorial/Step3/Tutorial/Tutorial.cxx b/Help/guide/tutorial/Step3/Tutorial/Tutorial.cxx new file mode 100644 index 0000000..c630f30 --- /dev/null +++ b/Help/guide/tutorial/Step3/Tutorial/Tutorial.cxx
@@ -0,0 +1,26 @@ +// A simple program that computes the square root of a number + +// TODO3: Include <format> + +#include <iostream> +#include <string> + +#include <MathFunctions.h> + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + // TODO4: Convert the print to use std::format + std::cout << "Usage: " << argv[0] << " number" << std::endl; + return 1; + } + + // convert input to double + double const inputValue = std::stod(argv[1]); + + // calculate square root + double const outputValue = mathfunctions::sqrt(inputValue); + // TODO5: Convert the print to use std::format + std::cout << "The square root of " << inputValue << " is " << outputValue + << std::endl; +}
diff --git a/Help/guide/tutorial/Step3/TutorialConfig.h.in b/Help/guide/tutorial/Step3/TutorialConfig.h.in deleted file mode 100644 index 7e4d7fa..0000000 --- a/Help/guide/tutorial/Step3/TutorialConfig.h.in +++ /dev/null
@@ -1,3 +0,0 @@ -// the configured options and settings for Tutorial -#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ -#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@
diff --git a/Help/guide/tutorial/Step3/tutorial.cxx b/Help/guide/tutorial/Step3/tutorial.cxx deleted file mode 100644 index 48be3c6..0000000 --- a/Help/guide/tutorial/Step3/tutorial.cxx +++ /dev/null
@@ -1,27 +0,0 @@ -// A simple program that computes the square root of a number -#include <cmath> -#include <iostream> -#include <string> - -#include "MathFunctions.h" -#include "TutorialConfig.h" - -int main(int argc, char* argv[]) -{ - if (argc < 2) { - // report version - std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." - << Tutorial_VERSION_MINOR << std::endl; - std::cout << "Usage: " << argv[0] << " number" << std::endl; - return 1; - } - - // convert input to double - double const inputValue = std::stod(argv[1]); - - double const outputValue = mathfunctions::sqrt(inputValue); - - std::cout << "The square root of " << inputValue << " is " << outputValue - << std::endl; - return 0; -}
diff --git a/Help/guide/tutorial/Step4/CMakeLists.txt b/Help/guide/tutorial/Step4/CMakeLists.txt index fba9766..7d09051 100644 --- a/Help/guide/tutorial/Step4/CMakeLists.txt +++ b/Help/guide/tutorial/Step4/CMakeLists.txt
@@ -1,44 +1,15 @@ -# TODO 1: Update the minimum required version to 3.15 +cmake_minimum_required(VERSION 3.23) -cmake_minimum_required(VERSION 3.10) +project(Tutorial) -# set the project name and version -project(Tutorial VERSION 1.0) +option(TUTORIAL_BUILD_UTILITIES "Build the Tutorial executable" ON) -# specify the C++ standard -add_library(tutorial_compiler_flags INTERFACE) -target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) +# TODO1: Add a default-OFF option named TUTORIAL_USE_STD_SQRT, with a doc +# string of "Use std::sqrt" -# TODO 2: Create helper variables to determine which compiler we are using: -# * Create a new variable gcc_like_cxx that is true if we are using CXX and -# any of the following compilers: ARMClang, AppleClang, Clang, GNU, LCC -# * Create a new variable msvc_cxx that is true if we are using CXX and MSVC -# Hint: Use set() and COMPILE_LANG_AND_ID +if(TUTORIAL_BUILD_UTILITIES) + add_subdirectory(Tutorial) +endif() -# TODO 3: Add warning flag compile options to the interface library -# tutorial_compiler_flags. -# * For gcc_like_cxx, add flags -Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused -# * For msvc_cxx, add flags -W3 -# Hint: Use target_compile_options() - -# TODO 4: With nested generator expressions, only use the flags for the -# build-tree -# Hint: Use BUILD_INTERFACE - -# configure a header file to pass some of the CMake settings -# to the source code -configure_file(TutorialConfig.h.in TutorialConfig.h) - -# add the MathFunctions library add_subdirectory(MathFunctions) - -# add the executable -add_executable(Tutorial tutorial.cxx) - -target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags) - -# add the binary tree to the search path for include files -# so that we will find TutorialConfig.h -target_include_directories(Tutorial PUBLIC - "${PROJECT_BINARY_DIR}" - ) +add_subdirectory(Vendor)
diff --git a/Help/guide/tutorial/Step4/CMakePresets.json b/Help/guide/tutorial/Step4/CMakePresets.json new file mode 100644 index 0000000..6c47447 --- /dev/null +++ b/Help/guide/tutorial/Step4/CMakePresets.json
@@ -0,0 +1,16 @@ +{ + "version": 4, + "configurePresets": [ + { + "name": "tutorial", + "displayName": "Tutorial Preset", + "description": "Preset to use with the tutorial", + "binaryDir": "${sourceDir}/build", + "cacheVariables": { + "TODO7": "Remove the CMAKE_CXX_STANDARD (and this TODO)", + "CMAKE_CXX_STANDARD": "20", + "TODO8": "Set TUTORIAL_USE_STD_SQRT to ON" + } + } + ] +}
diff --git a/Help/guide/tutorial/Step4/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step4/MathFunctions/CMakeLists.txt index 6931898..213aafb 100644 --- a/Help/guide/tutorial/Step4/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step4/MathFunctions/CMakeLists.txt
@@ -1,27 +1,16 @@ -# create the MathFunctions library -add_library(MathFunctions MathFunctions.cxx) +add_library(MathFunctions) -# state that anybody linking to us needs to include the current source dir -# to find MathFunctions.h, while we don't. -target_include_directories(MathFunctions - INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} - ) +target_sources(MathFunctions + PRIVATE + MathFunctions.cxx -# should we use our own math functions -option(USE_MYMATH "Use tutorial provided math implementation" ON) -if (USE_MYMATH) - target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") + PUBLIC + FILE_SET HEADERS + FILES + MathFunctions.h +) - # library that just does sqrt - add_library(SqrtLibrary STATIC - mysqrt.cxx - ) +# TODO2: Add a compile feature for C++20 support to MathFunctions - # link SqrtLibrary to tutorial_compiler_flags - target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) - - target_link_libraries(MathFunctions PRIVATE SqrtLibrary) -endif() - -# link MathFunctions to tutorial_compiler_flags -target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) +# TODO3: Add a conditional which checks TUTORIAL_USE_STD_SQRT and if +# ON, set a compile definition on MathFunctions of the same name
diff --git a/Help/guide/tutorial/Step4/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step4/MathFunctions/MathFunctions.cxx index dc28b4b..4635cc4 100644 --- a/Help/guide/tutorial/Step4/MathFunctions/MathFunctions.cxx +++ b/Help/guide/tutorial/Step4/MathFunctions/MathFunctions.cxx
@@ -1,19 +1,38 @@ -#include "MathFunctions.h" +// TODO5: Include <cmath> -#include <cmath> +#include <format> +#include <iostream> -#ifdef USE_MYMATH -# include "mysqrt.h" -#endif +namespace { +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + double result = x; + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + + std::cout << std::format("Computing sqrt of {} to be {}\n", x, result); + } + return result; +} +} namespace mathfunctions { double sqrt(double x) { -// which square root function should we use? -#ifdef USE_MYMATH - return detail::mysqrt(x); -#else - return std::sqrt(x); -#endif + // TODO6: Check if TUTORIAL_USE_STD_SQRT is defined, if so use std::sqrt + // instead of mysqrt + + return mysqrt(x); } }
diff --git a/Help/guide/tutorial/Step4/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step4/MathFunctions/mysqrt.cxx deleted file mode 100644 index ba0ac64..0000000 --- a/Help/guide/tutorial/Step4/MathFunctions/mysqrt.cxx +++ /dev/null
@@ -1,28 +0,0 @@ -#include "mysqrt.h" - -#include <iostream> - -namespace mathfunctions { -namespace detail { -// a hack square root calculation using simple operations -double mysqrt(double x) -{ - if (x <= 0) { - return 0; - } - - double result = x; - - // do ten iterations - for (int i = 0; i < 10; ++i) { - if (result <= 0) { - result = 0.1; - } - double delta = x - (result * result); - result = result + 0.5 * delta / result; - std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; - } - return result; -} -} -}
diff --git a/Help/guide/tutorial/Step4/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step4/MathFunctions/mysqrt.h deleted file mode 100644 index 593d41e..0000000 --- a/Help/guide/tutorial/Step4/MathFunctions/mysqrt.h +++ /dev/null
@@ -1,7 +0,0 @@ -#pragma once - -namespace mathfunctions { -namespace detail { -double mysqrt(double x); -} -}
diff --git a/Help/guide/tutorial/Step4/Tutorial/CMakeLists.txt b/Help/guide/tutorial/Step4/Tutorial/CMakeLists.txt new file mode 100644 index 0000000..65a1e74 --- /dev/null +++ b/Help/guide/tutorial/Step4/Tutorial/CMakeLists.txt
@@ -0,0 +1,33 @@ +add_executable(Tutorial) + +target_sources(Tutorial + PRIVATE + Tutorial.cxx +) + +# TODO14: Add VendorLib to Tutorial + +target_link_libraries(Tutorial + PRIVATE + MathFunctions +) + +# TODO4: Add a compile feature for C++20 support to Tutorial + + +if( + (CMAKE_CXX_COMPILER_ID STREQUAL "MSVC") OR + (CMAKE_CXX_COMPILER_FRONTEND_VARIANT STREQUAL "MSVC") +) + + # TODO9: Add the /W3 compile flag to Tutorial + +elseif( + (CMAKE_CXX_COMPILER_ID STREQUAL "GNU") OR + (CMAKE_CXX_COMPILER_ID MATCHES "Clang") +) + + # TODO10: Add the -Wall compile flag to Tutorial + + +endif()
diff --git a/Help/guide/tutorial/Step4/Tutorial/Tutorial.cxx b/Help/guide/tutorial/Step4/Tutorial/Tutorial.cxx new file mode 100644 index 0000000..2bb79bf --- /dev/null +++ b/Help/guide/tutorial/Step4/Tutorial/Tutorial.cxx
@@ -0,0 +1,36 @@ +// A simple program that computes the square root of a number +#include <format> +#include <iostream> +#include <string> + +#include <MathFunctions.h> + +#ifdef TUTORIAL_USE_VENDORLIB +# include <Vendor.h> +#endif + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + std::cout << std::format("Usage: {} number\n", argv[0]); + return 1; + } + + int unused; + + // convert input to double + double const inputValue = std::stod(argv[1]); + + // calculate square root + double const outputValue = mathfunctions::sqrt(inputValue); + std::cout << std::format("The square root of {} is {}\n", inputValue, + outputValue); + +#ifdef TUTORIAL_USE_VENDORLIB + if (CheckSqrt(inputValue, outputValue)) { + std::cout << "Sqrt verified by vendor\n"; + } else { + std::cout << "Sqrt rejected by vendor\n"; + } +#endif +}
diff --git a/Help/guide/tutorial/Step4/TutorialConfig.h.in b/Help/guide/tutorial/Step4/TutorialConfig.h.in deleted file mode 100644 index 7e4d7fa..0000000 --- a/Help/guide/tutorial/Step4/TutorialConfig.h.in +++ /dev/null
@@ -1,3 +0,0 @@ -// the configured options and settings for Tutorial -#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ -#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@
diff --git a/Help/guide/tutorial/Step4/Vendor/CMakeLists.txt b/Help/guide/tutorial/Step4/Vendor/CMakeLists.txt new file mode 100644 index 0000000..5850a8c --- /dev/null +++ b/Help/guide/tutorial/Step4/Vendor/CMakeLists.txt
@@ -0,0 +1,8 @@ +add_library(VendorLib INTERFACE) +target_compile_definitions(VendorLib INTERFACE TUTORIAL_USE_VENDORLIB) + +# TODO11: Add the include directory to VendorLib + +# TODO12: Add the lib directory to VendorLib + +# TODO13: Add the Vendor archive to VendorLib
diff --git a/Help/guide/tutorial/Step4/Vendor/include/Vendor.h b/Help/guide/tutorial/Step4/Vendor/include/Vendor.h new file mode 100644 index 0000000..78742c4 --- /dev/null +++ b/Help/guide/tutorial/Step4/Vendor/include/Vendor.h
@@ -0,0 +1,3 @@ +#pragma once + +bool CheckSqrt(double val, double sqrt);
diff --git a/Help/guide/tutorial/Step4/Vendor/lib/Vendor.cxx b/Help/guide/tutorial/Step4/Vendor/lib/Vendor.cxx new file mode 100644 index 0000000..a6e6c9a --- /dev/null +++ b/Help/guide/tutorial/Step4/Vendor/lib/Vendor.cxx
@@ -0,0 +1,8 @@ +bool CheckSqrt(double val, double sqrt) +{ + double pow2 = sqrt * sqrt; + double delta = val > pow2 ? val - pow2 : pow2 - val; + + // Close enough! + return delta < 0.1; +}
diff --git a/Help/guide/tutorial/Step4/tutorial.cxx b/Help/guide/tutorial/Step4/tutorial.cxx deleted file mode 100644 index 48be3c6..0000000 --- a/Help/guide/tutorial/Step4/tutorial.cxx +++ /dev/null
@@ -1,27 +0,0 @@ -// A simple program that computes the square root of a number -#include <cmath> -#include <iostream> -#include <string> - -#include "MathFunctions.h" -#include "TutorialConfig.h" - -int main(int argc, char* argv[]) -{ - if (argc < 2) { - // report version - std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." - << Tutorial_VERSION_MINOR << std::endl; - std::cout << "Usage: " << argv[0] << " number" << std::endl; - return 1; - } - - // convert input to double - double const inputValue = std::stod(argv[1]); - - double const outputValue = mathfunctions::sqrt(inputValue); - - std::cout << "The square root of " << inputValue << " is " << outputValue - << std::endl; - return 0; -}
diff --git a/Help/guide/tutorial/Step5/CMakeLists.txt b/Help/guide/tutorial/Step5/CMakeLists.txt index ad814f6..f5ed532 100644 --- a/Help/guide/tutorial/Step5/CMakeLists.txt +++ b/Help/guide/tutorial/Step5/CMakeLists.txt
@@ -1,59 +1,12 @@ -cmake_minimum_required(VERSION 3.15) +cmake_minimum_required(VERSION 3.23) -# set the project name and version -project(Tutorial VERSION 1.0) +project(Tutorial) -# specify the C++ standard -add_library(tutorial_compiler_flags INTERFACE) -target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) +option(TUTORIAL_BUILD_UTILITIES "Build the Tutorial executable" ON) +option(TUTORIAL_USE_STD_SQRT "Use std::sqrt" OFF) -# add compiler warning flags just when building this project via -# the BUILD_INTERFACE genex -set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>") -set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") -target_compile_options(tutorial_compiler_flags INTERFACE - "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>" - "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" -) +if(TUTORIAL_BUILD_UTILITIES) + add_subdirectory(Tutorial) +endif() -# configure a header file to pass some of the CMake settings -# to the source code -configure_file(TutorialConfig.h.in TutorialConfig.h) - -# add the MathFunctions library add_subdirectory(MathFunctions) - -# add the executable -add_executable(Tutorial tutorial.cxx) - -target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags) - -# add the binary tree to the search path for include files -# so that we will find TutorialConfig.h -target_include_directories(Tutorial PUBLIC - "${PROJECT_BINARY_DIR}" - ) - -# TODO 3: Install Tutorial in the bin directory -# Hint: Use the TARGETS and DESTINATION parameters - -# TODO 4: Install TutorialConfig.h to the include directory -# Hint: Use the FILES and DESTINATION parameters - -# TODO 5: Enable testing - -# TODO 6: Add a test called Runs which runs the following command: -# $ Tutorial 25 - -# TODO 7: Add a test called Usage which runs the following command: -# $ Tutorial -# Make sure the expected output is displayed. -# Hint: Use the PASS_REGULAR_EXPRESSION property with "Usage.*number" - -# TODO 8: Add a test which runs the following command: -# $ Tutorial 4 -# Make sure the result is correct. -# Hint: Use the PASS_REGULAR_EXPRESSION property with "4 is 2" - -# TODO 9: Add more tests. Create a function called do_test to avoid copy + -# paste. Test the following values: 4, 9, 5, 7, 25, -25 and 0.0001.
diff --git a/Help/guide/tutorial/Step5/CMakePresets.json b/Help/guide/tutorial/Step5/CMakePresets.json new file mode 100644 index 0000000..b8ca15f --- /dev/null +++ b/Help/guide/tutorial/Step5/CMakePresets.json
@@ -0,0 +1,14 @@ +{ + "version": 4, + "configurePresets": [ + { + "name": "tutorial", + "displayName": "Tutorial Preset", + "description": "Preset to use with the tutorial", + "binaryDir": "${sourceDir}/build", + "cacheVariables": { + "TUTORIAL_USE_STD_SQRT": "OFF" + } + } + ] +}
diff --git a/Help/guide/tutorial/Step5/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step5/MathFunctions/CMakeLists.txt index 61b3899..2c33965 100644 --- a/Help/guide/tutorial/Step5/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step5/MathFunctions/CMakeLists.txt
@@ -1,34 +1,30 @@ -add_library(MathFunctions MathFunctions.cxx) +add_library(MathFunctions) -# state that anybody linking to us needs to include the current source dir -# to find MathFunctions.h, while we don't. -target_include_directories(MathFunctions - INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} - ) +target_sources(MathFunctions + PRIVATE + MathFunctions.cxx -# should we use our own math functions -option(USE_MYMATH "Use tutorial provided math implementation" ON) -if (USE_MYMATH) - target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") + PUBLIC + FILE_SET HEADERS + FILES + MathFunctions.h +) - # library that just does sqrt - add_library(SqrtLibrary STATIC - mysqrt.cxx - ) +# TODO3: Add a link to MathLogger for the MathFunctions library. Note that +# MathLogger will only be used in the MathFunctions implementation, +# not the headers - # link SqrtLibrary to tutorial_compiler_flags - target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) +# TODO8: Add links to OpAdd, OpMul, and OpSub libraries for the +# MathFunctions library. Note that their headers will be +# exposed in the MathFunctions.h header, and must be available +# to consumers. - target_link_libraries(MathFunctions PRIVATE SqrtLibrary) +target_compile_features(MathFunctions PRIVATE cxx_std_20) + +if(TUTORIAL_USE_STD_SQRT) + target_compile_definitions(MathFunctions PRIVATE TUTORIAL_USE_STD_SQRT) endif() -# link MathFunctions to tutorial_compiler_flags -target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) +# TODO4: Add the MathLogger subdirectory -# TODO 1: Create a variable called installable_libs that is a list of all -# libraries we want to install (e.g. MathFunctions and tutorial_compiler_flags) -# Then install the installable libraries to the lib folder. -# Hint: Use the TARGETS and DESTINATION parameters - -# TODO 2: Install the library headers to the include folder. -# Hint: Use the FILES and DESTINATION parameters +# TODO9: Add the MathExtensions subdirectory
diff --git a/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/CMakeLists.txt b/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/CMakeLists.txt new file mode 100644 index 0000000..b113786 --- /dev/null +++ b/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/CMakeLists.txt
@@ -0,0 +1,3 @@ +add_subdirectory(OpAdd) +add_subdirectory(OpMul) +add_subdirectory(OpSub)
diff --git a/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/OpAdd/CMakeLists.txt b/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/OpAdd/CMakeLists.txt new file mode 100644 index 0000000..f35da81 --- /dev/null +++ b/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/OpAdd/CMakeLists.txt
@@ -0,0 +1,11 @@ +add_library(OpAdd OBJECT) + +target_sources(OpAdd + PRIVATE + OpAdd.cxx + + INTERFACE + FILE_SET HEADERS + FILES + OpAdd.h +)
diff --git a/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/OpAdd/OpAdd.cxx b/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/OpAdd/OpAdd.cxx new file mode 100644 index 0000000..ea11496 --- /dev/null +++ b/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/OpAdd/OpAdd.cxx
@@ -0,0 +1,6 @@ +namespace mathfunctions { +double OpAdd(double a, double b) +{ + return a + b; +} +}
diff --git a/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/OpAdd/OpAdd.h b/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/OpAdd/OpAdd.h new file mode 100644 index 0000000..9c9efc3 --- /dev/null +++ b/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/OpAdd/OpAdd.h
@@ -0,0 +1,5 @@ +#pragma once + +namespace mathfunctions { +double OpAdd(double a, double b); +}
diff --git a/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/OpMul/CMakeLists.txt b/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/OpMul/CMakeLists.txt new file mode 100644 index 0000000..f494fc6 --- /dev/null +++ b/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/OpMul/CMakeLists.txt
@@ -0,0 +1,11 @@ +add_library(OpMul OBJECT) + +target_sources(OpMul + PRIVATE + OpMul.cxx + + INTERFACE + FILE_SET HEADERS + FILES + OpMul.h +)
diff --git a/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/OpMul/OpMul.cxx b/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/OpMul/OpMul.cxx new file mode 100644 index 0000000..c8eb016 --- /dev/null +++ b/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/OpMul/OpMul.cxx
@@ -0,0 +1,6 @@ +namespace mathfunctions { +double OpMul(double a, double b) +{ + return a * b; +} +}
diff --git a/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/OpMul/OpMul.h b/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/OpMul/OpMul.h new file mode 100644 index 0000000..52b467b --- /dev/null +++ b/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/OpMul/OpMul.h
@@ -0,0 +1,5 @@ +#pragma once + +namespace mathfunctions { +double OpMul(double a, double b); +}
diff --git a/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/OpSub/CMakeLists.txt b/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/OpSub/CMakeLists.txt new file mode 100644 index 0000000..1a108fd --- /dev/null +++ b/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/OpSub/CMakeLists.txt
@@ -0,0 +1,11 @@ +add_library(OpSub OBJECT) + +target_sources(OpSub + PRIVATE + OpSub.cxx + + INTERFACE + FILE_SET HEADERS + FILES + OpSub.h +)
diff --git a/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/OpSub/OpSub.cxx b/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/OpSub/OpSub.cxx new file mode 100644 index 0000000..b7b35da --- /dev/null +++ b/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/OpSub/OpSub.cxx
@@ -0,0 +1,6 @@ +namespace mathfunctions { +double OpSub(double a, double b) +{ + return a - b; +} +}
diff --git a/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/OpSub/OpSub.h b/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/OpSub/OpSub.h new file mode 100644 index 0000000..1406733 --- /dev/null +++ b/Help/guide/tutorial/Step5/MathFunctions/MathExtensions/OpSub/OpSub.h
@@ -0,0 +1,5 @@ +#pragma once + +namespace mathfunctions { +double OpSub(double a, double b); +}
diff --git a/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.cxx index dc28b4b..811209f 100644 --- a/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.cxx +++ b/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.cxx
@@ -1,19 +1,45 @@ -#include "MathFunctions.h" - #include <cmath> +#include <format> -#ifdef USE_MYMATH -# include "mysqrt.h" -#endif +// TODO5: Replace <iostream> with <MathLogger.h> + +#include <iostream> + +namespace { + +// TODO6: Instantiate a logger inside the anonymous namespace + +// a hack square root calculation using simple operations +double mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + double result = x; + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + + // TODO7: Use the logger to log the message + std::cout << std::format("Computing sqrt of {} to be {}\n", x, result); + } + return result; +} +} namespace mathfunctions { double sqrt(double x) { -// which square root function should we use? -#ifdef USE_MYMATH - return detail::mysqrt(x); -#else +#ifdef TUTORIAL_USE_STD_SQRT return std::sqrt(x); +#else + return mysqrt(x); #endif } }
diff --git a/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.h index d5c2f22..fcc469b 100644 --- a/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.h +++ b/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.h
@@ -1,5 +1,7 @@ #pragma once +// TODO10: Include <OpAdd.h>, <OpMul.h>, and <OpSub.h> + namespace mathfunctions { double sqrt(double x); }
diff --git a/Help/guide/tutorial/Step5/MathFunctions/MathLogger/CMakeLists.txt b/Help/guide/tutorial/Step5/MathFunctions/MathLogger/CMakeLists.txt new file mode 100644 index 0000000..1077c7f --- /dev/null +++ b/Help/guide/tutorial/Step5/MathFunctions/MathLogger/CMakeLists.txt
@@ -0,0 +1,6 @@ + +# TODO1: Add an INTERFACE library called MathLogger + + +# TODO2: Add an appropriate FILE_SET to MathLogger to capture the headers in +# this directory
diff --git a/Help/guide/tutorial/Step5/MathFunctions/MathLogger/MathFormatting.h b/Help/guide/tutorial/Step5/MathFunctions/MathLogger/MathFormatting.h new file mode 100644 index 0000000..3b6d61c --- /dev/null +++ b/Help/guide/tutorial/Step5/MathFunctions/MathLogger/MathFormatting.h
@@ -0,0 +1,27 @@ +#pragma once + +#include <string> + +namespace mathlogger { + +enum LogLevel +{ + INFO, + WARN, + ERROR, +}; + +inline std::string FormatLog(LogLevel level, std::string const& message) +{ + switch (level) { + case INFO: + return "INFO: " + message; + case WARN: + return "WARN: " + message; + case ERROR: + return "ERROR: " + message; + } + return "UNKNOWN: " + message; +} + +}
diff --git a/Help/guide/tutorial/Step5/MathFunctions/MathLogger/MathLogger.h b/Help/guide/tutorial/Step5/MathFunctions/MathLogger/MathLogger.h new file mode 100644 index 0000000..ef7b31a --- /dev/null +++ b/Help/guide/tutorial/Step5/MathFunctions/MathLogger/MathLogger.h
@@ -0,0 +1,22 @@ +#pragma once + +#include <string> + +#include "MathFormatting.h" +#include "MathOutput.h" + +namespace mathlogger { + +struct Logger +{ + LogLevel level = INFO; + + void SetLevel(LogLevel new_level) { level = new_level; } + void Log(std::string const& message) + { + std::string formatted = FormatLog(level, message); + WriteLog(formatted); + } +}; + +}
diff --git a/Help/guide/tutorial/Step5/MathFunctions/MathLogger/MathOutput.h b/Help/guide/tutorial/Step5/MathFunctions/MathLogger/MathOutput.h new file mode 100644 index 0000000..63f0aeb --- /dev/null +++ b/Help/guide/tutorial/Step5/MathFunctions/MathLogger/MathOutput.h
@@ -0,0 +1,11 @@ +#pragma once + +#include <iostream> +#include <string> + +namespace mathlogger { +inline void WriteLog(std::string const& msg) +{ + std::cout << msg; +} +}
diff --git a/Help/guide/tutorial/Step5/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step5/MathFunctions/mysqrt.cxx deleted file mode 100644 index ba0ac64..0000000 --- a/Help/guide/tutorial/Step5/MathFunctions/mysqrt.cxx +++ /dev/null
@@ -1,28 +0,0 @@ -#include "mysqrt.h" - -#include <iostream> - -namespace mathfunctions { -namespace detail { -// a hack square root calculation using simple operations -double mysqrt(double x) -{ - if (x <= 0) { - return 0; - } - - double result = x; - - // do ten iterations - for (int i = 0; i < 10; ++i) { - if (result <= 0) { - result = 0.1; - } - double delta = x - (result * result); - result = result + 0.5 * delta / result; - std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; - } - return result; -} -} -}
diff --git a/Help/guide/tutorial/Step5/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step5/MathFunctions/mysqrt.h deleted file mode 100644 index 593d41e..0000000 --- a/Help/guide/tutorial/Step5/MathFunctions/mysqrt.h +++ /dev/null
@@ -1,7 +0,0 @@ -#pragma once - -namespace mathfunctions { -namespace detail { -double mysqrt(double x); -} -}
diff --git a/Help/guide/tutorial/Step5/Tutorial/CMakeLists.txt b/Help/guide/tutorial/Step5/Tutorial/CMakeLists.txt new file mode 100644 index 0000000..3daa5ea --- /dev/null +++ b/Help/guide/tutorial/Step5/Tutorial/CMakeLists.txt
@@ -0,0 +1,29 @@ +add_executable(Tutorial) + +target_sources(Tutorial + PRIVATE + Tutorial.cxx +) + +target_link_libraries(Tutorial + PRIVATE + MathFunctions +) + +target_compile_features(Tutorial PRIVATE cxx_std_20) + +if( + (CMAKE_CXX_COMPILER_ID STREQUAL "MSVC") OR + (CMAKE_CXX_COMPILER_FRONTEND_VARIANT STREQUAL "MSVC") +) + + target_compile_options(Tutorial PRIVATE /W3) + +elseif( + (CMAKE_CXX_COMPILER_ID STREQUAL "GNU") OR + (CMAKE_CXX_COMPILER_ID MATCHES "Clang") +) + + target_compile_options(Tutorial PRIVATE -Wall) + +endif()
diff --git a/Help/guide/tutorial/Step5/Tutorial/Tutorial.cxx b/Help/guide/tutorial/Step5/Tutorial/Tutorial.cxx new file mode 100644 index 0000000..e3e3604 --- /dev/null +++ b/Help/guide/tutorial/Step5/Tutorial/Tutorial.cxx
@@ -0,0 +1,26 @@ +// A simple program that computes the square root of a number +#include <format> +#include <iostream> +#include <string> + +#include <MathFunctions.h> + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + std::cout << std::format("Usage: {} number\n", argv[0]); + return 1; + } + + // convert input to double + double const inputValue = std::stod(argv[1]); + + // calculate square root + double const outputValue = mathfunctions::sqrt(inputValue); + std::cout << std::format("The square root of {} is {}\n", inputValue, + outputValue); + + // TODO11: Check the calculated square root using mathfunctions::OpMul to + // square the outputValue. Output the result with the format: + // "The square of {} is {}\n" +}
diff --git a/Help/guide/tutorial/Step5/TutorialConfig.h.in b/Help/guide/tutorial/Step5/TutorialConfig.h.in deleted file mode 100644 index 7e4d7fa..0000000 --- a/Help/guide/tutorial/Step5/TutorialConfig.h.in +++ /dev/null
@@ -1,3 +0,0 @@ -// the configured options and settings for Tutorial -#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ -#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@
diff --git a/Help/guide/tutorial/Step5/tutorial.cxx b/Help/guide/tutorial/Step5/tutorial.cxx deleted file mode 100644 index 48be3c6..0000000 --- a/Help/guide/tutorial/Step5/tutorial.cxx +++ /dev/null
@@ -1,27 +0,0 @@ -// A simple program that computes the square root of a number -#include <cmath> -#include <iostream> -#include <string> - -#include "MathFunctions.h" -#include "TutorialConfig.h" - -int main(int argc, char* argv[]) -{ - if (argc < 2) { - // report version - std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." - << Tutorial_VERSION_MINOR << std::endl; - std::cout << "Usage: " << argv[0] << " number" << std::endl; - return 1; - } - - // convert input to double - double const inputValue = std::stod(argv[1]); - - double const outputValue = mathfunctions::sqrt(inputValue); - - std::cout << "The square root of " << inputValue << " is " << outputValue - << std::endl; - return 0; -}
diff --git a/Help/guide/tutorial/Step6/CMakeLists.txt b/Help/guide/tutorial/Step6/CMakeLists.txt index a86d60a..c07a1ac 100644 --- a/Help/guide/tutorial/Step6/CMakeLists.txt +++ b/Help/guide/tutorial/Step6/CMakeLists.txt
@@ -1,71 +1,24 @@ -cmake_minimum_required(VERSION 3.15) +cmake_minimum_required(VERSION 3.23) -# set the project name and version -project(Tutorial VERSION 1.0) +project(Tutorial) -# specify the C++ standard -add_library(tutorial_compiler_flags INTERFACE) -target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) +option(TUTORIAL_BUILD_UTILITIES "Build the Tutorial executable" ON) +option(TUTORIAL_USE_STD_SQRT "Use std::sqrt" OFF) -# add compiler warning flags just when building this project via -# the BUILD_INTERFACE genex -set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>") -set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") -target_compile_options(tutorial_compiler_flags INTERFACE - "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>" - "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" -) +# TODO6: Add a default-ON option named TUTORIAL_ENABLE_IPO with a doc string: +# "Check for and use IPO support" -# configure a header file to pass some of the CMake settings -# to the source code -configure_file(TutorialConfig.h.in TutorialConfig.h) +# TODO7: Include and use the CheckIPOSupported module to enable IPO if +# TUTORIAL_ENABLE_IPO is True. To enable IPO, use: +# set(CMAKE_INTERPROCEDURAL_OPTIMIZATION True) +# Otherwise, follow the examples in the CheckIPOSupported documentation. +# Specifically, follow the documentation example to emit an error message +# if IPO is unavailable. Additionally, when IPO is available, emit a +# message indicating so (otherwise IPO has no easily visible change in +# the logs or build). -# add the MathFunctions library +if(TUTORIAL_BUILD_UTILITIES) + add_subdirectory(Tutorial) +endif() + add_subdirectory(MathFunctions) - -# add the executable -add_executable(Tutorial tutorial.cxx) - -target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags) - -# add the binary tree to the search path for include files -# so that we will find TutorialConfig.h -target_include_directories(Tutorial PUBLIC - "${PROJECT_BINARY_DIR}" - ) - -# add the install targets -install(TARGETS Tutorial DESTINATION bin) -install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" - DESTINATION include - ) - -# TODO 1: Replace enable_testing() with include(CTest) -# enable testing -enable_testing() - -# does the application run -add_test(NAME Runs COMMAND Tutorial 25) - -# does the usage message work? -add_test(NAME Usage COMMAND Tutorial) -set_tests_properties(Usage - PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" - ) - -# define a function to simplify adding tests -function(do_test target arg result) - add_test(NAME Comp${arg} COMMAND ${target} ${arg}) - set_tests_properties(Comp${arg} - PROPERTIES PASS_REGULAR_EXPRESSION ${result} - ) -endfunction() - -# do a bunch of result based tests -do_test(Tutorial 4 "4 is 2") -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 0.0001 "0.0001 is 0.01")
diff --git a/Help/guide/tutorial/Step6/CMakePresets.json b/Help/guide/tutorial/Step6/CMakePresets.json new file mode 100644 index 0000000..b8ca15f --- /dev/null +++ b/Help/guide/tutorial/Step6/CMakePresets.json
@@ -0,0 +1,14 @@ +{ + "version": 4, + "configurePresets": [ + { + "name": "tutorial", + "displayName": "Tutorial Preset", + "description": "Preset to use with the tutorial", + "binaryDir": "${sourceDir}/build", + "cacheVariables": { + "TUTORIAL_USE_STD_SQRT": "OFF" + } + } + ] +}
diff --git a/Help/guide/tutorial/Step6/CTestConfig.cmake b/Help/guide/tutorial/Step6/CTestConfig.cmake deleted file mode 100644 index b2922fe..0000000 --- a/Help/guide/tutorial/Step6/CTestConfig.cmake +++ /dev/null
@@ -1,3 +0,0 @@ -set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") - -set(CTEST_SUBMIT_URL "https://my.cdash.org/submit.php?project=CMakeTutorial")
diff --git a/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt index 8499a51..bac1e65 100644 --- a/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt
@@ -1,35 +1,49 @@ -add_library(MathFunctions MathFunctions.cxx) +add_library(MathFunctions) -# state that anybody linking to us needs to include the current source dir -# to find MathFunctions.h, while we don't. -target_include_directories(MathFunctions - INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} - ) +target_sources(MathFunctions + PRIVATE + MathFunctions.cxx -# should we use our own math functions -option(USE_MYMATH "Use tutorial provided math implementation" ON) -if (USE_MYMATH) - target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") + PUBLIC + FILE_SET HEADERS + FILES + MathFunctions.h +) - # library that just does sqrt - add_library(SqrtLibrary STATIC - mysqrt.cxx - ) +target_link_libraries(MathFunctions + PRIVATE + MathLogger - # link SqrtLibrary to tutorial_compiler_flags - target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) + PUBLIC + OpAdd + OpMul + OpSub +) - target_link_libraries(MathFunctions PRIVATE SqrtLibrary) +target_compile_features(MathFunctions PRIVATE cxx_std_20) + +if(TUTORIAL_USE_STD_SQRT) + target_compile_definitions(MathFunctions PRIVATE TUTORIAL_USE_STD_SQRT) endif() -# link MathFunctions to tutorial_compiler_flags -target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) +# TODO1: Include the CheckIncludeFiles module and use it to check for +# the emmintrin.h header. -# install libs -set(installable_libs MathFunctions tutorial_compiler_flags) -if(TARGET SqrtLibrary) - list(APPEND installable_libs SqrtLibrary) -endif() -install(TARGETS ${installable_libs} DESTINATION lib) -# install include headers -install(FILES MathFunctions.h DESTINATION include) +# TODO2: If emmintrin.h is available, add a compile definition to MathFunctions +# named TUTORIAL_USE_SSE2. This will only be needed by the MathFunctions +# implementation file. + +# TODO4: Include the CheckSourceCompiles module and use it to check if the +# following program compiles: +# +# typedef double v2df __attribute__((vector_size(16))); +# int main() { +# __builtin_ia32_sqrtsd(v2df{}); +# } + +# TODO5: If the GNU builtins are available, add a compile definition to +# MathFunctions named TUTORIAL_USE_GNU_BUILTIN. This will only be needed +# by the MathFunctions implementation file. + +add_subdirectory(MathLogger) +add_subdirectory(MathExtensions)
diff --git a/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/CMakeLists.txt b/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/CMakeLists.txt new file mode 100644 index 0000000..b113786 --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/CMakeLists.txt
@@ -0,0 +1,3 @@ +add_subdirectory(OpAdd) +add_subdirectory(OpMul) +add_subdirectory(OpSub)
diff --git a/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/OpAdd/CMakeLists.txt b/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/OpAdd/CMakeLists.txt new file mode 100644 index 0000000..f35da81 --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/OpAdd/CMakeLists.txt
@@ -0,0 +1,11 @@ +add_library(OpAdd OBJECT) + +target_sources(OpAdd + PRIVATE + OpAdd.cxx + + INTERFACE + FILE_SET HEADERS + FILES + OpAdd.h +)
diff --git a/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/OpAdd/OpAdd.cxx b/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/OpAdd/OpAdd.cxx new file mode 100644 index 0000000..ea11496 --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/OpAdd/OpAdd.cxx
@@ -0,0 +1,6 @@ +namespace mathfunctions { +double OpAdd(double a, double b) +{ + return a + b; +} +}
diff --git a/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/OpAdd/OpAdd.h b/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/OpAdd/OpAdd.h new file mode 100644 index 0000000..9c9efc3 --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/OpAdd/OpAdd.h
@@ -0,0 +1,5 @@ +#pragma once + +namespace mathfunctions { +double OpAdd(double a, double b); +}
diff --git a/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/OpMul/CMakeLists.txt b/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/OpMul/CMakeLists.txt new file mode 100644 index 0000000..f494fc6 --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/OpMul/CMakeLists.txt
@@ -0,0 +1,11 @@ +add_library(OpMul OBJECT) + +target_sources(OpMul + PRIVATE + OpMul.cxx + + INTERFACE + FILE_SET HEADERS + FILES + OpMul.h +)
diff --git a/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/OpMul/OpMul.cxx b/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/OpMul/OpMul.cxx new file mode 100644 index 0000000..c8eb016 --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/OpMul/OpMul.cxx
@@ -0,0 +1,6 @@ +namespace mathfunctions { +double OpMul(double a, double b) +{ + return a * b; +} +}
diff --git a/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/OpMul/OpMul.h b/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/OpMul/OpMul.h new file mode 100644 index 0000000..52b467b --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/OpMul/OpMul.h
@@ -0,0 +1,5 @@ +#pragma once + +namespace mathfunctions { +double OpMul(double a, double b); +}
diff --git a/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/OpSub/CMakeLists.txt b/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/OpSub/CMakeLists.txt new file mode 100644 index 0000000..1a108fd --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/OpSub/CMakeLists.txt
@@ -0,0 +1,11 @@ +add_library(OpSub OBJECT) + +target_sources(OpSub + PRIVATE + OpSub.cxx + + INTERFACE + FILE_SET HEADERS + FILES + OpSub.h +)
diff --git a/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/OpSub/OpSub.cxx b/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/OpSub/OpSub.cxx new file mode 100644 index 0000000..b7b35da --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/OpSub/OpSub.cxx
@@ -0,0 +1,6 @@ +namespace mathfunctions { +double OpSub(double a, double b) +{ + return a - b; +} +}
diff --git a/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/OpSub/OpSub.h b/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/OpSub/OpSub.h new file mode 100644 index 0000000..1406733 --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/MathExtensions/OpSub/OpSub.h
@@ -0,0 +1,5 @@ +#pragma once + +namespace mathfunctions { +double OpSub(double a, double b); +}
diff --git a/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.cxx index dc28b4b..eae6c32 100644 --- a/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.cxx +++ b/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.cxx
@@ -1,19 +1,79 @@ -#include "MathFunctions.h" - #include <cmath> +#include <format> -#ifdef USE_MYMATH -# include "mysqrt.h" +#include <MathLogger.h> + +// TODO3: If the TUTORIAL_USE_SSE2 definition is set, include +// the <emmintrin.h> header + +namespace { + +mathlogger::Logger Logger; + +#if defined(TUTORIAL_USE_GNU_BUILTIN) +typedef double v2df __attribute__((vector_size(16))); + +double gnu_mysqrt(double x) +{ + v2df root = __builtin_ia32_sqrtsd(v2df{ x, 0.0 }); + double result = root[0]; + Logger.Log(std::format("Computed sqrt of {} to be {} with GNU-builtins\n", x, + result)); + return result; +} +#elif defined(TUTORIAL_USE_SSE2) +double sse2_mysqrt(double x) +{ + __m128d root = _mm_sqrt_sd(_mm_setzero_pd(), _mm_set_sd(x)); + double result = _mm_cvtsd_f64(root); + Logger.Log( + std::format("Computed sqrt of {} to be {} with SSE2\n", x, result)); + return result; +} #endif +// a hack square root calculation using simple operations +double fallback_mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + double result = x; + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + + Logger.Log(std::format("Computing sqrt of {} to be {}\n", x, result)); + } + return result; +} + +double mysqrt(double x) +{ +#if defined(TUTORIAL_USE_GNU_BUILTIN) + return gnu_mysqrt(x); +#elif defined(TUTORIAL_USE_SSE2) + return sse2_mysqrt(x); +#else + return fallback_mysqrt(x); +#endif +} + +} + namespace mathfunctions { double sqrt(double x) { -// which square root function should we use? -#ifdef USE_MYMATH - return detail::mysqrt(x); -#else +#ifdef TUTORIAL_USE_STD_SQRT return std::sqrt(x); +#else + return mysqrt(x); #endif } }
diff --git a/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.h index d5c2f22..91cb176 100644 --- a/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.h +++ b/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.h
@@ -1,5 +1,9 @@ #pragma once +#include <OpAdd.h> +#include <OpMul.h> +#include <OpSub.h> + namespace mathfunctions { double sqrt(double x); }
diff --git a/Help/guide/tutorial/Step6/MathFunctions/MathLogger/CMakeLists.txt b/Help/guide/tutorial/Step6/MathFunctions/MathLogger/CMakeLists.txt new file mode 100644 index 0000000..b20151f --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/MathLogger/CMakeLists.txt
@@ -0,0 +1,6 @@ +add_library(MathLogger INTERFACE) + +target_sources(MathLogger + INTERFACE + FILE_SET HEADERS +)
diff --git a/Help/guide/tutorial/Step6/MathFunctions/MathLogger/MathFormatting.h b/Help/guide/tutorial/Step6/MathFunctions/MathLogger/MathFormatting.h new file mode 100644 index 0000000..3b6d61c --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/MathLogger/MathFormatting.h
@@ -0,0 +1,27 @@ +#pragma once + +#include <string> + +namespace mathlogger { + +enum LogLevel +{ + INFO, + WARN, + ERROR, +}; + +inline std::string FormatLog(LogLevel level, std::string const& message) +{ + switch (level) { + case INFO: + return "INFO: " + message; + case WARN: + return "WARN: " + message; + case ERROR: + return "ERROR: " + message; + } + return "UNKNOWN: " + message; +} + +}
diff --git a/Help/guide/tutorial/Step6/MathFunctions/MathLogger/MathLogger.h b/Help/guide/tutorial/Step6/MathFunctions/MathLogger/MathLogger.h new file mode 100644 index 0000000..ef7b31a --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/MathLogger/MathLogger.h
@@ -0,0 +1,22 @@ +#pragma once + +#include <string> + +#include "MathFormatting.h" +#include "MathOutput.h" + +namespace mathlogger { + +struct Logger +{ + LogLevel level = INFO; + + void SetLevel(LogLevel new_level) { level = new_level; } + void Log(std::string const& message) + { + std::string formatted = FormatLog(level, message); + WriteLog(formatted); + } +}; + +}
diff --git a/Help/guide/tutorial/Step6/MathFunctions/MathLogger/MathOutput.h b/Help/guide/tutorial/Step6/MathFunctions/MathLogger/MathOutput.h new file mode 100644 index 0000000..63f0aeb --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/MathLogger/MathOutput.h
@@ -0,0 +1,11 @@ +#pragma once + +#include <iostream> +#include <string> + +namespace mathlogger { +inline void WriteLog(std::string const& msg) +{ + std::cout << msg; +} +}
diff --git a/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx deleted file mode 100644 index ba0ac64..0000000 --- a/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx +++ /dev/null
@@ -1,28 +0,0 @@ -#include "mysqrt.h" - -#include <iostream> - -namespace mathfunctions { -namespace detail { -// a hack square root calculation using simple operations -double mysqrt(double x) -{ - if (x <= 0) { - return 0; - } - - double result = x; - - // do ten iterations - for (int i = 0; i < 10; ++i) { - if (result <= 0) { - result = 0.1; - } - double delta = x - (result * result); - result = result + 0.5 * delta / result; - std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; - } - return result; -} -} -}
diff --git a/Help/guide/tutorial/Step6/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step6/MathFunctions/mysqrt.h deleted file mode 100644 index 593d41e..0000000 --- a/Help/guide/tutorial/Step6/MathFunctions/mysqrt.h +++ /dev/null
@@ -1,7 +0,0 @@ -#pragma once - -namespace mathfunctions { -namespace detail { -double mysqrt(double x); -} -}
diff --git a/Help/guide/tutorial/Step6/Tutorial/CMakeLists.txt b/Help/guide/tutorial/Step6/Tutorial/CMakeLists.txt new file mode 100644 index 0000000..3daa5ea --- /dev/null +++ b/Help/guide/tutorial/Step6/Tutorial/CMakeLists.txt
@@ -0,0 +1,29 @@ +add_executable(Tutorial) + +target_sources(Tutorial + PRIVATE + Tutorial.cxx +) + +target_link_libraries(Tutorial + PRIVATE + MathFunctions +) + +target_compile_features(Tutorial PRIVATE cxx_std_20) + +if( + (CMAKE_CXX_COMPILER_ID STREQUAL "MSVC") OR + (CMAKE_CXX_COMPILER_FRONTEND_VARIANT STREQUAL "MSVC") +) + + target_compile_options(Tutorial PRIVATE /W3) + +elseif( + (CMAKE_CXX_COMPILER_ID STREQUAL "GNU") OR + (CMAKE_CXX_COMPILER_ID MATCHES "Clang") +) + + target_compile_options(Tutorial PRIVATE -Wall) + +endif()
diff --git a/Help/guide/tutorial/Step6/Tutorial/Tutorial.cxx b/Help/guide/tutorial/Step6/Tutorial/Tutorial.cxx new file mode 100644 index 0000000..44b7831 --- /dev/null +++ b/Help/guide/tutorial/Step6/Tutorial/Tutorial.cxx
@@ -0,0 +1,26 @@ +// A simple program that computes the square root of a number +#include <format> +#include <iostream> +#include <string> + +#include <MathFunctions.h> + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + std::cout << std::format("Usage: {} number\n", argv[0]); + return 1; + } + + // convert input to double + double const inputValue = std::stod(argv[1]); + + // calculate square root + double const outputValue = mathfunctions::sqrt(inputValue); + std::cout << std::format("The square root of {} is {}\n", inputValue, + outputValue); + + double const checkValue = mathfunctions::OpMul(outputValue, outputValue); + std::cout << std::format("The square of {} is {}\n", outputValue, + checkValue); +}
diff --git a/Help/guide/tutorial/Step6/TutorialConfig.h.in b/Help/guide/tutorial/Step6/TutorialConfig.h.in deleted file mode 100644 index 7e4d7fa..0000000 --- a/Help/guide/tutorial/Step6/TutorialConfig.h.in +++ /dev/null
@@ -1,3 +0,0 @@ -// the configured options and settings for Tutorial -#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ -#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@
diff --git a/Help/guide/tutorial/Step6/tutorial.cxx b/Help/guide/tutorial/Step6/tutorial.cxx deleted file mode 100644 index 48be3c6..0000000 --- a/Help/guide/tutorial/Step6/tutorial.cxx +++ /dev/null
@@ -1,27 +0,0 @@ -// A simple program that computes the square root of a number -#include <cmath> -#include <iostream> -#include <string> - -#include "MathFunctions.h" -#include "TutorialConfig.h" - -int main(int argc, char* argv[]) -{ - if (argc < 2) { - // report version - std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." - << Tutorial_VERSION_MINOR << std::endl; - std::cout << "Usage: " << argv[0] << " number" << std::endl; - return 1; - } - - // convert input to double - double const inputValue = std::stod(argv[1]); - - double const outputValue = mathfunctions::sqrt(inputValue); - - std::cout << "The square root of " << inputValue << " is " << outputValue - << std::endl; - return 0; -}
diff --git a/Help/guide/tutorial/Step7/CMakeLists.txt b/Help/guide/tutorial/Step7/CMakeLists.txt index 97ec6aa..0b486f0 100644 --- a/Help/guide/tutorial/Step7/CMakeLists.txt +++ b/Help/guide/tutorial/Step7/CMakeLists.txt
@@ -1,70 +1,25 @@ -cmake_minimum_required(VERSION 3.15) +cmake_minimum_required(VERSION 3.23) -# set the project name and version -project(Tutorial VERSION 1.0) +project(Tutorial) -# specify the C++ standard -add_library(tutorial_compiler_flags INTERFACE) -target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) +option(TUTORIAL_BUILD_UTILITIES "Build the Tutorial executable" ON) +option(TUTORIAL_USE_STD_SQRT "Use std::sqrt" OFF) +option(TUTORIAL_ENABLE_IPO "Check for and use IPO support" ON) -# add compiler warning flags just when building this project via -# the BUILD_INTERFACE genex -set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>") -set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") -target_compile_options(tutorial_compiler_flags INTERFACE - "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>" - "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" -) +if(TUTORIAL_ENABLE_IPO) + include(CheckIPOSupported) + check_ipo_supported(RESULT result OUTPUT output) + if(result) + message("IPO is supported, enabling IPO") + set(CMAKE_INTERPROCEDURAL_OPTIMIZATION ON) + else() + message(WARNING "IPO is not supported: ${output}") + endif() +endif() -# configure a header file to pass some of the CMake settings -# to the source code -configure_file(TutorialConfig.h.in TutorialConfig.h) -# add the MathFunctions library +if(TUTORIAL_BUILD_UTILITIES) + add_subdirectory(Tutorial) +endif() + add_subdirectory(MathFunctions) - -# add the executable -add_executable(Tutorial tutorial.cxx) - -target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags) - -# add the binary tree to the search path for include files -# so that we will find TutorialConfig.h -target_include_directories(Tutorial PUBLIC - "${PROJECT_BINARY_DIR}" - ) - -# add the install targets -install(TARGETS Tutorial DESTINATION bin) -install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" - DESTINATION include - ) - -# enable testing -include(CTest) - -# does the application run -add_test(NAME Runs COMMAND Tutorial 25) - -# does the usage message work? -add_test(NAME Usage COMMAND Tutorial) -set_tests_properties(Usage - PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" - ) - -# define a function to simplify adding tests -function(do_test target arg result) - add_test(NAME Comp${arg} COMMAND ${target} ${arg}) - set_tests_properties(Comp${arg} - PROPERTIES PASS_REGULAR_EXPRESSION ${result} - ) -endfunction() - -# do a bunch of result based tests -do_test(Tutorial 4 "4 is 2") -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 0.0001 "0.0001 is 0.01")
diff --git a/Help/guide/tutorial/Step7/CMakePresets.json b/Help/guide/tutorial/Step7/CMakePresets.json new file mode 100644 index 0000000..f393977 --- /dev/null +++ b/Help/guide/tutorial/Step7/CMakePresets.json
@@ -0,0 +1,15 @@ +{ + "version": 4, + "configurePresets": [ + { + "name": "tutorial", + "displayName": "Tutorial Preset", + "description": "Preset to use with the tutorial", + "binaryDir": "${sourceDir}/build", + "cacheVariables": { + "TUTORIAL_USE_STD_SQRT": "OFF", + "TUTORIAL_ENABLE_IPO": "OFF" + } + } + ] +}
diff --git a/Help/guide/tutorial/Step7/CTestConfig.cmake b/Help/guide/tutorial/Step7/CTestConfig.cmake deleted file mode 100644 index b2922fe..0000000 --- a/Help/guide/tutorial/Step7/CTestConfig.cmake +++ /dev/null
@@ -1,3 +0,0 @@ -set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") - -set(CTEST_SUBMIT_URL "https://my.cdash.org/submit.php?project=CMakeTutorial")
diff --git a/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt index a0b3037..3782f66 100644 --- a/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt
@@ -1,55 +1,54 @@ -add_library(MathFunctions MathFunctions.cxx) +add_library(MathFunctions) -# state that anybody linking to us needs to include the current source dir -# to find MathFunctions.h, while we don't. -target_include_directories(MathFunctions - INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} - ) +target_sources(MathFunctions + PRIVATE + MathFunctions.cxx -# should we use our own math functions -option(USE_MYMATH "Use tutorial provided math implementation" ON) -if (USE_MYMATH) - target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") + PUBLIC + FILE_SET HEADERS + FILES + MathFunctions.h +) - # library that just does sqrt - add_library(SqrtLibrary STATIC - mysqrt.cxx - ) +# TODO8: Add the interface library to MathFunctions +target_link_libraries(MathFunctions + PRIVATE + MathLogger - # link SqrtLibrary to tutorial_compiler_flags - target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) + PUBLIC + OpAdd + OpMul + OpSub +) - # TODO 1: Include CheckCXXSourceCompiles +target_compile_features(MathFunctions PRIVATE cxx_std_20) - # TODO 2: Use check_cxx_source_compiles with simple C++ code to verify - # availability of: - # * std::log - # * std::exp - # Store the results in HAVE_LOG and HAVE_EXP respectively. - - # Hint: Sample C++ code which uses log: - # #include <cmath> - # int main() { - # std::log(1.0); - # return 0; - # } - - # TODO 3: Conditionally on HAVE_LOG and HAVE_EXP, add private compile - # definitions "HAVE_LOG" and "HAVE_EXP" to the SqrtLibrary target. - - # Hint: Use target_compile_definitions() - - target_link_libraries(MathFunctions PRIVATE SqrtLibrary) +if(TUTORIAL_USE_STD_SQRT) + target_compile_definitions(MathFunctions PRIVATE TUTORIAL_USE_STD_SQRT) endif() -# link MathFunctions to tutorial_compiler_flags -target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) +include(CheckIncludeFiles) +check_include_files(emmintrin.h HAS_EMMINTRIN LANGUAGE CXX) -# install libs -set(installable_libs MathFunctions tutorial_compiler_flags) -if(TARGET SqrtLibrary) - list(APPEND installable_libs SqrtLibrary) +if(HAS_EMMINTRIN) + target_compile_definitions(MathFunctions PRIVATE TUTORIAL_USE_SSE2) endif() -install(TARGETS ${installable_libs} DESTINATION lib) -# install include headers -install(FILES MathFunctions.h DESTINATION include) + +include(CheckSourceCompiles) +check_source_compiles(CXX + [=[ + typedef double v2df __attribute__((vector_size(16))); + int main() { + __builtin_ia32_sqrtsd(v2df{}); + } + ]=] + HAS_GNU_BUILTIN +) + +if(HAS_GNU_BUILTIN) + target_compile_definitions(MathFunctions PRIVATE TUTORIAL_USE_GNU_BUILTIN) +endif() + +add_subdirectory(MathLogger) +add_subdirectory(MathExtensions) +# TODO9: Add the MakeTable subdirectory to the project
diff --git a/Help/guide/tutorial/Step7/MathFunctions/MakeTable/CMakeLists.txt b/Help/guide/tutorial/Step7/MathFunctions/MakeTable/CMakeLists.txt new file mode 100644 index 0000000..cef2be7 --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/MakeTable/CMakeLists.txt
@@ -0,0 +1,15 @@ +# TODO1: Add a MakeTable executable + +# TODO2: Add MakeTable.cxx to the MakeTable executable + +# TODO3: Add a custom command which invokes MakeTable to generate SqrtTable.h + +# TODO4: Add a custom target which depends on SqrtTable.h + +# TODO5: Add an INTERFACE library to describe the SqrtTable header + +# TODO6: Add the current binary directory (and optionally the SqrtTable.h FILE) +# to a header file set of the interface library + +# TODO7: Use add_dependencies to ensure the custom target always runs before +# targets that depend on the interface library
diff --git a/Help/guide/tutorial/Step10/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step7/MathFunctions/MakeTable/MakeTable.cxx similarity index 100% rename from Help/guide/tutorial/Step10/MathFunctions/MakeTable.cxx rename to Help/guide/tutorial/Step7/MathFunctions/MakeTable/MakeTable.cxx
diff --git a/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/CMakeLists.txt b/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/CMakeLists.txt new file mode 100644 index 0000000..b113786 --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/CMakeLists.txt
@@ -0,0 +1,3 @@ +add_subdirectory(OpAdd) +add_subdirectory(OpMul) +add_subdirectory(OpSub)
diff --git a/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/OpAdd/CMakeLists.txt b/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/OpAdd/CMakeLists.txt new file mode 100644 index 0000000..f35da81 --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/OpAdd/CMakeLists.txt
@@ -0,0 +1,11 @@ +add_library(OpAdd OBJECT) + +target_sources(OpAdd + PRIVATE + OpAdd.cxx + + INTERFACE + FILE_SET HEADERS + FILES + OpAdd.h +)
diff --git a/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/OpAdd/OpAdd.cxx b/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/OpAdd/OpAdd.cxx new file mode 100644 index 0000000..ea11496 --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/OpAdd/OpAdd.cxx
@@ -0,0 +1,6 @@ +namespace mathfunctions { +double OpAdd(double a, double b) +{ + return a + b; +} +}
diff --git a/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/OpAdd/OpAdd.h b/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/OpAdd/OpAdd.h new file mode 100644 index 0000000..9c9efc3 --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/OpAdd/OpAdd.h
@@ -0,0 +1,5 @@ +#pragma once + +namespace mathfunctions { +double OpAdd(double a, double b); +}
diff --git a/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/OpMul/CMakeLists.txt b/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/OpMul/CMakeLists.txt new file mode 100644 index 0000000..f494fc6 --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/OpMul/CMakeLists.txt
@@ -0,0 +1,11 @@ +add_library(OpMul OBJECT) + +target_sources(OpMul + PRIVATE + OpMul.cxx + + INTERFACE + FILE_SET HEADERS + FILES + OpMul.h +)
diff --git a/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/OpMul/OpMul.cxx b/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/OpMul/OpMul.cxx new file mode 100644 index 0000000..c8eb016 --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/OpMul/OpMul.cxx
@@ -0,0 +1,6 @@ +namespace mathfunctions { +double OpMul(double a, double b) +{ + return a * b; +} +}
diff --git a/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/OpMul/OpMul.h b/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/OpMul/OpMul.h new file mode 100644 index 0000000..52b467b --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/OpMul/OpMul.h
@@ -0,0 +1,5 @@ +#pragma once + +namespace mathfunctions { +double OpMul(double a, double b); +}
diff --git a/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/OpSub/CMakeLists.txt b/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/OpSub/CMakeLists.txt new file mode 100644 index 0000000..1a108fd --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/OpSub/CMakeLists.txt
@@ -0,0 +1,11 @@ +add_library(OpSub OBJECT) + +target_sources(OpSub + PRIVATE + OpSub.cxx + + INTERFACE + FILE_SET HEADERS + FILES + OpSub.h +)
diff --git a/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/OpSub/OpSub.cxx b/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/OpSub/OpSub.cxx new file mode 100644 index 0000000..b7b35da --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/OpSub/OpSub.cxx
@@ -0,0 +1,6 @@ +namespace mathfunctions { +double OpSub(double a, double b) +{ + return a - b; +} +}
diff --git a/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/OpSub/OpSub.h b/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/OpSub/OpSub.h new file mode 100644 index 0000000..1406733 --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/MathExtensions/OpSub/OpSub.h
@@ -0,0 +1,5 @@ +#pragma once + +namespace mathfunctions { +double OpSub(double a, double b); +}
diff --git a/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.cxx index dc28b4b..9da2656 100644 --- a/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.cxx +++ b/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.cxx
@@ -1,19 +1,102 @@ -#include "MathFunctions.h" - #include <cmath> +#include <format> -#ifdef USE_MYMATH -# include "mysqrt.h" +#include <MathLogger.h> + +#ifdef TUTORIAL_USE_SSE2 +# include <emmintrin.h> #endif +namespace { + +mathlogger::Logger Logger; + +#if defined(TUTORIAL_USE_GNU_BUILTIN) +typedef double v2df __attribute__((vector_size(16))); + +double gnu_mysqrt(double x) +{ + v2df root = __builtin_ia32_sqrtsd(v2df{ x, 0.0 }); + double result = root[0]; + Logger.Log(std::format("Computed sqrt of {} to be {} with GNU-builtins\n", x, + result)); + return result; +} +#elif defined(TUTORIAL_USE_SSE2) +double sse2_mysqrt(double x) +{ + __m128d root = _mm_sqrt_sd(_mm_setzero_pd(), _mm_set_sd(x)); + double result = _mm_cvtsd_f64(root); + Logger.Log( + std::format("Computed sqrt of {} to be {} with SSE2\n", x, result)); + return result; +} +#endif + +// a hack square root calculation using simple operations +double fallback_mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + double result = x; + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + + Logger.Log(std::format("Computing sqrt of {} to be {}\n", x, result)); + } + return result; +} + +// TODO10: Replace this hardcoded sqrtTable with #include <SqrtTable.h> +double sqrtTable[] = { 0, 1, 1, 2, 2, 2, 2, 3, 3, 3 }; + +double table_sqrt(double x) +{ + double result = sqrtTable[static_cast<int>(x)]; + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + } + Logger.Log( + std::format("Computed sqrt of {} to be {} with TableSqrt\n", x, result)); + return result; +} + +double mysqrt(double x) +{ + if (x >= 1 && x < 10) { + return table_sqrt(x); + } + +#if defined(TUTORIAL_USE_GNU_BUILTIN) + return gnu_mysqrt(x); +#elif defined(TUTORIAL_USE_SSE2) + return sse2_mysqrt(x); +#else + return fallback_mysqrt(x); +#endif +} +} + namespace mathfunctions { double sqrt(double x) { -// which square root function should we use? -#ifdef USE_MYMATH - return detail::mysqrt(x); -#else +#ifdef TUTORIAL_USE_STD_SQRT return std::sqrt(x); +#else + return mysqrt(x); #endif } }
diff --git a/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.h index d5c2f22..91cb176 100644 --- a/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.h +++ b/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.h
@@ -1,5 +1,9 @@ #pragma once +#include <OpAdd.h> +#include <OpMul.h> +#include <OpSub.h> + namespace mathfunctions { double sqrt(double x); }
diff --git a/Help/guide/tutorial/Step7/MathFunctions/MathLogger/CMakeLists.txt b/Help/guide/tutorial/Step7/MathFunctions/MathLogger/CMakeLists.txt new file mode 100644 index 0000000..b20151f --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/MathLogger/CMakeLists.txt
@@ -0,0 +1,6 @@ +add_library(MathLogger INTERFACE) + +target_sources(MathLogger + INTERFACE + FILE_SET HEADERS +)
diff --git a/Help/guide/tutorial/Step7/MathFunctions/MathLogger/MathFormatting.h b/Help/guide/tutorial/Step7/MathFunctions/MathLogger/MathFormatting.h new file mode 100644 index 0000000..3b6d61c --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/MathLogger/MathFormatting.h
@@ -0,0 +1,27 @@ +#pragma once + +#include <string> + +namespace mathlogger { + +enum LogLevel +{ + INFO, + WARN, + ERROR, +}; + +inline std::string FormatLog(LogLevel level, std::string const& message) +{ + switch (level) { + case INFO: + return "INFO: " + message; + case WARN: + return "WARN: " + message; + case ERROR: + return "ERROR: " + message; + } + return "UNKNOWN: " + message; +} + +}
diff --git a/Help/guide/tutorial/Step7/MathFunctions/MathLogger/MathLogger.h b/Help/guide/tutorial/Step7/MathFunctions/MathLogger/MathLogger.h new file mode 100644 index 0000000..ef7b31a --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/MathLogger/MathLogger.h
@@ -0,0 +1,22 @@ +#pragma once + +#include <string> + +#include "MathFormatting.h" +#include "MathOutput.h" + +namespace mathlogger { + +struct Logger +{ + LogLevel level = INFO; + + void SetLevel(LogLevel new_level) { level = new_level; } + void Log(std::string const& message) + { + std::string formatted = FormatLog(level, message); + WriteLog(formatted); + } +}; + +}
diff --git a/Help/guide/tutorial/Step7/MathFunctions/MathLogger/MathOutput.h b/Help/guide/tutorial/Step7/MathFunctions/MathLogger/MathOutput.h new file mode 100644 index 0000000..63f0aeb --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/MathLogger/MathOutput.h
@@ -0,0 +1,11 @@ +#pragma once + +#include <iostream> +#include <string> + +namespace mathlogger { +inline void WriteLog(std::string const& msg) +{ + std::cout << msg; +} +}
diff --git a/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx deleted file mode 100644 index 465b43a..0000000 --- a/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx +++ /dev/null
@@ -1,38 +0,0 @@ -#include "mysqrt.h" - -// TODO 4: include cmath -#include <iostream> - -namespace mathfunctions { -namespace detail { -// a hack square root calculation using simple operations -double mysqrt(double x) -{ - if (x <= 0) { - return 0; - } - - // TODO 5: If both HAVE_LOG and HAVE_EXP are defined, use the following: - //// double result = std::exp(std::log(x) * 0.5); - //// std::cout << "Computing sqrt of " << x << " to be " << result - //// << " using log and exp" << std::endl; - // else, use the existing logic. - - // Hint: Don't forget the #endif before returning the result! - - double result = x; - - // do ten iterations - for (int i = 0; i < 10; ++i) { - if (result <= 0) { - result = 0.1; - } - double delta = x - (result * result); - result = result + 0.5 * delta / result; - std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; - } - - return result; -} -} -}
diff --git a/Help/guide/tutorial/Step7/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step7/MathFunctions/mysqrt.h deleted file mode 100644 index 593d41e..0000000 --- a/Help/guide/tutorial/Step7/MathFunctions/mysqrt.h +++ /dev/null
@@ -1,7 +0,0 @@ -#pragma once - -namespace mathfunctions { -namespace detail { -double mysqrt(double x); -} -}
diff --git a/Help/guide/tutorial/Step7/Tutorial/CMakeLists.txt b/Help/guide/tutorial/Step7/Tutorial/CMakeLists.txt new file mode 100644 index 0000000..3daa5ea --- /dev/null +++ b/Help/guide/tutorial/Step7/Tutorial/CMakeLists.txt
@@ -0,0 +1,29 @@ +add_executable(Tutorial) + +target_sources(Tutorial + PRIVATE + Tutorial.cxx +) + +target_link_libraries(Tutorial + PRIVATE + MathFunctions +) + +target_compile_features(Tutorial PRIVATE cxx_std_20) + +if( + (CMAKE_CXX_COMPILER_ID STREQUAL "MSVC") OR + (CMAKE_CXX_COMPILER_FRONTEND_VARIANT STREQUAL "MSVC") +) + + target_compile_options(Tutorial PRIVATE /W3) + +elseif( + (CMAKE_CXX_COMPILER_ID STREQUAL "GNU") OR + (CMAKE_CXX_COMPILER_ID MATCHES "Clang") +) + + target_compile_options(Tutorial PRIVATE -Wall) + +endif()
diff --git a/Help/guide/tutorial/Step7/Tutorial/Tutorial.cxx b/Help/guide/tutorial/Step7/Tutorial/Tutorial.cxx new file mode 100644 index 0000000..44b7831 --- /dev/null +++ b/Help/guide/tutorial/Step7/Tutorial/Tutorial.cxx
@@ -0,0 +1,26 @@ +// A simple program that computes the square root of a number +#include <format> +#include <iostream> +#include <string> + +#include <MathFunctions.h> + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + std::cout << std::format("Usage: {} number\n", argv[0]); + return 1; + } + + // convert input to double + double const inputValue = std::stod(argv[1]); + + // calculate square root + double const outputValue = mathfunctions::sqrt(inputValue); + std::cout << std::format("The square root of {} is {}\n", inputValue, + outputValue); + + double const checkValue = mathfunctions::OpMul(outputValue, outputValue); + std::cout << std::format("The square of {} is {}\n", outputValue, + checkValue); +}
diff --git a/Help/guide/tutorial/Step7/TutorialConfig.h.in b/Help/guide/tutorial/Step7/TutorialConfig.h.in deleted file mode 100644 index 7e4d7fa..0000000 --- a/Help/guide/tutorial/Step7/TutorialConfig.h.in +++ /dev/null
@@ -1,3 +0,0 @@ -// the configured options and settings for Tutorial -#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ -#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@
diff --git a/Help/guide/tutorial/Step7/tutorial.cxx b/Help/guide/tutorial/Step7/tutorial.cxx deleted file mode 100644 index 48be3c6..0000000 --- a/Help/guide/tutorial/Step7/tutorial.cxx +++ /dev/null
@@ -1,27 +0,0 @@ -// A simple program that computes the square root of a number -#include <cmath> -#include <iostream> -#include <string> - -#include "MathFunctions.h" -#include "TutorialConfig.h" - -int main(int argc, char* argv[]) -{ - if (argc < 2) { - // report version - std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." - << Tutorial_VERSION_MINOR << std::endl; - std::cout << "Usage: " << argv[0] << " number" << std::endl; - return 1; - } - - // convert input to double - double const inputValue = std::stod(argv[1]); - - double const outputValue = mathfunctions::sqrt(inputValue); - - std::cout << "The square root of " << inputValue << " is " << outputValue - << std::endl; - return 0; -}
diff --git a/Help/guide/tutorial/Step8/CMakeLists.txt b/Help/guide/tutorial/Step8/CMakeLists.txt index 97ec6aa..79f78f5 100644 --- a/Help/guide/tutorial/Step8/CMakeLists.txt +++ b/Help/guide/tutorial/Step8/CMakeLists.txt
@@ -1,70 +1,30 @@ -cmake_minimum_required(VERSION 3.15) +cmake_minimum_required(VERSION 3.23) -# set the project name and version -project(Tutorial VERSION 1.0) +project(Tutorial) -# specify the C++ standard -add_library(tutorial_compiler_flags INTERFACE) -target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) +option(TUTORIAL_BUILD_UTILITIES "Build the Tutorial executable" ON) +option(TUTORIAL_USE_STD_SQRT "Use std::sqrt" OFF) +option(TUTORIAL_ENABLE_IPO "Check for and use IPO support" ON) -# add compiler warning flags just when building this project via -# the BUILD_INTERFACE genex -set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>") -set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") -target_compile_options(tutorial_compiler_flags INTERFACE - "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>" - "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" -) +# TODO6: Add a default-ON option named BUILD_TESTING with a doc string of: +# "Enable testing and build tests" -# configure a header file to pass some of the CMake settings -# to the source code -configure_file(TutorialConfig.h.in TutorialConfig.h) +if(TUTORIAL_ENABLE_IPO) + include(CheckIPOSupported) + check_ipo_supported(RESULT result OUTPUT output) + if(result) + message("IPO is supported, enabling IPO") + set(CMAKE_INTERPROCEDURAL_OPTIMIZATION ON) + else() + message(WARNING "IPO is not supported: ${output}") + endif() +endif() -# add the MathFunctions library +if(TUTORIAL_BUILD_UTILITIES) + add_subdirectory(Tutorial) +endif() + +# TODO7: Conditional on the value of BUILD_TESTING, enable testing and add the +# Tests subdirectory to the project + add_subdirectory(MathFunctions) - -# add the executable -add_executable(Tutorial tutorial.cxx) - -target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags) - -# add the binary tree to the search path for include files -# so that we will find TutorialConfig.h -target_include_directories(Tutorial PUBLIC - "${PROJECT_BINARY_DIR}" - ) - -# add the install targets -install(TARGETS Tutorial DESTINATION bin) -install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" - DESTINATION include - ) - -# enable testing -include(CTest) - -# does the application run -add_test(NAME Runs COMMAND Tutorial 25) - -# does the usage message work? -add_test(NAME Usage COMMAND Tutorial) -set_tests_properties(Usage - PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" - ) - -# define a function to simplify adding tests -function(do_test target arg result) - add_test(NAME Comp${arg} COMMAND ${target} ${arg}) - set_tests_properties(Comp${arg} - PROPERTIES PASS_REGULAR_EXPRESSION ${result} - ) -endfunction() - -# do a bunch of result based tests -do_test(Tutorial 4 "4 is 2") -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 0.0001 "0.0001 is 0.01")
diff --git a/Help/guide/tutorial/Step8/CMakePresets.json b/Help/guide/tutorial/Step8/CMakePresets.json new file mode 100644 index 0000000..f393977 --- /dev/null +++ b/Help/guide/tutorial/Step8/CMakePresets.json
@@ -0,0 +1,15 @@ +{ + "version": 4, + "configurePresets": [ + { + "name": "tutorial", + "displayName": "Tutorial Preset", + "description": "Preset to use with the tutorial", + "binaryDir": "${sourceDir}/build", + "cacheVariables": { + "TUTORIAL_USE_STD_SQRT": "OFF", + "TUTORIAL_ENABLE_IPO": "OFF" + } + } + ] +}
diff --git a/Help/guide/tutorial/Step8/CTestConfig.cmake b/Help/guide/tutorial/Step8/CTestConfig.cmake deleted file mode 100644 index b2922fe..0000000 --- a/Help/guide/tutorial/Step8/CTestConfig.cmake +++ /dev/null
@@ -1,3 +0,0 @@ -set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") - -set(CTEST_SUBMIT_URL "https://my.cdash.org/submit.php?project=CMakeTutorial")
diff --git a/Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt index b14d180..8673342 100644 --- a/Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt
@@ -1,59 +1,54 @@ -add_library(MathFunctions MathFunctions.cxx) +add_library(MathFunctions) -# should we use our own math functions -option(USE_MYMATH "Use tutorial provided math implementation" ON) -if (USE_MYMATH) - target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") +target_sources(MathFunctions + PRIVATE + MathFunctions.cxx - # library that just does sqrt - add_library(SqrtLibrary STATIC - mysqrt.cxx - ) + PUBLIC + FILE_SET HEADERS + FILES + MathFunctions.h +) - # link SqrtLibrary to tutorial_compiler_flags - target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) +target_link_libraries(MathFunctions + PRIVATE + MathLogger + SqrtTable - # does this system provide the log and exp functions? - include(CheckCXXSourceCompiles) - check_cxx_source_compiles(" - #include <cmath> - int main() { - std::log(1.0); - return 0; - } - " HAVE_LOG) - check_cxx_source_compiles(" - #include <cmath> - int main() { - std::exp(1.0); - return 0; - } - " HAVE_EXP) + PUBLIC + OpAdd + OpMul + OpSub +) - # add compile definitions - if(HAVE_LOG AND HAVE_EXP) - target_compile_definitions(SqrtLibrary - PRIVATE "HAVE_LOG" "HAVE_EXP" - ) - endif() +target_compile_features(MathFunctions PRIVATE cxx_std_20) - target_link_libraries(MathFunctions PRIVATE SqrtLibrary) +if(TUTORIAL_USE_STD_SQRT) + target_compile_definitions(MathFunctions PRIVATE TUTORIAL_USE_STD_SQRT) endif() -# state that anybody linking to us needs to include the current source dir -# to find MathFunctions.h, while we don't. -target_include_directories(MathFunctions - INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} - ) +include(CheckIncludeFiles) +check_include_files(emmintrin.h HAS_EMMINTRIN LANGUAGE CXX) -# link MathFunctions to tutorial_compiler_flags -target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) - -# install libs -set(installable_libs MathFunctions tutorial_compiler_flags) -if(TARGET SqrtLibrary) - list(APPEND installable_libs SqrtLibrary) +if(HAS_EMMINTRIN) + target_compile_definitions(MathFunctions PRIVATE TUTORIAL_USE_SSE2) endif() -install(TARGETS ${installable_libs} DESTINATION lib) -# install include headers -install(FILES MathFunctions.h DESTINATION include) + +include(CheckSourceCompiles) +check_source_compiles(CXX + [=[ + typedef double v2df __attribute__((vector_size(16))); + int main() { + __builtin_ia32_sqrtsd(v2df{}); + } + ]=] + HAS_GNU_BUILTIN +) + +if(HAS_GNU_BUILTIN) + target_compile_definitions(MathFunctions PRIVATE TUTORIAL_USE_GNU_BUILTIN) +endif() + +add_subdirectory(MathLogger) +add_subdirectory(MathExtensions) +add_subdirectory(MakeTable)
diff --git a/Help/guide/tutorial/Step8/MathFunctions/MakeTable/CMakeLists.txt b/Help/guide/tutorial/Step8/MathFunctions/MakeTable/CMakeLists.txt new file mode 100644 index 0000000..6aa2a32 --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/MakeTable/CMakeLists.txt
@@ -0,0 +1,28 @@ +add_executable(MakeTable) + +target_sources(MakeTable + PRIVATE + MakeTable.cxx +) + +add_custom_command( + OUTPUT SqrtTable.h + COMMAND MakeTable SqrtTable.h + DEPENDS MakeTable + VERBATIM +) + +add_custom_target(RunMakeTable DEPENDS SqrtTable.h) + +add_library(SqrtTable INTERFACE) + +target_sources(SqrtTable + INTERFACE + FILE_SET HEADERS + BASE_DIRS + ${CMAKE_CURRENT_BINARY_DIR} + FILES + ${CMAKE_CURRENT_BINARY_DIR}/SqrtTable.h +) + +add_dependencies(SqrtTable RunMakeTable)
diff --git a/Help/guide/tutorial/Step8/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step8/MathFunctions/MakeTable/MakeTable.cxx similarity index 100% rename from Help/guide/tutorial/Step8/MathFunctions/MakeTable.cxx rename to Help/guide/tutorial/Step8/MathFunctions/MakeTable/MakeTable.cxx
diff --git a/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/CMakeLists.txt b/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/CMakeLists.txt new file mode 100644 index 0000000..b113786 --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/CMakeLists.txt
@@ -0,0 +1,3 @@ +add_subdirectory(OpAdd) +add_subdirectory(OpMul) +add_subdirectory(OpSub)
diff --git a/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/OpAdd/CMakeLists.txt b/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/OpAdd/CMakeLists.txt new file mode 100644 index 0000000..f35da81 --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/OpAdd/CMakeLists.txt
@@ -0,0 +1,11 @@ +add_library(OpAdd OBJECT) + +target_sources(OpAdd + PRIVATE + OpAdd.cxx + + INTERFACE + FILE_SET HEADERS + FILES + OpAdd.h +)
diff --git a/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/OpAdd/OpAdd.cxx b/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/OpAdd/OpAdd.cxx new file mode 100644 index 0000000..ea11496 --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/OpAdd/OpAdd.cxx
@@ -0,0 +1,6 @@ +namespace mathfunctions { +double OpAdd(double a, double b) +{ + return a + b; +} +}
diff --git a/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/OpAdd/OpAdd.h b/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/OpAdd/OpAdd.h new file mode 100644 index 0000000..9c9efc3 --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/OpAdd/OpAdd.h
@@ -0,0 +1,5 @@ +#pragma once + +namespace mathfunctions { +double OpAdd(double a, double b); +}
diff --git a/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/OpMul/CMakeLists.txt b/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/OpMul/CMakeLists.txt new file mode 100644 index 0000000..f494fc6 --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/OpMul/CMakeLists.txt
@@ -0,0 +1,11 @@ +add_library(OpMul OBJECT) + +target_sources(OpMul + PRIVATE + OpMul.cxx + + INTERFACE + FILE_SET HEADERS + FILES + OpMul.h +)
diff --git a/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/OpMul/OpMul.cxx b/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/OpMul/OpMul.cxx new file mode 100644 index 0000000..c8eb016 --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/OpMul/OpMul.cxx
@@ -0,0 +1,6 @@ +namespace mathfunctions { +double OpMul(double a, double b) +{ + return a * b; +} +}
diff --git a/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/OpMul/OpMul.h b/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/OpMul/OpMul.h new file mode 100644 index 0000000..52b467b --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/OpMul/OpMul.h
@@ -0,0 +1,5 @@ +#pragma once + +namespace mathfunctions { +double OpMul(double a, double b); +}
diff --git a/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/OpSub/CMakeLists.txt b/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/OpSub/CMakeLists.txt new file mode 100644 index 0000000..1a108fd --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/OpSub/CMakeLists.txt
@@ -0,0 +1,11 @@ +add_library(OpSub OBJECT) + +target_sources(OpSub + PRIVATE + OpSub.cxx + + INTERFACE + FILE_SET HEADERS + FILES + OpSub.h +)
diff --git a/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/OpSub/OpSub.cxx b/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/OpSub/OpSub.cxx new file mode 100644 index 0000000..b7b35da --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/OpSub/OpSub.cxx
@@ -0,0 +1,6 @@ +namespace mathfunctions { +double OpSub(double a, double b) +{ + return a - b; +} +}
diff --git a/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/OpSub/OpSub.h b/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/OpSub/OpSub.h new file mode 100644 index 0000000..1406733 --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/MathExtensions/OpSub/OpSub.h
@@ -0,0 +1,5 @@ +#pragma once + +namespace mathfunctions { +double OpSub(double a, double b); +}
diff --git a/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.cxx index dc28b4b..4bf8051 100644 --- a/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.cxx +++ b/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.cxx
@@ -1,19 +1,101 @@ -#include "MathFunctions.h" - #include <cmath> +#include <format> -#ifdef USE_MYMATH -# include "mysqrt.h" +#include <MathLogger.h> + +#ifdef TUTORIAL_USE_SSE2 +# include <emmintrin.h> #endif +namespace { + +mathlogger::Logger Logger; + +#if defined(TUTORIAL_USE_GNU_BUILTIN) +typedef double v2df __attribute__((vector_size(16))); + +double gnu_mysqrt(double x) +{ + v2df root = __builtin_ia32_sqrtsd(v2df{ x, 0.0 }); + double result = root[0]; + Logger.Log(std::format("Computed sqrt of {} to be {} with GNU-builtins\n", x, + result)); + return result; +} +#elif defined(TUTORIAL_USE_SSE2) +double sse2_mysqrt(double x) +{ + __m128d root = _mm_sqrt_sd(_mm_setzero_pd(), _mm_set_sd(x)); + double result = _mm_cvtsd_f64(root); + Logger.Log( + std::format("Computed sqrt of {} to be {} with SSE2\n", x, result)); + return result; +} +#endif + +// a hack square root calculation using simple operations +double fallback_mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + double result = x; + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + + Logger.Log(std::format("Computing sqrt of {} to be {}\n", x, result)); + } + return result; +} + +#include <SqrtTable.h> + +double table_sqrt(double x) +{ + double result = sqrtTable[static_cast<int>(x)]; + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + } + Logger.Log( + std::format("Computed sqrt of {} to be {} with TableSqrt\n", x, result)); + return result; +} + +double mysqrt(double x) +{ + if (x >= 1 && x < 10) { + return table_sqrt(x); + } + +#if defined(TUTORIAL_USE_GNU_BUILTIN) + return gnu_mysqrt(x); +#elif defined(TUTORIAL_USE_SSE2) + return sse2_mysqrt(x); +#else + return fallback_mysqrt(x); +#endif +} +} + namespace mathfunctions { double sqrt(double x) { -// which square root function should we use? -#ifdef USE_MYMATH - return detail::mysqrt(x); -#else +#ifdef TUTORIAL_USE_STD_SQRT return std::sqrt(x); +#else + return mysqrt(x); #endif } }
diff --git a/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.h index d5c2f22..91cb176 100644 --- a/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.h +++ b/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.h
@@ -1,5 +1,9 @@ #pragma once +#include <OpAdd.h> +#include <OpMul.h> +#include <OpSub.h> + namespace mathfunctions { double sqrt(double x); }
diff --git a/Help/guide/tutorial/Step8/MathFunctions/MathLogger/CMakeLists.txt b/Help/guide/tutorial/Step8/MathFunctions/MathLogger/CMakeLists.txt new file mode 100644 index 0000000..b20151f --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/MathLogger/CMakeLists.txt
@@ -0,0 +1,6 @@ +add_library(MathLogger INTERFACE) + +target_sources(MathLogger + INTERFACE + FILE_SET HEADERS +)
diff --git a/Help/guide/tutorial/Step8/MathFunctions/MathLogger/MathFormatting.h b/Help/guide/tutorial/Step8/MathFunctions/MathLogger/MathFormatting.h new file mode 100644 index 0000000..3b6d61c --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/MathLogger/MathFormatting.h
@@ -0,0 +1,27 @@ +#pragma once + +#include <string> + +namespace mathlogger { + +enum LogLevel +{ + INFO, + WARN, + ERROR, +}; + +inline std::string FormatLog(LogLevel level, std::string const& message) +{ + switch (level) { + case INFO: + return "INFO: " + message; + case WARN: + return "WARN: " + message; + case ERROR: + return "ERROR: " + message; + } + return "UNKNOWN: " + message; +} + +}
diff --git a/Help/guide/tutorial/Step8/MathFunctions/MathLogger/MathLogger.h b/Help/guide/tutorial/Step8/MathFunctions/MathLogger/MathLogger.h new file mode 100644 index 0000000..ef7b31a --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/MathLogger/MathLogger.h
@@ -0,0 +1,22 @@ +#pragma once + +#include <string> + +#include "MathFormatting.h" +#include "MathOutput.h" + +namespace mathlogger { + +struct Logger +{ + LogLevel level = INFO; + + void SetLevel(LogLevel new_level) { level = new_level; } + void Log(std::string const& message) + { + std::string formatted = FormatLog(level, message); + WriteLog(formatted); + } +}; + +}
diff --git a/Help/guide/tutorial/Step8/MathFunctions/MathLogger/MathOutput.h b/Help/guide/tutorial/Step8/MathFunctions/MathLogger/MathOutput.h new file mode 100644 index 0000000..63f0aeb --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/MathLogger/MathOutput.h
@@ -0,0 +1,11 @@ +#pragma once + +#include <iostream> +#include <string> + +namespace mathlogger { +inline void WriteLog(std::string const& msg) +{ + std::cout << msg; +} +}
diff --git a/Help/guide/tutorial/Step8/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step8/MathFunctions/mysqrt.cxx deleted file mode 100644 index 28ab042..0000000 --- a/Help/guide/tutorial/Step8/MathFunctions/mysqrt.cxx +++ /dev/null
@@ -1,36 +0,0 @@ -#include "mysqrt.h" - -#include <cmath> -#include <iostream> - -namespace mathfunctions { -namespace detail { -// a hack square root calculation using simple operations -double mysqrt(double x) -{ - if (x <= 0) { - return 0; - } - - // if we have both log and exp then use them -#if defined(HAVE_LOG) && defined(HAVE_EXP) - double result = std::exp(std::log(x) * 0.5); - std::cout << "Computing sqrt of " << x << " to be " << result - << " using log and exp" << std::endl; -#else - double result = x; - - // do ten iterations - for (int i = 0; i < 10; ++i) { - if (result <= 0) { - result = 0.1; - } - double delta = x - (result * result); - result = result + 0.5 * delta / result; - std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; - } -#endif - return result; -} -} -}
diff --git a/Help/guide/tutorial/Step8/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step8/MathFunctions/mysqrt.h deleted file mode 100644 index 593d41e..0000000 --- a/Help/guide/tutorial/Step8/MathFunctions/mysqrt.h +++ /dev/null
@@ -1,7 +0,0 @@ -#pragma once - -namespace mathfunctions { -namespace detail { -double mysqrt(double x); -} -}
diff --git a/Help/guide/tutorial/Step8/Tests/CMakeLists.txt b/Help/guide/tutorial/Step8/Tests/CMakeLists.txt new file mode 100644 index 0000000..ce2ca46 --- /dev/null +++ b/Help/guide/tutorial/Step8/Tests/CMakeLists.txt
@@ -0,0 +1,13 @@ +# TODO1: Add an executable target for the tests + +# TODO2: Add the TestMathFunctions.cxx file to the test target's sources + +# TODO3: Add the MathFunctions library to the test target's link libraries + +# TODO4: Write a function that takes a single operation name as an argument. +# The function will call add_test() with the operation name as the NAME +# of the test, and a COMMAND of the form: <TestTarget> <operation name> + + +# TODO5: Call the function for all four supported operations: +# add, mul, sqrt, sub
diff --git a/Help/guide/tutorial/Step8/Tests/TestMathFunctions.cxx b/Help/guide/tutorial/Step8/Tests/TestMathFunctions.cxx new file mode 100644 index 0000000..bda0bba --- /dev/null +++ b/Help/guide/tutorial/Step8/Tests/TestMathFunctions.cxx
@@ -0,0 +1,24 @@ +#include <string> + +#include <MathFunctions.h> + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + return -1; + } + + std::string op(argv[1]); + + if (op == "add") { + return mathfunctions::OpAdd(1.0, 1.0) != 2.0; + } else if (op == "mul") { + return mathfunctions::OpMul(5.0, 5.0) != 25.0; + } else if (op == "sqrt") { + return mathfunctions::sqrt(25.0) != 5.0; + } else if (op == "sub") { + return mathfunctions::OpSub(5.0, 1.0) != 4.0; + } + + return -1; +}
diff --git a/Help/guide/tutorial/Step8/Tutorial/CMakeLists.txt b/Help/guide/tutorial/Step8/Tutorial/CMakeLists.txt new file mode 100644 index 0000000..3daa5ea --- /dev/null +++ b/Help/guide/tutorial/Step8/Tutorial/CMakeLists.txt
@@ -0,0 +1,29 @@ +add_executable(Tutorial) + +target_sources(Tutorial + PRIVATE + Tutorial.cxx +) + +target_link_libraries(Tutorial + PRIVATE + MathFunctions +) + +target_compile_features(Tutorial PRIVATE cxx_std_20) + +if( + (CMAKE_CXX_COMPILER_ID STREQUAL "MSVC") OR + (CMAKE_CXX_COMPILER_FRONTEND_VARIANT STREQUAL "MSVC") +) + + target_compile_options(Tutorial PRIVATE /W3) + +elseif( + (CMAKE_CXX_COMPILER_ID STREQUAL "GNU") OR + (CMAKE_CXX_COMPILER_ID MATCHES "Clang") +) + + target_compile_options(Tutorial PRIVATE -Wall) + +endif()
diff --git a/Help/guide/tutorial/Step8/Tutorial/Tutorial.cxx b/Help/guide/tutorial/Step8/Tutorial/Tutorial.cxx new file mode 100644 index 0000000..44b7831 --- /dev/null +++ b/Help/guide/tutorial/Step8/Tutorial/Tutorial.cxx
@@ -0,0 +1,26 @@ +// A simple program that computes the square root of a number +#include <format> +#include <iostream> +#include <string> + +#include <MathFunctions.h> + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + std::cout << std::format("Usage: {} number\n", argv[0]); + return 1; + } + + // convert input to double + double const inputValue = std::stod(argv[1]); + + // calculate square root + double const outputValue = mathfunctions::sqrt(inputValue); + std::cout << std::format("The square root of {} is {}\n", inputValue, + outputValue); + + double const checkValue = mathfunctions::OpMul(outputValue, outputValue); + std::cout << std::format("The square of {} is {}\n", outputValue, + checkValue); +}
diff --git a/Help/guide/tutorial/Step8/TutorialConfig.h.in b/Help/guide/tutorial/Step8/TutorialConfig.h.in deleted file mode 100644 index 7e4d7fa..0000000 --- a/Help/guide/tutorial/Step8/TutorialConfig.h.in +++ /dev/null
@@ -1,3 +0,0 @@ -// the configured options and settings for Tutorial -#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ -#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@
diff --git a/Help/guide/tutorial/Step8/tutorial.cxx b/Help/guide/tutorial/Step8/tutorial.cxx deleted file mode 100644 index 48be3c6..0000000 --- a/Help/guide/tutorial/Step8/tutorial.cxx +++ /dev/null
@@ -1,27 +0,0 @@ -// A simple program that computes the square root of a number -#include <cmath> -#include <iostream> -#include <string> - -#include "MathFunctions.h" -#include "TutorialConfig.h" - -int main(int argc, char* argv[]) -{ - if (argc < 2) { - // report version - std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." - << Tutorial_VERSION_MINOR << std::endl; - std::cout << "Usage: " << argv[0] << " number" << std::endl; - return 1; - } - - // convert input to double - double const inputValue = std::stod(argv[1]); - - double const outputValue = mathfunctions::sqrt(inputValue); - - std::cout << "The square root of " << inputValue << " is " << outputValue - << std::endl; - return 0; -}
diff --git a/Help/guide/tutorial/Step9/CMakeLists.txt b/Help/guide/tutorial/Step9/CMakeLists.txt index 97ec6aa..7edce35 100644 --- a/Help/guide/tutorial/Step9/CMakeLists.txt +++ b/Help/guide/tutorial/Step9/CMakeLists.txt
@@ -1,70 +1,58 @@ -cmake_minimum_required(VERSION 3.15) +cmake_minimum_required(VERSION 3.23) -# set the project name and version -project(Tutorial VERSION 1.0) +# TODO9: Add a VERSION parameter to the project() command for version 1.0.0 +project(Tutorial) -# specify the C++ standard -add_library(tutorial_compiler_flags INTERFACE) -target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) +option(TUTORIAL_BUILD_UTILITIES "Build the Tutorial executable" ON) +option(TUTORIAL_USE_STD_SQRT "Use std::sqrt" OFF) +option(TUTORIAL_ENABLE_IPO "Check for and use IPO support" ON) +option(BUILD_TESTING "Enable testing and build tests" ON) -# add compiler warning flags just when building this project via -# the BUILD_INTERFACE genex -set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>") -set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") -target_compile_options(tutorial_compiler_flags INTERFACE - "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>" - "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" -) +if(TUTORIAL_ENABLE_IPO) + include(CheckIPOSupported) + check_ipo_supported(RESULT result OUTPUT output) + if(result) + message("IPO is supported, enabling IPO") + set(CMAKE_INTERPROCEDURAL_OPTIMIZATION ON) + else() + message(WARNING "IPO is not supported: ${output}") + endif() +endif() -# configure a header file to pass some of the CMake settings -# to the source code -configure_file(TutorialConfig.h.in TutorialConfig.h) +if(TUTORIAL_BUILD_UTILITIES) + add_subdirectory(Tutorial) + # TODO1: Install the Tutorial target -# add the MathFunctions library + # TODO3: Add the Tutorial target to the TutorialTargets export +endif() + +if(BUILD_TESTING) + enable_testing() + add_subdirectory(Tests) +endif() + add_subdirectory(MathFunctions) -# add the executable -add_executable(Tutorial tutorial.cxx) +# TODO4: Include the GNUInstallDirs module -target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags) +# TODO2: Install the MathFunctions, OpAdd, OpMul, OpSub, SqrtTable, and +# MathLogger targets. Ensure you name their header file set so the +# headers will be installed. -# 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}" - ) +# TODO5: Add the targets from TODO2 to the TutorialTargets export -# add the install targets -install(TARGETS Tutorial DESTINATION bin) -install(FILES "${PROJECT_BINARY_DIR}/TutorialConfig.h" - DESTINATION include - ) +# TODO6: Install the TutorialTargets export to: +# ${CMAKE_INSTALL_LIBDIR}/cmake/Tutorial +# And give them a namespace of "Tutorial::" -# enable testing -include(CTest) +# TODO10: Include CMakePackageConfigHelpers -# does the application run -add_test(NAME Runs COMMAND Tutorial 25) +# TODO11: Use write_basic_package_version_file to write a +# TutorialConfigVersion.cmake file to the CMAKE_CURRENT_BINARY_DIR. +# The version compatibility should be ExactVersion. -# does the usage message work? -add_test(NAME Usage COMMAND Tutorial) -set_tests_properties(Usage - PROPERTIES PASS_REGULAR_EXPRESSION "Usage:.*number" - ) +# TODO12: Add the generated TutorialConfigVersion.cmake file to the file list +# of the TODO7 install() command. -# define a function to simplify adding tests -function(do_test target arg result) - add_test(NAME Comp${arg} COMMAND ${target} ${arg}) - set_tests_properties(Comp${arg} - PROPERTIES PASS_REGULAR_EXPRESSION ${result} - ) -endfunction() - -# do a bunch of result based tests -do_test(Tutorial 4 "4 is 2") -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 0.0001 "0.0001 is 0.01") +# TODO7: Install the config file at cmake/TutorialConfig.cmake to the same +# destination as the TutorialTargets export.
diff --git a/Help/guide/tutorial/Step9/CMakePresets.json b/Help/guide/tutorial/Step9/CMakePresets.json new file mode 100644 index 0000000..f393977 --- /dev/null +++ b/Help/guide/tutorial/Step9/CMakePresets.json
@@ -0,0 +1,15 @@ +{ + "version": 4, + "configurePresets": [ + { + "name": "tutorial", + "displayName": "Tutorial Preset", + "description": "Preset to use with the tutorial", + "binaryDir": "${sourceDir}/build", + "cacheVariables": { + "TUTORIAL_USE_STD_SQRT": "OFF", + "TUTORIAL_ENABLE_IPO": "OFF" + } + } + ] +}
diff --git a/Help/guide/tutorial/Step9/CTestConfig.cmake b/Help/guide/tutorial/Step9/CTestConfig.cmake deleted file mode 100644 index b2922fe..0000000 --- a/Help/guide/tutorial/Step9/CTestConfig.cmake +++ /dev/null
@@ -1,3 +0,0 @@ -set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") - -set(CTEST_SUBMIT_URL "https://my.cdash.org/submit.php?project=CMakeTutorial")
diff --git a/Help/guide/tutorial/Step9/License.txt b/Help/guide/tutorial/Step9/License.txt deleted file mode 100644 index 85760e5..0000000 --- a/Help/guide/tutorial/Step9/License.txt +++ /dev/null
@@ -1,2 +0,0 @@ -This is the open source License.txt file introduced in -CMake/Tutorial/Step9...
diff --git a/Help/guide/tutorial/Step9/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step9/MathFunctions/CMakeLists.txt index 5addc6d..8673342 100644 --- a/Help/guide/tutorial/Step9/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step9/MathFunctions/CMakeLists.txt
@@ -1,44 +1,54 @@ -add_library(MathFunctions MathFunctions.cxx) +add_library(MathFunctions) -# state that anybody linking to us needs to include the current source dir -# to find MathFunctions.h, while we don't. -target_include_directories(MathFunctions - INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} - ) +target_sources(MathFunctions + PRIVATE + MathFunctions.cxx -# should we use our own math functions -option(USE_MYMATH "Use tutorial provided math implementation" ON) -if (USE_MYMATH) - target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") + PUBLIC + FILE_SET HEADERS + FILES + MathFunctions.h +) - # generate Table.h - include(MakeTable.cmake) +target_link_libraries(MathFunctions + PRIVATE + MathLogger + SqrtTable - # library that just does sqrt - add_library(SqrtLibrary STATIC - mysqrt.cxx - ${CMAKE_CURRENT_BINARY_DIR}/Table.h - ) + PUBLIC + OpAdd + OpMul + OpSub +) - # state that we depend on our binary dir to find Table.h - target_include_directories(SqrtLibrary PRIVATE - ${CMAKE_CURRENT_BINARY_DIR} - ) +target_compile_features(MathFunctions PRIVATE cxx_std_20) - # link SqrtLibrary to tutorial_compiler_flags - target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) - - target_link_libraries(MathFunctions PRIVATE SqrtLibrary) +if(TUTORIAL_USE_STD_SQRT) + target_compile_definitions(MathFunctions PRIVATE TUTORIAL_USE_STD_SQRT) endif() -# link MathFunctions to tutorial_compiler_flags -target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) +include(CheckIncludeFiles) +check_include_files(emmintrin.h HAS_EMMINTRIN LANGUAGE CXX) -# install libs -set(installable_libs MathFunctions tutorial_compiler_flags) -if(TARGET SqrtLibrary) - list(APPEND installable_libs SqrtLibrary) +if(HAS_EMMINTRIN) + target_compile_definitions(MathFunctions PRIVATE TUTORIAL_USE_SSE2) endif() -install(TARGETS ${installable_libs} DESTINATION lib) -# install include headers -install(FILES MathFunctions.h DESTINATION include) + +include(CheckSourceCompiles) +check_source_compiles(CXX + [=[ + typedef double v2df __attribute__((vector_size(16))); + int main() { + __builtin_ia32_sqrtsd(v2df{}); + } + ]=] + HAS_GNU_BUILTIN +) + +if(HAS_GNU_BUILTIN) + target_compile_definitions(MathFunctions PRIVATE TUTORIAL_USE_GNU_BUILTIN) +endif() + +add_subdirectory(MathLogger) +add_subdirectory(MathExtensions) +add_subdirectory(MakeTable)
diff --git a/Help/guide/tutorial/Step9/MathFunctions/MakeTable.cmake b/Help/guide/tutorial/Step9/MathFunctions/MakeTable.cmake deleted file mode 100644 index 12865a9..0000000 --- a/Help/guide/tutorial/Step9/MathFunctions/MakeTable.cmake +++ /dev/null
@@ -1,10 +0,0 @@ -# first we add the executable that generates the table -add_executable(MakeTable MakeTable.cxx) -target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags) - -# add the command to generate the source code -add_custom_command( - OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h - COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h - DEPENDS MakeTable - )
diff --git a/Help/guide/tutorial/Step9/MathFunctions/MakeTable/CMakeLists.txt b/Help/guide/tutorial/Step9/MathFunctions/MakeTable/CMakeLists.txt new file mode 100644 index 0000000..6aa2a32 --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/MakeTable/CMakeLists.txt
@@ -0,0 +1,28 @@ +add_executable(MakeTable) + +target_sources(MakeTable + PRIVATE + MakeTable.cxx +) + +add_custom_command( + OUTPUT SqrtTable.h + COMMAND MakeTable SqrtTable.h + DEPENDS MakeTable + VERBATIM +) + +add_custom_target(RunMakeTable DEPENDS SqrtTable.h) + +add_library(SqrtTable INTERFACE) + +target_sources(SqrtTable + INTERFACE + FILE_SET HEADERS + BASE_DIRS + ${CMAKE_CURRENT_BINARY_DIR} + FILES + ${CMAKE_CURRENT_BINARY_DIR}/SqrtTable.h +) + +add_dependencies(SqrtTable RunMakeTable)
diff --git a/Help/guide/tutorial/Step9/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step9/MathFunctions/MakeTable/MakeTable.cxx similarity index 100% rename from Help/guide/tutorial/Step9/MathFunctions/MakeTable.cxx rename to Help/guide/tutorial/Step9/MathFunctions/MakeTable/MakeTable.cxx
diff --git a/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/CMakeLists.txt b/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/CMakeLists.txt new file mode 100644 index 0000000..b113786 --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/CMakeLists.txt
@@ -0,0 +1,3 @@ +add_subdirectory(OpAdd) +add_subdirectory(OpMul) +add_subdirectory(OpSub)
diff --git a/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/OpAdd/CMakeLists.txt b/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/OpAdd/CMakeLists.txt new file mode 100644 index 0000000..f35da81 --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/OpAdd/CMakeLists.txt
@@ -0,0 +1,11 @@ +add_library(OpAdd OBJECT) + +target_sources(OpAdd + PRIVATE + OpAdd.cxx + + INTERFACE + FILE_SET HEADERS + FILES + OpAdd.h +)
diff --git a/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/OpAdd/OpAdd.cxx b/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/OpAdd/OpAdd.cxx new file mode 100644 index 0000000..ea11496 --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/OpAdd/OpAdd.cxx
@@ -0,0 +1,6 @@ +namespace mathfunctions { +double OpAdd(double a, double b) +{ + return a + b; +} +}
diff --git a/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/OpAdd/OpAdd.h b/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/OpAdd/OpAdd.h new file mode 100644 index 0000000..9c9efc3 --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/OpAdd/OpAdd.h
@@ -0,0 +1,5 @@ +#pragma once + +namespace mathfunctions { +double OpAdd(double a, double b); +}
diff --git a/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/OpMul/CMakeLists.txt b/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/OpMul/CMakeLists.txt new file mode 100644 index 0000000..f494fc6 --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/OpMul/CMakeLists.txt
@@ -0,0 +1,11 @@ +add_library(OpMul OBJECT) + +target_sources(OpMul + PRIVATE + OpMul.cxx + + INTERFACE + FILE_SET HEADERS + FILES + OpMul.h +)
diff --git a/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/OpMul/OpMul.cxx b/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/OpMul/OpMul.cxx new file mode 100644 index 0000000..c8eb016 --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/OpMul/OpMul.cxx
@@ -0,0 +1,6 @@ +namespace mathfunctions { +double OpMul(double a, double b) +{ + return a * b; +} +}
diff --git a/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/OpMul/OpMul.h b/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/OpMul/OpMul.h new file mode 100644 index 0000000..52b467b --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/OpMul/OpMul.h
@@ -0,0 +1,5 @@ +#pragma once + +namespace mathfunctions { +double OpMul(double a, double b); +}
diff --git a/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/OpSub/CMakeLists.txt b/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/OpSub/CMakeLists.txt new file mode 100644 index 0000000..1a108fd --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/OpSub/CMakeLists.txt
@@ -0,0 +1,11 @@ +add_library(OpSub OBJECT) + +target_sources(OpSub + PRIVATE + OpSub.cxx + + INTERFACE + FILE_SET HEADERS + FILES + OpSub.h +)
diff --git a/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/OpSub/OpSub.cxx b/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/OpSub/OpSub.cxx new file mode 100644 index 0000000..b7b35da --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/OpSub/OpSub.cxx
@@ -0,0 +1,6 @@ +namespace mathfunctions { +double OpSub(double a, double b) +{ + return a - b; +} +}
diff --git a/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/OpSub/OpSub.h b/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/OpSub/OpSub.h new file mode 100644 index 0000000..1406733 --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/MathExtensions/OpSub/OpSub.h
@@ -0,0 +1,5 @@ +#pragma once + +namespace mathfunctions { +double OpSub(double a, double b); +}
diff --git a/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.cxx index dc28b4b..4bf8051 100644 --- a/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.cxx +++ b/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.cxx
@@ -1,19 +1,101 @@ -#include "MathFunctions.h" - #include <cmath> +#include <format> -#ifdef USE_MYMATH -# include "mysqrt.h" +#include <MathLogger.h> + +#ifdef TUTORIAL_USE_SSE2 +# include <emmintrin.h> #endif +namespace { + +mathlogger::Logger Logger; + +#if defined(TUTORIAL_USE_GNU_BUILTIN) +typedef double v2df __attribute__((vector_size(16))); + +double gnu_mysqrt(double x) +{ + v2df root = __builtin_ia32_sqrtsd(v2df{ x, 0.0 }); + double result = root[0]; + Logger.Log(std::format("Computed sqrt of {} to be {} with GNU-builtins\n", x, + result)); + return result; +} +#elif defined(TUTORIAL_USE_SSE2) +double sse2_mysqrt(double x) +{ + __m128d root = _mm_sqrt_sd(_mm_setzero_pd(), _mm_set_sd(x)); + double result = _mm_cvtsd_f64(root); + Logger.Log( + std::format("Computed sqrt of {} to be {} with SSE2\n", x, result)); + return result; +} +#endif + +// a hack square root calculation using simple operations +double fallback_mysqrt(double x) +{ + if (x <= 0) { + return 0; + } + + double result = x; + + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + + Logger.Log(std::format("Computing sqrt of {} to be {}\n", x, result)); + } + return result; +} + +#include <SqrtTable.h> + +double table_sqrt(double x) +{ + double result = sqrtTable[static_cast<int>(x)]; + // do ten iterations + for (int i = 0; i < 10; ++i) { + if (result <= 0) { + result = 0.1; + } + double delta = x - (result * result); + result = result + 0.5 * delta / result; + } + Logger.Log( + std::format("Computed sqrt of {} to be {} with TableSqrt\n", x, result)); + return result; +} + +double mysqrt(double x) +{ + if (x >= 1 && x < 10) { + return table_sqrt(x); + } + +#if defined(TUTORIAL_USE_GNU_BUILTIN) + return gnu_mysqrt(x); +#elif defined(TUTORIAL_USE_SSE2) + return sse2_mysqrt(x); +#else + return fallback_mysqrt(x); +#endif +} +} + namespace mathfunctions { double sqrt(double x) { -// which square root function should we use? -#ifdef USE_MYMATH - return detail::mysqrt(x); -#else +#ifdef TUTORIAL_USE_STD_SQRT return std::sqrt(x); +#else + return mysqrt(x); #endif } }
diff --git a/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.h index d5c2f22..91cb176 100644 --- a/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.h +++ b/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.h
@@ -1,5 +1,9 @@ #pragma once +#include <OpAdd.h> +#include <OpMul.h> +#include <OpSub.h> + namespace mathfunctions { double sqrt(double x); }
diff --git a/Help/guide/tutorial/Step9/MathFunctions/MathLogger/CMakeLists.txt b/Help/guide/tutorial/Step9/MathFunctions/MathLogger/CMakeLists.txt new file mode 100644 index 0000000..b20151f --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/MathLogger/CMakeLists.txt
@@ -0,0 +1,6 @@ +add_library(MathLogger INTERFACE) + +target_sources(MathLogger + INTERFACE + FILE_SET HEADERS +)
diff --git a/Help/guide/tutorial/Step9/MathFunctions/MathLogger/MathFormatting.h b/Help/guide/tutorial/Step9/MathFunctions/MathLogger/MathFormatting.h new file mode 100644 index 0000000..3b6d61c --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/MathLogger/MathFormatting.h
@@ -0,0 +1,27 @@ +#pragma once + +#include <string> + +namespace mathlogger { + +enum LogLevel +{ + INFO, + WARN, + ERROR, +}; + +inline std::string FormatLog(LogLevel level, std::string const& message) +{ + switch (level) { + case INFO: + return "INFO: " + message; + case WARN: + return "WARN: " + message; + case ERROR: + return "ERROR: " + message; + } + return "UNKNOWN: " + message; +} + +}
diff --git a/Help/guide/tutorial/Step9/MathFunctions/MathLogger/MathLogger.h b/Help/guide/tutorial/Step9/MathFunctions/MathLogger/MathLogger.h new file mode 100644 index 0000000..ef7b31a --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/MathLogger/MathLogger.h
@@ -0,0 +1,22 @@ +#pragma once + +#include <string> + +#include "MathFormatting.h" +#include "MathOutput.h" + +namespace mathlogger { + +struct Logger +{ + LogLevel level = INFO; + + void SetLevel(LogLevel new_level) { level = new_level; } + void Log(std::string const& message) + { + std::string formatted = FormatLog(level, message); + WriteLog(formatted); + } +}; + +}
diff --git a/Help/guide/tutorial/Step9/MathFunctions/MathLogger/MathOutput.h b/Help/guide/tutorial/Step9/MathFunctions/MathLogger/MathOutput.h new file mode 100644 index 0000000..63f0aeb --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/MathLogger/MathOutput.h
@@ -0,0 +1,11 @@ +#pragma once + +#include <iostream> +#include <string> + +namespace mathlogger { +inline void WriteLog(std::string const& msg) +{ + std::cout << msg; +} +}
diff --git a/Help/guide/tutorial/Step9/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step9/MathFunctions/mysqrt.cxx deleted file mode 100644 index 477d715..0000000 --- a/Help/guide/tutorial/Step9/MathFunctions/mysqrt.cxx +++ /dev/null
@@ -1,37 +0,0 @@ -#include "mysqrt.h" - -#include <iostream> - -// include the generated table -#include "Table.h" - -namespace mathfunctions { -namespace detail { -// a hack square root calculation using simple operations -double mysqrt(double x) -{ - if (x <= 0) { - return 0; - } - - // use the table to help find an initial value - double result = x; - if (x >= 1 && x < 10) { - std::cout << "Use the table to help find an initial value " << std::endl; - result = sqrtTable[static_cast<int>(x)]; - } - - // do ten iterations - for (int i = 0; i < 10; ++i) { - if (result <= 0) { - result = 0.1; - } - double delta = x - (result * result); - result = result + 0.5 * delta / result; - std::cout << "Computing sqrt of " << x << " to be " << result << std::endl; - } - - return result; -} -} -}
diff --git a/Help/guide/tutorial/Step9/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step9/MathFunctions/mysqrt.h deleted file mode 100644 index 593d41e..0000000 --- a/Help/guide/tutorial/Step9/MathFunctions/mysqrt.h +++ /dev/null
@@ -1,7 +0,0 @@ -#pragma once - -namespace mathfunctions { -namespace detail { -double mysqrt(double x); -} -}
diff --git a/Help/guide/tutorial/Step9/Tests/CMakeLists.txt b/Help/guide/tutorial/Step9/Tests/CMakeLists.txt new file mode 100644 index 0000000..c6750ae --- /dev/null +++ b/Help/guide/tutorial/Step9/Tests/CMakeLists.txt
@@ -0,0 +1,23 @@ +add_executable(TestMathFunctions) + +target_sources(TestMathFunctions + PRIVATE + TestMathFunctions.cxx +) + +target_link_libraries(TestMathFunctions + PRIVATE + MathFunctions +) + +function(MathFunctionTest op) + add_test( + NAME ${op} + COMMAND TestMathFunctions ${op} + ) +endfunction() + +MathFunctionTest(add) +MathFunctionTest(mul) +MathFunctionTest(sqrt) +MathFunctionTest(sub)
diff --git a/Help/guide/tutorial/Step9/Tests/TestMathFunctions.cxx b/Help/guide/tutorial/Step9/Tests/TestMathFunctions.cxx new file mode 100644 index 0000000..bda0bba --- /dev/null +++ b/Help/guide/tutorial/Step9/Tests/TestMathFunctions.cxx
@@ -0,0 +1,24 @@ +#include <string> + +#include <MathFunctions.h> + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + return -1; + } + + std::string op(argv[1]); + + if (op == "add") { + return mathfunctions::OpAdd(1.0, 1.0) != 2.0; + } else if (op == "mul") { + return mathfunctions::OpMul(5.0, 5.0) != 25.0; + } else if (op == "sqrt") { + return mathfunctions::sqrt(25.0) != 5.0; + } else if (op == "sub") { + return mathfunctions::OpSub(5.0, 1.0) != 4.0; + } + + return -1; +}
diff --git a/Help/guide/tutorial/Step9/Tutorial/CMakeLists.txt b/Help/guide/tutorial/Step9/Tutorial/CMakeLists.txt new file mode 100644 index 0000000..3daa5ea --- /dev/null +++ b/Help/guide/tutorial/Step9/Tutorial/CMakeLists.txt
@@ -0,0 +1,29 @@ +add_executable(Tutorial) + +target_sources(Tutorial + PRIVATE + Tutorial.cxx +) + +target_link_libraries(Tutorial + PRIVATE + MathFunctions +) + +target_compile_features(Tutorial PRIVATE cxx_std_20) + +if( + (CMAKE_CXX_COMPILER_ID STREQUAL "MSVC") OR + (CMAKE_CXX_COMPILER_FRONTEND_VARIANT STREQUAL "MSVC") +) + + target_compile_options(Tutorial PRIVATE /W3) + +elseif( + (CMAKE_CXX_COMPILER_ID STREQUAL "GNU") OR + (CMAKE_CXX_COMPILER_ID MATCHES "Clang") +) + + target_compile_options(Tutorial PRIVATE -Wall) + +endif()
diff --git a/Help/guide/tutorial/Step9/Tutorial/Tutorial.cxx b/Help/guide/tutorial/Step9/Tutorial/Tutorial.cxx new file mode 100644 index 0000000..44b7831 --- /dev/null +++ b/Help/guide/tutorial/Step9/Tutorial/Tutorial.cxx
@@ -0,0 +1,26 @@ +// A simple program that computes the square root of a number +#include <format> +#include <iostream> +#include <string> + +#include <MathFunctions.h> + +int main(int argc, char* argv[]) +{ + if (argc < 2) { + std::cout << std::format("Usage: {} number\n", argv[0]); + return 1; + } + + // convert input to double + double const inputValue = std::stod(argv[1]); + + // calculate square root + double const outputValue = mathfunctions::sqrt(inputValue); + std::cout << std::format("The square root of {} is {}\n", inputValue, + outputValue); + + double const checkValue = mathfunctions::OpMul(outputValue, outputValue); + std::cout << std::format("The square of {} is {}\n", outputValue, + checkValue); +}
diff --git a/Help/guide/tutorial/Step9/TutorialConfig.h.in b/Help/guide/tutorial/Step9/TutorialConfig.h.in deleted file mode 100644 index 7e4d7fa..0000000 --- a/Help/guide/tutorial/Step9/TutorialConfig.h.in +++ /dev/null
@@ -1,3 +0,0 @@ -// the configured options and settings for Tutorial -#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ -#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@
diff --git a/Help/guide/tutorial/Step9/cmake/TutorialConfig.cmake b/Help/guide/tutorial/Step9/cmake/TutorialConfig.cmake new file mode 100644 index 0000000..f8e61ea --- /dev/null +++ b/Help/guide/tutorial/Step9/cmake/TutorialConfig.cmake
@@ -0,0 +1,2 @@ +# TODO8: Include the TutorialTargets.cmake file, it will be located in the same +# list directory as this file when it is run.
diff --git a/Help/guide/tutorial/Step9/tutorial.cxx b/Help/guide/tutorial/Step9/tutorial.cxx deleted file mode 100644 index 48be3c6..0000000 --- a/Help/guide/tutorial/Step9/tutorial.cxx +++ /dev/null
@@ -1,27 +0,0 @@ -// A simple program that computes the square root of a number -#include <cmath> -#include <iostream> -#include <string> - -#include "MathFunctions.h" -#include "TutorialConfig.h" - -int main(int argc, char* argv[]) -{ - if (argc < 2) { - // report version - std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "." - << Tutorial_VERSION_MINOR << std::endl; - std::cout << "Usage: " << argv[0] << " number" << std::endl; - return 1; - } - - // convert input to double - double const inputValue = std::stod(argv[1]); - - double const outputValue = mathfunctions::sqrt(inputValue); - - std::cout << "The square root of " << inputValue << " is " << outputValue - << std::endl; - return 0; -}
diff --git a/Help/guide/tutorial/Testing and CTest.rst b/Help/guide/tutorial/Testing and CTest.rst new file mode 100644 index 0000000..360b383 --- /dev/null +++ b/Help/guide/tutorial/Testing and CTest.rst
@@ -0,0 +1,232 @@ +Step 8: Testing and CTest +========================= + +Testing is, historically, not the role of the build system. At best it might +have a specific target which maps to building and running the project's tests. + +In the CMake ecosystem, the opposite is true. CMake's testing ecosystem is +known as CTest. This ecosystem is both deceivingly simple and incredibly +powerful. In fact it is so powerful it deserves its own full tutorial to +describe everything we could achieve with it. + +This is not that tutorial. In this step, we will scratch the surface of some +of the facilities that CTest provides. + +Background +^^^^^^^^^^ + +At its core, CTest is a task launcher which runs commands and reports if they +have returned zero or non-zero values. This is the level we will be dealing +with CTest at. + +CMake provides direct integration with CTest via the :command:`enable_testing` +and :command:`add_test` commands. These allow CMake to setup the necessary +infrastructure in the build folder for CTest to discover, run, and report +on various tests we might be interested in. + +After setting up and building tests, the easiest way to invoke CTest is to run +it directly on the build directory with: + +.. code-block:: console + + ctest --test-dir build + +Which will run all available tests. Specific tests can be run with regular +expressions. + +.. code-block:: console + + ctest --test-dir build -R SpecificTest + +CTest also has advanced mechanisms for scripting, fixtures, sanitizers, +job servers, metric reportings, and much more. See the :manual:`ctest(1)` +manual for more information. + +Exercise 1 - Adding Tests +^^^^^^^^^^^^^^^^^^^^^^^^^ + +CTest convention dictates the building and running of tests be based on a +default-``ON`` variable named :variable:`BUILD_TESTING`. When using the full +suite of CTest capabilities via the :module:`CTest` module, this +:command:`option` is setup for us. When using a more stripped-down approach to +testing, it's expected the project will setup the option (or at least one of a +similar name) on its own. + +When :variable:`BUILD_TESTING` is true, the :command:`enable_testing` command +should be called in the root CML. + +.. code-block:: cmake + + enable_testing() + +This will generate all the necessary metadata into the build tree for CTest to +find and run tests. + +Once that has been done, the :command:`add_test` command can be used to create +a test anywhere in the project. The semantics of this command are similar to +:command:`add_custom_command`; we can name an executable target as the "command". + +.. code-block:: cmake + + add_test( + NAME MyAppWithTestFlag + COMMAND MyApp --test + ) + +Goal +---- + +Add tests for the MathFunctions library to the project and run them with CTest. + +Helpful Resources +----------------- + +* :variable:`BUILD_TESTING` +* :command:`enable_testing` +* :command:`function` +* :command:`add_test` + +Files to Edit +------------- + +* ``Tests/CMakeLists.txt`` +* ``CMakeLists.txt`` + +Getting Started +--------------- + +A testing program has been written in the file ``Tests/TestMathFunctions.cxx``. +This program takes a single command line argument, the math function to be +tested, with valid values of ``add``, ``mul``, ``sqrt``, and ``sub``. The return +code is zero if the operation is recognized and the calculated value is valid, +otherwise it is non-zero. + +Complete ``TODO 1`` through ``TODO 7``. + +Build and Run +------------- + +No special configuration is needed, configure and build as usual. + +.. code-block:: console + + cmake --preset tutorial + cmake --build build + +Verify all the tests pass with CTest. + +.. note:: + + If using a multi-config generator, eg Visual Studio, it will be necessary to + specify a configuration with ``ctest -C <config> <remaining flags>``, where + ``<config>`` is a value like ``Debug`` or ``Release``. This is true whenever + using a multi-config generator, and won't be called out specifically in + future commands. + +.. code-block:: console + + ctest --test-dir build + +You can run individual tests with the :option:`-R <ctest -R>` flag. + +.. code-block:: console + + ctest --test-dir build -R sqrt + +Solution +-------- + +First we add a new executable for the tests. + +.. raw:: html + + <details><summary>TODO 1-2: Click to show/hide answer</summary> + +.. literalinclude:: Step9/Tests/CMakeLists.txt + :caption: TODO 1-2: Tests/CMakeLists.txt + :name: Tests/CMakeLists.txt-add_executable + :language: cmake + :start-at: add_executable + :end-at: TestMathFunctions.cxx + :append: ) + +.. raw:: html + + </details> + +Then we link in the library we are testing. + +.. raw:: html + + <details><summary>TODO 3: Click to show/hide answer</summary> + +.. literalinclude:: Step9/Tests/CMakeLists.txt + :caption: TODO 3: Tests/CMakeLists.txt + :name: Tests/CMakeLists.txt-target_link_libraries + :language: cmake + :start-at: target_link_libraries(TestMathFunctions + :end-at: ) + +.. raw:: html + + </details> + +We need to call :command:`add_test` for each of the valid operations, but this +would get repetitive, so we write a :command:`function` to do it for us. + +.. raw:: html + + <details><summary>TODO 4: Click to show/hide answer</summary> + +.. literalinclude:: Step9/Tests/CMakeLists.txt + :caption: TODO 4: Tests/CMakeLists.txt + :name: Tests/CMakeLists.txt-function + :language: cmake + :start-at: function + :end-at: endfunction + +.. raw:: html + + </details> + +Now we can use our :command:`function` to add all the tests. + +.. raw:: html + + <details><summary>TODO 5: Click to show/hide answer</summary> + +.. literalinclude:: Step9/Tests/CMakeLists.txt + :caption: TODO 5: Tests/CMakeLists.txt + :name: Tests/CMakeLists.txt-add_test + :language: cmake + :start-at: MathFunctionTest(add + :end-at: MathFunctionTest(sub + +.. raw:: html + + </details> + +Finally, we can add the :variable:`BUILD_TESTING` option and conditionally +enable building and running tests in the top-level CML. + +.. raw:: html + + <details><summary>TODO 6-7: Click to show/hide answer</summary> + +.. literalinclude:: Step9/CMakeLists.txt + :caption: TODO 6: CMakeLists.txt + :name: CMakeLists.txt-BUILD_TESTING + :language: cmake + :start-at: option(BUILD_TESTING + :end-at: option(BUILD_TESTING + +.. literalinclude:: Step9/CMakeLists.txt + :caption: TODO 7: CMakeLists.txt + :name: CMakeLists.txt-enable_testing + :language: cmake + :start-at: if(BUILD_TESTING) + :end-at: endif() + +.. raw:: html + + </details>
diff --git a/Help/guide/tutorial/index.rst b/Help/guide/tutorial/index.rst index 438f368..d85506f 100644 --- a/Help/guide/tutorial/index.rst +++ b/Help/guide/tutorial/index.rst
@@ -21,6 +21,28 @@ .. toctree:: :maxdepth: 2 + Before You Begin + Getting Started with CMake + CMake Language Fundamentals + Configuration and Cache Variables + In-Depth CMake Target Commands + In-Depth CMake Library Concepts + In-Depth System Introspection + Custom Commands and Generated Files + Testing and CTest + Installation Commands and Concepts + Finding Dependencies + Miscellaneous Features + +.. + 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: + A Basic Starting Point Adding a Library Adding Usage Requirements for a Library @@ -33,12 +55,3 @@ Selecting Static or Shared Libraries 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/include/ENVIRONMENT_MODIFICATION_OPS.rst b/Help/include/ENVIRONMENT_MODIFICATION_OPS.rst new file mode 100644 index 0000000..9ef4b14 --- /dev/null +++ b/Help/include/ENVIRONMENT_MODIFICATION_OPS.rst
@@ -0,0 +1,20 @@ +- ``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 singular ``VALUE`` to the current value of + ``MYVAR``. +- ``string_prepend``: Prepends singular ``VALUE`` to the current value of + ``MYVAR``. +- ``path_list_append``: Appends singular ``VALUE`` to the current value of + ``MYVAR`` using the host platform's path list separator (``;`` on Windows + and ``:`` elsewhere). +- ``path_list_prepend``: Prepends singular ``VALUE`` to the current value of + ``MYVAR`` using the host platform's path list separator (``;`` on Windows + and ``:`` elsewhere). +- ``cmake_list_append``: Appends singular ``VALUE`` to the current value of + ``MYVAR`` using ``;`` as the separator. +- ``cmake_list_prepend``: Prepends singular ``VALUE`` to the current value of + ``MYVAR`` using ``;`` as the separator.
diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 4fa878e..e9b90fb 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst
@@ -404,9 +404,14 @@ These are passed to the compiler with ``-D`` flags, or equivalent, in an unspecified order. - The :prop_tgt:`DEFINE_SYMBOL` target property is also used - as a compile definition as a special convenience case for - ``SHARED`` and ``MODULE`` library targets. + When compiling sources of a ``SHARED`` library, a ``MODULE`` library, + or an ``EXECUTABLE`` with :prop_tgt:`ENABLE_EXPORTS` enabled, CMake + automatically defines a target-specific preprocessor symbol. + By default the definition is of the form ``<target>_EXPORTS``, but it + can be overridden by the :prop_tgt:`DEFINE_SYMBOL` target property. + This allows headers to detect whether they are included from inside + their implementation sources, and to correctly set up export/import + annotations or visibility of symbols. :prop_tgt:`COMPILE_OPTIONS` List of compile options for compiling sources in the target. @@ -1443,13 +1448,9 @@ An ``INTERFACE`` library target does not compile sources and does not produce a library artifact on disk, so it has no :prop_tgt:`LOCATION`. -It may specify usage requirements such as -:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`, -:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`, -:prop_tgt:`INTERFACE_COMPILE_OPTIONS`, -:prop_tgt:`INTERFACE_LINK_LIBRARIES`, -:prop_tgt:`INTERFACE_SOURCES`, -and :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE`. +It may specify `usage requirements <Target Usage Requirements_>`_, +`compatible interface properties <Compatible Interface Properties_>`_, and +`custom transitive properties <Custom Transitive Properties_>`_. Only the ``INTERFACE`` modes of the :command:`target_include_directories`, :command:`target_compile_definitions`, :command:`target_compile_options`, :command:`target_sources`, and :command:`target_link_libraries` commands @@ -1528,3 +1529,27 @@ Here, the headers defined in the header set are installed to ``include/Eigen``. The install destination automatically becomes an include directory that is a usage requirement for consumers. + +Properties Allowed on Interface Libraries +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Since CMake 3.19, interface libraries allow setting or reading target +properties with any name, just like other target kinds always have. + +Prior to CMake 3.19, interface libraries only allowed setting or reading +target properties with a limited set of names: + +* Properties named with an ``INTERFACE_`` prefix, either builtin + `usage requirements <Target Usage Requirements_>`_, or custom names. + +* Built-in properties named with a ``COMPATIBLE_INTERFACE_`` prefix + (`compatible interface properties <Compatible Interface Properties_>`_). + +* Built-in properties :prop_tgt:`NAME`, :prop_tgt:`EXPORT_NAME`, + :prop_tgt:`EXPORT_PROPERTIES`, :prop_tgt:`MANUALLY_ADDED_DEPENDENCIES`, + :prop_tgt:`IMPORTED`, :prop_tgt:`IMPORTED_LIBNAME_<CONFIG>`, and + :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>`. + +* .. versionadded:: 3.11 + Properties named with a leading underscore (``_``) + or lowercase ASCII character.
diff --git a/Help/manual/cmake-cxxmodules.7.rst b/Help/manual/cmake-cxxmodules.7.rst index ee16e27..9dc14d2 100644 --- a/Help/manual/cmake-cxxmodules.7.rst +++ b/Help/manual/cmake-cxxmodules.7.rst
@@ -5,61 +5,46 @@ .. versionadded:: 3.28 -C++ 20 introduced the concept of "modules" to the language. The design -requires build systems to order compilations among each other to satisfy -``import`` statements reliably. CMake's implementation asks the compiler -to scan source files for module dependencies during the build, collates -scanning results to infer ordering constraints, and tells the build tool -how to dynamically update the build graph. +C++ 20 introduced the concept of ":term:`modules <C++ module>`" to the +language. The design requires :term:`build systems <build system>` to order +compilations to satisfy ``import`` statements reliably. CMake's +implementation asks the compiler to scan source files for module dependencies +during the build, collates scanning results to infer ordering constraints, and +tells the :term:`build tool` how to dynamically update the +build graph. Compilation Strategy ==================== -With C++ modules, compiling a set of C++ sources is no longer embarrassingly -parallel. That is, any given source may first require the compilation of -another source file first in order to provide a "CMI" (compiled module -interface) or "BMI" (binary module interface) that C++ compilers use to -satisfy ``import`` statements in other sources. With headers, sources could +With C++ modules, compiling a set of C++ sources is no longer +:term:`embarrassingly parallel`. That is, any given source may require the +compilation of another source file first in order to provide a +":abbr:`BMI (built module interface)`" (or +":abbr:`CMI (compiled module interface)`") that C++ compilers use to satisfy +``import`` statements in other sources. With included headers, sources could share their declarations so that any consumers could compile independently. -With modules, declarations are now generated into these BMI files by the -compiler during compilation based on the contents of the source file and its -``export`` statements. +With modules, the compiler now generates :term:`BMI` files during compilation +based on the contents of the source file and its ``export`` statements. This +means that, to ensure a correct build without having to regenerate the build +graph (by running configure and generate steps) for every source change, the +correct ordering must be determined from the source files during the build +phase. -The order necessary for compilation requires build-time resolution of the -ordering because the order is controlled by the contents of the sources. This -means that the ordering needs extracted from the source during the build to -avoid regenerating the build graph via a configure and generate phase for -every source change to get a correct build. +:term:`Build systems <build system>` must be able to order these compilations +within the build graph. There are multiple strategies that are suitable for +this, but each has advantages and disadvantages. CMake uses a "scanning" step +strategy, which is the most visible modules-related change for CMake users in +the context of the build. CMake provides multiple ways to control the +scanning behavior of source files. -The general strategy is to use a "scanner" to extract the ordering dependency -information and update the build graph with new edges between existing edges -by taking the per-source scan results (represented by `P1689R5`_ files) and -"collating" the dependencies within a target and to modules produced by -targets visible to the target. The primary task is to generate "module map" -files to pass to each compile rule with the paths to the BMIs needed to -satisfy ``import`` statements. The collator also has tasks to use the -build-time information to fill out information including ``install`` rules for -the module interface units, their BMIs, and properties for any exported -targets with C++ modules. - -.. _`P1689R5`: https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1689r5.html - -.. note:: - - CMake is focusing on correct builds before looking at performance - improvements. There are known tactics within the chosen strategy which may - offer build performance improvements. However, they are being deferred - until we have a working model against which to compare them. It is also - important to note that a tactic useful in one situation (e.g., clean - builds) may not be performant in a different situation (e.g., incremental - builds). Finding a balance and offering controls to select the tactics is - future work. +.. _cxxmodules-scanning-control: Scanning Control ================ Whether or not sources get scanned for C++ module usage is dependent on the -following queries. The first query that provides a yes/no answer is used. +following queries. The first query that provides a decision of whether to +scan or not is used. - If the source file belongs to a file set of type ``CXX_MODULES``, it will be scanned. @@ -80,11 +65,12 @@ Compiler Support ================ -Compilers which CMake natively supports module dependency scanning include: +The list of compilers for which CMake supports scanning sources for C++ +modules includes: * MSVC toolset 14.34 and newer (provided with Visual Studio 17.4 and newer) * LLVM/Clang 16.0 and newer -* GCC 14 (for the in-development branch, after 2023-09-20) and newer +* GCC 14 and newer ``import std`` Support ====================== @@ -92,51 +78,887 @@ Support for ``import std`` is limited to the following toolchain and standard library combinations: -* Clang 18.1.2 and newer with ``-stdlib=libc++`` or ``-stdlib=libstdc++`` -* MSVC toolset 14.36 and newer (provided with Visual Studio 17.6 Preview 2 and - newer) -* GCC 15 and newer. +* Clang 18.1.2 and newer with standard library ``libc++`` or ``libstdc++`` +* MSVC toolset 14.36 and newer (provided with Visual Studio 17.6 and newer) +* GCC 15 and newer -The :variable:`CMAKE_CXX_COMPILER_IMPORT_STD` variable may be used to detect -support for a standard level with the active C++ toolchain. + .. note:: + + Ubuntu prior to 26.04 ships broken ``libstdc++.modules.json`` files. + See `Ubuntu issue 2141579`_. + +.. _`Ubuntu issue 2141579`: https://bugs.launchpad.net/ubuntu/+source/gcc-15/+bug/2141579 + +The :variable:`CMAKE_CXX_COMPILER_IMPORT_STD` variable lists standard levels +which have support for ``import std`` in the active C++ toolchain. + +Additionally, only the :ref:`Ninja Generators` currently support +``import std`` at this time because :ref:`Visual Studio Generators` do not +support building :term:`BMIs <BMI>` for ``IMPORTED`` targets. .. note:: This support is provided only when experimental support for - ``import std;`` has been enabled by the + ``import std`` has been enabled by the ``CMAKE_EXPERIMENTAL_CXX_IMPORT_STD`` gate. Generator Support ================= -The list of generators which support scanning sources for C++ modules include: +The list of generators which support scanning sources for C++ modules +includes: - :generator:`Ninja` - :generator:`Ninja Multi-Config` - :generator:`Visual Studio 17 2022` +- :generator:`Visual Studio 18 2026` + +Note that the :ref:`Ninja Generators` require ``ninja`` 1.11 or newer. Limitations ----------- There are a number of known limitations of the current C++ module support in -CMake. This does not document known limitations or bugs in compilers as these +CMake. Known limitations or bugs in compilers are not listed here, as these can change over time. For all generators: -- Header units are not supported. -- No builtin support for ``import std;`` or other compiler-provided modules. - -For the Ninja Generators: - -- ``ninja`` 1.11 or newer is required. +- :term:`Header units <header unit>` are not supported. For the :ref:`Visual Studio Generators`: - Only Visual Studio 2022 and MSVC toolsets 14.34 (Visual Studio - 17.4) and newer. -- No support for exporting or installing BMI or module information. -- No support for compiling BMIs from ``IMPORTED`` targets with C++ modules - (including ``import std``). -- No diagnosis of using modules provided by ``PRIVATE`` sources from - ``PUBLIC`` module sources. + 17.4) and newer are supported. +- Exporting or installing :term:`BMI` or module information is not supported. +- Compiling :term:`BMIs <BMI>` from ``IMPORTED`` targets with C++ modules + (including ``import std``) is not supported. +- Use of modules provided by ``PRIVATE`` sources from ``PUBLIC`` module + sources is not diagnosed. + +Separately, as a design choice, CMake does not express configuration-agnostic +module maps for imported targets. The :prop_tgt:`IMPORTED_CXX_MODULES_<CONFIG>` +target property is always tied to a specific configuration. This can lead to +some friction when importing/exporting targets from/to configuration-unaware +build systems. Future work will alleviate this restriction. + +Usage +===== + +Troubleshooting CMake +--------------------- + +This section aims to answer common questions about CMake's implementation and +to help diagnose or explain errors in CMake's C++ modules support. + +File Extension Support +^^^^^^^^^^^^^^^^^^^^^^ + +CMake imposes no requirements upon file extensions for modules of any unit +type. While there are preferences that differ between toolchains (e.g., +``.ixx`` on MSVC and ``.cppm`` on Clang), there is no universally agreed-upon +extension. As such, CMake only requires that the file be recognized as a +``CXX``-language source file. By default, any recognized extension will +suffice, but the :prop_sf:`LANGUAGE` property may be used with any other +extension as well. + +File Name Requirements +^^^^^^^^^^^^^^^^^^^^^^ + +The name of a module has no relation to the name or path of the file in which +its declaration resides. The C++ standard has no requirements here and +neither does CMake. However, it may be useful to have some pattern in use +within a project for easier navigation within environments that lack IDE-like +"find symbol" functionality (e.g., on code review platforms). + +Scanning Without Modules +^^^^^^^^^^^^^^^^^^^^^^^^ + +A common problem for projects that have not yet adopted modules is unnecessary +scanning of sources. This typically happens when a C++20 project becomes +aware of CMake 3.28, or a 3.28-aware project starts using C++20. Either case +ends up setting :policy:`CMP0155` to ``NEW``, which enables scanning of C++ +sources with C++20 or newer by default. The easiest way for projects to turn +this off is to add: + +.. code-block:: cmake + + set(CMAKE_CXX_SCAN_FOR_MODULES 0) + +near the top of their top-level ``CMakeLists.txt`` file. Note that it should +**not** be in the cache, as it may otherwise affect projects using it via +``FetchContent``. Attention should also be paid to vendored projects which +may want to enable scanning for their own sources, as this would change the +default for them as well. + +Debugging Module Builds +----------------------- + +This section aims to help diagnose or explain common errors that may arise on +the build side of CMake's C++ modules support. + +Import Cycles +^^^^^^^^^^^^^ + +The C++ standard does not allow for cycles in the ``import`` graph of a +:term:`translation unit`; therefore, CMake does not either. Currently, CMake +will leave it to the :term:`build tool` to detect this based on the +:term:`dynamic dependencies` used to order module compilations. +`CMake Issue 26119`_ tracks the desire to improve the user experience in this +case. + +.. _`CMake Issue 26119`: https://gitlab.kitware.com/cmake/cmake/-/issues/26119 + +Internal Module Partition Extension +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When the implementation of building C++ modules was first investigated, it +appeared as though there existed a type of :term:`translation unit` that +represented the intersection of a :term:`partition unit` and an +:term:`implementation unit`. Initial CMake designs included specific support +for these translation units; however, after a closer reading of the standard, +these did not actually exist. These units would have had ``module M:part;`` +as their module declaration statement. The problem is that this is also the +exact syntax also used for declaring module partitions that do not contribute +to the external interface of the primary module. Only MSVC supports this +distinction. Other compilers do not and will treat such files as an +:term:`internal partition unit` and CMake will raise an error that a +module-providing C++ source must be in a ``FILE_SET`` of type ``CXX_MODULES``. + +The fix is to not use the extension, as it provides no further expressivity +over not using the extension. All :term:`implementation unit` source files +should instead only use ``module M;`` as their module declaration statement +regardless of what partition the defined entities are declared within. As an +example: + +.. code-block:: cpp + + // module-interface.cpp + export module M; + export int foo(); + + // module-impl.cpp + module M:part; // module M:part; looks like an internal partition + int foo() { return 42; } + +Instead use explicit interface/implementation separation: + +.. code-block:: cpp + + // module-interface.cpp + export module M; + export int foo(); + + // module-impl.cpp + module M; + int foo() { return 42; } + +Module Visibility +^^^^^^^^^^^^^^^^^ + +CMake enforces :term:`module visibility` between and within targets. This +essentially means that a module (say, ``I``) provided from a ``PRIVATE`` +``FILE_SET`` on a target ``T`` may not be imported by: + +- other targets depending on ``T``; or +- modules provided from a ``PUBLIC`` ``FILE_SET`` on target ``T`` itself. + +This is because, in general, all imported entities from a module must also be +importable by all potential importers of that module. Even if module ``I`` is +only used within parts of a module without the ``export`` keyword, it may +affect things within it in such a way that consumers of the module need to be +able to transitively ``import`` it to work correctly. As CMake uses the +module visibility to determine whether to install :term:`module interface +units <module interface unit>`, a ``PRIVATE`` module interface unit will not +be installed, meaning that usage of any installed module which imports ``I`` +would not work. + +Instead, import ``PRIVATE`` C++ modules only from within an +:term:`implementation unit`, as these are not exposed to consumers of any +module. + +Design +====== + +The design of CMake's C++ module support makes a number of trade-offs compared +to other designs. First, CMake's chosen design will be covered. Later +sections cover alternative designs that were not chosen for CMake's +implementation. + +Overall, the designs fall somewhere along two axes: + +.. list-table:: + + * - Explicit Dynamic + - Explicit Static + - Explicit Fixed + * - Implicit Dynamic + - Implicit Static + - Implicit Fixed + +* **Explicit** builds control which modules are visible to each translation + unit directly. For example, when compiling a source requiring a module + ``M``, the compiler will be given information which states the exact BMI + file to use when importing the ``M`` module. +* **Implicit** builds can control module visibility as well, but do so by + instead grouping :term:`BMIs <BMI>` into directories which are then searched + for files to satisfy ``import`` statements in the source file. +* **Static** builds use a static set of build commands in order to complete + the build. There must be support to add edges between nodes at build time. +* **Dynamic** builds may create new build commands during the build and + schedule any discovered work during the build. +* **Fixed** builds are generated with all module dependencies already known. + +Design Goals +------------ + +CMake's implementation of building C++ modules focuses on the following design +goals: + +1. `Correct Builds <design-goal-correct-builds_>`__ +2. `Deterministic Builds <design-goal-deterministic-builds_>`__ +3. `Support Generated Sources <design-goal-generated-sources_>`__ +4. `Static Communication <design-goal-static-communication_>`__ +5. `Minimize Regeneration <design-goal-minimize-regeneration_>`__ + +.. _design-goal-correct-builds: + +Correct Builds +^^^^^^^^^^^^^^ + +Above all else, an incorrect build is a frustrating experience for all +involved. A build which does not detect errors and instead lets a build with +detectable problems run to completion is a good way to start wild goose chase +debugging sessions. CMake errs on the side of avoiding such situations. + +.. _design-goal-deterministic-builds: + +Deterministic Builds +^^^^^^^^^^^^^^^^^^^^ + +Given an on-disk state of a build, it should be possible to determine what +steps will happen next. This does not mean that the exact order of rules +within the build that can be run concurrently is deterministic, but instead +that the set of work to be done and its results are deterministic. For +example, if there is no dependency between tasks ``A`` and ``B``, ``A`` should +have no effects on the execution of ``B`` and vice versa. + +.. _design-goal-generated-sources: + +Support Generated Sources +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Code generation is prevalent in the C++ ecosystem, so only supporting modules +in files whose content is known at configure time is not suitable. Without +supporting generated sources which use or provide modules, code generation +tools are effectively cut off from the use of modules, and any dependencies of +generated sources must also provide non-modular ways of using their interfaces +(i.e., provide headers). Given that all C++ implementations use :term:`strong +module ownership` for symbol mangling, this is problematic when such +interfaces end up referring to compiled symbols in other libraries. + +.. _design-goal-static-communication: + +Static Communication +^^^^^^^^^^^^^^^^^^^^ + +All communication between different steps of the build should be handled +statically. Given the :term:`build tools <build tool>` that CMake supports, +it is challenging to establish a controlled lifetime for a companion tool that +needs to interact during compilation. Neither ``make`` nor ``ninja`` offer a +way to start a tool at the beginning of a build and ensure it is stopped at +the end. Instead, communication with compilers is managed through input and +output files, using dependencies in the :term:`build tool` to keep everything +up-to-date. This approach enables standard debugging strategies for builds +and allows developers to run build commands directly when investigating +issues, without needing to account for other tools running in the background. + +.. _design-goal-minimize-regeneration: + +Minimize Regeneration +^^^^^^^^^^^^^^^^^^^^^ + +Active development of a build with modules should not require the build graph +to be regenerated on every change. This means that the module dependencies +must be constructed after the build graph is available. Without this, a +`correct build <design-goal-correct-builds_>`__ would need to regenerate the +build graph any time a module-aware source file is edited, as any changes may +alter module dependencies. + +It also means that all module-aware sources must be known at configure time +(even if they do not yet exist) so that the build graph can include the +commands to :term:`scan` for their dependencies. + +.. note:: + + There is a known issue with ``ninja`` which can result in an erroneous + detection of a dependency cycle when the dependency order between two + sources reverses (i.e., ``a`` importing ``b`` becomes ``b`` importing + ``a``) between two builds. See `ninja issue 2666`_ for details. + +.. _`ninja issue 2666`: https://github.com/ninja-build/ninja/issues/2666 + +Use Case Considerations +----------------------- + +The design goals described above constrain the implementation. Additionally, +mixed configurations are supported by CMake via multi-config generators such +as :generator:`Ninja Multi-Config` and :ref:`Visual Studio Generators`. This +section describes how CMake addresses these constraints. + +Selected Design +--------------- + +The general strategy CMake uses is to ":term:`scan`" sources to extract the +ordering dependency information and update the build graph with new edges +between existing edges. This is done by taking the per-source scan results +(represented by `P1689R5`_ files) and then ":term:`collating <collate>`" them +for each target with information from its dependencies. The primary task of +the collator is to generate ":term:`module map`" files to pass to each compile +rule with the paths to the :term:`BMIs <BMI>` needed to satisfy ``import`` +statements, and to inform the :term:`build tool` of dependencies needed to +satisfy those ``import`` statements during the compilation. The collator also +uses the build-time information to generate ``install`` rules for the module +interface units, their :term:`BMIs <BMI>`, and properties for any exported +targets with C++ modules. It also enforces that ``PRIVATE`` modules may not +be used by other targets or by any ``PUBLIC`` :term:`module interface unit` +within the target. + +.. _`P1689R5`: https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1689r5.html + +Implementation Details +---------------------- + +.. warning:: + + The implementation details are not a stable interface. Each version + of CMake may revise them without any attempt at providing compatibility. + External toolchain maintainers are responsible for updating their + implementations for each version of CMake they support. + +This section describes how CMake actually structures the build graph, the data +passed between various parts, and the files which contain that data. It is +intended to be used both as functional documentation and as a guide to help +those debugging a module build to understand where to locate various bits of +data. + +.. note:: + + This section documents internal implementation details that may be useful + for :manual:`toolchain file <cmake-toolchains(7)>` authors or during + debugging of a module-related issue. Projects should not need to inspect + or modify any of the variables, properties, files, or targets mentioned + here. + +Toolchain (scanning) +^^^^^^^^^^^^^^^^^^^^ + +Compilers which support modules must also provide a scanning tool. This will +usually be either the compiler itself with some extra flags or a tool shipped +with the compiler. The command template for scanning is stored in the +``CMAKE_CXX_SCANDEP_SOURCE`` variable. The command is expected to write +`P1689R5`_ results to the ``<DYNDEP_FILE>`` placeholder. Additionally, the +command should provide any :term:`discovered dependencies` to the +``<DEP_FILE>`` placeholder. This allows :term:`build tools <build tool>` to +rerun the scan if any of the dependencies of the scanning command change. + +Additionally, toolchains should set the following variables: + +* ``CMAKE_CXX_MODULE_MAP_FORMAT``: The format of the :term:`module map` + describing where dependent :term:`BMI` files for imported modules exist + during compilation. Must be one of ``gcc``, ``clang``, or ``msvc``. +* ``CMAKE_CXX_MODULE_MAP_FLAG``: The arguments used to inform the compiler of + the :term:`module map` file. It should use the ``<MODULE_MAP_FILE>`` + placeholder. +* ``CMAKE_CXX_COMPILE_BMI``: The command template to compile a :term:`BMI` + file from a :term:`module interface unit`. Used when + ``CMAKE_CXX_MODULE_BMI_ONLY_FLAG`` is not completely additive to an + object compilation template. +* ``CMAKE_CXX_MODULE_BMI_ONLY_FLAG``: The arguments used to compile only a + :term:`BMI` file from a :term:`module interface unit`. This is used when + consuming modules from external projects to compile :term:`BMI` files for + use within the current build. + +If a toolchain does not provide the ``CMAKE_CXX_COMPILE_BMI`` or +``CMAKE_CXX_MODULE_BMI_ONLY_FLAG`` variables, it will not be able to consume +modules provided by ``IMPORTED`` targets. + +Configure +^^^^^^^^^ + +During the configure step, CMake needs to track which sources care about +modules at all. See :ref:`Scanning Control <cxxmodules-scanning-control>` for +how each source determines whether it cares about modules or not. CMake +tracks these in its internal target representation structure (``cmTarget``). +The set of sources which need to be scanned may be modified using the +:command:`target_sources`, :command:`target_compile_features`, and +:command:`set_property` commands. + +Additionally, targets may use the :prop_tgt:`CXX_MODULE_STD` target property +to indicate that ``import std`` is desired within the target's sources. + +Generate +^^^^^^^^ + +During generation, CMake needs to add additional rules to ensure that the +sources providing modules can be built before sources that import those +modules. Since CMake uses a :term:`static build`, the build graph must +contain all possible commands for scanning and module generation. The +dependency edges between commands to ensure that modules are provided will +then ensure that the build graph executes correctly. This means that, while +all sources may get scanned, only modules that are actually used will be +generated. + +The first step CMake performs is to generate a :term:`synthetic target` for +each unique usage of a module-providing target. These targets are based on +other targets, but provide only :term:`BMI` files for other targets rather +than object files. This is because the compatibility of :term:`BMI` files is +extremely narrow and cannot be shared between arbitrary ``import`` instances. +Due to the internal workings of toolchains, there can generally only be a +single set of settings for a variety of flags for any one compilation, +including :term:`BMI` files for imported modules. As an example, the C++ +standard in use needs to be consistent across all modules, but there are many +settings which may cause incompatibilities. + +.. note:: + + CMake currently assumes that all usages are compatible and will only create + one set of :term:`BMIs <BMI>` for each target. This may cause build + failures where multiple :term:`BMI` files are required, but CMake only + provides one set. See `CMake Issue 25916`_ for progress on removing this + assumption. + +.. _`CMake Issue 25916`: https://gitlab.kitware.com/cmake/cmake/-/issues/25916 + +Once all of the :term:`synthetic targets <synthetic target>` are created, +CMake looks at each target that has any source that might use C++ modules and +creates a command to :term:`scan` each of them. This command will output a +`P1689R5`_-formatted file describing the C++ modules it uses and provides (if +any). It will also create a command to :term:`collate` module dependencies +for the eligible compilations. This command depends on the :term:`scan` +results of all eligible sources, information about the target itself, as well +as the :term:`collate` results of any dependent targets which provide C++ +modules. The :term:`collate` step uses a target-specific +``CXXDependInfo.json`` file which contains the following information: + +- ``compiler-*``: basic compiler information (``id``, ``frontend-variant``, + and ``simulate-id``) which is used to generate correctly formatted paths + when generating paths for the compiler +- ``cxx-modules``: a map of object files to the ``FILE_SET`` information, + which is used to enforce :term:`module visibility` and generate install + rules for :term:`module interface unit` sources +- ``module-dir``: where to place :term:`BMI` files for this target +- ``dir-{cur,top}-{src,bld}``: the source (``src``) and build (``bld``) + directories for the current directory (``cur``) and the top (``top``) of the + project, used to compute accurate relative paths for the :term:`build tool` + dynamic dependencies +- ``exports``: The list of exports which both contain the target and are + providing C++ module information, used to provide accurate module properties + on ``IMPORTED`` targets from the exported targets. +- ``bmi-installation``: installation information, used to generate install + scripts for :term:`BMI` files +- ``database-info``: information required to generate :term:`build database` + information if requested by :prop_tgt:`EXPORT_BUILD_DATABASE` +- ``sources``: list of other source files in the target, used to add to the + :term:`build database` if requested +- ``config``: the configuration for the target, used to set the appropriate + properties in generated export files +- ``language``: the language (e.g., C++ or Fortran) the + :term:`collation <collate>` metadata file is describing +- ``include-dirs`` and ``forward-modules-from-target-dirs``: unused for C++ + +Each entry in the ``cxx-modules`` map records the following: + +- ``bmi-only`` (bool): True if only the BMI, not the source of the BMI, is + available +- ``compile-features`` (list[string]): :manual:`cmake-compile-features(7)` used + to build the object +- ``compile-options`` (list[string]): compilation options/flags used to build + the object, except for those derived from ``compile-features`` +- ``definitions`` (list[string]): preprocessor defines used to build the object +- ``destination`` (string): intended install destination of the source file +- ``include-directories`` (list[string]): include directories used to build the + object +- ``name`` (string): name of the file set which owns the source file +- ``relative-directory`` (string): base path relative to which the source file + will be relocated into the install destination +- ``source`` (string): path to the source file +- ``type`` (string): type of the file set which owns the source file +- ``visibility`` (string): visibility of the file set which owns the source file + +For each compilation, CMake will also provide a :term:`module map` which will +be created during the build by the :term:`collate` command. How this is +provided to the compiler is specified by the ``CMAKE_CXX_MODULE_MAP_FORMAT`` +and ``CMAKE_CXX_MODULE_MAP_FLAG`` toolchain variables. + +Scan +^^^^ + +The compiler is expected to implement the :term:`scan` command. This is +because only the compiler itself can reliably answer preprocessor predicates +like ``__has_builtin`` in order to provide accurate module usage information +in the face of arbitrary flags that may be used when compiling sources. + +CMake names these files with the ``.ddi`` extension, which stands for "dynamic +dependency information". These files are in `P1689R5`_ format and are used by +the :term:`collate` command to perform its tasks. + +Collate +^^^^^^^ + +The :term:`collate` command performs the bulk of the work to make C++ modules +work within the build graph. It consumes the following files as input: + +- ``CXXDependInfo.json`` from the generate step +- ``.ddi`` files from the :term:`scanning <scan>` results of the target's + sources +- ``CXXModules.json`` files output from eligible dependent targets' + :term:`collate` commands + +It uses the information from these files to generate: + +- ``CXX.dd`` files to inform the :term:`build tool` of dependencies that exist + between the compilation of a source and the :term:`BMI` files of the modules + that it imports +- ``CXXModules.json`` files for use in :term:`collate` commands of depending + targets +- ``*.modmap`` files for each compilation to find :term:`BMI` files for + imported modules +- ``install-cxx-module-bmi-$<CONFIG>.cmake`` scripts for the installation of + any :term:`BMI` files (included by the ``install`` scripts) +- ``target-*-$<CONFIG>.cmake`` export files for any exports of the target to + provide the :prop_tgt:`IMPORTED_CXX_MODULES_<CONFIG>` properties +- ``CXX_build_database.json`` :term:`build database` files for the target when + the its :prop_tgt:`EXPORT_BUILD_DATABASE` property is set + +During its processing, it enforces the following guarantees: + +- :term:`BMI` usage is consistent +- :term:`module visibility` is respected + +C++ modules have the rule that only a single module of a given name may +exist within a program. This is not exactly enforceable with the existence of +private modules, but it is enforceable for public modules. The enforcement is +done by the :term:`collate` command. Part of the ``CXXModules.json`` files is +the set of modules that are transitively imported by each module it provides. +When a module is then imported, the :term:`collate` command ensures that all +modules with a given name agree upon a given :term:`BMI` file to provide that +module. + +Compile +^^^^^^^ + +Compilation uses the :term:`module map` file generated by the :term:`collate` +command to find imported modules during compilation. Because CMake only +provides the locations of modules that are discovered by the :term:`scan` +command, any modules missed by it will not be provided to the compilation. + +It is possible for toolchains to reject the :term:`BMI` file that CMake +provides to a compilation as incompatible. This is because CMake assumes that +all usages are compatible at the moment. See `CMake Issue 25916`_ for +progress on removing this assumption. + +Install +^^^^^^^ + +During installation, install scripts which have been written by the +:term:`collate` command during the build are included so that any :term:`BMI` +files are installed as needed. These need to be generated, as it is not +known what the :term:`BMI` file names will be during CMake's generation +(because CMake names the :term:`BMI` files after the module name itself). +These install scripts are included with the ``OPTIONAL`` keyword, so an +incomplete build may result in an incomplete installation as well. + +Alternative Designs +------------------- + +There are alternative designs that CMake does not implement. This section +aims to give a brief overview and to explain why they were not chosen for +CMake's implementation. + +Implicit Builds +^^^^^^^^^^^^^^^ + +An implicit build performs module builds using compile-time search paths to +make the implementation of the build simpler. This is certainly something +that can be made to work. However, CMake's goals exclude it as a solution. + +When a build uses search directory management, the compiler is directed to +place module output files into a specified directory. These directories are +then provided as search paths to any compilation allowed to use the modules +within them. + +This strategy risks running into problems with the +`Correct Builds <design-goal-correct-builds_>`__ goal. This stems from the +hazard of stale files being present in the search directories. Since the +build system is unaware of the actual files being written, it is difficult to +know which files are allowed to be deleted (e.g., using ``ninja -t cleandead`` +to remove outputs ``ninja`` has encountered but are no longer generated). +Removal of intermediate files may also cause the build to become stuck if the +outputs are not known to the build system beyond consumers reporting "usage of +file X". + +There is also a need to at least do some level of ordering of :term:`BMI` +generation commands which share an output directory. Separate directories may +be used to order groups of modules (e.g., one directory per target); +otherwise, modules within the same directory may not assume that other modules +writing to the shared directory will complete first. If module paths are +grouped accurately according to the module dependency graph, it is a small +step to being an explicit build where the files are directly specified. + +Static Scanning +^^^^^^^^^^^^^^^ + +A :term:`fixed build` performs a scan while generating the build graph and +includes the necessary dependencies up-front. In CMake's case, it would look +at the source files during the generate phase and add the dependencies +directly to the build graph. This is more likely to be suitable for a +:term:`build system` that is also its own :term:`build tool` where build graph +manipulation can be done cooperatively. + +No matter whether it is integrated or not, this strategy necessitates either a +suitable C++ parser to extract the information in the first place, or toolchain +cooperation to obtain it. While module dependency information is available to +a simpler C++ parser, dependencies may be hidden behind preprocessor +conditionals that need to be understood in order to be accurate. Of course, +choosing to not support preprocessor conditionals around ``import`` statements +is also an option, but this may severely limit external library support. + +For CMake, this strategy would mean that any change to a module-aware source +file may need to trigger regeneration of the build graph. A benign edit would +at least need to trigger the *check* for changed imports, but may skip +actually regenerating if it is unchanged. This may be less critical for a +:term:`build system` which is also its own :term:`build tool`, but it is a +direct violation of the +`Minimize Regeneration <design-goal-minimize-regeneration_>`__ goal. + +Additionally, CMake's +`Support Generated Sources <design-goal-generated-sources_>`__ goal would be +unsupportable with this strategy. CMake could defer scanning until the +generated files are available, but those sources cannot be compiled until such +a scan has been performed. This would mean that there would be some unbounded +(but finite) number of regenerations of the build graph as sources become +available. + +Module Mapping Service +^^^^^^^^^^^^^^^^^^^^^^ + +Another strategy is to run a service alongside the build that can act as an +oracle for where to place and discover modules. The compiler is instructed to +query the service with questions such as "this source is exporting module X" +and "this source is importing module Y" and receive the path to either create +or find the :term:`BMI`, respectively. In this case, the service dynamically +implements the collation logic. + +Of particular note, this conflicts with the +`Deterministic Builds <design-goal-deterministic-builds_>`__ and +`Static Communication <design-goal-static-communication_>`__ goals because the +on-disk state may not match the actual state, and coordinating the lifetime of +the :term:`build tool` itself with the service is difficult. The primary +missing feature is some signal when a build session starts and ends so that +such a service can know in what context it is answering requests. There also +needs to be a way to resume a session and detect when a session is +invalidated. No :term:`build tool` that CMake supports today has such +features. + +There are also hazards which conflict with the +`Correct Builds <design-goal-correct-builds_>`__ goal. When a module is +imported, the compiler waits for a response before continuing. However, there +is no guarantee that a (visible) module of that name even exists, so it may +wait indefinitely. While waiting for a compilation to report that it creates +that module, it may run into a dependency cycle which leaves the compilations +hanging until some resource limit is reached (probably time, or that all +possible providers of the module have not reported a module of that name). +While these compilations are waiting on answers, there is the question of how +they affect the parallelism limits of the :term:`build tool` in use. Do +compilations waiting on an answer count towards the limit and block other +compilations from launching to potentially discover the module? If they do +not, what about other resources that may be held in use by those compilations +(e.g., memory or available file descriptors)? + +Possible Future Enhancements +============================ + +This section documents possible future enhancements to CMake's support of C++ +modules. Nothing here is a guarantee of future implementation, and the +ordering is arbitrary. + +Batch Scanning +-------------- + +It is possible to scan all sources within a target at once, which should be +faster when sources share transitive includes. This does have side effects +for incremental builds, as the update of any source in the target means that +all sources in the target are scanned again. Given how much faster scanning +can be, it should be negligible to do such "extra" scanning assuming that +unchanged results do not trigger recompilations. + +BMI Modification Optimization +----------------------------- + +Currently, as with object files, compilers always update a :term:`BMI` file +even if the contents have not changed. Because modules increase the potential +scope of "non-changes" to cause (conceptually) unnecessary recompilation, it +might be useful to avoid recompilation of module consumers if the :term:`BMI` +file has not changed. This might be achieved by wrapping the compilation to +juggle the :term:`BMI` through a ``cmake -E copy_if_different`` pass with +``ninja``'s ``restat = 1`` feature to avoid recompiling importers if the +:term:`BMI` file doesn't actually change. + +.. _`easier-source-specification`: + +Easier Source Specification +--------------------------- + +The initial implementation of CMake's module support had used the "just list +sources; CMake will figure it out" pattern. However, this ran into issues +related to other metadata requirements. These were discovered while +implementing CMake support beyond just building the modules-using code. + +Conflicts with `Separate BMI Generation <separate-bmi-generation_>`__ on a +single target, as that requires knowledge of all :term:`BMI`-generating rules +at generate time. + +.. _`separate-bmi-generation`: + +Separate BMI Generation +----------------------- + +CMake currently uses a single rule to generate both the :term:`BMI` and the +object file for a compilation. At least Clang supports compiling an object +directly from the :term:`BMI`. This would be beneficial because :term:`BMI` +generation is typically faster than compilation and generating the :term:`BMI` +as a separate step allows importers to start compiling without waiting for the +object to also be generated. + +This is not supported in the current implementation as only Clang supports +generating an object directly from the :term:`BMI`. Other compilers either do +not support such a two-phase generation (GCC) or need to start object +compilation from the source again. + +Conflicts with `Easier Source Specification <easier-source-specification_>`__ +on a single target because CMake must know all :term:`BMI`-generating sources +at generate time rather than build time to create the two-phase rules. + +Module Compilation Glossary +=========================== + +.. glossary:: + + BMI + Built Module Interface. A compiler-generated binary representation of a + C++ module's interface that is required by consumers of the module. File + extensions vary by compiler. + + CMI + Compiled Module Interface. Alternative name for :term:`BMI` used by some + compilers. + + build database + A JSON file containing compilation commands, module dependencies, and + grouping information. Used for IDE integration and build analysis. + + build system + A tool that facilitates the building of software which includes a model + of how components of the build relate to each other. For example, CMake, + Meson, build2, and more. + + build tool + A build graph execution tool. For example, `ninja` and `make`. Some + build tools are also their own :term:`build system`. + + C++ module + A C++20 language feature for describing the API of a piece of software. + Intended as a replacement for headers for this purpose. + + collate + The process of aggregating module information from scanned sources to + ensure correct compilation order and to provide metadata for other parts + of the build (e.g., installation or a :term:`build database`). + + discovered dependencies + Dependencies found during the processing of a command that do not need to + be explicitly declared. + + dynamic dependencies + Dependencies which require a separate command to detect so that a further + command may have its dependencies satisfied. + + embarrassingly parallel + A set of tasks which, due to having minimal dependencies between them, + can be easily divided into many independent tasks that can be executed + concurrently. + + explicit build + A build strategy where module dependencies are explicitly specified + rather than discovered. + + fixed build + A build strategy where all module dependencies are computed and inserted + directly into the build graph. + + header unit + A header file which is used via an ``import`` statement rather than an + ``#include`` preprocessor directive. Implementations may provide support + for treating ``#include`` as ``import`` as well. + + implementation unit + A C++ :term:`translation unit` that implements module entities declared + in a module interface unit. + + implicit build + A build strategy where module dependencies are discovered by searching + for :term:`BMI` files during compilation. + + internal partition unit + A :term:`translation unit` which contains a partition name and is not + exported from the :term:`primary module interface unit`. + + module interface unit + A :term:`translation unit` that declares a module's public interface + using ``export module``. Such a unit may or may not be also be a + :term:`partition unit`. + + module map + A compiler-specific file mapping module names to BMI locations. + + module visibility + CMake's enforcement of access rules for modules based on their + declaration scope (PUBLIC/PRIVATE). + + ODR + One Definition Rule. The C++ requirement that any entity be defined + exactly once per program. + + partition unit + A :term:`translation unit` which describes a module with a partition name + (i.e., `module MODNAME:PARTITION;`). The partition may or may not use + the ``export`` keyword. If it does, it is also a + :term:`module interface unit`; otherwise, it is a + :term:`internal partition unit`. + + primary module interface unit + A :term:`module interface unit` which exports a named module that is not + a :term:`partition unit`. + + scan + The process of analyzing a :term:`translation unit` to discover module + imports and exports. + + static build + A build configuration where all compilation rules are determined at + generate time. + + strong module ownership + C++ implementations have settled on a model where the module "owns" the + symbols declared within it. In practice, this means that the module name + is included into the symbol mangling of entities declared within it. + + synthetic target + A CMake-generated build target used to supply :term:`BMIs <BMI>` to a + specific user of a module-providing target. + + translation unit + The smallest component of a compilation for a C++ program. Generally, + there is one translation unit per source file. C++ source files which do + not use C++ modules may be combined into a single translation unit.
diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index f7896e5..f43b025 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst
@@ -29,9 +29,9 @@ .. versionadded:: 3.24 The :command:`cmake_host_system_information` command offers the possibility to -query the registry on the local computer. See -:ref:`cmake_host_system(QUERY_WINDOWS_REGISTRY) <Query Windows registry>` for -more information. +query the registry on the local computer. See the +:command:`cmake_host_system_information(QUERY WINDOWS_REGISTRY)` sub-command +for more information. .. _`Find Using Windows Registry`: @@ -154,7 +154,7 @@ ``Foo_FIND_COMPONENTS`` if it is set , and only set ``Foo_FOUND`` to true if for each searched-for component ``<c>`` that was not found, ``Foo_FIND_REQUIRED_<c>`` is not set to true. The ``HANDLE_COMPONENTS`` -argument of ``find_package_handle_standard_args()`` can be used to +argument of :command:`find_package_handle_standard_args` can be used to implement this. If ``Foo_FIND_COMPONENTS`` is not set, which modules are searched for @@ -361,10 +361,10 @@ Result Variables ^^^^^^^^^^^^^^^^ - This will define the following variables: + This module defines the following variables: ``Foo_FOUND`` - True if the system has the Foo library. + Boolean indicating whether (the requested version of) Foo was found. ``Foo_VERSION`` The version of the Foo library which was found. ``Foo_INCLUDE_DIRS`` @@ -415,7 +415,7 @@ .. code-block:: cmake find_package(PkgConfig) - if(PKG_CONFIG_FOUND) + if(PkgConfig_FOUND) pkg_check_modules(PC_Foo QUIET Foo) endif()
diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index e493655..f1b1cb1 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst
@@ -44,6 +44,7 @@ /envvar/ADSP_ROOT /envvar/CMAKE_APPLE_SILICON_PROCESSOR + /envvar/CMAKE_AUTOGEN_INTERMEDIATE_DIR_STRATEGY /envvar/CMAKE_BUILD_PARALLEL_LEVEL /envvar/CMAKE_BUILD_TYPE /envvar/CMAKE_COLOR_DIAGNOSTICS @@ -53,6 +54,7 @@ /envvar/CMAKE_CROSSCOMPILING_EMULATOR /envvar/CMAKE_EXPORT_BUILD_DATABASE /envvar/CMAKE_EXPORT_COMPILE_COMMANDS + /envvar/CMAKE_FASTBUILD_VERBOSE_GENERATOR /envvar/CMAKE_GENERATOR /envvar/CMAKE_GENERATOR_INSTANCE /envvar/CMAKE_GENERATOR_PLATFORM @@ -60,6 +62,7 @@ /envvar/CMAKE_INSTALL_MODE /envvar/CMAKE_INSTALL_PARALLEL_LEVEL /envvar/CMAKE_INSTALL_PREFIX + /envvar/CMAKE_INTERMEDIATE_DIR_STRATEGY /envvar/CMAKE_LANG_COMPILER_LAUNCHER /envvar/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES_EXCLUDE /envvar/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES_EXCLUDE
diff --git a/Help/manual/cmake-file-api.7.rst b/Help/manual/cmake-file-api.7.rst index 058e4aa..857d498 100644 --- a/Help/manual/cmake-file-api.7.rst +++ b/Help/manual/cmake-file-api.7.rst
@@ -125,6 +125,10 @@ This can be used to avoid asking CMake to generate multiple object versions unnecessarily. +.. versionadded:: 4.1 + The ``query.json`` file is described in machine-readable form by + :download:`this JSON schema </manual/file_api/schema_stateful_query.json>`. + A ``query.json`` file must contain a JSON object: .. code-block:: json @@ -200,6 +204,10 @@ the one with the largest name in lexicographic order is the current index file. +.. versionadded:: 4.1 + The reply index file is described in machine-readable form by + :download:`this JSON schema </manual/file_api/schema_index.json>`. + The reply index file contains a JSON object: .. code-block:: json @@ -471,6 +479,10 @@ Version 1 does not exist to avoid confusion with that from :manual:`cmake-server(7)` mode. +.. versionadded:: 4.1 + The ``codemodel`` object kind reply is described in machine-readable form + by :download:`this JSON schema </manual/file_api/schema_codemodel.json>`. + "codemodel" version 2 ^^^^^^^^^^^^^^^^^^^^^ @@ -495,6 +507,7 @@ "childIndexes": [ 1 ], "projectIndex": 0, "targetIndexes": [ 0 ], + "abstractTargetIndexes": [ 1 ], "hasInstallRule": true, "minimumCMakeVersion": { "string": "3.14" @@ -507,6 +520,7 @@ "parentIndex": 0, "projectIndex": 0, "targetIndexes": [ 1 ], + "abstractTargetIndexes": [ 0 ], "minimumCMakeVersion": { "string": "3.14" }, @@ -517,7 +531,8 @@ { "name": "MyProject", "directoryIndexes": [ 0, 1 ], - "targetIndexes": [ 0, 1 ] + "targetIndexes": [ 0, 1 ], + "abstractTargetIndexes": [ 0, 1 ], } ], "targets": [ @@ -534,6 +549,20 @@ "jsonFile": "<file>" } ] + "abstractTargets": [ + { + "name": "MyImportedExecutable", + "directoryIndex": 1, + "projectIndex": 0, + "jsonFile": "<file>" + }, + { + "name": "MyPureInterfaceLibrary", + "directoryIndex": 0, + "projectIndex": 0, + "jsonFile": "<file>" + } + ] } ] } @@ -600,10 +629,20 @@ indicating the build system project to which the this directory belongs. ``targetIndexes`` - Optional member that is present when the directory itself has targets, - excluding those belonging to subdirectories. The value is a JSON - array of entries corresponding to the targets. Each entry is an - unsigned integer 0-based index into the main ``targets`` array. + Optional member that is present when the directory itself has + build system targets, excluding those belonging to subdirectories. + The value is a JSON array of entries corresponding to the build system + targets. Each entry is an unsigned integer 0-based index into the main + ``targets`` array. + + ``abstractTargetIndexes`` + Optional member that is present when the directory itself has abstract + targets, excluding those belonging to subdirectories. + The value is a JSON array of entries corresponding to the abstract + targets. Each entry is an unsigned integer 0-based index into the main + ``abstractTargets`` array. + + This field was added in codemodel version 2.9. ``minimumCMakeVersion`` Optional member present when a minimum required version of CMake is @@ -665,17 +704,27 @@ integer 0-based index into the main ``directories`` array. ``targetIndexes`` - Optional member that is present when the project itself has targets, - excluding those belonging to sub-projects. The value is a JSON - array of entries corresponding to the targets. Each entry is an - unsigned integer 0-based index into the main ``targets`` array. + Optional member that is present when the project itself has + build system targets, excluding those belonging to sub-projects. + The value is a JSON array of entries corresponding to the build system + targets. Each entry is an unsigned integer 0-based index into the main + ``targets`` array. + + ``abstractTargetIndexes`` + Optional member that is present when the project itself has + abstract targets, excluding those belonging to sub-projects. + The value is a JSON array of entries corresponding to the abstract + targets. Each entry is an unsigned integer 0-based index into the main + ``abstractTargets`` array. + + This field was added in codemodel version 2.9. ``targets`` A JSON array of entries corresponding to the build system targets. Such targets are created by calls to :command:`add_executable`, :command:`add_library`, and :command:`add_custom_target`, excluding - imported targets and interface libraries (which do not generate any - build rules). Each entry is a JSON object containing members: + imported targets and interface libraries that do not generate any + build rules. Each entry is a JSON object containing members: ``name`` A string specifying the target name. @@ -697,13 +746,63 @@ to another JSON file containing a `"codemodel" version 2 "target" object`_. + ``abstractTargets`` + A JSON array of entries corresponding to targets that are not present + in the build system. These are imported targets or interface libraries + created by calls to :command:`add_executable` or :command:`add_library`. + In the case of interface libraries, only those that are not part of the + build system are included in this array. Interface libraries that do + participate in the build system will be included in the ``targets`` + array instead. + + Each entry is a JSON object containing members: + + ``name`` + A string specifying the target name. + + ``id`` + A string uniquely identifying the target. This matches the ``id`` + field in the file referenced by ``jsonFile``. + + ``directoryIndex`` + An unsigned integer 0-based index into the main ``directories`` array + indicating the build system directory in which the target is defined. + + ``projectIndex`` + An unsigned integer 0-based index into the main ``projects`` array + indicating the build system project in which the target is defined. + + ``jsonFile`` + A JSON string specifying a path relative to the codemodel file + to another JSON file containing a + `"codemodel" version 2 "target" object`_. + + This field was added in codemodel version 2.9. + "codemodel" version 2 "directory" object ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. versionadded:: 4.1 + The ``directory`` object reply is described in machine-readable form by + :download:`this JSON schema </manual/file_api/schema_directory.json>`. + A codemodel "directory" object is referenced by a `"codemodel" version 2`_ object's ``directories`` array. Each "directory" object is a JSON object with members: +``codemodelVersion`` + This specifies the codemodel version this file is part of. It will match + the ``version`` field of the codemodel object kind that references this file. + It is a JSON object with the following members: + + ``major`` + The codemodel major version. + + ``minor`` + The codemodel minor version. + + This field was added in codemodel version 2.9. + ``paths`` A JSON object containing members: @@ -976,10 +1075,27 @@ "codemodel" version 2 "target" object ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. versionadded:: 4.1 + The ``target`` object reply is described in machine-readable form by + :download:`this JSON schema </manual/file_api/schema_target.json>`. + A codemodel "target" object is referenced by a `"codemodel" version 2`_ object's ``targets`` array. Each "target" object is a JSON object with members: +``codemodelVersion`` + This specifies the codemodel version this file is part of. It will match + the ``version`` field of the codemodel object kind that references this file. + It is a JSON object with the following members: + + ``major`` + The codemodel major version. + + ``minor`` + The codemodel minor version. + + This field was added in codemodel version 2.9. + ``name`` A string specifying the logical name of the target. @@ -993,6 +1109,40 @@ ``MODULE_LIBRARY``, ``OBJECT_LIBRARY``, ``INTERFACE_LIBRARY``, or ``UTILITY``. +``imported`` + Optional member that is present with boolean value ``true`` if the + target is an imported target. + + This field was added in codemodel version 2.9. + +``local`` + Optional member that is present with boolean value ``true`` if the + target is only defined with local scope rather than being a global target. + Currently, only imported targets will potentially have this field. + + This field was added in codemodel version 2.9. + +``abstract`` + Optional member that is present with boolean value ``true`` if the + target is an abstract target. Abstract targets are not part of the build + system, they only exist to describe dependencies or to provide usage + requirements to targets that link to them. Examples include imported targets + and interface libraries that have no generated sources. Abstract targets + cannot be built, so they should not be presented to the user as a buildable + target. + + This field was added in codemodel version 2.9. Abstract targets were not + included in codemodel version 2.8 and earlier. + +``symbolic`` + Optional member that is present with boolean value ``true`` if the target + is :prop_tgt:`SYMBOLIC`. Symbolic targets are created by calls to + :command:`add_library(INTERFACE SYMBOLIC) <add_library(INTERFACE-SYMBOLIC)>`, + and are also abstract targets that are not part of the build system. + + This field was added in codemodel version 2.9. Symbolic targets were not + included in codemodel version 2.8 and earlier. + ``backtrace`` Optional member that is present when a CMake language backtrace to the command in the source code that created the target is available. @@ -1100,8 +1250,8 @@ This field was added in codemodel version 2.7. ``link`` - Optional member that is present for executables and shared library - targets that link into a runtime binary. The value is a JSON object + Optional member that is present for non-imported executables and shared + library targets that link into a runtime binary. The value is a JSON object with members describing the link step: ``language`` @@ -1147,8 +1297,8 @@ with forward slashes. ``archive`` - Optional member that is present for static library targets. The value - is a JSON object with members describing the archive step: + Optional member that is present for non-imported static library targets. + The value is a JSON object with members describing the archive step: ``commandFragments`` Optional member that is present when fragments of the archiver command @@ -1187,7 +1337,19 @@ ``dependencies`` Optional member that is present when the target depends on other targets. - The value is a JSON array of entries corresponding to the dependencies. + It is only present if the target is part of the build system. + Imported targets are not part of the build system. Interface libraries + are only part of the build system if they have sources or file sets. + + The value is a JSON array of entries corresponding to the build dependencies. + The array includes not just direct dependencies, but also transitive + dependencies. All listed targets will build before this one. + + The list of dependencies reflects the *build graph* dependencies, not + necessarily the link dependencies. If there are cycles in the link + dependencies of static libraries, not all link dependencies will be + reflected in this list of build graph dependencies. + Each entry is a JSON object with members: ``id`` @@ -1201,6 +1363,216 @@ available. The value is an unsigned integer 0-based index into the ``backtraceGraph`` member's ``nodes`` array. +``linkLibraries`` + Optional member that may be present when the target links directly to one or + more other targets or libraries. It contains items that are used when + linking this target. These come from the target's + :prop_tgt:`LINK_LIBRARIES` property (evaluated non-transitively), or the + :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` property of another target it + links to directly or transitively. + + Items that are only applied as usage requirements (such as being wrapped in a + :genex:`$<COMPILE_ONLY:...>` expression) will not be present in this member. + + The value is a JSON array of entries. Each entry is a JSON object with + members: + + ``id`` + Optional member that is present when the library to be linked is a target. + It uniquely identifies the target on which this one has a direct link + relationship. This matches the main ``id`` member of that other target. + + The target this ``id`` identifies is not necessarily part of the build + system. It may be an imported target or an interface library with no + sources or file sets. + + Exactly one of ``id`` or ``fragment`` will always be present. + + ``fragment`` + Optional member that is present when the library to be linked is not a + target. It is a string containing the raw linker command line arguments + that capture the relationship. These will typically be linking to + libraries or frameworks by name rather than as a target. + + Exactly one of ``id`` or ``fragment`` will always be present. + + ``backtrace`` + Optional member that is present when a CMake language backtrace to + the command invocation that created this relationship is available. + The value is an unsigned integer 0-based index into the + ``backtraceGraph`` member's ``nodes`` array. + + ``fromDependency`` + Optional member that is only present when the relationship is the result of + an :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` target property on one of + this target's directly or transitively linked libraries. It is a JSON + object with one member: + + ``id`` + A string uniquely identifying the target whose + :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` property created the + relationship. The value matches the main ``id`` member of that target. + + This field was added in codemodel version 2.9. + +``interfaceLinkLibraries`` + Optional member that may be present when the target has one or more interface + link libraries. It contains items that are used when linking consumers of + this target. These come from the target's + :prop_tgt:`INTERFACE_LINK_LIBRARIES` property. + + Items that are only applied as usage requirements (such as being wrapped in a + :genex:`$<COMPILE_ONLY:...>` expression) will not be present in this member. + + The value is a JSON array of entries. Each entry is a JSON object with + members: + + ``id`` + Optional member that is present when the interface link library is for a + target. It uniquely identifies that target, with the value matching the + main ``id`` member of that target. + + The target this ``id`` identifies is not necessarily part of the build + system. It may be an imported target or an interface library with no + sources or file sets. + + Exactly one of ``id`` or ``fragment`` will always be present. + + ``fragment`` + Optional member that is present when the interface link library is not for + a target. It is a string containing the raw linker command line arguments + to be applied to consumers of this target's interface link libraries. + These will typically be linker arguments for linking to libraries or + frameworks by name rather than as a target. + + Exactly one of ``id`` or ``fragment`` will always be present. + + ``backtrace`` + Optional member that is present when a CMake language backtrace to the + command invocation that created this interface relationship is available. + The value is an unsigned integer 0-based index into the + ``backtraceGraph`` member's ``nodes`` array. + + This field was added in codemodel version 2.9. + +``compileDependencies`` + Optional member that may be present when the target links directly to one or + more other targets that may provide usage requirements to this one. They + affect how this target's sources are compiled. These relationships are + defined by the target's :prop_tgt:`LINK_LIBRARIES` property (evaluated + non-transitively) and the :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` + property of other targets it links to directly or transitively. + + Relationships that only apply linking requirements (such as being wrapped + in a :genex:`$<LINK_ONLY:...>` expression) will not be present in this + member. + + The value is a JSON array of entries. Each entry is a JSON object with + members: + + ``id`` + A string uniquely identifying the target on which this target directly + depends. This matches the main ``id`` member of the other target. + + The target this ``id`` identifies is not necessarily part of the build + system. It may be an imported target or an interface library with no + sources or file sets. + + ``backtrace`` + Optional member that is present when a CMake language backtrace to + the command invocation that created this relationship is available. + The value is an unsigned integer 0-based index into the + ``backtraceGraph`` member's ``nodes`` array. + + ``fromDependency`` + Optional member that is only present when the relationship is the result of + an :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` target property on one of + this target's directly or transitively linked libraries. It is a JSON + object with one member: + + ``id`` + A string uniquely identifying the target whose + :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` property created the + relationship. The value matches the main ``id`` member of that target. + + This field was added in codemodel version 2.9. + +``interfaceCompileDependencies`` + Optional member that may be present when the target has one or more interface + linking relationships to other targets. It contains items that affect how + consumers' sources are compiled. These relationships are defined by the + target's :prop_tgt:`INTERFACE_LINK_LIBRARIES` property. + + Relationships that only apply linking requirements (such as being wrapped + in a :genex:`$<LINK_ONLY:...>` expression) will not be present in this + member. + + The value is a JSON array of entries. Each entry is a JSON object with + members: + + ``id`` + A string uniquely identifying the target on which this target specifies + an interface relationship. This matches the main ``id`` member of the + other target. + + The target this ``id`` identifies is not necessarily part of the build + system. It may be an imported target or an interface library with no + sources or file sets. + + ``backtrace`` + Optional member that is present when a CMake language backtrace to + the command invocation that created this relationship is available. + The value is an unsigned integer 0-based index into the + ``backtraceGraph`` member's ``nodes`` array. + + This field was added in codemodel version 2.9. + +``objectDependencies`` + Optional member that is present when the target has one or more entries in + its :prop_tgt:`SOURCES` property where the entry is specified using + :genex:`$<TARGET_OBJECTS:...>`, and where no other generator expression is + used within the :genex:`$<TARGET_OBJECTS:...>` expression. + + The value is a JSON array of entries. Each entry is a JSON object with + members: + + ``id`` + A string uniquely identifying the target whose objects are referred to in + the :genex:`$<TARGET_OBJECTS:...>` expression. This matches the main + ``id`` member of that other target. + + ``backtrace`` + Optional member that is present when a CMake language backtrace to + the command invocation that created this dependency is available. + The value is an unsigned integer 0-based index into the + ``backtraceGraph`` member's ``nodes`` array. + + This field was added in codemodel version 2.9. + +``orderDependencies`` + Optional member that is present when the target has one or more direct order + dependencies on other targets. Such dependencies may arise from calls to + :command:`add_dependencies` or from internal CMake processing. + Unlike the ``dependencies`` array, the ``ZERO_CHECK`` target will not be + included in ``orderDependencies`` (this is only relevant for + :generator:`Xcode` and :ref:`Visual Studio <Visual Studio Generators>` + generators). + + The value is a JSON array of entries. Each entry is a JSON object with + members: + + ``id`` + A string uniquely identifying the target on which this target depends. + This matches the main ``id`` member of the other target. + + ``backtrace`` + Optional member that is present when a CMake language backtrace to + the command invocation that created this dependency is available. + The value is an unsigned integer 0-based index into the + ``backtraceGraph`` member's ``nodes`` array. + + This field was added in codemodel version 2.9. + ``fileSets`` An optional member that is present when a target defines one or more file sets. The value is a JSON array of entries corresponding to the @@ -1265,6 +1637,35 @@ available. The value is an unsigned integer 0-based index into the ``backtraceGraph`` member's ``nodes`` array. +``interfaceSources`` + An optional member that is present when a target defines one or more + interface sources. The value is a JSON array of entries corresponding + to the target's interface source files. Each entry is a JSON object + with members: + + ``path`` + A string specifying the path to the source 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. + + ``sourceGroupIndex`` + Optional member that is present when the source is part of a source + group either via the :command:`source_group` command or by default. + The value is an unsigned integer 0-based index into the + ``sourceGroups`` array. + + ``isGenerated`` + Optional member that is present with boolean value ``true`` if + the source is :prop_sf:`GENERATED`. + + ``fileSetIndex`` + Optional member that is present when the source is part of a file set. + The value is an unsigned integer 0-based index into the ``fileSets`` + array. + + This field was added in codemodel version 2.10. + ``sourceGroups`` Optional member that is present when sources are grouped together by the :command:`source_group` command or by default. The value is a @@ -1279,6 +1680,15 @@ Each entry is an unsigned integer 0-based index into the main ``sources`` array for the target. + ``interfaceSourceIndexes`` + Optional member that is present when at least one interface source file + is part of the source group. The value is a JSON array listing the + interface sources belonging to the group. Each entry is an unsigned + integer 0-based index into the main ``interfaceSources`` array for the + target. + + This field was added in codemodel version 2.10. + ``compileGroups`` Optional member that is present when the target has sources that compile. The value is a JSON array of entries corresponding to groups of sources @@ -1471,6 +1881,10 @@ There is only one ``configureLog`` object major version, version 1. +.. versionadded:: 4.1 + The ``configureLog`` object kind reply is described in machine-readable form + by :download:`this JSON schema </manual/file_api/schema_configureLog.json>`. + "configureLog" version 1 ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1511,6 +1925,10 @@ Version 1 does not exist to avoid confusion with that from :manual:`cmake-server(7)` mode. +.. versionadded:: 4.1 + The ``cache`` object kind reply is described in machine-readable form by + :download:`this JSON schema </manual/file_api/schema_cache.json>`. + "cache" version 2 ^^^^^^^^^^^^^^^^^ @@ -1583,6 +2001,10 @@ There is only one ``cmakeFiles`` object major version, version 1. +.. versionadded:: 4.1 + The ``cmakeFiles`` object kind reply is described in machine-readable form + by :download:`this JSON schema </manual/file_api/schema_cmakeFiles.json>`. + "cmakeFiles" version 1 ^^^^^^^^^^^^^^^^^^^^^^ @@ -1712,6 +2134,10 @@ There is only one ``toolchains`` object major version, version 1. +.. versionadded:: 4.1 + The ``toolchains`` object kind reply is described in machine-readable form + by :download:`this JSON schema </manual/file_api/schema_toolchains.json>`. + "toolchains" version 1 ^^^^^^^^^^^^^^^^^^^^^^ @@ -1721,12 +2147,13 @@ { "kind": "toolchains", - "version": { "major": 1, "minor": 0 }, + "version": { "major": 1, "minor": 1 }, "toolchains": [ { "language": "C", "compiler": { "path": "/usr/bin/cc", + "commandFragment": "--config x86_64-linux-gnu.cfg", "id": "GNU", "version": "9.3.0", "implicit": { @@ -1805,6 +2232,16 @@ :variable:`CMAKE_<LANG>_COMPILER` variable is defined for the current language. Its value is a JSON string holding the path to the compiler. + ``commandFragment`` + Optional member that is present when the + :variable:`CMAKE_<LANG>_COMPILER` variable is a list containing multiple + elements or the :envvar:`CC` or similar environment variable contains + command line arguments after the compiler executable. + Its value is a JSON string holding the second and further elements + (mandatory arguments to the compiler) as a command line fragment. + + This field was added in toolchains version 1.1. + ``id`` Optional member that is present when the :variable:`CMAKE_<LANG>_COMPILER_ID` variable is defined for the current
diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 4bc0435..ac25627 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst
@@ -115,6 +115,17 @@ VERBATIM ) +For tools that expect ``-I``'s value to be a separate argument, use the +semicolon trick learned earlier: + +.. code-block:: cmake + + add_custom_target(run_some_tool + COMMAND some_tool "$<LIST:TRANSFORM,$<TARGET_PROPERTY:tgt,INCLUDE_DIRECTORIES>,PREPEND,-I;>" + COMMAND_EXPAND_LISTS + VERBATIM + ) + A common mistake is to try to split a generator expression across multiple lines with indenting: @@ -273,20 +284,8 @@ Other more specific comparison types are documented in their own separate sections further below. -String Comparisons -^^^^^^^^^^^^^^^^^^ - -.. genex:: $<STREQUAL:string1,string2> - - ``1`` if ``string1`` and ``string2`` are equal, else ``0``. - The comparison is case-sensitive. For a case-insensitive comparison, - combine with a :ref:`string transforming generator expression - <String Transforming Generator Expressions>`. For example, the following - evaluates to ``1`` if ``${foo}`` is any of ``BAR``, ``Bar``, ``bar``, etc. - - .. code-block:: cmake - - $<STREQUAL:$<UPPER_CASE:${foo}>,BAR> +Numeric Comparisons +^^^^^^^^^^^^^^^^^^^ .. genex:: $<EQUAL:value1,value2> @@ -319,10 +318,401 @@ ``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``. +String Expressions +------------------ + +Most of the expressions in this section are closely associated with the +:command:`string` command, providing the same capabilities, but in +the form of a generator expression. + +In each of the following string-related generator expressions, the ``string`` +must not contain any commas if that generator expression expects something to +be provided after the ``string``. For example, the expression +``$<STRING:FIND,string,value>`` requires a ``value`` after the ``string``. +Since a comma is used to separate the ``string`` and the ``value``, the +``string`` cannot itself contain a comma. This restriction does not apply to +the :command:`string` command, it is specific to the string-handling generator +expressions only. The :genex:`$<COMMA>` generator expression can be used to +specify a comma as part of the arguments of the string-related generator +expressions. + +.. _`String Comparisons Generator Expressions`: + +String Comparisons +^^^^^^^^^^^^^^^^^^ + +The comparisons are case-sensitive. For a case-insensitive comparison, +combine with a :ref:`string transforming generator expression +<String Transforming Generator Expressions>`. For example, the following +evaluates to ``1`` if ``${foo}`` is any of ``BAR``, ``Bar``, ``bar``, etc. + + .. code-block:: cmake + + $<STREQUAL:$<STRING:TOUPPER,${foo}>,BAR> + +.. genex:: $<STREQUAL:string1,string2> + + ``1`` if ``string1`` and ``string2`` are lexicographically equal, else ``0``. + +.. genex:: $<STRLESS:string1,string2> + + .. versionadded:: 4.3 + + ``1`` if ``string1`` is lexicographically less than ``string2``, else ``0``. + +.. genex:: $<STRGREATER:string1,string2> + + .. versionadded:: 4.3 + + ``1`` if ``string1`` is lexicographically greater than ``string2``, else + ``0``. + +.. genex:: $<STRLESS_EQUAL:string1,string2> + + .. versionadded:: 4.3 + + ``1`` if ``string1`` is lexicographically less than or equal to ``string2``, + else ``0``. + +.. genex:: $<STRGREATER_EQUAL:string1,string2> + + .. versionadded:: 4.3 + + ``1`` if ``string1`` is lexicographically greater than or equal to + ``string2``, else ``0``. + +.. _`String Queries Generator Expressions`: + +String Queries +^^^^^^^^^^^^^^ + +.. genex:: $<STRING:LENGTH,string> + + .. versionadded:: 4.3 + + The given string's length in bytes. Note that this means, if ``string`` + contains multi-byte characters, the result will *not* be the number of + characters. + +.. genex:: $<STRING:SUBSTRING,string,begin,length> + + .. versionadded:: 4.3 + + The substring of the given ``string``. If ``length`` is ``-1`` or greater + than the ``string`` length the remainder of the string starting at ``begin`` + will be returned. + + Both ``begin`` and ``length`` are counted in bytes, so care must + be exercised if ``string`` could contain multi-byte characters. + +.. genex:: $<STRING:FIND,string[,FROM:(BEGIN|END)],substring> + + .. versionadded:: 4.3 + + The position where the given ``substring`` was found in the supplied + ``string``. If the ``substring`` is not found, a position of -1 is returned. + + The ``FROM:`` option defines how the search will be done: + + ``BEGIN`` + The search will start at the beginning of the ``string``. This the default. + + ``END`` + The search will start from the end of the ``string``. + + The ``$<STRING:FIND>`` generator expression treats all strings as ASCII-only + characters. The index returned will also be counted in bytes, so strings + containing multi-byte characters may lead to unexpected results. + +.. genex:: $<STRING:MATCH,string[,SEEK:(ONCE|ALL)],regular_expression> + + .. versionadded:: 4.3 + + Match, in the ``string``, the ``regular_expression``. + + The ``SEEK:`` option specifies the match behavior: + + ``ONCE`` + Match only the first occurrence. This is the default. + + ``ALL`` + Match as many times as possible and return the matches as a list. + + See the :ref:`Regular expressions specification <Regex Specification>` for + the syntax of the ``regular_expression`` parameter. + +.. _`String Generating Generator Expressions`: + +String Generations +^^^^^^^^^^^^^^^^^^ + +.. genex:: $<STRING:JOIN,glue,input[,input]...> + + .. versionadded:: 4.3 + + Join all the ``input`` arguments together using the ``glue`` string. + +.. genex:: $<STRING:ASCII,number[,number]...> + + .. versionadded:: 4.3 + + Convert all numbers, in the range 1-255, into corresponding ASCII + characters. Any number outside this range will raise an error. + +.. genex:: $<STRING:TIMESTAMP[,(UTC|format)]...> + + .. versionadded:: 4.3 + + Produce a string representation of the current date and/or time. + + If the generator expression is unable to obtain a timestamp, the result will + be the empty string ``""``. + + The optional ``UTC`` flag requests the current date/time representation to + be in Coordinated Universal Time (UTC) rather than local time. + + If the ``SOURCE_DATE_EPOCH`` environment variable is set, its value will be + used instead of the current time. + See https://reproducible-builds.org/specs/source-date-epoch/ for details. + + The optional ``<format>`` may contain the following format specifiers: + + ``%%`` + 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) + + ``%f`` + The microsecond of the current second (000000-999999). + + ``%U`` + The week number of the current year (00-53). + + ``%V`` + The ISO 8601 week number of the current year (01-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. + + ``%z`` + The offset of the time zone from UTC, in hours and minutes, + with format ``+hhmm`` or ``-hhmm``. + + ``%Z`` + The time zone name. + + Unknown format specifiers will be ignored and copied to the output + as-is. + + If no explicit ``format`` is given, it will default to: + + * ``%Y-%m-%dT%H:%M:%S`` for local time. + * ``%Y-%m-%dT%H:%M:%SZ`` for UTC. + +.. genex:: $<STRING:RANDOM[,(LENGTH:length|ALPHABET:alphabet|RANDOM_SEED:seed)]...> + + .. versionadded:: 4.3 + + Produce a random string of ASCII characters. The possible options are: + + ``LENGTH:length`` + Define the length of the string. The default length is 5 characters. + + ``ALPHABET:alphabet`` + Define the characters used for the generation. The alphabet is always + interpreted as holding ASCII characters. The default alphabet is all + numbers and upper and lower case letters. + + ``RANDOM_SEED:seed`` + Specify an integer which will be used to seed the random number generator. + +.. genex:: $<STRING:UUID,NAMESPACE:namespace,TYPE:(MD5|SHA1)[,NAME:name][,CASE:(LOWER|UPPER)]> + + .. versionadded:: 4.3 + + Create a universally unique identifier (aka GUID) as per RFC4122. + A UUID has the format ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`` + where each ``x`` represents an hexadecimal character. + + The UUID is based on the hash of the combined values of: + + ``NAMESPACE:namespace`` + ``namespace`` which has to be a valid UUID. + + ``NAME:name`` + ``name`` is an arbitrary string. + + ``TYPE:`` + The hash algorithm can be either: + + ``MD5`` + Version 3 UUID. + + ``SHA1`` + Version 5 UUID. + + ``CASE:`` + Specify the case of the hexadecimal characters. + + ``LOWER`` + Hexadecimal characters are all of lowercase. This is the default. + + ``UPPER`` + Hexadecimal characters are all of uppercase. + .. _`String Transforming Generator Expressions`: String Transformations ----------------------- +^^^^^^^^^^^^^^^^^^^^^^ + +.. genex:: $<STRING:REPLACE[,(STRING|REGEX)],string,match_string,replace_string> + + .. versionadded:: 4.3 + + Replace all occurrences of ``match_string`` in the ``string`` with + ``replace_string``. + + The ``match_string`` can be of two different types: + + ``STRING`` + ``match_string`` is a literal string and match will be done by simple + string comparison. This is the default. + + ``REGEX`` + ``match_string`` is a regular expression. Match this regular_expression as + many times as possible and substitute the ``replace_string`` for the match + in the ``string``. + + The ``replace_string`` may refer to parenthesis-delimited subexpressions of + the match using \\1, \\2, ..., \\9. Note that two backslashes (\\\\1) are + required in CMake code to get a backslash through argument parsing. + +.. genex:: $<STRING:APPEND,string,input[,input]...> + + .. versionadded:: 4.3 + + Append all the ``input`` arguments to the ``string``. + +.. genex:: $<STRING:PREPEND,string,input[,input]...> + + .. versionadded:: 4.3 + + Prepend all the ``input`` arguments to the ``string``. + +.. genex:: $<STRING:TOLOWER,string> + + .. versionadded:: 4.3 + + Content of ``string`` converted to lower case. + +.. genex:: $<STRING:TOUPPER,string> + + .. versionadded:: 4.3 + + Content of ``string`` converted to upper case. + +.. genex:: $<STRING:STRIP,SPACES,string> + + .. versionadded:: 4.3 + + Remove the specified elements from the ``string``. The possible options are: + + ``SPACES`` + Remove the leading and trailing spaces of the ``string``. + +.. genex:: $<STRING:QUOTE,REGEX,string> + + .. versionadded:: 4.3 + + Escape the specified elements of the ``string``. The possible options are: + + ``REGEX`` + Escape all characters that have special meaning in a regular expressions, + such that the ``string`` can be used as part of a regular expression to + match the input literally. + +.. genex:: $<STRING:HEX,string> + + .. versionadded:: 4.3 + + Convert each byte in the ``string`` to its hexadecimal representation. + Letters in the result (a through f) are in lowercase. + +.. genex:: $<STRING:HASH,string,ALGORITHM:algorithm> + + .. versionadded:: 4.3 + + Compute a cryptographic hash of the ``string``. The supported algorithm + names, as specified by the ``ALGORITHM:`` option are: + + ``MD5`` + Message-Digest Algorithm 5, RFC 1321. + ``SHA1`` + US Secure Hash Algorithm 1, RFC 3174. + ``SHA224`` + US Secure Hash Algorithms, RFC 4634. + ``SHA256`` + US Secure Hash Algorithms, RFC 4634. + ``SHA384`` + US Secure Hash Algorithms, RFC 4634. + ``SHA512`` + US Secure Hash Algorithms, RFC 4634. + ``SHA3_224`` + Keccak SHA-3. + ``SHA3_256`` + Keccak SHA-3. + ``SHA3_384`` + Keccak SHA-3. + ``SHA3_512`` + Keccak SHA-3. + +.. genex:: $<STRING:MAKE_C_IDENTIFIER,string> + + .. versionadded:: 4.3 + + Convert each non-alphanumeric character in the ``string`` to an underscore. + If the first character of the ``string`` is a digit, an underscore will also + be prepended. .. genex:: $<LOWER_CASE:string> @@ -332,10 +722,10 @@ Content of ``string`` converted to upper case. -.. genex:: $<MAKE_C_IDENTIFIER:...> +.. genex:: $<MAKE_C_IDENTIFIER:string> - Content of ``...`` converted to a C identifier. The conversion follows the - same behavior as :command:`string(MAKE_C_IDENTIFIER)`. + Content of ``string`` converted to a C identifier. The conversion follows + the same behavior as :command:`string(MAKE_C_IDENTIFIER)`. List Expressions ---------------- @@ -568,9 +958,9 @@ Joins the ``list`` with the content of the ``glue`` string inserted between each item. This is conceptually the same operation as - :ref:`$\<LIST:JOIN,list,glue\> <GenEx LIST-JOIN>`, but the two have + :cref:`$\<LIST:JOIN,list,glue\> <GenEx LIST-JOIN>`, but the two have different behavior with regard to empty items. - :ref:`$\<LIST:JOIN,list,glue\> <GenEx LIST-JOIN>` preserves all empty items, + :cref:`$\<LIST:JOIN,list,glue\> <GenEx LIST-JOIN>` preserves all empty items, whereas ``$<JOIN:list,glue>`` drops all empty items from the list. .. genex:: $<REMOVE_DUPLICATES:list> @@ -580,7 +970,7 @@ Removes duplicated items in the given ``list``. The relative order of items is preserved, and if duplicates are encountered, only the first instance is retained. The result is the same as - :ref:`$\<LIST:REMOVE_DUPLICATES,list\> <GenEx LIST-REMOVE_DUPLICATES>`. + :cref:`$\<LIST:REMOVE_DUPLICATES,list\> <GenEx LIST-REMOVE_DUPLICATES>`. .. genex:: $<FILTER:list,INCLUDE|EXCLUDE,regex> @@ -588,7 +978,7 @@ Includes or removes items from ``list`` that match the regular expression ``regex``. The result is the same as - :ref:`$\<LIST:FILTER,list,INCLUDE|EXCLUDE,regex\> <GenEx LIST-FILTER>`. + :cref:`$\<LIST:FILTER,list,INCLUDE|EXCLUDE,regex\> <GenEx LIST-FILTER>`. .. _GenEx List Ordering: @@ -660,7 +1050,7 @@ the form of a generator expression. For all generator expressions in this section, paths are expected to be in -cmake-style format. The :ref:`$\<PATH:CMAKE_PATH\> <GenEx PATH-CMAKE_PATH>` +cmake-style format. The :cref:`$\<PATH:CMAKE_PATH\> <GenEx PATH-CMAKE_PATH>` generator expression can be used to convert a native path to a cmake-style one. @@ -677,7 +1067,7 @@ performed on either path. Returns ``1`` if the paths are equal, ``0`` otherwise. - See :ref:`cmake_path(COMPARE) <Path COMPARE>` for more details. + See :ref:`cmake_path(COMPARE) <Path Comparison>` for more details. .. _GenEx Path Queries: @@ -720,13 +1110,15 @@ .. versionadded:: 3.24 - Returns ``1`` if the path is :ref:`absolute <IS_ABSOLUTE>`, ``0`` otherwise. + Returns ``1`` if the path is absolute according to + :command:`cmake_path(IS_ABSOLUTE)`, ``0`` otherwise. .. genex:: $<PATH:IS_RELATIVE,path> .. versionadded:: 3.24 - This will return the opposite of ``IS_ABSOLUTE``. + Returns ``1`` if the path is relative according to + :command:`cmake_path(IS_RELATIVE)`, ``0`` otherwise. .. genex:: $<PATH:IS_PREFIX[,NORMALIZE],path,input> @@ -818,7 +1210,7 @@ ``directory-separator``. Depending on the ``input``, the value of ``path`` may be discarded. - See :ref:`cmake_path(APPEND) <APPEND>` for more details. + See :command:`cmake_path(APPEND)` for more details. .. genex:: $<PATH:REMOVE_FILENAME,path...> @@ -828,7 +1220,7 @@ ``$<PATH:GET_FILENAME>``) removed. After removal, any trailing ``directory-separator`` is left alone, if present. - See :ref:`cmake_path(REMOVE_FILENAME) <REMOVE_FILENAME>` for more details. + See :command:`cmake_path(REMOVE_FILENAME)` for more details. .. genex:: $<PATH:REPLACE_FILENAME,path...,input> @@ -838,7 +1230,7 @@ ``path`` has no filename component (i.e. ``$<PATH:HAS_FILENAME>`` returns ``0``), ``path`` is unchanged. - See :ref:`cmake_path(REPLACE_FILENAME) <REPLACE_FILENAME>` for more details. + See :command:`cmake_path(REPLACE_FILENAME)` for more details. .. genex:: $<PATH:REMOVE_EXTENSION[,LAST_ONLY],path...> @@ -846,7 +1238,7 @@ Returns ``path`` with the :ref:`extension <EXTENSION_DEF>` removed, if any. - See :ref:`cmake_path(REMOVE_EXTENSION) <REMOVE_EXTENSION>` for more details. + See :command:`cmake_path(REMOVE_EXTENSION)` for more details. .. genex:: $<PATH:REPLACE_EXTENSION[,LAST_ONLY],path...,input> @@ -855,7 +1247,7 @@ Returns ``path`` with the :ref:`extension <EXTENSION_DEF>` replaced by ``input``, if any. - See :ref:`cmake_path(REPLACE_EXTENSION) <REPLACE_EXTENSION>` for more details. + See :command:`cmake_path(REPLACE_EXTENSION)` for more details. .. genex:: $<PATH:NORMAL_PATH,path...> @@ -871,8 +1263,7 @@ Returns ``path``, modified to make it relative to the ``base_directory`` argument. - See :ref:`cmake_path(RELATIVE_PATH) <cmake_path-RELATIVE_PATH>` for more - details. + See :command:`cmake_path(RELATIVE_PATH)` for more details. .. genex:: $<PATH:ABSOLUTE_PATH[,NORMALIZE],path...,base_directory> @@ -885,7 +1276,7 @@ When the ``NORMALIZE`` option is specified, the path is :ref:`normalized <Normalization>` after the path computation. - See :ref:`cmake_path(ABSOLUTE_PATH) <ABSOLUTE_PATH>` for more details. + See :command:`cmake_path(ABSOLUTE_PATH)` for more details. Shell Paths ^^^^^^^^^^^ @@ -1420,8 +1811,8 @@ Note that for proper evaluation of this expression requires policy :policy:`CMP0099` to be set to ``NEW``. -Linker Language And ID -^^^^^^^^^^^^^^^^^^^^^^ +Link Language and ID +^^^^^^^^^^^^^^^^^^^^ .. genex:: $<LINK_LANGUAGE> @@ -1827,6 +2218,338 @@ (see :genex:`$<DEVICE_LINK:list>` generator expression). This expression can only be used to specify link options. +Linker ID and Frontend-Variant +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +See also the :variable:`CMAKE_<LANG>_COMPILER_LINKER_ID` and +:variable:`CMAKE_<LANG>_COMPILER_LINKER_FRONTEND_VARIANT` variables, which are +closely related to most of the expressions in this sub-section. + +.. genex:: $<C_COMPILER_LINKER_ID> + + .. versionadded:: 4.2 + + CMake's linker id of the C linker used. + +.. genex:: $<C_COMPILER_LINKER_ID:linker_ids> + + .. versionadded:: 4.2 + + where ``linker_ids`` is a comma-separated list. + ``1`` if CMake's linker id of the C linker matches any one + of the entries in ``linker_ids``, otherwise ``0``. + +.. genex:: $<CXX_COMPILER_LINKER_ID> + + .. versionadded:: 4.2 + + CMake's linker id of the C++ linker used. + +.. genex:: $<CXX_COMPILER_LINKER_ID:linker_ids> + + .. versionadded:: 4.2 + + where ``linker_ids`` is a comma-separated list. + ``1`` if CMake's linker id of the C++ linker matches any one + of the entries in ``linker_ids``, otherwise ``0``. + +.. genex:: $<CUDA_COMPILER_LINKER_ID> + + .. versionadded:: 4.2 + + CMake's linker id of the CUDA linker used. + +.. genex:: $<CUDA_COMPILER_LINKER_ID:linker_ids> + + .. versionadded:: 4.2 + + where ``linker_ids`` is a comma-separated list. + ``1`` if CMake's linker id of the CUDA linker matches any one + of the entries in ``linker_ids``, otherwise ``0``. + +.. genex:: $<OBJC_COMPILER_LINKER_ID> + + .. versionadded:: 4.2 + + CMake's linker id of the Objective-C linker used. + +.. genex:: $<OBJC_COMPILER_LINKER_ID:linker_ids> + + .. versionadded:: 4.2 + + where ``linker_ids`` is a comma-separated list. + ``1`` if CMake's linker id of the Objective-C linker matches any one + of the entries in ``linker_ids``, otherwise ``0``. + +.. genex:: $<OBJCXX_COMPILER_LINKER_ID> + + .. versionadded:: 4.2 + + CMake's linker id of the Objective-C++ linker used. + +.. genex:: $<OBJCXX_COMPILER_LINKER_ID:linker_ids> + + .. versionadded:: 4.2 + + where ``linker_ids`` is a comma-separated list. + ``1`` if CMake's linker id of the Objective-C++ linker matches any one + of the entries in ``linker_ids``, otherwise ``0``. + +.. genex:: $<Fortran_COMPILER_LINKER_ID> + + .. versionadded:: 4.2 + + CMake's linker id of the Fortran linker used. + +.. genex:: $<Fortran_COMPILER_LINKER_ID:linker_ids> + + .. versionadded:: 4.2 + + where ``linker_ids`` is a comma-separated list. + ``1`` if CMake's linker id of the Fortran linker matches any one + of the entries in ``linker_ids``, otherwise ``0``. + +.. genex:: $<HIP_COMPILER_LINKER_ID> + + .. versionadded:: 4.2 + + CMake's linker id of the HIP linker used. + +.. genex:: $<HIP_COMPILER_LINKER_ID:linker_ids> + + .. versionadded:: 4.2 + + where ``linker_ids`` is a comma-separated list. + ``1`` if CMake's linker id of the HIP linker matches any one + of the entries in ``linker_ids``, otherwise ``0``. + +.. genex:: $<C_COMPILER_LINKER_FRONTEND_VARIANT> + + .. versionadded:: 4.2 + + CMake's linker frontend variant of the C linker used. + +.. genex:: $<C_COMPILER_LINKER_FRONTEND_VARIANT:variant_ids> + + .. versionadded:: 4.2 + + where ``variant_ids`` is a comma-separated list. + ``1`` if CMake's linker frontend variant of the C linker matches any one + of the entries in ``variant_ids``, otherwise ``0``. + +.. genex:: $<CXX_COMPILER_LINKER_FRONTEND_VARIANT> + + .. versionadded:: 4.2 + + CMake's linker frontend variant of the C++ linker used. + +.. genex:: $<CXX_COMPILER_LINKER_FRONTEND_VARIANT:variant_ids> + + .. versionadded:: 4.2 + + where ``variant_ids`` is a comma-separated list. + ``1`` if CMake's linker frontend variant of the C++ linker matches any one + of the entries in ``variant_ids``, otherwise ``0``. + +.. genex:: $<CUDA_COMPILER_LINKER_FRONTEND_VARIANT> + + .. versionadded:: 4.2 + + CMake's linker frontend variant of the CUDA linker used. + +.. genex:: $<CUDA_COMPILER_LINKER_FRONTEND_VARIANT:variant_ids> + + .. versionadded:: 4.2 + + where ``variant_ids`` is a comma-separated list. + ``1`` if CMake's linker frontend variant of the CUDA linker matches any one + of the entries in ``variant_ids``, otherwise ``0``. + +.. genex:: $<OBJC_COMPILER_LINKER_FRONTEND_VARIANT> + + .. versionadded:: 4.2 + + CMake's linker frontend variant of the Objective-C linker used. + +.. genex:: $<OBJC_COMPILER_LINKER_FRONTEND_VARIANT:variant_ids> + + .. versionadded:: 4.2 + + where ``variant_ids`` is a comma-separated list. + ``1`` if CMake's linker frontend variant of the Objective-C linker matches + any one of the entries in ``variant_ids``, otherwise ``0``. + +.. genex:: $<OBJCXX_COMPILER_LINKER_FRONTEND_VARIANT> + + .. versionadded:: 4.2 + + CMake's linker frontend variant of the Objective-C++ linker used. + +.. genex:: $<OBJCXX_COMPILER_LINKER_FRONTEND_VARIANT:variant_ids> + + .. versionadded:: 4.2 + + where ``variant_ids`` is a comma-separated list. + ``1`` if CMake's linker frontend variant of the Objective-C++ linker matches + any one of the entries in ``variant_ids``, otherwise ``0``. + +.. genex:: $<Fortran_COMPILER_LINKER_FRONTEND_VARIANT> + + .. versionadded:: 4.2 + + CMake's linker frontend variant of the Fortran linker used. + +.. genex:: $<Fortran_COMPILER_LINKER_FRONTEND_VARIANT:variant_ids> + + .. versionadded:: 4.2 + + where ``variant_ids`` is a comma-separated list. + ``1`` if CMake's linker frontend variant of the Fortran linker matches + any one of the entries in ``variant_ids``, otherwise ``0``. + +.. genex:: $<HIP_COMPILER_LINKER_FRONTEND_VARIANT> + + .. versionadded:: 4.2 + + CMake's linker frontend variant of the HIP linker used. + +.. genex:: $<HIP_COMPILER_LINKER_FRONTEND_VARIANT:variant_ids> + + .. versionadded:: 4.2 + + where ``variant_ids`` is a comma-separated list. + ``1`` if CMake's linker frontend variant of the HIP linker matches + any one of the entries in ``variant_ids``, otherwise ``0``. + + +.. _`Source-Dependent Expressions`: + +Source-Dependent Expressions +---------------------------- + +The source file, as specified in the following expressions, can be nonexistent +on the file system (i.e. generated file) but must be known from CMake. A source +file becomes known from CMake if it is part of some target (library or +executable) or when a source file property is defined. Moreover, this +information is specific to the directory where the declaration occurred. + +For example, these generator expressions enable to offer a uniform behavior, +for the :command:`add_custom_command` and :command:`add_custom_target` +commands, regarding the source properties: + +.. code-block:: cmake + + function(custom_add_library target) + unset(sources) + foreach(source IN LISTS ARGN) + add_custom_command( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${source}.bin + COMMAND my-compiler -o ${CMAKE_CURRENT_BINARY_DIR}/${source}.bin + "$<$<SOURCE_EXISTS:${source}>:$<SOURCE_PROPERTY:${source},COMPILE_OPTIONS>>" + ${source}) + list(APPEND sources ${CMAKE_CURRENT_BINARY_DIR}/${source}.bin) + endforeach() + add_custom_target(${target} + DEPENDS ${sources}) + endfunction() + + custom_add_library(my-lib file1.x file2.x file3.x) + set_property(SOURCE file1.x PROPERTY COMPILE_OPTIONS -X) + set_property(SOURCE file2.x PROPERTY COMPILE_OPTIONS -Y) + +Source Meta-Data +^^^^^^^^^^^^^^^^ + +These expressions look up information about a source file. + +.. genex:: $<SOURCE_EXISTS:src[,(DIRECTORY:dir|TARGET_DIRECTORY:tgt)]> + + .. versionadded:: 4.3 + + ``1`` if ``src`` exists as a CMake source file, else ``0``. By default, the + source file is searched in the scope of the current source directory or the + directory of the consuming target. + + Directory scope can be overridden with one of the following sub-options: + + ``DIRECTORY:dir`` + The source file will be searched in the ``dir`` directory's scope. + CMake must know about the directory, either by having added it through a + call to :command:`add_subdirectory` or ``dir`` being the top level + directory. Relative paths are treated as relative to the current source + directory. + + ``TARGET_DIRECTORY:target`` + The source file will be searched in the directory scope in which + ``target`` was created (``target`` must therefore exist). + +Source Properties +^^^^^^^^^^^^^^^^^ + +These expressions look up the values of +:ref:`source file properties <Source File Properties>`. + +.. genex:: $<SOURCE_PROPERTY:src[,(DIRECTORY:dir|TARGET_DIRECTORY:target)],prop> + + .. versionadded:: 4.3 + + Value of the property ``prop`` on the source file ``src``, or empty if + the property is not set. An error will be raised if the source file is not + known by CMake. By default, the source file's property will be read from the + current source directory's scope or the directory of the consuming target. + + Directory scope can be overridden with one of the following sub-options: + + ``DIRECTORY:dir`` + The source file property will be read from the ``dir`` directory's scope. + CMake must know about the directory, either by having added it through a + call to :command:`add_subdirectory` or ``dir`` being the top level + directory. Relative paths are treated as relative to the current source + directory. + + ``TARGET_DIRECTORY:target`` + The source file property will be read from the directory scope in which + ``target`` was created (``target`` must therefore exist). + +.. _`FileSet-Dependent Expressions`: + +FileSet-Dependent Expressions +----------------------------- + +FileSet Meta-Data +^^^^^^^^^^^^^^^^^ + +These expressions look up information about a file set. + +.. genex:: $<FILE_SET_EXISTS:fileset,TARGET:target> + + .. versionadded:: 4.3 + + ``1`` if the ``fileset`` exists as a CMake file set attached to the + ``target``, else ``0``. + + The possible sub-options are: + + ``TARGET:target`` + The target on which the file set depends. + +FileSet Properties +^^^^^^^^^^^^^^^^^^ + +These expressions look up the values of file set properties. + +.. genex:: $<FILE_SET_PROPERTY:fileset,TARGET:target,prop> + + .. versionadded:: 4.3 + + Value of the property ``prop`` on the file set ``fileset``, or empty if + the property is not set. An error will be raised if the file set is not + known by CMake. + + The possible sub-options are: + + ``TARGET:target`` + The target on which the file set depends. .. _`Target-Dependent Expressions`: @@ -2032,13 +2755,23 @@ expression is evaluated on, unless the expression is being used in :command:`add_custom_command` or :command:`add_custom_target`. -.. genex:: $<TARGET_FILE_BASE_NAME:tgt> +.. genex:: $<TARGET_FILE_BASE_NAME:tgt[,POSTFIX:(INCLUDE|EXCLUDE)]> .. versionadded:: 3.15 + .. versionadded:: 4.2 + The ``POSTFIX`` option can be used to control the inclusion or not + of the :prop_tgt:`<CONFIG>_POSTFIX` target property value as part of the + base name. The default is ``POSTFIX:INCLUDE``. + Base name of ``tgt``, i.e. ``$<TARGET_FILE_NAME:tgt>`` without prefix and - suffix. - For example, if the ``tgt`` filename is ``libbase.so``, the base name is ``base``. + suffix and, optionally, postfix. + For example, if the ``tgt`` filename is ``libbase_postfix.so``, the base name + is: + + * ``base_postfix`` for ``$<TARGET_FILE_BASE_NAME:tgt>`` or + ``$<TARGET_FILE_BASE_NAME:tgt,POSTFIX:INCLUDE>``. + * ``base`` for ``$<TARGET_FILE_BASE_NAME:tgt,POSTFIX:EXCLUDE>``. See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, :prop_tgt:`LIBRARY_OUTPUT_NAME` and :prop_tgt:`RUNTIME_OUTPUT_NAME` @@ -2100,13 +2833,23 @@ This expands to an empty string when there is no import file associated with the target. -.. genex:: $<TARGET_IMPORT_FILE_BASE_NAME:tgt> +.. genex:: $<TARGET_IMPORT_FILE_BASE_NAME:tgt[,POSTFIX:(INCLUDE|EXCLUDE)]> .. versionadded:: 3.27 + .. versionadded:: 4.2 + The ``POSTFIX`` option can be used to control the inclusion or not + of the :prop_tgt:`<CONFIG>_POSTFIX` target property value as part of the + base name. The default is ``POSTFIX:INCLUDE``. + Base name of the linker import file of the target ``tgt`` without prefix or - suffix. For example, if the target file name is ``libbase.tbd``, the base - name is ``base``. + suffix and, optionally, postfix. + For example, if the target file name is ``libbase_postfix.tbd``, the base + name is: + + * ``base_postfix`` for ``$<TARGET_IMPORT_FILE_BASE_NAME:tgt>`` or + ``$<TARGET_IMPORT_FILE_BASE_NAME:tgt,POSTFIX:INCLUDE>``. + * ``base`` for ``$<TARGET_IMPORT_FILE_BASE_NAME:tgt,POSTFIX:EXCLUDE>``. See also the :prop_tgt:`OUTPUT_NAME` and :prop_tgt:`ARCHIVE_OUTPUT_NAME` target properties, their configuration-specific variants @@ -2176,13 +2919,24 @@ :genex:`$<TARGET_LINKER_IMPORT_FILE>` generator expressions, depending on the characteristics of the target and the platform. -.. genex:: $<TARGET_LINKER_FILE_BASE_NAME:tgt> +.. genex:: $<TARGET_LINKER_FILE_BASE_NAME:tgt[,POSTFIX:(INCLUDE|EXCLUDE)]> .. versionadded:: 3.15 + .. versionadded:: 4.2 + The ``POSTFIX`` option can be used to control the inclusion or not + of the :prop_tgt:`<CONFIG>_POSTFIX` target property value as part of the + base name. The default is ``POSTFIX:INCLUDE``. + Base name of file used to link the target ``tgt``, i.e. - :genex:`$<TARGET_LINKER_FILE_NAME:tgt>` without prefix and suffix. For - example, if target file name is ``libbase.a``, the base name is ``base``. + :genex:`$<TARGET_LINKER_FILE_NAME:tgt>` without prefix and suffix, and, + optionally, postfix. + For example, if the target file name is ``libbase_postfix.a``, the base name + is: + + * ``base_postfix`` for ``$<TARGET_LINKER_FILE_BASE_NAME:tgt>`` or + ``$<TARGET_LINKER_FILE_BASE_NAME:tgt,POSTFIX:INCLUDE>``. + * ``base`` for ``$<TARGET_LINKER_FILE_BASE_NAME:tgt,POSTFIX:EXCLUDE>``. See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, and :prop_tgt:`LIBRARY_OUTPUT_NAME` target properties, their @@ -2244,13 +2998,25 @@ ``tgt`` represents (``.a``, ``.so``, ``.dylib``). So, on DLL platforms, it will be an empty string. -.. genex:: $<TARGET_LINKER_LIBRARY_FILE_BASE_NAME:tgt> +.. genex:: $<TARGET_LINKER_LIBRARY_FILE_BASE_NAME:tgt[,POSTFIX:(INCLUDE|EXCLUDE)]> .. versionadded:: 3.27 + .. versionadded:: 4.2 + The ``POSTFIX`` option can be used to control the inclusion or not + of the :prop_tgt:`<CONFIG>_POSTFIX` target property value as part of the + base name. The default is ``POSTFIX:INCLUDE``. + Base name of library file used to link the target ``tgt``, i.e. - :genex:`$<TARGET_LINKER_LIBRARY_FILE_NAME:tgt>` without prefix and suffix. - For example, if target file name is ``libbase.a``, the base name is ``base``. + :genex:`$<TARGET_LINKER_LIBRARY_FILE_NAME:tgt>` without prefix and + suffix,and, optionally, postfix. + For example, if the target file name is ``libbase_postfix.a``, the base name + is: + + * ``base_postfix`` for ``$<TARGET_LINKER_LIBRARY_FILE_BASE_NAME:tgt>`` or + ``$<TARGET_LINKER_LIBRARY_FILE_BASE_NAME:tgt,POSTFIX:INCLUDE>``. + * ``base`` for + ``$<TARGET_LINKER_LIBRARY_FILE_BASE_NAME:tgt,POSTFIX:EXCLUDE>``. See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, and :prop_tgt:`LIBRARY_OUTPUT_NAME` target properties, their @@ -2314,13 +3080,25 @@ (``.lib``, ``.tbd``). So, when no import file is involved in the link step, an empty string is returned. -.. genex:: $<TARGET_LINKER_IMPORT_FILE_BASE_NAME:tgt> +.. genex:: $<TARGET_LINKER_IMPORT_FILE_BASE_NAME:tgt[,POSTFIX:(INCLUDE|EXCLUDE)]> .. versionadded:: 3.27 + .. versionadded:: 4.2 + The ``POSTFIX`` option can be used to control the inclusion or not + of the :prop_tgt:`<CONFIG>_POSTFIX` target property value as part of the + base name. The default is ``POSTFIX:INCLUDE``. + Base name of the import file used to link the target ``tgt``, i.e. - :genex:`$<TARGET_LINKER_IMPORT_FILE_NAME:tgt>` without prefix and suffix. - For example, if target file name is ``libbase.tbd``, the base name is ``base``. + :genex:`$<TARGET_LINKER_IMPORT_FILE_NAME:tgt>` without prefix and suffix, + and, optionally, postfix. + For example, if the target file name is ``libbase_postfix.tbd``, the base + name is + + * ``base_postfix`` for ``$<TARGET_LINKER_IMPORT_FILE_BASE_NAME:tgt>`` or + ``$<TARGET_LINKER_IMPORT_FILE_BASE_NAME:tgt,POSTFIX:INCLUDE>``. + * ``base`` for + ``$<TARGET_LINKER_IMPORT_FILE_BASE_NAME:tgt,POSTFIX:EXCLUDE>``. See also the :prop_tgt:`OUTPUT_NAME` and :prop_tgt:`ARCHIVE_OUTPUT_NAME`, target properties, their configuration-specific variants @@ -2423,23 +3201,46 @@ Full path to the linker generated program database file (.pdb) where ``tgt`` is the name of a target. + .. versionchanged:: 4.2 + The postfix, as specified by :prop_tgt:`DEBUG_POSTFIX` or + :prop_tgt:`<CONFIG>_POSTFIX` target properties, is always included in the + ``PDB`` file name. See the policy :policy:`CMP0202`. + See also the :prop_tgt:`PDB_NAME` and :prop_tgt:`PDB_OUTPUT_DIRECTORY` target properties and their configuration specific variants :prop_tgt:`PDB_NAME_<CONFIG>` and :prop_tgt:`PDB_OUTPUT_DIRECTORY_<CONFIG>`. -.. genex:: $<TARGET_PDB_FILE_BASE_NAME:tgt> +.. genex:: $<TARGET_PDB_FILE_BASE_NAME:tgt[,POSTFIX:(INCLUDE|EXCLUDE)]> .. versionadded:: 3.15 Base name of the linker generated program database file (.pdb) where ``tgt`` is the name of a target. - The base name corresponds to the target PDB file name (see - ``$<TARGET_PDB_FILE_NAME:tgt>``) without prefix and suffix. For example, - if target file name is ``base.pdb``, the base name is ``base``. + .. versionadded:: 4.2 + The ``POSTFIX`` option can be used to control the inclusion or not + of the :prop_tgt:`<CONFIG>_POSTFIX` target property value as part of the + base name. The default is ``POSTFIX:INCLUDE``. - See also the :prop_tgt:`PDB_NAME` target property, and its - configuration-specific variant :prop_tgt:`PDB_NAME_<CONFIG>`. + .. versionchanged:: 4.2 + The postfix, as specified by :prop_tgt:`DEBUG_POSTFIX` or + :prop_tgt:`<CONFIG>_POSTFIX` target properties, is always included in the + ``PDB`` base name, except if the ``POSTFIX`` option has the value + ``EXCLUDE``. See the policy :policy:`CMP0202`. + + The base name corresponds to the target PDB file name (see + ``$<TARGET_PDB_FILE_NAME:tgt>``) without prefix and suffix, and, optionally, + postfix. For example, if the target file name is ``base_postfix.pdb``, the + base name is + + * ``base_postfix`` for ``$<TARGET_PDB_FILE_BASE_NAME:tgt>`` or + ``$<TARGET_PDB_FILE_BASE_NAME:tgt,POSTFIX:INCLUDE>``. + * ``base`` for ``$<TARGET_PDB_FILE_BASE_NAME:tgt,POSTFIX:EXCLUDE>``. + + See also the :prop_tgt:`OUTPUT_NAME` and :prop_tgt:`PDB_NAME` target + properties, their configuration-specific variants + :prop_tgt:`OUTPUT_NAME_<CONFIG>` and :prop_tgt:`PDB_NAME_<CONFIG>`, and the + :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target properties. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. @@ -2558,6 +3359,13 @@ This generator expression can e.g. be used to create a batch file using :command:`file(GENERATE)` which sets the PATH environment variable accordingly. +.. genex:: $<TARGET_INTERMEDIATE_DIR:tgt> + + .. versionadded:: 4.2 + + The full path to the directory where intermediate target files, such as + object and dependency files, are stored. + Export And Install Expressions ------------------------------
diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst index 9647f0d..a68a1f7 100644 --- a/Help/manual/cmake-generators.7.rst +++ b/Help/manual/cmake-generators.7.rst
@@ -63,6 +63,14 @@ /generator/Ninja /generator/Ninja Multi-Config +FASTBuild Generator +^^^^^^^^^^^^^^^^^^^ + +.. toctree:: + :maxdepth: 1 + + /generator/FASTBuild + .. _`IDE Build Tool Generators`: IDE Build Tool Generators @@ -92,6 +100,7 @@ /generator/Visual Studio 15 2017 /generator/Visual Studio 16 2019 /generator/Visual Studio 17 2022 + /generator/Visual Studio 18 2026 Other Generators ^^^^^^^^^^^^^^^^
diff --git a/Help/manual/cmake-instrumentation.7.rst b/Help/manual/cmake-instrumentation.7.rst index e20d8a6..582adf8 100644 --- a/Help/manual/cmake-instrumentation.7.rst +++ b/Help/manual/cmake-instrumentation.7.rst
@@ -3,7 +3,7 @@ cmake-instrumentation(7) ************************ -.. versionadded:: 4.0 +.. versionadded:: 4.3 .. only:: html @@ -12,75 +12,107 @@ Introduction ============ -.. note:: - - This feature is only available when experimental support for instrumentation - has been enabled by the ``CMAKE_EXPERIMENTAL_INSTRUMENTATION`` gate. - The CMake Instrumentation API allows for the collection of timing data, target information and system diagnostic information during the configure, generate, build, test and install steps for a CMake project. -This feature is only available for projects using the :ref:`Makefile Generators` -or the :ref:`Ninja Generators`. - All interactions with the CMake instrumentation API must specify both an API version and a Data version. At this time, there is only one version for each of these: the `API v1`_ and `Data v1`_. +.. note:: + + This feature is only available for projects using the + :ref:`Makefile Generators`, :ref:`Ninja Generators` or :generator:`FASTBuild`. + +Overview +-------- + +CMake Instrumentation works in 2 major stages: `Data Collection`_, and +`Indexing`_. + +`Data Collection`_ is the process by which CMake writes out instrumentation +data into a project build tree. The commands instrumented in this way range +from overall builds, to individual compile commands. The full list of commands +instrumented is documented under the `v1 Snippet File`_. + +Collected data will accumulate until `Indexing`_ occurs: the process of +collating the generated data. Indexing occurs on events called "hooks", +which can be configured as part of the `v1 Query Files`_. A `v1 Index File`_ is +created and passed to any user-defined `Callbacks`_ provided to process +the data. Once all `Callbacks`_ have run, CMake deletes the files. + +Without the need for any custom `Callbacks`_, CMake can submit instrumentation +data to `CDash`_, or generate a `Google Trace File`_ for visualization. + Data Collection --------------- -Whenever a command is executed with -instrumentation enabled, a `v1 Snippet File`_ is created in the project build -tree with data specific to that command. These files remain until after -`Indexing`_ occurs. +Whenever a command is executed with instrumentation enabled, a +`v1 Snippet File`_ is created in the project build tree with data specific to +that command. These files remain until after `Indexing`_ occurs. -CMake sets the :prop_gbl:`RULE_LAUNCH_COMPILE`, :prop_gbl:`RULE_LAUNCH_LINK` and -:prop_gbl:`RULE_LAUNCH_CUSTOM` global properties to use the -``ctest --instrument`` launcher in order to capture details of each compile, link -and custom command respectively. If the project has been configured with :module:`CTestUseLaunchers`, -``ctest --instrument`` will also include the behavior usually performed by -``ctest --launch``. +CMake sets the :prop_gbl:`RULE_LAUNCH_COMPILE`, :prop_gbl:`RULE_LAUNCH_LINK` +and :prop_gbl:`RULE_LAUNCH_CUSTOM` global properties to wrap each compile, link +and custom command invocation in a launcher that performs instrumentation and +writes out a `v1 Snippet File`_. If the project has been configured with +:module:`CTestUseLaunchers`, the launcher will collect instrumentation data in +addition to performing the communication typically handled by that module. + +.. _`cmake-instrumentation Indexing`: Indexing -------- -Indexing is the process of collating generated instrumentation data. Indexing -occurs at specific intervals called hooks, such as after every build. These -hooks are configured as part of the `v1 Query Files`_. Whenever a hook is -triggered, an index file is generated containing a list of snippet files newer -than the previous indexing. +Indexing is the process of collating generated instrumentation data. The +available hooks to trigger indexing include options such as after every build, +or every :manual:`ctest <ctest(1)>` invocation, and are configured as part of +the `v1 Query Files`_. Whenever a hook is triggered, an index file is generated +containing a list of snippet files newer than the previous indexing. This index +file is passed to user-defined `Callbacks`_ commands to process the data. Indexing and can also be performed by manually invoking -``ctest --collect-instrumentation <build>``. +:option:`ctest --collect-instrumentation`. + +Indexing, and the subsequent callbacks, will not occur concurrently in a +single build tree. When multiple hooks trigger indexing at the same time, +a file-based lock is used to ensure one indexing completes, executes all of its +callbacks, and deletes the instrumentation data before the next indexing can +begin. + +.. _`cmake-instrumentation Callbacks`: Callbacks ---------- +^^^^^^^^^ As part of the `v1 Query Files`_, users can provide a list of callbacks intended to handle data collected by this feature. Whenever `Indexing`_ occurs, each provided callback is executed, passing the -path to the generated index file as an argument. +path to the generated `v1 Index File`_ as an additional argument. -These callbacks, defined either at the user-level or project-level should read +These callbacks, defined either at the user-level or project-level, should read the instrumentation data and perform any desired handling of it. The index file and its listed snippets are automatically deleted by CMake once all callbacks have completed. Note that a callback should never move or delete these data files manually as they may be needed by other callbacks. +If indexing is triggered again before `Callbacks`_ have finished running, +the generated index file will contain only instrumentation data generated since +the previous indexing. + Enabling Instrumentation ======================== Instrumentation can be enabled either for an individual CMake project, or -for all CMake projects configured and built by a user. For both cases, -see the `v1 Query Files`_ for details on configuring this feature. +for all CMake projects configured and built by a user. In all cases, a "query" +represents a request for instrumentation behavior. See the `v1 Query Files`_ +for details on configuring this feature. Enabling Instrumentation at the Project-Level --------------------------------------------- -Project code can contain instrumentation queries with the +Project code can contain instrumentation queries by using the :command:`cmake_instrumentation` command. In addition, query files can be placed manually under @@ -94,13 +126,15 @@ the :envvar:`CMAKE_CONFIG_DIR` under ``<config_dir>/instrumentation/<version>/query/``. +.. _`CDash`: + Enabling Instrumentation for CDash Submissions ---------------------------------------------- -You can enable instrumentation when using CTest in :ref:`Dashboard Client` -mode by setting the :envvar:`CTEST_USE_INSTRUMENTATION` environment variable -to the current UUID for the ``CMAKE_EXPERIMENTAL_INSTRUMENTATION`` feature. -Doing so automatically enables the ``dynamicSystemInformation`` query. +You can enable instrumentation when using :module:`CTest` in +:ref:`Dashboard Client` mode by setting the :envvar:`CTEST_USE_INSTRUMENTATION` +environment variable. Doing so automatically enables the +``dynamicSystemInformation`` option. The following table shows how each type of instrumented command gets mapped to a corresponding type of CTest XML file. @@ -125,13 +159,21 @@ You can instead choose to report the full command line (including arguments) by setting :envvar:`CTEST_USE_VERBOSE_INSTRUMENTATION` to 1. +Alternatively, you can use the `v1 Query Files`_ to enable instrumentation for +CDash using the ``cdashSubmit`` and ``cdashVerbose`` options. + +In order for the submitted ``Build.xml`` file to group the snippet files +correctly, all configure and build commands should be executed with CTest in +Dashboard Client mode. + .. _`cmake-instrumentation API v1`: API v1 ====== -The API version specifies both the subdirectory layout of the instrumentation data, -and the format of the query files. +The API version specifies the layout of the instrumentation directory, as well +as the general format of the query files and :command:`cmake_instrumentation` +command arguments. The Instrumentation API v1 is housed in the ``instrumentation/v1/`` directory under either ``<build>/.cmake/`` for output data and project-level queries, or @@ -146,14 +188,30 @@ ``query/generated/`` Holds query files generated by a CMake project with the - :command:`cmake_instrumentation` command. These files are owned by CMake and - are deleted and regenerated automatically during the CMake configure step. + :command:`cmake_instrumentation` command or the + :envvar:`CTEST_USE_INSTRUMENTATION` variable. These files are owned by CMake + and are deleted and regenerated automatically during the CMake configure + step. ``data/`` Holds instrumentation data collected on the project. CMake owns all data files, they should never be removed by other processes. Data collected here remains until after `Indexing`_ occurs and all `Callbacks`_ are executed. +``data/index/`` + A subset of the collected data, containing any + `v1 Index Files <v1 Index File_>`_. + +``data/content/`` + A subset of the collected data, containing any + `v1 CMake Content Files <v1 CMake Content File_>`_. + +``data/trace/`` + A subset of the collected data, containing the `Google Trace File`_ created + from the most recent `Indexing`_. Unlike other data files, the most recent + trace file remains even after `Indexing`_ occurs and all `Callbacks`_ are + executed, until the next time `Indexing`_ occurs. + ``cdash/`` Holds temporary files used internally to generate XML content to be submitted to CDash. @@ -185,16 +243,23 @@ should be one of the following: * ``postGenerate`` - * ``preBuild`` (called when ``ninja`` or ``make`` is invoked; unavailable on Windows) - * ``postBuild`` (called when ``ninja`` or ``make`` completes; unavailable on Windows) - * ``preCMakeBuild`` (called when ``cmake --build`` is invoked) - * ``postCMakeBuild`` (called when ``cmake --build`` completes) - * ``postInstall`` - * ``postTest`` + * ``preBuild`` (called when ``ninja`` or ``make`` is invoked) + * ``postBuild`` (called when ``ninja`` or ``make`` completes) + * ``preCMakeBuild`` (called when :option:`cmake --build` is invoked) + * ``postCMakeBuild`` (called when :option:`cmake --build` completes) + * ``postCMakeInstall`` + * ``postCMakeWorkflow`` + * ``postCTest`` -``queries`` - A list of strings specifying additional optional data to collect during - instrumentation. Elements in this list should be one of the following: + ``preBuild`` and ``postBuild`` are not supported when using the + :generator:`MSYS Makefiles` or :generator:`FASTBuild` generators. + Additionally, they will not be triggered when the build tool is invoked by + :option:`cmake --build`. + +``options`` + A list of strings used to enable certain optional behavior, including the + collection of certain additional data. Elements in this list should be one of + the following: ``staticSystemInformation`` Enables collection of the static information about the host machine CMake @@ -207,13 +272,33 @@ generated by CMake, and includes information from immediately before and after the command is executed. + ``cdashSubmit`` + Enables including instrumentation data in CDash. This is + equivalent to having the :envvar:`CTEST_USE_INSTRUMENTATION` environment + variable enabled. + + ``cdashVerbose`` + Enables including the full untruncated commands in data submitted to + CDash. Equivalent to having the + :envvar:`CTEST_USE_VERBOSE_INSTRUMENTATION` and + :envvar:`CTEST_USE_INSTRUMENTATION` environment variables enabled. + + ``trace`` + Enables generation of a `Google Trace File`_ during `Indexing`_ to + visualize data from the `v1 Snippet Files <v1 Snippet File_>`_ collected. + The ``callbacks`` listed will be invoked during the specified hooks *at a minimum*. When there are multiple query files, the ``callbacks``, -``hooks`` and ``queries`` between them will be merged. Therefore, if any query +``hooks`` and ``options`` between them will be merged. Therefore, if any query file includes any ``hooks``, every ``callback`` across all query files will be executed at every ``hook`` across all query files. Additionally, if any query -file includes any optional ``queries``, the optional query data will be present -in all data files. +file requests optional data using the ``options`` field, any related data will +be present in all snippet files. User written ``callbacks`` should be able to +handle the presence of this optional data, since it may be requested by an +unrelated query. + +The JSON format is described in machine-readable form by +:download:`this JSON schema </manual/instrumentation/query-v1-schema.json>`. Example: @@ -227,25 +312,31 @@ ], "hooks": [ "postCMakeBuild", - "postInstall" + "postCMakeInstall" ], - "queries": [ + "options": [ "staticSystemInformation", - "dynamicSystemInformation" + "dynamicSystemInformation", + "cdashSubmit", + "trace" ] } -In this example, after every ``cmake --build`` or ``cmake --install`` -invocation, an index file ``index-<timestamp>.json`` will be generated in -``<build>/.cmake/instrumentation/v1/data`` containing a list of data snippet -files created since the previous indexing. The commands -``/usr/bin/python callback.py index-<timestamp>.json`` and -``/usr/bin/cmake -P callback.cmake arg index-<timestamp>.json`` will be executed in -that order. The index file will contain the ``staticSystemInformation`` data and -each snippet file listed in the index will contain the -``dynamicSystemInformation`` data. Once both callbacks have completed, the index -file and all snippet files listed by it will be deleted from the project build -tree. +In this example, after every :option:`cmake --build` or +:option:`cmake --install` invocation, an index file ``index-<timestamp>.json`` +will be generated in ``<build>/.cmake/instrumentation/v1/data/index`` +containing a list of data snippet files created since the previous indexing. +The commands ``/usr/bin/python callback.py index-<timestamp>.json`` and +``/usr/bin/cmake -P callback.cmake arg index-<timestamp>.json`` will be +executed in that order. The index file will contain the +``staticSystemInformation`` data and each snippet file listed in the index will +contain the ``dynamicSystemInformation`` data. Additionally, the index file +will contain the path to the generated `Google Trace File`_. Once both +callbacks have completed, the index file and data files listed by it (including +snippet files, but not the trace file) will be deleted from the project build +tree. The instrumentation data will be present in the XML files submitted to +CDash, but with truncated command strings because ``cdashVerbose`` was not +enabled. .. _`cmake-instrumentation Data v1`: @@ -253,30 +344,46 @@ ======= Data version specifies the contents of the output files generated by the CMake -instrumentation API as part of the `Data Collection`_ and `Indexing`_. There are -two types of data files generated: the `v1 Snippet File`_ and `v1 Index File`_. -When using the `API v1`_, these files live in +instrumentation API as part of the `Data Collection`_ and `Indexing`_. A new +version number will be created whenever previously included data is removed or +reformatted such that scripts written to parse this data may become +incompatible with the new format. There are four types of data files generated: +the `v1 Snippet File`_, `v1 Index File`_, `v1 CMake Content File`_, and the +`Google Trace File`_. When using the `API v1`_, these files live in ``<build>/.cmake/instrumentation/v1/data/`` under the project build tree. +.. _`cmake-instrumentation v1 Snippet File`: + v1 Snippet File --------------- Snippet files are generated for every compile, link and custom command invoked -as part of the CMake build or install step and contain instrumentation data about -the command executed. Additionally, snippet files are created for the following: +as part of the CMake build or install step and contain instrumentation data +about the command executed. Additionally, snippet files are created for the +following: * The CMake configure step * The CMake generate step -* Entire build step (executed with ``cmake --build``) -* Entire install step (executed with ``cmake --install``) -* Each ``ctest`` invocation -* Each individual test executed by ``ctest``. +* Entire build step (executed with :option:`cmake --build`) +* Entire install step (executed with :option:`cmake --install`) +* Each time :manual:`ctest <ctest(1)>` is invoked to + :ref:`run tests <Run Tests>` (even if no tests are found) +* Each individual test executed by :manual:`ctest <ctest(1)>` These files remain in the build tree until after `Indexing`_ occurs and any user-specified `Callbacks`_ are executed. -Snippet files have a filename with the syntax ``<role>-<hash>-<timestamp>.json`` -and contain the following data: +.. note:: + + Configure and generate snippet files are not written by CMake until the + generate step is complete. When using :manual:`cmake-gui(1)` or + :manual:`ccmake(1)`, triggering only configure step(s) without generating the + project files will not generate any configure snippets. Once the generate + step is run, there will be one configure snippet for each time the configure + step was run. + +Snippet files have a filename with the syntax +``<role>-<hash>-<timestamp>.json`` and contain the following data: ``version`` The Data version of the snippet file, an integer. Currently the version is @@ -289,7 +396,8 @@ The working directory in which the ``command`` was executed. ``result`` - The exit-value of the command, an integer. + The exit code of the command, an integer. This will be ``null`` when + ``role`` is ``build``. ``role`` The type of command executed, which will be one of the following values: @@ -299,24 +407,20 @@ * ``compile``: an individual compile step invoked during the build * ``link``: an individual link step invoked during the build * ``custom``: an individual custom command invoked during the build - * ``build``: a complete ``make`` or ``ninja`` invocation. Only generated if ``preBuild`` or ``postBuild`` hooks are enabled. - * ``cmakeBuild``: a complete ``cmake --build`` invocation - * ``cmakeInstall``: a complete ``cmake --install`` invocation + * ``build``: a complete ``make`` or ``ninja`` invocation + (not through :option:`cmake --build`). + * ``cmakeBuild``: a complete :option:`cmake --build` invocation + * ``cmakeInstall``: a complete :option:`cmake --install` invocation * ``install``: an individual ``cmake -P cmake_install.cmake`` invocation - * ``ctest``: a complete ``ctest`` invocation - * ``test``: a single test executed by CTest + * ``ctest``: a complete :manual:`ctest <ctest(1)>` command invocation + * ``test``: a single test executed by :manual:`ctest <ctest(1)>` ``target`` - The CMake target associated with the command. Only included when ``role`` is - ``compile`` or ``link``. - - ``targetType`` - The :prop_tgt:`TYPE` of the target. Only included when ``role`` is - ``link``. - - ``targetLabels`` - The :prop_tgt:`LABELS` of the target. Only included when ``role`` is - ``link``. + The CMake target associated with the command. Only included when ``role`` + is ``compile`` or ``link``, or when ``role`` is ``custom`` and the custom + command is attached to a target with :command:`add_custom_command(TARGET)`. + In conjunction with ``cmakeContent``, this can be used to look up the + target :prop_tgt:`TYPE` and :prop_tgt:`LABELS`. ``timeStart`` Time at which the command started, expressed as the number of milliseconds @@ -338,15 +442,17 @@ The source file being compiled. Only included when ``role`` is ``compile``. ``language`` - The language of the source file being compiled. Only included when ``role`` is - ``compile``. + The language of the source file being compiled. Only included when ``role`` + is ``compile`` or ``link``. ``testName`` - The name of the test being executed. Only included when ``role`` is ``test``. + The name of the test being executed. Only included when ``role`` is + ``test``. ``config`` - The type of build, such as ``Release`` or ``Debug``. Only included when - ``role`` is ``compile``, ``link`` or ``test``. + The :ref:`Build Configuration <Build Configurations>`, such as ``Release`` + or ``Debug``. Only included when ``role`` is one of: ``compile``, ``link``, + ``custom``, ``install``, ``test``. ``dynamicSystemInformation`` Specifies the dynamic information collected about the host machine @@ -358,13 +464,27 @@ The Host Memory Used in KiB at ``timeStart``. ``afterHostMemoryUsed`` - The Host Memory Used in KiB at ``timeStop``. + The Host Memory Used in KiB at ``timeStart + duration``. ``beforeCPULoadAverage`` - The Average CPU Load at ``timeStart``. + The Average CPU Load at ``timeStart``, or ``null`` if it cannot be + determined. ``afterCPULoadAverage`` - The Average CPU Load at ``timeStop``. + The Average CPU Load at ``timeStart + duration``, or ``null`` if it + cannot be determined. + + ``cmakeContent`` + The path to a `v1 CMake Content File`_ located under ``data``, which + contains information about the CMake configure and generate steps + responsible for generating the ``command`` in this snippet. When using + :manual:`cmake-gui(1)` or :manual:`ccmake(1)`, this field may be ``null`` + for all configure steps up to the most recent one before the generate step. + + ``showOnly`` + A boolean representing whether the + :option:`--show-only <ctest --show-only>` option was passed to + :manual:`ctest <ctest(1)>`. Only included when ``role`` is ``ctest``. Example: @@ -374,7 +494,7 @@ "version": 1, "command" : "\"/usr/bin/c++\" \"-MD\" \"-MT\" \"CMakeFiles/main.dir/main.cxx.o\" \"-MF\" \"CMakeFiles/main.dir/main.cxx.o.d\" \"-o\" \"CMakeFiles/main.dir/main.cxx.o\" \"-c\" \"<src>/main.cxx\"", "role" : "compile", - "return" : 1, + "result" : 1, "target": "main", "language" : "C++", "outputs" : [ "CMakeFiles/main.dir/main.cxx.o" ], @@ -389,15 +509,17 @@ "beforeHostMemoryUsed" : 6635832.0 }, "timeStart" : 1737053448177, - "duration" : 31 + "duration" : 31, + "cmakeContent" : "content/cmake-2025-07-11T12-46-32-0572.json" } v1 Index File ------------- -Index files contain a list of `v1 Snippet File`_. It serves as an entry point -for navigating the instrumentation data. They are generated whenever `Indexing`_ -occurs and deleted after any user-specified `Callbacks`_ are executed. +Index files contain a list of `v1 Snippet Files <v1 Snippet File_>`_. It +serves as an entry point for navigating the instrumentation data. They are +generated whenever `Indexing`_ occurs and deleted after any user-specified +`Callbacks`_ are executed. ``version`` The Data version of the index file, an integer. Currently the version is @@ -411,18 +533,35 @@ ``hook`` The name of the hook responsible for generating the index file. In addition - to the hooks that can be specified by one of the `v1 Query Files`_, this value may - be set to ``manual`` if indexing is performed by invoking - ``ctest --collect-instrumentation <build>``. + to the hooks that can be specified by one of the `v1 Query Files`_, this + value may be set to ``manual`` if indexing is performed by invoking + :option:`ctest --collect-instrumentation`. + + Note that the hook is not directly tied to what data may be available. + A ``postBuild`` hook, for example, may include ``test`` or ``install`` + snippets, if these steps were run since the previous indexing. ``snippets`` - Contains a list of `v1 Snippet File`_. This includes all snippet files - generated since the previous index file was created. The file paths are - relative to ``dataDir``. + Contains a list of `v1 Snippet Files <v1 Snippet File_>`_. This includes all + snippet files generated since the previous index file was created. The file + paths are relative to ``dataDir``. + + This list may be empty if indexing was run twice in succession, such as when + building multiple times with both the ``preBuild`` and ``postBuild`` hooks + enabled. + +``trace`` + Contains the path to the `Google Trace File`_. This includes data from all + corresponding ``snippets`` in the index file. The file path is relative to + ``dataDir``. Only included when enabled by the `v1 Query Files`_. ``staticSystemInformation`` Specifies the static information collected about the host machine - CMake is being run from. Only included when enabled by the `v1 Query Files`_. + CMake is being run from. If CMake is unable to determine the value of any + given field, it will be ``null``. See :command:`cmake_host_system_information` + for a description of each of the following fields. + + Only included when enabled by the `v1 Query Files`_. * ``OSName`` * ``OSPlatform`` @@ -432,6 +571,7 @@ * ``hostname`` * ``is64Bits`` * ``modelId`` + * ``modelName`` * ``numberOfLogicalCPU`` * ``numberOfPhysicalCPU`` * ``processorAPICID`` @@ -462,5 +602,90 @@ "ctest-<hash>-<timestamp>.json", "test-<hash>-<timestamp>.json", "test-<hash>-<timestamp>.json", - ] + ], + "trace": "trace/trace-<timestamp>.json" } + +.. _`cmake-instrumentation v1 CMake Content File`: + +v1 CMake Content File +--------------------- + +CMake content files contain information about the CMake configure and generate +steps. Each `v1 Snippet File`_ provides the path to one of these files +corresponding to the CMake invocation responsible for generating its command. + +Each CMake content file contains the following: + + ``project`` + The value of :variable:`CMAKE_PROJECT_NAME`. + + ``custom`` + An object containing arbitrary JSON data specified by the user with the + :ref:`cmake_instrumentation CUSTOM_CONTENT` functionality of the + :command:`cmake_instrumentation` command. + + ``targets`` + An object containing CMake targets, indexed by name, that have + corresponding instrumentation data. Each target contains the following: + + ``type`` + The :prop_tgt:`TYPE` property of the target. Only ``EXECUTABLE``, + ``STATIC_LIBRARY``, ``SHARED_LIBRARY``, ``MODULE_LIBRARY`` and + ``OBJECT_LIBRARY`` targets are included. + + ``labels`` + The :prop_tgt:`LABELS` property of the target. + +.. _`cmake-instrumentation Google Trace File`: + +Google Trace File +----------------- + +CMake can generate a file in the `Google Trace Event Format`_ to help visualize +collected instrumentation data. Enabling the ``trace`` option in the +`v1 Query Files`_ causes such a file to be generated under +``<build>/.cmake/instrumentation/v1/data/trace`` whenever `Indexing`_ occurs. + +Generated trace files include data from all +`v1 Snippet Files <v1 Snippet File_>`_ listed in the current index file. + +When instrumentation data is deleted by CMake after `Indexing`_, the most +recent trace file remains so that it can be manually inspected without the need +for any custom `Callbacks`_. + +Trace files are stored in the ``JSON Array Format``, where each +`v1 Snippet File`_ corresponds to a single trace event object. Each trace +event contains the following data: + +``name`` + A descriptive name generated by CMake based on the given snippet data. + +``cat`` + The ``role`` from the `v1 Snippet File`_. + +``ph`` + Currently, always ``"X"`` to represent "Complete Events". + +``ts`` + The ``timeStart`` from the `v1 Snippet File`_, converted from milliseconds to + microseconds. + +``dur`` + The ``duration`` from the `v1 Snippet File`_, converted from milliseconds to + microseconds. + +``pid`` + Unused (always zero). + +``tid`` + An integer ranging from zero to the number of concurrent jobs with which the + processes being indexed ran. This is a synthetic ID calculated by CMake + based on the ``ts`` and ``dur`` of all snippet files being indexed in + order to produce a more useful visualization of the process concurrency. + +``args`` + Contains all data from the `v1 Snippet File`_ corresponding to this trace + event. + +.. _`Google Trace Event Format`: https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview
diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index d590b5a..777ef0b 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst
@@ -12,6 +12,8 @@ CMake input files are written in the "CMake Language" in source files named ``CMakeLists.txt`` or ending in a ``.cmake`` file name extension. +The term *listfile* is a general name for any such source file containing +CMake commands that the tool processes. CMake Language source files in a project are organized into: @@ -76,6 +78,11 @@ .. _Byte-Order Mark: https://en.wikipedia.org/wiki/Byte_order_mark +.. versionadded:: 4.3 + + The :command:`cmake_host_system_information` command's ``LOCALE_CHARSET`` + query returns the expected character set encoding. + Source Files ------------
diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index d9b9f2e..265a128 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst
@@ -30,8 +30,8 @@ /module/CheckFortranSourceCompiles /module/CheckFortranSourceRuns /module/CheckFunctionExists - /module/CheckIncludeFileCXX /module/CheckIncludeFile + /module/CheckIncludeFileCXX /module/CheckIncludeFiles /module/CheckIPOSupported /module/CheckLanguage @@ -55,8 +55,6 @@ /module/CMakeBackwardCompatibilityCXX /module/CMakeDependentOption /module/CMakeFindDependencyMacro - /module/CMakeFindPackageMode - /module/CMakeGraphVizOptions /module/CMakePackageConfigHelpers /module/CMakePrintHelpers /module/CMakePrintSystemInformation @@ -69,7 +67,6 @@ /module/CSharpUtilities /module/CTest /module/CTestCoverageCollectGCOV - /module/CTestScriptMode /module/CTestUseLaunchers /module/DeployQt4 /module/ExternalData @@ -186,7 +183,6 @@ /module/FindOpenSSL /module/FindOpenThreads /module/Findosg - /module/Findosg_functions /module/FindosgAnimation /module/FindosgDB /module/FindosgFX @@ -232,8 +228,8 @@ /module/FindSDL_sound /module/FindSDL_ttf /module/FindSelfPackers - /module/FindSquish /module/FindSQLite3 + /module/FindSquish /module/FindSubversion /module/FindSWIG /module/FindTCL @@ -271,7 +267,6 @@ /module/Documentation /module/GetPrerequisites /module/MacroAddFileDependencies - /module/SquishTestScript /module/TestBigEndian /module/TestCXXAcceptsFlag /module/Use_wxWindows @@ -322,3 +317,17 @@ /module/CPackProductBuild /module/CPackRPM /module/CPackWIX + +Miscellaneous Modules +--------------------- + +These internal modules are not intended to be included directly in projects: + +.. toctree:: + :maxdepth: 1 + + /module/CMakeFindPackageMode + /module/CMakeGraphVizOptions + /module/CTestScriptMode + /module/Findosg_functions + /module/SquishTestScript
diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 45e0ca0..c6bdacb 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst
@@ -7,6 +7,8 @@ .. contents:: +.. _cmake-policies-intro: + Introduction ============ @@ -34,10 +36,10 @@ .. code-block:: cmake - cmake_minimum_required(VERSION 3.10...4.0) + cmake_minimum_required(VERSION 3.10...4.2) -This uses the ``<min>...<max>`` syntax to enable the ``NEW`` behaviors -of policies introduced in CMake 4.0 and earlier while only requiring a +This uses the ``<min>...<policy_max>`` syntax to enable the ``NEW`` behaviors +of policies introduced in CMake 4.2 and earlier while only requiring a minimum version of CMake 3.10. The project is expected to work with both the ``OLD`` and ``NEW`` behaviors of policies introduced between those versions. @@ -92,6 +94,33 @@ The following policies are supported. +Policies Introduced by CMake 4.3 +-------------------------------- + +.. toctree:: + :maxdepth: 1 + + CMP0210: CMAKE_<LANG>_LINK_FLAGS adds link flags to all target types. </policy/CMP0210> + CMP0209: Verify interface header sets checks executables without exports. </policy/CMP0209> + CMP0208: export(EXPORT) does not allow empty arguments. </policy/CMP0208> + CMP0207: file(GET_RUNTIME_DEPENDENCIES) normalizes paths before matching. </policy/CMP0207> + CMP0206: The CPack Archive Generator defaults to UID 0 and GID 0. </policy/CMP0206> + CMP0205: file(CREATE_LINK) with COPY_ON_ERROR copies directory content. </policy/CMP0205> + +Policies Introduced by CMake 4.2 +-------------------------------- + +.. toctree:: + :maxdepth: 1 + + CMP0204: A character set is always defined when targeting the MSVC ABI. </policy/CMP0204> + CMP0203: _WINDLL is defined for shared libraries targeting the MSVC ABI. </policy/CMP0203> + CMP0202: PDB file names always include their target's per-config POSTFIX. </policy/CMP0202> + CMP0201: Python::NumPy does not depend on Python::Development.Module. </policy/CMP0201> + CMP0200: Location and configuration selection for imported targets is more consistent. </policy/CMP0200> + CMP0199: $<CONFIG> does not match mapped configurations that are not selected. </policy/CMP0199> + CMP0198: CMAKE_PARENT_LIST_FILE is not defined in CMakeLists.txt. </policy/CMP0198> + Policies Introduced by CMake 4.1 --------------------------------
diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst index 9400a1b..8bbee0f 100644 --- a/Help/manual/cmake-presets.7.rst +++ b/Help/manual/cmake-presets.7.rst
@@ -44,6 +44,8 @@ The root object recognizes the following fields: +.. _`CMakePresets schema`: + ``$schema`` An optional string that provides a URI to the JSON schema that describes the structure of this JSON document. This field is used for validation and @@ -51,41 +53,11 @@ behavior of the document itself. If this field is not specified, the JSON document will still be valid, but tools that use JSON schema for validation and autocompletion may not function correctly. - This is allowed in preset files specifying version ``8`` or above. ``version`` - A required integer representing the version of the JSON schema. - The supported versions are: - - ``1`` - .. versionadded:: 3.19 - - ``2`` - .. versionadded:: 3.20 - - ``3`` - .. versionadded:: 3.21 - - ``4`` - .. versionadded:: 3.23 - - ``5`` - .. versionadded:: 3.24 - - ``6`` - .. versionadded:: 3.25 - - ``7`` - .. versionadded:: 3.27 - - ``8`` - .. versionadded:: 3.28 - - ``9`` - .. versionadded:: 3.30 - - ``10`` - .. versionadded:: 3.31 + A required integer representing the version of the JSON schema. See + `Versions`_ for discussion of the supported versions and the corresponding + version of CMake in which they were added. ``cmakeMinimumRequired`` An optional object representing the minimum version of CMake needed to @@ -168,7 +140,7 @@ ``name`` A required string representing the machine-friendly name of the preset. - This identifier is used in the :ref:`cmake --preset <CMake Options>` option. + This identifier is used in the :option:`cmake --preset` option. There must not be two configure presets in the union of ``CMakePresets.json`` and ``CMakeUserPresets.json`` in the same directory with the same name. However, a configure preset may have the same name as a build, test, @@ -176,11 +148,12 @@ ``hidden`` An optional boolean specifying whether or not a preset should be hidden. - If a preset is hidden, it cannot be used in the ``--preset=`` argument, - will not show up in the :manual:`CMake GUI <cmake-gui(1)>`, and does not - have to have a valid ``generator`` or ``binaryDir``, even from - inheritance. ``hidden`` presets are intended to be used as a base for - other presets to inherit via the ``inherits`` field. + If a preset is hidden, it cannot be used in the + :option:`--preset <cmake --preset>` argument, will not show up in the + :manual:`CMake GUI <cmake-gui(1)>`, and does not have to have a valid + ``generator`` or ``binaryDir``, even from inheritance. ``hidden`` presets are + intended to be used as a base for other presets to inherit via the + ``inherits`` field. ``inherits`` An optional array of strings representing the names of presets to inherit @@ -217,14 +190,16 @@ ``description`` An optional string with a human-friendly description of the preset. -``generator`` - 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``). In version ``3`` - or above, this field may be omitted to fall back to regular generator - discovery procedure. +.. _`CMakePresets generator`: - Note that for Visual Studio generators, unlike in the command line +``generator`` + An optional string representing the :manual:`generator <cmake-generators(7)>` + to use for the preset. If ``generator`` is not specified, it must be + inherited from the ``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 :ref:`Visual Studio generators`, unlike in the command line :option:`-G <cmake -G>` argument, you cannot include the platform name in the generator name. Use the ``architecture`` field instead. @@ -259,6 +234,8 @@ If no ``strategy`` field is given, or if the field uses the string form rather than the object form, the behavior is the same as ``"set"``. +.. _`CMakePresets toolchainFile`: + ``toolchainFile`` An optional string representing the path to the toolchain file. This field supports `macro expansion`_. If a relative path is specified, @@ -267,16 +244,20 @@ :variable:`CMAKE_TOOLCHAIN_FILE` value. It is allowed in preset files specifying version ``3`` or above. +.. _`CMakePresets graphviz`: + ``graphviz`` An optional string representing the path to the graphviz input file, that will contain all the library and executable dependencies - in the project. See the documentation for :module:`CMakeGraphVizOptions` - for more details. + in the project. See the documentation for :option:`cmake --graphviz` for + more details. This field supports `macro expansion`_. If a relative path is specified, it is calculated relative to the current working directory. It is allowed in preset files specifying version ``10`` or above. +.. _`CMakePresets binaryDir`: + ``binaryDir`` An optional string representing the path to the output binary directory. This field supports `macro expansion`_. If a relative path is specified, @@ -285,8 +266,11 @@ preset is ``hidden``). In version ``3`` or above, this field may be omitted. +.. _`CMakePresets installDir`: + ``installDir`` - An optional string representing the path to the installation directory. + An optional string representing the path to the installation directory, + which will be used as the :variable:`CMAKE_INSTALL_PREFIX` variable. 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. @@ -403,6 +387,8 @@ An optional boolean. Setting this to ``true`` is equivalent to passing :option:`--debug-find <cmake --debug-find>` on the command line. +.. _`CMakePresets trace`: + ``trace`` An optional object specifying trace options. This is allowed in preset files specifying version ``7``. The object may contain the following fields: @@ -458,7 +444,7 @@ ``name`` A required string representing the machine-friendly name of the preset. This identifier is used in the - :ref:`cmake --build --preset <Build Tool Mode>` option. + :option:`cmake --build --preset <cmake--build --preset>` option. There must not be two build presets in the union of ``CMakePresets.json`` and ``CMakeUserPresets.json`` in the same directory with the same name. However, a build preset may have the same name as a configure, test, @@ -467,7 +453,7 @@ ``hidden`` An optional boolean specifying whether or not a preset should be hidden. If a preset is hidden, it cannot be used in the - :option:`--preset <cmake --preset>` argument + :option:`--preset <cmake--build --preset>` argument and does not have to have a valid ``configurePreset``, even from inheritance. ``hidden`` presets are intended to be used as a base for other presets to inherit via the ``inherits`` field. @@ -507,6 +493,8 @@ ``description`` An optional string with a human-friendly description of the preset. +.. _`CMakePresets build environment`: + ``environment`` An optional map of environment variables. The key is the variable name (which may not be an empty string), and the value is either ``null`` or @@ -530,16 +518,16 @@ .. 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 + For a CMake project using :module:`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. + preset environment variables :envvar:`CC` and :envvar:`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 @@ -555,9 +543,20 @@ inherited build preset environments, but before environment variables explicitly specified in this build preset. +.. _`CMakePresets build jobs`: + ``jobs`` An optional integer. Equivalent to passing :option:`--parallel <cmake--build --parallel>` or ``-j`` on the command line. + If the value is ``0``, it is equivalent to passing ``--parallel`` with + ``<jobs>`` omitted; alternatively, one can define the environment variable + :envvar:`CMAKE_BUILD_PARALLEL_LEVEL` as an empty string using the + ``environment`` field. + + .. versionchanged:: 4.3 + + This field does not accept negative integer values, regardless of the + version in the preset file. ``targets`` An optional string or array of strings. Equivalent to passing @@ -573,14 +572,16 @@ An optional bool. If true, equivalent to passing :option:`--clean-first <cmake--build --clean-first>` on the command line. +.. _`CMakePresets resolvePackageReferences`: + ``resolvePackageReferences`` An optional string that specifies the package resolve mode. This is allowed in preset files specifying version ``4`` or above. Package references are used to define dependencies to packages from external package managers. Currently only NuGet in combination with the - Visual Studio generator is supported. If there are no targets that define - package references, this option does nothing. Valid values are: + :ref:`Visual Studio generators` is supported. If there are no targets that + define package references, this option does nothing. Valid values are: ``on`` Causes package references to be resolved before attempting a build. @@ -601,11 +602,11 @@ variable will be evaluated to decide, if package restoration should be performed. - When using the Visual Studio generator, package references are defined - using the :prop_tgt:`VS_PACKAGE_REFERENCES` property. Package references - are restored using NuGet. It can be disabled by setting the - ``CMAKE_VS_NUGET_PACKAGE_RESTORE`` variable to ``OFF``. This can also be - done from within a configure preset. + When using the :ref:`Visual Studio generators`, package references are + defined using the :prop_tgt:`VS_PACKAGE_REFERENCES` property. Package + references are restored using NuGet. It can be disabled by setting the + :variable:`CMAKE_VS_NUGET_PACKAGE_RESTORE` variable to ``OFF``. This can + also be done from within a configure preset. ``verbose`` An optional bool. If true, equivalent to passing @@ -717,6 +718,8 @@ :option:`--overwrite <ctest --overwrite>` for each value in the array. The array values support macro expansion. +.. _`CMakePresets output`: + ``output`` An optional object specifying output options. The object may contain the following fields. @@ -758,6 +761,8 @@ passing :option:`--output-log <ctest --output-log>` on the command line. This field supports macro expansion. +.. _`CMakePresets outputJUnitFile`: + ``outputJUnitFile`` An optional string specifying a path to a JUnit file. Equivalent to passing :option:`--output-junit <ctest --output-junit>` on the command line. @@ -786,6 +791,8 @@ :option:`--test-output-size-failed <ctest --test-output-size-failed>` on the command line. +.. _`CMakePresets testOutputTruncation`: + ``testOutputTruncation`` An optional string specifying the test output truncation mode. Equivalent to passing @@ -890,9 +897,21 @@ An optional bool. If true, equivalent to passing :option:`-F <ctest -F>` on the command line. +.. _`CMakePresets test jobs`: + ``jobs`` An optional integer. Equivalent to passing - :option:`--parallel <ctest --parallel>` on the command line. + :option:`--parallel <ctest --parallel>` on the command line. If the value + is ``0``, it is equivalent to unbounded parallelism. + + In preset files specifying version ``11`` or above, this field can also be + a string, in which case it must be empty, and is equivalent to passing + ``--parallel`` with ``<jobs>`` omitted. + + .. versionchanged:: 4.3 + + This field does not accept negative integer values, regardless of the + version in the preset file. ``resourceSpecFile`` An optional string. Equivalent to passing @@ -1083,9 +1102,25 @@ ``packageName`` An optional string representing the package name. + .. note:: + + Due to problems with the implementation, this field does not affect the + name of the final package file produced. Other aspects of the package + may use the value though, leading to inconsistencies. + A future CMake release may address this problem, but until then, it is + recommended that this field not be used. + ``packageVersion`` An optional string representing the package version. + .. note:: + + Due to problems with the implementation, this field does not affect the + name of the final package file produced. Other aspects of the package + may use the value though, leading to inconsistencies. + A future CMake release may address this problem, but until then, it is + recommended that this field not be used. + ``packageDirectory`` An optional string representing the directory in which to place the package. @@ -1104,8 +1139,8 @@ ``name`` A required string representing the machine-friendly name of the preset. This identifier is used in the - :ref:`cmake --workflow --preset <Workflow Mode>` option. There must not be - two workflow presets in the union of ``CMakePresets.json`` and + :option:`cmake --workflow --preset <cmake--workflow --preset>` option. There + must not be two workflow presets in the union of ``CMakePresets.json`` and ``CMakeUserPresets.json`` in the same directory with the same name. However, a workflow preset may have the same name as a configure, build, test, or package preset. @@ -1259,11 +1294,15 @@ This is a preset-specific macro. +.. _`CMakePresets hostSystemName`: + ``${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. +.. _`CMakePresets fileDir`: + ``${fileDir}`` Path to the directory containing the preset file which contains the macro. This is allowed in preset files specifying version ``4`` or above. @@ -1271,6 +1310,8 @@ ``${dollar}`` A literal dollar sign (``$``). +.. _`CMakePresets pathListSep`: + ``${pathListSep}`` Native character for separating lists of paths, such as ``:`` or ``;``. @@ -1314,6 +1355,123 @@ identifier prefix, followed by a ``.``, followed by the macro name. For example, the Example IDE could have ``$vendor{xide.ideInstallDir}``. +Versions +======== + +The JSON schema of ``CMakePresets.json`` and ``CMakeUserPresets.json`` +follows a version scheme where new versions are added and allowed in newer +versions of CMake. + +A list of the supported versions along with the version of CMake in which +they were added and a summary of the new features and changes is given below. + + ``1`` + .. versionadded:: 3.19 + + The initial version supports `Configure Presets <Configure Preset_>`_ + and `Macro Expansion`_. + + ``2`` + .. versionadded:: 3.20 + + * `Build Presets <Build Preset_>`_ were added. + * `Test Presets <Test Preset_>`_ were added. + + ``3`` + .. versionadded:: 3.21 + + * The `Condition`_ object was added for `Configure <Configure Preset_>`_, + `Build <Build Preset_>`_, and `Test Presets <Test Preset_>`_. + * Changes to `Configure Presets <Configure Preset_>`_ + + * The `installDir <CMakePresets installDir_>`_ field was added. + * The `toolchainFile <CMakePresets toolchainFile_>`_ field was added. + * The `binaryDir <CMakePresets binaryDir_>`_ field is now optional. + * The `generator <CMakePresets generator_>`_ field is now optional. + + * Changes to `Macro Expansion`_ + + * The `${hostSystemName} <CMakePresets hostSystemName_>`_ macro was + added. + + ``4`` + .. versionadded:: 3.23 + + * `Includes`_ were added to support including other JSON files in + ``CMakePresets.json`` and ``CMakeUserPresets.json``. + * Changes to `Build Presets <Build Preset_>`_ + + * The + `resolvePackageReferences <CMakePresets resolvePackageReferences_>`_ + field was added. + + * Changes to `Macro Expansion`_ + + * The `${fileDir} <CMakePresets fileDir_>`_ macro was added. + + ``5`` + .. versionadded:: 3.24 + + * Changes to `Test Presets <Test Preset_>`_ + + * The `testOutputTruncation <CMakePresets testOutputTruncation_>`_ + field was added to the `output <CMakePresets output_>`_ object. + + * Changes to `Macro Expansion`_ + + * The `${pathListSep} <CMakePresets pathListSep_>`_ macro was added. + + ``6`` + .. versionadded:: 3.25 + + * `Package Presets <Package Preset_>`_ were added. + * `Workflow Presets <Workflow Preset_>`_ were added. + * Changes to `Test Presets <Test Preset_>`_ + + * The `outputJUnitFile <CMakePresets outputJUnitFile_>`_ field was added + to the `output <CMakePresets output_>`_ object. + + ``7`` + .. versionadded:: 3.27 + + * Changes to `Configure Presets <Configure Preset_>`_ + + * The `trace <CMakePresets trace_>`_ field was added. + + * Changes to `Includes`_ + + * The ``include`` field now supports ``$penv{}`` `macro expansion`_. + + ``8`` + .. versionadded:: 3.28 + + * The `$schema <CMakePresets schema_>`_ field was added to the root object. + + ``9`` + .. versionadded:: 3.30 + + * Changes to `Includes`_ + + * The ``include`` field now supports other types of `macro expansion`_. + + ``10`` + .. versionadded:: 3.31 + + * The optional ``$comment`` field was added to support documentation + throughout ``CMakePresets.json`` and ``CMakeUserPresets.json``. + * Changes to `Configure Presets <Configure Preset_>`_: + + * The `graphviz <CMakePresets graphviz_>`_ field was added. + + ``11`` + .. versionadded:: 4.3 + + * Changes to `Test Presets <Test Preset_>`_ + + * The `jobs <CMakePresets test jobs_>`_ field now accepts an empty string + representing :option:`--parallel <ctest --parallel>` with ``<jobs>`` + omitted. + Schema ======
diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index a2b88dd..2102fc5 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst
@@ -40,8 +40,8 @@ /prop_gbl/GENERATOR_IS_MULTI_CONFIG /prop_gbl/GLOBAL_DEPENDS_DEBUG_MODE /prop_gbl/GLOBAL_DEPENDS_NO_CYCLES - /prop_gbl/INSTALL_PARALLEL /prop_gbl/IN_TRY_COMPILE + /prop_gbl/INSTALL_PARALLEL /prop_gbl/JOB_POOLS /prop_gbl/PACKAGES_FOUND /prop_gbl/PACKAGES_NOT_FOUND @@ -226,6 +226,8 @@ /prop_tgt/EXPORT_NAME /prop_tgt/EXPORT_NO_SYSTEM /prop_tgt/EXPORT_PROPERTIES + /prop_tgt/FASTBUILD_CACHING + /prop_tgt/FASTBUILD_DISTRIBUTION /prop_tgt/FOLDER /prop_tgt/Fortran_BUILDING_INTRINSIC_MODULES /prop_tgt/Fortran_FORMAT @@ -255,6 +257,7 @@ /prop_tgt/IMPORTED_CXX_MODULES_COMPILE_DEFINITIONS /prop_tgt/IMPORTED_CXX_MODULES_COMPILE_FEATURES /prop_tgt/IMPORTED_CXX_MODULES_COMPILE_OPTIONS + /prop_tgt/IMPORTED_CXX_MODULES_CONFIG /prop_tgt/IMPORTED_CXX_MODULES_INCLUDE_DIRECTORIES /prop_tgt/IMPORTED_CXX_MODULES_LINK_LIBRARIES /prop_tgt/IMPORTED_GLOBAL @@ -282,6 +285,8 @@ /prop_tgt/IMPORT_SUFFIX /prop_tgt/INCLUDE_DIRECTORIES /prop_tgt/INSTALL_NAME_DIR + /prop_tgt/INSTALL_OBJECT_NAME_STRATEGY + /prop_tgt/INSTALL_OBJECT_ONLY_USE_DESTINATION /prop_tgt/INSTALL_REMOVE_ENVIRONMENT_RPATH /prop_tgt/INSTALL_RPATH /prop_tgt/INSTALL_RPATH_USE_LINK_PATH @@ -322,6 +327,7 @@ /prop_tgt/LANG_ICSTAT /prop_tgt/LANG_INCLUDE_WHAT_YOU_USE /prop_tgt/LANG_LINKER_LAUNCHER + /prop_tgt/LANG_PVS_STUDIO /prop_tgt/LANG_STANDARD /prop_tgt/LANG_STANDARD_REQUIRED /prop_tgt/LANG_VISIBILITY_PRESET @@ -329,7 +335,6 @@ /prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG /prop_tgt/LIBRARY_OUTPUT_NAME /prop_tgt/LIBRARY_OUTPUT_NAME_CONFIG - /prop_tgt/SPDX_LICENSE /prop_tgt/LINK_DEPENDS /prop_tgt/LINK_DEPENDS_NO_SHARED /prop_tgt/LINK_DIRECTORIES @@ -389,6 +394,7 @@ /prop_tgt/PRECOMPILE_HEADERS_REUSE_FROM /prop_tgt/PREFIX /prop_tgt/PRIVATE_HEADER + /prop_tgt/PRIVATE_HEADER_SETS_TO_VERIFY /prop_tgt/PROJECT_LABEL /prop_tgt/PUBLIC_HEADER /prop_tgt/RESOURCE @@ -400,9 +406,11 @@ /prop_tgt/RUNTIME_OUTPUT_NAME /prop_tgt/RUNTIME_OUTPUT_NAME_CONFIG /prop_tgt/SKIP_BUILD_RPATH + /prop_tgt/SKIP_LINTING /prop_tgt/SOURCE_DIR /prop_tgt/SOURCES /prop_tgt/SOVERSION + /prop_tgt/SPDX_LICENSE /prop_tgt/STATIC_LIBRARY_FLAGS /prop_tgt/STATIC_LIBRARY_FLAGS_CONFIG /prop_tgt/STATIC_LIBRARY_OPTIONS @@ -412,6 +420,7 @@ /prop_tgt/Swift_LANGUAGE_VERSION /prop_tgt/Swift_MODULE_DIRECTORY /prop_tgt/Swift_MODULE_NAME + /prop_tgt/SYMBOLIC /prop_tgt/SYSTEM /prop_tgt/TEST_LAUNCHER /prop_tgt/TRANSITIVE_COMPILE_PROPERTIES @@ -421,10 +430,12 @@ /prop_tgt/UNITY_BUILD_BATCH_SIZE /prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE /prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE + /prop_tgt/UNITY_BUILD_FILENAME_PREFIX /prop_tgt/UNITY_BUILD_MODE /prop_tgt/UNITY_BUILD_RELOCATABLE /prop_tgt/UNITY_BUILD_UNIQUE_ID /prop_tgt/VERIFY_INTERFACE_HEADER_SETS + /prop_tgt/VERIFY_PRIVATE_HEADER_SETS /prop_tgt/VERSION /prop_tgt/VISIBILITY_INLINES_HIDDEN /prop_tgt/VS_CONFIGURATION_TYPE @@ -498,13 +509,13 @@ /prop_tgt/XCODE_SCHEME_EXECUTABLE /prop_tgt/XCODE_SCHEME_GUARD_MALLOC /prop_tgt/XCODE_SCHEME_LAUNCH_CONFIGURATION - /prop_tgt/XCODE_SCHEME_TEST_CONFIGURATION /prop_tgt/XCODE_SCHEME_LAUNCH_MODE /prop_tgt/XCODE_SCHEME_LLDB_INIT_FILE /prop_tgt/XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP /prop_tgt/XCODE_SCHEME_MALLOC_GUARD_EDGES /prop_tgt/XCODE_SCHEME_MALLOC_SCRIBBLE /prop_tgt/XCODE_SCHEME_MALLOC_STACK + /prop_tgt/XCODE_SCHEME_TEST_CONFIGURATION /prop_tgt/XCODE_SCHEME_THREAD_SANITIZER /prop_tgt/XCODE_SCHEME_THREAD_SANITIZER_STOP /prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER @@ -573,12 +584,15 @@ /prop_sf/GENERATED /prop_sf/HEADER_FILE_ONLY /prop_sf/INCLUDE_DIRECTORIES + /prop_sf/INSTALL_OBJECT_NAME + /prop_sf/JOB_POOL_COMPILE /prop_sf/KEEP_EXTENSION /prop_sf/LABELS /prop_sf/LANGUAGE /prop_sf/LOCATION /prop_sf/MACOSX_PACKAGE_LOCATION /prop_sf/OBJECT_DEPENDS + /prop_sf/OBJECT_NAME /prop_sf/OBJECT_OUTPUTS /prop_sf/SKIP_AUTOGEN /prop_sf/SKIP_AUTOMOC
diff --git a/Help/manual/cmake-qt.7.rst b/Help/manual/cmake-qt.7.rst index f9729b3..fe269c2 100644 --- a/Help/manual/cmake-qt.7.rst +++ b/Help/manual/cmake-qt.7.rst
@@ -224,10 +224,10 @@ =============================== The ``moc`` and ``uic`` tools are executed as part of a synthesized -:ref:`<ORIGIN>_autogen` :command:`custom target <add_custom_target>` generated by -CMake. By default that :ref:`<ORIGIN>_autogen` target inherits the dependencies +``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>` generated by +CMake. By default, that ``<ORIGIN>_autogen`` target inherits the dependencies of the ``<ORIGIN>`` target (see :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`). -Target dependencies may be added to the :ref:`<ORIGIN>_autogen` target by adding +Target dependencies may be added to the ``<ORIGIN>_autogen`` target by adding them to the :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property. .. note:: @@ -241,9 +241,10 @@ If Qt 5.15 or later is used and the generator is either :generator:`Ninja` or :ref:`Makefile Generators`, the ``<ORIGIN>_autogen_timestamp_deps`` target is -also created in addition to the :ref:`<ORIGIN>_autogen` target. This target -does not have any sources or commands to execute, but it has dependencies that -were previously inherited by the pre-Qt 5.15 :ref:`<ORIGIN>_autogen` target. +also created in addition to the :ref:`<ORIGIN>_autogen <<ORIGIN>_autogen>` +target. This target does not have any sources or commands to execute, but it +has dependencies that were previously inherited by the pre-Qt 5.15 +:ref:`<ORIGIN>_autogen <<ORIGIN>_autogen>` target. These dependencies will serve as a list of order-only dependencies for the custom command, without forcing the custom command to re-execute. @@ -252,11 +253,11 @@ When using the :ref:`Visual Studio Generators`, CMake generates a ``PRE_BUILD`` :command:`custom command <add_custom_command>` -instead of the :ref:`<ORIGIN>_autogen` +instead of the :ref:`<ORIGIN>_autogen <<ORIGIN>_autogen>` :command:`custom target <add_custom_target>` (for :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`). This isn't always possible though and an -:ref:`<ORIGIN>_autogen` :command:`custom target <add_custom_target>` is used, -when either +:ref:`<ORIGIN>_autogen <<ORIGIN>_autogen>` +:command:`custom target <add_custom_target>` is used, when either - the ``<ORIGIN>`` target depends on :prop_sf:`GENERATED` files which aren't excluded from :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` by
diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst index 9eee219..21363c7 100644 --- a/Help/manual/cmake-toolchains.7.rst +++ b/Help/manual/cmake-toolchains.7.rst
@@ -70,9 +70,16 @@ :variable:`CMAKE_<LANG>_COMPILER_VERSION` The version of the compiler. :variable:`CMAKE_<LANG>_FLAGS` - The variables and the configuration-specific equivalents contain flags that - will be added to the compile command when compiling a file of a particular - language. + These variables and the configuration-specific equivalents contain flags that + will be added to all invocations of the compiler for a particular language, + including those driving compiling and linking. + +:variable:`CMAKE_<LANG>_LINK_FLAGS` + .. versionadded:: 4.3 + + These variables and the configuration-specific equivalents contain flags that + will be added to all invocations of the compiler for a particular language + when driving linking only. CMake needs a way to determine which compiler to use to invoke the linker. This is determined by the :prop_sf:`LANGUAGE` property of source files of the @@ -234,11 +241,11 @@ set(CMAKE_SYSTEM_NAME QNX) - set(arch gcc_ntoarmv7le) + set(arch gcc_ntoaarch64) set(CMAKE_C_COMPILER qcc) set(CMAKE_C_COMPILER_TARGET ${arch}) - set(CMAKE_CXX_COMPILER QCC) + set(CMAKE_CXX_COMPILER q++) set(CMAKE_CXX_COMPILER_TARGET ${arch}) set(CMAKE_SYSROOT $ENV{QNX_TARGET}) @@ -704,3 +711,75 @@ - Use :command:`find_package` only for libraries installed with :variable:`CMAKE_IOS_INSTALL_COMBINED` feature + +.. _`Cross Compiling for Emscripten`: + +Cross Compiling for Emscripten +------------------------------ + +.. versionadded:: 4.2 + +A toolchain file may configure cross-compiling for `Emscripten`_ by +setting the :variable:`CMAKE_SYSTEM_NAME` variable to ``Emscripten``. +For example, a toolchain file might contain: + +.. code-block:: cmake + + set(CMAKE_SYSTEM_NAME Emscripten) + set(CMAKE_C_COMPILER /path/to/emcc) + set(CMAKE_CXX_COMPILER /path/to/em++) + +.. _`Emscripten`: https://emscripten.org/ + +Cross Compiling using Renesas compilers +--------------------------------------- + +For cross-compiling with Renesas compilers, specify at least: + +:variable:`CMAKE_SYSTEM_NAME` + Set to ``Generic``. Must be specified to enable cross compiling. + +:variable:`CMAKE_C_COMPILER <CMAKE_<LANG>_COMPILER>` + Set to the path to the Renesas C compiler, e.g., + ``ccrx``, ``ccrl``, or ``ccrh``. + +:variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>` + Set to the ``-isa=`` or ``-cpu=`` flag the compiler requires. + +See example toolchain files in the following sections. + +Renesas CC-RX +^^^^^^^^^^^^^ + +.. code-block:: cmake + + set(CMAKE_SYSTEM_NAME Generic) + set(CMAKE_C_COMPILER "ccrx.exe") + set(CMAKE_ASM_COMPILER "ccrx.exe") # if using ASM language + set(CMAKE_C_FLAGS "-isa=rxv3") # specify the version of target RX CPU + set(CMAKE_EXE_LINKER_FLAGS "-lnkopt=<your linker option here>") + +Renesas CC-RL +^^^^^^^^^^^^^ + +.. code-block:: cmake + + set(CMAKE_SYSTEM_NAME Generic) + set(CMAKE_C_COMPILER "ccrl.exe") + set(CMAKE_ASM_COMPILER "ccrl.exe") # if using ASM language + set(CMAKE_C_FLAGS "-cpu=S3") # specify the version of target RL CPU + # To avoid test executable runs out of const section's size. + set(CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY) + # Specifying device file and section layout linker options through compiler driver. + set(CMAKE_EXE_LINKER_FLAGS "-lnkopt=-device=dr5f10y14.dvf -lnkopt=-auto_section_layout") + +Renesas CC-RH +^^^^^^^^^^^^^ + +.. code-block:: cmake + + set(CMAKE_SYSTEM_NAME Generic) + set(CMAKE_C_COMPILER "ccrh.exe") + set(CMAKE_ASM_COMPILER "ccrh.exe") # if using ASM language + set(CMAKE_C_FLAGS "-Xcommon=rh850") # specify the version of target RH850 CPU + set(CMAKE_EXE_LINKER_FLAGS "-lnkopt=<your linker option here>")
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index d3ff681..f9ca444 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst
@@ -45,6 +45,7 @@ /variable/CMAKE_CURRENT_LIST_FILE /variable/CMAKE_CURRENT_LIST_LINE /variable/CMAKE_CURRENT_SOURCE_DIR + /variable/CMAKE_CXX_STDLIB_MODULES_JSON /variable/CMAKE_DEBUG_TARGET_PROPERTIES /variable/CMAKE_DIRECTORY_LABELS /variable/CMAKE_DL_LIBS @@ -55,6 +56,21 @@ /variable/CMAKE_EXECUTABLE_SUFFIX /variable/CMAKE_EXECUTABLE_SUFFIX_LANG /variable/CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES + /variable/CMAKE_FASTBUILD_ALLOW_RESPONSE_FILE + /variable/CMAKE_FASTBUILD_CACHE_PATH + /variable/CMAKE_FASTBUILD_CAPTURE_SYSTEM_ENV + /variable/CMAKE_FASTBUILD_CLANG_GCC_UPDATE_XLANG_ARG + /variable/CMAKE_FASTBUILD_CLANG_REWRITE_INCLUDES + /variable/CMAKE_FASTBUILD_COMPILER_EXTRA_FILES + /variable/CMAKE_FASTBUILD_ENV_OVERRIDES + /variable/CMAKE_FASTBUILD_FORCE_RESPONSE_FILE + /variable/CMAKE_FASTBUILD_IDE_ARGS + /variable/CMAKE_FASTBUILD_SOURCE_MAPPING + /variable/CMAKE_FASTBUILD_TRACK_BYPRODUCTS_AS_OUTPUT + /variable/CMAKE_FASTBUILD_USE_DETERMINISTIC_PATHS + /variable/CMAKE_FASTBUILD_USE_LIGHTCACHE + /variable/CMAKE_FASTBUILD_USE_RELATIVE_PATHS + /variable/CMAKE_FASTBUILD_VERBOSE_GENERATOR /variable/CMAKE_FIND_DEBUG_MODE /variable/CMAKE_FIND_DEBUG_MODE_NO_IMPLICIT_CONFIGURE_LOG /variable/CMAKE_FIND_PACKAGE_NAME @@ -98,22 +114,23 @@ /variable/CMAKE_OBJDUMP /variable/CMAKE_PARENT_LIST_FILE /variable/CMAKE_PATCH_VERSION + /variable/CMAKE_PROJECT_COMPAT_VERSION /variable/CMAKE_PROJECT_DESCRIPTION /variable/CMAKE_PROJECT_HOMEPAGE_URL /variable/CMAKE_PROJECT_NAME + /variable/CMAKE_PROJECT_SPDX_LICENSE /variable/CMAKE_PROJECT_VERSION /variable/CMAKE_PROJECT_VERSION_MAJOR /variable/CMAKE_PROJECT_VERSION_MINOR /variable/CMAKE_PROJECT_VERSION_PATCH /variable/CMAKE_PROJECT_VERSION_TWEAK - /variable/CMAKE_PROJECT_COMPAT_VERSION /variable/CMAKE_RANLIB /variable/CMAKE_ROOT /variable/CMAKE_RULE_MESSAGES /variable/CMAKE_SCRIPT_MODE_FILE + /variable/CMAKE_SHARED_LIBRARY_ARCHIVE_SUFFIX /variable/CMAKE_SHARED_LIBRARY_PREFIX /variable/CMAKE_SHARED_LIBRARY_SUFFIX - /variable/CMAKE_SHARED_LIBRARY_ARCHIVE_SUFFIX /variable/CMAKE_SHARED_MODULE_PREFIX /variable/CMAKE_SHARED_MODULE_SUFFIX /variable/CMAKE_SIZEOF_VOID_P @@ -154,28 +171,30 @@ /variable/CMAKE_XCODE_BUILD_SYSTEM /variable/CMAKE_XCODE_PLATFORM_TOOLSET /variable/PROJECT-NAME_BINARY_DIR + /variable/PROJECT-NAME_COMPAT_VERSION /variable/PROJECT-NAME_DESCRIPTION /variable/PROJECT-NAME_HOMEPAGE_URL /variable/PROJECT-NAME_IS_TOP_LEVEL /variable/PROJECT-NAME_SOURCE_DIR + /variable/PROJECT-NAME_SPDX_LICENSE /variable/PROJECT-NAME_VERSION /variable/PROJECT-NAME_VERSION_MAJOR /variable/PROJECT-NAME_VERSION_MINOR /variable/PROJECT-NAME_VERSION_PATCH /variable/PROJECT-NAME_VERSION_TWEAK - /variable/PROJECT-NAME_COMPAT_VERSION /variable/PROJECT_BINARY_DIR + /variable/PROJECT_COMPAT_VERSION /variable/PROJECT_DESCRIPTION /variable/PROJECT_HOMEPAGE_URL /variable/PROJECT_IS_TOP_LEVEL /variable/PROJECT_NAME /variable/PROJECT_SOURCE_DIR + /variable/PROJECT_SPDX_LICENSE /variable/PROJECT_VERSION /variable/PROJECT_VERSION_MAJOR /variable/PROJECT_VERSION_MINOR /variable/PROJECT_VERSION_PATCH /variable/PROJECT_VERSION_TWEAK - /variable/PROJECT_COMPAT_VERSION Variables that Change Behavior ============================== @@ -188,6 +207,7 @@ /variable/CMAKE_ABSOLUTE_DESTINATION_FILES /variable/CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY /variable/CMAKE_APPBUNDLE_PATH + /variable/CMAKE_AUTOGEN_INTERMEDIATE_DIR_STRATEGY /variable/CMAKE_BUILD_TYPE /variable/CMAKE_CLANG_VFS_OVERLAY /variable/CMAKE_CODEBLOCKS_COMPILER_ID @@ -209,9 +229,9 @@ /variable/CMAKE_EXECUTE_PROCESS_COMMAND_ERROR_IS_FATAL /variable/CMAKE_EXPORT_BUILD_DATABASE /variable/CMAKE_EXPORT_COMPILE_COMMANDS - /variable/CMAKE_EXPORT_SARIF - /variable/CMAKE_EXPORT_PACKAGE_REGISTRY /variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY + /variable/CMAKE_EXPORT_PACKAGE_REGISTRY + /variable/CMAKE_EXPORT_SARIF /variable/CMAKE_FIND_APPBUNDLE /variable/CMAKE_FIND_FRAMEWORK /variable/CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX @@ -243,9 +263,11 @@ /variable/CMAKE_INCLUDE_PATH /variable/CMAKE_INSTALL_DEFAULT_COMPONENT_NAME /variable/CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS + /variable/CMAKE_INSTALL_EXPORTS_AS_PACKAGE_INFO /variable/CMAKE_INSTALL_MESSAGE /variable/CMAKE_INSTALL_PREFIX /variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT + /variable/CMAKE_INTERMEDIATE_DIR_STRATEGY /variable/CMAKE_KATE_FILES_MODE /variable/CMAKE_KATE_MAKE_ARGUMENTS /variable/CMAKE_LIBRARY_PATH @@ -312,13 +334,13 @@ /variable/CMAKE_XCODE_SCHEME_ENVIRONMENT /variable/CMAKE_XCODE_SCHEME_GUARD_MALLOC /variable/CMAKE_XCODE_SCHEME_LAUNCH_CONFIGURATION - /variable/CMAKE_XCODE_SCHEME_TEST_CONFIGURATION /variable/CMAKE_XCODE_SCHEME_LAUNCH_MODE /variable/CMAKE_XCODE_SCHEME_LLDB_INIT_FILE /variable/CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP /variable/CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES /variable/CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE /variable/CMAKE_XCODE_SCHEME_MALLOC_STACK + /variable/CMAKE_XCODE_SCHEME_TEST_CONFIGURATION /variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER /variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP /variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER @@ -342,8 +364,8 @@ /variable/CMAKE_ANDROID_NDK_VERSION /variable/CMAKE_CL_64 /variable/CMAKE_COMPILER_2005 - /variable/CMAKE_HOST_APPLE /variable/CMAKE_HOST_AIX + /variable/CMAKE_HOST_APPLE /variable/CMAKE_HOST_BSD /variable/CMAKE_HOST_EXECUTABLE_SUFFIX /variable/CMAKE_HOST_LINUX @@ -387,8 +409,8 @@ :maxdepth: 1 /variable/CMAKE_ADSP_ROOT - /variable/CMAKE_AIX_SHARED_LIBRARY_ARCHIVE /variable/CMAKE_AIX_EXPORT_ALL_SYMBOLS + /variable/CMAKE_AIX_SHARED_LIBRARY_ARCHIVE /variable/CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS /variable/CMAKE_ANDROID_API /variable/CMAKE_ANDROID_API_MIN @@ -428,18 +450,18 @@ /variable/CMAKE_AUTOMOC /variable/CMAKE_AUTOMOC_COMPILER_PREDEFINES /variable/CMAKE_AUTOMOC_DEPEND_FILTERS + /variable/CMAKE_AUTOMOC_EXECUTABLE /variable/CMAKE_AUTOMOC_INCLUDE_DIRECTORIES /variable/CMAKE_AUTOMOC_MACRO_NAMES /variable/CMAKE_AUTOMOC_MOC_OPTIONS /variable/CMAKE_AUTOMOC_PATH_PREFIX - /variable/CMAKE_AUTOMOC_EXECUTABLE /variable/CMAKE_AUTORCC - /variable/CMAKE_AUTORCC_OPTIONS /variable/CMAKE_AUTORCC_EXECUTABLE + /variable/CMAKE_AUTORCC_OPTIONS /variable/CMAKE_AUTOUIC + /variable/CMAKE_AUTOUIC_EXECUTABLE /variable/CMAKE_AUTOUIC_OPTIONS /variable/CMAKE_AUTOUIC_SEARCH_PATHS - /variable/CMAKE_AUTOUIC_EXECUTABLE /variable/CMAKE_BUILD_RPATH /variable/CMAKE_BUILD_RPATH_USE_ORIGIN /variable/CMAKE_BUILD_WITH_INSTALL_NAME_DIR @@ -462,7 +484,6 @@ /variable/CMAKE_DEPENDS_USE_COMPILER /variable/CMAKE_DISABLE_PRECOMPILE_HEADERS /variable/CMAKE_DLL_NAME_WITH_SOVERSION - /variable/CMAKE_ENABLE_EXPORTS /variable/CMAKE_EXECUTABLE_ENABLE_EXPORTS /variable/CMAKE_EXE_LINKER_FLAGS /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG @@ -484,6 +505,8 @@ /variable/CMAKE_INCLUDE_CURRENT_DIR /variable/CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE /variable/CMAKE_INSTALL_NAME_DIR + /variable/CMAKE_INSTALL_OBJECT_NAME_STRATEGY + /variable/CMAKE_INSTALL_OBJECT_ONLY_USE_DESTINATION /variable/CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH /variable/CMAKE_INSTALL_RPATH /variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH @@ -494,9 +517,9 @@ /variable/CMAKE_LANG_COMPILER_LAUNCHER /variable/CMAKE_LANG_CPPCHECK /variable/CMAKE_LANG_CPPLINT - /variable/CMAKE_LANG_LINK_DEF_FILE_FLAG /variable/CMAKE_LANG_ICSTAT /variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE + /variable/CMAKE_LANG_LINK_DEF_FILE_FLAG /variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE /variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE_SUPPORTED /variable/CMAKE_LANG_LINK_LIBRARY_FEATURE_ATTRIBUTES @@ -506,6 +529,7 @@ /variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE_SUPPORTED /variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG /variable/CMAKE_LANG_LINKER_LAUNCHER + /variable/CMAKE_LANG_PVS_STUDIO /variable/CMAKE_LANG_USING_LINKER_TYPE /variable/CMAKE_LANG_VISIBILITY_PRESET /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY @@ -560,6 +584,7 @@ /variable/CMAKE_SHARED_LINKER_FLAGS_INIT /variable/CMAKE_SKIP_BUILD_RPATH /variable/CMAKE_SKIP_INSTALL_RPATH + /variable/CMAKE_SKIP_LINTING /variable/CMAKE_STATIC_LINKER_FLAGS /variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG /variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT @@ -574,6 +599,7 @@ /variable/CMAKE_UNITY_BUILD_RELOCATABLE /variable/CMAKE_UNITY_BUILD_UNIQUE_ID /variable/CMAKE_VERIFY_INTERFACE_HEADER_SETS + /variable/CMAKE_VERIFY_PRIVATE_HEADER_SETS /variable/CMAKE_VISIBILITY_INLINES_HIDDEN /variable/CMAKE_VS_DEBUGGER_COMMAND /variable/CMAKE_VS_DEBUGGER_COMMAND_ARGUMENTS @@ -678,6 +704,8 @@ /variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES /variable/CMAKE_LANG_LIBRARY_ARCHITECTURE /variable/CMAKE_LANG_LINK_EXECUTABLE + /variable/CMAKE_LANG_LINK_FLAGS + /variable/CMAKE_LANG_LINK_FLAGS_CONFIG /variable/CMAKE_LANG_LINKER_WRAPPER_FLAG /variable/CMAKE_LANG_LINKER_WRAPPER_FLAG_SEP /variable/CMAKE_LANG_OUTPUT_EXTENSION @@ -872,6 +900,7 @@ .. toctree:: :maxdepth: 1 + /variable/CMAKE_ENABLE_EXPORTS /variable/CMAKE_IOS_INSTALL_COMBINED /variable/CMAKE_LANG_USING_LINKER_MODE /variable/CMAKE_USE_RELATIVE_PATHS
diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 46ad589..62b8074 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst
@@ -252,11 +252,145 @@ .. option:: --graphviz=<file> - Generate graphviz of dependencies, see :module:`CMakeGraphVizOptions` for more. + Generate `Graphviz <https://www.graphviz.org/>`_ of dependencies - Generate a graphviz input file that will contain all the library and - executable dependencies in the project. See the documentation for - :module:`CMakeGraphVizOptions` for more details. + This option generates a graphviz input file that will contain all the + library and executable dependencies in the project showing the + dependencies between the targets in a project, as well as external libraries + which are linked against. + + When running CMake with the ``--graphviz=foo.dot`` option, it produces: + + * a ``foo.dot`` file, showing all dependencies in the project + * a ``foo.dot.<target>`` file for each target, showing on which other targets + it depends + * a ``foo.dot.<target>.dependers`` file for each target, showing which other + targets depend on it + + Those .dot files can be converted to images using the *dot* command from the + Graphviz package: + + .. code-block:: shell + + dot -Tpng -o foo.png foo.dot + + .. versionadded:: 3.10 + The different dependency types ``PUBLIC``, ``INTERFACE`` and ``PRIVATE`` + are represented as solid, dashed and dotted edges. + + .. rubric:: Variables specific to the Graphviz support + + The resulting graphs can be huge. The look and content of the generated graphs + can be controlled using the file ``CMakeGraphVizOptions.cmake``. This file is + first searched in :variable:`CMAKE_BINARY_DIR`, and then in + :variable:`CMAKE_SOURCE_DIR`. If found, the variables set in it are used to + adjust options for the generated Graphviz files. + + .. variable:: GRAPHVIZ_GRAPH_NAME + + The graph name. + + * Mandatory: NO + * Default: value of :variable:`CMAKE_PROJECT_NAME` + + .. variable:: GRAPHVIZ_GRAPH_HEADER + + The header written at the top of the Graphviz files. + + * Mandatory: NO + * Default: "node [ fontsize = "12" ];" + + .. variable:: GRAPHVIZ_NODE_PREFIX + + The prefix for each node in the Graphviz files. + + * Mandatory: NO + * Default: "node" + + .. variable:: GRAPHVIZ_EXECUTABLES + + Set to FALSE to exclude executables from the generated graphs. + + * Mandatory: NO + * Default: TRUE + + .. variable:: GRAPHVIZ_STATIC_LIBS + + Set to FALSE to exclude static libraries from the generated graphs. + + * Mandatory: NO + * Default: TRUE + + .. variable:: GRAPHVIZ_SHARED_LIBS + + Set to FALSE to exclude shared libraries from the generated graphs. + + * Mandatory: NO + * Default: TRUE + + .. variable:: GRAPHVIZ_MODULE_LIBS + + Set to FALSE to exclude module libraries from the generated graphs. + + * Mandatory: NO + * Default: TRUE + + .. variable:: GRAPHVIZ_INTERFACE_LIBS + + Set to FALSE to exclude interface libraries from the generated graphs. + + * Mandatory: NO + * Default: TRUE + + .. variable:: GRAPHVIZ_OBJECT_LIBS + + Set to FALSE to exclude object libraries from the generated graphs. + + * Mandatory: NO + * Default: TRUE + + .. variable:: GRAPHVIZ_UNKNOWN_LIBS + + Set to FALSE to exclude unknown libraries from the generated graphs. + + * Mandatory: NO + * Default: TRUE + + .. variable:: GRAPHVIZ_EXTERNAL_LIBS + + Set to FALSE to exclude external libraries from the generated graphs. + + * Mandatory: NO + * Default: TRUE + + .. variable:: GRAPHVIZ_CUSTOM_TARGETS + + Set to TRUE to include custom targets in the generated graphs. + + * Mandatory: NO + * Default: FALSE + + .. variable:: GRAPHVIZ_IGNORE_TARGETS + + A list of regular expressions for names of targets to exclude from the + generated graphs. + + * Mandatory: NO + * Default: empty + + .. variable:: GRAPHVIZ_GENERATE_PER_TARGET + + Set to FALSE to not generate per-target graphs ``foo.dot.<target>``. + + * Mandatory: NO + * Default: TRUE + + .. variable:: GRAPHVIZ_GENERATE_DEPENDERS + + Set to FALSE to not generate depender graphs ``foo.dot.<target>.dependers``. + + * Mandatory: NO + * Default: TRUE .. option:: --system-information [file] @@ -573,6 +707,11 @@ if the preset sets a variable called ``MYVAR`` to ``1``, but the user sets it to ``2`` with a ``-D`` argument, the value ``2`` is preferred. + .. versionadded:: 3.21 + The ``-B`` option may optionally be specified with a different binary + directory than the one specified by the ``binaryDir`` key of the + configure preset. + .. option:: --list-presets[=<type>] Lists the available presets of the specified ``<type>``. Valid values for @@ -656,9 +795,13 @@ .. option:: --preset <preset>, --preset=<preset> Use a build preset to specify build options. The project binary directory - is inferred from the ``configurePreset`` key. The current working directory - must contain CMake preset files. - See :manual:`preset <cmake-presets(7)>` for more details. + is inferred from the ``configurePreset`` key unless a directory is specified + after ``--build``. The current working directory must contain CMake preset + files. See :manual:`preset <cmake-presets(7)>` for more details. + + .. versionadded:: 4.3 + ``cmake --build`` now supports specifying a build directory and + preset together. .. option:: --list-presets @@ -785,7 +928,23 @@ .. option:: --prefix <prefix> - Override the installation prefix, :variable:`CMAKE_INSTALL_PREFIX`. + Specifies an alternative installation prefix, temporarily replacing the + value of the :variable:`CMAKE_INSTALL_PREFIX` variable at the installation + phase. + + The main purpose of this option is to allow installation to occur in an + arbitrary location. This is commonly used in certain installation and + packaging workflows. It is analogous to selecting the installation + directory during the installation phase. For example, on Windows, where + a user may choose the destination folder for the project. + + .. note:: + + When the project is using the :module:`GNUInstallDirs` module, there are + some :ref:`special cases <GNUInstallDirs special cases>` that are + evaluated based on the value of the :variable:`CMAKE_INSTALL_PREFIX` + variable during the configuration phase. The results persist even if an + alternative prefix is used during installation. .. option:: --strip @@ -873,6 +1032,78 @@ Available commands are: +.. option:: bin2c [<options>...] [--] [<input-file> [<output-file>]] + + .. versionadded:: 4.3 + + Convert a binary file to a C array. If input file is unspecified or ``-``, + read from standard input instead of a file. If output file is unspecified or + ``-``, write to standard output instead of a file. + + By default, this prints only the bytes. Enclosing text can be added with the + ``--template-file`` argument. You can also ``#include`` the bytes from + another file, acting as a drop-in replacement for the ``#embed`` directive + from C23 and C++26: + + .. code-block:: c + + unsigned char my_bytes[] = { + /* #embed "bin2c_input.bin" */ + #include "bin2c_output.c.txt" + }; + + .. program:: cmake-E_bin2c + + .. option:: --signed + + Print the bytes as signed integers rather than unsigned. + + .. option:: --decimal + + Print the bytes as decimal rather than hexadecimal. + + .. option:: --trailing-comma + + Append a trailing comma after the last byte (not included by default.) + + .. option:: --template-file <template-file> + + Format from a template file. The template file contains placeholders for + the array and optionally the length (which will be a non-negative decimal + integer). Such placeholders are enclosed in ``@`` at the beginning and end + of the placeholder. This functionality is similar to + :command:`configure_file` called with the ``@ONLY`` argument, but only the + array and length placeholders will be replaced, and any other placeholders + will be left as-is. + + An example of a potential template file: + + .. code-block:: text + + unsigned char my_bytes[] = {@array@}; + + size_t length = @length@; + + The array placeholder may occur at most once in the template file. The + length placeholder may occur zero or more times after the array + placeholder, but not before it. + + Note that the length is the number of elements printed, and may not match + the ``sizeof`` the resulting array if a type other than ``unsigned char`` + is used. + + .. option:: --template-array-placeholder <placeholder-name> + + Specify a name for the array placeholder in the template file. Set to + ``array`` by default. + + .. option:: --template-length-placeholder <placeholder-name> + + Specify a name for the length placeholder in the template file. Set to + ``length`` by default. + +.. program:: cmake-E + .. option:: capabilities .. versionadded:: 3.7 @@ -1029,6 +1260,19 @@ ``copy_directory_if_different`` does follow symlinks. The command fails when the source directory does not exist. +.. option:: copy_directory_if_newer <dir>... <destination> + + .. versionadded:: 4.2 + + Copy content of ``<dir>...`` directories to ``<destination>`` directory + if source files are newer than destination files (based on file timestamps). + If ``<destination>`` directory does not exist it will be created. + + ``copy_directory_if_newer`` does follow symlinks. + The command fails when the source directory does not exist. + This is faster than ``copy_directory_if_different`` as it only compares + file timestamps instead of file contents. + .. option:: copy_if_different <file>... <destination> Copy files to ``<destination>`` (either file or directory) if @@ -1040,6 +1284,18 @@ .. versionadded:: 3.5 Support for multiple input files. +.. option:: copy_if_newer <file>... <destination> + + .. versionadded:: 4.2 + + Copy files to ``<destination>`` (either file or directory) if + source files are newer than destination files (based on file timestamps). + If multiple files are specified, the ``<destination>`` must be + directory and it must exist. + ``copy_if_newer`` does follow symlinks. + This is faster than ``copy_if_different`` as it only compares + file timestamps instead of file contents. + .. option:: create_symlink <old> <new> Create a symbolic link ``<new>`` naming ``<old>``. @@ -1133,6 +1389,9 @@ 351abe79cd3800b38cdfb25d45015a15 file1.txt 052f86c15bbde68af55c7f7b340ab639 file2.txt + .. versionchanged:: 4.3 + Passing ``-`` reads from standard input. + .. option:: sha1sum <file>... .. versionadded:: 3.10 @@ -1142,6 +1401,9 @@ 4bb7932a29e6f73c97bb9272f2bdc393122f86e0 file1.txt 1df4c8f318665f9a5f2ed38f55adadb7ef9f559c file2.txt + .. versionchanged:: 4.3 + Passing ``-`` reads from standard input. + .. option:: sha224sum <file>... .. versionadded:: 3.10 @@ -1151,6 +1413,9 @@ b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930 file1.txt 6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24 file2.txt + .. versionchanged:: 4.3 + Passing ``-`` reads from standard input. + .. option:: sha256sum <file>... .. versionadded:: 3.10 @@ -1160,6 +1425,9 @@ 76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc file1.txt 15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea file2.txt + .. versionchanged:: 4.3 + Passing ``-`` reads from standard input. + .. option:: sha384sum <file>... .. versionadded:: 3.10 @@ -1169,6 +1437,9 @@ acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434 file1.txt 668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d file2.txt + .. versionchanged:: 4.3 + Passing ``-`` reads from standard input. + .. option:: sha512sum <file>... .. versionadded:: 3.10 @@ -1178,6 +1449,9 @@ 2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89 file1.txt 7a0b54896fe5e70cca6dd643ad6f672614b189bf26f8153061c4d219474b05dad08c4e729af9f4b009f1a1a280cb625454bf587c690f4617c27e3aebdf3b7a2d file2.txt + .. versionchanged:: 4.3 + Passing ``-`` reads from standard input. + .. option:: remove [-f] <file>... .. deprecated:: 3.17 @@ -1257,6 +1531,10 @@ When extracting selected files or directories, you must provide their exact names including the path, as printed by list (``-t``). + .. versionchanged:: 4.3 + Archive entries containing path traversal sequences (``..``), or + absolute paths, are rejected for security. + .. option:: t List archive contents. @@ -1271,7 +1549,7 @@ .. option:: z - Compress the resulting archive with gzip. + Compress the resulting archive with gzip (Deflate). .. option:: j @@ -1281,7 +1559,7 @@ .. versionadded:: 3.1 - Compress the resulting archive with XZ. + Compress the resulting archive with XZ (LZMA2). .. option:: --zstd @@ -1289,6 +1567,12 @@ Compress the resulting archive with Zstandard. + .. option:: --lzma + + .. versionadded:: 4.3 + + Compress the resulting archive with LZMA algorithm. + .. option:: --files-from=<file> .. versionadded:: 3.1 @@ -1303,8 +1587,33 @@ .. versionadded:: 3.3 Specify the format of the archive to be created. - Supported formats are: ``7zip``, ``gnutar``, ``pax``, - ``paxr`` (restricted pax, default), and ``zip``. + Supported formats are: + + * ``7zip`` + * ``gnutar`` + * ``pax`` + * ``paxr`` (restricted pax, default) + * ``raw`` + + .. versionadded:: 4.3 + + If this format is used, only one file will be compressed + with the compression type specified by the + :option:`--cmake-tar-compression-method <cmake-E_tar --cmake-tar-compression-method>`. + + * ``zip`` + + If the compression method is not specified, the compression method + depends on the format: + + * ``7zip`` uses ``LZMA`` compression + * ``zip`` uses ``Deflate`` compression + * others uses no compression by default + + .. versionadded:: 4.3 + + The ``7zip`` and ``zip`` formats support changing the default compression + method and compression level. .. option:: --mtime=<date> @@ -1312,6 +1621,57 @@ Specify modification time recorded in tarball entries. + .. option:: --cmake-tar-compression-method=<compression-method> + + .. versionadded:: 4.3 + + The ``<compression-method>`` must be one of the following: + + * ``none`` or ``store`` - no compression is used + * ``deflate`` or ``gzip`` - Deflate-based + * ``bzip2`` - BZip2-based + * ``lzma`` - LZMA-based + * ``lzma2`` or ``xz`` - LZMA2-based + * ``ppmd`` - PPMd-based + + This compression method is only supported by the ``7zip`` archive format. + + * ``zstd`` - Zstandard-based + + This is the second variant for the compression method selection. + It provide more compression methods, that the classic ``tar``-like interface. + You can use any of them. + + The default value depends on the :option:`--format <cmake-E_tar --format>` + option value and described in the corresponding section. + + .. option:: --cmake-tar-compression-level=<compression-level> + + .. versionadded:: 4.3 + + The ``<compression-level>`` should be between ``0`` and ``9``, with the + default being ``0``. The compression algorithm must be selected when + the ``--cmake-tar-compression-level`` option is given. + + The ``<compression-level>`` of the ``Zstd`` algorithm can be set + between ``0`` and ``19``, except for the ``zip`` format. + + The value ``0`` is used to specify the default compression level. + It is selected automatically by the archive library backend and + not directly set by CMake itself. The default compression level + may vary between archive formats, platforms, etc. + + .. option:: --cmake-tar-threads=<number> + + .. versionadded:: 4.3 + + Use the ``<number>`` threads to operate on the archive. Currently only + multi-threaded compression is supported. + + If set to ``0``, the number of available cores on the machine will be + used instead. Note that not all compression modes support threading + in all environments. + .. option:: --touch .. versionadded:: 3.24
diff --git a/Help/manual/cmake/version-schema.json b/Help/manual/cmake/version-schema.json new file mode 100644 index 0000000..71b7ea6 --- /dev/null +++ b/Help/manual/cmake/version-schema.json
@@ -0,0 +1,109 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "properties": { + "dependencies": { + "type": "array", + "items": { + "type": "object", + "description": "Information about a single dependency.", + "properties": { + "name": { + "type": "string", + "description": "The name of the dependency." + }, + "type": { + "type": "string", + "description": "The type of the dependency.", + "enum": [ + "system", + "bundled" + ] + }, + "version": { + "type": "string", + "description": "The version of the dependency if available." + }, + "via": { + "type": "string", + "description": "The source from which the dependency is came from. Not presented for direct CMake dependencies." + } + }, + "required": [ + "name", + "type" + ], + "additionalProperties": false + }, + "additionalItems": false + }, + "program": { + "type": "object", + "description": "Information about the CMake tool.", + "properties": { + "name": { + "type": "string", + "description": "The name of the CMake tool." + }, + "version": { + "type": "object", + "description": "Information about the version of the CMake tool.", + "properties": { + "major": { + "type": "integer", + "description": "The major version of the CMake tool." + }, + "minor": { + "type": "integer", + "description": "The minor version of the CMake tool." + }, + "patch": { + "type": "integer", + "description": "The patch version of the CMake tool." + }, + "string": { + "type": "string", + "description": "The full version string of the CMake tool." + } + }, + "required": [ + "major", + "minor", + "patch", + "string" + ], + "additionalProperties": false + } + }, + "required": [ + "name", + "version" + ], + "additionalProperties": false + }, + "version": { + "type": "object", + "properties": { + "major": { + "type": "integer", + "description": "The major version of the JSON output format." + }, + "minor": { + "type": "integer", + "description": "The minor version of the JSON output format." + } + }, + "required": [ + "major", + "minor" + ], + "additionalProperties": false + } + }, + "required": [ + "dependencies", + "program", + "version" + ], + "additionalProperties": false +}
diff --git a/Help/manual/cpack-generators.7.rst b/Help/manual/cpack-generators.7.rst index abb291b..5c8c075 100644 --- a/Help/manual/cpack-generators.7.rst +++ b/Help/manual/cpack-generators.7.rst
@@ -13,6 +13,7 @@ .. toctree:: :maxdepth: 1 + /cpack_gen/appimage /cpack_gen/archive /cpack_gen/bundle /cpack_gen/cygwin
diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 3a871bb..2cbb41b 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst
@@ -51,6 +51,11 @@ must contain CMake preset files. See :manual:`preset <cmake-presets(7)>` for more details. + .. versionadded:: 3.30 + The ``--test-dir`` option may optionally be specified with a different + binary directory than the one specified by the ``configurePreset`` key + of the test preset. + .. option:: --list-presets Lists the available test presets. The current working directory must contain @@ -497,6 +502,14 @@ This option can also be set by setting the :envvar:`CTEST_NO_TESTS_ACTION` environment variable. +.. option:: --collect-instrumentation <build> + + .. versionadded:: 4.0 + + Manually collect instrumentation data from the specified build directory. See + the :ref:`cmake-instrumentation Indexing` section of CMake instrumentation for + more details. + View Help =========
diff --git a/Help/manual/file_api/schema_cache.json b/Help/manual/file_api/schema_cache.json new file mode 100644 index 0000000..78ebf8e --- /dev/null +++ b/Help/manual/file_api/schema_cache.json
@@ -0,0 +1,83 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "description": "Schema for the CMake cache object kind", + "type": "object", + "required": [ + "kind", + "version", + "entries" + ], + "properties": { + "kind": { + "type": "string", + "const": "cache" + }, + "version": { + "type": "object", + "required": [ + "major", + "minor" + ], + "properties": { + "major": { + "type": "integer", + "const": 2 + }, + "minor": { + "type": "integer", + "const": 0 + } + }, + "additionalProperties": false + }, + "entries": { + "type": "array", + "description": "Array of CMake cache entries", + "items": { + "type": "object", + "required": [ + "name", + "value", + "type", + "properties" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the cache entry" + }, + "value": { + "type": "string", + "description": "Value of the cache entry" + }, + "type": { + "type": "string", + "description": "Type of the cache entry used by CMake GUI to choose a widget for editing" + }, + "properties": { + "type": "array", + "description": "Associated properties for the cache entry", + "items": { + "type": "object", + "required": [ + "name", + "value" + ], + "properties": { + "name": { + "type": "string" + }, + "value": { + "type": "string" + } + }, + "additionalProperties": false + } + } + }, + "additionalProperties": false + } + } + }, + "additionalProperties": false +}
diff --git a/Help/manual/file_api/schema_cmakeFiles.json b/Help/manual/file_api/schema_cmakeFiles.json new file mode 100644 index 0000000..3611825 --- /dev/null +++ b/Help/manual/file_api/schema_cmakeFiles.json
@@ -0,0 +1,186 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "description": "Schema for the CMake cmakeFiles object kind", + "type": "object", + "required": [ + "kind", + "version", + "paths", + "inputs" + ], + "oneOf": [ + { + "$ref": "#/definitions/cmakeFilesV1_0" + }, + { + "$ref": "#/definitions/cmakeFilesV1_1" + } + ], + "definitions": { + "kind": { + "type": "string", + "const": "cmakeFiles", + "description": "Specifies the object kind" + }, + "versionV1_0": { + "type": "object", + "required": [ + "major", + "minor" + ], + "properties": { + "major": { + "type": "integer", + "const": 1 + }, + "minor": { + "type": "integer", + "const": 0 + } + }, + "additionalProperties": false + }, + "versionV1_1": { + "type": "object", + "required": [ + "major", + "minor" + ], + "properties": { + "major": { + "type": "integer", + "const": 1 + }, + "minor": { + "type": "integer", + "const": 1 + } + }, + "additionalProperties": false + }, + "paths": { + "type": "object", + "required": [ + "build", + "source" + ], + "properties": { + "build": { + "type": "string", + "description": "Absolute path to the top-level build directory" + }, + "source": { + "type": "string", + "description": "Absolute path to the top-level source directory" + } + }, + "additionalProperties": false + }, + "inputs": { + "type": "array", + "items": { + "type": "object", + "required": [ + "path" + ], + "properties": { + "path": { + "type": "string", + "description": "Path to an input file to CMake" + }, + "isGenerated": { + "type": "boolean", + "description": "Indicates if the file is under the build directory in out-of-source builds" + }, + "isExternal": { + "type": "boolean", + "description": "Indicates if the file is not under source or build directories" + }, + "isCMake": { + "type": "boolean", + "description": "Indicates if the file is in the CMake installation" + } + }, + "additionalProperties": false + } + }, + "globsDependentV1_1": { + "type": "array", + "description": "Optional member present only when the project calls file(GLOB) or file(GLOB_RECURSE) with the CONFIGURE_DEPENDS option", + "items": { + "type": "object", + "required": [ + "expression", + "paths" + ], + "properties": { + "expression": { + "type": "string", + "description": "The globbing expression. If the result of the expression no longer matches the same list of paths, the build system is considered out of date and the build tool will re-run cmake." + }, + "recurse": { + "type": "boolean", + "description": "This will be true if the glob expression was from a file(GLOB_RECURSE) call" + }, + "listDirectories": { + "type": "boolean", + "description": "This will be true if the expression is from a file(GLOB) that does not specify LIST_DIRECTORIES false, or from a file(GLOB_RECURSE) with LIST_DIRECTORIES set to true" + }, + "followSymlinks": { + "type": "boolean", + "description": "This will be true if the FOLLOW_SYMLINKS option was given" + }, + "relative": { + "type": "string", + "description": "This will be present if the RELATIVE option was given. The value is the path given after the RELATIVE keyword." + }, + "paths": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Paths matched by the globbing expression" + } + }, + "additionalProperties": false + } + }, + "cmakeFilesV1_0": { + "properties": { + "kind": { + "$ref": "#/definitions/kind" + }, + "version": { + "$ref": "#/definitions/versionV1_0" + }, + "paths": { + "$ref": "#/definitions/paths" + }, + "inputs": { + "$ref": "#/definitions/inputs" + } + }, + "additionalProperties": false + }, + "cmakeFilesV1_1": { + "properties": { + "kind": { + "$ref": "#/definitions/kind" + }, + "version": { + "$ref": "#/definitions/versionV1_1" + }, + "paths": { + "$ref": "#/definitions/paths" + }, + "inputs": { + "$ref": "#/definitions/inputs" + }, + "globsDependent": { + "$ref": "#/definitions/globsDependentV1_1" + } + }, + "additionalProperties": false + } + } +}
diff --git a/Help/manual/file_api/schema_codemodel.json b/Help/manual/file_api/schema_codemodel.json new file mode 100644 index 0000000..72902cb --- /dev/null +++ b/Help/manual/file_api/schema_codemodel.json
@@ -0,0 +1,565 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "description": "Schema for the CMake codemodel object kind", + "type": "object", + "required": [ + "kind", + "version", + "paths", + "configurations" + ], + "oneOf": [ + { + "$ref": "#/definitions/codemodelV2_0" + }, + { + "$ref": "#/definitions/codemodelV2_3" + }, + { + "$ref": "#/definitions/codemodelV2_9" + } + ], + "definitions": { + "kind": { + "type": "string", + "const": "codemodel", + "description": "Specifies the object kind" + }, + "versionV2_0": { + "type": "object", + "required": [ + "major", + "minor" + ], + "properties": { + "major": { + "type": "integer", + "const": 2 + }, + "minor": { + "type": "integer", + "minimum": 0, + "maximum": 2 + } + }, + "additionalProperties": false + }, + "versionV2_3": { + "type": "object", + "required": [ + "major", + "minor" + ], + "properties": { + "major": { + "type": "integer", + "const": 2 + }, + "minor": { + "type": "integer", + "minimum": 3, + "maximum": 8 + } + }, + "additionalProperties": false + }, + "versionV2_9": { + "type": "object", + "required": [ + "major", + "minor" + ], + "properties": { + "major": { + "type": "integer", + "const": 2 + }, + "minor": { + "type": "integer", + "minimum": 9 + } + }, + "additionalProperties": false + }, + "paths": { + "type": "object", + "required": [ + "source", + "build" + ], + "properties": { + "source": { + "type": "string", + "description": "Absolute path to the top-level source directory" + }, + "build": { + "type": "string", + "description": "Absolute path to the top-level build directory" + } + }, + "additionalProperties": false + }, + "configurationDirectoryItemSource": { + "type": "string", + "description": "Path to the source directory. If it is inside the top level source directory, the path will be relative to that directory. For the top level source directory, this will simply be '.'. Paths outside the top level source directory will be absolute." + }, + "configurationDirectoryItemBuild": { + "type": "string", + "description": "Path to the build directory. If it is inside the top level build directory, the path will be relative to that directory. For the top level build directory, this will simply be '.'. Paths outside the top level build directory will be absolute." + }, + "configurationDirectoryItemParentIndex": { + "type": "integer", + "minimum": 0, + "description": "Index of the parent directory in the directories array" + }, + "configurationDirectoryItemChildIndexes": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + }, + "description": "Indices of child directories" + }, + "configurationDirectoryItemProjectIndex": { + "type": "integer", + "minimum": 0, + "description": "Index into the projects array" + }, + "configurationDirectoryItemBuildSystemTargetIndexes": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + }, + "description": "Indices into the targets array" + }, + "configurationDirectoryItemAbstractTargetIndexesV2_9": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + }, + "description": "Indices into the abstractTargets array" + }, + "configurationDirectoryItemMinimumCMakeVersion": { + "type": "object", + "required": [ + "string" + ], + "properties": { + "string": { + "type": "string", + "description": "Minimum required CMake version, if known" + } + }, + "additionalProperties": false + }, + "configurationDirectoryItemHasInstallRule": { + "type": "boolean", + "description": "Whether the directory has install rules" + }, + "configurationDirectoryItemJsonFileV2_3": { + "jsonFile": { + "type": "string", + "description": "Path to directory-specific JSON file" + } + }, + "configurationDirectoriesV2_0": { + "type": "array", + "items": { + "type": "object", + "required": [ + "source", + "build", + "projectIndex" + ], + "properties": { + "source": { + "$ref": "#/definitions/configurationDirectoryItemSource" + }, + "build": { + "$ref": "#/definitions/configurationDirectoryItemBuild" + }, + "parentIndex": { + "$ref": "#/definitions/configurationDirectoryItemParentIndex" + }, + "childIndexes": { + "$ref": "#/definitions/configurationDirectoryItemChildIndexes" + }, + "projectIndex": { + "$ref": "#/definitions/configurationDirectoryItemProjectIndex" + }, + "targetIndexes": { + "$ref": "#/definitions/configurationDirectoryItemBuildSystemTargetIndexes" + }, + "minimumCMakeVersion": { + "$ref": "#/definitions/configurationDirectoryItemMinimumCMakeVersion" + }, + "hasInstallRule": { + "$ref": "#/definitions/configurationDirectoryItemHasInstallRule" + } + }, + "additionalProperties": false + } + }, + "configurationDirectoriesV2_3": { + "type": "array", + "items": { + "type": "object", + "required": [ + "source", + "build", + "projectIndex" + ], + "properties": { + "source": { + "$ref": "#/definitions/configurationDirectoryItemSource" + }, + "build": { + "$ref": "#/definitions/configurationDirectoryItemBuild" + }, + "parentIndex": { + "$ref": "#/definitions/configurationDirectoryItemParentIndex" + }, + "childIndexes": { + "$ref": "#/definitions/configurationDirectoryItemChildIndexes" + }, + "projectIndex": { + "$ref": "#/definitions/configurationDirectoryItemProjectIndex" + }, + "targetIndexes": { + "$ref": "#/definitions/configurationDirectoryItemBuildSystemTargetIndexes" + }, + "minimumCMakeVersion": { + "$ref": "#/definitions/configurationDirectoryItemMinimumCMakeVersion" + }, + "hasInstallRule": { + "$ref": "#/definitions/configurationDirectoryItemHasInstallRule" + }, + "jsonFile": { + "$ref": "#/definitions/configurationDirectoryItemJsonFileV2_3" + } + }, + "additionalProperties": false + } + }, + "configurationDirectoriesV2_9": { + "type": "array", + "items": { + "type": "object", + "required": [ + "source", + "build", + "projectIndex" + ], + "properties": { + "source": { + "$ref": "#/definitions/configurationDirectoryItemSource" + }, + "build": { + "$ref": "#/definitions/configurationDirectoryItemBuild" + }, + "parentIndex": { + "$ref": "#/definitions/configurationDirectoryItemParentIndex" + }, + "childIndexes": { + "$ref": "#/definitions/configurationDirectoryItemChildIndexes" + }, + "projectIndex": { + "$ref": "#/definitions/configurationDirectoryItemProjectIndex" + }, + "targetIndexes": { + "$ref": "#/definitions/configurationDirectoryItemBuildSystemTargetIndexes" + }, + "abstractTargetIndexes": { + "$ref": "#/definitions/configurationDirectoryItemAbstractTargetIndexesV2_9" + }, + "minimumCMakeVersion": { + "$ref": "#/definitions/configurationDirectoryItemMinimumCMakeVersion" + }, + "hasInstallRule": { + "$ref": "#/definitions/configurationDirectoryItemHasInstallRule" + }, + "jsonFile": { + "$ref": "#/definitions/configurationDirectoryItemJsonFileV2_3" + } + }, + "additionalProperties": false + } + }, + "configurationName": { + "type": "string", + "description": "Configuration name (e.g., 'Debug')" + }, + "configurationProjects": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "directoryIndexes" + ], + "properties": { + "name": { + "type": "string", + "description": "Project name" + }, + "parentIndex": { + "type": "integer", + "minimum": 0, + "description": "Index of parent project" + }, + "childIndexes": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + }, + "description": "Indices of child projects" + }, + "directoryIndexes": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + }, + "description": "Indices into directories array" + }, + "targetIndexes": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + }, + "description": "Indices into targets array" + } + } + } + }, + "configurationProjectsV2_9": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "directoryIndexes" + ], + "properties": { + "name": { + "type": "string", + "description": "Project name" + }, + "parentIndex": { + "type": "integer", + "minimum": 0, + "description": "Index of parent project" + }, + "childIndexes": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + }, + "description": "Indices of child projects" + }, + "directoryIndexes": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + }, + "description": "Indices into directories array" + }, + "targetIndexes": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + }, + "description": "Indices into targets array" + }, + "abstractTargetIndexes": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + }, + "description": "Indices into abstractTargets array" + } + } + } + }, + "configurationTargets": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "directoryIndex", + "projectIndex", + "jsonFile" + ], + "properties": { + "name": { + "type": "string", + "description": "Target name" + }, + "id": { + "type": "string", + "description": "Unique target identifier" + }, + "directoryIndex": { + "type": "integer", + "minimum": 0, + "description": "Index into directories array" + }, + "projectIndex": { + "type": "integer", + "minimum": 0, + "description": "Index into projects array" + }, + "jsonFile": { + "type": "string", + "description": "Path to target-specific JSON file" + } + } + } + }, + "configurationsV2_0": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "directories", + "projects", + "targets" + ], + "properties": { + "name": { + "$ref": "#/definitions/configurationName" + }, + "projects": { + "$ref": "#/definitions/configurationProjects" + }, + "targets": { + "$ref": "#/definitions/configurationTargets" + }, + "directories": { + "$ref": "#/definitions/configurationDirectoriesV2_0" + } + }, + "additionalProperties": false + } + }, + "configurationsV2_3": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "directories", + "projects", + "targets" + ], + "properties": { + "name": { + "$ref": "#/definitions/configurationName" + }, + "projects": { + "$ref": "#/definitions/configurationProjects" + }, + "targets": { + "$ref": "#/definitions/configurationTargets" + }, + "directories": { + "$ref": "#/definitions/configurationDirectoriesV2_3" + } + }, + "additionalProperties": false + } + }, + "configurationsV2_9": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "directories", + "projects", + "targets", + "abstractTargets" + ], + "properties": { + "name": { + "$ref": "#/definitions/configurationName" + }, + "projects": { + "$ref": "#/definitions/configurationProjectsV2_9" + }, + "targets": { + "$ref": "#/definitions/configurationTargets" + }, + "abstractTargets": { + "$ref": "#/definitions/configurationTargets" + }, + "directories": { + "$ref": "#/definitions/configurationDirectoriesV2_9" + } + }, + "additionalProperties": false + } + }, + "codemodelV2_0": { + "properties": { + "kind": { + "$ref": "#/definitions/kind" + }, + "version": { + "$ref": "#/definitions/versionV2_0" + }, + "paths": { + "$ref": "#/definitions/paths" + }, + "configurations": { + "$ref": "#/definitions/configurationsV2_0" + } + }, + "additionalProperties": false + }, + "codemodelV2_3": { + "properties": { + "kind": { + "$ref": "#/definitions/kind" + }, + "version": { + "$ref": "#/definitions/versionV2_3" + }, + "paths": { + "$ref": "#/definitions/paths" + }, + "configurations": { + "$ref": "#/definitions/configurationsV2_3" + } + }, + "additionalProperties": false + }, + "codemodelV2_9": { + "properties": { + "kind": { + "$ref": "#/definitions/kind" + }, + "version": { + "$ref": "#/definitions/versionV2_9" + }, + "paths": { + "$ref": "#/definitions/paths" + }, + "configurations": { + "$ref": "#/definitions/configurationsV2_9" + } + }, + "additionalProperties": false + } + } +}
diff --git a/Help/manual/file_api/schema_configureLog.json b/Help/manual/file_api/schema_configureLog.json new file mode 100644 index 0000000..2f380b8 --- /dev/null +++ b/Help/manual/file_api/schema_configureLog.json
@@ -0,0 +1,55 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "description": "Schema for the CMake configureLog object kind", + "type": "object", + "required": [ + "kind", + "version", + "path", + "eventKindNames" + ], + "properties": { + "kind": { + "type": "string", + "const": "configureLog" + }, + "version": { + "type": "object", + "required": [ + "major", + "minor" + ], + "properties": { + "major": { + "type": "integer", + "const": 1 + }, + "minor": { + "type": "integer", + "const": 0 + } + }, + "additionalProperties": false + }, + "path": { + "type": "string", + "description": "Path to the configure log file. Clients must read the log file from this path, which may be different to the path in CMake's documentation. The log file specified by this path might not exist if no events have been logged." + }, + "eventKindNames": { + "type": "array", + "description": "Names of versioned event kinds included in the configure log. Other event kinds might be present in the configure log, but clients must ignore those not listed in this array.", + "items": { + "type": "string", + "enum": [ + "message-v1", + "try_compile-v1", + "try_run-v1", + "find-v1", + "find_package-v1" + ] + }, + "uniqueItems": true + } + }, + "additionalProperties": false +}
diff --git a/Help/manual/file_api/schema_directory.json b/Help/manual/file_api/schema_directory.json new file mode 100644 index 0000000..9b59229 --- /dev/null +++ b/Help/manual/file_api/schema_directory.json
@@ -0,0 +1,636 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "description": "Schema for the CMake codemodel directory object", + "type": "object", + "oneOf": [ + { + "$comment": "The top level codemodelVersion field was only added in version 2.9, so we can't differentiate between earlier versions", + "anyOf": [ + { + "$ref": "#/definitions/codemodelV2_0" + }, + { + "$ref": "#/definitions/codemodelV2_4" + }, + { + "$ref": "#/definitions/codemodelV2_5" + } + ] + }, + { + "$ref": "#/definitions/codemodelV2_9" + } + ], + "definitions": { + "codemodelVersionV2_9": { + "type": "object", + "required": [ + "major", + "minor" + ], + "properties": { + "major": { + "type": "integer", + "const": 2 + }, + "minor": { + "type": "integer", + "minimum": 9 + } + }, + "additionalProperties": false + }, + "backtraceGraph": { + "type": "object", + "required": [ + "nodes", + "commands", + "files" + ], + "properties": { + "nodes": { + "type": "array", + "items": { + "type": "object", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "integer", + "minimum": 0, + "description": "0-based index into the backtrace files array" + }, + "line": { + "type": "integer", + "minimum": 1, + "description": "This is present when the node represents a line within the file. The line number is a 1-based value." + }, + "command": { + "type": "integer", + "minimum": 0, + "description": "This is present when the node represents a command invocation. It is a 0-based index into the backtrace commands array." + }, + "parent": { + "type": "integer", + "minimum": 0, + "description": "This is present when the node is not the bottom of the call stack. It is a 0-based index of another node in the backtrace nodes array." + } + }, + "additionalProperties": false + } + }, + "commands": { + "type": "array", + "description": "Each list item is a string specifying a command name", + "items": { + "type": "string" + } + }, + "files": { + "type": "array", + "description": "Each list item is a string specifying the path to a file, represented with forward slashes. If the file is inside the top level source directory, the path is specified relative to that directory. Otherwise, the path is absolute.", + "items": { + "type": "string" + } + } + }, + "additionalProperties": false + }, + "paths": { + "type": "object", + "required": [ + "source", + "build" + ], + "properties": { + "source": { + "type": "string", + "description": "Path to the source directory. If it is inside the top level source directory, the path will be relative to that directory. For the top level source directory, this will simply be '.'. Paths outside the top level source directory will be absolute." + }, + "build": { + "type": "string", + "description": "Path to the build directory. If it is inside the top level build directory, the path will be relative to that directory. For the top level build directory, this will simply be '.'. Paths outside the top level build directory will be absolute." + } + }, + "additionalProperties": false + }, + "installerComponent": { + "type": "string", + "description": "Specifies the component selected by the corresponding install command invocation" + }, + "installerDestination": { + "type": "string", + "description": "The install destination path. May be absolute or relative to the install prefix" + }, + "installerPaths": { + "type": "array", + "description": "Paths (files or directories) to be installed", + "items": { + "oneOf": [ + { + "type": "string", + "description": "Path from which a file/directory is installed, also specifying the install path" + }, + { + "type": "object", + "properties": { + "from": { + "type": "string", + "description": "Path from which a file/directory is installed" + }, + "to": { + "type": "string", + "description": "Path to which the file/directory is installed under the destination" + } + }, + "required": [ + "from", + "to" + ] + } + ] + } + }, + "installerItemTypesV2_0": { + "type": "string", + "enum": [ + "file", + "directory", + "target", + "export", + "script", + "code", + "importedRuntimeArtifacts", + "runtimeDependencySet" + ] + }, + "installerItemTypesV2_4": { + "type": "string", + "enum": [ + "fileSet" + ] + }, + "installerItemTypesV2_5": { + "type": "string", + "enum": [ + "cxxModuleBmi" + ] + }, + "installerTypeV2_0": { + "$ref": "#/definitions/installerItemTypesV2_0", + "description": "Type of installation rule" + }, + "installerTypeV2_4": { + "anyOf": [ + { + "$ref": "#/definitions/installerItemTypesV2_0" + }, + { + "$ref": "#/definitions/installerItemTypesV2_4" + } + ], + "description": "Type of installation rule" + }, + "installerTypeV2_5": { + "anyOf": [ + { + "$ref": "#/definitions/installerItemTypesV2_0" + }, + { + "$ref": "#/definitions/installerItemTypesV2_4" + }, + { + "$ref": "#/definitions/installerItemTypesV2_5" + } + ], + "description": "Type of installation rule" + }, + "installerIsExcludeFromAll": { + "type": "boolean", + "description": "Present when install is called with EXCLUDE_FROM_ALL option" + }, + "installerIsForAllComponents": { + "type": "boolean", + "description": "Present when install(SCRIPT|CODE) is called with ALL_COMPONENTS option" + }, + "installerIsOptional": { + "type": "boolean", + "description": "Present when install is called with OPTIONAL option" + }, + "installerTargetId": { + "type": "string", + "description": "Uniquely identifying string for the target to be installed" + }, + "installerTargetIndex": { + "type": "integer", + "minimum": 0, + "description": "0-based index into the codemodel targets array" + }, + "installerTargetIsImportLibrary": { + "type": "boolean", + "description": "Present for Windows DLL import library or AIX linker import file" + }, + "installerTargetInstallNamelink": { + "type": "string", + "enum": [ + "skip", + "only" + ], + "description": "How to handle symlinks for VERSION/SOVERSION target properties" + }, + "installerExportName": { + "type": "string", + "description": "Name of the export for export type" + }, + "installerExportTargets": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "String uniquely identifying the target" + }, + "index": { + "type": "integer", + "minimum": 0, + "description": "0-based index into the codemodel targets array" + } + }, + "additionalProperties": false, + "required": [ + "id", + "index" + ] + } + }, + "installerRuntimeDependencySetName": { + "type": "string", + "description": "Name of the runtime dependency set" + }, + "installerRuntimeDependencySetType": { + "type": "string", + "enum": [ + "library", + "framework" + ], + "description": "Type of runtime dependency set" + }, + "installerScriptFile": { + "type": "string", + "description": "Path to the script file on disk" + }, + "installerBacktrace": { + "type": "integer", + "minimum": 0, + "description": "0-based index into the backtraceGraph nodes array" + }, + "installerFileSetNameV2_4": { + "type": "string", + "description": "Name of the file set" + }, + "installerFileSetTypeV2_4": { + "type": "string", + "description": "Type of the file set" + }, + "installerFileSetDirectoriesV2_4": { + "type": "array", + "items": { + "type": "string" + }, + "description": "File set's base directories" + }, + "installerFileSetTargetV2_4": { + "type": "object", + "required": [ + "id", + "index" + ], + "properties": { + "id": { + "type": "string", + "description": "String uniquely identifying the target" + }, + "index": { + "type": "integer", + "minimum": 0, + "description": "0-based index into the codemodel targets array" + } + }, + "additionalProperties": false + }, + "installerCxxModuleBmiTargetV2_5": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "index": { + "type": "integer", + "minimum": 0 + } + }, + "additionalProperties": false + }, + "installersV2_0": { + "type": "array", + "items": { + "type": "object", + "required": [ + "component", + "type" + ], + "properties": { + "component": { + "$ref": "#/definitions/installerComponent" + }, + "destination": { + "$ref": "#/definitions/installerDestination" + }, + "paths": { + "$ref": "#/definitions/installerPaths" + }, + "type": { + "$ref": "#/definitions/installerTypeV2_0" + }, + "isExcludeFromAll": { + "$ref": "#/definitions/installerIsExcludeFromAll" + }, + "isForAllComponents": { + "$ref": "#/definitions/installerIsForAllComponents" + }, + "isOptional": { + "$ref": "#/definitions/installerIsOptional" + }, + "targetId": { + "$ref": "#/definitions/installerTargetId" + }, + "targetIndex": { + "$ref": "#/definitions/installerTargetIndex" + }, + "targetIsImportLibrary": { + "$ref": "#/definitions/installerTargetIsImportLibrary" + }, + "targetInstallNamelink": { + "$ref": "#/definitions/installerTargetInstallNamelink" + }, + "exportName": { + "$ref": "#/definitions/installerExportName" + }, + "exportTargets": { + "$ref": "#/definitions/installerExportTargets" + }, + "runtimeDependencySetName": { + "$ref": "#/definitions/installerRuntimeDependencySetName" + }, + "runtimeDependencySetType": { + "$ref": "#/definitions/installerRuntimeDependencySetType" + }, + "scriptFile": { + "$ref": "#/definitions/installerScriptFile" + }, + "backtrace": { + "$ref": "#/definitions/installerBacktrace" + } + }, + "additionalProperties": false + } + }, + "installersV2_4": { + "type": "array", + "items": { + "type": "object", + "required": [ + "component", + "type" + ], + "properties": { + "component": { + "$ref": "#/definitions/installerComponent" + }, + "destination": { + "$ref": "#/definitions/installerDestination" + }, + "paths": { + "$ref": "#/definitions/installerPaths" + }, + "type": { + "$ref": "#/definitions/installerTypeV2_0" + }, + "isExcludeFromAll": { + "$ref": "#/definitions/installerIsExcludeFromAll" + }, + "isForAllComponents": { + "$ref": "#/definitions/installerIsForAllComponents" + }, + "isOptional": { + "$ref": "#/definitions/installerIsOptional" + }, + "targetId": { + "$ref": "#/definitions/installerTargetId" + }, + "targetIndex": { + "$ref": "#/definitions/installerTargetIndex" + }, + "targetIsImportLibrary": { + "$ref": "#/definitions/installerTargetIsImportLibrary" + }, + "targetInstallNamelink": { + "$ref": "#/definitions/installerTargetInstallNamelink" + }, + "exportName": { + "$ref": "#/definitions/installerExportName" + }, + "exportTargets": { + "$ref": "#/definitions/installerExportTargets" + }, + "runtimeDependencySetName": { + "$ref": "#/definitions/installerRuntimeDependencySetName" + }, + "runtimeDependencySetType": { + "$ref": "#/definitions/installerRuntimeDependencySetType" + }, + "scriptFile": { + "$ref": "#/definitions/installerScriptFile" + }, + "backtrace": { + "$ref": "#/definitions/installerBacktrace" + }, + "fileSetName": { + "$ref": "#/definitions/installerFileSetNameV2_4" + }, + "fileSetType": { + "$ref": "#/definitions/installerFileSetTypeV2_4" + }, + "fileSetDirectories": { + "$ref": "#/definitions/installerFileSetDirectoriesV2_4" + }, + "fileSetTarget": { + "$ref": "#/definitions/installerFileSetTargetV2_4" + } + }, + "additionalProperties": false + } + }, + "installersV2_5": { + "type": "array", + "items": { + "type": "object", + "required": [ + "component", + "type" + ], + "properties": { + "component": { + "$ref": "#/definitions/installerComponent" + }, + "destination": { + "$ref": "#/definitions/installerDestination" + }, + "paths": { + "$ref": "#/definitions/installerPaths" + }, + "type": { + "$ref": "#/definitions/installerTypeV2_5" + }, + "isExcludeFromAll": { + "$ref": "#/definitions/installerIsExcludeFromAll" + }, + "isForAllComponents": { + "$ref": "#/definitions/installerIsForAllComponents" + }, + "isOptional": { + "$ref": "#/definitions/installerIsOptional" + }, + "targetId": { + "$ref": "#/definitions/installerTargetId" + }, + "targetIndex": { + "$ref": "#/definitions/installerTargetIndex" + }, + "targetIsImportLibrary": { + "$ref": "#/definitions/installerTargetIsImportLibrary" + }, + "targetInstallNamelink": { + "$ref": "#/definitions/installerTargetInstallNamelink" + }, + "exportName": { + "$ref": "#/definitions/installerExportName" + }, + "exportTargets": { + "$ref": "#/definitions/installerExportTargets" + }, + "runtimeDependencySetName": { + "$ref": "#/definitions/installerRuntimeDependencySetName" + }, + "runtimeDependencySetType": { + "$ref": "#/definitions/installerRuntimeDependencySetType" + }, + "scriptFile": { + "$ref": "#/definitions/installerScriptFile" + }, + "backtrace": { + "$ref": "#/definitions/installerBacktrace" + }, + "fileSetName": { + "$ref": "#/definitions/installerFileSetNameV2_4" + }, + "fileSetType": { + "$ref": "#/definitions/installerFileSetTypeV2_4" + }, + "fileSetDirectories": { + "$ref": "#/definitions/installerFileSetDirectoriesV2_4" + }, + "fileSetTarget": { + "$ref": "#/definitions/installerFileSetTargetV2_4" + }, + "cxxModuleBmiTarget": { + "$ref": "#/definitions/installerCxxModuleBmiTargetV2_5" + } + }, + "additionalProperties": false + } + }, + "codemodelV2_0": { + "required": [ + "backtraceGraph", + "paths", + "installers" + ], + "properties": { + "backtraceGraph": { + "$ref": "#/definitions/backtraceGraph" + }, + "paths": { + "$ref": "#/definitions/paths" + }, + "installers": { + "$ref": "#/definitions/installersV2_0" + } + }, + "additionalProperties": false + }, + "codemodelV2_4": { + "required": [ + "backtraceGraph", + "paths", + "installers" + ], + "properties": { + "backtraceGraph": { + "$ref": "#/definitions/backtraceGraph" + }, + "paths": { + "$ref": "#/definitions/paths" + }, + "installers": { + "$ref": "#/definitions/installersV2_4" + } + }, + "additionalProperties": false + }, + "codemodelV2_5": { + "required": [ + "backtraceGraph", + "paths", + "installers" + ], + "properties": { + "backtraceGraph": { + "$ref": "#/definitions/backtraceGraph" + }, + "paths": { + "$ref": "#/definitions/paths" + }, + "installers": { + "$ref": "#/definitions/installersV2_5" + } + }, + "additionalProperties": false + }, + "codemodelV2_9": { + "required": [ + "codemodelVersion", + "backtraceGraph", + "paths", + "installers" + ], + "properties": { + "codemodelVersion": { + "$ref": "#/definitions/codemodelVersionV2_9" + }, + "backtraceGraph": { + "$ref": "#/definitions/backtraceGraph" + }, + "paths": { + "$ref": "#/definitions/paths" + }, + "installers": { + "$ref": "#/definitions/installersV2_5" + } + }, + "additionalProperties": false + } + } +}
diff --git a/Help/manual/file_api/schema_index.json b/Help/manual/file_api/schema_index.json new file mode 100644 index 0000000..a49ba1a --- /dev/null +++ b/Help/manual/file_api/schema_index.json
@@ -0,0 +1,248 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "required": [ + "cmake", + "objects", + "reply" + ], + "properties": { + "cmake": { + "type": "object", + "description": "High level details about CMake itself and the CMake generator used", + "required": [ + "version", + "paths", + "generator" + ], + "properties": { + "version": { + "description": "Full version details of the CMake used to produce the replies", + "type": "object", + "required": [ + "major", + "minor", + "patch", + "string", + "isDirty" + ], + "properties": { + "major": { + "type": "integer", + "minimum": 3 + }, + "minor": { + "type": "integer", + "minimum": 0 + }, + "patch": { + "type": "integer", + "minimum": 0 + }, + "suffix": { + "type": "string", + "description": "A version suffix may be present when CMake is built from sources, or for release candidates. Official releases do not normally have a suffix." + }, + "string": { + "type": "string", + "description": "The full version string in the format <major>.<minor>.<patch>[-<suffix>]" + }, + "isDirty": { + "type": "boolean", + "description": "When this is true, it indicates CMake was built from a version-controlled source tree with local modifications" + } + }, + "additionalProperties": false + }, + "paths": { + "description": "Absolute paths to tools and locations within the CMake installation", + "type": "object", + "required": [ + "cmake", + "ctest", + "cpack", + "root" + ], + "properties": { + "cmake": { + "description": "Absolute path to the cmake executable", + "type": "string" + }, + "ctest": { + "description": "Absolute path to the ctest executable", + "type": "string" + }, + "cpack": { + "description": "Absolute path to the cpack executable", + "type": "string" + }, + "root": { + "description": "Absolute path to the directory containing CMake resources like the Modules directory", + "type": "string" + } + }, + "additionalProperties": false + }, + "generator": { + "description": "Details for the CMake generator used", + "type": "object", + "required": [ + "multiConfig", + "name" + ], + "properties": { + "multiConfig": { + "description": "True for multi-configuration generators, false for single-configuration generators", + "type": "boolean" + }, + "name": { + "type": "string" + }, + "platform": { + "description": "This string will only be set if the generator supports the CMAKE_GENERATOR_PLATFORM variable, which specifies the generator platform name", + "type": "string" + } + }, + "additionalProperties": false + } + } + }, + "objects": { + "type": "array", + "items": { + "$ref": "#/definitions/kindJsonFile" + } + }, + "reply": { + "type": "object", + "patternProperties": { + "^[^-]+-v\\d+$": { + "description": "A member of this form appears for each of the shared stateless query files that CMake recognized as a request for the specified object kind and major version", + "oneOf": [ + { + "$ref": "#/definitions/kindJsonFile" + }, + { + "description": "A member of this form appears if the query's object kind is not recognized or is malformed", + "$ref": "#/definitions/replyError" + } + ] + }, + "^client-[^/]+$": { + "description": "A member of this form appears for each client-owned directory holding client stateless query files. The value is a JSON object mirroring the content of the query/client-<client>/ directory.", + "patternProperties": { + "^[^-]+-v\\d+$": { + "description": "A member of this form appears for each of the client stateless query files that CMake recognized as a request for the specified object kind and major version", + "oneOf": [ + { + "$ref": "#/definitions/kindJsonFile" + }, + { + "description": "A member of this form appears if the client query's object kind is not recognized or is malformed", + "$ref": "#/definitions/replyError" + } + ] + }, + "^query\\.json$": { + "description": "This member appears for clients using client stateful query files", + "oneOf": [ + { + "type": "object", + "properties": { + "client": { + "type": "object" + }, + "requests": {}, + "responses": { + "oneOf": [ + { + "$ref": "#/definitions/replyError" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/definitions/kindJsonFile" + }, + { + "$ref": "#/definitions/replyError" + } + ] + } + } + ] + } + }, + "additionalProperties": false + }, + { + "description": "A member of this form appears if the query.json file failed to read or parse as a JSON object", + "$ref": "#/definitions/replyError" + } + ] + } + }, + "additionalProperties": { + "description": "A member of this form appears for each of the client stateless query files that CMake did not recognize.", + "$ref": "#/definitions/replyError" + } + } + }, + "additionalProperties": { + "description": "A member of this form appears for each of the shared stateless query files that CMake did not recognize.", + "$ref": "#/definitions/replyError" + } + } + }, + "definitions": { + "kindJsonFile": { + "type": "object", + "required": [ + "kind", + "version", + "jsonFile" + ], + "properties": { + "kind": { + "type": "string" + }, + "version": { + "type": "object", + "required": [ + "major", + "minor" + ], + "properties": { + "major": { + "type": "integer", + "minimum": 1 + }, + "minor": { + "type": "integer", + "minimum": 0 + } + }, + "additionalProperties": false + }, + "jsonFile": { + "type": "string", + "description": "Specifies a path relative to the reply index file to another JSON file containing the object" + } + }, + "additionalProperties": false + }, + "replyError": { + "type": "object", + "required": [ + "error" + ], + "properties": { + "error": { + "type": "string" + } + }, + "additionalProperties": false + } + } +}
diff --git a/Help/manual/file_api/schema_stateful_query.json b/Help/manual/file_api/schema_stateful_query.json new file mode 100644 index 0000000..fc3c251 --- /dev/null +++ b/Help/manual/file_api/schema_stateful_query.json
@@ -0,0 +1,84 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "description": "Schema for CMake file API query.json files", + "type": "object", + "required": [ + "requests" + ], + "properties": { + "requests": { + "type": "array", + "items": { + "type": "object", + "required": [ + "kind", + "version" + ], + "properties": { + "kind": { + "type": "string", + "description": "Specifies one of the Object Kinds to be included in the reply" + }, + "version": { + "description": "Version(s) of the object kind that the client understands", + "oneOf": [ + { + "$ref": "#/definitions/versionMajorOnly" + }, + { + "$ref": "#/definitions/versionObject" + }, + { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/definitions/versionMajorOnly" + }, + { + "$ref": "#/definitions/versionObject" + } + ] + } + } + ] + }, + "client": { + "description": "Optional member reserved for use by the client. This value is preserved in the reply." + } + } + } + }, + "client": { + "description": "Optional member reserved for use by the client. This value is preserved in the reply." + } + }, + "$comment": "Other top level properties are reserved for future use. If present, they are ignored for forward compatibility.", + "additionalProperties": true, + "definitions": { + "versionMajorOnly": { + "type": "integer", + "description": "A non-negative major version number", + "minimum": 0 + }, + "versionObject": { + "type": "object", + "required": [ + "major" + ], + "properties": { + "major": { + "type": "integer", + "description": "The major version number", + "minimum": 0 + }, + "minor": { + "type": "integer", + "description": "The minor version number", + "minimum": 0 + } + }, + "additionalProperties": false + } + } +}
diff --git a/Help/manual/file_api/schema_target.json b/Help/manual/file_api/schema_target.json new file mode 100644 index 0000000..68cb14e --- /dev/null +++ b/Help/manual/file_api/schema_target.json
@@ -0,0 +1,1767 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "description": "Schema for the CMake codemodel target object", + "type": "object", + "oneOf": [ + { + "$comment": "The top level codemodelVersion field was only added in version 2.9, so we can't differentiate between earlier versions", + "anyOf": [ + { + "$ref": "#/definitions/codemodelV2_0" + }, + { + "$ref": "#/definitions/codemodelV2_1" + }, + { + "$ref": "#/definitions/codemodelV2_2" + }, + { + "$ref": "#/definitions/codemodelV2_5" + }, + { + "$ref": "#/definitions/codemodelV2_6" + }, + { + "$ref": "#/definitions/codemodelV2_7" + }, + { + "$ref": "#/definitions/codemodelV2_8" + } + ] + }, + { + "$ref": "#/definitions/codemodelV2_9" + }, + { + "$ref": "#/definitions/codemodelV2_10" + } + ], + "definitions": { + "codemodelVersionV2_9": { + "type": "object", + "required": [ + "major", + "minor" + ], + "properties": { + "major": { + "type": "integer", + "const": 2 + }, + "minor": { + "type": "integer", + "const": 9 + } + }, + "additionalProperties": false + }, + "codemodelVersionV2_10": { + "type": "object", + "required": [ + "major", + "minor" + ], + "properties": { + "major": { + "type": "integer", + "const": 2 + }, + "minor": { + "type": "integer", + "minimum": 10 + } + }, + "additionalProperties": false + }, + "name": { + "type": "string", + "description": "Logical name of the target" + }, + "id": { + "type": "string", + "description": "Unique identifier for the target. The format is unspecified and should not be interpreted by clients." + }, + "typeV2_0": { + "type": "string", + "enum": [ + "EXECUTABLE", + "STATIC_LIBRARY", + "SHARED_LIBRARY", + "MODULE_LIBRARY", + "OBJECT_LIBRARY", + "INTERFACE_LIBRARY", + "UTILITY" + ] + }, + "typeV2_9": { + "type": "string", + "enum": [ + "EXECUTABLE", + "STATIC_LIBRARY", + "SHARED_LIBRARY", + "MODULE_LIBRARY", + "OBJECT_LIBRARY", + "INTERFACE_LIBRARY", + "UNKNOWN_LIBRARY", + "UTILITY" + ] + }, + "importedV2_9": { + "type": "boolean", + "description": "True if the target is imported" + }, + "localV2_9": { + "type": "boolean", + "description": "True if the target is defined in a local scope rather than being a global target" + }, + "symbolicV2_9": { + "type": "boolean", + "description": "True if an interface target has the SYMBOLIC property set" + }, + "abstractV2_9": { + "type": "boolean", + "description": "True if the target is not part of the build system" + }, + "backtrace": { + "type": "integer", + "minimum": 0, + "description": "Index into backtraceGraph nodes array" + }, + "folder": { + "type": "object", + "description": "This will only be present if the FOLDER target property is set", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the folder to place the target under in IDEs and other GUI tools" + } + }, + "additionalProperties": false + }, + "paths": { + "type": "object", + "required": [ + "source", + "build" + ], + "properties": { + "source": { + "type": "string", + "description": "Path to the source directory. If it is inside the top level source directory, the path will be relative to that directory. For the top level source directory, this will simply be '.'. Paths outside the top level source directory will be absolute." + }, + "build": { + "type": "string", + "description": "Path to the build directory. If it is inside the top level build directory, the path will be relative to that directory. For the top level build directory, this will simply be '.'. Paths outside the top level build directory will be absolute." + } + }, + "additionalProperties": false + }, + "nameOnDisk": { + "type": "string", + "description": "File name of the primary artifact on disk, only present for executable and library targets that are linked or archived into a single primary artifact" + }, + "artifacts": { + "type": "array", + "description": "Only present for executable and library targets that produce artifacts on disk meant for consumption by dependents", + "items": { + "type": "object", + "required": [ + "path" + ], + "properties": { + "path": { + "type": "string", + "description": "Path to artifact file on disk. If the file is inside the top-level build directory, the path is specified relative to that directory. Otherwise, the path is absolute." + } + }, + "additionalProperties": false + } + }, + "isGeneratorProvided": { + "type": "boolean", + "description": "Only present and will have the value true if the target is provided by CMake's build system generator rather than by a command in the project's source code" + }, + "install": { + "type": "object", + "description": "Only present if the target has an install() rule", + "required": [ + "prefix", + "destinations" + ], + "properties": { + "prefix": { + "type": "object", + "required": [ + "path" + ], + "properties": { + "path": { + "type": "string", + "description": "The value of CMAKE_INSTALL_PREFIX" + } + }, + "additionalProperties": false + }, + "destinations": { + "type": "array", + "items": { + "type": "object", + "required": [ + "path" + ], + "properties": { + "path": { + "type": "string", + "description": "Install destination path. It may be absolute or relative to the install prefix." + }, + "backtrace": { + "type": "integer", + "minimum": 0, + "description": "Index into the backtraceGraph nodes array, if a backtrace is available" + } + }, + "additionalProperties": false + } + } + }, + "additionalProperties": false + }, + "launchersV2_7": { + "type": "array", + "items": { + "type": "object", + "required": [ + "command", + "type" + ], + "properties": { + "command": { + "type": "string", + "description": "Path to the launcher on disk. If the file is inside the top-level source directory, the path is specified relative to that directory." + }, + "arguments": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Arguments preceding the executable" + }, + "type": { + "type": "string", + "enum": [ + "emulator", + "test" + ], + "description": "Type of launcher" + } + }, + "additionalProperties": false + } + }, + "link": { + "type": "object", + "description": "This is only present for executables and shared library targets that link into a runtime binary", + "required": [ + "language" + ], + "properties": { + "language": { + "type": "string", + "description": "Language of the toolchain used to invoke the linker" + }, + "commandFragments": { + "type": "array", + "description": "Ordered fragments of the link command line, if available", + "items": { + "type": "object", + "required": [ + "fragment", + "role" + ], + "properties": { + "fragment": { + "type": "string", + "description": "Fragment of link command line" + }, + "role": { + "type": "string", + "enum": [ + "flags", + "libraries", + "libraryPath", + "frameworkPath" + ], + "description": "Role of the fragment content" + }, + "backtrace": { + "type": "integer", + "minimum": 0, + "description": "Index into backtraceGraph nodes array for the command that added the link fragment, if available" + } + }, + "additionalProperties": false + } + }, + "lto": { + "type": "boolean", + "description": "True if link-time optimization is enabled" + }, + "sysroot": { + "type": "object", + "description": "Only present when the CMAKE_SYSROOT_LINK or CMAKE_SYSROOT variable is defined", + "required": [ + "path" + ], + "properties": { + "path": { + "type": "string", + "description": "Absolute path to the sysroot" + } + }, + "additionalProperties": false + } + }, + "additionalProperties": false + }, + "archive": { + "type": "object", + "description": "Only present for static library targets", + "properties": { + "commandFragments": { + "type": "array", + "description": "Ordered fragments of the archiver command line, if available", + "items": { + "type": "object", + "required": [ + "fragment", + "role" + ], + "properties": { + "fragment": { + "type": "string", + "description": "Fragment of the archiver command line" + }, + "role": { + "type": "string", + "enum": [ + "flags" + ], + "description": "Role of the fragment content" + } + }, + "additionalProperties": false + } + }, + "lto": { + "type": "boolean", + "description": "True if link-time optimization is enabled" + } + }, + "additionalProperties": false + }, + "debuggerV2_8": { + "type": "object", + "properties": { + "workingDirectory": { + "type": "string", + "description": "Working directory for a debugger" + } + }, + "additionalProperties": false + }, + "dependencies": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique identifier of another target on which this one depends" + }, + "backtrace": { + "type": "integer", + "minimum": 0, + "description": "Index into backtraceGraph nodes array of the command that created the dependency, if available" + } + }, + "additionalProperties": false + } + }, + "linkLibrariesV2_9": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier of the target for the dependency" + }, + "fragment": { + "type": "string", + "description": "Raw linker command line arguments that capture the dependency" + }, + "backtrace": { + "type": "integer", + "minimum": 0, + "description": "Index into backtraceGraph nodes array of the command that created the dependency, if available" + }, + "fromDependency": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier of another target whose INTERFACE_LINK_LIBRARIES_DIRECT property created this dependency" + } + } + } + }, + "additionalProperties": false + } + }, + "interfaceLinkLibrariesV2_9": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier of the target for the dependency" + }, + "fragment": { + "type": "string", + "description": "Raw linker command line arguments that capture the dependency" + }, + "backtrace": { + "type": "integer", + "minimum": 0, + "description": "Index into backtraceGraph nodes array of the command that created the dependency, if available" + } + }, + "additionalProperties": false + } + }, + "compileDependenciesV2_9": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique identifier of the target for the dependency" + }, + "backtrace": { + "type": "integer", + "minimum": 0, + "description": "Index into backtraceGraph nodes array of the command that created the dependency, if available" + }, + "fromDependency": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier of another target whose INTERFACE_LINK_LIBRARIES_DIRECT property created this dependency" + } + } + } + }, + "additionalProperties": false + } + }, + "interfaceCompileDependenciesV2_9": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique identifier of the target for the dependency" + }, + "backtrace": { + "type": "integer", + "minimum": 0, + "description": "Index into backtraceGraph nodes array of the command that created the dependency, if available" + } + }, + "additionalProperties": false + } + }, + "onlyTargetDependenciesArrayV2_9": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier of the target for the dependency" + }, + "backtrace": { + "type": "integer", + "minimum": 0, + "description": "Index into backtraceGraph nodes array of the command that created the dependency, if available" + } + }, + "additionalProperties": false + } + }, + "fileSetsV2_5": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "type", + "visibility", + "baseDirectories" + ], + "properties": { + "name": { + "type": "string" + }, + "type": { + "type": "string", + "enum": [ + "HEADERS", + "CXX_MODULES" + ] + }, + "visibility": { + "type": "string", + "enum": [ + "PUBLIC", + "PRIVATE", + "INTERFACE" + ] + }, + "baseDirectories": { + "type": "array", + "minItems": 1, + "items": { + "type": "string" + }, + "description": "Base directories containing the file set's files. If a directory is inside the top level source directory, its path is specified relative to that directory. Otherwise, its path is absolute." + } + }, + "additionalProperties": false + } + }, + "sourcesPath": { + "type": "string", + "description": "Path to the source file. If the file is inside the top level source directory, the path is specified relative to that directory. Otherwise, the path is absolute." + }, + "sourcesCompileGroupIndex": { + "type": "integer", + "minimum": 0, + "description": "Index into the compileGroups array. Only present if the file is compiled." + }, + "sourcesSourceGroupIndex": { + "type": "integer", + "minimum": 0, + "description": "Index into the sourceGroups array. Only present if the file is part of a source group." + }, + "sourcesIsGenerated": { + "type": "boolean", + "description": "True if the file has its GENERATED property set to true" + }, + "sourcesFileSetIndexV2_5": { + "type": "integer", + "minimum": 0, + "description": "Index into the fileSets array. Only present if the file is part of a file set." + }, + "sourcesV2_0": { + "type": "array", + "items": { + "type": "object", + "required": [ + "path" + ], + "properties": { + "path": { + "$ref": "#/definitions/sourcesPath" + }, + "compileGroupIndex": { + "$ref": "#/definitions/sourcesCompileGroupIndex" + }, + "sourceGroupIndex": { + "$ref": "#/definitions/sourcesSourceGroupIndex" + }, + "isGenerated": { + "$ref": "#/definitions/sourcesIsGenerated" + }, + "backtrace": { + "$ref": "#/definitions/backtrace" + } + }, + "additionalProperties": false + } + }, + "sourcesV2_5": { + "type": "array", + "items": { + "type": "object", + "required": [ + "path" + ], + "properties": { + "path": { + "$ref": "#/definitions/sourcesPath" + }, + "compileGroupIndex": { + "$ref": "#/definitions/sourcesCompileGroupIndex" + }, + "sourceGroupIndex": { + "$ref": "#/definitions/sourcesSourceGroupIndex" + }, + "isGenerated": { + "$ref": "#/definitions/sourcesIsGenerated" + }, + "backtrace": { + "$ref": "#/definitions/backtrace" + }, + "fileSetIndex": { + "$ref": "#/definitions/sourcesFileSetIndexV2_5" + } + }, + "additionalProperties": false + } + }, + "interfaceSourcesV2_10": { + "type": "array", + "items": { + "type": "object", + "required": [ + "path" + ], + "properties": { + "path": { + "$ref": "#/definitions/sourcesPath" + }, + "sourceGroupIndex": { + "$ref": "#/definitions/sourcesSourceGroupIndex" + }, + "isGenerated": { + "$ref": "#/definitions/sourcesIsGenerated" + }, + "fileSetIndex": { + "$ref": "#/definitions/sourcesFileSetIndexV2_5" + } + }, + "additionalProperties": false + } + }, + "sourceGroupsV2_0": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "sourceIndexes" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of source group" + }, + "sourceIndexes": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + }, + "description": "Indices into sources array" + } + }, + "additionalProperties": false + } + }, + "sourceGroupsV2_10": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "sourceIndexes" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of source group" + }, + "sourceIndexes": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + }, + "description": "Indices into sources array" + }, + "interfaceSourceIndexes": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + }, + "description": "Indices into interfaceSources array" + } + }, + "additionalProperties": false + } + }, + "compileGroupsSourceIndexes": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + }, + "description": "Indices into the sources array for sources belonging to the group" + }, + "compileGroupsLanguage": { + "type": "string", + "description": "Language used to compile sources in the group" + }, + "compileGroupsLanguageStandardV2_2": { + "type": "object", + "required": [ + "backtraces", + "standard" + ], + "properties": { + "backtraces": { + "type": "array", + "items": { + "type": "integer", + "minimum": 0 + }, + "description": "Indices into the backtraceGraph nodes array" + }, + "standard": { + "type": "string", + "description": "Language standard" + } + }, + "additionalProperties": false + }, + "compileGroupsCompileCommandFragments": { + "type": "array", + "items": { + "type": "object", + "required": [ + "fragment" + ], + "properties": { + "fragment": { + "type": "string", + "description": "Fragment of the compile command line" + }, + "backtrace": { + "type": "integer", + "minimum": 0, + "description": "Index into the backtraceGraph nodes array" + } + }, + "additionalProperties": false + } + }, + "compileGroupsIncludes": { + "type": "array", + "items": { + "type": "object", + "required": [ + "path" + ], + "properties": { + "path": { + "type": "string", + "description": "Include directory path" + }, + "isSystem": { + "type": "boolean", + "description": "True if the path is a system include directory" + }, + "backtrace": { + "type": "integer", + "minimum": 0, + "description": "Index into the backtraceGraph nodes array" + } + }, + "additionalProperties": false + } + }, + "compileGroupsFrameworksV2_6": { + "type": "array", + "items": { + "type": "object", + "required": [ + "path" + ], + "properties": { + "path": { + "type": "string", + "description": "Framework directory path" + }, + "isSystem": { + "type": "boolean", + "description": "True if the path is to a system framework directory" + }, + "backtrace": { + "type": "integer", + "minimum": 0, + "description": "Index into the backtraceGraph nodes array" + } + }, + "additionalProperties": false + } + }, + "compileGroupsPrecompileHeadersV2_1": { + "type": "array", + "items": { + "type": "object", + "required": [ + "header" + ], + "properties": { + "header": { + "type": "string", + "description": "Path to the precompile header file" + }, + "backtrace": { + "type": "integer", + "minimum": 0, + "description": "Index into the backtraceGraph nodes array" + } + }, + "additionalProperties": false + } + }, + "compileGroupsDefines": { + "type": "array", + "items": { + "type": "object", + "required": [ + "define" + ], + "properties": { + "define": { + "type": "string", + "description": "Preprocessor definition in name or name=value format" + }, + "backtrace": { + "type": "integer", + "minimum": 0, + "description": "Index into the backtraceGraph nodes array" + } + }, + "additionalProperties": false + } + }, + "compileGroupsSysroot": { + "type": "object", + "required": [ + "path" + ], + "properties": { + "path": { + "type": "string", + "description": "Absolute path to the sysroot" + } + }, + "additionalProperties": false + }, + "compileGroupsV2_0": { + "type": "array", + "items": { + "type": "object", + "required": [ + "sourceIndexes", + "language" + ], + "properties": { + "sourceIndexes": { + "$ref": "#/definitions/compileGroupsSourceIndexes" + }, + "language": { + "$ref": "#/definitions/compileGroupsLanguage" + }, + "compileCommandFragments": { + "$ref": "#/definitions/compileGroupsCompileCommandFragments" + }, + "includes": { + "$ref": "#/definitions/compileGroupsIncludes" + }, + "defines": { + "$ref": "#/definitions/compileGroupsDefines" + }, + "sysroot": { + "$ref": "#/definitions/compileGroupsSysroot" + } + }, + "additionalProperties": false + } + }, + "compileGroupsV2_1": { + "type": "array", + "items": { + "type": "object", + "required": [ + "sourceIndexes", + "language" + ], + "properties": { + "sourceIndexes": { + "$ref": "#/definitions/compileGroupsSourceIndexes" + }, + "language": { + "$ref": "#/definitions/compileGroupsLanguage" + }, + "compileCommandFragments": { + "$ref": "#/definitions/compileGroupsCompileCommandFragments" + }, + "includes": { + "$ref": "#/definitions/compileGroupsIncludes" + }, + "precompileHeaders": { + "$ref": "#/definitions/compileGroupsPrecompileHeadersV2_1" + }, + "defines": { + "$ref": "#/definitions/compileGroupsDefines" + }, + "sysroot": { + "$ref": "#/definitions/compileGroupsSysroot" + } + }, + "additionalProperties": false + } + }, + "compileGroupsV2_2": { + "type": "array", + "items": { + "type": "object", + "required": [ + "sourceIndexes", + "language" + ], + "properties": { + "sourceIndexes": { + "$ref": "#/definitions/compileGroupsSourceIndexes" + }, + "language": { + "$ref": "#/definitions/compileGroupsLanguage" + }, + "languageStandard": { + "$ref": "#/definitions/compileGroupsLanguageStandardV2_2" + }, + "compileCommandFragments": { + "$ref": "#/definitions/compileGroupsCompileCommandFragments" + }, + "includes": { + "$ref": "#/definitions/compileGroupsIncludes" + }, + "precompileHeaders": { + "$ref": "#/definitions/compileGroupsPrecompileHeadersV2_1" + }, + "defines": { + "$ref": "#/definitions/compileGroupsDefines" + }, + "sysroot": { + "$ref": "#/definitions/compileGroupsSysroot" + } + }, + "additionalProperties": false + } + }, + "compileGroupsV2_6": { + "type": "array", + "items": { + "type": "object", + "required": [ + "sourceIndexes", + "language" + ], + "properties": { + "sourceIndexes": { + "$ref": "#/definitions/compileGroupsSourceIndexes" + }, + "language": { + "$ref": "#/definitions/compileGroupsLanguage" + }, + "languageStandard": { + "$ref": "#/definitions/compileGroupsLanguageStandardV2_2" + }, + "compileCommandFragments": { + "$ref": "#/definitions/compileGroupsCompileCommandFragments" + }, + "includes": { + "$ref": "#/definitions/compileGroupsIncludes" + }, + "frameworks": { + "$ref": "#/definitions/compileGroupsFrameworksV2_6" + }, + "precompileHeaders": { + "$ref": "#/definitions/compileGroupsPrecompileHeadersV2_1" + }, + "defines": { + "$ref": "#/definitions/compileGroupsDefines" + }, + "sysroot": { + "$ref": "#/definitions/compileGroupsSysroot" + } + }, + "additionalProperties": false + } + }, + "backtraceGraph": { + "type": "object", + "required": [ + "nodes", + "commands", + "files" + ], + "properties": { + "nodes": { + "type": "array", + "items": { + "type": "object", + "required": [ + "file" + ], + "properties": { + "file": { + "type": "integer", + "minimum": 0, + "description": "0-based index into the backtrace files array" + }, + "line": { + "type": "integer", + "minimum": 1, + "description": "This is present when the node represents a line within the file. The line number is a 1-based value." + }, + "command": { + "type": "integer", + "minimum": 0, + "description": "This is present when the node represents a command invocation. It is a 0-based index into the backtrace commands array." + }, + "parent": { + "type": "integer", + "minimum": 0, + "description": "This is present when the node is not the bottom of the call stack. It is a 0-based index of another node in the backtrace nodes array." + } + }, + "additionalProperties": false + } + }, + "commands": { + "type": "array", + "description": "Each list item is a string specifying a command name", + "items": { + "type": "string" + } + }, + "files": { + "type": "array", + "description": "Each list item is a string specifying the path to a file, represented with forward slashes. If the file is inside the top level source directory, the path is specified relative to that directory. Otherwise, the path is absolute.", + "items": { + "type": "string" + } + } + }, + "additionalProperties": false + }, + "codemodelV2_0": { + "required": [ + "name", + "id", + "type", + "paths", + "sources", + "backtraceGraph" + ], + "properties": { + "name": { + "$ref": "#/definitions/name" + }, + "id": { + "$ref": "#/definitions/id" + }, + "type": { + "$ref": "#/definitions/typeV2_0" + }, + "backtrace": { + "$ref": "#/definitions/backtrace" + }, + "folder": { + "$ref": "#/definitions/folder" + }, + "paths": { + "$ref": "#/definitions/paths" + }, + "nameOnDisk": { + "$ref": "#/definitions/nameOnDisk" + }, + "artifacts": { + "$ref": "#/definitions/artifacts" + }, + "isGeneratorProvided": { + "$ref": "#/definitions/isGeneratorProvided" + }, + "install": { + "$ref": "#/definitions/install" + }, + "link": { + "$ref": "#/definitions/link" + }, + "archive": { + "$ref": "#/definitions/archive" + }, + "dependencies": { + "$ref": "#/definitions/dependencies" + }, + "sources": { + "$ref": "#/definitions/sourcesV2_0" + }, + "sourceGroups": { + "$ref": "#/definitions/sourceGroupsV2_0" + }, + "compileGroups": { + "$ref": "#/definitions/compileGroupsV2_0" + }, + "backtraceGraph": { + "$ref": "#/definitions/backtraceGraph" + } + }, + "additionalProperties": false + }, + "codemodelV2_1": { + "required": [ + "name", + "id", + "type", + "paths", + "sources", + "backtraceGraph" + ], + "properties": { + "name": { + "$ref": "#/definitions/name" + }, + "id": { + "$ref": "#/definitions/id" + }, + "type": { + "$ref": "#/definitions/typeV2_0" + }, + "backtrace": { + "$ref": "#/definitions/backtrace" + }, + "folder": { + "$ref": "#/definitions/folder" + }, + "paths": { + "$ref": "#/definitions/paths" + }, + "nameOnDisk": { + "$ref": "#/definitions/nameOnDisk" + }, + "artifacts": { + "$ref": "#/definitions/artifacts" + }, + "isGeneratorProvided": { + "$ref": "#/definitions/isGeneratorProvided" + }, + "install": { + "$ref": "#/definitions/install" + }, + "link": { + "$ref": "#/definitions/link" + }, + "archive": { + "$ref": "#/definitions/archive" + }, + "dependencies": { + "$ref": "#/definitions/dependencies" + }, + "sources": { + "$ref": "#/definitions/sourcesV2_0" + }, + "sourceGroups": { + "$ref": "#/definitions/sourceGroupsV2_0" + }, + "compileGroups": { + "$ref": "#/definitions/compileGroupsV2_1" + }, + "backtraceGraph": { + "$ref": "#/definitions/backtraceGraph" + } + }, + "additionalProperties": false + }, + "codemodelV2_2": { + "required": [ + "name", + "id", + "type", + "paths", + "sources", + "backtraceGraph" + ], + "properties": { + "name": { + "$ref": "#/definitions/name" + }, + "id": { + "$ref": "#/definitions/id" + }, + "type": { + "$ref": "#/definitions/typeV2_0" + }, + "backtrace": { + "$ref": "#/definitions/backtrace" + }, + "folder": { + "$ref": "#/definitions/folder" + }, + "paths": { + "$ref": "#/definitions/paths" + }, + "nameOnDisk": { + "$ref": "#/definitions/nameOnDisk" + }, + "artifacts": { + "$ref": "#/definitions/artifacts" + }, + "isGeneratorProvided": { + "$ref": "#/definitions/isGeneratorProvided" + }, + "install": { + "$ref": "#/definitions/install" + }, + "link": { + "$ref": "#/definitions/link" + }, + "archive": { + "$ref": "#/definitions/archive" + }, + "dependencies": { + "$ref": "#/definitions/dependencies" + }, + "sources": { + "$ref": "#/definitions/sourcesV2_0" + }, + "sourceGroups": { + "$ref": "#/definitions/sourceGroupsV2_0" + }, + "compileGroups": { + "$ref": "#/definitions/compileGroupsV2_2" + }, + "backtraceGraph": { + "$ref": "#/definitions/backtraceGraph" + } + }, + "additionalProperties": false + }, + "codemodelV2_5": { + "required": [ + "name", + "id", + "type", + "paths", + "sources", + "backtraceGraph" + ], + "properties": { + "name": { + "$ref": "#/definitions/name" + }, + "id": { + "$ref": "#/definitions/id" + }, + "type": { + "$ref": "#/definitions/typeV2_0" + }, + "backtrace": { + "$ref": "#/definitions/backtrace" + }, + "folder": { + "$ref": "#/definitions/folder" + }, + "paths": { + "$ref": "#/definitions/paths" + }, + "nameOnDisk": { + "$ref": "#/definitions/nameOnDisk" + }, + "artifacts": { + "$ref": "#/definitions/artifacts" + }, + "isGeneratorProvided": { + "$ref": "#/definitions/isGeneratorProvided" + }, + "install": { + "$ref": "#/definitions/install" + }, + "link": { + "$ref": "#/definitions/link" + }, + "archive": { + "$ref": "#/definitions/archive" + }, + "dependencies": { + "$ref": "#/definitions/dependencies" + }, + "fileSets": { + "$ref": "#/definitions/fileSetsV2_5" + }, + "sources": { + "$ref": "#/definitions/sourcesV2_5" + }, + "sourceGroups": { + "$ref": "#/definitions/sourceGroupsV2_0" + }, + "compileGroups": { + "$ref": "#/definitions/compileGroupsV2_2" + }, + "backtraceGraph": { + "$ref": "#/definitions/backtraceGraph" + } + }, + "additionalProperties": false + }, + "codemodelV2_6": { + "required": [ + "name", + "id", + "type", + "paths", + "sources", + "backtraceGraph" + ], + "properties": { + "name": { + "$ref": "#/definitions/name" + }, + "id": { + "$ref": "#/definitions/id" + }, + "type": { + "$ref": "#/definitions/typeV2_0" + }, + "backtrace": { + "$ref": "#/definitions/backtrace" + }, + "folder": { + "$ref": "#/definitions/folder" + }, + "paths": { + "$ref": "#/definitions/paths" + }, + "nameOnDisk": { + "$ref": "#/definitions/nameOnDisk" + }, + "artifacts": { + "$ref": "#/definitions/artifacts" + }, + "isGeneratorProvided": { + "$ref": "#/definitions/isGeneratorProvided" + }, + "install": { + "$ref": "#/definitions/install" + }, + "link": { + "$ref": "#/definitions/link" + }, + "archive": { + "$ref": "#/definitions/archive" + }, + "dependencies": { + "$ref": "#/definitions/dependencies" + }, + "fileSets": { + "$ref": "#/definitions/fileSetsV2_5" + }, + "sources": { + "$ref": "#/definitions/sourcesV2_5" + }, + "sourceGroups": { + "$ref": "#/definitions/sourceGroupsV2_0" + }, + "compileGroups": { + "$ref": "#/definitions/compileGroupsV2_6" + }, + "backtraceGraph": { + "$ref": "#/definitions/backtraceGraph" + } + }, + "additionalProperties": false + }, + "codemodelV2_7": { + "required": [ + "name", + "id", + "type", + "paths", + "sources", + "backtraceGraph" + ], + "properties": { + "name": { + "$ref": "#/definitions/name" + }, + "id": { + "$ref": "#/definitions/id" + }, + "type": { + "$ref": "#/definitions/typeV2_0" + }, + "backtrace": { + "$ref": "#/definitions/backtrace" + }, + "folder": { + "$ref": "#/definitions/folder" + }, + "paths": { + "$ref": "#/definitions/paths" + }, + "nameOnDisk": { + "$ref": "#/definitions/nameOnDisk" + }, + "artifacts": { + "$ref": "#/definitions/artifacts" + }, + "isGeneratorProvided": { + "$ref": "#/definitions/isGeneratorProvided" + }, + "install": { + "$ref": "#/definitions/install" + }, + "launchers": { + "$ref": "#/definitions/launchersV2_7" + }, + "link": { + "$ref": "#/definitions/link" + }, + "archive": { + "$ref": "#/definitions/archive" + }, + "dependencies": { + "$ref": "#/definitions/dependencies" + }, + "fileSets": { + "$ref": "#/definitions/fileSetsV2_5" + }, + "sources": { + "$ref": "#/definitions/sourcesV2_5" + }, + "sourceGroups": { + "$ref": "#/definitions/sourceGroupsV2_0" + }, + "compileGroups": { + "$ref": "#/definitions/compileGroupsV2_6" + }, + "backtraceGraph": { + "$ref": "#/definitions/backtraceGraph" + } + }, + "additionalProperties": false + }, + "codemodelV2_8": { + "required": [ + "name", + "id", + "type", + "paths", + "sources", + "backtraceGraph" + ], + "properties": { + "name": { + "$ref": "#/definitions/name" + }, + "id": { + "$ref": "#/definitions/id" + }, + "type": { + "$ref": "#/definitions/typeV2_0" + }, + "backtrace": { + "$ref": "#/definitions/backtrace" + }, + "folder": { + "$ref": "#/definitions/folder" + }, + "paths": { + "$ref": "#/definitions/paths" + }, + "nameOnDisk": { + "$ref": "#/definitions/nameOnDisk" + }, + "artifacts": { + "$ref": "#/definitions/artifacts" + }, + "isGeneratorProvided": { + "$ref": "#/definitions/isGeneratorProvided" + }, + "install": { + "$ref": "#/definitions/install" + }, + "launchers": { + "$ref": "#/definitions/launchersV2_7" + }, + "link": { + "$ref": "#/definitions/link" + }, + "archive": { + "$ref": "#/definitions/archive" + }, + "debugger": { + "$ref": "#/definitions/debuggerV2_8" + }, + "dependencies": { + "$ref": "#/definitions/dependencies" + }, + "fileSets": { + "$ref": "#/definitions/fileSetsV2_5" + }, + "sources": { + "$ref": "#/definitions/sourcesV2_5" + }, + "sourceGroups": { + "$ref": "#/definitions/sourceGroupsV2_0" + }, + "compileGroups": { + "$ref": "#/definitions/compileGroupsV2_6" + }, + "backtraceGraph": { + "$ref": "#/definitions/backtraceGraph" + } + }, + "additionalProperties": false + }, + "codemodelV2_9": { + "required": [ + "codemodelVersion", + "name", + "id", + "type", + "paths", + "sources", + "backtraceGraph" + ], + "properties": { + "codemodelVersion": { + "$ref": "#/definitions/codemodelVersionV2_9" + }, + "name": { + "$ref": "#/definitions/name" + }, + "id": { + "$ref": "#/definitions/id" + }, + "type": { + "$ref": "#/definitions/typeV2_9" + }, + "imported": { + "$ref": "#/definitions/importedV2_9" + }, + "local": { + "$ref": "#/definitions/localV2_9" + }, + "abstract": { + "$ref": "#/definitions/abstractV2_9" + }, + "backtrace": { + "$ref": "#/definitions/backtrace" + }, + "folder": { + "$ref": "#/definitions/folder" + }, + "paths": { + "$ref": "#/definitions/paths" + }, + "nameOnDisk": { + "$ref": "#/definitions/nameOnDisk" + }, + "artifacts": { + "$ref": "#/definitions/artifacts" + }, + "isGeneratorProvided": { + "$ref": "#/definitions/isGeneratorProvided" + }, + "install": { + "$ref": "#/definitions/install" + }, + "launchers": { + "$ref": "#/definitions/launchersV2_7" + }, + "link": { + "$ref": "#/definitions/link" + }, + "archive": { + "$ref": "#/definitions/archive" + }, + "debugger": { + "$ref": "#/definitions/debuggerV2_8" + }, + "dependencies": { + "$ref": "#/definitions/dependencies" + }, + "linkLibraries": { + "$ref": "#/definitions/linkLibrariesV2_9" + }, + "interfaceLinkLibraries": { + "$ref": "#/definitions/interfaceLinkLibrariesV2_9" + }, + "compileDependencies": { + "$ref": "#/definitions/compileDependenciesV2_9" + }, + "interfaceCompileDependencies": { + "$ref": "#/definitions/interfaceCompileDependenciesV2_9" + }, + "objectDependencies": { + "$ref": "#/definitions/onlyTargetDependenciesArrayV2_9" + }, + "orderDependencies": { + "$ref": "#/definitions/onlyTargetDependenciesArrayV2_9" + }, + "fileSets": { + "$ref": "#/definitions/fileSetsV2_5" + }, + "sources": { + "$ref": "#/definitions/sourcesV2_5" + }, + "symbolic": { + "$ref": "#/definitions/symbolicV2_9" + }, + "sourceGroups": { + "$ref": "#/definitions/sourceGroupsV2_0" + }, + "compileGroups": { + "$ref": "#/definitions/compileGroupsV2_6" + }, + "backtraceGraph": { + "$ref": "#/definitions/backtraceGraph" + } + }, + "additionalProperties": false + }, + "codemodelV2_10": { + "required": [ + "codemodelVersion", + "name", + "id", + "type", + "paths", + "sources", + "backtraceGraph" + ], + "properties": { + "codemodelVersion": { + "$ref": "#/definitions/codemodelVersionV2_10" + }, + "name": { + "$ref": "#/definitions/name" + }, + "id": { + "$ref": "#/definitions/id" + }, + "type": { + "$ref": "#/definitions/typeV2_9" + }, + "imported": { + "$ref": "#/definitions/importedV2_9" + }, + "local": { + "$ref": "#/definitions/localV2_9" + }, + "abstract": { + "$ref": "#/definitions/abstractV2_9" + }, + "backtrace": { + "$ref": "#/definitions/backtrace" + }, + "folder": { + "$ref": "#/definitions/folder" + }, + "paths": { + "$ref": "#/definitions/paths" + }, + "nameOnDisk": { + "$ref": "#/definitions/nameOnDisk" + }, + "artifacts": { + "$ref": "#/definitions/artifacts" + }, + "isGeneratorProvided": { + "$ref": "#/definitions/isGeneratorProvided" + }, + "install": { + "$ref": "#/definitions/install" + }, + "launchers": { + "$ref": "#/definitions/launchersV2_7" + }, + "link": { + "$ref": "#/definitions/link" + }, + "archive": { + "$ref": "#/definitions/archive" + }, + "debugger": { + "$ref": "#/definitions/debuggerV2_8" + }, + "dependencies": { + "$ref": "#/definitions/dependencies" + }, + "linkLibraries": { + "$ref": "#/definitions/linkLibrariesV2_9" + }, + "interfaceLinkLibraries": { + "$ref": "#/definitions/interfaceLinkLibrariesV2_9" + }, + "compileDependencies": { + "$ref": "#/definitions/compileDependenciesV2_9" + }, + "interfaceCompileDependencies": { + "$ref": "#/definitions/interfaceCompileDependenciesV2_9" + }, + "objectDependencies": { + "$ref": "#/definitions/onlyTargetDependenciesArrayV2_9" + }, + "orderDependencies": { + "$ref": "#/definitions/onlyTargetDependenciesArrayV2_9" + }, + "fileSets": { + "$ref": "#/definitions/fileSetsV2_5" + }, + "sources": { + "$ref": "#/definitions/sourcesV2_5" + }, + "interfaceSources": { + "$ref": "#/definitions/interfaceSourcesV2_10" + }, + "symbolic": { + "$ref": "#/definitions/symbolicV2_9" + }, + "sourceGroups": { + "$ref": "#/definitions/sourceGroupsV2_10" + }, + "compileGroups": { + "$ref": "#/definitions/compileGroupsV2_6" + }, + "backtraceGraph": { + "$ref": "#/definitions/backtraceGraph" + } + }, + "additionalProperties": false + } + } +}
diff --git a/Help/manual/file_api/schema_toolchains.json b/Help/manual/file_api/schema_toolchains.json new file mode 100644 index 0000000..d82e439 --- /dev/null +++ b/Help/manual/file_api/schema_toolchains.json
@@ -0,0 +1,241 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "description": "Schema for the CMake toolchains object kind", + "type": "object", + "required": [ + "kind", + "version", + "toolchains" + ], + "oneOf": [ + { + "$ref": "#/definitions/toolchainsObjV1_0" + }, + { + "$ref": "#/definitions/toolchainsObjV1_1" + } + ], + "definitions": { + "kind": { + "type": "string", + "const": "toolchains", + "description": "Specifies the object kind" + }, + "versionV1_0": { + "type": "object", + "required": [ + "major", + "minor" + ], + "properties": { + "major": { + "type": "integer", + "const": 1 + }, + "minor": { + "type": "integer", + "const": 0 + } + }, + "additionalProperties": false + }, + "versionV1_1": { + "type": "object", + "required": [ + "major", + "minor" + ], + "properties": { + "major": { + "type": "integer", + "const": 1 + }, + "minor": { + "type": "integer", + "const": 1 + } + }, + "additionalProperties": false + }, + "language": { + "type": "string", + "description": "Toolchain language identifier (e.g. C, CXX)" + }, + "sourceFileExtensions": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of source file extensions (without leading dot) supported by this toolchain" + }, + "compilerPath": { + "type": "string", + "description": "Path to the compiler executable. This is present when the CMAKE_<LANG>_COMPILER variable is defined." + }, + "compilerCommandFragment": { + "type": "string", + "description": "Mandatory arguments to the compiler, as a command line fragment. This is present when the CMAKE_<LANG>_COMPILER variable is a list containing multiple elements or the CC or similar environment variable contains command line arguments." + }, + "compilerId": { + "type": "string", + "description": "Compiler identifier (e.g. GNU, MSVC). This is present when the CMAKE_<LANG>_COMPILER_ID variable is defined." + }, + "compilerVersion": { + "type": "string", + "description": "Version of the compiler. This is present when the CMAKE_<LANG>_COMPILER_VERSION variable is defined." + }, + "compilerTarget": { + "type": "string", + "description": "Cross-compiling target of the compiler. This is present when the CMAKE_<LANG>_COMPILER_TARGET variable is defined." + }, + "compilerImplicit": { + "type": "object", + "properties": { + "includeDirectories": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of implicit include directories for the compiler. This is present when the CMAKE_<LANG>_IMPLICIT_INCLUDE_DIRECTORIES variable is defined." + }, + "linkDirectories": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of implicit link directories for the compiler front end. This is present when the CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES variable is defined." + }, + "linkFrameworkDirectories": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of implicit link framework directories for the compiler front end. This is present when the CMAKE_<LANG>_IMPLICIT_FRAMEWORK_DIRECTORIES variable is defined." + }, + "linkLibraries": { + "type": "array", + "items": { + "type": "string" + }, + "description": "List of implicit link libraries for the compiler front end. This is present when the CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES variable is defined." + } + }, + "additionalProperties": false + }, + "compilerV1_0": { + "type": "object", + "properties": { + "path": { + "$ref": "#/definitions/compilerPath" + }, + "id": { + "$ref": "#/definitions/compilerId" + }, + "version": { + "$ref": "#/definitions/compilerVersion" + }, + "target": { + "$ref": "#/definitions/compilerTarget" + }, + "implicit": { + "$ref": "#/definitions/compilerImplicit" + } + }, + "additionalProperties": false + }, + "compilerV1_1": { + "type": "object", + "properties": { + "path": { + "$ref": "#/definitions/compilerPath" + }, + "commandFragment": { + "$ref": "#/definitions/compilerCommandFragment" + }, + "id": { + "$ref": "#/definitions/compilerId" + }, + "version": { + "$ref": "#/definitions/compilerVersion" + }, + "target": { + "$ref": "#/definitions/compilerTarget" + }, + "implicit": { + "$ref": "#/definitions/compilerImplicit" + } + }, + "additionalProperties": false + }, + "toolchainsObjV1_0": { + "type": "object", + "properties": { + "kind": { + "$ref": "#/definitions/kind" + }, + "version": { + "$ref": "#/definitions/versionV1_0" + }, + "toolchains": { + "type": "array", + "description": "Array of toolchain configurations per language", + "items": { + "type": "object", + "required": [ + "language", + "compiler" + ], + "properties": { + "language": { + "$ref": "#/definitions/language" + }, + "compiler": { + "$ref": "#/definitions/compilerV1_0" + }, + "sourceFileExtensions": { + "$ref": "#/definitions/sourceFileExtensions" + } + }, + "additionalProperties": false + } + } + }, + "additionalProperties": false + }, + "toolchainsObjV1_1": { + "type": "object", + "properties": { + "kind": { + "$ref": "#/definitions/kind" + }, + "version": { + "$ref": "#/definitions/versionV1_1" + }, + "toolchains": { + "type": "array", + "description": "Array of toolchain configurations per language", + "items": { + "type": "object", + "required": [ + "language", + "compiler" + ], + "properties": { + "language": { + "$ref": "#/definitions/language" + }, + "compiler": { + "$ref": "#/definitions/compilerV1_1" + }, + "sourceFileExtensions": { + "$ref": "#/definitions/sourceFileExtensions" + } + }, + "additionalProperties": false + } + } + }, + "additionalProperties": false + } + } +}
diff --git a/Help/manual/include/OPTIONS_HELP.rst b/Help/manual/include/OPTIONS_HELP.rst index f4f2dbe..aaa6b03 100644 --- a/Help/manual/include/OPTIONS_HELP.rst +++ b/Help/manual/include/OPTIONS_HELP.rst
@@ -1,10 +1,16 @@ .. |file| replace:: The output is printed to a named ``<file>`` if given. -.. option:: -version [<file>], --version [<file>], /V [<file>] +.. option:: -version[=json-v1] [<file>], --version[=json-v1] [<file>], /V[=json-v1] [<file>], /version[=json-v1] [<file>] - Show program name/version banner and exit. + Show program name/version banner and exit. If ``json-v1`` is + specified, print extended version information in JSON format. + The JSON output contains the versions for the CMake and its + dependencies. |file| + The JSON output format is described in machine-readable form by + :download:`this JSON schema </manual/cmake/version-schema.json>`. + .. option:: -h, -H, --help, -help, -usage, /? Print usage information and exit.
diff --git a/Help/manual/instrumentation/query-v1-schema.json b/Help/manual/instrumentation/query-v1-schema.json new file mode 100644 index 0000000..23d4554 --- /dev/null +++ b/Help/manual/instrumentation/query-v1-schema.json
@@ -0,0 +1,54 @@ +{ + "$schema": "http://json-schema.org/draft/2020-12/schema#", + "type": "object", + "required": ["version"], + "properties": { + "version": { + "type": "integer", + "description": "The data version of snippet file to generate.", + "enum": [ + 1 + ] + }, + "callbacks": { + "type": "array", + "description": "A list of command-line strings for callbacks to handle collected instrumentation data. Whenever these callbacks are executed, the full path to a v1 Index File is appended to the arguments included in the string.", + "items": { + "type": "string" + } + }, + "hooks": { + "type": "array", + "description": "A list of strings specifying when indexing should occur automatically. These are the intervals when instrumentation data should be collated and user callbacks should be invoked to handle the data.", + "items": { + "enum": [ + "postGenerate", + "preBuild", + "postBuild", + "preCMakeBuild", + "postCMakeBuild", + "postCMakeInstall", + "postCMakeWorkflow", + "postCTest" + ], + "type": "string" + }, + "uniqueItems": true + }, + "options": { + "type": "array", + "description": "A list of strings used to enable certain optional behavior, including the collection of certain additional data.", + "uniqueItems": true, + "items": { + "enum": [ + "staticSystemInformation", + "dynamicSystemInformation", + "cdashSubmit", + "cdashVerbose", + "trace" + ], + "type": "string" + } + } + } +}
diff --git a/Help/manual/presets/schema.json b/Help/manual/presets/schema.json index 63fbdb7..6b60967 100644 --- a/Help/manual/presets/schema.json +++ b/Help/manual/presets/schema.json
@@ -1,5 +1,5 @@ { - "$schema": "http://json-schema.org/draft-07/schema#", + "$schema": "http://json-schema.org/draft/2020-12/schema#", "type": "object", "description": "The presets specify the generator and the build directory, and optionally a list of variables and other arguments to pass to CMake.", "oneOf": [ @@ -161,6 +161,25 @@ "include": { "$ref": "#/definitions/include" } }, "additionalProperties": false + }, + { + "properties": { + "$schema": { "$ref": "#/definitions/$schema" }, + "$comment": { "$ref": "#/definitions/$comment" }, + "version": { + "const": 11, + "description": "A required integer representing the version of the JSON schema." + }, + "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequiredV10" }, + "vendor": { "$ref": "#/definitions/vendor" }, + "configurePresets": { "$ref": "#/definitions/configurePresetsV10" }, + "buildPresets": { "$ref": "#/definitions/buildPresetsV10" }, + "testPresets": { "$ref": "#/definitions/testPresetsV11" }, + "packagePresets": { "$ref": "#/definitions/packagePresetsV10" }, + "workflowPresets": { "$ref": "#/definitions/workflowPresetsV10" }, + "include": { "$ref": "#/definitions/include" } + }, + "additionalProperties": false } ], "required": [ @@ -189,16 +208,58 @@ } ] }, - "cmakeMinimumRequiredPropertiesV10": { - "type": "object", - "description": "An optional object representing the minimum version of CMake needed to build this project. Available in version 10 and higher.", + "commonPropertiesAll": { + "properties": { + "name": { + "type": "string", + "description": "A required string representing the machine-friendly name of the preset. This identifier is used in the --preset argument. There must not be two presets (configure, build, test, package, or workflow) in the union of CMakePresets.json and CMakeUserPresets.json in the same directory with the same name.", + "minLength": 1 + }, + "vendor": { + "type": "object", + "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, it should follow the same conventions as the root-level vendor field.", + "properties": {} + }, + "displayName": { + "type": "string", + "description": "An optional string with a human-friendly name of the preset." + }, + "description": { + "type": "string", + "description": "An optional string with a human-friendly description of the preset." + } + } + }, + "configureBuildTestPackagePresetsEnvironmentProperty": { + "properties": { + "environment": { + "type": "object", + "description": "An optional map of environment variables. The key is the variable name (which must not be an empty string). Each variable is set regardless of whether or not a value was given to it by the process's environment. This field supports macro expansion, and environment variables in this map may reference each other, and may be listed in any order, as long as such references do not cause a cycle (for example,if ENV_1 is $env{ENV_2}, ENV_2 may not be $env{ENV_1}.) Environment variables are inherited through the inherits field, and the preset's environment will be the union of its own environment and the environment from all its parents. If multiple presets in this union define the same variable, the standard rules of inherits are applied. Setting a variable to null causes it to not be set, even if a value was inherited from another preset.", + "properties": {}, + "additionalProperties": { + "anyOf": [ + { + "type": "null", + "description": "Setting a variable to null causes it to not be set, even if a value was inherited from another preset." + }, + { + "type": "string", + "description": "A string representing the value of the variable." + } + ] + }, + "propertyNames": { + "pattern": "^.+$" + } + } + } + }, + "commentAsProperty": { "properties": { "$comment": { "$ref": "#/definitions/$comment" } } }, - "cmakeMinimumRequiredPropertiesV1": { - "type": "object", - "description": "An optional object representing the minimum version of CMake needed to build this project. Available in version 1 and higher.", + "cmakeMinimumRequiredObject": { "properties": { "major": { "type": "integer", @@ -218,29 +279,18 @@ "type": "object", "description": "An optional object representing the minimum version of CMake needed to build this project. Available in version 10 and higher.", "allOf": [ - { "$ref": "#/definitions/cmakeMinimumRequiredPropertiesV10" }, - { "$ref": "#/definitions/cmakeMinimumRequiredPropertiesV1" } + { "$ref": "#/definitions/cmakeMinimumRequiredObject" }, + { "$ref": "#/definitions/commentAsProperty" } ], - "properties": { - "$comment": {}, - "major": {}, - "minor": {}, - "patch": {} - }, - "additionalProperties": false + "unevaluatedProperties": false }, "cmakeMinimumRequiredV1": { "type": "object", "description": "An optional object representing the minimum version of CMake needed to build this project. Available in version 1 and higher.", "allOf": [ - { "$ref": "#/definitions/cmakeMinimumRequiredPropertiesV1" } + { "$ref": "#/definitions/cmakeMinimumRequiredObject" } ], - "properties": { - "major": {}, - "minor": {}, - "patch": {} - }, - "additionalProperties": false + "unevaluatedProperties": false }, "vendor": { "type": "object", @@ -251,16 +301,7 @@ "type": "string", "description": "An optional string representing the platform for generators that support it." }, - "configurePresetsArchitectureAsObjectV10": { - "type": "object", - "description": "An optional object representing the platform for generators that support it. Available in version 10 and higher.", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" } - } - }, "configurePresetsArchitectureAsObjectV1": { - "type": "object", - "description": "An optional object representing the platform for generators that support it. Available in version 1 and higher.", "properties": { "value": { "type": "string", @@ -283,15 +324,10 @@ "type": "object", "description": "An optional object representing the platform for generators that support it. Available in version 10 and higher.", "allOf": [ - { "$ref": "#/definitions/configurePresetsArchitectureAsObjectV10" }, - { "$ref": "#/definitions/configurePresetsArchitectureAsObjectV1" } + { "$ref": "#/definitions/configurePresetsArchitectureAsObjectV1" }, + { "$ref": "#/definitions/commentAsProperty" } ], - "properties": { - "$comment": {}, - "value": {}, - "strategy": {} - }, - "additionalProperties": false + "unevaluatedProperties": false } ] }, @@ -304,11 +340,7 @@ "allOf": [ { "$ref": "#/definitions/configurePresetsArchitectureAsObjectV1" } ], - "properties": { - "value": {}, - "strategy": {} - }, - "additionalProperties": false + "unevaluatedProperties": false } ] }, @@ -316,16 +348,7 @@ "type": "string", "description": "An optional string representing the toolset for generators that support it." }, - "configurePresetsToolsetAsObjectV10": { - "type": "object", - "description": "An optional object representing the toolset for generators that support it. Available in version 10 and higher.", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" } - } - }, "configurePresetsToolsetAsObjectV1": { - "type": "object", - "description": "An optional object representing the toolset for generators that support it. Available in version 1 and higher.", "properties": { "value": { "type": "string", @@ -348,15 +371,10 @@ "type": "object", "description": "An optional object representing the toolset for generators that support it. Available in version 10 and higher.", "allOf": [ - { "$ref": "#/definitions/configurePresetsToolsetAsObjectV10" }, - { "$ref": "#/definitions/configurePresetsToolsetAsObjectV1" } + { "$ref": "#/definitions/configurePresetsToolsetAsObjectV1" }, + { "$ref": "#/definitions/commentAsProperty" } ], - "properties": { - "$comment": {}, - "value": {}, - "strategy": {} - }, - "additionalProperties": false + "unevaluatedProperties": false } ] }, @@ -369,905 +387,646 @@ "allOf": [ { "$ref": "#/definitions/configurePresetsToolsetAsObjectV1" } ], - "properties": { - "value": {}, - "strategy": {} - }, - "additionalProperties": false + "unevaluatedProperties": false } ] }, - "configurePresetsCacheVariablesAdditionalPropertiesAsNullV1": { + "configurePresetsCacheVariablesAdditionalPropertiesAsNull": { "type": "null", "description": "Setting a variable to null causes it to not be set, even if a value was inherited from another preset." }, - "configurePresetsCacheVariablesAdditionalPropertiesAsBooleanV1": { + "configurePresetsCacheVariablesAdditionalPropertiesAsBoolean": { "type": "boolean", "description": "A boolean representing the value of the variable. Equivalent to \"TRUE\" or \"FALSE\"." }, - "configurePresetsCacheVariablesAdditionalPropertiesAsStringV1": { + "configurePresetsCacheVariablesAdditionalPropertiesAsString": { "type": "string", "description": "A string representing the value of the variable (which supports macro expansion)." }, - "configurePresetsCacheVariablesAdditionalPropertiesAsObjectV10": { - "type": "object", - "description": "An optional object representing the cache variables for generators that support it. Available in version 10 and higher.", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" } - } - }, - "configurePresetsCacheVariablesAdditionalPropertiesAsObjectV1": { - "type": "object", - "description": "An optional object representing the cache variables for generators that support it. Available in version 1 and higher.", + "configurePresetsCacheVariablesAdditionalPropertiesAsObject": { "properties": { "type": { "type": "string", - "description": "An optional string representing the type of the variable. It should be BOOL, FILEPATH, PATH, STRING, or INTERNAL." + "description": "An optional string representing the type of the variable. It should be BOOL, FILEPATH, PATH, STRING, or INTERNAL.", + "enum": [ + "BOOL", "FILEPATH", "PATH", "STRING", "INTERNAL" + ] }, "value": { "anyOf": [ - { - "type": "boolean", - "description": "A required boolean representing the value of the variable. Equivalent to \"TRUE\" or \"FALSE\"." - }, - { - "type": "string", - "description": "A required string representing the value of the variable. This field supports macro expansion." - } + { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesAsBoolean" }, + { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesAsString" } ] } - } + }, + "required": [ + "value" + ] }, "configurePresetsCacheVariablesAdditionalPropertiesV10": { "anyOf": [ - { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesAsNullV1" }, - { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesAsBooleanV1" }, - { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesAsStringV1" }, + { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesAsNull" }, + { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesAsBoolean" }, + { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesAsString" }, { "type": "object", - "description": "An object representing the type and value of the variable. Available in version 10 and higher.", + "description": "An optional object representing the cache variables for generators that support it. Available in version 10 and higher.", "allOf": [ - { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesAsObjectV10" }, - { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesAsObjectV1" } + { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesAsObject" }, + { "$ref": "#/definitions/commentAsProperty" } ], - "properties": { - "$comment": {}, - "type": {}, - "value": {} - }, - "required": [ - "value" - ], - "additionalProperties": false + "unevaluatedProperties": false } ] }, "configurePresetsCacheVariablesAdditionalPropertiesV1": { "anyOf": [ - { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesAsNullV1" }, - { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesAsBooleanV1" }, - { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesAsStringV1" }, + { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesAsNull" }, + { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesAsBoolean" }, + { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesAsString" }, { "type": "object", - "description": "An object representing the type and value of the variable. Available in version 1 and higher.", + "description": "An optional object representing the cache variables for generators that support it. Available in version 1 and higher.", "allOf": [ - { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesAsObjectV1" } + { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesAsObject" } ], - "properties": { - "type": {}, - "value": {} - }, - "required": [ - "value" - ], - "additionalProperties": false + "unevaluatedProperties": false } ] }, - "configurePresetsItemsV10": { - "type": "array", - "description": "An optional array of configure preset objects. Available in version 10 and higher.", - "items": { - "type": "object", - "description": "A configure preset object. Available in version 10 and higher.", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" }, - "warnings": { - "properties": { - "$comment": { "$ref": "#/definitions/$comment" } + "configurePresetsTraceV10": { + "type": "object", + "description": "An optional object specifying trace options.", + "allOf": [ + { "$ref": "#/definitions/configurePresetsTraceObject" }, + { "$ref": "#/definitions/commentAsProperty" } + ], + "unevaluatedProperties": false + }, + "configurePresetsTraceV7": { + "type": "object", + "description": "An optional object specifying trace options.", + "allOf": [ + { "$ref": "#/definitions/configurePresetsTraceObject" } + ], + "unevaluatedProperties": false + }, + "configurePresetsTraceObject": { + "properties": { + "mode": { + "type": "string", + "description": "An optional string that specifies the trace mode.", + "enum": [ + "on", "off", "expand" + ] + }, + "format": { + "type": "string", + "description": "An optional string that specifies the trace output format.", + "enum": [ + "human", "json-v1" + ] + }, + "source": { + "anyOf": [ + { + "type": "string", + "description": "An optional string representing the path to one source file to be traced.", + "minLength": 1 + }, + { + "type": "array", + "description": "An optional array of strings representing the paths to source files to be traced.", + "items": { + "type": "string", + "description": "A string representing the path to one source file to be traced.", + "minLength": 1 + } } - }, - "errors": { - "properties": { - "$comment": { "$ref": "#/definitions/$comment" } - } - }, - "debug": { - "properties": { - "$comment": { "$ref": "#/definitions/$comment" } - } - }, - "trace": { - "properties": { - "$comment": { "$ref": "#/definitions/$comment" } - } - }, - "graphviz": { - "type": "string", - "description": "An optional string specifying the path to graphviz dot file. Available in version 10 and higher." - } + ] + }, + "redirect": { + "type": "string", + "description": "An optional string specifying a path to a trace output file." } } }, - "configurePresetsItemsV7": { - "type": "array", - "description": "An optional array of configure preset objects. Available in version 7 and higher.", - "items": { - "type": "object", - "description": "A configure preset object. Available in version 7 and higher.", - "properties": { - "trace": { - "type": "object", - "description": "An optional object specifying trace options.", - "properties": { - "mode": { - "type": "string", - "description": "An optional string that specifies the trace mode.", - "enum": [ - "on", "off", "expand" - ] - }, - "format": { - "type": "string", - "description": "An optional string that specifies the trace output format.", - "enum": [ - "human", "json-v1" - ] - }, - "source": { - "anyOf": [ - { - "type": "string", - "description": "An optional string representing the path to one source file to be traced.", - "minLength": 1 - }, - { - "type": "array", - "description": "An optional array of strings representing the paths to source files to be traced.", - "items": { - "type": "string", - "description": "A string representing the path to one source file to be traced.", - "minLength": 1 - } - } - ] - }, - "redirect": { - "type": "string", - "description": "An optional string specifying a path to a trace output file." - } - } - } + "configurePresetsDebugV10": { + "type": "object", + "description": "An optional object specifying debug options.", + "allOf": [ + { "$ref": "#/definitions/configurePresetsDebugObject" }, + { "$ref": "#/definitions/commentAsProperty" } + ], + "unevaluatedProperties": false + }, + "configurePresetsDebugV1": { + "type": "object", + "description": "An optional object specifying debug options.", + "allOf": [ + { "$ref": "#/definitions/configurePresetsDebugObject" } + ], + "unevaluatedProperties": false + }, + "configurePresetsErrorsV10": { + "type": "object", + "description": "An optional object specifying errors.", + "allOf": [ + { "$ref": "#/definitions/configurePresetsErrorsObject" }, + { "$ref": "#/definitions/commentAsProperty" } + ], + "unevaluatedProperties": false + }, + "configurePresetsErrorsV1": { + "type": "object", + "description": "An optional object specifying errors.", + "allOf": [ + { "$ref": "#/definitions/configurePresetsErrorsObject" } + ], + "unevaluatedProperties": false + }, + "configurePresetsWarningsV10": { + "type": "object", + "description": "An optional object specifying warnings.", + "allOf": [ + { "$ref": "#/definitions/configurePresetsWarningsObject" }, + { "$ref": "#/definitions/commentAsProperty" } + ], + "unevaluatedProperties": false + }, + "configurePresetsWarningsV1": { + "type": "object", + "description": "An optional object specifying warnings.", + "allOf": [ + { "$ref": "#/definitions/configurePresetsWarningsObject" } + ], + "unevaluatedProperties": false + }, + "configurePresetsDebugObject": { + "properties": { + "output": { + "type": "boolean", + "description": "An optional boolean. Setting this to true is equivalent to passing --debug-output on the command line." + }, + "tryCompile": { + "type": "boolean", + "description": "An optional boolean. Setting this to true is equivalent to passing --debug-trycompile on the command line." + }, + "find": { + "type": "boolean", + "description": "An optional boolean. Setting this to true is equivalent to passing --debug-find on the command line." + } + } + }, + "configurePresetsErrorsObject": { + "properties": { + "dev": { + "type": "boolean", + "description": "An optional boolean. Equivalent to passing -Werror=dev or -Wno-error=dev on the command line. This may not be set to true if warnings.dev is set to false." + }, + "deprecated": { + "type": "boolean", + "description": "An optional boolean. Equivalent to passing -Werror=deprecated or -Wno-error=deprecated on the command line. This may not be set to true if warnings.deprecated is set to false." + } + } + }, + "configurePresetsWarningsObject": { + "properties": { + "dev": { + "type": "boolean", + "description": "An optional boolean. Equivalent to passing -Wdev or -Wno-dev on the command line. This may not be set to false if errors.dev is set to true." + }, + "deprecated": { + "type": "boolean", + "description": "An optional boolean. Equivalent to passing -Wdeprecated or -Wno-deprecated on the command line. This may not be set to false if errors.deprecated is set to true." + }, + "uninitialized": { + "type": "boolean", + "description": "An optional boolean. Setting this to true is equivalent to passing --warn-uninitialized on the command line." + }, + "unusedCli": { + "type": "boolean", + "description": "An optional boolean. Setting this to false is equivalent to passing --no-warn-unused-cli on the command line." + }, + "systemVars": { + "type": "boolean", + "description": "An optional boolean. Setting this to true is equivalent to passing --check-system-vars on the command line." + } + } + }, + "configurePresetsItemsV10": { + "properties": { + "graphviz": { + "type": "string", + "description": "An optional string specifying the path to graphviz dot file. Available in version 10 and higher." } } }, "configurePresetsItemsV3": { - "type": "array", - "description": "An optional array of configure preset objects. Available in version 3 and higher.", - "items": { - "type": "object", - "description": "A configure preset object. Available in version 3 and higher.", - "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." - } + "properties": { + "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, which will be used as the CMAKE_INSTALL_PREFIX variable. This field supports macro expansion. If a relative path is specified, it is calculated relative to the source directory." } } }, "configurePresetsItemsV1": { - "type": "array", - "description": "An optional array of configure preset objects. Available in version 1 and higher.", - "items": { - "type": "object", - "description": "A configure preset object. Available in version 1 and higher.", - "properties": { - "name": { - "type": "string", - "description": "A required string representing the machine-friendly name of the preset. This identifier is used in the --preset argument. There must not be two presets in the union of CMakePresets.json and CMakeUserPresets.json in the same directory with the same name.", - "minLength": 1 - }, - "hidden": { - "type": "boolean", - "description": "An optional boolean specifying whether or not a preset should be hidden. If a preset is hidden, it cannot be used in the --preset= argument, will not show up in the CMake GUI, and does not have to have a valid generator or binaryDir, even from inheritance. Hidden presets are intended to be used as a base for other presets to inherit via the inherits field." - }, - "inherits": { - "anyOf": [ - { - "type": "string", - "description": "An optional string representing the name of the preset to inherit from.", - "minLength": 1 - }, - { - "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 must not inherit from presets in CMakeUserPresets.json.", - "items": { + "allOf": [ + { "$ref": "#/definitions/commonPropertiesAll" }, + { "$ref": "#/definitions/configureBuildTestPackagePresetsEnvironmentProperty" }, + { + "properties": { + "hidden": { + "type": "boolean", + "description": "An optional boolean specifying whether or not a preset should be hidden. If a preset is hidden, it cannot be used in the --preset= argument, will not show up in the CMake GUI, and does not have to have a valid generator or binaryDir, even from inheritance. Hidden presets are intended to be used as a base for other presets to inherit via the inherits field." + }, + "inherits": { + "anyOf": [ + { "type": "string", "description": "An optional string representing the name of the preset to inherit from.", "minLength": 1 - } - } - ] - }, - "vendor": { - "type": "object", - "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, it should follow the same conventions as the root-level vendor field. If vendors use their own per-preset vendor field, they should implement inheritance in a sensible manner when appropriate.", - "properties": {} - }, - "displayName": { - "type": "string", - "description": "An optional string with a human-friendly name of the preset." - }, - "description": { - "type": "string", - "description": "An optional string with a human-friendly description of the preset." - }, - "generator": { - "type": "string", - "description": "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). 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." - }, - "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, it must be inherited from the inherits preset (unless this preset is hidden)." - }, - "cmakeExecutable": { - "type": "string", - "description": "An optional string representing the path to the CMake executable to use for this preset. This is reserved for use by IDEs, and is not used by CMake itself. IDEs that use this field should expand any macros in it." - }, - "cacheVariables": { - "type": "object", - "description": "An optional map of cache variables. The key is the variable name (which must not be an empty string). Cache variables are inherited through the inherits field, and the preset's variables will be the union of its own cacheVariables and the cacheVariables from all its parents. If multiple presets in this union define the same variable, the standard rules of inherits are applied.", - "properties": {}, - "propertyNames": { - "pattern": "^.+$" - } - }, - "environment": { - "type": "object", - "description": "An optional map of environment variables. The key is the variable name (which must not be an empty string). Each variable is set regardless of whether or not a value was given to it by the process's environment. This field supports macro expansion, and environment variables in this map may reference each other, and may be listed in any order, as long as such references do not cause a cycle (for example,if ENV_1 is $env{ENV_2}, ENV_2 may not be $env{ENV_1}.) Environment variables are inherited through the inherits field, and the preset's environment will be the union of its own environment and the environment from all its parents. If multiple presets in this union define the same variable, the standard rules of inherits are applied. Setting a variable to null causes it to not be set, even if a value was inherited from another preset.", - "properties": {}, - "additionalProperties": { - "anyOf": [ - { - "type": "null", - "description": "Setting a variable to null causes it to not be set, even if a value was inherited from another preset." }, { - "type": "string", - "description": "A string representing the value of the variable." + "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 must not inherit from presets in CMakeUserPresets.json.", + "items": { + "type": "string", + "description": "An optional string representing the name of the preset to inherit from.", + "minLength": 1 + } } ] }, - "propertyNames": { - "pattern": "^.+$" - } - }, - "warnings": { - "type": "object", - "description": "An optional object specifying warnings.", - "properties": { - "dev": { - "type": "boolean", - "description": "An optional boolean. Equivalent to passing -Wdev or -Wno-dev on the command line. This may not be set to false if errors.dev is set to true." - }, - "deprecated": { - "type": "boolean", - "description": "An optional boolean. Equivalent to passing -Wdeprecated or -Wno-deprecated on the command line. This may not be set to false if errors.deprecated is set to true." - }, - "uninitialized": { - "type": "boolean", - "description": "An optional boolean. Setting this to true is equivalent to passing --warn-uninitialized on the command line." - }, - "unusedCli": { - "type": "boolean", - "description": "An optional boolean. Setting this to false is equivalent to passing --no-warn-unused-cli on the command line." - }, - "systemVars": { - "type": "boolean", - "description": "An optional boolean. Setting this to true is equivalent to passing --check-system-vars on the command line." - } - } - }, - "errors": { - "type": "object", - "description": "An optional object specifying errors.", - "properties": { - "dev": { - "type": "boolean", - "description": "An optional boolean. Equivalent to passing -Werror=dev or -Wno-error=dev on the command line. This may not be set to true if warnings.dev is set to false." - }, - "deprecated": { - "type": "boolean", - "description": "An optional boolean. Equivalent to passing -Werror=deprecated or -Wno-error=deprecated on the command line. This may not be set to true if warnings.deprecated is set to false." - } - } - }, - "debug": { - "type": "object", - "description": "An optional object specifying debug options.", - "properties": { - "output": { - "type": "boolean", - "description": "An optional boolean. Setting this to true is equivalent to passing --debug-output on the command line." - }, - "tryCompile": { - "type": "boolean", - "description": "An optional boolean. Setting this to true is equivalent to passing --debug-trycompile on the command line." - }, - "find": { - "type": "boolean", - "description": "An optional boolean. Setting this to true is equivalent to passing --debug-find on the command line." - } + "cmakeExecutable": { + "type": "string", + "description": "An optional string representing the path to the CMake executable to use for this preset. This is reserved for use by IDEs, and is not used by CMake itself. IDEs that use this field should expand any macros in it." } } } + ], + "required": [ + "name" + ] + }, + "configurePresetsAdditionalPropertiesV10": { + "properties": { + "toolset": { "$ref": "#/definitions/configurePresetsToolsetV10" }, + "architecture": { "$ref": "#/definitions/configurePresetsArchitectureV10" }, + "cacheVariables": { + "type": "object", + "description": "An optional map of cache variables. The key is the variable name (which must not be an empty string). Cache variables are inherited through the inherits field, and the preset's variables will be the union of its own cacheVariables and the cacheVariables from all its parents. If multiple presets in this union define the same variable, the standard rules of inherits are applied.", + "properties": {}, + "propertyNames": { + "pattern": "^.+$" + }, + "additionalProperties": { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesV10" } + }, + "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." + }, + "condition": { "$ref": "#/definitions/topConditionV10" }, + "warnings": { "$ref": "#/definitions/configurePresetsWarningsV10" }, + "errors": { "$ref": "#/definitions/configurePresetsErrorsV10" }, + "debug": { "$ref": "#/definitions/configurePresetsDebugV10" }, + "trace": { "$ref": "#/definitions/configurePresetsTraceV10" } + } + }, + "configurePresetsAdditionalPropertiesV7": { + "allOf": [ + { "$ref": "#/definitions/configurePresetsAdditionalPropertiesV3" }, + { + "properties": { + "trace": { "$ref": "#/definitions/configurePresetsTraceV7" } + } + } + ] + }, + "configurePresetsAdditionalPropertiesV3": { + "allOf": [ + { "$ref": "#/definitions/configurePresetsAdditionalPropertiesV1" }, + { + "properties": { + "condition": { "$ref": "#/definitions/topConditionV3" }, + "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." + } + } + } + ] + }, + "configurePresetsAdditionalPropertiesV1": { + "properties": { + "toolset": { "$ref": "#/definitions/configurePresetsToolsetV1" }, + "architecture": { "$ref": "#/definitions/configurePresetsArchitectureV1" }, + "cacheVariables": { + "type": "object", + "description": "An optional map of cache variables. The key is the variable name (which must not be an empty string). Cache variables are inherited through the inherits field, and the preset's variables will be the union of its own cacheVariables and the cacheVariables from all its parents. If multiple presets in this union define the same variable, the standard rules of inherits are applied.", + "properties": {}, + "propertyNames": { + "pattern": "^.+$" + }, + "additionalProperties": { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesV1" } + }, + "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, it must be inherited from the inherits preset (unless this preset is hidden)." + }, + "generator": { + "type": "string", + "description": "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). 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." + }, + "warnings": { "$ref": "#/definitions/configurePresetsWarningsV1" }, + "errors": { "$ref": "#/definitions/configurePresetsErrorsV1" }, + "debug": { "$ref": "#/definitions/configurePresetsDebugV1" } } }, "configurePresetsV10": { "type": "array", "description": "An optional array of configure preset objects. Available in version 10 and higher.", - "allOf": [ - { "$ref": "#/definitions/configurePresetsItemsV10" }, - { "$ref": "#/definitions/configurePresetsItemsV7" }, - { "$ref": "#/definitions/configurePresetsItemsV3" }, - { "$ref": "#/definitions/configurePresetsItemsV1" } - ], "items": { - "properties": { - "$comment": {}, - "name": {}, - "hidden": {}, - "inherits": {}, - "vendor": {}, - "displayName": {}, - "description": {}, - "generator": {}, - "architecture": { "$ref": "#/definitions/configurePresetsArchitectureV10" }, - "toolset": { "$ref": "#/definitions/configurePresetsToolsetV10" }, - "toolchainFile": {}, - "graphviz": {}, - "binaryDir": {}, - "installDir": {}, - "cmakeExecutable": {}, - "cacheVariables": { - "additionalProperties": { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesV10" } - }, - "environment": {}, - "warnings": { - "properties": { - "$comment": {}, - "dev": {}, - "deprecated": {}, - "uninitialized": {}, - "unusedCli": {}, - "systemVars": {} - }, - "additionalProperties": false - }, - "errors": { - "properties": { - "$comment": {}, - "dev": {}, - "deprecated": {} - }, - "additionalProperties": false - }, - "debug": { - "properties": { - "$comment": {}, - "output": {}, - "tryCompile": {}, - "find": {} - }, - "additionalProperties": false - }, - "condition": { "$ref": "#/definitions/topConditionV10" }, - "trace": { - "properties": { - "$comment": {}, - "mode": {}, - "format": {}, - "source": {}, - "redirect": {} - }, - "additionalProperties": false - } - }, - "required": [ - "name" + "type": "object", + "description": "A configure preset object.", + "allOf": [ + { "$ref": "#/definitions/configurePresetsItemsV10" }, + { "$ref": "#/definitions/configurePresetsItemsV3" }, + { "$ref": "#/definitions/configurePresetsItemsV1" }, + { "$ref": "#/definitions/configurePresetsAdditionalPropertiesV10" }, + { "$ref": "#/definitions/commentAsProperty" } ], - "additionalProperties": false + "unevaluatedProperties": false } }, "configurePresetsV7": { "type": "array", "description": "An optional array of configure preset objects. Available in version 7 and higher.", - "allOf": [ - { "$ref": "#/definitions/configurePresetsItemsV7" }, - { "$ref": "#/definitions/configurePresetsItemsV3" }, - { "$ref": "#/definitions/configurePresetsItemsV1" } - ], "items": { - "properties": { - "name": {}, - "hidden": {}, - "inherits": {}, - "vendor": {}, - "displayName": {}, - "description": {}, - "generator": {}, - "architecture": { "$ref": "#/definitions/configurePresetsArchitectureV1" }, - "toolset": { "$ref": "#/definitions/configurePresetsToolsetV1" }, - "toolchainFile": {}, - "binaryDir": {}, - "installDir": {}, - "cmakeExecutable": {}, - "cacheVariables": { - "additionalProperties": { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesV1" } - }, - "environment": {}, - "warnings": { - "properties": { - "dev": {}, - "deprecated": {}, - "uninitialized": {}, - "unusedCli": {}, - "systemVars": {} - }, - "additionalProperties": false - }, - "errors": { - "properties": { - "dev": {}, - "deprecated": {} - }, - "additionalProperties": false - }, - "debug": { - "properties": { - "output": {}, - "tryCompile": {}, - "find": {} - }, - "additionalProperties": false - }, - "condition": { "$ref": "#/definitions/topConditionV3" }, - "trace": { - "properties": { - "mode": {}, - "format": {}, - "source": {}, - "redirect": {} - }, - "additionalProperties": false - } - }, - "required": [ - "name" + "type": "object", + "description": "A configure preset object.", + "allOf": [ + { "$ref": "#/definitions/configurePresetsItemsV3" }, + { "$ref": "#/definitions/configurePresetsItemsV1" }, + { "$ref": "#/definitions/configurePresetsAdditionalPropertiesV7" } ], - "additionalProperties": false + "unevaluatedProperties": false } }, "configurePresetsV3": { "type": "array", "description": "An optional array of configure preset objects. Available in version 3 and higher.", - "allOf": [ - { "$ref": "#/definitions/configurePresetsItemsV3" }, - { "$ref": "#/definitions/configurePresetsItemsV1" } - ], "items": { - "properties": { - "name": {}, - "hidden": {}, - "inherits": {}, - "vendor": {}, - "displayName": {}, - "description": {}, - "generator": {}, - "architecture": { "$ref": "#/definitions/configurePresetsArchitectureV1" }, - "toolset": { "$ref": "#/definitions/configurePresetsToolsetV1" }, - "toolchainFile": {}, - "binaryDir": {}, - "installDir": {}, - "cmakeExecutable": {}, - "cacheVariables": { - "additionalProperties": { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesV1" } - }, - "environment": {}, - "warnings": { - "properties": { - "dev": {}, - "deprecated": {}, - "uninitialized": {}, - "unusedCli": {}, - "systemVars": {} - }, - "additionalProperties": false - }, - "errors": { - "properties": { - "dev": {}, - "deprecated": {} - }, - "additionalProperties": false - }, - "debug": { - "properties": { - "output": {}, - "tryCompile": {}, - "find": {} - }, - "additionalProperties": false - }, - "condition": { "$ref": "#/definitions/topConditionV3" } - }, - "required": [ - "name" + "type": "object", + "description": "A configure preset object.", + "allOf": [ + { "$ref": "#/definitions/configurePresetsItemsV3" }, + { "$ref": "#/definitions/configurePresetsItemsV1" }, + { "$ref": "#/definitions/configurePresetsAdditionalPropertiesV3" } ], - "additionalProperties": false + "unevaluatedProperties": false } }, "configurePresetsV1": { "type": "array", "description": "An optional array of configure preset objects. Available in version 1 and higher.", - "allOf": [ - { "$ref": "#/definitions/configurePresetsItemsV1" } - ], - "items": { - "properties": { - "name": {}, - "hidden": {}, - "inherits": {}, - "vendor": {}, - "displayName": {}, - "description": {}, - "generator": {}, - "architecture": { "$ref": "#/definitions/configurePresetsArchitectureV1" }, - "toolset": { "$ref": "#/definitions/configurePresetsToolsetV1" }, - "binaryDir": {}, - "cmakeExecutable": {}, - "cacheVariables": { - "additionalProperties": { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesV1" } - }, - "environment": {}, - "warnings": { - "properties": { - "dev": {}, - "deprecated": {}, - "uninitialized": {}, - "unusedCli": {}, - "systemVars": {} - }, - "additionalProperties": false - }, - "errors": { - "properties": { - "dev": {}, - "deprecated": {} - }, - "additionalProperties": false - }, - "debug": { - "properties": { - "output": {}, - "tryCompile": {}, - "find": {} - }, - "additionalProperties": false - } - }, - "required": [ - "name" - ], - "additionalProperties": false - } - }, - "buildPresetsItemsV10": { - "type": "array", - "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 10 and higher.", "items": { "type": "object", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" } - } + "description": "A configure preset object.", + "allOf": [ + { "$ref": "#/definitions/configurePresetsItemsV1" }, + { "$ref": "#/definitions/configurePresetsAdditionalPropertiesV1" } + ], + "unevaluatedProperties": false } }, "buildPresetsItemsV4": { - "type": "array", - "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 4 and higher.", - "items": { - "type": "object", - "properties": { - "resolvePackageReferences": { - "type": "string", - "description": "An optional string specifying the package resolve behavior. Valid values are \"on\" (packages are resolved prior to the build), \"off\" (packages are not resolved prior to the build), and \"only\" (packages are resolved, but no build will be performed).", - "enum": [ - "on", "off", "only" - ] - } + "properties": { + "resolvePackageReferences": { + "type": "string", + "description": "An optional string specifying the package resolve behavior. Valid values are \"on\" (packages are resolved prior to the build), \"off\" (packages are not resolved prior to the build), and \"only\" (packages are resolved, but no build will be performed).", + "enum": [ + "on", "off", "only" + ] } } }, - "buildPresetsItemsV3": { - "type": "array", - "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 3 and higher." - }, "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": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "A required string representing the machine-friendly name of the preset. This identifier is used in the --preset argument. There must not be two presets (configure, build, test, package, or workflow) in the union of CMakePresets.json and CMakeUserPresets.json in the same directory with the same name.", - "minLength": 1 - }, - "hidden": { - "type": "boolean", - "description": "An optional boolean specifying whether or not a preset should be hidden. If a preset is hidden, it cannot be used in the --preset argument and does not have to have a valid configurePreset, even from inheritance. Hidden presets are intended to be used as a base for other presets to inherit via the inherits field." - }, - "inherits": { - "anyOf": [ - { - "type": "string", - "description": "An optional string representing the name of the build preset to inherit from.", - "minLength": 1 - }, - { - "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 must not inherit from presets in CMakeUserPresets.json.", - "items": { - "type": "string", - "description": "An optional string representing the name of the preset to inherit from.", - "minLength": 1 - } - } - ] - }, - "configurePreset": { - "type": "string", - "description": "An optional string specifying the name of a configure preset to associate with this build preset. If configurePreset is not specified, it must be inherited from the inherits preset (unless this preset is hidden). The build tree directory is inferred from the configure preset.", - "minLength": 1 - }, - "vendor": { - "type": "object", - "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, it should follow the same conventions as the root-level vendor field. If vendors use their own per-preset vendor field, they should implement inheritance in a sensible manner when appropriate.", - "properties": {} - }, - "displayName": { - "type": "string", - "description": "An optional string with a human-friendly name of the preset." - }, - "description": { - "type": "string", - "description": "An optional string with a human-friendly description of the preset." - }, - "inheritConfigureEnvironment": { - "type": "boolean", - "description": "An optional boolean that defaults to true. If true, the environment variables from the associated configure preset are inherited after all inherited build preset environments, but before environment variables explicitly specified in this build preset." - }, - "environment": { - "type": "object", - "description": "An optional map of environment variables. The key is the variable name (which must not be an empty string). Each variable is set regardless of whether or not a value was given to it by the process's environment. This field supports macro expansion, and environment variables in this map may reference each other, and may be listed in any order, as long as such references do not cause a cycle (for example,if ENV_1 is $env{ENV_2}, ENV_2 may not be $env{ENV_1}.) Environment variables are inherited through the inherits field, and the preset's environment will be the union of its own environment and the environment from all its parents. If multiple presets in this union define the same variable, the standard rules of inherits are applied. Setting a variable to null causes it to not be set, even if a value was inherited from another preset.", - "properties": {}, - "additionalProperties": { + "allOf": [ + { "$ref": "#/definitions/commonPropertiesAll" }, + { "$ref": "#/definitions/configureBuildTestPackagePresetsEnvironmentProperty" }, + { + "properties": { + "hidden": { + "type": "boolean", + "description": "An optional boolean specifying whether or not a preset should be hidden. If a preset is hidden, it cannot be used in the --preset argument and does not have to have a valid configurePreset, even from inheritance. Hidden presets are intended to be used as a base for other presets to inherit via the inherits field." + }, + "inherits": { "anyOf": [ { - "type": "null", - "description": "Setting a variable to null causes it to not be set, even if a value was inherited from another preset." + "type": "string", + "description": "An optional string representing the name of the build preset to inherit from.", + "minLength": 1 }, { - "type": "string", - "description": "A string representing the value of the variable." + "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 must not inherit from presets in CMakeUserPresets.json.", + "items": { + "type": "string", + "description": "An optional string representing the name of the preset to inherit from.", + "minLength": 1 + } } ] }, - "propertyNames": { - "pattern": "^.+$" - } - }, - "jobs": { - "type": "integer", - "description": "An optional integer. Equivalent to passing --parallel or -j on the command line." - }, - "targets": { - "anyOf": [ - { - "type": "string", - "description": "An optional string. Equivalent to passing --target or -t on the command line. Vendors may ignore the targets property or hide build presets that explicitly specify targets." - }, - { - "type": "array", - "description": "An optional array of strings. Equivalent to passing --target or -t on the command line. Vendors may ignore the targets property or hide build presets that explicitly specify targets.", - "items": { + "configurePreset": { + "type": "string", + "description": "An optional string specifying the name of a configure preset to associate with this build preset. If configurePreset is not specified, it must be inherited from the inherits preset (unless this preset is hidden). The build tree directory is inferred from the configure preset.", + "minLength": 1 + }, + "inheritConfigureEnvironment": { + "type": "boolean", + "description": "An optional boolean that defaults to true. If true, the environment variables from the associated configure preset are inherited after all inherited build preset environments, but before environment variables explicitly specified in this build preset." + }, + "jobs": { + "type": "integer", + "description": "An optional non-negative integer. Equivalent to passing --parallel or -j on the command line.", + "minimum": 0 + }, + "targets": { + "anyOf": [ + { "type": "string", "description": "An optional string. Equivalent to passing --target or -t on the command line. Vendors may ignore the targets property or hide build presets that explicitly specify targets." + }, + { + "type": "array", + "description": "An optional array of strings. Equivalent to passing --target or -t on the command line. Vendors may ignore the targets property or hide build presets that explicitly specify targets.", + "items": { + "type": "string", + "description": "An optional string. Equivalent to passing --target or -t on the command line. Vendors may ignore the targets property or hide build presets that explicitly specify targets." + } } - } - ] - }, - "configuration": { - "type": "string", - "description": "An optional string. Equivalent to passing --config on the command line." - }, - "cleanFirst": { - "type": "boolean", - "description": "An optional boolean. If true, equivalent to passing --clean-first on the command line." - }, - "verbose": { - "type": "boolean", - "description": "An optional boolean. If true, equivalent to passing --verbose on the command line." - }, - "nativeToolOptions": { - "type": "array", - "description": "An optional array of strings. Equivalent to passing options after -- on the command line.", - "items": { + ] + }, + "configuration": { "type": "string", - "description": "An optional string representing an option to pass after -- on the command line." + "description": "An optional string. Equivalent to passing --config on the command line." + }, + "cleanFirst": { + "type": "boolean", + "description": "An optional boolean. If true, equivalent to passing --clean-first on the command line." + }, + "verbose": { + "type": "boolean", + "description": "An optional boolean. If true, equivalent to passing --verbose on the command line." + }, + "nativeToolOptions": { + "type": "array", + "description": "An optional array of strings. Equivalent to passing options after -- on the command line.", + "items": { + "type": "string", + "description": "An optional string representing an option to pass after -- on the command line." + } } } } + ], + "required": [ + "name" + ] + }, + "buildPresetsAdditionalPropertiesV10": { + "properties": { + "condition": { "$ref": "#/definitions/topConditionV10" } + } + }, + "buildPresetsAdditionalPropertiesV3": { + "properties": { + "condition": { "$ref": "#/definitions/topConditionV3" } } }, "buildPresetsV10": { "type": "array", "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 10 and higher.", - "allOf": [ - { "$ref": "#/definitions/buildPresetsItemsV10" }, - { "$ref": "#/definitions/buildPresetsItemsV4" }, - { "$ref": "#/definitions/buildPresetsItemsV3" }, - { "$ref": "#/definitions/buildPresetsItemsV2" } - ], "items": { "type": "object", - "properties": { - "$comment": {}, - "name": {}, - "hidden": {}, - "inherits": {}, - "configurePreset": {}, - "vendor": {}, - "displayName": {}, - "description": {}, - "inheritConfigureEnvironment": {}, - "environment": {}, - "jobs": {}, - "targets": {}, - "configuration": {}, - "cleanFirst": {}, - "resolvePackageReferences": {}, - "verbose": {}, - "nativeToolOptions": {}, - "condition": { "$ref": "#/definitions/topConditionV10" } - }, - "required": [ - "name" + "description": "A build preset object.", + "allOf": [ + { "$ref": "#/definitions/buildPresetsItemsV4" }, + { "$ref": "#/definitions/buildPresetsItemsV2" }, + { "$ref": "#/definitions/buildPresetsAdditionalPropertiesV10" }, + { "$ref": "#/definitions/commentAsProperty" } ], - "additionalProperties": false + "unevaluatedProperties": false } }, "buildPresetsV4": { "type": "array", "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 4 and higher.", - "allOf": [ - { "$ref": "#/definitions/buildPresetsItemsV4" }, - { "$ref": "#/definitions/buildPresetsItemsV3" }, - { "$ref": "#/definitions/buildPresetsItemsV2" } - ], "items": { "type": "object", - "properties": { - "name": {}, - "hidden": {}, - "inherits": {}, - "configurePreset": {}, - "vendor": {}, - "displayName": {}, - "description": {}, - "inheritConfigureEnvironment": {}, - "environment": {}, - "jobs": {}, - "targets": {}, - "configuration": {}, - "cleanFirst": {}, - "resolvePackageReferences": {}, - "verbose": {}, - "nativeToolOptions": {}, - "condition": { "$ref": "#/definitions/topConditionV3" } - }, - "required": [ - "name" + "description": "A build preset object.", + "allOf": [ + { "$ref": "#/definitions/buildPresetsItemsV4" }, + { "$ref": "#/definitions/buildPresetsItemsV2" }, + { "$ref": "#/definitions/buildPresetsAdditionalPropertiesV3" } ], - "additionalProperties": false + "unevaluatedProperties": false } }, "buildPresetsV3": { "type": "array", "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 3 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": { "$ref": "#/definitions/topConditionV3" } - }, - "required": [ - "name" + "description": "A build preset object.", + "allOf": [ + { "$ref": "#/definitions/buildPresetsItemsV2" }, + { "$ref": "#/definitions/buildPresetsAdditionalPropertiesV3" } ], - "additionalProperties": false + "unevaluatedProperties": 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" + "description": "A build preset object.", + "allOf": [ + { "$ref": "#/definitions/buildPresetsItemsV2" } ], - "additionalProperties": false + "unevaluatedProperties": false } }, + "testPresetsExecutionJobsV11": { + "oneOf": [ + { + "type": "integer", + "description": "An optional non-negative integer. Equivalent to passing --parallel or -j on the command line.", + "minimum": 0 + }, + { + "type": "string", + "description": "An optional string. Equivalent to passing --parallel or -j on the command line with the number of jobs omitted.", + "minLength": 0, + "maxLength": 0 + } + ] + }, + "testPresetsExecutionJobsV2": { + "type": "integer", + "description": "An optional non-negative integer. Equivalent to passing --parallel or -j on the command line.", + "minimum": 0 + }, + "testPresetsExecutionRepeatV10": { + "type": "object", + "description": "An optional object specifying how to repeat tests. Equivalent to passing --repeat on the command line.", + "allOf": [ + { "$ref": "#/definitions/testPresetsExecutionRepeatObject" }, + { "$ref": "#/definitions/commentAsProperty" } + ], + "unevaluatedProperties": false + }, + "testPresetsExecutionRepeatV2": { + "type": "object", + "description": "An optional object specifying how to repeat tests. Equivalent to passing --repeat on the command line.", + "allOf": [ + { "$ref": "#/definitions/testPresetsExecutionRepeatObject" } + ], + "unevaluatedProperties": false + }, + "testPresetsExecutionRepeatObject": { + "properties": { + "mode": { + "type": "string", + "description": "A required string. Must be one of the following values: \"until-fail\", \"until-pass\", or \"after-timeout\".", + "enum": [ + "until-fail", "until-pass", "after-timeout" + ] + }, + "count": { + "type": "integer", + "description": "A required integer." + } + }, + "required": [ + "mode", "count" + ] + }, "testPresetsFilterIncludeIndexAsStringV2": { "type": "string", "description": "An optional string specifying a file with the command line syntax for --tests-information. Available in version 2 and higher." @@ -1312,17 +1071,10 @@ "type": "object", "description": "An optional object specifying test preset filters. Available in version 10 and higher.", "allOf": [ - { "$ref": "#/definitions/testPresetsFilterIncludeIndexAsObjectV10" }, - { "$ref": "#/definitions/testPresetsFilterIncludeIndexAsObjectV2" } + { "$ref": "#/definitions/testPresetsFilterIncludeIndexAsObjectV2" }, + { "$ref": "#/definitions/commentAsProperty" } ], - "properties": { - "$comment": {}, - "start": {}, - "end": {}, - "stride": {}, - "specificTests": {} - }, - "additionalProperties": false + "unevaluatedProperties": false } ] }, @@ -1335,1310 +1087,781 @@ "allOf": [ { "$ref": "#/definitions/testPresetsFilterIncludeIndexAsObjectV2" } ], - "properties": { - "start": {}, - "end": {}, - "stride": {}, - "specificTests": {} - }, - "additionalProperties": false + "unevaluatedProperties": false } ] }, - "testPresetsItemsV10": { - "type": "array", - "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 10 and higher.", - "items": { - "type": "object", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" }, - "filter": { - "type": "object", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" }, - "include": { - "type": "object", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" } - } - }, - "exclude": { - "type": "object", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" }, - "fixtures": { - "type": "object", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" } - } - } - } - } + "testPresetsFilterIncludeV10": { + "type": "object", + "description": "An optional object specifying which tests to include.", + "allOf": [ + { "$ref": "#/definitions/testPresetsFilterIncludeObject" }, + { "$ref": "#/definitions/commentAsProperty" }, + { + "properties": { + "index": { "$ref": "#/definitions/testPresetsFilterIncludeIndexV10" } + } + } + ] + }, + "testPresetsFilterIncludeV2": { + "type": "object", + "description": "An optional object specifying which tests to include.", + "allOf": [ + { "$ref": "#/definitions/testPresetsFilterIncludeObject" }, + { + "properties": { + "index": { "$ref": "#/definitions/testPresetsFilterIncludeIndexV2" } + } + } + ] + }, + "testPresetsFilterIncludeObject": { + "properties": { + "name": { + "type": "string", + "description": "An optional string specifying a regex for test names. Equivalent to passing --tests-regex on the command line." + }, + "label": { + "type": "string", + "description": "An optional string specifying a regex for test labels. Equivalent to passing --label-regex on the command line." + }, + "useUnion": { + "type": "boolean", + "description": "An optional boolean. Equivalent to passing --union on the command line." + } + } + }, + "testPresetsFilterExcludeV10": { + "type": "object", + "description": "An optional object specifying which tests to exclude.", + "allOf": [ + { "$ref": "#/definitions/testPresetsFilterExcludeObject" }, + { "$ref": "#/definitions/commentAsProperty" }, + { + "properties": { + "fixtures": { + "allOf": [ + { "$ref": "#/definitions/testPresetsFilterExcludeFixturesV2" }, + { "$ref": "#/definitions/commentAsProperty" } + ] } + } + } + ] + }, + "testPresetsFilterExcludeV2": { + "type": "object", + "description": "An optional object specifying which tests to exclude.", + "allOf": [ + { "$ref": "#/definitions/testPresetsFilterExcludeObject" }, + { + "properties": { + "fixtures": { "$ref": "#/definitions/testPresetsFilterExcludeFixturesV2" } + } + } + ] + }, + "testPresetsFilterExcludeFixturesV2": { + "type": "object", + "description": "An optional object specifying which fixtures to exclude from adding tests.", + "properties": { + "any": { + "type": "string", + "description": "An optional string specifying a regex for text fixtures to exclude from adding any tests. Equivalent to --fixture-exclude-any on the command line." }, - "execution": { - "type": "object", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" }, - "repeat": { - "type": "object", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" } - } - } - } + "setup": { + "type": "string", + "description": "An optional string specifying a regex for text fixtures to exclude from adding setup tests. Equivalent to --fixture-exclude-setup on the command line." + }, + "cleanup": { + "type": "string", + "description": "An optional string specifying a regex for text fixtures to exclude from adding cleanup tests. Equivalent to --fixture-exclude-cleanup on the command line." } } + }, + "testPresetsFilterExcludeObject": { + "properties": { + "name": { + "type": "string", + "description": "An optional string specifying a regex for test names. Equivalent to passing --exclude-regex on the command line." + }, + "label": { + "type": "string", + "description": "An optional string specifying a regex for test labels. Equivalent to passing --label-exclude on the command line." + } } }, - "testPresetsItemsV6": { - "type": "array", - "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 6 and higher.", - "items": { - "type": "object", - "properties": { - "output": { - "type": "object", - "description": "An optional object specifying output options.", - "properties": { - "outputJUnitFile": { - "type": "string", - "description": "An optional string specifying a path to a JUnit file. Equivalent to passing --output-junit on the command line." - } - } + "testPresetsExecutionV11": { + "type": "object", + "description": "An optional object specifying options for test execution.", + "allOf": [ + { "$ref": "#/definitions/testPresetsExecutionObject" }, + { "$ref": "#/definitions/commentAsProperty" }, + { + "properties": { + "repeat": { "$ref": "#/definitions/testPresetsExecutionRepeatV10" }, + "jobs": { "$ref": "#/definitions/testPresetsExecutionJobsV11" } } } + ], + "unevaluatedProperties": false + }, + "testPresetsExecutionV10": { + "type": "object", + "description": "An optional object specifying options for test execution.", + "allOf": [ + { "$ref": "#/definitions/testPresetsExecutionObject" }, + { "$ref": "#/definitions/commentAsProperty" }, + { + "properties": { + "repeat": { "$ref": "#/definitions/testPresetsExecutionRepeatV10" }, + "jobs": { "$ref": "#/definitions/testPresetsExecutionJobsV2" } + } + } + ], + "unevaluatedProperties": false + }, + "testPresetsExecutionV2": { + "type": "object", + "description": "An optional object specifying options for test execution.", + "allOf": [ + { "$ref": "#/definitions/testPresetsExecutionObject" }, + { + "properties": { + "repeat": { "$ref": "#/definitions/testPresetsExecutionRepeatV2" }, + "jobs": { "$ref": "#/definitions/testPresetsExecutionJobsV2" } + } + } + ], + "unevaluatedProperties": false + }, + "testPresetsExecutionObject": { + "properties": { + "stopOnFailure": { + "type": "boolean", + "description": "An optional boolean. If true, equivalent to passing --stop-on-failure on the command line." + }, + "enableFailover": { + "type": "boolean", + "description": "An optional boolean. If true, equivalent to passing -F on the command line." + }, + "resourceSpecFile": { + "type": "string", + "description": "An optional string. Equivalent to passing --resource-spec-file on the command line." + }, + "testLoad": { + "type": "integer", + "description": "An optional integer. Equivalent to passing --test-load on the command line." + }, + "showOnly": { + "type": "string", + "description": "An optional string. Equivalent to passing --show-only on the command line. Value must be \"human\" or \"json-v1\".", + "enum": [ + "human", "json-v1" + ] + }, + "interactiveDebugging": { + "type": "boolean", + "description": "An optional boolean. If true, equivalent to passing --interactive-debug-mode 1 on the command line. If false, equivalent to passing --interactive-debug-mode 0 on the command line." + }, + "scheduleRandom": { + "type": "boolean", + "description": "An optional boolean. If true, equivalent to passing --schedule-random on the command line." + }, + "timeout": { + "type": "integer", + "description": "An optional integer. Equivalent to passing --timeout on the command line." + }, + "noTestsAction": { + "type": "string", + "description": "An optional string specifying the behavior if no tests are found. Must be one of the following values: \"default\" (equivalent to not passing any value on the command line), \"error\" (equivalent to passing --no-tests=error on the command line), or \"ignore\" (equivalent to passing --no-tests-ignore on the command line).", + "enum": [ + "default", "error", "ignore" + ] + } } }, - "testPresetsItemsV5": { - "type": "array", - "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 5 and higher.", - "items": { - "type": "object", - "properties": { - "output": { - "type": "object", - "description": "An optional object specifying output options.", - "properties": { - "testOutputTruncation": { - "type": "string", - "description": "An optional string specifying the test output truncation mode. Equivalent to passing --test-output-truncation on the command line. Must be one of the following values: \"tail\", \"middle\", or \"head\".", - "enum": [ - "tail", "middle", "head" - ] - } - } + "testPresetsOutputJUnitFile": { + "type": "string", + "description": "An optional string specifying a path to a JUnit file. Equivalent to passing --output-junit on the command line." + }, + "testPresetsTestOutputTruncation": { + "type": "string", + "description": "An optional string specifying the test output truncation mode. Equivalent to passing --test-output-truncation on the command line. Must be one of the following values: \"tail\", \"middle\", or \"head\".", + "enum": [ + "tail", "middle", "head" + ] + }, + "testPresetsOutputV10": { + "type": "object", + "description": "An optional object specifying output options.", + "allOf": [ + { "$ref": "#/definitions/testPresetsOutputObject" }, + { + "properties": { + "outputJUnitFile": { "$ref": "#/definitions/testPresetsOutputJUnitFile" }, + "testOutputTruncation": { "$ref": "#/definitions/testPresetsTestOutputTruncation" }, + "$comment": { "$ref": "#/definitions/$comment" } } } + ], + "unevaluatedProperties": false + }, + "testPresetsOutputV6": { + "type": "object", + "description": "An optional object specifying output options.", + "allOf": [ + { "$ref": "#/definitions/testPresetsOutputObject" }, + { + "properties": { + "outputJUnitFile": { "$ref": "#/definitions/testPresetsOutputJUnitFile" }, + "testOutputTruncation": { "$ref": "#/definitions/testPresetsTestOutputTruncation" } + } + } + ], + "unevaluatedProperties": false + }, + "testPresetsOutputV5": { + "type": "object", + "description": "An optional object specifying output options.", + "allOf": [ + { "$ref": "#/definitions/testPresetsOutputObject" }, + { + "properties": { + "testOutputTruncation": { "$ref": "#/definitions/testPresetsTestOutputTruncation" } + } + } + ], + "unevaluatedProperties": false + }, + "testPresetsOutputV2": { + "type": "object", + "description": "An optional object specifying output options.", + "allOf": [ + { "$ref": "#/definitions/testPresetsOutputObject" } + ], + "unevaluatedProperties": false + }, + "testPresetsOutputObject": { + "properties": { + "shortProgress": { + "type": "boolean", + "description": "An optional boolean. If true, equivalent to passing --progress on the command line." + }, + "verbosity": { + "type": "string", + "description": "An optional string specifying verbosity level. Valid values are \"default\" (equivalent to passing no verbosity flags on the command line), \"verbose\" (equivalent to passing --verbose on the command line), and \"extra\" (equivalent to passing --extra-verbose on the command line).", + "enum": [ + "default", "verbose", "extra" + ] + }, + "debug": { + "type": "boolean", + "description": "An optional boolean. If true, equivalent to passing --debug on the command line." + }, + "outputOnFailure": { + "type": "boolean", + "description": "An optional boolean. If true, equivalent to passing --output-on-failure on the command line." + }, + "quiet": { + "type": "boolean", + "description": "An optional boolean. If true, equivalent to passing --quiet on the command line." + }, + "outputLogFile": { + "type": "string", + "description": "An optional string specifying a path to a log file. Equivalent to passing --output-log on the command line." + }, + "labelSummary": { + "type": "boolean", + "description": "An optional boolean. If false, equivalent to passing --no-label-summary on the command line." + }, + "subprojectSummary": { + "type": "boolean", + "description": "An optional boolean. If false, equivalent to passing --no-subproject-summary on the command line." + }, + "maxPassedTestOutputSize": { + "type": "integer", + "description": "An optional integer specifying the maximum output for passed tests in bytes. Equivalent to passing --test-output-size-passed on the command line." + }, + "maxFailedTestOutputSize": { + "type": "integer", + "description": "An optional integer specifying the maximum output for failed tests in bytes. Equivalent to passing --test-output-size-failed on the command line." + }, + "maxTestNameWidth": { + "type": "integer", + "description": "An optional integer specifying the maximum width of a test name to output. Equivalent to passing --max-width on the command line." + } } }, - "testPresetsItemsV3": { - "type": "array", - "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 3 and higher." + "testPresetsAdditionalPropertiesV11": { + "properties": { + "execution": { "$ref": "#/definitions/testPresetsExecutionV11" }, + "filter": { + "type": "object", + "description": "An optional object specifying how to filter the tests to run.", + "properties": { + "include": { "$ref": "#/definitions/testPresetsFilterIncludeV10" }, + "exclude": { "$ref": "#/definitions/testPresetsFilterExcludeV10" }, + "$comment": { "$ref": "#/definitions/$comment" } + } + }, + "output": { "$ref": "#/definitions/testPresetsOutputV6" }, + "condition": { "$ref": "#/definitions/topConditionV10" } + } + }, + "testPresetsAdditionalPropertiesV10": { + "properties": { + "execution": { "$ref": "#/definitions/testPresetsExecutionV10" }, + "filter": { + "type": "object", + "description": "An optional object specifying how to filter the tests to run.", + "properties": { + "include": { "$ref": "#/definitions/testPresetsFilterIncludeV10" }, + "exclude": { "$ref": "#/definitions/testPresetsFilterExcludeV10" }, + "$comment": { "$ref": "#/definitions/$comment" } + } + }, + "output": { "$ref": "#/definitions/testPresetsOutputV6" }, + "condition": { "$ref": "#/definitions/topConditionV10" } + } + }, + "testPresetsAdditionalPropertiesV6": { + "properties": { + "execution": { "$ref": "#/definitions/testPresetsExecutionV2" }, + "filter": { + "type": "object", + "description": "An optional object specifying how to filter the tests to run.", + "properties": { + "include": { "$ref": "#/definitions/testPresetsFilterIncludeV2" }, + "exclude": { "$ref": "#/definitions/testPresetsFilterExcludeV2" } + } + }, + "output": { "$ref": "#/definitions/testPresetsOutputV6" }, + "condition": { "$ref": "#/definitions/topConditionV3" } + } + }, + "testPresetsAdditionalPropertiesV5": { + "properties": { + "execution": { "$ref": "#/definitions/testPresetsExecutionV2" }, + "filter": { + "type": "object", + "description": "An optional object specifying how to filter the tests to run.", + "properties": { + "include": { "$ref": "#/definitions/testPresetsFilterIncludeV2" }, + "exclude": { "$ref": "#/definitions/testPresetsFilterExcludeV2" } + } + }, + "output": { "$ref": "#/definitions/testPresetsOutputV5" }, + "condition": { "$ref": "#/definitions/topConditionV3" } + } + }, + "testPresetsAdditionalPropertiesV3": { + "allOf": [ + { "$ref": "#/definitions/testPresetsAdditionalPropertiesV2" }, + { + "properties": { + "condition": { "$ref": "#/definitions/topConditionV3" } + } + } + ] + }, + "testPresetsAdditionalPropertiesV2": { + "properties": { + "execution": { "$ref": "#/definitions/testPresetsExecutionV2" }, + "filter": { + "type": "object", + "description": "An optional object specifying how to filter the tests to run.", + "properties": { + "include": { "$ref": "#/definitions/testPresetsFilterIncludeV2" }, + "exclude": { "$ref": "#/definitions/testPresetsFilterExcludeV2" } + } + }, + "output": { "$ref": "#/definitions/testPresetsOutputV2" } + } }, "testPresetsItemsV2": { - "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": { - "name": { - "type": "string", - "description": "A required string representing the machine-friendly name of the preset. This identifier is used in the --preset argument. There must not be two presets (configure, build, test, package, or workflow) in the union of CMakePresets.json and CMakeUserPresets.json in the same directory with the same name.", - "minLength": 1 - }, - "hidden": { - "type": "boolean", - "description": "An optional boolean specifying whether or not a preset should be hidden. If a preset is hidden, it cannot be used in the --preset argument and does not have to have a valid configurePreset, even from inheritance. Hidden presets are intended to be used as a base for other presets to inherit via the inherits field." - }, - "inherits": { - "anyOf": [ - { - "type": "string", - "description": "An optional string representing the name of the test preset to inherit from.", - "minLength": 1 - }, - { - "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 must not inherit from presets in CMakeUserPresets.json.", - "items": { - "type": "string", - "description": "An optional string representing the name of the preset to inherit from.", - "minLength": 1 - } - } - ] - }, - "configurePreset": { - "type": "string", - "description": "An optional string specifying the name of a configure preset to associate with this test preset. If configurePreset is not specified, it must be inherited from the inherits preset (unless this preset is hidden). The build tree directory is inferred from the configure preset.", - "minLength": 1 - }, - "vendor": { - "type": "object", - "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, it should follow the same conventions as the root-level vendor field. If vendors use their own per-preset vendor field, they should implement inheritance in a sensible manner when appropriate.", - "properties": {} - }, - "displayName": { - "type": "string", - "description": "An optional string with a human-friendly name of the preset." - }, - "description": { - "type": "string", - "description": "An optional string with a human-friendly description of the preset." - }, - "inheritConfigureEnvironment": { - "type": "boolean", - "description": "An optional boolean that defaults to true. If true, the environment variables from the associated configure preset are inherited after all inherited test preset environments, but before environment variables explicitly specified in this test preset." - }, - "environment": { - "type": "object", - "description": "An optional map of environment variables. The key is the variable name (which must not be an empty string). Each variable is set regardless of whether or not a value was given to it by the process's environment. This field supports macro expansion, and environment variables in this map may reference each other, and may be listed in any order, as long as such references do not cause a cycle (for example,if ENV_1 is $env{ENV_2}, ENV_2 may not be $env{ENV_1}.) Environment variables are inherited through the inherits field, and the preset's environment will be the union of its own environment and the environment from all its parents. If multiple presets in this union define the same variable, the standard rules of inherits are applied. Setting a variable to null causes it to not be set, even if a value was inherited from another preset.", - "properties": {}, - "additionalProperties": { + "allOf": [ + { "$ref": "#/definitions/commonPropertiesAll" }, + { "$ref": "#/definitions/configureBuildTestPackagePresetsEnvironmentProperty" }, + { + "properties": { + "hidden": { + "type": "boolean", + "description": "An optional boolean specifying whether or not a preset should be hidden. If a preset is hidden, it cannot be used in the --preset argument and does not have to have a valid configurePreset, even from inheritance. Hidden presets are intended to be used as a base for other presets to inherit via the inherits field." + }, + "inherits": { "anyOf": [ { - "type": "null", - "description": "Setting a variable to null causes it to not be set, even if a value was inherited from another preset." + "type": "string", + "description": "An optional string representing the name of the test preset to inherit from.", + "minLength": 1 }, { - "type": "string", - "description": "A string representing the value of the variable." + "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 must not inherit from presets in CMakeUserPresets.json.", + "items": { + "type": "string", + "description": "An optional string representing the name of the preset to inherit from.", + "minLength": 1 + } } ] }, - "propertyNames": { - "pattern": "^.+$" - } - }, - "configuration": { - "type": "string", - "description": "An optional string. Equivalent to passing --build-config on the command line." - }, - "overwriteConfigurationFile": { - "type": "array", - "description": "An optional array of configuration options to overwrite options specified in the CTest configuration file. Equivalent to passing ``--overwrite`` for each value in the array.", - "items": { + "configurePreset": { "type": "string", - "description": "An option written as a key-value pair in the form \"key=value\"." - } - }, - "output": { - "type": "object", - "description": "An optional object specifying output options.", - "properties": { - "shortProgress": { - "type": "boolean", - "description": "An optional boolean. If true, equivalent to passing --progress on the command line." - }, - "verbosity": { + "description": "An optional string specifying the name of a configure preset to associate with this test preset. If configurePreset is not specified, it must be inherited from the inherits preset (unless this preset is hidden). The build tree directory is inferred from the configure preset.", + "minLength": 1 + }, + "inheritConfigureEnvironment": { + "type": "boolean", + "description": "An optional boolean that defaults to true. If true, the environment variables from the associated configure preset are inherited after all inherited test preset environments, but before environment variables explicitly specified in this test preset." + }, + "configuration": { + "type": "string", + "description": "An optional string. Equivalent to passing --build-config on the command line." + }, + "overwriteConfigurationFile": { + "type": "array", + "description": "An optional array of configuration options to overwrite options specified in the CTest configuration file. Equivalent to passing ``--overwrite`` for each value in the array.", + "items": { "type": "string", - "description": "An optional string specifying verbosity level. Valid values are \"default\" (equivalent to passing no verbosity flags on the command line), \"verbose\" (equivalent to passing --verbose on the command line), and \"extra\" (equivalent to passing --extra-verbose on the command line).", - "enum": [ - "default", "verbose", "extra" - ] - }, - "debug": { - "type": "boolean", - "description": "An optional boolean. If true, equivalent to passing --debug on the command line." - }, - "outputOnFailure": { - "type": "boolean", - "description": "An optional boolean. If true, equivalent to passing --output-on-failure on the command line." - }, - "quiet": { - "type": "boolean", - "description": "An optional boolean. If true, equivalent to passing --quiet on the command line." - }, - "outputLogFile": { - "type": "string", - "description": "An optional string specifying a path to a log file. Equivalent to passing --output-log on the command line." - }, - "labelSummary": { - "type": "boolean", - "description": "An optional boolean. If false, equivalent to passing --no-label-summary on the command line." - }, - "subprojectSummary": { - "type": "boolean", - "description": "An optional boolean. If false, equivalent to passing --no-subproject-summary on the command line." - }, - "maxPassedTestOutputSize": { - "type": "integer", - "description": "An optional integer specifying the maximum output for passed tests in bytes. Equivalent to passing --test-output-size-passed on the command line." - }, - "maxFailedTestOutputSize": { - "type": "integer", - "description": "An optional integer specifying the maximum output for failed tests in bytes. Equivalent to passing --test-output-size-failed on the command line." - }, - "maxTestNameWidth": { - "type": "integer", - "description": "An optional integer specifying the maximum width of a test name to output. Equivalent to passing --max-width on the command line." - } - } - }, - "filter": { - "type": "object", - "description": "An optional object specifying how to filter the tests to run.", - "properties": { - "include": { - "type": "object", - "description": "An optional object specifying which tests to include.", - "properties": { - "name": { - "type": "string", - "description": "An optional string specifying a regex for test names. Equivalent to passing --tests-regex on the command line." - }, - "label": { - "type": "string", - "description": "An optional string specifying a regex for test labels. Equivalent to passing --label-regex on the command line." - }, - "useUnion": { - "type": "boolean", - "description": "An optional boolean. Equivalent to passing --union on the command line." - } - } - }, - "exclude": { - "type": "object", - "description": "An optional object specifying which tests to exclude.", - "properties": { - "name": { - "type": "string", - "description": "An optional string specifying a regex for test names. Equivalent to passing --exclude-regex on the command line." - }, - "label": { - "type": "string", - "description": "An optional string specifying a regex for test labels. Equivalent to passing --label-exclude on the command line." - }, - "fixtures": { - "type": "object", - "description": "An optional object specifying which fixtures to exclude from adding tests.", - "properties": { - "any": { - "type": "string", - "description": "An optional string specifying a regex for text fixtures to exclude from adding any tests. Equivalent to --fixture-exclude-any on the command line." - }, - "setup": { - "type": "string", - "description": "An optional string specifying a regex for text fixtures to exclude from adding setup tests. Equivalent to --fixture-exclude-setup on the command line." - }, - "cleanup": { - "type": "string", - "description": "An optional string specifying a regex for text fixtures to exclude from adding cleanup tests. Equivalent to --fixture-exclude-cleanup on the command line." - } - } - } - } - } - } - }, - "execution": { - "type": "object", - "description": "An optional object specifying options for test execution.", - "properties": { - "stopOnFailure": { - "type": "boolean", - "description": "An optional boolean. If true, equivalent to passing --stop-on-failure on the command line." - }, - "enableFailover": { - "type": "boolean", - "description": "An optional boolean. If true, equivalent to passing -F on the command line." - }, - "jobs": { - "type": "integer", - "description": "An optional integer. Equivalent to passing --parallel on the command line." - }, - "resourceSpecFile": { - "type": "string", - "description": "An optional string. Equivalent to passing --resource-spec-file on the command line." - }, - "testLoad": { - "type": "integer", - "description": "An optional integer. Equivalent to passing --test-load on the command line." - }, - "showOnly": { - "type": "string", - "description": "An optional string. Equivalent to passing --show-only on the command line. Value must be \"human\" or \"json-v1\".", - "enum": [ - "human", "json-v1" - ] - }, - "repeat": { - "type": "object", - "description": "An optional object specifying how to repeat tests. Equivalent to passing --repeat on the command line.", - "properties": { - "mode": { - "type": "string", - "description": "A required string. Must be one of the following values: \"until-fail\", \"until-pass\", or \"after-timeout\".", - "enum": [ - "until-fail", "until-pass", "after-timeout" - ] - }, - "count": { - "type": "integer", - "description": "A required integer." - } - } - }, - "interactiveDebugging": { - "type": "boolean", - "description": "An optional boolean. If true, equivalent to passing --interactive-debug-mode 1 on the command line. If false, equivalent to passing --interactive-debug-mode 0 on the command line." - }, - "scheduleRandom": { - "type": "boolean", - "description": "An optional boolean. If true, equivalent to passing --schedule-random on the command line." - }, - "timeout": { - "type": "integer", - "description": "An optional integer. Equivalent to passing --timeout on the command line." - }, - "noTestsAction": { - "type": "string", - "description": "An optional string specifying the behavior if no tests are found. Must be one of the following values: \"default\" (equivalent to not passing any value on the command line), \"error\" (equivalent to passing --no-tests=error on the command line), or \"ignore\" (equivalent to passing --no-tests-ignore on the command line).", - "enum": [ - "default", "error", "ignore" - ] + "description": "An option written as a key-value pair in the form \"key=value\"." } } } } + ], + "required": [ + "name" + ] + }, + "testPresetsV11": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 11 and higher.", + "items": { + "type": "object", + "description": "A test preset object", + "allOf": [ + { "$ref": "#/definitions/testPresetsItemsV2" }, + { "$ref": "#/definitions/testPresetsAdditionalPropertiesV11" }, + { "$ref": "#/definitions/commentAsProperty" } + ], + "unevaluatedProperties": false } }, "testPresetsV10": { "type": "array", "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 10 and higher.", - "allOf": [ - { "$ref": "#/definitions/testPresetsItemsV10" }, - { "$ref": "#/definitions/testPresetsItemsV6" }, - { "$ref": "#/definitions/testPresetsItemsV5" }, - { "$ref": "#/definitions/testPresetsItemsV3" }, - { "$ref": "#/definitions/testPresetsItemsV2" } - ], "items": { "type": "object", - "properties": { - "$comment": {}, - "name": {}, - "hidden": {}, - "inherits": {}, - "configurePreset": {}, - "vendor": {}, - "displayName": {}, - "description": {}, - "inheritConfigureEnvironment": {}, - "environment": {}, - "configuration": {}, - "overwriteConfigurationFile": {}, - "output": { - "type": "object", - "properties": { - "shortProgress": {}, - "verbosity": {}, - "debug": {}, - "outputOnFailure": {}, - "quiet": {}, - "outputLogFile": {}, - "outputJUnitFile": {}, - "labelSummary": {}, - "subprojectSummary": {}, - "maxPassedTestOutputSize": {}, - "maxFailedTestOutputSize": {}, - "maxTestNameWidth": {}, - "testOutputTruncation": {} - }, - "additionalProperties": false - }, - "filter": { - "type": "object", - "properties": { - "$comment": {}, - "include": { - "type": "object", - "properties": { - "$comment": {}, - "name": {}, - "label": {}, - "useUnion": {}, - "index": { "$ref": "#/definitions/testPresetsFilterIncludeIndexV10" } - }, - "additionalProperties": false - }, - "exclude": { - "type": "object", - "properties": { - "$comment": {}, - "name": {}, - "label": {}, - "fixtures": { - "type": "object", - "properties": { - "$comment": {}, - "any": {}, - "setup": {}, - "cleanup": {} - }, - "additionalProperties": false - } - }, - "additionalProperties": false - } - }, - "additionalProperties": false - }, - "execution": { - "type": "object", - "properties": { - "$comment": {}, - "stopOnFailure": {}, - "enableFailover": {}, - "jobs": {}, - "resourceSpecFile": {}, - "testLoad": {}, - "showOnly": {}, - "repeat": { - "type": "object", - "properties": { - "$comment": {}, - "mode": {}, - "count": {} - }, - "required": [ - "mode", "count" - ], - "additionalProperties": false - }, - "interactiveDebugging": {}, - "scheduleRandom": {}, - "timeout": {}, - "noTestsAction": {} - }, - "additionalProperties": false - }, - "condition": { "$ref": "#/definitions/topConditionV10" } - }, - "required": [ - "name" + "description": "A test preset object", + "allOf": [ + { "$ref": "#/definitions/testPresetsItemsV2" }, + { "$ref": "#/definitions/testPresetsAdditionalPropertiesV10" }, + { "$ref": "#/definitions/commentAsProperty" } ], - "additionalProperties": false + "unevaluatedProperties": false } }, "testPresetsV6": { "type": "array", "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 6 and higher.", - "allOf": [ - { "$ref": "#/definitions/testPresetsItemsV6" }, - { "$ref": "#/definitions/testPresetsItemsV5" }, - { "$ref": "#/definitions/testPresetsItemsV3" }, - { "$ref": "#/definitions/testPresetsItemsV2" } - ], "items": { "type": "object", - "properties": { - "name": {}, - "hidden": {}, - "inherits": {}, - "configurePreset": {}, - "vendor": {}, - "displayName": {}, - "description": {}, - "inheritConfigureEnvironment": {}, - "environment": {}, - "configuration": {}, - "overwriteConfigurationFile": {}, - "output": { - "type": "object", - "properties": { - "shortProgress": {}, - "verbosity": {}, - "debug": {}, - "outputOnFailure": {}, - "quiet": {}, - "outputLogFile": {}, - "outputJUnitFile": {}, - "labelSummary": {}, - "subprojectSummary": {}, - "maxPassedTestOutputSize": {}, - "maxFailedTestOutputSize": {}, - "maxTestNameWidth": {}, - "testOutputTruncation": {} - }, - "additionalProperties": false - }, - "filter": { - "type": "object", - "properties": { - "include": { - "type": "object", - "properties": { - "name": {}, - "label": {}, - "useUnion": {}, - "index": { "$ref": "#/definitions/testPresetsFilterIncludeIndexV2" } - }, - "additionalProperties": false - }, - "exclude": { - "type": "object", - "properties": { - "name": {}, - "label": {}, - "fixtures": { - "type": "object", - "properties": { - "any": {}, - "setup": {}, - "cleanup": {} - }, - "additionalProperties": false - } - }, - "additionalProperties": false - } - }, - "additionalProperties": false - }, - "execution": { - "type": "object", - "properties": { - "stopOnFailure": {}, - "enableFailover": {}, - "jobs": {}, - "resourceSpecFile": {}, - "testLoad": {}, - "showOnly": {}, - "repeat": { - "type": "object", - "properties": { - "mode": {}, - "count": {} - }, - "required": [ - "mode", "count" - ], - "additionalProperties": false - }, - "interactiveDebugging": {}, - "scheduleRandom": {}, - "timeout": {}, - "noTestsAction": {} - }, - "additionalProperties": false - }, - "condition": { "$ref": "#/definitions/topConditionV3" } - }, - "required": [ - "name" + "description": "A test preset object", + "allOf": [ + { "$ref": "#/definitions/testPresetsItemsV2" }, + { "$ref": "#/definitions/testPresetsAdditionalPropertiesV6" } ], - "additionalProperties": false + "unevaluatedProperties": false } }, "testPresetsV5": { "type": "array", "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 5 and higher.", - "allOf": [ - { "$ref": "#/definitions/testPresetsItemsV5" }, - { "$ref": "#/definitions/testPresetsItemsV3" }, - { "$ref": "#/definitions/testPresetsItemsV2" } - ], "items": { "type": "object", - "properties": { - "name": {}, - "hidden": {}, - "inherits": {}, - "configurePreset": {}, - "vendor": {}, - "displayName": {}, - "description": {}, - "inheritConfigureEnvironment": {}, - "environment": {}, - "configuration": {}, - "overwriteConfigurationFile": {}, - "output": { - "type": "object", - "properties": { - "shortProgress": {}, - "verbosity": {}, - "debug": {}, - "outputOnFailure": {}, - "quiet": {}, - "outputLogFile": {}, - "labelSummary": {}, - "subprojectSummary": {}, - "maxPassedTestOutputSize": {}, - "maxFailedTestOutputSize": {}, - "maxTestNameWidth": {}, - "testOutputTruncation": {} - }, - "additionalProperties": false - }, - "filter": { - "type": "object", - "properties": { - "include": { - "type": "object", - "properties": { - "name": {}, - "label": {}, - "useUnion": {}, - "index": { "$ref": "#/definitions/testPresetsFilterIncludeIndexV2" } - }, - "additionalProperties": false - }, - "exclude": { - "type": "object", - "properties": { - "name": {}, - "label": {}, - "fixtures": { - "type": "object", - "properties": { - "any": {}, - "setup": {}, - "cleanup": {} - }, - "additionalProperties": false - } - }, - "additionalProperties": false - } - }, - "additionalProperties": false - }, - "execution": { - "type": "object", - "properties": { - "stopOnFailure": {}, - "enableFailover": {}, - "jobs": {}, - "resourceSpecFile": {}, - "testLoad": {}, - "showOnly": {}, - "repeat": { - "type": "object", - "properties": { - "mode": {}, - "count": {} - }, - "required": [ - "mode", "count" - ], - "additionalProperties": false - }, - "interactiveDebugging": {}, - "scheduleRandom": {}, - "timeout": {}, - "noTestsAction": {} - }, - "additionalProperties": false - }, - "condition": { "$ref": "#/definitions/topConditionV3" } - }, - "required": [ - "name" + "description": "A test preset object", + "allOf": [ + { "$ref": "#/definitions/testPresetsItemsV2" }, + { "$ref": "#/definitions/testPresetsAdditionalPropertiesV5" } ], - "additionalProperties": false + "unevaluatedProperties": false } }, "testPresetsV3": { "type": "array", "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 3 and higher.", - "allOf": [ - { "$ref": "#/definitions/testPresetsItemsV3" }, - { "$ref": "#/definitions/testPresetsItemsV2" } - ], "items": { "type": "object", - "properties": { - "name": {}, - "hidden": {}, - "inherits": {}, - "configurePreset": {}, - "vendor": {}, - "displayName": {}, - "description": {}, - "inheritConfigureEnvironment": {}, - "environment": {}, - "configuration": {}, - "overwriteConfigurationFile": {}, - "output": { - "type": "object", - "properties": { - "shortProgress": {}, - "verbosity": {}, - "debug": {}, - "outputOnFailure": {}, - "quiet": {}, - "outputLogFile": {}, - "labelSummary": {}, - "subprojectSummary": {}, - "maxPassedTestOutputSize": {}, - "maxFailedTestOutputSize": {}, - "maxTestNameWidth": {} - }, - "additionalProperties": false - }, - "filter": { - "type": "object", - "properties": { - "include": { - "type": "object", - "properties": { - "name": {}, - "label": {}, - "useUnion": {}, - "index": { "$ref": "#/definitions/testPresetsFilterIncludeIndexV2" } - }, - "additionalProperties": false - }, - "exclude": { - "type": "object", - "properties": { - "name": {}, - "label": {}, - "fixtures": { - "type": "object", - "properties": { - "any": {}, - "setup": {}, - "cleanup": {} - }, - "additionalProperties": false - } - }, - "additionalProperties": false - } - }, - "additionalProperties": false - }, - "execution": { - "type": "object", - "properties": { - "stopOnFailure": {}, - "enableFailover": {}, - "jobs": {}, - "resourceSpecFile": {}, - "testLoad": {}, - "showOnly": {}, - "repeat": { - "type": "object", - "properties": { - "mode": {}, - "count": {} - }, - "required": [ - "mode", "count" - ], - "additionalProperties": false - }, - "interactiveDebugging": {}, - "scheduleRandom": {}, - "timeout": {}, - "noTestsAction": {} - }, - "additionalProperties": false - }, - "condition": { "$ref": "#/definitions/topConditionV3" } - }, - "required": [ - "name" + "description": "A test preset object", + "allOf": [ + { "$ref": "#/definitions/testPresetsItemsV2" }, + { "$ref": "#/definitions/testPresetsAdditionalPropertiesV3" } ], - "additionalProperties": false + "unevaluatedProperties": 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": { - "type": "object", - "properties": { - "shortProgress": {}, - "verbosity": {}, - "debug": {}, - "outputOnFailure": {}, - "quiet": {}, - "outputLogFile": {}, - "labelSummary": {}, - "subprojectSummary": {}, - "maxPassedTestOutputSize": {}, - "maxFailedTestOutputSize": {}, - "maxTestNameWidth": {} - }, - "additionalProperties": false - }, - "filter": { - "type": "object", - "properties": { - "include": { - "type": "object", - "properties": { - "name": {}, - "label": {}, - "useUnion": {}, - "index": { "$ref": "#/definitions/testPresetsFilterIncludeIndexV2" } - }, - "additionalProperties": false - }, - "exclude": { - "type": "object", - "properties": { - "name": {}, - "label": {}, - "fixtures": { - "type": "object", - "properties": { - "any": {}, - "setup": {}, - "cleanup": {} - }, - "additionalProperties": false - } - }, - "additionalProperties": false - } - }, - "additionalProperties": false - }, - "execution": { - "type": "object", - "properties": { - "stopOnFailure": {}, - "enableFailover": {}, - "jobs": {}, - "resourceSpecFile": {}, - "testLoad": {}, - "showOnly": {}, - "repeat": { - "type": "object", - "properties": { - "mode": {}, - "count": {} - }, - "required": [ - "mode", "count" - ], - "additionalProperties": false - }, - "interactiveDebugging": {}, - "scheduleRandom": {}, - "timeout": {}, - "noTestsAction": {} - }, - "additionalProperties": false - } - }, - "required": [ - "name" + "description": "A test preset object", + "allOf": [ + { "$ref": "#/definitions/testPresetsItemsV2" }, + { "$ref": "#/definitions/testPresetsAdditionalPropertiesV2" } ], - "additionalProperties": false + "unevaluatedProperties": false } }, - "packagePresetsItemsV10": { - "type": "array", - "description": "An optional array of package preset objects. Used to specify arguments to cpack. Available in version 10 and higher.", - "items": { - "type": "object", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" }, - "output": { - "type": "object", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" } - } - } + "packagePresetsOutputV10": { + "type": "object", + "description": "An optional object specifying output options.", + "allOf": [ + { "$ref": "#/definitions/packagePresetsOutputObject" }, + { "$ref": "#/definitions/commentAsProperty" } + ], + "unevaluatedProperties": false + }, + "packagePresetsOutputV6": { + "type": "object", + "description": "An optional object specifying output options.", + "allOf": [ + { "$ref": "#/definitions/packagePresetsOutputObject" } + ], + "unevaluatedProperties": false + }, + "packagePresetsOutputObject": { + "properties": { + "debug": { + "type": "boolean", + "description": "An optional boolean specifying whether or not to print debug information. A value of true is equivalent to passing --debug on the command line." + }, + "verbose": { + "type": "boolean", + "description": "An optional boolean specifying whether or not to print verbosely. A value of true is equivalent to passing --verbose on the command line." } } }, + "packagePresetsAdditionalPropertiesV10": { + "properties": { + "output": { "$ref": "#/definitions/packagePresetsOutputV10" }, + "condition": { "$ref": "#/definitions/topConditionV10" }, + "$comment": { "$ref": "#/definitions/$comment" } + } + }, + "packagePresetsAdditionalPropertiesV6": { + "properties": { + "output": { "$ref": "#/definitions/packagePresetsOutputV6" }, + "condition": { "$ref": "#/definitions/topConditionV3" } + } + }, "packagePresetsItemsV6": { - "type": "array", - "description": "An optional array of package preset objects. Used to specify arguments to cpack. Available in version 6 and higher.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "A required string representing the machine-friendly name of the preset. This identifier is used in the --preset argument. There must not be two presets (configure, build, test, package, or workflow) in the union of CMakePresets.json and CMakeUserPresets.json in the same directory with the same name.", - "minLength": 1 - }, - "hidden": { - "type": "boolean", - "description": "An optional boolean specifying whether or not a preset should be hidden. If a preset is hidden, it cannot be used in the --preset argument and does not have to have a valid configurePreset, even from inheritance. Hidden presets are intended to be used as a base for other presets to inherit via the inherits field." - }, - "inherits": { - "anyOf": [ - { - "type": "string", - "description": "An optional string representing the name of the package preset to inherit from.", - "minLength": 1 - }, - { - "type": "array", - "description": "An optional array of strings representing the names of package 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.", - "minLength": 1 - } - } - ] - }, - "configurePreset": { - "type": "string", - "description": "An optional string specifying the name of a configure preset to associate with this package preset. If configurePreset is not specified, it must be inherited from the inherits preset (unless this preset is hidden). The build tree directory is inferred from the configure preset.", - "minLength": 1 - }, - "vendor": { - "type": "object", - "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, it should follow the same conventions as the root-level vendor field. If vendors use their own per-preset vendor field, they should implement inheritance in a sensible manner when appropriate.", - "properties": {} - }, - "displayName": { - "type": "string", - "description": "An optional string with a human-friendly name of the preset." - }, - "description": { - "type": "string", - "description": "An optional string with a human-friendly description of the preset." - }, - "inheritConfigureEnvironment": { - "type": "boolean", - "description": "An optional boolean that defaults to true. If true, the environment variables from the associated configure preset are inherited after all inherited package preset environments, but before environment variables explicitly specified in this package preset." - }, - "environment": { - "type": "object", - "description": "An optional map of environment variables. The key is the variable name (which must not be an empty string). Each variable is set regardless of whether or not a value was given to it by the process's environment. This field supports macro expansion, and environment variables in this map may reference each other, and may be listed in any order, as long as such references do not cause a cycle (for example,if ENV_1 is $env{ENV_2}, ENV_2 may not be $env{ENV_1}.) Environment variables are inherited through the inherits field, and the preset's environment will be the union of its own environment and the environment from all its parents. If multiple presets in this union define the same variable, the standard rules of inherits are applied. Setting a variable to null causes it to not be set, even if a value was inherited from another preset.", - "properties": {}, - "additionalProperties": { + "allOf": [ + { "$ref": "#/definitions/commonPropertiesAll" }, + { "$ref": "#/definitions/configureBuildTestPackagePresetsEnvironmentProperty" }, + { + "properties": { + "hidden": { + "type": "boolean", + "description": "An optional boolean specifying whether or not a preset should be hidden. If a preset is hidden, it cannot be used in the --preset argument and does not have to have a valid configurePreset, even from inheritance. Hidden presets are intended to be used as a base for other presets to inherit via the inherits field." + }, + "inherits": { "anyOf": [ { - "type": "null", - "description": "Setting a variable to null causes it to not be set, even if a value was inherited from another preset." + "type": "string", + "description": "An optional string representing the name of the package preset to inherit from.", + "minLength": 1 }, { - "type": "string", - "description": "A string representing the value of the variable." + "type": "array", + "description": "An optional array of strings representing the names of package 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.", + "minLength": 1 + } } ] }, - "propertyNames": { - "pattern": "^.+$" - } - }, - "generators": { - "type": "array", - "description": "An optional list of strings representing generators for CPack to use.", - "items": { + "configurePreset": { "type": "string", - "description": "An optional string representing the name of the CPack generator to use." - } - }, - "configurations": { - "type": "array", - "description": "An optional list of strings representing build configurations for CPack to package.", - "items": { - "type": "string", - "description": "An optional string representing the name of the configuration to use." - } - }, - "variables": { - "type": "object", - "description": "An optional map of variables to pass to CPack, equivalent to -D arguments. Each key is the name of a variable, and the value is the string to assign to that variable.", - "items": { - "type": "string", - "description": "An optional string representing the value of the variable." - } - }, - "configFile": { - "type": "string", - "description": "An optional string representing the config file for CPack to use." - }, - "output": { - "type": "object", - "description": "An optional object specifying output options.", - "properties": { - "debug": { - "type": "boolean", - "description": "An optional boolean specifying whether or not to print debug information. A value of true is equivalent to passing --debug on the command line." - }, - "verbose": { - "type": "boolean", - "description": "An optional boolean specifying whether or not to print verbosely. A value of true is equivalent to passing --verbose on the command line." + "description": "An optional string specifying the name of a configure preset to associate with this package preset. If configurePreset is not specified, it must be inherited from the inherits preset (unless this preset is hidden). The build tree directory is inferred from the configure preset.", + "minLength": 1 + }, + "inheritConfigureEnvironment": { + "type": "boolean", + "description": "An optional boolean that defaults to true. If true, the environment variables from the associated configure preset are inherited after all inherited package preset environments, but before environment variables explicitly specified in this package preset." + }, + "generators": { + "type": "array", + "description": "An optional list of strings representing generators for CPack to use.", + "items": { + "type": "string", + "description": "An optional string representing the name of the CPack generator to use." } + }, + "configurations": { + "type": "array", + "description": "An optional list of strings representing build configurations for CPack to package.", + "items": { + "type": "string", + "description": "An optional string representing the name of the configuration to use." + } + }, + "variables": { + "type": "object", + "description": "An optional map of variables to pass to CPack, equivalent to -D arguments. Each key is the name of a variable, and the value is the string to assign to that variable.", + "items": { + "type": "string", + "description": "An optional string representing the value of the variable." + } + }, + "configFile": { + "type": "string", + "description": "An optional string representing the config file for CPack to use." + }, + "packageName": { + "type": "string", + "description": "An optional string representing the package name." + }, + "packageVersion": { + "type": "string", + "description": "An optional string representing the package version." + }, + "packageDirectory": { + "type": "string", + "description": "An optional string representing the directory in which to place the package." + }, + "vendorName": { + "type": "string", + "description": "An optional string representing the vendor name." } - }, - "packageName": { - "type": "string", - "description": "An optional string representing the package name." - }, - "packageVersion": { - "type": "string", - "description": "An optional string representing the package version." - }, - "packageDirectory": { - "type": "string", - "description": "An optional string representing the directory in which to place the package." - }, - "vendorName": { - "type": "string", - "description": "An optional string representing the vendor name." } } - } + ], + "required": [ + "name" + ] }, "packagePresetsV10": { "type": "array", "description": "An optional array of package preset objects. Used to specify arguments to cpack. Available in version 10 and higher.", - "allOf": [ - { "$ref": "#/definitions/packagePresetsItemsV10" }, - { "$ref": "#/definitions/packagePresetsItemsV6" } - ], "items": { "type": "object", - "properties": { - "$comment": {}, - "name": {}, - "hidden": {}, - "inherits": {}, - "configurePreset": {}, - "vendor": {}, - "displayName": {}, - "description": {}, - "inheritConfigureEnvironment": {}, - "environment": {}, - "condition": { "$ref": "#/definitions/topConditionV10" }, - "generators": {}, - "configurations": {}, - "variables": {}, - "configFile": {}, - "output": { - "type": "object", - "properties": { - "$comment": {}, - "debug": {}, - "verbose": {} - }, - "additionalProperties": false - }, - "packageName": {}, - "packageVersion": {}, - "packageDirectory": {}, - "vendorName": {} - }, - "required": [ - "name" + "description": "An optional package preset object.", + "allOf": [ + { "$ref": "#/definitions/packagePresetsItemsV6" }, + { "$ref": "#/definitions/packagePresetsAdditionalPropertiesV10" } ], - "additionalProperties": false + "unevaluatedProperties": false } }, "packagePresetsV6": { "type": "array", "description": "An optional array of package preset objects. Used to specify arguments to cpack. Available in version 6 and higher.", - "allOf": [ - { "$ref": "#/definitions/packagePresetsItemsV6" } - ], "items": { "type": "object", - "properties": { - "name": {}, - "hidden": {}, - "inherits": {}, - "configurePreset": {}, - "vendor": {}, - "displayName": {}, - "description": {}, - "inheritConfigureEnvironment": {}, - "environment": {}, - "condition": { "$ref": "#/definitions/topConditionV3" }, - "generators": {}, - "configurations": {}, - "variables": {}, - "configFile": {}, - "output": { - "type": "object", - "properties": { - "debug": {}, - "verbose": {} - }, - "additionalProperties": false - }, - "packageName": {}, - "packageVersion": {}, - "packageDirectory": {}, - "vendorName": {} - }, - "required": [ - "name" + "description": "An optional package preset object.", + "allOf": [ + { "$ref": "#/definitions/packagePresetsItemsV6" }, + { "$ref": "#/definitions/packagePresetsAdditionalPropertiesV6" } ], - "additionalProperties": false + "unevaluatedProperties": false } }, - "workflowPresetsItemsV10": { + "workflowPresetsStepsV10": { "type": "array", - "description": "An optional array of workflow preset objects. Used to execute configure, build, test, and package presets in order. Available in version 10 and higher.", + "description": "A required array of objects describing the steps of the workflow. The first step must be a configure preset, and all subsequent steps must be non-configure presets whose configurePreset field matches the starting configure preset.", "items": { "type": "object", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" }, - "steps": { - "type": "array", - "items": { - "type": "object", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" } - } - } - } - } + "allOf": [ + { "$ref": "#/definitions/workflowPresetsStepsObject" }, + { "$ref": "#/definitions/commentAsProperty" } + ], + "unevaluatedProperties": false } }, - "workflowPresetsItemsV6": { + "workflowPresetsStepsV6": { "type": "array", - "description": "An optional array of workflow preset objects. Used to execute configure, build, test, and package presets in order. Available in version 6 and higher.", + "description": "A required array of objects describing the steps of the workflow. The first step must be a configure preset, and all subsequent steps must be non-configure presets whose configurePreset field matches the starting configure preset.", "items": { "type": "object", - "properties": { - "name": { - "type": "string", - "description": "A required string representing the machine-friendly name of the preset. This identifier is used in the --preset argument. There must not be two presets (configure, build, test, package, or workflow) in the union of CMakePresets.json and CMakeUserPresets.json in the same directory with the same name.", - "minLength": 1 - }, - "vendor": { - "type": "object", - "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, it should follow the same conventions as the root-level vendor field.", - "properties": {} - }, - "displayName": { - "type": "string", - "description": "An optional string with a human-friendly name of the preset." - }, - "description": { - "type": "string", - "description": "An optional string with a human-friendly description of the preset." - }, - "steps": { - "type": "array", - "description": "A required array of objects describing the steps of the workflow. The first step must be a configure preset, and all subsequent steps must be non-configure presets whose configurePreset field matches the starting configure preset.", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "A required string. The first step must be configure. Subsequent steps must be either build, test, or package.", - "enum": ["configure", "build", "test", "package"] - }, - "name": { - "type": "string", - "description": "A required string representing the name of the configure, build, test, or package preset to run as this workflow step.", - "minLength": 1 - } - } - } - } + "allOf": [ + { "$ref": "#/definitions/workflowPresetsStepsObject" } + ], + "unevaluatedProperties": false + } + }, + "workflowPresetsStepsObject": { + "properties": { + "type": { + "type": "string", + "description": "A required string. The first step must be configure. Subsequent steps must be either build, test, or package.", + "enum": ["configure", "build", "test", "package"] + }, + "name": { + "type": "string", + "description": "A required string representing the name of the configure, build, test, or package preset to run as this workflow step.", + "minLength": 1 } + }, + "required": [ + "type", + "name" + ] + }, + "workflowPresetsAdditionalPropertiesV10": { + "properties": { + "steps": { "$ref": "#/definitions/workflowPresetsStepsV10" }, + "$comment": { "$ref": "#/definitions/$comment" } + } + }, + "workflowPresetsAdditionalPropertiesV6": { + "properties": { + "steps": { "$ref": "#/definitions/workflowPresetsStepsV6" } } }, "workflowPresetsV10": { "type": "array", "description": "An optional array of workflow preset objects. Used to execute configure, build, test, and package presets in order. Available in version 10 and higher.", - "allOf": [ - { "$ref": "#/definitions/workflowPresetsItemsV10" }, - { "$ref": "#/definitions/workflowPresetsItemsV6" } - ], "items": { "type": "object", - "properties": { - "$comment": {}, - "name": {}, - "vendor": {}, - "displayName": {}, - "description": {}, - "steps": { - "type": "array", - "items": { - "type": "object", - "properties": { - "$comment": {}, - "type": {}, - "name": {} - }, - "required": [ - "type", - "name" - ], - "additionalProperties": false - } - } - }, + "description": "An optional workflow preset object", + "allOf": [ + { "$ref": "#/definitions/commonPropertiesAll" }, + { "$ref": "#/definitions/workflowPresetsAdditionalPropertiesV10" } + ], "required": [ "name", "steps" ], - "additionalProperties": false + "unevaluatedProperties": false } }, "workflowPresetsV6": { "type": "array", "description": "An optional array of workflow preset objects. Used to execute configure, build, test, and package presets in order. Available in version 6 and higher.", - "allOf": [ - { "$ref": "#/definitions/workflowPresetsItemsV6" } - ], "items": { "type": "object", - "properties": { - "name": {}, - "vendor": {}, - "displayName": {}, - "description": {}, - "steps": { - "type": "array", - "items": { - "type": "object", - "properties": { - "type": {}, - "name": {} - }, - "required": [ - "type", - "name" - ], - "additionalProperties": false - } - } - }, + "description": "An optional workflow preset object", + "allOf": [ + { "$ref": "#/definitions/commonPropertiesAll" }, + { "$ref": "#/definitions/workflowPresetsAdditionalPropertiesV6" } + ], "required": [ "name", "steps" ], - "additionalProperties": false + "unevaluatedProperties": false } }, "conditionAsBooleanV3": { "type": "boolean", "description": "A boolean which provides a constant value for the condition's evaluation." }, - "conditionAsObjectConstV10": { - "type": "object", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" } - } - }, "conditionAsObjectConstV3": { "type": "object", "properties": { @@ -2651,13 +1874,11 @@ "type": "boolean", "description": "A required boolean which provides a constant value for the condition's evaluation." } - } - }, - "conditionAsObjectEqualsV10": { - "type": "object", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" } - } + }, + "required": [ + "type", + "value" + ] }, "conditionAsObjectEqualsV3": { "type": "object", @@ -2675,13 +1896,12 @@ "type": "string", "description": "Second string to compare. This field supports macro expansion." } - } - }, - "conditionAsObjectInListV10": { - "type": "object", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" } - } + }, + "required": [ + "type", + "lhs", + "rhs" + ] }, "conditionAsObjectInListV3": { "type": "object", @@ -2702,13 +1922,12 @@ "type": "string" } } - } - }, - "conditionAsObjectMatchesV10": { - "type": "object", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" } - } + }, + "required": [ + "type", + "string", + "list" + ] }, "conditionAsObjectMatchesV3": { "type": "object", @@ -2726,13 +1945,12 @@ "type": "string", "description": "A required regular expression to search for. This field supports macro expansion." } - } - }, - "conditionAsObjectAggregationV10": { - "type": "object", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" } - } + }, + "required": [ + "type", + "string", + "regex" + ] }, "conditionAsObjectAggregationV3": { "type": "object", @@ -2744,15 +1962,18 @@ }, "conditions": { "type": "array", - "description": "A required array of condition objects. These conditions use short-circuit evaluation." + "description": "A required array of condition objects. These conditions use short-circuit evaluation.", + "items": { + "properties": { + "condition": { "$ref": "#/definitions/conditionV3" } + } + } } - } - }, - "conditionAsObjectNotV10": { - "type": "object", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" } - } + }, + "required": [ + "type", + "conditions" + ] }, "conditionAsObjectNotV3": { "type": "object", @@ -2761,8 +1982,13 @@ "type": "string", "description": "A required string specifying the type of the condition.", "const": "not" - } - } + }, + "condition": { "$ref": "#/definitions/conditionV3" } + }, + "required": [ + "type", + "condition" + ] }, "conditionV10": { "anyOf": [ @@ -2770,113 +1996,63 @@ { "type": "object", "allOf": [ - { "$ref": "#/definitions/conditionAsObjectConstV10" }, - { "$ref": "#/definitions/conditionAsObjectConstV3" } + { "$ref": "#/definitions/conditionAsObjectConstV3" }, + { "$ref": "#/definitions/commentAsProperty" } ], - "properties": { - "$comment": {}, - "type": {}, - "value": {} - }, - "required": [ - "type", - "value" - ], - "additionalProperties": false + "unevaluatedProperties": false }, { "type": "object", "allOf": [ - { "$ref": "#/definitions/conditionAsObjectEqualsV10" }, - { "$ref": "#/definitions/conditionAsObjectEqualsV3" } + { "$ref": "#/definitions/conditionAsObjectEqualsV3" }, + { "$ref": "#/definitions/commentAsProperty" } ], - "properties": { - "$comment": {}, - "type": {}, - "lhs": {}, - "rhs": {} - }, - "required": [ - "type", - "lhs", - "rhs" - ], - "additionalProperties": false + "unevaluatedProperties": false }, { "type": "object", "allOf": [ - { "$ref": "#/definitions/conditionAsObjectInListV10" }, - { "$ref": "#/definitions/conditionAsObjectInListV3" } + { "$ref": "#/definitions/conditionAsObjectInListV3" }, + { "$ref": "#/definitions/commentAsProperty" } ], - "properties": { - "$comment": {}, - "type": {}, - "string": {}, - "list": {} - }, - "required": [ - "type", - "string", - "list" - ], - "additionalProperties": false + "unevaluatedProperties": false }, { "type": "object", "allOf": [ - { "$ref": "#/definitions/conditionAsObjectMatchesV10" }, - { "$ref": "#/definitions/conditionAsObjectMatchesV3" } + { "$ref": "#/definitions/conditionAsObjectMatchesV3" }, + { "$ref": "#/definitions/commentAsProperty" } ], - "properties": { - "$comment": {}, - "type": {}, - "string": {}, - "regex": {} - }, - "required": [ - "type", - "string", - "regex" - ], - "additionalProperties": false + "unevaluatedProperties": false }, { "type": "object", "allOf": [ - { "$ref": "#/definitions/conditionAsObjectAggregationV10" }, - { "$ref": "#/definitions/conditionAsObjectAggregationV3" } - ], - "properties": { - "$comment": {}, - "type": {}, - "conditions": { - "type": "array", - "items": { "$ref": "#/definitions/conditionV10" } + { "$ref": "#/definitions/conditionAsObjectAggregationV3" }, + { "$ref": "#/definitions/commentAsProperty" }, + { + "properties": { + "conditions": { + "type": "array", + "items": { "$ref": "#/definitions/conditionV10" } + } + } } - }, - "required": [ - "type", - "conditions" ], - "additionalProperties": false + "unevaluatedProperties": false }, { "type": "object", "allOf": [ - { "$ref": "#/definitions/conditionAsObjectNotV10" }, - { "$ref": "#/definitions/conditionAsObjectNotV3" } + { "$ref": "#/definitions/conditionAsObjectNotV3" }, + { "$ref": "#/definitions/commentAsProperty" }, + { + "properties": { + "condition": { "$ref": "#/definitions/conditionV10" } + } + } ], - "properties": { - "$comment": {}, - "type": {}, - "condition": { "$ref": "#/definitions/conditionV10" } - }, - "required": [ - "type", - "condition" - ], - "additionalProperties": false + "unevaluatedProperties": false } ] }, @@ -2888,99 +2064,42 @@ "allOf": [ { "$ref": "#/definitions/conditionAsObjectConstV3" } ], - "properties": { - "type": {}, - "value": {} - }, - "required": [ - "type", - "value" - ], - "additionalProperties": false + "unevaluatedProperties": false }, { "type": "object", "allOf": [ { "$ref": "#/definitions/conditionAsObjectEqualsV3" } ], - "properties": { - "type": {}, - "lhs": {}, - "rhs": {} - }, - "required": [ - "type", - "lhs", - "rhs" - ], - "additionalProperties": false + "unevaluatedProperties": false }, { "type": "object", "allOf": [ { "$ref": "#/definitions/conditionAsObjectInListV3" } ], - "properties": { - "type": {}, - "string": {}, - "list": {} - }, - "required": [ - "type", - "string", - "list" - ], - "additionalProperties": false + "unevaluatedProperties": false }, { "type": "object", "allOf": [ { "$ref": "#/definitions/conditionAsObjectMatchesV3" } ], - "properties": { - "type": {}, - "string": {}, - "regex": {} - }, - "required": [ - "type", - "string", - "regex" - ], - "additionalProperties": false + "unevaluatedProperties": false }, { "type": "object", "allOf": [ { "$ref": "#/definitions/conditionAsObjectAggregationV3" } ], - "properties": { - "type": {}, - "conditions": { - "type": "array", - "items": { "$ref": "#/definitions/conditionV3" } - } - }, - "required": [ - "type", - "conditions" - ], - "additionalProperties": false + "unevaluatedProperties": false }, { "type": "object", "allOf": [ { "$ref": "#/definitions/conditionAsObjectNotV3" } ], - "properties": { - "type": {}, - "condition": { "$ref": "#/definitions/conditionV3" } - }, - "required": [ - "type", - "condition" - ], - "additionalProperties": false + "unevaluatedProperties": false } ] },
diff --git a/Help/policy/CMP0183.rst b/Help/policy/CMP0183.rst index 6804c3b..f2d6601 100644 --- a/Help/policy/CMP0183.rst +++ b/Help/policy/CMP0183.rst
@@ -5,7 +5,7 @@ :command:`add_feature_info` supports full :ref:`Condition Syntax`. -The ``<enabled>`` parameter accepts a :ref:`semicolon-separated list <CMake +The ``<condition>`` parameter accepts a :ref:`semicolon-separated list <CMake Language Lists>` of conditions. CMake 3.31 and lower evaluate each ``condition`` as ``if(${condition})``, which does not properly handle conditions with nested paren groups. CMake 4.0 and above instead prefer
diff --git a/Help/policy/CMP0198.rst b/Help/policy/CMP0198.rst new file mode 100644 index 0000000..4e32e1c --- /dev/null +++ b/Help/policy/CMP0198.rst
@@ -0,0 +1,23 @@ +CMP0198 +------- + +.. versionadded:: 4.2 + +:variable:`CMAKE_PARENT_LIST_FILE` is not defined in ``CMakeLists.txt``. + +CMake 4.1 and below defined ``CMAKE_PARENT_LIST_FILE`` when processing +a ``CMakeLists.txt`` even though there is no parent file. CMake 4.2 +and above prefer to not define ``CMAKE_PARENT_LIST_FILE``. This policy +provides compatibility for projects that accidentally relied on the +old behavior. + +The ``OLD`` behavior for this policy is to set +:variable:`CMAKE_PARENT_LIST_FILE` to :variable:`CMAKE_CURRENT_LIST_FILE` +when processing a ``CMakeLists.txt``. The ``NEW`` behavior for this policy +is to not set :variable:`CMAKE_PARENT_LIST_FILE`. + +.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 4.2 +.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn +.. include:: include/STANDARD_ADVICE.rst + +.. include:: include/DEPRECATED.rst
diff --git a/Help/policy/CMP0199.rst b/Help/policy/CMP0199.rst new file mode 100644 index 0000000..b102845 --- /dev/null +++ b/Help/policy/CMP0199.rst
@@ -0,0 +1,97 @@ +CMP0199 +------- + +.. versionadded:: 4.2 + +:genex:`$<CONFIG:cfgs>` does not match mapped configurations that are not +selected. + +Historically, when a :genex:`$<CONFIG:cfgs>` generator expression appeared in +the properties of an imported target, it would match (that is, evaluate to +``1``) if any of the ``cfgs`` matched *any* of the following: + +1. The selected configuration of the imported target being consumed. + +2. The configuration of the consuming target. + +3. *Any* of the configurations in the :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` + of the imported target being consumed + (where ``<CONFIG>`` is the configuration of the consuming target), + *whether or not such configurations are valid for the imported target*. + +This can result in expressions which are intended to be mutually exclusive +being concurrently evaluated. This can be especially problematic if the value +of a compile definition is intended to be determined by the configuration, as +this lack of exclusivity could result in redefinition. + +CMake 4.2 and above prefer to consider *only* the configuration of the +consuming target and (when applicable) the selected configuration of the +imported target; that is, (2) and (1) in the above list. Unfortunately, +because users rely on both of these, this policy is not able to fully prevent +multiple unique ``$<CONFIG:cfg>`` expressions from matching concurrently. + +This policy provides compatibility with projects that rely on the historical +behavior. The ``OLD`` behavior for this policy is to retain the historic +behavior as described above. The ``NEW`` behavior is to consider only the +configurations of the consuming and consumed targets. + +.. note:: + + This policy only applies to generator expressions being evaluated as part of + the usage requirements of imported targets which are not imported from |CPS| + packages. + + For non-imported targets, both the historic and ongoing behavior is to + consider only the configuration of the consuming target. (The selected + configuration of a non-imported target is always the active build + configuration, which is necessarily the same as the consuming target's + configuration.) + + For targets imported from |CPS| packages, **only** the configuration of the + consumed imported target is considered, regardless of the policy setting. + +.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 4.2 +.. |WARNS_OR_DOES_NOT_WARN| replace:: warns +.. include:: include/STANDARD_ADVICE.rst + +.. include:: include/DEPRECATED.rst + +Examples +^^^^^^^^ + +Consider the following imported libraries: + +.. code-block:: cmake + + add_library(test1 INTERFACE IMPORTED) + set_target_properties(test1 PROPERTIES + IMPORTED_CONFIGURATIONS "DEBUG" + INTERFACE_COMPILE_DEFINITIONS + "$<$<CONFIG:debug>:DEBUG>;$<$<CONFIG:release>:RELEASE>" + ) + + add_library(test2 INTERFACE IMPORTED) + set_target_properties(test2 PROPERTIES + IMPORTED_CONFIGURATIONS "TEST" + INTERFACE_COMPILE_DEFINITIONS + "$<$<CONFIG:debug>:DEBUG>;$<$<CONFIG:example>:EXAMPLE>;$<$<CONFIG:test>:TEST>" + MAP_IMPORTED_CONFIG_RELEASE "DEBUG;EXAMPLE;TEST" + ) + +Assume that the consuming project is built in the ``Release`` configuration. +A consumer of ``test1`` will see both ``DEBUG`` and ``RELEASE`` defined, +regardless of the policy setting; ``$<CONFIG:debug>`` evaluates to ``1`` +because the selected configuration of ``test1`` is ``DEBUG``, and +``$<CONFIG:release>`` evaluates to ``1`` because the consumer's configuration +is ``Release`` (keeping in mind that configuration matching is +case-insensitive). + +Under the ``OLD`` policy, a consumer of ``test2`` would see all of ``DEBUG``, +``EXAMPLE`` and ``TEST`` defined; ``$<CONFIG:debug>``, ``$<CONFIG:example>`` +and ``$<CONFIG:test>`` all evaluate to ``1`` because all of these +configurations appear in ``MAP_IMPORTED_CONFIG_RELEASE``. + +Under the ``NEW`` policy, a consumer of ``test2`` will see only ``TEST`` +defined. + +.. |CPS| replace:: Common Package Specification
diff --git a/Help/policy/CMP0200.rst b/Help/policy/CMP0200.rst new file mode 100644 index 0000000..cf2dbde --- /dev/null +++ b/Help/policy/CMP0200.rst
@@ -0,0 +1,117 @@ +CMP0200 +------- + +.. versionadded:: 4.2 + +Location and configuration selection for imported targets is more consistent. + +The way CMake historically selected the configuration to use for imported +targets prioritized selection based on location properties for a candidate +configuration and only considered :prop_tgt:`IMPORTED_CONFIGURATIONS` as a +fallback. This could result in incorrect configuration selection especially +for ``INTERFACE`` libraries. + +CMake 4.2 and above consider :prop_tgt:`IMPORTED_CONFIGURATIONS` to be a +definitive list of available configurations, regardless of whether a +configuration specific location is provided for the library. Additionally, +CMake will respect non-configuration-specific locations when a configuration +specific location is not specified. + +This policy provides compatibility with projects that rely on the historical +behavior. The policy setting applies to targets and is recorded at the point +an imported target is created. Accordingly, imported packages may override the +policy set by the consumer for targets they create. In particular, targets +imported from |CPS| packages always use the ``NEW`` behavior. + +The ``OLD`` behavior for this policy is to retain the historic behavior. +The ``NEW`` behavior prioritizes selection based on the advertised list of +available configurations. Both behaviors are described in detail below. + +.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 4.2 +.. |WARNS_OR_DOES_NOT_WARN| replace:: warns +.. include:: include/STANDARD_ADVICE.rst + +.. include:: include/DEPRECATED.rst + +Mapped configuration selection +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` (where ``<CONFIG>`` is the +configuration of the consuming target) is set on an imported target, CMake +would historically select from that list the first configuration which provides +a configuration-specific location. If no such configuration exists, CMake +would selects the consuming target's configuration, if the imported target is +an ``INTERFACE`` library. Otherwise, CMake considers the target as not having +a suitable configuration. + +For ``INTERFACE`` libraries which do not provide a location, this results in +CMake always selecting the consuming target's configuration and effectively +ignoring :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>`. This behavior is not +consistent with configuration selection for imported targets which provide a +location. + +Under the ``NEW`` behavior, CMake selects the first configuration from the +mapping which appears in :prop_tgt:`IMPORTED_CONFIGURATIONS`. If +:prop_tgt:`IMPORTED_CONFIGURATIONS` is not set, CMake selects the first +configuration from the mapping which is "usable". For non-``INTERFACE`` +libraries, "usable" means that a location (either configuration-specific or +configuration-agnostic) is available. ``INTERFACE`` libraries are always +considered "usable". + +If no match is found, CMake considers the target as not having a suitable +configuration. + +Non-mapped configuration selection +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is *not* set, CMake would +historically select the first configuration which provides a location out of +the following: + +- The consuming target's configuration, or + +- The empty configuration, or + +- The list of configurations in :prop_tgt:`IMPORTED_CONFIGURATIONS`. + +As an implementation artifact, this results in CMake selecting the *last* +configuration in :prop_tgt:`IMPORTED_CONFIGURATIONS` for ``INTERFACE`` +libraries which do not provide a location. Again, this behavior is not +consistent with configuration selection for imported targets which provide a +location. + +Under the ``NEW`` behavior, if :prop_tgt:`IMPORTED_CONFIGURATIONS` is set, +CMake will select the consuming target's configuration if present therein, +otherwise CMake will select the first imported configuration. If +:prop_tgt:`IMPORTED_CONFIGURATIONS` is *not* set, CMake will select the +consuming target's configuration if it is "usable" (as defined in the previous +section); otherwise, CMake considers the target as not having a suitable +configuration. + +Examples +^^^^^^^^ + +Consider the following imported library: + +.. code-block:: cmake + + add_library(test INTERFACE IMPORTED) + set_target_properties(test PROPERTIES + IMPORTED_CONFIGURATIONS "RELEASE;DEBUG" + INTERFACE_COMPILE_DEFINITIONS "$<$<CONFIG:debug>:DEBUG>" + ) + +Under the ``OLD`` policy, CMake will select the ``DEBUG`` configuration of +``test`` (and thus define the symbol ``DEBUG``) for any target linking to +``test``, because CMake does not consider any configuration "valid", and, as +an implementation artifact, the last configuration considered is accepted. + +Under the ``NEW`` policy, the ``RELEASE`` configuration will be selected +if the consuming project is built in any configuration other than ``Debug`` +(keeping in mind that configuration matching is case-insensitive). This is +because ``DEBUG`` will be preferred if the consumer's configuration is also +``DEBUG``, but ``RELEASE`` will be preferred otherwise because it appears +first in :prop_tgt:`IMPORTED_CONFIGURATIONS`, and its appearance therein makes +it a "valid" configuration for an ``INTERFACE`` library. + +.. |CPS| replace:: Common Package Specification
diff --git a/Help/policy/CMP0201.rst b/Help/policy/CMP0201.rst new file mode 100644 index 0000000..d2c5f21 --- /dev/null +++ b/Help/policy/CMP0201.rst
@@ -0,0 +1,30 @@ +CMP0201 +------- + +.. versionadded:: 4.2 + +``Python::NumPy`` does not depend on ``Python::Development.Module``. + +:module:`FindPython3`, :module:`FindPython2`, and :module:`FindPython` provide +``Python{3,2,}::NumPy`` and ``Python{3,2,}::Development.Module`` targets when +the corresponding components are requested. + +In CMake 4.1 and below, requesting the ``NumPy`` component implies the +``Development.Module`` component, and the provided ``Python{3,2,}::NumPy`` +targets depend on the provided ``Python{3,2,}::Development.Module`` targets. +This dependency is not necessary. +In CMake 4.2 and above, requesting the ``NumPy`` component does not imply the +``Development.Module`` component, and the provided ``Python{3,2,}::NumPy`` +targets do not depend on the provided ``Python{3,2,}::Development.Module`` +targets. +This policy provides compatibility with projects that expect the legacy +behavior. + +The ``OLD`` behavior for this policy makes ``NumPy`` depend on +``Development.Module``. The ``NEW`` behavior for this policy does not. + +.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 4.2 +.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn +.. include:: include/STANDARD_ADVICE.rst + +.. include:: include/DEPRECATED.rst
diff --git a/Help/policy/CMP0202.rst b/Help/policy/CMP0202.rst new file mode 100644 index 0000000..98c8b01 --- /dev/null +++ b/Help/policy/CMP0202.rst
@@ -0,0 +1,30 @@ +CMP0202 +------- + +.. versionadded:: 4.2 + +PDB file names always include their target's per-config POSTFIX. + +Program database files (``.pdb``) are always named with their target's +:prop_tgt:`DEBUG_POSTFIX` or :prop_tgt:`<CONFIG>_POSTFIX` target property +value. + +If the :prop_tgt:`PDB_NAME` target property is defined, CMake 4.1 and below +exclude the target's per-config postfix from the program data base file name. +Otherwise, the per-config postfix is included. This is inconsistent. +CMake 4.2 and above prefer to always name the program database file with the +per-config postfix regardless how the name is computed, i.e., using +:prop_tgt:`OUTPUT_NAME`, or :prop_tgt:`PDB_NAME`, or neither. This policy +provides compatibility with projects that have not been updated to account +for the new behavior. + +The ``OLD`` behavior for this policy does not use the per-config postfix in +``.pdb`` file names if the :prop_tgt:`PDB_NAME` target property is defined. +The ``NEW`` behavior always uses the per-config postfix in ``.pdb`` file +names. + +.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 4.2 +.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn +.. include:: include/STANDARD_ADVICE.rst + +.. include:: include/DEPRECATED.rst
diff --git a/Help/policy/CMP0203.rst b/Help/policy/CMP0203.rst new file mode 100644 index 0000000..c6927eb --- /dev/null +++ b/Help/policy/CMP0203.rst
@@ -0,0 +1,28 @@ +CMP0203 +------- + +.. versionadded:: 4.2 + +``_WINDLL`` is defined for shared libraries targeting the MSVC ABI. + +In CMake 4.1 and below, :ref:`Visual Studio Generators` compile sources in +shared libraries with ``_WINDLL`` defined due to behavior of Visual Studio +itself. The preprocessor definition is not modeled by CMake and is therefore +not added by other generators, such as :generator:`Ninja`. + +CMake 4.2 and above, when targeting the MSVC ABI, prefer to compile sources +in shared libraries with ``_WINDLL`` defined by all generators. +This policy provides compatibility with projects that have not been updated +to be aware of the definition. Its setting is recorded by each target as +it is created, and affects compilation of sources in that target. + +The ``OLD`` behavior for this policy does not model the ``_WINDLL`` +preprocessor definition in CMake itself. The ``NEW`` behavior for this +policy adds the ``_WINDLL`` preprocessor definition to sources in shared +libraries when targeting the MSVC ABI. + +.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 4.2 +.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn +.. include:: include/STANDARD_ADVICE.rst + +.. include:: include/DEPRECATED.rst
diff --git a/Help/policy/CMP0204.rst b/Help/policy/CMP0204.rst new file mode 100644 index 0000000..d22263a --- /dev/null +++ b/Help/policy/CMP0204.rst
@@ -0,0 +1,29 @@ +CMP0204 +------- + +.. versionadded:: 4.2 + +A character set is always defined when targeting the MSVC ABI. + +In CMake 4.1 and below, :ref:`Visual Studio Generators` compile sources in with +``_MBCS``, ``_UNICODE`` or ``_SBCS`` defined due to behavior of Visual Studio +itself. The preprocessor definition is not modeled by CMake and is therefore +not added by other generators, such as :generator:`Ninja`. + +CMake 4.2 and above, when targeting the MSVC ABI, prefer to compile sources +with ``_MBCS`` defined by all generators unless another charset preprocessor +definition is found (``_UNICODE`` or ``_SBCS``). +This policy provides compatibility with projects that have not been updated +to be aware of the definition. Its setting is recorded by each target as +it is created, and affects compilation of sources in that target. + +The ``OLD`` behavior for this policy does not model the ``_MBCS`` +preprocessor definition in CMake itself. The ``NEW`` behavior for this +policy adds the ``_MBCS`` preprocessor definition to sources +as a default encoding when targeting the MSVC ABI. + +.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 4.2 +.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn +.. include:: include/STANDARD_ADVICE.rst + +.. include:: include/DEPRECATED.rst
diff --git a/Help/policy/CMP0205.rst b/Help/policy/CMP0205.rst new file mode 100644 index 0000000..b08ef4a --- /dev/null +++ b/Help/policy/CMP0205.rst
@@ -0,0 +1,23 @@ +CMP0205 +------- + +.. versionadded:: 4.3 + +:command:`file(CREATE_LINK)` with ``COPY_ON_ERROR`` copies directory content. + +The :command:`file(CREATE_LINK)` command's ``COPY_ON_ERROR`` option copies +the source file to the destination as a fallback if linking it fails. +If the source is a directory, CMake 4.2 and below create the destination +directory but do not copy its contents. CMake 4.3 and above prefer to +copy the directory contents too. This policy provides compatibility with +projects that have not been updated to expect the contents to be copied. + +The ``OLD`` behavior for this policy is to create the destination directory +without copying contents. The ``NEW`` behavior for this policy to create +the destination directory and copy contents from the source directory. + +.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 4.3 +.. |WARNS_OR_DOES_NOT_WARN| replace:: warns +.. include:: include/STANDARD_ADVICE.rst + +.. include:: include/DEPRECATED.rst
diff --git a/Help/policy/CMP0206.rst b/Help/policy/CMP0206.rst new file mode 100644 index 0000000..f6ed03d --- /dev/null +++ b/Help/policy/CMP0206.rst
@@ -0,0 +1,30 @@ +CMP0206 +------- + +.. versionadded:: 4.3 + +The :cpack_gen:`CPack Archive Generator` defaults to UID 0 and GID 0. + +In CMake 4.2 and below, the :cpack_gen:`CPack Archive Generator` always used +the current user's UID/GID in archive entries. CMake 4.3 added the +:variable:`CPACK_ARCHIVE_UID` and :variable:`CPACK_ARCHIVE_GID` variables +to control them. If either is set, the default for the other is ``0``. +If neither is set, CMake 4.3 and above prefer to default both UID and GID +to ``0`` so that unpacking by ``root`` produces paths owned by ``root``. +This policy provides compatibility with projects that have not been updated +to expect the new behavior. + +The ``OLD`` behavior for this policy is to produce archive entries with +the current user's UID/GID by default. +The ``NEW`` behavior for this policy is to produce archive entries with +the UID/GID set to 0/0 by default. + +.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 4.3 +.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn +.. include:: include/STANDARD_ADVICE.rst + +See documentation of the +:variable:`CMAKE_POLICY_WARNING_CMP0206 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. + +.. include:: include/DEPRECATED.rst
diff --git a/Help/policy/CMP0207.rst b/Help/policy/CMP0207.rst new file mode 100644 index 0000000..b544bd2 --- /dev/null +++ b/Help/policy/CMP0207.rst
@@ -0,0 +1,26 @@ +CMP0207 +------- + +.. versionadded:: 4.3 + +:command:`file(GET_RUNTIME_DEPENDENCIES)` normalizes paths before matching. + +The :command:`file(GET_RUNTIME_DEPENDENCIES)` and +:command:`install(RUNTIME_DEPENDENCY_SET)` commands support filtering +resolved dependencies using regular expressions matching their paths. +In CMake 4.2 and below, callers were responsible for matching both forward +and backward slashes as path separators on Windows, e.g., via ``[\/]``. +CMake 4.3 and above prefer to normalize paths to use forward slashes before +matching. This policy provides compaitiblity for projects that may have +been relying on matching backslashes only. + +The ``OLD`` behavior for this policy matches filters against paths that +may contain any combination of forward and backward slashes on Windows. +The ``NEW`` behavior for this policy to convert all paths to forward +slashes before matching filters. + +.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 4.3 +.. |WARNS_OR_DOES_NOT_WARN| replace:: warns +.. include:: include/STANDARD_ADVICE.rst + +.. include:: include/DEPRECATED.rst
diff --git a/Help/policy/CMP0208.rst b/Help/policy/CMP0208.rst new file mode 100644 index 0000000..ae91daf --- /dev/null +++ b/Help/policy/CMP0208.rst
@@ -0,0 +1,30 @@ +CMP0208 +------- + +.. versionadded:: 4.3 + +:command:`export(EXPORT)` does not allow empty arguments. + +In CMake 4.2 and below, the :command:`export(EXPORT)` command silently +accepted ``NAMESPACE``, ``FILE`` or ``CXX_MODULES_DIRECTORY`` arguments with +empty or missing values. + +CMake 4.3 and above issue a diagnostic if any of these keywords are present +without an associated value, or of the value given to ``FILE`` or +``CXX_MODULES_DIRECTORY`` is empty. (``NAMESPACE`` is allowed to have an empty +value, but an empty value must be quoted.) A diagnostic is also issued +immediately if the value of ``EXPORT`` is missing or empty. (Previously, this +would result in an error at generate-time because no export set whose name is +empty can exist.) + +This policy provides compatibility with projects which may have relied on the +previous lack of enforcement. The ``OLD`` behavior for this policy permits +these keywords to be present without an accompanying value, or to be given an +empty value. The ``NEW`` behavior requires that a value be given, and that +the value (except for ``NAMESPACE``) is non-empty. + +.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 4.3 +.. |WARNS_OR_DOES_NOT_WARN| replace:: warns +.. include:: include/STANDARD_ADVICE.rst + +.. include:: include/DEPRECATED.rst
diff --git a/Help/policy/CMP0209.rst b/Help/policy/CMP0209.rst new file mode 100644 index 0000000..f8fa22e --- /dev/null +++ b/Help/policy/CMP0209.rst
@@ -0,0 +1,27 @@ +CMP0209 +------- + +.. versionadded:: 4.3 + +Verify interface header sets checks executables without exports. + +When :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` is set to true on an executable +target, CMake 4.2 and below would only perform those checks if the target's +:prop_tgt:`ENABLE_EXPORTS` property was true. The reasoning behind this +exclusion was that no other target could consume the headers of an executable +target if that executable target didn't export symbols. Since then, other +use cases have emerged for verifying header file sets where exporting symbols +is no longer a requirement. Therefore, CMake 4.3 and above prefer to verify +interface file sets of executable targets regardless of whether they export +symbols or not. + +The ``OLD`` behavior of this policy only verifies interface file sets of an +executable target if its :prop_tgt:`ENABLE_EXPORTS` property is set to true. +The ``NEW`` behavior always verifies interface file sets of an executable +target when :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` is set to true. + +.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 4.3 +.. |WARNS_OR_DOES_NOT_WARN| replace:: warns +.. include:: include/STANDARD_ADVICE.rst + +.. include:: include/DEPRECATED.rst
diff --git a/Help/policy/CMP0210.rst b/Help/policy/CMP0210.rst new file mode 100644 index 0000000..f615604 --- /dev/null +++ b/Help/policy/CMP0210.rst
@@ -0,0 +1,30 @@ +CMP0210 +------- + +.. versionadded:: 4.3 + +:variable:`CMAKE_<LANG>_LINK_FLAGS` adds link flags to all target types. + +In CMake 4.2 and below, :variable:`CMAKE_<LANG>_LINK_FLAGS` held flags +relevant to target creation and applied when linking executables only. It was +undocumented and originally intended for internal use only, but still +available for projects and users to set in order to control linking behavior. + +CMake 4.3 and above repurpose this variable to add per-language link flags for +all target types that link (executables, shared libraries, and module +libraries). + +This policy provides compatibility with projects that relied on this variable +and have not been updated to be aware of the change. + +The ``OLD`` behavior for this policy is to apply +:variable:`CMAKE_<LANG>_LINK_FLAGS` to invocations of the compiler which drive +linking for executables only. The ``NEW`` behavior is to apply the flags to +all target types. + +.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 4.3 +.. |WARNS_OR_DOES_NOT_WARN| replace:: + warns when :variable:`CMAKE_<LANG>_LINK_FLAGS` is set +.. include:: include/STANDARD_ADVICE.rst + +.. include:: include/DEPRECATED.rst
diff --git a/Help/policy/include/DEPRECATED.rst b/Help/policy/include/DEPRECATED.rst index f66de55..4cec1bb 100644 --- a/Help/policy/include/DEPRECATED.rst +++ b/Help/policy/include/DEPRECATED.rst
@@ -1,4 +1,4 @@ .. note:: The ``OLD`` behavior of a policy is - :manual:`deprecated by definition <cmake-policies(7)>` + :ref:`deprecated by definition <cmake-policies-intro>` and may be removed in a future version of CMake.
diff --git a/Help/prop_dir/ADDITIONAL_CLEAN_FILES.rst b/Help/prop_dir/ADDITIONAL_CLEAN_FILES.rst index 6097d14..8bb5f01 100644 --- a/Help/prop_dir/ADDITIONAL_CLEAN_FILES.rst +++ b/Help/prop_dir/ADDITIONAL_CLEAN_FILES.rst
@@ -3,11 +3,11 @@ .. versionadded:: 3.15 -A :ref:`;-list <CMake Language Lists>` of files or directories that will be -removed as a part of the global ``clean`` target. It is useful for -specifying generated files or directories that are used by multiple targets -or by CMake itself, or that are generated in ways which cannot be captured as -outputs or byproducts of custom commands. +A :ref:`semicolon-separated list <CMake Language Lists>` of files or +directories that will be removed as a part of the global ``clean`` target. +It is useful for specifying generated files or directories that are used by +multiple targets or by CMake itself, or that are generated in ways which cannot +be captured as outputs or byproducts of custom commands. If an additional clean file is specific to a single target only, then the :prop_tgt:`ADDITIONAL_CLEAN_FILES` target property would usually be a better
diff --git a/Help/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.rst b/Help/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.rst index a19cc4e..12b50d6 100644 --- a/Help/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.rst +++ b/Help/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.rst
@@ -7,8 +7,8 @@ Additional files to remove during the clean stage. -A :ref:`;-list <CMake Language Lists>` of files that will be removed as a -part of the ``make clean`` target. +A :ref:`semicolon-separated list <CMake Language Lists>` of files that will be +removed as a part of the ``make clean`` target. Arguments to ``ADDITIONAL_MAKE_CLEAN_FILES`` may use :manual:`generator expressions <cmake-generator-expressions(7)>`.
diff --git a/Help/prop_gbl/INSTALL_PARALLEL.rst b/Help/prop_gbl/INSTALL_PARALLEL.rst index 936b1ef..5c5c78a 100644 --- a/Help/prop_gbl/INSTALL_PARALLEL.rst +++ b/Help/prop_gbl/INSTALL_PARALLEL.rst
@@ -23,5 +23,5 @@ Calls to :command:`install(CODE)` or :command:`install(SCRIPT)` might depend on actions performed by an earlier :command:`install` command in a different directory such as files installed or variable settings. If the project has -such order-dependent installation logic, parallel installation should be +such order-dependent installation logic, parallel installation should not be enabled, in order to prevent possible race conditions.
diff --git a/Help/prop_gbl/JOB_POOLS.rst b/Help/prop_gbl/JOB_POOLS.rst index 5dfe6de..7d39d8b 100644 --- a/Help/prop_gbl/JOB_POOLS.rst +++ b/Help/prop_gbl/JOB_POOLS.rst
@@ -14,15 +14,21 @@ set_property(GLOBAL PROPERTY JOB_POOLS two_jobs=2 ten_jobs=10) -Defined pools could be used globally by setting -:variable:`CMAKE_JOB_POOL_COMPILE` and :variable:`CMAKE_JOB_POOL_LINK` -or per target by setting the target properties -:prop_tgt:`JOB_POOL_COMPILE` and :prop_tgt:`JOB_POOL_LINK`. -:command:`Custom commands <add_custom_command>` and -:command:`custom targets <add_custom_target>` can specify pools using the -option ``JOB_POOL``. -Using a pool that is not defined by ``JOB_POOLS`` causes -an error by ninja at build time. +Defined pools can be used at different levels: + +* Globally, by setting :variable:`CMAKE_JOB_POOL_COMPILE` and + :variable:`CMAKE_JOB_POOL_LINK`. +* Per target, by setting the target properties :prop_tgt:`JOB_POOL_COMPILE` + and :prop_tgt:`JOB_POOL_LINK`. +* :command:`Custom commands <add_custom_command>` and + :command:`custom targets <add_custom_target>` can specify pools using the + option ``JOB_POOL``. +* Per-source, by setting the source file property :prop_sf:`JOB_POOL_COMPILE`, + in case some specific source files require to override their global or + target assigned pool. + +Using a pool that is not defined by ``JOB_POOLS`` causes an error by ninja +at build time. If not set, this property uses the value of the :variable:`CMAKE_JOB_POOLS` variable.
diff --git a/Help/prop_sf/INSTALL_OBJECT_NAME.rst b/Help/prop_sf/INSTALL_OBJECT_NAME.rst new file mode 100644 index 0000000..34d1b6a --- /dev/null +++ b/Help/prop_sf/INSTALL_OBJECT_NAME.rst
@@ -0,0 +1,26 @@ +INSTALL_OBJECT_NAME +------------------- + +.. versionadded:: 4.2 + +Set the installed object name (without the object extension) of the source +file. An empty string value disables custom object naming. The value must be a +relative path, and may not include special directory components (e.g., +``..``). + +Note that the object name might not be used as-is in some +:prop_tgt:`INSTALL_OBJECT_NAME_STRATEGY` strategies. It may be changed as +the strategy requires to fulfill its goals. + +This property supports +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +.. note:: + No collision resistance within a target is performed by CMake. When using + this property, collisions must be avoided in the project code. CMake has a + number of source files it generates that also create object files that may + collide with a given custom name. These include: + + * Generated PCH source files (``cmake_pch``) + * Generated Unity compilation files (``unity_...``) + * Qt autogen sources (``moc_compilations.cpp``)
diff --git a/Help/prop_sf/JOB_POOL_COMPILE.rst b/Help/prop_sf/JOB_POOL_COMPILE.rst new file mode 100644 index 0000000..79409da --- /dev/null +++ b/Help/prop_sf/JOB_POOL_COMPILE.rst
@@ -0,0 +1,21 @@ +JOB_POOL_COMPILE +---------------- + +.. versionadded:: 4.2 + +Ninja only: Pool used for compiling. + +The number of parallel compile processes could be limited by defining +pools with the global :prop_gbl:`JOB_POOLS` +property and then specifying here the pool name. + +This allows to override the :prop_tgt:`JOB_POOL_COMPILE` +value for specific source files within a same target. + +For instance: + +.. code-block:: cmake + + set_property(SOURCE main.cc PROPERTY JOB_POOL_COMPILE two_jobs) + +This property is undefined by default.
diff --git a/Help/prop_sf/LABELS.rst b/Help/prop_sf/LABELS.rst index d0d2a0a..a2e18c8 100644 --- a/Help/prop_sf/LABELS.rst +++ b/Help/prop_sf/LABELS.rst
@@ -4,5 +4,5 @@ Specify a list of text labels associated with a source file. This property has meaning only when the source file is listed in a -target whose ``LABELS`` property is also set. No other semantics are +target whose :prop_tgt:`LABELS` property is also set. No other semantics are currently specified.
diff --git a/Help/prop_sf/OBJECT_NAME.rst b/Help/prop_sf/OBJECT_NAME.rst new file mode 100644 index 0000000..173e5ba --- /dev/null +++ b/Help/prop_sf/OBJECT_NAME.rst
@@ -0,0 +1,34 @@ +OBJECT_NAME +----------- + +.. versionadded:: 4.2 + +Set the object name (without the object extension) of the source file. An +empty string value disables custom object naming. The value must be a relative +path, and may not include special directory components (e.g., ``..``). + +Note that the object name might not be used as-is in +:variable:`CMAKE_INTERMEDIATE_DIR_STRATEGY` and +:prop_tgt:`INSTALL_OBJECT_NAME_STRATEGY` strategies. It may be changed as +the strategy requires to fulfill its goals. + +When installing objects, the :prop_sf:`INSTALL_OBJECT_NAME` property takes +precedence. + +This property supports +:manual:`generator expressions <cmake-generator-expressions(7)>`, but does not +allow for context-sensitive (i.e., configuration-dependent) expressions. + +.. note:: + No collision resistance within a target is performed by CMake. When using + this property, collisions must be avoided in the project code. CMake has a + number of source files it generates that also create object files that may + collide with a given custom name. These include: + + * Generated PCH source files (``cmake_pch``) + * Generated Unity compilation files (``unity_...``) + * Qt autogen sources (``moc_compilations.cpp``) + +.. note:: + The :generator:`FASTBuild` and :generator:`Xcode` generators do not support + this property and will ignore it.
diff --git a/Help/prop_sf/SKIP_LINTING.rst b/Help/prop_sf/SKIP_LINTING.rst index fe0f2d4..5d2c0c4 100644 --- a/Help/prop_sf/SKIP_LINTING.rst +++ b/Help/prop_sf/SKIP_LINTING.rst
@@ -6,11 +6,12 @@ This property allows you to exclude a specific source file from the linting process. The linting process involves running tools such as :prop_tgt:`<LANG>_CPPLINT`, :prop_tgt:`<LANG>_CLANG_TIDY`, -:prop_tgt:`<LANG>_CPPCHECK`, :prop_tgt:`<LANG>_ICSTAT` and -:prop_tgt:`<LANG>_INCLUDE_WHAT_YOU_USE` on the source files, as well -as compiling header files as part of :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS`. -By setting ``SKIP_LINTING`` on a source file, the mentioned linting tools -will not be executed for that particular file. +:prop_tgt:`<LANG>_CPPCHECK`, :prop_tgt:`<LANG>_ICSTAT`, +:prop_tgt:`<LANG>_PVS_STUDIO` and :prop_tgt:`<LANG>_INCLUDE_WHAT_YOU_USE` on the +source files, as well as compiling header files as part of +:prop_tgt:`VERIFY_INTERFACE_HEADER_SETS`. By setting ``SKIP_LINTING`` on a +source file, the mentioned linting tools will not be executed for that +particular file. Example ^^^^^^^ @@ -41,3 +42,8 @@ source files from the linting process. This allows you to focus the linting tools on the relevant parts of your project, enhancing the efficiency and effectiveness of the linting workflow. + +See Also +^^^^^^^^ + +* :prop_tgt:`SKIP_LINTING` target property
diff --git a/Help/prop_test/ENVIRONMENT_MODIFICATION.rst b/Help/prop_test/ENVIRONMENT_MODIFICATION.rst index c6c1a82..cb9cfcd 100644 --- a/Help/prop_test/ENVIRONMENT_MODIFICATION.rst +++ b/Help/prop_test/ENVIRONMENT_MODIFICATION.rst
@@ -13,26 +13,7 @@ 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 singular ``VALUE`` to the current value of - ``MYVAR``. -- ``string_prepend``: Prepends singular ``VALUE`` to the current value of - ``MYVAR``. -- ``path_list_append``: Appends singular ``VALUE`` to the current value of - ``MYVAR`` using the host platform's path list separator (``;`` on Windows - and ``:`` elsewhere). -- ``path_list_prepend``: Prepends singular ``VALUE`` to the current value of - ``MYVAR`` using the host platform's path list separator (``;`` on Windows - and ``:`` elsewhere). -- ``cmake_list_append``: Appends singular ``VALUE`` to the current value of - ``MYVAR`` using ``;`` as the separator. -- ``cmake_list_prepend``: Prepends singular ``VALUE`` to the current value of - ``MYVAR`` using ``;`` as the separator. + .. include:: ../include/ENVIRONMENT_MODIFICATION_OPS.rst Unrecognized ``OP`` values will result in the test failing before it is executed. This is so that future operations may be added without changing
diff --git a/Help/prop_tgt/ADDITIONAL_CLEAN_FILES.rst b/Help/prop_tgt/ADDITIONAL_CLEAN_FILES.rst index dc87d23..97cfe13 100644 --- a/Help/prop_tgt/ADDITIONAL_CLEAN_FILES.rst +++ b/Help/prop_tgt/ADDITIONAL_CLEAN_FILES.rst
@@ -3,11 +3,11 @@ .. versionadded:: 3.15 -A :ref:`;-list <CMake Language Lists>` of files or directories that will be -removed as a part of the global ``clean`` target. It can be used to specify -files and directories that are generated as part of building the target or -that are directly associated with the target in some way (e.g. created as a -result of running the target). +A :ref:`semicolon-separated list <CMake Language Lists>` of files or +directories that will be removed as a part of the global ``clean`` target. +It can be used to specify files and directories that are generated as part of +building the target or that are directly associated with the target in some way +(e.g. created as a result of running the target). For custom targets, if such files can be captured as outputs or byproducts instead, then that should be preferred over adding them to this property.
diff --git a/Help/prop_tgt/AUTOGEN_ORIGIN_DEPENDS.rst b/Help/prop_tgt/AUTOGEN_ORIGIN_DEPENDS.rst index 33db8a7..4bf83eb 100644 --- a/Help/prop_tgt/AUTOGEN_ORIGIN_DEPENDS.rst +++ b/Help/prop_tgt/AUTOGEN_ORIGIN_DEPENDS.rst
@@ -4,29 +4,29 @@ .. versionadded:: 3.14 Switch for forwarding origin target dependencies to the corresponding -:ref:`<ORIGIN>_autogen` target. +:ref:`<ORIGIN>_autogen <<ORIGIN>_autogen>` target. .. note:: If Qt 5.15 or later is used and the generator is either :generator:`Ninja` or :ref:`Makefile Generators`, origin target dependencies are forwarded to - the :ref:`<ORIGIN>_autogen_timestamp_deps` target instead of - :ref:`<ORIGIN>_autogen` - + the :ref:`<ORIGIN>_autogen_timestamp_deps <<ORIGIN>_autogen_timestamp_deps>` + target instead of :ref:`<ORIGIN>_autogen <<ORIGIN>_autogen>`. Targets which have their :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` property -``ON`` have a corresponding :ref:`<ORIGIN>_autogen` target which generates -``moc`` and ``uic`` files. As this :ref:`<ORIGIN>_autogen` target is created at +``ON`` have a corresponding :ref:`<ORIGIN>_autogen <<ORIGIN>_autogen>` target +which generates ``moc`` and ``uic`` files. +As this :ref:`<ORIGIN>_autogen <<ORIGIN>_autogen>` target is created at generate-time, it is not possible to define dependencies of it using e.g. :command:`add_dependencies`. Instead the ``AUTOGEN_ORIGIN_DEPENDS`` target property decides whether the origin target dependencies should be -forwarded to the :ref:`<ORIGIN>_autogen` target or not. +forwarded to the :ref:`<ORIGIN>_autogen <<ORIGIN>_autogen>` target or not. By default ``AUTOGEN_ORIGIN_DEPENDS`` is initialized from :variable:`CMAKE_AUTOGEN_ORIGIN_DEPENDS` which is ``ON`` by default. -In total the dependencies of the :ref:`<ORIGIN>_autogen` target are composed -from +In total the dependencies of the :ref:`<ORIGIN>_autogen <<ORIGIN>_autogen>` +target are composed from - forwarded origin target dependencies (enabled by default via ``AUTOGEN_ORIGIN_DEPENDS``) @@ -38,11 +38,12 @@ .. note:: Disabling ``AUTOGEN_ORIGIN_DEPENDS`` is useful to avoid building of - origin target dependencies when building the :ref:`<ORIGIN>_autogen` target - only. This is especially interesting when a + origin target dependencies when building the + :ref:`<ORIGIN>_autogen <<ORIGIN>_autogen>` target only. + This is especially interesting when a :variable:`global autogen target <CMAKE_GLOBAL_AUTOGEN_TARGET>` is enabled. - When the :ref:`<ORIGIN>_autogen` target doesn't require all the origin target's - dependencies, and ``AUTOGEN_ORIGIN_DEPENDS`` is disabled, it might be - necessary to extend :prop_tgt:`AUTOGEN_TARGET_DEPENDS` to add missing - dependencies. + When the :ref:`<ORIGIN>_autogen <<ORIGIN>_autogen>` target doesn't require + all the origin target's dependencies, and ``AUTOGEN_ORIGIN_DEPENDS`` is + disabled, it might be necessary to extend :prop_tgt:`AUTOGEN_TARGET_DEPENDS` + to add missing dependencies.
diff --git a/Help/prop_tgt/AUTOGEN_PARALLEL.rst b/Help/prop_tgt/AUTOGEN_PARALLEL.rst index 9d34355..c1c86e8 100644 --- a/Help/prop_tgt/AUTOGEN_PARALLEL.rst +++ b/Help/prop_tgt/AUTOGEN_PARALLEL.rst
@@ -6,9 +6,9 @@ Number of parallel ``moc`` or ``uic`` processes to start when using :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. -The custom :ref:`<ORIGIN>_autogen` target starts a number of threads of which -each one parses a source file and on demand starts a ``moc`` or ``uic`` -process. ``AUTOGEN_PARALLEL`` controls how many parallel threads +The custom :ref:`<ORIGIN>_autogen <<ORIGIN>_autogen>` target starts a number +of threads. Each thread parses a source file and on demand starts a ``moc`` +or ``uic`` process. ``AUTOGEN_PARALLEL`` controls how many parallel threads (and therefore ``moc`` or ``uic`` processes) are started. - An empty (or unset) value or the string ``AUTO`` sets the number of
diff --git a/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst index 13e2ef7..27f1fd3 100644 --- a/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst +++ b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst
@@ -1,28 +1,29 @@ AUTOGEN_TARGET_DEPENDS ---------------------- -Additional target dependencies of the corresponding :ref:`<ORIGIN>_autogen` -target. +Additional target dependencies of the corresponding +:ref:`<ORIGIN>_autogen <<ORIGIN>_autogen>` target. .. note:: If Qt 5.15 or later is used and the generator is either :generator:`Ninja` or :ref:`Makefile Generators`, additional target dependencies are added to - the :ref:`<ORIGIN>_autogen_timestamp_deps` target instead of the - :ref:`<ORIGIN>_autogen` target. + the :ref:`<ORIGIN>_autogen_timestamp_deps <<ORIGIN>_autogen_timestamp_deps>` + target instead of the :ref:`<ORIGIN>_autogen <<ORIGIN>_autogen>` target. Targets which have their :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` property -``ON`` have a corresponding :ref:`<ORIGIN>_autogen` target which generates -``moc`` and ``uic`` files. As this :ref:`<ORIGIN>_autogen` target is created +``ON`` have a corresponding :ref:`<ORIGIN>_autogen <<ORIGIN>_autogen>` target +which generates ``moc`` and ``uic`` files. +As this :ref:`<ORIGIN>_autogen <<ORIGIN>_autogen>` target is created at generate-time, it is not possible to define dependencies of it using e.g. :command:`add_dependencies`. Instead the ``AUTOGEN_TARGET_DEPENDS`` target -property can be set to a :ref:`;-list <CMake Language Lists>` of additional -dependencies for the :ref:`<ORIGIN>_autogen` target. Dependencies can be target -names or file names. +property can be set to a :ref:`semicolon-separated list <CMake Language Lists>` +of additional dependencies for the :ref:`<ORIGIN>_autogen <<ORIGIN>_autogen>` +target. Dependencies can be target names or file names. -In total the dependencies of the :ref:`<ORIGIN>_autogen` target are composed -from +In total, the dependencies of the :ref:`<ORIGIN>_autogen <<ORIGIN>_autogen>` +target are composed from - forwarded origin target dependencies (enabled by default via :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`)
diff --git a/Help/prop_tgt/AUTOMOC.rst b/Help/prop_tgt/AUTOMOC.rst index 0bd4d13..25c5632 100644 --- a/Help/prop_tgt/AUTOMOC.rst +++ b/Help/prop_tgt/AUTOMOC.rst
@@ -251,8 +251,8 @@ :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET`: A global ``autogen`` target, that depends on all ``AUTOMOC`` or -:prop_tgt:`AUTOUIC` generated :ref:`<ORIGIN>_autogen` targets in the project, -will be generated when this variable is ``ON``. +:prop_tgt:`AUTOUIC` generated :ref:`<ORIGIN>_autogen <<ORIGIN>_autogen>` +targets in the project, will be generated when this variable is ``ON``. :prop_tgt:`AUTOGEN_PARALLEL`: This target property controls the number of ``moc`` or ``uic`` processes to
diff --git a/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst b/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst index fec98f6..50da7c0 100644 --- a/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst +++ b/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst
@@ -22,7 +22,7 @@ If any of the extracted files is :prop_sf:`GENERATED` or if it is not in the target's sources, then it might be necessary to add it to the -:ref:`<ORIGIN>_autogen` target dependencies. +:ref:`<ORIGIN>_autogen <<ORIGIN>_autogen>` target dependencies. See :prop_tgt:`AUTOGEN_TARGET_DEPENDS` for reference. By default ``AUTOMOC_DEPEND_FILTERS`` is initialized from
diff --git a/Help/prop_tgt/AUTOUIC.rst b/Help/prop_tgt/AUTOUIC.rst index 6f1c85c..8901de3 100644 --- a/Help/prop_tgt/AUTOUIC.rst +++ b/Help/prop_tgt/AUTOUIC.rst
@@ -76,8 +76,8 @@ :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET`: A global ``autogen`` target, that depends on all :prop_tgt:`AUTOMOC` or -``AUTOUIC`` generated :ref:`<ORIGIN>_autogen` targets in the project, -will be generated when this variable is ``ON``. +``AUTOUIC`` generated :ref:`<ORIGIN>_autogen <<ORIGIN>_autogen>` +targets in the project, will be generated when this variable is ``ON``. :prop_tgt:`AUTOGEN_PARALLEL`: This target property controls the number of ``moc`` or ``uic`` processes to
diff --git a/Help/prop_tgt/COMPILE_PDB_NAME.rst b/Help/prop_tgt/COMPILE_PDB_NAME.rst index 1b4657e..166cfc1 100644 --- a/Help/prop_tgt/COMPILE_PDB_NAME.rst +++ b/Help/prop_tgt/COMPILE_PDB_NAME.rst
@@ -9,6 +9,9 @@ This property specifies the base name for the debug symbols file. If not set, the default is unspecified. +If the :prop_tgt:`PRECOMPILE_HEADERS_REUSE_FROM` target is set, this property +is ignored and the reusage target's value of this property is used instead. + .. versionadded:: 4.1 Contents of ``COMPILE_PDB_NAME`` may use
diff --git a/Help/prop_tgt/COMPILE_PDB_NAME_CONFIG.rst b/Help/prop_tgt/COMPILE_PDB_NAME_CONFIG.rst index f21bdc9..162011d 100644 --- a/Help/prop_tgt/COMPILE_PDB_NAME_CONFIG.rst +++ b/Help/prop_tgt/COMPILE_PDB_NAME_CONFIG.rst
@@ -13,5 +13,8 @@ Contents of ``COMPILE_PDB_NAME_<CONFIG>`` may use :manual:`generator expressions <cmake-generator-expressions(7)>`. +If the :prop_tgt:`PRECOMPILE_HEADERS_REUSE_FROM` target is set, this property +is ignored and the reusage target's value of this property is used instead. + .. |PDB_XXX| replace:: :prop_tgt:`PDB_NAME_<CONFIG>` .. include:: include/COMPILE_PDB_NOTE.rst
diff --git a/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY.rst b/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY.rst index 5bfb50b..9fa7ff2 100644 --- a/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY.rst +++ b/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY.rst
@@ -21,5 +21,8 @@ :variable:`CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY` variable if it is set when a target is created. +If the :prop_tgt:`PRECOMPILE_HEADERS_REUSE_FROM` target is set, this property +is ignored and the reusage target's value of this property is used instead. + .. |PDB_XXX| replace:: :prop_tgt:`PDB_OUTPUT_DIRECTORY` .. include:: include/COMPILE_PDB_NOTE.rst
diff --git a/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst b/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst index c2d4a94..fc9121c 100644 --- a/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst +++ b/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst
@@ -20,5 +20,8 @@ Contents of ``COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG>`` may use :manual:`generator expressions <cmake-generator-expressions(7)>`. +If the :prop_tgt:`PRECOMPILE_HEADERS_REUSE_FROM` target is set, this property +is ignored and the reusage target's value of this property is used instead. + .. |PDB_XXX| replace:: :prop_tgt:`PDB_OUTPUT_DIRECTORY_<CONFIG>` .. include:: include/COMPILE_PDB_NOTE.rst
diff --git a/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst b/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst index d09ff19..8a5c562 100644 --- a/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst +++ b/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst
@@ -20,3 +20,6 @@ This property is initialized by the value of the :variable:`CMAKE_CROSSCOMPILING_EMULATOR` variable if it is set when a target is created. + +This property is not supported when using the old form of :command:`add_test` +(i.e. without the ``NAME`` and ``COMMAND`` keywords).
diff --git a/Help/prop_tgt/CXX_STANDARD.rst b/Help/prop_tgt/CXX_STANDARD.rst index 9b381e4..177f12e 100644 --- a/Help/prop_tgt/CXX_STANDARD.rst +++ b/Help/prop_tgt/CXX_STANDARD.rst
@@ -40,9 +40,6 @@ ``26`` .. versionadded:: 3.25 - C++26. CMake 3.25 and later *recognize* ``26`` as a valid value, - no version has support for any compiler. - 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:
diff --git a/Help/prop_tgt/DEBUGGER_WORKING_DIRECTORY.rst b/Help/prop_tgt/DEBUGGER_WORKING_DIRECTORY.rst index f8f2f30..0916f02 100644 --- a/Help/prop_tgt/DEBUGGER_WORKING_DIRECTORY.rst +++ b/Help/prop_tgt/DEBUGGER_WORKING_DIRECTORY.rst
@@ -3,7 +3,9 @@ .. versionadded:: 4.0 -Sets the local debugger working directory for C++ targets. +Sets the local debugger working directory for targets, +specifically the process launched by the debugger. + The property value may use :manual:`generator expressions <cmake-generator-expressions(7)>`. This property is initialized by the value of the variable
diff --git a/Help/prop_tgt/DEFINE_SYMBOL.rst b/Help/prop_tgt/DEFINE_SYMBOL.rst index 775cf89..6cd6472 100644 --- a/Help/prop_tgt/DEFINE_SYMBOL.rst +++ b/Help/prop_tgt/DEFINE_SYMBOL.rst
@@ -1,17 +1,21 @@ DEFINE_SYMBOL ------------- -Define a symbol when compiling this target's sources. +Define a preprocessor symbol when compiling this target's sources. -``DEFINE_SYMBOL`` sets the name of the preprocessor symbol defined when -compiling sources in a shared library. If not set here then it is set -to ``target_EXPORTS`` by default (with some substitutions if the target is -not a valid C identifier). This is useful for headers to know whether -they are being included from inside their library or outside to -properly setup dllexport/dllimport decorations on Windows. +CMake adds this definition when compiling sources of a ``SHARED`` library, +a ``MODULE`` library, or an ``EXECUTABLE`` with :prop_tgt:`ENABLE_EXPORTS` +enabled. If ``DEFINE_SYMBOL`` is not set, the default definition is of +the form ``<target>_EXPORTS`` (with some substitutions if the target is +not a valid C identifier). + +The symbol is only defined while compiling the target itself and is not +propagated to dependent targets. On POSIX platforms, this can optionally be used to control the visibility of symbols. CMake provides support for such decorations with the :module:`GenerateExportHeader` module. + +See also the ``COMPILE_DEFINITIONS`` under :ref:`Target Compile Properties`.
diff --git a/Help/prop_tgt/EXPORT_FIND_PACKAGE_NAME.rst b/Help/prop_tgt/EXPORT_FIND_PACKAGE_NAME.rst index b7405d6..f74f6d3 100644 --- a/Help/prop_tgt/EXPORT_FIND_PACKAGE_NAME.rst +++ b/Help/prop_tgt/EXPORT_FIND_PACKAGE_NAME.rst
@@ -6,9 +6,10 @@ Experimental. Gated by ``CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_DEPENDENCIES``. Control the package name associated with a dependency target when exporting a -:command:`find_dependency` call in :command:`install(EXPORT)` or +:command:`find_dependency` call in :command:`install(PACKAGE_INFO)`, +:command:`export(PACKAGE_INFO)`, :command:`install(EXPORT)` or :command:`export(EXPORT)`. This can be used to assign a package name to a -package that is built by CMake and exported, or to override the package in the -:command:`find_package` call that created the target. +package that is built by CMake and exported, or a package that was provided by +:module:`FetchContent`. This property is initialized by :variable:`CMAKE_EXPORT_FIND_PACKAGE_NAME`.
diff --git a/Help/prop_tgt/FASTBUILD_CACHING.rst b/Help/prop_tgt/FASTBUILD_CACHING.rst new file mode 100644 index 0000000..6ef1dc0 --- /dev/null +++ b/Help/prop_tgt/FASTBUILD_CACHING.rst
@@ -0,0 +1,19 @@ +FASTBUILD_CACHING +----------------- + +.. versionadded:: 4.2 + +A target property that controls whether caching is enabled for the given +target in the generated ``fbuild.bff``. + +If set to ``OFF``, the :generator:`FASTBuild` generator disables caching +features for this target. This is useful for targets that are known to be +unreliably cached or not worth caching. + +Example: + +.. code-block:: cmake + + set_property(TARGET my_target PROPERTY FASTBUILD_CACHING OFF) + +Defaults to ``ON``.
diff --git a/Help/prop_tgt/FASTBUILD_DISTRIBUTION.rst b/Help/prop_tgt/FASTBUILD_DISTRIBUTION.rst new file mode 100644 index 0000000..58d6df6 --- /dev/null +++ b/Help/prop_tgt/FASTBUILD_DISTRIBUTION.rst
@@ -0,0 +1,19 @@ +FASTBUILD_DISTRIBUTION +---------------------- + +.. versionadded:: 4.2 + +A target property that controls whether distribution is enabled for the given +target in the generated ``fbuild.bff``. + +If set to ``OFF``, the :generator:`FASTBuild` generator disables distributed +compilation for this target. This can be helpful for targets that are fast to +build locally or are incompatible with distributed execution. + +Example: + +.. code-block:: cmake + + set_property(TARGET my_target PROPERTY FASTBUILD_DISTRIBUTION OFF) + +Defaults to ``ON``.
diff --git a/Help/prop_tgt/IMPORTED_CXX_MODULES_CONFIG.rst b/Help/prop_tgt/IMPORTED_CXX_MODULES_CONFIG.rst new file mode 100644 index 0000000..b4106e1 --- /dev/null +++ b/Help/prop_tgt/IMPORTED_CXX_MODULES_CONFIG.rst
@@ -0,0 +1,16 @@ +IMPORTED_CXX_MODULES_<CONFIG> +----------------------------- + +.. versionadded:: 3.28 + +A list of C++ module specifications available with the target for +configuration ``<CONFIG>``. Each item in the list is of the form +``<NAME>=<INTERFACE>[,<BMI>]*`` where ``<NAME>`` is the name of the module, +``<INTERFACE>`` is its module interface unit, and any number of available +``<BMI>`` files are provided. + +.. note:: + + CMake currently does not use the ``<BMI>`` files as there is limited + support for determining whether an existing ``<BMI>`` file is suitable for + a given importer of the module it represents.
diff --git a/Help/prop_tgt/INSTALL_OBJECT_NAME_STRATEGY.rst b/Help/prop_tgt/INSTALL_OBJECT_NAME_STRATEGY.rst new file mode 100644 index 0000000..45cf7d8 --- /dev/null +++ b/Help/prop_tgt/INSTALL_OBJECT_NAME_STRATEGY.rst
@@ -0,0 +1,24 @@ +INSTALL_OBJECT_NAME_STRATEGY +---------------------------- + +.. versionadded:: 4.2 + +``INSTALL_OBJECT_NAME_STRATEGY`` is a string target property variable +specifying the strategy to use when naming installed object files. The +supported values are: + +- ``FULL``: Object files are named after the associated source file or + its :prop_sf:`OBJECT_NAME` property. +- ``SHORT``: Object files are named based on the hash of the source file name + to reduce path lengths. + +When unset or the named strategy is not supported, the ``FULL`` strategy is +used. + +This property is initialized by the value of the variable +:variable:`CMAKE_INSTALL_OBJECT_NAME_STRATEGY` if it is set when a target is +created. + +.. note:: + Not all generators support all strategies and paths may differ between + generators.
diff --git a/Help/prop_tgt/INSTALL_OBJECT_ONLY_USE_DESTINATION.rst b/Help/prop_tgt/INSTALL_OBJECT_ONLY_USE_DESTINATION.rst new file mode 100644 index 0000000..9f55496 --- /dev/null +++ b/Help/prop_tgt/INSTALL_OBJECT_ONLY_USE_DESTINATION.rst
@@ -0,0 +1,20 @@ +INSTALL_OBJECT_ONLY_USE_DESTINATION +----------------------------------- + +.. versionadded:: 4.2 + +Controls whether the ``install(DESTINATION)`` for object libraries is used +as-is or supplemented with conflict-avoiding subdirectories. + +When installing object files, CMake automatically adds +``objects[-<CONFIG>]/<TARGET_NAME>`` components to the destination to avoid +conflicts. Use this property to suppress these components. Note that when +using a single install prefix for multiple configurations (whether via +multi-config generators or separate build trees), the destination must use +``$<CONFIG>`` to avoid conflicts. Alternatively, the +:prop_sf:`INSTALL_OBJECT_NAME` may be used to avoid configuration-based +conflicts. + +This property is initialized by the value of +:variable:`CMAKE_INSTALL_OBJECT_ONLY_USE_DESTINATION` when the target is +created.
diff --git a/Help/prop_tgt/INTERFACE_HEADER_SETS_TO_VERIFY.rst b/Help/prop_tgt/INTERFACE_HEADER_SETS_TO_VERIFY.rst index b0d63f3..7eb6ec3 100644 --- a/Help/prop_tgt/INTERFACE_HEADER_SETS_TO_VERIFY.rst +++ b/Help/prop_tgt/INTERFACE_HEADER_SETS_TO_VERIFY.rst
@@ -4,10 +4,12 @@ .. versionadded:: 3.24 Used to specify which ``PUBLIC`` and ``INTERFACE`` header sets of a target -should be verified. +should be verified as interface headers. This property contains a semicolon-separated list of header sets which -should be verified if :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` is set to -``TRUE``. If the list is empty, all ``PUBLIC`` and ``INTERFACE`` header sets -are verified. (If the project does not want to verify any header sets on the -target, simply set :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` to ``FALSE``.) +should be verified if :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` is set to true. +If the list is empty, all ``PUBLIC`` and ``INTERFACE`` header sets are +verified. If the project does not want to verify any interface header sets on +the target, set :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` to false. + +See also :prop_tgt:`PRIVATE_HEADER_SETS_TO_VERIFY`.
diff --git a/Help/prop_tgt/LANG_PVS_STUDIO.rst b/Help/prop_tgt/LANG_PVS_STUDIO.rst new file mode 100644 index 0000000..f7ae4de --- /dev/null +++ b/Help/prop_tgt/LANG_PVS_STUDIO.rst
@@ -0,0 +1,39 @@ +<LANG>_PVS_STUDIO +----------------- + +.. versionadded:: 4.3 + +This property is implemented only when ``<LANG>`` is ``C`` or ``CXX``. + +Specify a :ref:`semicolon-separated list <CMake Language Lists>` containing +a command line for the ``pvs-studio-analyzer`` tool (named +``CompilerCommandsAnalyzer`` on Windows). The :ref:`Makefile Generators` and +:ref:`Ninja Generators` will run this tool along with the compiler and +report a warning if the tool reports any problems. + +The specified ``pvs-studio-analyzer`` command line will be invoked with +the following additional arguments: + +- ``--source-file``: The source file. +- ``--output-file``: A path adjacent to the object file to write the PVS log. +- ``--cl-params``: The compile options. +- ``--preprocessor``: The preprocessor, based on + :variable:`CMAKE_<LANG>_COMPILER_ID`, if determined to be one of: + ``visualcpp``, ``clang``, ``gcc``, ``bcc``, ``iar``. +- ``--platform``: The target platform, if determined to be one of: ``arm``, + ``win32``, ``x64``, ``linux32``, ``linux64``, ``macOS``. + +See the +`PVS-Studio documentation <https://pvs-studio.com/en/docs/manual/6615/#flags>`_ +for details on these and other available options. + +CMake will look for the ``plog-converter`` tool in the same directory as the +provided ``pvs-studio-analyzer``, and in the user's path if not present in that +directory. The ``plog-converter`` will run automatically with the ``Txt`` +output type on Windows, and ``errorfile`` on other platforms, and the contents +of that file will be sent to ``stderr``. The PVS log file will be deleted after +the converter runs. + +This property is initialized by the value of +the :variable:`CMAKE_<LANG>_PVS_STUDIO` variable if it is set +when a target is created.
diff --git a/Help/prop_tgt/OPTIMIZE_DEPENDENCIES.rst b/Help/prop_tgt/OPTIMIZE_DEPENDENCIES.rst index fcacb00..51c7254 100644 --- a/Help/prop_tgt/OPTIMIZE_DEPENDENCIES.rst +++ b/Help/prop_tgt/OPTIMIZE_DEPENDENCIES.rst
@@ -21,8 +21,8 @@ * The dependency has any ``PRE_BUILD``, ``PRE_LINK``, or ``POST_BUILD`` custom commands associated with it. * The dependency contains any source files that were generated by a custom - command. However, if :policy:`CMP0154` is `NEW` for the dependency and it - uses :ref:`File Sets`, only source files that are not in a ``PUBLIC``, + command. However, if :policy:`CMP0154` is ``NEW`` for the dependency and it + uses :ref:`File Sets`, only source files that are scoped as ``PUBLIC``, ``INTERFACE``, or of type ``CXX_MODULES`` are considered. * The dependency contains any languages which produce side effects that are relevant to the library. Currently, all languages except C, C++, Objective-C,
diff --git a/Help/prop_tgt/POSITION_INDEPENDENT_CODE.rst b/Help/prop_tgt/POSITION_INDEPENDENT_CODE.rst index 2ba1e6f..85e4cf6 100644 --- a/Help/prop_tgt/POSITION_INDEPENDENT_CODE.rst +++ b/Help/prop_tgt/POSITION_INDEPENDENT_CODE.rst
@@ -1,10 +1,11 @@ POSITION_INDEPENDENT_CODE ------------------------- -Whether to create a position-independent target +A target property that specifies whether to create a target that has +position-independent code enabled. -The ``POSITION_INDEPENDENT_CODE`` property determines whether position -independent executables or libraries will be created. This +The ``POSITION_INDEPENDENT_CODE`` target property determines whether +position-independent executables or libraries will be created. This property is ``True`` by default for ``SHARED`` and ``MODULE`` library targets. For other targets, this property is initialized by the value of the :variable:`CMAKE_POSITION_INDEPENDENT_CODE` variable if it is set @@ -14,3 +15,57 @@ For executable targets, the link step is controlled by the :policy:`CMP0083` policy and the :module:`CheckPIESupported` module. + +Position-independent code (PIC) refers to machine code that executes +properly regardless of its absolute memory address. This is particularly +important for shared libraries, which are often loaded at different memory +addresses by different programs. Generating position-independent code +ensures that these libraries can be safely and efficiently shared among +multiple processes without causing address conflicts. On some platforms +(notably UNIX-like systems), generating PIC is also a requirement for +creating shared libraries. + +Use of position-independent code is recommended or required in the following +cases: + +* When building shared or module libraries (e.g., with + ``add_library(... SHARED)``, or ``add_library(... MODULE)``), where PIC + allows dynamic relocation at runtime. + +* When building executables as position-independent executables (PIE), which + can enhance security by enabling Address Space Layout Randomization (ASLR). + +* On platforms or toolchains that require PIC for certain types of linking + or sandboxed environments. + +Enabling PIC can result in slightly larger or slower code on some +architectures, but this is often outweighed by the benefits of flexibility +and security. + +Examples +^^^^^^^^ + +Enabling PIC for a static library target: + +.. code-block:: cmake + + add_library(foo STATIC foo.c) + set_target_properties(foo PROPERTIES POSITION_INDEPENDENT_CODE TRUE) + +Enabling PIC for an executable target: + +.. code-block:: cmake + + add_executable(app app.c) + + set_target_properties(app PROPERTIES POSITION_INDEPENDENT_CODE TRUE) + + # Additionally, pass PIE-related link-time options to executable(s). + include(CheckPIESupported) + check_pie_supported() + +See Also +^^^^^^^^ + +* The :module:`CheckPIESupported` module to pass PIE-related options to the + linker for executables.
diff --git a/Help/prop_tgt/PRIVATE_HEADER_SETS_TO_VERIFY.rst b/Help/prop_tgt/PRIVATE_HEADER_SETS_TO_VERIFY.rst new file mode 100644 index 0000000..e7ad642 --- /dev/null +++ b/Help/prop_tgt/PRIVATE_HEADER_SETS_TO_VERIFY.rst
@@ -0,0 +1,15 @@ +PRIVATE_HEADER_SETS_TO_VERIFY +----------------------------- + +.. versionadded:: 4.3 + +Used to specify which ``PUBLIC`` and ``PRIVATE`` header sets of a target +should be verified as private headers. + +This property contains a semicolon-separated list of header sets which +should be verified if :prop_tgt:`VERIFY_PRIVATE_HEADER_SETS` is set to true. +If the list is empty, all ``PUBLIC`` and ``PRIVATE`` header sets are verified. +If the project does not want to verify any private header sets on the target, +set :prop_tgt:`VERIFY_PRIVATE_HEADER_SETS` to false. + +See also :prop_tgt:`INTERFACE_HEADER_SETS_TO_VERIFY`.
diff --git a/Help/prop_tgt/SKIP_LINTING.rst b/Help/prop_tgt/SKIP_LINTING.rst new file mode 100644 index 0000000..031f653 --- /dev/null +++ b/Help/prop_tgt/SKIP_LINTING.rst
@@ -0,0 +1,25 @@ +SKIP_LINTING +------------ + +.. versionadded:: 4.2 + +Exclude all sources of a target from running configured linting tools. + +When this boolean property is enabled on a target, C/C++ linting tools enabled +for that target (e.g. :prop_tgt:`<LANG>_CPPLINT`, :prop_tgt:`<LANG>_CLANG_TIDY`, +:prop_tgt:`<LANG>_CPPCHECK`, :prop_tgt:`<LANG>_ICSTAT` and +:prop_tgt:`<LANG>_INCLUDE_WHAT_YOU_USE`) will not be invoked for source files +compiled by the target. If the :prop_sf:`SKIP_LINTING` source-file property +is set on a specific source, it takes precedence over this target-wide property. + +This is a convenience alternative to setting the :prop_sf:`SKIP_LINTING` +source file property individually on each source. If either the target's +:prop_tgt:`SKIP_LINTING` or a source’s :prop_sf:`SKIP_LINTING` is enabled, +that source will be excluded from linting. + +The property has no effect on targets that do not have sources. + +See Also +^^^^^^^^ + +* :prop_sf:`SKIP_LINTING` source file property
diff --git a/Help/prop_tgt/SPDX_LICENSE.rst b/Help/prop_tgt/SPDX_LICENSE.rst index 056c860..a030e6c 100644 --- a/Help/prop_tgt/SPDX_LICENSE.rst +++ b/Help/prop_tgt/SPDX_LICENSE.rst
@@ -3,9 +3,9 @@ .. versionadded:: 4.1 -Specify the license of a target using a |SPDX|_ (SPDX) `License Expression`_. -See the SPDX `License List`_ for a list of commonly used licenses and their -identifiers. +Specify the license(s) of a target using a |SPDX|_ (SPDX) +`License Expression`_. See the SPDX `License List`_ for a list of commonly used +licenses and their identifiers. .. _SPDX: https://spdx.dev/ .. |SPDX| replace:: System Package Data Exchange
diff --git a/Help/prop_tgt/SYMBOLIC.rst b/Help/prop_tgt/SYMBOLIC.rst new file mode 100644 index 0000000..36ebe6b --- /dev/null +++ b/Help/prop_tgt/SYMBOLIC.rst
@@ -0,0 +1,11 @@ +SYMBOLIC +-------- + +.. versionadded:: 4.2 + +Read-only indication of whether a target is ``SYMBOLIC``. + +Symbolic targets are created by calls to +:command:`add_library(INTERFACE SYMBOLIC) <add_library(INTERFACE-SYMBOLIC)>`. +They are useful for packages to represent additional **components** or +**feature selectors** that consumers can request via ``find_package()``.
diff --git a/Help/prop_tgt/TEST_LAUNCHER.rst b/Help/prop_tgt/TEST_LAUNCHER.rst index 7eec319..a2103bc 100644 --- a/Help/prop_tgt/TEST_LAUNCHER.rst +++ b/Help/prop_tgt/TEST_LAUNCHER.rst
@@ -21,3 +21,6 @@ This property is initialized by the value of the :variable:`CMAKE_TEST_LAUNCHER` variable if it is set when a target is created. + +This property is not supported when using the old form of :command:`add_test` +(i.e. without the ``NAME`` and ``COMMAND`` keywords).
diff --git a/Help/prop_tgt/UNITY_BUILD_FILENAME_PREFIX.rst b/Help/prop_tgt/UNITY_BUILD_FILENAME_PREFIX.rst new file mode 100644 index 0000000..d6c1e6a --- /dev/null +++ b/Help/prop_tgt/UNITY_BUILD_FILENAME_PREFIX.rst
@@ -0,0 +1,25 @@ +UNITY_BUILD_FILENAME_PREFIX +--------------------------- + +.. versionadded:: 4.2 + +By default, the unity file generated when :prop_tgt:`UNITY_BUILD` is enabled +is of the form ``unity_<index>_<suffix>``, where ``<suffix>`` is language-specific. + +If several targets are using unity builds, the build output may give no +indication which target a unity file belongs to. This property allows +customizing the prefix of the generated unity file name. If unset, +the default prefix ``unity_`` is used. + +Example usage: + +.. code-block:: cmake + + add_library(example_library + source1.cxx + source2.cxx + source3.cxx) + + set_target_properties(example_library PROPERTIES + UNITY_BUILD True + UNITY_BUILD_FILENAME_PREFIX "example_")
diff --git a/Help/prop_tgt/VERIFY_INTERFACE_HEADER_SETS.rst b/Help/prop_tgt/VERIFY_INTERFACE_HEADER_SETS.rst index bdd7792..a14f7c8 100644 --- a/Help/prop_tgt/VERIFY_INTERFACE_HEADER_SETS.rst +++ b/Help/prop_tgt/VERIFY_INTERFACE_HEADER_SETS.rst
@@ -7,35 +7,20 @@ header sets can be included on their own. When this property is set to true, and the target is an object library, static -library, shared library, interface library, or executable with exports enabled, -and the target has one or more ``PUBLIC`` or ``INTERFACE`` header sets, an -object library target named ``<target_name>_verify_interface_header_sets`` is -created. This verification target has one source file per header in the -``PUBLIC`` and ``INTERFACE`` header sets. Each source file only includes its -associated header file. The verification target links against the original -target to get all of its usage requirements. The verification target has its -:prop_tgt:`EXCLUDE_FROM_ALL` and :prop_tgt:`DISABLE_PRECOMPILE_HEADERS` -properties set to true, and its :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTORCC`, -:prop_tgt:`AUTOUIC`, and :prop_tgt:`UNITY_BUILD` properties set to false. +library, shared library, interface library, or executable (subject to policy +:policy:`CMP0209`) and the target has one or more ``PUBLIC`` or ``INTERFACE`` +header sets, an object library target named +``<target_name>_verify_interface_header_sets`` is created. This verification +target has one source file per header in the ``PUBLIC`` and ``INTERFACE`` +header sets. Each source file only includes its associated header file. +The verification target links against the original target to get all of its +usage requirements. -If the header's :prop_sf:`LANGUAGE` property is set, the value of that property -is used to determine the language with which to compile the header file. -Otherwise, if the target has any C++ sources, the header is compiled as C++. -Otherwise, if the target has any C sources, the header is compiled as C. -Otherwise, if C++ is enabled globally, the header is compiled as C++. -Otherwise, if C is enabled globally, the header is compiled as C. Otherwise, -the header file is not compiled. - -If the header's :prop_sf:`SKIP_LINTING` property is set to true, the file is -not compiled. - -If any verification targets are created, a top-level target called -``all_verify_interface_header_sets`` is created which depends on all -verification targets. - -This property is initialized by the value of the -:variable:`CMAKE_VERIFY_INTERFACE_HEADER_SETS` variable if it is set when -a target is created. - -If the project wishes to control which header sets are verified by this -property, it can set :prop_tgt:`INTERFACE_HEADER_SETS_TO_VERIFY`. +.. |xxx| replace:: interface +.. |THIS_PROPERTY| replace:: ``VERIFY_INTERFACE_HEADER_SETS`` +.. |COMPLEMENTARY_PROPERTY| replace:: :prop_tgt:`VERIFY_PRIVATE_HEADER_SETS` +.. |THIS_ALL_TARGET| replace:: ``all_verify_interface_header_sets`` +.. |COMPLEMENTARY_ALL_TARGET| replace:: ``all_verify_private_header_sets`` +.. |INIT_VARIABLE| replace:: :variable:`CMAKE_VERIFY_INTERFACE_HEADER_SETS` +.. |SETS_TO_VERIFY_PROPERTY| replace:: :prop_tgt:`INTERFACE_HEADER_SETS_TO_VERIFY` +.. include:: include/VERIFY_XXX_HEADER_SETS.rst
diff --git a/Help/prop_tgt/VERIFY_PRIVATE_HEADER_SETS.rst b/Help/prop_tgt/VERIFY_PRIVATE_HEADER_SETS.rst new file mode 100644 index 0000000..df9d183 --- /dev/null +++ b/Help/prop_tgt/VERIFY_PRIVATE_HEADER_SETS.rst
@@ -0,0 +1,34 @@ +VERIFY_PRIVATE_HEADER_SETS +-------------------------- + +.. versionadded:: 4.3 + +Used to verify that all headers in a target's ``PUBLIC`` and ``PRIVATE`` +header sets can be included on their own. + +When this property is set to true, and the target is an object library, static +library, shared library, module library, interface library, or executable, and +the target has one or more ``PUBLIC`` or ``PRIVATE`` header sets, an object +library target named ``<target_name>_verify_private_header_sets`` is created. +This verification target has one source file per header in the ``PUBLIC`` and +``PRIVATE`` header sets. Each source file only includes its associated header +file. + +Properties affecting compilation are copied from the original target to the +verification target so that the headers will be interpreted the same way by +the compiler as when compiling the original target's sources. There are some +caveats with this approach. It cannot replicate the same conditions if any +of those properties or properties inherited through build requirements from +transitive dependencies contain +:ref:`target-dependent generator expressions <Target-Dependent Expressions>` +that do not specify the target for the expansion. Such expressions can expand +to different contents depending on the target they are being used on. + +.. |xxx| replace:: private +.. |THIS_PROPERTY| replace:: ``VERIFY_PRIVATE_HEADER_SETS`` +.. |COMPLEMENTARY_PROPERTY| replace:: :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` +.. |THIS_ALL_TARGET| replace:: ``all_verify_private_header_sets`` +.. |COMPLEMENTARY_ALL_TARGET| replace:: ``all_verify_interface_header_sets`` +.. |INIT_VARIABLE| replace:: :variable:`CMAKE_VERIFY_PRIVATE_HEADER_SETS` +.. |SETS_TO_VERIFY_PROPERTY| replace:: :prop_tgt:`PRIVATE_HEADER_SETS_TO_VERIFY` +.. include:: include/VERIFY_XXX_HEADER_SETS.rst
diff --git a/Help/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY.rst b/Help/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY.rst index 9dfa79f..aa62517 100644 --- a/Help/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY.rst +++ b/Help/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY.rst
@@ -3,7 +3,9 @@ .. versionadded:: 3.8 -Sets the local debugger working directory for Visual Studio C++ targets. +Sets the local debugger working directory for Visual Studio targets, +specifically the process launched by the debugger. + The property value may use :manual:`generator expressions <cmake-generator-expressions(7)>`. This is defined in ``<LocalDebuggerWorkingDirectory>`` in the Visual Studio
diff --git a/Help/prop_tgt/include/VERIFY_XXX_HEADER_SETS.rst b/Help/prop_tgt/include/VERIFY_XXX_HEADER_SETS.rst new file mode 100644 index 0000000..f190213 --- /dev/null +++ b/Help/prop_tgt/include/VERIFY_XXX_HEADER_SETS.rst
@@ -0,0 +1,34 @@ +The verification target has its +:prop_tgt:`EXCLUDE_FROM_ALL` and :prop_tgt:`DISABLE_PRECOMPILE_HEADERS` +properties set to true, and its :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTORCC`, +:prop_tgt:`AUTOUIC`, :prop_tgt:`UNITY_BUILD`, and +:prop_tgt:`CXX_SCAN_FOR_MODULES` properties set to false. + +If the header's :prop_sf:`LANGUAGE` property is set, the value of that property +is used to determine the language with which to compile the header file. +Otherwise, if the target has any C++ sources, the header is compiled as C++. +Otherwise, if the target has any C sources, the header is compiled as C. +Otherwise, if C++ is enabled globally, the header is compiled as C++. +Otherwise, if C is enabled globally, the header is compiled as C. Otherwise, +the header file is not compiled. + +If the header's :prop_sf:`SKIP_LINTING` property is set to true, the file is +not compiled. + +If |THIS_PROPERTY| and |COMPLEMENTARY_PROPERTY| are both set to true, headers +belonging to ``PUBLIC`` file sets will be verified twice, but with different +conditions. The compiler flags used for private and interface contexts can be +different, leading to the compiler interpreting the contents of the header +differently. + +If any |xxx| file set verification targets are created, a top-level target +called |THIS_ALL_TARGET| is created which depends on all |xxx| verification +targets. Another target called ``all_verify_header_sets`` is also created +which depends on |THIS_ALL_TARGET|, and on |COMPLEMENTARY_ALL_TARGET| if it +exists (see |COMPLEMENTARY_PROPERTY|). + +This property is initialized by the value of the |INIT_VARIABLE| variable if +it is set when a target is created. + +If the project wishes to control which header sets are verified by this +property, it can set |SETS_TO_VERIFY_PROPERTY|.
diff --git a/Help/release/3.14.rst b/Help/release/3.14.rst index 6b3a187..e4a386a 100644 --- a/Help/release/3.14.rst +++ b/Help/release/3.14.rst
@@ -302,7 +302,7 @@ * A new :variable:`CMAKE_AUTOGEN_ORIGIN_DEPENDS` variable and :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` target property may be set to enable or disable forwarding of the origin target dependencies to the corresponding - :ref:`<ORIGIN>_autogen` target. + :ref:`<ORIGIN>_autogen <<ORIGIN>_autogen>` target. CTest ----- @@ -346,6 +346,9 @@ ``xmlrpc``. CDash is the only maintained testing dashboard for CTest, and it only supports submissions over ``http`` and ``https``. +* The :module:`MacroAddFileDependencies` module is deprecated. + Port projects to use :command:`set_property` directly. + Other Changes =============
diff --git a/Help/release/3.16.rst b/Help/release/3.16.rst index 28273a7..c46e3dc 100644 --- a/Help/release/3.16.rst +++ b/Help/release/3.16.rst
@@ -113,7 +113,7 @@ :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` target property. * The :variable:`CMAKE_ECLIPSE_RESOURCE_ENCODING` variable was added to - specify the resource encoding for the the :generator:`Eclipse CDT4` extra + specify the resource encoding for the :generator:`Eclipse CDT4` extra generator. * The :variable:`CMAKE_UNITY_BUILD` variable was added to initialize the @@ -165,7 +165,7 @@ a new ``REASON_FAILURE_MESSAGE`` option to specify a message giving the reason for the failure. -* The :module:`FindPkgConfig` module :command:`pkg_search_module` macro +* The :module:`FindPkgConfig` module :command:`pkg_search_module` command now defines a ``<prefix>_MODULE_NAME`` result variable containing the first matching module name.
diff --git a/Help/release/3.21.rst b/Help/release/3.21.rst index 8da1c94..0372cd8 100644 --- a/Help/release/3.21.rst +++ b/Help/release/3.21.rst
@@ -98,7 +98,6 @@ * is now supported by the :generator:`Xcode` generator. * The :command:`add_custom_command(TARGET)` command - (for :ref:`Build Events <add_custom_command(TARGET)>`) gained support for resolving target-dependent generator expressions. * The :command:`build_command` command gained a ``PARALLEL_LEVEL`` option.
diff --git a/Help/release/3.22.rst b/Help/release/3.22.rst index efc8115..fa57fc4 100644 --- a/Help/release/3.22.rst +++ b/Help/release/3.22.rst
@@ -75,7 +75,7 @@ * The :module:`FindMatlab` module now provides imported targets. -* The :module:`FindPkgConfig` module gained a :variable:`PKG_CONFIG_ARGN` +* The :module:`FindPkgConfig` module gained a ``PKG_CONFIG_ARGN`` variable to specify arguments to ``pkg-config`` calls. * The :module:`GoogleTest` module :command:`gtest_discover_tests`
diff --git a/Help/release/3.24.rst b/Help/release/3.24.rst index e7ddf2a..56342c0 100644 --- a/Help/release/3.24.rst +++ b/Help/release/3.24.rst
@@ -85,7 +85,8 @@ * The :command:`cmake_host_system_information` command, on Windows, gained a ``QUERY WINDOWS_REGISTRY`` mode. - See its :ref:`Query Windows registry` section. + See its :command:`cmake_host_system_information(QUERY WINDOWS_REGISTRY)` + signature. * The :command:`cmake_language` command gained a new ``SET_DEPENDENCY_PROVIDER`` sub-command. When a dependency provider is set,
diff --git a/Help/release/3.29.rst b/Help/release/3.29.rst index fbde3c6..4916ca4 100644 --- a/Help/release/3.29.rst +++ b/Help/release/3.29.rst
@@ -50,7 +50,7 @@ Commands -------- -* The :ref:`add_custom_command(TARGET) <add_custom_command(TARGET)>` +* The :command:`add_custom_command(TARGET)` signature now supports adding build events through :ref:`Alias Targets`. * The :command:`cmake_language(EXIT)` sub-command was added to terminate
diff --git a/Help/release/3.3.rst b/Help/release/3.3.rst index efb6a7c..3b1da25 100644 --- a/Help/release/3.3.rst +++ b/Help/release/3.3.rst
@@ -135,7 +135,7 @@ documentation, and unit tests. * The :module:`FindPackageHandleStandardArgs` module - ``find_package_handle_standard_args`` function now + :command:`find_package_handle_standard_args` command now always populates both the ``<PackageName>_FOUND`` and ``<UPPERCASE_NAME>_FOUND`` variables (the latter for backwards compatibility). The ``FOUND_VAR``
diff --git a/Help/release/4.2.rst b/Help/release/4.2.rst new file mode 100644 index 0000000..9feb25c --- /dev/null +++ b/Help/release/4.2.rst
@@ -0,0 +1,254 @@ +CMake 4.2 Release Notes +*********************** + +.. only:: html + + .. contents:: + +Changes made since CMake 4.1 include the following. + +New Features +============ + +File-Based API +-------------- + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field has + been updated to 2.9. + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" and + "directory" objects gained a new ``codemodelVersion`` field. + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 now includes imported + targets and all interface library targets in its replies. Previously, + imported targets were omitted, and only those interface targets that + participated in the build system were included. The following changes + support these new additions: + + * The "target" object gained ``imported``, ``local``, and ``abstract`` fields. + * The "target" object's ``type`` field can now also hold the value + ``UNKNOWN_LIBRARY``. + * The "codemodel" object's ``configurations`` entries gained a new + ``abstractTargets`` array. + * Entries in the ``directories`` and ``projects`` arrays of the "codemodel" + object's ``configurations`` entries gained a new ``abstractTargetIndexes`` + array. + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object gained + new ``linkLibraries``, ``interfaceLinkLibraries``, ``compileDependencies``, + ``interfaceCompileDependencies``, ``objectDependencies``, and + ``orderDependencies`` fields. + +Generators +---------- + +* The :generator:`Visual Studio 18 2026` generator was added. + +* The :generator:`FASTBuild` generator was added. + +Platforms +--------- + +* CMake now supports :ref:`Cross Compiling for Emscripten` with simple + toolchain files. + +Command-Line +------------ + +* The :manual:`cmake(1)` command-line tool now supports + ``cmake -E copy_if_newer`` and ``cmake -E copy_directory_if_newer`` + subcommands to copy files based on timestamp comparison instead of + content comparison. These commands copy files only if the source is + newer than the destination, providing better performance for build + systems compared to ``copy_if_different`` which compares file contents. + +Commands +-------- + +* The :command:`cmake_language(TRACE)` command was added to enable or + disable tracing during script execution. + +* The :command:`set(CACHE{<variable>}) <set(CACHE)>` and + :command:`unset(CACHE{<variable>}) <unset(CACHE)>` commands were added to + explicitly set and unset cache entries. + +* The :command:`string(REGEX QUOTE)` command was added to + generate a regular expression exactly matching a string. + +Variables +--------- + +* The :variable:`CMAKE_CXX_STDLIB_MODULES_JSON` variable was added to set + the path to the ``import std`` metadata file for the standard library + rather than using the compiler to discover its location. + +* The :variable:`CMAKE_INTERMEDIATE_DIR_STRATEGY` variable and corresponding + :envvar:`CMAKE_INTERMEDIATE_DIR_STRATEGY` environment variable were added + to change the strategy used to name intermediate directories used for + object files and other associated target metadata. + +* The :variable:`CMAKE_AUTOGEN_INTERMEDIATE_DIR_STRATEGY` variable and + corresponding :envvar:`CMAKE_AUTOGEN_INTERMEDIATE_DIR_STRATEGY` environment + variable were added to change the strategy used to name intermediate + directories used for :manual:`Qt Autogen <cmake-qt(7)>` files. + +* The :variable:`CMAKE_SKIP_LINTING` variable and corresponding + :prop_tgt:`SKIP_LINTING` target property were added to tell the + :ref:`Command-Line Build Tool Generators` to skip linting all + sources in a target. + +Properties +---------- + +* The :prop_sf:`INSTALL_OBJECT_NAME` source file property was added to + control names of installed object files for specific compiled sources. + +* The :prop_tgt:`INSTALL_OBJECT_NAME_STRATEGY` target property was added + to control the naming strategy for installed object files. + +* The :prop_tgt:`INSTALL_OBJECT_ONLY_USE_DESTINATION` target property was + added to more precisely control the installation path for object files. + +* The :prop_sf:`JOB_POOL_COMPILE` source file property was added + to assign individual source compilations to :prop_gbl:`JOB_POOLS`. + +* The :prop_sf:`OBJECT_NAME` source file property was added to control + object names of compiled source files. + +* The :prop_tgt:`UNITY_BUILD_FILENAME_PREFIX` target property was added + to control names of source files generated by :prop_tgt:`UNITY_BUILD`. + +Modules +------- + +* Nearly all find modules now provide a ``<PackageName>_VERSION`` result + variable matching the casing of its module name. Existing variants such as + ``<PackageName>_VERSION_STRING`` and uppercased ``<PACKAGENAME>_VERSION`` + are deprecated. See documentation of each find module for details. + +* The :module:`CheckTypeSize` module's :command:`check_type_size` command + gained a new ``RESULT_VARIABLE`` keyword to customize the result variable + name instead of the default ``HAVE_<size-var>``. + +* The :module:`ExternalProject` module's :command:`ExternalProject_Add` + and :command:`ExternalProject_Add_Step` commands now provide options to set + environment variables on the configure, build, install, and test steps. + +* The :module:`FindPython3`, :module:`FindPython2`, and :module:`FindPython` + modules no longer make ``NumPy`` depend on ``Development.Module``. + See policy :policy:`CMP0201`. + +* The :module:`GoogleTest` module's :command:`gtest_discover_tests()` + command now sets the ``DEF_SOURCE_LINE`` test property for each + discovered test if gtest supports the ``--gtest_output=json`` option. + This test property is used by some IDEs to locate the source for each test. + +* The :module:`UseSWIG` module's :command:`swig_add_library` command gained a + ``DEBUG_POSTFIX`` option to control the :prop_tgt:`DEBUG_POSTFIX` target + property. + +Generator Expressions +--------------------- + +* The :genex:`<LANG>_COMPILER_LINKER_ID <C_COMPILER_LINKER_ID>` and + :genex:`<LANG>_COMPILER_LINKER_FRONTEND_VARIANT <C_COMPILER_LINKER_FRONTEND_VARIANT>` + families of generator expressions were added to access the value of the + associated :variable:`CMAKE_<LANG>_COMPILER_LINKER_ID` and + :variable:`CMAKE_<LANG>_COMPILER_LINKER_FRONTEND_VARIANT` variables. + +* The :genex:`TARGET_FILE_BASE_NAME`, :genex:`TARGET_IMPORT_FILE_BASE_NAME`, + :genex:`TARGET_LINKER_FILE_BASE_NAME`, + :genex:`TARGET_LINKER_LIBRARY_FILE_BASE_NAME`, + :genex:`TARGET_LINKER_IMPORT_FILE_BASE_NAME`, and + :genex:`TARGET_PDB_FILE_BASE_NAME` + generator expressions gained a ``POSTFIX`` option to control the inclusion + of the :prop_tgt:`<CONFIG>_POSTFIX` target property as part of the base + names of the corresponding files. + +* The :genex:`TARGET_INTERMEDIATE_DIR` generator expression was + added to refer to a target's intermediate files directory in + the build tree. + +CPack +----- + +* The :cpack_gen:`CPack AppImage Generator` was added. + +* The :variable:`CPACK_PACKAGE_CHECKSUM` variable now supports multiple values. + +* The :cpack_gen:`CPack NSIS Generator` gained a + :variable:`CPACK_NSIS_CRC_CHECK` variable for setting the ``CRCCheck`` + attribute. + +* The :cpack_gen:`CPack WIX Generator` gained a + :variable:`CPACK_WIX_CAB_PER_COMPONENT` variable to enable one ``.cab`` + per component. + +Deprecated and Removed Features +=============================== + +* All find modules now provide a ``<PackageName>_FOUND`` result variable + matching the casing of its module name. Existing variants, such as the + uppercased ``<PACKAGENAME>_FOUND``, are deprecated where appropriate. + See documentation of each find module for details. + +* The :module:`FindwxWidgets` module's result variable + ``wxWidgets_USE_FILE`` is now deprecated in favor of including the + :module:`UsewxWidgets` module directly. + +* The :generator:`Visual Studio 14 2015` generator is now deprecated + and will be removed in a future version of CMake. + +Other Changes +============= + +* The :genex:`$<CONFIG:cfgs>` generator expression, when appearing on an + imported target, has been fixed to not match configurations that are not + applicable. See policy :policy:`CMP0199`. + +* Selection of configuration and location of imported targets is now more + consistent. See policy :policy:`CMP0200`. + +* The :variable:`CMAKE_PARENT_LIST_FILE` variable is no longer defined when + processing a ``CMakeLists.txt`` file. See policy :policy:`CMP0198`. + +* For builds targeting the MSVC ABI, all generators now add the ``_MBCS`` + preprocessor definition when compiling sources unless ``_UNICODE`` or + ``_SBCS`` is found. See policy :policy:`CMP0204`. + +* For builds targeting the MSVC ABI, all generators now add the ``_WINDLL`` + preprocessor definition when compiling sources in shared libraries. + See policy :policy:`CMP0203`. + +* The :ref:`Visual Studio Generators` now suppress Visual Studio's default + flags ``-fp:precise``, ``-Gd``, and ``-GS`` if they are not specified by + the project or user. This makes builds more consistent with other + generators, and with what projects and users actually specify. + +Updates +======= + +Changes made since CMake 4.2.0 include the following. + +4.2.1 +----- + +* This version made no changes to documented features or interfaces. + Some implementation updates were made to support ecosystem changes + and/or fix regressions. + +4.2.2 +----- + +* Policy :policy:`CMP0199`'s NEW behavior has been partially reverted. + In 4.2.0 and 4.2.1, ``$<CONFIG:cfgs>`` only matched the configuration + of the consumed target. This broke existing use cases that rely on + matching the configuration of the consuming target, and so has been + partially reverted to match either as CMake 4.1 and below did. + +4.2.3, 4.2.4, 4.2.5 +------------------- + +* 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/4.3.rst b/Help/release/4.3.rst new file mode 100644 index 0000000..b13656f --- /dev/null +++ b/Help/release/4.3.rst
@@ -0,0 +1,294 @@ +CMake 4.3 Release Notes +*********************** + +.. only:: html + + .. contents:: + +Changes made since CMake 4.2 include the following. + +New Features +============ + +Common Package Specification +---------------------------- + +* Support for importing and exporting packages described using the |CPS|_ + (CPS) was added. This improves build system interoperability by allowing + expressive, feature-rich package descriptions to be exchanged in a format + other than CMake Language. + + * The :command:`find_package` now searches for and can import CPS packages. + + * The :command:`install` and :command:`export` commands gained a new + ``PACKAGE_INFO`` sub-command to generate CPS package descriptions. + + * The :command:`project` command gained new ``COMPAT_VERSION`` and + ``SPDX_LICENSE`` options. These values may be inherited when creating a + CPS package description. See the :command:`install(PACKAGE_INFO)` + documentation for details. + +.. _CPS: https://cps-org.github.io/cps/ +.. |CPS| replace:: Common Package Specification + +Instrumentation +--------------- + +* :manual:`cmake-instrumentation(7)` was added to enable collection of + timing data, target information, and system diagnostic information during + the configure, generate, build, test, and install steps of a CMake project: + + * Instrumentation data are :ref:`indexed <cmake-instrumentation Indexing>` + and provided to :ref:`callbacks <cmake-instrumentation Callbacks>` for + custom processing. + + * Instrumentation data are included in submissions to CDash. + + * Optionally, + :ref:`Google Trace Event Format <cmake-instrumentation Google Trace File>` + files may be generated to visualize instrumentation data. + +Presets +------- + +* :manual:`cmake-presets(7)` files now support schema version ``11``. + The ``jobs`` field under test presets now supports an empty string, to + match the behavior of :option:`ctest --parallel` with the value omitted. +* The ``jobs`` field under both build and test presets no longer accept + negative integer values, regardless of the schema version. + +File-Based API +-------------- + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 version field + has been updated to 2.10. + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object + gained a new ``interfaceSources`` array field, and the ``sourceGroups`` + array items gained a new ``interfaceSourceIndexes`` array field. + +Platforms +--------- + +* ``HIP`` language code may now be compiled for SPIR-V targets, + e.g., via chipStar. See the :variable:`CMAKE_HIP_PLATFORM` variable. + +Command-Line +------------ + +* :option:`cmake --version` now supports a ``=json-v1`` value to print + detailed version information in a JSON format. + +* :option:`cmake --build` now supports specifying a build directory and + preset together. The build preset will be used with the explicit + build directory substituted. + +* The :option:`cmake -E` commands + :option:`md5sum <cmake-E md5sum>`, + :option:`sha1sum <cmake-E sha1sum>`, + :option:`sha224sum <cmake-E sha224sum>`, + :option:`sha256sum <cmake-E sha256sum>`, + :option:`sha384sum <cmake-E sha384sum>`, and + :option:`sha512sum <cmake-E sha512sum>` + now support reading from standard input by passing ``-``. + +* The :option:`cmake -E bin2c <cmake-E bin2c>` command-line tool was added. + +* The :option:`cmake -E tar <cmake-E tar>` command-line tool: + + * Gained a ``--cmake-tar-compression-level`` flag to specify the + compression level. + * Gained a ``--cmake-tar-compression-method`` flag to specify the + compression method. + * Gained a ``--cmake-tar-threads`` flag to enable multithreaded operations. + * Now supports specifying compression method and level for ``7zip`` and + ``zip`` formats. + * Gained a ``--format=raw`` flag to disable compression. + * Gained a ``--lzma`` flag to specify ``LZMA`` compression. + +Commands +-------- + +* The :command:`cmake_instrumentation` command was added to make + project-level instrumentation queries. + +* The :command:`file(ARCHIVE_CREATE)` command: + + * Gained a ``THREADS`` option to enable multithreaded operations. + * Now supports ``COMPRESSION`` method ``Deflate`` as an alias for ``GZip``. + * Now supports ``COMPRESSION`` method ``LZMA``. + * Now supports ``COMPRESSION`` method ``LZMA2`` as an alias for ``XZ``. + * Now supports ``COMPRESSION`` method ``PPMd`` for format ``7zip``. + * Now supports ``COMPRESSION`` and ``COMPRESSION_LEVEL`` options + for formats ``7zip`` and ``zip``. + +* The :command:`get_property` and :command:`set_property` commands + now support a ``FILE_SET`` scope for file set properties of a target. + +* The :command:`string(JSON)` command gained new ``GET_RAW`` and + ``STRING_ENCODE`` modes. + +* The :command:`source_group` command now supports + :manual:`generator expressions <cmake-generator-expressions(7)>`. + +* The :command:`cmake_host_system_information` command gained a + ``LOCALE_CHARSET`` query for the expected :manual:`cmake-language(7)` + script encoding. + +Variables +--------- + +* The :variable:`CMAKE_<LANG>_LINK_FLAGS` and + :variable:`CMAKE_<LANG>_LINK_FLAGS_<CONFIG>` variables were added + to support per-language link flags for all target types. + See policy :policy:`CMP0210`. + +* The :variable:`CMAKE_VERIFY_PRIVATE_HEADER_SETS` variable and corresponding + :prop_tgt:`VERIFY_PRIVATE_HEADER_SETS` target property were added to + enable build rules that verify all headers in private file sets can be used + on their own. + +Properties +---------- + +* A :prop_tgt:`<LANG>_PVS_STUDIO` target property and supporting + :variable:`CMAKE_<LANG>_PVS_STUDIO` variable were introduced to tell + :ref:`Makefile Generators` and :ref:`Ninja Generators` to run + ``pvs-studio-analyzer`` with the compiler for ``C`` and ``CXX`` languages. + +* When :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` is set to true on an executable + target, that target's interface file sets are verified regardless of its + :prop_tgt:`ENABLE_EXPORTS` property. See policy :policy:`CMP0209`. + +* The :prop_tgt:`PRIVATE_HEADER_SETS_TO_VERIFY` target property was added to + customize which private file sets to verify when the target's + :prop_tgt:`VERIFY_PRIVATE_HEADER_SETS` property is true. + +Modules +------- + +* The :module:`FindCUDAToolkit` module now creates a ``CUDA::bin2c`` + imported target for the :ref:`bin2c <FindCUDAToolkit_bin2c>` utility. + +* The :module:`FindLibXml2` module gained a ``LibXml2_USE_STATIC_LIBS`` hint + to select static libraries. + +* The :module:`FindRuby` module now provides imported targets. + +* The :module:`FindSQLite3` module now provides imported + targets with the ``SQLite3::`` prefix. + +* The :module:`UseJava` module's :command:`add_jar` command now accepts a new + ``INCLUDE_MODULES`` option that adds its arguments to the ``--module-path`` + argument to the Java compiler. This allows building JAR files that use JPMS + modules in their build. + +Generator Expressions +--------------------- + +* :ref:`String Comparison <String Comparisons Generator Expressions>` + generator expressions were added. + +* :genex:`$<STRING:...>` generator expressions were added for + :ref:`query <String Queries Generator Expressions>`, + :ref:`generation <String Generating Generator Expressions>`, and + :ref:`transformation <String Transforming Generator Expressions>` + operations on strings. + +* The :genex:`$<FILE_SET_EXISTS>` and :genex:`$<FILE_SET_PROPERTY>` generator + expressions were added to query file set existence and properties. + +* The :genex:`$<SOURCE_EXISTS>` and :genex:`$<SOURCE_PROPERTY>` generator + expressions were added to query source file existence and properties. + +CTest +----- + +* The :module:`CTestCoverageCollectGCOV` module: + + * Now supports ``TARBALL_COMPRESSION`` method ``LZMA``. + + * Now supports ``TARBALL_COMPRESSION`` method ``LZMA2`` + as an alias for ``XZ``. + + * Now supports ``FROM_EXT`` with file extensions corresponding to + ``LZMA`` and ``ZSTD`` compression. + +CPack +----- + +* :module:`CPack` gained the :variable:`CPACK_COMPRESSION_LEVEL` + variable to control the compression level used when creating + packages. + +* The :cpack_gen:`CPack Archive Generator`: + + * Now supports compression method specification for formats + ``7zip`` and ``zip``. + + * Gained a :variable:`CPACK_ARCHIVE_COMPRESSION_LEVEL` option to + control the compression level used when creating archive packages. + + * Gained :variable:`CPACK_ARCHIVE_UID` and :variable:`CPACK_ARCHIVE_GID` + options to specify the UID and GID of archive entries, respectively. + The defaults are UID ``0`` and GID ``0``. See policy :policy:`CMP0206`. + +* The :cpack_gen:`CPack DEB Generator` gained a new + :variable:`CPACK_DEBIAN_COMPRESSION_LEVEL` variable to control the + compression level used when creating Debian packages. + +* The :cpack_gen:`CPack WIX Generator` now supports per-user installers + by setting :variable:`CPACK_WIX_INSTALL_SCOPE` to ``perUser``. + +Deprecated and Removed Features +=============================== + +* The :variable:`CMAKE_ENABLE_EXPORTS` variable is deprecated in favor of + the :variable:`CMAKE_EXECUTABLE_ENABLE_EXPORTS` and + :variable:`CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS` variables. + +* The :command:`export(EXPORT)` command no longer allows certain + arguments to be missing or empty. See policy :policy:`CMP0208`. + +Other Changes +============= + +* The :option:`cmake -E tar <cmake-E tar>` command-line tool + and the :command:`file(ARCHIVE_EXTRACT)` command now reject archive + entries whose paths are absolute or contain ``..`` path traversal + components. + +* The family of :option:`cmake --trace` and related commands now print "end" + commands for control structures: :command:`endblock`, :command:`endforeach`, + :command:`endfunction`, :command:`endif`, :command:`endmacro`, and + :command:`endwhile`. + +* The :command:`file(CREATE_LINK)` command's ``COPY_ON_ERROR`` option, + when used with a directory, now copies directory content. + See policy :policy:`CMP0205`. + +* The :command:`file(GET_RUNTIME_DEPENDENCIES)` + and :command:`install(RUNTIME_DEPENDENCY_SET)` commands now normalize + paths before matching filters. See policy :policy:`CMP0207`. + +* The precompiled Linux ``aarch64`` binaries provided on + `cmake.org <https://cmake.org/download/>`_ now require GLIBC 2.28 or higher. + +* The precompiled macOS binary provided on ``cmake.org`` for macOS 10.13+ + now requires macOS 12 or newer for the :manual:`cmake-gui(1)` application. + The command-line tools still run on macOS 10.13. + +* The precompiled Windows binaries provided on + `cmake.org <https://cmake.org/download/>`_ now require Windows 10 or higher. + +Updates +======= + +Changes made since CMake 4.3.0 include the following. + +4.3.1, 4.3.2 +------------ + +* 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/index.rst b/Help/release/index.rst index 400e1f2..c525705 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst
@@ -13,6 +13,8 @@ .. toctree:: :maxdepth: 1 + 4.3 <4.3> + 4.2 <4.2> 4.1 <4.1> 4.0 <4.0> 3.31 <3.31>
diff --git a/Help/variable/CMAKE_AUTOGEN_INTERMEDIATE_DIR_STRATEGY.rst b/Help/variable/CMAKE_AUTOGEN_INTERMEDIATE_DIR_STRATEGY.rst new file mode 100644 index 0000000..3cede1f --- /dev/null +++ b/Help/variable/CMAKE_AUTOGEN_INTERMEDIATE_DIR_STRATEGY.rst
@@ -0,0 +1,33 @@ +CMAKE_AUTOGEN_INTERMEDIATE_DIR_STRATEGY +--------------------------------------- + +.. versionadded:: 4.2 + +``CMAKE_AUTOGEN_INTERMEDIATE_DIR_STRATEGY`` is a string cache variable +specifying the strategy to use for autogen target intermediate directories and +their contents. The supported values are: + +- ``FULL``: Intermediate directories are named based on a + ``<TARGET_NAME>_autogen.dir`` and ``<TARGET_NAME>_autogen`` pattern (with + some slight deviations and sanitizations applied in various places). Object + file names are based on the filename of the source file being compiled. +- ``SHORT``: Intermediate directories are named from the hash of the target + name and the build directory location and an ``/autogen`` subdirectory. + This may help with projects that generate long paths in the build directory + to support building in directories other than those near a root path. + +When unset or the named strategy is not supported, the ``FULL`` strategy is +used. + +.. note:: + This only works as a cache variable, not a locally-scoped variable. + +This is supported by the following generators: + +- :ref:`Ninja Generators` +- :ref:`Makefile Generators` +- :ref:`Visual Studio Generators` + +.. note:: + Not all generators support all strategies and paths may differ between + generators.
diff --git a/Help/variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS.rst b/Help/variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS.rst index 52aa891..139268b 100644 --- a/Help/variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS.rst +++ b/Help/variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS.rst
@@ -4,14 +4,14 @@ .. versionadded:: 3.14 Switch for forwarding origin target dependencies to the corresponding -:ref:`<ORIGIN>_autogen` targets. +:ref:`<ORIGIN>_autogen <<ORIGIN>_autogen>` targets. .. note:: If Qt 5.15 or later is used and the generator is either :generator:`Ninja` or :ref:`Makefile Generators`, additional target dependencies are added to - the :ref:`<ORIGIN>_autogen_timestamp_deps` target instead of the - :ref:`<ORIGIN>_autogen` target. + the :ref:`<ORIGIN>_autogen_timestamp_deps <<ORIGIN>_autogen_timestamp_deps>` + target instead of the :ref:`<ORIGIN>_autogen <<ORIGIN>_autogen>` target. This variable is used to initialize the :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` property on all the targets. See that target property for additional
diff --git a/Help/variable/CMAKE_BINARY_DIR.rst b/Help/variable/CMAKE_BINARY_DIR.rst index 96c6319..b046037 100644 --- a/Help/variable/CMAKE_BINARY_DIR.rst +++ b/Help/variable/CMAKE_BINARY_DIR.rst
@@ -11,3 +11,5 @@ ``CMAKE_BINARY_DIR``, :variable:`CMAKE_SOURCE_DIR`, :variable:`CMAKE_CURRENT_BINARY_DIR` and :variable:`CMAKE_CURRENT_SOURCE_DIR` to the current working directory. + +Modifying ``CMAKE_BINARY_DIR`` has undefined behavior.
diff --git a/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst b/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst index 1d7a111..1eabaef 100644 --- a/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst +++ b/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst
@@ -13,3 +13,5 @@ :variable:`CMAKE_BINARY_DIR`, :variable:`CMAKE_SOURCE_DIR`, ``CMAKE_CURRENT_BINARY_DIR`` and :variable:`CMAKE_CURRENT_SOURCE_DIR` to the current working directory. + +Modifying ``CMAKE_CURRENT_BINARY_DIR`` has undefined behavior.
diff --git a/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst b/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst index 4205efb..7a08892 100644 --- a/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst +++ b/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst
@@ -10,3 +10,5 @@ :variable:`CMAKE_BINARY_DIR`, :variable:`CMAKE_SOURCE_DIR`, :variable:`CMAKE_CURRENT_BINARY_DIR` and ``CMAKE_CURRENT_SOURCE_DIR`` to the current working directory. + +Modifying ``CMAKE_CURRENT_SOURCE_DIR`` has undefined behavior.
diff --git a/Help/variable/CMAKE_CXX_STDLIB_MODULES_JSON.rst b/Help/variable/CMAKE_CXX_STDLIB_MODULES_JSON.rst new file mode 100644 index 0000000..134e8d6 --- /dev/null +++ b/Help/variable/CMAKE_CXX_STDLIB_MODULES_JSON.rst
@@ -0,0 +1,11 @@ +CMAKE_CXX_STDLIB_MODULES_JSON +----------------------------- + +.. versionadded:: 4.2 + +This variable may be used to set the path to a metadata file for CMake to +understand how the ``import std`` target for the active CXX compiler should be +constructed. + +This should only be used when the compiler does not know how to discover the +relevant module metadata file without such assistance.
diff --git a/Help/variable/CMAKE_DL_LIBS.rst b/Help/variable/CMAKE_DL_LIBS.rst index 50d313d..11fc742 100644 --- a/Help/variable/CMAKE_DL_LIBS.rst +++ b/Help/variable/CMAKE_DL_LIBS.rst
@@ -1,7 +1,49 @@ CMAKE_DL_LIBS ------------- -Name of library containing ``dlopen`` and ``dlclose``. +This variable contains a name of the dynamic loading library, or a list of +system libraries needed to use the ``dlopen()`` and ``dlclose()`` functions. -The name of the library that has ``dlopen`` and ``dlclose`` in it, usually -``-ldl`` on most UNIX machines. +Few examples of the values this variable is set to: + +``dl`` + On most Unix-like systems. + +``-lld`` + On AIX, prior to CMake 4.2. + +``dld`` + On HP-UX. + +"" + Empty string value or not set on systems that have ``dl*()`` functions + either in the default library that is implicitly linked (e.g., BSD-like + systems, Haiku, macOS, SunOS, etc.), or on systems that don't provide these + functions (e.g., Windows). + +Examples +^^^^^^^^ + +Example: Linking Dynamic Loading Library +"""""""""""""""""""""""""""""""""""""""" + +Using this variable in a project that uses dynamic loading functionality: + +.. code-block:: cmake + + target_link_libraries(example PRIVATE ${CMAKE_DL_LIBS}) + +Example: Checking Symbols +""""""""""""""""""""""""" + +Checking for symbols with the dynamic loading library linked during the check: + +.. code-block:: cmake + + include(CheckSymbolExists) + include(CMakePushCheckState) + + cmake_push_check_state(RESET) + set(CMAKE_REQUIRED_LIBRARIES ${CMAKE_DL_LIBS}) + check_symbol_exists(dlopen "dlfcn.h" HAVE_DLOPEN) + cmake_pop_check_state()
diff --git a/Help/variable/CMAKE_ENABLE_EXPORTS.rst b/Help/variable/CMAKE_ENABLE_EXPORTS.rst index da23342..efde96d 100644 --- a/Help/variable/CMAKE_ENABLE_EXPORTS.rst +++ b/Help/variable/CMAKE_ENABLE_EXPORTS.rst
@@ -3,13 +3,16 @@ .. versionadded:: 3.4 +.. deprecated:: 4.3 + This variable has been deprecated in favor of the + :variable:`CMAKE_EXECUTABLE_ENABLE_EXPORTS` and + :variable:`CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS` variables, + which have been available since CMake 3.27. + It is provided for backward compatibility with older CMake code, + but should not be used in new projects. + Specify whether executables export symbols for loadable modules. This variable is used to initialize the :prop_tgt:`ENABLE_EXPORTS` target property for executable targets when they are created by calls to the :command:`add_executable` command. See the property documentation for details. - -This variable has been superseded by the -:variable:`CMAKE_EXECUTABLE_ENABLE_EXPORTS` variable. It is provided for -backward compatibility with older CMake code, but should not be used in new -projects.
diff --git a/Help/variable/CMAKE_EXECUTABLE_ENABLE_EXPORTS.rst b/Help/variable/CMAKE_EXECUTABLE_ENABLE_EXPORTS.rst index aa6dda2..5168555 100644 --- a/Help/variable/CMAKE_EXECUTABLE_ENABLE_EXPORTS.rst +++ b/Help/variable/CMAKE_EXECUTABLE_ENABLE_EXPORTS.rst
@@ -9,4 +9,9 @@ property for executable targets when they are created by calls to the :command:`add_executable` command. See the property documentation for details. -This variable supersede the :variable:`CMAKE_ENABLE_EXPORTS` variable. +This variable supersedes the :variable:`CMAKE_ENABLE_EXPORTS` variable. + +See Also +^^^^^^^^ + +* The :variable:`CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS` variable.
diff --git a/Help/variable/CMAKE_EXE_LINKER_FLAGS.rst b/Help/variable/CMAKE_EXE_LINKER_FLAGS.rst index 0bb08ce..4e746ea 100644 --- a/Help/variable/CMAKE_EXE_LINKER_FLAGS.rst +++ b/Help/variable/CMAKE_EXE_LINKER_FLAGS.rst
@@ -3,6 +3,12 @@ Linker flags to be used to create executables. -These flags will be used by the linker when creating an executable. +These flags will be used by the linker when creating an executable for all +build configurations. .. include:: ../variable/include/LINKER_FLAGS.rst + +See Also +^^^^^^^^ + +* :variable:`CMAKE_EXE_LINKER_FLAGS_<CONFIG>`
diff --git a/Help/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG.rst b/Help/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG.rst index 30aad20..7dac9e9 100644 --- a/Help/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG.rst +++ b/Help/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG.rst
@@ -3,7 +3,12 @@ Flags to be used when linking an executable. -Same as ``CMAKE_C_FLAGS_*`` but used by the linker when creating -executables. +These flags will be used by the linker when creating an executable for the +``<CONFIG>`` configuration. .. include:: ../variable/include/LINKER_FLAGS.rst + +See Also +^^^^^^^^ + +* :variable:`CMAKE_EXE_LINKER_FLAGS`
diff --git a/Help/variable/CMAKE_FASTBUILD_ALLOW_RESPONSE_FILE.rst b/Help/variable/CMAKE_FASTBUILD_ALLOW_RESPONSE_FILE.rst new file mode 100644 index 0000000..c937537 --- /dev/null +++ b/Help/variable/CMAKE_FASTBUILD_ALLOW_RESPONSE_FILE.rst
@@ -0,0 +1,9 @@ +CMAKE_FASTBUILD_ALLOW_RESPONSE_FILE +----------------------------------- + +.. versionadded:: 4.2 + +Enables FASTBuild's ``AllowResponseFile`` option. + +See the `FASTBuild Compiler() documentation <https://www.fastbuild.org/docs/functions/compiler.html>`_ +for more information.
diff --git a/Help/variable/CMAKE_FASTBUILD_CACHE_PATH.rst b/Help/variable/CMAKE_FASTBUILD_CACHE_PATH.rst new file mode 100644 index 0000000..0bb0d94 --- /dev/null +++ b/Help/variable/CMAKE_FASTBUILD_CACHE_PATH.rst
@@ -0,0 +1,12 @@ +CMAKE_FASTBUILD_CACHE_PATH +-------------------------- + +.. versionadded:: 4.2 + +Specifies the directory for the FASTBuild artifact cache in the generated file. + +If not set, FASTBuild will use the ``FASTBUILD_CACHE_PATH`` environment +variable at build time. + +See the `FASTBuild caching documentation <https://www.fastbuild.org/docs/features/caching.html>`_ +for more information.
diff --git a/Help/variable/CMAKE_FASTBUILD_CAPTURE_SYSTEM_ENV.rst b/Help/variable/CMAKE_FASTBUILD_CAPTURE_SYSTEM_ENV.rst new file mode 100644 index 0000000..c415984 --- /dev/null +++ b/Help/variable/CMAKE_FASTBUILD_CAPTURE_SYSTEM_ENV.rst
@@ -0,0 +1,15 @@ +CMAKE_FASTBUILD_CAPTURE_SYSTEM_ENV +---------------------------------- + +.. versionadded:: 4.2 + +Controls capturing of the system environment into ``fbuild.bff``. +Setting it to ``OFF`` makes the invocation of all tools (compilers and other external processes) hermetic. + +.. note:: + + Setting this variable to ``OFF`` can break MSVC toolchains that rely on + environment variables such as ``INCLUDE`` or ``LIB`` unless these are + manually configured elsewhere. + +Defaults to ``ON``.
diff --git a/Help/variable/CMAKE_FASTBUILD_CLANG_GCC_UPDATE_XLANG_ARG.rst b/Help/variable/CMAKE_FASTBUILD_CLANG_GCC_UPDATE_XLANG_ARG.rst new file mode 100644 index 0000000..0552d90 --- /dev/null +++ b/Help/variable/CMAKE_FASTBUILD_CLANG_GCC_UPDATE_XLANG_ARG.rst
@@ -0,0 +1,9 @@ +CMAKE_FASTBUILD_CLANG_GCC_UPDATE_XLANG_ARG +------------------------------------------ + +.. versionadded:: 4.2 + +Enables FASTBuild's ``ClangGCCUpdateXLanguageArg`` option. + +See the `FASTBuild Compiler() documentation <https://www.fastbuild.org/docs/functions/compiler.html>`_ +for more information.
diff --git a/Help/variable/CMAKE_FASTBUILD_CLANG_REWRITE_INCLUDES.rst b/Help/variable/CMAKE_FASTBUILD_CLANG_REWRITE_INCLUDES.rst new file mode 100644 index 0000000..4be7b2e --- /dev/null +++ b/Help/variable/CMAKE_FASTBUILD_CLANG_REWRITE_INCLUDES.rst
@@ -0,0 +1,9 @@ +CMAKE_FASTBUILD_CLANG_REWRITE_INCLUDES +-------------------------------------- + +.. versionadded:: 4.2 + +Enables FASTBuild's ``ClangRewriteIncludes`` option. + +See the `FASTBuild Compiler() documentation <https://www.fastbuild.org/docs/functions/compiler.html>`_ +for more information.
diff --git a/Help/variable/CMAKE_FASTBUILD_COMPILER_EXTRA_FILES.rst b/Help/variable/CMAKE_FASTBUILD_COMPILER_EXTRA_FILES.rst new file mode 100644 index 0000000..86c6172 --- /dev/null +++ b/Help/variable/CMAKE_FASTBUILD_COMPILER_EXTRA_FILES.rst
@@ -0,0 +1,10 @@ +CMAKE_FASTBUILD_COMPILER_EXTRA_FILES +------------------------------------- + +.. versionadded:: 4.2 + +Specifies a semicolon-separated list of additional files (usually DLLs) to +include in the FASTBuild ``Compiler()`` node. + +See the `FASTBuild Compiler() documentation <https://www.fastbuild.org/docs/functions/compiler.html>`_ +for more information.
diff --git a/Help/variable/CMAKE_FASTBUILD_ENV_OVERRIDES.rst b/Help/variable/CMAKE_FASTBUILD_ENV_OVERRIDES.rst new file mode 100644 index 0000000..d469409 --- /dev/null +++ b/Help/variable/CMAKE_FASTBUILD_ENV_OVERRIDES.rst
@@ -0,0 +1,32 @@ +CMAKE_FASTBUILD_ENV_OVERRIDES +----------------------------- + +.. versionadded:: 4.2 + +Allows overriding environment variables in the captured environment written to +``fbuild.bff``. + +Specify a CMake-style list of key=value pairs. These values will override the +corresponding variables in the environment block that FASTBuild uses during +execution of tools (e.g., compilers, linkers, resource compilers, etc.). + +This is especially useful for ensuring consistent behavior when tools depend +on environment variables (e.g., overriding ``PATH`` to control tool resolution +for ``rc.exe`` or ``mt.exe``). + +Example: + +.. code-block:: cmake + + set(CMAKE_FASTBUILD_ENV_OVERRIDES + "PATH=C:/MyTools/bin" + "TMP=C:/temp" + "MY_CUSTOM_VAR=some_value" + ) + +.. note:: + + This only affects the environment seen by FASTBuild-generated rules. + It does **not** modify the environment in which CMake itself runs. + +Defaults to empty (no overrides).
diff --git a/Help/variable/CMAKE_FASTBUILD_FORCE_RESPONSE_FILE.rst b/Help/variable/CMAKE_FASTBUILD_FORCE_RESPONSE_FILE.rst new file mode 100644 index 0000000..04bae8e --- /dev/null +++ b/Help/variable/CMAKE_FASTBUILD_FORCE_RESPONSE_FILE.rst
@@ -0,0 +1,9 @@ +CMAKE_FASTBUILD_FORCE_RESPONSE_FILE +----------------------------------- + +.. versionadded:: 4.2 + +Enables FASTBuild's ``ForceResponseFile`` option. + +See the `FASTBuild Compiler() documentation <https://www.fastbuild.org/docs/functions/compiler.html>`_ +for more information.
diff --git a/Help/variable/CMAKE_FASTBUILD_IDE_ARGS.rst b/Help/variable/CMAKE_FASTBUILD_IDE_ARGS.rst new file mode 100644 index 0000000..a594bb3 --- /dev/null +++ b/Help/variable/CMAKE_FASTBUILD_IDE_ARGS.rst
@@ -0,0 +1,17 @@ +CMAKE_FASTBUILD_IDE_ARGS +------------------------ + +.. versionadded:: 4.2 + +Specifies the command-line arguments used when invoking ``fbuild`` from IDE +projects. + +If not set, the following arguments are used:: + + -ide -cache -summary -dist + +Example: + +.. code-block:: cmake + + set(CMAKE_FASTBUILD_IDE_ARGS "-ide -cache -summary -dist -clean")
diff --git a/Help/variable/CMAKE_FASTBUILD_SOURCE_MAPPING.rst b/Help/variable/CMAKE_FASTBUILD_SOURCE_MAPPING.rst new file mode 100644 index 0000000..69cd9f2 --- /dev/null +++ b/Help/variable/CMAKE_FASTBUILD_SOURCE_MAPPING.rst
@@ -0,0 +1,15 @@ +CMAKE_FASTBUILD_SOURCE_MAPPING +------------------------------ + +.. versionadded:: 4.2 + +Sets FASTBuild's ``SourceMapping_Experimental`` option. + +Example: + +.. code-block:: cmake + + set(CMAKE_FASTBUILD_SOURCE_MAPPING "/another/root") + +See the `FASTBuild Compiler() documentation <https://www.fastbuild.org/docs/functions/compiler.html>`_ +for more information.
diff --git a/Help/variable/CMAKE_FASTBUILD_TRACK_BYPRODUCTS_AS_OUTPUT.rst b/Help/variable/CMAKE_FASTBUILD_TRACK_BYPRODUCTS_AS_OUTPUT.rst new file mode 100644 index 0000000..07da28d --- /dev/null +++ b/Help/variable/CMAKE_FASTBUILD_TRACK_BYPRODUCTS_AS_OUTPUT.rst
@@ -0,0 +1,17 @@ +CMAKE_FASTBUILD_TRACK_BYPRODUCTS_AS_OUTPUT +------------------------------------------ + +.. versionadded:: 4.2 + +By default, custom commands declaring only ``BYPRODUCTS`` will always +run unconditionally. +You can use this variable to make FASTBuild rerun the command only when its +inputs have changed or the byproduct file is missing. + +.. note:: + + When this variable is ``OFF`` (the default), ``BYPRODUCTS`` are treated + similarly to how Ninja handles them — as opaque side effects — and the + generator emits ``ExecAlways`` nodes to ensure they always run. + +Defaults to ``OFF``.
diff --git a/Help/variable/CMAKE_FASTBUILD_USE_DETERMINISTIC_PATHS.rst b/Help/variable/CMAKE_FASTBUILD_USE_DETERMINISTIC_PATHS.rst new file mode 100644 index 0000000..cf2bc19 --- /dev/null +++ b/Help/variable/CMAKE_FASTBUILD_USE_DETERMINISTIC_PATHS.rst
@@ -0,0 +1,9 @@ +CMAKE_FASTBUILD_USE_DETERMINISTIC_PATHS +--------------------------------------- + +.. versionadded:: 4.2 + +Enables FASTBuild's ``UseDeterministicPaths_Experimental`` option. + +See the `FASTBuild Compiler() documentation <https://www.fastbuild.org/docs/functions/compiler.html>`_ +for more information.
diff --git a/Help/variable/CMAKE_FASTBUILD_USE_LIGHTCACHE.rst b/Help/variable/CMAKE_FASTBUILD_USE_LIGHTCACHE.rst new file mode 100644 index 0000000..e3498d9 --- /dev/null +++ b/Help/variable/CMAKE_FASTBUILD_USE_LIGHTCACHE.rst
@@ -0,0 +1,10 @@ +CMAKE_FASTBUILD_USE_LIGHTCACHE +------------------------------- + +.. versionadded:: 4.2 + +Enables FASTBuild’s *light caching* mode, which accelerates cache lookups by +parsing source files directly (instead of invoking the compiler preprocessor). + +See the `FASTBuild Compiler() documentation <https://www.fastbuild.org/docs/functions/compiler.html>`_ +for more information.
diff --git a/Help/variable/CMAKE_FASTBUILD_USE_RELATIVE_PATHS.rst b/Help/variable/CMAKE_FASTBUILD_USE_RELATIVE_PATHS.rst new file mode 100644 index 0000000..6fd5571 --- /dev/null +++ b/Help/variable/CMAKE_FASTBUILD_USE_RELATIVE_PATHS.rst
@@ -0,0 +1,9 @@ +CMAKE_FASTBUILD_USE_RELATIVE_PATHS +---------------------------------- + +.. versionadded:: 4.2 + +Enables FASTBuild's ``UseRelativePaths_Experimental`` option. + +See the `FASTBuild Compiler() documentation <https://www.fastbuild.org/docs/functions/compiler.html>`_ +for more information.
diff --git a/Help/variable/CMAKE_FASTBUILD_VERBOSE_GENERATOR.rst b/Help/variable/CMAKE_FASTBUILD_VERBOSE_GENERATOR.rst new file mode 100644 index 0000000..522ed05 --- /dev/null +++ b/Help/variable/CMAKE_FASTBUILD_VERBOSE_GENERATOR.rst
@@ -0,0 +1,11 @@ +CMAKE_FASTBUILD_VERBOSE_GENERATOR +---------------------------------- + +.. versionadded:: 4.2 + +Enables verbose logging during FASTBuild file generation. + +Initialized by the :envvar:`CMAKE_FASTBUILD_VERBOSE_GENERATOR` +environment variable. + +Defaults to ``OFF``.
diff --git a/Help/variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION.rst b/Help/variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION.rst index 92758fd..033748a 100644 --- a/Help/variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION.rst +++ b/Help/variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION.rst
@@ -3,16 +3,21 @@ .. versionadded:: 3.7 +.. versionchanged:: 4.2 + + The default sort direction has changed from ``DEC`` to ``ASC``. + + The sorting direction used by :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER`. It can assume one of the following values: ``ASC`` - Default. Ordering is done in ascending mode. + Ordering is done in ascending mode. The lowest folder found will be tested first. ``DEC`` - Ordering is done in descending mode. + Default. Ordering is done in descending mode. The highest folder found will be tested first. -If :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` is not set or is set to ``NONE`` -this variable has no effect. +If :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` is set to ``NONE`` this variable +has no effect.
diff --git a/Help/variable/CMAKE_FIND_PACKAGE_SORT_ORDER.rst b/Help/variable/CMAKE_FIND_PACKAGE_SORT_ORDER.rst index f1016d9..524b2ef 100644 --- a/Help/variable/CMAKE_FIND_PACKAGE_SORT_ORDER.rst +++ b/Help/variable/CMAKE_FIND_PACKAGE_SORT_ORDER.rst
@@ -3,39 +3,40 @@ .. versionadded:: 3.7 +.. versionchanged:: 4.2 + + The default sort order has changed from ``NONE`` to ``NATURAL``. + + The default order for sorting directories which match a search path containing a glob expression found using :command:`find_package`. It can assume one of the following values: ``NONE`` - Default. No attempt is done to sort directories. + No attempt is done to sort directories. The first valid package found will be selected. ``NAME`` Sort directories lexicographically before searching. ``NATURAL`` - Sort directories using natural order (see ``strverscmp(3)`` manual), + Default. Sort directories using natural order (see ``strverscmp(3)`` manual), i.e. such that contiguous digits are compared as whole numbers. -Natural sorting can be employed to return the highest version when multiple -versions of the same library are available to be found by -:command:`find_package`. For example suppose that the following libraries -have package configuration files on disk, in a directory of the same name, -with all such directories residing in the same parent directory: +Natural sorting is employed by default to return the highest version when +multiple versions of the same library are available to be found by +:command:`find_package`. For example suppose that the following libraries have +package configuration files on disk, in a directory of the same name, with all +such directories residing in the same parent directory: -* libX-1.1.0 -* libX-1.2.9 -* libX-1.2.10 +* ``libX-1.1.0`` +* ``libX-1.2.9`` +* ``libX-1.2.10`` -By setting ``NATURAL`` order we can select the one with the highest -version number ``libX-1.2.10``. - -.. code-block:: cmake - - set(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL) - find_package(libX CONFIG) +The default order of ``NATURAL`` will select the one with the highest version +number, i.e. ``libX-1.2.10``. The sort direction can be controlled using the -:variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION` variable -(by default descending, e.g. lib-B will be tested before lib-A). +:variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION` variable (by default descending, +i.e. ``libX-1.2`` will be tested before ``libX-1.0`` and ``lib-B`` will be +tested before ``lib-A``).
diff --git a/Help/variable/CMAKE_FIND_REQUIRED.rst b/Help/variable/CMAKE_FIND_REQUIRED.rst index 0518edb..cb3f4b1 100644 --- a/Help/variable/CMAKE_FIND_REQUIRED.rst +++ b/Help/variable/CMAKE_FIND_REQUIRED.rst
@@ -22,6 +22,6 @@ Multiple calls to :command:`find_package` are sometimes used to obtain a different search order to the default. -See also the :variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` for making -a :command:`find_package` call ``REQUIRED``, and for additional information on -how enabling these variables can break commonly used patterns. +See also the :variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` variable for +making a :command:`find_package` call ``REQUIRED``, and for additional +information on how enabling these variables can break commonly used patterns.
diff --git a/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst b/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst index 2bf5f05..6e2ecc3 100644 --- a/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst +++ b/Help/variable/CMAKE_GLOBAL_AUTOGEN_TARGET.rst
@@ -7,9 +7,10 @@ When ``CMAKE_GLOBAL_AUTOGEN_TARGET`` is enabled, a custom target ``autogen`` is generated. This target depends on all :prop_tgt:`AUTOMOC` and -:prop_tgt:`AUTOUIC` generated :ref:`<ORIGIN>_autogen` targets in the project. -By building the global ``autogen`` target, all :prop_tgt:`AUTOMOC` and -:prop_tgt:`AUTOUIC` files in the project will be generated. +:prop_tgt:`AUTOUIC` generated :ref:`<ORIGIN>_autogen <<ORIGIN>_autogen>` +targets in the project. By building the global ``autogen`` target, all +:prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` files in the project will be +generated. The name of the global ``autogen`` target can be changed by setting :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET_NAME`. @@ -21,7 +22,8 @@ .. note:: - :ref:`<ORIGIN>_autogen` targets by default inherit their origin target's - dependencies. This might result in unintended dependency target builds when - only :ref:`<ORIGIN>_autogen` targets are built. A solution is to disable - :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` on the respective origin targets. + :ref:`<ORIGIN>_autogen <<ORIGIN>_autogen>` targets by default inherit their + origin target's dependencies. This might result in unintended dependency + target builds when only :ref:`<ORIGIN>_autogen <<ORIGIN>_autogen>` targets + are built. A solution is to disable :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` on + the respective origin targets.
diff --git a/Help/variable/CMAKE_HIP_ARCHITECTURES.rst b/Help/variable/CMAKE_HIP_ARCHITECTURES.rst index 3f17983..96876b8 100644 --- a/Help/variable/CMAKE_HIP_ARCHITECTURES.rst +++ b/Help/variable/CMAKE_HIP_ARCHITECTURES.rst
@@ -12,5 +12,9 @@ Uses architectures reported by ``rocm_agent_enumerator``, if available, and otherwise to a default chosen by the compiler. +``spirv`` + Defaults to ``OFF``. The HIP package (e.g., chipStar) handles targeting + via its own configuration. + 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_PLATFORM.rst b/Help/variable/CMAKE_HIP_PLATFORM.rst index 5e3a2b7..82e1a03 100644 --- a/Help/variable/CMAKE_HIP_PLATFORM.rst +++ b/Help/variable/CMAKE_HIP_PLATFORM.rst
@@ -13,6 +13,11 @@ ``nvidia`` NVIDIA GPUs +``spirv`` + .. versionadded:: 4.3 + + SPIR-V target (e.g., chipStar) + If not specified, a default is computed via ``hipconfig --platform``. :variable:`CMAKE_HIP_ARCHITECTURES` entries are interpreted with
diff --git a/Help/variable/CMAKE_INSTALL_EXPORTS_AS_PACKAGE_INFO.rst b/Help/variable/CMAKE_INSTALL_EXPORTS_AS_PACKAGE_INFO.rst new file mode 100644 index 0000000..9ddd449 --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_EXPORTS_AS_PACKAGE_INFO.rst
@@ -0,0 +1,124 @@ +CMAKE_INSTALL_EXPORTS_AS_PACKAGE_INFO +------------------------------------- + +.. versionadded:: 4.3 + +.. note:: + + This variable is meaningful only when experimental support has been enabled + by the ``CMAKE_EXPERIMENTAL_FIXME`` gate. + +A list of directives instructing CMake to install |CPS| package information +when exported target information is installed via :command:`install(EXPORT)`. +The value is treated as a list, with each directive having the form:: + + <export-name>:<package-name>[/[l][a<appendix-name>][/<destination>]] + +Slashes are used to separate different components of the directive. + +Note that this feature is intended for package distributors, and should +**only** be used when editing a project's CMake script is not feasible. +Developers should use :command:`install(PACKAGE_INFO)` directly. + +Additionally, because ``CMAKE_INSTALL_EXPORTS_AS_PACKAGE_INFO`` functions by +emulating a call to :command:`install(PACKAGE_INFO)`, using it with a project +that is already calling :command:`install(PACKAGE_INFO)` directly may result +in conflicting installation directives, which will usually cause the project's +configure step to fail. + +The meaning of the values is as follows: + +``<export-name>`` + Name of the export for which package information should be installed. + +``<package-name>`` + Name of the package for which to generate package information. This is also + the name that users would use in a :command:`find_package` call. + +``l`` + Optional. Specifies that the name of the package information file on disk + should be lower case. See the ``LOWER_CASE_FILE`` option of + :command:`install(PACKAGE_INFO)`. + +``a<appendix-name>`` + Optional. Specifies that an appendix ``<appendix-name>`` should be created + rather than a root package description. See the ``APPENDIX`` option of + :command:`install(PACKAGE_INFO)`. Note that additional information + (see below) cannot be added to appendices. + +``<destination>`` + Optional. Specifies the destination to which the package information file + should be installed. See the ``DESTINATION`` option of + :command:`install(PACKAGE_INFO)`. Note that the default is a + platform-specific location that is appropriate for |CPS| files in most + instances, *not* the ``DESTINATION`` of the :command:`install(EXPORT)` + which the directive matched. + +For non-appendices, CMake will also infer additional information from several +CMake variables of the form ``<export-name>_EXPORT_PACKAGE_INFO_<var>``. The +values of these are first processed as if by :command:`string(CONFIGURE)` with +the ``@ONLY`` option. These are optional, and their effect is equivalent to +passing their value to the ``<var>`` option of the +:command:`install(PACKAGE_INFO)` command. + +The additional variables are: + + * ``<export-name>_EXPORT_PACKAGE_INFO_VERSION`` + * ``<export-name>_EXPORT_PACKAGE_INFO_COMPAT_VERSION`` + * ``<export-name>_EXPORT_PACKAGE_INFO_VERSION_SCHEMA`` + * ``<export-name>_EXPORT_PACKAGE_INFO_LICENSE`` + * ``<export-name>_EXPORT_PACKAGE_INFO_DEFAULT_LICENSE`` + * ``<export-name>_EXPORT_PACKAGE_INFO_DEFAULT_CONFIGURATIONS`` + +Ideally, the version should be set to ``@PROJECT_VERSION@``. However, +some projects may not use the ``VERSION`` option of the :command:`project` +command. + +Example +^^^^^^^ + +Consider the following (simplified) project: + +.. code-block:: cmake + + project(Example VERSION 1.2.3 SPDX_LICENSE "BSD-3-Clause") + + add_library(foo ...) + add_library(bar ...) + + install(TARGETS foo EXPORT required-targets) + install(TARGETS bar EXPORT optional-targets) + + install(EXPORT required-targets FILE example-targets.cmake ...) + install(EXPORT optional-targets FILE example-optional-targets.cmake ...) + +In this example, let ``example-targets.cmake`` be a file which is always +installed, and ``example-optional-targets.cmake`` be a file which is +optionally installed (e.g. is distributed as part of a separate package which +depends on the 'base' package). + +Now, imagine we are a distributor that wants to make |CPS| package information +files available to our users, but we do not want to modify the project's build +files. We can do this by passing the following arguments to CMake: + +.. code-block:: + + -DCMAKE_EXPERIMENTAL_FIXME=<elided> + -DCMAKE_INSTALL_EXPORTS_AS_PACKAGE_INFO=\ + required-targets:Example/l;\ + optional-targets:Example/laoptional + -Drequired-targets_EXPORT_PACKAGE_INFO_VERSION=@Example_VERSION@ + -Drequired-targets_EXPORT_PACKAGE_INFO_LICENSE=@Example_SPDX_LICENSE@ + +(Whitespace and line continuation characters, added for readability, should +be removed in real usage. Arguments may need to be quoted to prevent being +reinterpreted by the command shell.) + +This will cause CMake to also create and install the files ``example.cps`` and +``example-optional.cps`` which describe the ``Example`` package. We could +also specify the version and license information using substitutions provided +by the package build system (e.g. rpm, dpkg) if the project does not provide +this information via the :command:`project` command. + +.. _CPS: https://cps-org.github.io/cps/ +.. |CPS| replace:: Common Package Specification
diff --git a/Help/variable/CMAKE_INSTALL_OBJECT_NAME_STRATEGY.rst b/Help/variable/CMAKE_INSTALL_OBJECT_NAME_STRATEGY.rst new file mode 100644 index 0000000..4c71d73 --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_OBJECT_NAME_STRATEGY.rst
@@ -0,0 +1,10 @@ +CMAKE_INSTALL_OBJECT_NAME_STRATEGY +---------------------------------- + +.. versionadded:: 4.2 + +Strategy to use for naming installed object files. + +``CMAKE_INSTALL_OBJECT_NAME_STRATEGY`` is used to initialize the +:prop_tgt:`INSTALL_OBJECT_NAME_STRATEGY` property on all targets. See that +target property for more information.
diff --git a/Help/variable/CMAKE_INSTALL_OBJECT_ONLY_USE_DESTINATION.rst b/Help/variable/CMAKE_INSTALL_OBJECT_ONLY_USE_DESTINATION.rst new file mode 100644 index 0000000..cb5fa56 --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_OBJECT_ONLY_USE_DESTINATION.rst
@@ -0,0 +1,11 @@ +CMAKE_INSTALL_OBJECT_ONLY_USE_DESTINATION +----------------------------------------- + +.. versionadded:: 4.2 + +Controls whether the ``install(DESTINATION)`` for object libraries is used +as-is or supplemented with conflict-avoiding subdirectories. + +``CMAKE_INSTALL_OBJECT_ONLY_USE_DESTINATION`` is used to initialize the +:prop_tgt:`INSTALL_OBJECT_ONLY_USE_DESTINATION` property on all targets. See +that target property for more information.
diff --git a/Help/variable/CMAKE_INSTALL_PREFIX.rst b/Help/variable/CMAKE_INSTALL_PREFIX.rst index ce7cb8b..340bc35 100644 --- a/Help/variable/CMAKE_INSTALL_PREFIX.rst +++ b/Help/variable/CMAKE_INSTALL_PREFIX.rst
@@ -45,3 +45,21 @@ .. code-block:: shell cmake --install . --prefix /my/install/prefix + +.. note:: + + When the project is using the :module:`GNUInstallDirs` module, there are + some :ref:`special cases <GNUInstallDirs special cases>` that are + evaluated based on the value of the :variable:`CMAKE_INSTALL_PREFIX` + variable during the configuration phase. The results persist even + if an alternative :option:`--prefix <cmake--install --prefix>` option + is used during installation. + +See Also +^^^^^^^^ + +* The :option:`--install-prefix <cmake --install-prefix>` option. +* The :genex:`$<INSTALL_PREFIX>` generator expression. +* The :ref:`installDir <CMakePresets installDir>` field in CMake configure + presets. +* The :variable:`CPACK_PACKAGING_INSTALL_PREFIX` variable.
diff --git a/Help/variable/CMAKE_INTERMEDIATE_DIR_STRATEGY.rst b/Help/variable/CMAKE_INTERMEDIATE_DIR_STRATEGY.rst new file mode 100644 index 0000000..1d26ffd --- /dev/null +++ b/Help/variable/CMAKE_INTERMEDIATE_DIR_STRATEGY.rst
@@ -0,0 +1,35 @@ +CMAKE_INTERMEDIATE_DIR_STRATEGY +------------------------------- + +.. versionadded:: 4.2 + +``CMAKE_INTERMEDIATE_DIR_STRATEGY`` is a string cache variable specifying the +strategy to use for target intermediate directories and their contents. The +supported values are: + +- ``FULL``: Intermediate directories are named based on a + ``<TARGET_NAME>.dir`` pattern (with some slight deviations and sanitizations + applied in various places). Object file names are based on the filename of + the source file being compiled or, if set, its :prop_sf:`OBJECT_NAME` + property. +- ``SHORT``: Intermediate directories are named from the hash of the target + name and the build directory location. Object file names are based on hashes + of the source file name to reduce path lengths. This may help with projects + that generate long paths in the build directory to support building in + directories other than those near a root path. + +When unset or the named strategy is not supported, the ``FULL`` strategy is +used. + +.. note:: + This only works as a cache variable, not a locally-scoped variable. + +This is supported by the following generators: + +- :ref:`Ninja Generators` +- :ref:`Makefile Generators` +- :ref:`Visual Studio Generators` + +.. note:: + Not all generators support all strategies and paths may differ between + generators.
diff --git a/Help/variable/CMAKE_LANG_BYTE_ORDER.rst b/Help/variable/CMAKE_LANG_BYTE_ORDER.rst index 78f0ae6..da60af6 100644 --- a/Help/variable/CMAKE_LANG_BYTE_ORDER.rst +++ b/Help/variable/CMAKE_LANG_BYTE_ORDER.rst
@@ -18,3 +18,78 @@ If :variable:`CMAKE_OSX_ARCHITECTURES` specifies multiple architectures, the value of ``CMAKE_<LANG>_BYTE_ORDER`` is non-empty only if all architectures share the same byte order. + +Examples +^^^^^^^^ + +Example: Checking Endianness +"""""""""""""""""""""""""""" + +Checking endianness (byte order) of the target architecture in a CMake +project, where ``C`` language is one of the enabled languages, and storing +the result in a variable ``WORDS_BIGENDIAN``: + +.. code-block:: cmake + + if(CMAKE_C_BYTE_ORDER STREQUAL "BIG_ENDIAN") + set(WORDS_BIGENDIAN TRUE) + elseif(CMAKE_C_BYTE_ORDER STREQUAL "LITTLE_ENDIAN") + set(WORDS_BIGENDIAN FALSE) + else() + set(WORDS_BIGENDIAN FALSE) + message(WARNING "Endianness could not be determined.") + endif() + +Or, if the project doesn't have ``C`` language enabled, it can be replaced +with some other enabled language. For example, if ``CXX`` is enabled: + +.. code-block:: cmake + + if(CMAKE_CXX_BYTE_ORDER STREQUAL "BIG_ENDIAN") + set(WORDS_BIGENDIAN TRUE) + elseif(CMAKE_CXX_BYTE_ORDER STREQUAL "LITTLE_ENDIAN") + set(WORDS_BIGENDIAN FALSE) + else() + set(WORDS_BIGENDIAN FALSE) + message(WARNING "Endianness could not be determined.") + endif() + +Note, that in most cases this can be simplified by only checking for a +big-endian target: + +.. code-block:: cmake + + if(CMAKE_C_BYTE_ORDER STREQUAL "BIG_ENDIAN") + set(WORDS_BIGENDIAN TRUE) + else() + set(WORDS_BIGENDIAN FALSE) + endif() + +Example: Per-language Endianness Check +"""""""""""""""""""""""""""""""""""""" + +Most of the time, architectures used today are consistent in endianness +across compilers. But here's when per-language endianness check can matter: + +* Cross-compilation to different architectures (e.g., big-endian embedded + system). + +* Heterogeneous toolchains where one target architecture is for C language + and another target is for different language. + +* Static libraries or binaries reused across platforms (e.g., distributing + precompiled CUDA kernels). + +.. code-block:: cmake + + if(CMAKE_C_BYTE_ORDER) + message(STATUS "C byte order: ${CMAKE_C_BYTE_ORDER}") + endif() + + if(CMAKE_CXX_BYTE_ORDER) + message(STATUS "C++ byte order: ${CMAKE_CXX_BYTE_ORDER}") + endif() + + if(CMAKE_CUDA_BYTE_ORDER) + message(STATUS "CUDA byte order: ${CMAKE_CUDA_BYTE_ORDER}") + endif()
diff --git a/Help/variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID.rst b/Help/variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID.rst index 1efbf1c..c6853e3 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID.rst
@@ -123,6 +123,15 @@ ``sparcv9`` SPARC 64-bit +``sw_64`` + Sunway + +``wasm32`` + WebAssembly (Emscripten) 32-bit + +``wasm64`` + WebAssembly (Emscripten) 64-bit + ``x86_64`` Intel 64-bit
diff --git a/Help/variable/CMAKE_LANG_LINK_FLAGS.rst b/Help/variable/CMAKE_LANG_LINK_FLAGS.rst new file mode 100644 index 0000000..9e2c45c --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_FLAGS.rst
@@ -0,0 +1,38 @@ +CMAKE_<LANG>_LINK_FLAGS +----------------------- + +.. versionadded:: 4.3 + +Language-wide flags for language ``<LANG>`` used when linking for all +configurations. These flags will be passed to all invocations of the compiler +which drive linking. + +The flags in this variable will obey the following behavior with respect to +ordering of flags from other variables. + +* They will be passed after those added by :variable:`CMAKE_<LANG>_FLAGS` and + :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`. +* They will be passed after those added by :variable:`CMAKE_EXE_LINKER_FLAGS`, + :variable:`CMAKE_EXE_LINKER_FLAGS_<CONFIG>`, + :variable:`CMAKE_SHARED_LINKER_FLAGS`, + :variable:`CMAKE_SHARED_LINKER_FLAGS_<CONFIG>`, + :variable:`CMAKE_MODULE_LINKER_FLAGS`, + and :variable:`CMAKE_MODULE_LINKER_FLAGS_<CONFIG>` depending on the given + target type. +* They will be passed before those added by + :variable:`CMAKE_<LANG>_LINK_FLAGS_<CONFIG>`. +* They will be passed before those added by commands such + as :command:`add_link_options` and :command:`target_link_options`. + +Use of this variable is enabled when policy :policy:`CMP0210` is ``NEW``. + +.. include:: ../command/include/LINK_LIBRARIES_LINKER.rst + +This support implies to parse and re-quote the content of the variable. + +See Also +^^^^^^^^ + +* :variable:`CMAKE_<LANG>_LINK_FLAGS_<CONFIG>` +* :variable:`CMAKE_<LANG>_FLAGS` +* :policy:`CMP0210`
diff --git a/Help/variable/CMAKE_LANG_LINK_FLAGS_CONFIG.rst b/Help/variable/CMAKE_LANG_LINK_FLAGS_CONFIG.rst new file mode 100644 index 0000000..c0c517b --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_FLAGS_CONFIG.rst
@@ -0,0 +1,23 @@ +CMAKE_<LANG>_LINK_FLAGS_<CONFIG> +-------------------------------- + +.. versionadded:: 4.3 + +Language-wide flags for language ``<LANG>`` used when linking for the +``<CONFIG>`` configuration. These flags will be passed to all invocations of +the compiler which drive linking. + +See :variable:`CMAKE_<LANG>_LINK_FLAGS` for the ordering of these flags with +respect to other variables. Notably, flags in +``CMAKE_<LANG>_LINK_FLAGS_<CONFIG>`` are passed after those in +:variable:`CMAKE_<LANG>_LINK_FLAGS`. + +.. include:: ../command/include/LINK_LIBRARIES_LINKER.rst + +This support implies to parse and re-quote the content of the variable. + +See Also +^^^^^^^^ + +* :variable:`CMAKE_<LANG>_LINK_FLAGS` +* :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`
diff --git a/Help/variable/CMAKE_LANG_LINK_MODE.rst b/Help/variable/CMAKE_LANG_LINK_MODE.rst index 6025671..f8286e4 100644 --- a/Help/variable/CMAKE_LANG_LINK_MODE.rst +++ b/Help/variable/CMAKE_LANG_LINK_MODE.rst
@@ -12,3 +12,8 @@ The linker is used directly for the link step. This variable is read-only. Setting it is undefined behavior. + +See Also +^^^^^^^^ + +* The :variable:`CMAKE_<LANG>_USING_LINKER_<TYPE>` variable.
diff --git a/Help/variable/CMAKE_LANG_PVS_STUDIO.rst b/Help/variable/CMAKE_LANG_PVS_STUDIO.rst new file mode 100644 index 0000000..5128080 --- /dev/null +++ b/Help/variable/CMAKE_LANG_PVS_STUDIO.rst
@@ -0,0 +1,15 @@ +CMAKE_<LANG>_PVS_STUDIO +----------------------- + +.. versionadded:: 4.3 + +Default value for :prop_tgt:`<LANG>_PVS_STUDIO` target property +when ``<LANG>`` is ``C`` or ``CXX``. + +This variable is used to initialize the property on each target as it is +created. For example: + +.. code-block:: cmake + + set(CMAKE_CXX_PVS_STUDIO pvs-studio-analyzer analyze -a "GA\;OP") + add_executable(foo foo.cxx)
diff --git a/Help/variable/CMAKE_LANG_USING_LINKER_MODE.rst b/Help/variable/CMAKE_LANG_USING_LINKER_MODE.rst index 7b252aa..a3d6c97 100644 --- a/Help/variable/CMAKE_LANG_USING_LINKER_MODE.rst +++ b/Help/variable/CMAKE_LANG_USING_LINKER_MODE.rst
@@ -1,10 +1,17 @@ CMAKE_<LANG>_USING_LINKER_MODE ------------------------------ +.. deprecated:: 4.0 + + This variable is no longer used. The type of information stored in the + :variable:`CMAKE_<LANG>_USING_LINKER_<TYPE>` variable is determined by + the :variable:`CMAKE_<LANG>_LINK_MODE` variable. + .. versionadded:: 3.29 -This controls how the value of the :variable:`CMAKE_<LANG>_USING_LINKER_<TYPE>` -variable should be interpreted. The supported linker mode values are: +This variable controls how the value of the +:variable:`CMAKE_<LANG>_USING_LINKER_<TYPE>` variable should be interpreted. +The supported linker mode values are: ``FLAG`` :variable:`CMAKE_<LANG>_USING_LINKER_<TYPE>` holds a @@ -22,11 +29,5 @@ * value ``TOOL`` is expected and required when the linker is used directly for the link step. - * value ``FLAGS`` is expected or the variable not set when the compiler is + * value ``FLAG`` is expected or the variable not set when the compiler is used as driver for the link step. - -.. deprecated:: 4.0 - -This variable is no longer used. The type of information stored in the -:variable:`CMAKE_<LANG>_USING_LINKER_<TYPE>` variable is determined by the -:variable:`CMAKE_<LANG>_LINK_MODE` variable.
diff --git a/Help/variable/CMAKE_MODULE_LINKER_FLAGS.rst b/Help/variable/CMAKE_MODULE_LINKER_FLAGS.rst index e74b6ee..5e7797f 100644 --- a/Help/variable/CMAKE_MODULE_LINKER_FLAGS.rst +++ b/Help/variable/CMAKE_MODULE_LINKER_FLAGS.rst
@@ -3,6 +3,12 @@ Linker flags to be used to create modules. -These flags will be used by the linker when creating a module. +These flags will be used by the linker when creating a module for all build +configurations. .. include:: ../variable/include/LINKER_FLAGS.rst + +See Also +^^^^^^^^ + +* :variable:`CMAKE_MODULE_LINKER_FLAGS_<CONFIG>`
diff --git a/Help/variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG.rst b/Help/variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG.rst index 693565a..864c45b 100644 --- a/Help/variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG.rst +++ b/Help/variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG.rst
@@ -3,6 +3,12 @@ Flags to be used when linking a module. -Same as ``CMAKE_C_FLAGS_*`` but used by the linker when creating modules. +These flags will be used by the linker when creating a module for the +``<CONFIG>`` configuration. .. include:: ../variable/include/LINKER_FLAGS.rst + +See Also +^^^^^^^^ + +* :variable:`CMAKE_MODULE_LINKER_FLAGS`
diff --git a/Help/variable/CMAKE_OSX_ARCHITECTURES.rst b/Help/variable/CMAKE_OSX_ARCHITECTURES.rst index f660df9..3e9e427 100644 --- a/Help/variable/CMAKE_OSX_ARCHITECTURES.rst +++ b/Help/variable/CMAKE_OSX_ARCHITECTURES.rst
@@ -7,4 +7,8 @@ property on each target as it is created. See that target property for additional information. +If ``CMAKE_OSX_ARCHITECTURES`` is not set, the compiler's default target +architecture is used. For compilers provided by Xcode, this is the host +machine's architecture. + .. include:: include/CMAKE_OSX_VARIABLE.rst
diff --git a/Help/variable/CMAKE_PARENT_LIST_FILE.rst b/Help/variable/CMAKE_PARENT_LIST_FILE.rst index 7e71efa..c0c6469 100644 --- a/Help/variable/CMAKE_PARENT_LIST_FILE.rst +++ b/Help/variable/CMAKE_PARENT_LIST_FILE.rst
@@ -8,7 +8,8 @@ including it. While processing a ``CMakeLists.txt`` file, even in subdirectories, -this variable has the same value as :variable:`CMAKE_CURRENT_LIST_FILE`. +this variable is not defined. See policy :policy:`CMP0198`. + While processing a :option:`cmake -P` script, this variable is not defined in the outermost script.
diff --git a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst index 3a9605f..1197560 100644 --- a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst +++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst
@@ -40,6 +40,8 @@ policy :policy:`CMP0133`. * ``CMAKE_POLICY_WARNING_CMP0172`` controls the warning for policy :policy:`CMP0172`. +* ``CMAKE_POLICY_WARNING_CMP0206`` controls the warning for + policy :policy:`CMP0206`. 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_POSITION_INDEPENDENT_CODE.rst b/Help/variable/CMAKE_POSITION_INDEPENDENT_CODE.rst index f83246a..19f5e57 100644 --- a/Help/variable/CMAKE_POSITION_INDEPENDENT_CODE.rst +++ b/Help/variable/CMAKE_POSITION_INDEPENDENT_CODE.rst
@@ -1,9 +1,19 @@ CMAKE_POSITION_INDEPENDENT_CODE ------------------------------- -Default value for :prop_tgt:`POSITION_INDEPENDENT_CODE` of targets. +Default value for the :prop_tgt:`POSITION_INDEPENDENT_CODE` target property. This variable is used to initialize the :prop_tgt:`POSITION_INDEPENDENT_CODE` property on targets that are not ``SHARED`` or ``MODULE`` library targets. If set, its value is also used by the :command:`try_compile` command. + +The ``SHARED`` and ``MODULE`` library targets have by default position +independent code enabled regardless of this variable. To disable PIC on +these library types, only manually setting the target property disables it. + +See Also +^^^^^^^^ + +* The :module:`CheckPIESupported` module to pass PIE-related options to the + linker for executables.
diff --git a/Help/variable/CMAKE_PROJECT_COMPAT_VERSION.rst b/Help/variable/CMAKE_PROJECT_COMPAT_VERSION.rst index e32d381..1b5e96a 100644 --- a/Help/variable/CMAKE_PROJECT_COMPAT_VERSION.rst +++ b/Help/variable/CMAKE_PROJECT_COMPAT_VERSION.rst
@@ -1,24 +1,20 @@ CMAKE_PROJECT_COMPAT_VERSION ---------------------------- -.. versionadded:: 4.1 - -.. note:: - - Experimental. Gated by ``CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_INFO``. +.. versionadded:: 4.3 The compatibility version of the top level project. -This variable holds the compatibility version of the project as specified in the -top level CMakeLists.txt file by a :command:`project` command. In the event -that the top level CMakeLists.txt contains multiple :command:`project` calls, -the most recently called one from that top level CMakeLists.txt will determine -the value that ``CMAKE_PROJECT_COMPAT_VERSION`` contains. For example, consider -the following top level CMakeLists.txt: +This variable holds the compatibility version of the project as specified in +the top level CMakeLists.txt file by a :command:`project` command. In the +event that the top level CMakeLists.txt contains multiple :command:`project` +calls, the most recently called one from that top level CMakeLists.txt will +determine the value that ``CMAKE_PROJECT_COMPAT_VERSION`` contains. For +example, consider the following top level CMakeLists.txt: .. code-block:: cmake - cmake_minimum_required(VERSION 4.1) + cmake_minimum_required(VERSION 4.3) project(First VERSION 9.0 COMPAT_VERSION 1.2.3) project(Second VERSION 9.0 COMPAT_VERSION 3.4.5) add_subdirectory(sub) @@ -36,6 +32,6 @@ CMAKE_PROJECT_COMPAT_VERSION = 3.4.5 -To obtain the version from the most recent call to :command:`project` in -the current directory scope or above, see the :variable:`PROJECT_COMPAT_VERSION` -variable. +To obtain the version from the most recent call to :command:`project` +in the current directory scope or above, see the +:variable:`PROJECT_COMPAT_VERSION` variable.
diff --git a/Help/variable/CMAKE_PROJECT_SPDX_LICENSE.rst b/Help/variable/CMAKE_PROJECT_SPDX_LICENSE.rst new file mode 100644 index 0000000..3164b7e --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_SPDX_LICENSE.rst
@@ -0,0 +1,37 @@ +CMAKE_PROJECT_SPDX_LICENSE +-------------------------- + +.. versionadded:: 4.3 + +The license(s) of the top level project. + +This variable holds the license expression of the project as specified in the +top level CMakeLists.txt file by a :command:`project` command. In the event +that the top level CMakeLists.txt contains multiple :command:`project` calls, +the most recently called one from that top level CMakeLists.txt will determine +the value that ``CMAKE_PROJECT_SPDX_LICENSE`` contains. For example, consider +the following top level CMakeLists.txt: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 4.3) + project(First SPDX_LICENSE "BSD-3-Clause") + project(Second SPDX_LICENSE "BSD-3-Clause AND CC-BY-SA-4.0") + add_subdirectory(sub) + project(Third SPDX_LICENSE "BSD-3-Clause AND CC0-1.0") + +And ``sub/CMakeLists.txt`` with the following contents: + +.. code-block:: cmake + + project(SubProj SPDX_LICENSE Apache-2.0) + message("CMAKE_PROJECT_SPDX_LICENSE = ${CMAKE_PROJECT_SPDX_LICENSE}") + +The most recently seen :command:`project` command from the top level +CMakeLists.txt would be ``project(Second ...)``, so this will print:: + + CMAKE_PROJECT_SPDX_LICENSE = BSD-3-Clause AND CC-BY-SA-4.0 + +To obtain the version from the most recent call to :command:`project` in +the current directory scope or above, see the :variable:`PROJECT_SPDX_LICENSE` +variable.
diff --git a/Help/variable/CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS.rst b/Help/variable/CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS.rst index 3e2c6df..07c99e2 100644 --- a/Help/variable/CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS.rst +++ b/Help/variable/CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS.rst
@@ -8,3 +8,8 @@ This variable is used to initialize the :prop_tgt:`ENABLE_EXPORTS` target property for shared library targets when they are created by calls to the :command:`add_library` command. See the property documentation for details. + +See Also +^^^^^^^^ + +* The :variable:`CMAKE_EXECUTABLE_ENABLE_EXPORTS` variable.
diff --git a/Help/variable/CMAKE_SHARED_LINKER_FLAGS.rst b/Help/variable/CMAKE_SHARED_LINKER_FLAGS.rst index 93c84ee..5a81879 100644 --- a/Help/variable/CMAKE_SHARED_LINKER_FLAGS.rst +++ b/Help/variable/CMAKE_SHARED_LINKER_FLAGS.rst
@@ -3,6 +3,12 @@ Linker flags to be used to create shared libraries. -These flags will be used by the linker when creating a shared library. +These flags will be used by the linker when creating a shared library for all +build configurations. .. include:: ../variable/include/LINKER_FLAGS.rst + +See Also +^^^^^^^^ + +* :variable:`CMAKE_SHARED_LINKER_FLAGS_<CONFIG>`
diff --git a/Help/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG.rst b/Help/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG.rst index d0eb4fd..51b276b 100644 --- a/Help/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG.rst +++ b/Help/variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG.rst
@@ -3,7 +3,12 @@ Flags to be used when linking a shared library. -Same as ``CMAKE_C_FLAGS_*`` but used by the linker when creating shared -libraries. +These flags will be used by the linker when creating a shared library for the +``<CONFIG>`` configuration. .. include:: ../variable/include/LINKER_FLAGS.rst + +See Also +^^^^^^^^ + +* :variable:`CMAKE_SHARED_LINKER_FLAGS`
diff --git a/Help/variable/CMAKE_SKIP_LINTING.rst b/Help/variable/CMAKE_SKIP_LINTING.rst new file mode 100644 index 0000000..72fe635 --- /dev/null +++ b/Help/variable/CMAKE_SKIP_LINTING.rst
@@ -0,0 +1,9 @@ +CMAKE_SKIP_LINTING +------------------ + +.. versionadded:: 4.2 + +Default value for the :prop_tgt:`SKIP_LINTING` target property. + +This is used to initialize the :prop_tgt:`SKIP_LINTING` target property +for all targets created *afterward*.
diff --git a/Help/variable/CMAKE_SOURCE_DIR.rst b/Help/variable/CMAKE_SOURCE_DIR.rst index f1d1bee..be28f4d 100644 --- a/Help/variable/CMAKE_SOURCE_DIR.rst +++ b/Help/variable/CMAKE_SOURCE_DIR.rst
@@ -11,3 +11,5 @@ :variable:`CMAKE_BINARY_DIR`, ``CMAKE_SOURCE_DIR``, :variable:`CMAKE_CURRENT_BINARY_DIR` and :variable:`CMAKE_CURRENT_SOURCE_DIR` to the current working directory. + +Modifying ``CMAKE_SOURCE_DIR`` has undefined behavior.
diff --git a/Help/variable/CMAKE_SYSTEM_NAME.rst b/Help/variable/CMAKE_SYSTEM_NAME.rst index 41c1b78..de688b5 100644 --- a/Help/variable/CMAKE_SYSTEM_NAME.rst +++ b/Help/variable/CMAKE_SYSTEM_NAME.rst
@@ -104,3 +104,15 @@ * Cygwin's ``cmake`` package (``/usr/bin/cmake``) uses system name ``CYGWIN``. A non-cygwin CMake on Windows (e.g. ``$PROGRAMFILES/CMake/bin/cmake``) uses system name ``Windows`` even when it runs under a Cygwin environment. + +Removed Platforms +^^^^^^^^^^^^^^^^^ + +The following platforms were once supported by CMake and got removed either due +to platform's EOL, or other incompatibilities: + +========================= ===================================== ================ +Value Name Removed in CMake +========================= ===================================== ================ +``kFreeBSD`` FreeBSD kernel with a GNU userland 4.1 +========================= ===================================== ================
diff --git a/Help/variable/CMAKE_VERIFY_INTERFACE_HEADER_SETS.rst b/Help/variable/CMAKE_VERIFY_INTERFACE_HEADER_SETS.rst index 3fb8817..f0302ba 100644 --- a/Help/variable/CMAKE_VERIFY_INTERFACE_HEADER_SETS.rst +++ b/Help/variable/CMAKE_VERIFY_INTERFACE_HEADER_SETS.rst
@@ -3,37 +3,8 @@ .. versionadded:: 3.24 -This variable is used to initialize the -:prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` property of targets when they are -created. Setting it to true enables header set verification. - -Projects should not normally set this variable, it is intended as a developer -control to be set on the :manual:`cmake(1)` command line or other -equivalent methods. The developer must have the ability to enable or -disable header set verification according to the capabilities of their own -machine and compiler. - -Verification of a dependency's header sets is not typically of interest -to developers. Therefore, :command:`FetchContent_MakeAvailable` explicitly -sets ``CMAKE_VERIFY_INTERFACE_HEADER_SETS`` to false for the duration of its -call, but restores its original value before returning. If a project brings -a dependency directly into the main build (e.g. calling -:command:`add_subdirectory` on a vendored project from a git submodule), it -should also do likewise. For example: - -.. code:: cmake - - # Save original setting so we can restore it later - set(want_header_set_verification ${CMAKE_VERIFY_INTERFACE_HEADER_SETS}) - - # Include the vendored dependency with header set verification disabled - set(CMAKE_VERIFY_INTERFACE_HEADER_SETS OFF) - add_subdirectory(...) # Vendored sources, e.g. from git submodules - - # Add the project's own sources. Restore the developer's original choice - # for whether to enable header set verification. - set(CMAKE_VERIFY_INTERFACE_HEADER_SETS ${want_header_set_verification}) - add_subdirectory(src) - -By default, this variable is not set, which will result in header set -verification being disabled. +.. |VERIFY_XXX_HEADER_SETS| replace:: :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` +.. |CMAKE_VERIFY_XXX_HEADER_SETS| replace:: ``CMAKE_VERIFY_INTERFACE_HEADER_SETS`` +.. |COMPLEMENTARY_CMAKE_VERIFY_XXX_HEADER_SETS| replace:: :variable:`CMAKE_VERIFY_PRIVATE_HEADER_SETS` +.. |xxx| replace:: interface +.. include:: include/CMAKE_VERIFY_XXX_HEADER_SETS.rst
diff --git a/Help/variable/CMAKE_VERIFY_PRIVATE_HEADER_SETS.rst b/Help/variable/CMAKE_VERIFY_PRIVATE_HEADER_SETS.rst new file mode 100644 index 0000000..3dd15fa --- /dev/null +++ b/Help/variable/CMAKE_VERIFY_PRIVATE_HEADER_SETS.rst
@@ -0,0 +1,10 @@ +CMAKE_VERIFY_PRIVATE_HEADER_SETS +-------------------------------- + +.. versionadded:: 4.3 + +.. |VERIFY_XXX_HEADER_SETS| replace:: :prop_tgt:`VERIFY_PRIVATE_HEADER_SETS` +.. |CMAKE_VERIFY_XXX_HEADER_SETS| replace:: ``CMAKE_VERIFY_PRIVATE_HEADER_SETS`` +.. |COMPLEMENTARY_CMAKE_VERIFY_XXX_HEADER_SETS| replace:: :variable:`CMAKE_VERIFY_INTERFACE_HEADER_SETS` +.. |xxx| replace:: private +.. include:: include/CMAKE_VERIFY_XXX_HEADER_SETS.rst
diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_FORTRAN.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_FORTRAN.rst index c7e4148..afad4b2 100644 --- a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_FORTRAN.rst +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_FORTRAN.rst
@@ -9,4 +9,11 @@ that have the required Visual Studio Integration feature installed. The compiler may be specified by a field in :variable:`CMAKE_GENERATOR_TOOLSET` of the form ``fortran=...``. CMake provides the selected Fortran compiler in this -variable. The value may be empty if the field was not specified. +variable. + +If the field was not specified, the default depends on the generator: + +* On :generator:`Visual Studio 18 2026` and above, the default is ``ifx``. + +* On older :ref:`Visual Studio Generators`, the default is empty, which the + Intel Visual Studio Integration interprets as equivalent to ``ifort``.
diff --git a/Help/variable/CTEST_BINARY_DIRECTORY.rst b/Help/variable/CTEST_BINARY_DIRECTORY.rst index 8413e37..ec30f2d 100644 --- a/Help/variable/CTEST_BINARY_DIRECTORY.rst +++ b/Help/variable/CTEST_BINARY_DIRECTORY.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``BuildDirectory`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_BUILD_COMMAND.rst b/Help/variable/CTEST_BUILD_COMMAND.rst index 31c44e2..e4110c7 100644 --- a/Help/variable/CTEST_BUILD_COMMAND.rst +++ b/Help/variable/CTEST_BUILD_COMMAND.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``MakeCommand`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_BUILD_NAME.rst b/Help/variable/CTEST_BUILD_NAME.rst index 3d08397..d6b0636 100644 --- a/Help/variable/CTEST_BUILD_NAME.rst +++ b/Help/variable/CTEST_BUILD_NAME.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``BuildName`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_BZR_COMMAND.rst b/Help/variable/CTEST_BZR_COMMAND.rst index 0c05d1a..8927886 100644 --- a/Help/variable/CTEST_BZR_COMMAND.rst +++ b/Help/variable/CTEST_BZR_COMMAND.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``BZRCommand`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_BZR_UPDATE_OPTIONS.rst b/Help/variable/CTEST_BZR_UPDATE_OPTIONS.rst index 4dd5e5b..475dab2 100644 --- a/Help/variable/CTEST_BZR_UPDATE_OPTIONS.rst +++ b/Help/variable/CTEST_BZR_UPDATE_OPTIONS.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``BZRUpdateOptions`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_CHANGE_ID.rst b/Help/variable/CTEST_CHANGE_ID.rst index a6d15f7..5202020 100644 --- a/Help/variable/CTEST_CHANGE_ID.rst +++ b/Help/variable/CTEST_CHANGE_ID.rst
@@ -4,7 +4,7 @@ .. versionadded:: 3.4 Specify the CTest ``ChangeId`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script. This setting allows CTest to pass arbitrary information about this build up to CDash. One use of this feature is to allow CDash to
diff --git a/Help/variable/CTEST_CHECKOUT_COMMAND.rst b/Help/variable/CTEST_CHECKOUT_COMMAND.rst index 852c28e..2203d6b 100644 --- a/Help/variable/CTEST_CHECKOUT_COMMAND.rst +++ b/Help/variable/CTEST_CHECKOUT_COMMAND.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Tell the :command:`ctest_start` command how to checkout or initialize -the source directory in a :manual:`ctest(1)` dashboard client script. +the source directory in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_CONFIGURATION_TYPE.rst b/Help/variable/CTEST_CONFIGURATION_TYPE.rst index 932f81d..6ae4a34 100644 --- a/Help/variable/CTEST_CONFIGURATION_TYPE.rst +++ b/Help/variable/CTEST_CONFIGURATION_TYPE.rst
@@ -4,7 +4,7 @@ .. versionadded:: 3.1 Specify the CTest ``DefaultCTestConfigurationType`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script. If the configuration type is set via :option:`-C \<cfg\> <ctest -C>` from the command line then this variable is populated accordingly.
diff --git a/Help/variable/CTEST_CONFIGURE_COMMAND.rst b/Help/variable/CTEST_CONFIGURE_COMMAND.rst index 992ef47..90c50f4 100644 --- a/Help/variable/CTEST_CONFIGURE_COMMAND.rst +++ b/Help/variable/CTEST_CONFIGURE_COMMAND.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``ConfigureCommand`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_COVERAGE_COMMAND.rst b/Help/variable/CTEST_COVERAGE_COMMAND.rst index 3df2262..8168b33 100644 --- a/Help/variable/CTEST_COVERAGE_COMMAND.rst +++ b/Help/variable/CTEST_COVERAGE_COMMAND.rst
@@ -4,7 +4,7 @@ .. versionadded:: 3.1 Specify the CTest ``CoverageCommand`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script. Cobertura '''''''''
diff --git a/Help/variable/CTEST_COVERAGE_EXTRA_FLAGS.rst b/Help/variable/CTEST_COVERAGE_EXTRA_FLAGS.rst index 39d9b5d..bae5c79 100644 --- a/Help/variable/CTEST_COVERAGE_EXTRA_FLAGS.rst +++ b/Help/variable/CTEST_COVERAGE_EXTRA_FLAGS.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``CoverageExtraFlags`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_CURL_OPTIONS.rst b/Help/variable/CTEST_CURL_OPTIONS.rst index 45e84ed..07557e9 100644 --- a/Help/variable/CTEST_CURL_OPTIONS.rst +++ b/Help/variable/CTEST_CURL_OPTIONS.rst
@@ -8,4 +8,4 @@ .. versionadded:: 3.1 Specify the CTest ``CurlOptions`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_CVS_COMMAND.rst b/Help/variable/CTEST_CVS_COMMAND.rst index 7932070..797a4e7 100644 --- a/Help/variable/CTEST_CVS_COMMAND.rst +++ b/Help/variable/CTEST_CVS_COMMAND.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``CVSCommand`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_CVS_UPDATE_OPTIONS.rst b/Help/variable/CTEST_CVS_UPDATE_OPTIONS.rst index 359e708..6d9288a 100644 --- a/Help/variable/CTEST_CVS_UPDATE_OPTIONS.rst +++ b/Help/variable/CTEST_CVS_UPDATE_OPTIONS.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``CVSUpdateOptions`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_DROP_LOCATION.rst b/Help/variable/CTEST_DROP_LOCATION.rst index f66793b..3955193 100644 --- a/Help/variable/CTEST_DROP_LOCATION.rst +++ b/Help/variable/CTEST_DROP_LOCATION.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``DropLocation`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_DROP_METHOD.rst b/Help/variable/CTEST_DROP_METHOD.rst index 3a84658..6a0d0a7 100644 --- a/Help/variable/CTEST_DROP_METHOD.rst +++ b/Help/variable/CTEST_DROP_METHOD.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``DropMethod`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_DROP_SITE.rst b/Help/variable/CTEST_DROP_SITE.rst index 9c871e3..be64d72 100644 --- a/Help/variable/CTEST_DROP_SITE.rst +++ b/Help/variable/CTEST_DROP_SITE.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``DropSite`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_DROP_SITE_CDASH.rst b/Help/variable/CTEST_DROP_SITE_CDASH.rst index dcdb286..7d09a36 100644 --- a/Help/variable/CTEST_DROP_SITE_CDASH.rst +++ b/Help/variable/CTEST_DROP_SITE_CDASH.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``IsCDash`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_DROP_SITE_PASSWORD.rst b/Help/variable/CTEST_DROP_SITE_PASSWORD.rst index 8259651..b2f684e 100644 --- a/Help/variable/CTEST_DROP_SITE_PASSWORD.rst +++ b/Help/variable/CTEST_DROP_SITE_PASSWORD.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``DropSitePassword`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_DROP_SITE_USER.rst b/Help/variable/CTEST_DROP_SITE_USER.rst index 8d2e3a3..07f115e 100644 --- a/Help/variable/CTEST_DROP_SITE_USER.rst +++ b/Help/variable/CTEST_DROP_SITE_USER.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``DropSiteUser`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_EXTRA_SUBMIT_FILES.rst b/Help/variable/CTEST_EXTRA_SUBMIT_FILES.rst index 21f801f..a721ecf 100644 --- a/Help/variable/CTEST_EXTRA_SUBMIT_FILES.rst +++ b/Help/variable/CTEST_EXTRA_SUBMIT_FILES.rst
@@ -2,4 +2,4 @@ ------------------------ Specify files for :command:`ctest_submit(PARTS ExtraFiles)` to submit -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_GIT_COMMAND.rst b/Help/variable/CTEST_GIT_COMMAND.rst index eb9b440..01ffca7 100644 --- a/Help/variable/CTEST_GIT_COMMAND.rst +++ b/Help/variable/CTEST_GIT_COMMAND.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``GITCommand`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_GIT_INIT_SUBMODULES.rst b/Help/variable/CTEST_GIT_INIT_SUBMODULES.rst index 529bfc7..6e4b9c1 100644 --- a/Help/variable/CTEST_GIT_INIT_SUBMODULES.rst +++ b/Help/variable/CTEST_GIT_INIT_SUBMODULES.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.6 Specify the CTest ``GITInitSubmodules`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_GIT_UPDATE_CUSTOM.rst b/Help/variable/CTEST_GIT_UPDATE_CUSTOM.rst index 82a8a6a..1ae1099 100644 --- a/Help/variable/CTEST_GIT_UPDATE_CUSTOM.rst +++ b/Help/variable/CTEST_GIT_UPDATE_CUSTOM.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``GITUpdateCustom`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_GIT_UPDATE_OPTIONS.rst b/Help/variable/CTEST_GIT_UPDATE_OPTIONS.rst index 1568239..a063ba3 100644 --- a/Help/variable/CTEST_GIT_UPDATE_OPTIONS.rst +++ b/Help/variable/CTEST_GIT_UPDATE_OPTIONS.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``GITUpdateOptions`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_HG_COMMAND.rst b/Help/variable/CTEST_HG_COMMAND.rst index 3372fe4..426cfd5 100644 --- a/Help/variable/CTEST_HG_COMMAND.rst +++ b/Help/variable/CTEST_HG_COMMAND.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``HGCommand`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_HG_UPDATE_OPTIONS.rst b/Help/variable/CTEST_HG_UPDATE_OPTIONS.rst index 85c6b03..751b300 100644 --- a/Help/variable/CTEST_HG_UPDATE_OPTIONS.rst +++ b/Help/variable/CTEST_HG_UPDATE_OPTIONS.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``HGUpdateOptions`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_LABELS_FOR_SUBPROJECTS.rst b/Help/variable/CTEST_LABELS_FOR_SUBPROJECTS.rst index dd6d125..4c1ec4b 100644 --- a/Help/variable/CTEST_LABELS_FOR_SUBPROJECTS.rst +++ b/Help/variable/CTEST_LABELS_FOR_SUBPROJECTS.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.10 Specify the CTest ``LabelsForSubprojects`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_MEMORYCHECK_COMMAND.rst b/Help/variable/CTEST_MEMORYCHECK_COMMAND.rst index 25f1bd9..1c86357 100644 --- a/Help/variable/CTEST_MEMORYCHECK_COMMAND.rst +++ b/Help/variable/CTEST_MEMORYCHECK_COMMAND.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``MemoryCheckCommand`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_MEMORYCHECK_COMMAND_OPTIONS.rst b/Help/variable/CTEST_MEMORYCHECK_COMMAND_OPTIONS.rst index 51830d5..f2c91e3 100644 --- a/Help/variable/CTEST_MEMORYCHECK_COMMAND_OPTIONS.rst +++ b/Help/variable/CTEST_MEMORYCHECK_COMMAND_OPTIONS.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``MemoryCheckCommandOptions`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_MEMORYCHECK_SANITIZER_OPTIONS.rst b/Help/variable/CTEST_MEMORYCHECK_SANITIZER_OPTIONS.rst index b6fee2e..d9f3eea 100644 --- a/Help/variable/CTEST_MEMORYCHECK_SANITIZER_OPTIONS.rst +++ b/Help/variable/CTEST_MEMORYCHECK_SANITIZER_OPTIONS.rst
@@ -4,7 +4,7 @@ .. versionadded:: 3.1 Specify the CTest ``MemoryCheckSanitizerOptions`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script. CTest prepends correct sanitizer options ``*_OPTIONS`` environment variable to executed command. CTests adds
diff --git a/Help/variable/CTEST_MEMORYCHECK_SUPPRESSIONS_FILE.rst b/Help/variable/CTEST_MEMORYCHECK_SUPPRESSIONS_FILE.rst index a61a3ef..fe54eb9 100644 --- a/Help/variable/CTEST_MEMORYCHECK_SUPPRESSIONS_FILE.rst +++ b/Help/variable/CTEST_MEMORYCHECK_SUPPRESSIONS_FILE.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``MemoryCheckSuppressionFile`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_MEMORYCHECK_TYPE.rst b/Help/variable/CTEST_MEMORYCHECK_TYPE.rst index 80353a4..d412e79 100644 --- a/Help/variable/CTEST_MEMORYCHECK_TYPE.rst +++ b/Help/variable/CTEST_MEMORYCHECK_TYPE.rst
@@ -4,7 +4,7 @@ .. versionadded:: 3.1 Specify the CTest ``MemoryCheckType`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script. Valid values are ``Valgrind``, ``Purify``, ``BoundsChecker``, ``DrMemory``, ``CudaSanitizer``, ``ThreadSanitizer``, ``AddressSanitizer``, ``LeakSanitizer``, ``MemorySanitizer`` and ``UndefinedBehaviorSanitizer``.
diff --git a/Help/variable/CTEST_NIGHTLY_START_TIME.rst b/Help/variable/CTEST_NIGHTLY_START_TIME.rst index 2d707d5..3ccf50a 100644 --- a/Help/variable/CTEST_NIGHTLY_START_TIME.rst +++ b/Help/variable/CTEST_NIGHTLY_START_TIME.rst
@@ -4,7 +4,7 @@ .. versionadded:: 3.1 Specify the CTest ``NightlyStartTime`` setting in a :manual:`ctest(1)` -dashboard client script. +:ref:`Dashboard Client` script. Note that this variable must always be set for a nightly build in a dashboard script. It is needed so that nightly builds can be properly grouped
diff --git a/Help/variable/CTEST_NOTES_FILES.rst b/Help/variable/CTEST_NOTES_FILES.rst index 301b78a..cc66345 100644 --- a/Help/variable/CTEST_NOTES_FILES.rst +++ b/Help/variable/CTEST_NOTES_FILES.rst
@@ -2,4 +2,4 @@ ----------------- Specify files for :command:`ctest_submit(PARTS Notes)` to submit -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_P4_CLIENT.rst b/Help/variable/CTEST_P4_CLIENT.rst index 0778c5b..63c1739 100644 --- a/Help/variable/CTEST_P4_CLIENT.rst +++ b/Help/variable/CTEST_P4_CLIENT.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``P4Client`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_P4_COMMAND.rst b/Help/variable/CTEST_P4_COMMAND.rst index 5cc2a81..61cd4a1 100644 --- a/Help/variable/CTEST_P4_COMMAND.rst +++ b/Help/variable/CTEST_P4_COMMAND.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``P4Command`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_P4_OPTIONS.rst b/Help/variable/CTEST_P4_OPTIONS.rst index 01b6534..b4889f8 100644 --- a/Help/variable/CTEST_P4_OPTIONS.rst +++ b/Help/variable/CTEST_P4_OPTIONS.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``P4Options`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_P4_UPDATE_OPTIONS.rst b/Help/variable/CTEST_P4_UPDATE_OPTIONS.rst index 365aa3f..5dec345 100644 --- a/Help/variable/CTEST_P4_UPDATE_OPTIONS.rst +++ b/Help/variable/CTEST_P4_UPDATE_OPTIONS.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``P4UpdateOptions`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_RESOURCE_SPEC_FILE.rst b/Help/variable/CTEST_RESOURCE_SPEC_FILE.rst index 8e9bf01..294e138 100644 --- a/Help/variable/CTEST_RESOURCE_SPEC_FILE.rst +++ b/Help/variable/CTEST_RESOURCE_SPEC_FILE.rst
@@ -4,7 +4,7 @@ .. versionadded:: 3.18 Specify the CTest ``ResourceSpecFile`` setting in a :manual:`ctest(1)` -dashboard client script. +:ref:`Dashboard Client` script. This can also be used to specify the resource spec file from a CMake build. If no ``RESOURCE_SPEC_FILE`` is passed to :command:`ctest_test`, and
diff --git a/Help/variable/CTEST_SITE.rst b/Help/variable/CTEST_SITE.rst index 526e6ed..7875b30 100644 --- a/Help/variable/CTEST_SITE.rst +++ b/Help/variable/CTEST_SITE.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``Site`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_SOURCE_DIRECTORY.rst b/Help/variable/CTEST_SOURCE_DIRECTORY.rst index 4c6ac54..84fd1f8 100644 --- a/Help/variable/CTEST_SOURCE_DIRECTORY.rst +++ b/Help/variable/CTEST_SOURCE_DIRECTORY.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``SourceDirectory`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_SUBMIT_INACTIVITY_TIMEOUT.rst b/Help/variable/CTEST_SUBMIT_INACTIVITY_TIMEOUT.rst index 175885a..cdc4ff4 100644 --- a/Help/variable/CTEST_SUBMIT_INACTIVITY_TIMEOUT.rst +++ b/Help/variable/CTEST_SUBMIT_INACTIVITY_TIMEOUT.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.23 Specify the CTest ``SubmitInactivityTimeout`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_SUBMIT_URL.rst b/Help/variable/CTEST_SUBMIT_URL.rst index b6e7f68..3147b4a 100644 --- a/Help/variable/CTEST_SUBMIT_URL.rst +++ b/Help/variable/CTEST_SUBMIT_URL.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.14 Specify the CTest ``SubmitURL`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_SVN_COMMAND.rst b/Help/variable/CTEST_SVN_COMMAND.rst index e97acd0..8d8b263 100644 --- a/Help/variable/CTEST_SVN_COMMAND.rst +++ b/Help/variable/CTEST_SVN_COMMAND.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``SVNCommand`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_SVN_OPTIONS.rst b/Help/variable/CTEST_SVN_OPTIONS.rst index 5326e20..3d111cc 100644 --- a/Help/variable/CTEST_SVN_OPTIONS.rst +++ b/Help/variable/CTEST_SVN_OPTIONS.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``SVNOptions`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_SVN_UPDATE_OPTIONS.rst b/Help/variable/CTEST_SVN_UPDATE_OPTIONS.rst index 24e0bbf..0830c2f 100644 --- a/Help/variable/CTEST_SVN_UPDATE_OPTIONS.rst +++ b/Help/variable/CTEST_SVN_UPDATE_OPTIONS.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``SVNUpdateOptions`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_TEST_LOAD.rst b/Help/variable/CTEST_TEST_LOAD.rst index b6a9d62..fed4042 100644 --- a/Help/variable/CTEST_TEST_LOAD.rst +++ b/Help/variable/CTEST_TEST_LOAD.rst
@@ -4,6 +4,6 @@ .. versionadded:: 3.4 Specify the ``TestLoad`` setting in the :ref:`CTest Test Step` -of a :manual:`ctest(1)` dashboard client script. This sets the +of a :manual:`ctest(1)` :ref:`Dashboard Client` script. This sets the default value for the ``TEST_LOAD`` option of the :command:`ctest_test` command.
diff --git a/Help/variable/CTEST_TEST_TIMEOUT.rst b/Help/variable/CTEST_TEST_TIMEOUT.rst index 61d9191..f6a1daa 100644 --- a/Help/variable/CTEST_TEST_TIMEOUT.rst +++ b/Help/variable/CTEST_TEST_TIMEOUT.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``TimeOut`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_UPDATE_COMMAND.rst b/Help/variable/CTEST_UPDATE_COMMAND.rst index c4ed645..1084065 100644 --- a/Help/variable/CTEST_UPDATE_COMMAND.rst +++ b/Help/variable/CTEST_UPDATE_COMMAND.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``UpdateCommand`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_UPDATE_OPTIONS.rst b/Help/variable/CTEST_UPDATE_OPTIONS.rst index 96c4b6c..ef2dad3 100644 --- a/Help/variable/CTEST_UPDATE_OPTIONS.rst +++ b/Help/variable/CTEST_UPDATE_OPTIONS.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``UpdateOptions`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_UPDATE_VERSION_ONLY.rst b/Help/variable/CTEST_UPDATE_VERSION_ONLY.rst index f7c863c..c778338 100644 --- a/Help/variable/CTEST_UPDATE_VERSION_ONLY.rst +++ b/Help/variable/CTEST_UPDATE_VERSION_ONLY.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest :ref:`UpdateVersionOnly <UpdateVersionOnly>` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_UPDATE_VERSION_OVERRIDE.rst b/Help/variable/CTEST_UPDATE_VERSION_OVERRIDE.rst index 87918cb..9f4ecc3 100644 --- a/Help/variable/CTEST_UPDATE_VERSION_OVERRIDE.rst +++ b/Help/variable/CTEST_UPDATE_VERSION_OVERRIDE.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.15 Specify the CTest :ref:`UpdateVersionOverride <UpdateVersionOverride>` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/CTEST_USE_LAUNCHERS.rst b/Help/variable/CTEST_USE_LAUNCHERS.rst index 728cdc5..3326bad 100644 --- a/Help/variable/CTEST_USE_LAUNCHERS.rst +++ b/Help/variable/CTEST_USE_LAUNCHERS.rst
@@ -4,4 +4,4 @@ .. versionadded:: 3.1 Specify the CTest ``UseLaunchers`` setting -in a :manual:`ctest(1)` dashboard client script. +in a :manual:`ctest(1)` :ref:`Dashboard Client` script.
diff --git a/Help/variable/MSVC_TOOLSET_VERSION.rst b/Help/variable/MSVC_TOOLSET_VERSION.rst index 84a6f33..cfd24ab 100644 --- a/Help/variable/MSVC_TOOLSET_VERSION.rst +++ b/Help/variable/MSVC_TOOLSET_VERSION.rst
@@ -24,6 +24,7 @@ 141 VS 2017 (15.0) 142 VS 2019 (16.0) 143 VS 2022 (17.0) + 145 VS 2026 (18.0) ===== ============== Compiler versions newer than those known to CMake will be reported
diff --git a/Help/variable/MSVC_VERSION.rst b/Help/variable/MSVC_VERSION.rst index 4d87a03..e3140a9 100644 --- a/Help/variable/MSVC_VERSION.rst +++ b/Help/variable/MSVC_VERSION.rst
@@ -26,6 +26,7 @@ 1910-1919 VS 15.0 (v141 toolset) 1920-1929 VS 16.0 (v142 toolset) 1930-1949 VS 17.0 (v143 toolset) + 1950-1959 VS 18.0 (v145 toolset) ========= ============== See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` and
diff --git a/Help/variable/PROJECT-NAME_COMPAT_VERSION.rst b/Help/variable/PROJECT-NAME_COMPAT_VERSION.rst index 29c24b8..5bcd8d5 100644 --- a/Help/variable/PROJECT-NAME_COMPAT_VERSION.rst +++ b/Help/variable/PROJECT-NAME_COMPAT_VERSION.rst
@@ -1,11 +1,7 @@ <PROJECT-NAME>_COMPAT_VERSION ----------------------------- -.. versionadded:: 4.1 - -.. note:: - - Experimental. Gated by ``CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_INFO``. +.. versionadded:: 4.3 Value given to the ``COMPAT_VERSION`` option of the most recent call to the :command:`project` command with project name ``<PROJECT-NAME>``, if any.
diff --git a/Help/variable/PROJECT-NAME_SPDX_LICENSE.rst b/Help/variable/PROJECT-NAME_SPDX_LICENSE.rst new file mode 100644 index 0000000..0febd48 --- /dev/null +++ b/Help/variable/PROJECT-NAME_SPDX_LICENSE.rst
@@ -0,0 +1,7 @@ +<PROJECT-NAME>_SPDX_LICENSE +--------------------------- + +.. versionadded:: 4.3 + +Value given to the ``SPDX_LICENSE`` option of the most recent call to the +:command:`project` command with project name ``<PROJECT-NAME>``, if any.
diff --git a/Help/variable/PROJECT_COMPAT_VERSION.rst b/Help/variable/PROJECT_COMPAT_VERSION.rst index cab800c..94bea94 100644 --- a/Help/variable/PROJECT_COMPAT_VERSION.rst +++ b/Help/variable/PROJECT_COMPAT_VERSION.rst
@@ -1,11 +1,7 @@ PROJECT_COMPAT_VERSION ---------------------- -.. versionadded:: 4.1 - -.. note:: - - Experimental. Gated by ``CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_INFO``. +.. versionadded:: 4.3 Value given to the ``COMPAT_VERSION`` option of the most recent call to the :command:`project` command, if any. To obtain the compatibility version of the
diff --git a/Help/variable/PROJECT_SPDX_LICENSE.rst b/Help/variable/PROJECT_SPDX_LICENSE.rst new file mode 100644 index 0000000..947e753 --- /dev/null +++ b/Help/variable/PROJECT_SPDX_LICENSE.rst
@@ -0,0 +1,8 @@ +PROJECT_SPDX_LICENSE +-------------------- + +.. versionadded:: 4.3 + +Value given to the ``SPDX_LICENSE`` option of the most recent call to the +:command:`project` command, if any. To obtain the compatibility version of the +top level project, see the :variable:`CMAKE_PROJECT_SPDX_LICENSE` variable.
diff --git a/Help/variable/include/CMAKE_VERIFY_XXX_HEADER_SETS.rst b/Help/variable/include/CMAKE_VERIFY_XXX_HEADER_SETS.rst new file mode 100644 index 0000000..9a274d3 --- /dev/null +++ b/Help/variable/include/CMAKE_VERIFY_XXX_HEADER_SETS.rst
@@ -0,0 +1,39 @@ +This variable is used to initialize the |VERIFY_XXX_HEADER_SETS| property of +targets when they are created. Setting it to true enables |xxx| header set +verification. + +Projects should not normally set this variable, it is intended as a developer +control to be set on the :manual:`cmake(1)` command line or other +equivalent methods. The developer must have the ability to enable or +disable header set verification according to the capabilities of their own +machine and compiler. + +Verification of a dependency's header sets is not typically of interest to +developers. Therefore, :command:`FetchContent_MakeAvailable` explicitly sets +|CMAKE_VERIFY_XXX_HEADER_SETS| and |COMPLEMENTARY_CMAKE_VERIFY_XXX_HEADER_SETS| +to false for the duration of its call, but restores their original values +before returning. If a project brings a dependency directly into the main +build (e.g. calling :command:`add_subdirectory` on a vendored project from a +git submodule), it should also do likewise. For example: + +.. code:: cmake + + # Save original setting so we can restore it later + set(want_interface_header_set_verification ${CMAKE_VERIFY_INTERFACE_HEADER_SETS}) + set(want_private_header_set_verification ${CMAKE_VERIFY_PRIVATE_HEADER_SETS}) + + # Include the vendored dependency with header set verification disabled + set(CMAKE_VERIFY_INTERFACE_HEADER_SETS OFF) + set(CMAKE_VERIFY_PRIVATE_HEADER_SETS OFF) + add_subdirectory(...) # Vendored sources, e.g. from git submodules + + # Add the project's own sources. Restore the developer's original choice + # for whether to enable header set verification. + set(CMAKE_VERIFY_INTERFACE_HEADER_SETS ${want_interface_header_set_verification}) + set(CMAKE_VERIFY_PRIVATE_HEADER_SETS ${want_private_header_set_verification}) + add_subdirectory(src) + +By default, this variable is not set, which will result in |xxx| header set +verification being disabled. + +See also |COMPLEMENTARY_CMAKE_VERIFY_XXX_HEADER_SETS|.
diff --git a/LICENSE.rst b/LICENSE.rst index 782e365..3ddcf87 100644 --- a/LICENSE.rst +++ b/LICENSE.rst
@@ -1,4 +1,4 @@ -Copyright 2000-2025 Kitware, Inc. and `Contributors <CONTRIBUTORS.rst>`_ +Copyright 2000-2026 Kitware, Inc. and `Contributors <CONTRIBUTORS.rst>`_ Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions
diff --git a/Modules/AddFileDependencies.cmake b/Modules/AddFileDependencies.cmake index 13828f2..25a78a8 100644 --- a/Modules/AddFileDependencies.cmake +++ b/Modules/AddFileDependencies.cmake
@@ -6,28 +6,38 @@ ------------------- .. deprecated:: 3.20 + Do not use this module in new code. -Add dependencies to a source file. + Instead use the :command:`set_property` command to append to the + :prop_sf:`OBJECT_DEPENDS` source file property directly: + + .. code-block:: cmake + + set_property(SOURCE <source> APPEND PROPERTY OBJECT_DEPENDS <files>...) + +Load this module in a CMake project with: .. code-block:: cmake - add_file_dependencies(<source> <files>...) + include(AddFileDependencies) -Adds the given ``<files>`` to the dependencies of file ``<source>``. +Commands +^^^^^^^^ -Do not use this command in new code. It is just a wrapper around: +This module provides the following command: -.. code-block:: cmake +.. command:: add_file_dependencies - set_property(SOURCE <source> APPEND PROPERTY OBJECT_DEPENDS <files>...) + Adds dependencies to a source file: -Instead use the :command:`set_property` command to append to the -:prop_sf:`OBJECT_DEPENDS` source file property directly. + .. code-block:: cmake + add_file_dependencies(<source> <files>...) + + This command adds the given ``<files>`` to the dependencies of file + ``<source>``. #]=======================================================================] function(add_file_dependencies _file) - set_property(SOURCE "${_file}" APPEND PROPERTY OBJECT_DEPENDS "${ARGN}") - endfunction()
diff --git a/Modules/BundleUtilities.cmake b/Modules/BundleUtilities.cmake index 4df5bb9..40821e0 100644 --- a/Modules/BundleUtilities.cmake +++ b/Modules/BundleUtilities.cmake
@@ -9,7 +9,7 @@ bundle-style applications with CMake, such as macOS ``.app`` bundles or similar directory-based application bundles on other operating systems. -Load this module in CMake installation with: +Load this module in a CMake installation with: .. code-block:: cmake @@ -733,7 +733,9 @@ string(REGEX REPLACE "rpath " "" load_cmds_ov "${load_cmds_ov}") if(load_cmds_ov) foreach(rpath ${load_cmds_ov}) - gp_append_unique(${rpaths_var} "${rpath}") + if(NOT rpath IN_LIST ${rpaths_var}) + list(APPEND ${rpaths_var} "${rpath}") + endif() endforeach() endif() endif() @@ -744,7 +746,9 @@ foreach(rpath ${rpath_var} ${runpath_var}) # Substitute $ORIGIN with the exepath and add to the found rpaths string(REPLACE "$ORIGIN" "${item_dir}" rpath "${rpath}") - gp_append_unique(${rpaths_var} "${rpath}") + if(NOT rpath IN_LIST ${rpaths_var}) + list(APPEND ${rpaths_var} "${rpath}") + endif() endforeach() endif() @@ -787,7 +791,9 @@ get_item_key("${item}" key) list(LENGTH ${keys_var} length_before) - gp_append_unique(${keys_var} "${key}") + if(NOT key IN_LIST ${keys_var}) + list(APPEND ${keys_var} "${key}") + endif() list(LENGTH ${keys_var} length_after) if(NOT length_before EQUAL length_after)
diff --git a/Modules/CMakeAddFortranSubdirectory.cmake b/Modules/CMakeAddFortranSubdirectory.cmake index 9b386b0..7eec1f2 100644 --- a/Modules/CMakeAddFortranSubdirectory.cmake +++ b/Modules/CMakeAddFortranSubdirectory.cmake
@@ -8,7 +8,7 @@ This module provides a command to add a Fortran project located in a subdirectory. -Load it in a CMake project with: +Load this module in a CMake project with: .. code-block:: cmake
diff --git a/Modules/CMakeCCompiler.cmake.in b/Modules/CMakeCCompiler.cmake.in index 1ccc7f5..96e5c60 100644 --- a/Modules/CMakeCCompiler.cmake.in +++ b/Modules/CMakeCCompiler.cmake.in
@@ -22,6 +22,7 @@ set(CMAKE_C_COMPILER_ARCHITECTURE_ID "@CMAKE_C_COMPILER_ARCHITECTURE_ID@") @_SET_CMAKE_C_COMPILER_SYSROOT@ @SET_MSVC_C_ARCHITECTURE_ID@ +@SET_CMAKE_C_MSVC_I18N_DIR@ @SET_CMAKE_XCODE_ARCHS@ set(CMAKE_AR "@CMAKE_AR@") set(CMAKE_C_COMPILER_AR "@CMAKE_C_COMPILER_AR@")
diff --git a/Modules/CMakeCSharpCompilerId.cs.in b/Modules/CMakeCSharpCompilerId.cs.in index b43ec04..7a9011b 100644 --- a/Modules/CMakeCSharpCompilerId.cs.in +++ b/Modules/CMakeCSharpCompilerId.cs.in
@@ -19,6 +19,8 @@ + "Visual Studio" #elif PlatformToolsetv143 + "Visual Studio" +#elif PlatformToolsetv145 + + "Visual Studio" #else + "unknown" #endif @@ -53,6 +55,8 @@ + "2019" #elif PlatformToolsetv143 + "2022" +#elif PlatformToolsetv145 + + "2026" #else + "9999" #endif
diff --git a/Modules/CMakeCXXCompiler.cmake.in b/Modules/CMakeCXXCompiler.cmake.in index 8e2e3d6..9e1db3b 100644 --- a/Modules/CMakeCXXCompiler.cmake.in +++ b/Modules/CMakeCXXCompiler.cmake.in
@@ -24,6 +24,7 @@ set(CMAKE_CXX_COMPILER_ARCHITECTURE_ID "@CMAKE_CXX_COMPILER_ARCHITECTURE_ID@") @_SET_CMAKE_CXX_COMPILER_SYSROOT@ @SET_MSVC_CXX_ARCHITECTURE_ID@ +@SET_CMAKE_CXX_MSVC_I18N_DIR@ @SET_CMAKE_XCODE_ARCHS@ set(CMAKE_AR "@CMAKE_AR@") set(CMAKE_CXX_COMPILER_AR "@CMAKE_CXX_COMPILER_AR@") @@ -96,5 +97,6 @@ set(CMAKE_CXX_IMPLICIT_LINK_FRAMEWORK_DIRECTORIES "@CMAKE_CXX_IMPLICIT_LINK_FRAMEWORK_DIRECTORIES@") set(CMAKE_CXX_COMPILER_CLANG_RESOURCE_DIR "@CMAKE_CXX_COMPILER_CLANG_RESOURCE_DIR@") -set(CMAKE_CXX_COMPILER_IMPORT_STD "") -@CMAKE_CXX_IMPORT_STD@ +set(CMAKE_CXX_COMPILER_IMPORT_STD "@CMAKE_CXX_COMPILER_IMPORT_STD@") +set(CMAKE_CXX_COMPILER_IMPORT_STD_ERROR_MESSAGE "@CMAKE_CXX_COMPILER_IMPORT_STD_ERROR_MESSAGE@") +set(CMAKE_CXX_STDLIB_MODULES_JSON "@CMAKE_CXX_STDLIB_MODULES_JSON@")
diff --git a/Modules/CMakeCheckCompilerFlagCommonPatterns.cmake b/Modules/CMakeCheckCompilerFlagCommonPatterns.cmake index ef9f138..92fdc69 100644 --- a/Modules/CMakeCheckCompilerFlagCommonPatterns.cmake +++ b/Modules/CMakeCheckCompilerFlagCommonPatterns.cmake
@@ -8,34 +8,34 @@ macro (CHECK_COMPILER_FLAG_COMMON_PATTERNS _VAR) set(${_VAR} - 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 - FAIL_REGEX "unknown argument ignored" # Clang (cl) - FAIL_REGEX "ignoring unknown option" # MSVC, Intel - FAIL_REGEX "warning D9002" # MSVC, any lang - FAIL_REGEX "option.*not supported" # Intel - FAIL_REGEX "invalid argument .*option" # Intel - FAIL_REGEX "ignoring option .*argument required" # Intel - FAIL_REGEX "ignoring option .*argument is of wrong type" # Intel + FAIL_REGEX "[Uu]nrecogni[sz]ed [^\n]*option" # GNU, NAG, Fujitsu + FAIL_REGEX "switch [^\n]* is no longer supported" # GNU + FAIL_REGEX "unknown [^\n]*option" # Clang + FAIL_REGEX "optimization flag [^\n]* not supported" # Clang + FAIL_REGEX "unknown argument ignored" # Clang (cl) + FAIL_REGEX "ignoring unknown option" # MSVC, Intel + FAIL_REGEX "warning D9002" # MSVC, any lang + FAIL_REGEX "option[^\n]*not supported" # Intel + FAIL_REGEX "invalid argument [^\n]*option" # Intel + FAIL_REGEX "ignoring option [^\n]*argument required" # Intel + FAIL_REGEX "ignoring option [^\n]*argument is of wrong type" # Intel # noqa: spellcheck off - FAIL_REGEX "[Uu]nknown option" # HP + FAIL_REGEX "[Uu]nknown option" # HP # noqa: spellcheck on - FAIL_REGEX "[Ww]arning: [Oo]ption" # SunPro - FAIL_REGEX "command option .* is not recognized" # XL - FAIL_REGEX "command option .* contains an incorrect subargument" # XL - FAIL_REGEX "Option .* is not recognized. Option will be ignored." # XL - FAIL_REGEX "not supported in this configuration. ignored" # AIX - FAIL_REGEX "File with unknown suffix passed to linker" # PGI + FAIL_REGEX "[Ww]arning: [Oo]ption" # SunPro + FAIL_REGEX "command option [^\n]* is not recognized" # XL + FAIL_REGEX "command option [^\n]* contains an incorrect subargument" # XL + FAIL_REGEX "Option [^\n]* is not recognized. Option will be ignored." # XL + FAIL_REGEX "not supported in this configuration. ignored" # AIX + FAIL_REGEX "File with unknown suffix passed to linker" # PGI # noqa: spellcheck off - FAIL_REGEX "[Uu]nknown switch" # PGI + FAIL_REGEX "[Uu]nknown switch" # PGI # noqa: spellcheck on - FAIL_REGEX "WARNING: unknown flag:" # Open64 - FAIL_REGEX "Incorrect command line option:" # Borland - 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 + FAIL_REGEX "WARNING: unknown flag:" # Open64 + FAIL_REGEX "Incorrect command line option:" # Borland + FAIL_REGEX "Warning: illegal option" # SunStudio 12 + FAIL_REGEX "[Ww]arning: Invalid suboption" # Fujitsu + FAIL_REGEX "An invalid option [^\n]* appears on the command line" # Cray + FAIL_REGEX "WARNING: invalid compiler option" # TI armcl ) endmacro ()
diff --git a/Modules/CMakeCompilerABI.h b/Modules/CMakeCompilerABI.h index dc71f9f..bd90ea2 100644 --- a/Modules/CMakeCompilerABI.h +++ b/Modules/CMakeCompilerABI.h
@@ -114,6 +114,8 @@ # define ARCHITECTURE_ID "riscv64" #elif defined(__riscv) && __riscv_xlen == 32 # define ARCHITECTURE_ID "riscv32" +#elif defined(__sw_64) +# define ARCHITECTURE_ID "sw_64" #elif defined(__s390x__) # define ARCHITECTURE_ID "s390x" #elif defined(__s390__) @@ -142,6 +144,10 @@ # else # define ARCHITECTURE_ID "ppc" # endif +#elif defined(__wasm64) || defined(__wasm64__) +# define ARCHITECTURE_ID "wasm64" +#elif defined(__wasm32) || defined(__wasm32__) +# define ARCHITECTURE_ID "wasm32" #endif /* Construct the string literal in pieces to prevent the source from
diff --git a/Modules/CMakeDependentOption.cmake b/Modules/CMakeDependentOption.cmake index 3db05da..0d840fc 100644 --- a/Modules/CMakeDependentOption.cmake +++ b/Modules/CMakeDependentOption.cmake
@@ -10,7 +10,7 @@ maintain a clean configuration interface by only displaying options that are relevant to the current settings. -Load this module in a CMake project with: +Load this module in CMake with: .. code-block:: cmake @@ -82,6 +82,9 @@ The value assigned to a local variable named ``<variable>``, when ``<condition>`` evaluates to boolean false. + In CMake project mode, boolean cache variables are created as explained + above. In CMake script mode, boolean variables are set instead. + Examples ^^^^^^^^
diff --git a/Modules/CMakeDetermineASMCompiler.cmake b/Modules/CMakeDetermineASMCompiler.cmake index 5f72d2f..46f42e0 100644 --- a/Modules/CMakeDetermineASMCompiler.cmake +++ b/Modules/CMakeDetermineASMCompiler.cmake
@@ -16,7 +16,7 @@ set(CMAKE_ASM${ASM_DIALECT}_COMPILER_ARG1 "${CMAKE_ASM${ASM_DIALECT}_FLAGS_ENV_INIT}" CACHE STRING "Arguments to ASM${ASM_DIALECT} compiler") endif() if(NOT EXISTS ${CMAKE_ASM${ASM_DIALECT}_COMPILER_INIT}) - message(FATAL_ERROR "Could not find compiler set in environment variable ASM${ASM_DIALECT}:\n$ENV{ASM${ASM_DIALECT}}.") + message(FATAL_ERROR "Could not find the compiler specified in the environment variable ASM${ASM_DIALECT}:\n$ENV{ASM${ASM_DIALECT}}.") endif() endif()
diff --git a/Modules/CMakeDetermineCCompiler.cmake b/Modules/CMakeDetermineCCompiler.cmake index fbe5166..9723fb6 100644 --- a/Modules/CMakeDetermineCCompiler.cmake +++ b/Modules/CMakeDetermineCCompiler.cmake
@@ -45,7 +45,7 @@ set(CMAKE_C_COMPILER_ARG1 "${CMAKE_C_FLAGS_ENV_INIT}" CACHE STRING "Arguments to C compiler") endif() if(NOT EXISTS ${CMAKE_C_COMPILER_INIT}) - message(FATAL_ERROR "Could not find compiler set in environment variable CC:\n$ENV{CC}.") + message(FATAL_ERROR "Could not find the compiler specified in the environment variable CC:\n$ENV{CC}.") endif() endif() @@ -214,6 +214,11 @@ "set(MSVC_C_ARCHITECTURE_ID ${MSVC_C_ARCHITECTURE_ID})") endif() +if(CMAKE_C_MSVC_I18N_DIR) + set(SET_CMAKE_C_MSVC_I18N_DIR + "set(CMAKE_C_MSVC_I18N_DIR ${CMAKE_C_MSVC_I18N_DIR})") +endif() + if(CMAKE_C_XCODE_ARCHS) set(SET_CMAKE_XCODE_ARCHS "set(CMAKE_XCODE_ARCHS \"${CMAKE_C_XCODE_ARCHS}\")")
diff --git a/Modules/CMakeDetermineCUDACompiler.cmake b/Modules/CMakeDetermineCUDACompiler.cmake index edb3cc8..e70742b 100644 --- a/Modules/CMakeDetermineCUDACompiler.cmake +++ b/Modules/CMakeDetermineCUDACompiler.cmake
@@ -4,9 +4,10 @@ include(${CMAKE_ROOT}/Modules/CMakeDetermineCompiler.cmake) include(${CMAKE_ROOT}/Modules/CMakeParseImplicitLinkInfo.cmake) -if(NOT ((CMAKE_GENERATOR MATCHES "Make") OR - (CMAKE_GENERATOR MATCHES "Ninja") OR - (CMAKE_GENERATOR MATCHES "Visual Studio (1|[9][0-9])"))) +if( NOT ( ("${CMAKE_GENERATOR}" MATCHES "Make") OR + ("${CMAKE_GENERATOR}" MATCHES "Ninja") OR + ("${CMAKE_GENERATOR}" MATCHES "FASTBuild") OR + ("${CMAKE_GENERATOR}" MATCHES "Visual Studio (1|[9][0-9])") ) ) message(FATAL_ERROR "CUDA language not currently supported by \"${CMAKE_GENERATOR}\" generator") endif() @@ -25,7 +26,7 @@ set(CMAKE_CUDA_COMPILER_ARG1 "${CMAKE_CUDA_FLAGS_ENV_INIT}" CACHE STRING "Arguments to CUDA compiler") endif() if(NOT EXISTS ${CMAKE_CUDA_COMPILER_INIT}) - message(FATAL_ERROR "Could not find compiler set in environment variable CUDACXX:\n$ENV{CUDACXX}.\n${CMAKE_CUDA_COMPILER_INIT}") + message(FATAL_ERROR "Could not find the compiler specified in the environment variable CUDACXX:\n$ENV{CUDACXX}.\n${CMAKE_CUDA_COMPILER_INIT}") endif() endif() @@ -47,7 +48,7 @@ if(NOT $ENV{CUDAHOSTCXX} STREQUAL "") get_filename_component(CMAKE_CUDA_HOST_COMPILER $ENV{CUDAHOSTCXX} PROGRAM) if(NOT EXISTS ${CMAKE_CUDA_HOST_COMPILER}) - message(FATAL_ERROR "Could not find compiler set in environment variable CUDAHOSTCXX:\n$ENV{CUDAHOSTCXX}.\n${CMAKE_CUDA_HOST_COMPILER}") + message(FATAL_ERROR "Could not find the compiler specified in the environment variable CUDAHOSTCXX:\n$ENV{CUDAHOSTCXX}.\n${CMAKE_CUDA_HOST_COMPILER}") endif() elseif(CMAKE_CUDA_HOST_COMPILER) # We get here if CMAKE_CUDA_HOST_COMPILER was specified by the user or toolchain file. @@ -63,7 +64,7 @@ unset(_CMAKE_CUDA_HOST_COMPILER_PATH) endif() if(NOT EXISTS "${CMAKE_CUDA_HOST_COMPILER}") - message(FATAL_ERROR "Could not find compiler set in variable CMAKE_CUDA_HOST_COMPILER:\n ${CMAKE_CUDA_HOST_COMPILER}") + message(FATAL_ERROR "Could not find the compiler specified in the variable CMAKE_CUDA_HOST_COMPILER:\n ${CMAKE_CUDA_HOST_COMPILER}") endif() # If the value was cached, update the cache entry with our modifications. get_property(_CMAKE_CUDA_HOST_COMPILER_CACHED CACHE CMAKE_CUDA_HOST_COMPILER PROPERTY TYPE)
diff --git a/Modules/CMakeDetermineCXXCompiler.cmake b/Modules/CMakeDetermineCXXCompiler.cmake index 5331681..5c5d441 100644 --- a/Modules/CMakeDetermineCXXCompiler.cmake +++ b/Modules/CMakeDetermineCXXCompiler.cmake
@@ -44,7 +44,7 @@ set(CMAKE_CXX_COMPILER_ARG1 "${CMAKE_CXX_FLAGS_ENV_INIT}" CACHE STRING "Arguments to CXX compiler") endif() if(NOT EXISTS ${CMAKE_CXX_COMPILER_INIT}) - message(FATAL_ERROR "Could not find compiler set in environment variable CXX:\n$ENV{CXX}.\n${CMAKE_CXX_COMPILER_INIT}") + message(FATAL_ERROR "Could not find the compiler specified in the environment variable CXX:\n$ENV{CXX}.\n${CMAKE_CXX_COMPILER_INIT}") endif() endif() @@ -220,6 +220,11 @@ "set(MSVC_CXX_ARCHITECTURE_ID ${MSVC_CXX_ARCHITECTURE_ID})") endif() +if(CMAKE_CXX_MSVC_I18N_DIR) + set(SET_CMAKE_CXX_MSVC_I18N_DIR + "set(CMAKE_CXX_MSVC_I18N_DIR ${CMAKE_CXX_MSVC_I18N_DIR})") +endif() + if(CMAKE_CXX_XCODE_ARCHS) set(SET_CMAKE_XCODE_ARCHS "set(CMAKE_XCODE_ARCHS \"${CMAKE_CXX_XCODE_ARCHS}\")")
diff --git a/Modules/CMakeDetermineCompiler.cmake b/Modules/CMakeDetermineCompiler.cmake index 16c5554..097916e 100644 --- a/Modules/CMakeDetermineCompiler.cmake +++ b/Modules/CMakeDetermineCompiler.cmake
@@ -137,9 +137,13 @@ execute_process(COMMAND "${CMAKE_${lang}_COMPILER}" -print-sysroot OUTPUT_STRIP_TRAILING_WHITESPACE OUTPUT_VARIABLE _cmake_sysroot_run_out - ERROR_VARIABLE _cmake_sysroot_run_err) + ERROR_VARIABLE _cmake_sysroot_run_err + RESULT_VARIABLE _cmake_sysroot_run_res + ) - if(_cmake_sysroot_run_out AND NOT _cmake_sysroot_run_err + if(_cmake_sysroot_run_res EQUAL 0 + AND _cmake_sysroot_run_out + AND NOT _cmake_sysroot_run_err AND NOT _cmake_sysroot_run_out STREQUAL "/" AND IS_DIRECTORY "${_cmake_sysroot_run_out}/usr") file(TO_CMAKE_PATH "${_cmake_sysroot_run_out}/usr" _cmake_sysroot_run_out_usr)
diff --git a/Modules/CMakeDetermineCompilerId.cmake b/Modules/CMakeDetermineCompilerId.cmake index 2b7d797..0518128 100644 --- a/Modules/CMakeDetermineCompilerId.cmake +++ b/Modules/CMakeDetermineCompilerId.cmake
@@ -242,7 +242,7 @@ set(CMAKE_EXECUTABLE_FORMAT "Unknown" CACHE INTERNAL "Executable file format") endif() - if((CMAKE_GENERATOR MATCHES "^Ninja" + if((CMAKE_GENERATOR MATCHES "^Ninja|FASTBuild" OR ((NOT DEFINED CMAKE_DEPENDS_USE_COMPILER OR CMAKE_DEPENDS_USE_COMPILER) AND CMAKE_GENERATOR MATCHES "Makefiles|WMake")) AND MSVC_${lang}_ARCHITECTURE_ID) @@ -256,6 +256,12 @@ set(CMAKE_${lang}_CL_SHOWINCLUDES_PREFIX "") endif() + if(CMAKE_GENERATOR MATCHES "^FASTBuild" + AND CMAKE_${lang}_COMPILER_ID STREQUAL "MSVC") + cmake_determine_msvc_i18n_dir(${lang}) + set(CMAKE_${lang}_MSVC_I18N_DIR ${CMAKE_${lang}_MSVC_I18N_DIR} PARENT_SCOPE) + endif() + if(CMAKE_EFFECTIVE_SYSTEM_NAME STREQUAL "Apple" AND CMAKE_${lang}_COMPILER_ID MATCHES "Clang$") cmake_path(GET src EXTENSION LAST_ONLY ext) set(apple_sdk_dir "${CMAKE_${lang}_COMPILER_ID_DIR}") @@ -604,7 +610,7 @@ set(id_api_level "<AndroidAPILevel>android-${CMAKE_SYSTEM_VERSION}</AndroidAPILevel>") if(CMAKE_GENERATOR MATCHES "Visual Studio 14") set(id_system_version "<ApplicationTypeRevision>2.0</ApplicationTypeRevision>") - elseif(CMAKE_GENERATOR MATCHES "Visual Studio 1[567]") + elseif(CMAKE_GENERATOR MATCHES "Visual Studio 1[5678]") set(id_system_version "<ApplicationTypeRevision>3.0</ApplicationTypeRevision>") else() set(id_system_version "") @@ -1340,3 +1346,40 @@ endif() message(CONFIGURE_LOG "Detecting ${lang} compiler /showIncludes prefix:\n${msg}\n") endfunction() + +function(CMAKE_DETERMINE_MSVC_I18N_DIR lang) + # The FASTBuild generator needs the full path to clui.dll: + cmake_path(GET CMAKE_${lang}_COMPILER PARENT_PATH cldir) + + # if the VSLANG env.var is set, prefer that. + # If that doesn't exist, try 1033, the US version. + # Otherwise, search for any clui.dll, and use the first one that is found. + if(DEFINED ENV{VSLANG}) + if(EXISTS "${cldir}/$ENV{VSLANG}/clui.dll") + set(MSVC_I18N_DIR "$ENV{VSLANG}") + else() + message(WARNING "The environment variable VSLANG is set to $ENV{VSLANG}, but could not find ${cldir}/$ENV{VSLANG}/clui.dll") + endif() + endif() + + if (NOT MSVC_I18N_DIR) + if(EXISTS "${cldir}/1033/clui.dll") + set(MSVC_I18N_DIR "1033") + endif() + endif() + + if(NOT MSVC_I18N_DIR) + file(GLOB_RECURSE cluis "${cldir}/*/clui.dll") + list(GET cluis 0 firstClui) + if (firstClui) + cmake_path(GET firstClui PARENT_PATH cluiParentPath) + cmake_path(GET cluiParentPath FILENAME MSVC_I18N_DIR) + endif() + endif() + + if(MSVC_I18N_DIR) + set(CMAKE_${lang}_MSVC_I18N_DIR ${MSVC_I18N_DIR} PARENT_SCOPE ) + else() + message(FATAL_ERROR "Could not find clui.dll !") + endif() +endfunction()
diff --git a/Modules/CMakeDetermineCompilerSupport.cmake b/Modules/CMakeDetermineCompilerSupport.cmake index c22bf07..512a1c4 100644 --- a/Modules/CMakeDetermineCompilerSupport.cmake +++ b/Modules/CMakeDetermineCompilerSupport.cmake
@@ -105,18 +105,21 @@ ) endif() - # Create targets for use with `import std;` here. - set(CMAKE_CXX_IMPORT_STD "") - foreach (_cmake_import_std_version IN ITEMS 23 26) - if (CMAKE_CXX${_cmake_import_std_version}_COMPILE_FEATURES) - set(_cmake_cxx_import_std "") - cmake_create_cxx_import_std("${_cmake_import_std_version}" _cmake_cxx_import_std) - if (_cmake_cxx_import_std) - string(APPEND CMAKE_CXX_IMPORT_STD "### Imported target for C++${_cmake_import_std_version} standard library\n") - string(APPEND CMAKE_CXX_IMPORT_STD "${_cmake_cxx_import_std}\n\n") - endif () - endif () - endforeach () + # Find the module metadata for import std + set(CMAKE_CXX_COMPILER_IMPORT_STD "") + cmake_cxx_find_modules_json() + foreach(_cmake_import_std_version IN ITEMS 23 26) + if(CMAKE_CXX${_cmake_import_std_version}_COMPILE_FEATURES) + # Modules JSON covers all versions, otherwise rely on toolchain targets + if(CMAKE_CXX_STDLIB_MODULES_JSON OR (TARGET "__CMAKE:CXX${_cmake_import_std_version}")) + list(APPEND CMAKE_CXX_COMPILER_IMPORT_STD ${_cmake_import_std_version}) + endif() + endif() + endforeach() + + set(CMAKE_CXX_COMPILER_IMPORT_STD ${CMAKE_CXX_COMPILER_IMPORT_STD} PARENT_SCOPE) + set(CMAKE_CXX_STDLIB_MODULES_JSON ${CMAKE_CXX_STDLIB_MODULES_JSON} PARENT_SCOPE) + set(CMAKE_CXX_COMPILER_IMPORT_STD_ERROR_MESSAGE "${CMAKE_CXX_COMPILER_IMPORT_STD_ERROR_MESSAGE}" PARENT_SCOPE) set(CMAKE_CXX_COMPILE_FEATURES ${CMAKE_CXX_COMPILE_FEATURES} PARENT_SCOPE) set(CMAKE_CXX98_COMPILE_FEATURES ${CMAKE_CXX98_COMPILE_FEATURES} PARENT_SCOPE) @@ -126,7 +129,6 @@ set(CMAKE_CXX20_COMPILE_FEATURES ${CMAKE_CXX20_COMPILE_FEATURES} PARENT_SCOPE) set(CMAKE_CXX23_COMPILE_FEATURES ${CMAKE_CXX23_COMPILE_FEATURES} PARENT_SCOPE) set(CMAKE_CXX26_COMPILE_FEATURES ${CMAKE_CXX26_COMPILE_FEATURES} PARENT_SCOPE) - set(CMAKE_CXX_IMPORT_STD ${CMAKE_CXX_IMPORT_STD} PARENT_SCOPE) message(CHECK_PASS "done")
diff --git a/Modules/CMakeDetermineFortranCompiler.cmake b/Modules/CMakeDetermineFortranCompiler.cmake index f7727a9..dc39577 100644 --- a/Modules/CMakeDetermineFortranCompiler.cmake +++ b/Modules/CMakeDetermineFortranCompiler.cmake
@@ -30,7 +30,7 @@ endif() if(EXISTS ${CMAKE_Fortran_COMPILER_INIT}) else() - message(FATAL_ERROR "Could not find compiler set in environment variable FC:\n$ENV{FC}.") + message(FATAL_ERROR "Could not find the compiler specified in the environment variable FC:\n$ENV{FC}.") endif() endif()
diff --git a/Modules/CMakeDetermineHIPCompiler.cmake b/Modules/CMakeDetermineHIPCompiler.cmake index 13ec392..c3a1649 100644 --- a/Modules/CMakeDetermineHIPCompiler.cmake +++ b/Modules/CMakeDetermineHIPCompiler.cmake
@@ -17,15 +17,17 @@ ) if(_CMAKE_HIPCONFIG_RESULT EQUAL 0 AND _CMAKE_HIPCONFIG_PLATFORM MATCHES "^(nvidia|nvcc)$") set(CMAKE_HIP_PLATFORM "nvidia" CACHE STRING "HIP platform" FORCE) + elseif(_CMAKE_HIPCONFIG_RESULT EQUAL 0 AND _CMAKE_HIPCONFIG_PLATFORM MATCHES "^(spirv)$") + set(CMAKE_HIP_PLATFORM "spirv" CACHE STRING "HIP platform" FORCE) else() set(CMAKE_HIP_PLATFORM "amd" CACHE STRING "HIP platform" FORCE) endif() endif() -if(NOT CMAKE_HIP_PLATFORM MATCHES "^(amd|nvidia)$") +if(NOT CMAKE_HIP_PLATFORM MATCHES "^(amd|nvidia|spirv)$") message(FATAL_ERROR "The CMAKE_HIP_PLATFORM has unsupported value:\n" " '${CMAKE_HIP_PLATFORM}'\n" - "It must be 'amd' or 'nvidia'." + "It must be 'amd', 'nvidia', or 'spirv'." ) endif() @@ -46,7 +48,7 @@ set(CMAKE_HIP_COMPILER_ARG1 "${CMAKE_HIP_FLAGS_ENV_INIT}" CACHE STRING "Arguments to CXX compiler") endif() if(NOT EXISTS ${CMAKE_HIP_COMPILER_INIT}) - message(FATAL_ERROR "Could not find compiler set in environment variable HIPCXX:\n$ENV{HIPCXX}.\n${CMAKE_HIP_COMPILER_INIT}") + message(FATAL_ERROR "Could not find the compiler specified in the environment variable HIPCXX:\n$ENV{HIPCXX}.\n${CMAKE_HIP_COMPILER_INIT}") endif() endif() @@ -54,10 +56,10 @@ if(NOT CMAKE_HIP_COMPILER_INIT) if(CMAKE_HIP_PLATFORM STREQUAL "nvidia") set(CMAKE_HIP_COMPILER_LIST nvcc) - elseif(CMAKE_HIP_PLATFORM STREQUAL "amd") + elseif(CMAKE_HIP_PLATFORM STREQUAL "amd" OR CMAKE_HIP_PLATFORM STREQUAL "spirv") set(CMAKE_HIP_COMPILER_LIST clang++) - # Look for the Clang coming with ROCm to support HIP. + # Look for the Clang coming with ROCm or chipStar to support HIP. execute_process(COMMAND hipconfig --hipclangpath OUTPUT_VARIABLE _CMAKE_HIPCONFIG_CLANGPATH RESULT_VARIABLE _CMAKE_HIPCONFIG_RESULT @@ -111,7 +113,7 @@ if(NOT CMAKE_HIP_HOST_COMPILER AND NOT $ENV{HIPHOSTCXX} STREQUAL "") get_filename_component(CMAKE_HIP_HOST_COMPILER $ENV{HIPHOSTCXX} PROGRAM) if(NOT EXISTS "${CMAKE_HIP_HOST_COMPILER}") - message(FATAL_ERROR "Could not find compiler set in environment variable HIPHOSTCXX:\n$ENV{HIPHOSTCXX}.\n${CMAKE_HIP_HOST_COMPILER}") + message(FATAL_ERROR "Could not find the compiler specified in the environment variable HIPHOSTCXX:\n$ENV{HIPHOSTCXX}.\n${CMAKE_HIP_HOST_COMPILER}") endif() elseif(CMAKE_HIP_HOST_COMPILER) # We get here if CMAKE_HIP_HOST_COMPILER was specified by the user or toolchain file. @@ -127,7 +129,7 @@ unset(_CMAKE_HIP_HOST_COMPILER_PATH) endif() if(NOT EXISTS "${CMAKE_HIP_HOST_COMPILER}") - message(FATAL_ERROR "Could not find compiler set in variable CMAKE_HIP_HOST_COMPILER:\n ${CMAKE_HIP_HOST_COMPILER}") + message(FATAL_ERROR "Could not find the compiler specified in the variable CMAKE_HIP_HOST_COMPILER:\n ${CMAKE_HIP_HOST_COMPILER}") endif() # If the value was cached, update the cache entry with our modifications. get_property(_CMAKE_HIP_HOST_COMPILER_CACHED CACHE CMAKE_HIP_HOST_COMPILER PROPERTY TYPE) @@ -140,7 +142,13 @@ endif() if(CMAKE_HIP_COMPILER_ID STREQUAL "Clang") - list(APPEND CMAKE_HIP_COMPILER_ID_TEST_FLAGS_FIRST "-v") + # For spirv platform (chipStar), set special flags for compiler identification + include(Internal/CMakeChipStarHIP) + if(CMAKE_HIP_PLATFORM STREQUAL "spirv") + _cmake_chipstar_set_compiler_id_flags() + else() + list(APPEND CMAKE_HIP_COMPILER_ID_TEST_FLAGS_FIRST "-v") + endif() elseif(CMAKE_HIP_COMPILER_ID STREQUAL "NVIDIA") # Tell nvcc to treat .hip files as CUDA sources. list(APPEND CMAKE_HIP_COMPILER_ID_TEST_FLAGS_FIRST "-x cu -v") @@ -194,11 +202,18 @@ endif() endif() if(NOT CMAKE_HIP_COMPILER_ROCM_ROOT) - message(FATAL_ERROR "Failed to find ROCm root directory.") + # For spirv platform (chipStar), fall back to HIP_PATH environment variable + if(CMAKE_HIP_PLATFORM STREQUAL "spirv" AND DEFINED ENV{HIP_PATH} AND IS_DIRECTORY "$ENV{HIP_PATH}") + set(CMAKE_HIP_COMPILER_ROCM_ROOT "$ENV{HIP_PATH}") + file(TO_CMAKE_PATH "${CMAKE_HIP_COMPILER_ROCM_ROOT}" CMAKE_HIP_COMPILER_ROCM_ROOT) + else() + message(FATAL_ERROR "Failed to find HIP root directory.") + endif() endif() -if(CMAKE_HIP_PLATFORM STREQUAL "amd") - # For this platform we need the hip-lang cmake package. + +if(CMAKE_HIP_PLATFORM STREQUAL "amd" OR CMAKE_HIP_PLATFORM STREQUAL "spirv") + # For amd and spirv platforms we need the hip-lang cmake package. # Normally implicit link information is not detected until ABI detection, # but we need to populate CMAKE_HIP_LIBRARY_ARCHITECTURE to find hip-lang. @@ -227,6 +242,8 @@ ) if(CMAKE_HIP_LIBRARY_ARCHITECTURE) list(APPEND _CMAKE_HIP_COMPILER_ROCM_LIB_DIRS "${CMAKE_HIP_COMPILER_ROCM_ROOT}/lib/${CMAKE_HIP_LIBRARY_ARCHITECTURE}") + elseif(CMAKE_LIBRARY_ARCHITECTURE) + list(APPEND _CMAKE_HIP_COMPILER_ROCM_LIB_DIRS "${CMAKE_HIP_COMPILER_ROCM_ROOT}/lib/${CMAKE_LIBRARY_ARCHITECTURE}") endif() foreach(dir IN LISTS _CMAKE_HIP_COMPILER_ROCM_LIB_DIRS) if(EXISTS "${dir}/cmake/hip-lang/hip-lang-config.cmake") @@ -309,6 +326,9 @@ endif() endif() unset(CMAKE_HIP_ARCHITECTURES_DEFAULT) +elseif(NOT DEFINED CMAKE_HIP_ARCHITECTURES AND CMAKE_HIP_PLATFORM STREQUAL "spirv") + # chipStar handles targeting via hip package + set(CMAKE_HIP_ARCHITECTURES "OFF" CACHE STRING "HIP architectures") elseif(NOT DEFINED CMAKE_HIP_ARCHITECTURES) # Use 'rocm_agent_enumerator' to get the current GPU architecture. set(_CMAKE_HIP_ARCHITECTURES)
diff --git a/Modules/CMakeDetermineISPCCompiler.cmake b/Modules/CMakeDetermineISPCCompiler.cmake index 9b7866c..29e97fd 100644 --- a/Modules/CMakeDetermineISPCCompiler.cmake +++ b/Modules/CMakeDetermineISPCCompiler.cmake
@@ -29,7 +29,7 @@ set(CMAKE_ISPC_COMPILER_ARG1 "${CMAKE_ISPC_FLAGS_ENV_INIT}" CACHE STRING "First argument to ISPC compiler") endif() if(NOT EXISTS ${CMAKE_ISPC_COMPILER_INIT}) - message(FATAL_ERROR "Could not find compiler set in environment variable ISPC:\n$ENV{ISPC}.") + message(FATAL_ERROR "Could not find the compiler specified in the environment variable ISPC:\n$ENV{ISPC}.") endif() endif()
diff --git a/Modules/CMakeDetermineJavaCompiler.cmake b/Modules/CMakeDetermineJavaCompiler.cmake index b20a255..f66402e 100644 --- a/Modules/CMakeDetermineJavaCompiler.cmake +++ b/Modules/CMakeDetermineJavaCompiler.cmake
@@ -14,21 +14,21 @@ set(CMAKE_Java_COMPILER_ARG1 "${CMAKE_Java_FLAGS_ENV_INIT}" CACHE STRING "Arguments to Java compiler") endif() if(NOT EXISTS ${CMAKE_Java_COMPILER_INIT}) - message(SEND_ERROR "Could not find compiler set in environment variable JAVA_COMPILER:\n$ENV{JAVA_COMPILER}.") + message(SEND_ERROR "Could not find the compiler specified in the environment variable JAVA_COMPILER:\n$ENV{JAVA_COMPILER}.") endif() endif() if(NOT $ENV{JAVA_RUNTIME} STREQUAL "") get_filename_component(CMAKE_Java_RUNTIME_INIT $ENV{JAVA_RUNTIME} PROGRAM PROGRAM_ARGS CMAKE_Java_FLAGS_ENV_INIT) if(NOT EXISTS ${CMAKE_Java_RUNTIME_INIT}) - message(SEND_ERROR "Could not find compiler set in environment variable JAVA_RUNTIME:\n$ENV{JAVA_RUNTIME}.") + message(SEND_ERROR "Could not find the compiler specified in the environment variable JAVA_RUNTIME:\n$ENV{JAVA_RUNTIME}.") endif() endif() if(NOT $ENV{JAVA_ARCHIVE} STREQUAL "") get_filename_component(CMAKE_Java_ARCHIVE_INIT $ENV{JAVA_ARCHIVE} PROGRAM PROGRAM_ARGS CMAKE_Java_FLAGS_ENV_INIT) if(NOT EXISTS ${CMAKE_Java_ARCHIVE_INIT}) - message(SEND_ERROR "Could not find compiler set in environment variable JAVA_ARCHIVE:\n$ENV{JAVA_ARCHIVE}.") + message(SEND_ERROR "Could not find the compiler specified in the environment variable JAVA_ARCHIVE:\n$ENV{JAVA_ARCHIVE}.") endif() endif()
diff --git a/Modules/CMakeDetermineOBJCCompiler.cmake b/Modules/CMakeDetermineOBJCCompiler.cmake index 75b3900..f8d334a 100644 --- a/Modules/CMakeDetermineOBJCCompiler.cmake +++ b/Modules/CMakeDetermineOBJCCompiler.cmake
@@ -40,7 +40,7 @@ set(CMAKE_OBJC_COMPILER_ARG1 "${CMAKE_OBJC_FLAGS_ENV_INIT}" CACHE STRING "Arguments to Objective-C compiler") endif() if(NOT EXISTS ${CMAKE_OBJC_COMPILER_INIT}) - message(FATAL_ERROR "Could not find compiler set in environment variable ${var}:\n $ENV{${var}}") + message(FATAL_ERROR "Could not find the compiler specified in the environment variable ${var}:\n $ENV{${var}}") endif() break() endif()
diff --git a/Modules/CMakeDetermineOBJCXXCompiler.cmake b/Modules/CMakeDetermineOBJCXXCompiler.cmake index 8036da2..0c03eea 100644 --- a/Modules/CMakeDetermineOBJCXXCompiler.cmake +++ b/Modules/CMakeDetermineOBJCXXCompiler.cmake
@@ -42,7 +42,7 @@ set(CMAKE_OBJCXX_COMPILER_ARG1 "${CMAKE_OBJCXX_FLAGS_ENV_INIT}" CACHE STRING "Arguments to Objective-C++ compiler") endif() if(NOT EXISTS ${CMAKE_OBJCXX_COMPILER_INIT}) - message(FATAL_ERROR "Could not find compiler set in environment variable ${var}:\n $ENV{${var}}") + message(FATAL_ERROR "Could not find the compiler specified in the environment variable ${var}:\n $ENV{${var}}") endif() break() endif()
diff --git a/Modules/CMakeDetermineRCCompiler.cmake b/Modules/CMakeDetermineRCCompiler.cmake index 354fef4..5de8599 100644 --- a/Modules/CMakeDetermineRCCompiler.cmake +++ b/Modules/CMakeDetermineRCCompiler.cmake
@@ -17,7 +17,7 @@ endif() if(EXISTS ${CMAKE_RC_COMPILER_INIT}) else() - message(FATAL_ERROR "Could not find compiler set in environment variable RC:\n$ENV{RC}.") + message(FATAL_ERROR "Could not find the compiler specified in the environment variable RC:\n$ENV{RC}.") endif() endif()
diff --git a/Modules/CMakeDetermineRustCompiler.cmake b/Modules/CMakeDetermineRustCompiler.cmake new file mode 100644 index 0000000..43441b0 --- /dev/null +++ b/Modules/CMakeDetermineRustCompiler.cmake
@@ -0,0 +1,49 @@ +# Distributed under the OSI-approved BSD 3-Clause License. See accompanying +# file LICENSE.rst or https://cmake.org/licensing for details. + +include(${CMAKE_ROOT}/Modules/CMakeDetermineCompiler.cmake) + +if(NOT "${CMAKE_GENERATOR}" MATCHES "^Ninja") + message(FATAL_ERROR "Rust language not supported by \"${CMAKE_GENERATOR}\" generator") +endif() + +set(CMAKE_Rust_COMPILER_INIT "rustc") +set(CMAKE_Rust_COMPILER_HINTS "$ENV{HOME}/.cargo/bin") + +_cmake_find_compiler(Rust) + +get_filename_component(RUSTC_REAL "${CMAKE_Rust_COMPILER}" REALPATH) +get_filename_component(RUSTC_FILENAME "${RUSTC_REAL}" NAME) + +# When rustup is used for installing rust, rustc will just be a symlink to rustup. In such cases, +# we need to query rustup for underlying rustc path. +if(RUSTC_FILENAME STREQUAL "rustup") + get_filename_component(RUSTC_DIR "${CMAKE_Rust_COMPILER}" DIRECTORY) + set(RUSTUP_PATH "${RUSTC_DIR}/rustup") + + # Fix RUSTUP_HOME in ctest. + if(RUSTC_FILENAME STREQUAL "rustup" AND NOT "$ENV{CTEST_REAL_HOME}" STREQUAL "" AND "$ENV{RUSTUP_HOME}" STREQUAL "") + set(ENV{RUSTUP_HOME} "$ENV{CTEST_REAL_HOME}/.rustup") + endif() + + execute_process( + COMMAND ${RUSTUP_PATH} which rustc + OUTPUT_VARIABLE REAL_RUSTC + OUTPUT_STRIP_TRAILING_WHITESPACE + ) + + if("${REAL_RUSTC}" STREQUAL "") + message(FATAL_ERROR "Failed to find path to real rustc") + endif() + + set_property(CACHE CMAKE_Rust_COMPILER PROPERTY VALUE "${REAL_RUSTC}") +endif() + +if(CMAKE_Rust_COMPILER) + set(CMAKE_Rust_COMPILER_WORKS TRUE) +endif() + +configure_file( + "${CMAKE_ROOT}/Modules/CMakeRustCompiler.cmake.in" + "${CMAKE_PLATFORM_INFO_DIR}/CMakeRustCompiler.cmake" + @ONLY)
diff --git a/Modules/CMakeDetermineSwiftCompiler.cmake b/Modules/CMakeDetermineSwiftCompiler.cmake index 6d46e78..e9285b6 100644 --- a/Modules/CMakeDetermineSwiftCompiler.cmake +++ b/Modules/CMakeDetermineSwiftCompiler.cmake
@@ -37,7 +37,7 @@ STRING "Arguments to the Swift compiler") endif() if(NOT EXISTS ${CMAKE_Swift_COMPILER_INIT}) - message(FATAL_ERROR "Could not find compiler set in environment variable SWIFTC\n$ENV{SWIFTC}.\n${CMAKE_Swift_COMPILER_INIT}") + message(FATAL_ERROR "Could not find the compiler specified in the environment variable SWIFTC\n$ENV{SWIFTC}.\n${CMAKE_Swift_COMPILER_INIT}") endif() endif()
diff --git a/Modules/CMakeFastbuildFindMake.cmake b/Modules/CMakeFastbuildFindMake.cmake new file mode 100644 index 0000000..d37fac6 --- /dev/null +++ b/Modules/CMakeFastbuildFindMake.cmake
@@ -0,0 +1,7 @@ +# Distributed under the OSI-approved BSD 3-Clause License. See accompanying +# file LICENSE.rst or https://cmake.org/licensing for details. + +find_program(CMAKE_MAKE_PROGRAM + NAMES fbuild + DOC "Program used to build from FASTBuild .bff files.") +mark_as_advanced(CMAKE_MAKE_PROGRAM)
diff --git a/Modules/CMakeFindBinUtils.cmake b/Modules/CMakeFindBinUtils.cmake index 1948c63..91543a6 100644 --- a/Modules/CMakeFindBinUtils.cmake +++ b/Modules/CMakeFindBinUtils.cmake
@@ -219,6 +219,11 @@ list(PREPEND _CMAKE_LINKER_NAMES "armlink") endif() + if(EMSCRIPTEN) + list(PREPEND _CMAKE_AR_NAMES "emar") + list(PREPEND _CMAKE_RANLIB_NAMES "emranlib") + endif() + list(APPEND _CMAKE_TOOL_VARS AR RANLIB STRIP LINKER NM OBJDUMP OBJCOPY READELF DLLTOOL ADDR2LINE TAPI) endif() @@ -259,8 +264,7 @@ if(CMAKE_PLATFORM_HAS_INSTALLNAME) - find_program(CMAKE_INSTALL_NAME_TOOL NAMES ${_CMAKE_TOOLCHAIN_PREFIX}install_name_tool HINTS ${_CMAKE_TOOLCHAIN_LOCATION} NO_CMAKE_PATH NO_CMAKE_ENVIRONMENT_PATH) - + find_program(CMAKE_INSTALL_NAME_TOOL NAMES ${_CMAKE_TOOLCHAIN_PREFIX}install_name_tool llvm-install-name-tool HINTS ${_CMAKE_TOOLCHAIN_LOCATION} NO_CMAKE_PATH NO_CMAKE_ENVIRONMENT_PATH) if(NOT CMAKE_INSTALL_NAME_TOOL) message(FATAL_ERROR "Could not find install_name_tool, please check your installation.") endif()
diff --git a/Modules/CMakeFindDependencyMacro.cmake b/Modules/CMakeFindDependencyMacro.cmake index 99624d2..fba1f63 100644 --- a/Modules/CMakeFindDependencyMacro.cmake +++ b/Modules/CMakeFindDependencyMacro.cmake
@@ -5,6 +5,26 @@ CMakeFindDependencyMacro ------------------------ +This module provides a command implemented as a macro that finds dependency +for a package. + +Load this module in a CMake package configuration file with: + +.. code-block:: cmake + :caption: ``FooConfig.cmake`` or ``foo-config.cmake``: + + include(CMakeFindDependencyMacro) + +.. note:: + + This module is designed to be used in a :ref:`Package Configuration File + <Config File Packages>` (``<PackageName>Config.cmake``). + +Commands +^^^^^^^^ + +This module provides the following command: + .. command:: find_dependency The ``find_dependency()`` macro wraps a :command:`find_package` call for @@ -56,44 +76,59 @@ #]=======================================================================] -macro(find_dependency dep) +macro(__find_dependency_common cmake_fd_call_hash dep) + set(cmake_fd_quiet_arg) + if(${CMAKE_FIND_PACKAGE_NAME}_FIND_QUIETLY) + set(cmake_fd_quiet_arg QUIET) + endif() + set(cmake_fd_required_arg) + if(${CMAKE_FIND_PACKAGE_NAME}_FIND_REQUIRED) + set(cmake_fd_required_arg REQUIRED) + endif() + + get_property(cmake_fd_alreadyTransitive GLOBAL PROPERTY + _CMAKE_${dep}_TRANSITIVE_DEPENDENCY + ) + + find_package(${dep} ${ARGN} + ${cmake_fd_quiet_arg} + ${cmake_fd_required_arg} + ) + set("_CMAKE_${dep}_${cmake_fd_call_hash}_FOUND" "${${dep}_FOUND}") + + if(NOT DEFINED cmake_fd_alreadyTransitive OR cmake_fd_alreadyTransitive) + set_property(GLOBAL PROPERTY _CMAKE_${dep}_TRANSITIVE_DEPENDENCY TRUE) + endif() + + unset(cmake_fd_alreadyTransitive) + unset(cmake_fd_quiet_arg) + unset(cmake_fd_required_arg) +endmacro() + +macro(__find_dependency_no_return dep) string(SHA256 cmake_fd_call_hash "${dep};${ARGN};${${CMAKE_FIND_PACKAGE_NAME}_FIND_REQUIRED}") if(_CMAKE_${dep}_${cmake_fd_call_hash}_FOUND) - unset(cmake_fd_call_hash) + set(${dep}_FOUND ${_CMAKE_${dep}_${cmake_fd_call_hash}_FOUND}) else() - list(APPEND _CMAKE_${dep}_HASH_STACK ${cmake_fd_call_hash}) - set(cmake_fd_quiet_arg) - if(${CMAKE_FIND_PACKAGE_NAME}_FIND_QUIETLY) - set(cmake_fd_quiet_arg QUIET) - endif() - set(cmake_fd_required_arg) - if(${CMAKE_FIND_PACKAGE_NAME}_FIND_REQUIRED) - set(cmake_fd_required_arg REQUIRED) - endif() - - get_property(cmake_fd_alreadyTransitive GLOBAL PROPERTY - _CMAKE_${dep}_TRANSITIVE_DEPENDENCY - ) - - find_package(${dep} ${ARGN} - ${cmake_fd_quiet_arg} - ${cmake_fd_required_arg} - ) - list(POP_BACK _CMAKE_${dep}_HASH_STACK cmake_fd_call_hash) - set("_CMAKE_${dep}_${cmake_fd_call_hash}_FOUND" "${${dep}_FOUND}") - - if(NOT DEFINED cmake_fd_alreadyTransitive OR cmake_fd_alreadyTransitive) - set_property(GLOBAL PROPERTY _CMAKE_${dep}_TRANSITIVE_DEPENDENCY TRUE) - endif() - - unset(cmake_fd_alreadyTransitive) - unset(cmake_fd_call_hash) - unset(cmake_fd_quiet_arg) - unset(cmake_fd_required_arg) + __find_dependency_common(${cmake_fd_call_hash} ${ARGV}) if (NOT ${dep}_FOUND) set(${CMAKE_FIND_PACKAGE_NAME}_NOT_FOUND_MESSAGE "${CMAKE_FIND_PACKAGE_NAME} could not be found because dependency ${dep} could not be found.") set(${CMAKE_FIND_PACKAGE_NAME}_FOUND False) + endif() + endif() + unset(cmake_fd_call_hash) +endmacro() + +macro(find_dependency dep) + string(SHA256 cmake_fd_call_hash "${dep};${ARGN};${${CMAKE_FIND_PACKAGE_NAME}_FIND_REQUIRED}") + if(NOT _CMAKE_${dep}_${cmake_fd_call_hash}_FOUND) + __find_dependency_common(${cmake_fd_call_hash} ${ARGV}) + if (NOT ${dep}_FOUND) + set(${CMAKE_FIND_PACKAGE_NAME}_NOT_FOUND_MESSAGE "${CMAKE_FIND_PACKAGE_NAME} could not be found because dependency ${dep} could not be found.") + set(${CMAKE_FIND_PACKAGE_NAME}_FOUND False) + unset(cmake_fd_call_hash) return() endif() endif() + unset(cmake_fd_call_hash) endmacro()
diff --git a/Modules/CMakeForceCompiler.cmake b/Modules/CMakeForceCompiler.cmake index e85c3f9..9b85c68 100644 --- a/Modules/CMakeForceCompiler.cmake +++ b/Modules/CMakeForceCompiler.cmake
@@ -9,66 +9,98 @@ Do not use. -The macros provided by this module were once intended for use by -cross-compiling toolchain files when CMake was not able to automatically -detect the compiler identification. Since the introduction of this module, -CMake's compiler identification capabilities have improved and can now be -taught to recognize any compiler. Furthermore, the suite of information -CMake detects from a compiler is now too extensive to be provided by -toolchain files using these macros. + The commands provided by this module were once intended for use by + cross-compiling toolchain files when CMake was not able to automatically + detect the compiler identification. Since the introduction of this module, + CMake's compiler identification capabilities have improved and can now be + taught to recognize any compiler. Furthermore, the suite of information + CMake detects from a compiler is now too extensive to be provided by + toolchain files using these macros. -One common use case for this module was to skip CMake's checks for a -working compiler when using a cross-compiler that cannot link binaries -without special flags or custom linker scripts. This case is now supported -by setting the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable in the -toolchain file instead. + One common use case for this module was to skip CMake's checks for a + working compiler when using a cross-compiler that cannot link binaries + without special flags or custom linker scripts. This case is now supported + by setting the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable in the + toolchain file instead. -------------------------------------------------------------------------- - -Macro ``CMAKE_FORCE_C_COMPILER`` has the following signature: +Load this module in a CMake toolchain file: .. code-block:: cmake - CMAKE_FORCE_C_COMPILER(<compiler> <compiler-id>) + include(CMakeForceCompiler) -It sets :variable:`CMAKE_C_COMPILER <CMAKE_<LANG>_COMPILER>` to -the given compiler and the cmake internal variable -:variable:`CMAKE_C_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` to the given -compiler-id. It also bypasses the check for working compiler and basic -compiler information tests. +Commands +^^^^^^^^ -Macro ``CMAKE_FORCE_CXX_COMPILER`` has the following signature: +This module provides the following commands: + +.. command:: cmake_force_c_compiler + + Sets the :variable:`CMAKE_C_COMPILER <CMAKE_<LANG>_COMPILER>` variable to + the given compiler and the :variable:`CMAKE_C_COMPILER_ID + <CMAKE_<LANG>_COMPILER_ID>` variable to the given compiler-id: + + .. code-block:: cmake + + cmake_force_c_compiler(<compiler> <compiler-id>) + + This command also bypasses the check for working compiler and basic + compiler information tests. + +.. command:: cmake_force_cxx_compiler + + Sets the :variable:`CMAKE_CXX_COMPILER <CMAKE_<LANG>_COMPILER>` variable + to the given compiler and the :variable:`CMAKE_CXX_COMPILER_ID + <CMAKE_<LANG>_COMPILER_ID>` variable to the given compiler-id: + + .. code-block:: cmake + + cmake_force_cxx_compiler(<compiler> <compiler-id>) + + This command also bypasses the check for working compiler and basic + compiler information tests. + +.. command:: cmake_force_fortran_compiler + + Sets the :variable:`CMAKE_Fortran_COMPILER <CMAKE_<LANG>_COMPILER>` + variable to the given compiler and the + :variable:`CMAKE_Fortran_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` variable + to the given compiler-id: + + .. code-block:: cmake + + cmake_force_fortran_compiler(<compiler> <compiler-id>) + + This command also bypasses the check for working compiler and basic + compiler information tests. + +Examples +^^^^^^^^ + +A simple toolchain file using this module could look like this: .. code-block:: cmake + :caption: ``cmake/toolchains/example-toolchain.cmake`` - CMAKE_FORCE_CXX_COMPILER(<compiler> <compiler-id>) + include(CMakeForceCompiler) + set(CMAKE_SYSTEM_NAME Generic) + cmake_force_c_compiler(chc12 MetrowerksHicross) + cmake_force_cxx_compiler(chc12 MetrowerksHicross) -It sets :variable:`CMAKE_CXX_COMPILER <CMAKE_<LANG>_COMPILER>` to -the given compiler and the cmake internal variable -:variable:`CMAKE_CXX_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` to the given -compiler-id. It also bypasses the check for working compiler and basic -compiler information tests. - -Macro ``CMAKE_FORCE_Fortran_COMPILER`` has the following signature: +In new CMake code, compiler is detected automatically when setting required +variables instead: .. code-block:: cmake + :caption: ``cmake/toolchains/example-toolchain.cmake`` - CMAKE_FORCE_Fortran_COMPILER(<compiler> <compiler-id>) + set(CMAKE_SYSTEM_NAME Generic) + set(CMAKE_C_COMPILER chc12) + set(CMAKE_CXX_COMPILER chc12) -It sets :variable:`CMAKE_Fortran_COMPILER <CMAKE_<LANG>_COMPILER>` to -the given compiler and the cmake internal variable -:variable:`CMAKE_Fortran_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` to the given -compiler-id. It also bypasses the check for working compiler and basic -compiler information tests. +See Also +^^^^^^^^ -So a simple toolchain file could look like this: - -.. code-block:: cmake - - include (CMakeForceCompiler) - set(CMAKE_SYSTEM_NAME Generic) - CMAKE_FORCE_C_COMPILER (chc12 MetrowerksHicross) - CMAKE_FORCE_CXX_COMPILER (chc12 MetrowerksHicross) +* :manual:`cmake-toolchains(7)` #]=======================================================================] macro(CMAKE_FORCE_C_COMPILER compiler id)
diff --git a/Modules/CMakeFortranCompilerABI.F b/Modules/CMakeFortranCompilerABI.F index 81676cb..ed82730 100644 --- a/Modules/CMakeFortranCompilerABI.F +++ b/Modules/CMakeFortranCompilerABI.F
@@ -113,6 +113,8 @@ PRINT *, 'INFO:arch[riscv64]' #elif defined(__riscv) && __riscv_xlen == 32 PRINT *, 'INFO:arch[riscv32]' +#elif defined(__sw_64) || defined(__sw_64__) + PRINT *, 'INFO:arch[sw_64]' #elif defined(__s390x__) PRINT *, 'INFO:arch[s390x]' #elif defined(__s390__) @@ -141,6 +143,10 @@ # else PRINT *, 'INFO:arch[ppc]' # endif +#elif defined(__wasm64) || defined(__wasm64__) + PRINT *, 'INFO:arch[wasm64]' +#elif defined(__wasm32) || defined(__wasm32__) + PRINT *, 'INFO:arch[wasm32]' #endif PRINT *, 'ABI Detection'
diff --git a/Modules/CMakeFortranCompilerABI.F90 b/Modules/CMakeFortranCompilerABI.F90 index 2a9259b..1dfd560 100644 --- a/Modules/CMakeFortranCompilerABI.F90 +++ b/Modules/CMakeFortranCompilerABI.F90
@@ -105,6 +105,8 @@ PRINT *, 'INFO:arch[loongarch32]' #elif defined(__m68k__) PRINT *, 'INFO:arch[m68k]' +#elif defined(__sw_64) +PRINT *, 'INFO:arch[sw_64]' #elif defined(__mips64) || defined(__mips64__) # if defined(_MIPSEL) PRINT *, 'INFO:arch[mips64el]' @@ -149,6 +151,10 @@ # else PRINT *, 'INFO:arch[ppc]' # endif +#elif defined(__wasm64) || defined(__wasm64__) +PRINT *, 'INFO:arch[wasm64]' +#elif defined(__wasm32) || defined(__wasm32__) +PRINT *, 'INFO:arch[wasm32]' #endif PRINT *, 'ABI Detection'
diff --git a/Modules/CMakeGraphVizOptions.cmake b/Modules/CMakeGraphVizOptions.cmake index 1d7dc0f..ee1c55a 100644 --- a/Modules/CMakeGraphVizOptions.cmake +++ b/Modules/CMakeGraphVizOptions.cmake
@@ -5,146 +5,9 @@ CMakeGraphVizOptions -------------------- -The builtin Graphviz support of CMake. +.. note:: -Generating Graphviz files -^^^^^^^^^^^^^^^^^^^^^^^^^ - -CMake can generate `Graphviz <https://www.graphviz.org/>`_ files showing the -dependencies between the targets in a project, as well as external libraries -which are linked against. - -When running CMake with the ``--graphviz=foo.dot`` option, it produces: - -* a ``foo.dot`` file, showing all dependencies in the project -* a ``foo.dot.<target>`` file for each target, showing on which other targets - it depends -* a ``foo.dot.<target>.dependers`` file for each target, showing which other - targets depend on it - -Those .dot files can be converted to images using the *dot* command from the -Graphviz package: - -.. code-block:: shell - - dot -Tpng -o foo.png foo.dot - -.. versionadded:: 3.10 - The different dependency types ``PUBLIC``, ``INTERFACE`` and ``PRIVATE`` - are represented as solid, dashed and dotted edges. - -Variables specific to the Graphviz support -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The resulting graphs can be huge. The look and content of the generated graphs -can be controlled using the file ``CMakeGraphVizOptions.cmake``. This file is -first searched in :variable:`CMAKE_BINARY_DIR`, and then in -:variable:`CMAKE_SOURCE_DIR`. If found, the variables set in it are used to -adjust options for the generated Graphviz files. - -.. variable:: GRAPHVIZ_GRAPH_NAME - - The graph name. - - * Mandatory: NO - * Default: value of :variable:`CMAKE_PROJECT_NAME` - -.. variable:: GRAPHVIZ_GRAPH_HEADER - - The header written at the top of the Graphviz files. - - * Mandatory: NO - * Default: "node [ fontsize = "12" ];" - -.. variable:: GRAPHVIZ_NODE_PREFIX - - The prefix for each node in the Graphviz files. - - * Mandatory: NO - * Default: "node" - -.. variable:: GRAPHVIZ_EXECUTABLES - - Set to FALSE to exclude executables from the generated graphs. - - * Mandatory: NO - * Default: TRUE - -.. variable:: GRAPHVIZ_STATIC_LIBS - - Set to FALSE to exclude static libraries from the generated graphs. - - * Mandatory: NO - * Default: TRUE - -.. variable:: GRAPHVIZ_SHARED_LIBS - - Set to FALSE to exclude shared libraries from the generated graphs. - - * Mandatory: NO - * Default: TRUE - -.. variable:: GRAPHVIZ_MODULE_LIBS - - Set to FALSE to exclude module libraries from the generated graphs. - - * Mandatory: NO - * Default: TRUE - -.. variable:: GRAPHVIZ_INTERFACE_LIBS - - Set to FALSE to exclude interface libraries from the generated graphs. - - * Mandatory: NO - * Default: TRUE - -.. variable:: GRAPHVIZ_OBJECT_LIBS - - Set to FALSE to exclude object libraries from the generated graphs. - - * Mandatory: NO - * Default: TRUE - -.. variable:: GRAPHVIZ_UNKNOWN_LIBS - - Set to FALSE to exclude unknown libraries from the generated graphs. - - * Mandatory: NO - * Default: TRUE - -.. variable:: GRAPHVIZ_EXTERNAL_LIBS - - Set to FALSE to exclude external libraries from the generated graphs. - - * Mandatory: NO - * Default: TRUE - -.. variable:: GRAPHVIZ_CUSTOM_TARGETS - - Set to TRUE to include custom targets in the generated graphs. - - * Mandatory: NO - * Default: FALSE - -.. variable:: GRAPHVIZ_IGNORE_TARGETS - - A list of regular expressions for names of targets to exclude from the - generated graphs. - - * Mandatory: NO - * Default: empty - -.. variable:: GRAPHVIZ_GENERATE_PER_TARGET - - Set to FALSE to not generate per-target graphs ``foo.dot.<target>``. - - * Mandatory: NO - * Default: TRUE - -.. variable:: GRAPHVIZ_GENERATE_DEPENDERS - - Set to FALSE to not generate depender graphs ``foo.dot.<target>.dependers``. - - * Mandatory: NO - * Default: TRUE + This module is not intended to be included in CMake projects directly. + It once contained the information for using Graphviz in CMake. For + Graphviz usage in CMake refer to the :option:`cmake --graphviz`. #]=======================================================================]
diff --git a/Modules/CMakeHIPInformation.cmake b/Modules/CMakeHIPInformation.cmake index 9162129..e8d0232 100644 --- a/Modules/CMakeHIPInformation.cmake +++ b/Modules/CMakeHIPInformation.cmake
@@ -69,6 +69,13 @@ # CMAKE_HIP_COMPILE_OBJECT # CMAKE_HIP_LINK_EXECUTABLE +# For spirv platform (chipStar), set compile and link commands +if(CMAKE_HIP_PLATFORM STREQUAL "spirv") + include(Internal/CMakeChipStarHIP) + _cmake_chipstar_set_compiler_flags() + _cmake_chipstar_set_link_commands() +endif() + # create a shared library if(NOT CMAKE_HIP_CREATE_SHARED_LIBRARY) set(CMAKE_HIP_CREATE_SHARED_LIBRARY
diff --git a/Modules/CMakePackageConfigHelpers.cmake b/Modules/CMakePackageConfigHelpers.cmake index ba03080..c253296 100644 --- a/Modules/CMakePackageConfigHelpers.cmake +++ b/Modules/CMakePackageConfigHelpers.cmake
@@ -5,9 +5,16 @@ CMakePackageConfigHelpers ------------------------- -Helper functions for creating config files that can be included by other +This module provides helper commands for creating :ref:`config files +<Libraries providing Config-file packages>` that can be included by other projects to find and use a package. +Load this module in a CMake project with: + +.. code-block:: cmake + + include(CMakePackageConfigHelpers) + Generating a Package Configuration File ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/Modules/CMakeParseImplicitLinkInfo.cmake b/Modules/CMakeParseImplicitLinkInfo.cmake index 77e999c..1b16a68 100644 --- a/Modules/CMakeParseImplicitLinkInfo.cmake +++ b/Modules/CMakeParseImplicitLinkInfo.cmake
@@ -71,6 +71,9 @@ if(is_cray) string(APPEND linker "|cce_omp_offload_linker") endif() + if(CMAKE_SYSTEM_NAME STREQUAL "Emscripten") + string(APPEND linker "|wasm-ld") + endif() if(CMAKE_LINKER) get_filename_component(default_linker ${CMAKE_LINKER} NAME) if (NOT default_linker MATCHES "(${linker})") @@ -86,7 +89,10 @@ # whole line and just the command (argv[0]). set(linker_regex "^( *|.*[/\\])(${linker}|${startfile}|([^/\\]+-)?ld|collect2)[^/\\]*( |$)") set(linker_exclude_regex "collect2 version |^[A-Za-z0-9_]+=|/ldfe ") - set(linker_tool_regex "^[ \t]*(->|\")?[ \t]*(([^\"]*[/\\])?(${linker}))(\"|,| |$)") + + # Skip FASTBuild's output mangling, like: + # "2> -Build: 0 ms .../link.exe"/"13>-Build: 0 ms .../link.exe" + set(linker_tool_regex "^[ \t]*(->|\"|[0-9]+>[ \t-]*Build:[ \t0-9]+ ms[ \t]*)?[ \t]*(([^\"]*[/\\])?(${linker}))(\"|,| |$)") set(linker_tool_exclude_regex "cuda-fake-ld|-fuse-ld=|^ExecuteExternalTool ") if(is_lfortran_less_0_40) # lfortran < 0.40 has no way to pass -v to clang/gcc driver.
diff --git a/Modules/CMakePrintSystemInformation.cmake b/Modules/CMakePrintSystemInformation.cmake index 4a539bc..da04af8 100644 --- a/Modules/CMakePrintSystemInformation.cmake +++ b/Modules/CMakePrintSystemInformation.cmake
@@ -7,16 +7,27 @@ This module can be used for diagnostics to print system information. -Examples -^^^^^^^^ - -Including this module in a project: +Load this module in a CMake project with: .. code-block:: cmake include(CMakePrintSystemInformation) -prints various internal CMake variables. For example:: +Examples +^^^^^^^^ + +For example, including this module in a project: + +.. code-block:: cmake + :caption: ``CMakeLists.txt`` + + project(Example) + + # ... + + include(CMakePrintSystemInformation) + +prints various CMake variables:: CMAKE_SYSTEM is Linux-6.11.0-17-generic Linux 6.11.0-17-generic x86_64 CMAKE_SYSTEM file is Platform/Linux
diff --git a/Modules/CMakePushCheckState.cmake b/Modules/CMakePushCheckState.cmake index cbf49de..30505cd 100644 --- a/Modules/CMakePushCheckState.cmake +++ b/Modules/CMakePushCheckState.cmake
@@ -11,7 +11,7 @@ how various CMake check commands (e.g., :command:`check_symbol_exists`, etc.) are performed. -Load this module in CMake project with: +Load this module in a CMake project with: .. code-block:: cmake
diff --git a/Modules/CMakeRustCompiler.cmake.in b/Modules/CMakeRustCompiler.cmake.in new file mode 100644 index 0000000..deb19ba --- /dev/null +++ b/Modules/CMakeRustCompiler.cmake.in
@@ -0,0 +1,5 @@ +set(CMAKE_Rust_COMPILER "@CMAKE_Rust_COMPILER@") +set(CMAKE_Rust_COMPILER_ENV_VAR "RUSTC") +set(CMAKE_Rust_SOURCE_FILE_EXTENSIONS rs) +set(CMAKE_Rust_COMPILER_LOADED 1) +set(CMAKE_Rust_COMPILER_WORKS @CMAKE_Rust_COMPILER_WORKS@)
diff --git a/Modules/CMakeRustInformation.cmake b/Modules/CMakeRustInformation.cmake new file mode 100644 index 0000000..2224d01 --- /dev/null +++ b/Modules/CMakeRustInformation.cmake
@@ -0,0 +1,41 @@ +# Distributed under the OSI-approved BSD 3-Clause License. See accompanying +# file LICENSE.rst or https://cmake.org/licensing for details. + +include(CMakeLanguageInformation) + +if(UNIX) + set(CMAKE_Rust_OUTPUT_EXTENSION .o) +else() + set(CMAKE_Rust_OUTPUT_EXTENSION .obj) +endif() + +set(CMAKE_Rust_LIBRARY_PATH_FLAG "-L ") +set(CMAKE_Rust_LINK_LIBRARY_FILE_FLAG "-C link-arg=") +set(CMAKE_EXECUTABLE_RUNTIME_Rust_FLAG "-C link-arg=-Wl,-rpath,") +set(CMAKE_EXECUTABLE_RUNTIME_Rust_FLAG_SEP ",") + +set(CMAKE_Rust_FLAGS_DEBUG_INIT "-C opt-level=0 -g") +set(CMAKE_Rust_FLAGS_RELEASE_INIT "-O") +set(CMAKE_Rust_FLAGS_RELWITHDEBINFO_INIT "-O -g") +set(CMAKE_Rust_FLAGS_MINSIZEREL_INIT "-C opt-level=z") + +cmake_initialize_per_config_variable(CMAKE_Rust_FLAGS "Flags used by the Rust compiler") + +if(NOT CMAKE_Rust_CREATE_STATIC_LIBRARY) + set(CMAKE_Rust_CREATE_STATIC_LIBRARY "${CMAKE_Rust_COMPILER} <LANGUAGE_COMPILE_FLAGS> --crate-type=staticlib <RUST_SOURCES> -o <TARGET> -C link-args=\"<RUST_OBJECT_DEPS>\"") +endif() + +if(NOT CMAKE_Rust_CREATE_SHARED_LIBRARY) + set(CMAKE_Rust_CREATE_SHARED_LIBRARY "${CMAKE_Rust_COMPILER} <LANGUAGE_COMPILE_FLAGS> --crate-type=cdylib <RUST_SOURCES> -o <TARGET> <LINK_FLAGS> <LINK_LIBRARIES> -C link-args=\"<RUST_OBJECT_DEPS>\"") +endif() + +# Deadcode warnings are not useful when generating object files. +if(NOT CMAKE_Rust_COMPILE_OBJECT) + set(CMAKE_Rust_COMPILE_OBJECT "${CMAKE_Rust_COMPILER} <FLAGS> -A dead_code --crate-type=lib --emit=obj=<OBJECT>,dep-info=<DEP_FILE> <SOURCE>") +endif() + +if(NOT CMAKE_Rust_LINK_EXECUTABLE) + set(CMAKE_Rust_LINK_EXECUTABLE "${CMAKE_Rust_COMPILER} <FLAGS> --crate-type=bin <RUST_SOURCES> -o <TARGET> <LINK_FLAGS> <LINK_LIBRARIES> -C link-args=\"<RUST_OBJECT_DEPS>\"") +endif() + +set(CMAKE_Rust_INFORMATION_LOADED 1)
diff --git a/Modules/CMakeTestHIPCompiler.cmake b/Modules/CMakeTestHIPCompiler.cmake index 60b2121..ed1df10 100644 --- a/Modules/CMakeTestHIPCompiler.cmake +++ b/Modules/CMakeTestHIPCompiler.cmake
@@ -11,7 +11,7 @@ set(__CMAKE_HIP_FLAGS "${CMAKE_HIP_FLAGS}") -if(CMAKE_HIP_COMPILER_ID STREQUAL "Clang") +if(CMAKE_HIP_COMPILER_ID STREQUAL "Clang" AND NOT CMAKE_HIP_PLATFORM STREQUAL "spirv") string(APPEND CMAKE_HIP_FLAGS " --cuda-host-only") endif()
diff --git a/Modules/CMakeTestRustCompiler.cmake b/Modules/CMakeTestRustCompiler.cmake new file mode 100644 index 0000000..8e3e819 --- /dev/null +++ b/Modules/CMakeTestRustCompiler.cmake
@@ -0,0 +1,9 @@ +# Distributed under the OSI-approved BSD 3-Clause License. See accompanying +# file LICENSE.rst or https://cmake.org/licensing for details. + +configure_file( + "${CMAKE_ROOT}/Modules/CMakeRustCompiler.cmake.in" + "${CMAKE_PLATFORM_INFO_DIR}/CMakeRustCompiler.cmake" + @ONLY) + +include(${CMAKE_PLATFORM_INFO_DIR}/CMakeRustCompiler.cmake)
diff --git a/Modules/CMakeVerifyManifest.cmake b/Modules/CMakeVerifyManifest.cmake index d98a49e..5333869 100644 --- a/Modules/CMakeVerifyManifest.cmake +++ b/Modules/CMakeVerifyManifest.cmake
@@ -5,31 +5,53 @@ CMakeVerifyManifest ------------------- -Use this script to verify that embedded manifests and side-by-side -manifests for a project match. +This module is intended to be used in command-line mode using the +:ref:`cmake -P <Script Processing Mode>` to verify that embedded manifests +and side-by-side manifests for a project match. -This script first recursively globs ``*.manifest`` files from -the current directory and creates a list of allowed version. -Additional versions can be passed by setting ``allow_versions`` -from the invocation command. -Next, the script globs ``*.exe`` and ``*.dll`` files. Each +Load this module in a CMake script with: + +.. code-block:: cmake + + include(CMakeVerifyManifest) + +This module first recursively globs ``*.manifest`` files from +the current source directory and creates a list of allowed versions. + +Next, the script globs all ``*.exe`` and ``*.dll`` files. Each ``.exe`` and ``.dll`` file is scanned for embedded manifests and the versions of CRT are checked to be in the list of allowed -version. +versions. -Example -^^^^^^^ +Input Variables +^^^^^^^^^^^^^^^ -To run this script, navigate to a directory and run the script -with ``cmake -P``. +This module accepts the following variables: -:: +``allow_versions`` + Additional versions can be passed by setting the ``allow_versions`` + variable from the invocation command. This enables using additional + embedded manifest versions in a project, even if that version was not + found in a ``.manifest`` file. - cmake -Dallow_versions=8.0.50608.0 -PCMakeVerifyManifest.cmake +Examples +^^^^^^^^ -This call allows an embedded manifest of 8.0.50608.0 to be used -in a project, even if that version was not found in a -``.manifest`` file. +To use this module in the project, create a local command-line script (for +example, in the project's subdirectory ``cmake/scripts``) and include the +module: + +.. code-block:: cmake + :caption: ``cmake/scripts/verify-manifest.cmake`` + + include(CMakeVerifyManifest) + +Then run the local script in command-line and, for example, specify +additional embedded manifest of ``8.0.50608.0`` to be used in a project: + +.. code-block:: shell + + cmake -Dallow_versions=8.0.50608.0 -Pcmake/scripts/verify-manifest.cmake #]=======================================================================] # crt_version:
diff --git a/Modules/CPack.cmake b/Modules/CPack.cmake index 803332b..b8e7049 100644 --- a/Modules/CPack.cmake +++ b/Modules/CPack.cmake
@@ -5,7 +5,13 @@ CPack ----- -Configure generators for binary installers and source packages. +This module configures generators for binary installers and source packages. + +Load this module in a CMake project with: + +.. code-block:: cmake + + include(CPack) Introduction ^^^^^^^^^^^^ @@ -198,8 +204,8 @@ .. versionadded:: 3.7 - An algorithm that will be used to generate an additional file with the - checksum of the package. The output file name will be: + One or multiple algorithms that will be used to generate additional files with + the checksum of the package. The output file names will be: .. code-block:: cmake @@ -208,6 +214,9 @@ Supported algorithms are those listed by the :ref:`string(\<HASH\>) <Supported Hash Algorithms>` command. + .. versionchanged:: 4.2 + The variable accepts a list of algorithms. + .. variable:: CPACK_PROJECT_CONFIG_FILE CPack-time project CPack configuration file. This file is included at cpack @@ -329,6 +338,24 @@ Other compression methods ignore this value and use only one thread. +.. variable:: CPACK_COMPRESSION_LEVEL + + .. versionadded:: 4.3 + + Select the compression level to use when it's applicable, + such as compressing the installer package. + + Some compression methods used by CPack generators such as Debian or Archive + may take advantage of different compression levels. The accepted values + are in the range ``0`` to ``9``. If you select the ``zstd`` compression method, + you can select the compression level between ``0`` and ``19``, except the ``zip`` + archive format. + + By default ``CPACK_COMPRESSION_LEVEL`` is set to ``0``, which selects the default + compression level. It is selected automatically by the archive library backend and + not directly set by CMake itself. The default compression level + may vary between archive formats, platforms, etc. + Variables for Source Package Generators ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -545,16 +572,15 @@ function(cpack_encode_variables) set(commands "") get_cmake_property(res VARIABLES) - foreach(var ${res}) - if(var MATCHES "^CPACK") - if(CPACK_VERBATIM_VARIABLES) - _cpack_escape_for_cmake(value "${${var}}") - else() - set(value "${${var}}") - endif() - - string(APPEND commands "\nset(${var} \"${value}\")") + list(FILTER res INCLUDE REGEX "^CPACK") + foreach(var IN LISTS res) + if(CPACK_VERBATIM_VARIABLES) + _cpack_escape_for_cmake(value "${${var}}") + else() + set(value "${${var}}") endif() + + string(APPEND commands "\nset(${var} \"${value}\")") endforeach() set(_CPACK_OTHER_VARIABLES_ "${commands}" PARENT_SCOPE) @@ -927,6 +953,24 @@ endif() unset(_CPack_CMP0161) +# Archive specific variables +if(NOT DEFINED CPACK_ARCHIVE_UID AND NOT DEFINED CPACK_ARCHIVE_GID) + cmake_policy(GET CMP0206 _CPack_CMP0206) + if(NOT "x${_CPack_CMP0206}x" STREQUAL "xNEWx") + if(NOT "x${_CPack_CMP0206}x" STREQUAL "xOLDx" AND CMAKE_POLICY_WARNING_CMP0206) + cmake_policy(GET_WARNING CMP0206 _CMP0206_warning) + message(AUTHOR_WARNING + "${_CMP0206_warning}\n" + "For compatibility, CMake will set archive UID/GID to -1/-1." + ) + unset(_CMP0206_warning) + endif() + _cpack_set_default(CPACK_ARCHIVE_UID "-1") + _cpack_set_default(CPACK_ARCHIVE_GID "-1") + endif() + unset(_CPack_CMP0206) +endif() + # set sysroot so SDK tools can be used if(CMAKE_OSX_SYSROOT) _cpack_set_default(CPACK_OSX_SYSROOT "${_CMAKE_OSX_SYSROOT_PATH}")
diff --git a/Modules/CPackComponent.cmake b/Modules/CPackComponent.cmake index 3197fc3..96d6bde 100644 --- a/Modules/CPackComponent.cmake +++ b/Modules/CPackComponent.cmake
@@ -5,7 +5,14 @@ CPackComponent -------------- -Configure components for binary installers and source packages. +This module provides commands to configure components for binary installers +and source packages. + +Load this module in a CMake project with: + +.. code-block:: cmake + + include(CPackComponent) .. only:: html @@ -14,7 +21,7 @@ Introduction ^^^^^^^^^^^^ -This module is automatically included by :module:`CPack`. +This module is also automatically included by :module:`CPack`. Certain binary installers (especially the graphical installers) generated by CPack allow users to select individual application *components* to install.
diff --git a/Modules/CPackIFW.cmake b/Modules/CPackIFW.cmake index 2a2f478..8826064 100644 --- a/Modules/CPackIFW.cmake +++ b/Modules/CPackIFW.cmake
@@ -11,6 +11,12 @@ `Qt Installer Framework <https://doc.qt.io/qtinstallerframework/index.html>`_ (QtIFW). +Load this module in a CMake project with: + +.. code-block:: cmake + + include(CPackIFW) + The module also defines several commands to control the behavior of the :cpack_gen:`CPack IFW Generator`. @@ -639,7 +645,7 @@ endmacro() # Resolve full path to license file -macro(_cpack_ifw_resolve_lisenses _variable) +macro(_cpack_ifw_resolve_licenses _variable) if(${_variable}) set(_ifw_license_file FALSE) set(_ifw_licenses_fix) @@ -683,7 +689,7 @@ cmake_parse_arguments(CPACK_IFW_COMPONENT_${_CPACK_IFWCOMP_UNAME} "${_IFW_OPT}" "${_IFW_ARGS}" "${_IFW_MULTI_ARGS}" ${ARGN}) _cpack_ifw_resolve_script(CPACK_IFW_COMPONENT_${_CPACK_IFWCOMP_UNAME}_SCRIPT) - _cpack_ifw_resolve_lisenses(CPACK_IFW_COMPONENT_${_CPACK_IFWCOMP_UNAME}_LICENSES) + _cpack_ifw_resolve_licenses(CPACK_IFW_COMPONENT_${_CPACK_IFWCOMP_UNAME}_LICENSES) _cpack_ifw_resolve_file_list(CPACK_IFW_COMPONENT_${_CPACK_IFWCOMP_UNAME}_USER_INTERFACES) _cpack_ifw_resolve_file_list(CPACK_IFW_COMPONENT_${_CPACK_IFWCOMP_UNAME}_TRANSLATIONS) @@ -724,7 +730,7 @@ cmake_parse_arguments(CPACK_IFW_COMPONENT_GROUP_${_CPACK_IFWGRP_UNAME} "${_IFW_OPT}" "${_IFW_ARGS}" "${_IFW_MULTI_ARGS}" ${ARGN}) _cpack_ifw_resolve_script(CPACK_IFW_COMPONENT_GROUP_${_CPACK_IFWGRP_UNAME}_SCRIPT) - _cpack_ifw_resolve_lisenses(CPACK_IFW_COMPONENT_GROUP_${_CPACK_IFWGRP_UNAME}_LICENSES) + _cpack_ifw_resolve_licenses(CPACK_IFW_COMPONENT_GROUP_${_CPACK_IFWGRP_UNAME}_LICENSES) _cpack_ifw_resolve_file_list(CPACK_IFW_COMPONENT_GROUP_${_CPACK_IFWGRP_UNAME}_USER_INTERFACES) _cpack_ifw_resolve_file_list(CPACK_IFW_COMPONENT_GROUP_${_CPACK_IFWGRP_UNAME}_TRANSLATIONS)
diff --git a/Modules/CPackIFWConfigureFile.cmake b/Modules/CPackIFWConfigureFile.cmake index 6759c9c..bed78f9 100644 --- a/Modules/CPackIFWConfigureFile.cmake +++ b/Modules/CPackIFWConfigureFile.cmake
@@ -7,33 +7,113 @@ .. versionadded:: 3.8 -The module defines :command:`configure_file` similar command to -configure file templates prepared in QtIFW/SDK/Creator style. +This module provides a command similar to :command:`configure_file` for +configuring file templates prepared in QtIFW/SDK/Creator style. +Load this module in a CMake project with: + +.. code-block:: cmake + + include(CPackIFWConfigureFile) Commands ^^^^^^^^ -The module defines the following commands: +This module provides the following command: .. command:: cpack_ifw_configure_file - Copy a file to another location and modify its contents. + Copies a file template to output file and substitutes variable values + referenced as ``%{VAR}`` or ``%VAR%`` from the input file template + content: .. code-block:: cmake cpack_ifw_configure_file(<input> <output>) - Copies an ``<input>`` file to an ``<output>`` file and substitutes variable - values referenced as ``%{VAR}`` or ``%VAR%`` in the input file content. + ``<input>`` + Input file template. If given as a relative path, it is interpreted as + relative to the current source directory + (:variable:`CMAKE_CURRENT_SOURCE_DIR`). + + ``<output>`` + Output file. If given as a relative path, it is interpreted as relative + to the current binary directory (:variable:`CMAKE_CURRENT_BINARY_DIR`). + + Qt Installer Framework (QtIFW) uses ``@`` characters for embedding + predefined variables (``TargetDir``, ``StartMenuDir``, etc.) in Qt + installer scripts: + + .. code-block:: javascript + :caption: ``example.qs`` + + component.addOperation( + "CreateShortcut", + "@TargetDir@/example.com.html", + "@StartMenuDir@/Example Web Site.lnk" + ); + + The purpose of this command is to preserve the QtIFW predefined variables + containing the ``@`` characters (``@VAR@``), and instead use the ``%`` + characters for template placeholders (``%VAR%``, ``%{VAR}``) in + Qt/IFW/SDK/Creator templates. The :command:`configure_file` command + would otherwise replace all variable references containing the ``@`` + characters. + Each variable reference will be replaced with the current value of the variable, or the empty string if the variable is not defined. -#]=======================================================================] +Examples +^^^^^^^^ -# NOTE: This file used to himself packaging via CPack IFW generator and -# should be compatible with minimal CMake version defined in -# ../CMakeLists.txt file. +In the following example this module is used to create an IFW component +script from a given template file ``qt.tools.foo.qs.in``, where +``%FOO_DOC_DIR%`` variable reference will be replaced by the values of +the ``FOO_DOC_DIR`` CMake variable. + +.. code-block:: cmake + :caption: ``CMakeLists.txt`` + + cmake_minimum_required(VERSION 3.8) + + project(Foo) + + # ... + + include(CPackIFWConfigureFile) + + set(FOO_DOC_DIR "doc/foo") + + cpack_ifw_configure_file(qt.tools.foo.qs.in qt.tools.foo.qs) + +.. code-block:: javascript + :caption: ``qt.tools.foo.qs.in`` + + function Component() + { + } + + Component.prototype.createOperations = function() + { + if (installer.value("os") === "win") { + component.addOperation( + "CreateShortcut", + "@TargetDir@/%FOO_DOC_DIR%/example.com.html", + "@StartMenuDir@/Example Web Site.lnk" + ); + } + + component.createOperations(); + } + + // ... + +See Also +^^^^^^^^ + +* The :cpack_gen:`CPack IFW Generator`. +* The :module:`CPackIFW` module. +#]=======================================================================] if(NOT DEFINED CPackIFWConfigureFile_CMake_INCLUDED) set(CPackIFWConfigureFile_CMake_INCLUDED 1)
diff --git a/Modules/CTest.cmake b/Modules/CTest.cmake index 06d11bb..66f6cda 100644 --- a/Modules/CTest.cmake +++ b/Modules/CTest.cmake
@@ -7,7 +7,7 @@ Configure a project for testing with CTest/CDash -Include this module in the top CMakeLists.txt file of a project to +Include this module in the top ``CMakeLists.txt`` file of a project to enable testing with CTest and dashboard submissions to CDash: .. code-block:: cmake @@ -41,8 +41,8 @@ set(CTEST_NIGHTLY_START_TIME "01:00:00 UTC") set(CTEST_SUBMIT_URL "http://my.cdash.org/submit.php?project=MyProject") -(the CDash server can provide the file to a project administrator who -configures ``MyProject``). Settings in the config file are shared by +The CDash server can provide the file to a project administrator who +configures ``MyProject``. Settings in the config file are shared by both this ``CTest`` module and the :manual:`ctest(1)` command-line :ref:`Dashboard Client` mode (:option:`ctest -S`).
diff --git a/Modules/CTestCoverageCollectGCOV.cmake b/Modules/CTestCoverageCollectGCOV.cmake index 4c1211f..f36c022 100644 --- a/Modules/CTestCoverageCollectGCOV.cmake +++ b/Modules/CTestCoverageCollectGCOV.cmake
@@ -65,14 +65,53 @@ Specify a compression algorithm for the ``TARBALL`` data file. Using this option reduces the size of the data file - before it is submitted to CDash. ``<compression>`` must be one of ``GZIP``, - ``BZIP2``, ``XZ``, ``ZSTD``, ``FROM_EXT``, or an expression that CMake - evaluates as ``FALSE``. The default value is ``BZIP2``. + before it is submitted to CDash. + ``<compression>`` should be one of the following: + + * ``GZIP`` + * ``BZIP2`` + * ``LZMA`` + + .. versionadded:: 4.3 + + * ``LZMA2`` + + .. versionadded:: 4.3 + + This is an alias for ``XZ``. + + * ``XZ`` + * ``ZSTD`` + * ``FROM_EXT`` + * An expression that CMake evaluates as ``FALSE`` + + The default value is ``BZIP2``. If ``FROM_EXT`` is specified, the resulting file will be compressed based on the file extension of the ``<tar-file>`` (i.e. ``.tar.gz`` will use ``GZIP`` - compression). File extensions that will produce compressed output include - ``.tar.gz``, ``.tgz``, ``.tar.bzip2``, ``.tbz``, ``.tar.xz``, and ``.txz``. + compression). File extensions that will produce compressed output include: + + * ``.tar.gz`` + * ``.tgz`` + * ``.tar.bzip2`` + * ``.tbz`` + * ``.tar.xz`` + * ``.txz`` + * ``.tar.lzma`` + + .. versionadded:: 4.3 + + * ``.tlzma`` + + .. versionadded:: 4.3 + + * ``.tar.zst`` + + .. versionadded:: 4.3 + + * ``.tzst`` + + .. versionadded:: 4.3 ``SOURCE <source-dir>`` Specify the top-level source directory for the build. @@ -152,12 +191,12 @@ else() set(gcov_command "${GCOV_GCOV_COMMAND}") endif() + set(supported_compressions "GZIP" "BZIP2" "LZMA" "LZMA2" "XZ" "ZSTD" "FROM_EXT") if(NOT DEFINED GCOV_TARBALL_COMPRESSION) set(GCOV_TARBALL_COMPRESSION "BZIP2") elseif( GCOV_TARBALL_COMPRESSION AND - NOT GCOV_TARBALL_COMPRESSION MATCHES "^(GZIP|BZIP2|XZ|ZSTD|FROM_EXT)$") - message(FATAL_ERROR "TARBALL_COMPRESSION must be one of OFF, GZIP, " - "BZIP2, XZ, ZSTD, or FROM_EXT for ctest_coverage_collect_gcov") + NOT GCOV_TARBALL_COMPRESSION IN_LIST supported_compressions) + message(FATAL_ERROR "TARBALL_COMPRESSION must be OFF or one of ${supported_compressions} for ctest_coverage_collect_gcov") endif() # run gcov on each gcda file in the binary tree set(gcda_files) @@ -341,6 +380,7 @@ # Prepare tar command line arguments set(tar_opts "") + set(zstd_tar_opt "") # Select data compression mode if( GCOV_TARBALL_COMPRESSION STREQUAL "FROM_EXT") if( GCOV_TARBALL MATCHES [[\.(tgz|tar.gz)$]] ) @@ -349,15 +389,21 @@ string(APPEND tar_opts "J") elseif( GCOV_TARBALL MATCHES [[\.(tbz|tar.bz)$]] ) string(APPEND tar_opts "j") + elseif( GCOV_TARBALL MATCHES [[\.(tlzma|tar.lzma)$]] ) + set(zstd_tar_opt "--lzma") + elseif( GCOV_TARBALL MATCHES [[\.(tzst|tar.zst)$]] ) + set(zstd_tar_opt "--zstd") endif() elseif(GCOV_TARBALL_COMPRESSION STREQUAL "GZIP") string(APPEND tar_opts "z") - elseif(GCOV_TARBALL_COMPRESSION STREQUAL "XZ") + elseif((GCOV_TARBALL_COMPRESSION STREQUAL "XZ") OR (GCOV_TARBALL_COMPRESSION STREQUAL "LZMA2")) string(APPEND tar_opts "J") elseif(GCOV_TARBALL_COMPRESSION STREQUAL "BZIP2") string(APPEND tar_opts "j") elseif(GCOV_TARBALL_COMPRESSION STREQUAL "ZSTD") set(zstd_tar_opt "--zstd") + elseif(GCOV_TARBALL_COMPRESSION STREQUAL "LZMA") + set(zstd_tar_opt "--lzma") endif() # Verbosity options if(NOT GCOV_QUIET AND NOT tar_opts MATCHES v)
diff --git a/Modules/CTestScriptMode.cmake b/Modules/CTestScriptMode.cmake index d5dbddb..b8f98b4 100644 --- a/Modules/CTestScriptMode.cmake +++ b/Modules/CTestScriptMode.cmake
@@ -5,9 +5,11 @@ CTestScriptMode --------------- +.. note:: - -This file is read by ctest in script mode (-S) + This module is not intended to be included or invoked directly by project + code. It is internally used by CTest running in script mode (-S) to + determine current system. For usage details refer to the :option:`ctest -S`. #]=======================================================================] # Determine the current system, so this information can be used
diff --git a/Modules/CTestTargets.cmake b/Modules/CTestTargets.cmake index 5a7232f..2840875 100644 --- a/Modules/CTestTargets.cmake +++ b/Modules/CTestTargets.cmake
@@ -86,7 +86,7 @@ endforeach() # For Makefile generators add more granular targets. - if("${CMAKE_GENERATOR}" MATCHES "(Ninja|Make)") + if("${CMAKE_GENERATOR}" MATCHES "(Ninja|Make|FASTBuild)") # Make targets for Experimental builds foreach(mode Nightly Experimental Continuous) foreach(testtype
diff --git a/Modules/CTestUseLaunchers.cmake b/Modules/CTestUseLaunchers.cmake index dc015f8..0ffaa11 100644 --- a/Modules/CTestUseLaunchers.cmake +++ b/Modules/CTestUseLaunchers.cmake
@@ -13,6 +13,12 @@ * :prop_gbl:`RULE_LAUNCH_CUSTOM` * :prop_gbl:`RULE_LAUNCH_LINK` +Load this module in a CMake project with: + +.. code-block:: cmake + + include(CTestUseLaunchers) + The ``CTestUseLaunchers`` module is automatically included by the :module:`CTest` module when ``include(CTest)`` is called. However, it is provided as a separate module so that projects can use the @@ -54,13 +60,13 @@ CACHE INTERNAL "CTEST_USE_LAUNCHERS initial value from ENV") endif() -if(NOT "${CMAKE_GENERATOR}" MATCHES "Make|Ninja") +if(NOT "${CMAKE_GENERATOR}" MATCHES "Make|Ninja|FASTBuild") set(CTEST_USE_LAUNCHERS 0) endif() if(CTEST_USE_LAUNCHERS) set(__launch_common_options - "--target-name <TARGET_NAME> --current-build-dir <CMAKE_CURRENT_BINARY_DIR>") + "--target-name <TARGET_NAME> --current-build-dir <CMAKE_CURRENT_BINARY_DIR> --build-dir <CMAKE_BINARY_DIR> --object-dir <TARGET_SUPPORT_DIR>") set(__launch_compile_options "${__launch_common_options} --output <OBJECT> --source <SOURCE> --language <LANGUAGE>") @@ -71,7 +77,7 @@ set(__launch_custom_options "${__launch_common_options} --output <OUTPUT>") - if("${CMAKE_GENERATOR}" MATCHES "Ninja") + if("${CMAKE_GENERATOR}" MATCHES "Ninja|FASTBuild") string(APPEND __launch_compile_options " --filter-prefix <CMAKE_CL_SHOWINCLUDES_PREFIX>") endif()
diff --git a/Modules/CheckCSourceCompiles.cmake b/Modules/CheckCSourceCompiles.cmake index 8367206..4681ef0 100644 --- a/Modules/CheckCSourceCompiles.cmake +++ b/Modules/CheckCSourceCompiles.cmake
@@ -77,7 +77,7 @@ include(CheckCSourceCompiles) - check_c_source_compiles(" + check_c_source_compiles([[ #include <emmintrin.h> int main(void) { @@ -85,7 +85,7 @@ (void)a; return 0; } - " PROJECT_HAVE_SSE2_INTRINSICS) + ]] PROJECT_HAVE_SSE2_INTRINSICS) See Also ^^^^^^^^
diff --git a/Modules/CheckCSourceRuns.cmake b/Modules/CheckCSourceRuns.cmake index f1188a3..e4e27c3 100644 --- a/Modules/CheckCSourceRuns.cmake +++ b/Modules/CheckCSourceRuns.cmake
@@ -65,12 +65,12 @@ include(CheckCSourceRuns) - check_c_source_runs(" + check_c_source_runs([[ #include <stdlib.h> #include <stdnoreturn.h> noreturn void f(){ exit(0); } int main(void) { f(); return 1; } - " HAVE_NORETURN) + ]] HAVE_NORETURN) See Also ^^^^^^^^
diff --git a/Modules/CheckCXXSourceCompiles.cmake b/Modules/CheckCXXSourceCompiles.cmake index 2da6ef2..134782a 100644 --- a/Modules/CheckCXXSourceCompiles.cmake +++ b/Modules/CheckCXXSourceCompiles.cmake
@@ -79,13 +79,13 @@ include(CheckCXXSourceCompiles) - check_cxx_source_compiles(" + check_cxx_source_compiles([[ int main() { auto lambda = []() { return 42; }; return lambda(); } - " HAVE_CXX11_LAMBDAS) + ]] HAVE_CXX11_LAMBDAS) See Also ^^^^^^^^
diff --git a/Modules/CheckIncludeFile.cmake b/Modules/CheckIncludeFile.cmake index dab4f68..74f0edb 100644 --- a/Modules/CheckIncludeFile.cmake +++ b/Modules/CheckIncludeFile.cmake
@@ -20,17 +20,26 @@ .. command:: check_include_file - Checks once whether a header file can be included in C code: + Checks once whether a header file exists and can be included in C code: .. code-block:: cmake check_include_file(<include> <variable> [<flags>]) - This command checks once whether the given ``<include>`` header file - exists and can be included in a C source file. The result of the check - is stored in an internal cache variable named ``<variable>``. The - optional third argument may be used to add additional compilation flags - to the check (or use the ``CMAKE_REQUIRED_FLAGS`` variable below). + .. rubric:: The arguments are: + + ``<include>`` + A header file to be checked. + + ``<variable>`` + The name of the variable to store the result of the check. This + variable will be created as an internal cache variable. + + ``<flags>`` + (Optional) A space-separated string of + additional compilation flags to be added to the check. Alternatively, + flags can be also specified with the ``CMAKE_REQUIRED_FLAGS`` variable + below. .. rubric:: Variables Affecting the Check @@ -76,7 +85,7 @@ In the following example, this module is used in combination with the :module:`CMakePushCheckState` module to temporarily modify the required compile definitions (via ``CMAKE_REQUIRED_DEFINITIONS``) and verify whether -the C header ``ucontext.h`` is available. The result is stored +the C header ``<ucontext.h>`` is available. The result is stored in the internal cache variable ``HAVE_UCONTEXT_H``. For example, on macOS, the ``ucontext`` API is deprecated, and headers may @@ -95,7 +104,7 @@ set(CMAKE_REQUIRED_DEFINITIONS -D_XOPEN_SOURCE) endif() - check_include_files(ucontext.h HAVE_UCONTEXT_H) + check_include_file(ucontext.h HAVE_UCONTEXT_H) cmake_pop_check_state() See Also
diff --git a/Modules/CheckIncludeFileCXX.cmake b/Modules/CheckIncludeFileCXX.cmake index 54b7f55..3d487a4 100644 --- a/Modules/CheckIncludeFileCXX.cmake +++ b/Modules/CheckIncludeFileCXX.cmake
@@ -20,17 +20,26 @@ .. command:: check_include_file_cxx - Checks once whether a header file can be included in C++ code: + Checks once whether a header file exists and can be included in C++ code: .. code-block:: cmake check_include_file_cxx(<include> <variable> [<flags>]) - This command checks once whether the given ``<include>`` header file - exists and can be included in a ``CXX`` source file. The result of the - check is stored in an internal cache variable named ``<variable>``. The - optional third argument may be used to add additional compilation flags - to the check (or use the ``CMAKE_REQUIRED_FLAGS`` variable below). + .. rubric:: The arguments are: + + ``<include>`` + A header file to be checked. + + ``<variable>`` + The name of the variable to store the result of the check. This + variable will be created as an internal cache variable. + + ``<flags>`` + (Optional) A space-separated string of + additional compilation flags to be added to the check. Alternatively, + flags can be also specified with the ``CMAKE_REQUIRED_FLAGS`` variable + below. .. rubric:: Variables Affecting the Check
diff --git a/Modules/CheckIncludeFiles.cmake b/Modules/CheckIncludeFiles.cmake index 7debbe6..9870340 100644 --- a/Modules/CheckIncludeFiles.cmake +++ b/Modules/CheckIncludeFiles.cmake
@@ -20,24 +20,30 @@ .. command:: check_include_files - Checks once whether one or more header files can be included together in - source code: + Checks once whether one or more header files exist and can be included + together in C or C++ code: .. code-block:: cmake check_include_files(<includes> <variable> [LANGUAGE <language>]) - This command checks once whether the given ``<includes>`` list of header - files exist and can be included together in a C or C++ source file. The - result of the check is stored in an internal cache variable named - ``<variable>``. Specify the ``<includes>`` argument as a - :ref:`semicolon-separated list <CMake Language Lists>` of header file - names. + .. rubric:: The arguments are: - If ``LANGUAGE`` is set, the specified compiler will be used to perform the - check. Acceptable values are ``C`` and ``CXX``. If not set, the C - compiler will be used if enabled. If the C compiler is not enabled, the - C++ compiler will be used if enabled. + ``<includes>`` + A :ref:`semicolon-separated list <CMake Language Lists>` of header + files to be checked. + + ``<variable>`` + The name of the variable to store the result of the check. This + variable will be created as an internal cache variable. + + ``LANGUAGE <language>`` + .. versionadded:: 3.11 + + If set, the specified ``<language>`` compiler will be used to perform + the check. Acceptable values are ``C`` and ``CXX``. If this option is + not given, the C compiler will be used if enabled. If the C compiler + is not enabled, the C++ compiler will be used if enabled. .. rubric:: Variables Affecting the Check
diff --git a/Modules/CheckPIESupported.cmake b/Modules/CheckPIESupported.cmake index 592612c..b4d47f9 100644 --- a/Modules/CheckPIESupported.cmake +++ b/Modules/CheckPIESupported.cmake
@@ -7,23 +7,36 @@ .. versionadded:: 3.14 -This module provides the ``check_pie_supported()`` function to check whether the -linker supports Position Independent Code (PIE) or No Position Independent Code -(NO_PIE) for executables. +This module provides a command to check whether the linker supports Position +Independent Code (PIE) or No Position Independent Code (NO_PIE) for +executables. + +Load this module in a CMake project with: + +.. code-block:: cmake + + include(CheckPIESupported) When setting the :prop_tgt:`POSITION_INDEPENDENT_CODE` target property, PIC-related compile and link options are added when building library objects, and PIE-related compile options are added when building objects of executable targets, regardless of this module. Use this module to ensure that the -``POSITION_INDEPENDENT_CODE`` target property for executables is also honored at -link time. +``POSITION_INDEPENDENT_CODE`` target property for executables is also honored +at link time. + +Commands +^^^^^^^^ + +This module provides the following command: .. command:: check_pie_supported + Checks for PIE/NO_PIE support and prepares all executables to have link + time PIE options enabled: + .. code-block:: cmake - check_pie_supported([OUTPUT_VARIABLE <output>] - [LANGUAGES <lang>...]) + check_pie_supported([OUTPUT_VARIABLE <output>] [LANGUAGES <langs>...]) Options are: @@ -32,7 +45,7 @@ bypassed because it uses cached results from a previous call, the output will be empty even if errors were present in the previous call. - ``LANGUAGES <lang>...`` + ``LANGUAGES <langs>...`` Check the linkers used for each of the specified languages. If this option is not provided, the command checks all enabled languages. @@ -50,13 +63,13 @@ Variables ^^^^^^^^^ -For each language checked, the ``check_pie_supported()`` function defines two +For each language checked, the ``check_pie_supported()`` command defines two boolean cache variables: - ``CMAKE_<lang>_LINK_PIE_SUPPORTED`` - Set to true if ``PIE`` is supported by the linker and false otherwise. - ``CMAKE_<lang>_LINK_NO_PIE_SUPPORTED`` - Set to true if ``NO_PIE`` is supported by the linker and false otherwise. +``CMAKE_<lang>_LINK_PIE_SUPPORTED`` + Set to true if ``PIE`` is supported by the linker and false otherwise. +``CMAKE_<lang>_LINK_NO_PIE_SUPPORTED`` + Set to true if ``NO_PIE`` is supported by the linker and false otherwise. Examples ^^^^^^^^ @@ -82,11 +95,17 @@ add_executable(foo ...) + message(CHECK_START "Checking for C linker PIE support") + include(CheckPIESupported) check_pie_supported(OUTPUT_VARIABLE output LANGUAGES C) set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE) - if(NOT CMAKE_C_LINK_PIE_SUPPORTED) - message(WARNING "PIE is not supported at link time:\n${output}" + + if(CMAKE_C_LINK_PIE_SUPPORTED) + message(CHECK_PASS "yes") + else() + message(CHECK_FAIL "no") + message(VERBOSE "PIE is not supported at link time:\n${output}" "PIE link options will not be passed to linker.") endif() @@ -98,7 +117,6 @@ add_executable(foo ...) set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE) - #]=======================================================================]
diff --git a/Modules/CheckPrototypeDefinition.cmake b/Modules/CheckPrototypeDefinition.cmake index b1acaab..d77e81c 100644 --- a/Modules/CheckPrototypeDefinition.cmake +++ b/Modules/CheckPrototypeDefinition.cmake
@@ -93,10 +93,6 @@ ) #]=======================================================================] -# - -get_filename_component(__check_proto_def_dir "${CMAKE_CURRENT_LIST_FILE}" PATH) - include_guard(GLOBAL) function(check_prototype_definition _FUNCTION _PROTOTYPE _RETURN _HEADER _VARIABLE) @@ -143,7 +139,7 @@ set(CHECK_PROTOTYPE_DEFINITION_PROTO ${_PROTOTYPE}) set(CHECK_PROTOTYPE_DEFINITION_RETURN ${_RETURN}) - file(READ ${__check_proto_def_dir}/CheckPrototypeDefinition.c.in _SOURCE) + file(READ ${CMAKE_CURRENT_FUNCTION_LIST_DIR}/CheckPrototypeDefinition.c.in _SOURCE) string(CONFIGURE "${_SOURCE}" _SOURCE @ONLY) try_compile(${_VARIABLE}
diff --git a/Modules/CheckSourceCompiles.cmake b/Modules/CheckSourceCompiles.cmake index 96246da..7984296 100644 --- a/Modules/CheckSourceCompiles.cmake +++ b/Modules/CheckSourceCompiles.cmake
@@ -111,13 +111,13 @@ include(CheckSourceCompiles) - check_source_compiles(CXX " + check_source_compiles(CXX [[ int main() { auto lambda = []() { return 42; }; return lambda(); } - " HAVE_CXX11_LAMBDAS) + ]] HAVE_CXX11_LAMBDAS) Example: Checking Code With Bracket Argument """""""""""""""""""""""""""""""""""""""""""" @@ -179,7 +179,7 @@ cmake_push_check_state(RESET) set(CMAKE_REQUIRED_LIBRARIES PostgreSQL::PostgreSQL) - check_source_compiles(C " + check_source_compiles(C [[ #include <libpq-fe.h> int main(void) { @@ -187,7 +187,7 @@ (void)e; return 0; } - " HAVE_PQERRORS_SQLSTATE) + ]] HAVE_PQERRORS_SQLSTATE) cmake_pop_check_state() endif()
diff --git a/Modules/CheckSourceRuns.cmake b/Modules/CheckSourceRuns.cmake index 0874a1f..97e1eb5 100644 --- a/Modules/CheckSourceRuns.cmake +++ b/Modules/CheckSourceRuns.cmake
@@ -96,12 +96,12 @@ include(CheckSourceRuns) - check_source_runs(C " + check_source_runs(C [[ #include <stdlib.h> #include <stdnoreturn.h> noreturn void f(){ exit(0); } int main(void) { f(); return 1; } - " HAVE_NORETURN) + ]] HAVE_NORETURN) Example: Checking Fortran Code """""""""""""""""""""""""""""" @@ -112,12 +112,12 @@ include(CheckSourceRuns) - check_source_runs(Fortran " + check_source_runs(Fortran [[ program test real :: x[*] call co_sum(x) end program - " HAVE_COARRAY) + ]] HAVE_COARRAY) Example: Checking C++ Code With Bracket Argument """""""""""""""""""""""""""""""""""""""""""""""" @@ -171,7 +171,7 @@ set(CMAKE_REQUIRED_LIBRARIES gnu) endif() - check_source_runs(C " + check_source_runs(C [[ #include <sched.h> int main(void) { @@ -180,7 +180,7 @@ } return 0; } - " HAVE_SCHED_GETCPU) + ]] HAVE_SCHED_GETCPU) cmake_pop_check_state() See Also
diff --git a/Modules/CheckTypeSize.cmake b/Modules/CheckTypeSize.cmake index 9643d87..1f5a622 100644 --- a/Modules/CheckTypeSize.cmake +++ b/Modules/CheckTypeSize.cmake
@@ -25,23 +25,42 @@ .. code-block:: cmake - check_type_size(<type> <variable> [BUILTIN_TYPES_ONLY] [LANGUAGE <language>]) + check_type_size( + <type> + <size-var> + [RESULT_VARIABLE <result-var>] + [BUILTIN_TYPES_ONLY] + [LANGUAGE <language>] + ) The arguments are: ``<type>`` The type or expression being checked. - ``<variable>`` - The name of the variable and a prefix used for storing the check results. + ``<size-var>`` + The name of the internal cache variable for storing the size of the type + or expression ``<type>``. This name is also used as a prefix as + explained below. + + ``RESULT_VARIABLE <result-var>`` + .. versionadded:: 4.2 + + The name of the internal cache variable that holds a boolean value + indicating whether the type or expression ``<type>`` exists. If *not* + given, the command will by default define an internal cache variable + named ``HAVE_<size-var>`` instead. ``BUILTIN_TYPES_ONLY`` If given, only compiler-builtin types will be supported in the check. If *not* given, the command checks for common headers ``<sys/types.h>``, ``<stdint.h>``, and ``<stddef.h>``, and saves results in ``HAVE_SYS_TYPES_H``, ``HAVE_STDINT_H``, and ``HAVE_STDDEF_H`` internal - cache variables. The type size check automatically includes the available - headers, thus supporting checks of types defined in the headers. + cache variables. For C++ ``std::`` types, ``<cstdint>`` and + ``<cstddef>`` are also checked with ``HAVE_CSTDINT`` and + ``HAVE_CSTDDEF`` defined respectively. The command automatically + includes the available headers in the type size check, thus supporting + checks of types defined in the headers. ``LANGUAGE <language>`` Uses the ``<language>`` compiler to perform the check. @@ -52,40 +71,50 @@ Results are reported in the following variables: - ``HAVE_<variable>`` - Internal cache variable that holds a boolean true or false value - indicating whether the type or expression ``<type>`` exists. - - ``<variable>`` + ``<size-var>`` Internal cache variable that holds one of the following values: ``<size>`` - If the type or expression exists, it will have a non-zero size - ``<size>`` in bytes. + If the type or expression ``<type>`` exists, it will have a non-zero + size ``<size>`` in bytes. ``0`` - When type has architecture-dependent size; This may occur when - :variable:`CMAKE_OSX_ARCHITECTURES` has multiple architectures. - In this case ``<variable>_CODE`` contains preprocessor tests - mapping from each architecture macro to the corresponding type size. - The list of architecture macros is stored in ``<variable>_KEYS``, - and the value for each key is stored in ``<variable>-<key>``. + When the type has an architecture-dependent size; This may occur when + :variable:`CMAKE_OSX_ARCHITECTURES` has multiple architectures. In + this case also the ``<size-var>_KEYS`` variable is defined and the + ``<size-var>_CODE`` variable contains preprocessor tests mapping as + explained below. "" (empty string) - When type or expression does not exist. + When the type or expression ``<type>`` does not exist. - ``<variable>_CODE`` + ``HAVE_<size-var>`` + Internal cache variable that holds a boolean value indicating whether + the type or expression ``<type>`` exists. This variable is defined + when the ``RESULT_VARIABLE`` argument is not used. + + ``<result-var>`` + .. versionadded:: 4.2 + + Internal cache variable defined when the ``RESULT_VARIABLE`` argument + is used. It holds a boolean value indicating whether the type or + expression ``<type>`` exists (same value as ``HAVE_<size-var>``). In + this case, the ``HAVE_<size-var>`` variable is not defined. + + ``<size-var>_CODE`` CMake variable that holds preprocessor code to define the macro - ``<variable>`` to the size of the type, or to leave the macro undefined + ``<size-var>`` to the size of the type, or to leave the macro undefined if the type does not exist. - Despite the name of this command, it may also be used to determine the size - of more complex expressions. For example, to check the size of a struct - member: + When the type has an architecture-dependent size (``<size-var>`` value + is ``0``) this variable contains preprocessor tests mapping from each + architecture macro to the corresponding type size. - .. code-block:: cmake - - check_type_size("((struct something*)0)->member" SIZEOF_MEMBER) + ``<size-var>_KEYS`` + CMake variable that is defined only when the type has an + architecture-dependent size (``<size-var>`` value is ``0``) and contains + a list of architecture macros. The value for each key is stored in + ``<size-var>-<key>`` variables. .. rubric:: Variables Affecting the Check @@ -121,6 +150,7 @@ # Check for size of long. check_type_size(long SIZEOF_LONG) + message("HAVE_SIZEOF_LONG: ${HAVE_SIZEOF_LONG}") message("SIZEOF_LONG: ${SIZEOF_LONG}") message("SIZEOF_LONG_CODE: ${SIZEOF_LONG_CODE}") @@ -133,21 +163,21 @@ On Apple platforms, when :variable:`CMAKE_OSX_ARCHITECTURES` has multiple architectures, types may have architecture-dependent sizes. -For example, with the code +For example, with the code: .. code-block:: cmake include(CheckTypeSize) check_type_size(long SIZEOF_LONG) + message("HAVE_SIZEOF_LONG: ${HAVE_SIZEOF_LONG}") message("SIZEOF_LONG: ${SIZEOF_LONG}") - foreach(key IN LISTS SIZE_OF_LONG_KEYS) + foreach(key IN LISTS SIZEOF_LONG_KEYS) message("key: ${key}") - message("value: ${SIZE_OF_LONG-${key}}") + message("value: ${SIZEOF_LONG-${key}}") endforeach() - message("SIZEOF_LONG_CODE: - ${SIZEOF_LONG_CODE}") + message("SIZEOF_LONG_CODE:\n${SIZEOF_LONG_CODE}") the result may be:: @@ -159,27 +189,108 @@ value: 8 SIZEOF_LONG_CODE: #if defined(__i386) - # define SIZE_OF_LONG 4 + # define SIZEOF_LONG 4 #elif defined(__x86_64) - # define SIZE_OF_LONG 8 + # define SIZEOF_LONG 8 #else - # error SIZE_OF_LONG unknown + # error SIZEOF_LONG unknown #endif + +Example: Configuration Header +""""""""""""""""""""""""""""" + +The next example demonstrates how the result variables can be used in a +configuration header: + +.. code-block:: cmake + + include(CheckTypeSize) + check_type_size(long SIZEOF_LONG) + + configure_file(config.h.in config.h @ONLY) + +.. code-block:: c + :caption: ``config.h.in`` + :force: + + /* Define whether the type 'long' exists. */ + #cmakedefine HAVE_SIZEOF_LONG + + /* The size of 'long', as computed by sizeof. */ + @SIZEOF_LONG_CODE@ + +Example: Checking Complex Expressions +""""""""""""""""""""""""""""""""""""" + +Despite the name of this module, it may also be used to determine the size +of more complex expressions. For example, to check the size of a struct +member: + +.. code-block:: cmake + + include(CheckTypeSize) + check_type_size("((struct something*)0)->member" SIZEOF_MEMBER) + +Example: Isolated Check +""""""""""""""""""""""" + +In the following example, the check is performed with temporarily modified +additional headers using the ``CMAKE_EXTRA_INCLUDE_FILES`` variable and +:module:`CMakePushCheckState` module. The result of the check is stored in +``HAVE_SIZEOF_UNION_SEMUN``, and size is stored in ``SIZEOF_UNION_SEMUN`` +internal cache variables. + +.. code-block:: cmake + + include(CheckTypeSize) + include(CMakePushCheckState) + + cmake_push_check_state(RESET) + set(CMAKE_EXTRA_INCLUDE_FILES sys/types.h sys/ipc.h sys/sem.h) + check_type_size("union semun" SIZEOF_UNION_SEMUN) + cmake_pop_check_state() + +Example: Customizing Result Variable +"""""""""""""""""""""""""""""""""""" + +Since CMake 4.2, the ``HAVE_<size-var>`` variable name can be customized +using the ``RESULT_VARIABLE`` argument. In the following example, this +module is used to check whether the ``struct flock`` exists, and the result +is stored in the ``MyProj_HAVE_STRUCT_FLOCK`` internal cache variable: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 4.2) + + # ... + + include(CheckTypeSize) + include(CMakePushCheckState) + + cmake_push_check_state(RESET) + set(CMAKE_EXTRA_INCLUDE_FILES "fcntl.h") + + check_type_size( + "struct flock" + MyProj_SIZEOF_STRUCT_FLOCK + RESULT_VARIABLE MyProj_HAVE_STRUCT_FLOCK + ) + cmake_pop_check_state() #]=======================================================================] include(CheckIncludeFile) include(CheckIncludeFileCXX) -get_filename_component(__check_type_size_dir "${CMAKE_CURRENT_LIST_FILE}" PATH) - include_guard(GLOBAL) block(SCOPE_FOR POLICIES) +cmake_policy(SET CMP0140 NEW) cmake_policy(SET CMP0159 NEW) # file(STRINGS) with REGEX updates CMAKE_MATCH_<n> +cmake_policy(SET CMP0174 NEW) #----------------------------------------------------------------------------- # Helper function. DO NOT CALL DIRECTLY. -function(__check_type_size_impl type var map builtin language) +function(__check_type_size_impl type var result_var map builtin language) if(NOT CMAKE_REQUIRED_QUIET) message(CHECK_START "Check size of ${type}") endif() @@ -196,7 +307,7 @@ # Include header files. set(headers) - if(builtin) + if(NOT builtin) if(language STREQUAL "CXX" AND type MATCHES "^std::") if(HAVE_SYS_TYPES_H) string(APPEND headers "#include <sys/types.h>\n") @@ -232,9 +343,9 @@ # Perform the check. set(bin ${CMAKE_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/CheckTypeSize/${var}.bin) - file(READ ${__check_type_size_dir}/CheckTypeSize.c.in src_content) + file(READ ${CMAKE_CURRENT_FUNCTION_LIST_DIR}/CheckTypeSize.c.in src_content) string(CONFIGURE "${src_content}" src_content @ONLY) - try_compile(HAVE_${var} SOURCE_FROM_VAR "${src}" src_content + try_compile(${result_var} SOURCE_FROM_VAR "${src}" src_content COMPILE_DEFINITIONS ${CMAKE_REQUIRED_DEFINITIONS} LINK_OPTIONS ${CMAKE_REQUIRED_LINK_OPTIONS} LINK_LIBRARIES ${CMAKE_REQUIRED_LIBRARIES} @@ -246,7 +357,7 @@ ) unset(_CTS_LINK_DIRECTORIES) - if(HAVE_${var}) + if(${result_var}) # The check compiled. Load information from the binary. file(STRINGS ${bin} strings LIMIT_COUNT 10 REGEX "INFO:size") @@ -280,7 +391,7 @@ # Update the architecture-to-size map. if(mismatch AND keys) - configure_file(${__check_type_size_dir}/CheckTypeSizeMap.cmake.in ${map} @ONLY) + configure_file(${CMAKE_CURRENT_FUNCTION_LIST_DIR}/CheckTypeSizeMap.cmake.in ${map} @ONLY) set(${var} 0) else() file(REMOVE ${map}) @@ -305,45 +416,53 @@ endfunction() #----------------------------------------------------------------------------- -macro(CHECK_TYPE_SIZE TYPE VARIABLE) - # parse arguments - unset(doing) - foreach(arg ${ARGN}) - if("x${arg}" STREQUAL "xBUILTIN_TYPES_ONLY") - set(_CHECK_TYPE_SIZE_${arg} 1) - unset(doing) - elseif("x${arg}" STREQUAL "xLANGUAGE") # change to MATCHES for more keys - set(doing "${arg}") - set(_CHECK_TYPE_SIZE_${doing} "") - elseif("x${doing}" STREQUAL "xLANGUAGE") - set(_CHECK_TYPE_SIZE_${doing} "${arg}") - unset(doing) - else() - message(FATAL_ERROR "Unknown argument:\n ${arg}\n") - endif() - endforeach() - if("x${doing}" MATCHES "^x(LANGUAGE)$") - message(FATAL_ERROR "Missing argument:\n ${doing} arguments requires a value\n") +function(CHECK_TYPE_SIZE TYPE VARIABLE) + cmake_parse_arguments( + PARSE_ARGV + 2 + _CHECK_TYPE_SIZE + "BUILTIN_TYPES_ONLY" # Options + "RESULT_VARIABLE;LANGUAGE" # One-value arguments + "" # Multi-value arguments + ) + + if(_CHECK_TYPE_SIZE_UNPARSED_ARGUMENTS) + message( + FATAL_ERROR + "Unknown arguments:\n ${_CHECK_TYPE_SIZE_UNPARSED_ARGUMENTS}\n" + ) endif() - if(DEFINED _CHECK_TYPE_SIZE_LANGUAGE) - if(NOT "x${_CHECK_TYPE_SIZE_LANGUAGE}" MATCHES "^x(C|CXX)$") - message(FATAL_ERROR "Unknown language:\n ${_CHECK_TYPE_SIZE_LANGUAGE}.\nSupported languages: C, CXX.\n") - endif() - set(_language ${_CHECK_TYPE_SIZE_LANGUAGE}) - else() - set(_language C) + + if(NOT DEFINED _CHECK_TYPE_SIZE_RESULT_VARIABLE) + set(_CHECK_TYPE_SIZE_RESULT_VARIABLE HAVE_${VARIABLE}) + elseif(_CHECK_TYPE_SIZE_RESULT_VARIABLE STREQUAL "") + message( + FATAL_ERROR + "Missing argument:\n RESULT_VARIABLE argument requires a value\n" + ) + endif() + + if(NOT DEFINED _CHECK_TYPE_SIZE_LANGUAGE) + set(_CHECK_TYPE_SIZE_LANGUAGE C) + elseif(_CHECK_TYPE_SIZE_LANGUAGE STREQUAL "") + message( + FATAL_ERROR + "Missing argument:\n LANGUAGE argument requires a value\n" + ) + elseif(NOT _CHECK_TYPE_SIZE_LANGUAGE MATCHES "^(C|CXX)$") + message( + FATAL_ERROR + "Unknown language:\n ${_CHECK_TYPE_SIZE_LANGUAGE}.\n" + "Supported languages: C, CXX.\n") endif() # Optionally check for standard headers. - if(_CHECK_TYPE_SIZE_BUILTIN_TYPES_ONLY) - set(_builtin 0) - else() - set(_builtin 1) - if(_language STREQUAL "C") + if(NOT _CHECK_TYPE_SIZE_BUILTIN_TYPES_ONLY) + if(_CHECK_TYPE_SIZE_LANGUAGE STREQUAL "C") check_include_file(sys/types.h HAVE_SYS_TYPES_H) check_include_file(stdint.h HAVE_STDINT_H) check_include_file(stddef.h HAVE_STDDEF_H) - elseif(_language STREQUAL "CXX") + elseif(_CHECK_TYPE_SIZE_LANGUAGE STREQUAL "CXX") check_include_file_cxx(sys/types.h HAVE_SYS_TYPES_H) if("${TYPE}" MATCHES "^std::") check_include_file_cxx(cstdint HAVE_CSTDINT) @@ -354,18 +473,23 @@ endif() endif() endif() - unset(_CHECK_TYPE_SIZE_BUILTIN_TYPES_ONLY) - unset(_CHECK_TYPE_SIZE_LANGUAGE) # Compute or load the size or size map. set(${VARIABLE}_KEYS) set(_map_file ${CMAKE_BINARY_DIR}/${CMAKE_FILES_DIRECTORY}/CheckTypeSize/${VARIABLE}.cmake) - if(NOT DEFINED HAVE_${VARIABLE}) - __check_type_size_impl(${TYPE} ${VARIABLE} ${_map_file} ${_builtin} ${_language}) + if(NOT DEFINED ${_CHECK_TYPE_SIZE_RESULT_VARIABLE}) + __check_type_size_impl( + ${TYPE} + ${VARIABLE} + ${_CHECK_TYPE_SIZE_RESULT_VARIABLE} + ${_map_file} + ${_CHECK_TYPE_SIZE_BUILTIN_TYPES_ONLY} + ${_CHECK_TYPE_SIZE_LANGUAGE} + ) endif() include(${_map_file} OPTIONAL) - set(_map_file) - set(_builtin) + + set(_propagated_vars "") # Create preprocessor code. if(${VARIABLE}_KEYS) @@ -374,15 +498,17 @@ foreach(key ${${VARIABLE}_KEYS}) string(APPEND ${VARIABLE}_CODE "#${_if} defined(${key})\n# define ${VARIABLE} ${${VARIABLE}-${key}}\n") set(_if elif) + list(APPEND _propagated_vars ${VARIABLE}-${key}) endforeach() string(APPEND ${VARIABLE}_CODE "#else\n# error ${VARIABLE} unknown\n#endif") - set(_if) elseif(${VARIABLE}) set(${VARIABLE}_CODE "#define ${VARIABLE} ${${VARIABLE}}") else() set(${VARIABLE}_CODE "/* #undef ${VARIABLE} */") endif() -endmacro() + + return(PROPAGATE ${VARIABLE}_CODE ${VARIABLE}_KEYS ${_propagated_vars}) +endfunction() #----------------------------------------------------------------------------- endblock()
diff --git a/Modules/Compiler/ARMClang.cmake b/Modules/Compiler/ARMClang.cmake index 89a523b..2f0ee91 100644 --- a/Modules/Compiler/ARMClang.cmake +++ b/Modules/Compiler/ARMClang.cmake
@@ -121,7 +121,12 @@ list(TRANSFORM CMAKE_LINKER_CPU_LIST TOLOWER) __armclang_check_processor("${CMAKE_SYSTEM_PROCESSOR}" "${CMAKE_LINKER_CPU_LIST}" _CMAKE_CHECK_LINK_CPU_RESULT) if(_CMAKE_CHECK_LINK_CPU_RESULT) - string(APPEND CMAKE_${lang}_LINK_FLAGS " --cpu=${CMAKE_SYSTEM_PROCESSOR}") + string(APPEND CMAKE_EXECUTABLE_CREATE_${lang}_FLAGS " --cpu=${CMAKE_SYSTEM_PROCESSOR}") + cmake_policy(GET CMP0210 _CMP0210) + if (NOT _CMP0210 STREQUAL "NEW") + string(APPEND CMAKE_${lang}_LINK_FLAGS " --cpu=${CMAKE_SYSTEM_PROCESSOR}") + endif() + unset(_CMP0210) endif() endif()
diff --git a/Modules/Compiler/AppleClang-CXX.cmake b/Modules/Compiler/AppleClang-CXX.cmake index 8a6c855..bd92cbb 100644 --- a/Modules/Compiler/AppleClang-CXX.cmake +++ b/Modules/Compiler/AppleClang-CXX.cmake
@@ -63,7 +63,13 @@ set(CMAKE_CXX_STANDARD_LATEST 20) endif() -if (NOT CMAKE_CXX_COMPILER_VERSION VERSION_LESS 13.0) +if (NOT CMAKE_CXX_COMPILER_VERSION VERSION_LESS 16.0) + set(CMAKE_CXX23_STANDARD_COMPILE_OPTION "-std=c++23") + set(CMAKE_CXX23_EXTENSION_COMPILE_OPTION "-std=gnu++23") + set(CMAKE_CXX26_STANDARD_COMPILE_OPTION "-std=c++26") + set(CMAKE_CXX26_EXTENSION_COMPILE_OPTION "-std=gnu++26") + set(CMAKE_CXX_STANDARD_LATEST 26) +elseif (NOT CMAKE_CXX_COMPILER_VERSION VERSION_LESS 13.0) set(CMAKE_CXX23_STANDARD_COMPILE_OPTION "-std=c++2b") set(CMAKE_CXX23_EXTENSION_COMPILE_OPTION "-std=gnu++2b") set(CMAKE_CXX_STANDARD_LATEST 23)
diff --git a/Modules/Compiler/CMakeCommonCompilerMacros.cmake b/Modules/Compiler/CMakeCommonCompilerMacros.cmake index 067aa6f..a97fe0f 100644 --- a/Modules/Compiler/CMakeCommonCompilerMacros.cmake +++ b/Modules/Compiler/CMakeCommonCompilerMacros.cmake
@@ -202,43 +202,21 @@ _has_compiler_features_hip(98) endmacro() -function(cmake_create_cxx_import_std std variable) - set(_cmake_supported_import_std_features - # Compilers support `import std` in C++20 as an extension. Skip - # for now. - # 20 - 23 - 26) - list(FIND _cmake_supported_import_std_features "${std}" _cmake_supported_import_std_idx) - if (_cmake_supported_import_std_idx EQUAL "-1") - set("${variable}" - "set(CMAKE_CXX${std}_COMPILER_IMPORT_STD_NOT_FOUND_MESSAGE \"Unsupported C++ standard: C++${std}\")\n" - PARENT_SCOPE) - return () - endif () - # If the target exists, skip. A toolchain file may have provided it. - if (TARGET "__CMAKE::CXX${std}") - return () - endif () +function(cmake_cxx_find_modules_json) # The generator must support imported C++ modules. if (NOT CMAKE_GENERATOR MATCHES "Ninja") - set("${variable}" - "set(CMAKE_CXX${std}_COMPILER_IMPORT_STD_NOT_FOUND_MESSAGE \"Unsupported generator: ${CMAKE_GENERATOR}\")\n" - PARENT_SCOPE) + set(CMAKE_CXX_COMPILER_IMPORT_STD_ERROR_MESSAGE "Unsupported generator: ${CMAKE_GENERATOR}" PARENT_SCOPE) return () endif () + # Check if the compiler understands how to `import std;`. include("${CMAKE_ROOT}/Modules/Compiler/${CMAKE_CXX_COMPILER_ID}-CXX-CXXImportStd.cmake" OPTIONAL RESULT_VARIABLE _cmake_import_std_res) if (NOT _cmake_import_std_res) - set("${variable}" - "set(CMAKE_CXX${std}_COMPILER_IMPORT_STD_NOT_FOUND_MESSAGE \"Toolchain does not support discovering `import std` support\")\n" - PARENT_SCOPE) + set(CMAKE_CXX_COMPILER_IMPORT_STD_ERROR_MESSAGE "Toolchain does not support discovering module metadata" PARENT_SCOPE) return () endif () - if (NOT COMMAND _cmake_cxx_import_std) - set("${variable}" - "set(CMAKE_CXX${std}_COMPILER_IMPORT_STD_NOT_FOUND_MESSAGE \"Toolchain does not provide `import std` discovery command\")\n" - PARENT_SCOPE) + if (NOT COMMAND _cmake_cxx_find_modules_json) + set(CMAKE_CXX_COMPILER_IMPORT_STD_ERROR_MESSAGE "Toolchain does not provide module metadata discovery command" PARENT_SCOPE) return () endif () @@ -249,19 +227,11 @@ "CxxImportStd" _cmake_supported_import_std_experimental) if (NOT _cmake_supported_import_std_experimental) - set("${variable}" - "set(CMAKE_CXX${std}_COMPILER_IMPORT_STD_NOT_FOUND_MESSAGE \"Experimental `import std` support not enabled when detecting toolchain; it must be set before `CXX` is enabled (usually a `project()` call)\")\n" - PARENT_SCOPE) + set(CMAKE_CXX_COMPILER_IMPORT_STD_ERROR_MESSAGE "Experimental `import std` support not enabled when detecting toolchain; it must be set before `CXX` is enabled (usually a `project()` call)" PARENT_SCOPE) return () endif () - _cmake_cxx_import_std("${std}" target_definition) - string(CONCAT guarded_target_definition - "if (NOT TARGET \"__CMAKE::CXX${std}\")\n" - "${target_definition}" - "endif ()\n" - "if (TARGET \"__CMAKE::CXX${std}\")\n" - " list(APPEND CMAKE_CXX_COMPILER_IMPORT_STD \"${std}\")\n" - "endif ()\n") - set("${variable}" "${guarded_target_definition}" PARENT_SCOPE) + _cmake_cxx_find_modules_json() + set(CMAKE_CXX_COMPILER_IMPORT_STD_ERROR_MESSAGE "${CMAKE_CXX_COMPILER_IMPORT_STD_ERROR_MESSAGE}" PARENT_SCOPE) + set(CMAKE_CXX_STDLIB_MODULES_JSON "${CMAKE_CXX_STDLIB_MODULES_JSON}" PARENT_SCOPE) endfunction()
diff --git a/Modules/Compiler/Clang-C.cmake b/Modules/Compiler/Clang-C.cmake index 24b7157..b7359b2 100644 --- a/Modules/Compiler/Clang-C.cmake +++ b/Modules/Compiler/Clang-C.cmake
@@ -5,11 +5,6 @@ set(CMAKE_C_COMPILE_OPTIONS_EXPLICIT_LANGUAGE -TC) set(CMAKE_C_CLANG_TIDY_DRIVER_MODE "cl") set(CMAKE_C_INCLUDE_WHAT_YOU_USE_DRIVER_MODE "cl") - if((NOT DEFINED CMAKE_DEPENDS_USE_COMPILER OR CMAKE_DEPENDS_USE_COMPILER) - AND CMAKE_GENERATOR MATCHES "Makefiles|WMake" - AND CMAKE_DEPFILE_FLAGS_C) - set(CMAKE_C_DEPENDS_USE_COMPILER TRUE) - endif() elseif("x${CMAKE_C_COMPILER_FRONTEND_VARIANT}" STREQUAL "xGNU") set(CMAKE_C_COMPILE_OPTIONS_EXPLICIT_LANGUAGE -x c) if((NOT DEFINED CMAKE_DEPENDS_USE_COMPILER OR CMAKE_DEPENDS_USE_COMPILER)
diff --git a/Modules/Compiler/Clang-CXX-CXXImportStd.cmake b/Modules/Compiler/Clang-CXX-CXXImportStd.cmake index 5330eb1..9b66b56 100644 --- a/Modules/Compiler/Clang-CXX-CXXImportStd.cmake +++ b/Modules/Compiler/Clang-CXX-CXXImportStd.cmake
@@ -1,38 +1,30 @@ -function (_cmake_cxx_import_std std variable) +function (_cmake_cxx_find_modules_json) if (CMAKE_CXX_STANDARD_LIBRARY STREQUAL "libc++") set(_clang_modules_json_impl "libc++") elseif (CMAKE_CXX_STANDARD_LIBRARY STREQUAL "libstdc++") set(_clang_modules_json_impl "libstdc++") else () - set("${variable}" - "set(CMAKE_CXX${std}_COMPILER_IMPORT_STD_NOT_FOUND_MESSAGE \"Only `libc++` and `libstdc++` are supported\")\n" - PARENT_SCOPE) + set(CMAKE_CXX_COMPILER_IMPORT_STD_ERROR_MESSAGE "Only `libc++` and `libstdc++` are supported" PARENT_SCOPE) return () endif () - execute_process( - COMMAND - "${CMAKE_CXX_COMPILER}" - ${CMAKE_CXX_COMPILER_ID_ARG1} - "-print-file-name=${_clang_modules_json_impl}.modules.json" - OUTPUT_VARIABLE _clang_libcxx_modules_json_file - ERROR_VARIABLE _clang_libcxx_modules_json_file_err - RESULT_VARIABLE _clang_libcxx_modules_json_file_res - OUTPUT_STRIP_TRAILING_WHITESPACE - ERROR_STRIP_TRAILING_WHITESPACE) - if (_clang_libcxx_modules_json_file_res) - set("${variable}" - "set(CMAKE_CXX${std}_COMPILER_IMPORT_STD_NOT_FOUND_MESSAGE \"Could not find `${_clang_modules_json_impl}.modules.json` resource\")\n" - PARENT_SCOPE) - return () - endif () - - # Without this file, we do not have modules installed. - if (NOT EXISTS "${_clang_libcxx_modules_json_file}") - set("${variable}" - "set(CMAKE_CXX${std}_COMPILER_IMPORT_STD_NOT_FOUND_MESSAGE \"`${_clang_modules_json_impl}.modules.json` resource does not exist\")\n" - PARENT_SCOPE) - return () + if (NOT CMAKE_CXX_STDLIB_MODULES_JSON) + execute_process( + COMMAND + "${CMAKE_CXX_COMPILER}" + ${CMAKE_CXX_COMPILER_ID_ARG1} + "-print-file-name=${_clang_modules_json_impl}.modules.json" + OUTPUT_VARIABLE _clang_libcxx_modules_json_file + ERROR_VARIABLE _clang_libcxx_modules_json_file_err + RESULT_VARIABLE _clang_libcxx_modules_json_file_res + OUTPUT_STRIP_TRAILING_WHITESPACE + ERROR_STRIP_TRAILING_WHITESPACE) + if (_clang_libcxx_modules_json_file_res) + set(CMAKE_CXX_COMPILER_IMPORT_STD_ERROR_MESSAGE "Could not find `${_clang_modules_json_impl}.modules.json` resource" PARENT_SCOPE) + return () + endif () + cmake_path(CONVERT "${_clang_libcxx_modules_json_file}" TO_CMAKE_PATH_LIST CMAKE_CXX_STDLIB_MODULES_JSON NORMALIZE) + set(CMAKE_CXX_STDLIB_MODULES_JSON "${CMAKE_CXX_STDLIB_MODULES_JSON}" PARENT_SCOPE) endif () if (CMAKE_CXX_COMPILER_VERSION VERSION_LESS "18.1.2" AND @@ -40,145 +32,7 @@ # The original PR had a key spelling mismatch internally. Do not support it # and instead require a release known to have the fix. # https://github.com/llvm/llvm-project/pull/83036 - set("${variable}" - "set(CMAKE_CXX${std}_COMPILER_IMPORT_STD_NOT_FOUND_MESSAGE \"LLVM 18.1.2 is required for `${_clang_modules_json_impl}.modules.json` format fix\")\n" - PARENT_SCOPE) + set(CMAKE_CXX_COMPILER_IMPORT_STD_ERROR_MESSAGE "LLVM 18.1.2 is required for `${_clang_modules_json_impl}.modules.json` format fix" PARENT_SCOPE) return () endif () - - file(READ "${_clang_libcxx_modules_json_file}" _clang_libcxx_modules_json) - string(JSON _clang_modules_json_version GET "${_clang_libcxx_modules_json}" "version") - string(JSON _clang_modules_json_revision GET "${_clang_libcxx_modules_json}" "revision") - # Require version 1. - if (NOT _clang_modules_json_version EQUAL "1") - set("${variable}" - "set(CMAKE_CXX${std}_COMPILER_IMPORT_STD_NOT_FOUND_MESSAGE \"`libc++.modules.json` version ${_clang_modules_json_version}.${_clang_modules_json_revision} is not recognized\")\n" - PARENT_SCOPE) - return () - endif () - - string(JSON _clang_modules_json_nmodules LENGTH "${_clang_libcxx_modules_json}" "modules") - # Don't declare the target without any modules. - if (NOT _clang_modules_json_nmodules) - set("${variable}" - "set(CMAKE_CXX${std}_COMPILER_IMPORT_STD_NOT_FOUND_MESSAGE \"`libc++.modules.json` does not list any available modules\")\n" - PARENT_SCOPE) - return () - endif () - - # Declare the target. - set(_clang_libcxx_target "") - # Clang 18 does not provide the module initializer for the `std` modules. - # Create a static library to hold these. Hope that Clang 19 can provide this, - # but never run the code. - string(APPEND _clang_libcxx_target - "add_library(__cmake_cxx${std} STATIC)\n") - string(APPEND _clang_libcxx_target - "target_sources(__cmake_cxx${std} INTERFACE \"$<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,STATIC_LIBRARY>:$<TARGET_OBJECTS:__cmake_cxx${std}>>\")\n") - string(APPEND _clang_libcxx_target - "set_property(TARGET __cmake_cxx${std} PROPERTY EXCLUDE_FROM_ALL 1)\n") - string(APPEND _clang_libcxx_target - "set_property(TARGET __cmake_cxx${std} PROPERTY CXX_SCAN_FOR_MODULES 1)\n") - string(APPEND _clang_libcxx_target - "set_property(TARGET __cmake_cxx${std} PROPERTY CXX_MODULE_STD 0)\n") - string(APPEND _clang_libcxx_target - "target_compile_features(__cmake_cxx${std} PUBLIC cxx_std_${std})\n") - - set(_clang_modules_is_stdlib 0) - set(_clang_modules_include_dirs_list "") - set(_clang_modules_module_paths "") - get_filename_component(_clang_modules_dir "${_clang_libcxx_modules_json_file}" DIRECTORY) - - # Add module sources. - math(EXPR _clang_modules_json_nmodules_range "${_clang_modules_json_nmodules} - 1") - foreach (_clang_modules_json_modules_idx RANGE 0 "${_clang_modules_json_nmodules_range}") - string(JSON _clang_modules_json_module GET "${_clang_libcxx_modules_json}" "modules" "${_clang_modules_json_modules_idx}") - - string(JSON _clang_modules_json_module_source GET "${_clang_modules_json_module}" "source-path") - string(JSON _clang_modules_json_module_is_stdlib GET "${_clang_modules_json_module}" "is-std-library") - string(JSON _clang_modules_json_module_local_arguments ERROR_VARIABLE _clang_modules_json_module_local_arguments_error GET "${_clang_modules_json_module}" "local-arguments") - string(JSON _clang_modules_json_module_nsystem_include_directories ERROR_VARIABLE _clang_modules_json_module_nsystem_include_directories_error LENGTH "${_clang_modules_json_module_local_arguments}" "system-include-directories") - - if (_clang_modules_json_module_local_arguments_error) - set(_clang_modules_json_module_local_arguments "") - endif () - if (_clang_modules_json_module_nsystem_include_directories_error) - set(_clang_modules_json_module_nsystem_include_directories 0) - endif () - if (NOT IS_ABSOLUTE "${_clang_modules_json_module_source}") - string(PREPEND _clang_modules_json_module_source "${_clang_modules_dir}/") - endif () - list(APPEND _clang_modules_module_paths - "${_clang_modules_json_module_source}") - - if (_clang_modules_json_module_is_stdlib) - set(_clang_modules_is_stdlib 1) - endif () - - if (_clang_modules_json_module_nsystem_include_directories) - math(EXPR _clang_modules_json_module_nsystem_include_directories_range "${_clang_modules_json_module_nsystem_include_directories} - 1") - foreach (_clang_modules_json_modules_system_include_directories_idx RANGE 0 "${_clang_modules_json_module_nsystem_include_directories_range}") - string(JSON _clang_modules_json_module_system_include_directory GET "${_clang_modules_json_module_local_arguments}" "system-include-directories" "${_clang_modules_json_modules_system_include_directories_idx}") - - if (NOT IS_ABSOLUTE "${_clang_modules_json_module_system_include_directory}") - string(PREPEND _clang_modules_json_module_system_include_directory "${_clang_modules_dir}/") - endif () - list(APPEND _clang_modules_include_dirs_list - "${_clang_modules_json_module_system_include_directory}") - endforeach () - endif () - endforeach () - - # Split the paths into basedirs and module paths. - set(_clang_modules_base_dirs_list "") - set(_clang_modules_files "") - foreach (_clang_modules_module_path IN LISTS _clang_modules_module_paths) - get_filename_component(_clang_module_dir "${_clang_modules_module_path}" DIRECTORY) - - list(APPEND _clang_modules_base_dirs_list - "${_clang_module_dir}") - string(APPEND _clang_modules_files - " \"${_clang_modules_module_path}\"") - endforeach () - list(REMOVE_DUPLICATES _clang_modules_base_dirs_list) - set(_clang_modules_base_dirs "") - foreach (_clang_modules_base_dir IN LISTS _clang_modules_base_dirs_list) - string(APPEND _clang_modules_base_dirs - " \"${_clang_modules_base_dir}\"") - endforeach () - - # If we have a standard library module, suppress warnings about reserved - # module names. - if (_clang_modules_is_stdlib) - string(APPEND _clang_libcxx_target - "target_compile_options(__cmake_cxx${std} PRIVATE -Wno-reserved-module-identifier)\n") - endif () - - # Set up include directories. - list(REMOVE_DUPLICATES _clang_modules_include_dirs_list) - set(_clang_modules_include_dirs "") - foreach (_clang_modules_include_dir IN LISTS _clang_modules_include_dirs_list) - string(APPEND _clang_modules_include_dirs - " \"${_clang_modules_include_dir}\"") - endforeach () - string(APPEND _clang_libcxx_target - "target_include_directories(__cmake_cxx${std} PRIVATE ${_clang_modules_include_dirs})\n") - - # Create the file set for the modules. - string(APPEND _clang_libcxx_target - "target_sources(__cmake_cxx${std} - PUBLIC - FILE_SET std TYPE CXX_MODULES - BASE_DIRS ${_clang_modules_base_dirs} - FILES ${_clang_modules_files})\n") - - # Wrap the `__cmake_cxx${std}` target in a check. - string(PREPEND _clang_libcxx_target - "if (NOT TARGET \"__cmake_cxx${std}\")\n") - string(APPEND _clang_libcxx_target - "endif ()\n") - string(APPEND _clang_libcxx_target - "add_library(__CMAKE::CXX${std} ALIAS __cmake_cxx${std})\n") - - set("${variable}" "${_clang_libcxx_target}" PARENT_SCOPE) endfunction ()
diff --git a/Modules/Compiler/Clang-CXX.cmake b/Modules/Compiler/Clang-CXX.cmake index 87a4cdd..205c5f7 100644 --- a/Modules/Compiler/Clang-CXX.cmake +++ b/Modules/Compiler/Clang-CXX.cmake
@@ -18,11 +18,6 @@ if("x${CMAKE_CXX_COMPILER_FRONTEND_VARIANT}" STREQUAL "xMSVC") set(CMAKE_CXX_CLANG_TIDY_DRIVER_MODE "cl") set(CMAKE_CXX_INCLUDE_WHAT_YOU_USE_DRIVER_MODE "cl") - if((NOT DEFINED CMAKE_DEPENDS_USE_COMPILER OR CMAKE_DEPENDS_USE_COMPILER) - AND CMAKE_GENERATOR MATCHES "Makefiles" - AND CMAKE_DEPFILE_FLAGS_CXX) - set(CMAKE_CXX_DEPENDS_USE_COMPILER TRUE) - endif() endif() if(CMAKE_CXX_COMPILER_VERSION VERSION_GREATER_EQUAL 16.0) @@ -61,6 +56,7 @@ unset(_clang_scan_deps_mv) set(CMAKE_CXX_MODULE_MAP_FORMAT "clang") set(CMAKE_CXX_MODULE_MAP_FLAG "@<MODULE_MAP_FILE>") - set(CMAKE_CXX_MODULE_BMI_ONLY_FLAG "--precompile") + set(CMAKE_CXX_COMPILE_BMI + "<CMAKE_CXX_COMPILER> <DEFINES> <INCLUDES> <FLAGS> -o <OBJECT> --precompile <SOURCE>") endif() endif()
diff --git a/Modules/Compiler/Clang.cmake b/Modules/Compiler/Clang.cmake index d01d704..6b150ea 100644 --- a/Modules/Compiler/Clang.cmake +++ b/Modules/Compiler/Clang.cmake
@@ -113,8 +113,14 @@ if(CMAKE_${lang}_COMPILER_VERSION VERSION_GREATER_EQUAL 11.0.0 AND NOT __is_apple_clang) set(CMAKE_${lang}_COMPILE_OPTIONS_INSTANTIATE_TEMPLATES_PCH -fpch-instantiate-templates) endif() - set(CMAKE_${lang}_COMPILE_OPTIONS_USE_PCH -Xclang -include-pch -Xclang <PCH_FILE> -Xclang -include -Xclang <PCH_HEADER>) - set(CMAKE_${lang}_COMPILE_OPTIONS_CREATE_PCH -Xclang -emit-pch -Xclang -include -Xclang <PCH_HEADER> -x ${__pch_header_${lang}}) + if (CMAKE_GENERATOR MATCHES "FASTBuild") + # We can't use "-Xclang -emit-pch" since Fastbuild gets spammed with binary content of the .pch file while trying to scan dependencies. + set(CMAKE_${lang}_COMPILE_OPTIONS_USE_PCH -include-pch <PCH_FILE> -Xclang -include -Xclang <PCH_HEADER>) + set(CMAKE_${lang}_COMPILE_OPTIONS_CREATE_PCH -Xclang -include -Xclang <PCH_HEADER> -x ${__pch_header_${lang}}) + else() + set(CMAKE_${lang}_COMPILE_OPTIONS_USE_PCH -Xclang -include-pch -Xclang <PCH_FILE> -Xclang -include -Xclang <PCH_HEADER>) + set(CMAKE_${lang}_COMPILE_OPTIONS_CREATE_PCH -Xclang -emit-pch -Xclang -include -Xclang <PCH_HEADER> -x ${__pch_header_${lang}}) + endif() # '-fcolor-diagnostics' introduced since Clang 2.6 if(CMAKE_${lang}_COMPILER_VERSION VERSION_GREATER_EQUAL 2.6)
diff --git a/Modules/Compiler/GHS-C.cmake b/Modules/Compiler/GHS-C.cmake index a825b0b..9b0d0e8 100644 --- a/Modules/Compiler/GHS-C.cmake +++ b/Modules/Compiler/GHS-C.cmake
@@ -5,6 +5,6 @@ string(APPEND CMAKE_C_FLAGS_INIT " ") string(APPEND CMAKE_C_FLAGS_DEBUG_INIT " -Odebug -g") -string(APPEND CMAKE_C_FLAGS_MINSIZEREL_INIT " -Ospace") -string(APPEND CMAKE_C_FLAGS_RELEASE_INIT " -O") -string(APPEND CMAKE_C_FLAGS_RELWITHDEBINFO_INIT " -O -g") +string(APPEND CMAKE_C_FLAGS_MINSIZEREL_INIT " -DNDEBUG -Ospace") +string(APPEND CMAKE_C_FLAGS_RELEASE_INIT " -DNDEBUG -O") +string(APPEND CMAKE_C_FLAGS_RELWITHDEBINFO_INIT " -DNDEBUG -O -g")
diff --git a/Modules/Compiler/GHS-CXX.cmake b/Modules/Compiler/GHS-CXX.cmake index 07b5044..773fe1c 100644 --- a/Modules/Compiler/GHS-CXX.cmake +++ b/Modules/Compiler/GHS-CXX.cmake
@@ -5,6 +5,6 @@ string(APPEND CMAKE_CXX_FLAGS_INIT " ") string(APPEND CMAKE_CXX_FLAGS_DEBUG_INIT " -Odebug -g") -string(APPEND CMAKE_CXX_FLAGS_MINSIZEREL_INIT " -Ospace") -string(APPEND CMAKE_CXX_FLAGS_RELEASE_INIT " -O") -string(APPEND CMAKE_CXX_FLAGS_RELWITHDEBINFO_INIT " -O -g") +string(APPEND CMAKE_CXX_FLAGS_MINSIZEREL_INIT " -DNDEBUG -Ospace") +string(APPEND CMAKE_CXX_FLAGS_RELEASE_INIT " -DNDEBUG -O") +string(APPEND CMAKE_CXX_FLAGS_RELWITHDEBINFO_INIT " -DNDEBUG -O -g")
diff --git a/Modules/Compiler/GNU-CXX-CXXImportStd.cmake b/Modules/Compiler/GNU-CXX-CXXImportStd.cmake index 965e25a..c8bd960 100644 --- a/Modules/Compiler/GNU-CXX-CXXImportStd.cmake +++ b/Modules/Compiler/GNU-CXX-CXXImportStd.cmake
@@ -1,134 +1,24 @@ -function (_cmake_cxx_import_std std variable) +function (_cmake_cxx_find_modules_json) if (NOT CMAKE_CXX_STANDARD_LIBRARY STREQUAL "libstdc++") - set("${variable}" - "set(CMAKE_CXX${std}_COMPILER_IMPORT_STD_NOT_FOUND_MESSAGE \"Only `libstdc++` is supported\")\n" - PARENT_SCOPE) + set(CMAKE_CXX_COMPILER_IMPORT_STD_ERROR_MESSAGE "Only `libstdc++` is supported" PARENT_SCOPE) return () endif () - execute_process( - COMMAND - "${CMAKE_CXX_COMPILER}" - ${CMAKE_CXX_COMPILER_ID_ARG1} - -print-file-name=libstdc++.modules.json - OUTPUT_VARIABLE _gnu_libstdcxx_modules_json_file - ERROR_VARIABLE _gnu_libstdcxx_modules_json_file_err - RESULT_VARIABLE _gnu_libstdcxx_modules_json_file_res - OUTPUT_STRIP_TRAILING_WHITESPACE - ERROR_STRIP_TRAILING_WHITESPACE) - if (_gnu_libstdcxx_modules_json_file_res) - set("${variable}" - "set(CMAKE_CXX${std}_COMPILER_IMPORT_STD_NOT_FOUND_MESSAGE \"Could not find `libstdc++.modules.json` resource\")\n" - PARENT_SCOPE) - return () + if (NOT CMAKE_CXX_STDLIB_MODULES_JSON) + execute_process( + COMMAND + "${CMAKE_CXX_COMPILER}" + ${CMAKE_CXX_COMPILER_ID_ARG1} + -print-file-name=libstdc++.modules.json + OUTPUT_VARIABLE _gnu_libstdcxx_modules_json_file + ERROR_VARIABLE _gnu_libstdcxx_modules_json_file_err + RESULT_VARIABLE _gnu_libstdcxx_modules_json_file_res + OUTPUT_STRIP_TRAILING_WHITESPACE + ERROR_STRIP_TRAILING_WHITESPACE) + if (_gnu_libstdcxx_modules_json_file_res) + set(CMAKE_CXX_COMPILER_IMPORT_STD_ERROR_MESSAGE "Could not find `libstdc++.modules.json` resource" PARENT_SCOPE) + return () + endif () + set(CMAKE_CXX_STDLIB_MODULES_JSON "${_gnu_libstdcxx_modules_json_file}" PARENT_SCOPE) endif () - - # Without this file, we do not have modules installed. - if (NOT EXISTS "${_gnu_libstdcxx_modules_json_file}") - set("${variable}" - "set(CMAKE_CXX${std}_COMPILER_IMPORT_STD_NOT_FOUND_MESSAGE \"`libstdc++.modules.json` resource does not exist\")\n" - PARENT_SCOPE) - return () - endif () - - file(READ "${_gnu_libstdcxx_modules_json_file}" _gnu_libstdcxx_modules_json) - string(JSON _gnu_modules_json_version GET "${_gnu_libstdcxx_modules_json}" "version") - string(JSON _gnu_modules_json_revision GET "${_gnu_libstdcxx_modules_json}" "revision") - # Require version 1. - if (NOT _gnu_modules_json_version EQUAL "1") - set("${variable}" - "set(CMAKE_CXX${std}_COMPILER_IMPORT_STD_NOT_FOUND_MESSAGE \"`libstdc++.modules.json` version ${_gnu_modules_json_version}.${_gnu_modules_json_revision} is not recognized\")\n" - PARENT_SCOPE) - return () - endif () - - string(JSON _gnu_modules_json_nmodules LENGTH "${_gnu_libstdcxx_modules_json}" "modules") - # Don't declare the target without any modules. - if (NOT _gnu_modules_json_nmodules) - set("${variable}" - "set(CMAKE_CXX${std}_COMPILER_IMPORT_STD_NOT_FOUND_MESSAGE \"`libstdc++.modules.json` does not list any available modules\")\n" - PARENT_SCOPE) - return () - endif () - - # Declare the target. - set(_gnu_libstdcxx_target "") - string(APPEND _gnu_libstdcxx_target - "add_library(__CMAKE::CXX${std} IMPORTED INTERFACE)\n") - string(APPEND _gnu_libstdcxx_target - "target_compile_features(__CMAKE::CXX${std} INTERFACE cxx_std_${std})\n") - - set(_gnu_modules_is_stdlib 0) - set(_gnu_modules_include_dirs_list "") - set(_gnu_modules_module_paths "") - get_filename_component(_gnu_modules_dir "${_gnu_libstdcxx_modules_json_file}" DIRECTORY) - - # Add module sources. - math(EXPR _gnu_modules_json_nmodules_range "${_gnu_modules_json_nmodules} - 1") - foreach (_gnu_modules_json_modules_idx RANGE 0 "${_gnu_modules_json_nmodules_range}") - string(JSON _gnu_modules_json_module GET "${_gnu_libstdcxx_modules_json}" "modules" "${_gnu_modules_json_modules_idx}") - - string(JSON _gnu_modules_json_module_source GET "${_gnu_modules_json_module}" "source-path") - string(JSON _gnu_modules_json_module_is_stdlib GET "${_gnu_modules_json_module}" "is-std-library") - string(JSON _gnu_modules_json_module_local_arguments ERROR_VARIABLE _gnu_modules_json_module_local_arguments_error GET "${_gnu_modules_json_module}" "local-arguments") - string(JSON _gnu_modules_json_module_nsystem_include_directories ERROR_VARIABLE _gnu_modules_json_module_nsystem_include_directories_error LENGTH "${_gnu_modules_json_module_local_arguments}" "system-include-directories") - - if (_gnu_modules_json_module_local_arguments_error STREQUAL "NOTFOUND") - set(_gnu_modules_json_module_local_arguments "") - endif () - if (_gnu_modules_json_module_nsystem_include_directories_error STREQUAL "NOTFOUND") - set(_gnu_modules_json_module_nsystem_include_directories 0) - endif () - - if (NOT IS_ABSOLUTE "${_gnu_modules_json_module_source}") - string(PREPEND _gnu_modules_json_module_source "${_gnu_modules_dir}/") - endif () - list(APPEND _gnu_modules_module_paths - "${_gnu_modules_json_module_source}") - - if (_gnu_modules_json_module_is_stdlib) - set(_gnu_modules_is_stdlib 1) - endif () - - if (_gnu_modules_json_module_nsystem_include_directories) - math(EXPR _gnu_modules_json_module_nsystem_include_directories_range "${_gnu_modules_json_module_nsystem_include_directories} - 1") - foreach (_gnu_modules_json_modules_system_include_directories_idx RANGE 0 "${_gnu_modules_json_module_nsystem_include_directories_range}") - string(JSON _gnu_modules_json_module_system_include_directory GET "${_gnu_modules_json_module_local_arguments}" "system-include-directories" "${_gnu_modules_json_modules_system_include_directories_idx}") - - if (NOT IS_ABSOLUTE "${_gnu_modules_json_module_system_include_directory}") - string(PREPEND _gnu_modules_json_module_system_include_directory "${_gnu_modules_dir}/") - endif () - list(APPEND _gnu_modules_include_dirs_list - "${_gnu_modules_json_module_system_include_directory}") - endforeach () - endif () - endforeach () - - # Split the paths into basedirs and module paths. - set(_gnu_modules_base_dirs_list "") - set(_gnu_modules_files "") - foreach (_gnu_modules_module_path IN LISTS _gnu_modules_module_paths) - get_filename_component(_gnu_module_dir "${_gnu_modules_module_path}" DIRECTORY) - - list(APPEND _gnu_modules_base_dirs_list - "${_gnu_module_dir}") - string(APPEND _gnu_modules_files - " \"${_gnu_modules_module_path}\"") - endforeach () - list(REMOVE_DUPLICATES _gnu_modules_base_dirs_list) - set(_gnu_modules_base_dirs "") - foreach (_gnu_modules_base_dir IN LISTS _gnu_modules_base_dirs_list) - string(APPEND _gnu_modules_base_dirs - " \"${_gnu_modules_base_dir}\"") - endforeach () - - # Create the file set for the modules. - string(APPEND _gnu_libstdcxx_target - "target_sources(__CMAKE::CXX${std} - INTERFACE - FILE_SET std TYPE CXX_MODULES - BASE_DIRS ${_gnu_modules_base_dirs} - FILES ${_gnu_modules_files})\n") - - set("${variable}" "${_gnu_libstdcxx_target}" PARENT_SCOPE) endfunction ()
diff --git a/Modules/Compiler/MSVC-C.cmake b/Modules/Compiler/MSVC-C.cmake index 7de6039..85ceae8 100644 --- a/Modules/Compiler/MSVC-C.cmake +++ b/Modules/Compiler/MSVC-C.cmake
@@ -33,6 +33,16 @@ endmacro() endif() + if(CMAKE_C_COMPILER_VERSION VERSION_GREATER_EQUAL 19.39) + # VS 17.10 did not have a "stdclatest" value for LanguageStandard_C. + if(NOT CMAKE_GENERATOR MATCHES "Visual Studio" + OR CMAKE_VS_VERSION_BUILD_NUMBER VERSION_GREATER_EQUAL 17.11) + set(CMAKE_C23_STANDARD_COMPILE_OPTION "-std:clatest") + set(CMAKE_C23_EXTENSION_COMPILE_OPTION "-std:clatest") + set(CMAKE_C_STANDARD_LATEST 23) + endif() + endif() + __compiler_check_default_language_standard(C 19.27 99) else() # MSVC has no specific options to set C language standards, but set them as
diff --git a/Modules/Compiler/MSVC-CXX-CXXImportStd.cmake b/Modules/Compiler/MSVC-CXX-CXXImportStd.cmake index 08199f7..b7bd525 100644 --- a/Modules/Compiler/MSVC-CXX-CXXImportStd.cmake +++ b/Modules/Compiler/MSVC-CXX-CXXImportStd.cmake
@@ -1,4 +1,8 @@ -function (_cmake_cxx_import_std std variable) +function (_cmake_cxx_find_modules_json) + if (CMAKE_CXX_STDLIB_MODULES_JSON) + return () + endif () + find_file(_msvc_modules_json_file NAME modules.json HINTS @@ -10,106 +14,91 @@ PATH_SUFFIXES ../modules NO_CACHE) + # Without this file, we do not have modules installed. if (NOT EXISTS "${_msvc_modules_json_file}") - set("${variable}" - "set(CMAKE_CXX${std}_COMPILER_IMPORT_STD_NOT_FOUND_MESSAGE \"Could not find `modules.json` resource\")\n" - PARENT_SCOPE) + set(CMAKE_CXX_COMPILER_IMPORT_STD_ERROR_MESSAGE "Could not find `modules.json` resource" PARENT_SCOPE) return () endif () file(READ "${_msvc_modules_json_file}" _msvc_modules_json) + string(JSON _msvc_json_modules ERROR_VARIABLE _msvc_json_err GET "${_msvc_modules_json}" "modules") + + # This is probably a conforming module metadata file, use it as is + if (_msvc_json_modules) + set(CMAKE_CXX_STDLIB_MODULES_JSON "${_msvc_modules_json_file}" PARENT_SCOPE) + return () + endif () + + # Otherwise it's a Microsoft STL-style modules.json, check if we recognize it string(JSON _msvc_json_version GET "${_msvc_modules_json}" "version") string(JSON _msvc_json_revision GET "${_msvc_modules_json}" "revision") # Require version 1. if (NOT _msvc_json_version EQUAL "1") - set("${variable}" - "set(CMAKE_CXX${std}_COMPILER_IMPORT_STD_NOT_FOUND_MESSAGE \"`modules.json` version ${_msvc_json_version}.${_msvc_json_revision} is not recognized\")\n" - PARENT_SCOPE) + set(CMAKE_CXX_COMPILER_IMPORT_STD_ERROR_MESSAGE "`modules.json` version ${_msvc_json_version}.${_msvc_json_revision} is not recognized" PARENT_SCOPE) return () endif () string(JSON _msvc_json_library GET "${_msvc_modules_json}" "library") # Bail if we don't understand the library. if (NOT _msvc_json_library STREQUAL "microsoft/STL") - set("${variable}" - "set(CMAKE_CXX${std}_COMPILER_IMPORT_STD_NOT_FOUND_MESSAGE \"`modules.json` library `${_msvc_json_library}` is not recognized\")\n" - PARENT_SCOPE) + set(CMAKE_CXX_COMPILER_IMPORT_STD_ERROR_MESSAGE "`modules.json` library `${_msvc_json_library}` is not recognized" PARENT_SCOPE) return () endif () - string(JSON _msvc_json_nmodules LENGTH "${_msvc_modules_json}" "module-sources") - # Don't declare the target without any modules. - if (NOT _msvc_json_nmodules) - set("${variable}" - "set(CMAKE_CXX${std}_COMPILER_IMPORT_STD_NOT_FOUND_MESSAGE \"`modules.json` does not list any available modules\")\n" - PARENT_SCOPE) + string(JSON _msvc_json_sources_len LENGTH "${_msvc_modules_json}" "module-sources") + # Bail if there aren't any sources + if (NOT _msvc_json_sources_len) + set(CMAKE_CXX_COMPILER_IMPORT_STD_ERROR_MESSAGE "`modules.json` does not list any available sources" PARENT_SCOPE) return () endif () - # Declare the target. - set(_msvc_std_target "") - string(APPEND _msvc_std_target - "add_library(__cmake_cxx${std} STATIC)\n") - string(APPEND _msvc_std_target - "target_sources(__cmake_cxx${std} INTERFACE \"$<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,STATIC_LIBRARY>:$<TARGET_OBJECTS:__cmake_cxx${std}>>\")\n") - string(APPEND _msvc_std_target - "set_property(TARGET __cmake_cxx${std} PROPERTY EXCLUDE_FROM_ALL 1)\n") - string(APPEND _msvc_std_target - "set_property(TARGET __cmake_cxx${std} PROPERTY CXX_SCAN_FOR_MODULES 1)\n") - string(APPEND _msvc_std_target - "set_property(TARGET __cmake_cxx${std} PROPERTY CXX_MODULE_STD 0)\n") - string(APPEND _msvc_std_target - "target_compile_features(__cmake_cxx${std} PUBLIC cxx_std_${std})\n") + set(_msvc_module_metadata [=[{ + "version": 1, + "revision": 1, + "modules": [] + }]=]) - set(_msvc_modules_module_paths "") - get_filename_component(_msvc_modules_dir "${_msvc_modules_json_file}" DIRECTORY) + cmake_path(GET _msvc_modules_json_file PARENT_PATH _msvc_base_dir) + math(EXPR _msvc_json_sources_len "${_msvc_json_sources_len}-1") + foreach (idx RANGE ${_msvc_json_sources_len}) + string(JSON _msvc_source GET "${_msvc_modules_json}" "module-sources" ${idx}) - # Add module sources. - math(EXPR _msvc_modules_json_nmodules_range "${_msvc_json_nmodules} - 1") - foreach (_msvc_modules_json_modules_idx RANGE 0 "${_msvc_modules_json_nmodules_range}") - string(JSON _msvc_modules_json_module_source GET "${_msvc_modules_json}" "module-sources" "${_msvc_modules_json_modules_idx}") - - if (NOT IS_ABSOLUTE "${_msvc_modules_json_module_source}") - string(PREPEND _msvc_modules_json_module_source "${_msvc_modules_dir}/") + set(_msvc_path ${_msvc_source}) + cmake_path(IS_RELATIVE _msvc_path _msvc_is_rel) + if (_msvc_is_rel) + cmake_path(ABSOLUTE_PATH _msvc_path BASE_DIRECTORY "${_msvc_base_dir}") endif () - list(APPEND _msvc_modules_module_paths - "${_msvc_modules_json_module_source}") - endforeach () - # Split the paths into basedirs and module paths. - set(_msvc_modules_base_dirs_list "") - set(_msvc_modules_files "") - foreach (_msvc_modules_module_path IN LISTS _msvc_modules_module_paths) - get_filename_component(_msvc_module_dir "${_msvc_modules_module_path}" DIRECTORY) + if (_msvc_source MATCHES "std.ixx") + string(JSON _msvc_module_metadata + SET "${_msvc_module_metadata}" "modules" ${idx} + "{ + \"logical-name\": \"std\", + \"source-path\": \"${_msvc_path}\", + \"is-std-library\": true + }" + ) + elseif (_msvc_source MATCHES "std.compat.ixx") + string(JSON _msvc_module_metadata + SET "${_msvc_module_metadata}" "modules" ${idx} + "{ + \"logical-name\": \"std.compat\", + \"source-path\": \"${_msvc_path}\", + \"is-std-library\": true + }" + ) + endif () + endforeach() - list(APPEND _msvc_modules_base_dirs_list - "${_msvc_module_dir}") - string(APPEND _msvc_modules_files - " \"${_msvc_modules_module_path}\"") - endforeach () - list(REMOVE_DUPLICATES _msvc_modules_base_dirs_list) - set(_msvc_modules_base_dirs "") - foreach (_msvc_modules_base_dir IN LISTS _msvc_modules_base_dirs_list) - string(APPEND _msvc_modules_base_dirs - " \"${_msvc_modules_base_dir}\"") - endforeach () + string(JSON _msvc_module_metadata_modules_len LENGTH ${_msvc_module_metadata} "modules") - # Create the file set for the modules. - string(APPEND _msvc_std_target - "target_sources(__cmake_cxx${std} - PUBLIC - FILE_SET std TYPE CXX_MODULES - BASE_DIRS ${_msvc_modules_base_dirs} - FILES ${_msvc_modules_files})\n") + # Bail if we didn't recognize any of the modules + if (NOT _msvc_module_metadata_modules_len) + set(CMAKE_CXX_COMPILER_IMPORT_STD_ERROR_MESSAGE "`modules.json` did not contain any recognized sources (std.ixx, std.compat.ixx)" PARENT_SCOPE) + return () + endif () - # Wrap the `__cmake_cxx${std}` target in a check. - string(PREPEND _msvc_std_target - "if (NOT TARGET \"__cmake_cxx${std}\")\n") - string(APPEND _msvc_std_target - "endif ()\n") - string(APPEND _msvc_std_target - "add_library(__CMAKE::CXX${std} ALIAS __cmake_cxx${std})\n") - - set("${variable}" "${_msvc_std_target}" PARENT_SCOPE) + file(WRITE "${CMAKE_PLATFORM_INFO_DIR}/msvcstl.modules.json" "${_msvc_module_metadata}") + set(CMAKE_CXX_STDLIB_MODULES_JSON "${CMAKE_PLATFORM_INFO_DIR}/msvcstl.modules.json" PARENT_SCOPE) endfunction ()
diff --git a/Modules/Compiler/QCC.cmake b/Modules/Compiler/QCC.cmake index d16b2d4..aede0bc 100644 --- a/Modules/Compiler/QCC.cmake +++ b/Modules/Compiler/QCC.cmake
@@ -13,7 +13,7 @@ set(CMAKE_PREFIX_LIBRARY_ARCHITECTURE "ON") set(CMAKE_${lang}_COMPILE_OPTIONS_SYSROOT "-Wc,-isysroot,") - set(CMAKE_INCLUDE_SYSTEM_FLAG_${lang} "-Wp,-isystem,") + set(CMAKE_INCLUDE_SYSTEM_FLAG_${lang} "-isystem ") set(CMAKE_DEPFILE_FLAGS_${lang} "-Wp,-MD,<DEP_FILE> -Wp,-MT,<DEP_TARGET> -Wp,-MF,<DEP_FILE>") set(CMAKE_${lang}_LINKER_WRAPPER_FLAG "-Wl,")
diff --git a/Modules/Compiler/TIClang-C.cmake b/Modules/Compiler/TIClang-C.cmake index b6ce3dc..ed637be 100644 --- a/Modules/Compiler/TIClang-C.cmake +++ b/Modules/Compiler/TIClang-C.cmake
@@ -22,12 +22,23 @@ set(CMAKE_C11_EXTENSION_COMPILE_OPTION "-std=gnu11") set(CMAKE_C11_STANDARD__HAS_FULL_SUPPORT ON) -set(CMAKE_C_STANDARD_LATEST 11) +if(CMAKE_C_COMPILER_VERSION VERSION_GREATER_EQUAL 1.3) + set(CMAKE_C17_STANDARD_COMPILE_OPTION "-std=c17") + set(CMAKE_C17_EXTENSION_COMPILE_OPTION "-std=gnu17") + set(CMAKE_C17_STANDARD__HAS_FULL_SUPPORT ON) + set(CMAKE_C_STANDARD_LATEST 17) +else() + set(CMAKE_C_STANDARD_LATEST 11) +endif() + # Including the "${CMAKE_ROOT}/Modules/Compiler/Clang-C.cmake" script above may set several other compile option # variables which do not necessarily apply here. So, we unset those variables accordingly. -unset(CMAKE_C17_STANDARD_COMPILE_OPTION) -unset(CMAKE_C17_EXTENSION_COMPILE_OPTION) + +if(CMAKE_C_COMPILER_VERSION VERSION_LESS 1.3) + unset(CMAKE_C17_STANDARD_COMPILE_OPTION) + unset(CMAKE_C17_EXTENSION_COMPILE_OPTION) +endif() unset(CMAKE_C23_STANDARD_COMPILE_OPTION) unset(CMAKE_C23_EXTENSION_COMPILE_OPTION)
diff --git a/Modules/ExternalData.cmake b/Modules/ExternalData.cmake index 5d28929..02d8bd9 100644 --- a/Modules/ExternalData.cmake +++ b/Modules/ExternalData.cmake
@@ -9,7 +9,14 @@ .. contents:: -Manage data files stored outside source tree +This module provides commands to manage data files stored outside source +tree. + +Load this module in a CMake project with: + +.. code-block:: cmake + + include(ExternalData) Introduction ^^^^^^^^^^^^ @@ -485,7 +492,7 @@ # Store configuration for use by build-time script. set(config ${CMAKE_CURRENT_BINARY_DIR}/${target}_config.cmake) - configure_file(${_ExternalData_SELF_DIR}/ExternalData_config.cmake.in ${config} @ONLY) + configure_file(${CMAKE_CURRENT_FUNCTION_LIST_DIR}/ExternalData_config.cmake.in ${config} @ONLY) set(files "") @@ -517,7 +524,7 @@ -DExternalData_ACTION=local -DExternalData_SHOW_PROGRESS=${_ExternalData_add_target_SHOW_PROGRESS} -DExternalData_CONFIG=${config} - -P ${_ExternalData_SELF} + -P ${CMAKE_CURRENT_FUNCTION_LIST_FILE} MAIN_DEPENDENCY "${name}" ) endif() @@ -554,7 +561,7 @@ -DExternalData_ACTION=fetch -DExternalData_SHOW_PROGRESS=${_ExternalData_add_target_SHOW_PROGRESS} -DExternalData_CONFIG=${config} - -P ${_ExternalData_SELF} + -P ${CMAKE_CURRENT_FUNCTION_LIST_FILE} # Update whenever the object hash changes. MAIN_DEPENDENCY "${name}${first_ext}" ) @@ -608,8 +615,6 @@ set(_ExternalData_REGEX_ALGO "MD5|SHA1|SHA224|SHA256|SHA384|SHA512|SHA3_224|SHA3_256|SHA3_384|SHA3_512") set(_ExternalData_REGEX_EXT "md5|sha1|sha224|sha256|sha384|sha512|sha3-224|sha3-256|sha3-384|sha3-512") -set(_ExternalData_SELF "${CMAKE_CURRENT_LIST_FILE}") -get_filename_component(_ExternalData_SELF_DIR "${_ExternalData_SELF}" PATH) function(_ExternalData_compute_hash var_hash algo file) if("${algo}" MATCHES "^${_ExternalData_REGEX_ALGO}$")
diff --git a/Modules/ExternalProject.cmake b/Modules/ExternalProject.cmake index 61e2ea5..fefcd27 100644 --- a/Modules/ExternalProject.cmake +++ b/Modules/ExternalProject.cmake
@@ -11,6 +11,15 @@ .. contents:: +This module provides commands to download and build external projects as +part of CMake build phase. + +Load this module in a CMake project with: + +.. code-block:: cmake + + include(ExternalProject) + External Project Definition ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -654,6 +663,48 @@ examples of build systems whose build step is smart enough to know if the configure step needs to be rerun. +``CONFIGURE_ENVIRONMENT_MODIFICATION <modification>...`` + .. versionadded:: 4.2 + + Specify environment variables that should be modified for the configure step. + + Set a :ref:`semicolon-separated list <CMake Language Lists>` 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: + + .. include:: ../include/ENVIRONMENT_MODIFICATION_OPS.rst + + .. code-block:: cmake + + ExternalProject_Add(example + ... # Download options, etc... + CONFIGURE_ENVIRONMENT_MODIFICATION + SDKROOT=set:macosx + PKG_CONFIG_PATH=set:$ENV{PKG_CONFIG_PATH} + ) + + This snippet defines two environment variables when configuring the example + project. The ``SDKROOT`` environment variable is set to ``macosx``, while + the value of ``PKG_CONFIG_PATH`` is forwarded to the external project. + + Environment modifications work with ``LIST_SEPARATOR`` to replace the + separator with a ``;`` in the environment variable. + + .. code-block:: cmake + + ExternalProject_Add(example + ... # Download options, etc... + LIST_SEPARATOR , + CONFIGURE_ENVIRONMENT_MODIFICATION + LIST_VAR=set:a,b,c + ) + + This snippet + and the environment variable ``LIST_VAR`` is passed to the configure command + invocation with the value ``a;b;c``. + Build Step Options """""""""""""""""" @@ -719,6 +770,19 @@ ``JOB_SERVER_AWARE`` option for details. This option is relevant only when an explicit ``BUILD_COMMAND`` is specified. +``BUILD_ENVIRONMENT_MODIFICATION <modification>...`` + .. versionadded:: 4.2 + + Specify environment variables that should be modified for the build step. + + Set a :ref:`semicolon-separated list <CMake Language Lists>` 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: + + .. include:: ../include/ENVIRONMENT_MODIFICATION_OPS.rst + Install Step Options """""""""""""""""""" @@ -777,6 +841,19 @@ :envvar:`CMAKE_INSTALL_MODE` environment variable changes from one run to another. +``INSTALL_ENVIRONMENT_MODIFICATION <modification>...`` + .. versionadded:: 4.2 + + Specify environment variables that should be modified for the install step. + + Set a :ref:`semicolon-separated list <CMake Language Lists>` 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: + + .. include:: ../include/ENVIRONMENT_MODIFICATION_OPS.rst + Test Step Options """"""""""""""""" @@ -815,6 +892,19 @@ This may cause a step target to be created automatically for either the ``install`` or ``build`` step. See policy :policy:`CMP0114`. +``TEST_ENVIRONMENT_MODIFICATION <modification>...`` + .. versionadded:: 4.2 + + Specify environment variables that should be modified for the test step. + + Set a :ref:`semicolon-separated list <CMake Language Lists>` 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: + + .. include:: ../include/ENVIRONMENT_MODIFICATION_OPS.rst + Output Logging Options """""""""""""""""""""" @@ -940,7 +1030,8 @@ """"""""""""""""""""" ``LIST_SEPARATOR <sep>`` - For any of the various ``..._COMMAND`` options, and ``CMAKE_ARGS``, + For any of the various ``..._COMMAND`` options, ``CMAKE_ARGS``, and + `..._ENVIRONMENT_MODIFICATION`` operations, ``ExternalProject`` will replace ``<sep>`` with ``;`` in the specified command lines. This can be used to ensure a command has a literal ``;`` in it where direct usage would otherwise be interpreted as argument separators to @@ -1043,6 +1134,20 @@ ``DEPENDS <file>...`` Files on which this custom step depends. + ``ENVIRONMENT_MODIFICATION <modification>...`` + .. versionadded:: 4.2 + + Specify environment variables that should be modified while running the + commands in the external project step. + + Set a :ref:`semicolon-separated list <CMake Language Lists>` 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: + + .. include:: ../include/ENVIRONMENT_MODIFICATION_OPS.rst + ``INDEPENDENT <bool>`` .. versionadded:: 3.19 @@ -2057,6 +2162,7 @@ DEPENDEES DEPENDERS DEPENDS + ENVIRONMENT_MODIFICATION INDEPENDENT BYPRODUCTS ALWAYS @@ -2167,13 +2273,50 @@ PROPERTY _EP_${step}_WORKING_DIRECTORY ) - # Replace list separators. + # Replace list separators and inject environment modifications. get_property(sep TARGET ${name} PROPERTY _EP_LIST_SEPARATOR ) - if(sep AND command) - string(REPLACE "${sep}" "\\;" command "${command}") + get_property(environment + TARGET ${name} + PROPERTY _EP_${step}_ENVIRONMENT_MODIFICATION + ) + if(environment) + set(env_args "") + foreach(env_mod IN LISTS environment) + if(env_mod MATCHES [[^([^=:]+)=([a-z_]+):(.*)$]]) + set(_value "${CMAKE_MATCH_3}") + # Replace the separator only in the value in case it is `:`. + if(sep) + string(REPLACE "${sep}" [[\;]] _value "${_value}") + endif() + list(APPEND env_args --modify "${CMAKE_MATCH_1}=${CMAKE_MATCH_2}:${_value}") + else() + message(SEND_ERROR "Malformed environment modification specifier:" + " '${env_mod}'\n" + "Expected MYVAR=OP:VALUE") + endif() + endforeach() + set(env_command "${CMAKE_COMMAND};-E;env;${env_args};--") + else() + set(env_command "") + endif() + if(command) + if(env_command) + # Strip empty commands so we do not add env for them. + string(REGEX REPLACE [[^COMMAND;+(COMMAND;+)*]] "" command "${command}") + string(REGEX REPLACE [[;COMMAND;+(COMMAND;+)*]] ";COMMAND;" command "${command}") + # Replace the separator with an extra escape to survive list(TRANSFORM). + if(sep) + string(REPLACE "${sep}" [[\\;]] command "${command}") + endif() + # Prepend every command with our environment modification launcher. + list(TRANSFORM command APPEND ";${env_command}" REGEX "^COMMAND$") + set(command "${env_command};${command}") + elseif(sep) + string(REPLACE "${sep}" [[\;]] command "${command}") + endif() endif() # Replace location tags. @@ -2660,6 +2803,14 @@ set(dependees patch) endif() + get_property(environment + TARGET ${name} + PROPERTY _EP_CONFIGURE_ENVIRONMENT_MODIFICATION + ) + if(environment) + set(environment "ENVIRONMENT_MODIFICATION" ${environment}) + endif() + get_property(log TARGET ${name} PROPERTY _EP_LOG_CONFIGURE @@ -2691,6 +2842,7 @@ WORKING_DIRECTORY \${binary_dir} DEPENDEES \${dependees} DEPENDS \${file_deps} + ${environment} ${log} ${uses_terminal} )" @@ -2770,6 +2922,13 @@ set(maybe_JOB_SERVER_AWARE "") endif() + get_property(environment + TARGET ${name} + PROPERTY _EP_BUILD_ENVIRONMENT_MODIFICATION + ) + if(environment) + set(environment ENVIRONMENT_MODIFICATION ${environment}) + endif() set(__cmdQuoted) foreach(__item IN LISTS cmd) @@ -2785,6 +2944,7 @@ DEPENDS \${file_deps} ALWAYS \${always} ${maybe_JOB_SERVER_AWARE} + ${environment} ${log} ${uses_terminal} )" @@ -2857,6 +3017,14 @@ set(maybe_JOB_SERVER_AWARE "") endif() + get_property(environment + TARGET ${name} + PROPERTY _EP_INSTALL_ENVIRONMENT_MODIFICATION + ) + if(environment) + set(environment ENVIRONMENT_MODIFICATION ${environment}) + endif() + set(__cmdQuoted) foreach(__item IN LISTS cmd) string(APPEND __cmdQuoted " [==[${__item}]==]") @@ -2870,6 +3038,7 @@ DEPENDEES build ALWAYS \${always} ${maybe_JOB_SERVER_AWARE} + ${environment} ${log} ${uses_terminal} )" @@ -2936,6 +3105,14 @@ set(uses_terminal "") endif() + get_property(environment + TARGET ${name} + PROPERTY _EP_TEST_ENVIRONMENT_MODIFICATION + ) + if(environment) + set(environment ENVIRONMENT_MODIFICATION ${environment}) + endif() + set(__cmdQuoted) foreach(__item IN LISTS cmd) string(APPEND __cmdQuoted " [==[${__item}]==]") @@ -2948,6 +3125,7 @@ ${dependees_args} ${dependers_args} ${exclude_args} + ${environment} ${log} ${uses_terminal} )" @@ -3043,11 +3221,11 @@ # rebuilds. It is important that 'done' is not the output of any # custom command so that CMake does not propagate build rules to # other external project targets, which may cause problems during - # parallel builds. However, the Ninja generator needs to see the entire + # parallel builds. However, the Ninja and Fastbuild generators need to see the entire # dependency graph, and can cope with custom commands belonging to - # multiple targets, so we add the 'done' mark as an output for Ninja only. + # multiple targets, so we add the 'done' mark as an output for Ninja and Fastbuild only. set(complete_outputs ${complete_stamp_file}) - if(${CMAKE_GENERATOR} MATCHES "Ninja") + if(${CMAKE_GENERATOR} MATCHES "Ninja|FASTBuild") set(complete_outputs ${complete_outputs} ${done_stamp_file}) endif()
diff --git a/Modules/ExternalProject/shared_internal_commands.cmake b/Modules/ExternalProject/shared_internal_commands.cmake index cb7b772..b7077ef 100644 --- a/Modules/ExternalProject/shared_internal_commands.cmake +++ b/Modules/ExternalProject/shared_internal_commands.cmake
@@ -1,4 +1,4 @@ -cmake_policy(VERSION 3.25) +cmake_policy(VERSION 4.1) # Determine the remote URL of the project containing the working_directory. # This will leave output_variable unset if the URL can't be determined. @@ -55,9 +55,9 @@ endif() endif() - if(GIT_VERSION VERSION_LESS 1.7.5) + if(Git_VERSION VERSION_LESS 1.7.5) set(_git_remote_url_cmd_args config remote.${git_remote_name}.url) - elseif(GIT_VERSION VERSION_LESS 2.7) + elseif(Git_VERSION VERSION_LESS 2.7) set(_git_remote_url_cmd_args ls-remote --get-url ${git_remote_name}) else() set(_git_remote_url_cmd_args remote get-url ${git_remote_name}) @@ -399,7 +399,7 @@ tls_verify ) - if(NOT GIT_VERSION_STRING VERSION_LESS 1.8.5) + if(NOT Git_VERSION VERSION_LESS 1.8.5) # Use `git checkout <tree-ish> --` to avoid ambiguity with a local path. set(git_checkout_explicit-- "--") else() @@ -412,14 +412,14 @@ message(FATAL_ERROR "Tag for git checkout should not be empty.") endif() - if(GIT_VERSION_STRING VERSION_LESS 2.20 OR - 2.21 VERSION_LESS_EQUAL GIT_VERSION_STRING) + if(Git_VERSION VERSION_LESS 2.20 OR + 2.21 VERSION_LESS_EQUAL Git_VERSION) set(git_clone_options "--no-checkout") else() set(git_clone_options) endif() if(git_shallow) - if(NOT GIT_VERSION_STRING VERSION_LESS 1.7.10) + if(NOT Git_VERSION VERSION_LESS 1.7.10) list(APPEND git_clone_options "--depth 1 --no-single-branch") else() list(APPEND git_clone_options "--depth 1") @@ -511,10 +511,10 @@ message(FATAL_ERROR "Tag for git checkout should not be empty.") endif() set(git_stash_save_options --quiet) - if(GIT_VERSION_STRING VERSION_GREATER_EQUAL 1.7.7) + if(Git_VERSION VERSION_GREATER_EQUAL 1.7.7) # This avoids stashing files covered by .gitignore list(APPEND git_stash_save_options --include-untracked) - elseif(GIT_VERSION_STRING VERSION_GREATER_EQUAL 1.7.6) + elseif(Git_VERSION VERSION_GREATER_EQUAL 1.7.6) # Untracked files, but also ignored files, so potentially slower list(APPEND git_stash_save_options --all) endif() @@ -740,10 +740,10 @@ set(${git_submodules_recurse} "${recurseFlag}" PARENT_SCOPE) # The git submodule update '--recursive' flag requires git >= v1.6.5 - if(recurseFlag AND GIT_VERSION_STRING VERSION_LESS 1.6.5) + if(recurseFlag AND Git_VERSION VERSION_LESS 1.6.5) message(FATAL_ERROR "git version 1.6.5 or later required for --recursive flag with " - "'git submodule ...': GIT_VERSION_STRING='${GIT_VERSION_STRING}'" + "'git submodule ...': Git_VERSION='${Git_VERSION}'" ) endif() endfunction() @@ -921,7 +921,7 @@ elseif(git_repository) set(method git) # FetchContent gives us these directly, so don't try to recompute them - if(NOT GIT_EXECUTABLE OR NOT GIT_VERSION_STRING) + if(NOT GIT_EXECUTABLE OR NOT Git_VERSION) unset(CMAKE_MODULE_PATH) # Use CMake builtin find module find_package(Git QUIET) if(NOT GIT_EXECUTABLE) @@ -957,7 +957,7 @@ # If git supports it, make checkouts quiet when checking out a git hash. # This avoids the very noisy detached head message. - if(GIT_VERSION_STRING VERSION_GREATER_EQUAL 1.7.7) + if(Git_VERSION VERSION_GREATER_EQUAL 1.7.7) list(PREPEND git_config advice.detachedHead=false) endif() @@ -1496,7 +1496,7 @@ elseif(git_repository) # FetchContent gives us these directly, so don't try to recompute them - if(NOT GIT_EXECUTABLE OR NOT GIT_VERSION_STRING) + if(NOT GIT_EXECUTABLE OR NOT Git_VERSION) unset(CMAKE_MODULE_PATH) # Use CMake builtin find module find_package(Git QUIET) if(NOT GIT_EXECUTABLE) @@ -1596,7 +1596,7 @@ set(hg_tag "tip") endif() - if("${HG_VERSION_STRING}" STREQUAL "2.1") + if("${Hg_VERSION}" STREQUAL "2.1") set(notesAnchor "#A2.1.1:_revert_pull_return_code_change.2C_compile_issue_on_OS_X" ) @@ -1896,6 +1896,7 @@ # Configure step options # CONFIGURE_COMMAND + CONFIGURE_ENVIRONMENT_MODIFICATION CMAKE_COMMAND CMAKE_GENERATOR CMAKE_GENERATOR_PLATFORM @@ -1910,6 +1911,7 @@ # Build step options # BUILD_COMMAND + BUILD_ENVIRONMENT_MODIFICATION BUILD_IN_SOURCE BUILD_ALWAYS BUILD_BYPRODUCTS @@ -1918,12 +1920,14 @@ # Install step options # INSTALL_COMMAND + INSTALL_ENVIRONMENT_MODIFICATION INSTALL_BYPRODUCTS INSTALL_JOB_SERVER_AWARE # # Test step options # TEST_COMMAND + TEST_ENVIRONMENT_MODIFICATION TEST_BEFORE_INSTALL TEST_AFTER_INSTALL TEST_EXCLUDE_FROM_MAIN
diff --git a/Modules/FeatureSummary.cmake b/Modules/FeatureSummary.cmake index c4b27da..6b83903 100644 --- a/Modules/FeatureSummary.cmake +++ b/Modules/FeatureSummary.cmake
@@ -7,32 +7,45 @@ FeatureSummary -------------- -Functions for generating a summary of enabled/disabled features. +.. only:: html -These functions can be used to generate a summary of enabled and disabled -packages and/or features for a build tree such as:: + .. contents:: - -- The following features have been enabled: +This module provides commands for generating a summary of enabled/disabled +features. - * Example, usage example +Load this module in CMake with: - -- The following OPTIONAL packages have been found: +.. code-block:: cmake - * LibXml2 (required version >= 2.4), XML library, <http://xmlsoft.org> - Enables HTML-import in MyWordProcessor - Enables odt-export in MyWordProcessor - * PNG, image library, <http://www.libpng.org/pub/png/> - Enables saving screenshots + include(FeatureSummary) - -- The following OPTIONAL packages have not been found: +Commands provided by this module can be used to generate a summary of enabled +and disabled packages and/or features for a build tree such as:: - * Lua, the Lua scripting language, <https://www.lua.org> - Enables macros in MyWordProcessor - * OpenGL, Open Graphics Library + -- The following features have been enabled: + + * Example, usage example + + -- The following OPTIONAL packages have been found: + + * LibXml2 (required version >= 2.4), XML library, <http://xmlsoft.org> + Enables HTML-import in MyWordProcessor + Enables odt-export in MyWordProcessor + * PNG, image library, <http://www.libpng.org/pub/png/> + Enables saving screenshots + + -- The following OPTIONAL packages have not been found: + + * Lua, the Lua scripting language, <https://www.lua.org> + Enables macros in MyWordProcessor + * OpenGL, Open Graphics Library Global Properties ^^^^^^^^^^^^^^^^^ +The following global properties are used by this module: + .. variable:: FeatureSummary_PKG_TYPES .. versionadded:: 3.8 @@ -69,8 +82,9 @@ This global property defines the default package type. - When the :command:`feature_summary()` command is called, and the user has not - explicitly set a type of some package, its type will be set to this value. + When the :command:`feature_summary()` command is called, and the user has + not explicitly set a type of some package, its type will be set to the + value of this property. This value must be one of the types defined in the :variable:`FeatureSummary_PKG_TYPES` global property. @@ -88,6 +102,519 @@ The following <FeatureSummary_<TYPE>_DESCRIPTION> have been found: If not set, default string ``<TYPE> packages`` is used. + +Commands +^^^^^^^^ + +This module provides the following commands: + +* :command:`feature_summary` +* :command:`set_package_properties` +* :command:`add_feature_info` + +Printing Feature Summary +"""""""""""""""""""""""" + +.. command:: feature_summary + + Prints information about enabled or disabled packages and features of a + project: + + .. code-block:: cmake + + feature_summary( + WHAT (ALL + | PACKAGES_FOUND | PACKAGES_NOT_FOUND + | <TYPE>_PACKAGES_FOUND | <TYPE>_PACKAGES_NOT_FOUND + | ENABLED_FEATURES | DISABLED_FEATURES) + [FILENAME <file>] + [APPEND] + [VAR <variable-name>] + [INCLUDE_QUIET_PACKAGES] + [FATAL_ON_MISSING_REQUIRED_PACKAGES] + [DESCRIPTION <description> | DEFAULT_DESCRIPTION] + [QUIET_ON_EMPTY] + ) + + This command can be used to print information about enabled or disabled + packages and features of a project. By default, only the names of the + features/packages will be printed and their required version when one was + specified. Use :command:`set_package_properties()` to add more useful + information, e.g., a homepage URL for the respective package or their + purpose in the project. + + .. rubric:: The arguments are: + + ``WHAT`` + This is the only mandatory option. It specifies what information will be + printed: + + ``ALL`` + Print everything. + ``ENABLED_FEATURES`` + The list of all features which are enabled. + ``DISABLED_FEATURES`` + The list of all features which are disabled. + ``PACKAGES_FOUND`` + The list of all packages which have been found. + ``PACKAGES_NOT_FOUND`` + The list of all packages which have not been found. + + For each package type ``<TYPE>`` defined by the + :variable:`FeatureSummary_PKG_TYPES` global property, the following + information can also be used: + + ``<TYPE>_PACKAGES_FOUND`` + The list of only packages of type ``<TYPE>`` which have been found. + ``<TYPE>_PACKAGES_NOT_FOUND`` + The list of only packages of type ``<TYPE>`` which have not been found. + + .. versionchanged:: 3.1 + The ``WHAT`` option is now a multi-value keyword, so that these values can + be combined, with the exception of the ``ALL`` value, in order to + customize the output. For example: + + .. code-block:: cmake + + feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES) + + ``FILENAME <file>`` + If this option is given, the information is printed into this file instead + of the terminal. Relative ``<file>`` path is interpreted as being relative + to the current source directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`). + + ``APPEND`` + If this option is given, the output is appended to the ``<file>`` provided + by the ``FILENAME`` option, otherwise the file is overwritten if it already + exists. + + ``VAR <variable-name>`` + If this option is given, the information is stored into the specified + variable ``<variable-name>`` instead of the terminal. + + ``INCLUDE_QUIET_PACKAGES`` + If this option is given, packages which have been searched with + :command:`find_package(... QUIET)` will also be listed. By default they are + skipped. + + ``FATAL_ON_MISSING_REQUIRED_PACKAGES`` + If this option is given, CMake will abort with fatal error if a package + which is marked as one of the package types listed in the + :variable:`FeatureSummary_REQUIRED_PKG_TYPES` global property has not been + found. + + ``DESCRIPTION <description>`` + A description or headline which will be printed above the actual content. + Without this option, if only one package type was requested, no title is + printed, unless a custom string is explicitly set using this option or + ``DEFAULT_DESCRIPTION`` option is used that outputs a default title for the + requested type. + + ``DEFAULT_DESCRIPTION`` + .. versionadded:: 3.9 + + The default description or headline to be printed above the content as + opposed to the customizable ``DESCRIPTION <description>``. + + ``QUIET_ON_EMPTY`` + .. versionadded:: 3.8 + + If this option is given, when only one package type was requested, and no + packages belonging to that category were found, then no output (including + the ``DESCRIPTION``) is printed nor added to the ``FILENAME``, or the + ``VAR`` variable. + +Package Properties +"""""""""""""""""" + +.. command:: set_package_properties + + Sets package properties: + + .. code-block:: cmake + + set_package_properties( + <PackageName> + PROPERTIES + [URL <url>] + [DESCRIPTION <description>] + [TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED)] + [PURPOSE <purpose>] + ) + + Use this command to configure and provide information about the package + named ``<PackageName>``, which can then be displayed using the + :command:`feature_summary()` command. This command can be called either + directly within the corresponding :ref:`Find module <Find Modules>` or in + the project that uses the module after invoking the :command:`find_package()` + call. The features for which information can be set are determined + automatically after the :command:`find_package()` command. + + .. rubric:: The arguments are: + + ``<PackageName>`` + The name of the package. For example, as specified in the + :command:`find_package(<PackageName>)` argument. + + ``PROPERTIES`` + Specifies the properties to set: + + ``URL <url>`` + This should be the homepage of the package, or something similar. + Ideally this is set already directly in the + :ref:`Find module <Find Modules>`. + + ``DESCRIPTION <description>`` + A short description what that package is, at most one sentence. + Ideally this is set already directly in the + :ref:`Find module <Find Modules>`. + + ``TYPE <type>`` + What type of dependency has the using project on that package. + + Default ``<type>`` is ``OPTIONAL``. In this case it is a package + which can be used by the project when available at buildtime, but the + project also works without it. + + ``RECOMMENDED`` package type is similar to ``OPTIONAL``, i.e. the + project will build if the package is not present, but the + functionality of the resulting binaries will be severely limited. If + a ``REQUIRED`` package is not available at buildtime, the project may + not even build. This can be combined with the + :command:`feature_summary(FATAL_ON_MISSING_REQUIRED_PACKAGES)` command + option. + + Last, a ``RUNTIME`` package is a package which is actually not used + at all during the build, but which is required for actually running + the resulting binaries. So if such a package is missing, the project + can still be built, but it may not work later on. + + If ``set_package_properties()`` is called multiple times for the same + package with different TYPEs, the ``TYPE`` is only changed to higher + TYPEs (``RUNTIME < OPTIONAL < RECOMMENDED < REQUIRED``), lower TYPEs + are ignored. The ``TYPE`` property is project-specific, so it cannot + be set by the :ref:`Find module <Find Modules>`, but must be set in + the project. + + The accepted types can be changed by setting the + :variable:`FeatureSummary_PKG_TYPES` global property. + + ``PURPOSE <purpose>`` + This describes which features this package enables in the project, + i.e. it tells the user what functionality they get in the resulting + binaries. If ``set_package_properties()`` is called multiple times + for a package, all ``PURPOSE`` properties are appended to a list of + purposes of the package in the project. As the ``TYPE`` property, + also the ``PURPOSE`` property is project-specific, so it cannot be + set by the :ref:`Find module <Find Modules>`, but must be set in the + project. + +Adding Feature Info +""""""""""""""""""" + +.. command:: add_feature_info + + Adds feature information: + + .. code-block:: cmake + + add_feature_info(<name> <condition> <description>) + + Use this command to add information about a feature identified with a given + ``<name>``. + + .. rubric:: The arguments are: + + ``<name>`` + Identification name for a feature being added. + + ``<condition>`` + Specifies the conditions that determine whether this feature is enabled + or disabled. + + The ``<condition>`` argument can be: + + * A single condition (such as a variable name). + + * .. versionadded:: 3.8 + A :ref:`semicolon-separated list <CMake Language Lists>` of multiple + conditions. + + * .. versionadded:: 4.0 + A full :ref:`Condition Syntax` as used in an ``if(<condition>)`` + clause. See policy :policy:`CMP0183`. This enables using entire + condition syntax (such as grouping conditions with parens and + similar). + + ``<description>`` + A text describing the feature. This information can be displayed using + :command:`feature_summary()` for ``ENABLED_FEATURES`` and + ``DISABLED_FEATURES`` respectively. + +Deprecated Commands +""""""""""""""""""" + +The following legacy and deprecated commands are provided for backward +compatibility with previous CMake versions: + +.. command:: set_package_info + + .. deprecated:: 3.8 + Use the :command:`set_package_properties`, and :command:`add_feature_info` + commands instead. + + Sets up information about the specified package, which can then be displayed + via :command:`feature_summary()`: + + .. code-block:: cmake + + set_package_info(<PackageName> <description> [<url> [<purpose>]]) + + ``<PackageName>`` + Name of the package. + + ``<description>`` + A short description of the package. + + ``<url>`` + Homepage of the package. + + ``<purpose>`` + The purpose of the package. + + This command can be used either directly in the + :ref:`Find module <Find Modules>` or in the project which uses the + ``FeatureSummary`` module after the :command:`find_package()` call. The + features for which information can be set are added automatically by the + ``find_package()`` command. + +.. command:: set_feature_info + + .. deprecated:: 3.8 + + Sets feature info for a package: + + .. code-block:: cmake + + set_feature_info(<name> <description> [<url>]) + + Does the same as: + + .. code-block:: cmake + + set_package_info(<name> <description> [<url>]) + +.. command:: print_enabled_features + + .. deprecated:: 3.8 + + Prints enabled features: + + .. code-block:: cmake + + print_enabled_features() + + Does the same as: + + .. code-block:: cmake + + feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:") + +.. command:: print_disabled_features + + .. deprecated:: 3.8 + + Prints disabled features: + + .. code-block:: cmake + + print_disabled_features() + + Does the same as: + + .. code-block:: cmake + + feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:") + +Examples +^^^^^^^^ + +Example: Appending Feature Summary to a File +"""""""""""""""""""""""""""""""""""""""""""" + +In the following example, the feature summary output will be appended to +a specified file instead of printing: + +.. code-block:: cmake + + include(FeatureSummary) + feature_summary(WHAT ALL FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND) + +Example: Storing Feature Summary in a Variable +"""""""""""""""""""""""""""""""""""""""""""""" + +In the following example, the feature summary of enabled features is stored +in a specified variable ``enabledFeaturesText``, including the ``QUIET`` +packages: + +.. code-block:: cmake + + include(FeatureSummary) + + feature_summary( + WHAT ENABLED_FEATURES + INCLUDE_QUIET_PACKAGES + DESCRIPTION "Enabled Features:" + VAR enabledFeaturesText + ) + + message(STATUS "${enabledFeaturesText}") + +Example: Adding a Custom Package Type +""""""""""""""""""""""""""""""""""""" + +In the following example a custom package type is added and printed only +the categories that are not empty: + +.. code-block:: cmake + + include(FeatureSummary) + + set_property(GLOBAL APPEND PROPERTY FeatureSummary_PKG_TYPES BUILD) + + find_package(FOO) + set_package_properties(FOO PROPERTIES TYPE BUILD) + + feature_summary( + WHAT BUILD_PACKAGES_FOUND + DESCRIPTION "Build tools found:" + QUIET_ON_EMPTY + ) + + feature_summary( + WHAT BUILD_PACKAGES_NOT_FOUND + DESCRIPTION "Build tools not found:" + QUIET_ON_EMPTY + ) + +Example: Setting Package Info +""""""""""""""""""""""""""""" + +Example for setting the info for a package: + +.. code-block:: cmake + + include(FeatureSummary) + + find_package(LibXml2) + set_package_properties( + LibXml2 + PROPERTIES + DESCRIPTION "XML library" + URL "http://xmlsoft.org" + ) + # or + set_package_properties( + LibXml2 + PROPERTIES + TYPE RECOMMENDED + PURPOSE "Enables HTML-import in MyWordProcessor" + ) + # or + set_package_properties( + LibXml2 + PROPERTIES + TYPE OPTIONAL + PURPOSE "Enables odt-export in MyWordProcessor" + ) + + find_package(DBUS) + set_package_properties( + DBUS + PROPERTIES + TYPE RUNTIME + PURPOSE "Necessary to disable the screensaver during a presentation" + ) + +Example: Printing Feature Summary +""""""""""""""""""""""""""""""""" + +In the following example, this module is used to output feature summary at +the end of the configuration. If any required package is not found, +processing stops with an error message at the end of the configuration +phase. + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.15) + project(Example) + + add_library(example example.c) + + include(FeatureSummary) + + find_package(CURL) + set_package_properties(CURL PROPERTIES TYPE REQUIRED) + target_link_libraries(example PRIVATE CURL::libcurl) + + find_package(LibXml2 QUIET) + set_package_properties(LibXml2 PROPERTIES TYPE RECOMMENDED) + if(LibXml2_FOUND) + target_link_libraries(example PRIVATE LibXml2::LibXml2) + endif() + + feature_summary( + WHAT ALL + INCLUDE_QUIET_PACKAGES + DESCRIPTION "Feature summary:" + FATAL_ON_MISSING_REQUIRED_PACKAGES + ) + +Examples: Setting Feature Info +"""""""""""""""""""""""""""""" + +Example for setting the info for a feature: + +.. code-block:: cmake + + include(FeatureSummary) + + option(WITH_FOO "Help for foo" ON) + + add_feature_info(Foo WITH_FOO "this feature provides very cool stuff") + +Example for setting feature info based on a list of conditions: + +.. code-block:: cmake + + include(FeatureSummary) + + option(WITH_FOO "Help for foo" ON) + option(WITH_BAR "Help for bar" OFF) + + add_feature_info( + FooBar + "WITH_FOO;NOT WITH_BAR" + "this feature is enabled when WITH_FOO is ON and WITH_BAR turned OFF" + ) + +In the next example feature info are set depending on a full condition +syntax. Unlike semicolon-separated list of conditions, this enables using +entire condition syntax as being the ``if`` clause argument: + +.. code-block:: cmake + + include(FeatureSummary) + + option(WITH_FOO "Help for foo" ON) + option(WITH_BAR "Help for bar" ON) + option(WITH_BAZ "Help for baz" OFF) + + add_feature_info( + FooBarBaz + "WITH_FOO AND (WITH_BAR OR WITH_BAZ)" + "this feature is enabled when the entire condition is true" + ) #]=======================================================================] get_property(_fsPkgTypeIsSet GLOBAL PROPERTY FeatureSummary_PKG_TYPES SET) @@ -105,15 +632,7 @@ set_property(GLOBAL PROPERTY FeatureSummary_DEFAULT_PKG_TYPE OPTIONAL) endif() -#[=======================================================================[.rst: - -Functions -^^^^^^^^^ - -#]=======================================================================] - function(_FS_GET_FEATURE_SUMMARY _property _var _includeQuiet) - get_property(_fsPkgTypes GLOBAL PROPERTY FeatureSummary_PKG_TYPES) get_property(_fsDefaultPkgType GLOBAL PROPERTY FeatureSummary_DEFAULT_PKG_TYPE) @@ -208,155 +727,6 @@ set(${_var} "${_currentFeatureText}" PARENT_SCOPE) endfunction() - -#[=======================================================================[.rst: -.. command:: feature_summary - - .. code-block:: cmake - - feature_summary([FILENAME <file>] - [APPEND] - [VAR <variable_name>] - [INCLUDE_QUIET_PACKAGES] - [FATAL_ON_MISSING_REQUIRED_PACKAGES] - [DESCRIPTION <description> | DEFAULT_DESCRIPTION] - [QUIET_ON_EMPTY] - WHAT (ALL - | PACKAGES_FOUND | PACKAGES_NOT_FOUND - | <TYPE>_PACKAGES_FOUND | <TYPE>_PACKAGES_NOT_FOUND - | ENABLED_FEATURES | DISABLED_FEATURES) - ) - - This function can be used to print information about - enabled or disabled packages and features of a project. By default, - only the names of the features/packages will be printed and their - required version when one was specified. Use - :command:`set_package_properties()` to add more useful information, like e.g. - a homepage URL for the respective package or their purpose in the project. - - The options are: - - ``WHAT`` - This is the only mandatory option. It specifies what information will be - printed: - - ``ALL`` - Print everything. - ``ENABLED_FEATURES`` - The list of all features which are enabled. - ``DISABLED_FEATURES`` - The list of all features which are disabled. - ``PACKAGES_FOUND`` - The list of all packages which have been found. - ``PACKAGES_NOT_FOUND`` - The list of all packages which have not been found. - - For each package type ``<TYPE>`` defined by the - :variable:`FeatureSummary_PKG_TYPES` global property, the following - information can also be used: - - ``<TYPE>_PACKAGES_FOUND`` - The list of only packages of type ``<TYPE>`` which have been found. - ``<TYPE>_PACKAGES_NOT_FOUND`` - The list of only packages of type ``<TYPE>`` which have not been found. - - .. versionchanged:: 3.1 - The ``WHAT`` option is now a multi-value keyword, so that these values can - be combined, with the exception of the ``ALL`` value, in order to - customize the output. For example: - - .. code-block:: cmake - - feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES) - - ``FILENAME <file>`` - If this option is given, the information is printed into this file instead - of the terminal. Relative ``<file>`` path is interpreted as being relative - to the current source directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`). - - ``APPEND`` - If this option is given, the output is appended to the ``<file>`` provided - by the ``FILENAME`` option, otherwise the file is overwritten if it already - exists. - - ``VAR <variable_name>`` - If this option is given, the information is stored into the specified - variable ``<variable_name>`` instead of the terminal. - - ``DESCRIPTION <description>`` - A description or headline which will be printed above the actual content. - Without this option, if only one package type was requested, no title is - printed, unless a custom string is explicitly set using this option or - ``DEFAULT_DESCRIPTION`` option is used that outputs a default title for the - requested type. - - ``DEFAULT_DESCRIPTION`` - .. versionadded:: 3.9 - - The default description or headline to be printed above the content as - opposed to the customizable ``DESCRIPTION <description>``. - - ``INCLUDE_QUIET_PACKAGES`` - If this option is given, packages which have been searched with - :command:`find_package(... QUIET)` will also be listed. By default they are - skipped. - - ``FATAL_ON_MISSING_REQUIRED_PACKAGES`` - If this option is given, CMake will abort with fatal error if a package - which is marked as one of the package types listed in the - :variable:`FeatureSummary_REQUIRED_PKG_TYPES` global property has not been - found. - - The :variable:`FeatureSummary_DEFAULT_PKG_TYPE` global property can be - modified to change the default package type assigned when not explicitly - assigned by the user. - - ``QUIET_ON_EMPTY`` - .. versionadded:: 3.8 - - If this option is given, when only one package type was requested, and no - packages belonging to that category were found, then no output (including - the ``DESCRIPTION``) is printed nor added to the ``FILENAME``, or the - ``VAR`` variable. - - Example 1, append everything to a file: - - .. code-block:: cmake - - include(FeatureSummary) - feature_summary(WHAT ALL - FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND) - - Example 2, print the enabled features into the variable - ``enabledFeaturesText``, including the ``QUIET`` packages: - - .. code-block:: cmake - - include(FeatureSummary) - feature_summary(WHAT ENABLED_FEATURES - INCLUDE_QUIET_PACKAGES - DESCRIPTION "Enabled Features:" - VAR enabledFeaturesText) - message(STATUS "${enabledFeaturesText}") - - Example 3, add custom package type and print only the categories that are not - empty: - - .. code-block:: cmake - - include(FeatureSummary) - set_property(GLOBAL APPEND PROPERTY FeatureSummary_PKG_TYPES BUILD) - find_package(FOO) - set_package_properties(FOO PROPERTIES TYPE BUILD) - feature_summary(WHAT BUILD_PACKAGES_FOUND - DESCRIPTION "Build tools found:" - QUIET_ON_EMPTY) - feature_summary(WHAT BUILD_PACKAGES_NOT_FOUND - DESCRIPTION "Build tools not found:" - QUIET_ON_EMPTY) - -#]=======================================================================] - function(FEATURE_SUMMARY) # cmake_parse_arguments(<prefix> <options> <one_value_keywords> <multi_value_keywords> args...) set(options APPEND @@ -498,93 +868,8 @@ if(requiredPackagesNotFound AND _FS_FATAL_ON_MISSING_REQUIRED_PACKAGES) message(FATAL_ERROR "feature_summary() Error: REQUIRED package(s) are missing, aborting CMake run.") endif() - endfunction() -#[=======================================================================[.rst: -.. command:: set_package_properties - - .. code-block:: cmake - - set_package_properties(<name> PROPERTIES - [URL <url>] - [DESCRIPTION <description>] - [TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED)] - [PURPOSE <purpose>] - ) - - Use this function to configure and provide information about the package named - ``<name>``, which can then be displayed using the - :command:`feature_summary()` command. This can be performed either directly - within the corresponding :ref:`Find module <Find Modules>` or in the project - that uses the module after invoking the :command:`find_package()` call. The - features for which information can be set are determined automatically after - the :command:`find_package()` command. - - ``URL <url>`` - This should be the homepage of the package, or something similar. - Ideally this is set already directly in the - :ref:`Find module <Find Modules>`. - - ``DESCRIPTION <description>`` - A short description what that package is, at most one sentence. - Ideally this is set already directly in the - :ref:`Find module <Find Modules>`. - - ``TYPE <type>`` - What type of dependency has the using project on that package. - Default is ``OPTIONAL``. In this case it is a package which can be used - by the project when available at buildtime, but it also work without. - ``RECOMMENDED`` is similar to ``OPTIONAL``, i.e. the project will build if - the package is not present, but the functionality of the resulting - binaries will be severely limited. If a ``REQUIRED`` package is not - available at buildtime, the project may not even build. This can be - combined with the - :command:`feature_summary(FATAL_ON_MISSING_REQUIRED_PACKAGES)` command - option. Last, a ``RUNTIME`` package is a package which is actually not used - at all during the build, but which is required for actually running the - resulting binaries. So if such a package is - missing, the project can still be built, but it may not work later on. - If ``set_package_properties()`` is called multiple times for the same - package with different TYPEs, the ``TYPE`` is only changed to higher - TYPEs (``RUNTIME < OPTIONAL < RECOMMENDED < REQUIRED``), lower TYPEs are - ignored. The ``TYPE`` property is project-specific, so it cannot be set - by the :ref:`Find module <Find Modules>`, but must be set in the project. - The accepted types can be changed by setting the - :variable:`FeatureSummary_PKG_TYPES` global property. - - ``PURPOSE <purpose>`` - This describes which features this package enables in the - project, i.e. it tells the user what functionality they get in the - resulting binaries. If ``set_package_properties()`` is called multiple - times for a package, all ``PURPOSE`` properties are appended to a list of - purposes of the package in the project. As the ``TYPE`` property, also - the ``PURPOSE`` property is project-specific, so it cannot be set by the - :ref:`Find module <Find Modules>`, but must be set in the project. - - Example for setting the info for a package: - - .. code-block:: cmake - - include(FeatureSummary) - find_package(LibXml2) - set_package_properties(LibXml2 PROPERTIES - DESCRIPTION "XML library" - URL "http://xmlsoft.org") - # or - set_package_properties(LibXml2 PROPERTIES - TYPE RECOMMENDED - PURPOSE "Enables HTML-import in MyWordProcessor") - # or - set_package_properties(LibXml2 PROPERTIES - TYPE OPTIONAL - PURPOSE "Enables odt-export in MyWordProcessor") - - find_package(DBUS) - set_package_properties(DBUS PROPERTIES - TYPE RUNTIME - PURPOSE "Necessary to disable the screensaver during a presentation") -#]=======================================================================] function(SET_PACKAGE_PROPERTIES _name _props) if(NOT "${_props}" STREQUAL "PROPERTIES") message(FATAL_ERROR "PROPERTIES keyword is missing in SET_PACKAGE_PROPERTIES() call.") @@ -609,7 +894,6 @@ set_property(GLOBAL PROPERTY _CMAKE_${_name}_DESCRIPTION "${_SPP_DESCRIPTION}" ) endif() - if(_SPP_URL) get_property(_info GLOBAL PROPERTY _CMAKE_${_name}_URL) if(_info AND NOT "${_info}" STREQUAL "${_SPP_URL}") @@ -619,7 +903,6 @@ set_property(GLOBAL PROPERTY _CMAKE_${_name}_URL "${_SPP_URL}" ) endif() - # handle the PURPOSE: use APPEND, since there can be multiple purposes for one package inside a project if(_SPP_PURPOSE) set_property(GLOBAL APPEND PROPERTY _CMAKE_${_name}_PURPOSE "${_SPP_PURPOSE}" ) @@ -648,68 +931,8 @@ set_property(GLOBAL PROPERTY _CMAKE_${_name}_TYPE "${_SPP_TYPE}" ) endif() endif() - endfunction() -#[=======================================================================[.rst: -.. command:: add_feature_info - - .. code-block:: cmake - - add_feature_info(<name> <enabled> <description>) - - Use this function to add information about a feature identified with a given - ``<name>``. The ``<enabled>`` contains whether this feature is enabled or - not. It can be a variable or a list of conditions. - ``<description>`` is a text describing the feature. The information can - be displayed using :command:`feature_summary()` for ``ENABLED_FEATURES`` and - ``DISABLED_FEATURES`` respectively. - - .. versionchanged:: 3.8 - ``<enabled>`` can be a list of conditions. - - .. versionchanged:: 4.0 - Full :ref:`Condition Syntax` is now supported for ``<enabled>``. - See policy :policy:`CMP0183`. - - Example for setting the info for a feature: - - .. code-block:: cmake - - include(FeatureSummary) - - option(WITH_FOO "Help for foo" ON) - add_feature_info(Foo WITH_FOO "this feature provides very cool stuff") - - Example for setting feature info based on a list of conditions: - - .. code-block:: cmake - - option(WITH_FOO "Help for foo" ON) - option(WITH_BAR "Help for bar" OFF) - add_feature_info( - FooBar - "WITH_FOO;NOT WITH_BAR" - "this feature is enabled when WITH_FOO is ON and WITH_BAR turned OFF" - ) - - Example for setting feature info depending on a full condition syntax: - - Unlike semicolon-separated list of conditions, this enables using entire - condition syntax as being the ``if`` clause argument, such as grouping - conditions with parens and similar. - - .. code-block:: cmake - - option(WITH_FOO "Help for foo" ON) - option(WITH_BAR "Help for bar" ON) - option(WITH_BAZ "Help for baz" OFF) - add_feature_info( - FooBarBaz - "WITH_FOO AND (WITH_BAR OR WITH_BAZ)" - "this feature is enabled when the entire condition is true" - ) -#]=======================================================================] function(ADD_FEATURE_INFO _name _depends _desc) cmake_policy(GET CMP0183 _CDO_CMP0183 PARENT_SCOPE # undocumented, do not use outside of CMake @@ -749,34 +972,8 @@ unset(_CDO_CMP0183) endfunction() - # The stuff below is only kept for compatibility -#[=======================================================================[.rst: -Deprecated Functions -^^^^^^^^^^^^^^^^^^^^ - -The following legacy and deprecated functions are provided for backward -compatibility with previous CMake versions: - -.. command:: set_package_info - - .. deprecated:: 3.8 - - .. code-block:: cmake - - set_package_info(<name> <description> [ <url> [<purpose>] ]) - - Set up information about the package ``<name>``, which can then be displayed - via :command:`feature_summary()`. This can be done either directly in the - :ref:`Find module <Find Modules>` or in the project which uses the - ``FeatureSummary`` module after the :command:`find_package()` call. The - features for which information can be set are added automatically by the - ``find_package()`` command. - - This function is deprecated. Use the :command:`set_package_properties()`, and - :command:`add_feature_info()` functions instead. -#]=======================================================================] function(SET_PACKAGE_INFO _name _desc) message(DEPRECATION "SET_PACKAGE_INFO is deprecated. Use SET_PACKAGE_PROPERTIES instead.") unset(_url) @@ -796,62 +993,17 @@ endif() endfunction() -#[=======================================================================[.rst: -.. command:: set_feature_info - - .. deprecated:: 3.8 - - .. code-block:: cmake - - set_feature_info(<name> <description> [<url>]) - - Does the same as: - - .. code-block:: cmake - - set_package_info(<name> <description> [<url>]) -#]=======================================================================] function(SET_FEATURE_INFO) message(DEPRECATION "SET_FEATURE_INFO is deprecated. Use ADD_FEATURE_INFO instead.") set_package_info(${ARGN}) endfunction() -#[=======================================================================[.rst: -.. command:: print_enabled_features - - .. deprecated:: 3.8 - - .. code-block:: cmake - - print_enabled_features() - - Does the same as: - - .. code-block:: cmake - - feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:") -#]=======================================================================] function(PRINT_ENABLED_FEATURES) message(DEPRECATION "PRINT_ENABLED_FEATURES is deprecated. Use feature_summary(WHAT ENABLED_FEATURES DESCRIPTION \"Enabled features:\")") feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:") endfunction() -#[=======================================================================[.rst: -.. command:: print_disabled_features - - .. deprecated:: 3.8 - - .. code-block:: cmake - - print_disabled_features() - - Does the same as: - - .. code-block:: cmake - - feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:") -#]=======================================================================] function(PRINT_DISABLED_FEATURES) message(DEPRECATION "PRINT_DISABLED_FEATURES is deprecated. Use feature_summary(WHAT DISABLED_FEATURES DESCRIPTION \"Disabled features:\")")
diff --git a/Modules/FetchContent.cmake b/Modules/FetchContent.cmake index 2088549..80152f6 100644 --- a/Modules/FetchContent.cmake +++ b/Modules/FetchContent.cmake
@@ -11,6 +11,15 @@ .. contents:: +This module provides commands to populate content at configure time or as +part of the calling script. + +Load this module in CMake with: + +.. code-block:: cmake + + include(FetchContent) + .. note:: The :guide:`Using Dependencies Guide` provides a high-level introduction to this general topic. It provides a broader overview of where the ``FetchContent`` module fits into the bigger picture, @@ -111,9 +120,10 @@ The ``<contentOptions>`` can be any of the download, update, or patch options that the :command:`ExternalProject_Add` command understands. The configure, build, install, and test steps are explicitly disabled, so options related - to those steps will be ignored. The ``SOURCE_SUBDIR`` option is an - exception, see :command:`FetchContent_MakeAvailable` for details on how that - affects behavior. + to those steps are prohibited and will be discarded if given. + The ``SOURCE_SUBDIR`` option is an exception, see + :command:`FetchContent_MakeAvailable` for details on how that affects + behavior. .. versionchanged:: 3.30 When policy :policy:`CMP0168` is set to ``NEW``, some output-related and @@ -387,17 +397,20 @@ FetchContent_Declare(other ...) FetchContent_MakeAvailable(uses_other other) - Note that :variable:`CMAKE_VERIFY_INTERFACE_HEADER_SETS` is explicitly set - to false upon entry to ``FetchContent_MakeAvailable()``, and is restored to - its original value before the command returns. Developers typically only + Note that :variable:`CMAKE_VERIFY_INTERFACE_HEADER_SETS` and + :variable:`CMAKE_VERIFY_PRIVATE_HEADER_SETS` are explicitly set to false + upon entry to ``FetchContent_MakeAvailable()``, and are restored to their + original values before the command returns. Developers typically only want to verify header sets from the main project, not those from any dependencies. This local manipulation of the - :variable:`CMAKE_VERIFY_INTERFACE_HEADER_SETS` variable provides that + :variable:`CMAKE_VERIFY_INTERFACE_HEADER_SETS` and + :variable:`CMAKE_VERIFY_PRIVATE_HEADER_SETS` variables provides that intuitive behavior. You can use variables like :variable:`CMAKE_PROJECT_INCLUDE` or :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` to turn verification back on for all or some dependencies. You can also set the - :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` property of individual targets. + :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` and + :prop_tgt:`VERIFY_PRIVATE_HEADER_SETS` properties of individual targets. .. command:: FetchContent_Populate @@ -1128,7 +1141,7 @@ # FetchContent_MakeAvailable() implementation details are excluded for # backward compatibility reasons (see just after the endblock()). block(SCOPE_FOR POLICIES) -cmake_policy(VERSION 3.29) +cmake_policy(VERSION 4.1) include(${CMAKE_CURRENT_LIST_DIR}/ExternalProject/shared_internal_commands.cmake) @@ -1876,9 +1889,9 @@ # Pass through things we've already detected in the main project to avoid # paying the cost of redetecting them again in ExternalProject_Add() set(GIT_EXECUTABLE [==[${GIT_EXECUTABLE}]==]) -set(GIT_VERSION_STRING [==[${GIT_VERSION_STRING}]==]) +set(Git_VERSION [==[${Git_VERSION}]==]) set_property(GLOBAL PROPERTY _CMAKE_FindGit_GIT_EXECUTABLE_VERSION - [==[${GIT_EXECUTABLE};${GIT_VERSION_STRING}]==] + [==[${GIT_EXECUTABLE};${Git_VERSION}]==] ) ") endif() @@ -2230,12 +2243,14 @@ # calls will be available to the caller. macro(FetchContent_MakeAvailable) - # We must append an item, even if the variable is unset, so prefix its value. - # We will strip that prefix when we pop the value at the end of the macro. + # We must append these, even if the variables are unset, so prefix the values. + # We will strip that prefix when we pop the values at the end of the macro. list(APPEND __cmake_fcCurrentVarsStack "__fcprefix__${CMAKE_VERIFY_INTERFACE_HEADER_SETS}" + "__fcprefix__${CMAKE_VERIFY_PRIVATE_HEADER_SETS}" ) set(CMAKE_VERIFY_INTERFACE_HEADER_SETS FALSE) + set(CMAKE_VERIFY_PRIVATE_HEADER_SETS FALSE) get_property(__cmake_providerCommand GLOBAL PROPERTY __FETCHCONTENT_MAKEAVAILABLE_SERIAL_PROVIDER @@ -2443,18 +2458,30 @@ endforeach() # Prefix will be "__fcprefix__" - list(POP_BACK __cmake_fcCurrentVarsStack __cmake_original_verify_setting) - string(SUBSTRING "${__cmake_original_verify_setting}" - 12 -1 __cmake_original_verify_setting + list(POP_BACK __cmake_fcCurrentVarsStack + __cmake_original_verify_private_setting + __cmake_original_verify_interface_setting ) - set(CMAKE_VERIFY_INTERFACE_HEADER_SETS ${__cmake_original_verify_setting}) + string(SUBSTRING "${__cmake_original_verify_private_setting}" + 12 -1 __cmake_original_verify_private_setting + ) + string(SUBSTRING "${__cmake_original_verify_interface_setting}" + 12 -1 __cmake_original_verify_interface_setting + ) + set(CMAKE_VERIFY_PRIVATE_HEADER_SETS + ${__cmake_original_verify_private_setting} + ) + set(CMAKE_VERIFY_INTERFACE_HEADER_SETS + ${__cmake_original_verify_interface_setting} + ) # clear local variables to prevent leaking into the caller's scope unset(__cmake_contentName) unset(__cmake_contentNameLower) unset(__cmake_contentNameUpper) unset(__cmake_providerCommand) - unset(__cmake_original_verify_setting) + unset(__cmake_original_verify_interface_setting) + unset(__cmake_original_verify_private_setting) endmacro()
diff --git a/Modules/FindALSA.cmake b/Modules/FindALSA.cmake index 1198abe..7a5edce 100644 --- a/Modules/FindALSA.cmake +++ b/Modules/FindALSA.cmake
@@ -5,7 +5,11 @@ FindALSA -------- -Finds the Advanced Linux Sound Architecture (ALSA) library (``asound``). +Finds the Advanced Linux Sound Architecture (ALSA) library (``asound``): + +.. code-block:: cmake + + find_package(ALSA [<version>] [...]) Imported Targets ^^^^^^^^^^^^^^^^ @@ -24,7 +28,13 @@ This module defines the following variables: ``ALSA_FOUND`` - Boolean indicating whether the ALSA library is found. + Boolean indicating whether the (requested version of) ALSA library was + found. + +``ALSA_VERSION`` + .. versionadded:: 4.2 + + The version of ALSA found. ``ALSA_LIBRARIES`` List of libraries needed for linking to use ALSA library. @@ -43,6 +53,17 @@ ``ALSA_LIBRARY`` The absolute path of the asound library. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``ALSA_VERSION_STRING`` + .. deprecated:: 4.2 + Superseded by the ``ALSA_VERSION``. + + The version of ALSA found. + Examples ^^^^^^^^ @@ -68,14 +89,15 @@ if(ALSA_INCLUDE_DIR AND EXISTS "${ALSA_INCLUDE_DIR}/alsa/version.h") file(STRINGS "${ALSA_INCLUDE_DIR}/alsa/version.h" alsa_version_str REGEX "^#define[\t ]+SND_LIB_VERSION_STR[\t ]+\".*\"") - string(REGEX REPLACE "^.*SND_LIB_VERSION_STR[\t ]+\"([^\"]*)\".*$" "\\1" ALSA_VERSION_STRING "${alsa_version_str}") + string(REGEX REPLACE "^.*SND_LIB_VERSION_STR[\t ]+\"([^\"]*)\".*$" "\\1" ALSA_VERSION "${alsa_version_str}") + set(ALSA_VERSION_STRING "${ALSA_VERSION}") unset(alsa_version_str) endif() include(FindPackageHandleStandardArgs) find_package_handle_standard_args(ALSA REQUIRED_VARS ALSA_LIBRARY ALSA_INCLUDE_DIR - VERSION_VAR ALSA_VERSION_STRING) + VERSION_VAR ALSA_VERSION) if(ALSA_FOUND) set( ALSA_LIBRARIES ${ALSA_LIBRARY} )
diff --git a/Modules/FindASPELL.cmake b/Modules/FindASPELL.cmake index 2c5cb93..5d612cd 100644 --- a/Modules/FindASPELL.cmake +++ b/Modules/FindASPELL.cmake
@@ -5,12 +5,23 @@ FindASPELL ---------- -Finds the GNU Aspell spell checker library. +Finds the GNU Aspell spell checker library: + +.. code-block:: cmake + + find_package(ASPELL [<version>] [COMPONENTS <components>] [...]) Components ^^^^^^^^^^ -This module supports the following components: +This module supports optional components which can be specified using the +:command:`find_package` command: + +.. code-block:: cmake + + find_package(ASPELL [COMPONENTS <components>...]) + +Supported components include: ``ASPELL`` .. versionadded:: 4.1 @@ -22,13 +33,7 @@ Finds the Aspell command-line interactive spell checker executable. -Components can be specified using the standard CMake syntax: - -.. code-block:: cmake - - find_package(ASPELL [COMPONENTS <components>...]) - -If no ``COMPONENTS`` are specified, the module searches for both the ``ASPELL`` +If no components are specified, the module searches for both the ``ASPELL`` and ``Executable`` components by default. Imported Targets @@ -55,7 +60,8 @@ This module defines the following variables: ``ASPELL_FOUND`` - Boolean indicating whether the requested Aspell components have been found. + Boolean indicating whether (the requested version of) Aspell and all + requested components were found. ``ASPELL_VERSION`` .. versionadded:: 4.1
diff --git a/Modules/FindAVIFile.cmake b/Modules/FindAVIFile.cmake index d3387ea..b6cfe7e 100644 --- a/Modules/FindAVIFile.cmake +++ b/Modules/FindAVIFile.cmake
@@ -5,7 +5,11 @@ FindAVIFile ----------- -Finds `AVIFile <https://avifile.sourceforge.net/>`_ library and include paths. +Finds `AVIFile <https://avifile.sourceforge.net/>`_ library and include paths: + +.. code-block:: cmake + + find_package(AVIFile [...]) AVIFile is a set of libraries for i386 machines to use various AVI codecs. Support is limited beyond Linux. Windows provides native AVI support, and so @@ -17,29 +21,58 @@ This module defines the following variables: ``AVIFile_FOUND`` - True if AVIFile is found. For backward compatibility, the ``AVIFILE_FOUND`` - variable is also set to the same value. + .. versionadded:: 3.3 + + Boolean indicating whether AVIFile was found. + ``AVIFILE_LIBRARIES`` The libraries to link against. + ``AVIFILE_DEFINITIONS`` Definitions to use when compiling. Cache Variables ^^^^^^^^^^^^^^^ -The following cache variables may be also set: +The following cache variables may also be set: ``AVIFILE_INCLUDE_DIR`` Directory containing ``avifile.h`` and other AVIFile headers. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``AVIFILE_FOUND`` + .. deprecated:: 4.2 + Use ``AVIFile_FOUND``, which has the same value. + + Boolean indicating whether AVIFile was found. + Examples ^^^^^^^^ -Finding AVIFile: +Finding AVIFile and conditionally creating an interface :ref:`Imported Target +<Imported Targets>` that encapsulates its usage requirements for linking to a +project target: .. code-block:: cmake find_package(AVIFile) + + if(AVIFile_FOUND AND NOT TARGET AVIFile::AVIFile) + add_library(AVIFile::AVIFile INTERFACE IMPORTED) + set_target_properties( + AVIFile::AVIFile + PROPERTIES + INTERFACE_INCLUDE_DIRECTORIES "${AVIFILE_INCLUDE_DIR}" + INTERFACE_LINK_LIBRARIES "${AVIFILE_LIBRARIES}" + INTERFACE_COMPILE_DEFINITIONS "${AVIFILE_DEFINITIONS}" + ) + endif() + + target_link_libraries(example PRIVATE AVIFile::AVIFile) #]=======================================================================] if (UNIX) @@ -50,7 +83,10 @@ endif () include(FindPackageHandleStandardArgs) -find_package_handle_standard_args(AVIFile DEFAULT_MSG AVIFILE_INCLUDE_DIR AVIFILE_AVIPLAY_LIBRARY) +find_package_handle_standard_args( + AVIFile + REQUIRED_VARS AVIFILE_AVIPLAY_LIBRARY AVIFILE_INCLUDE_DIR +) if (AVIFile_FOUND) set(AVIFILE_LIBRARIES ${AVIFILE_AVIPLAY_LIBRARY})
diff --git a/Modules/FindArmadillo.cmake b/Modules/FindArmadillo.cmake index f185f10..901ea22 100644 --- a/Modules/FindArmadillo.cmake +++ b/Modules/FindArmadillo.cmake
@@ -5,8 +5,13 @@ FindArmadillo ------------- -Finds the Armadillo C++ library. Armadillo is a library for linear algebra and -scientific computing. +Finds the Armadillo C++ library: + +.. code-block:: cmake + + find_package(Armadillo [<version>] [...]) + +Armadillo is a library for linear algebra and scientific computing. .. versionadded:: 3.18 Support for linking wrapped libraries directly (see the @@ -16,30 +21,76 @@ Result Variables ^^^^^^^^^^^^^^^^ -This module sets the following variables: +This module defines the following variables: ``Armadillo_FOUND`` - Set to true if the library is found. For backward compatibility, the - ``ARMADILLO_FOUND`` variable is also set to the same value. + .. versionadded:: 3.3 + + Boolean indicating whether the (requested version of) Armadillo library + was found. + +``Armadillo_VERSION`` + .. versionadded:: 4.2 + + The version of Armadillo found (e.g., ``14.90.0``). + +``Armadillo_VERSION_NAME`` + .. versionadded:: 4.2 + + The version name of Armadillo found (e.g., ``Antipodean Antileech``). + ``ARMADILLO_INCLUDE_DIRS`` List of required include directories. + ``ARMADILLO_LIBRARIES`` List of libraries to be linked. + +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``ARMADILLO_FOUND`` + .. deprecated:: 4.2 + Use ``Armadillo_FOUND``, which has the same value. + + Boolean indicating whether the (requested version of) Armadillo library + was found. + ``ARMADILLO_VERSION_STRING`` - Version as a string (ex: ``1.0.4``). + .. deprecated:: 4.2 + Superseded by the ``Armadillo_VERSION``. + + The version of Armadillo found. + ``ARMADILLO_VERSION_MAJOR`` + .. deprecated:: 4.2 + Superseded by the ``Armadillo_VERSION``. + Major version number. + ``ARMADILLO_VERSION_MINOR`` + .. deprecated:: 4.2 + Superseded by the ``Armadillo_VERSION``. + Minor version number. + ``ARMADILLO_VERSION_PATCH`` + .. deprecated:: 4.2 + Superseded by the ``Armadillo_VERSION``. + Patch version number. + ``ARMADILLO_VERSION_NAME`` - Name of the version (ex: ``Antipodean Antileech``). + .. deprecated:: 4.2 + Superseded by the ``Armadillo_VERSION_NAME``. + + The version name of Armadillo found (e.g., ``Antipodean Antileech``). Examples ^^^^^^^^ -Using Armadillo: +Finding Armadillo and creating an imported target: .. code-block:: cmake @@ -79,10 +130,9 @@ set(ARMADILLO_VERSION_MAJOR 0) set(ARMADILLO_VERSION_MINOR 0) set(ARMADILLO_VERSION_PATCH 0) - set(ARMADILLO_VERSION_NAME "EARLY RELEASE") + set(Armadillo_VERSION_NAME "EARLY RELEASE") if(EXISTS "${ARMADILLO_INCLUDE_DIR}/armadillo_bits/arma_version.hpp") - # Read and parse armdillo version header file for version number file(STRINGS "${ARMADILLO_INCLUDE_DIR}/armadillo_bits/arma_version.hpp" _ARMA_HEADER_CONTENTS REGEX "#define ARMA_VERSION_[A-Z]+ ") string(REGEX REPLACE ".*#define ARMA_VERSION_MAJOR ([0-9]+).*" "\\1" ARMADILLO_VERSION_MAJOR "${_ARMA_HEADER_CONTENTS}") @@ -90,11 +140,13 @@ string(REGEX REPLACE ".*#define ARMA_VERSION_PATCH ([0-9]+).*" "\\1" ARMADILLO_VERSION_PATCH "${_ARMA_HEADER_CONTENTS}") # WARNING: The number of spaces before the version name is not one. - string(REGEX REPLACE ".*#define ARMA_VERSION_NAME\ +\"([0-9a-zA-Z\ _-]+)\".*" "\\1" ARMADILLO_VERSION_NAME "${_ARMA_HEADER_CONTENTS}") + string(REGEX REPLACE ".*#define ARMA_VERSION_NAME\ +\"([0-9a-zA-Z\ _-]+)\".*" "\\1" Armadillo_VERSION_NAME "${_ARMA_HEADER_CONTENTS}") + set(ARMADILLO_VERSION_NAME "${Armadillo_VERSION_NAME}") endif() - set(ARMADILLO_VERSION_STRING "${ARMADILLO_VERSION_MAJOR}.${ARMADILLO_VERSION_MINOR}.${ARMADILLO_VERSION_PATCH}") + set(Armadillo_VERSION "${ARMADILLO_VERSION_MAJOR}.${ARMADILLO_VERSION_MINOR}.${ARMADILLO_VERSION_PATCH}") + set(ARMADILLO_VERSION_STRING "${Armadillo_VERSION}") endif () if(EXISTS "${ARMADILLO_INCLUDE_DIR}/armadillo_bits/config.hpp") @@ -150,7 +202,7 @@ find_package_handle_standard_args(Armadillo REQUIRED_VARS ARMADILLO_INCLUDE_DIR ${_ARMA_REQUIRED_VARS} - VERSION_VAR ARMADILLO_VERSION_STRING) + VERSION_VAR Armadillo_VERSION) if (Armadillo_FOUND) set(ARMADILLO_INCLUDE_DIRS ${ARMADILLO_INCLUDE_DIR})
diff --git a/Modules/FindBISON.cmake b/Modules/FindBISON.cmake index ef76f6a..38ea407 100644 --- a/Modules/FindBISON.cmake +++ b/Modules/FindBISON.cmake
@@ -10,7 +10,7 @@ .. code-block:: cmake - find_package(BISON [<version>] ...) + find_package(BISON [<version>] [...]) Bison is a parser generator that replaced earlier Yacc (Yet Another Compiler-Compiler). On Unix-like systems, most common implementation is @@ -23,7 +23,7 @@ This module defines the following variables: ``BISON_FOUND`` - Boolean indicating whether (the requested version of) Bison is found. + Boolean indicating whether (the requested version of) Bison was found. ``BISON_VERSION`` The version of Bison found.
diff --git a/Modules/FindBLAS.cmake b/Modules/FindBLAS.cmake index 2b8a75a..9f986a7 100644 --- a/Modules/FindBLAS.cmake +++ b/Modules/FindBLAS.cmake
@@ -5,34 +5,67 @@ FindBLAS -------- -Find Basic Linear Algebra Subprograms (BLAS) library +Finds the installed Basic Linear Algebra Subprograms (BLAS) Fortran library, +which implements the `BLAS linear-algebra interface`_: -This module finds an installed Fortran library that implements the -`BLAS linear-algebra interface`_. +.. code-block:: cmake + + find_package(BLAS [...]) At least one of the ``C``, ``CXX``, or ``Fortran`` languages must be enabled. .. _`BLAS linear-algebra interface`: https://netlib.org/blas/ +Imported Targets +^^^^^^^^^^^^^^^^ + +This module provides the following :ref:`Imported Targets`: + +``BLAS::BLAS`` + .. versionadded:: 3.18 + + Target encapsulating the libraries and usage requirements to use BLAS, + available only if BLAS is found. + +Result Variables +^^^^^^^^^^^^^^^^ + +This module defines the following variables: + +``BLAS_FOUND`` + Boolean indicating whether the library implementing the BLAS interface + was found. +``BLAS_LINKER_FLAGS`` + Uncached list of required linker flags (excluding ``-l`` and ``-L``). +``BLAS_LIBRARIES`` + Uncached list of libraries (using full path name) to link against + to use BLAS (may be empty if compiler implicitly links BLAS). +``BLAS95_LIBRARIES`` + Uncached list of libraries (using full path name) to link against + to use BLAS95 interface. +``BLAS95_FOUND`` + Boolean indicating whether the library implementing the BLAS95 interface + was found. + Input Variables ^^^^^^^^^^^^^^^ The following variables may be set to influence this module's behavior: ``BLA_STATIC`` - if ``ON`` use static linkage + If ``ON``, the static linkage will be used. ``BLA_VENDOR`` Set to one of the :ref:`BLAS/LAPACK Vendors` to search for BLAS only from the specified vendor. If not set, all vendors are considered. ``BLA_F95`` - if ``ON`` tries to find the BLAS95 interfaces + If ``ON``, the module tries to find the BLAS95 interfaces. ``BLA_PREFER_PKGCONFIG`` .. versionadded:: 3.11 - if set ``pkg-config`` will be used to search for a BLAS library first + If set, ``pkg-config`` will be used to search for a BLAS library first and if one is found that is preferred ``BLA_PKGCONFIG_BLAS`` @@ -69,41 +102,13 @@ This is currently only supported by NVIDIA NVPL. -Imported Targets -^^^^^^^^^^^^^^^^ - -This module defines the following :prop_tgt:`IMPORTED` targets: - -``BLAS::BLAS`` - .. versionadded:: 3.18 - - The libraries to use for BLAS, if found. - -Result Variables -^^^^^^^^^^^^^^^^ - -This module defines the following variables: - -``BLAS_FOUND`` - library implementing the BLAS interface is found -``BLAS_LINKER_FLAGS`` - uncached list of required linker flags (excluding ``-l`` and ``-L``). -``BLAS_LIBRARIES`` - uncached list of libraries (using full path name) to link against - to use BLAS (may be empty if compiler implicitly links BLAS) -``BLAS95_LIBRARIES`` - uncached list of libraries (using full path name) to link against - to use BLAS95 interface -``BLAS95_FOUND`` - library implementing the BLAS95 interface is found - .. _`BLAS/LAPACK Vendors`: BLAS/LAPACK Vendors ^^^^^^^^^^^^^^^^^^^ ``Generic`` - Generic reference implementation + Generic reference implementation. ``ACML``, ``ACML_MP``, ``ACML_GPU`` AMD Core Math Library @@ -111,31 +116,31 @@ ``AOCL``, ``AOCL_mt`` .. versionadded:: 3.27 - AMD Optimizing CPU Libraries + AMD Optimizing CPU Libraries. ``Apple``, ``NAS`` - Apple BLAS (Accelerate), and Apple NAS (vecLib) + Apple BLAS (Accelerate), and Apple NAS (vecLib). ``Arm``, ``Arm_mp``, ``Arm_ilp64``, ``Arm_ilp64_mp`` .. versionadded:: 3.18 - Arm Performance Libraries + Arm Performance Libraries. ``ATLAS`` - Automatically Tuned Linear Algebra Software + Automatically Tuned Linear Algebra Software. ``CXML``, ``DXML`` - Compaq/Digital Extended Math Library + Compaq/Digital Extended Math Library. ``EML``, ``EML_mt`` .. versionadded:: 3.20 - Elbrus Math Library + Elbrus Math Library. ``FLAME`` .. versionadded:: 3.11 - BLIS Framework + BLIS Framework. ``FlexiBLAS`` .. versionadded:: 3.19 @@ -143,71 +148,71 @@ ``Fujitsu_SSL2``, ``Fujitsu_SSL2BLAMP``, ``Fujitsu_SSL2SVE``, ``Fujitsu_SSL2BLAMPSVE`` .. versionadded:: 3.20 - Fujitsu SSL2 serial and parallel blas/lapack with SVE instructions + Fujitsu SSL2 serial and parallel blas/lapack with SVE instructions. ``Goto`` - GotoBLAS + GotoBLAS. ``IBMESSL``, ``IBMESSL_SMP`` - IBM Engineering and Scientific Subroutine Library + IBM Engineering and Scientific Subroutine Library. ``Intel`` - Intel MKL 32 bit and 64 bit obsolete versions + Intel MKL 32 bit and 64 bit obsolete versions. ``Intel10_32`` - Intel MKL v10 32 bit, threaded code + Intel MKL v10 32 bit, threaded code. ``Intel10_64lp`` - Intel MKL v10+ 64 bit, threaded code, lp64 model + Intel MKL v10+ 64 bit, threaded code, lp64 model. ``Intel10_64lp_seq`` - Intel MKL v10+ 64 bit, sequential code, lp64 model + Intel MKL v10+ 64 bit, sequential code, lp64 model. ``Intel10_64ilp`` .. versionadded:: 3.13 - Intel MKL v10+ 64 bit, threaded code, ilp64 model + Intel MKL v10+ 64 bit, threaded code, ilp64 model. ``Intel10_64ilp_seq`` .. versionadded:: 3.13 - Intel MKL v10+ 64 bit, sequential code, ilp64 model + Intel MKL v10+ 64 bit, sequential code, ilp64 model. ``Intel10_64_dyn`` .. versionadded:: 3.17 - Intel MKL v10+ 64 bit, single dynamic library + Intel MKL v10+ 64 bit, single dynamic library. ``libblastrampoline`` .. versionadded:: 3.30 - A BLAS/LAPACK demuxing library using PLT trampolines + A BLAS/LAPACK demuxing library using PLT trampolines. ``NVPL`` .. versionadded:: 4.1 - NVIDIA Performance Libraries + NVIDIA Performance Libraries. ``NVHPC`` .. versionadded:: 3.21 - NVIDIA HPC SDK + NVIDIA HPC SDK. ``OpenBLAS`` .. versionadded:: 3.6 ``PhiPACK`` - Portable High Performance ANSI C (PHiPAC) + Portable High Performance ANSI C (PHiPAC). ``SCSL``, ``SCSL_mp`` - Scientific Computing Software Library + Scientific Computing Software Library. ``SGIMATH`` - SGI Scientific Mathematical Library + SGI Scientific Mathematical Library. ``SunPerf`` - Sun Performance Library + Sun Performance Library. .. _`Intel MKL`: @@ -270,6 +275,15 @@ . /opt/intel/oneapi/compiler/latest/env/vars.sh +Examples +^^^^^^^^ + +Finding BLAS and linking it to a project target: + +.. code-block:: cmake + + find_package(BLAS) + target_link_libraries(example PRIVATE BLAS::BLAS) #]=======================================================================] # The approach follows that of the ``autoconf`` macro file, ``acx_blas.m4`` @@ -313,7 +327,7 @@ set(BLA_PKGCONFIG_BLAS "blas") endif() find_package(PkgConfig QUIET) - if(PKG_CONFIG_FOUND) + if(PkgConfig_FOUND) pkg_check_modules(PKGC_BLAS QUIET ${BLA_PKGCONFIG_BLAS}) if(PKGC_BLAS_FOUND) set(BLAS_FOUND ${PKGC_BLAS_FOUND}) @@ -1108,9 +1122,9 @@ else() file(GLOB _ACML_GPU_ROOT "/opt/acml*/GPGPUexamples") endif() - list(GET _ACML_ROOT 0 _ACML_ROOT) - list(GET _ACML_GPU_ROOT 0 _ACML_GPU_ROOT) if(_ACML_ROOT) + list(GET _ACML_ROOT 0 _ACML_ROOT) + list(GET _ACML_GPU_ROOT 0 _ACML_GPU_ROOT) get_filename_component(_ACML_ROOT ${_ACML_ROOT} PATH) if(_blas_sizeof_integer EQUAL 8) set(_ACML_PATH_SUFFIX "_int64")
diff --git a/Modules/FindBZip2.cmake b/Modules/FindBZip2.cmake index 0b9f3fe..344aa1b 100644 --- a/Modules/FindBZip2.cmake +++ b/Modules/FindBZip2.cmake
@@ -28,8 +28,15 @@ This module defines the following variables: ``BZip2_FOUND`` - Boolean indicating whether the BZip2 library is found. For backward - compatibility, the ``BZIP2_FOUND`` variable is also set to the same value. + .. versionadded:: 3.3 + + Boolean indicating whether the (requested version of) BZip2 library was + found. + +``BZip2_VERSION`` + .. versionadded:: 4.2 + + The version of BZip2 found. ``BZIP2_INCLUDE_DIRS`` .. versionadded:: 3.12 @@ -39,11 +46,6 @@ ``BZIP2_LIBRARIES`` Libraries needed for linking to use BZip2. -``BZIP2_VERSION`` - .. versionadded:: 3.26 - - The version of BZip2 found. - Cache Variables ^^^^^^^^^^^^^^^ @@ -63,14 +65,29 @@ (e.g., ``BZ2_bzCompressInit()``). Versions of BZip2 prior to 1.0.0 used unprefixed function names (e.g., ``bzCompressInit()``). -Legacy Variables -^^^^^^^^^^^^^^^^ +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ The following variables are provided for backward compatibility: +``BZIP2_FOUND`` + .. deprecated:: 4.2 + Use ``BZip2_FOUND``, which has the same value. + + Boolean indicating whether the (requested version of) BZip2 library was + found. + ``BZIP2_VERSION_STRING`` - .. versionchanged:: 3.26 - Superseded by ``BZIP2_VERSION``. + .. deprecated:: 3.26 + Superseded by the ``BZIP2_VERSION`` (and ``BZip2_VERSION``). + + The version of BZip2 found. + +``BZIP2_VERSION`` + .. versionadded:: 3.26 + + .. deprecated:: 4.2 + Superseded by the ``BZip2_VERSION``. The version of BZip2 found. @@ -108,12 +125,13 @@ file(STRINGS "${BZIP2_INCLUDE_DIR}/bzlib.h" BZLIB_H REGEX "bzip2/libbzip2 version [0-9]+\\.[^ ]+ of [0-9]+ ") string(REGEX REPLACE ".* bzip2/libbzip2 version ([0-9]+\\.[^ ]+) of [0-9]+ .*" "\\1" BZIP2_VERSION_STRING "${BZLIB_H}") set(BZIP2_VERSION ${BZIP2_VERSION_STRING}) + set(BZip2_VERSION ${BZIP2_VERSION_STRING}) endif () include(FindPackageHandleStandardArgs) find_package_handle_standard_args(BZip2 REQUIRED_VARS BZIP2_LIBRARIES BZIP2_INCLUDE_DIR - VERSION_VAR BZIP2_VERSION) + VERSION_VAR BZip2_VERSION) if (BZip2_FOUND) set(BZIP2_INCLUDE_DIRS ${BZIP2_INCLUDE_DIR}) @@ -126,7 +144,7 @@ # Versions before 1.0.2 required <stdio.h> for the FILE definition. set(BZip2_headers "bzlib.h") - if(BZIP2_VERSION VERSION_LESS "1.0.2") + if(BZip2_VERSION VERSION_LESS "1.0.2") list(PREPEND BZip2_headers "stdio.h") endif() check_symbol_exists(BZ2_bzCompressInit "${BZip2_headers}" BZIP2_NEED_PREFIX)
diff --git a/Modules/FindBacktrace.cmake b/Modules/FindBacktrace.cmake index 0674c5f..052e6b5 100644 --- a/Modules/FindBacktrace.cmake +++ b/Modules/FindBacktrace.cmake
@@ -6,7 +6,11 @@ ------------- Finds `backtrace(3) <https://man7.org/linux/man-pages/man3/backtrace.3.html>`_, -a library that provides functions for application self-debugging. +a library that provides functions for application self-debugging: + +.. code-block:: cmake + + find_package(Backtrace [...]) This module checks whether ``backtrace(3)`` is supported, either through the standard C library (``libc``), or a separate library. @@ -14,11 +18,11 @@ Imported Targets ^^^^^^^^^^^^^^^^ -.. versionadded:: 3.30 - This module provides the following :ref:`Imported Targets`: ``Backtrace::Backtrace`` + .. versionadded:: 3.30 + An interface library encapsulating the usage requirements of Backtrace. This target is available only when Backtrace is found. @@ -27,13 +31,15 @@ This module defines the following variables: -``Backtrace_INCLUDE_DIRS`` - The include directories needed to use ``backtrace(3)`` header. -``Backtrace_LIBRARIES`` - The libraries (linker flags) needed to use ``backtrace(3)``, if any. ``Backtrace_FOUND`` Boolean indicating whether the ``backtrace(3)`` support is available. +``Backtrace_INCLUDE_DIRS`` + The include directories needed to use ``backtrace(3)`` header. + +``Backtrace_LIBRARIES`` + The libraries (linker flags) needed to use ``backtrace(3)``, if any. + Cache Variables ^^^^^^^^^^^^^^^ @@ -43,18 +49,20 @@ The header file needed for ``backtrace(3)``. This variable allows dynamic usage of the header in the project code. It can also be overridden by the user. -``Backtrace_LIBRARY`` - The external library providing backtrace, if any. + ``Backtrace_INCLUDE_DIR`` The directory holding the ``backtrace(3)`` header. +``Backtrace_LIBRARY`` + The external library providing backtrace, if any. + Examples ^^^^^^^^ Finding Backtrace and linking it to a project target as of CMake 3.30: .. code-block:: cmake - :caption: CMakeLists.txt + :caption: ``CMakeLists.txt`` find_package(Backtrace) target_link_libraries(app PRIVATE Backtrace::Backtrace) @@ -63,7 +71,7 @@ header file created by :command:`configure_file`: .. code-block:: cmake - :caption: CMakeLists.txt + :caption: ``CMakeLists.txt`` add_library(app app.c) @@ -73,7 +81,7 @@ configure_file(config.h.in config.h) .. code-block:: c - :caption: config.h.in + :caption: ``config.h.in`` #cmakedefine01 Backtrace_FOUND #if Backtrace_FOUND @@ -81,7 +89,7 @@ #endif .. code-block:: c - :caption: app.c + :caption: ``app.c`` #include "config.h" @@ -89,7 +97,7 @@ be defined manually: .. code-block:: cmake - :caption: CMakeLists.txt + :caption: ``CMakeLists.txt`` find_package(Backtrace) if(Backtrace_FOUND AND NOT TARGET Backtrace::Backtrace)
diff --git a/Modules/FindBoost.cmake b/Modules/FindBoost.cmake index 8ae4223..af11d87 100644 --- a/Modules/FindBoost.cmake +++ b/Modules/FindBoost.cmake
@@ -47,7 +47,7 @@ This module defines the following variables: ``Boost_FOUND`` - True if headers and requested libraries were found. + Boolean indicating whether headers and requested libraries were found. ``Boost_INCLUDE_DIRS`` Boost include directories. @@ -59,7 +59,8 @@ Boost component libraries to be linked. ``Boost_<COMPONENT>_FOUND`` - True if component ``<COMPONENT>`` was found (``<COMPONENT>`` name is upper-case). + Boolean indicating whether the component ``<COMPONENT>`` was found + (``<COMPONENT>`` name is upper-case). ``Boost_<COMPONENT>_LIBRARY`` Libraries to link for component ``<COMPONENT>`` (may include @@ -102,7 +103,7 @@ .. versionadded:: 3.15 The ``Boost_VERSION_<PART>`` variables. -Cache variables +Cache Variables ^^^^^^^^^^^^^^^ Search results are saved persistently in CMake cache entries: @@ -172,7 +173,7 @@ .. versionadded:: 3.5 -This module defines the following :prop_tgt:`IMPORTED` targets: +This module provides the following :ref:`Imported Targets`: ``Boost::boost`` Target for header-only dependencies. (Boost include directory). @@ -1424,6 +1425,7 @@ set(_Boost_WAVE_DEPENDENCIES filesystem serialization thread chrono atomic) set(_Boost_WSERIALIZATION_DEPENDENCIES serialization) else() + set(_Boost_COBALT_DEPENDENCIES cobalt_io cobalt_io_ssl container context) set(_Boost_CONTRACT_DEPENDENCIES thread chrono) set(_Boost_COROUTINE_DEPENDENCIES context) set(_Boost_FIBER_DEPENDENCIES context) @@ -1438,7 +1440,7 @@ set(_Boost_THREAD_DEPENDENCIES chrono atomic) set(_Boost_WAVE_DEPENDENCIES filesystem serialization thread chrono atomic) set(_Boost_WSERIALIZATION_DEPENDENCIES serialization) - if(Boost_VERSION_STRING VERSION_GREATER_EQUAL 1.89.0 AND NOT Boost_NO_WARN_NEW_VERSIONS) + if(Boost_VERSION_STRING VERSION_GREATER_EQUAL 1.91.0 AND NOT Boost_NO_WARN_NEW_VERSIONS) message(WARNING "New Boost version may have incorrect or missing dependencies and imported targets") endif() endif() @@ -1713,6 +1715,7 @@ # _Boost_COMPONENT_HEADERS. See the instructions at the top of # _Boost_COMPONENT_DEPENDENCIES. set(_Boost_KNOWN_VERSIONS ${Boost_ADDITIONAL_VERSIONS} + "1.90.0" "1.90" "1.89.0" "1.89" "1.88.0" "1.88" "1.87.0" "1.87" "1.86.0" "1.86" "1.85.0" "1.85" "1.84.0" "1.84" "1.83.0" "1.83" "1.82.0" "1.82" "1.81.0" "1.81" "1.80.0" "1.80" "1.79.0" "1.79" "1.78.0" "1.78" "1.77.0" "1.77" "1.76.0" "1.76" "1.75.0" "1.75" "1.74.0" "1.74"
diff --git a/Modules/FindBullet.cmake b/Modules/FindBullet.cmake index 61a5fb3..d2ef0d4 100644 --- a/Modules/FindBullet.cmake +++ b/Modules/FindBullet.cmake
@@ -5,7 +5,11 @@ FindBullet ---------- -Finds the Bullet physics engine. +Finds the Bullet physics engine: + +.. code-block:: cmake + + find_package(Bullet [...]) Result Variables ^^^^^^^^^^^^^^^^ @@ -13,10 +17,13 @@ This module defines the following variables: ``Bullet_FOUND`` - Boolean true if Bullet was found. For backward compatibility, the - ``BULLET_FOUND`` variable is also set to the same value. + .. versionadded:: 3.3 + + Boolean indicating whether Bullet was found. + ``BULLET_INCLUDE_DIRS`` The Bullet include directories. + ``BULLET_LIBRARIES`` Libraries needed to link to Bullet. By default, all Bullet components (Dynamics, Collision, LinearMath, and SoftBody) are added. @@ -30,14 +37,39 @@ Can be set to Bullet install path or Windows build path to specify where to find Bullet. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``BULLET_FOUND`` + .. deprecated:: 4.2 + Use ``Bullet_FOUND``, which has the same value. + + Boolean indicating whether Bullet was found. + Examples ^^^^^^^^ -Finding Bullet: +Finding Bullet and conditionally creating an interface :ref:`imported target +<Imported Targets>` that encapsulates its usage requirements for linking to a +project target: .. code-block:: cmake find_package(Bullet) + + if(Bullet_FOUND AND NOT TARGET Bullet::Bullet) + add_library(Bullet::Bullet INTERFACE IMPORTED) + set_target_properties( + Bullet::Bullet + PROPERTIES + INTERFACE_INCLUDE_DIRECTORIES "${BULLET_INCLUDE_DIRS}" + INTERFACE_LINK_LIBRARIES "${BULLET_LIBRARIES}" + ) + endif() + + target_link_libraries(example PRIVATE Bullet::Bullet) #]=======================================================================] macro(_FIND_BULLET_LIBRARY _var)
diff --git a/Modules/FindCABLE.cmake b/Modules/FindCABLE.cmake index af0e6b6..aa68ff4 100644 --- a/Modules/FindCABLE.cmake +++ b/Modules/FindCABLE.cmake
@@ -8,7 +8,11 @@ .. versionchanged:: 4.1 This module is available only if policy :policy:`CMP0191` is not set to ``NEW``. -Finds the CABLE installation and determines its include paths and libraries. +Finds the CABLE installation and determines its include paths and libraries: + +.. code-block:: cmake + + find_package(CABLE [...]) Package called CABLE (CABLE Automates Bindings for Language Extension) was initially developed by Kitware to generate bindings to C++ classes for use in @@ -25,7 +29,7 @@ Cache Variables ^^^^^^^^^^^^^^^ -The following cache variables may be set when using this module: +The following cache variables may also be set: ``CABLE`` Path to the ``cable`` executable.
diff --git a/Modules/FindCUDA.cmake b/Modules/FindCUDA.cmake index bceb615..96b1659 100644 --- a/Modules/FindCUDA.cmake +++ b/Modules/FindCUDA.cmake
@@ -584,10 +584,8 @@ # This macro helps us find the location of helper files we will need the full path to macro(CUDA_FIND_HELPER_FILE _name _extension) set(_full_name "${_name}.${_extension}") - # CMAKE_CURRENT_LIST_FILE contains the full path to the file currently being - # processed. Using this variable, we can pull out the current path, and + # Using CMAKE_CURRENT_LIST_DIR, we can pull out the current path, and # provide a way to get access to the other files we need local to here. - get_filename_component(CMAKE_CURRENT_LIST_DIR "${CMAKE_CURRENT_LIST_FILE}" PATH) set(CUDA_${_name} "${CMAKE_CURRENT_LIST_DIR}/FindCUDA/${_full_name}") if(NOT EXISTS "${CUDA_${_name}}") set(error_message "${_full_name} not found in ${CMAKE_CURRENT_LIST_DIR}/FindCUDA")
diff --git a/Modules/FindCUDAToolkit.cmake b/Modules/FindCUDAToolkit.cmake index b00cd26..17e2735 100644 --- a/Modules/FindCUDAToolkit.cmake +++ b/Modules/FindCUDAToolkit.cmake
@@ -7,9 +7,14 @@ .. versionadded:: 3.17 -This script locates the NVIDIA CUDA toolkit and the associated libraries, but -does not require the ``CUDA`` language be enabled for a given project. This -module does not search for the NVIDIA CUDA Samples. +Finds the NVIDIA CUDA toolkit and the associated libraries, but does not +require the ``CUDA`` language be enabled for a given project: + +.. code-block:: cmake + + find_package(CUDAToolkit [<version>] [QUIET] [REQUIRED] [EXACT] [...]) + +This module does not search for the NVIDIA CUDA Samples. .. versionadded:: 3.19 QNX support. @@ -107,7 +112,7 @@ An :ref:`imported target <Imported targets>` named ``CUDA::toolkit`` is provided. -This module defines :prop_tgt:`IMPORTED` targets for each +This module provides :ref:`Imported Targets` for each of the following libraries that are part of the CUDAToolkit: - `CUDA Runtime Library`_ @@ -519,9 +524,24 @@ **Note**: direct usage of this target by consumers should not be necessary. -Result variables +.. _`FindCUDAToolkit_bin2c`: + +bin2c +""""" + +.. versionadded:: 4.3 + +A utility that converts binary files to C files containing byte arrays. + +Target Created: + +- ``CUDA::bin2c`` + +Result Variables ^^^^^^^^^^^^^^^^ +This module defines the following variables: + ``CUDAToolkit_FOUND`` A boolean specifying whether or not the CUDA Toolkit was found. @@ -568,8 +588,6 @@ found to determine the CUDA Toolkit version as well as determining other features of the Toolkit. This variable is set for the convenience of modules that depend on this one. - - #]=======================================================================] # NOTE: much of this was simply extracted from FindCUDA.cmake. @@ -660,29 +678,65 @@ PATHS ${possible_nvcc_path} ) endif() - endif() + else() + if(NOT CUDAToolkit_SENTINEL_FILE) + find_program(CUDAToolkit_NVCC_EXECUTABLE + NAMES nvcc nvcc.exe + PATHS ${arg_SEARCH_PATHS} + ${arg_FIND_FLAGS} + ) + endif() - if(NOT CUDAToolkit_SENTINEL_FILE) - find_program(CUDAToolkit_NVCC_EXECUTABLE - NAMES nvcc nvcc.exe - PATHS ${arg_SEARCH_PATHS} - ${arg_FIND_FLAGS} - ) - endif() - - if(NOT CUDAToolkit_NVCC_EXECUTABLE) - find_file(CUDAToolkit_SENTINEL_FILE - NAMES version.txt version.json - PATHS ${arg_SEARCH_PATHS} - NO_DEFAULT_PATH - ) + if(NOT CUDAToolkit_NVCC_EXECUTABLE) + find_file(CUDAToolkit_SENTINEL_FILE + NAMES version.txt version.json + PATHS ${arg_SEARCH_PATHS} + NO_DEFAULT_PATH + ) + endif() endif() if(EXISTS "${CUDAToolkit_NVCC_EXECUTABLE}") # If NVCC exists then invoke it to find the toolkit location. # This allows us to support wrapper scripts (e.g. ccache or colornvcc), CUDA Toolkit, # NVIDIA HPC SDK, and distro's splayed layouts - execute_process(COMMAND ${CUDAToolkit_NVCC_EXECUTABLE} "-v" "__cmake_determine_cuda" + + + #Allow the user to specify a host compiler except for Visual Studio + if(NOT $ENV{CUDAHOSTCXX} STREQUAL "") + get_filename_component(CUDAToolkit_CUDA_HOST_COMPILER $ENV{CUDAHOSTCXX} PROGRAM) + if(NOT EXISTS ${CUDAToolkit_CUDA_HOST_COMPILER}) + message(FATAL_ERROR "Could not find the compiler specified in the environment variable CUDAHOSTCXX:\n$ENV{CUDAHOSTCXX}.\n${CUDAToolkit_CUDA_HOST_COMPILER}") + endif() + elseif(CUDAToolkit_CUDA_HOST_COMPILER) + # We get here if CUDAToolkit_CUDA_HOST_COMPILER was specified by the user or toolchain file. + if(IS_ABSOLUTE "${CUDAToolkit_CUDA_HOST_COMPILER}") + # Convert to forward slashes. + cmake_path(CONVERT "${CUDAToolkit_CUDA_HOST_COMPILER}" TO_CMAKE_PATH_LIST CUDAToolkit_CUDA_HOST_COMPILER NORMALIZE) + else() + # Convert to absolute path so changes in `PATH` do not impact CUDA compilation. + find_program(_CUDAToolkit_CUDA_HOST_COMPILER_PATH NO_CACHE NAMES "${CUDAToolkit_CUDA_HOST_COMPILER}") + if(_CUDAToolkit_CUDA_HOST_COMPILER_PATH) + set(CUDAToolkit_CUDA_HOST_COMPILER "${_CUDAToolkit_CUDA_HOST_COMPILER_PATH}") + endif() + unset(_CUDAToolkit_CUDA_HOST_COMPILER_PATH) + endif() + if(NOT EXISTS "${CUDAToolkit_CUDA_HOST_COMPILER}") + message(FATAL_ERROR "Could not find the compiler specified in the variable CUDAToolkit_CUDA_HOST_COMPILER:\n ${CUDAToolkit_CUDA_HOST_COMPILER}") + endif() + # If the value was cached, update the cache entry with our modifications. + get_property(_CUDAToolkit_CUDA_HOST_COMPILER_CACHED CACHE CUDAToolkit_CUDA_HOST_COMPILER PROPERTY TYPE) + if(_CUDAToolkit_CUDA_HOST_COMPILER_CACHED) + set_property(CACHE CUDAToolkit_CUDA_HOST_COMPILER PROPERTY VALUE "${CUDAToolkit_CUDA_HOST_COMPILER}") + mark_as_advanced(CUDAToolkit_CUDA_HOST_COMPILER) + endif() + unset(_CUDAToolkit_CUDA_HOST_COMPILER_CACHED) + endif() + + if(CUDAToolkit_CUDA_HOST_COMPILER) + set(nvcc_ccbin_flag "-ccbin=${CUDAToolkit_CUDA_HOST_COMPILER}") + endif() + execute_process(COMMAND ${CUDAToolkit_NVCC_EXECUTABLE} "${nvcc_ccbin_flag}" "-v" "__cmake_determine_cuda" OUTPUT_VARIABLE _CUDA_NVCC_OUT ERROR_VARIABLE _CUDA_NVCC_OUT) message(CONFIGURE_LOG "Executed nvcc to extract CUDAToolkit information:\n${_CUDA_NVCC_OUT}\n\n") @@ -766,6 +820,65 @@ endfunction() + function(_CUDAToolkit_guess_root_dir) + # CUDAToolkit_ROOT cmake / env variable not specified, try platform defaults. + # + # - Linux: /usr/local/cuda-X.Y + # - macOS: /Developer/NVIDIA/CUDA-X.Y + # - Windows: C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\vX.Y + # + # We will also search the default symlink location /usr/local/cuda first since + # if CUDAToolkit_ROOT is not specified, it is assumed that the symlinked + # directory is the desired location. + if(UNIX) + if(NOT APPLE) + set(platform_base "/usr/local/cuda-") + else() + set(platform_base "/Developer/NVIDIA/CUDA-") + endif() + else() + set(platform_base "C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v") + endif() + + # Build out a descending list of possible cuda installations, e.g. + file(GLOB possible_paths "${platform_base}*") + # Iterate the glob results and create a descending list. + set(versions) + foreach(p ${possible_paths}) + # Extract version number from end of string + string(REGEX MATCH "[0-9][0-9]?\\.[0-9]$" p_version ${p}) + if(IS_DIRECTORY ${p} AND p_version) + list(APPEND versions ${p_version}) + endif() + endforeach() + + # Sort numerically in descending order, so we try the newest versions first. + list(SORT versions COMPARE NATURAL ORDER DESCENDING) + + # With a descending list of versions, populate possible paths to search. + set(search_paths) + foreach(v ${versions}) + list(APPEND search_paths "${platform_base}${v}") + endforeach() + + # Force the global default /usr/local/cuda to the front on Unix. + if(UNIX) + list(INSERT search_paths 0 "/usr/local/cuda") + endif() + + # Now search for the toolkit again using the platform default search paths. + _CUDAToolkit_find_root_dir(SEARCH_PATHS "${search_paths}" FIND_FLAGS PATH_SUFFIXES bin) + if(CUDAToolkit_ROOT_DIR) + set(CUDAToolkit_ROOT_DIR "${CUDAToolkit_ROOT_DIR}" PARENT_SCOPE) + endif() + + # We are done with these variables now, cleanup for caller. + unset(platform_base) + unset(possible_paths) + unset(versions) + unset(search_paths) + endfunction() + function(_CUDAToolkit_find_version_file result_variable) # We first check for a non-scattered installation to prefer it over a scattered installation. set(version_files version.txt version.json) @@ -807,6 +920,28 @@ endif() endfunction() + macro(_CUDAToolkit_find_failure_message _CUDAToolkit_fail_mode) + # Declare error messages now, print later depending on find_package args. + if("${_CUDAToolkit_fail_mode}" STREQUAL "GUESS") + set(_CUDAToolkit_fail_message "Could not find `nvcc` executable in any searched paths, please set CUDAToolkit_ROOT") + elseif("${_CUDAToolkit_fail_mode}" STREQUAL "VARIABLE") + set(_CUDAToolkit_fail_message "Could not find `nvcc` executable in path specified by variable CUDAToolkit_ROOT=${CUDAToolkit_ROOT}") + else() + set(_CUDAToolkit_fail_message "Could not find `nvcc` executable in path specified by environment variable CUDAToolkit_ROOT=$ENV{CUDAToolkit_ROOT}") + endif() + + if(CUDAToolkit_FIND_REQUIRED) + message(FATAL_ERROR ${_CUDAToolkit_fail_message}) + else() + if(NOT CUDAToolkit_FIND_QUIETLY) + message(STATUS ${_CUDAToolkit_fail_message}) + endif() + set(CUDAToolkit_FOUND FALSE) + unset(_CUDAToolkit_fail_message) + return() + endif() + endmacro() + # For NVCC we can easily deduce the SDK binary directory from the compiler path. if(CMAKE_CUDA_COMPILER_LOADED AND NOT CUDAToolkit_BIN_DIR AND CMAKE_CUDA_COMPILER_ID STREQUAL "NVIDIA") get_filename_component(CUDAToolkit_BIN_DIR "${CMAKE_CUDA_COMPILER}" DIRECTORY) @@ -816,108 +951,38 @@ mark_as_advanced(CUDAToolkit_BIN_DIR) endif() - # Try user provided path - _CUDAToolkit_find_root_dir(COMPILER_PATHS) - if(NOT CUDAToolkit_ROOT_DIR AND CUDAToolkit_ROOT) - _CUDAToolkit_find_root_dir(SEARCH_PATHS "${CUDAToolkit_ROOT}" FIND_FLAGS PATH_SUFFIXES bin NO_DEFAULT_PATH) + # Try `CMAKE_CUDA_COMPILER` and `ENV{CUDACXX}` + if(NOT CUDAToolkit_ROOT_DIR) + _CUDAToolkit_find_root_dir(COMPILER_PATHS) endif() + + # Try user provided path + if(NOT CUDAToolkit_ROOT_DIR AND DEFINED CUDAToolkit_ROOT) + _CUDAToolkit_find_root_dir(SEARCH_PATHS "${CUDAToolkit_ROOT}" FIND_FLAGS PATH_SUFFIXES bin NO_DEFAULT_PATH) + if(NOT CUDAToolkit_ROOT_DIR) + # If the user specified CUDAToolkit_ROOT but the toolkit could not be found, this is an error. + _CUDAToolkit_find_failure_message(VARIABLE) + endif() + endif() + + if(NOT CUDAToolkit_ROOT_DIR AND DEFINED ENV{CUDAToolkit_ROOT}) + _CUDAToolkit_find_root_dir(SEARCH_PATHS "$ENV{CUDAToolkit_ROOT}" FIND_FLAGS PATH_SUFFIXES bin NO_DEFAULT_PATH) + if(NOT CUDAToolkit_ROOT_DIR) + # If the user specified ENV{CUDAToolkit_ROOT} but the toolkit could not be found, this is an error. + _CUDAToolkit_find_failure_message(ENV) + endif() + endif() + + # Try users PATH, and CUDA_PATH env variable if(NOT CUDAToolkit_ROOT_DIR) _CUDAToolkit_find_root_dir(FIND_FLAGS PATHS ENV CUDA_PATH PATH_SUFFIXES bin) endif() - # If the user specified CUDAToolkit_ROOT but the toolkit could not be found, this is an error. - if(NOT CUDAToolkit_ROOT_DIR AND (DEFINED CUDAToolkit_ROOT OR DEFINED ENV{CUDAToolkit_ROOT})) - # Declare error messages now, print later depending on find_package args. - set(fail_base "Could not find nvcc executable in path specified by") - set(cuda_root_fail "${fail_base} CUDAToolkit_ROOT=${CUDAToolkit_ROOT}") - set(env_cuda_root_fail "${fail_base} environment variable CUDAToolkit_ROOT=$ENV{CUDAToolkit_ROOT}") - - if(CUDAToolkit_FIND_REQUIRED) - if(DEFINED CUDAToolkit_ROOT) - message(FATAL_ERROR ${cuda_root_fail}) - elseif(DEFINED ENV{CUDAToolkit_ROOT}) - message(FATAL_ERROR ${env_cuda_root_fail}) - endif() - else() - if(NOT CUDAToolkit_FIND_QUIETLY) - if(DEFINED CUDAToolkit_ROOT) - message(STATUS ${cuda_root_fail}) - elseif(DEFINED ENV{CUDAToolkit_ROOT}) - message(STATUS ${env_cuda_root_fail}) - endif() - endif() - set(CUDAToolkit_FOUND FALSE) - unset(fail_base) - unset(cuda_root_fail) - unset(env_cuda_root_fail) - return() - endif() - endif() - - # CUDAToolkit_ROOT cmake / env variable not specified, try platform defaults. - # - # - Linux: /usr/local/cuda-X.Y - # - macOS: /Developer/NVIDIA/CUDA-X.Y - # - Windows: C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\vX.Y - # - # We will also search the default symlink location /usr/local/cuda first since - # if CUDAToolkit_ROOT is not specified, it is assumed that the symlinked - # directory is the desired location. + # Try guessing where CUDA is installed if(NOT CUDAToolkit_ROOT_DIR) - if(UNIX) - if(NOT APPLE) - set(platform_base "/usr/local/cuda-") - else() - set(platform_base "/Developer/NVIDIA/CUDA-") - endif() - else() - set(platform_base "C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v") - endif() - - # Build out a descending list of possible cuda installations, e.g. - file(GLOB possible_paths "${platform_base}*") - # Iterate the glob results and create a descending list. - set(versions) - foreach(p ${possible_paths}) - # Extract version number from end of string - string(REGEX MATCH "[0-9][0-9]?\\.[0-9]$" p_version ${p}) - if(IS_DIRECTORY ${p} AND p_version) - list(APPEND versions ${p_version}) - endif() - endforeach() - - # Sort numerically in descending order, so we try the newest versions first. - list(SORT versions COMPARE NATURAL ORDER DESCENDING) - - # With a descending list of versions, populate possible paths to search. - set(search_paths) - foreach(v ${versions}) - list(APPEND search_paths "${platform_base}${v}") - endforeach() - - # Force the global default /usr/local/cuda to the front on Unix. - if(UNIX) - list(INSERT search_paths 0 "/usr/local/cuda") - endif() - - # Now search for the toolkit again using the platform default search paths. - _CUDAToolkit_find_root_dir(SEARCH_PATHS "${search_paths}" FIND_FLAGS PATH_SUFFIXES bin) - - # We are done with these variables now, cleanup for caller. - unset(platform_base) - unset(possible_paths) - unset(versions) - unset(search_paths) - + _CUDAToolkit_guess_root_dir() if(NOT CUDAToolkit_ROOT_DIR) - if(CUDAToolkit_FIND_REQUIRED) - message(FATAL_ERROR "Could not find nvcc, please set CUDAToolkit_ROOT.") - elseif(NOT CUDAToolkit_FIND_QUIETLY) - message(STATUS "Could not find nvcc, please set CUDAToolkit_ROOT.") - endif() - - set(CUDAToolkit_FOUND FALSE) - return() + _CUDAToolkit_find_failure_message(GUESS) endif() endif() @@ -955,8 +1020,9 @@ endif() endif() -# Find target directory when crosscompiling. -if(CMAKE_CROSSCOMPILING) +# Figure out the target directory when either crosscompiling +# or if we don't have `nvcc` and need to deduce the target arch +if(CMAKE_CROSSCOMPILING OR NOT CUDAToolkit_NVCC_EXECUTABLE) # When a language is enabled we can use its compiler's target architecture. if(CMAKE_CUDA_COMPILER_LOADED AND CMAKE_CUDA_COMPILER_ARCHITECTURE_ID) set(_CUDA_TARGET_PROCESSOR "${CMAKE_CUDA_COMPILER_ARCHITECTURE_ID}") @@ -966,7 +1032,7 @@ set(_CUDA_TARGET_PROCESSOR "${CMAKE_C_COMPILER_ARCHITECTURE_ID}") elseif(CMAKE_SYSTEM_PROCESSOR) set(_CUDA_TARGET_PROCESSOR "${CMAKE_SYSTEM_PROCESSOR}") - else() + elseif(CMAKE_CROSSCOMPILING) message(FATAL_ERROR "Cross-compiling with the CUDA toolkit requires CMAKE_SYSTEM_PROCESSOR to be set.") endif() # Keep in sync with equivalent table in CMakeDetermineCUDACompiler and FindCUDA! @@ -997,13 +1063,18 @@ # Mark that we need to pop the root search path changes after we have # found all cuda libraries so that searches for our cross-compilation # libraries work when another cuda sdk is in CMAKE_PREFIX_PATH or - # PATh + # PATH set(_CUDAToolkit_Pop_ROOT_PATH True) break() endif() endforeach() endif() + #If not already set we simply use the toolkit root +if(NOT CUDAToolkit_TARGET_DIR) + set(CUDAToolkit_TARGET_DIR "${CUDAToolkit_ROOT_DIR}") +endif() + # Determine windows search path suffix for libraries if(CMAKE_HOST_SYSTEM_NAME STREQUAL "Windows") if(CMAKE_HOST_SYSTEM_PROCESSOR STREQUAL "AMD64") @@ -1012,19 +1083,6 @@ endif() endif() -# If not already set we can simply use the toolkit root or it's a scattered installation. -if(NOT CUDAToolkit_TARGET_DIR) - # Not cross compiling - set(CUDAToolkit_TARGET_DIR "${CUDAToolkit_ROOT_DIR}") - # Now that we have the real ROOT_DIR, find components inside it. - list(APPEND CMAKE_PREFIX_PATH ${CUDAToolkit_ROOT_DIR}) - - # Mark that we need to pop the prefix path changes after we have - # found the cudart library. - set(_CUDAToolkit_Pop_Prefix True) -endif() - - # We don't need to verify the cuda_runtime header when we are using `nvcc` include paths # as the compiler being enabled means the header was found if(NOT CUDAToolkit_INCLUDE_DIRECTORIES) @@ -1054,7 +1112,8 @@ cmake_path(NORMAL_PATH CUDAToolkit_MATH_INCLUDE_DIR) find_path(CUDAToolkit_CUBLAS_INCLUDE_DIR cublas_v2.h PATHS - ${CUDAToolkit_INCLUDE_DIRECTORIES} + ${CUDAToolkit_MATH_INCLUDE_DIR} + NO_DEFAULT_PATH ) if(CUDAToolkit_CUBLAS_INCLUDE_DIR) list(APPEND CUDAToolkit_INCLUDE_DIRECTORIES "${CUDAToolkit_CUBLAS_INCLUDE_DIR}") @@ -1066,12 +1125,12 @@ # Find the CUDA Runtime Library libcudart find_library(CUDA_CUDART NAMES cudart - PATHS ${CUDAToolkit_IMPLICIT_LIBRARY_DIRECTORIES} + PATHS ${CUDAToolkit_IMPLICIT_LIBRARY_DIRECTORIES} ${CUDAToolkit_TARGET_DIR} PATH_SUFFIXES lib64 ${_CUDAToolkit_win_search_dirs} ) find_library(CUDA_CUDART NAMES cudart - PATHS ${CUDAToolkit_IMPLICIT_LIBRARY_DIRECTORIES} + PATHS ${CUDAToolkit_IMPLICIT_LIBRARY_DIRECTORIES} ${CUDAToolkit_TARGET_DIR} PATH_SUFFIXES lib64/stubs ${_CUDAToolkit_win_stub_search_dirs} lib/stubs stubs ) @@ -1079,11 +1138,6 @@ message(STATUS "Unable to find cudart library.") endif() -if(_CUDAToolkit_Pop_Prefix) - list(REMOVE_AT CMAKE_PREFIX_PATH -1) - unset(_CUDAToolkit_Pop_Prefix) -endif() - #----------------------------------------------------------------------------- # Perform version comparison and validate all required variables are set. include(FindPackageHandleStandardArgs) @@ -1114,7 +1168,10 @@ # Detect we are in a splayed nvhpc toolkit layout and add extra # search paths without symlinks - if(CUDAToolkit_LIBRARY_DIR MATCHES ".*/cuda/${CUDAToolkit_VERSION_MAJOR}.${CUDAToolkit_VERSION_MINOR}/lib64$") + # + # When the `nvcc` compiler output is parsed we have already resolved + # symlinks so we have `cuda/12.X/targets/....` and not `cuda/12.X/lib64`. + if(CUDAToolkit_LIBRARY_DIR MATCHES ".*/cuda/${CUDAToolkit_VERSION_MAJOR}.${CUDAToolkit_VERSION_MINOR}/(lib64$|targets/)") # Search location for math_libs/ block(SCOPE_FOR POLICIES) cmake_policy(SET CMP0152 NEW) @@ -1258,7 +1315,7 @@ if(CUDAToolkit_VERSION VERSION_GREATER_EQUAL 12.0.0) _CUDAToolkit_find_and_add_import_lib(nvJitLink) - _CUDAToolkit_find_and_add_import_lib(nvJitLink_static DEPS cudart_static_deps) + _CUDAToolkit_find_and_add_import_lib(nvJitLink_static DEPS cudart_static_deps nvptxcompiler_static) endif() if(CUDAToolkit_VERSION VERSION_GREATER_EQUAL 12.4.0) @@ -1442,6 +1499,16 @@ endif() _CUDAToolkit_find_and_add_import_lib(OpenCL) + + find_program(CUDA_bin2c_EXECUTABLE + NAMES bin2c + HINTS ${CUDAToolkit_BIN_DIR} + NO_DEFAULT_PATH + ) + if(NOT TARGET CUDA::bin2c AND CUDA_bin2c_EXECUTABLE) + add_executable(CUDA::bin2c IMPORTED) + set_property(TARGET CUDA::bin2c PROPERTY IMPORTED_LOCATION "${CUDA_bin2c_EXECUTABLE}") + endif() endif() if(_CUDAToolkit_Pop_ROOT_PATH)
diff --git a/Modules/FindCURL.cmake b/Modules/FindCURL.cmake index 1488412..9af420f 100644 --- a/Modules/FindCURL.cmake +++ b/Modules/FindCURL.cmake
@@ -6,7 +6,11 @@ -------- Finds the native curl installation (include directories and libraries) for -transferring data with URLS. +transferring data with URLS: + +.. code-block:: cmake + + find_package(CURL [<version>] [COMPONENTS <components>...] [...]) .. versionadded:: 3.17 If curl is built using its CMake-based build system, it will provide its own @@ -68,8 +72,8 @@ This module defines the following variables: ``CURL_FOUND`` - Boolean indicating whether the (requested version of) curl and all required - components are found. + Boolean indicating whether (the requested version of) curl and all required + components were found. ``CURL_VERSION`` .. versionadded:: 4.0 @@ -80,7 +84,7 @@ .. versionadded:: 3.14 Boolean indicating whether the specified component (curl protocol or feature) - is found. + was found. ``CURL_INCLUDE_DIRS`` Include directories containing the ``curl/curl.h`` and other headers needed to @@ -183,7 +187,7 @@ endif() find_package(PkgConfig QUIET) -if(PKG_CONFIG_FOUND) +if(PkgConfig_FOUND) pkg_check_modules(PC_CURL QUIET libcurl) if(PC_CURL_FOUND) pkg_get_variable(CURL_SUPPORTED_PROTOCOLS_STRING libcurl supported_protocols)
diff --git a/Modules/FindCVS.cmake b/Modules/FindCVS.cmake index d50a758..b79f5f1 100644 --- a/Modules/FindCVS.cmake +++ b/Modules/FindCVS.cmake
@@ -5,7 +5,11 @@ FindCVS ------- -Finds the Concurrent Versions System (CVS). +Finds the Concurrent Versions System (CVS): + +.. code-block:: cmake + + find_package(CVS [...]) Result Variables ^^^^^^^^^^^^^^^^ @@ -13,7 +17,7 @@ This module defines the following variables: ``CVS_FOUND`` - True if the command-line client was found. + Boolean indicating whether the ``cvs`` command-line client was found. Cache Variables ^^^^^^^^^^^^^^^ @@ -78,8 +82,5 @@ ) mark_as_advanced(CVS_EXECUTABLE) -# Handle the QUIETLY and REQUIRED arguments and set CVS_FOUND to TRUE if -# all listed variables are TRUE - include(FindPackageHandleStandardArgs) find_package_handle_standard_args(CVS DEFAULT_MSG CVS_EXECUTABLE)
diff --git a/Modules/FindCoin3D.cmake b/Modules/FindCoin3D.cmake index 1d89c60..07cbb69 100644 --- a/Modules/FindCoin3D.cmake +++ b/Modules/FindCoin3D.cmake
@@ -5,7 +5,11 @@ FindCoin3D ---------- -Finds Coin3D (Open Inventor). +Finds Coin3D (Open Inventor): + +.. code-block:: cmake + + find_package(Coin3D [...]) Coin3D is an implementation of the Open Inventor API. It provides data structures and algorithms for 3D visualization. @@ -16,8 +20,9 @@ This module defines the following variables: ``Coin3D_FOUND`` - True if Coin3D, Open Inventor was found. For backward compatibility, the - ``COIN3D_FOUND`` variable is also set to the same value. + .. versionadded:: 3.3 + + Boolean indicating whether Coin3D, Open Inventor was found. Cache Variables ^^^^^^^^^^^^^^^ @@ -29,14 +34,39 @@ ``COIN3D_LIBRARIES`` Coin3D libraries required for linking. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``COIN3D_FOUND`` + .. deprecated:: 4.2 + Use ``Coin3D_FOUND``, which has the same value. + + Boolean indicating whether Coin3D, Open Inventor was found. + Examples ^^^^^^^^ -Finding Coin3D: +Finding Coin3D and conditionally creating an interface :ref:`imported target +<Imported Targets>` that encapsulates its usage requirements for linking to a +project target: .. code-block:: cmake find_package(Coin3D) + + if(Coin3D_FOUND AND NOT TARGET Coin3D::Coin3D) + add_library(Coin3D::Coin3D INTERFACE IMPORTED) + set_target_properties( + Coin3D::Coin3D + PROPERTIES + INTERFACE_INCLUDE_DIRECTORIES "${COIN3D_INCLUDE_DIRS}" + INTERFACE_LINK_LIBRARIES "${COIN3D_LIBRARIES}" + ) + endif() + + target_link_libraries(example PRIVATE Coin3D::Coin3D) #]=======================================================================] if (WIN32)
diff --git a/Modules/FindCups.cmake b/Modules/FindCups.cmake index 871a809..e9c5587 100644 --- a/Modules/FindCups.cmake +++ b/Modules/FindCups.cmake
@@ -5,7 +5,11 @@ FindCups -------- -Finds the Common UNIX Printing System (CUPS). +Finds the Common UNIX Printing System (CUPS): + +.. code-block:: cmake + + find_package(Cups [<version>] [...]) Imported Targets ^^^^^^^^^^^^^^^^ @@ -24,12 +28,17 @@ This module defines the following variables: ``Cups_FOUND`` - Boolean indicating whether the CUPS is found. For backward compatibility, the - ``CUPS_FOUND`` variable is also set to the same value. + .. versionadded:: 3.3 + + Boolean indicating whether (the requested version of) CUPS was found. + +``Cups_VERSION`` + .. versionadded:: 4.2 + + The version of CUPS found. + ``CUPS_INCLUDE_DIRS`` Include directories needed for using CUPS. -``CUPS_VERSION_STRING`` - The version of CUPS found. Cache Variables ^^^^^^^^^^^^^^^ @@ -38,6 +47,7 @@ ``CUPS_INCLUDE_DIR`` The directory containing the CUPS headers. + ``CUPS_LIBRARIES`` Libraries needed to link against to use CUPS. @@ -50,6 +60,23 @@ Set this variable to ``TRUE`` to require CUPS version which features the ``ippDeleteAttribute()`` function (i.e. at least of CUPS ``1.1.19``). +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``CUPS_FOUND`` + .. deprecated:: 4.2 + Use ``Cups_FOUND``, which has the same value. + + Boolean indicating whether (the requested version of) CUPS was found. + +``CUPS_VERSION_STRING`` + .. deprecated:: 4.2 + Superseded by the ``Cups_VERSION``. + + The version of CUPS found. + Examples ^^^^^^^^ @@ -83,19 +110,20 @@ file(STRINGS "${CUPS_INCLUDE_DIR}/cups/cups.h" cups_version_str REGEX "^#[\t ]*define[\t ]+CUPS_VERSION_(MAJOR|MINOR|PATCH)[\t ]+[0-9]+$") - unset(CUPS_VERSION_STRING) + unset(Cups_VERSION) foreach(VPART MAJOR MINOR PATCH) foreach(VLINE ${cups_version_str}) if(VLINE MATCHES "^#[\t ]*define[\t ]+CUPS_VERSION_${VPART}[\t ]+([0-9]+)$") set(CUPS_VERSION_PART "${CMAKE_MATCH_1}") - if(CUPS_VERSION_STRING) - string(APPEND CUPS_VERSION_STRING ".${CUPS_VERSION_PART}") + if(Cups_VERSION) + string(APPEND Cups_VERSION ".${CUPS_VERSION_PART}") else() - set(CUPS_VERSION_STRING "${CUPS_VERSION_PART}") + set(Cups_VERSION "${CUPS_VERSION_PART}") endif() endif() endforeach() endforeach() + set(CUPS_VERSION_STRING ${Cups_VERSION}) endif () include(FindPackageHandleStandardArgs) @@ -103,11 +131,11 @@ if (CUPS_REQUIRE_IPP_DELETE_ATTRIBUTE) find_package_handle_standard_args(Cups REQUIRED_VARS CUPS_LIBRARIES CUPS_INCLUDE_DIR CUPS_HAS_IPP_DELETE_ATTRIBUTE - VERSION_VAR CUPS_VERSION_STRING) + VERSION_VAR Cups_VERSION) else () find_package_handle_standard_args(Cups REQUIRED_VARS CUPS_LIBRARIES CUPS_INCLUDE_DIR - VERSION_VAR CUPS_VERSION_STRING) + VERSION_VAR Cups_VERSION) endif () mark_as_advanced(CUPS_INCLUDE_DIR CUPS_LIBRARIES)
diff --git a/Modules/FindCurses.cmake b/Modules/FindCurses.cmake index 64600c6..c93cb86 100644 --- a/Modules/FindCurses.cmake +++ b/Modules/FindCurses.cmake
@@ -5,7 +5,11 @@ FindCurses ---------- -Finds the curses or ncurses library. +Finds the curses or ncurses library: + +.. code-block:: cmake + + find_package(Curses [...]) Curses is a terminal control library for Unix-like systems, used to build text user interface (TUI) applications. Originally developed in 1978, it has since @@ -18,8 +22,9 @@ This module defines the following variables: ``Curses_FOUND`` - Boolean indicating whether the Curses is found. For backward compatibility, - the ``CURSES_FOUND`` variable is also set to the same value. + .. versionadded:: 3.3 + + Boolean indicating whether Curses was found. ``CURSES_INCLUDE_DIRS`` .. versionadded:: 3.1 @@ -52,7 +57,7 @@ This module accepts the following variables: ``CURSES_NEED_NCURSES`` - Set this variable to ``TRUE`` before calling ``find_package(Curses)`` if the + Set this variable to ``TRUE`` before calling ``find_package(Curses)`` if the ncurses implementation functionality is specifically required. ``CURSES_NEED_WIDE`` @@ -64,7 +69,13 @@ Deprecated Variables ^^^^^^^^^^^^^^^^^^^^ -The following legacy variables are provided for backward compatibility: +The following variables are provided for backward compatibility: + +``CURSES_FOUND`` + .. deprecated:: 4.2 + Use ``Curses_FOUND``, which has the same value. + + Boolean indicating whether Curses was found. ``CURSES_INCLUDE_DIR`` .. deprecated:: 3.1 @@ -318,7 +329,7 @@ set(CURSES_INCLUDE_DIR ${CURSES_INCLUDE_PATH}) # compatibility find_package(PkgConfig QUIET) -if(PKG_CONFIG_FOUND) +if(PkgConfig_FOUND) pkg_check_modules(NCURSES QUIET ${NCURSES_LIBRARY_NAME}) set(CURSES_CFLAGS ${NCURSES_CFLAGS_OTHER}) endif()
diff --git a/Modules/FindCxxTest.cmake b/Modules/FindCxxTest.cmake index 37f1e7a..8978e3e 100644 --- a/Modules/FindCxxTest.cmake +++ b/Modules/FindCxxTest.cmake
@@ -6,7 +6,11 @@ ----------- Finds `CxxTest`_, a C++ unit testing framework suite, and provides a helper -command to create test runners and integrate them with CTest. +command to create test runners and integrate them with CTest: + +.. code-block:: cmake + + find_package(CxxTest [...]) .. _`CxxTest`: https://github.com/CxxTest/cxxtest @@ -15,8 +19,10 @@ This module defines the following variables: -``CXXTEST_FOUND`` - Boolean indicating whether the CxxTest framework is found. +``CxxTest_FOUND`` + .. versionadded:: 4.2 + + Boolean indicating whether the CxxTest framework was found. ``CXXTEST_INCLUDE_DIRS`` Include directories containing headers needed to use CxxTest. @@ -35,11 +41,15 @@ The following cache variables may also be set: +``CXXTEST_PYTHON_TESTGEN_EXECUTABLE`` + The path to the Python-based CxxTest test generator script. + ``CXXTEST_PERL_TESTGEN_EXECUTABLE`` The path to the Perl-based CxxTest test generator script. -``CXXTEST_PYTHON_TESTGEN_EXECUTABLE`` - The path to the Python-based CxxTest test generator script. + .. note:: + Perl-based test generator script has been removed in CxxTest version + 4.0 in favor of Python-based script. Hints ^^^^^ @@ -76,7 +86,7 @@ This must be a relative path. It is interpreted relative to the current binary directory (:variable:`CMAKE_CURRENT_BINARY_DIR`). - ``<input-files-to-testgen>`` + ``<input-files-to-testgen>...`` A list of header files containing test suite classes derived from the C++ class ``CxxTest::TestSuite``, to be included in the test runner. These must be given as absolute paths. @@ -84,7 +94,13 @@ Deprecated Variables ^^^^^^^^^^^^^^^^^^^^ -The following variables are deprecated and provided for backward compatibility: +The following variables are provided for backward compatibility: + +``CXXTEST_FOUND`` + .. deprecated:: 4.2 + Use ``CxxTest_FOUND``, which has the same value. + + Boolean indicating whether the CxxTest framework was found. ``CXXTEST_USE_PYTHON`` .. deprecated:: 2.8.3 @@ -121,7 +137,7 @@ find_package(CxxTest) # Create interface imported target: - if(CXXTEST_FOUND AND NOT TARGET CxxTest::CxxTest) + if(CxxTest_FOUND AND NOT TARGET CxxTest::CxxTest) add_library(CxxTest::CxxTest INTERFACE IMPORTED) set_target_properties( CxxTest::CxxTest @@ -130,7 +146,7 @@ endif() # Add test: - if(CXXTEST_FOUND) + if(CxxTest_FOUND) enable_testing() cxxtest_add_test( @@ -164,8 +180,11 @@ }; #]=======================================================================] +# CMake 4.2 +# Module now consistently defines the CxxTest_FOUND result variable. +# # Version 1.4 (11/18/10) (CMake 2.8.4) -# Issue 11384: Added support to the CXX_ADD_TEST macro so header +# Issue 11384: Added support to the cxxtest_add_test() macro so header # files (containing the tests themselves) show up in # Visual Studio and other IDEs. # @@ -177,17 +196,21 @@ # # Also added support for CXXTEST_TESTGEN_ARGS, for manually specifying # options to the CxxTest code generator. -# Version 1.2 (3/2/08) +# +# Version 1.2 (3/2/08) (CMake 2.8.0) # Included patch from Tyler Roscoe to have the perl & python binaries -# detected based on CXXTEST_INCLUDE_DIR -# Version 1.1 (2/9/08) -# Clarified example to illustrate need to call target_link_libraries() -# Changed commands to lowercase -# Added licensing info -# Version 1.0 (1/8/08) -# Fixed CXXTEST_INCLUDE_DIRS so it will work properly -# Eliminated superfluous CXXTEST_FOUND assignment -# Cleaned up and added more documentation +# detected based on CXXTEST_INCLUDE_DIR. +# +# Version 1.1 (2/9/08) (CMake 2.8.0) +# Clarified example to illustrate need to call target_link_libraries(). +# Changed commands to lowercase. +# Added licensing info. +# +# Version 1.0 (1/8/08) (CMake 2.6.3) +# Module added to CMake. +# Fixed CXXTEST_INCLUDE_DIRS so it will work properly. +# Eliminated superfluous CXXTEST_FOUND assignment. +# Cleaned up and added more documentation. #============================================================= # cxxtest_add_test (public macro) @@ -214,7 +237,6 @@ else() add_test(${_cxxtest_testname} ${CMAKE_CURRENT_BINARY_DIR}/${_cxxtest_testname}) endif() - endmacro() #============================================================= @@ -234,10 +256,10 @@ find_program(CXXTEST_PERL_TESTGEN_EXECUTABLE cxxtestgen.pl PATHS ${CXXTEST_INCLUDE_DIR}) -if(PYTHON_FOUND OR Perl_FOUND) +if(Python_FOUND OR Perl_FOUND) include(FindPackageHandleStandardArgs) - if(PYTHON_FOUND AND (CXXTEST_USE_PYTHON OR NOT Perl_FOUND OR NOT DEFINED CXXTEST_USE_PYTHON)) + if(Python_FOUND AND (CXXTEST_USE_PYTHON OR NOT Perl_FOUND OR NOT DEFINED CXXTEST_USE_PYTHON)) set(CXXTEST_TESTGEN_EXECUTABLE ${CXXTEST_PYTHON_TESTGEN_EXECUTABLE}) execute_process(COMMAND ${CXXTEST_PYTHON_TESTGEN_EXECUTABLE} --version OUTPUT_VARIABLE _CXXTEST_OUT ERROR_VARIABLE _CXXTEST_OUT RESULT_VARIABLE _CXXTEST_RESULT) @@ -256,13 +278,14 @@ CXXTEST_INCLUDE_DIR CXXTEST_PERL_TESTGEN_EXECUTABLE) endif() - if(CXXTEST_FOUND) + if(CxxTest_FOUND) set(CXXTEST_INCLUDE_DIRS ${CXXTEST_INCLUDE_DIR}) endif() else() + set(CxxTest_FOUND FALSE) + set(CXXTEST_FOUND ${CxxTest_FOUND}) - set(CXXTEST_FOUND false) if(NOT CxxTest_FIND_QUIETLY) if(CxxTest_FIND_REQUIRED) message(FATAL_ERROR "Neither Python nor Perl found, cannot use CxxTest, aborting!")
diff --git a/Modules/FindCygwin.cmake b/Modules/FindCygwin.cmake index ba26980..102f2fe 100644 --- a/Modules/FindCygwin.cmake +++ b/Modules/FindCygwin.cmake
@@ -6,7 +6,11 @@ ---------- Finds Cygwin, a POSIX-compatible environment that runs natively on Microsoft -Windows. +Windows: + +.. code-block:: cmake + + find_package(Cygwin [...]) .. note:: @@ -21,6 +25,11 @@ This module defines the following variables: +``Cygwin_FOUND`` + .. versionadded:: 4.2 + + Boolean indicating whether Cygwin was found. + ``CYGWIN_INSTALL_PATH`` The path to the Cygwin root installation directory. @@ -30,7 +39,7 @@ Finding the Cygwin installation and using its path in a custom find module: .. code-block:: cmake - :caption: FindFoo.cmake + :caption: ``FindFoo.cmake`` find_package(Cygwin) find_program(Foo_EXECUTABLE NAMES foo PATHS ${CYGWIN_INSTALL_PATH}/bin) @@ -61,3 +70,9 @@ mark_as_advanced(CYGWIN_BAT) endif () + +if(CYGWIN_BAT AND CYGWIN_INSTALL_PATH) + set(Cygwin_FOUND TRUE) +else() + set(Cygwin_FOUND FALSE) +endif()
diff --git a/Modules/FindDCMTK.cmake b/Modules/FindDCMTK.cmake index 4e0ff47..181142c 100644 --- a/Modules/FindDCMTK.cmake +++ b/Modules/FindDCMTK.cmake
@@ -5,79 +5,149 @@ FindDCMTK --------- -Find DICOM ToolKit (DCMTK) libraries and applications +Finds the DICOM ToolKit (DCMTK) libraries and applications: -The module defines the following variables:: +.. code-block:: cmake - DCMTK_INCLUDE_DIRS - Directories to include to use DCMTK - DCMTK_LIBRARIES - Files to link against to use DCMTK - DCMTK_FOUND - If false, don't try to use DCMTK - DCMTK_DIR - (optional) Source directory for DCMTK + find_package(DCMTK [...]) -Compatibility -^^^^^^^^^^^^^ +DCMTK is a set of libraries and applications implementing large parts of +the DICOM Standard (Digital Imaging and Communications in Medicine). -This module is able to find a version of DCMTK that does or does not export -a ``DCMTKConfig.cmake`` file. It applies a two step process: +.. versionadded:: 3.5 + This module is now able to find a version of DCMTK that does or does not + export a ``DCMTKConfig.cmake`` file. -* Step 1: Attempt to find DCMTK version providing a ``DCMTKConfig.cmake`` file. -* Step 2: If step 1 failed, rely on ``FindDCMTK.cmake`` to set ``DCMTK_*`` - variables details below. + DCMTK since its version `3.6.1_20140617 + <https://git.dcmtk.org/?p=dcmtk.git;a=commit;h=662ae187c493c6b9a73dd5e3875372cebd0c11fe>`_ + supports and installs :ref:`package configuration file + <Config File Packages>` (``DCMTKConfig.cmake``) for use with the + :command:`find_package` command in *config mode*. + This module now applies a two-step process: -`Recent DCMTK -<https://git.dcmtk.org/?p=dcmtk.git;a=commit;h=662ae187c493c6b9a73dd5e3875372cebd0c11fe>`_ -provides a ``DCMTKConfig.cmake`` :manual:`package configuration file -<cmake-packages(7)>`. To exclusively use the package configuration file -(recommended when possible), pass the `NO_MODULE` option to -:command:`find_package`. For example, `find_package(DCMTK NO_MODULE)`. -This requires official DCMTK snapshot *3.6.1_20140617* or newer. + * Step 1: Attempts to find DCMTK version providing a ``DCMTKConfig.cmake`` + file and, if found, returns the results without further action. + * Step 2: If step 1 failed, this module falls back to *module mode* + (it searches standard locations) and sets the ``DCMTK_*`` result + variables. + Until all clients update to the more recent DCMTK, build systems will need + to support different versions of DCMTK. -Until all clients update to the more recent DCMTK, build systems will need -to support different versions of DCMTK. + On any given system, the following combinations of DCMTK versions could + be considered for the DCMTK installed on the system (for example, via a + system package manager), or locally (for example, a custom installation, + or through the :module:`FetchContent` module): -On any given system, the following combinations of DCMTK versions could be -considered: + ===== ================== =================== ============ + Case System DCMTK Local DCMTK Supported? + ===== ================== =================== ============ + A N/A [ ] DCMTKConfig YES + B N/A [X] DCMTKConfig YES + C [ ] DCMTKConfig N/A YES + D [X] DCMTKConfig N/A YES + E [ ] DCMTKConfig [ ] DCMTKConfig YES (*) + F [X] DCMTKConfig [ ] DCMTKConfig NO + G [ ] DCMTKConfig [X] DCMTKConfig YES + H [X] DCMTKConfig [X] DCMTKConfig YES + ===== ================== =================== ============ -+--------+---------------------+-----------------------+-------------------+ -| | SYSTEM DCMTK | LOCAL DCMTK | Supported ? | -+--------+---------------------+-----------------------+-------------------+ -| Case A | NA | [ ] DCMTKConfig | YES | -+--------+---------------------+-----------------------+-------------------+ -| Case B | NA | [X] DCMTKConfig | YES | -+--------+---------------------+-----------------------+-------------------+ -| Case C | [ ] DCMTKConfig | NA | YES | -+--------+---------------------+-----------------------+-------------------+ -| Case D | [X] DCMTKConfig | NA | YES | -+--------+---------------------+-----------------------+-------------------+ -| Case E | [ ] DCMTKConfig | [ ] DCMTKConfig | YES (*) | -+--------+---------------------+-----------------------+-------------------+ -| Case F | [X] DCMTKConfig | [ ] DCMTKConfig | NO | -+--------+---------------------+-----------------------+-------------------+ -| Case G | [ ] DCMTKConfig | [X] DCMTKConfig | YES | -+--------+---------------------+-----------------------+-------------------+ -| Case H | [X] DCMTKConfig | [X] DCMTKConfig | YES | -+--------+---------------------+-----------------------+-------------------+ + Legend: - (*) See Troubleshooting section. + (*) + See the `Troubleshooting`_ section. -Legend: + N/A + DCMTK is not available. - NA ...............: Means that no System or Local DCMTK is available + [ ] DCMTKConfig + DCMTK does NOT export a ``DCMTKConfig.cmake`` file. - [ ] DCMTKConfig ..: Means that the version of DCMTK does NOT export a DCMTKConfig.cmake file. + [X] DCMTKConfig + DCMTK exports a ``DCMTKConfig.cmake`` file. - [X] DCMTKConfig ..: Means that the version of DCMTK exports a DCMTKConfig.cmake file. +Result Variables +^^^^^^^^^^^^^^^^ +This module defines the following variables: + +``DCMTK_FOUND`` + Boolean indicating whether DCMTK was found. + +``DCMTK_INCLUDE_DIRS`` + Include directories containing headers needed to use DCMTK. + +``DCMTK_LIBRARIES`` + Libraries needed to link against to use DCMTK. + +Hints +^^^^^ + +This module accepts the following variables: + +``DCMTK_DIR`` + (optional) Source directory for DCMTK. Troubleshooting ^^^^^^^^^^^^^^^ -What to do if my project finds a different version of DCMTK? +.. rubric:: What to do if project finds a different version of DCMTK? Remove DCMTK entry from the CMake cache per :command:`find_package` -documentation. +documentation, and re-run configuration. To find DCMTK on custom location +use variables such as :variable:`CMAKE_PREFIX_PATH`, or ``DCMTK_DIR``. + +Examples +^^^^^^^^ + +Example: Finding DCMTK +"""""""""""""""""""""" + +Finding DCMTK with this module: + +.. code-block:: cmake + + find_package(DCMTK) + +Example: Finding DCMTK Without This Module +"""""""""""""""""""""""""""""""""""""""""" + +To explicitly use the ``DCMTKConfig.cmake`` package configuration file +(recommended when possible) and find DCMTK in *config mode* without using +this module, the ``NO_MODULE`` option can be given to +:command:`find_package`: + +.. code-block:: cmake + + find_package(DCMTK NO_MODULE) + +Example: Creating Imported Target +""""""""""""""""""""""""""""""""" + +In the following example, DCMTK is searched with this module and +an :ref:`imported target <Imported Targets>` is conditionally created to +provide DCMTK usage requirements which can be easily linked to project +targets. For example, if DCMTK is found in *config mode*, the +``DCMTK::DCMTK`` imported target will be available through the found config +files instead: + +.. code-block:: cmake + + find_package(DCMTK) + + # Upstream DCMTKConfig.cmake already provides DCMTK::DCMTK imported target + if(DCMTK_FOUND AND NOT TARGET DCMTK::DCMTK) + add_library(DCMTK::DCMTK INTERFACE IMPORTED) + set_target_properties( + DCMTK:DCMTK + PROPERTIES + INTERFACE_LINK_LIBRARIES "${DCMTK_LIBRARIES}" + INTERFACE_INCLUDE_DIRECTORIES "${DCMTK_INCLUDE_DIRS}" + ) + endif() + + target_link_libraries(example PRIVATE DCMTK::DCMTK) #]=======================================================================] #
diff --git a/Modules/FindDart.cmake b/Modules/FindDart.cmake index 96cce45..6d4b9a3 100644 --- a/Modules/FindDart.cmake +++ b/Modules/FindDart.cmake
@@ -8,10 +8,32 @@ .. deprecated:: 3.27 This module is available only if policy :policy:`CMP0145` is not set to ``NEW``. -Find DART +Finds DART: -This module looks for the dart testing software and sets DART_ROOT to +.. code-block:: cmake + + find_package(DART [...]) + +This module looks for the dart testing software and sets ``DART_ROOT`` to point to where it found it. + +Result Variables +^^^^^^^^^^^^^^^^ + +This module defines the following variables: + +``Dart_FOUND`` + .. versionadded:: 3.3 + + Boolean indicating whether DART was found. + +Cache Variables +^^^^^^^^^^^^^^^ + +The following cache variables may also be set: + +``DART_ROOT`` + The path to the Dart root installation. #]=======================================================================] if(_FindDart_testing)
diff --git a/Modules/FindDevIL.cmake b/Modules/FindDevIL.cmake index 9e195d3..923fe45 100644 --- a/Modules/FindDevIL.cmake +++ b/Modules/FindDevIL.cmake
@@ -5,7 +5,15 @@ FindDevIL --------- -Finds the Developer's Image Library, `DevIL <https://openil.sourceforge.net/>`_. +Finds the Developer's Image Library, `DevIL <https://openil.sourceforge.net/>`_: + +.. code-block:: cmake + + find_package(DevIL [<version>] [...]) + +.. versionadded:: 4.2 + Support for the ``<version>`` argument in the :command:`find_package` + call. Version can be also specified as a range. The DevIL package internally consists of the following libraries, all distributed as part of the same release: @@ -58,14 +66,21 @@ This module defines the following variables: ``DevIL_FOUND`` - Boolean indicating whether the DevIL package is found, including the IL and - ILU libraries. + .. versionadded:: 3.8 + + Boolean indicating whether the (requested version of) DevIL package was + found, including the IL and ILU libraries. + +``DevIL_VERSION`` + .. versionadded:: 4.2 + + The version of the DevIL found. ``DevIL_ILUT_FOUND`` .. versionadded:: 3.21 - Boolean indicating whether the ILUT library is found. On most systems, ILUT - is found when both IL and ILU are available. + Boolean indicating whether the ILUT library was found. On most systems, + ILUT is found when both IL and ILU are available. Cache Variables ^^^^^^^^^^^^^^^ @@ -109,8 +124,8 @@ target_link_libraries(app PRIVATE DevIL::ILUT) #]=======================================================================] -# TODO: Add version support. -# Tested under Linux and Windows (MSVC) +cmake_policy(PUSH) +cmake_policy(SET CMP0159 NEW) # file(STRINGS) with REGEX updates CMAKE_MATCH_<n> include(FindPackageHandleStandardArgs) @@ -119,35 +134,62 @@ DOC "The path to the directory that contains il.h" ) -#message("IL_INCLUDE_DIR is ${IL_INCLUDE_DIR}") - find_library(IL_LIBRARIES NAMES IL DEVIL PATH_SUFFIXES libx32 lib64 lib lib32 DOC "The file that corresponds to the base il library." ) -#message("IL_LIBRARIES is ${IL_LIBRARIES}") - find_library(ILUT_LIBRARIES NAMES ILUT PATH_SUFFIXES libx32 lib64 lib lib32 DOC "The file that corresponds to the il (system?) utility library." ) -#message("ILUT_LIBRARIES is ${ILUT_LIBRARIES}") - find_library(ILU_LIBRARIES NAMES ILU PATH_SUFFIXES libx32 lib64 lib lib32 DOC "The file that corresponds to the il utility library." ) -#message("ILU_LIBRARIES is ${ILU_LIBRARIES}") +# Get version. +block(PROPAGATE DevIL_VERSION) + if(IL_INCLUDE_DIR AND EXISTS "${IL_INCLUDE_DIR}/il.h") + set(regex "^[ \t]*#[ \t]*define[ \t]+IL_VERSION[ \t]+([0-9]+)[ \t]*$") -find_package_handle_standard_args(DevIL DEFAULT_MSG - IL_LIBRARIES ILU_LIBRARIES - IL_INCLUDE_DIR) + file(STRINGS ${IL_INCLUDE_DIR}/il.h result REGEX "${regex}") + + if(result MATCHES "${regex}") + set(DevIL_VERSION "${CMAKE_MATCH_1}") + + math(EXPR DevIL_VERSION_MAJOR "${DevIL_VERSION} / 100") + math(EXPR DevIL_VERSION_MINOR "${DevIL_VERSION} / 10 % 10") + math(EXPR DevIL_VERSION_PATCH "${DevIL_VERSION} % 10") + + set(DevIL_VERSION "") + foreach(part MAJOR MINOR PATCH) + if(DevIL_VERSION) + string(APPEND ".${DevIL_VERSION_${part}}") + else() + set(DevIL_VERSION "${DevIL_VERSION_${part}}") + endif() + + set( + DevIL_VERSION + "${DevIL_VERSION_MAJOR}.${DevIL_VERSION_MINOR}.${DevIL_VERSION_PATCH}" + ) + endforeach() + endif() + endif() +endblock() + +find_package_handle_standard_args( + DevIL + REQUIRED_VARS IL_LIBRARIES ILU_LIBRARIES IL_INCLUDE_DIR + VERSION_VAR DevIL_VERSION + HANDLE_VERSION_RANGE +) + # provide legacy variable for compatibility set(IL_FOUND ${DevIL_FOUND}) @@ -183,3 +225,5 @@ target_link_libraries(DevIL::ILUT INTERFACE DevIL::ILU) endif() endif() + +cmake_policy(POP)
diff --git a/Modules/FindDoxygen.cmake b/Modules/FindDoxygen.cmake index 2d43099..e72110c 100644 --- a/Modules/FindDoxygen.cmake +++ b/Modules/FindDoxygen.cmake
@@ -11,7 +11,7 @@ .. code-block:: cmake - find_package(Doxygen [<version>] [...] [COMPONENTS <components>...] [...]) + find_package(Doxygen [<version>] [COMPONENTS <components>...] [...]) Components ^^^^^^^^^^ @@ -90,12 +90,14 @@ This module defines the following variables: ``Doxygen_FOUND`` - Boolean indicating whether (the requested version of) ``doxygen`` executable - and all requested required components are found. For backward compatibility, - the ``DOXYGEN_FOUND`` variable is also set, except it has boolean value of - ``YES`` or ``NO``. + .. versionadded:: 3.3 -``DOXYGEN_VERSION`` + Boolean indicating whether the (requested version of) ``doxygen`` executable + and all requested required components were found. + +``Doxygen_VERSION`` + .. versionadded:: 4.2 + The version of Doxygen found (as reported by ``doxygen --version``). Commands @@ -490,6 +492,14 @@ For compatibility with previous versions of CMake, the following variables are also defined but they are deprecated and should no longer be used: +``DOXYGEN_FOUND`` + .. deprecated:: 4.2 + Use ``Doxygen_FOUND``. + + Boolean indicating whether the (requested version of) ``doxygen`` executable + and all requested required components were found. It has a boolean value + of ``YES`` or ``NO``. + ``DOXYGEN_EXECUTABLE`` .. deprecated:: 3.9 Use ``Doxygen::doxygen`` imported target instead of referring to the @@ -499,8 +509,9 @@ ``DOXYGEN_DOT_FOUND`` .. deprecated:: 3.9 + Use ``Doxygen_dot_FOUND``. - Boolean result variable indicating whether ``dot`` executable is found. + Boolean result variable indicating whether ``dot`` executable was found. ``DOXYGEN_DOT_EXECUTABLE`` .. deprecated:: 3.9 @@ -529,6 +540,12 @@ (i.e. without specifying components) it prevents this find module from searching for Graphviz's ``dot`` utility. +``DOXYGEN_VERSION`` + .. deprecated:: 4.2 + Superseded by the ``Doxygen_VERSION``. + + The version of Doxygen found. + Examples ^^^^^^^^ @@ -653,7 +670,7 @@ In the following example, a custom ``Doxyfile`` configuration file is created in the current binary directory (:variable:`CMAKE_CURRENT_BINARY_DIR`) prior -to calling the ``doxygen_add_doxs()``. This allows project-specific +to calling the ``doxygen_add_docs()``. This allows project-specific configuration tags to be customized as needed: .. code-block:: cmake @@ -664,7 +681,7 @@ if(Doxygen_FOUND) configure_file(Doxyfile.in Doxyfile) - doxygen_add_doxs( + doxygen_add_docs( example_docs foo.c bar.c ALL @@ -765,7 +782,8 @@ mark_as_advanced(DOXYGEN_EXECUTABLE) if(DOXYGEN_EXECUTABLE) - _Doxygen_get_version(DOXYGEN_VERSION _Doxygen_version_result "${DOXYGEN_EXECUTABLE}") + _Doxygen_get_version(Doxygen_VERSION _Doxygen_version_result "${DOXYGEN_EXECUTABLE}") + set(DOXYGEN_VERSION "${Doxygen_VERSION}") if(_Doxygen_version_result) if(NOT Doxygen_FIND_QUIETLY) @@ -959,7 +977,7 @@ find_package_handle_standard_args( Doxygen REQUIRED_VARS DOXYGEN_EXECUTABLE - VERSION_VAR DOXYGEN_VERSION + VERSION_VAR Doxygen_VERSION HANDLE_VERSION_RANGE HANDLE_COMPONENTS )
diff --git a/Modules/FindEXPAT.cmake b/Modules/FindEXPAT.cmake index dd45e58..bcb604f 100644 --- a/Modules/FindEXPAT.cmake +++ b/Modules/FindEXPAT.cmake
@@ -5,8 +5,13 @@ FindEXPAT --------- -Finds the native Expat headers and library. Expat is a stream-oriented XML -parser library written in C. +Finds the native Expat headers and library: + +.. code-block:: cmake + + find_package(EXPAT [<version>] [...]) + +Expat is a stream-oriented XML parser library written in C. Imported Targets ^^^^^^^^^^^^^^^^ @@ -22,15 +27,22 @@ Result Variables ^^^^^^^^^^^^^^^^ -This module sets the following variables: +This module defines the following variables: + +``EXPAT_FOUND`` + Boolean indicating whether (the requested version of) Expat was found. + +``EXPAT_VERSION`` + .. versionadded:: 4.2 + + The version of Expat found. ``EXPAT_INCLUDE_DIRS`` Include directories containing ``expat.h`` and related headers needed to use Expat. + ``EXPAT_LIBRARIES`` Libraries needed to link against to use Expat. -``EXPAT_FOUND`` - Boolean indicating whether the Expat is found. Hints ^^^^^ @@ -46,6 +58,17 @@ Implemented on non-Windows platforms. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``EXPAT_VERSION_STRING`` + .. deprecated:: 4.2 + Superseded by the ``EXPAT_VERSION``. + + The version of Expat found. + Examples ^^^^^^^^ @@ -61,7 +84,7 @@ cmake_policy(SET CMP0159 NEW) # file(STRINGS) with REGEX updates CMAKE_MATCH_<n> find_package(PkgConfig QUIET) -if(PKG_CONFIG_FOUND) +if(PkgConfig_FOUND) pkg_check_modules(PC_EXPAT QUIET expat) endif() @@ -135,25 +158,26 @@ file(STRINGS "${EXPAT_INCLUDE_DIR}/expat.h" expat_version_str REGEX "^#[\t ]*define[\t ]+XML_(MAJOR|MINOR|MICRO)_VERSION[\t ]+[0-9]+$") - unset(EXPAT_VERSION_STRING) + unset(EXPAT_VERSION) foreach(VPART MAJOR MINOR MICRO) foreach(VLINE ${expat_version_str}) if(VLINE MATCHES "^#[\t ]*define[\t ]+XML_${VPART}_VERSION[\t ]+([0-9]+)$") set(EXPAT_VERSION_PART "${CMAKE_MATCH_1}") - if(EXPAT_VERSION_STRING) - string(APPEND EXPAT_VERSION_STRING ".${EXPAT_VERSION_PART}") + if(EXPAT_VERSION) + string(APPEND EXPAT_VERSION ".${EXPAT_VERSION_PART}") else() - set(EXPAT_VERSION_STRING "${EXPAT_VERSION_PART}") + set(EXPAT_VERSION "${EXPAT_VERSION_PART}") endif() endif() endforeach() endforeach() + set(EXPAT_VERSION_STRING ${EXPAT_VERSION}) endif() include(FindPackageHandleStandardArgs) find_package_handle_standard_args(EXPAT REQUIRED_VARS EXPAT_LIBRARY EXPAT_INCLUDE_DIR - VERSION_VAR EXPAT_VERSION_STRING) + VERSION_VAR EXPAT_VERSION) # Copy the results to the output variables and target. if(EXPAT_FOUND)
diff --git a/Modules/FindEnvModules.cmake b/Modules/FindEnvModules.cmake index 3e7d800..bb19d04 100644 --- a/Modules/FindEnvModules.cmake +++ b/Modules/FindEnvModules.cmake
@@ -43,7 +43,7 @@ This module defines the following variables: ``EnvModules_FOUND`` - Boolean indicating whether a compatible Environment Modules framework is + Boolean indicating whether a compatible Environment Modules framework was found. Cache Variables
diff --git a/Modules/FindFLEX.cmake b/Modules/FindFLEX.cmake index 11c53a9..c76e052 100644 --- a/Modules/FindFLEX.cmake +++ b/Modules/FindFLEX.cmake
@@ -10,7 +10,7 @@ .. code-block:: cmake - find_package(FLEX [<version>] ...) + find_package(FLEX [<version>] [...]) Flex generates lexical analyzers, also known as *scanners* or *lexers*. It also includes a runtime library (``fl``) that supplies support functions for the @@ -23,7 +23,7 @@ This module defines the following variables: ``FLEX_FOUND`` - Boolean indicating whether (the requested version of) Flex is found. + Boolean indicating whether (the requested version of) Flex was found. ``FLEX_VERSION`` The version of Flex found.
diff --git a/Modules/FindFLTK.cmake b/Modules/FindFLTK.cmake index 6b3438c..eed585c 100644 --- a/Modules/FindFLTK.cmake +++ b/Modules/FindFLTK.cmake
@@ -6,7 +6,11 @@ -------- Finds the Fast Light Toolkit (FLTK), a cross-platform toolkit for GUI -development. +development: + +.. code-block:: cmake + + find_package(FLTK [...]) FLTK uses CMake-based build system and provides a package configuration file for projects to find it. As of its 1.4.0 version it also provides @@ -18,8 +22,8 @@ documentation for more information, how to use FLTK with CMake. .. versionadded:: 3.11 - Debug and Release library variants are found separately and use - per-configuration variables. + Debug and release (optimized) library variants are found separately and use + :ref:`per-configuration <Build Configurations>` variables. Result Variables ^^^^^^^^^^^^^^^^ @@ -27,7 +31,7 @@ This module defines the following variables: ``FLTK_FOUND`` - Boolean indicating whether FLTK is found. + Boolean indicating whether FLTK was found. ``FLTK_LIBRARIES`` Libraries needed to link against to use FLTK.
diff --git a/Modules/FindFLTK2.cmake b/Modules/FindFLTK2.cmake index c839d3f..a276ed8 100644 --- a/Modules/FindFLTK2.cmake +++ b/Modules/FindFLTK2.cmake
@@ -14,7 +14,11 @@ modern versions, use the :module:`FindFLTK` module instead. Finds the Fast Light Toolkit (FLTK) version 2.x, a cross-platform toolkit for -GUI development. +GUI development: + +.. code-block:: cmake + + find_package(FLTK2 [...]) Result Variables ^^^^^^^^^^^^^^^^ @@ -22,7 +26,7 @@ This module defines the following variables: ``FLTK2_FOUND`` - Boolean indicating whether FLTK 2.x is found. + Boolean indicating whether FLTK 2.x was found. ``FLTK2_LIBRARIES`` Libraries needed to link against to use FLTK 2.x.
diff --git a/Modules/FindFontconfig.cmake b/Modules/FindFontconfig.cmake index 218ad2f..1e37c7c 100644 --- a/Modules/FindFontconfig.cmake +++ b/Modules/FindFontconfig.cmake
@@ -7,7 +7,11 @@ .. versionadded:: 3.14 -Finds Fontconfig, a library for font configuration and customization. +Finds Fontconfig, a library for font configuration and customization: + +.. code-block:: cmake + + find_package(Fontconfig [<version>] [...]) Imported Targets ^^^^^^^^^^^^^^^^ @@ -24,7 +28,7 @@ This module defines the following variables: ``Fontconfig_FOUND`` - Boolean indicating whether the (requested version of) Fontconfig is found. + Boolean indicating whether (the requested version of) Fontconfig was found. ``Fontconfig_VERSION`` The version of Fontconfig found. ``Fontconfig_LIBRARIES`` @@ -53,7 +57,7 @@ # use pkg-config to get the directories and then use these values # in the find_path() and find_library() calls find_package(PkgConfig QUIET) -if(PKG_CONFIG_FOUND) +if(PkgConfig_FOUND) pkg_check_modules(PKG_FONTCONFIG QUIET fontconfig) endif() set(Fontconfig_COMPILE_OPTIONS ${PKG_FONTCONFIG_CFLAGS_OTHER})
diff --git a/Modules/FindFreetype.cmake b/Modules/FindFreetype.cmake index 0a4d9a3..436a62a 100644 --- a/Modules/FindFreetype.cmake +++ b/Modules/FindFreetype.cmake
@@ -5,7 +5,14 @@ FindFreetype ------------ -Finds the FreeType font renderer library. +Finds the FreeType font renderer library: + +.. code-block:: cmake + + find_package(Freetype [<version>] [...]) + +.. versionadded:: 3.7 + Debug and Release (optimized) library variants are found separately. Imported Targets ^^^^^^^^^^^^^^^^ @@ -24,9 +31,14 @@ This module defines the following variables: ``Freetype_FOUND`` - Boolean indicating whether the (requested version of) Freetype is found. For - backward compatibility, the ``FREETYPE_FOUND`` variable is also set to the - same value. + .. versionadded:: 3.3 + + Boolean indicating whether (the requested version of) Freetype was found. + +``Freetype_VERSION`` + .. versionadded:: 4.2 + + The version of Freetype found. ``FREETYPE_INCLUDE_DIRS`` Include directories containing headers needed to use Freetype. This is the @@ -36,9 +48,6 @@ ``FREETYPE_LIBRARIES`` Libraries needed to link against for using Freetype. -``FREETYPE_VERSION_STRING`` - The version of Freetype found. - .. versionadded:: 3.7 Debug and Release library variants are found separately. @@ -62,6 +71,23 @@ The user may set this environment variable to the root directory of a Freetype installation to find Freetype in non-standard locations. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``FREETYPE_FOUND`` + .. deprecated:: 4.2 + Use ``Freetype_FOUND``, which has the same value. + + Boolean indicating whether (the requested version of) Freetype was found. + +``FREETYPE_VERSION_STRING`` + .. deprecated:: 4.2 + Superseded by the ``Freetype_VERSION``. + + The version of Freetype found. + Examples ^^^^^^^^ @@ -170,20 +196,21 @@ file(STRINGS "${FREETYPE_H}" freetype_version_str REGEX "^#[\t ]*define[\t ]+FREETYPE_(MAJOR|MINOR|PATCH)[\t ]+[0-9]+$") - unset(FREETYPE_VERSION_STRING) + unset(Freetype_VERSION) foreach(VPART MAJOR MINOR PATCH) foreach(VLINE ${freetype_version_str}) if(VLINE MATCHES "^#[\t ]*define[\t ]+FREETYPE_${VPART}[\t ]+([0-9]+)$") set(FREETYPE_VERSION_PART "${CMAKE_MATCH_1}") - if(FREETYPE_VERSION_STRING) - string(APPEND FREETYPE_VERSION_STRING ".${FREETYPE_VERSION_PART}") + if(Freetype_VERSION) + string(APPEND Freetype_VERSION ".${FREETYPE_VERSION_PART}") else() - set(FREETYPE_VERSION_STRING "${FREETYPE_VERSION_PART}") + set(Freetype_VERSION "${FREETYPE_VERSION_PART}") endif() unset(FREETYPE_VERSION_PART) endif() endforeach() endforeach() + set(FREETYPE_VERSION_STRING ${Freetype_VERSION}) endif() include(FindPackageHandleStandardArgs) @@ -194,7 +221,7 @@ FREETYPE_LIBRARY FREETYPE_INCLUDE_DIRS VERSION_VAR - FREETYPE_VERSION_STRING + Freetype_VERSION ) mark_as_advanced(
diff --git a/Modules/FindGCCXML.cmake b/Modules/FindGCCXML.cmake index fdab959..cf4a96f 100644 --- a/Modules/FindGCCXML.cmake +++ b/Modules/FindGCCXML.cmake
@@ -7,14 +7,30 @@ .. versionchanged:: 4.1 This module is available only if policy :policy:`CMP0188` is not set to ``NEW``. - Port projects to search for CastXML by calling ``find_program`` directly. + Port projects to search for CastXML by calling :command:`find_program` directly. -Find the GCC-XML front-end executable. +Finds the GCC-XML front-end executable: -This module will define the following variables: +.. code-block:: cmake + + find_package(GCCXML [...]) + +Cache Variables +^^^^^^^^^^^^^^^ + +The following cache variables may also be set: ``GCCXML`` The GCC-XML front-end executable. + +Examples +^^^^^^^^ + +In new code, find CastXML with :command:`find_program` instead: + +.. code-block:: cmake + + find_program(CASTXML_EXECUTABLE castxml) #]=======================================================================] cmake_policy(GET CMP0188 _FindGCCXML_CMP0188)
diff --git a/Modules/FindGDAL.cmake b/Modules/FindGDAL.cmake index b952949..71883da 100644 --- a/Modules/FindGDAL.cmake +++ b/Modules/FindGDAL.cmake
@@ -5,61 +5,86 @@ FindGDAL -------- -Find Geospatial Data Abstraction Library (GDAL). - .. deprecated:: 4.0 GDAL 3.5 and above provide a ``GDALConfig.cmake`` package configuration file. Call ``find_package(GDAL CONFIG)`` to find it directly and avoid using this find module. For further details, see `GDAL's documentation on CMake integration <https://gdal.org/en/latest/development/cmake.html>`_. +Finds Geospatial Data Abstraction Library (GDAL): + +.. code-block:: cmake + + find_package(GDAL [<version>] [...]) + Imported Targets ^^^^^^^^^^^^^^^^ -.. versionadded:: 3.14 +This module provides the following :ref:`Imported Targets`: -This module defines :prop_tgt:`IMPORTED` target ``GDAL::GDAL`` -if GDAL has been found. +``GDAL::GDAL`` + .. versionadded:: 3.14 + + Target encapsulating the GDAL usage requirements, available only if GDAL + has been found. Result Variables ^^^^^^^^^^^^^^^^ -This module will set the following variables in your project: +This module defines the following variables: ``GDAL_FOUND`` - True if GDAL is found. -``GDAL_INCLUDE_DIRS`` - Include directories for GDAL headers. -``GDAL_LIBRARIES`` - Libraries to link to GDAL. + Boolean indicating whether (the requested version of) GDAL was found. + ``GDAL_VERSION`` .. versionadded:: 3.14 - The version of GDAL found. -Cache variables + The version of GDAL found. + +``GDAL_INCLUDE_DIRS`` + Include directories for GDAL headers. + +``GDAL_LIBRARIES`` + Libraries to link to GDAL. + +Cache Variables ^^^^^^^^^^^^^^^ The following cache variables may also be set: +``GDAL_INCLUDE_DIR`` + The directory containing ``<gdal.h>``. + ``GDAL_LIBRARY`` The libgdal library file. -``GDAL_INCLUDE_DIR`` - The directory containing ``gdal.h``. Hints ^^^^^ -Set ``GDAL_DIR`` or ``GDAL_ROOT`` in the environment to specify the -GDAL installation prefix. - The following variables may be set to modify the search strategy: +``GDAL_DIR`` or ``GDAL_ROOT`` + Set one of these environment variables to specify the GDAL installation + prefix. + ``FindGDAL_SKIP_GDAL_CONFIG`` - If set, ``gdal-config`` will not be used. This can be useful if there are + If set, ``gdal-config`` will not be used. This can be useful if there are GDAL libraries built with autotools (which provide the tool) and CMake (which do not) in the same environment. + ``GDAL_ADDITIONAL_LIBRARY_VERSIONS`` Extra versions of library names to search for. + +Examples +^^^^^^^^ + +Finding GDAL in config mode without using this module and linking its +imported target to a project target: + +.. code-block:: cmake + + find_package(GDAL CONFIG) + target_link_libraries(example PRIVATE GDAL::GDAL) #]=======================================================================] # $GDALDIR is an environment variable that would
diff --git a/Modules/FindGIF.cmake b/Modules/FindGIF.cmake index 585b846..7005954 100644 --- a/Modules/FindGIF.cmake +++ b/Modules/FindGIF.cmake
@@ -5,7 +5,11 @@ FindGIF ------- -Finds the Graphics Interchange Format (GIF) library (``giflib``). +Finds the Graphics Interchange Format (GIF) library (``giflib``): + +.. code-block:: cmake + + find_package(GIF [<version>] [...]) Imported Targets ^^^^^^^^^^^^^^^^ @@ -21,19 +25,22 @@ Result Variables ^^^^^^^^^^^^^^^^ -This module sets the following variables: +This module defines the following variables: ``GIF_FOUND`` - Boolean indicating whether the GIF library was found. -``GIF_INCLUDE_DIRS`` - Include directories needed to use the GIF library. -``GIF_LIBRARIES`` - Libraries needed to link to the GIF library. + Boolean indicating whether the (requested version of) GIF library was found. + ``GIF_VERSION`` Version string of the GIF library found (for example, ``5.1.4``). For GIF library versions prior to 4.1.6, version string will be set only to ``3`` or ``4`` as these versions did not provide version information in their headers. +``GIF_INCLUDE_DIRS`` + Include directories needed to use the GIF library. + +``GIF_LIBRARIES`` + Libraries needed to link to the GIF library. + Cache Variables ^^^^^^^^^^^^^^^ @@ -41,6 +48,7 @@ ``GIF_INCLUDE_DIR`` Directory containing the ``gif_lib.h`` and other GIF library headers. + ``GIF_LIBRARY`` Path to the GIF library.
diff --git a/Modules/FindGLEW.cmake b/Modules/FindGLEW.cmake index 03d19bf..6169553 100644 --- a/Modules/FindGLEW.cmake +++ b/Modules/FindGLEW.cmake
@@ -5,7 +5,11 @@ FindGLEW -------- -Finds the OpenGL Extension Wrangler Library (GLEW). +Finds the OpenGL Extension Wrangler Library (GLEW): + +.. code-block:: cmake + + find_package(GLEW [<version>] [...]) GLEW is a cross-platform C/C++ library that helps manage OpenGL extensions by providing efficient run-time mechanisms to query and load OpenGL functionality @@ -53,7 +57,7 @@ This module defines the following variables: ``GLEW_FOUND`` - Boolean indicating whether GLEW is found. + Boolean indicating whether (the requested version of) GLEW was found. ``GLEW_VERSION`` .. versionadded:: 3.15 @@ -185,17 +189,17 @@ function(__glew_set_find_library_suffix shared_or_static) - if((UNIX AND NOT APPLE) AND "${shared_or_static}" MATCHES "SHARED") + if((UNIX AND NOT APPLE AND NOT CYGWIN) AND "${shared_or_static}" MATCHES "SHARED") set(CMAKE_FIND_LIBRARY_SUFFIXES ".so" PARENT_SCOPE) - elseif((UNIX AND NOT APPLE) AND "${shared_or_static}" MATCHES "STATIC") + elseif((UNIX AND NOT APPLE AND NOT CYGWIN) AND "${shared_or_static}" MATCHES "STATIC") set(CMAKE_FIND_LIBRARY_SUFFIXES ".a" PARENT_SCOPE) elseif(APPLE AND "${shared_or_static}" MATCHES "SHARED") set(CMAKE_FIND_LIBRARY_SUFFIXES ".dylib;.so" PARENT_SCOPE) elseif(APPLE AND "${shared_or_static}" MATCHES "STATIC") set(CMAKE_FIND_LIBRARY_SUFFIXES ".a" PARENT_SCOPE) - elseif(WIN32 AND MINGW AND "${shared_or_static}" MATCHES "SHARED") + elseif((WIN32 AND MINGW OR CYGWIN) AND "${shared_or_static}" MATCHES "SHARED") set(CMAKE_FIND_LIBRARY_SUFFIXES ".dll.a" PARENT_SCOPE) - elseif(WIN32 AND MINGW AND "${shared_or_static}" MATCHES "STATIC") + elseif((WIN32 AND MINGW OR CYGWIN) AND "${shared_or_static}" MATCHES "STATIC") set(CMAKE_FIND_LIBRARY_SUFFIXES ".a" PARENT_SCOPE) elseif(WIN32 AND "${shared_or_static}" MATCHES "SHARED") set(CMAKE_FIND_LIBRARY_SUFFIXES ".lib" PARENT_SCOPE)
diff --git a/Modules/FindGLUT.cmake b/Modules/FindGLUT.cmake index e29758d..dcb0359 100644 --- a/Modules/FindGLUT.cmake +++ b/Modules/FindGLUT.cmake
@@ -5,8 +5,13 @@ FindGLUT -------- -Finds the OpenGL Utility Toolkit (GLUT) library, which provides a simple API for -creating windows, handling input, and managing events in OpenGL applications. +Finds the OpenGL Utility Toolkit (GLUT) library, which provides a simple API +for creating windows, handling input, and managing events in OpenGL +applications: + +.. code-block:: cmake + + find_package(GLUT [...]) Imported Targets ^^^^^^^^^^^^^^^^ @@ -24,7 +29,7 @@ This module defines the following variables: ``GLUT_FOUND`` - Boolean indicating whether GLUT is found. + Boolean indicating whether GLUT was found. ``GLUT_INCLUDE_DIRS`` .. versionadded:: 3.23 @@ -72,7 +77,7 @@ include(FindPackageHandleStandardArgs) find_package(PkgConfig QUIET) -if(PKG_CONFIG_FOUND) +if(PkgConfig_FOUND) pkg_check_modules(PC_GLUT QUIET glut) if(NOT PC_GLUT_FOUND) pkg_check_modules(PC_GLUT QUIET freeglut)
diff --git a/Modules/FindGSL.cmake b/Modules/FindGSL.cmake index a3cd654..041e9d1 100644 --- a/Modules/FindGSL.cmake +++ b/Modules/FindGSL.cmake
@@ -7,7 +7,11 @@ .. versionadded:: 3.2 -Finds the native GNU Scientific Library (GSL) includes and libraries. +Finds the native GNU Scientific Library (GSL) includes and libraries: + +.. code-block:: cmake + + find_package(GSL [<version>] [...]) The GNU Scientific Library (GSL) is a numerical library for C and C++ programmers. It is free software under the GNU General Public @@ -16,43 +20,31 @@ Imported Targets ^^^^^^^^^^^^^^^^ -If GSL is found, this module defines the following :ref:`Imported Targets`: +This module provides the following :ref:`Imported Targets`: ``GSL::gsl`` - The main GSL library that provides all usage requirements to use GSL. + Target encapsulating the main GSL library and all usage requirements, + available only if GSL is found. + ``GSL::gslcblas`` - The CBLAS support library used by GSL. It is linked also into the - ``GSL::gsl`` target but provided separately for granularity. + Target encapsulating the usage requirements of the CBLAS support library + used by GSL. This target is available if GSL is found. It is linked also + into the ``GSL::gsl`` target but provided separately for granularity. Result Variables ^^^^^^^^^^^^^^^^ -This module will set the following variables in the project: +This module defines the following variables: ``GSL_FOUND`` - True if GSL is found on the local system. + Boolean indicating whether (the requested version of) GSL was found on the + local system. +``GSL_VERSION`` + The version of the discovered GSL installation. ``GSL_INCLUDE_DIRS`` Directory containing GSL header files. ``GSL_LIBRARIES`` The GSL libraries. -``GSL_VERSION`` - The version of the discovered GSL installation. - -Hints -^^^^^ - -``GSL_ROOT_DIR`` - Set this variable to a directory that contains a GSL installation. - - If this variable is not set, this module will use pkg-config and default paths - to find GSL. If this variable is provided, then this module expects to find - libraries at ``${GSL_ROOT_DIR}/lib`` and the GSL headers at - ``${GSL_ROOT_DIR}/include/gsl``. - - The library directory may optionally provide Release and Debug folders. If - available, the libraries named ``gsld``, ``gslblasd`` or ``cblasd`` are - recognized as debug libraries. For Unix-like systems, this module will also - use ``gsl-config`` (if found) to aid in the discovery of GSL. Cache Variables ^^^^^^^^^^^^^^^ @@ -72,6 +64,24 @@ ``GSL_LIBRARY_DEBUG`` Location of the debug GSL library (if any). +Hints +^^^^^ + +This module accepts the following variables: + +``GSL_ROOT_DIR`` + Set this variable to a directory that contains a GSL installation. + + If this variable is not set, this module will use pkg-config and default paths + to find GSL. If this variable is provided, then this module expects to find + libraries at ``${GSL_ROOT_DIR}/lib`` and the GSL headers at + ``${GSL_ROOT_DIR}/include/gsl``. + + The library directory may optionally provide Release and Debug folders. If + available, the libraries named ``gsld``, ``gslblasd`` or ``cblasd`` are + recognized as debug libraries. For Unix-like systems, this module will also + use ``gsl-config`` (if found) to aid in the discovery of GSL. + Examples ^^^^^^^^ @@ -105,7 +115,7 @@ # This will return ``GSL_INCLUDEDIR`` and ``GSL_LIBDIR`` used below. if( GSL_USE_PKGCONFIG ) find_package(PkgConfig QUIET) - if(PKG_CONFIG_FOUND) + if(PkgConfig_FOUND) pkg_check_modules( GSL QUIET gsl ) if( EXISTS "${GSL_INCLUDEDIR}" ) get_filename_component( GSL_ROOT_DIR "${GSL_INCLUDEDIR}" DIRECTORY CACHE) @@ -174,8 +184,6 @@ endif() #============================================================================= -# handle the QUIETLY and REQUIRED arguments and set GSL_FOUND to TRUE if all -# listed variables are TRUE find_package_handle_standard_args( GSL REQUIRED_VARS GSL_INCLUDE_DIR
diff --git a/Modules/FindGTK.cmake b/Modules/FindGTK.cmake index 6e39f5a..87325e2 100644 --- a/Modules/FindGTK.cmake +++ b/Modules/FindGTK.cmake
@@ -5,10 +5,6 @@ FindGTK ------- -Finds GTK, glib and GTKGLArea. - -GTK is a multi-platform toolkit for creating graphical user interfaces. - .. note:: This module works only on Unix-like systems and was intended for early GTK @@ -22,15 +18,23 @@ pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk4>=4.14) target_link_libraries(example PRIVATE PkgConfig::GTK) +Finds GTK, glib and GTKGLArea: + +.. code-block:: cmake + + find_package(GTK [...]) + +GTK is a multi-platform toolkit for creating graphical user interfaces. + Result Variables ^^^^^^^^^^^^^^^^ This module defines the following variables: ``GTK_FOUND`` - Boolean indicating whether GTK is found. + Boolean indicating whether GTK was found. ``GTK_GL_FOUND`` - Boolean indicating whether GTK's GL features are found. + Boolean indicating whether GTK's GL features were found. ``GTK_INCLUDE_DIR`` Include directories containing headers needed to use GTK. ``GTK_LIBRARIES``
diff --git a/Modules/FindGTK2.cmake b/Modules/FindGTK2.cmake index 9c5bc63..2cbb3a6 100644 --- a/Modules/FindGTK2.cmake +++ b/Modules/FindGTK2.cmake
@@ -5,14 +5,10 @@ FindGTK2 -------- -Finds the GTK widget libraries and several of its other optional components. - -GTK is a multi-platform toolkit for creating graphical user interfaces. - .. note:: - This module is specifically for GTK version 2.x, which is obsolete and no - longer maintained. Use the latest supported GTK version and + This module is intended specifically for GTK version 2.x, which is obsolete + and no longer maintained. Use the latest supported GTK version and :module:`FindPkgConfig` module to find GTK in CMake instead of this module. For example: @@ -22,6 +18,14 @@ pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk4>=4.14) target_link_libraries(example PRIVATE PkgConfig::GTK) +Finds the GTK widget libraries and several of its other optional components: + +.. code-block:: cmake + + find_package(GTK2 [<version>] [COMPONENTS <components>...] [...]) + +GTK is a multi-platform toolkit for creating graphical user interfaces. + Components ^^^^^^^^^^ @@ -93,7 +97,8 @@ This module defines the following variables: ``GTK2_FOUND`` - Boolean indicating whether GTK and all specified components are found. + Boolean indicating whether (the requested version of) GTK 2 and all + specified components were found. ``GTK2_VERSION`` The version of GTK found (x.y.z). ``GTK2_MAJOR_VERSION`` @@ -703,7 +708,7 @@ # used to compute the arch-specific include prefixes. While at it, # also retrieve their INCLUDEDIR, to accommodate non-standard layouts. find_package(PkgConfig QUIET) -if(PKG_CONFIG_FOUND) +if(PkgConfig_FOUND) pkg_check_modules(PC_GTK2 QUIET gtk+-2.0) if(PC_GTK2_FOUND) pkg_get_variable(PC_GTK2_INCLUDEDIR gtk+-2.0 includedir)
diff --git a/Modules/FindGTest.cmake b/Modules/FindGTest.cmake index 3043768..f8fda89 100644 --- a/Modules/FindGTest.cmake +++ b/Modules/FindGTest.cmake
@@ -78,7 +78,9 @@ This module defines the following variables: ``GTest_FOUND`` - Boolean indicating whether GoogleTest is found. + .. versionadded:: 3.3 + + Boolean indicating whether GoogleTest was found. Hints ^^^^^ @@ -150,6 +152,12 @@ Result variable providing both ``gtest`` and ``gtest_main`` libraries combined. +``GTEST_FOUND`` + .. deprecated:: 4.2 + Use ``GTest_FOUND``, which has the same value. + + Boolean indicating whether GoogleTest was found. + Deprecated Imported Targets """""""""""""""""""""""""""
diff --git a/Modules/FindGettext.cmake b/Modules/FindGettext.cmake index 71d41e0..347d30d 100644 --- a/Modules/FindGettext.cmake +++ b/Modules/FindGettext.cmake
@@ -10,7 +10,7 @@ .. code-block:: cmake - find_package(Gettext [<version>] ...) + find_package(Gettext [<version>] [...]) GNU gettext is a system for internationalization (i18n) and localization (l10n), consisting of command-line tools and a runtime library (``libintl``). @@ -36,11 +36,13 @@ This module defines the following variables: ``Gettext_FOUND`` - Boolean indicating whether (the requested version of) gettext is found. For - backward compatibility, the ``GETTEXT_FOUND`` variable is also set to the same - value. + .. versionadded:: 3.3 -``GETTEXT_VERSION_STRING`` + Boolean indicating whether (the requested version of) gettext was found. + +``Gettext_VERSION`` + .. versionadded:: 4.2 + The version of gettext found. Cache Variables @@ -194,6 +196,23 @@ For better control over build and installation behavior, use :command:`gettext_process_po_files` instead. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``GETTEXT_FOUND`` + .. deprecated:: 4.2 + Use ``Gettext_FOUND``, which has the same value. + + Boolean indicating whether (the requested version of) gettext was found. + +``GETTEXT_VERSION_STRING`` + .. deprecated:: 4.2 + Superseded by the ``Gettext_VERSION``. + + The version of gettext found. + Examples ^^^^^^^^ @@ -398,7 +417,8 @@ get_filename_component(msgmerge_name ${GETTEXT_MSGMERGE_EXECUTABLE} NAME) get_filename_component(msgmerge_namewe ${GETTEXT_MSGMERGE_EXECUTABLE} NAME_WE) if(gettext_version MATCHES "^(${msgmerge_name}|${msgmerge_namewe}) \\([^\\)]*\\) ([0-9\\.]+[^ \n]*)") - set(GETTEXT_VERSION_STRING "${CMAKE_MATCH_2}") + set(Gettext_VERSION "${CMAKE_MATCH_2}") + set(GETTEXT_VERSION_STRING "${Gettext_VERSION}") endif() unset(gettext_version) unset(msgmerge_name) @@ -408,7 +428,7 @@ include(FindPackageHandleStandardArgs) find_package_handle_standard_args(Gettext REQUIRED_VARS GETTEXT_MSGMERGE_EXECUTABLE GETTEXT_MSGFMT_EXECUTABLE - VERSION_VAR GETTEXT_VERSION_STRING) + VERSION_VAR Gettext_VERSION) function(_GETTEXT_GET_UNIQUE_TARGET_NAME _name _unique_name) set(propertyName "_GETTEXT_UNIQUE_COUNTER_${_name}")
diff --git a/Modules/FindGit.cmake b/Modules/FindGit.cmake index 2b6187e..978746b 100644 --- a/Modules/FindGit.cmake +++ b/Modules/FindGit.cmake
@@ -5,7 +5,11 @@ FindGit ------- -Finds the Git distributed version control system. +Finds the Git distributed version control system: + +.. code-block:: cmake + + find_package(Git [<version>] [...]) Imported Targets ^^^^^^^^^^^^^^^^ @@ -27,9 +31,13 @@ This module defines the following variables: ``Git_FOUND`` - Boolean indicating whether the Git was found. For backward compatibility, the - ``GIT_FOUND`` variable is also set to the same value. -``GIT_VERSION_STRING`` + .. versionadded:: 3.3 + + Boolean indicating whether (the requested version of) Git was found. + +``Git_VERSION`` + .. versionadded:: 4.2 + The version of Git found. Cache Variables @@ -40,6 +48,23 @@ ``GIT_EXECUTABLE`` Path to the ``git`` command-line client executable. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``GIT_FOUND`` + .. deprecated:: 4.2 + Use ``Git_FOUND``, which has the same value. + + Boolean indicating whether (the requested version of) Git was found. + +``GIT_VERSION_STRING`` + .. deprecated:: 4.2 + Use ``Git_VERSION``, which has the same value. + + The version of Git found. + Examples ^^^^^^^^ @@ -124,7 +149,8 @@ list(GET __gitVersionProp 0 __gitExe) list(GET __gitVersionProp 1 __gitVersion) if(__gitExe STREQUAL GIT_EXECUTABLE AND NOT __gitVersion STREQUAL "") - set(GIT_VERSION_STRING "${__gitVersion}") + set(Git_VERSION "${__gitVersion}") + set(GIT_VERSION_STRING "${Git_VERSION}") set(__doGitVersionCheck FALSE) endif() unset(__gitExe) @@ -138,9 +164,10 @@ ERROR_QUIET OUTPUT_STRIP_TRAILING_WHITESPACE) if (git_version MATCHES "^git version [0-9]") - string(REPLACE "git version " "" GIT_VERSION_STRING "${git_version}") + string(REPLACE "git version " "" Git_VERSION "${git_version}") + set(GIT_VERSION_STRING "${Git_VERSION}") set_property(GLOBAL PROPERTY _CMAKE_FindGit_GIT_EXECUTABLE_VERSION - "${GIT_EXECUTABLE};${GIT_VERSION_STRING}" + "${GIT_EXECUTABLE};${Git_VERSION}" ) endif() unset(git_version) @@ -158,4 +185,4 @@ include(FindPackageHandleStandardArgs) find_package_handle_standard_args(Git REQUIRED_VARS GIT_EXECUTABLE - VERSION_VAR GIT_VERSION_STRING) + VERSION_VAR Git_VERSION)
diff --git a/Modules/FindGnuTLS.cmake b/Modules/FindGnuTLS.cmake index d9d8260..a0c2c85 100644 --- a/Modules/FindGnuTLS.cmake +++ b/Modules/FindGnuTLS.cmake
@@ -5,12 +5,17 @@ FindGnuTLS ---------- -Finds the GNU Transport Layer Security library (GnuTLS). The GnuTLS -package includes the main libraries (libgnutls and libdane), as well as the -optional gnutls-openssl compatibility extra library. They are all distributed -as part of the same release. This module checks for the presence of the main -libgnutls library and provides usage requirements for integrating GnuTLS into -CMake projects. +Finds the GNU Transport Layer Security library (GnuTLS): + +.. code-block:: cmake + + find_package(GnuTLS [<version>] [...]) + +The GnuTLS package includes the main libraries (libgnutls and libdane), as +well as the optional gnutls-openssl compatibility extra library. They are +all distributed as part of the same release. This module checks for the +presence of the main libgnutls library and provides usage requirements for +integrating GnuTLS into CMake projects. Imported Targets ^^^^^^^^^^^^^^^^ @@ -29,12 +34,12 @@ This module defines the following variables: ``GnuTLS_FOUND`` - Boolean indicating whether the (requested version of) GnuTLS is found. For - backward compatibility, the ``GNUTLS_FOUND`` variable is also set to the same - value. + .. versionadded:: 3.3 -``GNUTLS_VERSION`` - .. versionadded:: 3.16 + Boolean indicating whether (the requested version of) GnuTLS was found. + +``GnuTLS_VERSION`` + .. versionadded:: 4.2 The version of GnuTLS found. @@ -61,13 +66,22 @@ Deprecated Variables ^^^^^^^^^^^^^^^^^^^^ -These variables are provided for backward compatibility: +The following variables are provided for backward compatibility: + +``GNUTLS_FOUND`` + .. deprecated:: 4.2 + Use ``GnuTLS_FOUND``, which has the same value. + + Boolean indicating whether (the requested version of) GnuTLS was found. ``GNUTLS_VERSION_STRING`` .. deprecated:: 3.16 - Superseded by ``GNUTLS_VERSION``. + Use the ``GnuTLS_VERSION``, which has the same value. - The version of GnuTLS found. +``GNUTLS_VERSION`` + .. versionadded:: 3.16 + .. deprecated:: 4.2 + Use the ``GnuTLS_VERSION``, which has the same value. Examples ^^^^^^^^ @@ -80,6 +94,9 @@ target_link_libraries(project_target PRIVATE GnuTLS::GnuTLS) #]=======================================================================] +cmake_policy(PUSH) +cmake_policy(SET CMP0159 NEW) # file(STRINGS) with REGEX updates CMAKE_MATCH_<n> + if (GNUTLS_INCLUDE_DIR AND GNUTLS_LIBRARY) # in cache already set(gnutls_FIND_QUIETLY TRUE) @@ -90,13 +107,10 @@ # in the find_path() and find_library() calls # also fills in GNUTLS_DEFINITIONS, although that isn't normally useful find_package(PkgConfig QUIET) - if(PKG_CONFIG_FOUND) + if(PkgConfig_FOUND) pkg_check_modules(PC_GNUTLS QUIET gnutls) endif() set(GNUTLS_DEFINITIONS ${PC_GNUTLS_CFLAGS_OTHER}) - set(GNUTLS_VERSION ${PC_GNUTLS_VERSION}) - # keep for backward compatibility - set(GNUTLS_VERSION_STRING ${PC_GNUTLS_VERSION}) endif () find_path(GNUTLS_INCLUDE_DIR gnutls/gnutls.h @@ -113,10 +127,43 @@ mark_as_advanced(GNUTLS_INCLUDE_DIR GNUTLS_LIBRARY) +if(GNUTLS_INCLUDE_DIR AND EXISTS "${GNUTLS_INCLUDE_DIR}/gnutls/gnutls.h") + file( + STRINGS + "${GNUTLS_INCLUDE_DIR}/gnutls/gnutls.h" + gnutls_version + # GnuTLS versions prior to 2.7.2 defined LIBGNUTLS_VERSION instead of the + # current GNUTLS_VERSION. + REGEX "^#define[\t ]+(LIB)?GNUTLS_VERSION[\t ]+\".*\"" + ) + + string( + REGEX REPLACE + "^.*GNUTLS_VERSION[\t ]+\"([^\"]*)\".*$" + "\\1" + GnuTLS_VERSION + "${gnutls_version}" + ) + unset(gnutls_version) + + # Fallback to version defined by pkg-config if not successful. + if( + NOT GnuTLS_VERSION + AND PC_GNUTLS_VERSION + AND GNUTLS_INCLUDE_DIR IN_LIST PC_GNUTLS_INCLUDE_DIRS + ) + set(GnuTLS_VERSION "${PC_GNUTLS_VERSION}") + endif() + + # For backward compatibility. + set(GNUTLS_VERSION "${GnuTLS_VERSION}") + set(GNUTLS_VERSION_STRING "${GnuTLS_VERSION}") +endif() + include(FindPackageHandleStandardArgs) find_package_handle_standard_args(GnuTLS REQUIRED_VARS GNUTLS_LIBRARY GNUTLS_INCLUDE_DIR - VERSION_VAR GNUTLS_VERSION_STRING) + VERSION_VAR GnuTLS_VERSION) if(GnuTLS_FOUND) set(GNUTLS_LIBRARIES ${GNUTLS_LIBRARY}) @@ -131,3 +178,5 @@ IMPORTED_LOCATION "${GNUTLS_LIBRARIES}") endif() endif() + +cmake_policy(POP)
diff --git a/Modules/FindGnuplot.cmake b/Modules/FindGnuplot.cmake index abbb681..f5bf309 100644 --- a/Modules/FindGnuplot.cmake +++ b/Modules/FindGnuplot.cmake
@@ -6,18 +6,25 @@ ----------- Finds the Gnuplot command-line graphing utility for generating two- and -three-dimensional plots (``gnuplot``). +three-dimensional plots (``gnuplot``): + +.. code-block:: cmake + + find_package(Gnuplot [<version>] [...]) Result Variables ^^^^^^^^^^^^^^^^ -This module sets the following variables: +This module defines the following variables: ``Gnuplot_FOUND`` - Boolean indicating whether Gnuplot has been found. For backward - compatibility, the ``GNUPLOT_FOUND`` variable is also set to the same value. + .. versionadded:: 3.3 -``GNUPLOT_VERSION_STRING`` + Boolean indicating whether (the requested version of) Gnuplot was found. + +``Gnuplot_VERSION`` + .. versionadded:: 4.2 + The version of Gnuplot found. .. note:: @@ -33,14 +40,34 @@ ``GNUPLOT_EXECUTABLE`` Absolute path to the ``gnuplot`` executable. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``GNUPLOT_FOUND`` + .. deprecated:: 4.2 + Use ``Gnuplot_FOUND``, which has the same value. + + Boolean indicating whether (the requested version of) Gnuplot was found. + +``GNUPLOT_VERSION_STRING`` + .. deprecated:: 4.2 + Superseded by the ``Gnuplot_VERSION``. + + The version of Gnuplot found. + Examples ^^^^^^^^ -Finding Gnuplot: +Finding Gnuplot and executing it in a process: .. code-block:: cmake find_package(Gnuplot) + if(Gnuplot_FOUND) + execute_process(COMMAND ${GNUPLOT_EXECUTABLE} --help) + endif() #]=======================================================================] include(${CMAKE_CURRENT_LIST_DIR}/FindCygwin.cmake) @@ -62,8 +89,9 @@ ERROR_QUIET OUTPUT_STRIP_TRAILING_WHITESPACE) - string(REGEX REPLACE "^gnuplot ([0-9\\.]+)( patchlevel )?" "\\1." GNUPLOT_VERSION_STRING "${GNUPLOT_OUTPUT_VARIABLE}") - string(REGEX REPLACE "\\.$" "" GNUPLOT_VERSION_STRING "${GNUPLOT_VERSION_STRING}") + string(REGEX REPLACE "^gnuplot ([0-9\\.]+)( patchlevel )?" "\\1." Gnuplot_VERSION "${GNUPLOT_OUTPUT_VARIABLE}") + string(REGEX REPLACE "\\.$" "" Gnuplot_VERSION "${Gnuplot_VERSION}") + set(GNUPLOT_VERSION_STRING "${Gnuplot_VERSION}") unset(GNUPLOT_OUTPUT_VARIABLE) endif() @@ -73,6 +101,6 @@ include(FindPackageHandleStandardArgs) find_package_handle_standard_args(Gnuplot REQUIRED_VARS GNUPLOT_EXECUTABLE - VERSION_VAR GNUPLOT_VERSION_STRING) + VERSION_VAR Gnuplot_VERSION) mark_as_advanced( GNUPLOT_EXECUTABLE )
diff --git a/Modules/FindHDF5.cmake b/Modules/FindHDF5.cmake index a49e994..0a15557 100644 --- a/Modules/FindHDF5.cmake +++ b/Modules/FindHDF5.cmake
@@ -10,7 +10,7 @@ .. code-block:: cmake - find_package(HDF5 [<version>] ... [COMPONENTS <components>...] ...) + find_package(HDF5 [<version>] [COMPONENTS <components>...] [...]) If the HDF5 library is built using its CMake-based build system, it will as of HDF5 version 1.8.15 provide its own CMake Package Configuration file @@ -71,8 +71,9 @@ ``HDF5::HDF5`` .. versionadded:: 3.19 - Target encapsulating the usage requirements for all found HDF5 libraries - (``HDF5_LIBRARIES``), available if HDF5 and all required components are found. + Target encapsulating the usage requirements for all found HDF5 binding + libraries (``HDF5_LIBRARIES``), available if HDF5 and all required components + are found. ``hdf5::hdf5`` .. versionadded:: 3.19 @@ -126,7 +127,7 @@ This module defines the following variables: ``HDF5_FOUND`` - Boolean indicating whether (the requested version of) HDF5 is found. + Boolean indicating whether (the requested version of) HDF5 was found. ``HDF5_VERSION`` .. versionadded:: 3.3 @@ -682,7 +683,16 @@ if(HDF5_FIND_DEBUG) message(STATUS "Found HDF5 at ${HDF5_DIR} via NO_MODULE. Now trying to extract locations etc.") endif() - set(HDF5_IS_PARALLEL ${HDF5_ENABLE_PARALLEL}) + # Extract information from imported targets + if (DEFINED HDF5_ENABLE_PARALLEL) + # Versions of <2.0.0 use `HDF5_ENABLE_PARALLEL` + set(HDF5_IS_PARALLEL ${HDF5_ENABLE_PARALLEL}) + elseif(DEFINED HDF5_PROVIDES_PARALLEL) + # Versions of >=2.0.0 use `HDF5_PROVIDES_PARALLEL` + set(HDF5_IS_PARALLEL ${HDF5_PROVIDES_PARALLEL}) + else() + set(HDF5_IS_PARALLEL NONE) + endif() set(HDF5_INCLUDE_DIRS ${HDF5_INCLUDE_DIR}) set(HDF5_LIBRARIES) if (NOT TARGET hdf5 AND NOT TARGET hdf5-static AND NOT TARGET hdf5-shared)
diff --git a/Modules/FindHSPELL.cmake b/Modules/FindHSPELL.cmake index f326f33..d759216 100644 --- a/Modules/FindHSPELL.cmake +++ b/Modules/FindHSPELL.cmake
@@ -5,7 +5,11 @@ FindHSPELL ---------- -Finds Hebrew spell-checker (Hspell) and morphology engine. +Finds the Hebrew spell-checker and morphology engine (Hspell): + +.. code-block:: cmake + + find_package(HSPELL [<version>] [...]) Result Variables ^^^^^^^^^^^^^^^^ @@ -13,13 +17,18 @@ This module defines the following variables: ``HSPELL_FOUND`` - Boolean indicating whether the Hspell is found. -``HSPELL_VERSION_STRING`` + Boolean indicating whether (the requested version of) Hspell was found. + +``HSPELL_VERSION`` + .. versionadded:: 4.2 + The version of Hspell found (x.y). -``HSPELL_MAJOR_VERSION`` - The major version of Hspell. -``HSPELL_MINOR_VERSION`` - The minor version of Hspell. + +``HSPELL_VERSION_MAJOR`` + The major version of Hspell found. + +``HSPELL_VERSION_MINOR`` + The minor version of Hspell found. Cache Variables ^^^^^^^^^^^^^^^ @@ -28,9 +37,21 @@ ``HSPELL_INCLUDE_DIR`` The Hspell include directory. + ``HSPELL_LIBRARIES`` The libraries needed to use Hspell. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``HSPELL_VERSION_STRING`` + .. deprecated:: 4.2 + Use ``HSPELL_VERSION``, which has the same value. + + The version of Hspell found (x.y). + Examples ^^^^^^^^ @@ -52,14 +73,15 @@ file(STRINGS "${HSPELL_INCLUDE_DIR}/hspell.h" HSPELL_H REGEX "#define HSPELL_VERSION_M(AJO|INO)R [0-9]+") string(REGEX REPLACE ".*#define HSPELL_VERSION_MAJOR ([0-9]+).*" "\\1" HSPELL_VERSION_MAJOR "${HSPELL_H}") string(REGEX REPLACE ".*#define HSPELL_VERSION_MINOR ([0-9]+).*" "\\1" HSPELL_VERSION_MINOR "${HSPELL_H}") - set(HSPELL_VERSION_STRING "${HSPELL_VERSION_MAJOR}.${HSPELL_VERSION_MINOR}") + set(HSPELL_VERSION "${HSPELL_VERSION_MAJOR}.${HSPELL_VERSION_MINOR}") + set(HSPELL_VERSION_STRING "${HSPELL_VERSION}") unset(HSPELL_H) endif() include(FindPackageHandleStandardArgs) find_package_handle_standard_args(HSPELL REQUIRED_VARS HSPELL_LIBRARIES HSPELL_INCLUDE_DIR - VERSION_VAR HSPELL_VERSION_STRING) + VERSION_VAR HSPELL_VERSION) mark_as_advanced(HSPELL_INCLUDE_DIR HSPELL_LIBRARIES)
diff --git a/Modules/FindHTMLHelp.cmake b/Modules/FindHTMLHelp.cmake index 76b3dcf..cb9b62c 100644 --- a/Modules/FindHTMLHelp.cmake +++ b/Modules/FindHTMLHelp.cmake
@@ -5,8 +5,12 @@ FindHTMLHelp ------------ -This module finds the Microsoft HTML Help Compiler and its API. It is part of -the HTML Help Workshop. +Finds the Microsoft HTML Help Compiler and its API which is part of the HTML +Help Workshop: + +.. code-block:: cmake + + find_package(HTMLHelp [...]) .. note:: @@ -14,10 +18,20 @@ For modern documentation, consider alternatives such as Microsoft Help Viewer for producing ``.mshc`` files or web-based documentation tools. +Result Variables +^^^^^^^^^^^^^^^^ + +This module defines the following variables: + +``HTMLHelp_FOUND`` + .. versionadded:: 4.2 + + Boolean indicating whether HTML Help was found. + Cache Variables ^^^^^^^^^^^^^^^ -This module may set the following cache variables: +The following cache variables may also be set: ``HTML_HELP_COMPILER`` Full path to the HTML Help Compiler (``hhc.exe``), used to compile ``.chm`` @@ -74,3 +88,9 @@ ) endif() + +if(HTML_HELP_COMPILER AND HTML_HELP_INCLUDE_PATH AND HTML_HELP_LIBRARY) + set(HTMLHelp_FOUND TRUE) +else() + set(HTMLHelp_FOUND FALSE) +endif()
diff --git a/Modules/FindHg.cmake b/Modules/FindHg.cmake index f4f3074..06fe7dc 100644 --- a/Modules/FindHg.cmake +++ b/Modules/FindHg.cmake
@@ -18,11 +18,14 @@ This module defines the following variables: ``Hg_FOUND`` - Boolean indicating whether (the requested version of) Mercurial client is - found. For backward compatibility, the ``HG_FOUND`` variable is also set - to the same value. + .. versionadded:: 3.3 -``HG_VERSION_STRING`` + Boolean indicating whether the (requested version of) Mercurial client was + found. + +``Hg_VERSION`` + .. versionadded:: 4.2 + The version of Mercurial found. Cache Variables @@ -58,6 +61,24 @@ ``<var-prefix>_WC_REVISION`` Current revision. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``HG_FOUND`` + .. deprecated:: 4.2 + Use ``Hg_FOUND``, which has the same value. + + Boolean indicating whether the (requested version of) Mercurial client was + found. + +``HG_VERSION_STRING`` + .. deprecated:: 4.2 + Use ``Hg_VERSION``, which has the same value. + + The version of Mercurial found. + Examples ^^^^^^^^ @@ -103,7 +124,8 @@ set_property(CACHE HG_EXECUTABLE PROPERTY VALUE "HG_EXECUTABLE-NOTFOUND") endif() if(hg_version MATCHES "^Mercurial Distributed SCM \\(version ([0-9][^)]*)\\)") - set(HG_VERSION_STRING "${CMAKE_MATCH_1}") + set(Hg_VERSION "${CMAKE_MATCH_1}") + set(HG_VERSION_STRING "${Hg_VERSION}") endif() unset(hg_version) @@ -126,4 +148,4 @@ include(FindPackageHandleStandardArgs) find_package_handle_standard_args(Hg REQUIRED_VARS HG_EXECUTABLE - VERSION_VAR HG_VERSION_STRING) + VERSION_VAR Hg_VERSION)
diff --git a/Modules/FindICU.cmake b/Modules/FindICU.cmake index 942a0ae..97d766d 100644 --- a/Modules/FindICU.cmake +++ b/Modules/FindICU.cmake
@@ -7,7 +7,11 @@ .. versionadded:: 3.7 -Finds the International Components for Unicode (ICU) libraries and programs. +Finds the International Components for Unicode (ICU) libraries and programs: + +.. code-block:: cmake + + find_package(ICU [<version>] COMPONENTS <components>... [...]) .. versionadded:: 3.11 Support for static libraries on Windows. @@ -15,7 +19,13 @@ Components ^^^^^^^^^^ -This module supports the following components: +This module supports components, which can be specified with: + +.. code-block:: cmake + + find_package(ICU COMPONENTS <components>...) + +The following components are supported: ``data`` Finds the ICU Data library. On Windows, this library component is named @@ -49,12 +59,8 @@ all other ICU libraries and is recommended to include when working with ICU components. -At least one component should be specified for this module to successfully find -ICU: - -.. code-block:: cmake - - find_package(ICU COMPONENTS <components>...) +At least one component should be specified for this module to successfully +find ICU. Imported Targets ^^^^^^^^^^^^^^^^ @@ -74,13 +80,14 @@ This module defines the following variables: ``ICU_FOUND`` - Boolean indicating whether the main programs and libraries were found. + Boolean indicating whether the (requested version of) main ICU programs + and libraries were found. +``ICU_VERSION`` + The version of the ICU release found. ``ICU_INCLUDE_DIRS`` The include directories containing the ICU headers. ``ICU_LIBRARIES`` Component libraries to be linked. -``ICU_VERSION`` - The version of the ICU release found. ICU programs are defined in the following variables:
diff --git a/Modules/FindIce.cmake b/Modules/FindIce.cmake index 8215674..a0be791 100644 --- a/Modules/FindIce.cmake +++ b/Modules/FindIce.cmake
@@ -7,7 +7,12 @@ .. versionadded:: 3.1 -Finds the Internet Communication Engine (Ice) programs, libraries and datafiles. +Finds the Internet Communication Engine (Ice) programs, libraries and datafiles: + +.. code-block:: cmake + + find_package(Ice [<version>] COMPONENTS <components>... [...]) + Ice is an open-source remote procedure call (RPC) framework developed by ZeroC and provides SDKs for various languages to develop network applications. @@ -88,8 +93,8 @@ This module defines the following variables: ``Ice_FOUND`` - Boolean indicating whether the main programs, libraries and all requested - components for using Ice were found. + Boolean indicating whether the (requested version of) main programs, + libraries and all requested components for using Ice were found. ``Ice_VERSION`` The version of Ice release found. @@ -107,7 +112,7 @@ Ice component libraries are stored in: ``Ice_<COMPONENT>_FOUND`` - Boolean indicating whether the specified Ice component is found. The + Boolean indicating whether the specified Ice component was found. The ``<COMPONENT>`` should be written in uppercase. ``Ice_<COMPONENT>_LIBRARIES``
diff --git a/Modules/FindIconv.cmake b/Modules/FindIconv.cmake index a11d746..d49c2db 100644 --- a/Modules/FindIconv.cmake +++ b/Modules/FindIconv.cmake
@@ -7,9 +7,14 @@ .. versionadded:: 3.11 -This module finds the ``iconv()`` POSIX.1 functions on the system. These -functions might be provided in the standard C library or externally in the form -of an additional library. +Finds the ``iconv()`` POSIX.1 functions on the system: + +.. code-block:: cmake + + find_package(Iconv [<version>] [...]) + +Iconv functions might be provided in the standard C library or externally +in the form of an additional library. Imported Targets ^^^^^^^^^^^^^^^^ @@ -26,13 +31,8 @@ This module defines the following variables: ``Iconv_FOUND`` - Boolean indicating if the iconv support was found. - -``Iconv_INCLUDE_DIRS`` - The include directories containing the iconv headers. - -``Iconv_LIBRARIES`` - The iconv libraries to be linked. + Boolean indicating whether the (requested version of) iconv support was + found. ``Iconv_VERSION`` .. versionadded:: 3.21 @@ -53,17 +53,23 @@ The minor version of iconv. -``Iconv_IS_BUILT_IN`` - A boolean variable indicating whether iconv support is stemming from the C - standard library or not. Even if the C library provides ``iconv()``, the - presence of an external ``libiconv`` implementation might lead to this being - false. +``Iconv_INCLUDE_DIRS`` + The include directories containing the iconv headers. + +``Iconv_LIBRARIES`` + The iconv libraries to be linked. Cache Variables ^^^^^^^^^^^^^^^ The following cache variables may also be set: +``Iconv_IS_BUILT_IN`` + A boolean variable indicating whether iconv support is stemming from the C + standard library or not. Even if the C library provides ``iconv()``, the + presence of an external ``libiconv`` implementation might lead to this being + false. + ``Iconv_INCLUDE_DIR`` The directory containing the iconv headers.
diff --git a/Modules/FindIcotool.cmake b/Modules/FindIcotool.cmake index 92dfe7f..ea9cb04 100644 --- a/Modules/FindIcotool.cmake +++ b/Modules/FindIcotool.cmake
@@ -6,7 +6,11 @@ ----------- Finds ``icotool``, command-line program for converting and creating Win32 icon -and cursor files. +and cursor files: + +.. code-block:: cmake + + find_package(Icotool [<version>] [...]) Result Variables ^^^^^^^^^^^^^^^^ @@ -14,9 +18,14 @@ This module defines the following variables: ``Icotool_FOUND`` - True if ``icotool`` has been found. For backward compatibility, the - ``ICOTOOL_FOUND`` variable is also set to the same value. -``ICOTOOL_VERSION_STRING`` + .. versionadded:: 3.3 + + Boolean indicating whether (the requested version of) ``icotool`` was + found. + +``Icotool_VERSION`` + .. versionadded:: 4.2 + The version of ``icotool`` found. Cache Variables @@ -27,6 +36,24 @@ ``ICOTOOL_EXECUTABLE`` The full path to the ``icotool`` tool. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``ICOTOOL_FOUND`` + .. deprecated:: 4.2 + Use ``Icotool_FOUND``, which has the same value. + + Boolean indicating whether (the requested version of) ``icotool`` was + found. + +``ICOTOOL_VERSION_STRING`` + .. deprecated:: 4.2 + Use ``Icotool_VERSION``, which has the same value. + + The version of ``icotool`` found. + Examples ^^^^^^^^ @@ -51,27 +78,23 @@ if(ICOTOOL_EXECUTABLE) execute_process( COMMAND ${ICOTOOL_EXECUTABLE} --version - OUTPUT_VARIABLE _icotool_version + OUTPUT_VARIABLE Icotool_VERSION ERROR_QUIET OUTPUT_STRIP_TRAILING_WHITESPACE ) - if("${_icotool_version}" MATCHES "^icotool \\([^\\)]*\\) ([0-9\\.]+[^ \n]*)") - set( ICOTOOL_VERSION_STRING - "${CMAKE_MATCH_1}" - ) + if("${Icotool_VERSION}" MATCHES "^icotool \\([^\\)]*\\) ([0-9\\.]+[^ \n]*)") + set(Icotool_VERSION "${CMAKE_MATCH_1}") else() - set( ICOTOOL_VERSION_STRING - "" - ) + set(Icotool_VERSION "") endif() - unset(_icotool_version) + set(ICOTOOL_VERSION_STRING "${Icotool_VERSION}") endif() include(FindPackageHandleStandardArgs) find_package_handle_standard_args( Icotool REQUIRED_VARS ICOTOOL_EXECUTABLE - VERSION_VAR ICOTOOL_VERSION_STRING + VERSION_VAR Icotool_VERSION ) mark_as_advanced(
diff --git a/Modules/FindImageMagick.cmake b/Modules/FindImageMagick.cmake index 8289d6d..c34ebdb 100644 --- a/Modules/FindImageMagick.cmake +++ b/Modules/FindImageMagick.cmake
@@ -6,7 +6,11 @@ --------------- Finds ImageMagick, a software suite for displaying, converting, and manipulating -raster images. +raster images: + +.. code-block:: cmake + + find_package(ImageMagick [<version>] [COMPONENTS <components>...] [...]) .. versionadded:: 3.9 Support for ImageMagick 7. @@ -78,11 +82,15 @@ This module defines the following variables: ``ImageMagick_FOUND`` - Boolean indicating whether ImageMagick and all its requested components are - found. + Boolean indicating whether (the requested version of) ImageMagick and all + its requested components were found. -``ImageMagick_VERSION_STRING`` - The version of ImageMagick found. +``ImageMagick_VERSION`` + .. versionadded:: 4.2 + + The version of ImageMagick found in form of + ``<major>.<minor>.<patch>-<addendum>`` (e.g., ``6.9.12-98``, where ``98`` + is the addendum release number). .. note:: @@ -127,6 +135,17 @@ ``ImageMagick_EXECUTABLE_DIR`` The full path to directory containing ImageMagick executables. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``ImageMagick_VERSION_STRING`` + .. deprecated:: 4.2 + Use ``ImageMagick_VERSION``, which has the same value. + + The version of ImageMagick found. + Examples ^^^^^^^^ @@ -139,6 +158,10 @@ target_link_libraries(example PRIVATE ImageMagick::Magick++) #]=======================================================================] +cmake_policy(PUSH) +cmake_policy(SET CMP0140 NEW) +cmake_policy(SET CMP0159 NEW) # file(STRINGS) with REGEX updates CMAKE_MATCH_<n> + find_package(PkgConfig QUIET) #--------------------------------------------------------------------- @@ -147,7 +170,7 @@ function(FIND_IMAGEMAGICK_API component header) set(ImageMagick_${component}_FOUND FALSE PARENT_SCOPE) - if(PKG_CONFIG_FOUND) + if(PkgConfig_FOUND) pkg_check_modules(PC_${component} QUIET ${component}) endif() @@ -253,6 +276,66 @@ endif() endfunction() +function(_ImageMagick_GetVersion) + unset(version) + + if(ImageMagick_mogrify_EXECUTABLE) + execute_process( + COMMAND ${ImageMagick_mogrify_EXECUTABLE} -version + OUTPUT_VARIABLE version + ERROR_QUIET + OUTPUT_STRIP_TRAILING_WHITESPACE + ) + + if(version MATCHES "^Version: ImageMagick ([-0-9.]+)") + set(version "${CMAKE_MATCH_1}") + endif() + elseif(ImageMagick_INCLUDE_DIRS) + # MagickLibSubversion was used in ImageMagick <= 6.5. + set( + regex + "^[\t ]*#[\t ]*define[\t ]+(MagickLibVersionText|MagickLibAddendum|MagickLibSubversion)[\t ]+\"([-0-9.]+)\"" + ) + + foreach(dir IN LISTS ImageMagick_INCLUDE_DIRS) + foreach(subdir IN ITEMS MagickCore magick) + if(EXISTS ${dir}/${subdir}/version.h) + file(STRINGS "${dir}/${subdir}/version.h" results REGEX "${regex}") + + foreach(line ${results}) + if(line MATCHES "${regex}") + if(DEFINED version) + string(APPEND version "${CMAKE_MATCH_2}") + else() + set(version "${CMAKE_MATCH_2}") + endif() + + if(CMAKE_MATCH_1 STREQUAL "MagickLibAddendum") + break() + endif() + endif() + endforeach() + endif() + + if(DEFINED version) + break() + endif() + endforeach() + + if(DEFINED version) + break() + endif() + endforeach() + endif() + + if(DEFINED version) + set(ImageMagick_VERSION "${version}") + set(ImageMagick_VERSION_STRING "${ImageMagick_VERSION}") + endif() + + return(PROPAGATE ImageMagick_VERSION ImageMagick_VERSION_STRING) +endfunction() + #--------------------------------------------------------------------- # Start Actual Work #--------------------------------------------------------------------- @@ -340,16 +423,7 @@ set(ImageMagick_INCLUDE_DIRS ${ImageMagick_INCLUDE_DIRS}) set(ImageMagick_LIBRARIES ${ImageMagick_LIBRARIES}) -if(ImageMagick_mogrify_EXECUTABLE) - execute_process(COMMAND ${ImageMagick_mogrify_EXECUTABLE} -version - OUTPUT_VARIABLE imagemagick_version - ERROR_QUIET - OUTPUT_STRIP_TRAILING_WHITESPACE) - if(imagemagick_version MATCHES "^Version: ImageMagick ([-0-9\\.]+)") - set(ImageMagick_VERSION_STRING "${CMAKE_MATCH_1}") - endif() - unset(imagemagick_version) -endif() +_ImageMagick_GetVersion() #--------------------------------------------------------------------- # Standard Package Output @@ -357,7 +431,7 @@ include(FindPackageHandleStandardArgs) find_package_handle_standard_args(ImageMagick REQUIRED_VARS ${ImageMagick_REQUIRED_VARS} - VERSION_VAR ImageMagick_VERSION_STRING + VERSION_VAR ImageMagick_VERSION ) #--------------------------------------------------------------------- @@ -383,3 +457,5 @@ IMAGEMAGICK_MONTAGE_EXECUTABLE IMAGEMAGICK_COMPOSITE_EXECUTABLE ) + +cmake_policy(POP)
diff --git a/Modules/FindIntl.cmake b/Modules/FindIntl.cmake index cdc6541..7fd0afd 100644 --- a/Modules/FindIntl.cmake +++ b/Modules/FindIntl.cmake
@@ -8,9 +8,15 @@ .. versionadded:: 3.2 Finds internationalization support that includes message translation functions -such as ``gettext()``. These functions originate from the GNU ``libintl`` -library, which is part of the GNU gettext utilities, but may also be provided by -the standard C library. +such as ``gettext()``: + +.. code-block:: cmake + + find_package(Intl [<version>] [...]) + +These functions originate from the GNU ``libintl`` library, which is part +of the GNU gettext utilities, but may also be provided by the standard C +library. Imported Targets ^^^^^^^^^^^^^^^^ @@ -28,13 +34,7 @@ This module defines the following variables: ``Intl_FOUND`` - Boolean indicating whether the Intl is found. - -``Intl_INCLUDE_DIRS`` - Include directories containing headers needed to use Intl. - -``Intl_LIBRARIES`` - The libraries needed to link against to use Intl. + Boolean indicating whether (the requested version of) Intl was found. ``Intl_VERSION`` .. versionadded:: 3.21 @@ -61,23 +61,29 @@ The patch version of Intl found. +``Intl_INCLUDE_DIRS`` + Include directories containing headers needed to use Intl. + +``Intl_LIBRARIES`` + The libraries needed to link against to use Intl. + Cache Variables ^^^^^^^^^^^^^^^ The following cache variables may also be set: -``Intl_INCLUDE_DIR`` - The directory containing the ``libintl.h`` header file. - -``Intl_LIBRARY`` - The path to the Intl library (if any). - ``Intl_IS_BUILT_IN`` .. versionadded:: 3.20 Boolean indicating whether the found Intl functionality is provided by the standard C library rather than a separate ``libintl`` library. +``Intl_INCLUDE_DIR`` + The directory containing the ``libintl.h`` header file. + +``Intl_LIBRARY`` + The path to the Intl library (if any). + .. note:: On some platforms, such as Linux with GNU libc, the gettext functions are present in the C standard library and libintl is not required. The
diff --git a/Modules/FindJNI.cmake b/Modules/FindJNI.cmake index 10dcc51..a70b00f 100644 --- a/Modules/FindJNI.cmake +++ b/Modules/FindJNI.cmake
@@ -5,7 +5,11 @@ FindJNI ------- -Finds the Java Native Interface (JNI) include directories and libraries. +Finds the Java Native Interface (JNI) include directories and libraries: + +.. code-block:: cmake + + find_package(JNI [<version>] [COMPONENTS <components>...] [...]) JNI enables Java code running in a Java Virtual Machine (JVM) or Dalvik Virtual Machine (DVM) on Android to call and be called by native applications and @@ -95,12 +99,12 @@ This module defines the following variables: ``JNI_FOUND`` - Boolean indicating whether the JNI is found. + Boolean indicating whether (the requested version of) JNI was found. ``JNI_<component>_FOUND`` .. versionadded:: 3.24 - Boolean indicating whether the ``<component>`` is found. + Boolean indicating whether the ``<component>`` was found. ``JNI_VERSION`` Full Android NDK package version (including suffixes such as ``-beta3`` and @@ -381,6 +385,11 @@ # Arch Linux specific paths for default JVM /usr/lib/jvm/default # Ubuntu specific paths for default JVM + /usr/lib/jvm/java-26-openjdk-{libarch} + /usr/lib/jvm/java-25-openjdk-{libarch} # Ubuntu 24.04 LTS + /usr/lib/jvm/java-24-openjdk-{libarch} + /usr/lib/jvm/java-23-openjdk-{libarch} + /usr/lib/jvm/java-22-openjdk-{libarch} /usr/lib/jvm/java-21-openjdk-{libarch} # Ubuntu 23.04 /usr/lib/jvm/java-20-openjdk-{libarch} # Ubuntu 22.10 /usr/lib/jvm/java-19-openjdk-{libarch} # Ubuntu 22.04 LTS
diff --git a/Modules/FindJPEG.cmake b/Modules/FindJPEG.cmake index 9d43f58..c5687ea 100644 --- a/Modules/FindJPEG.cmake +++ b/Modules/FindJPEG.cmake
@@ -5,7 +5,11 @@ FindJPEG -------- -Finds the Joint Photographic Experts Group (JPEG) library (``libjpeg``). +Finds the Joint Photographic Experts Group (JPEG) library (``libjpeg``): + +.. code-block:: cmake + + find_package(JPEG [<version>] [...]) .. versionchanged:: 3.12 Debug and Release JPEG library variants are now found separately. @@ -24,10 +28,16 @@ Result Variables ^^^^^^^^^^^^^^^^ -This module sets the following variables: +This module defines the following variables: ``JPEG_FOUND`` - Boolean indicating whether the JPEG is found. + Boolean indicating whether the (requested version of) JPEG library was + found. + +``JPEG_VERSION`` + .. versionadded:: 3.12 + + The version of JPEG library found. ``JPEG_INCLUDE_DIRS`` Include directories containing headers needed to use JPEG. @@ -35,18 +45,13 @@ ``JPEG_LIBRARIES`` Libraries needed to link to JPEG. -``JPEG_VERSION`` - .. versionadded:: 3.12 - - The version of the JPEG library found. - Cache Variables ^^^^^^^^^^^^^^^ The following cache variables may also be set: ``JPEG_INCLUDE_DIR`` - Directory containing the ``jpeglib.h`` and related header files. + Directory containing the ``<jpeglib.h>`` and related header files. ``JPEG_LIBRARY_RELEASE`` .. versionadded:: 3.12 @@ -58,13 +63,13 @@ Path to the debug variant of the JPEG library. -Obsolete Variables -^^^^^^^^^^^^^^^^^^ +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ -The following legacy variables are provided for backward compatibility: +The following variables are provided for backward compatibility: ``JPEG_LIBRARY`` - .. versionchanged:: 3.12 + .. deprecated:: 3.12 This variable has been superseded by the ``JPEG_LIBRARY_RELEASE`` and ``JPEG_LIBRARY_DEBUG`` variables.
diff --git a/Modules/FindJasper.cmake b/Modules/FindJasper.cmake index 3902f6d..a19179c 100644 --- a/Modules/FindJasper.cmake +++ b/Modules/FindJasper.cmake
@@ -6,7 +6,11 @@ ---------- Finds the JasPer Image Coding Toolkit for handling image data in a variety of -formats, such as the JPEG-2000. +formats, such as the JPEG-2000: + +.. code-block:: cmake + + find_package(Jasper [<version>] [...]) Imported Targets ^^^^^^^^^^^^^^^^ @@ -25,8 +29,14 @@ This module defines the following variables: ``Jasper_FOUND`` - Boolean indicating whether the JasPer is found. For backward compatibility, - the ``JASPER_FOUND`` variable is also set to the same value. + .. versionadded:: 3.3 + + Boolean indicating whether (the requested version of) JasPer was found. + +``Jasper_VERSION`` + .. versionadded:: 4.2 + + The version of JasPer found. ``JASPER_INCLUDE_DIRS`` .. versionadded:: 3.22 @@ -36,9 +46,6 @@ ``JASPER_LIBRARIES`` The libraries needed to use JasPer. -``JASPER_VERSION_STRING`` - The version of JasPer found. - Cache Variables ^^^^^^^^^^^^^^^ @@ -54,6 +61,23 @@ ``JASPER_LIBRARY_DEBUG`` The path to the debug variant of the JasPer library. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``JASPER_FOUND`` + .. deprecated:: 4.2 + Use ``Jasper_FOUND``, which has the same value. + + Boolean indicating whether (the requested version of) JasPer was found. + +``JASPER_VERSION_STRING`` + .. deprecated:: 4.2 + Superseded by the ``Jasper_VERSION``. + + The version of JasPer found. + Examples ^^^^^^^^ @@ -81,13 +105,14 @@ if(JASPER_INCLUDE_DIR AND EXISTS "${JASPER_INCLUDE_DIR}/jasper/jas_config.h") file(STRINGS "${JASPER_INCLUDE_DIR}/jasper/jas_config.h" jasper_version_str REGEX "^#define[\t ]+JAS_VERSION[\t ]+\".*\".*") - string(REGEX REPLACE "^#define[\t ]+JAS_VERSION[\t ]+\"([^\"]+)\".*" "\\1" JASPER_VERSION_STRING "${jasper_version_str}") + string(REGEX REPLACE "^#define[\t ]+JAS_VERSION[\t ]+\"([^\"]+)\".*" "\\1" Jasper_VERSION "${jasper_version_str}") + set(JASPER_VERSION_STRING "${Jasper_VERSION}") endif() include(FindPackageHandleStandardArgs) find_package_handle_standard_args(Jasper REQUIRED_VARS JASPER_LIBRARIES JASPER_INCLUDE_DIR - VERSION_VAR JASPER_VERSION_STRING) + VERSION_VAR Jasper_VERSION) if(Jasper_FOUND) set(JASPER_LIBRARIES ${JASPER_LIBRARIES})
diff --git a/Modules/FindJava.cmake b/Modules/FindJava.cmake index 1587ce6..09e9fd7 100644 --- a/Modules/FindJava.cmake +++ b/Modules/FindJava.cmake
@@ -6,7 +6,11 @@ -------- Finds the Java installation and determines its runtime tools and development -components. +components: + +.. code-block:: cmake + + find_package(Java [<version>] [COMPONENTS <components>...] [...]) .. versionadded:: 3.10 Support for Java 9+ version parsing. @@ -14,7 +18,14 @@ Components ^^^^^^^^^^ -This module supports the following components: +This module supports optional components, which can be specified with the +:command:`find_package` command: + +.. code-block:: cmake + + find_package(Java [COMPONENTS <components>...]) + +Supported components include: ``Runtime`` Finds the Java Runtime Environment used to execute Java byte-compiled @@ -35,13 +46,7 @@ Finds the signer and verifier tool for Java Archive (JAR) files. -Components can optionally be specified using the standard syntax with: - -.. code-block:: cmake - - find_package(Java [COMPONENTS <components>...]) - -If no ``COMPONENTS`` are specified, the module searches for the ``Runtime`` +If no components are specified, the module searches for the ``Runtime`` component by default. Result Variables @@ -50,10 +55,13 @@ This module defines the following variables: ``Java_FOUND`` - Boolean indicating whether Java with all specified components is found. + .. versionadded:: 3.3 + + Boolean indicating whether (the requested version of) Java with all + specified components was found. ``Java_<component>_FOUND`` - Boolean indicating whether the ``<component>`` is found. + Boolean indicating whether the ``<component>`` was found. ``Java_VERSION`` Version of Java found. This is set to:
diff --git a/Modules/FindKDE3.cmake b/Modules/FindKDE3.cmake index ccfad5e..bc6b0e4 100644 --- a/Modules/FindKDE3.cmake +++ b/Modules/FindKDE3.cmake
@@ -13,9 +13,15 @@ `KDE documentation <https://develop.kde.org/docs/getting-started/building/cmake-build/>`_. -This module finds KDE 3 include directories, libraries, and KDE-specific -preprocessor tools. It provides usage requirements for building KDE 3 software -and defines several helper commands to simplify working with KDE 3 in CMake. +Finds KDE 3 include directories, libraries, and KDE-specific preprocessor +tools: + +.. code-block:: cmake + + find_package(KDE3 [...]) + +This module provides usage requirements for building KDE 3 software and +defines several helper commands to simplify working with KDE 3 in CMake. Result Variables ^^^^^^^^^^^^^^^^ @@ -23,7 +29,7 @@ This module defines the following variables: ``KDE3_FOUND`` - Boolean indicating whether KDE 3 is found. + Boolean indicating whether KDE 3 was found. ``KDE3_DEFINITIONS`` Compiler definitions required for compiling KDE 3 software. ``KDE3_INCLUDE_DIRS`` @@ -206,7 +212,7 @@ endif() # If Qt4 has already been found, fail. -if(QT4_FOUND) +if(Qt4_FOUND) if(KDE3_FIND_REQUIRED) message( FATAL_ERROR "KDE3/Qt3 and Qt4 cannot be used together in one project.") else()
diff --git a/Modules/FindKDE4.cmake b/Modules/FindKDE4.cmake index 220906b..04c76da 100644 --- a/Modules/FindKDE4.cmake +++ b/Modules/FindKDE4.cmake
@@ -5,27 +5,223 @@ FindKDE4 -------- +.. note:: + + This module is specifically intended for KDE version 4, which is obsolete + and no longer maintained. For modern application development using KDE + technologies with CMake, use a newer version of KDE, and refer to the + `KDE documentation + <https://develop.kde.org/docs/getting-started/building/cmake-build/>`_. + +Finds the KDE 4 installation: + +.. code-block:: cmake + + find_package(KDE4 [...]) + +This module is a wrapper around the following upstream KDE 4 modules: + +``FindKDE4Internal.cmake`` + + Upstream internal module, which finds the KDE 4 include directories, + libraries, and KDE-specific preprocessor tools. It provides usage + requirements for building KDE 4 software and defines several helper + commands to simplify working with KDE 4 in CMake. + +``KDE4Macros.cmake`` + Upstream utility module that defines all additional KDE4-specific + commands to use KDE 4 in CMake. For example: + ``kde4_automoc()``, ``kde4_add_executable()``, ``kde4_add_library()``, + ``kde4_add_ui_files()``, ``kde4_add_ui3_files()``, + ``kde4_add_kcfg_files()``, ``kde4_add_kdeinit_executable()``, etc. + +Upstream KDE 4 modules are installed by the KDE 4 distribution package in +``$KDEDIRS/share/apps/cmake/modules/``. This path is automatically +appended to the :variable:`CMAKE_MODULE_PATH` variable when calling +``find_package(KDE4)``, so any additional KDE 4 modules can be included in +the project with :command:`include`. For example: + +``KDE4Defaults.cmake`` + Upstream internal module that sets some CMake options which are useful, + but not required for building KDE 4 software. If these settings should + be used, include this module after finding KDE 4: + + .. code-block:: cmake + + find_package(KDE4) + include(KDE4Defaults) + +For usage details, refer to the upstream KDE 4 documentation. For example, +at the top of the ``FindKDE4Internal`` module a complete documentation is +available for all variables and commands these modules provide. + +Result Variables +^^^^^^^^^^^^^^^^ + +This module defines the following variables: + +``KDE4_FOUND`` + Boolean indicating whether KDE 4 was found. This variable is set by the + upstream ``FindKDE4Internal`` module. + +Hints +^^^^^ + +This module accepts the following variables before calling the +``find_package(KDE4)``: + +``ENV{KDEDIRS}`` + Environment variable containing the path to the KDE 4 installation. + +KDE 4 is searched in the following directories in the given order: + +* :variable:`CMAKE_INSTALL_PREFIX` variable +* ``KDEDIRS`` environment variable +* ``/opt/kde4`` path + +Examples +^^^^^^^^ + +Example: Basic Usage +"""""""""""""""""""" + +Finding KDE 4 as required and using it in CMake: + +.. code-block:: cmake + + find_package(KDE4 REQUIRED) + + set(sources main.cpp mywidget.cpp mypart.cpp) + + # The kde4_*() commands are provided by the KDE4Macros module, which is + # included automatically by FindKDE4, if KDE4 is found: + kde4_automoc(${sources}) + kde4_add_executable(example ${sources}) + + target_include_directories(example PRIVATE ${KDE4_INCLUDES}) + target_link_libraries(example PRIVATE ${KDE4_KDEUI_LIBS} ${KDE4_KPARTS_LIBS}) + + install(TARGETS example DESTINATION ${CMAKE_INSTALL_BINDIR}) + install(FILES kfoo.desktop DESTINATION ${XDG_APPS_DIR}) + +Example: Full Featured Example +"""""""""""""""""""""""""""""" + +In the following example this module is used to find KDE 4 installation. + +.. code-block:: cmake + + project(kfoo) + + find_package(KDE4 REQUIRED) + + # Append path from where to include local project modules if any: + list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake) + + include_directories(${KDE4_INCLUDE_DIRS}) + add_definitions(${KDE4_DEFINITIONS}) + + set(sources main.cpp myappl.cpp view.cpp) + + # If Qt designer UI files version 3 or 4 are available add them to the + # sources variable: + kde4_add_ui_files(sources maindialog.ui logindialog.ui) + kde4_add_ui3_files(sources printerdlg.ui previewdlg.ui) + + # If there are files for the kconfig_compiler add them this way: + kde4_add_kcfg_files(sources settings.kcfg) + + # When everything is listed, probably automoc is wanted: + kde4_automoc(${sources}) + + # Finally, specify what to build: + kde4_add_executable(kfoo ${sources}) -Find KDE4 and provide all necessary variables and macros to compile -software for it. It looks for KDE 4 in the following directories in -the given order: +The ``kde4_add_executable()`` command is a slightly extended version of the +CMake command :command:`add_executable`. Additionally, it does some more +``RPATH`` handling and supports the ``KDE4_ENABLE_FINAL`` variable. The +first argument is the name of the executable followed by a list of source +files. If a library needs to be created instead of an executable, the +``kde4_add_library()`` can be used. It is an extended version of the +:command:`add_library` command. It adds support for the +``KDE4_ENABLE_FINAL`` variable and under Windows it adds the +``-DMAKE_KFOO_LIB`` to the compile flags. -:: +.. code-block:: cmake - CMAKE_INSTALL_PREFIX - KDEDIRS - /opt/kde4 + find_package(KDE4 REQUIRED) + # ... + kde4_add_library(kfoo ${sources}) -Please look in ``FindKDE4Internal.cmake`` and ``KDE4Macros.cmake`` for more -information. They are installed with the KDE 4 libraries in -$KDEDIRS/share/apps/cmake/modules/. + # Optionally, set the library version number if needed: + set_target_properties(kfoo PROPERTIES VERSION 5.0.0 SOVERSION 5) -Author: Alexander Neundorf <neundorf@kde.org> +KDE is very modular, so if a KPart, a control center module, or an ioslave +needs to be created, here's how to do it: + +.. code-block:: cmake + + find_package(KDE4 REQUIRED) + # ... + kde4_add_plugin(kfoo ${sources}) + +Now, the application/library/plugin probably needs to link to some +libraries. For this use the standard :command:`target_link_libraries` +command. For every KDE library there are variables available in the form +of ``KDE4_FOO_LIBS``. Use them to get also all depending libraries: + +.. code-block:: cmake + + target_link_libraries(kfoo ${KDE4_KDEUI_LIBS} ${KDE4_KIO_LIBS}) + +Example: The kdeinit Executable +""""""""""""""""""""""""""""""" + +In the following example, the so called kdeinit executable is created. +The ``kde4_add_kdeinit_executable()`` command creates both an executable +with the given name and a library with the given name prefixed with +``kdeinit_``. The :command:`target_link_libraries` command adds all +required libraries to the ``kdeinit_kbar`` library, and then links the +``kbar`` against the ``kdeinit_kbar``: + +.. code-block:: cmake + + find_package(KDE4 REQUIRED) + + # ... + + kde4_add_kdeinit_executable(kbar ${kbarSources}) + target_link_libraries(kdeinit_kbar ${KDE4_KIO_LIBS}) + target_link_libraries(kbar kdeinit_kbar) + + install(TARGETS kbar DESTINATION ${CMAKE_INSTALL_BINDIR}) + install(TARGETS kdeinit_kbar DESTINATION ${CMAKE_INSTALL_LIBDIR}) + +Example: Removing Compile Definitions +""""""""""""""""""""""""""""""""""""" + +Sometimes, a default compile definition passed to the compiler needs to be +removed. The :command:`remove_definitions` command can be used. For +example, by default, the KDE4 build system sets the ``-DQT_NO_STL`` flag. +If the project code uses some of the Qt STL compatibility layer, this flag +should be removed: + +.. code-block:: cmake + + find_package(KDE4 REQUIRED) + + add_definitions(${KDE4_DEFINITIONS}) + + # ... + + remove_definitions(-DQT_NO_STL) #]=======================================================================] +# Author: Alexander Neundorf <neundorf@kde.org> + # If Qt3 has already been found, fail. if(QT_QT_LIBRARY) if(KDE4_FIND_REQUIRED) @@ -100,4 +296,6 @@ if (KDE4_FIND_REQUIRED) message(FATAL_ERROR "ERROR: cmake/modules/FindKDE4Internal.cmake not found in ${_data_DIR}") endif () + + set(KDE4_FOUND FALSE) endif ()
diff --git a/Modules/FindLAPACK.cmake b/Modules/FindLAPACK.cmake index 8bd5121..52b13d9 100644 --- a/Modules/FindLAPACK.cmake +++ b/Modules/FindLAPACK.cmake
@@ -5,35 +5,68 @@ FindLAPACK ---------- -Find Linear Algebra PACKage (LAPACK) library +Finds the installed Linear Algebra PACKage (LAPACK) Fortran library that +implements the `LAPACK linear-algebra interface`_: -This module finds an installed Fortran library that implements the -`LAPACK linear-algebra interface`_. +.. code-block:: cmake + + find_package(LAPACK [...]) At least one of the ``C``, ``CXX``, or ``Fortran`` languages must be enabled. .. _`LAPACK linear-algebra interface`: https://netlib.org/lapack/ +Imported Targets +^^^^^^^^^^^^^^^^ + +This module provides the following :ref:`Imported Targets`: + +``LAPACK::LAPACK`` + .. versionadded:: 3.18 + + Target encapsulating the LAPACK usage requirements, available only if + LAPACK is found. + +Result Variables +^^^^^^^^^^^^^^^^ + +This module defines the following variables: + +``LAPACK_FOUND`` + Boolean indicating whether the library implementing the LAPACK interface + was found. +``LAPACK_LINKER_FLAGS`` + Uncached list of required linker flags (excluding ``-l`` and ``-L``). +``LAPACK_LIBRARIES`` + Uncached list of libraries (using full path name) to link against to use + LAPACK. +``LAPACK95_LIBRARIES`` + Uncached list of libraries (using full path name) to link against to use + LAPACK95. +``LAPACK95_FOUND`` + Boolean indicating whether the library implementing the LAPACK95 interface + was found. + Input Variables ^^^^^^^^^^^^^^^ The following variables may be set to influence this module's behavior: ``BLA_STATIC`` - if ``ON`` use static linkage + If ``ON``, the static linkage will be used. ``BLA_VENDOR`` Set to one of the :ref:`BLAS/LAPACK Vendors` to search for BLAS only from the specified vendor. If not set, all vendors are considered. ``BLA_F95`` - if ``ON`` tries to find the BLAS95/LAPACK95 interfaces + If ``ON``, the module tries to find the BLAS95/LAPACK95 interfaces. ``BLA_PREFER_PKGCONFIG`` .. versionadded:: 3.20 - if set ``pkg-config`` will be used to search for a LAPACK library first - and if one is found that is preferred + If set, ``pkg-config`` will be used to search for a LAPACK library first + and if one is found that is preferred. ``BLA_PKGCONFIG_LAPACK`` .. versionadded:: 3.25 @@ -41,7 +74,6 @@ If set, the ``pkg-config`` method will look for this module name instead of just ``lapack``. - ``BLA_SIZEOF_INTEGER`` .. versionadded:: 3.22 @@ -70,34 +102,6 @@ This is currently only supported by NVIDIA NVPL. -Imported Targets -^^^^^^^^^^^^^^^^ - -This module defines the following :prop_tgt:`IMPORTED` targets: - -``LAPACK::LAPACK`` - .. versionadded:: 3.18 - - The libraries to use for LAPACK, if found. - -Result Variables -^^^^^^^^^^^^^^^^ - -This module defines the following variables: - -``LAPACK_FOUND`` - library implementing the LAPACK interface is found -``LAPACK_LINKER_FLAGS`` - uncached list of required linker flags (excluding ``-l`` and ``-L``). -``LAPACK_LIBRARIES`` - uncached list of libraries (using full path name) to link against - to use LAPACK -``LAPACK95_LIBRARIES`` - uncached list of libraries (using full path name) to link against - to use LAPACK95 -``LAPACK95_FOUND`` - library implementing the LAPACK95 interface is found - Intel MKL ^^^^^^^^^ @@ -115,6 +119,15 @@ establish an Intel MKL environment. See the :module:`FindBLAS` module section on :ref:`Intel MKL` for details. +Examples +^^^^^^^^ + +Finding LAPACK and linking it to a project target: + +.. code-block:: cmake + + find_package(LAPACK) + target_link_libraries(project_target PRIVATE LAPACK::LAPACK) #]=======================================================================] # The approach follows that of the ``autoconf`` macro file, ``acx_lapack.m4`` @@ -314,7 +327,7 @@ set(BLA_PKGCONFIG_LAPACK "lapack") endif() find_package(PkgConfig QUIET) - if(PKG_CONFIG_FOUND) + if(PkgConfig_FOUND) pkg_check_modules(PKGC_LAPACK QUIET ${BLA_PKGCONFIG_LAPACK}) if(PKGC_LAPACK_FOUND) set(LAPACK_FOUND TRUE)
diff --git a/Modules/FindLATEX.cmake b/Modules/FindLATEX.cmake index e272770..7db4fc6 100644 --- a/Modules/FindLATEX.cmake +++ b/Modules/FindLATEX.cmake
@@ -5,8 +5,14 @@ FindLATEX --------- -Finds LaTeX compiler and Latex-related software like BibTeX. LaTeX is a -typesetting system for the production of technical and scientific documentation. +Finds LaTeX compiler and Latex-related software like BibTeX: + +.. code-block:: cmake + + find_package(LATEX [...]) + +LaTeX is a typesetting system for the production of technical and scientific +documentation. Components ^^^^^^^^^^ @@ -40,7 +46,7 @@ Finds the MakeIndex compiler. ``XINDY`` - Find the xindy compiler. + Finds the xindy compiler. ``DVIPS`` Finds the DVI-to-PostScript (DVIPS) converter. @@ -49,7 +55,7 @@ Finds the DVIPDF converter. ``PS2PDF`` - Finds the the PS2PDF converter. + Finds the PS2PDF converter. ``PDFTOPS`` Finds the PDF-to-PostScript converter. @@ -67,10 +73,10 @@ ``LATEX_FOUND`` Boolean indicating whether the LaTex compiler and all its required components - are found. + were found. ``LATEX_<component>_FOUND`` - Boolean indicating whether the LaTeX ``<component>`` is found. + Boolean indicating whether the LaTeX ``<component>`` was found. Cache Variables ^^^^^^^^^^^^^^^ @@ -84,12 +90,12 @@ The path to the PdfLaTeX compiler. ``XELATEX_COMPILER`` - .. versionadded: 3.2 + .. versionadded:: 3.2 The path to the XeLaTeX compiler. ``LUALATEX_COMPILER`` - .. versionadded: 3.2 + .. versionadded:: 3.2 The path to the LuaLaTeX compiler. @@ -97,7 +103,7 @@ The path to the BibTeX compiler. ``BIBER_COMPILER`` - .. versionadded: 3.2 + .. versionadded:: 3.2 The path to the Biber compiler. @@ -105,7 +111,7 @@ The path to the MakeIndex compiler. ``XINDY_COMPILER`` - .. versionadded: 3.2 + .. versionadded:: 3.2 The path to the xindy compiler. @@ -119,7 +125,7 @@ The path to the PS2PDF converter. ``PDFTOPS_CONVERTER`` - .. versionadded: 3.2 + .. versionadded:: 3.2 The path to the pdftops converter. @@ -127,7 +133,7 @@ The path to the LaTeX2Html converter. ``HTLATEX_COMPILER`` - .. versionadded: 3.2 + .. versionadded:: 3.2 The path to the htlatex compiler.
diff --git a/Modules/FindLTTngUST.cmake b/Modules/FindLTTngUST.cmake index 14aa766..6d024bc 100644 --- a/Modules/FindLTTngUST.cmake +++ b/Modules/FindLTTngUST.cmake
@@ -8,12 +8,16 @@ .. versionadded:: 3.6 Finds the `LTTng <https://lttng.org/>`_ (Linux Trace Toolkit: next generation) -user space tracing library (LTTng-UST). +user space tracing library (LTTng-UST): + +.. code-block:: cmake + + find_package(LTTngUST [<version>] [...]) Imported Targets ^^^^^^^^^^^^^^^^ -This module defines the following :ref:`Imported Targets`: +This module provides the following :ref:`Imported Targets`: ``LTTng::UST`` Target providing the LTTng-UST library usage requirements. This target is @@ -22,15 +26,20 @@ Result Variables ^^^^^^^^^^^^^^^^ -This module sets the following variables: +This module defines the following variables: ``LTTngUST_FOUND`` - Boolean indicating whether the LTTng-UST library is found. For backward - compatibility, the ``LTTNGUST_FOUND`` variable is also set to the same value. -``LTTNGUST_VERSION_STRING`` + Boolean indicating whether the (requested version of) LTTng-UST library + was found. + +``LTTngUST_VERSION`` + .. versionadded:: 4.2 + The LTTng-UST version. + ``LTTNGUST_HAS_TRACEF`` ``TRUE`` if the ``tracef()`` API is available in the system's LTTng-UST. + ``LTTNGUST_HAS_TRACELOG`` ``TRUE`` if the ``tracelog()`` API is available in the system's LTTng-UST. @@ -44,6 +53,24 @@ ``LTTNGUST_LIBRARIES`` The libraries needed to use LTTng-UST. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``LTTNGUST_FOUND`` + .. deprecated:: 4.2 + Use ``LTTngUST_FOUND``, which has the same value. + + Boolean indicating whether the (requested version of) LTTng-UST library + was found. + +``LTTNGUST_VERSION_STRING`` + .. deprecated:: 4.2 + Superseded by the ``LTTngUST_VERSION``. + + The LTTng-UST version. + Examples ^^^^^^^^ @@ -90,8 +117,9 @@ lttngust_v_minor "${lttngust_version_minor_string}") string(REGEX REPLACE ".*[\t ]+([0-9]+).*" "\\1" lttngust_v_patch "${lttngust_version_patch_string}") - set(LTTNGUST_VERSION_STRING + set(LTTngUST_VERSION "${lttngust_v_major}.${lttngust_v_minor}.${lttngust_v_patch}") + set(LTTNGUST_VERSION_STRING "${LTTngUST_VERSION}") unset(lttngust_version_major_string) unset(lttngust_version_minor_string) unset(lttngust_version_patch_string) @@ -119,7 +147,7 @@ find_package_handle_standard_args(LTTngUST REQUIRED_VARS LTTNGUST_LIBRARIES LTTNGUST_INCLUDE_DIRS - VERSION_VAR LTTNGUST_VERSION_STRING) + VERSION_VAR LTTngUST_VERSION) mark_as_advanced(LTTNGUST_LIBRARIES LTTNGUST_INCLUDE_DIRS) cmake_policy(POP)
diff --git a/Modules/FindLibArchive.cmake b/Modules/FindLibArchive.cmake index 9072d95..5f006e6 100644 --- a/Modules/FindLibArchive.cmake +++ b/Modules/FindLibArchive.cmake
@@ -5,18 +5,24 @@ FindLibArchive -------------- -Finds the libarchive library and include directories. Libarchive is a -multi-format archive and compression library. +Finds the libarchive library and include directories: -Import Targets -^^^^^^^^^^^^^^ +.. code-block:: cmake -This module defines the following :ref:`Imported Targets`: + find_package(LibArchive [<version>] [...]) + +Libarchive is a multi-format archive and compression library. + +Imported Targets +^^^^^^^^^^^^^^^^ + +This module provides the following :ref:`Imported Targets`: ``LibArchive::LibArchive`` .. versionadded:: 3.17 - A target for linking against libarchive. + A target encapsulating the libarchive usage requirements, available only + if libarchive is found. Result Variables ^^^^^^^^^^^^^^^^ @@ -24,11 +30,8 @@ This module defines the following variables: ``LibArchive_FOUND`` - Boolean indicating whether libarchive was found. -``LibArchive_INCLUDE_DIRS`` - Include search path for using libarchive. -``LibArchive_LIBRARIES`` - Libraries to link against libarchive. + Boolean indicating whether (the requested version of) libarchive was found. + ``LibArchive_VERSION`` A 3-component version string (``major.minor.patch``) of libarchive found. @@ -40,10 +43,16 @@ only for libarchive versions 3.1 and earlier. In CMake 3.6 and newer, this variable will be set for all libarchive versions. +``LibArchive_INCLUDE_DIRS`` + Include search path for using libarchive. + +``LibArchive_LIBRARIES`` + Libraries to link against libarchive. + Examples ^^^^^^^^ -Finding LibArchive and linking it to a project target: +Finding libarchive and linking it to a project target: .. code-block:: cmake
diff --git a/Modules/FindLibLZMA.cmake b/Modules/FindLibLZMA.cmake index 3711214..95d2692 100644 --- a/Modules/FindLibLZMA.cmake +++ b/Modules/FindLibLZMA.cmake
@@ -5,8 +5,12 @@ FindLibLZMA ----------- -Finds the data compression library that implements the LZMA (Lempel–Ziv–Markov -chain algorithm) - liblzma. +Finds the liblzma, a data compression library that implements the LZMA +(Lempel-Ziv-Markov chain algorithm): + +.. code-block:: cmake + + find_package(LibLZMA [<version>] [...]) Imported Targets ^^^^^^^^^^^^^^^^ @@ -25,17 +29,21 @@ This module defines the following variables: ``LibLZMA_FOUND`` - Boolean indicating whether the liblzma is found. For backward compatibility, - the ``LIBLZMA_FOUND`` variable is also set to the same value. -``LIBLZMA_INCLUDE_DIRS`` - Include directories containing headers needed to use liblzma. -``LIBLZMA_LIBRARIES`` - Libraries needed to link against to use liblzma. -``LIBLZMA_VERSION`` - .. versionadded:: 3.26 + .. versionadded:: 3.3 + + Boolean indicating whether (the requested version of) liblzma was found. + +``LibLZMA_VERSION`` + .. versionadded:: 4.2 The version of liblzma found (available as a string, for example, ``5.0.3``). +``LIBLZMA_INCLUDE_DIRS`` + Include directories containing headers needed to use liblzma. + +``LIBLZMA_LIBRARIES`` + Libraries needed to link against to use liblzma. + Cache Variables ^^^^^^^^^^^^^^^ @@ -44,29 +52,53 @@ ``LIBLZMA_HAS_AUTO_DECODER`` Boolean sanity check result indicating whether the ``lzma_auto_decoder()`` function (automatic decoder functionality) is found in liblzma (required). + ``LIBLZMA_HAS_EASY_ENCODER`` Boolean sanity check result indicating whether the ``lzma_easy_encoder()`` function (basic encoder API) is found in liblzma (required). + ``LIBLZMA_HAS_LZMA_PRESET`` Boolean sanity check result indicating whether the ``lzma_lzma_preset()`` function (preset compression configuration) is found in liblzma (required). -Legacy Variables -^^^^^^^^^^^^^^^^ +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ The following variables are provided for backward compatibility: -``LIBLZMA_VERSION_MAJOR`` - The major version of liblzma found. -``LIBLZMA_VERSION_MINOR`` - The minor version of liblzma found. -``LIBLZMA_VERSION_PATCH`` - The patch version of liblzma found. -``LIBLZMA_VERSION_STRING`` +``LIBLZMA_FOUND`` + .. deprecated:: 4.2 + Use ``LibLZMA_FOUND``, which has the same value. + + Boolean indicating whether (the requested version of) liblzma was found. + +``LIBLZMA_VERSION`` + .. versionadded:: 3.26 + .. deprecated:: 4.2 + Superseded by the ``LibLZMA_VERSION``. + The version of liblzma found. - .. versionchanged:: 3.26 - Superseded by ``LIBLZMA_VERSION``. +``LIBLZMA_VERSION_STRING`` + .. deprecated:: 3.26 + Superseded by the ``LIBLZMA_VERSION`` (and ``LibLZMA_VERSION``). + + The version of liblzma found. + +``LIBLZMA_VERSION_MAJOR`` + .. deprecated:: 3.26 + + The major version of liblzma found. + +``LIBLZMA_VERSION_MINOR`` + .. deprecated:: 3.26 + + The minor version of liblzma found. + +``LIBLZMA_VERSION_PATCH`` + .. deprecated:: 3.26 + + The patch version of liblzma found. Examples ^^^^^^^^ @@ -99,8 +131,9 @@ string(REGEX REPLACE ".*#define LZMA_VERSION_MINOR ([0-9]+).*" "\\1" LIBLZMA_VERSION_MINOR "${LIBLZMA_HEADER_CONTENTS}") string(REGEX REPLACE ".*#define LZMA_VERSION_PATCH ([0-9]+).*" "\\1" LIBLZMA_VERSION_PATCH "${LIBLZMA_HEADER_CONTENTS}") - set(LIBLZMA_VERSION_STRING "${LIBLZMA_VERSION_MAJOR}.${LIBLZMA_VERSION_MINOR}.${LIBLZMA_VERSION_PATCH}") - set(LIBLZMA_VERSION ${LIBLZMA_VERSION_STRING}) + set(LibLZMA_VERSION "${LIBLZMA_VERSION_MAJOR}.${LIBLZMA_VERSION_MINOR}.${LIBLZMA_VERSION_PATCH}") + set(LIBLZMA_VERSION "${LibLZMA_VERSION}") + set(LIBLZMA_VERSION_STRING "${LibLZMA_VERSION}") unset(LIBLZMA_HEADER_CONTENTS) endif() @@ -131,7 +164,7 @@ LIBLZMA_HAS_AUTO_DECODER LIBLZMA_HAS_EASY_ENCODER LIBLZMA_HAS_LZMA_PRESET - VERSION_VAR LIBLZMA_VERSION + VERSION_VAR LibLZMA_VERSION ) mark_as_advanced( LIBLZMA_INCLUDE_DIR LIBLZMA_LIBRARY )
diff --git a/Modules/FindLibXml2.cmake b/Modules/FindLibXml2.cmake index f453021..05d198b 100644 --- a/Modules/FindLibXml2.cmake +++ b/Modules/FindLibXml2.cmake
@@ -5,7 +5,11 @@ FindLibXml2 ----------- -Finds the XML processing library (libxml2). +Finds the XML processing library (libxml2): + +.. code-block:: cmake + + find_package(LibXml2 [<version>] [...]) Imported Targets ^^^^^^^^^^^^^^^^ @@ -30,15 +34,32 @@ This module defines the following variables: ``LibXml2_FOUND`` - Boolean indicating whether the libxml2 library is found. + .. versionadded:: 3.3 + + Boolean indicating whether the (requested version of) libxml2 library was + found. + +``LibXml2_VERSION`` + .. versionadded:: 4.2 + + The version of the libxml2 found. + ``LIBXML2_INCLUDE_DIRS`` Include directories needed to use the libxml2 library. + ``LIBXML2_LIBRARIES`` Libraries needed to link against to use the libxml2 library. + ``LIBXML2_DEFINITIONS`` The compiler switches required for using libxml2. -``LIBXML2_VERSION_STRING`` - The version of the libxml2 found. + +Other Variables +^^^^^^^^^^^^^^^ + +``LibXml2_USE_STATIC_LIBS`` + .. versionadded:: 4.3 + + Set to ``TRUE`` to use static libraries. Default is ``FALSE``. Cache Variables ^^^^^^^^^^^^^^^ @@ -47,11 +68,31 @@ ``LIBXML2_INCLUDE_DIR`` The include directory containing libxml2 headers. + ``LIBXML2_LIBRARY`` The path to the libxml2 library. + ``LIBXML2_XMLLINT_EXECUTABLE`` The path to the XML checking tool ``xmllint`` coming with libxml2. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``LIBXML2_FOUND`` + .. deprecated:: 4.2 + Use ``LibXml2_FOUND``, which has the same value. + + Boolean indicating whether the (requested version of) libxml2 library was + found. + +``LIBXML2_VERSION_STRING`` + .. deprecated:: 4.2 + Superseded by the ``LibXml2_VERSION``. + + The version of the libxml2 found. + Examples ^^^^^^^^ @@ -69,7 +110,7 @@ # use pkg-config to get the directories and then use these values # in the find_path() and find_library() calls find_package(PkgConfig QUIET) -if(PKG_CONFIG_FOUND) +if(PkgConfig_FOUND) pkg_check_modules(PC_LIBXML QUIET libxml-2.0) endif() @@ -87,12 +128,27 @@ set(LIBXML2_LIBRARY ${LIBXML2_LIBRARIES}) endif() +# Support preference of static libs by adjusting CMAKE_FIND_LIBRARY_SUFFIXES +if(LibXml2_USE_STATIC_LIBS) + set(_libxml2_ORIG_CMAKE_FIND_LIBRARY_SUFFIXES ${CMAKE_FIND_LIBRARY_SUFFIXES}) + if(WIN32) + list(INSERT CMAKE_FIND_LIBRARY_SUFFIXES 0 .lib .a) + else() + set(CMAKE_FIND_LIBRARY_SUFFIXES .a) + endif() +endif() + find_library(LIBXML2_LIBRARY NAMES xml2 libxml2 libxml2_a HINTS ${PC_LIBXML_LIBDIR} ${PC_LIBXML_LIBRARY_DIRS} ) +# Restore the original find library ordering +if(LibXml2_USE_STATIC_LIBS) + set(CMAKE_FIND_LIBRARY_SUFFIXES ${_libxml2_ORIG_CMAKE_FIND_LIBRARY_SUFFIXES}) +endif() + find_program(LIBXML2_XMLLINT_EXECUTABLE xmllint) # for backwards compat. with KDE 4.0.x: set(XMLLINT_EXECUTABLE "${LIBXML2_XMLLINT_EXECUTABLE}") @@ -102,7 +158,8 @@ REGEX "^#define[\t ]+LIBXML_DOTTED_VERSION[\t ]+\".*\"") string(REGEX REPLACE "^#define[\t ]+LIBXML_DOTTED_VERSION[\t ]+\"([^\"]*)\".*" "\\1" - LIBXML2_VERSION_STRING "${libxml2_version_str}") + LibXml2_VERSION "${libxml2_version_str}") + set(LIBXML2_VERSION_STRING "${LibXml2_VERSION}") unset(libxml2_version_str) endif() @@ -123,7 +180,7 @@ include(FindPackageHandleStandardArgs) find_package_handle_standard_args(LibXml2 REQUIRED_VARS LIBXML2_LIBRARY LIBXML2_INCLUDE_DIR - VERSION_VAR LIBXML2_VERSION_STRING) + VERSION_VAR LibXml2_VERSION) mark_as_advanced(LIBXML2_INCLUDE_DIR LIBXML2_LIBRARY LIBXML2_XMLLINT_EXECUTABLE)
diff --git a/Modules/FindLibXslt.cmake b/Modules/FindLibXslt.cmake index d612c7d..c102e93 100644 --- a/Modules/FindLibXslt.cmake +++ b/Modules/FindLibXslt.cmake
@@ -6,7 +6,11 @@ ----------- Finds the XSL Transformations, Extensible Stylesheet Language Transformations -(XSLT) library (libxslt). +(XSLT) library (libxslt): + +.. code-block:: cmake + + find_package(LibXslt [<version>] [...]) Imported Targets ^^^^^^^^^^^^^^^^ @@ -33,11 +37,17 @@ Result Variables ^^^^^^^^^^^^^^^^ -This module sets the following variables: +This module defines the following variables: ``LibXslt_FOUND`` - Boolean indicating whether the libxslt is found. For backward compatibility, - the ``LIBXSLT_FOUND`` variable is also set to the same value. + .. versionadded:: 3.3 + + Boolean indicating whether (the requested version of) libxslt was found. + +``LibXslt_VERSION`` + .. versionadded:: 4.2 + + The version of libxslt found. ``LIBXSLT_LIBRARIES`` Libraries needed to link to libxslt. @@ -45,9 +55,6 @@ ``LIBXSLT_DEFINITIONS`` Compiler switches required for using libxslt. -``LIBXSLT_VERSION_STRING`` - Version of libxslt found. - ``LIBXSLT_EXSLT_LIBRARIES`` Libraries needed when linking against the exslt library. These are available and needed only when using exslt library. @@ -70,6 +77,23 @@ Full path to the XSLT processor executable ``xsltproc`` if found. This path is optional. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``LIBXSLT_FOUND`` + .. deprecated:: 4.2 + Use ``LibXslt_FOUND``, which has the same value. + + Boolean indicating whether (the requested version of) libxslt was found. + +``LIBXSLT_VERSION_STRING`` + .. deprecated:: 4.2 + Superseded by the ``LibXslt_VERSION``. + + The version of libxslt found. + Examples ^^^^^^^^ @@ -109,7 +133,7 @@ # use pkg-config to get the directories and then use these values # in the find_path() and find_library() calls find_package(PkgConfig QUIET) -if(PKG_CONFIG_FOUND) +if(PkgConfig_FOUND) pkg_check_modules(PC_LIBXSLT QUIET libxslt) endif() set(LIBXSLT_DEFINITIONS ${PC_LIBXSLT_CFLAGS_OTHER}) @@ -135,7 +159,7 @@ set(LIBXSLT_LIBRARIES ${LIBXSLT_LIBRARY}) -if(PKG_CONFIG_FOUND) +if(PkgConfig_FOUND) pkg_check_modules(PC_LIBXSLT_EXSLT QUIET libexslt) endif() set(LIBXSLT_EXSLT_DEFINITIONS ${PC_LIBXSLT_EXSLT_CFLAGS_OTHER}) @@ -159,20 +183,22 @@ find_program(LIBXSLT_XSLTPROC_EXECUTABLE xsltproc) if(PC_LIBXSLT_VERSION) - set(LIBXSLT_VERSION_STRING ${PC_LIBXSLT_VERSION}) + set(LibXslt_VERSION ${PC_LIBXSLT_VERSION}) + set(LIBXSLT_VERSION_STRING "${LibXslt_VERSION}") elseif(LIBXSLT_INCLUDE_DIR AND EXISTS "${LIBXSLT_INCLUDE_DIR}/libxslt/xsltconfig.h") file(STRINGS "${LIBXSLT_INCLUDE_DIR}/libxslt/xsltconfig.h" libxslt_version_str REGEX "^#define[\t ]+LIBXSLT_DOTTED_VERSION[\t ]+\".*\"") string(REGEX REPLACE "^#define[\t ]+LIBXSLT_DOTTED_VERSION[\t ]+\"([^\"]*)\".*" "\\1" - LIBXSLT_VERSION_STRING "${libxslt_version_str}") + LibXslt_VERSION "${libxslt_version_str}") + set(LIBXSLT_VERSION_STRING "${LibXslt_VERSION}") unset(libxslt_version_str) endif() include(FindPackageHandleStandardArgs) find_package_handle_standard_args(LibXslt REQUIRED_VARS LIBXSLT_LIBRARIES LIBXSLT_INCLUDE_DIR - VERSION_VAR LIBXSLT_VERSION_STRING) + VERSION_VAR LibXslt_VERSION) mark_as_advanced(LIBXSLT_INCLUDE_DIR LIBXSLT_LIBRARY
diff --git a/Modules/FindLibinput.cmake b/Modules/FindLibinput.cmake index f3e66af..5c420e9 100644 --- a/Modules/FindLibinput.cmake +++ b/Modules/FindLibinput.cmake
@@ -8,7 +8,11 @@ .. versionadded:: 3.14 Finds the libinput library which handles input devices in Wayland compositors -and provides a generic X.Org input driver. +and provides a generic X.Org input driver: + +.. code-block:: cmake + + find_package(Libinput [<version>] [...]) Imported Targets ^^^^^^^^^^^^^^^^ @@ -25,7 +29,7 @@ This module defines the following variables: ``Libinput_FOUND`` - Boolean indicating whether the (requested version of) libinput library is + Boolean indicating whether the (requested version of) libinput library was found. ``Libinput_VERSION`` The version of the libinput found. @@ -53,7 +57,7 @@ # Use pkg-config to get the directories and then use these values # in the FIND_PATH() and FIND_LIBRARY() calls find_package(PkgConfig QUIET) -if(PKG_CONFIG_FOUND) +if(PkgConfig_FOUND) pkg_check_modules(PKG_Libinput QUIET libinput) endif()
diff --git a/Modules/FindLua.cmake b/Modules/FindLua.cmake index 50f37f6..d37ad81 100644 --- a/Modules/FindLua.cmake +++ b/Modules/FindLua.cmake
@@ -5,11 +5,20 @@ FindLua ------- -Finds the Lua library. Lua is a embeddable scripting language. +Finds the Lua library: + +.. code-block:: cmake + + find_package(Lua [<version>] [...]) + +Lua is a embeddable scripting language. .. versionadded:: 3.18 Support for Lua 5.4. +.. versionadded:: 4.3 + Support for Lua 5.5. + When working with Lua, its library headers are intended to be included in project source code as: @@ -32,17 +41,30 @@ This module defines the following variables: ``Lua_FOUND`` - Boolean indicating whether (the requested version of) Lua is found. For - backward compatibility, the ``LUA_FOUND`` variable is also set to the same - value. -``LUA_VERSION_STRING`` + .. versionadded:: 3.3 + + Boolean indicating whether (the requested version of) Lua was found. + +``Lua_VERSION`` + .. versionadded:: 4.2 + The version of Lua found. -``LUA_VERSION_MAJOR`` + +``Lua_VERSION_MAJOR`` + .. versionadded:: 4.2 + The major version of Lua found. -``LUA_VERSION_MINOR`` + +``Lua_VERSION_MINOR`` + .. versionadded:: 4.2 + The minor version of Lua found. -``LUA_VERSION_PATCH`` + +``Lua_VERSION_PATCH`` + .. versionadded:: 4.2 + The patch version of Lua found. + ``LUA_LIBRARIES`` Libraries needed to link against to use Lua. This list includes both ``lua`` and ``lualib`` libraries. @@ -56,6 +78,41 @@ The directory containing the Lua header files, such as ``lua.h``, ``lualib.h``, and ``lauxlib.h``, needed to use Lua. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``LUA_FOUND`` + .. deprecated:: 4.2 + Use ``Lua_FOUND``, which has the same value. + + Boolean indicating whether (the requested version of) Lua was found. + +``LUA_VERSION_STRING`` + .. deprecated:: 4.2 + Superseded by the ``Lua_VERSION``. + + The version of Lua found. + +``LUA_VERSION_MAJOR`` + .. deprecated:: 4.2 + Superseded by the ``Lua_VERSION_MAJOR``. + + The major version of Lua found. + +``LUA_VERSION_MINOR`` + .. deprecated:: 4.2 + Superseded by the ``Lua_VERSION_MINOR``. + + The minor version of Lua found. + +``LUA_VERSION_PATCH`` + .. deprecated:: 4.2 + Superseded by the ``Lua_VERSION_PATCH``. + + The patch version of Lua found. + Examples ^^^^^^^^ @@ -81,6 +138,7 @@ #]=======================================================================] cmake_policy(PUSH) # Policies apply to functions at definition-time +cmake_policy(SET CMP0140 NEW) cmake_policy(SET CMP0159 NEW) # file(STRINGS) with REGEX updates CMAKE_MATCH_<n> unset(_lua_include_subdirs) @@ -89,7 +147,7 @@ # this is a function only to have all the variables inside go away automatically function(_lua_get_versions) - set(LUA_VERSIONS5 5.4 5.3 5.2 5.1 5.0) + set(LUA_VERSIONS5 5.5 5.4 5.3 5.2 5.1 5.0) if (Lua_FIND_VERSION_EXACT) if (Lua_FIND_VERSION_COUNT GREATER 1) @@ -146,7 +204,7 @@ endfunction() function(_lua_get_header_version) - unset(LUA_VERSION_STRING PARENT_SCOPE) + unset(Lua_VERSION PARENT_SCOPE) set(_hdr_file "${LUA_INCLUDE_DIR}/lua.h") if (NOT EXISTS "${_hdr_file}") @@ -159,27 +217,39 @@ file(STRINGS "${_hdr_file}" lua_version_strings REGEX "^#define[ \t]+LUA_(RELEASE[ \t]+\"Lua [0-9]|VERSION([ \t]+\"Lua [0-9]|_[MR])).*") - string(REGEX REPLACE ".*;#define[ \t]+LUA_VERSION_MAJOR[ \t]+\"([0-9])\"[ \t]*;.*" "\\1" LUA_VERSION_MAJOR ";${lua_version_strings};") - if (LUA_VERSION_MAJOR MATCHES "^[0-9]+$") - string(REGEX REPLACE ".*;#define[ \t]+LUA_VERSION_MINOR[ \t]+\"([0-9])\"[ \t]*;.*" "\\1" LUA_VERSION_MINOR ";${lua_version_strings};") - string(REGEX REPLACE ".*;#define[ \t]+LUA_VERSION_RELEASE[ \t]+\"([0-9])\"[ \t]*;.*" "\\1" LUA_VERSION_PATCH ";${lua_version_strings};") - set(LUA_VERSION_STRING "${LUA_VERSION_MAJOR}.${LUA_VERSION_MINOR}.${LUA_VERSION_PATCH}") + string(REGEX REPLACE ".*;#define[ \t]+LUA_VERSION_MAJOR(_N)?[ \t]+\"?([0-9])\"?[ \t]*;.*" "\\2" Lua_VERSION_MAJOR ";${lua_version_strings};") + + if (Lua_VERSION_MAJOR MATCHES "^[0-9]+$") + string(REGEX REPLACE ".*;#define[ \t]+LUA_VERSION_MINOR(_N)?[ \t]+\"?([0-9])\"?[ \t]*;.*" "\\2" Lua_VERSION_MINOR ";${lua_version_strings};") + string(REGEX REPLACE ".*;#define[ \t]+LUA_VERSION_RELEASE(_N)?[ \t]+\"?([0-9])\"?[ \t]*;.*" "\\2" Lua_VERSION_PATCH ";${lua_version_strings};") + set(Lua_VERSION "${Lua_VERSION_MAJOR}.${Lua_VERSION_MINOR}.${Lua_VERSION_PATCH}") else () - string(REGEX REPLACE ".*;#define[ \t]+LUA_RELEASE[ \t]+\"Lua ([0-9.]+)\"[ \t]*;.*" "\\1" LUA_VERSION_STRING ";${lua_version_strings};") - if (NOT LUA_VERSION_STRING MATCHES "^[0-9.]+$") - string(REGEX REPLACE ".*;#define[ \t]+LUA_VERSION[ \t]+\"Lua ([0-9.]+)\"[ \t]*;.*" "\\1" LUA_VERSION_STRING ";${lua_version_strings};") + string(REGEX REPLACE ".*;#define[ \t]+LUA_RELEASE[ \t]+\"Lua ([0-9.]+)\"[ \t]*;.*" "\\1" Lua_VERSION ";${lua_version_strings};") + if (NOT Lua_VERSION MATCHES "^[0-9.]+$") + string(REGEX REPLACE ".*;#define[ \t]+LUA_VERSION[ \t]+\"Lua ([0-9.]+)\"[ \t]*;.*" "\\1" Lua_VERSION ";${lua_version_strings};") endif () - string(REGEX REPLACE "^([0-9]+)\\.[0-9.]*$" "\\1" LUA_VERSION_MAJOR "${LUA_VERSION_STRING}") - string(REGEX REPLACE "^[0-9]+\\.([0-9]+)[0-9.]*$" "\\1" LUA_VERSION_MINOR "${LUA_VERSION_STRING}") - string(REGEX REPLACE "^[0-9]+\\.[0-9]+\\.([0-9]).*" "\\1" LUA_VERSION_PATCH "${LUA_VERSION_STRING}") + string(REGEX REPLACE "^([0-9]+)\\.[0-9.]*$" "\\1" Lua_VERSION_MAJOR "${Lua_VERSION}") + string(REGEX REPLACE "^[0-9]+\\.([0-9]+)[0-9.]*$" "\\1" Lua_VERSION_MINOR "${Lua_VERSION}") + string(REGEX REPLACE "^[0-9]+\\.[0-9]+\\.([0-9]).*" "\\1" Lua_VERSION_PATCH "${Lua_VERSION}") endif () foreach (ver IN LISTS _lua_append_versions) - if (ver STREQUAL "${LUA_VERSION_MAJOR}.${LUA_VERSION_MINOR}") - set(LUA_VERSION_MAJOR ${LUA_VERSION_MAJOR} PARENT_SCOPE) - set(LUA_VERSION_MINOR ${LUA_VERSION_MINOR} PARENT_SCOPE) - set(LUA_VERSION_PATCH ${LUA_VERSION_PATCH} PARENT_SCOPE) - set(LUA_VERSION_STRING ${LUA_VERSION_STRING} PARENT_SCOPE) - return() + if (ver STREQUAL "${Lua_VERSION_MAJOR}.${Lua_VERSION_MINOR}") + set(LUA_VERSION_STRING "${Lua_VERSION}") + set(LUA_VERSION_MAJOR "${Lua_VERSION_MAJOR}") + set(LUA_VERSION_MINOR "${Lua_VERSION_MINOR}") + set(LUA_VERSION_PATCH "${Lua_VERSION_PATCH}") + + return( + PROPAGATE + Lua_VERSION + Lua_VERSION_MAJOR + Lua_VERSION_MINOR + Lua_VERSION_PATCH + LUA_VERSION_STRING + LUA_VERSION_MAJOR + LUA_VERSION_MINOR + LUA_VERSION_PATCH + ) endif () endforeach () endfunction() @@ -208,9 +278,9 @@ endif() _lua_get_header_version() # Found accepted version -> Ok - if (LUA_VERSION_STRING) + if (Lua_VERSION) if (LUA_Debug) - message(STATUS "Found suitable version ${LUA_VERSION_STRING} in ${LUA_INCLUDE_DIR}/lua.h") + message(STATUS "Found suitable version ${Lua_VERSION} in ${LUA_INCLUDE_DIR}/lua.h") endif() return() endif() @@ -230,12 +300,12 @@ _lua_get_header_version() unset(_lua_append_versions) -if (LUA_VERSION_STRING) +if (Lua_VERSION) set(_lua_library_names - lua${LUA_VERSION_MAJOR}${LUA_VERSION_MINOR} - lua${LUA_VERSION_MAJOR}.${LUA_VERSION_MINOR} - lua-${LUA_VERSION_MAJOR}.${LUA_VERSION_MINOR} - lua.${LUA_VERSION_MAJOR}.${LUA_VERSION_MINOR} + lua${Lua_VERSION_MAJOR}${Lua_VERSION_MINOR} + lua${Lua_VERSION_MAJOR}.${Lua_VERSION_MINOR} + lua-${Lua_VERSION_MAJOR}.${Lua_VERSION_MINOR} + lua.${Lua_VERSION_MAJOR}.${Lua_VERSION_MINOR} ) endif () @@ -270,7 +340,7 @@ include(FindPackageHandleStandardArgs) find_package_handle_standard_args(Lua REQUIRED_VARS LUA_LIBRARIES LUA_INCLUDE_DIR - VERSION_VAR LUA_VERSION_STRING) + VERSION_VAR Lua_VERSION) mark_as_advanced(LUA_INCLUDE_DIR LUA_LIBRARY)
diff --git a/Modules/FindLua50.cmake b/Modules/FindLua50.cmake index ac36c86..0651a56 100644 --- a/Modules/FindLua50.cmake +++ b/Modules/FindLua50.cmake
@@ -7,11 +7,17 @@ .. note:: - This module is specifically for Lua version branch 5.0, which is obsolete and - not maintained anymore. In new code use the latest supported Lua version and - the version-agnostic module :module:`FindLua` instead. + This module is intended specifically for Lua version branch 5.0, which is + obsolete and not maintained anymore. In new code use the latest supported + Lua version and the version-agnostic module :module:`FindLua` instead. -Finds the Lua library. Lua is a embeddable scripting language. +Finds the Lua library: + +.. code-block:: cmake + + find_package(Lua50 [...]) + +Lua is a embeddable scripting language. When working with Lua, its library headers are intended to be included in project source code as: @@ -35,8 +41,9 @@ This module defines the following variables: ``Lua50_FOUND`` - Boolean indicating whether Lua is found. For backward compatibility, the - ``LUA50_FOUND`` variable is also set to the same value. + .. versionadded:: 3.3 + + Boolean indicating whether Lua was found. Cache Variables ^^^^^^^^^^^^^^^ @@ -51,6 +58,17 @@ Libraries needed to link against to use Lua. This list includes both ``lua`` and ``lualib`` libraries. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``LUA50_FOUND`` + .. deprecated:: 4.2 + Use ``Lua50_FOUND``, which has the same value. + + Boolean indicating whether Lua was found. + Examples ^^^^^^^^
diff --git a/Modules/FindLua51.cmake b/Modules/FindLua51.cmake index cba30e4..ad8a8ea 100644 --- a/Modules/FindLua51.cmake +++ b/Modules/FindLua51.cmake
@@ -7,11 +7,17 @@ .. note:: - This module is specifically for Lua version branch 5.1, which is obsolete and - not maintained anymore. In new code use the latest supported Lua version and - the version-agnostic module :module:`FindLua` instead. + This module is intended specifically for Lua version branch 5.1, which is + obsolete and not maintained anymore. In new code use the latest supported + Lua version and the version-agnostic module :module:`FindLua` instead. -Finds the Lua library. Lua is a embeddable scripting language. +Finds the Lua library: + +.. code-block:: cmake + + find_package(Lua51 [<version>] [...]) + +Lua is a embeddable scripting language. When working with Lua, its library headers are intended to be included in project source code as: @@ -35,10 +41,14 @@ This module defines the following variables: ``Lua51_FOUND`` - Boolean indicating whether Lua is found. For backward compatibility, the - ``LUA51_FOUND`` variable is also set to the same value. -``LUA_VERSION_STRING`` - The version of Lua found. + .. versionadded:: 3.3 + + Boolean indicating whether (the requested version of) Lua was found. + +``Lua51_VERSION`` + .. versionadded:: 4.2 + + The version of Lua 5.1 found. Cache Variables ^^^^^^^^^^^^^^^ @@ -48,9 +58,27 @@ ``LUA_INCLUDE_DIR`` The directory containing the Lua header files, such as ``lua.h``, ``lualib.h``, and ``lauxlib.h``, needed to use Lua. + ``LUA_LIBRARIES`` Libraries needed to link against to use Lua. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``LUA51_FOUND`` + .. deprecated:: 4.2 + Use ``Lua51_FOUND``, which has the same value. + + Boolean indicating whether (the requested version of) Lua was found. + +``LUA_VERSION_STRING`` + .. deprecated:: 4.2 + Use ``Lua51_VERSION``, which has the same value. + + The version of Lua 5.1 found. + Examples ^^^^^^^^ @@ -118,14 +146,15 @@ if(LUA_INCLUDE_DIR AND EXISTS "${LUA_INCLUDE_DIR}/lua.h") file(STRINGS "${LUA_INCLUDE_DIR}/lua.h" lua_version_str REGEX "^#define[ \t]+LUA_RELEASE[ \t]+\"Lua .+\"") - string(REGEX REPLACE "^#define[ \t]+LUA_RELEASE[ \t]+\"Lua ([^\"]+)\".*" "\\1" LUA_VERSION_STRING "${lua_version_str}") + string(REGEX REPLACE "^#define[ \t]+LUA_RELEASE[ \t]+\"Lua ([^\"]+)\".*" "\\1" Lua51_VERSION "${lua_version_str}") + set(LUA_VERSION_STRING "${Lua51_VERSION}") unset(lua_version_str) endif() include(FindPackageHandleStandardArgs) find_package_handle_standard_args(Lua51 REQUIRED_VARS LUA_LIBRARIES LUA_INCLUDE_DIR - VERSION_VAR LUA_VERSION_STRING) + VERSION_VAR Lua51_VERSION) mark_as_advanced(LUA_INCLUDE_DIR LUA_LIBRARIES LUA_LIBRARY LUA_MATH_LIBRARY)
diff --git a/Modules/FindMFC.cmake b/Modules/FindMFC.cmake index 27c5458..77adebf 100644 --- a/Modules/FindMFC.cmake +++ b/Modules/FindMFC.cmake
@@ -6,7 +6,11 @@ ------- Finds the native Microsoft Foundation Class Library (MFC) for developing MFC -applications on Windows. +applications on Windows: + +.. code-block:: cmake + + find_package(MFC [...]) .. note:: @@ -22,7 +26,7 @@ This module defines the following variables: ``MFC_FOUND`` - Boolean indicating whether MFC support is found. + Boolean indicating whether MFC support was found. Examples ^^^^^^^^
diff --git a/Modules/FindMPEG.cmake b/Modules/FindMPEG.cmake index 6c49702..824ae14 100644 --- a/Modules/FindMPEG.cmake +++ b/Modules/FindMPEG.cmake
@@ -5,7 +5,11 @@ FindMPEG -------- -Finds the native MPEG library (libmpeg2). +Finds the native MPEG library (libmpeg2): + +.. code-block:: cmake + + find_package(MPEG [...]) .. note:: @@ -24,14 +28,14 @@ This module defines the following variables: ``MPEG_FOUND`` - Boolean indicating whether the libmpeg2 library is found. + Boolean indicating whether the libmpeg2 library was found. ``MPEG_LIBRARIES`` Libraries needed to link against to use libmpeg2. Cache Variables ^^^^^^^^^^^^^^^ -The following cache variables may be also set: +The following cache variables may also be set: ``MPEG_INCLUDE_DIR`` The directory containing the ``mpeg2.h`` and related headers needed to use
diff --git a/Modules/FindMPEG2.cmake b/Modules/FindMPEG2.cmake index 103f2c4..2e647ba 100644 --- a/Modules/FindMPEG2.cmake +++ b/Modules/FindMPEG2.cmake
@@ -5,7 +5,11 @@ FindMPEG2 --------- -Finds the native MPEG2 library (libmpeg2). +Finds the native MPEG2 library (libmpeg2): + +.. code-block:: cmake + + find_package(MPEG2 [...]) .. note:: @@ -19,14 +23,14 @@ This module defines the following variables: ``MPEG2_FOUND`` - Boolean indicating whether the libmpeg2 library is found. + Boolean indicating whether the libmpeg2 library was found. ``MPEG2_LIBRARIES`` Libraries needed to link against to use libmpeg2. Cache Variables ^^^^^^^^^^^^^^^ -The following cache variables may be also set: +The following cache variables may also be set: ``MPEG2_INCLUDE_DIR`` The directory containing the ``mpeg2.h`` and related headers needed to use
diff --git a/Modules/FindMPI.cmake b/Modules/FindMPI.cmake index 78b1c5c..ebfd79f 100644 --- a/Modules/FindMPI.cmake +++ b/Modules/FindMPI.cmake
@@ -5,7 +5,11 @@ FindMPI ------- -Find a Message Passing Interface (MPI) implementation. +Finds a Message Passing Interface (MPI) implementation: + +.. code-block:: cmake + + find_package(MPI [<version>] [COMPONENTS <langs>...] [...]) The Message Passing Interface (MPI) is a library used to write high-performance distributed-memory parallel applications, and is @@ -14,253 +18,410 @@ .. versionadded:: 3.10 Major overhaul of the module: many new variables, per-language components, - support for a wider variety of runtimes. + and support for a wider variety of runtimes. -Variables for using MPI -^^^^^^^^^^^^^^^^^^^^^^^ +Components +^^^^^^^^^^ -The module exposes the components ``C``, ``CXX``, ``MPICXX`` and ``Fortran``. -Each of these controls the various MPI languages to search for. -The difference between ``CXX`` and ``MPICXX`` is that ``CXX`` refers to the -MPI C API being usable from C++, whereas ``MPICXX`` refers to the MPI-2 C++ API -that was removed again in MPI-3. +This module supports optional components that can be specified with the +:command:`find_package` command to control which MPI languages to search +for: -Depending on the enabled components the following variables will be set: +.. code-block:: cmake + + find_package(MPI [COMPONENTS <langs>...]) + +Supported components include: + +``C`` + .. versionadded:: 3.10 + + Finds MPI C API. + +``CXX`` + .. versionadded:: 3.10 + + Finds the MPI C API that is usable from C++. + +``MPICXX`` + .. versionadded:: 3.10 + + Finds the MPI-2 C++ API that was removed in MPI-3. + +``Fortran`` + .. versionadded:: 3.10 + + Finds the MPI Fortran API. + +If no components are specified, module searches for the ``C``, ``CXX``, and +``Fortran`` components automatically, depending on which languages are +enabled in the project. + +Imported Targets +^^^^^^^^^^^^^^^^ + +This module provides the following :ref:`Imported Targets`: + +``MPI::MPI_<lang>`` + .. versionadded:: 3.9 + + Target encapsulating usage requirements for using MPI from language + ``<lang>``, available if MPI is found. The ``<lang>`` is a specified + component name as listed above. + +Result Variables +^^^^^^^^^^^^^^^^ + +This module defines the following variables: ``MPI_FOUND`` - Variable indicating that MPI settings for all requested languages have been found. - If no components are specified, this is true if MPI settings for all enabled languages - were detected. Note that the ``MPICXX`` component does not affect this variable. -``MPI_VERSION`` - Minimal version of MPI detected among the requested languages, or all enabled languages - if no components were specified. + Boolean indicating that MPI settings for all requested components + (languages) were found. If no components are specified, this variable is + set to boolean true if MPI settings for all enabled languages were + detected. Note that the ``MPICXX`` component does not affect this + variable. -This module will set the following variables per language in your -project, where ``<lang>`` is one of C, CXX, or Fortran: +``MPI_VERSION`` + Minimal version of MPI detected among the requested languages, or all + enabled languages if no components were specified. + +This module will set the following variables per language in CMake project, +where ``<lang>`` is one of C, CXX, or Fortran: ``MPI_<lang>_FOUND`` - Variable indicating the MPI settings for ``<lang>`` were found and that + Boolean indicating the MPI settings for ``<lang>`` were found and that simple MPI test programs compile with the provided settings. + ``MPI_<lang>_COMPILER`` MPI compiler for ``<lang>`` if such a program exists. + ``MPI_<lang>_COMPILE_OPTIONS`` - Compilation options for MPI programs in ``<lang>``, given as a :ref:`;-list <CMake Language Lists>`. + Compilation options for MPI programs in ``<lang>``, given as a + :ref:`semicolon-separated list <CMake Language Lists>`. + ``MPI_<lang>_COMPILE_DEFINITIONS`` - Compilation definitions for MPI programs in ``<lang>``, given as a :ref:`;-list <CMake Language Lists>`. + Compilation definitions for MPI programs in ``<lang>``, given as a + :ref:`semicolon-separated list <CMake Language Lists>`. + ``MPI_<lang>_INCLUDE_DIRS`` Include path(s) for MPI header. + ``MPI_<lang>_LINK_FLAGS`` Linker flags for MPI programs. + ``MPI_<lang>_LIBRARIES`` All libraries to link MPI programs against. -.. versionadded:: 3.9 - Additionally, the following :prop_tgt:`IMPORTED` targets are defined: - -``MPI::MPI_<lang>`` - Target for using MPI from ``<lang>``. - -The following variables indicating which bindings are present will be defined: +The following variables indicating which bindings are present will be +defined: ``MPI_MPICXX_FOUND`` - Variable indicating whether the MPI-2 C++ bindings are present (introduced in MPI-2, removed with MPI-3). + Boolean indicating whether the MPI-2 C++ bindings are present (introduced + in MPI-2, removed with MPI-3). + ``MPI_Fortran_HAVE_F77_HEADER`` - True if the Fortran 77 header ``mpif.h`` is available. + True if the Fortran 77 header ``<mpif.h>`` is available. + ``MPI_Fortran_HAVE_F90_MODULE`` - True if the Fortran 90 module ``mpi`` can be used for accessing MPI (MPI-2 and higher only). + True if the Fortran 90 module ``mpi`` can be used for accessing MPI (MPI-2 + and higher only). + ``MPI_Fortran_HAVE_F08_MODULE`` - True if the Fortran 2008 ``mpi_f08`` is available to MPI programs (MPI-3 and higher only). + True if the Fortran 2008 ``mpi_f08`` is available to MPI programs (MPI-3 + and higher only). -If possible, the MPI version will be determined by this module. The facilities to detect the MPI version -were introduced with MPI-1.2, and therefore cannot be found for older MPI versions. +If possible, the MPI version will be determined by this module. The +facilities to detect the MPI version were introduced with MPI-1.2, and +therefore cannot be found for older MPI versions. -``MPI_<lang>_VERSION_MAJOR`` - Major version of MPI implemented for ``<lang>`` by the MPI distribution. -``MPI_<lang>_VERSION_MINOR`` - Minor version of MPI implemented for ``<lang>`` by the MPI distribution. ``MPI_<lang>_VERSION`` MPI version implemented for ``<lang>`` by the MPI distribution. -Note that there's no variable for the C bindings being accessible through ``mpi.h``, since the MPI standards -always have required this binding to work in both C and C++ code. +``MPI_<lang>_VERSION_MAJOR`` + Major version of MPI implemented for ``<lang>`` by the MPI distribution. -For running MPI programs, the module sets the following variables +``MPI_<lang>_VERSION_MINOR`` + Minor version of MPI implemented for ``<lang>`` by the MPI distribution. + +Note that there's no variable for the C bindings being accessible through +``<mpi.h>``, since the MPI standards always have required this binding to +work in both C and C++ code. + +For running MPI programs, the module sets the following variables: ``MPIEXEC_EXECUTABLE`` Executable for running MPI programs, if such exists. + ``MPIEXEC_NUMPROC_FLAG`` - Flag to pass to ``mpiexec`` before giving it the number of processors to run on. + Flag to pass to ``mpiexec`` before giving it the number of processors to + run on. + ``MPIEXEC_MAX_NUMPROCS`` - Number of MPI processors to utilize. Defaults to the number - of processors detected on the host system. + Number of MPI processors to utilize. Defaults to the number of + processors detected on the host system. + ``MPIEXEC_PREFLAGS`` Flags to pass to ``mpiexec`` directly before the executable to run. + ``MPIEXEC_POSTFLAGS`` Flags to pass to ``mpiexec`` after other flags. -Variables for locating MPI +Variables for Locating MPI ^^^^^^^^^^^^^^^^^^^^^^^^^^ -This module performs a four step search for an MPI implementation: +This module performs a four-step search for an MPI implementation: -1. Search for ``MPIEXEC_EXECUTABLE`` and, if found, use its base directory. -2. Check if the compiler has MPI support built-in. This is the case if the user passed a - compiler wrapper as ``CMAKE_<LANG>_COMPILER`` or if they use Cray system compiler wrappers. -3. Attempt to find an MPI compiler wrapper and determine the compiler information from it. -4. Try to find an MPI implementation that does not ship such a wrapper by guessing settings. - Currently, only Microsoft MPI and MPICH2 on Windows are supported. +1. Searches for ``MPIEXEC_EXECUTABLE`` and, if found, uses its base + directory. +2. Checks if the compiler has MPI support built-in. This is the case if + the user passed a compiler wrapper as :variable:`CMAKE_<LANG>_COMPILER` + or if they use Cray system compiler wrappers. +3. Attempts to find an MPI compiler wrapper and determines the compiler + information from it. +4. Tries to find an MPI implementation that does not ship such a wrapper by + guessing settings. Currently, only Microsoft MPI and MPICH2 on Windows + are supported. -For controlling the ``MPIEXEC_EXECUTABLE`` step, the following variables may be set: +For controlling the ``MPIEXEC_EXECUTABLE`` step, the following variables +may be set: ``MPIEXEC_EXECUTABLE`` Manually specify the location of ``mpiexec``. + ``MPI_HOME`` Specify the base directory of the MPI installation. + ``ENV{MPI_HOME}`` Environment variable to specify the base directory of the MPI installation. + ``ENV{I_MPI_ROOT}`` Environment variable to specify the base directory of the MPI installation. -For controlling the compiler wrapper step, the following variables may be set: +For controlling the compiler wrapper step, the following variables may be +set: ``MPI_<lang>_COMPILER`` Search for the specified compiler wrapper and use it. + ``MPI_<lang>_COMPILER_FLAGS`` - Flags to pass to the MPI compiler wrapper during interrogation. Some compiler wrappers - support linking debug or tracing libraries if a specific flag is passed and this variable - may be used to obtain them. + Flags to pass to the MPI compiler wrapper during interrogation. Some + compiler wrappers support linking debug or tracing libraries if a specific + flag is passed and this variable may be used to obtain them. + ``MPI_COMPILER_FLAGS`` - Used to initialize ``MPI_<lang>_COMPILER_FLAGS`` if no language specific flag has been given. - Empty by default. + Used to initialize ``MPI_<lang>_COMPILER_FLAGS`` if no language specific + flag has been given. Empty by default. + ``MPI_EXECUTABLE_SUFFIX`` - A suffix which is appended to all names that are being looked for. For instance you may set this - to ``.mpich`` or ``.openmpi`` to prefer the one or the other on Debian and its derivatives. + A suffix which is appended to all names that are being looked for. For + instance, it may be set to ``.mpich`` or ``.openmpi`` to prefer the one + or the other on Debian and its derivatives. In order to control the guessing step, the following variable may be set: ``MPI_GUESS_LIBRARY_NAME`` - Valid values are ``MSMPI`` and ``MPICH2``. If set, only the given library will be searched for. - By default, ``MSMPI`` will be preferred over ``MPICH2`` if both are available. - This also sets ``MPI_SKIP_COMPILER_WRAPPER`` to ``true``, which may be overridden. + Valid values are ``MSMPI`` and ``MPICH2``. If set, only the given library + will be searched for. By default, ``MSMPI`` will be preferred over + ``MPICH2`` if both are available. This also sets + ``MPI_SKIP_COMPILER_WRAPPER`` variable to ``true``, which may be + overridden. Each of the search steps may be skipped with the following control variables: ``MPI_ASSUME_NO_BUILTIN_MPI`` - If true, the module assumes that the compiler itself does not provide an MPI implementation and - skips to step 2. + If true, the module assumes that the compiler itself does not provide an + MPI implementation and skips to step 2. + ``MPI_SKIP_COMPILER_WRAPPER`` If true, no compiler wrapper will be searched for. + ``MPI_SKIP_GUESSING`` If true, the guessing step will be skipped. -Additionally, the following control variable is available to change search behavior: +Additionally, the following control variable is available to change search +behavior: ``MPI_CXX_SKIP_MPICXX`` Add some definitions that will disable the MPI-2 C++ bindings. - Currently supported are MPICH, Open MPI, Platform MPI and derivatives thereof, - for example MVAPICH or Intel MPI. + Currently supported are MPICH, Open MPI, Platform MPI and derivatives + thereof, for example, MVAPICH or Intel MPI. -If the find procedure fails for a variable ``MPI_<lang>_WORKS``, then the settings detected by or passed to -the module did not work and even a simple MPI test program failed to compile. +If the find procedure fails for the module's internal variable +``MPI_<lang>_WORKS``, then the settings detected by or passed to the module +did not work and even a simple MPI test program failed to compile. -If all of these parameters were not sufficient to find the right MPI implementation, a user may -disable the entire autodetection process by specifying both a list of libraries in ``MPI_<lang>_LIBRARIES`` -and a list of include directories in ``MPI_<lang>_ADDITIONAL_INCLUDE_DIRS``. -Any other variable may be set in addition to these two. The module will then validate the MPI settings and store the -settings in the cache. +If all of these parameters were not sufficient to find the right MPI +implementation, a user may disable the entire autodetection process by +specifying both a list of libraries in ``MPI_<lang>_LIBRARIES`` and a list +of include directories in ``MPI_<lang>_ADDITIONAL_INCLUDE_DIRS``. Any other +variable may be set in addition to these two. The module will then validate +the MPI settings and store the settings in the cache. -Cache variables for MPI -^^^^^^^^^^^^^^^^^^^^^^^ +Cache Variables +^^^^^^^^^^^^^^^ -The variable ``MPI_<lang>_INCLUDE_DIRS`` will be assembled from the following variables. +The variable ``MPI_<lang>_INCLUDE_DIRS`` will be assembled from the +following variables. + For C and CXX: ``MPI_<lang>_HEADER_DIR`` - Location of the ``mpi.h`` header on disk. + Location of the ``<mpi.h>`` header on disk. For Fortran: ``MPI_Fortran_F77_HEADER_DIR`` - Location of the Fortran 77 header ``mpif.h``, if it exists. + Location of the Fortran 77 header ``<mpif.h>``, if it exists. + ``MPI_Fortran_MODULE_DIR`` Location of the ``mpi`` or ``mpi_f08`` modules, if available. For all languages the following variables are additionally considered: ``MPI_<lang>_ADDITIONAL_INCLUDE_DIRS`` - A :ref:`;-list <CMake Language Lists>` of paths needed in addition to the normal include directories. -``MPI_<include_name>_INCLUDE_DIR`` - Path variables for include folders referred to by ``<include_name>``. + A :ref:`semicolon-separated list <CMake Language Lists>` of paths needed + in addition to the normal include directories. + +``MPI_<include-name>_INCLUDE_DIR`` + Path variables for include folders referred to by ``<include-name>``. + ``MPI_<lang>_ADDITIONAL_INCLUDE_VARS`` - A :ref:`;-list <CMake Language Lists>` of ``<include_name>`` that will be added to the include locations of ``<lang>``. + A :ref:`semicolon-separated list <CMake Language Lists>` of + ``<include-name>`` that will be added to the include locations of + ``<lang>``. -The variable ``MPI_<lang>_LIBRARIES`` will be assembled from the following variables: +The variable ``MPI_<lang>_LIBRARIES`` will be assembled from the following +variables: -``MPI_<lib_name>_LIBRARY`` - The location of a library called ``<lib_name>`` for use with MPI. +``MPI_<lib-name>_LIBRARY`` + The location of a library called ``<lib-name>`` for use with MPI. + ``MPI_<lang>_LIB_NAMES`` - A :ref:`;-list <CMake Language Lists>` of ``<lib_name>`` that will be added to the include locations of ``<lang>``. + A :ref:`semicolon-separated list <CMake Language Lists>` of ``<lib-name>`` + that will be added to the include locations of ``<lang>``. -Usage of mpiexec -^^^^^^^^^^^^^^^^ +Advanced Variables for Using MPI +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -When using ``MPIEXEC_EXECUTABLE`` to execute MPI applications, you should typically -use all of the ``MPIEXEC_EXECUTABLE`` flags as follows: +The module can perform some advanced feature detections upon explicit +request. + +.. note:: + + The following checks cannot be performed without *executing* an MPI test + program. Consider the special considerations for the behavior of + :command:`try_run` during cross compilation. Moreover, running an MPI + program can cause additional issues, like a firewall notification on some + systems. These detections should be only enabled if information is + absolutely needed. + +If the following variables are set to true, the respective search will be +performed: + +``MPI_DETERMINE_Fortran_CAPABILITIES`` + Determine for all available Fortran bindings what the values of + ``MPI_SUBARRAYS_SUPPORTED`` and ``MPI_ASYNC_PROTECTS_NONBLOCKING`` are + and make their values available as ``MPI_Fortran_<binding>_SUBARRAYS`` + and ``MPI_Fortran_<binding>_ASYNCPROT``, where ``<binding>`` is one of + ``F77_HEADER``, ``F90_MODULE`` and ``F08_MODULE``. + +``MPI_DETERMINE_LIBRARY_VERSION`` + For each language, find the output of ``MPI_Get_library_version`` and + make it available as ``MPI_<lang>_LIBRARY_VERSION_STRING``. This + information is usually tied to the runtime component of an MPI + implementation and might differ depending on ``<lang>``. + Note that the return value is entirely implementation defined. This + information might be used to identify the MPI vendor and for example pick + the correct one of multiple third party binaries that matches the MPI + vendor. + +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``MPI_COMPILER`` + .. deprecated:: 2.8.5 + Use the ``MPI_<lang>_COMPILER`` instead. + +``MPI_LIBRARY`` + .. deprecated:: 2.8.5 + Use the ``MPI_<lang>_LIBRARIES`` instead. + +``MPI_EXTRA_LIBRARY`` + .. deprecated:: 2.8.5 + Use the ``MPI_<lang>_LIBRARIES`` instead. + +``MPI_COMPILE_FLAGS`` + .. deprecated:: 2.8.5 + Use ``MPI_<lang>_COMPILE_OPTIONS`` and ``MPI_<lang>_COMPILE_DEFINITIONS`` + instead. + +``MPI_INCLUDE_PATH`` + .. deprecated:: 2.8.5 + Use the ``MPI_<lang>_INCLUDE_DIRS`` instead. + +``MPI_LINK_FLAGS`` + .. deprecated:: 2.8.5 + Use the ``MPI_<lang>_LINK_FLAGS`` instead. + +``MPI_LIBRARIES`` + .. deprecated:: 2.8.5 + Use the ``MPI_<lang>_LIBRARIES`` instead. + +``MPI_<lang>_COMPILE_FLAGS`` + .. deprecated:: 3.10 + Use the ``MPI_<lang>_COMPILE_OPTIONS`` and + ``MPI_<lang>_COMPILE_DEFINITIONS`` instead. + +``MPI_<lang>_INCLUDE_PATH`` + .. deprecated:: 3.10 + For consumption use ``MPI_<lang>_INCLUDE_DIRS`` and for specifying + folders use ``MPI_<lang>_ADDITIONAL_INCLUDE_DIRS`` instead. + +``MPIEXEC`` + .. deprecated:: 3.10 + Use ``MPIEXEC_EXECUTABLE`` instead. + +Examples +^^^^^^^^ + +Example: Basic Usage +"""""""""""""""""""" + +Finding MPI and linking imported target to project target: .. code-block:: cmake - ${MPIEXEC_EXECUTABLE} ${MPIEXEC_NUMPROC_FLAG} ${MPIEXEC_MAX_NUMPROCS} - ${MPIEXEC_PREFLAGS} EXECUTABLE ${MPIEXEC_POSTFLAGS} ARGS + find_package(MPI) + target_link_libraries(example PRIVATE MPI::MPI_C) -where ``EXECUTABLE`` is the MPI program, and ``ARGS`` are the arguments to -pass to the MPI program. +Example: Usage of mpiexec +""""""""""""""""""""""""" -Advanced variables for using MPI -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +When using ``MPIEXEC_EXECUTABLE`` to execute MPI applications, typically +all of the ``MPIEXEC_EXECUTABLE`` flags should be used as follows. -The module can perform some advanced feature detections upon explicit request. +In the following example, the command is executed in a process. +``<executable>`` should be replaced with the MPI program, and ``<args>`` +with the arguments to pass to the MPI program. -**Important notice:** The following checks cannot be performed without *executing* an MPI test program. -Consider the special considerations for the behavior of :command:`try_run` during cross compilation. -Moreover, running an MPI program can cause additional issues, like a firewall notification on some systems. -You should only enable these detections if you absolutely need the information. +.. code-block:: cmake -If the following variables are set to true, the respective search will be performed: + find_package(MPI) -``MPI_DETERMINE_Fortran_CAPABILITIES`` - Determine for all available Fortran bindings what the values of ``MPI_SUBARRAYS_SUPPORTED`` and - ``MPI_ASYNC_PROTECTS_NONBLOCKING`` are and make their values available as ``MPI_Fortran_<binding>_SUBARRAYS`` - and ``MPI_Fortran_<binding>_ASYNCPROT``, where ``<binding>`` is one of ``F77_HEADER``, ``F90_MODULE`` and - ``F08_MODULE``. -``MPI_DETERMINE_LIBRARY_VERSION`` - For each language, find the output of ``MPI_Get_library_version`` and make it available as ``MPI_<lang>_LIBRARY_VERSION_STRING``. - This information is usually tied to the runtime component of an MPI implementation and might differ depending on ``<lang>``. - Note that the return value is entirely implementation defined. This information might be used to identify - the MPI vendor and for example pick the correct one of multiple third party binaries that matches the MPI vendor. - -Backward Compatibility -^^^^^^^^^^^^^^^^^^^^^^ - -.. deprecated:: 3.10 - -For backward compatibility with older versions of FindMPI, these -variables are set: - -:: - - MPI_COMPILER MPI_LIBRARY MPI_EXTRA_LIBRARY - MPI_COMPILE_FLAGS MPI_INCLUDE_PATH MPI_LINK_FLAGS - MPI_LIBRARIES - -In new projects, please use the ``MPI_<lang>_XXX`` equivalents. -Additionally, the following variables are deprecated: - -``MPI_<lang>_COMPILE_FLAGS`` - Use ``MPI_<lang>_COMPILE_OPTIONS`` and ``MPI_<lang>_COMPILE_DEFINITIONS`` instead. -``MPI_<lang>_INCLUDE_PATH`` - For consumption use ``MPI_<lang>_INCLUDE_DIRS`` and for specifying folders use ``MPI_<lang>_ADDITIONAL_INCLUDE_DIRS`` instead. -``MPIEXEC`` - Use ``MPIEXEC_EXECUTABLE`` instead. + if(MPI_FOUND) + execute_process( + COMMAND + ${MPIEXEC_EXECUTABLE} + ${MPIEXEC_NUMPROC_FLAG} + ${MPIEXEC_MAX_NUMPROCS} + ${MPIEXEC_PREFLAGS} + <executable> + ${MPIEXEC_POSTFLAGS} + <args> + ) + endif() #]=======================================================================] cmake_policy(PUSH) @@ -982,7 +1143,7 @@ # Our strategy is now to locate all libraries, but enter msmpifec into the LIB_NAMES array. # Should this not be adequate it's a straightforward way for a user to change the LIB_NAMES array and - # have his library found. Still, this should not be necessary outside of exceptional cases, as reasoned. + # have their library found. Still, this should not be necessary outside of exceptional cases, as reasoned. if (LANG STREQUAL "Fortran") set(MPI_MSMPI_CALLINGCONVS c) if(CMAKE_SIZEOF_VOID_P EQUAL "4") @@ -1598,7 +1759,7 @@ else() set(_MPI_PKG "") endif() - if(_MPI_PKG AND PKG_CONFIG_FOUND) + if(_MPI_PKG AND PkgConfig_FOUND) pkg_check_modules("MPI_${LANG}_PKG" "${_MPI_PKG}") if(MPI_${LANG}_PKG_FOUND) set(MPI_${LANG}_COMPILE_OPTIONS ${MPI_${LANG}_PKG_CFLAGS} CACHE STRING "MPI ${LANG} compilation options" FORCE)
diff --git a/Modules/FindMatlab.cmake b/Modules/FindMatlab.cmake index 8a7bd80..231700a 100644 --- a/Modules/FindMatlab.cmake +++ b/Modules/FindMatlab.cmake
@@ -5,301 +5,767 @@ FindMatlab ---------- -Finds Matlab or Matlab Compiler Runtime (MCR) and provides Matlab tools, -libraries and compilers to CMake. +Finds MATLAB or MATLAB Compiler Runtime (MCR) and provides its tools, +libraries and compilers to CMake: -This package primary purpose is to find the libraries associated with Matlab -or the MCR in order to be able to build Matlab extensions (mex files). It -can also be used: +.. code-block:: cmake -* to run specific commands in Matlab in case Matlab is available -* for declaring Matlab unit test -* to retrieve various information from Matlab (mex extensions, versions and + find_package(Matlab [<version>] [COMPONENTS <components>...] [REGISTRY_VIEW <view>] [...]) + +The primary purpose of this module is to find the libraries associated with +MATLAB or the MCR in order to be able to build MATLAB extensions (MEX files). +It can also be used: + +* to run specific commands in MATLAB in case MATLAB is available +* for declaring MATLAB unit tests +* to retrieve various information from MATLAB (MEX extensions, versions and release queries, ...) .. versionadded:: 3.12 - Added Matlab Compiler Runtime (MCR) support. - -The module supports the following components: - -* ``ENG_LIBRARY`` and ``MAT_LIBRARY``: respectively the ``ENG`` and ``MAT`` - libraries of Matlab -* ``MAIN_PROGRAM`` the Matlab binary program. Note that this component is not - available on the MCR version, and will yield an error if the MCR is found - instead of the regular Matlab installation. -* ``MEX_COMPILER`` the MEX compiler. -* ``MCC_COMPILER`` the MCC compiler, included with the Matlab Compiler add-on. -* ``SIMULINK`` the Simulink environment. - -.. versionadded:: 3.7 - Added the ``MAT_LIBRARY`` component. - -.. versionadded:: 3.13 - Added the ``ENGINE_LIBRARY``, ``DATAARRAY_LIBRARY`` and ``MCC_COMPILER`` - components. - -.. versionchanged:: 3.14 - Removed the ``MX_LIBRARY``, ``ENGINE_LIBRARY`` and ``DATAARRAY_LIBRARY`` - components. These libraries are found unconditionally. + MATLAB Compiler Runtime (MCR) support. .. versionadded:: 3.30 - Added support for specifying a version range to :command:`find_package` and - added support for specifying ``REGISTRY_VIEW`` to :command:`find_package`, + Support for specifying a version range to :command:`find_package`, + support for specifying ``REGISTRY_VIEW`` argument to + :command:`find_package`, :command:`matlab_extract_all_installed_versions_from_registry` and - :command:`matlab_get_all_valid_matlab_roots_from_registry`. The default - behavior remained unchanged, by using the registry view ``TARGET``. + :command:`matlab_get_all_valid_matlab_roots_from_registry` commands. + The default behavior remained unchanged, by using the registry view + ``TARGET``. .. note:: - The version given to the :command:`find_package` directive is the Matlab - **version**, which should not be confused with the Matlab *release* name - (e.g. `R2023b`). - The :command:`matlab_get_version_from_release_name` and - :command:`matlab_get_release_name_from_version` provide a mapping - between the release name and the version. + The version given to the :command:`find_package` argument is the MATLAB + *version*, which should not be confused with the MATLAB *release name* + (e.g. ``R2023b``). The :command:`matlab_get_version_from_release_name` + and :command:`matlab_get_release_name_from_version` commands provide a + mapping between the release name and the version. -The variable :variable:`Matlab_ROOT_DIR` may be specified in order to give -the path of the desired Matlab version. Otherwise, the behavior is platform -specific: +Components +^^^^^^^^^^ -* Windows: The installed versions of Matlab/MCR are retrieved from the - Windows registry. The ``REGISTRY_VIEW`` argument may optionally be specified - to manually control whether 32bit or 64bit versions shall be searched for. -* macOS: The installed versions of Matlab/MCR are given by the MATLAB - default installation paths under ``$HOME/Applications`` and ``/Applications``. - If no such application is found, it falls back to the one that might be - accessible from the ``PATH``. -* Unix: The desired Matlab should be accessible from the ``PATH``. This does - not work for MCR installation and :variable:`Matlab_ROOT_DIR` should be - specified on this platform. +This module supports optional components which can be specified using the +:command:`find_package` command: -Additional information is provided when :variable:`MATLAB_FIND_DEBUG` is set. -When a Matlab/MCR installation is found automatically and the ``MATLAB_VERSION`` -is not given, the version is queried from Matlab directly (on Windows this -may pop up a Matlab window) or from the MCR installation. +.. code-block:: cmake -The mapping of the release names and the version of Matlab is performed by -defining pairs (name, version). The variable -:variable:`MATLAB_ADDITIONAL_VERSIONS` may be provided before the call to -the :command:`find_package` in order to handle additional versions. + find_package(Matlab [COMPONENTS <components>...]) -A Matlab scripts can be added to the set of tests using the -:command:`matlab_add_unit_test`. By default, the Matlab unit test framework -will be used (>= 2013a) to run this script, but regular ``.m`` files -returning an exit code can be used as well (0 indicating a success). +Supported components include: -Module Input Variables -^^^^^^^^^^^^^^^^^^^^^^ +``ENG_LIBRARY`` + .. versionadded:: 3.3 -Users or projects may set the following variables to configure the module -behavior: + Finds the ``ENG`` library of MATLAB. -:variable:`Matlab_ROOT <<PackageName>_ROOT>` - .. versionadded:: 3.25 +``MAT_LIBRARY`` + .. versionadded:: 3.7 - Default value for :variable:`Matlab_ROOT_DIR`, the root of the Matlab - installation. + Finds the ``MAT`` library of MATLAB. -:variable:`Matlab_ROOT_DIR` - The root of the Matlab installation. +``MAIN_PROGRAM`` + .. versionadded:: 3.3 -:variable:`MATLAB_FIND_DEBUG` - outputs debug information + Finds the MATLAB binary program. Note that this component is not + available on the MCR version, and will yield an error if the MCR is found + instead of the regular MATLAB installation. -:variable:`MATLAB_ADDITIONAL_VERSIONS` - additional versions of Matlab for the automatic retrieval of the installed - versions. +``MEX_COMPILER`` + .. versionadded:: 3.3 + + Finds the MEX compiler. + +``MCC_COMPILER`` + .. versionadded:: 3.13 + + Finds the MCC compiler, included with the MATLAB Compiler add-on. + +``SIMULINK`` + .. versionadded:: 3.3 + + Finds the Simulink environment. + +Implicitly Found Components +""""""""""""""""""""""""""" + +The following components are always found unconditionally, without needing +to be specified explicitly: + +``MX_LIBRARY`` + .. versionchanged:: 3.14 + This component has been removed and is now always found unconditionally. + + .. versionadded:: 3.3 + + Finds the MATLAB mx library. + +``ENGINE_LIBRARY`` + .. versionchanged:: 3.14 + This component has been removed and is now always found unconditionally. + + .. versionadded:: 3.13 + + Finds the MATLAB engine library. + +``DATAARRAY_LIBRARY`` + .. versionchanged:: 3.14 + This component has been removed and is now always found unconditionally. + + .. versionadded:: 3.13 + + Finds the C++ MATLAB data array library. + +If no components are specified, the module looks for the ``MX_LIBRARY``, +``ENGINE_LIBRARY``, and ``DATAARRAY_LIBRARY`` by default. Imported Targets ^^^^^^^^^^^^^^^^ -.. versionadded:: 3.22 - -This module defines the following :prop_tgt:`IMPORTED` targets: +This module provides the following :ref:`Imported Targets`: ``Matlab::mex`` - The ``mex`` library, always available for MATLAB installations. Available for - MCR installations if provided by MCR. + .. versionadded:: 3.22 + + Target encapsulating the ``mex`` library usage requirements, always + available for MATLAB installations. Available for MCR installations if + provided by MCR. ``Matlab::mx`` - The mx library of Matlab (arrays), always available for MATLAB installations. - Available for MCR installations if provided by MCR. + .. versionadded:: 3.22 + + Target encapsulating the usage requirements of the mx library of MATLAB + (arrays), always available for MATLAB installations. Available for MCR + installations if provided by MCR. ``Matlab::eng`` - Matlab engine library. Available only if the ``ENG_LIBRARY`` component - is requested. + .. versionadded:: 3.22 + + Target encapsulating the MATLAB engine library usage requirements. + Available only if the ``ENG_LIBRARY`` component is requested. ``Matlab::mat`` - Matlab matrix library. Available only if the ``MAT_LIBRARY`` component - is requested. + .. versionadded:: 3.22 + + Target encapsulating the MATLAB matrix library usage requirements. + Available only if the ``MAT_LIBRARY`` component is requested. ``Matlab::MatlabEngine`` - Matlab C++ engine library, always available for MATLAB R2018a and newer. - Available for MCR installations if provided by MCR. + .. versionadded:: 3.22 + + Target encapsulating the MATLAB C++ engine library usage requirements, + always available for MATLAB R2018a and newer. Available for MCR + installations if provided by MCR. ``Matlab::MatlabDataArray`` - Matlab C++ data array library, always available for MATLAB R2018a and newer. - Available for MCR installations if provided by MCR. + .. versionadded:: 3.22 -Variables defined by the module -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + Target encapsulating the MATLAB C++ data array library usage requirements, + always available for MATLAB R2018a and newer. Available for MCR + installations if provided by MCR. -Result variables -"""""""""""""""" +Result Variables +^^^^^^^^^^^^^^^^ + +This module defines the following variables: ``Matlab_FOUND`` - ``TRUE`` if the Matlab installation is found, ``FALSE`` - otherwise. All variable below are defined if Matlab is found. + .. versionadded:: 3.3 + + Boolean indicating whether the (requested version of) MATLAB installation + was found. All variables below are defined if MATLAB is found. + ``Matlab_VERSION`` .. versionadded:: 3.27 - the numerical version (e.g. 23.2.0) of Matlab found. Not to be confused with - Matlab release name (e.g. R2023b) that can be obtained with - :command:`matlab_get_release_name_from_version`. + The numerical version (e.g. ``23.2.0``) of MATLAB found. Not to be + confused with MATLAB release name (e.g. ``R2023b``) that can be obtained + with :command:`matlab_get_release_name_from_version`. + + When a MATLAB/MCR installation is found automatically and the + ``Matlab_VERSION`` is not given, the version is queried from MATLAB + directly (on Windows this may pop up a MATLAB window) or from the MCR + installation. + ``Matlab_ROOT_DIR`` - the final root of the Matlab installation determined by the FindMatlab - module. + .. versionadded:: 3.3 + + The final root of the MATLAB installation determined by this module. + ``Matlab_MAIN_PROGRAM`` - the Matlab binary program. Available only if the component ``MAIN_PROGRAM`` - is given in the :command:`find_package` directive. + .. versionadded:: 3.3 + + The MATLAB binary program. Available only if the component ``MAIN_PROGRAM`` + is given in the :command:`find_package` argument. + ``Matlab_INCLUDE_DIRS`` - the path of the Matlab libraries headers + .. versionadded:: 3.3 + + The path of the MATLAB libraries headers. + ``Matlab_MEX_LIBRARY`` - library for mex, always available for MATLAB installations. Available for MCR - installations if provided by MCR. + Library for MEX, always available for MATLAB installations. Available + for MCR installations if provided by MCR. + ``Matlab_MX_LIBRARY`` - mx library of Matlab (arrays), always available for MATLAB installations. - Available for MCR installations if provided by MCR. + The mx library of MATLAB (arrays), always available for MATLAB + installations. Available for MCR installations if provided by MCR. + ``Matlab_ENG_LIBRARY`` - Matlab engine library. Available only if the component ``ENG_LIBRARY`` + MATLAB engine library. Available only if the component ``ENG_LIBRARY`` is requested. + ``Matlab_MAT_LIBRARY`` - Matlab matrix library. Available only if the component ``MAT_LIBRARY`` + .. versionadded:: 3.7 + + Matlab matrix library. Available only if the component ``MAT_LIBRARY`` is requested. + ``Matlab_ENGINE_LIBRARY`` .. versionadded:: 3.13 Matlab C++ engine library, always available for MATLAB R2018a and newer. Available for MCR installations if provided by MCR. + ``Matlab_DATAARRAY_LIBRARY`` .. versionadded:: 3.13 - Matlab C++ data array library, always available for MATLAB R2018a and newer. - Available for MCR installations if provided by MCR. + Matlab C++ data array library, always available for MATLAB R2018a and + newer. Available for MCR installations if provided by MCR. + ``Matlab_LIBRARIES`` - the whole set of libraries of Matlab + The whole set of libraries of MATLAB. + ``Matlab_MEX_COMPILER`` - the mex compiler of Matlab. Currently not used. - Available only if the component ``MEX_COMPILER`` is requested. + .. versionadded:: 3.3 + + The MEX compiler of MATLAB. Currently not used. Available only if the + component ``MEX_COMPILER`` is requested. + ``Matlab_MCC_COMPILER`` .. versionadded:: 3.13 - the mcc compiler of Matlab. Included with the Matlab Compiler add-on. + The mcc compiler of MATLAB. Included with the MATLAB Compiler add-on. Available only if the component ``MCC_COMPILER`` is requested. -Cached variables -"""""""""""""""" +Cache Variables +^^^^^^^^^^^^^^^ + +The following cache variables may also be set: ``Matlab_MEX_EXTENSION`` - the extension of the mex files for the current platform (given by Matlab). + .. versionadded:: 3.3 + + The extension of the MEX files for the current platform (given by MATLAB). + ``Matlab_ROOT_DIR`` - the location of the root of the Matlab installation found. If this value + .. versionadded:: 3.3 + + The location of the root of the MATLAB installation found. If this value is changed by the user, the result variables are recomputed. -Provided commands -^^^^^^^^^^^^^^^^^ +Input Variables +^^^^^^^^^^^^^^^ -:command:`matlab_get_version_from_release_name` - returns the version from the Matlab release name -:command:`matlab_get_release_name_from_version` - returns the release name from the Matlab version -:command:`matlab_add_mex` - adds a target compiling a MEX file. -:command:`matlab_add_unit_test` - adds a Matlab unit test file as a test to the project. -:command:`matlab_extract_all_installed_versions_from_registry` - parses the registry for all Matlab versions. Available on Windows only. - The part of the registry parsed is dependent on the host processor -:command:`matlab_get_all_valid_matlab_roots_from_registry` - returns all the possible Matlab or MCR paths, according to a previously - given list. Only the existing/accessible paths are kept. This is mainly - useful for the searching all possible Matlab installation. -:command:`matlab_get_mex_suffix` - returns the suffix to be used for the mex files - (platform/architecture dependent) -:command:`matlab_get_version_from_matlab_run` - returns the version of Matlab/MCR, given the full directory of the Matlab/MCR - installation path. +Users or projects may set the following variables to configure the module +behavior before calling ``find_package(Matlab)``: +:variable:`Matlab_ROOT <<PackageName>_ROOT>` + .. versionadded:: 3.25 -Known issues -^^^^^^^^^^^^ + Default value for the ``Matlab_ROOT_DIR`` variable, the root of the + MATLAB installation. -**Symbol clash in a MEX target** - By default, every symbols inside a MEX - file defined with the command :command:`matlab_add_mex` have hidden - visibility, except for the entry point. This is the default behavior of - the MEX compiler, which lowers the risk of symbol collision between the - libraries shipped with Matlab, and the libraries to which the MEX file is - linking to. This is also the default on Windows platforms. +``Matlab_ROOT_DIR`` + .. versionadded:: 3.3 - However, this is not sufficient in certain case, where for instance your - MEX file is linking against libraries that are already loaded by Matlab, - even if those libraries have different SONAMES. - A possible solution is to hide the symbols of the libraries to which the - MEX target is linking to. This can be achieved in GNU GCC compilers with - the linker option ``-Wl,--exclude-libs,ALL``. + The root folder of the MATLAB installation. If set before the call to + :command:`find_package`, the module will look for the components in that + path. If not set, then an automatic search of MATLAB will be performed. + If set, it should point to a valid version of MATLAB. -**Tests using GPU resources** - in case your MEX file is using the GPU and - in order to be able to run unit tests on this MEX file, the GPU resources - should be properly released by Matlab. A possible solution is to make - Matlab aware of the use of the GPU resources in the session, which can be - performed by a command such as ``D = gpuDevice()`` at the beginning of - the test script (or via a fixture). + This variable may be specified in order to give the path of the desired + MATLAB version. Otherwise, the behavior is platform specific: + * Windows: The installed versions of MATLAB/MCR are retrieved from the + Windows registry. The ``REGISTRY_VIEW`` argument may optionally be + specified to manually control whether 32bit or 64bit versions shall be + searched for. + * macOS: The installed versions of MATLAB/MCR are given by the MATLAB + default installation paths under ``$HOME/Applications`` and + ``/Applications``. If no such application is found, it falls back to + the one that might be accessible from the ``PATH``. + * Unix: The desired MATLAB should be accessible from the ``PATH``. This + does not work for MCR installation and ``Matlab_ROOT_DIR`` should be + specified on this platform. -Reference -^^^^^^^^^ +``MATLAB_FIND_DEBUG`` + .. versionadded:: 3.3 -.. variable:: Matlab_ROOT_DIR + If set to a boolean true, additional debug information is outputted to + the console, such as the lookup of MATLAB and the intermediate + configuration steps. - The root folder of the Matlab installation. If set before the call to - :command:`find_package`, the module will look for the components in that - path. If not set, then an automatic search of Matlab - will be performed. If set, it should point to a valid version of Matlab. +``MATLAB_ADDITIONAL_VERSIONS`` + .. versionadded:: 3.3 -.. variable:: MATLAB_FIND_DEBUG + If set, it specifies additional versions of MATLAB for the automatic + retrieval of the installed versions that may be handled and looked for. - If set, the lookup of Matlab and the intermediate configuration steps are - outputted to the console. - -.. variable:: MATLAB_ADDITIONAL_VERSIONS - - If set, specifies additional versions of Matlab that may be looked for. - The variable should be a list of strings, organized by pairs of release - name and versions, such as follows: + The mapping of the release names and the version of MATLAB is performed + by defining pairs (name, version). The variable should be a list of + strings, organized by pairs of release name and versions, such as + follows: .. code-block:: cmake - set(MATLAB_ADDITIONAL_VERSIONS + set( + MATLAB_ADDITIONAL_VERSIONS "release_name1=corresponding_version1" "release_name2=corresponding_version2" - ... - ) + # ... + ) + + find_package(Matlab) Example: .. code-block:: cmake - set(MATLAB_ADDITIONAL_VERSIONS + set( + MATLAB_ADDITIONAL_VERSIONS "R2013b=8.2" "R2013a=8.1" - "R2012b=8.0") + "R2012b=8.0" + # ... + ) - The order of entries in this list matters when several versions of - Matlab are installed. The priority is set according to the ordering in - this list. + find_package(Matlab) + + The order of entries in this list matters when several versions of MATLAB + are installed. The priority is set according to the ordering in this + list. + +Commands +^^^^^^^^ + +This module provides the following commands: + +* :command:`matlab_get_version_from_release_name` +* :command:`matlab_get_release_name_from_version` +* :command:`matlab_get_version_from_matlab_run` +* :command:`matlab_extract_all_installed_versions_from_registry` +* :command:`matlab_get_all_valid_matlab_roots_from_registry` +* :command:`matlab_add_mex` +* :command:`matlab_get_mex_suffix` +* :command:`matlab_add_unit_test` + +.. command:: matlab_get_version_from_release_name + + .. versionadded:: 3.3 + + Returns the version of MATLAB from a release name: + + .. code-block:: cmake + + matlab_get_version_from_release_name(<release-name> <version-var>) + + The arguments are: + + ``<release-name>`` + Input release name string (e.g. ``R2023b``). + + ``<version-var>`` + The name of the variable in which to store the version of MATLAB. The + output result is e.g. ``23.2.0``. + + .. note:: + + This command provides correct versions mappings for MATLAB but not MCR. + +.. command:: matlab_get_release_name_from_version + + .. versionadded:: 3.3 + + Returns the release name from the version of MATLAB: + + .. code-block:: cmake + + matlab_get_release_name_from_version(<version> <release-name-var>) + + The arguments are: + + ``<version>`` + Input MATLAB version string (e.g. ``23.2.0``). + + ``<release-name-var>`` + The name of the variable in which to store the MATLAB release name. The + output result is e.g. ``R2023b``. + + .. note:: + + This command provides correct version mappings for MATLAB but not MCR. + +.. command:: matlab_get_version_from_matlab_run + + .. versionadded:: 3.3 + + Runs the specified MATLAB program and extracts the version of MATLAB/MCR, + given the full directory of the MATLAB/MCR installation path: + + .. code-block:: cmake + + matlab_get_version_from_matlab_run(<matlab-binary> <matlab-versions-var>) + + The arguments are: + + ``<matlab-binary>`` + The path to the ``matlab`` binary executable. + + ``<matlab-versions-var>`` + The name of the variable in which a list of extracted MATLAB versions + are stored. + + If the path provided for the MATLAB installation points to an MCR + installation, the version is extracted from the installed files. + +.. command:: matlab_extract_all_installed_versions_from_registry + + .. versionadded:: 3.3 + + Parses the Windows registry and finds all installed MATLAB versions: + + .. signature:: + matlab_extract_all_installed_versions_from_registry(<versions-var> + [REGISTRY_VIEW <view>]) + :target: matlab_extract_all_installed_versions_from_registry-keyword + + The arguments are: + + ``<versions-var>`` + The name of the variable in which to store the list of all MATLAB + versions found. + + ``REGISTRY_VIEW <view>`` + .. versionadded:: 3.30 + + Optional registry view argument that provides a more precise interface + on how to interact with the Windows Registry. The argument is passed + (or omitted) to :command:`cmake_host_system_information` without + further checks or modification. For example, ``<view>`` value can be + one of ``64``, ``32``, ``64_32``, ``32_64``, ``HOST``, ``TARGET``, + ``BOTH``. + + The old signature is: + + .. signature:: + matlab_extract_all_installed_versions_from_registry(<win64> <versions-var>) + :target: matlab_extract_all_installed_versions_from_registry-positional + + The arguments are: + + ``<win64>`` + Boolean whether to search for the 64-bit version of MATLAB. If set + to boolean true, 64-bit registry view will be searched. If set to + boolean false, 32-bit registry view will be searched. For finer + control, use the above signature. + + ``<versions-var>`` + The name of the variable in which to store the list of all MATLAB + versions found. + + This command is available on Windows only. The part of the registry + parsed is dependent on the host processor. + + The returned list contains all versions under + ``HKLM\SOFTWARE\Mathworks\MATLAB``, + ``HKLM\SOFTWARE\Mathworks\MATLAB Runtime`` and + ``HKLM\SOFTWARE\Mathworks\MATLAB Compiler Runtime`` or an empty list in + case an error occurred (or nothing found). + + .. note:: + + Only the versions are provided. No check is made over the existence of + the installation referenced in the registry. + +.. command:: matlab_get_all_valid_matlab_roots_from_registry + + .. versionadded:: 3.3 + + Returns all the possible MATLAB or MCR paths, according to a previously + given list: + + .. code-block:: cmake + + matlab_get_all_valid_matlab_roots_from_registry( + <matlab-versions> + <matlab-roots-var> + [REGISTRY_VIEW <view>] + ) + + This command populates the MATLAB root with valid versions of MATLAB or + MATLAB Runtime (MCR) and is mainly useful for the searching of all + possible MATLAB installations. Only the existing/accessible paths are + kept. + + The arguments are: + + ``<matlab-versions>`` + A :ref:`semicolon-separated list <CMake Language Lists>` of each of the + MATLAB or MCR installations. Specify it as a single string value. + + ``<matlab-roots-var>`` + The name of the variable in which to store a list of locations of each + of the MATLAB or MCR installations. + + The value of this variable is organized in triplets + ``(type,version_number,matlab_root_path)``, where ``type`` indicates + either ``MATLAB`` or ``MCR``. + + ``REGISTRY_VIEW <view>`` + .. versionadded:: 3.30 + + Optional registry view argument that provides a more precise interface + on how to interact with the Windows Registry. The argument is passed + (or omitted) to :command:`cmake_host_system_information` without + further checks or modification. For example, ``<view>`` value can be + one of ``64``, ``32``, ``64_32``, ``32_64``, ``HOST``, ``TARGET``, + ``BOTH``. + +.. command:: matlab_add_mex + + .. versionadded:: 3.3 + + Adds a target that compiles MATLAB MEX target file: + + .. code-block:: cmake + + matlab_add_mex( + NAME <name> + [EXECUTABLE | MODULE | SHARED] + SRC <sources>... + [OUTPUT_NAME <output-name>] + [DOCUMENTATION <file>] + [LINK_TO <targets>...] + [R2017b | R2018a] + [EXCLUDE_FROM_ALL] + [NO_IMPLICIT_LINK_TO_MATLAB_LIBRARIES] + [...] + ) + + This commands compiles the given sources with the current tool-chain in + order to produce a MEX file. The final name of the produced output may + be specified, as well as additional link libraries, and a documentation + entry for the MEX file. Remaining arguments of the call are passed to + the :command:`add_library` or :command:`add_executable` command. + + The arguments are: + + ``NAME <name>`` + The name of the target. + + ``SRC <sources>...`` + One or more source files to be compiled. + + ``LINK_TO <targets>...`` + A list of additional link dependencies. The target links to ``libmex`` + and ``libmx`` by default, unless the + ``NO_IMPLICIT_LINK_TO_MATLAB_LIBRARIES`` option is passed. + + ``OUTPUT_NAME <output-name>`` + If given, overrides the default name. The default name is the name of + the target without any prefix and with ``Matlab_MEX_EXTENSION`` suffix. + + ``DOCUMENTATION <file>`` + If given, the ``<file>`` will be considered as being the documentation + file for the MEX file. This file is copied into the same folder without + any processing, with the same name as the final MEX file, and with + extension ``.m``. In that case, typing ``help <name>`` in MATLAB + prints the documentation contained in this file. + + The documentation file is not processed and should be in the following + format: + + .. code-block:: matlab + + % This is the documentation + function ret = mex_target_output_name(input1) + + ``R2017b`` or ``R2018a`` + .. versionadded:: 3.14 + + May be given to specify the version of the C API + to use: ``R2017b`` specifies the traditional (separate complex) C API, + and corresponds to the ``-R2017b`` flag for the ``mex`` command. + ``R2018a`` specifies the new interleaved complex C API, and corresponds + to the ``-R2018a`` flag for the ``mex`` command. Ignored for MATLAB + versions prior to R2018a. Defaults to ``R2017b``. + + ``MODULE`` or ``SHARED`` + .. versionadded:: 3.7 + + May be given to specify the type of library to be created. + + ``EXECUTABLE`` + .. versionadded:: 3.7 + + May be given to create an executable instead of a library. If no type + is given explicitly, the default type is ``SHARED``. + + ``EXCLUDE_FROM_ALL`` + This option has the same meaning as the :prop_tgt:`EXCLUDE_FROM_ALL` + target property and is forwarded to the :command:`add_library`, or + :command:`add_executable` command. + + ``NO_IMPLICIT_LINK_TO_MATLAB_LIBRARIES`` + .. versionadded:: 3.24 + + This option permits to disable the automatic linking of MATLAB + libraries, so that only the libraries that are actually required can be + linked via the ``LINK_TO`` option. + +.. command:: matlab_get_mex_suffix + + .. versionadded:: 3.3 + + Returns the extension to be used for the MEX files (the suffix): + + .. code-block:: cmake + + matlab_get_mex_suffix(<matlab-root> <mex-suffix-var>) + + The arguments are: + + ``<matlab-root>`` + The root of MATLAB/MCR installation. For example, the value of the + ``Matlab_ROOT_DIR`` variable. + + ``<mex-suffix-var>`` + The name of the variable in which the suffix will be returned. + + This command is platform and architecture dependent. It should not be + called before the appropriate MATLAB root has been found. + +.. command:: matlab_add_unit_test + + .. versionadded:: 3.3 + + Adds a MATLAB unit test file to the project's test set of CMake/CTest: + + .. code-block:: cmake + + matlab_add_unit_test( + NAME <name> + UNITTEST_FILE <matlab-file-containing-unittest.m> + [CUSTOM_TEST_COMMAND <matlab-command-to-run-as-test>] + [UNITTEST_PRECOMMAND <matlab-command-to-run>] + [TIMEOUT <timeout>] + [ADDITIONAL_PATH <paths>...] + [MATLAB_ADDITIONAL_STARTUP_OPTIONS <options>...] + [TEST_ARGS <args>...] + [NO_UNITTEST_FRAMEWORK] + [WORKING_DIRECTORY <dir>] + ) + + By default, the MATLAB unit test framework will be used (>= 2013a) to run + the added MATLAB script, but regular ``.m`` files returning an exit code + can be used as well (0 indicating a success). + + This command requires the component ``MAIN_PROGRAM`` and hence is not + available for an MCR installation. + + The unit test uses the MATLAB unittest framework (default, available + starting MATLAB 2013b+) except if the option ``NO_UNITTEST_FRAMEWORK`` + is given. + + The command expects one MATLAB test script file to be given. + In the case ``NO_UNITTEST_FRAMEWORK`` is given, the unittest script file + should contain the script to be run, plus an exit command with the exit + value. This exit value will be passed to the ctest framework (0 success, + non 0 failure). Additional arguments accepted by :command:`add_test` can + be passed through ``TEST_ARGS`` (e.g. ``CONFIGURATIONS <config> ...``). + + The arguments are: + + ``NAME <name>`` + The name of the unittest in ctest. + + ``UNITTEST_FILE <matlab-file-containing-unittest.m>`` + The MATLAB unittest file. Its path will be automatically added to the + MATLAB path. + + ``CUSTOM_TEST_COMMAND <matlab-command-to-run-as-test>`` + MATLAB script command to run as the test. + If this is not set, then the following is run: + ``runtests('matlab_file_name'), exit(max([ans(1,:).Failed]))`` where + ``matlab_file_name`` is the ``UNITTEST_FILE`` without the extension. + + ``UNITTEST_PRECOMMAND <matlab-command-to-run>`` + MATLAB script command to be ran before the file + containing the test (e.g. GPU device initialization based on CMake + variables). + + ``TIMEOUT <timeout>`` + The test timeout in seconds. Defaults to 180 seconds as the + MATLAB unit test may hang. + + ``ADDITIONAL_PATH <paths>...`` + A list of paths to add to the MATLAB path prior to running the unit + test. + + ``MATLAB_ADDITIONAL_STARTUP_OPTIONS <options>`` + A list of additional option in order to run MATLAB from the command + line. The ``-nosplash``, ``-nodesktop``, and ``-nodisplay`` options + are always added automatically. + + ``TEST_ARGS <args>...`` + Additional options provided to the add_test command. These + options are added to the default options (e.g. ``CONFIGURATIONS Release``). + + ``NO_UNITTEST_FRAMEWORK`` + When set, indicates that the test should not + use the unittest framework of MATLAB (available for versions >= R2013a). + + ``WORKING_DIRECTORY <dir>`` + This will be the working directory for the test. If specified it will + also be the output directory used for the log file of the test run. + If not specified the temporary directory ``${CMAKE_BINARY_DIR}/Matlab`` + will be used as the working directory and the log location. + +Known Issues +^^^^^^^^^^^^ + +**Symbol clash in a MEX target** + By default, every symbol inside a MEX + file defined with the command :command:`matlab_add_mex` have hidden + visibility, except for the entry point. This is the default behavior of + the MEX compiler, which lowers the risk of symbol collision between the + libraries shipped with MATLAB, and the libraries to which the MEX file is + linking to. This is also the default on Windows platforms. + + However, this is not sufficient in certain case, where for instance the + MEX file is linking against libraries that are already loaded by MATLAB, + even if those libraries have different SONAMES. + A possible solution is to hide the symbols of the libraries to which the + MEX target is linking to. This can be achieved in GNU GCC compilers with + the linker option ``-Wl,--exclude-libs,ALL``. + +**Tests using GPU resources** + In case the MEX file is using the GPU and in order to be able to run unit + tests on this MEX file, the GPU resources should be properly released by + MATLAB. A possible solution is to make MATLAB aware of the use of the + GPU resources in the session, which can be performed by a command, such + as ``D = gpuDevice()``, at the beginning of the test script (or via a + fixture). + +Examples +^^^^^^^^ + +Finding MATLAB and linking imported target to a project target: + +.. code-block:: cmake + + find_package(Matlab) + target_link_libraries(example PRIVATE Matlab::mx) #]=======================================================================] cmake_policy(PUSH) @@ -363,23 +829,7 @@ file(MAKE_DIRECTORY "${_matlab_temporary_folder}") -#[=======================================================================[.rst: -.. command:: matlab_get_version_from_release_name - - .. code-block:: cmake - - matlab_get_version_from_release_name(release version) - - * Input: ``release`` is the release name (e.g. R2023b) - * Output: ``version`` is the version of Matlab (e.g. 23.2.0) - - Returns the version of Matlab from a release name - - .. note:: - - This command provides correct versions mappings for Matlab but not MCR. - -#]=======================================================================] +# Public. macro(matlab_get_version_from_release_name release_name version_name) string(REGEX MATCHALL "${release_name}=([0-9]+\\.[0-9]+)" _matched ${MATLAB_VERSIONS_MAPPING}) @@ -394,24 +844,7 @@ endmacro() - -#[=======================================================================[.rst: -.. command:: matlab_get_release_name_from_version - - .. code-block:: cmake - - matlab_get_release_name_from_version(version release_name) - - * Input: ``version`` is the version of Matlab (e.g. 23.2.0) - * Output: ``release_name`` is the release name (R2023b) - - Returns the release name from the version of Matlab - - .. note:: - - This command provides correct version mappings for Matlab but not MCR. - -#]=======================================================================] +# Public. function(matlab_get_release_name_from_version version release_name) # only the major.minor version is used @@ -428,7 +861,6 @@ endfunction() - # extracts all the supported release names (R2022b...) of Matlab # internal use macro(matlab_get_supported_releases list_releases) @@ -444,8 +876,6 @@ unset(_var) endmacro() - - # extracts all the supported versions of Matlab # internal use macro(matlab_get_supported_versions list_versions) @@ -461,47 +891,7 @@ unset(_var) endmacro() - -#[=======================================================================[.rst: -.. command:: matlab_extract_all_installed_versions_from_registry - - This function parses the Windows registry and finds the Matlab versions that - are installed. The found versions are stored in a given ``<versions-var>``. - - .. signature:: - matlab_extract_all_installed_versions_from_registry(<versions-var> - [REGISTRY_VIEW view]) - :target: matlab_extract_all_installed_versions_from_registry-keyword - - .. versionadded:: 3.30 - - * Output: ``<versions-var>`` is a list of all the versions of Matlab found - * Input: ``REGISTRY_VIEW`` Optional registry view to use for registry - interaction. The argument is passed (or omitted) to - :command:`cmake_host_system_information` without further checks or - modification. - - .. signature:: - matlab_extract_all_installed_versions_from_registry(<win64> <versions-var>) - :target: matlab_extract_all_installed_versions_from_registry-positional - - * Input: ``win64`` is a boolean to search for the 64 bit version of - Matlab. Set to ``ON`` to use the 64bit registry view or ``OFF`` to use the - 32bit registry view. If finer control is needed, see signature above. - * Output: ``<versions-var>`` is a list of all the versions of Matlab found - - The returned list contains all versions under - ``HKLM\SOFTWARE\Mathworks\MATLAB``, - ``HKLM\SOFTWARE\Mathworks\MATLAB Runtime`` and - ``HKLM\SOFTWARE\Mathworks\MATLAB Compiler Runtime`` or an empty list in - case an error occurred (or nothing found). - - .. note:: - - Only the versions are provided. No check is made over the existence of the - installation referenced in the registry, - -#]=======================================================================] +# Public. function(matlab_extract_all_installed_versions_from_registry win64_or_matlab_versions) if(NOT CMAKE_HOST_WIN32) @@ -555,8 +945,6 @@ endfunction() - - # (internal) macro(extract_matlab_versions_from_registry_brute_force matlab_versions) # get the supported versions @@ -572,32 +960,7 @@ set(${matlab_versions} ${matlab_supported_versions}) endmacro() - -#[=======================================================================[.rst: -.. command:: matlab_get_all_valid_matlab_roots_from_registry - - Populates the Matlab root with valid versions of Matlab or - Matlab Runtime (MCR). - The returned matlab_roots is organized in triplets - ``(type,version_number,matlab_root_path)``, where ``type`` - indicates either ``MATLAB`` or ``MCR``. - - .. code-block:: cmake - - matlab_get_all_valid_matlab_roots_from_registry(matlab_versions matlab_roots [REGISTRY_VIEW view]) - - * Input: ``matlab_versions`` of each of the Matlab or MCR installations - * Output: ``matlab_roots`` location of each of the Matlab or MCR installations - * Input: ``REGISTRY_VIEW`` Optional registry view to use for registry - interaction. The argument is passed (or omitted) to - :command:`cmake_host_system_information` without further checks or - modification. - - .. versionadded:: 3.30 - The optional ``REGISTRY_VIEW`` argument was added to provide a more precise - interface on how to interact with the Windows Registry. - -#]=======================================================================] +# Public. function(matlab_get_all_valid_matlab_roots_from_registry matlab_versions matlab_roots) # The matlab_versions comes either from @@ -665,20 +1028,7 @@ set(${matlab_roots} ${_matlab_roots_list} PARENT_SCOPE) endfunction() -#[=======================================================================[.rst: -.. command:: matlab_get_mex_suffix - - Returns the extension of the mex files (the suffixes). - This function should not be called before the appropriate Matlab root has - been found. - - .. code-block:: cmake - - matlab_get_mex_suffix(matlab_root mex_suffix) - - * Input: ``matlab_root`` root of Matlab/MCR install e.g. ``Matlab_ROOT_DIR`` - * Output: ``mex_suffix`` variable name in which the suffix will be returned. -#]=======================================================================] +# Public. function(matlab_get_mex_suffix matlab_root mex_suffix) # find_program does not consider script suffix .bat for Matlab mexext.bat on Windows @@ -754,21 +1104,7 @@ set(${mex_suffix} ${_matlab_mex_extension} PARENT_SCOPE) endfunction() - -#[=======================================================================[.rst: -.. command:: matlab_get_version_from_matlab_run - - This function runs Matlab program specified on arguments and extracts its - version. If the path provided for the Matlab installation points to an MCR - installation, the version is extracted from the installed files. - - .. code-block:: cmake - - matlab_get_version_from_matlab_run(matlab_binary_path matlab_list_versions) - - * Input: ``matlab_binary_path`` path of the `matlab` binary executable - * Output: ``matlab_list_versions`` the version extracted from Matlab -#]=======================================================================] +# Public. function(matlab_get_version_from_matlab_run matlab_binary_program matlab_list_versions) set(${matlab_list_versions} "" PARENT_SCOPE) @@ -919,77 +1255,7 @@ endfunction() -#[=======================================================================[.rst: -.. command:: matlab_add_unit_test - - Adds a Matlab unit test to the test set of cmake/ctest. - This command requires the component ``MAIN_PROGRAM`` and hence is not - available for an MCR installation. - - The unit test uses the Matlab unittest framework (default, available - starting Matlab 2013b+) except if the option ``NO_UNITTEST_FRAMEWORK`` - is given. - - The function expects one Matlab test script file to be given. - In the case ``NO_UNITTEST_FRAMEWORK`` is given, the unittest script file - should contain the script to be run, plus an exit command with the exit - value. This exit value will be passed to the ctest framework (0 success, - non 0 failure). Additional arguments accepted by :command:`add_test` can be - passed through ``TEST_ARGS`` (eg. ``CONFIGURATION <config> ...``). - - .. code-block:: cmake - - matlab_add_unit_test( - NAME <name> - UNITTEST_FILE matlab_file_containing_unittest.m - [CUSTOM_TEST_COMMAND matlab_command_to_run_as_test] - [UNITTEST_PRECOMMAND matlab_command_to_run] - [TIMEOUT timeout] - [ADDITIONAL_PATH path1 [path2 ...]] - [MATLAB_ADDITIONAL_STARTUP_OPTIONS option1 [option2 ...]] - [TEST_ARGS arg1 [arg2 ...]] - [NO_UNITTEST_FRAMEWORK] - ) - - Function Parameters: - - ``NAME`` - name of the unittest in ctest. - ``UNITTEST_FILE`` - the matlab unittest file. Its path will be automatically - added to the Matlab path. - ``CUSTOM_TEST_COMMAND`` - Matlab script command to run as the test. - If this is not set, then the following is run: - ``runtests('matlab_file_name'), exit(max([ans(1,:).Failed]))`` - where ``matlab_file_name`` is the ``UNITTEST_FILE`` without the extension. - ``UNITTEST_PRECOMMAND`` - Matlab script command to be ran before the file - containing the test (eg. GPU device initialization based on CMake - variables). - ``TIMEOUT`` - the test timeout in seconds. Defaults to 180 seconds as the - Matlab unit test may hang. - ``ADDITIONAL_PATH`` - a list of paths to add to the Matlab path prior to - running the unit test. - ``MATLAB_ADDITIONAL_STARTUP_OPTIONS`` - a list of additional option in order - to run Matlab from the command line. - ``-nosplash -nodesktop -nodisplay`` are always added. - ``TEST_ARGS`` - Additional options provided to the add_test command. These - options are added to the default options (eg. "CONFIGURATIONS Release") - ``NO_UNITTEST_FRAMEWORK`` - when set, indicates that the test should not - use the unittest framework of Matlab (available for versions >= R2013a). - ``WORKING_DIRECTORY`` - This will be the working directory for the test. If specified it will - also be the output directory used for the log file of the test run. - If not specified the temporary directory ``${CMAKE_BINARY_DIR}/Matlab`` will - be used as the working directory and the log location. - -#]=======================================================================] +# Public. function(matlab_add_unit_test) if(NOT Matlab_MAIN_PROGRAM) @@ -1042,93 +1308,7 @@ ) endfunction() - -#[=======================================================================[.rst: -.. command:: matlab_add_mex - - Adds a Matlab MEX target. - This commands compiles the given sources with the current tool-chain in - order to produce a MEX file. The final name of the produced output may be - specified, as well as additional link libraries, and a documentation entry - for the MEX file. Remaining arguments of the call are passed to the - :command:`add_library` or :command:`add_executable` command. - - .. code-block:: cmake - - matlab_add_mex( - NAME <name> - [EXECUTABLE | MODULE | SHARED] - SRC src1 [src2 ...] - [OUTPUT_NAME output_name] - [DOCUMENTATION file.txt] - [LINK_TO target1 target2 ...] - [R2017b | R2018a] - [EXCLUDE_FROM_ALL] - [NO_IMPLICIT_LINK_TO_MATLAB_LIBRARIES] - [...] - ) - - Function Parameters: - - ``NAME`` - name of the target. - ``SRC`` - list of source files. - ``LINK_TO`` - a list of additional link dependencies. The target links to ``libmex`` - and ``libmx`` by default, unless the - ``NO_IMPLICIT_LINK_TO_MATLAB_LIBRARIES`` option is passed. - ``OUTPUT_NAME`` - if given, overrides the default name. The default name is - the name of the target without any prefix and - with ``Matlab_MEX_EXTENSION`` suffix. - ``DOCUMENTATION`` - if given, the file ``file.txt`` will be considered as - being the documentation file for the MEX file. This file is copied into - the same folder without any processing, with the same name as the final - mex file, and with extension `.m`. In that case, typing ``help <name>`` - in Matlab prints the documentation contained in this file. - ``R2017b`` or ``R2018a`` - .. versionadded:: 3.14 - - May be given to specify the version of the C API - to use: ``R2017b`` specifies the traditional (separate complex) C API, - and corresponds to the ``-R2017b`` flag for the `mex` command. ``R2018a`` - specifies the new interleaved complex C API, and corresponds to the - ``-R2018a`` flag for the `mex` command. Ignored if MATLAB version prior - to R2018a. Defaults to ``R2017b``. - - ``MODULE`` or ``SHARED`` - .. versionadded:: 3.7 - - May be given to specify the type of library to be - created. - - ``EXECUTABLE`` - .. versionadded:: 3.7 - - May be given to create an executable instead of - a library. If no type is given explicitly, the type is ``SHARED``. - ``EXCLUDE_FROM_ALL`` - This option has the same meaning as for :prop_tgt:`EXCLUDE_FROM_ALL` and - is forwarded to :command:`add_library` or :command:`add_executable` - commands. - ``NO_IMPLICIT_LINK_TO_MATLAB_LIBRARIES`` - .. versionadded:: 3.24 - - This option permits to disable the automatic linking of MATLAB - libraries, so that only the libraries that are actually required can be - linked via the ``LINK_TO`` option. - - The documentation file is not processed and should be in the following - format: - - :: - - % This is the documentation - function ret = mex_target_output_name(input1) - -#]=======================================================================] +# Public. function(matlab_add_mex) set(options EXECUTABLE MODULE SHARED R2017b R2018a EXCLUDE_FROM_ALL NO_IMPLICIT_LINK_TO_MATLAB_LIBRARIES) @@ -1324,7 +1504,6 @@ endfunction() - # (internal) # Used to get the version of matlab, using caching. This basically transforms the # output of the root list, with possible unknown version, to a version @@ -1470,7 +1649,6 @@ endfunction() - function(_Matlab_VersionInfoXML matlab_root _version) set(_ver "unknown") @@ -1489,7 +1667,6 @@ endfunction() - # Utility function for finding Matlab or MCR on Win32 function(_Matlab_find_instances_win32 matlab_roots) # On WIN32, we look for Matlab installation in the registry @@ -1812,7 +1989,6 @@ endif() - set(MATLAB_INCLUDE_DIR_TO_LOOK ${Matlab_ROOT_DIR}/extern/include) if(CMAKE_SIZEOF_VOID_P EQUAL 4) set(_matlab_current_suffix ${_matlab_bin_suffix_32bits}) @@ -1844,8 +2020,6 @@ message(STATUS "[MATLAB] _matlab_lib_prefix_for_search = ${_matlab_lib_prefix_for_search} | _matlab_lib_dir_for_search = ${_matlab_lib_dir_for_search}") endif() - - # internal # This small stub around find_library is to prevent any pollution of CMAKE_FIND_LIBRARY_PREFIXES in the global scope. # This is the function to be used below instead of the find_library directives.
diff --git a/Modules/FindMotif.cmake b/Modules/FindMotif.cmake index d72b193..1ce164c 100644 --- a/Modules/FindMotif.cmake +++ b/Modules/FindMotif.cmake
@@ -5,7 +5,11 @@ FindMotif --------- -Finds Motif (or LessTif) graphical user interface toolkit. +Finds Motif (or LessTif) graphical user interface toolkit: + +.. code-block:: cmake + + find_package(Motif [...]) Result Variables ^^^^^^^^^^^^^^^^ @@ -13,27 +17,53 @@ This module defines the following variables: ``Motif_FOUND`` - Boolean indicating whether the Motif was found. For backward compatibility, - the ``MOTIF_FOUND`` variable is also set to the same value. + .. versionadded:: 3.3 + + Boolean indicating whether Motif was found. Cache Variables ^^^^^^^^^^^^^^^ The following cache variables may also be set: -``MOTIF_LIBRARIES`` - Libraries needed to link to Motif. ``MOTIF_INCLUDE_DIR`` Include directories needed to use Motif. +``MOTIF_LIBRARIES`` + Libraries needed to link to Motif. + +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``MOTIF_FOUND`` + .. deprecated:: 4.2 + Use ``Motif_FOUND``, which has the same value. + + Boolean indicating whether Motif was found. + Examples ^^^^^^^^ -Finding Motif: +Finding Motif and creating an imported interface target for linking it to a +project target: .. code-block:: cmake find_package(Motif) + + if(Motif_FOUND AND NOT TARGET Motif::Motif) + add_library(Motif::Motif INTERFACE IMPORTED) + set_target_properties( + Motif::Motif + PROPERTIES + INTERFACE_INCLUDE_DIRECTORIES "${MOTIF_INCLUDE_DIR}" + INTERFACE_LINK_LIBRARIES "${MOTIF_LIBRARIES}" + ) + endif() + + target_link_libraries(example PRIVATE Motif::Motif) #]=======================================================================] if(UNIX)
diff --git a/Modules/FindMsys.cmake b/Modules/FindMsys.cmake index 0d78c9b..fcf62b1 100644 --- a/Modules/FindMsys.cmake +++ b/Modules/FindMsys.cmake
@@ -8,7 +8,11 @@ .. versionadded:: 3.21 Finds MSYS, a POSIX-compatible environment that runs natively on Microsoft -Windows. +Windows: + +.. code-block:: cmake + + find_package(Msys [...]) .. note:: @@ -23,6 +27,11 @@ This module defines the following variables: +``Msys_FOUND`` + .. versionadded:: 4.2 + + Boolean indicating whether MSYS was found. + ``MSYS_INSTALL_PATH`` The path to the MSYS root installation directory. @@ -32,7 +41,7 @@ Finding the MSYS installation and using its path in a custom find module: .. code-block:: cmake - :caption: FindFoo.cmake + :caption: ``FindFoo.cmake`` find_package(Msys) find_program(Foo_EXECUTABLE NAMES foo PATHS ${MSYS_INSTALL_PATH}/usr/bin) @@ -65,3 +74,9 @@ mark_as_advanced(MSYS_CMD) endif () + +if(MSYS_CMD AND MSYS_INSTALL_PATH) + set(Msys_FOUND TRUE) +else() + set(Msys_FOUND FALSE) +endif()
diff --git a/Modules/FindODBC.cmake b/Modules/FindODBC.cmake index 6e103d2..e8692bd 100644 --- a/Modules/FindODBC.cmake +++ b/Modules/FindODBC.cmake
@@ -7,11 +7,16 @@ .. versionadded:: 3.12 -Finds the Open Database Connectivity (ODBC) library, which implements a standard -API for accessing database systems. ODBC enables applications to communicate -with different database management systems (DBMS) using a common set of -functions. Communication with a specific database is handled through ODBC -drivers, which the library loads at runtime. +Finds the Open Database Connectivity (ODBC) library, which implements a +standard API for accessing database systems: + +.. code-block:: cmake + + find_package(ODBC [...]) + +ODBC enables applications to communicate with different database management +systems (DBMS) using a common set of functions. Communication with a specific +database is handled through ODBC drivers, which the library loads at runtime. On Windows, when building with Visual Studio, this module assumes the ODBC library is provided by the available Windows SDK. @@ -36,7 +41,7 @@ This module defines the following variables: ``ODBC_FOUND`` - Boolean indicating whether ODBC is found. + Boolean indicating whether ODBC was found. ``ODBC_INCLUDE_DIRS`` Include directories containing headers needed to use ODBC. @@ -76,19 +81,19 @@ Examples ^^^^^^^^ -Finding and using ODBC -"""""""""""""""""""""" +Example: Finding and Using ODBC +""""""""""""""""""""""""""""""" Finding ODBC and linking it to a project target: .. code-block:: cmake - :caption: CMakeLists.txt + :caption: ``CMakeLists.txt`` find_package(ODBC) target_link_libraries(project_target PRIVATE ODBC::ODBC) -Finding a custom ODBC installation on Unix-like systems -""""""""""""""""""""""""""""""""""""""""""""""""""""""" +Example: Finding a Custom ODBC Installation +""""""""""""""""""""""""""""""""""""""""""" The following examples are for Unix-like systems and demonstrate how to set hint and cache variables during the CMake configuration phase to help this module
diff --git a/Modules/FindOpenACC.cmake b/Modules/FindOpenACC.cmake index b78d381..efecb6a 100644 --- a/Modules/FindOpenACC.cmake +++ b/Modules/FindOpenACC.cmake
@@ -7,9 +7,12 @@ .. versionadded:: 3.10 -Detect OpenACC support by the compiler. +Finds and detects the OpenACC support in a compiler: -This module can be used to detect OpenACC support in a compiler. +.. code-block:: cmake + + find_package(OpenACC [<version>] [...]) + If the compiler supports OpenACC, the flags required to compile with OpenACC support are returned in variables for the different languages. Currently, only NVHPC, PGI, GNU and Cray compilers are supported. @@ -17,28 +20,32 @@ Imported Targets ^^^^^^^^^^^^^^^^ -.. versionadded:: 3.16 - -The module provides :prop_tgt:`IMPORTED` targets: +This module provides the following :ref:`Imported Targets`: ``OpenACC::OpenACC_<lang>`` - Target for using OpenACC from ``<lang>``. + .. versionadded:: 3.16 -Variables -^^^^^^^^^ + Target encapsulating the usage requirements for using OpenACC from + ``<lang>``. This target is available only if OpenACC support is found. + ``<lang>`` is one of C, CXX, or Fortran. -The module defines the following variables: +Result Variables +^^^^^^^^^^^^^^^^ + +This module defines the following variables: ``OpenACC_FOUND`` .. versionadded:: 3.25 - Variable indicating that OpenACC flags for at least one languages have been found. + Boolean indicating that OpenACC flags for at least one language were + found. -This module will set the following variables per language in your +This module will set the following variables per language in the project, where ``<lang>`` is one of C, CXX, or Fortran: ``OpenACC_<lang>_FOUND`` - Variable indicating if OpenACC support for ``<lang>`` was detected. + Boolean indicating whether OpenACC support for language ``<lang>`` was + detected. ``OpenACC_<lang>_FLAGS`` OpenACC compiler flags for ``<lang>``, separated by spaces. ``OpenACC_<lang>_OPTIONS`` @@ -65,9 +72,21 @@ Input Variables ^^^^^^^^^^^^^^^ +This module accepts the following variables: + ``OpenACC_ACCEL_TARGET=<target>`` -If set, will the correct target accelerator flag set to the <target> will -be returned with OpenACC_<lang>_FLAGS. + If set, the correct target accelerator flag set to the ``<target>`` + will be returned with the ``OpenACC_<lang>_FLAGS`` variable. + +Examples +^^^^^^^^ + +Finding OpenACC support and linking the imported target to a project target: + +.. code-block:: cmake + + find_package(OpenACC) + target_link_libraries(example PRIVATE OpenACC::OpenACC_C) #]=======================================================================] cmake_policy(PUSH)
diff --git a/Modules/FindOpenAL.cmake b/Modules/FindOpenAL.cmake index dad9ada..766c563 100644 --- a/Modules/FindOpenAL.cmake +++ b/Modules/FindOpenAL.cmake
@@ -5,7 +5,11 @@ FindOpenAL ---------- -Finds the Open Audio Library (OpenAL). +Finds the Open Audio Library (OpenAL): + +.. code-block:: cmake + + find_package(OpenAL [...]) OpenAL is a cross-platform 3D audio API designed for efficient rendering of multichannel three-dimensional positional audio. It is commonly used in games @@ -34,10 +38,9 @@ This module defines the following variables: ``OpenAL_FOUND`` - Boolean indicating whether the OpenAL is found. For backward compatibility, - the ``OPENAL_FOUND`` variable is also set to the same value. -``OPENAL_VERSION_STRING`` - Human-readable string containing the version of OpenAL found. + .. versionadded:: 3.3 + + Boolean indicating whether OpenAL was found. Cache Variables ^^^^^^^^^^^^^^^ @@ -69,6 +72,17 @@ 5. Manually compiled framework: ``/Library/Frameworks``. 6. Add-on package: ``/opt``. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``OPENAL_FOUND`` + .. deprecated:: 4.2 + Use ``OpenAL_FOUND``, which has the same value. + + Boolean indicating whether OpenAL was found. + Examples ^^^^^^^^ @@ -126,7 +140,6 @@ find_package_handle_standard_args( OpenAL REQUIRED_VARS OPENAL_LIBRARY OPENAL_INCLUDE_DIR - VERSION_VAR OPENAL_VERSION_STRING ) mark_as_advanced(OPENAL_LIBRARY OPENAL_INCLUDE_DIR)
diff --git a/Modules/FindOpenCL.cmake b/Modules/FindOpenCL.cmake index 3be945b..ff4e1d2 100644 --- a/Modules/FindOpenCL.cmake +++ b/Modules/FindOpenCL.cmake
@@ -7,7 +7,17 @@ .. versionadded:: 3.1 -Finds Open Computing Language (OpenCL). +Finds Open Computing Language (OpenCL): + +.. code-block:: cmake + + find_package(OpenCL [<version>] [...]) + +OpenCL is a framework for writing programs that execute across heterogeneous +platforms, such as CPUs, GPUs, and other accelerators. + +.. versionadded:: 3.24 + Detection of OpenCL 3.0. .. versionadded:: 3.10 Detection of OpenCL 2.1 and 2.2. @@ -15,13 +25,13 @@ Imported Targets ^^^^^^^^^^^^^^^^ -.. versionadded:: 3.7 - -This module provides the following :ref:`Imported Targets`, if OpenCL has been -found: +This module provides the following :ref:`Imported Targets`: ``OpenCL::OpenCL`` - Target providing OpenCL usage requirements. + .. versionadded:: 3.7 + + Target encapsulating the OpenCL usage requirements, available if OpenCL + has been found. Result Variables ^^^^^^^^^^^^^^^^ @@ -29,18 +39,26 @@ This module defines the following variables: ``OpenCL_FOUND`` - True if OpenCL was found. -``OpenCL_INCLUDE_DIRS`` - Include directories needed to use OpenCL. -``OpenCL_LIBRARIES`` - Libraries needed to link to OpenCL. -``OpenCL_VERSION_STRING`` - Highest supported OpenCL version (e.g., ``1.2``). + Boolean indicating whether (the requested version of) OpenCL was found. + +``OpenCL_VERSION`` + .. versionadded:: 4.2 + + Highest supported OpenCL version found in form of ``<major>.<minor>`` + (e.g., ``1.2``). + ``OpenCL_VERSION_MAJOR`` The major version of the OpenCL implementation. + ``OpenCL_VERSION_MINOR`` The minor version of the OpenCL implementation. +``OpenCL_INCLUDE_DIRS`` + Include directories needed to use OpenCL. + +``OpenCL_LIBRARIES`` + Libraries needed to link to OpenCL. + Cache Variables ^^^^^^^^^^^^^^^ @@ -48,9 +66,21 @@ ``OpenCL_INCLUDE_DIR`` The OpenCL include directory. + ``OpenCL_LIBRARY`` The path to the OpenCL library. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``OpenCL_VERSION_STRING`` + .. deprecated:: 4.2 + Use ``OpenCL_VERSION``, which has the same value. + + Highest supported OpenCL version found in form of ``<major>.<minor>``. + Examples ^^^^^^^^ @@ -62,21 +92,28 @@ target_link_libraries(project_target PRIVATE OpenCL::OpenCL) #]=======================================================================] +cmake_policy(PUSH) +cmake_policy(SET CMP0140 NEW) + set(_OPENCL_x86 "(x86)") function(_FIND_OPENCL_VERSION) + include(CheckIncludeFiles) include(CheckSymbolExists) include(CMakePushCheckState) - set(CMAKE_REQUIRED_QUIET ${OpenCL_FIND_QUIETLY}) cmake_push_check_state() - foreach(VERSION "3_0" "2_2" "2_1" "2_0" "1_2" "1_1" "1_0") - set(CMAKE_REQUIRED_INCLUDES "${OpenCL_INCLUDE_DIR}") - if(EXISTS ${OpenCL_INCLUDE_DIR}/Headers/cl.h) + set(CMAKE_REQUIRED_QUIET ${OpenCL_FIND_QUIETLY}) + set(CMAKE_REQUIRED_INCLUDES "${OpenCL_INCLUDE_DIR}") + + check_include_files(OpenCL/cl.h OpenCL_HAVE_OPENCL_CL_H) + + foreach(VERSION "3_0" "2_2" "2_1" "2_0" "1_2" "1_1" "1_0") + if(OpenCL_HAVE_OPENCL_CL_H) check_symbol_exists( CL_VERSION_${VERSION} - "Headers/cl.h" + "OpenCL/cl.h" OPENCL_VERSION_${VERSION}) else() check_symbol_exists( @@ -87,16 +124,25 @@ if(OPENCL_VERSION_${VERSION}) string(REPLACE "_" "." VERSION "${VERSION}") - set(OpenCL_VERSION_STRING ${VERSION} PARENT_SCOPE) + set(OpenCL_VERSION ${VERSION}) + set(OpenCL_VERSION_STRING "${OpenCL_VERSION}") string(REGEX MATCHALL "[0-9]+" version_components "${VERSION}") list(GET version_components 0 major_version) list(GET version_components 1 minor_version) - set(OpenCL_VERSION_MAJOR ${major_version} PARENT_SCOPE) - set(OpenCL_VERSION_MINOR ${minor_version} PARENT_SCOPE) + set(OpenCL_VERSION_MAJOR ${major_version}) + set(OpenCL_VERSION_MINOR ${minor_version}) break() endif() endforeach() cmake_pop_check_state() + + return( + PROPAGATE + OpenCL_VERSION + OpenCL_VERSION_MAJOR + OpenCL_VERSION_MINOR + OpenCL_VERSION_STRING + ) endfunction() find_path(OpenCL_INCLUDE_DIR @@ -200,7 +246,8 @@ find_package_handle_standard_args( OpenCL REQUIRED_VARS OpenCL_LIBRARY OpenCL_INCLUDE_DIR - VERSION_VAR OpenCL_VERSION_STRING) + VERSION_VAR OpenCL_VERSION +) mark_as_advanced( OpenCL_INCLUDE_DIR @@ -219,3 +266,5 @@ set_target_properties(OpenCL::OpenCL PROPERTIES INTERFACE_INCLUDE_DIRECTORIES "${OpenCL_INCLUDE_DIRS}") endif() + +cmake_policy(POP)
diff --git a/Modules/FindOpenGL.cmake b/Modules/FindOpenGL.cmake index a842756..6362edf 100644 --- a/Modules/FindOpenGL.cmake +++ b/Modules/FindOpenGL.cmake
@@ -5,28 +5,56 @@ FindOpenGL ---------- -FindModule for OpenGL and OpenGL Utility Library (GLU). +Finds the OpenGL and OpenGL Utility Library (GLU), for using OpenGL in a +CMake project: + +.. code-block:: cmake + + find_package(OpenGL [COMPONENTS <components>...] [...]) + +OpenGL (Open Graphics Library) is a cross-platform API for rendering 2D and +3D graphics. It is widely used in CAD, games, and visualization software. + +* *GL* refers to the core OpenGL library, which provides the fundamental + graphics rendering API. + +* *GLU* (OpenGL Utility Library) is a companion library that offers utility + functions built on top of OpenGL, such as tessellation and more complex + shape drawing. .. versionchanged:: 3.2 X11 is no longer added as a dependency on Unix/Linux systems. .. versionadded:: 3.10 - GLVND support on Linux. See the :ref:`Linux Specific` section below. + GLVND (GL Vendor-Neutral Dispatch library) support on Linux. See the + :ref:`Linux Specific` section below. -Optional COMPONENTS -^^^^^^^^^^^^^^^^^^^ +Components +^^^^^^^^^^ -.. versionadded:: 3.10 +This module supports optional components which can be specified with the +:command:`find_package` command: -This module respects several optional COMPONENTS: +.. code-block:: cmake + + find_package(OpenGL [COMPONENTS <components>...]) + +Supported components are: ``EGL`` - The EGL interface between OpenGL, OpenGL ES and the underlying windowing system. + .. versionadded:: 3.10 + + The EGL interface between OpenGL, OpenGL ES and the underlying windowing + system. ``GLX`` + .. versionadded:: 3.10 + An extension to X that interfaces OpenGL, OpenGL ES with X window system. ``OpenGL`` + .. versionadded:: 3.10 + The cross platform API for 3D graphics. ``GLES2`` @@ -42,103 +70,179 @@ Imported Targets ^^^^^^^^^^^^^^^^ -.. versionadded:: 3.8 - -This module defines the :prop_tgt:`IMPORTED` targets: +This module provides the following :ref:`Imported Targets`: ``OpenGL::GL`` - Defined to the platform-specific OpenGL libraries if the system has OpenGL. -``OpenGL::GLU`` - Defined if the system has OpenGL Utility Library (GLU). + .. versionadded:: 3.8 -.. versionadded:: 3.10 - Additionally, the following GLVND-specific library targets are defined: + Target encapsulating the usage requirements of platform-specific OpenGL + libraries, available if OpenGL is found. + +``OpenGL::GLU`` + .. versionadded:: 3.8 + + Target encapsulating the OpenGL Utility Library (GLU) usage requirements, + available if GLU is found. + +Additionally, the following GLVND-specific library imported targets are +provided: ``OpenGL::OpenGL`` - Defined to libOpenGL if the system is GLVND-based. + .. versionadded:: 3.10 + + Target encapsulating the libOpenGL usage requirements, available if + system is GLVND-based and OpenGL is found. + ``OpenGL::GLX`` - Defined if the system has OpenGL Extension to the X Window System (GLX). + .. versionadded:: 3.10 + + Target encapsulating the usage requirements of the OpenGL Extension to + the X Window System (GLX), available if OpenGL and GLX are found. + ``OpenGL::EGL`` - Defined if the system has EGL. + .. versionadded:: 3.10 + + Target encapsulating the EGL usage requirements, available if OpenGL and EGL + are found. + ``OpenGL::GLES2`` .. versionadded:: 3.27 - Defined if the system has GLES2. + Target encapsulating the GLES2 usage requirements, available if OpenGL and + GLES2 are found. + ``OpenGL::GLES3`` .. versionadded:: 3.27 - Defined if the system has GLES3. + Target encapsulating the GLES3 usage requirements, available if OpenGL and + GLES3 are found. Result Variables ^^^^^^^^^^^^^^^^ -This module sets the following variables: +This module defines the following variables: -``OPENGL_FOUND`` - True, if the system has OpenGL and all components are found. +``OpenGL_FOUND`` + .. versionadded:: 3.3 + + Boolean indicating whether OpenGL and all requested components were found. + ``OPENGL_XMESA_FOUND`` - True, if the system has XMESA. + Boolean indicating whether OpenGL XMESA was found. + ``OPENGL_GLU_FOUND`` - True, if the system has GLU. + Boolean indicating whether GLU was found. + ``OpenGL_OpenGL_FOUND`` - True, if the system has an OpenGL library. + .. versionadded:: 3.10 + + Boolean indicating whether the GLVND OpenGL library was found. + ``OpenGL_GLX_FOUND`` - True, if the system has GLX. + .. versionadded:: 3.10 + + Boolean indicating whether GLVND GLX was found. + ``OpenGL_EGL_FOUND`` - True, if the system has EGL. -``OpenGL::GLES2`` - Defined if the system has GLES2. -``OpenGL::GLES3`` - Defined if the system has GLES3. -``OPENGL_INCLUDE_DIR`` - Path to the OpenGL include directory. - The ``OPENGL_INCLUDE_DIRS`` variable is preferred. -``OPENGL_EGL_INCLUDE_DIRS`` - Path to the EGL include directory. -``OPENGL_LIBRARIES`` - Paths to the OpenGL library, windowing system libraries, and GLU libraries. - On Linux, this assumes GLX and is never correct for EGL-based targets. - Clients are encouraged to use the ``OpenGL::*`` import targets instead. + .. versionadded:: 3.10 + + Boolean indicating whether GLVND EGL was found. + +``OpenGL_GLES2_FOUND`` + .. versionadded:: 3.27 + + Boolean indicating whether GLES2 was found. + +``OpenGL_GLES3_FOUND`` + .. versionadded:: 3.27 + + Boolean indicating whether GLES3 was found. + ``OPENGL_INCLUDE_DIRS`` .. versionadded:: 3.29 Paths to the OpenGL include directories. -.. versionadded:: 3.10 - Variables for GLVND-specific libraries ``OpenGL``, ``EGL`` and ``GLX``. +``OPENGL_EGL_INCLUDE_DIRS`` + .. versionadded:: 3.10 -Cache variables + Path to the EGL include directory. + +``OPENGL_LIBRARIES`` + Paths to the OpenGL library, windowing system libraries, and GLU libraries. + On Linux, this assumes GLX and is never correct for EGL-based targets. + Clients are encouraged to use the ``OpenGL::*`` imported targets instead. + +Cache Variables ^^^^^^^^^^^^^^^ The following cache variables may also be set: -``OPENGL_egl_LIBRARY`` - Path to the EGL library. -``OPENGL_glu_LIBRARY`` - Path to the GLU library. -``OPENGL_glx_LIBRARY`` - Path to the GLVND 'GLX' library. -``OPENGL_opengl_LIBRARY`` - Path to the GLVND 'OpenGL' library -``OPENGL_gl_LIBRARY`` - Path to the OpenGL library. New code should prefer the ``OpenGL::*`` import - targets. -``OPENGL_gles2_LIBRARY`` - .. versionadded:: 3.27 - - Path to the OpenGL GLES2 library. -``OPENGL_gles3_LIBRARY`` - .. versionadded:: 3.27 - - Path to the OpenGL GLES3 library. +``OPENGL_INCLUDE_DIR`` + The path to the OpenGL include directory. + The ``OPENGL_INCLUDE_DIRS`` variable is preferred. ``OPENGL_GLU_INCLUDE_DIR`` .. versionadded:: 3.29 Path to the OpenGL GLU include directory. -.. versionadded:: 3.10 - Variables for GLVND-specific libraries ``OpenGL``, ``EGL`` and ``GLX``. +``OPENGL_egl_LIBRARY`` + .. versionadded:: 3.10 + + Path to the GLVND EGL library. + +``OPENGL_glu_LIBRARY`` + Path to the GLU library. + +``OPENGL_glx_LIBRARY`` + .. versionadded:: 3.10 + + Path to the GLVND GLX library. + +``OPENGL_opengl_LIBRARY`` + .. versionadded:: 3.10 + + Path to the GLVND OpenGL library + +``OPENGL_gl_LIBRARY`` + Path to the OpenGL library. + +``OPENGL_gles2_LIBRARY`` + .. versionadded:: 3.27 + + Path to the OpenGL GLES2 library. + +``OPENGL_gles3_LIBRARY`` + .. versionadded:: 3.27 + + Path to the OpenGL GLES3 library. + +Hints +^^^^^ + +This module accepts the following variables: + +``OpenGL_GL_PREFERENCE`` + .. versionadded:: 3.10 + + This variable is supported on Linux systems to specify the preferred way to + provide legacy GL interfaces in case multiple choices are available. The + value may be one of: + + ``GLVND`` + If the GLVND OpenGL and GLX libraries are available, prefer them. + This forces ``OPENGL_gl_LIBRARY`` to be empty. + + .. versionchanged:: 3.11 + This is the default, unless policy :policy:`CMP0072` is set to ``OLD`` + and no components are requested (since components + correspond to GLVND libraries). + + ``LEGACY`` + Prefer to use the legacy libGL library, if available. This makes + ``OPENGL_opengl_LIBRARY`` and ``OPENGL_glx_LIBRARY`` + point to ``OPENGL_gl_LIBRARY``. .. _`Linux Specific`: @@ -153,28 +257,13 @@ ``OpenGL::GLX`` or ``OpenGL::EGL``. Projects may use the ``OpenGL::GL`` target (or ``OPENGL_LIBRARIES`` variable) -to use legacy GL interfaces. These will use the legacy GL library located -by ``OPENGL_gl_LIBRARY``, if available. If ``OPENGL_gl_LIBRARY`` is empty or -not found and GLVND is available, the ``OpenGL::GL`` target will use GLVND -``OpenGL::OpenGL`` and ``OpenGL::GLX`` (and the ``OPENGL_LIBRARIES`` -variable will use the corresponding libraries). Thus, for non-EGL-based -Linux targets, the ``OpenGL::GL`` target is most portable. +to use legacy GL interfaces. Depending on ``OpenGL_GL_PREFERENCE``, these +will either use the legacy GL library or the GLVND ``OpenGL::OpenGL`` and +``OpenGL::GLX``. Thus, for non-EGL-based Linux targets, +the ``OpenGL::GL`` target is most portable. -A ``OpenGL_GL_PREFERENCE`` variable may be set to specify the preferred way +The ``OpenGL_GL_PREFERENCE`` variable may be set to specify the preferred way to provide legacy GL interfaces in case multiple choices are available. -The value may be one of: - -``GLVND`` - If the GLVND OpenGL and GLX libraries are available, prefer them. - This forces ``OPENGL_gl_LIBRARY`` to be empty. - - .. versionchanged:: 3.11 - This is the default, unless policy :policy:`CMP0072` is set to ``OLD`` - and no components are requested (since components - correspond to GLVND libraries). - -``LEGACY`` - Prefer to use the legacy libGL library, if available. For EGL targets the client must rely on GLVND support on the user's system. Linking should use the ``OpenGL::OpenGL OpenGL::EGL`` targets. Using GLES* @@ -189,7 +278,8 @@ On macOS this module defaults to using the macOS-native framework version of OpenGL. To use the X11 version of OpenGL on macOS, one -can disable searching of frameworks. For example: +can disable searching of frameworks using the :variable:`CMAKE_FIND_FRAMEWORK` +variable. For example: .. code-block:: cmake @@ -205,6 +295,35 @@ An end user building this project may need to point CMake at their X11 installation, e.g., with ``-DOpenGL_ROOT=/opt/X11``. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``OPENGL_FOUND`` + .. deprecated:: 4.2 + Use ``OpenGL_FOUND``, which has the same value. + + Boolean indicating whether OpenGL and all requested components were found. + +Examples +^^^^^^^^ + +Finding the OpenGL library and linking it to a project target: + +.. code-block:: cmake + + find_package(OpenGL) + target_link_libraries(project_target PRIVATE OpenGL::OpenGL) + +See Also +^^^^^^^^ + +* The :module:`FindGLEW` module to find OpenGL Extension Wrangler Library + (GLEW). +* The :module:`FindGLUT` module to find OpenGL Utility Toolkit (GLUT) + library. +* The :module:`FindVulkan` module to find Vulkan graphics API. #]=======================================================================] set(_OpenGL_REQUIRED_VARS OPENGL_gl_LIBRARY) @@ -410,6 +529,12 @@ list(APPEND _OpenGL_CACHE_VARS OPENGL_gl_LIBRARY) endif() + # When preferring legacy, linking OpenGL and GLX should behave the same as linking legacy GL. + if(OpenGL_GL_PREFERENCE STREQUAL "LEGACY") + set(OpenGL_glx_LIBRARY "${OPENGL_gl_LIBRARY}") + set(OpenGL_opengl_LIBRARY "${OPENGL_gl_LIBRARY}") + endif() + if(_OpenGL_GL_POLICY_WARN AND OPENGL_gl_LIBRARY AND OPENGL_opengl_LIBRARY AND OPENGL_glx_LIBRARY) cmake_policy(GET_WARNING CMP0072 _cmp0072_warning) message(AUTHOR_WARNING @@ -582,7 +707,7 @@ unset(_OpenGL_REQUIRED_VARS) # OpenGL:: targets -if(OPENGL_FOUND) +if(OpenGL_FOUND) set(OPENGL_INCLUDE_DIRS ${OPENGL_INCLUDE_DIR}) # ::OpenGL is a GLVND library, and thus Linux-only: we don't bother checking
diff --git a/Modules/FindOpenMP.cmake b/Modules/FindOpenMP.cmake index c1141c7..6ef1152 100644 --- a/Modules/FindOpenMP.cmake +++ b/Modules/FindOpenMP.cmake
@@ -5,17 +5,60 @@ FindOpenMP ---------- -Finds Open Multi-Processing (OpenMP) support. +Finds Open Multi-Processing (OpenMP) support in a compiler: -This module can be used to detect OpenMP support in a compiler. If -the compiler supports OpenMP, the flags required to compile with -OpenMP support are returned in variables for the different languages. -The variables may be empty if the compiler does not need a special -flag to support OpenMP. +.. code-block:: cmake + + find_package(OpenMP [<version>] [COMPONENTS <langs>...] [...]) + +If the compiler supports OpenMP, the flags required to compile with OpenMP +support are returned in variables for the different languages. The variables +may be empty if the compiler does not need a special flag to support OpenMP. .. versionadded:: 3.5 Clang support. +Components +^^^^^^^^^^ + +This module supports components that can be specified using the standard +syntax: + +.. code-block:: cmake + + find_package(OpenMP [COMPONENTS <langs>...]) + +Each of these components controls the various languages to search OpenMP +support for. The following components are exposed: + +``C`` + .. versionadded:: 3.10 + +``CXX`` + .. versionadded:: 3.10 + +``Fortran`` + .. versionadded:: 3.10 + +``CUDA`` + .. versionadded:: 3.31 + + The ``CUDA`` language component is supported when using a CUDA compiler + that supports OpenMP on the host. + +If no components are specified, module checks for all of them automatically, +depending on the enabled languages in the project. + +Imported Targets +^^^^^^^^^^^^^^^^ + +This module provides the following :ref:`Imported Targets`: + +``OpenMP::OpenMP_<lang>`` + .. versionadded:: 3.9 + + Target encapsulating the OpenMP usage requirements for language ``<lang>``. + Input Variables ^^^^^^^^^^^^^^^ @@ -33,32 +76,63 @@ Result Variables ^^^^^^^^^^^^^^^^ -.. versionadded:: 3.10 - The module exposes the components ``C``, ``CXX``, and ``Fortran``. - Each of these controls the various languages to search OpenMP support for. - -.. versionadded:: 3.31 - The ``CUDA`` language component is supported when using a CUDA compiler - that supports OpenMP on the host. - -Depending on the enabled components the following variables will be set: +This module defines the following variables: ``OpenMP_FOUND`` - Variable indicating that OpenMP flags for all requested languages have been found. - If no components are specified, this is true if OpenMP settings for all enabled languages - were detected. -``OpenMP_VERSION`` - Minimal version of the OpenMP standard detected among the requested languages, - or all enabled languages if no components were specified. + .. versionadded:: 3.10 -This module will set the following variables per language in your + Boolean indicating that OpenMP flags for all requested languages were + found. If no components are specified, this variable is set to boolean + true if OpenMP settings for all enabled languages were detected. + +``OpenMP_VERSION`` + .. versionadded:: 4.2 + + Minimal version of the OpenMP standard detected among the requested + languages, or all enabled languages if no components were specified. + +This module will set the following variables per language in the project, where ``<lang>`` is one of C, CXX, CUDA, or Fortran: ``OpenMP_<lang>_FOUND`` - Variable indicating if OpenMP support for ``<lang>`` was detected. + .. versionadded:: 3.9 + + Boolean indicating whether the (requested version of) OpenMP support for + ``<lang>`` was detected. + +``OpenMP_<lang>_VERSION`` + .. versionadded:: 3.9 + + OpenMP version implemented by the ``<lang>`` compiler, if available. + +``OpenMP_<lang>_VERSION_MAJOR`` + .. versionadded:: 3.9 + + Major version of OpenMP implemented by the ``<lang>`` compiler, if + available. + +``OpenMP_<lang>_VERSION_MINOR`` + .. versionadded:: 3.9 + + Minor version of OpenMP implemented by the ``<lang>`` compiler, if + available. + +``OpenMP_<lang>_SPEC_DATE`` + .. versionadded:: 3.7 + + Date of the OpenMP specification implemented by the ``<lang>`` compiler, + if available. + + The specification date is formatted as given in the OpenMP standard: + ``yyyymm`` where ``yyyy`` and ``mm`` represents the year and month of the + OpenMP specification implemented by the ``<lang>`` compiler. + ``OpenMP_<lang>_FLAGS`` OpenMP compiler flags for ``<lang>``, separated by spaces. + ``OpenMP_<lang>_INCLUDE_DIRS`` + .. versionadded:: 3.16 + Directories that must be added to the header search path for ``<lang>`` when using OpenMP. @@ -66,48 +140,56 @@ variables are provided: ``OpenMP_<lang>_LIB_NAMES`` - :ref:`;-list <CMake Language Lists>` of libraries for OpenMP programs for ``<lang>``. + .. versionadded:: 3.9 + + A :ref:`semicolon-separated list <CMake Language Lists>` of OpenMP + programs libraries for ``<lang>``. + ``OpenMP_<libname>_LIBRARY`` - Location of the individual libraries needed for OpenMP support in ``<lang>``. + .. versionadded:: 3.9 + + Location of the individual libraries needed for OpenMP support in + ``<lang>``. The ``<libname>`` names are stored in the + ``OpenMP_<lang>_LIB_NAMES`` list. + ``OpenMP_<lang>_LIBRARIES`` + .. versionadded:: 3.9 + A list of libraries needed to link with OpenMP code written in ``<lang>``. -Additionally, the module provides :prop_tgt:`IMPORTED` targets: - -``OpenMP::OpenMP_<lang>`` - Target for using OpenMP from ``<lang>``. - Specifically for Fortran, the module sets the following variables: ``OpenMP_Fortran_HAVE_OMPLIB_HEADER`` - Boolean indicating if OpenMP is accessible through ``omp_lib.h``. + .. versionadded:: 3.9 + + Boolean indicating whether OpenMP is accessible through the ``omp_lib.h`` + Fortran header. + ``OpenMP_Fortran_HAVE_OMPLIB_MODULE`` - Boolean indicating if OpenMP is accessible through the ``omp_lib`` Fortran module. + .. versionadded:: 3.9 -The module will also try to provide the OpenMP version variables: - -``OpenMP_<lang>_SPEC_DATE`` - .. versionadded:: 3.7 - - Date of the OpenMP specification implemented by the ``<lang>`` compiler. -``OpenMP_<lang>_VERSION_MAJOR`` - Major version of OpenMP implemented by the ``<lang>`` compiler. -``OpenMP_<lang>_VERSION_MINOR`` - Minor version of OpenMP implemented by the ``<lang>`` compiler. -``OpenMP_<lang>_VERSION`` - OpenMP version implemented by the ``<lang>`` compiler. - -The specification date is formatted as given in the OpenMP standard: -``yyyymm`` where ``yyyy`` and ``mm`` represents the year and month of -the OpenMP specification implemented by the ``<lang>`` compiler. + Boolean indicating whether OpenMP is accessible through the ``omp_lib`` + Fortran module. For some compilers, it may be necessary to add a header search path to find the relevant OpenMP headers. This location may be language-specific. Where this is needed, the module may attempt to find the location, but it can be provided directly by setting the ``OpenMP_<lang>_INCLUDE_DIR`` cache variable. -Note that this variable is an _input_ control to the module. Project code -should use the ``OpenMP_<lang>_INCLUDE_DIRS`` _output_ variable if it needs -to know what include directories are needed. +Note that this variable is an *input* control to the module. Project code +should use the ``OpenMP_<lang>_INCLUDE_DIRS`` *output* variable if it needs +to know what include directories are needed, or preferably the +``OpenMP::OpenMP_<lang>`` imported target. + +Examples +^^^^^^^^ + +Finding OpenMP support and linking the imported target to a project target +using the C language component: + +.. code-block:: cmake + + find_package(OpenMP) + target_link_libraries(project_target PRIVATE OpenMP::OpenMP_C) #]=======================================================================] cmake_policy(PUSH) @@ -376,7 +458,7 @@ break() endif() endif() - elseif(CMAKE_${LANG}_COMPILER_ID STREQUAL "LLVMFlang" AND WIN32) + elseif(CMAKE_${LANG}_COMPILER_ID STREQUAL "LLVMFlang") find_library(OpenMP_libomp_LIBRARY NAMES omp HINTS ${CMAKE_${LANG}_IMPLICIT_LINK_DIRECTORIES} @@ -622,7 +704,7 @@ set(OpenMP_FINDLIST ${OpenMP_FIND_COMPONENTS}) endif() -unset(_OpenMP_MIN_VERSION) +unset(OpenMP_VERSION) include(FindPackageHandleStandardArgs) @@ -657,8 +739,8 @@ if(OpenMP_${LANG}_FOUND) if(DEFINED OpenMP_${LANG}_VERSION) - if(NOT _OpenMP_MIN_VERSION OR _OpenMP_MIN_VERSION VERSION_GREATER OpenMP_${LANG}_VERSION) - set(_OpenMP_MIN_VERSION OpenMP_${LANG}_VERSION) + if(NOT OpenMP_VERSION OR OpenMP_VERSION VERSION_GREATER OpenMP_${LANG}_VERSION) + set(OpenMP_VERSION "${OpenMP_${LANG}_VERSION}") endif() endif() set(OpenMP_${LANG}_LIBRARIES "") @@ -678,7 +760,7 @@ set_property(TARGET OpenMP::OpenMP_${LANG} PROPERTY INTERFACE_COMPILE_OPTIONS "$<$<COMPILE_LANGUAGE:${LANG}>:SHELL:${OpenMP_${LANG}_FLAGS}>") if(CMAKE_${LANG}_COMPILER_ID STREQUAL "Fujitsu" - OR ${CMAKE_${LANG}_COMPILER_ID} STREQUAL "IntelLLVM" + OR CMAKE_${LANG}_COMPILER_ID STREQUAL "IntelLLVM" OR CMAKE_${LANG}_COMPILER_ID MATCHES "^(Cray|CrayClang)$") set_property(TARGET OpenMP::OpenMP_${LANG} PROPERTY INTERFACE_LINK_OPTIONS "SHELL:${OpenMP_${LANG}_FLAGS}") @@ -705,7 +787,7 @@ find_package_handle_standard_args(OpenMP REQUIRED_VARS ${_OpenMP_REQ_VARS} - VERSION_VAR ${_OpenMP_MIN_VERSION} + VERSION_VAR OpenMP_VERSION HANDLE_COMPONENTS) if(CMAKE_Fortran_COMPILER_LOADED AND OpenMP_Fortran_FOUND)
diff --git a/Modules/FindOpenSP.cmake b/Modules/FindOpenSP.cmake index 3ff6a99..8609210 100644 --- a/Modules/FindOpenSP.cmake +++ b/Modules/FindOpenSP.cmake
@@ -7,8 +7,14 @@ .. versionadded:: 3.25 -Finds the OpenSP library. OpenSP is an open-source implementation of the SGML -(Standard Generalized Markup Language) parser. +Finds the OpenSP library: + +.. code-block:: cmake + + find_package(OpenSP [<version>] [...]) + +OpenSP is an open-source implementation of the SGML (Standard Generalized +Markup Language) parser. Imported Targets ^^^^^^^^^^^^^^^^ @@ -25,7 +31,7 @@ This module defines the following variables: ``OpenSP_FOUND`` - Boolean indicating whether the (requested version of) OpenSP is available. + Boolean indicating whether (the requested version of) OpenSP is available. ``OpenSP_VERSION`` The version of found OpenSP.
diff --git a/Modules/FindOpenSSL.cmake b/Modules/FindOpenSSL.cmake index af137d4..458eac3 100644 --- a/Modules/FindOpenSSL.cmake +++ b/Modules/FindOpenSSL.cmake
@@ -5,7 +5,11 @@ FindOpenSSL ----------- -Finds the installed OpenSSL encryption library and determines its version. +Finds the installed OpenSSL encryption library and determines its version: + +.. code-block:: cmake + + find_package(OpenSSL [<version>] [COMPONENTS <components>...] [...]) .. versionadded:: 3.20 Support for specifying version range when calling the :command:`find_package` @@ -95,23 +99,35 @@ This module defines the following variables: ``OpenSSL_FOUND`` - Boolean indicating whether the OpenSSL library has been found. For backward - compatibility, the ``OPENSSL_FOUND`` variable is also set to the same value. + .. versionadded:: 3.3 + + Boolean indicating whether the (requested version of) OpenSSL library was + found. + +``OpenSSL_VERSION`` + .. versionadded:: 4.2 + + The OpenSSL version found. This is set to + ``<major>.<minor>.<revision><patch>`` (e.g., ``0.9.8s``). + ``OPENSSL_INCLUDE_DIR`` The OpenSSL include directory. + ``OPENSSL_CRYPTO_LIBRARY`` The OpenSSL ``crypto`` library. + ``OPENSSL_CRYPTO_LIBRARIES`` The OpenSSL ``crypto`` library and its dependencies. + ``OPENSSL_SSL_LIBRARY`` The OpenSSL ``ssl`` library. + ``OPENSSL_SSL_LIBRARIES`` The OpenSSL ``ssl`` library and its dependencies. + ``OPENSSL_LIBRARIES`` All OpenSSL libraries and their dependencies. -``OPENSSL_VERSION`` - The OpenSSL version found. This is set to - ``<major>.<minor>.<revision><patch>`` (e.g. ``0.9.8s``). + ``OPENSSL_APPLINK_SOURCE`` The sources in the target ``OpenSSL::applink`` mentioned above. This variable is only defined if found OpenSSL version is at least 0.9.8 and the platform is @@ -142,6 +158,24 @@ ``PKG_CONFIG_PATH`` environment variable to specify alternate locations, which is useful on systems with multiple library installations. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``OPENSSL_FOUND`` + .. deprecated:: 4.2 + Use ``OpenSSL_FOUND``, which has the same value. + + Boolean indicating whether the (requested version of) OpenSSL library was + found. + +``OPENSSL_VERSION`` + .. deprecated:: 4.2 + Superseded by the ``OpenSSL_VERSION``. + + The version of OpenSSL found. + Examples ^^^^^^^^ @@ -259,7 +293,7 @@ if (UNIX) find_package(PkgConfig QUIET) - if(PKG_CONFIG_FOUND) + if(PkgConfig_FOUND) pkg_check_modules(_OPENSSL QUIET openssl) endif() endif () @@ -661,7 +695,8 @@ string(ASCII "${OPENSSL_VERSION_PATCH_ASCII}" OPENSSL_VERSION_PATCH_STRING) endif () - set(OPENSSL_VERSION "${OPENSSL_VERSION_MAJOR}.${OPENSSL_VERSION_MINOR}.${OPENSSL_VERSION_FIX}${OPENSSL_VERSION_PATCH_STRING}") + set(OpenSSL_VERSION "${OPENSSL_VERSION_MAJOR}.${OPENSSL_VERSION_MINOR}.${OPENSSL_VERSION_FIX}${OPENSSL_VERSION_PATCH_STRING}") + set(OPENSSL_VERSION "${OpenSSL_VERSION}") else () # Since OpenSSL 3.0.0, the new version format is MAJOR.MINOR.PATCH and # a new OPENSSL_VERSION_STR macro contains exactly that @@ -670,10 +705,11 @@ string(REGEX REPLACE "^.*OPENSSL_VERSION_STR[\t ]+\"([0-9]+\\.[0-9]+\\.[0-9]+)\".*$" "\\1" OPENSSL_VERSION_STR "${OPENSSL_VERSION_STR}") - set(OPENSSL_VERSION "${OPENSSL_VERSION_STR}") + set(OpenSSL_VERSION "${OPENSSL_VERSION_STR}") + set(OPENSSL_VERSION "${OpenSSL_VERSION}") # Setting OPENSSL_VERSION_MAJOR OPENSSL_VERSION_MINOR and OPENSSL_VERSION_FIX - string(REGEX MATCHALL "([0-9])+" OPENSSL_VERSION_NUMBER "${OPENSSL_VERSION}") + string(REGEX MATCHALL "([0-9])+" OPENSSL_VERSION_NUMBER "${OpenSSL_VERSION}") list(POP_FRONT OPENSSL_VERSION_NUMBER OPENSSL_VERSION_MAJOR OPENSSL_VERSION_MINOR @@ -718,7 +754,7 @@ OPENSSL_CRYPTO_LIBRARY OPENSSL_INCLUDE_DIR VERSION_VAR - OPENSSL_VERSION + OpenSSL_VERSION HANDLE_VERSION_RANGE HANDLE_COMPONENTS FAIL_MESSAGE
diff --git a/Modules/FindOpenSceneGraph.cmake b/Modules/FindOpenSceneGraph.cmake index 26f406d..4bcedc0 100644 --- a/Modules/FindOpenSceneGraph.cmake +++ b/Modules/FindOpenSceneGraph.cmake
@@ -5,7 +5,11 @@ FindOpenSceneGraph ------------------ -Finds `OpenSceneGraph`_ (OSG), a 3D graphics application programming interface. +Finds `OpenSceneGraph`_ (OSG), a 3D graphics application programming interface: + +.. code-block:: cmake + + find_package(OpenSceneGraph [<version>] [COMPONENTS <components>...] [...]) .. note:: @@ -153,12 +157,15 @@ This module defines the following variables: ``OpenSceneGraph_FOUND`` - Boolean indicating whether the (requested version of) OpenSceneGraph with all - specified components is found. For backward compatibility, the - ``OPENSCENEGRAPH_FOUND`` variable is also set to the same value. + .. versionadded:: 3.3 -``OPENSCENEGRAPH_VERSION`` - The version of the OSG which was found. + Boolean indicating whether (the requested version of) OpenSceneGraph with + all specified components was found. + +``OpenSceneGraph_VERSION`` + .. versionadded:: 4.2 + + The version of OpenSceneGraph found. ``OPENSCENEGRAPH_INCLUDE_DIRS`` Include directories containing headers needed to use OpenSceneGraph. @@ -197,6 +204,24 @@ ``OSG_ROOT`` Environment variable treated the same as ``OSG_DIR``. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``OPENSCENEGRAPH_FOUND`` + .. deprecated:: 4.2 + Use ``OpenSceneGraph_FOUND``, which has the same value. + + Boolean indicating whether (the requested version of) OpenSceneGraph with + all specified components was found. + +``OPENSCENEGRAPH_VERSION`` + .. deprecated:: 4.2 + Superseded by the ``OpenSceneGraph_VERSION``. + + The version of OpenSceneGraph found. + Examples ^^^^^^^^ @@ -324,9 +349,11 @@ set(OPENSCENEGRAPH_VERSION "${_osg_VERSION_MAJOR}.${_osg_VERSION_MINOR}.${_osg_VERSION_PATCH}" CACHE INTERNAL "The version of OSG which was detected") + set(OpenSceneGraph_VERSION "${OPENSCENEGRAPH_VERSION}") + if(OpenSceneGraph_DEBUG) message(STATUS "[ FindOpenSceneGraph.cmake:${CMAKE_CURRENT_LIST_LINE} ] " - "Detected version ${OPENSCENEGRAPH_VERSION}") + "Detected version ${OpenSceneGraph_VERSION}") endif() endif() @@ -374,7 +401,7 @@ include(FindPackageHandleStandardArgs) find_package_handle_standard_args(OpenSceneGraph REQUIRED_VARS OPENSCENEGRAPH_LIBRARIES OPENSCENEGRAPH_INCLUDE_DIR ${_osg_component_founds} - VERSION_VAR OPENSCENEGRAPH_VERSION) + VERSION_VAR OpenSceneGraph_VERSION) unset(_osg_component_founds)
diff --git a/Modules/FindOpenThreads.cmake b/Modules/FindOpenThreads.cmake index 2e7c84f..0d3df43 100644 --- a/Modules/FindOpenThreads.cmake +++ b/Modules/FindOpenThreads.cmake
@@ -5,7 +5,11 @@ FindOpenThreads --------------- -Finds the OpenThreads C++ based threading library. +Finds the OpenThreads C++ based threading library: + +.. code-block:: cmake + + find_package(OpenThreads [...]) OpenThreads header files are intended to be included as: @@ -20,9 +24,9 @@ This module defines the following variables: ``OpenThreads_FOUND`` - Boolean indicating whether OpenThreads library is found. For backward - compatibility, the ``OPENTHREADS_FOUND`` variable is also set to the same - value. + .. versionadded:: 3.3 + + Boolean indicating whether the OpenThreads library was found. ``OPENTHREADS_LIBRARY`` Libraries needed to link against to use OpenThreads. This provides either @@ -67,6 +71,17 @@ ``OSGDIR`` Environment variable treated the same as ``OPENTHREADS_DIR``. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``OPENTHREADS_FOUND`` + .. deprecated:: 4.2 + Use ``OpenThreads_FOUND``, which has the same value. + + Boolean indicating whether the OpenThreads library was found. + Examples ^^^^^^^^ @@ -108,7 +123,7 @@ ) find_library(OPENTHREADS_LIBRARY_RELEASE - NAMES OpenThreads OpenThreadsWin32 + NAMES OpenThreads OpenThreadsWin32 OpenThreadsrd HINTS ENV OPENTHREADS_LIBRARY_DIR ENV OPENTHREADS_DIR
diff --git a/Modules/FindPHP4.cmake b/Modules/FindPHP4.cmake index edef791..46509fe 100644 --- a/Modules/FindPHP4.cmake +++ b/Modules/FindPHP4.cmake
@@ -5,7 +5,11 @@ FindPHP4 -------- -Finds PHP version 4, a general-purpose scripting language. +Finds PHP version 4, a general-purpose scripting language: + +.. code-block:: cmake + + find_package(PHP4 [...]) .. note:: @@ -15,6 +19,14 @@ This module checks if PHP 4 is installed and determines the locations of the include directories and the PHP command-line interpreter. +Result Variables +^^^^^^^^^^^^^^^^ + +This module defines the following variables: + +``PHP4_FOUND`` + Boolean indicating whether PHP 4 was found. + Cache Variables ^^^^^^^^^^^^^^^
diff --git a/Modules/FindPNG.cmake b/Modules/FindPNG.cmake index 1a72f7d..47540f7 100644 --- a/Modules/FindPNG.cmake +++ b/Modules/FindPNG.cmake
@@ -5,7 +5,11 @@ FindPNG ------- -Finds libpng, the official reference library for the PNG image format. +Finds libpng, the official reference library for the PNG image format: + +.. code-block:: cmake + + find_package(PNG [<version>] [...]) .. note:: @@ -15,41 +19,61 @@ Imported Targets ^^^^^^^^^^^^^^^^ -.. versionadded:: 3.5 - -This module defines the following :ref:`Imported Targets`: +This module provides the following :ref:`Imported Targets`: ``PNG::PNG`` - The libpng library, if found. + .. versionadded:: 3.5 + + Target encapsulating the libpng library usage requirements, available if + libpng is found. Result Variables ^^^^^^^^^^^^^^^^ -This module sets the following variables: +This module defines the following variables: + +``PNG_FOUND`` + Boolean indicating whether the (requested version of) PNG library was found. + +``PNG_VERSION`` + .. versionadded:: 4.2 + + The version of the PNG library found. ``PNG_INCLUDE_DIRS`` Directory containing the PNG headers (e.g., ``png.h``). + ``PNG_LIBRARIES`` PNG libraries required for linking. + ``PNG_DEFINITIONS`` Compile definitions for using PNG, if any. They can be added with :command:`target_compile_definitions` command when not using the ``PNG::PNG`` imported target. -``PNG_FOUND`` - True if PNG library is found. -``PNG_VERSION_STRING`` - The version of the PNG library found. -Obsolete Variables -^^^^^^^^^^^^^^^^^^ +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ The following variables may also be set for backward compatibility: ``PNG_LIBRARY`` + .. deprecated:: 3.0 + Use the ``PNG::PNG`` imported target. + Path to the PNG library. + ``PNG_INCLUDE_DIR`` + .. deprecated:: 3.0 + Use the ``PNG::PNG`` imported target. + Directory containing the PNG headers (same as ``PNG_INCLUDE_DIRS``). +``PNG_VERSION_STRING`` + .. deprecated:: 4.2 + Superseded by the ``PNG_VERSION``. + + The version of the PNG library found. + Examples ^^^^^^^^ @@ -81,7 +105,7 @@ find_package(ZLIB ${_FIND_ZLIB_ARG}) if(ZLIB_FOUND) - set(_PNG_VERSION_SUFFIXES 17 16 15 14 12) + set(_PNG_VERSION_SUFFIXES 18 17 16 15 14 12) list(APPEND _PNG_INCLUDE_PATH_SUFFIXES include/libpng) foreach(v IN LISTS _PNG_VERSION_SUFFIXES) @@ -184,7 +208,8 @@ if (PNG_PNG_INCLUDE_DIR AND EXISTS "${PNG_PNG_INCLUDE_DIR}/png.h") file(STRINGS "${PNG_PNG_INCLUDE_DIR}/png.h" png_version_str REGEX "^#define[ \t]+PNG_LIBPNG_VER_STRING[ \t]+\".+\"") - string(REGEX REPLACE "^#define[ \t]+PNG_LIBPNG_VER_STRING[ \t]+\"([^\"]+)\".*" "\\1" PNG_VERSION_STRING "${png_version_str}") + string(REGEX REPLACE "^#define[ \t]+PNG_LIBPNG_VER_STRING[ \t]+\"([^\"]+)\".*" "\\1" PNG_VERSION "${png_version_str}") + set(PNG_VERSION_STRING "${PNG_VERSION}") unset(png_version_str) endif () endif() @@ -192,6 +217,6 @@ include(FindPackageHandleStandardArgs) find_package_handle_standard_args(PNG REQUIRED_VARS PNG_LIBRARY PNG_PNG_INCLUDE_DIR - VERSION_VAR PNG_VERSION_STRING) + VERSION_VAR PNG_VERSION) cmake_policy(POP)
diff --git a/Modules/FindPackageHandleStandardArgs.cmake b/Modules/FindPackageHandleStandardArgs.cmake index 5081936..70c634b 100644 --- a/Modules/FindPackageHandleStandardArgs.cmake +++ b/Modules/FindPackageHandleStandardArgs.cmake
@@ -5,28 +5,42 @@ FindPackageHandleStandardArgs ----------------------------- -This module provides functions intended to be used in :ref:`Find Modules` +This module provides commands intended for use in :ref:`Find Modules` implementing :command:`find_package(<PackageName>)` calls. +Load this module in a CMake find module with: + +.. code-block:: cmake + :caption: ``FindFoo.cmake`` + + include(FindPackageHandleStandardArgs) + +Commands +^^^^^^^^ + +This module provides the following commands: + +* :command:`find_package_handle_standard_args` +* :command:`find_package_check_version` + .. command:: find_package_handle_standard_args - This command handles the ``REQUIRED``, ``QUIET`` and version-related - arguments of :command:`find_package`. It also sets the - ``<PackageName>_FOUND`` variable. The package is considered found if all - variables listed contain valid results, e.g. valid filepaths. + Handles the ``REQUIRED``, ``QUIET`` and version-related arguments of + :command:`find_package`. There are two signatures: .. code-block:: cmake - find_package_handle_standard_args(<PackageName> + find_package_handle_standard_args( + <PackageName> (DEFAULT_MSG|<custom-failure-message>) - <required-var>... - ) + <required-vars>... + ) - find_package_handle_standard_args(<PackageName> - [FOUND_VAR <result-var>] - [REQUIRED_VARS <required-var>...] + find_package_handle_standard_args( + <PackageName> + [REQUIRED_VARS <required-vars>...] [VERSION_VAR <version-var>] [HANDLE_VERSION_RANGE] [HANDLE_COMPONENTS] @@ -34,37 +48,33 @@ [NAME_MISMATCHED] [REASON_FAILURE_MESSAGE <reason-failure-message>] [FAIL_MESSAGE <custom-failure-message>] - ) + [FOUND_VAR <result-var>] # Deprecated + ) - The ``<PackageName>_FOUND`` variable will be set to ``TRUE`` if all - the variables ``<required-var>...`` are valid and any optional - constraints are satisfied, and ``FALSE`` otherwise. A success or - failure message may be displayed based on the results and on - whether the ``REQUIRED`` and/or ``QUIET`` option was given to - the :command:`find_package` call. + This command sets the ``<PackageName>_FOUND`` variable to ``TRUE`` if all + the variables listed in ``<required-vars>...`` contain valid results + (e.g., valid filepaths) and any optional constraints are satisfied, and + ``FALSE`` otherwise. A success or failure message may be displayed based + on the results and on whether the ``REQUIRED`` and/or ``QUIET`` option + was given to the :command:`find_package` call. - The options are: + The arguments are: + + ``<PackageName>`` + The name of the package. For example, as written in the + ``Find<PackageName>.cmake`` find module filename. ``(DEFAULT_MSG|<custom-failure-message>)`` In the simple signature this specifies the failure message. Use ``DEFAULT_MSG`` to ask for a default message to be computed (recommended). Not valid in the full signature. - ``FOUND_VAR <result-var>`` - .. deprecated:: 3.3 - - Specifies either ``<PackageName>_FOUND`` or - ``<PACKAGENAME>_FOUND`` as the result variable. This exists only - for compatibility with older versions of CMake and is now ignored. - Result variables of both names are now always set for compatibility - also with or without this option. - - ``REQUIRED_VARS <required-var>...`` + ``REQUIRED_VARS <required-vars>...`` Specify the variables which are required for this package. These may be named in the generated failure message asking the user to set the missing variable values. Therefore these should - typically be cache entries such as ``FOO_LIBRARY`` and not output - variables like ``FOO_LIBRARIES``. + typically be cache entries such as ``Foo_LIBRARY`` and not output + variables like ``Foo_LIBRARIES``. .. versionchanged:: 3.18 If ``HANDLE_COMPONENTS`` is specified, this option can be omitted. @@ -100,6 +110,14 @@ will automatically check whether the package configuration file was found. + ``NAME_MISMATCHED`` + .. versionadded:: 3.17 + + Indicate that the ``<PackageName>`` does not match the value of + :variable:`CMAKE_FIND_PACKAGE_NAME` variable. This is usually a mistake + and raises a warning, but it may be intentional for usage of the + command for components of a larger package. + ``REASON_FAILURE_MESSAGE <reason-failure-message>`` .. versionadded:: 3.16 @@ -110,48 +128,76 @@ Specify a custom failure message instead of using the default generated message. Not recommended. - ``NAME_MISMATCHED`` - .. versionadded:: 3.17 + ``FOUND_VAR <result-var>`` + .. deprecated:: 3.3 + This option should no longer be used. - Indicate that the ``<PackageName>`` does not match - ``${CMAKE_FIND_PACKAGE_NAME}``. This is usually a mistake and raises a - warning, but it may be intentional for usage of the command for components - of a larger package. + Specifies either ``<PackageName>_FOUND`` or ``<PACKAGENAME>_FOUND`` as the + result variable. This exists only for backward compatibility with older + versions of CMake and is now ignored. Result variables of both names are + now always set for compatibility also with or without this option. -Example for the simple signature: + .. note:: + + If ``<PackageName>`` does not match :variable:`CMAKE_FIND_PACKAGE_NAME` + for the calling module, a warning that there is a mismatch is given. The + ``FPHSA_NAME_MISMATCHED`` variable may be set to bypass the warning if using + the old signature and the ``NAME_MISMATCHED`` argument using the new + signature. To avoid forcing the caller to require newer versions of CMake + for usage, the variable's value will be used if defined when the + ``NAME_MISMATCHED`` argument is not passed for the new signature (but using + both is an error). + +.. command:: find_package_check_version + + .. versionadded:: 3.19 + + Checks if a given version is valid against the version-related arguments + of :command:`find_package`: + + .. code-block:: cmake + + find_package_check_version( + <version> + <result-var> + [HANDLE_VERSION_RANGE] + [RESULT_MESSAGE_VARIABLE <message-var>] + ) + + The arguments are: + + ``<version>`` + The version string to check. + + ``<result-var>`` + Name of the result variable that will hold a boolean value giving the + result of the check. + + ``HANDLE_VERSION_RANGE`` + Enable handling of a version range, if one is specified. Without this + option, a developer warning will be displayed if a version range is + specified. + + ``RESULT_MESSAGE_VARIABLE <message-var>`` + Specify a variable to get back a message describing the result of the check. + +Examples +^^^^^^^^ + +Examples: Full Signature +"""""""""""""""""""""""" + +Example for using a full signature of ``find_package_handle_standard_args()``: .. code-block:: cmake + :caption: ``FindLibArchive.cmake`` - find_package_handle_standard_args(LibXml2 DEFAULT_MSG - LIBXML2_LIBRARY LIBXML2_INCLUDE_DIR) - -The ``LibXml2`` package is considered to be found if both -``LIBXML2_LIBRARY`` and ``LIBXML2_INCLUDE_DIR`` are valid. -Then also ``LibXml2_FOUND`` is set to ``TRUE``. If it is not found -and ``REQUIRED`` was used, it fails with a -:command:`message(FATAL_ERROR)`, independent whether ``QUIET`` was -used or not. If it is found, success will be reported, including -the content of the first ``<required-var>``. On repeated CMake runs, -the same message will not be printed again. - -.. note:: - - If ``<PackageName>`` does not match ``CMAKE_FIND_PACKAGE_NAME`` for the - calling module, a warning that there is a mismatch is given. The - ``FPHSA_NAME_MISMATCHED`` variable may be set to bypass the warning if using - the old signature and the ``NAME_MISMATCHED`` argument using the new - signature. To avoid forcing the caller to require newer versions of CMake for - usage, the variable's value will be used if defined when the - ``NAME_MISMATCHED`` argument is not passed for the new signature (but using - both is an error).. - -Example for the full signature: - -.. code-block:: cmake - - find_package_handle_standard_args(LibArchive + include(FindPackageHandleStandardArgs) + find_package_handle_standard_args( + LibArchive REQUIRED_VARS LibArchive_LIBRARY LibArchive_INCLUDE_DIR - VERSION_VAR LibArchive_VERSION) + VERSION_VAR LibArchive_VERSION + ) In this case, the ``LibArchive`` package is considered to be found if both ``LibArchive_LIBRARY`` and ``LibArchive_INCLUDE_DIR`` are valid. @@ -159,56 +205,73 @@ contained in ``LibArchive_VERSION``. Since no ``FAIL_MESSAGE`` is given, the default messages will be printed. -Another example for the full signature: +Another example for the full signature of +``find_package_handle_standard_args()``: .. code-block:: cmake + :caption: ``FindAutomoc4.cmake`` find_package(Automoc4 QUIET NO_MODULE HINTS /opt/automoc4) - find_package_handle_standard_args(Automoc4 CONFIG_MODE) -In this case, a ``FindAutmoc4.cmake`` module wraps a call to + include(FindPackageHandleStandardArgs) + find_package_handle_standard_args(Automoc4 CONFIG_MODE) + +In this case, a ``FindAutomoc4.cmake`` module wraps a call to ``find_package(Automoc4 NO_MODULE)`` and adds an additional search directory for ``automoc4``. Then the call to -``find_package_handle_standard_args`` produces a proper success/failure +``find_package_handle_standard_args()`` produces a proper success/failure message. -.. command:: find_package_check_version +Example: Simple Signature +""""""""""""""""""""""""" - .. versionadded:: 3.19 - - Helper function which can be used to check if a ``<version>`` is valid - against version-related arguments of :command:`find_package`. - - .. code-block:: cmake - - find_package_check_version(<version> <result-var> - [HANDLE_VERSION_RANGE] - [RESULT_MESSAGE_VARIABLE <message-var>] - ) - - The ``<result-var>`` will hold a boolean value giving the result of the check. - - The options are: - - ``HANDLE_VERSION_RANGE`` - Enable handling of a version range, if one is specified. Without this - option, a developer warning will be displayed if a version range is - specified. - - ``RESULT_MESSAGE_VARIABLE <message-var>`` - Specify a variable to get back a message describing the result of the check. - -Example for the usage: +Example for using a simple signature of ``find_package_handle_standard_args()``: .. code-block:: cmake + :caption: ``FindLibXml2.cmake`` - find_package_check_version(1.2.3 result HANDLE_VERSION_RANGE - RESULT_MESSAGE_VARIABLE reason) + include(FindPackageHandleStandardArgs) + find_package_handle_standard_args( + LibXml2 + DEFAULT_MSG + LIBXML2_LIBRARY LIBXML2_INCLUDE_DIR + ) + +In this example, the ``LibXml2`` package is considered to be found if both +``LIBXML2_LIBRARY`` and ``LIBXML2_INCLUDE_DIR`` variables are valid. Then +also ``LibXml2_FOUND`` is set to ``TRUE``. If it is not found and +``REQUIRED`` was used, it fails with a :command:`message(FATAL_ERROR)`, +independent whether ``QUIET`` was used or not. If it is found, success will +be reported, including the content of the first required variable specified +in ``<required-vars>...``. On repeated CMake runs, the same message will +not be printed again. + +Example: Checking Version +""""""""""""""""""""""""" + +Example for the ``find_package_check_version()`` usage: + +.. code-block:: cmake + :caption: ``FindFoo.cmake`` + + include(FindPackageHandleStandardArgs) + find_package_check_version( + 1.2.3 + result + HANDLE_VERSION_RANGE + RESULT_MESSAGE_VARIABLE reason + ) if(result) message(STATUS "${reason}") else() - message(FATAL_ERROR "${reason}") + # Logic when version check is not successful. + message(WARNING "${reason}") endif() + +See Also +^^^^^^^^ + +* :ref:`Find Modules` for details how to write a find module. #]=======================================================================] include(${CMAKE_CURRENT_LIST_DIR}/FindPackageMessage.cmake)
diff --git a/Modules/FindPackageMessage.cmake b/Modules/FindPackageMessage.cmake index 29db756..859b0b6 100644 --- a/Modules/FindPackageMessage.cmake +++ b/Modules/FindPackageMessage.cmake
@@ -6,11 +6,13 @@ ------------------ This module provides a command for printing find result messages and is -intended for use in :ref:`Find Modules`. +intended for use in :ref:`Find Modules` implementing +:command:`find_package(<PackageName>)` calls. -Load it in a CMake find module with: +Load this module in a CMake find module with: .. code-block:: cmake + :caption: ``FindFoo.cmake`` include(FindPackageMessage)
diff --git a/Modules/FindPatch.cmake b/Modules/FindPatch.cmake index c6ca07b..cb81b6f 100644 --- a/Modules/FindPatch.cmake +++ b/Modules/FindPatch.cmake
@@ -8,7 +8,11 @@ .. versionadded:: 3.10 Finds the ``patch`` command-line executable for applying diff patches to -original files. +original files: + +.. code-block:: cmake + + find_package(Patch [...]) Imported Targets ^^^^^^^^^^^^^^^^ @@ -29,7 +33,7 @@ This module defines the following variables: ``Patch_FOUND`` - Boolean indicating whether the ``patch`` command-line executable is found. + Boolean indicating whether the ``patch`` command-line executable was found. Cache Variables ^^^^^^^^^^^^^^^
diff --git a/Modules/FindPerl.cmake b/Modules/FindPerl.cmake index 06a2e62..1214a18 100644 --- a/Modules/FindPerl.cmake +++ b/Modules/FindPerl.cmake
@@ -5,8 +5,13 @@ FindPerl -------- -Finds a Perl interpreter. Perl is a general-purpose, interpreted, dynamic -programming language. +Finds a Perl interpreter: + +.. code-block:: cmake + + find_package(Perl [<version>] [...]) + +Perl is a general-purpose, interpreted, dynamic programming language. Result Variables ^^^^^^^^^^^^^^^^ @@ -14,10 +19,14 @@ This module defines the following variables: ``Perl_FOUND`` - True if the Perl executable was found. For backward compatibility, the - ``PERL_FOUND`` variable is also set to the same value. + .. versionadded:: 3.3 -``PERL_VERSION_STRING`` + Boolean indicating whether the (requested version of) Perl executable was + found. + +``Perl_VERSION`` + .. versionadded:: 4.2 + The version of Perl found. Cache Variables @@ -28,14 +37,41 @@ ``PERL_EXECUTABLE`` Full path to the ``perl`` executable. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``PERL_FOUND`` + .. deprecated:: 4.2 + Use ``Perl_FOUND``, which has the same value. + + Boolean indicating whether the (requested version of) Perl executable was + found. + +``PERL_VERSION_STRING`` + .. deprecated:: 4.2 + Superseded by the ``Perl_VERSION``. + + The version of Perl found. + Examples ^^^^^^^^ -Finding the Perl interpreter: +Finding the Perl interpreter and executing it in a process: .. code-block:: cmake find_package(Perl) + + if(Perl_FOUND) + execute_process(COMMAND ${PERL_EXECUTABLE} --help) + endif() + +See Also +^^^^^^^^ + +* The :module:`FindPerlLibs` to find Perl libraries. #]=======================================================================] include(${CMAKE_CURRENT_LIST_DIR}/FindCygwin.cmake) @@ -64,7 +100,6 @@ ) if(PERL_EXECUTABLE) - ### PERL_VERSION execute_process( COMMAND ${PERL_EXECUTABLE} -V:version @@ -76,7 +111,8 @@ OUTPUT_STRIP_TRAILING_WHITESPACE ) if(NOT PERL_VERSION_RESULT_VARIABLE AND NOT PERL_VERSION_OUTPUT_VARIABLE MATCHES "^version='UNKNOWN'") - string(REGEX REPLACE "version='([^']+)'.*" "\\1" PERL_VERSION_STRING ${PERL_VERSION_OUTPUT_VARIABLE}) + string(REGEX REPLACE "version='([^']+)'.*" "\\1" Perl_VERSION ${PERL_VERSION_OUTPUT_VARIABLE}) + set(PERL_VERSION_STRING "${Perl_VERSION}") else() execute_process( COMMAND ${PERL_EXECUTABLE} -v @@ -86,9 +122,11 @@ OUTPUT_STRIP_TRAILING_WHITESPACE ) if(NOT PERL_VERSION_RESULT_VARIABLE AND PERL_VERSION_OUTPUT_VARIABLE MATCHES "This is perl.*[ \\(]v([0-9\\._]+)[ \\)]") - set(PERL_VERSION_STRING "${CMAKE_MATCH_1}") + set(Perl_VERSION "${CMAKE_MATCH_1}") + set(PERL_VERSION_STRING "${Perl_VERSION}") elseif(NOT PERL_VERSION_RESULT_VARIABLE AND PERL_VERSION_OUTPUT_VARIABLE MATCHES "This is perl, version ([0-9\\._]+) +") - set(PERL_VERSION_STRING "${CMAKE_MATCH_1}") + set(Perl_VERSION "${CMAKE_MATCH_1}") + set(PERL_VERSION_STRING "${Perl_VERSION}") endif() endif() endif() @@ -105,7 +143,7 @@ endif () find_package_handle_standard_args(Perl REQUIRED_VARS PERL_EXECUTABLE - VERSION_VAR PERL_VERSION_STRING) + VERSION_VAR Perl_VERSION) unset(FPHSA_NAME_MISMATCHED) mark_as_advanced(PERL_EXECUTABLE)
diff --git a/Modules/FindPerlLibs.cmake b/Modules/FindPerlLibs.cmake index 330700e..fbe1aad 100644 --- a/Modules/FindPerlLibs.cmake +++ b/Modules/FindPerlLibs.cmake
@@ -5,18 +5,34 @@ FindPerlLibs ------------ -Finds Perl libraries. Perl is a general-purpose, interpreted, dynamic -programming language. This module detects whether Perl is installed and -determines the locations of include paths, libraries, and the library name. +Finds Perl libraries: + +.. code-block:: cmake + + find_package(PerlLibs [<version>] [...]) + +Perl is a general-purpose, interpreted, dynamic programming language. + +This module detects whether Perl interpreter is installed via the +:module:`FindPerl` module and determines the locations of Perl include paths, +libraries, and the library name. Result Variables ^^^^^^^^^^^^^^^^ -This module sets the following variables: +This module defines the following variables: ``PerlLibs_FOUND`` - True if ``perl.h`` and ``libperl`` were found. For backward compatibility, - the ``PERLLIBS_FOUND`` variable is also set to the same value. + .. versionadded:: 3.3 + + Boolean indicating whether (the requested version of) ``<perl.h>`` and + ``libperl`` were found. + +``PerlLibs_VERSION`` + .. versionadded:: 4.2 + + The version of Perl library found. + ``PERL_SITESEARCH`` Path to the sitesearch install directory (``-V:installsitesearch``). ``PERL_SITEARCH`` @@ -50,6 +66,18 @@ ``PERL_EXECUTABLE`` Full path to the ``perl`` executable. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``PERLLIBS_FOUND`` + .. deprecated:: 4.2 + Use ``PerlLibs_FOUND``, which has the same value. + + Boolean indicating whether (the requested version of) ``<perl.h>`` and + ``libperl`` were found. + Examples ^^^^^^^^ @@ -58,11 +86,18 @@ .. code-block:: cmake find_package(PerlLibs 6.0) + +See Also +^^^^^^^^ + +* The :module:`FindPerl` module to find the Perl interpreter. #]=======================================================================] # find the perl executable include(${CMAKE_CURRENT_LIST_DIR}/FindPerl.cmake) +set(PerlLibs_VERSION "${Perl_VERSION}") + if (PERL_EXECUTABLE) function (perl_get_info _pgi_info tag) @@ -122,10 +157,10 @@ ### PERL_POSSIBLE_LIBRARY_NAMES perl_get_info(PERL_POSSIBLE_LIBRARY_NAMES libperl) if (NOT PERL_POSSIBLE_LIBRARY_NAMES) - set(PERL_POSSIBLE_LIBRARY_NAMES perl${PERL_VERSION_STRING} perl) + set(PERL_POSSIBLE_LIBRARY_NAMES perl${PerlLibs_VERSION} perl) endif() if(CMAKE_SYSTEM_NAME MATCHES "CYGWIN") - list (APPEND PERL_POSSIBLE_LIBRARY_NAMES perl${PERL_VERSION_STRING}) + list (APPEND PERL_POSSIBLE_LIBRARY_NAMES perl${PerlLibs_VERSION}) endif() if (CMAKE_SYSTEM_NAME MATCHES "MSYS|CYGWIN") # On MSYS and CYGWIN environments, current perl -V:libperl gives shared @@ -141,10 +176,10 @@ PATHS "${PERL_UPDATE_ARCHLIB}/CORE" "${PERL_ARCHLIB}/CORE" - /usr/lib/perl5/${PERL_VERSION_STRING}/${PERL_ARCHNAME}/CORE - /usr/lib/perl/${PERL_VERSION_STRING}/${PERL_ARCHNAME}/CORE - /usr/lib/perl5/${PERL_VERSION_STRING}/CORE - /usr/lib/perl/${PERL_VERSION_STRING}/CORE + /usr/lib/perl5/${PerlLibs_VERSION}/${PERL_ARCHNAME}/CORE + /usr/lib/perl/${PerlLibs_VERSION}/${PERL_ARCHNAME}/CORE + /usr/lib/perl5/${PerlLibs_VERSION}/CORE + /usr/lib/perl/${PerlLibs_VERSION}/CORE ) ### PERL_LIBRARY @@ -154,24 +189,24 @@ PATHS "${PERL_UPDATE_ARCHLIB}/CORE" "${PERL_ARCHLIB}/CORE" - /usr/lib/perl5/${PERL_VERSION_STRING}/${PERL_ARCHNAME}/CORE - /usr/lib/perl/${PERL_VERSION_STRING}/${PERL_ARCHNAME}/CORE - /usr/lib/perl5/${PERL_VERSION_STRING}/CORE - /usr/lib/perl/${PERL_VERSION_STRING}/CORE + /usr/lib/perl5/${PerlLibs_VERSION}/${PERL_ARCHNAME}/CORE + /usr/lib/perl/${PerlLibs_VERSION}/${PERL_ARCHNAME}/CORE + /usr/lib/perl5/${PerlLibs_VERSION}/CORE + /usr/lib/perl/${PerlLibs_VERSION}/CORE ) endif () include(FindPackageHandleStandardArgs) find_package_handle_standard_args(PerlLibs REQUIRED_VARS PERL_LIBRARY PERL_INCLUDE_PATH - VERSION_VAR PERL_VERSION_STRING) + VERSION_VAR PerlLibs_VERSION) # Introduced after CMake 2.6.4 to bring module into compliance set(PERL_INCLUDE_DIR ${PERL_INCLUDE_PATH}) set(PERL_INCLUDE_DIRS ${PERL_INCLUDE_PATH}) set(PERL_LIBRARIES ${PERL_LIBRARY}) # For backward compatibility with CMake before 2.8.8 -set(PERL_VERSION ${PERL_VERSION_STRING}) +set(PERL_VERSION ${PerlLibs_VERSION}) mark_as_advanced( PERL_INCLUDE_PATH
diff --git a/Modules/FindPhysFS.cmake b/Modules/FindPhysFS.cmake index 1894498..6031d17 100644 --- a/Modules/FindPhysFS.cmake +++ b/Modules/FindPhysFS.cmake
@@ -5,7 +5,11 @@ FindPhysFS ---------- -Finds the PhysicsFS library (PhysFS) for file I/O abstraction. +Finds the PhysicsFS library (PhysFS) for file I/O abstraction: + +.. code-block:: cmake + + find_package(PhysFS [...]) Result Variables ^^^^^^^^^^^^^^^^ @@ -13,19 +17,20 @@ This module defines the following variables: ``PhysFS_FOUND`` - Boolean indicating whether PhysicsFS library is found. For backward - compatibility, the ``PHYSFS_FOUND`` variable is also set to the same value. + .. versionadded:: 3.3 + + Boolean indicating whether the PhysicsFS library was found. Cache Variables ^^^^^^^^^^^^^^^ The following cache variables may also be set: +``PHYSFS_INCLUDE_DIR`` + Directory containing the ``<physfs.h>`` and related headers needed for using + the library. ``PHYSFS_LIBRARY`` Path to the PhysicsFS library needed to link against. -``PHYSFS_INCLUDE_DIR`` - Directory containing the ``physfs.h`` and related headers needed for using - the library. Hints ^^^^^ @@ -38,6 +43,17 @@ destination that was used when configuring, building, and installing PhysicsFS library: ``./configure --prefix=$PHYSFSDIR``. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``PHYSFS_FOUND`` + .. deprecated:: 4.2 + Use the ``PhysFS_FOUND``, which has the same value. + + Boolean indicating whether the PhysicsFS library was found. + Examples ^^^^^^^^
diff --git a/Modules/FindPike.cmake b/Modules/FindPike.cmake index 457e82a..08eb3f4 100644 --- a/Modules/FindPike.cmake +++ b/Modules/FindPike.cmake
@@ -5,8 +5,24 @@ FindPike -------- -Finds the Pike compiler and interpreter. Pike is interpreted, general purpose, -high-level, dynamic programming language. +Finds the Pike compiler and interpreter: + +.. code-block:: cmake + + find_package(Pike [...]) + +Pike is interpreted, general purpose, high-level, dynamic programming +language. + +Result Variables +^^^^^^^^^^^^^^^^ + +This module defines the following variables: + +``Pike_FOUND`` + .. versionadded:: 4.2 + + Boolean indicating whether Pike was found. Cache Variables ^^^^^^^^^^^^^^^ @@ -40,3 +56,9 @@ PIKE_EXECUTABLE PIKE_INCLUDE_PATH ) + +if(PIKE_EXECUTABLE AND PIKE_INCLUDE_PATH) + set(Pike_FOUND TRUE) +else() + set(Pike_FOUND FALSE) +endif()
diff --git a/Modules/FindPkgConfig.cmake b/Modules/FindPkgConfig.cmake index b230eb5..924284a 100644 --- a/Modules/FindPkgConfig.cmake +++ b/Modules/FindPkgConfig.cmake
@@ -7,28 +7,476 @@ A ``pkg-config`` module for CMake. -Finds the ``pkg-config`` executable and adds the :command:`pkg_get_variable`, -:command:`pkg_check_modules` and :command:`pkg_search_module` commands. The -following variables will also be set: +Finds the ``pkg-config`` executable and provides commands to use it in +CMake: -``PKG_CONFIG_FOUND`` - True if a pkg-config executable was found. +.. code-block:: cmake -``PKG_CONFIG_VERSION_STRING`` - The version of pkg-config that was found. + find_package(PkgConfig [<version>] [QUIET] [REQUIRED] [...]) + +``pkg-config`` is a command-line program for configuring build dependency +information. Initially developed by FreeDesktop, it is also available in +several implementations, such as pkgconf, u-config, and similar. It reads +package data from the so-called PC metadata files (``<module-name>.pc``) +that may come installed with packages. This module is a wrapper around the +``pkg-config`` command-line executable. + +Result Variables +^^^^^^^^^^^^^^^^ + +This module defines the following variables: + +``PkgConfig_FOUND`` + .. versionadded:: 3.3 + + Boolean indicating whether the (requested version of) ``pkg-config`` + executable was found. + +``PkgConfig_VERSION`` + .. versionadded:: 4.2 + + The version of ``pkg-config`` that was found. ``PKG_CONFIG_EXECUTABLE`` - The pathname of the pkg-config program. + The pathname of the ``pkg-config`` program. ``PKG_CONFIG_ARGN`` .. versionadded:: 3.22 - A list of arguments to pass to pkg-config. + A list of arguments to pass to ``pkg-config``. Both ``PKG_CONFIG_EXECUTABLE`` and ``PKG_CONFIG_ARGN`` are initialized by the -module, but may be overridden by the user. See `Variables Affecting Behavior`_ -for how these variables are initialized. +module, but may be overridden by the user. See `Hints`_ for how these +variables are initialized. +Commands +^^^^^^^^ + +This module provides the following commands, if ``pkg-config`` is found: + +* :command:`pkg_check_modules` +* :command:`pkg_search_module` +* :command:`pkg_get_variable` + +.. command:: pkg_check_modules + + Checks for all the given modules, setting a variety of result variables + in the calling scope: + + .. code-block:: cmake + + pkg_check_modules( + <prefix> + [QUIET] + [REQUIRED] + [NO_CMAKE_PATH] + [NO_CMAKE_ENVIRONMENT_PATH] + [IMPORTED_TARGET [GLOBAL]] + <module-spec> [<module-spec>...] + ) + + .. rubric:: The arguments are: + + ``<prefix>`` + Prefix string prepended to result variables for the specified modules. + + ``QUIET`` + When this argument is given, no status messages will be printed. + + ``REQUIRED`` + When this argument is given, the command will fail with an error if any + of the specified module(s) could not be found. + + ``NO_CMAKE_PATH``, ``NO_CMAKE_ENVIRONMENT_PATH`` + .. versionadded:: 3.3 + + The :variable:`CMAKE_PREFIX_PATH`, + :variable:`CMAKE_FRAMEWORK_PATH`, and :variable:`CMAKE_APPBUNDLE_PATH` cache + and environment variables will be added to the ``pkg-config`` search path. + The ``NO_CMAKE_PATH`` and ``NO_CMAKE_ENVIRONMENT_PATH`` arguments + disable this behavior for the cache variables and environment variables + respectively. + The ``PKG_CONFIG_USE_CMAKE_PREFIX_PATH`` variable set to ``FALSE`` + disables this behavior globally. + + .. This was actually added in 3.1, but didn't work until 3.3. + + ``IMPORTED_TARGET [GLOBAL]`` + .. versionadded:: 3.7 + + This argument will create an :ref:`imported target <Imported Targets>` + named ``PkgConfig::<prefix>`` that can be passed directly as an argument + to :command:`target_link_libraries`. It will encapsulate usage + requirements for all specified modules ``<module-spec>...`` at once. + + .. This was actually added in 3.6, but didn't work until 3.7. + + ``GLOBAL`` + .. versionadded:: 3.13 + + This argument is used together with ``IMPORTED_TARGET`` and will make + the imported target available in global scope. + + .. versionadded:: 3.15 + Non-library linker options reported by ``pkg-config`` are stored in the + :prop_tgt:`INTERFACE_LINK_OPTIONS` target property. + + .. versionchanged:: 3.18 + Include directories specified with ``-isystem`` are stored in the + :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property. Previous + versions of CMake left them in the :prop_tgt:`INTERFACE_COMPILE_OPTIONS` + property. + + ``<module-spec>`` + Each ``<module-spec>`` can be either a bare module name (as defined in + its PC metadata file name ``<module-name>.pc``) or it can be a module + name with a version constraint (operators ``=``, ``<``, ``>``, ``<=`` + and ``>=`` are supported). The following are examples for a module + named ``foo`` with various constraints: + + - ``foo`` matches any version. + - ``foo<2`` only matches versions before 2. + - ``foo>=3.1`` matches any version from 3.1 or later. + - ``foo=1.2.3`` requires that foo must be exactly version 1.2.3. + + .. rubric:: Result Variables + + The following variables may be set upon return. Two sets of values exist: + One for the common case (``<XXX> = <prefix>``) and another for the + information ``pkg-config`` provides when called with the ``--static`` + option (``<XXX> = <prefix>_STATIC``). + + ``<XXX>_FOUND`` + Boolean variable set to 1 if module(s) exist. + ``<XXX>_LIBRARIES`` + A list of only the libraries (without the ``-l``). + ``<XXX>_LINK_LIBRARIES`` + The libraries and their absolute paths. + ``<XXX>_LIBRARY_DIRS`` + The paths of the libraries (without the ``-L``). + ``<XXX>_LDFLAGS`` + All required linker flags. + ``<XXX>_LDFLAGS_OTHER`` + All other linker flags. + ``<XXX>_INCLUDE_DIRS`` + The ``-I`` preprocessor flags (without the ``-I``). + ``<XXX>_CFLAGS`` + All required cflags. + ``<XXX>_CFLAGS_OTHER`` + The other compiler flags. + + All but ``<XXX>_FOUND`` may be a :ref:`semicolon-separated list + <CMake Language Lists>` if the + associated variable returned from ``pkg-config`` has multiple values. + + .. versionchanged:: 3.18 + Include directories specified with ``-isystem`` are stored in the + ``<XXX>_INCLUDE_DIRS`` variable. Previous versions of CMake left them + in ``<XXX>_CFLAGS_OTHER``. + + There are some special variables whose prefix depends on the number of + ``<module-spec>`` given. When there is only one ``<module-spec>``, + ``<YYY>`` will simply be ``<prefix>``, but if two or more ``<module-spec>`` + items are given, ``<YYY>`` will be ``<prefix>_<module-name>``. + + ``<YYY>_VERSION`` + The version of the module. + ``<YYY>_PREFIX`` + The prefix directory of the module. + ``<YYY>_INCLUDEDIR`` + The include directory of the module. + ``<YYY>_LIBDIR`` + The lib directory of the module. + + .. versionchanged:: 3.8 + For any given ``<prefix>``, ``pkg_check_modules()`` can be called multiple + times with different parameters. Previous versions of CMake cached and + returned the first successful result. + + .. versionchanged:: 3.16 + If a full path to the found library can't be determined, but it's still + visible to the linker, pass it through as ``-l<name>``. Previous versions + of CMake failed in this case. + +.. command:: pkg_search_module + + Searches for the first successful match from one or more provided module + specifications: + + .. code-block:: cmake + + pkg_search_module( + <prefix> + [QUIET] + [REQUIRED] + [NO_CMAKE_PATH] + [NO_CMAKE_ENVIRONMENT_PATH] + [IMPORTED_TARGET [GLOBAL]] + <module-spec> [<module-spec>...] + ) + + The behavior and arguments of this command are the same as + :command:`pkg_check_modules`, except that rather than checking for all + the specified modules, it searches for just the first successful match. + + This command can be used, for example, when some package is known to have + possible multiple ``<module-spec>`` on different platforms or versions for + the same package. + + .. rubric:: Result Variables + + This command defines the same variables as described above with addition + to: + + ``<prefix>_MODULE_NAME`` + .. versionadded:: 3.16 + + If a module is found, the ``<prefix>_MODULE_NAME`` variable will contain + the name of the matching module. This variable can be used if the + :command:`pkg_get_variable` command needs to be called with the + ``<module-name>`` argument that was found by the + :command:`pkg_search_module`. + +.. command:: pkg_get_variable + + .. versionadded:: 3.4 + + Retrieves the value of a ``pkg-config`` variable and stores it in the + result variable in the calling scope: + + .. code-block:: cmake + + pkg_get_variable( + <result-var> + <module-name> + <var-name> + [DEFINE_VARIABLES <key>=<value>...] + ) + + .. rubric:: The arguments are: + + ``<result-var>`` + Name of the result variable that will contain the value of ``pkg-config`` + variable. If ``pkg-config`` returns multiple values for the specified + variable ``<var-name>``, ``<result-var>`` will contain a + :ref:`semicolon-separated list <CMake Language Lists>`. + + ``<module-name>`` + Name of the module as defined in its PC metadata file name + (``<module-name>.pc``). + + ``<var-name>`` + The ``pkg-config`` variable name from the PC metadata file + ``<module-name>.pc``. + + ``DEFINE_VARIABLES <key>=<value>...`` + .. versionadded:: 3.28 + + Specify key-value pairs to redefine variables affecting the variable + retrieved with ``pkg-config``. + +Hints +^^^^^ + +This module accepts the following variables before calling +``find_package(PkgConfig)`` to influence this module's behavior: + +``ENV{PKG_CONFIG_PATH}`` + Environment variable that specifies additional paths in which + ``pkg-config`` will search for its ``.pc`` files. The ``pkg-config`` + tool by default uses this variable, while CMake also provides more common + :variable:`CMAKE_PREFIX_PATH` variable to specify additional paths where + to look for packages and their ``.pc`` files. + +``ENV{PKG_CONFIG}`` + .. versionadded:: 3.1 + + Environment variable that can be set to the path of the ``pkg-config`` + executable and can be used to initialize the ``PKG_CONFIG_EXECUTABLE`` + variable, if it has not yet been set. + +``PKG_CONFIG_EXECUTABLE`` + + This cache variable can be set to the path of the ``pkg-config`` + executable. :command:`find_program` is called internally by the module + with this variable. + + .. versionchanged:: 3.22 + If the ``PKG_CONFIG`` environment variable is set, only the first + argument is taken from it when using it as a hint. + +``PKG_CONFIG_ARGN`` + + .. versionadded:: 3.22 + + This cache variable can be set to a list of arguments to additionally pass + to ``pkg-config`` if needed. If not provided, it will be initialized from + the ``PKG_CONFIG`` environment variable, if set. The first argument in that + environment variable is assumed to be the ``pkg-config`` program, while all + remaining arguments after that are used to initialize ``PKG_CONFIG_ARGN``. + If no such environment variable is defined, ``PKG_CONFIG_ARGN`` is + initialized to an empty string. The module does not update the variable once + it has been set in the cache. + +``PKG_CONFIG_USE_CMAKE_PREFIX_PATH`` + + .. versionadded:: 3.1 + + Specifies whether :command:`pkg_check_modules` and + :command:`pkg_search_module` should add the paths in the + :variable:`CMAKE_PREFIX_PATH`, :variable:`CMAKE_FRAMEWORK_PATH` and + :variable:`CMAKE_APPBUNDLE_PATH` cache and environment variables to the + ``pkg-config`` search path. + + If this variable is not set, this behavior is enabled by default if + :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` is 3.1 or later, disabled + otherwise. + +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``PKG_CONFIG_FOUND`` + .. deprecated:: 4.2 + Use ``PkgConfig_FOUND``, which has the same value. + + Boolean indicating whether the (requested version of) ``pkg-config`` + executable was found. + +``PKG_CONFIG_VERSION_STRING`` + .. deprecated:: 4.2 + Use ``PkgConfig_VERSION``, which has the same value. + + The version of ``pkg-config`` that was found. + +Examples +^^^^^^^^ + +Examples: Finding pkg-config +"""""""""""""""""""""""""""" + +Finding ``pkg-config``: + +.. code-block:: cmake + + find_package(PkgConfig) + +Finding ``pkg-config`` and making it required (if not found, processing stops +with an error message): + +.. code-block:: cmake + + find_package(PkgConfig REQUIRED) + +Finding ``pkg-config`` quietly without printing status message as commonly +used in find modules: + +.. code-block:: cmake + + find_package(PkgConfig QUIET) + +Examples: Using ``pkg_check_modules()`` +""""""""""""""""""""""""""""""""""""""" + +Checking for any version of glib2. If found, the output variable +``GLIB2_VERSION`` will hold the actual version found: + +.. code-block:: cmake + + find_package(PkgConfig QUIET) + + if(PkgConfig_FOUND) + pkg_check_modules(GLIB2 glib-2.0) + endif() + +The following example looks for at least version 2.10 of glib2. If found, +the output variable ``GLIB2_VERSION`` will hold the actual version found: + +.. code-block:: cmake + + find_package(PkgConfig QUIET) + + if(PkgConfig_FOUND) + pkg_check_modules(GLIB2 glib-2.0>=2.10) + endif() + +The following example looks for both glib2-2.0 (at least version 2.10) and +any version of gtk2+-2.0. Only if both are found will ``FOO`` be considered +found. The ``FOO_glib-2.0_VERSION`` and ``FOO_gtk+-2.0_VERSION`` variables +will be set to their respective found module versions. + +.. code-block:: cmake + + find_package(PkgConfig QUIET) + + if(PkgConfig_FOUND) + pkg_check_modules(FOO glib-2.0>=2.10 gtk+-2.0) + endif() + +The following example requires any version of ``xrender``: + +.. code-block:: cmake + + find_package(PkgConfig QUIET REQUIRED) + pkg_check_modules(XRENDER REQUIRED xrender) + +Example output variables set by a successful call:: + + XRENDER_LIBRARIES=Xrender;X11 + XRENDER_STATIC_LIBRARIES=Xrender;X11;pthread;Xau;Xdmcp + +Example: Using ``pkg_search_module()`` +"""""""""""""""""""""""""""""""""""""" + +Searching for LibXml2 package, which might be provided with different +module specifications (``libxml-2.0`` or ``libxml2``): + +.. code-block:: cmake + + find_package(PkgConfig QUIET) + + if(PkgConfig_FOUND) + pkg_search_module(BAR libxml-2.0 libxml2 libxml>=2) + endif() + +Example: Creating Imported Target +""""""""""""""""""""""""""""""""" + +In the following example an imported target is created from the module +specifications to use in the project directly without using a find module. +These imported targets can be used, for example, in cases, where package is +known to support ``pkg-config`` on all supported platforms: + +.. code-block:: cmake + + find_package(PkgConfig QUIET REQUIRED) + pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk4>=4.14) + target_link_libraries(example PRIVATE PkgConfig::GTK) + +Example: Using ``pkg_get_variable()`` +""""""""""""""""""""""""""""""""""""" + +Retrieving the value of ``pkg-config`` variable ``girdir`` from the package +Gobject: + +.. code-block:: cmake + + find_package(PkgConfig QUIET) + + if(PkgConfig_FOUND) + pkg_get_variable(GI_GIRDIR gobject-introspection-1.0 girdir) + endif() + + message(STATUS "${GI_GIRDIR}") + +See Also +^^^^^^^^ + +* The :command:`cmake_pkg_config` command for a modern and more advanced + way to work with ``pkg-config`` in CMake without requiring ``pkg-config`` + executable to be installed. +* :ref:`Find Modules` for details how to write a find module. #]========================================] ### Common stuff #### @@ -80,7 +528,7 @@ set(_PKG_CONFIG_FAILURE_MESSAGE "") if (PKG_CONFIG_EXECUTABLE) execute_process(COMMAND ${PKG_CONFIG_EXECUTABLE} ${PKG_CONFIG_ARGN} --version - OUTPUT_VARIABLE PKG_CONFIG_VERSION_STRING OUTPUT_STRIP_TRAILING_WHITESPACE + OUTPUT_VARIABLE PkgConfig_VERSION OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_VARIABLE _PKG_CONFIG_VERSION_ERROR ERROR_STRIP_TRAILING_WHITESPACE RESULT_VARIABLE _PKG_CONFIG_VERSION_RESULT ) @@ -93,27 +541,33 @@ string(APPEND _PKG_CONFIG_FAILURE_MESSAGE "The command\n" " \"${PKG_CONFIG_EXECUTABLE}\"${PKG_CONFIG_ARGN} --version\n" - " failed with output:\n${PKG_CONFIG_VERSION_STRING}\n" + " failed with output:\n${PkgConfig_VERSION}\n" " stderr: \n${_PKG_CONFIG_VERSION_ERROR}\n" " result: \n${_PKG_CONFIG_VERSION_RESULT}" ) set(PKG_CONFIG_EXECUTABLE "") set(PKG_CONFIG_ARGN "") - unset(PKG_CONFIG_VERSION_STRING) + unset(PkgConfig_VERSION) endif () unset(_PKG_CONFIG_VERSION_RESULT) endif () +# For backward compatibility. +unset(PKG_CONFIG_VERSION_STRING) +if(DEFINED PkgConfig_VERSION) + set(PKG_CONFIG_VERSION_STRING "${PkgConfig_VERSION}") +endif() + include(FindPackageHandleStandardArgs) find_package_handle_standard_args(PkgConfig REQUIRED_VARS PKG_CONFIG_EXECUTABLE REASON_FAILURE_MESSAGE "${_PKG_CONFIG_FAILURE_MESSAGE}" - VERSION_VAR PKG_CONFIG_VERSION_STRING) + VERSION_VAR PkgConfig_VERSION) # This is needed because the module name is "PkgConfig" but the name of # this variable has always been PKG_CONFIG_FOUND so this isn't automatically # handled by FPHSA. -set(PKG_CONFIG_FOUND "${PKGCONFIG_FOUND}") +set(PKG_CONFIG_FOUND "${PkgConfig_FOUND}") # Unsets the given variables macro(_pkgconfig_unset var) @@ -154,8 +608,8 @@ # pkg-config <0.29.1 and pkgconf <1.5.1 prints quoted variables without unquoting # unquote only if quotes are first and last characters - if((PKG_CONFIG_VERSION_STRING VERSION_LESS 0.29.1) OR - (PKG_CONFIG_VERSION_STRING VERSION_GREATER_EQUAL 1.0 AND PKG_CONFIG_VERSION_STRING VERSION_LESS 1.5.1)) + if((PkgConfig_VERSION VERSION_LESS 0.29.1) OR + (PkgConfig_VERSION VERSION_GREATER_EQUAL 1.0 AND PkgConfig_VERSION VERSION_LESS 1.5.1)) if (_pkgconfig_invoke_result MATCHES "^\"(.*)\"$") set(_pkgconfig_invoke_result "${CMAKE_MATCH_1}") elseif(_pkgconfig_invoke_result MATCHES "^'(.*)'$") @@ -703,161 +1157,6 @@ endif() endmacro() - -#[========================================[.rst: -.. command:: pkg_check_modules - - Checks for all the given modules, setting a variety of result variables in - the calling scope. - - .. code-block:: cmake - - pkg_check_modules(<prefix> - [REQUIRED] [QUIET] - [NO_CMAKE_PATH] - [NO_CMAKE_ENVIRONMENT_PATH] - [IMPORTED_TARGET [GLOBAL]] - <moduleSpec> [<moduleSpec>...]) - - When the ``REQUIRED`` argument is given, the command will fail with an error - if module(s) could not be found. - - When the ``QUIET`` argument is given, no status messages will be printed. - - .. versionadded:: 3.3 - The :variable:`CMAKE_PREFIX_PATH`, - :variable:`CMAKE_FRAMEWORK_PATH`, and :variable:`CMAKE_APPBUNDLE_PATH` cache - and environment variables will be added to the ``pkg-config`` search path. - The ``NO_CMAKE_PATH`` and ``NO_CMAKE_ENVIRONMENT_PATH`` arguments - disable this behavior for the cache variables and environment variables - respectively. - The :variable:`PKG_CONFIG_USE_CMAKE_PREFIX_PATH` variable set to ``FALSE`` - disables this behavior globally. - - .. This was actually added in 3.1, but didn't work until 3.3. - - .. versionadded:: 3.7 - The ``IMPORTED_TARGET`` argument will create an imported target named - ``PkgConfig::<prefix>`` that can be passed directly as an argument to - :command:`target_link_libraries`. - - .. This was actually added in 3.6, but didn't work until 3.7. - - .. versionadded:: 3.13 - The ``GLOBAL`` argument will make the - imported target available in global scope. - - .. versionadded:: 3.15 - Non-library linker options reported by ``pkg-config`` are stored in the - :prop_tgt:`INTERFACE_LINK_OPTIONS` target property. - - .. versionchanged:: 3.18 - Include directories specified with ``-isystem`` are stored in the - :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property. Previous - versions of CMake left them in the :prop_tgt:`INTERFACE_COMPILE_OPTIONS` - property. - - Each ``<moduleSpec>`` can be either a bare module name or it can be a - module name with a version constraint (operators ``=``, ``<``, ``>``, - ``<=`` and ``>=`` are supported). The following are examples for a module - named ``foo`` with various constraints: - - - ``foo`` matches any version. - - ``foo<2`` only matches versions before 2. - - ``foo>=3.1`` matches any version from 3.1 or later. - - ``foo=1.2.3`` requires that foo must be exactly version 1.2.3. - - The following variables may be set upon return. Two sets of values exist: - One for the common case (``<XXX> = <prefix>``) and another for the - information ``pkg-config`` provides when called with the ``--static`` - option (``<XXX> = <prefix>_STATIC``). - - ``<XXX>_FOUND`` - set to 1 if module(s) exist - ``<XXX>_LIBRARIES`` - only the libraries (without the '-l') - ``<XXX>_LINK_LIBRARIES`` - the libraries and their absolute paths - ``<XXX>_LIBRARY_DIRS`` - the paths of the libraries (without the '-L') - ``<XXX>_LDFLAGS`` - all required linker flags - ``<XXX>_LDFLAGS_OTHER`` - all other linker flags - ``<XXX>_INCLUDE_DIRS`` - the '-I' preprocessor flags (without the '-I') - ``<XXX>_CFLAGS`` - all required cflags - ``<XXX>_CFLAGS_OTHER`` - the other compiler flags - - All but ``<XXX>_FOUND`` may be a :ref:`;-list <CMake Language Lists>` if the - associated variable returned from ``pkg-config`` has multiple values. - - .. versionchanged:: 3.18 - Include directories specified with ``-isystem`` are stored in the - ``<XXX>_INCLUDE_DIRS`` variable. Previous versions of CMake left them - in ``<XXX>_CFLAGS_OTHER``. - - There are some special variables whose prefix depends on the number of - ``<moduleSpec>`` given. When there is only one ``<moduleSpec>``, - ``<YYY>`` will simply be ``<prefix>``, but if two or more ``<moduleSpec>`` - items are given, ``<YYY>`` will be ``<prefix>_<moduleName>``. - - ``<YYY>_VERSION`` - version of the module - ``<YYY>_PREFIX`` - prefix directory of the module - ``<YYY>_INCLUDEDIR`` - include directory of the module - ``<YYY>_LIBDIR`` - lib directory of the module - - .. versionchanged:: 3.8 - For any given ``<prefix>``, ``pkg_check_modules()`` can be called multiple - times with different parameters. Previous versions of CMake cached and - returned the first successful result. - - .. versionchanged:: 3.16 - If a full path to the found library can't be determined, but it's still - visible to the linker, pass it through as ``-l<name>``. Previous versions - of CMake failed in this case. - - Examples: - - .. code-block:: cmake - - pkg_check_modules (GLIB2 glib-2.0) - - Looks for any version of glib2. If found, the output variable - ``GLIB2_VERSION`` will hold the actual version found. - - .. code-block:: cmake - - pkg_check_modules (GLIB2 glib-2.0>=2.10) - - Looks for at least version 2.10 of glib2. If found, the output variable - ``GLIB2_VERSION`` will hold the actual version found. - - .. code-block:: cmake - - pkg_check_modules (FOO glib-2.0>=2.10 gtk+-2.0) - - Looks for both glib2-2.0 (at least version 2.10) and any version of - gtk2+-2.0. Only if both are found will ``FOO`` be considered found. - The ``FOO_glib-2.0_VERSION`` and ``FOO_gtk+-2.0_VERSION`` variables will be - set to their respective found module versions. - - .. code-block:: cmake - - pkg_check_modules (XRENDER REQUIRED xrender) - - Requires any version of ``xrender``. Example output variables set by a - successful call:: - - XRENDER_LIBRARIES=Xrender;X11 - XRENDER_STATIC_LIBRARIES=Xrender;X11;pthread;Xau;Xdmcp -#]========================================] macro(pkg_check_modules _prefix _module0) _pkgconfig_parse_options(_pkg_modules _pkg_is_required _pkg_is_silent _no_cmake_path _no_cmake_environment_path _imp_target _imp_target_global "${_module0}" ${ARGN}) # check cached value @@ -877,34 +1176,6 @@ endif() endmacro() - -#[========================================[.rst: -.. command:: pkg_search_module - - The behavior of this command is the same as :command:`pkg_check_modules`, - except that rather than checking for all the specified modules, it searches - for just the first successful match. - - .. code-block:: cmake - - pkg_search_module(<prefix> - [REQUIRED] [QUIET] - [NO_CMAKE_PATH] - [NO_CMAKE_ENVIRONMENT_PATH] - [IMPORTED_TARGET [GLOBAL]] - <moduleSpec> [<moduleSpec>...]) - - .. versionadded:: 3.16 - If a module is found, the ``<prefix>_MODULE_NAME`` variable will contain the - name of the matching module. This variable can be used if you need to run - :command:`pkg_get_variable`. - - Example: - - .. code-block:: cmake - - pkg_search_module (BAR libxml-2.0 libxml2 libxml>=2) -#]========================================] macro(pkg_search_module _prefix _module0) _pkgconfig_parse_options(_pkg_modules_alt _pkg_is_required _pkg_is_silent _no_cmake_path _no_cmake_environment_path _imp_target _imp_target_global "${_module0}" ${ARGN}) # check cached value @@ -939,36 +1210,6 @@ endif() endmacro() -#[========================================[.rst: -.. command:: pkg_get_variable - - .. versionadded:: 3.4 - - Retrieves the value of a pkg-config variable ``varName`` and stores it in the - result variable ``resultVar`` in the calling scope. - - .. code-block:: cmake - - pkg_get_variable(<resultVar> <moduleName> <varName> - [DEFINE_VARIABLES <key>=<value>...]) - - If ``pkg-config`` returns multiple values for the specified variable, - ``resultVar`` will contain a :ref:`;-list <CMake Language Lists>`. - - Options: - - ``DEFINE_VARIABLES <key>=<value>...`` - .. versionadded:: 3.28 - - Specify key-value pairs to redefine variables affecting the variable - retrieved with ``pkg-config``. - - For example: - - .. code-block:: cmake - - pkg_get_variable(GI_GIRDIR gobject-introspection-1.0 girdir) -#]========================================] function (pkg_get_variable result pkg variable) set(_multiValueArgs DEFINE_VARIABLES) @@ -989,55 +1230,3 @@ PARENT_SCOPE) _pkg_restore_path_internal() endfunction () - - -#[========================================[.rst: -Variables Affecting Behavior -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. variable:: PKG_CONFIG_EXECUTABLE - - This cache variable can be set to the path of the pkg-config executable. - :command:`find_program` is called internally by the module with this - variable. - - .. versionadded:: 3.1 - The ``PKG_CONFIG`` environment variable can be used as a hint if - ``PKG_CONFIG_EXECUTABLE`` has not yet been set. - - .. versionchanged:: 3.22 - If the ``PKG_CONFIG`` environment variable is set, only the first - argument is taken from it when using it as a hint. - -.. variable:: PKG_CONFIG_ARGN - - .. versionadded:: 3.22 - - This cache variable can be set to a list of arguments to additionally pass - to pkg-config if needed. If not provided, it will be initialized from the - ``PKG_CONFIG`` environment variable, if set. The first argument in that - environment variable is assumed to be the pkg-config program, while all - remaining arguments after that are used to initialize ``PKG_CONFIG_ARGN``. - If no such environment variable is defined, ``PKG_CONFIG_ARGN`` is - initialized to an empty string. The module does not update the variable once - it has been set in the cache. - -.. variable:: PKG_CONFIG_USE_CMAKE_PREFIX_PATH - - .. versionadded:: 3.1 - - Specifies whether :command:`pkg_check_modules` and - :command:`pkg_search_module` should add the paths in the - :variable:`CMAKE_PREFIX_PATH`, :variable:`CMAKE_FRAMEWORK_PATH` and - :variable:`CMAKE_APPBUNDLE_PATH` cache and environment variables to the - ``pkg-config`` search path. - - If this variable is not set, this behavior is enabled by default if - :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` is 3.1 or later, disabled - otherwise. -#]========================================] - - -### Local Variables: -### mode: cmake -### End:
diff --git a/Modules/FindPostgreSQL.cmake b/Modules/FindPostgreSQL.cmake index ede8f0d..fd68c73 100644 --- a/Modules/FindPostgreSQL.cmake +++ b/Modules/FindPostgreSQL.cmake
@@ -6,7 +6,11 @@ -------------- Finds the PostgreSQL installation - the client library (``libpq``) and -optionally the server. +optionally the server: + +.. code-block:: cmake + + find_package(PostgreSQL [<version>] [...]) Imported Targets ^^^^^^^^^^^^^^^^ @@ -27,15 +31,22 @@ ``PostgreSQL_FOUND`` Boolean indicating whether the minimum required version and components of - PostgreSQL have been found. + PostgreSQL were found. + +``PostgreSQL_VERSION`` + .. versionadded:: 4.2 + + The version of PostgreSQL found. + ``PostgreSQL_LIBRARIES`` The PostgreSQL libraries needed for linking. + ``PostgreSQL_INCLUDE_DIRS`` The include directories containing PostgreSQL headers. + ``PostgreSQL_LIBRARY_DIRS`` The directories containing PostgreSQL libraries. -``PostgreSQL_VERSION_STRING`` - The version of PostgreSQL found. + ``PostgreSQL_TYPE_INCLUDE_DIR`` The include directory containing PostgreSQL server headers. @@ -51,6 +62,17 @@ ``PostgreSQL_TYPE_INCLUDE_DIR`` variable is set regardless of whether this component is specified in the ``find_package()`` call. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``PostgreSQL_VERSION_STRING`` + .. deprecated:: 4.2 + Superseded by the ``PostgreSQL_VERSION``. + + The version of PostgreSQL found. + Examples ^^^^^^^^ @@ -109,6 +131,7 @@ # In Windows the default installation of PostgreSQL uses that as part of the path. # E.g C:\Program Files\PostgreSQL\8.4. # Currently, the following version numbers are known to this module: +# "17" # "16" "15" "14" "13" "12" "11" "10" "9.6" "9.5" "9.4" "9.3" "9.2" "9.1" "9.0" "8.4" "8.3" "8.2" "8.1" "8.0" # # To use this variable just do something like this: @@ -158,6 +181,7 @@ set(PostgreSQL_KNOWN_VERSIONS ${PostgreSQL_ADDITIONAL_VERSIONS} + "17" "16" "15" "14" "13" "12" "11" "10" "9.6" "9.5" "9.4" "9.3" "9.2" "9.1" "9.0" "8.4" "8.3" "8.2" "8.1" "8.0") # Define additional search paths for root directories. @@ -288,14 +312,16 @@ math(EXPR _PostgreSQL_major_version "${_PostgreSQL_VERSION_NUM} / 10000") math(EXPR _PostgreSQL_minor_version "${_PostgreSQL_VERSION_NUM} % 10000 / 100") math(EXPR _PostgreSQL_patch_version "${_PostgreSQL_VERSION_NUM} % 100") - set(PostgreSQL_VERSION_STRING "${_PostgreSQL_major_version}.${_PostgreSQL_minor_version}.${_PostgreSQL_patch_version}") + set(PostgreSQL_VERSION "${_PostgreSQL_major_version}.${_PostgreSQL_minor_version}.${_PostgreSQL_patch_version}") + set(PostgreSQL_VERSION_STRING "${PostgreSQL_VERSION}") unset(_PostgreSQL_major_version) unset(_PostgreSQL_minor_version) unset(_PostgreSQL_patch_version) else () math(EXPR _PostgreSQL_major_version "${_PostgreSQL_VERSION_NUM} / 10000") math(EXPR _PostgreSQL_minor_version "${_PostgreSQL_VERSION_NUM} % 10000") - set(PostgreSQL_VERSION_STRING "${_PostgreSQL_major_version}.${_PostgreSQL_minor_version}") + set(PostgreSQL_VERSION "${_PostgreSQL_major_version}.${_PostgreSQL_minor_version}") + set(PostgreSQL_VERSION_STRING "${PostgreSQL_VERSION}") unset(_PostgreSQL_major_version) unset(_PostgreSQL_minor_version) endif () @@ -306,7 +332,8 @@ REGEX "^#define[\t ]+PG_VERSION[\t ]+\".*\"") if(pgsql_version_str) string(REGEX REPLACE "^#define[\t ]+PG_VERSION[\t ]+\"([^\"]*)\".*" - "\\1" PostgreSQL_VERSION_STRING "${pgsql_version_str}") + "\\1" PostgreSQL_VERSION "${pgsql_version_str}") + set(PostgreSQL_VERSION_STRING "${PostgreSQL_VERSION}") break() endif() endif() @@ -328,7 +355,7 @@ find_package_handle_standard_args(PostgreSQL REQUIRED_VARS PostgreSQL_LIBRARY PostgreSQL_INCLUDE_DIR HANDLE_COMPONENTS - VERSION_VAR PostgreSQL_VERSION_STRING) + VERSION_VAR PostgreSQL_VERSION) function(__postgresql_import_library _target _var _config) if(_config)
diff --git a/Modules/FindProducer.cmake b/Modules/FindProducer.cmake index 1d034bc..7fbd837 100644 --- a/Modules/FindProducer.cmake +++ b/Modules/FindProducer.cmake
@@ -14,8 +14,12 @@ library became obsolete and is no longer maintained. For details about OpenSceneGraph usage, refer to the :module:`FindOpenSceneGraph` module. -This module finds the Producer library, a windowing and event handling library -designed primarily for real-time graphics applications. +Finds the Producer library, a windowing and event handling library designed +primarily for real-time graphics applications: + +.. code-block:: cmake + + find_package(Producer [...]) Producer library headers are intended to be included in C++ project source code as: @@ -31,8 +35,9 @@ This module defines the following variables: ``Producer_FOUND`` - Boolean indicating whether Producer is found. For backward compatibility, the - ``PRODUCER_FOUND`` variable is also set to the same value. + .. versionadded:: 3.3 + + Boolean indicating whether Producer was found. Cache Variables ^^^^^^^^^^^^^^^ @@ -68,6 +73,17 @@ ``OSG_DIR`` Environment variable treated the same as ``PRODUCER_DIR``. +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +The following variables are provided for backward compatibility: + +``PRODUCER_FOUND`` + .. deprecated:: 4.2 + Use ``Producer_FOUND``, which has the same value. + + Boolean indicating whether Producer was found. + Examples ^^^^^^^^
diff --git a/Modules/FindProtobuf.cmake b/Modules/FindProtobuf.cmake index 4402afa..62baba1 100644 --- a/Modules/FindProtobuf.cmake +++ b/Modules/FindProtobuf.cmake
@@ -78,8 +78,11 @@ This module defines the following variables: ``Protobuf_FOUND`` - Boolean indicating whether (the requested version of) Protobuf library is - found. + .. versionadded:: 3.3 + + Boolean indicating whether the (requested version of) Protobuf library + was found. + ``Protobuf_VERSION`` .. versionadded:: 3.6
diff --git a/Modules/FindPython.cmake b/Modules/FindPython.cmake index 28f47b4..46a8cbb 100644 --- a/Modules/FindPython.cmake +++ b/Modules/FindPython.cmake
@@ -7,8 +7,12 @@ .. versionadded:: 3.12 -Find Python interpreter, compiler and development environment (include -directories and libraries). +Finds Python interpreter, compiler and development environment (include +directories and libraries): + +.. code-block:: cmake + + find_package(Python [<version>] [COMPONENTS <components>...] [...]) .. versionadded:: 3.19 When a version is requested, it can be specified as a simple value or as a @@ -38,10 +42,14 @@ `Stable Application Binary Interface <https://docs.python.org/3/c-api/stable.html>`_. This component is available only for version ``3.2`` and upper. -* ``NumPy``: search for NumPy include directories. - .. versionadded:: 3.14 - Added the ``NumPy`` component. + + * ``NumPy``: search for NumPy include directories. Specifying this component + imply also the components ``Interpreter`` and ``Development.Module``. + + .. versionchanged:: 4.2 + The component ``Development.Module`` is no longer implied when the policy + :policy:`CMP0201` is set to ``NEW``. If no ``COMPONENTS`` are specified, ``Interpreter`` is assumed. @@ -87,7 +95,7 @@ Imported Targets ^^^^^^^^^^^^^^^^ -This module defines the following :ref:`Imported Targets <Imported Targets>`: +This module provides the following :ref:`Imported Targets`: .. versionchanged:: 3.14 :ref:`Imported Targets <Imported Targets>` are only created when @@ -134,17 +142,22 @@ .. versionadded:: 3.14 NumPy Python library. Target defined if component ``NumPy`` is found. + Moreover, this target has the ``Python::Module`` target as dependency. + + .. versionchanged:: 4.2 + This target does not have anymore the ``Python::Module`` target as + dependency when the policy :policy:`CMP0201` is set to ``NEW``. Result Variables ^^^^^^^^^^^^^^^^ -This module will set the following variables in your project +This module defines the following variables (see :ref:`Standard Variable Names <CMake Developer Standard Variable Names>`): ``Python_FOUND`` - System has the Python requested components. + Boolean indicating whether system has the Python requested components. ``Python_Interpreter_FOUND`` - System has the Python interpreter. + Boolean indicating whether system has the Python interpreter. ``Python_EXECUTABLE`` Path to the Python interpreter. ``Python_EXECUTABLE_DEBUG`` @@ -206,7 +219,7 @@ string. ``Python_Compiler_FOUND`` - System has the Python compiler. + Boolean indicating whether system has the Python compiler. ``Python_COMPILER`` Path to the Python compiler. Only offered by IronPython. ``Python_COMPILER_ID`` @@ -219,23 +232,25 @@ The ``.Net`` interpreter. Only used by ``IronPython`` implementation. ``Python_Development_FOUND`` - System has the Python development artifacts. + Boolean indicating whether system has the Python development artifacts. ``Python_Development.Module_FOUND`` .. versionadded:: 3.18 - System has the Python development artifacts for Python module. + Boolean indicating whether system has the Python development artifacts + for Python module. ``Python_Development.SABIModule_FOUND`` .. versionadded:: 3.26 - System has the Python development artifacts for Python module using the - Stable Application Binary Interface. + Boolean indicating whether system has the Python development artifacts + for Python module using the Stable Application Binary Interface. ``Python_Development.Embed_FOUND`` .. versionadded:: 3.18 - System has the Python development artifacts for Python embedding. + Boolean indicating whether system has the Python development artifacts + for Python embedding. ``Python_INCLUDE_DIRS`` @@ -293,7 +308,7 @@ ``Python_NumPy_FOUND`` .. versionadded:: 3
