Merge topic 'gcc-implicit-libs' 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-format b/.clang-format index 84b96ab..a733a1a 100644 --- a/.clang-format +++ b/.clang-format
@@ -33,6 +33,8 @@ Priority: 3 - Regex: '^<sys/' Priority: 5 + - Regex: '^"QCMake' + Priority: 11 - Regex: '^(<|")Qt?[A-Z]' Priority: 6 - Regex: '^<cmtp/'
diff --git a/.clang-tidy b/.clang-tidy index 35503d4..3a0fd82 100644 --- a/.clang-tidy +++ b/.clang-tidy
@@ -3,8 +3,10 @@ bugprone-*,\ -bugprone-assignment-in-if-condition,\ -bugprone-crtp-constructor-accessibility,\ +-bugprone-derived-method-shadowing-base-method,\ -bugprone-easily-swappable-parameters,\ -bugprone-empty-catch,\ +-bugprone-exception-escape,\ -bugprone-implicit-widening-of-multiplication-result,\ -bugprone-inc-dec-in-conditions,\ -bugprone-macro-parentheses,\ @@ -13,8 +15,10 @@ -bugprone-return-const-ref-from-parameter,\ -bugprone-suspicious-stringview-data-usage,\ -bugprone-switch-missing-default-case,\ +-bugprone-throwing-static-initialization,\ -bugprone-too-small-loop-variable,\ -bugprone-unchecked-optional-access,\ +-bugprone-unchecked-string-to-number-conversion,\ -bugprone-unused-local-non-trivial-variable,\ -bugprone-unused-return-value,\ -bugprone-use-after-move,\ @@ -22,20 +26,26 @@ -misc-confusable-identifiers,\ -misc-const-correctness,\ -misc-include-cleaner,\ +-misc-multiple-inheritance,\ -misc-non-private-member-variables-in-classes,\ -misc-no-recursion,\ +-misc-override-with-different-visibility,\ +-misc-predictable-rand,\ -misc-static-assert,\ -misc-use-anonymous-namespace,\ -misc-use-internal-linkage,\ modernize-*,\ -modernize-avoid-c-arrays,\ +-modernize-avoid-c-style-cast,\ -modernize-concat-nested-namespaces,\ -modernize-macro-to-enum,\ -modernize-return-braced-init-list,\ -modernize-type-traits,\ +-modernize-unary-static-assert, \ -modernize-use-emplace,\ -modernize-use-nodiscard,\ -modernize-use-noexcept,\ +-modernize-use-scoped-lock,\ -modernize-use-trailing-return-type,\ -modernize-use-transparent-functors,\ performance-*,\ @@ -58,10 +68,14 @@ -readability-make-member-function-const,\ -readability-math-missing-parentheses,\ -readability-named-parameter,\ +-readability-redundant-casting,\ +-readability-redundant-parentheses,\ +-readability-redundant-typename,\ -readability-simplify-boolean-expr,\ -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,\ @@ -76,4 +90,18 @@ value: '0' - key: modernize-use-auto.MinTypeNameLength value: '80' + - key: readability-identifier-naming.ClassCase + value: 'CamelCase' + - key: readability-identifier-naming.ClassIgnoredRegexp + value: 'cm[A-Z][A-Za-z]+|(const_)?iterator' + - key: readability-identifier-naming.ClassMemberCase + value: 'CamelCase' + - key: readability-identifier-naming.ClassMemberIgnoredRegexp + value: 'prop[A-Z_]+' + - key: readability-identifier-naming.PrivateMemberCase + value: 'CamelCase' + - key: readability-identifier-naming.ParameterCase + value: 'camelBack' + - key: readability-identifier-naming.LocalVariableCase + value: 'camelBack' ...
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..8c78b99 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 + - .fedora44_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,150 @@ 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-fedora44: extends: - - .fedora42_tidy + - .fedora44_tidy - .cmake_build_linux - .cmake_tidy_artifacts - .linux_x86_64_tags - .cmake_cdash_artifacts - - .run_automatically + - .rules -l:sphinx-fedora42: +l:pvs-studio-fedora44: extends: - - .fedora42_sphinx + - .fedora44_pvs_studio + - .cmake_build_linux + - .linux_x86_64_tags + - .cmake_cdash_artifacts + - .rules + variables: + CMAKE_CI_JOB_CONTINUOUS: "true" + CMAKE_CI_JOB_NIGHTLY: "true" + CMAKE_CI_JOB_NO_MR: "true" + +l:sphinx-fedora44: + extends: + - .fedora44_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-fedora44: extends: - - .fedora42_clang_analyzer + - .fedora44_clang_analyzer - .cmake_build_linux - .linux_x86_64_tags - - .run_automatically + - .rules variables: CMAKE_CI_JOB_NIGHTLY: "true" +l:clang-fuzzing-fedora44: + extends: + - .fedora44_clang_fuzzing + - .cmake_build_linux + - .linux_x86_64_tags + - .rules + +l:clazy-fedora44: + extends: + - .fedora44_clazy + - .cmake_build_linux + - .linux_x86_64_tags + - .rules + +# Coverage builds + +b:fedora44-gcc-gcov: + extends: + - .fedora44_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:fedora44-gcc-gcov: + extends: + - .fedora44_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:fedora44-gcc-gcov + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + +a:fedora44-gcc-gcov: + extends: + - .fedora44_gcc_gcov + - .cmake_coverage_linux + - .cmake_cdash_artifacts + - .linux_x86_64_tags + - .rules + needs: + - t:fedora44-gcc-gcov + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + +b:fedora44-bullseye-coverage: + extends: + - .fedora44_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:fedora44-bullseye-coverage: + extends: + - .fedora44_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:fedora44-bullseye-coverage + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + CMAKE_CI_JOB_NO_MR: "true" + +a:fedora44-bullseye-coverage: + extends: + - .fedora44_bullseye_coverage + - .cmake_coverage_linux + - .cmake_cdash_artifacts + - .linux_x86_64_tags + - .rules + needs: + - t:fedora44-bullseye-coverage + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + CMAKE_CI_JOB_NO_MR: "true" + # Linux builds b:centos7-x86_64: @@ -148,172 +271,213 @@ - .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:fedora44-hip-radeon: extends: - - .fedora42_hip_radeon + - .fedora44_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:fedora44-makefiles-lfortran: extends: - - .fedora42_makefiles_lfortran + - .fedora44_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:fedora44-ninja-lfortran: extends: - - .fedora42_ninja_lfortran + - .fedora44_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:fedora44-ninja-multi: extends: - - .fedora42_ninja_clang + - .fedora44_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:fedora44-ninja-clang: extends: - - .fedora42_ninja_multi_clang + - .fedora44_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:fedora44-ninja-gcc-std-reloc: extends: - - .fedora42_makefiles_clang + - .fedora44_ninja_gcc_std_reloc - .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:fedora44-ninja-multi-clang: extends: - - .fedora42_makefiles + - .fedora44_ninja_multi_clang + - .cmake_test_linux_release + - .linux_x86_64_tags + - .rules + - .needs_centos7_x86_64 + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + +t:fedora44-makefiles-clang: + extends: + - .fedora44_makefiles_clang + - .cmake_test_linux_release + - .linux_x86_64_tags + - .rules + - .needs_centos7_x86_64 + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + +t:fedora44-makefiles: + extends: + - .fedora44_makefiles - .cmake_test_linux_release - .linux_x86_64_v3_tags - - .run_dependent + - .rules - .needs_centos7_x86_64 -t:fedora42-makefiles-nospace: +t:fedora44-makefiles-nospace: extends: - - .fedora42_makefiles + - .fedora44_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: fedora44_makefiles_nospace CMAKE_CI_JOB_NIGHTLY: "true" -t:nvhpc24.9-ninja: +t:fedora44-fastbuild: + extends: + - .fedora44_fastbuild + - .cmake_test_linux_release + - .linux_x86_64_v3_tags + - .rules + - .needs_centos7_x86_64 + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + +t:fedora44-instrumentation: + extends: + - .fedora44_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:nvhpc26.3-ninja: extends: - .nvhpc_ninja - .cmake_test_linux_release - - .linux_x86_64_v3_tags_cuda_arch_52 - - .run_dependent + - .linux_x86_64_v3_tags_cuda_arch_75 + - .rules - .needs_centos7_x86_64 variables: CMAKE_CI_JOB_NIGHTLY: "true" @@ -323,7 +487,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 +498,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 +508,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 +519,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 +529,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 +539,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 +549,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 +560,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 +570,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 +581,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 +592,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 +602,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 +644,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,27 +654,7 @@ - .hip6.3_radeon - .cmake_test_linux_release - .linux_x86_64_tags_rocm6.3 - - .run_dependent - - .needs_centos7_x86_64 - variables: - CMAKE_CI_JOB_NIGHTLY: "true" - -t:linux-gcc-cxx-modules-ninja: - extends: - - .gcc_cxx_modules_ninja - - .cmake_test_linux_release - - .linux_x86_64_tags - - .run_dependent - - .needs_centos7_x86_64 - variables: - CMAKE_CI_JOB_NIGHTLY: "true" - -t:linux-gcc-cxx-modules-ninja-multi: - extends: - - .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 +665,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:fedora44-ninja: extends: - - .fedora42_ninja + - .fedora44_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:fedora44-makefiles-symlinked: extends: - - .fedora42_makefiles_symlinked + - .fedora44_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:fedora44-extdeps: extends: - - .fedora42_extdeps + - .fedora44_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:fedora44-ninja: extends: - - .fedora42_ninja + - .fedora44_ninja - .cmake_test_linux - .linux_x86_64_tags_x11 - .cmake_test_artifacts - - .run_dependent + - .rules needs: - - b:fedora42-ninja + - b:fedora44-ninja variables: CMAKE_CI_JOB_CONTINUOUS: "true" -t:fedora42-makefiles-symlinked: +t:fedora44-makefiles-symlinked: extends: - - .fedora42_makefiles_symlinked + - .fedora44_makefiles_symlinked - .cmake_test_linux - .linux_x86_64_tags_x11 - .cmake_test_artifacts - - .run_dependent + - .rules needs: - - b:fedora42-makefiles-symlinked + - b:fedora44-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 @@ -617,34 +791,6 @@ CMAKE_CI_BUILD_NAME: intel2020u4_makefiles CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2020u4-el8 -t:intel2021.1.1-makefiles: - extends: - - .cmake_test_linux_intelclassic_makefiles - variables: - CMAKE_CI_BUILD_NAME: intel2021.1.1_makefiles - CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2021.1.1-el8 - -t:intel2021.1.2-makefiles: - extends: - - .cmake_test_linux_intelclassic_makefiles - variables: - CMAKE_CI_BUILD_NAME: intel2021.1.2_makefiles - CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2021.1.2-el8 - -t:intel2021.2.0-makefiles: - extends: - - .cmake_test_linux_intelclassic_makefiles - variables: - CMAKE_CI_BUILD_NAME: intel2021.2.0_makefiles - CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2021.2.0-el8 - -t:intel2021.3.0-makefiles: - extends: - - .cmake_test_linux_intelclassic_makefiles - variables: - CMAKE_CI_BUILD_NAME: intel2021.3.0_makefiles - CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2021.3.0-el8 - t:intel2021.4.0-makefiles: extends: - .cmake_test_linux_intelclassic_makefiles @@ -652,20 +798,6 @@ CMAKE_CI_BUILD_NAME: intel2021.4.0_makefiles CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2021.4.0-el8 -t:intel2021.5.0-makefiles: - extends: - - .cmake_test_linux_intelclassic_makefiles - variables: - CMAKE_CI_BUILD_NAME: intel2021.5.0_makefiles - CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2022.0.2-el8 - -t:intel2021.6.0-makefiles: - extends: - - .cmake_test_linux_intelclassic_makefiles - variables: - CMAKE_CI_BUILD_NAME: intel2021.6.0_makefiles - CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2022.1.0-el8 - t:intel2021.7.0-makefiles: extends: - .cmake_test_linux_intelclassic_makefiles @@ -673,20 +805,6 @@ CMAKE_CI_BUILD_NAME: intel2021.7.0_makefiles CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2022.2.0-el8 -t:intel2021.8.0-makefiles: - extends: - - .cmake_test_linux_intelclassic_makefiles - variables: - CMAKE_CI_BUILD_NAME: intel2021.8.0_makefiles - CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2023.0.0-el8 - -t:intel2021.9.0-makefiles: - extends: - - .cmake_test_linux_intelclassic_makefiles - variables: - CMAKE_CI_BUILD_NAME: intel2021.9.0_makefiles - CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2023.1.0-el8 - t:intel2021.10.0-makefiles: extends: - .cmake_test_linux_intelclassic_makefiles @@ -694,34 +812,6 @@ CMAKE_CI_BUILD_NAME: intel2021.10.0_makefiles CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2023.2.1-el8 -t:oneapi2021.1.1-makefiles: - extends: - - .cmake_test_linux_inteloneapi_makefiles - variables: - CMAKE_CI_BUILD_NAME: oneapi2021.1.1_makefiles - CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2021.1.1-el8 - -t:oneapi2021.1.2-makefiles: - extends: - - .cmake_test_linux_inteloneapi_makefiles - variables: - CMAKE_CI_BUILD_NAME: oneapi2021.1.2_makefiles - CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2021.1.2-el8 - -t:oneapi2021.2.0-makefiles: - extends: - - .cmake_test_linux_inteloneapi_makefiles - variables: - CMAKE_CI_BUILD_NAME: oneapi2021.2.0_makefiles - CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2021.2.0-el8 - -t:oneapi2021.3.0-makefiles: - extends: - - .cmake_test_linux_inteloneapi_makefiles - variables: - CMAKE_CI_BUILD_NAME: oneapi2021.3.0_makefiles - CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2021.3.0-el8 - t:oneapi2021.4.0-makefiles: extends: - .cmake_test_linux_inteloneapi_makefiles @@ -729,20 +819,6 @@ CMAKE_CI_BUILD_NAME: oneapi2021.4.0_makefiles CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2021.4.0-el8 -t:oneapi2022.0.2-makefiles: - extends: - - .cmake_test_linux_inteloneapi_makefiles - variables: - CMAKE_CI_BUILD_NAME: oneapi2022.0.2_makefiles - CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2022.0.2-el8 - -t:oneapi2022.1.0-makefiles: - extends: - - .cmake_test_linux_inteloneapi_makefiles - variables: - CMAKE_CI_BUILD_NAME: oneapi2022.1.0_makefiles - CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2022.1.0-el8 - t:oneapi2022.2.0-makefiles: extends: - .cmake_test_linux_inteloneapi_makefiles @@ -750,20 +826,6 @@ CMAKE_CI_BUILD_NAME: oneapi2022.2.0_makefiles CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2022.2.0-el8 -t:oneapi2023.0.0-makefiles: - extends: - - .cmake_test_linux_inteloneapi_makefiles - variables: - CMAKE_CI_BUILD_NAME: oneapi2023.0.0_makefiles - CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2023.0.0-el8 - -t:oneapi2023.1.0-makefiles: - extends: - - .cmake_test_linux_inteloneapi_makefiles - variables: - CMAKE_CI_BUILD_NAME: oneapi2023.1.0_makefiles - CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2023.1.0-el8 - t:oneapi2023.2.0-makefiles: extends: - .cmake_test_linux_inteloneapi_makefiles @@ -771,20 +833,6 @@ CMAKE_CI_BUILD_NAME: oneapi2023.2.1_makefiles CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2023.2.1-el8 -t:oneapi2024.0.0-makefiles: - extends: - - .cmake_test_linux_inteloneapi_makefiles - variables: - CMAKE_CI_BUILD_NAME: oneapi2024.0.0_makefiles - CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2024.0.0-el8 - -t:oneapi2024.1.0-makefiles: - extends: - - .cmake_test_linux_inteloneapi_makefiles - variables: - CMAKE_CI_BUILD_NAME: oneapi2024.1.0_makefiles - CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2024.1.0-el8 - t:oneapi2024.2.0-makefiles: extends: - .cmake_test_linux_inteloneapi_makefiles @@ -792,19 +840,12 @@ CMAKE_CI_BUILD_NAME: oneapi2024.2.0_makefiles CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2024.2.0-rocky9 -t:oneapi2025.0.0-makefiles: +t:oneapi2025.3.0-makefiles: extends: - .cmake_test_linux_inteloneapi_makefiles variables: - CMAKE_CI_BUILD_NAME: oneapi2025.0.0_makefiles - CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2025.0.0-rocky9 - -t:oneapi2025.1.0-makefiles: - extends: - - .cmake_test_linux_inteloneapi_makefiles - variables: - CMAKE_CI_BUILD_NAME: oneapi2025.1.0_makefiles - CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2025.1.0-rocky9 + CMAKE_CI_BUILD_NAME: oneapi2025.3.0_makefiles + CMAKE_CI_INTELCOMPILER_IMAGE_TAG: 2025.3.0-rocky9 b:linux-x86_64-package: extends: @@ -813,16 +854,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 +878,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 +902,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 +926,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:fedora44-asan: extends: - - .fedora42_asan + - .fedora44_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:fedora44-asan: + extends: + - .fedora44_asan + - .cmake_memcheck_linux + - .linux_x86_64_tags + - .cmake_junit_artifacts + - .rules + needs: + - b:fedora44-asan variables: CMAKE_CI_JOB_NIGHTLY: "true" -t:fedora42-asan: +t:fedora44-ninja-valgrind: extends: - - .fedora42_asan - - .cmake_memcheck_linux - - .linux_x86_64_tags - - .run_dependent - needs: - - b:fedora42-asan + - .fedora44_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 +989,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 +1000,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 +1011,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 +1032,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 +1044,7 @@ - .cmake_test_macos - .cmake_test_artifacts - .macos_arm64_tags - - .run_dependent + - .rules needs: - b:macos-arm64-ninja variables: @@ -991,38 +1057,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 +1089,7 @@ - .cmake_test_macos_external - .macos_arm64_tags_ext - .cmake_junit_artifacts - - .run_dependent + - .rules needs: - t:macos-arm64-ninja variables: @@ -1044,11 +1101,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 +1113,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 +1147,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 +1159,7 @@ - .cmake_test_macos_external - .macos_arm64_tags_ext - .cmake_junit_artifacts - - .run_dependent + - .rules needs: - t:macos-arm64-ninja variables: @@ -1102,18 +1171,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 +1206,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 +1333,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 +1381,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 +1393,75 @@ - .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-clang22.1-cl-fastbuild: + extends: + - .windows_clang_fastbuild + - .cmake_test_windows_external + - .windows_x86_64_tags_concurrent_vs2022_msvc14.44 + - .cmake_junit_artifacts + - .rules + needs: + - t:windows-vs2026-x64-ninja + variables: + CMAKE_CI_BUILD_NAME: windows_clang22.1_cl_fastbuild + CMAKE_CI_JOB_NIGHTLY: "true" + +t:windows-clang22.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_clang22.1_cl_ninja CMAKE_CI_JOB_NIGHTLY: "true" -t:windows-clang19.1-cl-nmake: +t:windows-clang22.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_clang22.1_cl_nmake CMAKE_CI_JOB_NIGHTLY: "true" -t:windows-clang19.1-gnu-ninja: +t:windows-clang22.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_clang22.1_gnu_ninja CMAKE_CI_JOB_NIGHTLY: "true" -t:windows-clang19.1-gnu-nmake: +t:windows-clang22.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_clang22.1_gnu_nmake CMAKE_CI_JOB_NIGHTLY: "true" t:windows-intel2021.9-ninja: @@ -1330,9 +1470,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 +1481,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 +1496,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 +1508,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 +1520,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,45 +1532,82 @@ - .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-orangec6.73.1: +t:windows-orangec6.73.8: extends: - - .windows_orangec6.73.1 + - .windows_orangec6.73.8 - .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-orangec7.0.7: + extends: + - .windows_orangec7.0.7 + - .cmake_test_windows_external + - .windows_x86_64_tags_concurrent + - .cmake_junit_artifacts + - .rules + needs: + - t:windows-vs2026-x64-ninja + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + +t:windows-pellesc13.01: + extends: + - .windows_pellesc13.01 + - .cmake_test_windows_external + - .windows_x86_64_tags_concurrent + - .cmake_junit_artifacts + - .rules + needs: + - 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 +1617,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 +1630,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 +1644,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 +1666,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 +1680,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 +1702,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 +1716,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..c0e73eb 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* @@ -16,6 +19,8 @@ /openmp /open-watcom* /orangec +/pellesc +/pvs-studio /python* /qt* /sccache*
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..132588c --- /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.25.1" + +case "$(uname -s)-$(uname -m)" in + Linux-x86_64) + tarball="BullseyeCoverage-$version-Linux-x64.tar.xz" + sha256sum="cc77ef1ffd846e9911a5a22c41a8e24c5e1f1c4c59c0c688b6756fcb14fa4af5" + 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..20830cc 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("clang22.1")) { + # LLVM/Clang 22.1.2 + # https://github.com/llvm/llvm-project/releases/tag/llvmorg-22.1.2 + $filename = "llvm-22.1.2-win-x86_64-1" + $sha256sum = "31022498417A1225FABF31EE66AF11971BA2E4BA97FFE7A10F9A206CAD8A85E7" } 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..ee0f4db 100644 --- a/.gitlab/ci/cmake.ps1 +++ b/.gitlab/ci/cmake.ps1
@@ -1,12 +1,12 @@ $erroractionpreference = "stop" -$version = "3.31.5" +$version = "4.3.2" if ("$env:PROCESSOR_ARCHITECTURE" -eq "AMD64") { - $sha256sum = "D4D2D4B9CCD68DAE975A066FCD42EA9807EF40F79EE6971923FD3788E7917585" + $sha256sum = "83D20C23F5C5F64B3B328785E35B23C532E33057A97ED6294ACACA3781B78A01" $platform = "windows-x86_64" } elseif ("$env:PROCESSOR_ARCHITECTURE" -eq "ARM64") { - $sha256sum = "A734E4E970FDAA4B5957157C059556F56CA5D655014CD4B5FD9194AABA316F31" + $sha256sum = "42A2A88FC57E70D04A92F6EAAAC2094241995F53584BC2AFDAE7E6EF982B3781" $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..bc41ddd 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.3.2" case "$(uname -s)-$(uname -m)" in Linux-x86_64) shatool="sha256sum" - sha256sum="2984e70515ff60c5e4a41922b5d715a8168a696a89721e3b114e36f453244f72" + sha256sum="791ae3604841ca03cb3889a3ad89165346e4b180ae3448efd4b0caa9ef46d245" platform="linux-x86_64" ;; Linux-aarch64) shatool="sha256sum" - sha256sum="eb92af175ea91e3706ff62484088c3a3774ef3e1a8c399111785dd5f47010164" + sha256sum="377079ab739f5765176f427609d9a2015b756ea20d5cba908d279c3731a2f481" platform="linux-aarch64" ;; Darwin-*) shatool="shasum -a 256" - sha256sum="cc8e3d9bef7eee70db52601a5ed60d221436a8def18388effdab0e7d0866f50d" + sha256sum="808ab43a0db04c8eec9ed7db12b90d7be1c8e2e75f4a060724d604a2043ccaf7" 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..c42b18d --- /dev/null +++ b/.gitlab/ci/configure_debian13_aarch64_ninja.cmake
@@ -0,0 +1,117 @@ +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_MATH_OVERFLOW ON CACHE BOOL "") +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..7cc4099 --- /dev/null +++ b/.gitlab/ci/configure_debian13_ninja_common.cmake
@@ -0,0 +1,124 @@ +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_MATH_OVERFLOW ON CACHE BOOL "") +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_fedora44_asan.cmake b/.gitlab/ci/configure_fedora44_asan.cmake new file mode 100644 index 0000000..88f40c3 --- /dev/null +++ b/.gitlab/ci/configure_fedora44_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_fedora44_common.cmake")
diff --git a/.gitlab/ci/configure_fedora44_bullseye_coverage.cmake b/.gitlab/ci/configure_fedora44_bullseye_coverage.cmake new file mode 100644 index 0000000..d2e44a9 --- /dev/null +++ b/.gitlab/ci/configure_fedora44_bullseye_coverage.cmake
@@ -0,0 +1,22 @@ +# 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_MATH_OVERFLOW 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_fedora44_common.cmake")
diff --git a/.gitlab/ci/configure_fedora44_clang_analyzer.cmake b/.gitlab/ci/configure_fedora44_clang_analyzer.cmake new file mode 100644 index 0000000..58046b9 --- /dev/null +++ b/.gitlab/ci/configure_fedora44_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_fedora44_common.cmake")
diff --git a/.gitlab/ci/configure_fedora44_clang_fuzzing.cmake b/.gitlab/ci/configure_fedora44_clang_fuzzing.cmake new file mode 100644 index 0000000..48a4b7b --- /dev/null +++ b/.gitlab/ci/configure_fedora44_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_fedora44_clazy.cmake b/.gitlab/ci/configure_fedora44_clazy.cmake new file mode 100644 index 0000000..7f2ec78 --- /dev/null +++ b/.gitlab/ci/configure_fedora44_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_fedora44_common.cmake")
diff --git a/.gitlab/ci/configure_fedora42_common.cmake b/.gitlab/ci/configure_fedora44_common.cmake similarity index 100% rename from .gitlab/ci/configure_fedora42_common.cmake rename to .gitlab/ci/configure_fedora44_common.cmake
diff --git a/.gitlab/ci/configure_fedora44_common_clang.cmake b/.gitlab/ci/configure_fedora44_common_clang.cmake new file mode 100644 index 0000000..c7b38b6 --- /dev/null +++ b/.gitlab/ci/configure_fedora44_common_clang.cmake
@@ -0,0 +1,17 @@ +set(CMAKE_Fortran_COMPILER "/usr/bin/flang" 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_fedora44_common_lfortran.cmake similarity index 100% rename from .gitlab/ci/configure_fedora42_common_lfortran.cmake rename to .gitlab/ci/configure_fedora44_common_lfortran.cmake
diff --git a/.gitlab/ci/configure_debian12_extdeps.cmake b/.gitlab/ci/configure_fedora44_extdeps.cmake similarity index 100% copy from .gitlab/ci/configure_debian12_extdeps.cmake copy to .gitlab/ci/configure_fedora44_extdeps.cmake
diff --git a/.gitlab/ci/configure_fedora44_fastbuild.cmake b/.gitlab/ci/configure_fedora44_fastbuild.cmake new file mode 100644 index 0000000..20863a2 --- /dev/null +++ b/.gitlab/ci/configure_fedora44_fastbuild.cmake
@@ -0,0 +1 @@ +include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake")
diff --git a/.gitlab/ci/configure_fedora44_gcc_gcov.cmake b/.gitlab/ci/configure_fedora44_gcc_gcov.cmake new file mode 100644 index 0000000..e54437e --- /dev/null +++ b/.gitlab/ci/configure_fedora44_gcc_gcov.cmake
@@ -0,0 +1,31 @@ +set(CMake_TEST_GUI "ON" CACHE BOOL "") +set(CMake_TEST_MATH_OVERFLOW 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(JOIN " " 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[.].*" +) +string(JOIN " " link_flags + "--coverage" +) + +set(CMAKE_C_FLAGS "${coverage_flags}" CACHE STRING "") +set(CMAKE_CXX_FLAGS "${coverage_flags}" 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_fedora44_common.cmake")
diff --git a/.gitlab/ci/configure_fedora42_hip_radeon.cmake b/.gitlab/ci/configure_fedora44_hip_radeon.cmake similarity index 100% rename from .gitlab/ci/configure_fedora42_hip_radeon.cmake rename to .gitlab/ci/configure_fedora44_hip_radeon.cmake
diff --git a/.gitlab/ci/configure_fedora44_makefiles.cmake b/.gitlab/ci/configure_fedora44_makefiles.cmake new file mode 100644 index 0000000..2cd93f4 --- /dev/null +++ b/.gitlab/ci/configure_fedora44_makefiles.cmake
@@ -0,0 +1,121 @@ +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_LOCALE_C_UTF8 ON CACHE BOOL "") +set(CMake_TEST_MATH_OVERFLOW ON CACHE BOOL "") +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_fedora44_makefiles_clang.cmake b/.gitlab/ci/configure_fedora44_makefiles_clang.cmake new file mode 100644 index 0000000..02bf288 --- /dev/null +++ b/.gitlab/ci/configure_fedora44_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_fedora44_common_clang.cmake")
diff --git a/.gitlab/ci/configure_fedora44_makefiles_lfortran.cmake b/.gitlab/ci/configure_fedora44_makefiles_lfortran.cmake new file mode 100644 index 0000000..2289116 --- /dev/null +++ b/.gitlab/ci/configure_fedora44_makefiles_lfortran.cmake
@@ -0,0 +1 @@ +include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora44_common_lfortran.cmake")
diff --git a/.gitlab/ci/configure_fedora44_makefiles_symlinked.cmake b/.gitlab/ci/configure_fedora44_makefiles_symlinked.cmake new file mode 100644 index 0000000..e14b28f --- /dev/null +++ b/.gitlab/ci/configure_fedora44_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_fedora44_common.cmake")
diff --git a/.gitlab/ci/configure_fedora44_ninja.cmake b/.gitlab/ci/configure_fedora44_ninja.cmake new file mode 100644 index 0000000..d536871 --- /dev/null +++ b/.gitlab/ci/configure_fedora44_ninja.cmake
@@ -0,0 +1,45 @@ +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_LOCALE_C_UTF8 ON CACHE BOOL "") +set(CMake_TEST_MATH_OVERFLOW 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_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 "") + +string(JOIN " " flags + "-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" +) + +set(CMAKE_C_FLAGS "${flags}" CACHE STRING "") +set(CMAKE_CXX_FLAGS "${flags} -Woverloaded-virtual -Wstrict-null-sentinel" 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_fedora44_common.cmake")
diff --git a/.gitlab/ci/configure_fedora44_ninja_clang.cmake b/.gitlab/ci/configure_fedora44_ninja_clang.cmake new file mode 100644 index 0000000..5e007f4 --- /dev/null +++ b/.gitlab/ci/configure_fedora44_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_fedora44_common_clang.cmake")
diff --git a/.gitlab/ci/configure_fedora44_ninja_gcc_std_reloc.cmake b/.gitlab/ci/configure_fedora44_ninja_gcc_std_reloc.cmake new file mode 100644 index 0000000..6cd5f3e --- /dev/null +++ b/.gitlab/ci/configure_fedora44_ninja_gcc_std_reloc.cmake
@@ -0,0 +1,4 @@ +set(CMake_TEST_CXX_STDLIB_MODULES_JSON "$ENV{CMAKE_CI_CXX_STDLIB_MODULES_JSON}" CACHE FILEPATH "") +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_external_test.cmake")
diff --git a/.gitlab/ci/configure_fedora44_ninja_instrumentation.cmake b/.gitlab/ci/configure_fedora44_ninja_instrumentation.cmake new file mode 100644 index 0000000..1033477 --- /dev/null +++ b/.gitlab/ci/configure_fedora44_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_fedora44_ninja.cmake")
diff --git a/.gitlab/ci/configure_fedora44_ninja_lfortran.cmake b/.gitlab/ci/configure_fedora44_ninja_lfortran.cmake new file mode 100644 index 0000000..2289116 --- /dev/null +++ b/.gitlab/ci/configure_fedora44_ninja_lfortran.cmake
@@ -0,0 +1 @@ +include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora44_common_lfortran.cmake")
diff --git a/.gitlab/ci/configure_fedora44_ninja_multi.cmake b/.gitlab/ci/configure_fedora44_ninja_multi.cmake new file mode 100644 index 0000000..a99b5d1 --- /dev/null +++ b/.gitlab/ci/configure_fedora44_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_fedora44_ninja_multi_clang.cmake b/.gitlab/ci/configure_fedora44_ninja_multi_clang.cmake new file mode 100644 index 0000000..3a54edf --- /dev/null +++ b/.gitlab/ci/configure_fedora44_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_fedora44_common_clang.cmake")
diff --git a/.gitlab/ci/configure_fedora44_ninja_valgrind.cmake b/.gitlab/ci/configure_fedora44_ninja_valgrind.cmake new file mode 100644 index 0000000..53f1b83 --- /dev/null +++ b/.gitlab/ci/configure_fedora44_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_fedora44_valgrind.cmake") +include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora44_ninja.cmake") +include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake")
diff --git a/.gitlab/ci/configure_fedora44_pvs_studio.cmake b/.gitlab/ci/configure_fedora44_pvs_studio.cmake new file mode 100644 index 0000000..b15137e --- /dev/null +++ b/.gitlab/ci/configure_fedora44_pvs_studio.cmake
@@ -0,0 +1,3 @@ +set(configure_no_sccache 1) +set(CMake_RUN_PVS_STUDIO ON CACHE BOOL "") +include("${CMAKE_CURRENT_LIST_DIR}/configure_fedora44_common.cmake")
diff --git a/.gitlab/ci/configure_fedora42_sphinx.cmake b/.gitlab/ci/configure_fedora44_sphinx.cmake similarity index 100% rename from .gitlab/ci/configure_fedora42_sphinx.cmake rename to .gitlab/ci/configure_fedora44_sphinx.cmake
diff --git a/.gitlab/ci/configure_fedora42_sphinx_package.cmake b/.gitlab/ci/configure_fedora44_sphinx_package.cmake similarity index 100% rename from .gitlab/ci/configure_fedora42_sphinx_package.cmake rename to .gitlab/ci/configure_fedora44_sphinx_package.cmake
diff --git a/.gitlab/ci/configure_fedora44_tidy.cmake b/.gitlab/ci/configure_fedora44_tidy.cmake new file mode 100644 index 0000000..18e7743 --- /dev/null +++ b/.gitlab/ci/configure_fedora44_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_fedora44_common.cmake")
diff --git a/.gitlab/ci/configure_fedora44_valgrind.cmake b/.gitlab/ci/configure_fedora44_valgrind.cmake new file mode 100644 index 0000000..0175395 --- /dev/null +++ b/.gitlab/ci/configure_fedora44_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_ninja.cmake b/.gitlab/ci/configure_linux_gcc_cxx_modules_ninja.cmake deleted file mode 100644 index b7faa36..0000000 --- a/.gitlab/ci/configure_linux_gcc_cxx_modules_ninja.cmake +++ /dev/null
@@ -1,3 +0,0 @@ -set(CMake_TEST_MODULE_COMPILATION "named,compile_commands,collation,partitions,internal_partitions,export_bmi,install_bmi,bmionly,build_database,import_std23" CACHE STRING "") - -include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake")
diff --git a/.gitlab/ci/configure_linux_gcc_cxx_modules_ninja_multi.cmake b/.gitlab/ci/configure_linux_gcc_cxx_modules_ninja_multi.cmake deleted file mode 100644 index b7faa36..0000000 --- a/.gitlab/ci/configure_linux_gcc_cxx_modules_ninja_multi.cmake +++ /dev/null
@@ -1,3 +0,0 @@ -set(CMake_TEST_MODULE_COMPILATION "named,compile_commands,collation,partitions,internal_partitions,export_bmi,install_bmi,bmionly,build_database,import_std23" CACHE STRING "") - -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..1d0787c 100644 --- a/.gitlab/ci/configure_macos_arm64_ninja.cmake +++ b/.gitlab/ci/configure_macos_arm64_ninja.cmake
@@ -1,11 +1,14 @@ 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_LOCALE_C_UTF8 ON CACHE BOOL "") +set(CMake_TEST_MATH_OVERFLOW 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.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_makefiles.cmake b/.gitlab/ci/configure_macos_x86_64_makefiles.cmake index 99beb68..1a5a6e5 100644 --- a/.gitlab/ci/configure_macos_x86_64_makefiles.cmake +++ b/.gitlab/ci/configure_macos_x86_64_makefiles.cmake
@@ -6,6 +6,7 @@ if (NOT "$ENV{CMAKE_CI_NIGHTLY}" STREQUAL "") set(CMake_TEST_ISPC "ON" CACHE STRING "") endif() +set(CMake_TEST_MATH_OVERFLOW 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.2" CACHE STRING "")
diff --git a/.gitlab/ci/configure_macos_x86_64_ninja.cmake b/.gitlab/ci/configure_macos_x86_64_ninja.cmake index 9de043e..c3c3d83 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,9 @@ 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_LOCALE_C_UTF8 ON CACHE BOOL "") +set(CMake_TEST_MATH_OVERFLOW 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.2" CACHE STRING "")
diff --git a/.gitlab/ci/configure_nvhpc_ninja.cmake b/.gitlab/ci/configure_nvhpc_ninja.cmake index e25ff72..b72c4aa 100644 --- a/.gitlab/ci/configure_nvhpc_ninja.cmake +++ b/.gitlab/ci/configure_nvhpc_ninja.cmake
@@ -1,9 +1,9 @@ set(CMake_TEST_CUDA "NVIDIA" CACHE STRING "") -set(CMake_TEST_CUDA_ARCH "52" CACHE STRING "") +set(CMake_TEST_CUDA_ARCH "75" CACHE STRING "") set(CMake_TEST_CUDA_CUPTI "ON" CACHE STRING "") -set(CMake_TEST_C_STANDARDS "90;99;11;17" CACHE STRING "") -set(CMake_TEST_CXX_STANDARDS "98;11;14;17;20;23" CACHE STRING "") +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(configure_no_sccache 1)
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_clang_fastbuild.cmake b/.gitlab/ci/configure_windows_clang_fastbuild.cmake new file mode 100644 index 0000000..ba19834 --- /dev/null +++ b/.gitlab/ci/configure_windows_clang_fastbuild.cmake
@@ -0,0 +1 @@ +include("${CMAKE_CURRENT_LIST_DIR}/configure_windows_clang_common.cmake")
diff --git a/.gitlab/ci/configure_windows_clang_ninja.cmake b/.gitlab/ci/configure_windows_clang_ninja.cmake index 214c754..e8a0171 100644 --- a/.gitlab/ci/configure_windows_clang_ninja.cmake +++ b/.gitlab/ci/configure_windows_clang_ninja.cmake
@@ -1,4 +1,2 @@ -if("$ENV{CMAKE_CI_BUILD_NAME}" MATCHES "(^|_)gnu(_|$)") - set(CMake_TEST_MODULE_COMPILATION "named,compile_commands,collation,partitions,internal_partitions,export_bmi,install_bmi,shared,bmionly,build_database" 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_windows_clang_common.cmake")
diff --git a/.gitlab/ci/configure_windows_common.cmake b/.gitlab/ci/configure_windows_common.cmake index 7467cfd..b243ece 100644 --- a/.gitlab/ci/configure_windows_common.cmake +++ b/.gitlab/ci/configure_windows_common.cmake
@@ -2,6 +2,8 @@ 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(CMake_TEST_LOCALE_C_UTF8 ON CACHE BOOL "") 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_intelclassic_ninja.cmake b/.gitlab/ci/configure_windows_intelclassic_ninja.cmake index c2d708b..84b9a88 100644 --- a/.gitlab/ci/configure_windows_intelclassic_ninja.cmake +++ b/.gitlab/ci/configure_windows_intelclassic_ninja.cmake
@@ -1 +1,4 @@ +set(CMake_TEST_C_STANDARDS "90;99;11" CACHE STRING "") +set(CMake_TEST_CXX_STANDARDS "98;11;14;17;20" CACHE STRING "") + include("${CMAKE_CURRENT_LIST_DIR}/configure_windows_intelcompiler_common.cmake")
diff --git a/.gitlab/ci/configure_windows_inteloneapi_ninja.cmake b/.gitlab/ci/configure_windows_inteloneapi_ninja.cmake index c2d708b..cb252e0 100644 --- a/.gitlab/ci/configure_windows_inteloneapi_ninja.cmake +++ b/.gitlab/ci/configure_windows_inteloneapi_ninja.cmake
@@ -1 +1,4 @@ +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 "") + include("${CMAKE_CURRENT_LIST_DIR}/configure_windows_intelcompiler_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_orangec6.73.1.cmake b/.gitlab/ci/configure_windows_orangec6.73.8.cmake similarity index 100% rename from .gitlab/ci/configure_windows_orangec6.73.1.cmake rename to .gitlab/ci/configure_windows_orangec6.73.8.cmake
diff --git a/.gitlab/ci/configure_windows_orangec7.0.7.cmake b/.gitlab/ci/configure_windows_orangec7.0.7.cmake new file mode 100644 index 0000000..e5ca56b --- /dev/null +++ b/.gitlab/ci/configure_windows_orangec7.0.7.cmake
@@ -0,0 +1,3 @@ +set(CMake_TEST_C_STANDARDS "90;99;11;23" CACHE STRING "") +set(CMake_TEST_CXX_STANDARDS "11;14;17" CACHE STRING "") +include("${CMAKE_CURRENT_LIST_DIR}/configure_windows_orangec_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_pellesc13.01.cmake b/.gitlab/ci/configure_windows_pellesc13.01.cmake new file mode 100644 index 0000000..db8a63c --- /dev/null +++ b/.gitlab/ci/configure_windows_pellesc13.01.cmake
@@ -0,0 +1 @@ +include("${CMAKE_CURRENT_LIST_DIR}/configure_windows_pellesc_common.cmake")
diff --git a/.gitlab/ci/configure_windows_pellesc_common.cmake b/.gitlab/ci/configure_windows_pellesc_common.cmake new file mode 100644 index 0000000..7027e7c --- /dev/null +++ b/.gitlab/ci/configure_windows_pellesc_common.cmake
@@ -0,0 +1,8 @@ +set(CMake_TEST_CXX OFF CACHE BOOL "") +set(CMake_TEST_Java OFF CACHE BOOL "") + +set(CMake_TEST_C_STANDARDS "90;99;11;17;23" CACHE STRING "") + +set(configure_no_sccache 1) + +include("${CMAKE_CURRENT_LIST_DIR}/configure_external_test.cmake")
diff --git a/.gitlab/ci/configure_windows_vs2019_x64_ninja.cmake b/.gitlab/ci/configure_windows_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..c4f6fd8 100644 --- a/.gitlab/ci/ctest_exclusions.cmake +++ b/.gitlab/ci/ctest_exclusions.cmake
@@ -27,6 +27,46 @@ ) 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() + +if ("$ENV{CMAKE_CONFIGURATION}" MATCHES [[windows_orangec7\.0\.7]]) + list(APPEND test_exclusions + # FIXME(OrangeC#1136): OrangeC 7 no longer fails when linking a missing library + "^RunCMake.CheckModules$" + ) +endif() + +if ("$ENV{CMAKE_CONFIGURATION}" MATCHES "windows_clang_fastbuild") + list(APPEND test_exclusions + # FIXME(#27697): These fail with clang-cl and FASTBuild. + "^BuildDepends$" + "^ExportImport$" + "^Module.CheckIPOSupported-C$" + "^RunCMake.PrecompileHeaders$" + "^RunCMake.PrecompileHeaders-Reuse$" + ) +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_fedora44.valgrind.supp b/.gitlab/ci/ctest_memcheck_fedora44.valgrind.supp new file mode 100644 index 0000000..acc1d2c --- /dev/null +++ b/.gitlab/ci/ctest_memcheck_fedora44.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_fedora44_asan.lsan.supp similarity index 100% rename from .gitlab/ci/ctest_memcheck_fedora42_asan.lsan.supp rename to .gitlab/ci/ctest_memcheck_fedora44_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/install_rvm.sh b/.gitlab/ci/docker/debian12-x86_64/install_rvm.sh deleted file mode 100755 index 1ad42c4..0000000 --- a/.gitlab/ci/docker/debian12-x86_64/install_rvm.sh +++ /dev/null
@@ -1,20 +0,0 @@ -#!/bin/sh - -set -e - -apt-get install -y $(grep '^[^#]\+$' /root/rvm_packages.lst) - -gpg2 --keyserver hkps://keyserver.ubuntu.com \ - --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 \ - 7D2BAF1CF37B13E2069D6956105BD0E739499BDB - -curl -sSL https://get.rvm.io | bash -s stable - -# keep version in sync with `env_debian*_ninja.sh` -/usr/local/rvm/bin/rvm install ruby-3.2.2 - -for p in archives examples gem-cache log src; do - touch /usr/local/rvm/${p}/.tar_exclude -done - -tar -C /usr/local --exclude-tag-under=.tar_exclude -cf /root/rvm.tar rvm
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/debian13-x86_64/install_rvm.sh b/.gitlab/ci/docker/debian13-x86_64/install_rvm.sh new file mode 100755 index 0000000..3e76005 --- /dev/null +++ b/.gitlab/ci/docker/debian13-x86_64/install_rvm.sh
@@ -0,0 +1,23 @@ +#!/bin/sh + +set -e + +apt-get install -y $(grep '^[^#]\+$' /root/rvm_packages.lst) + +gpg2 --keyserver hkps://keyserver.ubuntu.com \ + --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 \ + 7D2BAF1CF37B13E2069D6956105BD0E739499BDB + +curl -sSL https://raw.githubusercontent.com/rvm/rvm/stable/binscripts/rvm-installer -o rvm-installer && +curl -sSL https://raw.githubusercontent.com/rvm/rvm/stable/binscripts/rvm-installer.asc -o rvm-installer.asc && +gpg2 --verify rvm-installer.asc rvm-installer && +bash rvm-installer stable + +# keep version in sync with `env_debian*_ninja.sh` +/usr/local/rvm/bin/rvm install ruby-3.2.2 + +for p in archives examples gem-cache log src; do + touch /usr/local/rvm/${p}/.tar_exclude +done + +tar -C /usr/local --exclude-tag-under=.tar_exclude -cf /root/rvm.tar rvm
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-hip/deps_packages.lst b/.gitlab/ci/docker/fedora42-hip/deps_packages.lst deleted file mode 100644 index abae13a..0000000 --- a/.gitlab/ci/docker/fedora42-hip/deps_packages.lst +++ /dev/null
@@ -1,16 +0,0 @@ -# Install development tools. -clang -clang-tools-extra -compiler-rt -gcc-c++ -git-core -make - -# Install HIP language toolchain. -hsakmt-devel -lld -llvm -rocm-comgr-devel -rocm-hip-devel -rocm-runtime-devel -rocminfo
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_rbenv.sh b/.gitlab/ci/docker/fedora42/build_rbenv.sh deleted file mode 100755 index feb574f..0000000 --- a/.gitlab/ci/docker/fedora42/build_rbenv.sh +++ /dev/null
@@ -1,28 +0,0 @@ -#!/bin/sh - -set -e - -echo "gem: --no-document" > ~/.gemrc - -# Ruby rbenv -export RUBY_CONFIGURE_OPTS=--disable-install-doc -export RUBY_BUILD_CURL_OPTS=-C- -rbenv install 3.4.3 -k -s -v - -cat <<EOF >/tmp/exclude.lst -*LICENSE* -*/doc/* -*/man/* -*.md -BSDL -CONTRIBUTING.* -COPYING -LEGAL -PSFL -README.rdoc -History.rdoc -gem_make.out -test-unit-*/test -rss-*/test -EOF -tar -cf /root/rbenv.tar --exclude-from=/tmp/exclude.lst ${RBENV_ROOT}
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/build_rvm.sh b/.gitlab/ci/docker/fedora42/build_rvm.sh deleted file mode 100755 index 22c4333..0000000 --- a/.gitlab/ci/docker/fedora42/build_rvm.sh +++ /dev/null
@@ -1,41 +0,0 @@ -#!/bin/sh - -set -e - -echo "gem: --no-document" > ~/.gemrc - -gpg2 --keyserver hkps://keyserver.ubuntu.com \ - --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 \ - 7D2BAF1CF37B13E2069D6956105BD0E739499BDB - -curl -sSL https://get.rvm.io | bash -s stable --ignore-dotfiles - -export rvm_silence_banner=1 - -# keep version in sync with `env_fedora*_makefiles.cmake` -/usr/local/rvm/bin/rvm install ruby-3.3.8 --no-docs --disable-binary - -for p in archives docs examples gem-cache log src; do - touch /usr/local/rvm/${p}/.tar_exclude -done - -cat <<EOF >/tmp/exclude.lst -*LICENSE* -*/doc/* -*/man/* -*.md -BSDL -CONTRIBUTING.* -COPYING -LEGAL -PSFL -README.rdoc -History.rdoc -gem_make.out -test-unit-*/test -rss-*/test -EOF -tar -C /usr/local \ - --exclude-tag-under=.tar_exclude \ - --exclude-from=/tmp/exclude.lst \ - -cf /root/rvm.tar rvm
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/fedora42/rbenv_packages.lst b/.gitlab/ci/docker/fedora42/rbenv_packages.lst deleted file mode 100644 index d16afff..0000000 --- a/.gitlab/ci/docker/fedora42/rbenv_packages.lst +++ /dev/null
@@ -1,18 +0,0 @@ -rbenv -ruby-build-rbenv - -# Packages needed for `rbenv` -# https://github.com/rbenv/ruby-build/wiki#fedora -autoconf -bzip2 -gcc -gdbm-devel -libffi-devel -libyaml-devel -make -ncurses-devel -openssl-devel -patch -readline-devel -rust -zlib-devel
diff --git a/.gitlab/ci/docker/fedora44-hip/Dockerfile b/.gitlab/ci/docker/fedora44-hip/Dockerfile new file mode 100644 index 0000000..463d19f --- /dev/null +++ b/.gitlab/ci/docker/fedora44-hip/Dockerfile
@@ -0,0 +1,12 @@ +# syntax=docker/dockerfile:1 + +ARG BASE_IMAGE=fedora:44 + +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/fedora44-hip/deps_packages.lst b/.gitlab/ci/docker/fedora44-hip/deps_packages.lst new file mode 100644 index 0000000..bac9e53 --- /dev/null +++ b/.gitlab/ci/docker/fedora44-hip/deps_packages.lst
@@ -0,0 +1,15 @@ +# Install development tools. +clang +clang-tools-extra +compiler-rt +gcc-c++ +git-core +make + +# Install HIP language toolchain. +lld +llvm +rocm-comgr-devel +rocm-hip-devel +rocm-runtime-devel +rocminfo
diff --git a/.gitlab/ci/docker/fedora42-hip/dnf.conf b/.gitlab/ci/docker/fedora44-hip/dnf.conf similarity index 100% rename from .gitlab/ci/docker/fedora42-hip/dnf.conf rename to .gitlab/ci/docker/fedora44-hip/dnf.conf
diff --git a/.gitlab/ci/docker/fedora44/Dockerfile b/.gitlab/ci/docker/fedora44/Dockerfile new file mode 100644 index 0000000..d36ccc9 --- /dev/null +++ b/.gitlab/ci/docker/fedora44/Dockerfile
@@ -0,0 +1,135 @@ +# syntax=docker/dockerfile:1 + +ARG BASE_IMAGE=fedora:44 + +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.9
diff --git a/.gitlab/ci/docker/fedora42/build_iwyu.sh b/.gitlab/ci/docker/fedora44/build_iwyu.sh similarity index 100% rename from .gitlab/ci/docker/fedora42/build_iwyu.sh rename to .gitlab/ci/docker/fedora44/build_iwyu.sh
diff --git a/.gitlab/ci/docker/fedora44/build_rbenv.sh b/.gitlab/ci/docker/fedora44/build_rbenv.sh new file mode 100755 index 0000000..f5ddd06 --- /dev/null +++ b/.gitlab/ci/docker/fedora44/build_rbenv.sh
@@ -0,0 +1,28 @@ +#!/bin/sh + +set -e + +echo "gem: --no-document" > ~/.gemrc + +# Ruby rbenv +export RUBY_CONFIGURE_OPTS=--disable-install-doc +export RUBY_BUILD_CURL_OPTS=-C- +rbenv install 3.4.9 -k -s -v + +cat <<EOF >/tmp/exclude.lst +*LICENSE* +*/doc/* +*/man/* +*.md +BSDL +CONTRIBUTING.* +COPYING +LEGAL +PSFL +README.rdoc +History.rdoc +gem_make.out +test-unit-*/test +rss-*/test +EOF +tar -cf /root/rbenv.tar --exclude-from=/tmp/exclude.lst ${RBENV_ROOT}
diff --git a/.gitlab/ci/docker/fedora44/build_rust.sh b/.gitlab/ci/docker/fedora44/build_rust.sh new file mode 100755 index 0000000..1ee87eb --- /dev/null +++ b/.gitlab/ci/docker/fedora44/build_rust.sh
@@ -0,0 +1,10 @@ +#!/bin/sh + +set -e + +typos_version=1.45.2 +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/fedora44/build_rvm.sh b/.gitlab/ci/docker/fedora44/build_rvm.sh new file mode 100755 index 0000000..9da34fe --- /dev/null +++ b/.gitlab/ci/docker/fedora44/build_rvm.sh
@@ -0,0 +1,44 @@ +#!/bin/sh + +set -e + +echo "gem: --no-document" > ~/.gemrc + +gpg2 --keyserver hkps://keyserver.ubuntu.com \ + --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 \ + 7D2BAF1CF37B13E2069D6956105BD0E739499BDB + +curl -sSL https://raw.githubusercontent.com/rvm/rvm/stable/binscripts/rvm-installer -o rvm-installer && +curl -sSL https://raw.githubusercontent.com/rvm/rvm/stable/binscripts/rvm-installer.asc -o rvm-installer.asc && +gpg2 --verify rvm-installer.asc rvm-installer && +bash rvm-installer stable --ignore-dotfiles + +export rvm_silence_banner=1 + +# keep version in sync with `env_fedora*_makefiles.cmake` +/usr/local/rvm/bin/rvm install ruby-3.3.8 --no-docs --disable-binary + +for p in archives docs examples gem-cache log src; do + touch /usr/local/rvm/${p}/.tar_exclude +done + +cat <<EOF >/tmp/exclude.lst +*LICENSE* +*/doc/* +*/man/* +*.md +BSDL +CONTRIBUTING.* +COPYING +LEGAL +PSFL +README.rdoc +History.rdoc +gem_make.out +test-unit-*/test +rss-*/test +EOF +tar -C /usr/local \ + --exclude-tag-under=.tar_exclude \ + --exclude-from=/tmp/exclude.lst \ + -cf /root/rvm.tar rvm
diff --git a/.gitlab/ci/docker/fedora44/deps_packages.lst b/.gitlab/ci/docker/fedora44/deps_packages.lst new file mode 100644 index 0000000..b763bb7 --- /dev/null +++ b/.gitlab/ci/docker/fedora44/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-25-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/fedora44/dnf.conf similarity index 100% rename from .gitlab/ci/docker/fedora42/dnf.conf rename to .gitlab/ci/docker/fedora44/dnf.conf
diff --git a/.gitlab/ci/docker/fedora44/install_deps.sh b/.gitlab/ci/docker/fedora44/install_deps.sh new file mode 100755 index 0000000..cc3480a --- /dev/null +++ b/.gitlab/ci/docker/fedora44/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/fedora44/iwyu_packages.lst similarity index 100% rename from .gitlab/ci/docker/fedora42/iwyu_packages.lst rename to .gitlab/ci/docker/fedora44/iwyu_packages.lst
diff --git a/.gitlab/ci/docker/fedora44/rbenv_packages.lst b/.gitlab/ci/docker/fedora44/rbenv_packages.lst new file mode 100644 index 0000000..7cba990 --- /dev/null +++ b/.gitlab/ci/docker/fedora44/rbenv_packages.lst
@@ -0,0 +1,19 @@ +rbenv +ruby-build-rbenv +ruby-build-ruby + +# Packages needed for `rbenv` +# https://github.com/rbenv/ruby-build/wiki#fedora +autoconf +bzip2 +gcc +gdbm-devel +libffi-devel +libyaml-devel +make +ncurses-devel +openssl-devel +patch +readline-devel +rust +zlib-devel
diff --git a/.gitlab/ci/docker/fedora42/rust_packages.lst b/.gitlab/ci/docker/fedora44/rust_packages.lst similarity index 100% rename from .gitlab/ci/docker/fedora42/rust_packages.lst rename to .gitlab/ci/docker/fedora44/rust_packages.lst
diff --git a/.gitlab/ci/docker/fedora42/rvm_packages.lst b/.gitlab/ci/docker/fedora44/rvm_packages.lst similarity index 100% rename from .gitlab/ci/docker/fedora42/rvm_packages.lst rename to .gitlab/ci/docker/fedora44/rvm_packages.lst
diff --git a/.gitlab/ci/docker/gcc_cxx_modules/Dockerfile b/.gitlab/ci/docker/gcc_cxx_modules/Dockerfile deleted file mode 100644 index 7f6e297..0000000 --- a/.gitlab/ci/docker/gcc_cxx_modules/Dockerfile +++ /dev/null
@@ -1,9 +0,0 @@ -FROM fedora:41 -MAINTAINER Ben Boeckel <ben.boeckel@kitware.com> - -# Install build dependencies for packages. -COPY install_deps.sh /root/install_deps.sh -RUN sh /root/install_deps.sh - -COPY install_gcc.sh /root/install_gcc.sh -RUN sh /root/install_gcc.sh
diff --git a/.gitlab/ci/docker/gcc_cxx_modules/install_deps.sh b/.gitlab/ci/docker/gcc_cxx_modules/install_deps.sh deleted file mode 100755 index b8b706b..0000000 --- a/.gitlab/ci/docker/gcc_cxx_modules/install_deps.sh +++ /dev/null
@@ -1,7 +0,0 @@ -#!/bin/sh - -set -e - -dnf install -y --setopt=install_weak_deps=False \ - gcc-c++ mpfr-devel libmpc-devel isl-devel flex bison file findutils diffutils git-core -dnf clean all
diff --git a/.gitlab/ci/docker/gcc_cxx_modules/install_gcc.sh b/.gitlab/ci/docker/gcc_cxx_modules/install_gcc.sh deleted file mode 100755 index 32cb9ec..0000000 --- a/.gitlab/ci/docker/gcc_cxx_modules/install_gcc.sh +++ /dev/null
@@ -1,25 +0,0 @@ -#!/bin/sh - -set -e - -readonly revision="10e702789eeabcc88451e34c2a5c7dccb96190a5" # master as of 21 Nov 2024 -readonly tarball="git://gcc.gnu.org/git/gcc.git" - -readonly workdir="$HOME/gcc" -readonly srcdir="$workdir/gcc" -readonly builddir="$workdir/build" -readonly njobs="$( nproc )" - -mkdir -p "$workdir" -cd "$workdir" -git clone "$tarball" "$srcdir" -git -C "$srcdir" checkout "$revision" -mkdir -p "$builddir" -cd "$builddir" -"$srcdir/configure" \ - --disable-multilib \ - --enable-languages=c,c++ \ - --prefix="/opt/gcc-importstd" -make "-j$njobs" -make "-j$njobs" install-strip -rm -rf "$workdir"
diff --git a/.gitlab/ci/docker/nvhpc24.9/Dockerfile b/.gitlab/ci/docker/nvhpc24.9/Dockerfile deleted file mode 100644 index b94b14a..0000000 --- a/.gitlab/ci/docker/nvhpc24.9/Dockerfile +++ /dev/null
@@ -1,6 +0,0 @@ -# https://catalog.ngc.nvidia.com/orgs/nvidia/containers/nvhpc/tags -FROM kitware/nvidia-nvhpc:24.9-devel-cuda_multi-ubuntu24.04 -MAINTAINER Brad King <brad.king@kitware.com> - -COPY install_deps.sh /root/install_deps.sh -RUN sh /root/install_deps.sh
diff --git a/.gitlab/ci/docker/nvhpc26.3/Dockerfile b/.gitlab/ci/docker/nvhpc26.3/Dockerfile new file mode 100644 index 0000000..14b9bca --- /dev/null +++ b/.gitlab/ci/docker/nvhpc26.3/Dockerfile
@@ -0,0 +1,6 @@ +# https://catalog.ngc.nvidia.com/orgs/nvidia/containers/nvhpc/tags +FROM kitware/nvidia-nvhpc:26.3-devel-cuda_multi-ubuntu24.04 +MAINTAINER Brad King <brad.king@kitware.com> + +COPY install_deps.sh /root/install_deps.sh +RUN sh /root/install_deps.sh
diff --git a/.gitlab/ci/docker/nvhpc24.9/install_deps.sh b/.gitlab/ci/docker/nvhpc26.3/install_deps.sh similarity index 100% rename from .gitlab/ci/docker/nvhpc24.9/install_deps.sh rename to .gitlab/ci/docker/nvhpc26.3/install_deps.sh
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_fedora44_asan.sh similarity index 100% rename from .gitlab/ci/env_fedora42_asan.sh rename to .gitlab/ci/env_fedora44_asan.sh
diff --git a/.gitlab/ci/env_fedora44_bullseye_coverage.sh b/.gitlab/ci/env_fedora44_bullseye_coverage.sh new file mode 100644 index 0000000..57f92ab --- /dev/null +++ b/.gitlab/ci/env_fedora44_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_fedora44_clang_analyzer.sh similarity index 100% rename from .gitlab/ci/env_fedora42_clang_analyzer.sh rename to .gitlab/ci/env_fedora44_clang_analyzer.sh
diff --git a/.gitlab/ci/env_fedora44_clang_fuzzing.sh b/.gitlab/ci/env_fedora44_clang_fuzzing.sh new file mode 100644 index 0000000..729fb37 --- /dev/null +++ b/.gitlab/ci/env_fedora44_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_fedora44_clazy.sh b/.gitlab/ci/env_fedora44_clazy.sh new file mode 100644 index 0000000..007c52d --- /dev/null +++ b/.gitlab/ci/env_fedora44_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_fedora44_common_clang.sh b/.gitlab/ci/env_fedora44_common_clang.sh new file mode 100644 index 0000000..2200841 --- /dev/null +++ b/.gitlab/ci/env_fedora44_common_clang.sh
@@ -0,0 +1,3 @@ +export CC=/usr/bin/clang +export CXX=/usr/bin/clang++ +export FC=/usr/bin/flang
diff --git a/.gitlab/ci/env_fedora42_common_lfortran.sh b/.gitlab/ci/env_fedora44_common_lfortran.sh similarity index 100% rename from .gitlab/ci/env_fedora42_common_lfortran.sh rename to .gitlab/ci/env_fedora44_common_lfortran.sh
diff --git a/.gitlab/ci/env_debian12_extdeps.sh b/.gitlab/ci/env_fedora44_extdeps.sh similarity index 100% copy from .gitlab/ci/env_debian12_extdeps.sh copy to .gitlab/ci/env_fedora44_extdeps.sh
diff --git a/.gitlab/ci/env_fedora44_fastbuild.sh b/.gitlab/ci/env_fedora44_fastbuild.sh new file mode 100644 index 0000000..5e8b2df --- /dev/null +++ b/.gitlab/ci/env_fedora44_fastbuild.sh
@@ -0,0 +1 @@ +source .gitlab/ci/fastbuild-env.sh
diff --git a/.gitlab/ci/env_fedora44_hip_radeon.patch b/.gitlab/ci/env_fedora44_hip_radeon.patch new file mode 100644 index 0000000..a6411ed --- /dev/null +++ b/.gitlab/ci/env_fedora44_hip_radeon.patch
@@ -0,0 +1,14 @@ +--- a/usr/lib/clang/22/include/cuda_wrappers/new ++++ b/usr/lib/clang/22/include/cuda_wrappers/new +@@ -98,9 +98,9 @@ + __device__ inline void *operator new[](__SIZE_TYPE__, void *__ptr) CUDA_NOEXCEPT { + return __ptr; + } +-#endif + __device__ inline void operator delete(void *, void *) CUDA_NOEXCEPT {} + __device__ inline void operator delete[](void *, void *) CUDA_NOEXCEPT {} ++#endif + + #pragma pop_macro("CUDA_NOEXCEPT") + +---
diff --git a/.gitlab/ci/env_fedora44_hip_radeon.sh b/.gitlab/ci/env_fedora44_hip_radeon.sh new file mode 100644 index 0000000..dfa0121 --- /dev/null +++ b/.gitlab/ci/env_fedora44_hip_radeon.sh
@@ -0,0 +1,4 @@ +export HIPCXX=/usr/bin/clang++ +export HIPFLAGS='--rocm-path=/usr --rocm-device-lib-path=/usr/lib64/rocm/llvm/lib/clang/20/lib/amdgcn/bitcode' + +git apply --unsafe-paths --directory=/ .gitlab/ci/env_fedora44_hip_radeon.patch
diff --git a/.gitlab/ci/env_fedora42_makefiles.cmake b/.gitlab/ci/env_fedora44_makefiles.cmake similarity index 100% rename from .gitlab/ci/env_fedora42_makefiles.cmake rename to .gitlab/ci/env_fedora44_makefiles.cmake
diff --git a/.gitlab/ci/env_fedora44_makefiles.sh b/.gitlab/ci/env_fedora44_makefiles.sh new file mode 100644 index 0000000..f02e487 --- /dev/null +++ b/.gitlab/ci/env_fedora44_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_fedora44_makefiles_clang.sh b/.gitlab/ci/env_fedora44_makefiles_clang.sh new file mode 100644 index 0000000..4d2ba81 --- /dev/null +++ b/.gitlab/ci/env_fedora44_makefiles_clang.sh
@@ -0,0 +1 @@ +. .gitlab/ci/env_fedora44_common_clang.sh
diff --git a/.gitlab/ci/env_fedora44_makefiles_lfortran.sh b/.gitlab/ci/env_fedora44_makefiles_lfortran.sh new file mode 100644 index 0000000..409404e --- /dev/null +++ b/.gitlab/ci/env_fedora44_makefiles_lfortran.sh
@@ -0,0 +1 @@ +. .gitlab/ci/env_fedora44_common_lfortran.sh
diff --git a/.gitlab/ci/env_fedora44_makefiles_symlinked.cmake b/.gitlab/ci/env_fedora44_makefiles_symlinked.cmake new file mode 100644 index 0000000..8c39210 --- /dev/null +++ b/.gitlab/ci/env_fedora44_makefiles_symlinked.cmake
@@ -0,0 +1 @@ +include("${CMAKE_CURRENT_LIST_DIR}/env_fedora44_makefiles.cmake")
diff --git a/.gitlab/ci/env_fedora44_makefiles_symlinked.sh b/.gitlab/ci/env_fedora44_makefiles_symlinked.sh new file mode 100644 index 0000000..84a747c --- /dev/null +++ b/.gitlab/ci/env_fedora44_makefiles_symlinked.sh
@@ -0,0 +1 @@ +. .gitlab/ci/env_fedora44_makefiles.sh
diff --git a/.gitlab/ci/env_fedora44_ninja.sh b/.gitlab/ci/env_fedora44_ninja.sh new file mode 100644 index 0000000..3607fb1 --- /dev/null +++ b/.gitlab/ci/env_fedora44_ninja.sh
@@ -0,0 +1,14 @@ +if test "$CMAKE_CI_NIGHTLY" = "true"; then + source .gitlab/ci/appimagetool-env.sh + source .gitlab/ci/ispc-env.sh +fi + +# This job builds CMake as C++11. Prevent C++17 headers from being used. +if test "$CMAKE_CONFIGURATION" = "fedora44_ninja" -a "$CI_JOB_STAGE" = "build"; then + for i in filesystem optional string_view; do + sed -i -e '$a#error "Use <cm/'"$i"'> instead"' "/usr/include/c++/16/$i" + done +fi + +# Test in a UTF-8 locale. +export LANG=en_US.UTF-8
diff --git a/.gitlab/ci/env_fedora44_ninja_clang.sh b/.gitlab/ci/env_fedora44_ninja_clang.sh new file mode 100644 index 0000000..4d2ba81 --- /dev/null +++ b/.gitlab/ci/env_fedora44_ninja_clang.sh
@@ -0,0 +1 @@ +. .gitlab/ci/env_fedora44_common_clang.sh
diff --git a/.gitlab/ci/env_fedora44_ninja_gcc_std_reloc.sh b/.gitlab/ci/env_fedora44_ninja_gcc_std_reloc.sh new file mode 100644 index 0000000..ae640b7 --- /dev/null +++ b/.gitlab/ci/env_fedora44_ninja_gcc_std_reloc.sh
@@ -0,0 +1,7 @@ +# "Misplace" the `libstdc++.modules.json` file so that +# `CMAKE_CXX_STDLIB_MODULES_JSON` is needed to use `import std`. +stdlib_modules_dir="/usr/lib/gcc/x86_64-redhat-linux/16" +mkdir "$stdlib_modules_dir.reloc" +mv "$stdlib_modules_dir/libstdc++.modules.json" "$stdlib_modules_dir.reloc" +export CMAKE_CI_CXX_STDLIB_MODULES_JSON="$stdlib_modules_dir.reloc/libstdc++.modules.json" +unset stdlib_modules_dir
diff --git a/.gitlab/ci/env_fedora44_ninja_instrumentation.sh b/.gitlab/ci/env_fedora44_ninja_instrumentation.sh new file mode 100644 index 0000000..99f7538 --- /dev/null +++ b/.gitlab/ci/env_fedora44_ninja_instrumentation.sh
@@ -0,0 +1 @@ +source .gitlab/ci/env_fedora44_ninja.sh
diff --git a/.gitlab/ci/env_fedora44_ninja_lfortran.sh b/.gitlab/ci/env_fedora44_ninja_lfortran.sh new file mode 100644 index 0000000..409404e --- /dev/null +++ b/.gitlab/ci/env_fedora44_ninja_lfortran.sh
@@ -0,0 +1 @@ +. .gitlab/ci/env_fedora44_common_lfortran.sh
diff --git a/.gitlab/ci/env_fedora42_ninja_multi.sh b/.gitlab/ci/env_fedora44_ninja_multi.sh similarity index 100% rename from .gitlab/ci/env_fedora42_ninja_multi.sh rename to .gitlab/ci/env_fedora44_ninja_multi.sh
diff --git a/.gitlab/ci/env_fedora44_ninja_multi_clang.sh b/.gitlab/ci/env_fedora44_ninja_multi_clang.sh new file mode 100644 index 0000000..4d2ba81 --- /dev/null +++ b/.gitlab/ci/env_fedora44_ninja_multi_clang.sh
@@ -0,0 +1 @@ +. .gitlab/ci/env_fedora44_common_clang.sh
diff --git a/.gitlab/ci/env_fedora44_ninja_valgrind.sh b/.gitlab/ci/env_fedora44_ninja_valgrind.sh new file mode 100644 index 0000000..99f7538 --- /dev/null +++ b/.gitlab/ci/env_fedora44_ninja_valgrind.sh
@@ -0,0 +1 @@ +source .gitlab/ci/env_fedora44_ninja.sh
diff --git a/.gitlab/ci/env_fedora44_pvs_studio.sh b/.gitlab/ci/env_fedora44_pvs_studio.sh new file mode 100644 index 0000000..36dba85 --- /dev/null +++ b/.gitlab/ci/env_fedora44_pvs_studio.sh
@@ -0,0 +1 @@ +. .gitlab/ci/pvs-studio-env.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_clang_fastbuild.ps1 b/.gitlab/ci/env_windows_clang_fastbuild.ps1 new file mode 100644 index 0000000..e6c1235 --- /dev/null +++ b/.gitlab/ci/env_windows_clang_fastbuild.ps1
@@ -0,0 +1,2 @@ +. .gitlab/ci/fastbuild-env.ps1 +. .gitlab/ci/clang-env.ps1
diff --git a/.gitlab/ci/env_windows_orangec6.73.1.ps1 b/.gitlab/ci/env_windows_orangec6.73.8.ps1 similarity index 100% rename from .gitlab/ci/env_windows_orangec6.73.1.ps1 rename to .gitlab/ci/env_windows_orangec6.73.8.ps1
diff --git a/.gitlab/ci/env_windows_orangec6.73.1.ps1 b/.gitlab/ci/env_windows_orangec7.0.7.ps1 similarity index 100% copy from .gitlab/ci/env_windows_orangec6.73.1.ps1 copy to .gitlab/ci/env_windows_orangec7.0.7.ps1
diff --git a/.gitlab/ci/env_windows_pellesc13.01.ps1 b/.gitlab/ci/env_windows_pellesc13.01.ps1 new file mode 100644 index 0000000..84a38ac --- /dev/null +++ b/.gitlab/ci/env_windows_pellesc13.01.ps1
@@ -0,0 +1,2 @@ +. .gitlab/ci/ninja-env.ps1 +. .gitlab/ci/pellesc-env.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/orangec.ps1 b/.gitlab/ci/orangec.ps1 index 2201e12..0216fff 100644 --- a/.gitlab/ci/orangec.ps1 +++ b/.gitlab/ci/orangec.ps1
@@ -1,9 +1,14 @@ $erroractionpreference = "stop" -if ("$env:CMAKE_CONFIGURATION".Contains("orangec6.73.1")) { - # OrangeC 6.73.1 +if ("$env:CMAKE_CONFIGURATION".Contains("orangec7.0.7")) { + # OrangeC 7.0.7 + $archive = "ZippedBinaries707.zip" + $release = "v7.0.7" + $sha256sum = "853DDE0F4819E65E3EC8F94F67C88C07062F3736BF534D2834FDEFCCE3A0B598" +} elseif ("$env:CMAKE_CONFIGURATION".Contains("orangec6.73.8")) { + # OrangeC 6.73.8 $archive = "ZippedBinaries6738.zip" - $release = "Orange-C-v6.73.1" + $release = "Orange-C-v6.73.1" # release numbering seems mismatched $sha256sum = "29BC506AB105B2BF1002129C37826B2153DF1C8D0F22B9A2C38ACA3FB72A5B89" } else { throw ('unknown CMAKE_CONFIGURATION: ' + "$env:CMAKE_CONFIGURATION")
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/pellesc-env.ps1 b/.gitlab/ci/pellesc-env.ps1 new file mode 100644 index 0000000..23b8a62 --- /dev/null +++ b/.gitlab/ci/pellesc-env.ps1
@@ -0,0 +1,6 @@ +& "$pwsh" -File ".gitlab/ci/pellesc.ps1" +Invoke-Expression -Command .gitlab/ci/pellesc-vars.ps1 + +$env:CC = "pocc" +$env:CXX = "pocc-does-not-support-c++" +pocc | Select -First 1
diff --git a/.gitlab/ci/pellesc-vars.ps1 b/.gitlab/ci/pellesc-vars.ps1 new file mode 100644 index 0000000..457ddb1 --- /dev/null +++ b/.gitlab/ci/pellesc-vars.ps1
@@ -0,0 +1,7 @@ +$erroractionpreference = "stop" + +$all_env = cmd /c "`".gitlab\pellesc\bin\povars64.bat`" >NUL & powershell -Command `"Get-ChildItem env: | Select-Object -Property Key,Value | ConvertTo-Json`"" | ConvertFrom-Json + +foreach ($envvar in $all_env) { + [Environment]::SetEnvironmentVariable($envvar.Key, $envvar.Value) +}
diff --git a/.gitlab/ci/pellesc.ps1 b/.gitlab/ci/pellesc.ps1 new file mode 100644 index 0000000..0caacb2 --- /dev/null +++ b/.gitlab/ci/pellesc.ps1
@@ -0,0 +1,33 @@ +$erroractionpreference = "stop" + +if ("$env:CMAKE_CONFIGURATION".Contains("pellesc13.01")) { + # PellesC 13.01 + # https://www.pellesc.se/1300/setup.exe + $filename = "pellesc-13.01-1" + $sha256sum = "E48AF208D1A46F47490011979538C1DBC427B36D47554A76C3FF83284E8F83AE" +} else { + throw ('unknown CMAKE_CONFIGURATION: ' + "$env:CMAKE_CONFIGURATION") +} +$archive = "$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/$archive" -OutFile "$outdir\$archive" +$hash = Get-FileHash "$outdir\$archive" -Algorithm SHA256 +if ($hash.Hash -ne $sha256sum) { + exit 1 +} + +Add-Type -AssemblyName System.IO.Compression.FileSystem +[System.IO.Compression.ZipFile]::ExtractToDirectory("$outdir\$archive", "$outdir") +Move-Item -Path "$outdir\$filename" -Destination "$outdir\pellesc" +Remove-Item "$outdir\$archive" + +$scripts = "povars32.bat", "povars64.bat" +foreach ($script in $scripts) { + $bat = Get-Content -Path "$outdir\pellesc\bin\$script.in" -Raw + $bat = $bat -Replace "@PellesCDir@","$outdir\pellesc" + $bat | Set-Content -Path "$outdir\pellesc\bin\$script" +}
diff --git a/.gitlab/ci/post_build_fedora42_tidy.sh b/.gitlab/ci/post_build_fedora44_tidy.sh similarity index 100% rename from .gitlab/ci/post_build_fedora42_tidy.sh rename to .gitlab/ci/post_build_fedora44_tidy.sh
diff --git a/.gitlab/ci/pre_build_fedora44_bullseye_coverage.sh b/.gitlab/ci/pre_build_fedora44_bullseye_coverage.sh new file mode 100644 index 0000000..ab78d8f --- /dev/null +++ b/.gitlab/ci/pre_build_fedora44_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_fedora44_bullseye_coverage.sh b/.gitlab/ci/pre_configure_fedora44_bullseye_coverage.sh new file mode 100644 index 0000000..ec54ff2 --- /dev/null +++ b/.gitlab/ci/pre_configure_fedora44_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_fedora44_tidy.sh similarity index 100% rename from .gitlab/ci/pre_build_fedora42_tidy.sh rename to .gitlab/ci/pre_configure_fedora44_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_fedora44_bullseye_coverage.sh b/.gitlab/ci/pre_test_fedora44_bullseye_coverage.sh new file mode 100644 index 0000000..4e892d2 --- /dev/null +++ b/.gitlab/ci/pre_test_fedora44_bullseye_coverage.sh
@@ -0,0 +1,2 @@ +# Turn on Bullseye coverage for test step. +cov01 --on
diff --git a/.gitlab/ci/pvs-studio-env.sh b/.gitlab/ci/pvs-studio-env.sh new file mode 100644 index 0000000..c179b30 --- /dev/null +++ b/.gitlab/ci/pvs-studio-env.sh
@@ -0,0 +1,13 @@ +.gitlab/ci/pvs-studio.sh +export PATH=$PWD/.gitlab/pvs-studio/bin:$PATH +pvs-studio --version + +if test -f "$CMAKE_CI_PVS_STUDIO_LICENSE_USER" -a -f "$CMAKE_CI_PVS_STUDIO_LICENSE_KEY"; then + pvs-studio-analyzer credentials "$(<"$CMAKE_CI_PVS_STUDIO_LICENSE_USER")" "$(<"$CMAKE_CI_PVS_STUDIO_LICENSE_KEY")" +else + echo "The CMAKE_CI_PVS_STUDIO_LICENSE_USER and CMAKE_CI_PVS_STUDIO_LICENSE_KEY files were not both provided!" + exit 1 +fi +rm -f "$CMAKE_CI_PVS_STUDIO_LICENSE_USER" "$CMAKE_CI_PVS_STUDIO_LICENSE_KEY" +unset CMAKE_CI_PVS_STUDIO_LICENSE_KEY +unset CMAKE_CI_PVS_STUDIO_LICENSE_USER
diff --git a/.gitlab/ci/pvs-studio.sh b/.gitlab/ci/pvs-studio.sh new file mode 100755 index 0000000..b0eddf3 --- /dev/null +++ b/.gitlab/ci/pvs-studio.sh
@@ -0,0 +1,33 @@ +#!/bin/sh + +set -e + +readonly version="7.42.105112.761" + +case "$(uname -s)-$(uname -m)" in + Linux-x86_64) + # https://files.pvs-studio.com/pvs-studio-7.42.105112.761-x86_64.tgz + shatool="sha256sum" + sha256sum="0ced11d17855cc172a860f8cc19a89f10adb6ab7185992fb57474118e9bdabd7" + filename="pvs-studio-$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.tgz" +echo "$sha256sum $tarball" > pvs-studio.sha256sum +curl -OL "$baseurl/$tarball" +$shatool --check pvs-studio.sha256sum +tar xzf "$tarball" +rm "$tarball" pvs-studio.sha256sum +mv "$filename" "pvs-studio"
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/repackage/pellesc.ps1 b/.gitlab/ci/repackage/pellesc.ps1 new file mode 100644 index 0000000..0d10129 --- /dev/null +++ b/.gitlab/ci/repackage/pellesc.ps1
@@ -0,0 +1,74 @@ +# Pelles C compilers are available only via installers. +# Run an installer and repackage the installation directory. + +# From the Pelles C download page, download "setup.exe". +# Run this script passing "setup.exe" followed by the version number. + +#Requires -RunAsAdministrator + +param ( + [Parameter(Mandatory=$true)] + [string]$installer, + [Parameter(Mandatory=$true)] + [string]$version, + [string]$revision = "1", + [string]$basedir = "c:\PellesC" + ) + +$erroractionpreference = "stop" + +Add-Type -AssemblyName System.IO.Compression.FileSystem + +$installer_file = Get-Item $installer +$installer_name = $installer_file.Name +$package_name = "pellesc-$version-$revision" +$package_dir = New-Item -Force -ItemType Directory -Path "$basedir\$package_name" +if (-not $package_dir) { + Write-Host "Failed to create package install dir." + Exit 1 +} + +Write-Host "Installing to: $package_dir" + +# The installer treats everything after /D= as the destination. +# Start-Process adds a trailing space, so use "cmd" instead. +& "$env:ComSpec" /c start /wait "$installer_file" /S /D=$package_dir +Write-Host "" +Remove-Item "$package_dir/uninst.exe" -Force + +# Convert environment scripts to templates. +$bats = @( + "bin\povars32.bat" + "bin\povars64.bat" + ) +foreach ($p in $bats) { + $bat = Get-Content -Path "$package_dir\$p" -Raw + $bat = $bat -Replace "PellesCDir=.*","PellesCDir=@PellesCDir@" + $bat | Set-Content -Path "$package_dir\$p.in" + Remove-Item "$package_dir\$p" -Force +} + +@" +This was repackaged from an installation by + + Pelles C $version "$installer_name" + +using CMake's ".gitlab/ci/repackage/pellesc.ps1" script. + +Copy or rename the environment script templates in the "bin" directory: + + povars32.bat.in => povars32.bat + povars64.bat.in => povars64.bat + +and replace the "@PellesCDir@" placeholders with + + C:\path\to\this\directory + +Then use "povars32.bat" or "povars64.bat" to establish an environment. + +"@ | Add-Content -NoNewline "$package_dir/README.txt" + +Write-Host "Repackaging to: $package_name.zip" +$compressionLevel = [System.IO.Compression.CompressionLevel]::Optimal +$includeBaseDirectory = $true +[System.IO.Compression.ZipFile]::CreateFromDirectory("$package_dir", "$package_name.zip", $compressionLevel, $includeBaseDirectory)
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..96fed40 100644 --- a/.gitlab/os-linux.yml +++ b/.gitlab/os-linux.yml
@@ -5,13 +5,13 @@ ### Release .linux_prep_source: - image: "fedora:42" + image: "fedora:44" 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-04-28" 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,276 @@ ### Fedora -.fedora42: - image: "kitware/cmake:ci-fedora42-x86_64-2025-04-22" +.fedora44: + image: "kitware/cmake:ci-fedora44-x86_64-2026-04-30" 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" +.fedora44_hip: + image: "kitware/cmake:ci-fedora44-hip-x86_64-2026-04-30" 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 +.fedora44_gcc_gcov: + extends: .fedora44 variables: - CMAKE_CONFIGURATION: fedora42_tidy + # See issue #20001 + CMAKE_GENERATOR: "Unix Makefiles" + CMAKE_CONFIGURATION: fedora44_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 +.fedora44_bullseye_coverage: + extends: .fedora44 + environment: + name: bullseye-coverage + variables: + # See issue #20001 + CMAKE_GENERATOR: "Unix Makefiles" + CMAKE_CONFIGURATION: fedora44_bullseye_coverage + CTEST_NO_WARNINGS_ALLOWED: 1 + CMAKE_CI_BUILD_TYPE: Debug + CMAKE_CI_TEST_TIMEOUT: "1500" + CMAKE_CI_NO_INSTALL: 1 + +#### Lint builds + +.fedora44_tidy: + extends: .fedora44 variables: - CMAKE_CONFIGURATION: fedora42_clang_analyzer + CMAKE_CONFIGURATION: fedora44_tidy + CMAKE_CI_NO_INSTALL: 1 + +.fedora44_pvs_studio: + extends: .fedora44 + environment: + name: pvs-studio + variables: + CMAKE_CONFIGURATION: fedora44_pvs_studio + CMAKE_CI_NO_INSTALL: 1 + +.fedora44_clang_analyzer: + extends: .fedora44 + + variables: + CMAKE_CONFIGURATION: fedora44_clang_analyzer CMAKE_CI_BUILD_TYPE: Debug CTEST_NO_WARNINGS_ALLOWED: 1 CMAKE_CI_NO_INSTALL: 1 -.fedora42_sphinx: - extends: .fedora42 +.fedora44_clang_fuzzing: + extends: .fedora44 variables: - CMAKE_CONFIGURATION: fedora42_sphinx + CMAKE_CONFIGURATION: fedora44_clang_fuzzing + CTEST_NO_WARNINGS_ALLOWED: 1 + CMAKE_CI_NO_INSTALL: 1 + +.fedora44_clazy: + extends: .fedora44 + + variables: + CMAKE_CONFIGURATION: fedora44_clazy + CMAKE_CI_BUILD_TYPE: Debug + CTEST_NO_WARNINGS_ALLOWED: 1 + CMAKE_CI_NO_INSTALL: 1 + +.fedora44_sphinx: + extends: .fedora44 + + variables: + CMAKE_CONFIGURATION: fedora44_sphinx CTEST_NO_WARNINGS_ALLOWED: 1 CTEST_SOURCE_SUBDIRECTORY: "Utilities/Sphinx" CMAKE_CI_NO_INSTALL: 1 -.fedora42_sphinx_package: - extends: .fedora42 +.fedora44_sphinx_package: + extends: .fedora44 variables: - CMAKE_CONFIGURATION: fedora42_sphinx_package + CMAKE_CONFIGURATION: fedora44_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 +.fedora44_extdeps: + extends: .fedora44 variables: - CMAKE_CONFIGURATION: fedora42_extdeps + CMAKE_CONFIGURATION: fedora44_extdeps CMAKE_CI_BUILD_TYPE: Release CTEST_NO_WARNINGS_ALLOWED: 1 -.fedora42_ninja: - extends: .fedora42 +.fedora44_ninja: + extends: .fedora44 variables: - CMAKE_CONFIGURATION: fedora42_ninja + CMAKE_CONFIGURATION: fedora44_ninja CMAKE_CI_BUILD_TYPE: Release CTEST_NO_WARNINGS_ALLOWED: 1 -.fedora42_ninja_multi: - extends: .fedora42 +.fedora44_makefiles: + extends: .fedora44 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: fedora44_makefiles CTEST_NO_WARNINGS_ALLOWED: 1 CMAKE_GENERATOR: "Unix Makefiles" -.fedora42_makefiles_symlinked: - extends: .fedora42 +.fedora44_makefiles_symlinked: + extends: .fedora44 variables: - CMAKE_CONFIGURATION: fedora42_makefiles_symlinked + CMAKE_CONFIGURATION: fedora44_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" +.fedora44_fastbuild: + extends: .fedora44 + + variables: + CMAKE_CONFIGURATION: fedora44_fastbuild + CTEST_NO_WARNINGS_ALLOWED: 1 + CMAKE_GENERATOR: "FASTBuild" + +.fedora44_ninja_instrumentation: + extends: .fedora44 + + variables: + CMAKE_CONFIGURATION: fedora44_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 +.fedora44_makefiles_clang: + extends: .fedora44 variables: - CMAKE_CONFIGURATION: fedora42_makefiles_clang + CMAKE_CONFIGURATION: fedora44_makefiles_clang CMAKE_GENERATOR: "Unix Makefiles" -.fedora42_makefiles_lfortran: - extends: .fedora42 +.fedora44_makefiles_lfortran: + extends: .fedora44 variables: # FIXME(lfortran): -rpath flags with spaces not forwarded GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake-ci" - CMAKE_CONFIGURATION: fedora42_makefiles_lfortran + CMAKE_CONFIGURATION: fedora44_makefiles_lfortran CMAKE_GENERATOR: "Unix Makefiles" CTEST_LABELS: "Fortran" -.fedora42_ninja_lfortran: - extends: .fedora42 +.fedora44_ninja_lfortran: + extends: .fedora44 variables: # FIXME(lfortran): -rpath flags with spaces not forwarded GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake-ci" - CMAKE_CONFIGURATION: fedora42_ninja_lfortran + CMAKE_CONFIGURATION: fedora44_ninja_lfortran CTEST_LABELS: "Fortran" -.fedora42_ninja_clang: - extends: .fedora42 +.fedora44_ninja_multi: + extends: .fedora44 variables: - CMAKE_CONFIGURATION: fedora42_ninja_clang + CMAKE_CONFIGURATION: fedora44_ninja_multi + CMAKE_GENERATOR: "Ninja Multi-Config" -.fedora42_ninja_multi_clang: - extends: .fedora42 +.fedora44_ninja_clang: + extends: .fedora44 variables: - CMAKE_CONFIGURATION: fedora42_ninja_multi_clang + CMAKE_CONFIGURATION: fedora44_ninja_clang + +.fedora44_ninja_gcc_std_reloc: + extends: .fedora44 + + variables: + CMAKE_CONFIGURATION: fedora44_ninja_gcc_std_reloc + CTEST_LABELS: "CXXModules" + +.fedora44_ninja_multi_clang: + extends: .fedora44 + + variables: + CMAKE_CONFIGURATION: fedora44_ninja_multi_clang CMAKE_GENERATOR: "Ninja Multi-Config" ### Sanitizers @@ -293,13 +366,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: fedora44 + +.fedora44_asan: extends: - - .fedora42 + - .fedora44 - .fedora_asan_addon variables: - CMAKE_CONFIGURATION: fedora42_asan + CMAKE_CONFIGURATION: fedora44_asan + +.fedora44_ninja_valgrind: + extends: + - .fedora44 + - .fedora_valgrind_addon + + variables: + CMAKE_CONFIGURATION: fedora44_ninja_valgrind ### Intel Compiler @@ -325,7 +415,7 @@ ### NVHPC Compiler .nvhpc: - image: "kitware/cmake:ci-nvhpc24.9-x86_64-2024-09-27" + image: "kitware/cmake:ci-nvhpc26.3-x86_64-2026-03-31" variables: CMAKE_ARCH: x86_64 CMAKE_CUDA_ARCHITECTURES_NATIVE_CLAMP: 1 @@ -451,6 +541,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 +592,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 +.fedora44_hip_radeon: + extends: .fedora44_hip variables: - CMAKE_CONFIGURATION: fedora42_hip_radeon + CMAKE_CONFIGURATION: fedora44_hip_radeon CTEST_LABELS: "HIP" .hip6.3_nvidia: @@ -490,30 +612,7 @@ variables: CMAKE_CONFIGURATION: hip6.3_nvidia CTEST_LABELS: "HIP" - -### C++ modules - -.gcc_cxx_modules_x86_64: - image: "kitware/cmake:ci-gcc_cxx_modules-x86_64-2024-12-23" - - variables: - GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake ci" - CMAKE_ARCH: x86_64 - CC: "/opt/gcc-importstd/bin/gcc" - CXX: "/opt/gcc-importstd/bin/g++" - -.gcc_cxx_modules_ninja: - extends: .gcc_cxx_modules_x86_64 - - variables: - CMAKE_CONFIGURATION: linux_gcc_cxx_modules_ninja - -.gcc_cxx_modules_ninja_multi: - extends: .gcc_cxx_modules_x86_64 - - variables: - CMAKE_CONFIGURATION: linux_gcc_cxx_modules_ninja_multi - CMAKE_GENERATOR: "Ninja Multi-Config" + CMAKE_CUDA_ARCHITECTURES_NATIVE_CLAMP: 1 ### Debian 10 legacy packages @@ -554,6 +653,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 @@ -568,18 +674,25 @@ - docker - linux-x86_64 -.linux_x86_64_v3_tags_cuda_arch_52: +.linux_x86_64_v3_tags_cuda_arch_75: tags: - cmake - - cuda-arch-52 + - cuda-arch-75 - 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 +719,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 +758,14 @@ .cmake_version_update_linux: stage: build - extends: .fedora42 + extends: .fedora44 script: - .gitlab/ci/cmake_version_update.sh interruptible: false # The job internally fetches and retries. .cmake_spellcheck_linux: stage: build - extends: .fedora42 + extends: .fedora44 script: - .gitlab/ci/codespell.bash - .gitlab/ci/typos.bash @@ -659,8 +779,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 +793,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 +807,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 +883,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 +936,7 @@ .cmake_org_help: stage: build extends: - - .fedora42 + - .fedora44 - .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..5cea2ed 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,60 @@ 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_fastbuild: + extends: + - .windows_fastbuild + - .windows_vcvarsall_vs2022_x64_msvc14.44 + + variables: + CMAKE_CONFIGURATION: windows_clang_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 +262,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 +284,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 +297,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,13 +311,44 @@ 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: +.windows_orangec6.73.8: extends: .windows_orangec variables: - CMAKE_CONFIGURATION: windows_orangec6.73.1 + CMAKE_CONFIGURATION: windows_orangec6.73.8 + +.windows_orangec7.0.7: + extends: .windows_orangec + + variables: + CMAKE_CONFIGURATION: windows_orangec7.0.7 + +.windows_pellesc: + extends: .windows + + variables: + CMAKE_GENERATOR: "Ninja" + CMAKE_CI_BUILD_TYPE: Release + CMAKE_CI_JOB_NIGHTLY_IGNORE_DEPS: "true" + CTEST_LABELS: "PellesC" + +.windows_pellesc13.01: + extends: .windows_pellesc + + variables: + CMAKE_CONFIGURATION: windows_pellesc13.01 + +.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 +358,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 +367,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 +393,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 +475,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 +524,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 +553,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..7e7516b 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:44" stage: upload tags: - cmake @@ -21,7 +21,7 @@ .rsync_upload_help: stage: upload - image: "fedora:42" + image: "fedora:44" tags: - cmake - docker
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 8b6d940..b986c76 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.45.2 hooks: - id: typos # NOTE Override hook's default args to prevent automatic
diff --git a/.pvsconfig b/.pvsconfig new file mode 100644 index 0000000..4d7413f --- /dev/null +++ b/.pvsconfig
@@ -0,0 +1,100 @@ +# Identical sub-expressions to the left and to the right of 'foo' operator. +//-V::501 +# Pointer to local variable 'X' is stored outside the scope of this variable. Such a pointer will become invalid. +//-V::506 +# The 'new type(n)' pattern was detected. Probably meant: 'new type[n]'. +//-V::508 +# The 'x' variable is assigned values twice successively. Perhaps this is a mistake. +//-V::519 +# Possible null pointer dereference. +//-V::522 +# Constant value is represented by an octal form. +//-V::536 +# Iterators are passed as arguments to 'Foo' function. Consider inspecting the expression. +//-V::539 +# Expression is always true/false. +//-V::547 +# Expression of the 'A - B > 0' kind will work as 'A != B'. +//-V::555 +# Possible array overrun. +//-V::557 +# Part of conditional expression is always true/false. +//-V::560 +# It is suspicious that the argument of sizeof() operator is the expression. +//-V::568 +# Variable is assigned to itself. +//-V::570 +# Recurring check. This condition was already verified in previous line. +//-V::571 +# Function receives suspicious argument. +//-V::575 +# Conditional expressions of 'if' statements located next to each other are identical. +//-V::581 +# The 'Foo' function is called twice to deallocate the same resource. +//-V::586 +# Expression is enclosed by parentheses twice: ((expression)). One pair of parentheses is unnecessary or typo is present. +//-V::592 +# Pointer was used before its check for nullptr. Check lines: N1, N2. +//-V::595 +# Possible division or mod by zero. +//-V::609 +# Condition of a loop is always true/false. +//-V::654 +# Possible meaningless check for null, as memory was allocated using 'new' operator. Memory allocation will lead to an exception. +//-V::668 +# An object is used as an argument to its own method. +//-V::678 +# Pattern A || (A && ...) was detected. The expression is excessive or contains a logical error. +//-V::686 +# The class implements a copy constructor/operator=, but lacks the operator=/copy constructor. +//-V::690 +# Excessive check can be simplified. The '||' operator is surrounded by opposite expressions 'x' and '!x'. +//-V::728 +# Not all members of a class are initialized inside the constructor. +//-V::730 +# Suspicious access to element of '...' array by a constant index inside a loop. +//-V::767 +# The pointer in the expression equals nullptr. The resulting value is meaningless and should not be used. +//-V::769 +# Two similar code fragments were found. +//-V::778 +# Value of a variable is checked after it is used. Possible error in program's logic. Check lines: N1, N2. +//-V::781 +# Variable is assigned but not used by the end of the function. +//-V::1001 +# Pointer was used unsafely after its check for nullptr. +//-V::1004 +# Value from the uninitialized optional is used. It may be an error. +//-V::1007 +# The value is out of range of enum values. This causes unspecified or undefined behavior. +//-V::1016 +# A pointer without owner is added to the container by the 'emplace_back' method. A memory leak will occur in case of an exception. +//-V::1023 +# Possible overflow. Consider casting operands, not the result. +//-V::1028 +# Variable is used after it is moved. +//-V::1030 +# Two or more case-branches perform the same actions. +//-V::1037 +# This file is marked with copyleft license, which requires you to open the derived source code. +//-V::1042 +# Loop break conditions do not depend on the number of iterations. +//-V::1044 +# Variable 'foo' was assigned the same value. +//-V::1048 +# It is possible that an assigned variable should be checked in the next condition. Consider checking for typos. +//-V::1051 +# Calling the 'foo' virtual function in the constructor/destructor may lead to unexpected result at runtime. +//-V::1053 +# Return value is not always used. Consider inspecting the 'foo' function. +//-V::1071 +# Conditional initialization inside the constructor may leave some members uninitialized. +//-V::1077 +# Call of the 'Foo' function will lead to buffer underflow. +//-V::1086 +# Waiting on condition variable without predicate. A thread can wait indefinitely or experience a spurious wake-up. +//-V::1089 +# The 'emplace' / 'insert' function call contains potentially dangerous move operation. Moved object can be destroyed even if there is no insertion. +//-V::1098 +# Preprocessing directive is present within a macro argument. This leads to undefined behavior. +//-V::1119
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/bash-completion/cmake b/Auxiliary/bash-completion/cmake index 3c30d34..c46e02a 100644 --- a/Auxiliary/bash-completion/cmake +++ b/Auxiliary/bash-completion/cmake
@@ -114,6 +114,31 @@ _filedir -d return ;; + + --target) + local quoted + printf -v quoted %q "$cur" + # Options allowed right after `--target` + local target_options='--verbose --clean-first --config --' + local build_dir="build" + for ((i=0; i < ${#COMP_WORDS[@]}; i++)); do + if [[ "${COMP_WORDS[i]}" == "--build" ]]; then + build_dir="${COMP_WORDS[i+1]}" + break + fi + done + if [[ "$cur" == -* ]]; then + COMPREPLY=( $( compgen -W "$target_options" -- "$quoted" ) ) + else + local targets=$( cmake --build "$build_dir" --target help 2>/dev/null \ + | sed -n -e 's/^... \([^ ]*\).*$/\1/p' \ + -e '/^\[/d' -e 's/^\([^ :]*\):.*$/\1/p' | \ + grep -v '^/' | sort -u ) + COMPREPLY=( $( compgen -W "$targets $target_options" -- "$quoted" ) ) + fi + return + ;; + --install|--open) _filedir -d return
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..a2b2167 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,35 @@ \ SUFFIX \ SYMBOLIC \ SYSTEM + \ Swift_COMPILATION_MODE \ Swift_DEPENDENCIES_FILE \ Swift_DIAGNOSTICS_FILE \ Swift_LANGUAGE_VERSION \ Swift_MODULE_DIRECTORY \ Swift_MODULE_NAME - \ Swift_COMPILATION_MODE + \ Swift_PACKAGE_NAME + \ Swift_SEPARATE_MODULE_EMISSION \ 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 +448,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 +462,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 +495,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 +525,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 +603,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 +620,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 +634,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 +650,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 +667,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 +695,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 +709,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 +725,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 +742,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 +758,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 +786,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 +800,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 +816,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 +833,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 +849,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 +865,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 +882,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 +931,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 +948,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 +962,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 +978,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 +995,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 +1011,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 +1025,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 +1042,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 +1057,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 +1074,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 +1090,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 +1109,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 +1130,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 +1146,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 +1163,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 +1179,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 +1196,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 +1214,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 +1241,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 +1256,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 +1272,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 +1289,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 +1305,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 +1350,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 +1379,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 +1400,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 +1417,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 +1431,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 +1448,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 +1465,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 +1486,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 +1508,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 +1525,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 +1540,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 +1556,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 +1573,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 +1590,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 +1642,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 +1659,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 +1673,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 +1689,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 +1706,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 +1722,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 +1736,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 +1789,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 +1800,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 +1828,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 +1845,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 +1859,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 +1875,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 +1892,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 +1908,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 +1962,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 +1980,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 +1994,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 +2010,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,15 +2028,18 @@ \ 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 \ CMAKE_Swift_OUTPUT_EXTENSION \ CMAKE_Swift_PLATFORM_ID + \ CMAKE_Swift_SEPARATE_MODULE_EMISSION \ CMAKE_Swift_SIMULATE_ID \ CMAKE_Swift_SIMULATE_VERSION \ CMAKE_Swift_SIZEOF_DATA_PTR @@ -1765,13 +2047,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 +2067,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 +2106,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 +2119,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 +2130,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 +2139,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 +2192,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 +2211,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 +2225,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 +2243,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 +2518,7 @@ \ DOXYGEN_USE_PDFLATEX \ DOXYGEN_VERBATIM_HEADERS \ DOXYGEN_VERBATIM_VARS + \ Doxygen_VERSION \ DOXYGEN_VERSION \ DOXYGEN_WARNINGS \ DOXYGEN_WARN_AS_ERROR @@ -2259,17 +2552,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 +2583,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 +2594,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 +2641,8 @@ \ INSTALL_BYPRODUCTS \ INSTALL_COMMAND \ INSTALL_DIR - \ JOB_POOLS + \ INSTALL_ENVIRONMENT_MODIFICATION + \ INSTALL_JOB_SERVER_AWARE \ LIST_SEPARATOR \ LOG_BUILD \ LOG_CONFIGURE @@ -2380,10 +2681,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 +2710,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 +2735,7 @@ \ NAME \ NAMES \ NEVER + \ NOT \ NOTE \ OFF \ OPTIONAL @@ -2441,6 +2744,7 @@ \ PACKAGE_VERSION_COMPATIBLE \ PACKAGE_VERSION_EXACT \ QUIET + \ REQUIRED \ SOURCE_SUBDIR \ STREQUAL \ SUBBUILD_DIR @@ -2449,10 +2753,10 @@ \ SYSTEM \ TARGET \ TEST_COMMAND - \ TRUE \ URL \ URL_HASH \ VERIFY_INTERFACE_HEADER_SETS + \ WARNING \ WRITE \ WRONG \ _BINARY_DIR @@ -2475,11 +2779,13 @@ \ _FLAGS_ syn keyword cmakeKWadd_custom_command contained + \ ALIAS \ APPEND \ ARGS \ BNF \ BYPRODUCTS \ CC + \ CODEGEN \ COMMAND \ COMMAND_EXPAND_LISTS \ COMMENT @@ -2493,11 +2799,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 +2834,7 @@ \ INCLUDE_DIRECTORIES \ JOB_POOL \ JOB_POOLS + \ JOB_SERVER_AWARE \ JOIN \ PATH \ SOURCES @@ -2542,6 +2852,7 @@ syn keyword cmakeKWadd_dependencies contained \ DEPENDS + \ MANUALLY_ADDED_DEPENDENCIES \ OBJECT_DEPENDS syn keyword cmakeKWadd_executable contained @@ -2573,7 +2884,6 @@ \ HEADER_FILE_ONLY \ HEADER_SETS \ IMPORTED - \ IMPORTED_ \ IMPORTED_IMPLIB \ IMPORTED_IMPLIB_ \ IMPORTED_LOCATION @@ -2589,7 +2899,6 @@ \ LIBRARY_OUTPUT_DIRECTORY \ MODULE \ OBJECT - \ ON \ OUTPUT_NAME \ POSITION_INDEPENDENT_CODE \ POST_BUILD @@ -2631,22 +2940,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 +3035,7 @@ \ LISTS \ LTS \ MATCHES + \ MSYSTEM_PREFIX \ NNN \ NOT \ NUMBER_OF_LOGICAL_CORES @@ -2755,6 +3068,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 +3094,7 @@ \ DEFER \ DIRECTORY \ EVAL + \ EXIT \ FALSE \ FETCHCONTENT_MAKEAVAILABLE_SERIAL \ FETCHCONTENT_SOURCE_DIR_ @@ -2790,6 +3114,7 @@ \ OVERRIDE_FIND_PACKAGE \ PATH \ POP_BACK + \ PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE \ QUIET \ SET_DEPENDENCY_PROVIDER \ SOURCE_DIR @@ -2803,7 +3128,9 @@ \ _PATH syn keyword cmakeKWcmake_minimum_required contained + \ CMAKE_POLICY_DEFAULT_CMP \ FATAL_ERROR + \ NNNN \ VERSION syn keyword cmakeKWcmake_parse_arguments contained @@ -2813,21 +3140,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 +3212,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 +3396,6 @@ \ CAPTURE_CMAKE_ERROR \ CDASH_UPLOAD \ CDASH_UPLOAD_TYPE - \ CTEST_EXTRA_SUBMIT_FILES - \ CTEST_NOTES_FILES \ FILES \ HTTPHEADER \ PARTS @@ -3034,10 +3417,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 +3460,14 @@ \ BRIEF_DOCS \ CACHED_VARIABLE \ CMAKE_ + \ DEFINED \ DIRECTORY \ FULL_DOCS \ GLOBAL \ INHERITED \ INITIALIZE_FROM_VARIABLE + \ MY_NEW_PROP + \ NONE \ PROPERTY \ SOURCE \ TARGET @@ -3105,13 +3494,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 +3539,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 +3596,7 @@ \ CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM \ CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL \ CMAKE_INSTALL_MODE - \ CMAKE_OBJDUMP + \ CMAKE_MATCH_ \ CODE \ COMPILE_FEATURES \ COMPRESSION @@ -3197,13 +3613,14 @@ \ CREATE_LINK \ CRLF \ DESTINATION - \ DIRECTORIES \ DIRECTORY_PERMISSIONS \ DLL \ DOS \ DOWNLOAD + \ ELF \ ENCODING \ ESCAPE_QUOTES + \ EXCLUDE \ EXECUTABLES \ EXPAND_TILDE \ EXPECTED_HASH @@ -3244,6 +3661,7 @@ \ LOCK \ LOG \ MAKE_DIRECTORY + \ MATCHALL \ MODULES \ MTIME \ MYLIBRARY @@ -3309,6 +3727,7 @@ \ TIMESTAMP \ TLS_CAINFO \ TLS_VERIFY + \ TLS_VERSION \ TOUCH \ TOUCH_NOCREATE \ TO_CMAKE_PATH @@ -3323,7 +3742,9 @@ \ USE_SOURCE_PERMISSIONS \ UTC \ UTF + \ VAR \ VERBOSE + \ WORKING_DIRECTORY \ WORLD_EXECUTE \ WORLD_READ \ WORLD_WRITE @@ -3339,7 +3760,9 @@ \ DOC \ DVAR \ FALSE + \ FIND_XXX_ORDER \ FIND_XXX_REGISTRY_VIEW + \ FIND_XXX_ROOT \ HINTS \ HOST \ INCLUDE @@ -3356,6 +3779,7 @@ \ NO_PACKAGE_ROOT_PATH \ NO_SYSTEM_ENVIRONMENT_PATH \ ONLY_CMAKE_FIND_ROOT_PATH + \ OPTIONAL \ PACKAGENAME \ PARENT_SCOPE \ PATHS @@ -3374,7 +3798,9 @@ \ DOC \ DVAR \ FALSE + \ FIND_XXX_ORDER \ FIND_XXX_REGISTRY_VIEW + \ FIND_XXX_ROOT \ HINTS \ HOST \ LIB @@ -3392,6 +3818,7 @@ \ NO_PACKAGE_ROOT_PATH \ NO_SYSTEM_ENVIRONMENT_PATH \ ONLY_CMAKE_FIND_ROOT_PATH + \ OPTIONAL \ PACKAGENAME \ PARENT_SCOPE \ PATHS @@ -3404,17 +3831,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 +3848,7 @@ \ EXCLUDE \ FALSE \ FIND_PACKAGE_VERSION_FORMAT + \ FIND_XXX_REGISTRY_VIEW \ FRAMEWORK \ GLOBAL \ HINTS @@ -3430,6 +3857,7 @@ \ MODULE \ NAMES \ NATURAL + \ NONE \ NO_CMAKE_BUILDS_PATH \ NO_CMAKE_ENVIRONMENT_PATH \ NO_CMAKE_FIND_ROOT_PATH @@ -3443,8 +3871,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 +3905,6 @@ \ QUIET \ REGISTRY_VIEW \ REQUIRED - \ SET \ TARGET \ TRUE \ VALUE @@ -3501,7 +3928,9 @@ \ DOC \ DVAR \ FALSE + \ FIND_XXX_ORDER \ FIND_XXX_REGISTRY_VIEW + \ FIND_XXX_ROOT \ HINTS \ HOST \ INCLUDE @@ -3518,6 +3947,7 @@ \ NO_PACKAGE_ROOT_PATH \ NO_SYSTEM_ENVIRONMENT_PATH \ ONLY_CMAKE_FIND_ROOT_PATH + \ OPTIONAL \ PACKAGENAME \ PARENT_SCOPE \ PATHS @@ -3536,10 +3966,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 +3986,7 @@ \ NO_PACKAGE_ROOT_PATH \ NO_SYSTEM_ENVIRONMENT_PATH \ ONLY_CMAKE_FIND_ROOT_PATH + \ OPTIONAL \ PACKAGENAME \ PARENT_SCOPE \ PATHS @@ -3635,11 +4069,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 +4089,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 +4143,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 +4157,7 @@ \ CMAKE_INSTALL_INCLUDEDIR \ CMAKE_INSTALL_INFODIR \ CMAKE_INSTALL_LIBDIR + \ CMAKE_INSTALL_LIBEXECDIR \ CMAKE_INSTALL_LOCALEDIR \ CMAKE_INSTALL_LOCALSTATEDIR \ CMAKE_INSTALL_MANDIR @@ -3732,9 +4166,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 +4179,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 +4211,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 +4232,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 +4252,12 @@ \ PRE_INSTALL_SCRIPT \ PRIVATE_HEADER \ PROGRAMS + \ PROJECT \ PROPERTIES + \ PROPERTY \ PUBLIC_HEADER \ RENAME + \ REQUIRED \ RESOURCE \ RPM \ RUNSTATE @@ -3811,8 +4267,11 @@ \ SCRIPT \ SETGID \ SETUID + \ SETUP \ SHAREDSTATE \ SOVERSION + \ SPDX + \ SPDX_LICENSE \ STATIC \ SYSCONF \ TARGETS @@ -3820,6 +4279,7 @@ \ TYPE \ USE_SOURCE_PERMISSIONS \ VERSION + \ VERSION_SCHEMA \ WORLD_EXECUTE \ WORLD_READ \ WORLD_WRITE @@ -3896,7 +4356,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 +4418,8 @@ \ ASM_NASM \ ATT \ CMAKE_PROJECT_ + \ COMPAT_VERSION + \ CPS \ CUDA \ DESCRIPTION \ HIP @@ -3967,14 +4431,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 +4517,7 @@ \ PROPERTIES syn keyword cmakeKWset_tests_properties contained + \ DIRECTORY \ NAME \ PROPERTIES @@ -4195,28 +4662,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 +4724,6 @@ \ BUILD_INTERFACE \ COMPILE_LANGUAGE \ DISABLE_PRECOMPILE_HEADERS - \ EXPORT \ FI \ GCC \ IMPORTED @@ -4312,27 +4785,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 +4820,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 +4831,6 @@ \ STATIC_LIBRARY_OPTIONS \ TARGET \ TRUE - \ TYPE \ VALUE \ _EXTENSIONS \ _STANDARD @@ -4369,8 +4844,8 @@ \ COPY_FILE \ COPY_FILE_ERROR \ FAILED_TO_RUN - \ FALSE \ LANG + \ LINKER_LANGUAGE \ LINK_LIBRARIES \ LINK_OPTIONS \ LOG_DESCRIPTION @@ -4379,11 +4854,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 +4897,6 @@ syn keyword cmakeGeneratorExpressions contained \ ABSOLUTE_PATH \ ACTION - \ AIX \ ANGLE \ APPEND \ ARCHIVE_OUTPUT_NAME @@ -4440,6 +4913,7 @@ \ COMMAND_CONFIG \ COMMAND_EXPAND_LISTS \ COMPARE + \ COMPATIBLE_INTERFACE_ \ COMPILE_DEFINITIONS \ COMPILE_FEATURES \ COMPILE_LANGUAGE @@ -4453,16 +4927,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 +4984,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 +5004,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 +5033,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 +5071,7 @@ \ PREPEND \ PRIVATE \ PUBLIC + \ QUOTE \ REGEX \ RELATIVE_PATH \ REMOVE_AT @@ -4665,6 +5160,8 @@ \ TRANSFORM_REPLACE \ TRANSFORM_STRIP \ TRANSFORM_TOLOWER + \ TRANSITIVE_COMPILE_PROPERTIES + \ TRANSITIVE_LINK_PROPERTIES \ UNKNOWN \ UPPER_CASE \ VERBATIM @@ -4674,6 +5171,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 +5194,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 +5224,6 @@ \ define_property \ enable_language \ enable_testing - \ endblock - \ endfunction - \ endmacro \ execute_process \ export \ file @@ -4735,7 +5233,6 @@ \ find_path \ find_program \ fltk_wrap_ui - \ function \ get_cmake_property \ get_directory_property \ get_filename_component @@ -4753,7 +5250,6 @@ \ list \ load_cache \ load_command - \ macro \ mark_as_advanced \ math \ message @@ -4788,20 +5284,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 +5312,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 +5345,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 +5367,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..b391315 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt
@@ -1,13 +1,33 @@ # 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.2 FATAL_ERROR) + +if(CMake_TEST_HOST_CMAKE) + get_filename_component(CMake_TEST_EXTERNAL_CMAKE "${CMAKE_COMMAND}" DIRECTORY) +endif() + +set(CMake_LANGUAGES "") +if(CMake_TEST_EXTERNAL_CMAKE) + foreach(lang C CXX) + if(NOT DEFINED CMake_TEST_${lang}) + set(CMake_TEST_${lang} 1) + endif() + if(CMake_TEST_${lang}) + list(APPEND CMake_LANGUAGES ${lang}) + endif() + endforeach() +else() + set(CMake_TEST_C 1) + set(CMake_TEST_CXX 1) + list(APPEND CMake_LANGUAGES C CXX) +endif() set(CMAKE_USER_MAKE_RULES_OVERRIDE_C ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideC.cmake) set(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideCXX.cmake) - -project(CMake) +project(CMake LANGUAGES ${CMake_LANGUAGES}) unset(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX) unset(CMAKE_USER_MAKE_RULES_OVERRIDE_C) +unset(CMake_LANGUAGES) # FIXME: This block should go away after a transition period. if(MSVC AND NOT CMAKE_VERSION VERSION_LESS 3.15) @@ -30,10 +50,6 @@ unset(CMAKE_BOOTSTRAP CACHE) endif() -if(CMake_TEST_HOST_CMAKE) - get_filename_component(CMake_TEST_EXTERNAL_CMAKE "${CMAKE_COMMAND}" DIRECTORY) -endif() - if(NOT CMake_TEST_EXTERNAL_CMAKE) if(CMAKE_SYSTEM_NAME STREQUAL "HP-UX") message(FATAL_ERROR @@ -111,12 +127,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 +203,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 +255,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) @@ -344,6 +391,22 @@ list(APPEND CMAKE_CXX_INCLUDE_WHAT_YOU_USE ${CMake_IWYU_OPTIONS}) endif() +option(CMake_RUN_PVS_STUDIO "Run pvs-studio-analyzer with the compiler." OFF) +if(CMake_RUN_PVS_STUDIO) + if(CMake_SOURCE_DIR STREQUAL CMake_BINARY_DIR) + message(FATAL_ERROR "CMake_RUN_PVS_STUDIO requires an out-of-source build!") + endif() + find_program(PVS_STUDIO_COMMAND NAMES pvs-studio-analyzer) + if(NOT PVS_STUDIO_COMMAND) + message(FATAL_ERROR "CMake_RUN_PVS_STUDIO is ON but pvs-studio-analyzer is not found!") + endif() + set(CMAKE_CXX_PVS_STUDIO + "${PVS_STUDIO_COMMAND}" analyze + -a GA + --apply-pvs-configs + --project-root "${CMAKE_SOURCE_DIR}" + ) +endif() #----------------------------------------------------------------------- # a macro that only sets the FOLDER target property if it's @@ -435,6 +498,7 @@ if(CMake_TEST_EXTERNAL_CMAKE) set(KWIML_TEST_ENABLE 1) + set(KWIML_TEST_LABELS "PellesC") add_subdirectory(Utilities/KWIML) endif() @@ -443,19 +507,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 +536,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 +592,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/CONTRIBUTING.rst b/CONTRIBUTING.rst index 7247467..7b918dc 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst
@@ -45,6 +45,9 @@ The merge request will enter the `CMake Review Process`_ for consideration. +Please note `CMake's AI policy`_ if using AI tools or services as part of +preparing or submitting a change. + .. _`Kitware's GitLab Instance`: https://gitlab.kitware.com .. _`CMake Repository`: https://gitlab.kitware.com/cmake/cmake .. _`Utilities/SetupForDevelopment.sh`: Utilities/SetupForDevelopment.sh @@ -53,6 +56,7 @@ .. _`CMake Testing Guide`: Help/dev/testing.rst .. _`commit messages`: Help/dev/review.rst#commit-messages .. _`CMake Review Process`: Help/dev/review.rst +.. _`CMake's AI policy`: Help/dev/ai-policy.rst CMake Dashboard Client ======================
diff --git a/CONTRIBUTORS.rst b/CONTRIBUTORS.rst index 76cd4ba..cd5479a 100644 --- a/CONTRIBUTORS.rst +++ b/CONTRIBUTORS.rst
@@ -3,84 +3,86 @@ 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>`__ +* `Qualcomm Technologies, Inc. <https://www.qualcomm.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..591da55 100644 --- a/CTestCustom.cmake.in +++ b/CTestCustom.cmake.in
@@ -51,6 +51,7 @@ "Warning: Function .* can throw only the exceptions thrown by the function .* it overrides\\." "WarningMessagesDialog\\.cxx" "warning.*directory name.*CMake-Xcode.*/bin/.*does not exist.*" + "stl_algo(base)?\\.h:[0-9:]* warning: loop not unrolled" "stl_deque.h:1051" "Tests/CMakeLib/testCTestResourceSpec.cxx:.*warning: missing initializer for member.*cmCTestResourceSpec::.*" # GCC 4.8 disagrees with later compilers on C++11 initializer list conversion "(Lexer|Parser).*warning.*conversion.*may (alter its value|change the sign)" @@ -126,6 +127,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..4dc92b2 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst
@@ -3,478 +3,500 @@ 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). + .. versionchanged:: 4.4 - 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`). + Previously an executable target could be specified using the name + of the target with ``.exe`` appended. This is no longer allowed. + See policy :policy:`CMP0212`. - * ``TARGET_FILE`` - * ``TARGET_LINKER_FILE`` - * ``TARGET_SONAME_FILE`` - * ``TARGET_PDB_FILE`` + 2. If the argument is an absolute path, a file-level dependency + is created on that path. - 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. + 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. -``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. + 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. - .. versionadded:: 3.26 - Arguments to ``COMMENT`` may use - :manual:`generator expressions <cmake-generator-expressions(7)>`. + 5. Otherwise, a file-level dependency is created on that path relative + to the current binary directory. -``DEPENDS`` - Specify files on which the command depends. Each argument is converted - to a dependency as follows: + 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. - 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.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. - 2. If the argument is an absolute path, a file-level dependency - is created on that path. + 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. - 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. + .. versionadded:: 3.1 + Arguments to ``DEPENDS`` may use + :manual:`generator expressions <cmake-generator-expressions(7)>`. - 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. + ``COMMAND_EXPAND_LISTS`` + .. versionadded:: 3.8 - 5. Otherwise, a file-level dependency is created on that path relative - to the current binary directory. + 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. - 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. + 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. - .. 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. + ``CODEGEN`` + .. versionadded:: 3.31 - 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. + 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.1 - Arguments to ``DEPENDS`` may use - :manual:`generator expressions <cmake-generator-expressions(7)>`. + 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``. -``COMMAND_EXPAND_LISTS`` - .. versionadded:: 3.8 + 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. - 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 +599,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/block.rst b/Help/command/block.rst index 7b5b581..abdbd37 100644 --- a/Help/command/block.rst +++ b/Help/command/block.rst
@@ -7,7 +7,8 @@ .. code-block:: cmake - block([SCOPE_FOR [POLICIES] [VARIABLES]] [PROPAGATE <var-name>...]) + block([SCOPE_FOR [DIAGNOSTICS] [POLICIES] [VARIABLES]] + [PROPAGATE <var-name>...]) <commands> endblock() @@ -19,6 +20,13 @@ ``SCOPE_FOR`` Specify which scopes must be created. + ``DIAGNOSTICS`` + .. versionadded:: 4.4 + + Create a new diagnostic scope. This is equivalent to + :command:`cmake_diagnostic(PUSH)` with an automatic + :command:`cmake_diagnostic(POP)` when leaving the block scope. + ``POLICIES`` Create a new policy scope. This is equivalent to :command:`cmake_policy(PUSH)` with an automatic @@ -31,7 +39,7 @@ .. code-block:: cmake - block(SCOPE_FOR VARIABLES POLICIES) + block(SCOPE_FOR VARIABLES POLICIES DIAGNOSTICS) ``PROPAGATE`` When a variable scope is created by the :command:`block` command, this
diff --git a/Help/command/build_command.rst b/Help/command/build_command.rst index 21adab9..6bb7d58 100644 --- a/Help/command/build_command.rst +++ b/Help/command/build_command.rst
@@ -29,7 +29,7 @@ .. versionadded:: 3.21 The ``PARALLEL_LEVEL`` argument can be used to set the - :option:`--parallel <cmake--build --parallel>` flag. + :cmake-build-option:`--parallel` flag. .. code-block:: cmake @@ -39,7 +39,7 @@ compatibility. Use the first signature instead. It sets the given ``<cachevariable>`` to a command-line string as -above but without the :option:`--target <cmake--build --target>` option. +above but without the :cmake-build-option:`--target` option. The ``<makecommand>`` is ignored but should be the full path to devenv, nmake, make or one of the end user build tools for legacy invocations.
diff --git a/Help/command/cmake_diagnostic.rst b/Help/command/cmake_diagnostic.rst new file mode 100644 index 0000000..29b2589 --- /dev/null +++ b/Help/command/cmake_diagnostic.rst
@@ -0,0 +1,156 @@ +cmake_diagnostic +---------------- + +.. versionadded:: 4.4 + +Manage CMake Diagnostic settings. See the :manual:`cmake-diagnostics(7)` +manual for a list of available categories. + +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + `Setting Diagnostics`_ + cmake_diagnostic(`SET`_ <category> <action> [RECURSE]) + cmake_diagnostic(`PROMOTE`_ <category> <action> [NO_RECURSE]) + cmake_diagnostic(`DEMOTE`_ <category> <action> [NO_RECURSE]) + + `Checking Diagnostic Actions`_ + cmake_diagnostic(`GET`_ <diagnostic> <out-var>) + + `CMake Diagnostic Stack`_ + cmake_diagnostic(`PUSH`_) + cmake_diagnostic(`POP`_) + +Setting Diagnostics +^^^^^^^^^^^^^^^^^^^ + +.. signature:: + cmake_diagnostic(SET CMD_<CATEGORY> <action> [RECURSE]) + cmake_diagnostic(PROMOTE CMD_<CATEGORY> <action> [NO_RECURSE]) + cmake_diagnostic(DEMOTE CMD_<CATEGORY> <action> [NO_RECURSE]) + :target: + SET + PROMOTE + DEMOTE + +Set or alter the action taken when a diagnostic belonging to a particular +category is triggered. + +The ``SET`` subcommand sets the action for the specified diagnostic category. +The ``PROMOTE`` subcommand increases the severity for the specified diagnostic +category, or does nothing if the action was already set to an equal or higher +severity. The ``DEMOTE`` subcommand decreases the severity for the specified +diagnostic category, or does nothing if the action was already set to an equal +or lower severity. + +The possible ``<action>``\ s (in order of severity) are: + +``IGNORE`` + Do nothing. + +``WARN`` + Report a warning and continue processing. + +``SEND_ERROR`` + Report an error, continue processing, but skip generation. + + The :manual:`cmake(1)` executable will return a non-zero + :ref:`exit code <CMake Exit Code>`. + +``FATAL_ERROR`` + Report an error, stop processing and generation. + + The :manual:`cmake(1)` executable will return a non-zero + :ref:`exit code <CMake Exit Code>`. + +Some diagnostic categories are hierarchical. The ``RECURSE`` and +``NO_RECURSE`` options determine whether changing the action for a diagnostic +category also modifies any child categories. By default, the ``PROMOTE`` and +``DEMOTE`` subcommands are recursive, while the ``SET`` subcommand is not. +Note that the alteration for child categories is independent of the prior +action set on any parents; that is, ``PROMOTE`` and ``DEMOTE``, when operating +recursively, will operate on all child categories even if a parent category's +action was not altered. + +Checking Diagnostic Actions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. signature:: cmake_diagnostic(GET CMD_<CATEGORY> <variable>) + :target: GET + +Check what action is currently specified for a diagnostic category. +The output ``<variable>`` value will be one of ``IGNORE``, ``WARN``, +``SEND_ERROR`` or ``FATAL_ERROR``. + +CMake Diagnostic Stack +^^^^^^^^^^^^^^^^^^^^^^ + +CMake keeps diagnostic settings on a stack, so changes made by the +``cmake_diagnostic`` command affect only the top of the stack. A new entry on +the diagnostic stack is managed automatically for each subdirectory to protect +its parents and siblings. CMake also manages a new entry for scripts loaded by +:command:`include` and :command:`find_package` commands except when invoked +with the ``NO_DIAGNOSTIC_SCOPE`` option. The ``cmake_diagnostic`` command +provides an interface to manage custom entries on the diagnostic stack: + +.. signature:: cmake_diagnostic(PUSH) + + Create a new entry on the diagnostic stack. + +.. signature:: cmake_diagnostic(POP) + + Remove the last diagnostic stack entry created with + ``cmake_diagnostic(PUSH)``. + +Each ``PUSH`` must have a matching ``POP`` to erase any changes. +This is useful to make temporary changes to diagnostic settings. +Calls to the :command:`cmake_diagnostic(SET)`, +:command:`cmake_diagnostic(PROMOTE)`, or :command:`cmake_diagnostic(DEMOTE)` +commands influence only the current top of the diagnostic stack. + +The :command:`block(SCOPE_FOR DIAGNOSTICS)` command offers a more flexible +and more secure way to manage the diagnostic stack. The pop action is done +automatically when leaving the block scope, so there is no need to +precede each :command:`return` with a call to :command:`cmake_diagnostic(POP)`. + +.. code-block:: cmake + + # stack management with cmake_diagnostic() + function(my_func) + cmake_diagnostic(PUSH) + cmake_diagnostic(SET ...) + if (<cond1>) + ... + cmake_diagnostic(POP) + return() + elseif(<cond2>) + ... + cmake_diagnostic(POP) + return() + endif() + ... + cmake_diagnostic(POP) + endfunction() + + # stack management with block()/endblock() + function(my_func) + block(SCOPE_FOR DIAGNOSTICS) + cmake_diagnostic(SET ...) + if (<cond1>) + ... + return() + elseif(<cond2>) + ... + return() + endif() + ... + endblock() + endfunction() + +Commands created by the :command:`function` and :command:`macro` commands +record diagnostic settings when they are created and use the pre-record +diagnostics when they are invoked. If the function or macro implementation +sets diagnostics, the changes automatically propagate up through callers until +they reach the closest nested diagnostic stack entry.
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..2a36325 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/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/create_test_sourcelist.rst b/Help/command/create_test_sourcelist.rst index d0b43c4..f3aca7a 100644 --- a/Help/command/create_test_sourcelist.rst +++ b/Help/command/create_test_sourcelist.rst
@@ -60,3 +60,44 @@ .. variable:: CMAKE_TESTDRIVER_AFTER_TESTMAIN Code to be placed directly after the call to each test's function. + +The generated test driver supports the following command-line arguments: + +``<name>`` + Run the test with the exact name ``<name>`` (case-insensitive). + +``-R <substr>`` + Run the first test whose name contains ``<substr>`` (case-insensitive). + +``-A [<skip_test>...]`` + .. versionadded:: 3.21 + + Run all tests and print results in `TAP <https://testanything.org/>`_ + format. + + Any additional arguments after ``-A`` are interpreted as exact test names + to skip. + +``-N`` + .. versionadded:: 4.4 + + List all available test names (one per line) and exit. + +Example +^^^^^^^ + +.. code-block:: cmake + + create_test_sourcelist(SRCS main.c test1.c test2.c) + add_executable(MyTests ${SRCS}) + discover_tests(COMMAND MyTests + DISCOVERY_ARGS -N + DISCOVERY_MATCH "^(.+)$" + TEST_NAME "${PROJECT_NAME}.\\1" + TEST_ARGS "\\1" + ) + +See Also +^^^^^^^^ + +* :command:`discover_tests`
diff --git a/Help/command/ctest_build.rst b/Help/command/ctest_build.rst index bce1739..10922a7 100644 --- a/Help/command/ctest_build.rst +++ b/Help/command/ctest_build.rst
@@ -15,6 +15,7 @@ [NUMBER_WARNINGS <num-warn-var>] [RETURN_VALUE <result-var>] [CAPTURE_CMAKE_ERROR <result-var>] + [PRESET <preset>] ) Build the project and store results in ``Build.xml`` @@ -75,6 +76,15 @@ ``NUMBER_WARNINGS <num-warn-var>`` Store the number of build warnings detected in the given variable. +``PRESET <preset>`` + .. versionadded:: 4.4 + + Specify a :manual:`preset <cmake-presets(7)>` to use when building the + project. Any value set in the CTest script will take priority over a + corresponding setting from the preset. For example, the ``TARGET`` + argument will override the :preset:`buildPresets.targets` setting from + the chosen preset. + ``RETURN_VALUE <result-var>`` Store the return value of the native build tool in the given variable.
diff --git a/Help/command/ctest_configure.rst b/Help/command/ctest_configure.rst index f23dd22..5911554 100644 --- a/Help/command/ctest_configure.rst +++ b/Help/command/ctest_configure.rst
@@ -7,7 +7,9 @@ ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND] [OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET] - [CAPTURE_CMAKE_ERROR <result-var>]) + [CAPTURE_CMAKE_ERROR <result-var>] + [PRESET <preset>] + ) Configure the project build tree and record results in ``Configure.xml`` for submission with the :command:`ctest_submit` command. @@ -30,7 +32,21 @@ produced by a previous call to this command. ``OPTIONS <options>`` - Specify command-line arguments to pass to the configuration tool. + Specify a :ref:`semicolon-separated list <CMake Language Lists>` of + command-line arguments to pass to the configuration tool. + This option is ignored when :variable:`CTEST_CONFIGURE_COMMAND` is used. + +``PRESET <preset>`` + .. versionadded:: 4.4 + + Specify a :manual:`preset <cmake-presets(7)>` to use when configuring the + project. Any value set in the CTest script will take priority over a + corresponding setting from the preset. For example, the + :variable:`CTEST_BINARY_DIRECTORY` variable will override the + :preset:`configurePresets.binaryDir` setting from the chosen preset. + + This option is ignored when :variable:`CTEST_CONFIGURE_COMMAND` + is used. ``RETURN_VALUE <result-var>`` Store in the ``<result-var>`` variable the return value of the native @@ -39,8 +55,9 @@ ``CAPTURE_CMAKE_ERROR <result-var>`` .. versionadded:: 3.7 - Store in the ``<result-var>`` variable -1 if there are any errors running - the command and prevent ctest from returning non-zero if an error occurs. + Store in the ``<result-var>`` variable ``-1`` if there are any errors running + the command and prevent :manual:`ctest(1)` from returning non-zero if an + error occurs. ``QUIET`` .. versionadded:: 3.3
diff --git a/Help/command/ctest_coverage.rst b/Help/command/ctest_coverage.rst index 319c978..5a85007 100644 --- a/Help/command/ctest_coverage.rst +++ b/Help/command/ctest_coverage.rst
@@ -39,8 +39,9 @@ ``CAPTURE_CMAKE_ERROR <result-var>`` .. versionadded:: 3.7 - Store in the ``<result-var>`` variable -1 if there are any errors running - the command and prevent ctest from returning non-zero if an error occurs. + Store in the ``<result-var>`` variable ``-1`` if there are any errors running + the command and prevent :manual:`ctest(1)` from returning non-zero if an + error occurs. ``QUIET`` .. versionadded:: 3.3
diff --git a/Help/command/ctest_empty_binary_directory.rst b/Help/command/ctest_empty_binary_directory.rst index 5d26de1..1f91d0c 100644 --- a/Help/command/ctest_empty_binary_directory.rst +++ b/Help/command/ctest_empty_binary_directory.rst
@@ -1,7 +1,7 @@ ctest_empty_binary_directory ---------------------------- -empties the binary directory +Empties the binary directory. .. code-block:: cmake
diff --git a/Help/command/ctest_read_custom_files.rst b/Help/command/ctest_read_custom_files.rst index 53c093e..48b2060 100644 --- a/Help/command/ctest_read_custom_files.rst +++ b/Help/command/ctest_read_custom_files.rst
@@ -1,13 +1,13 @@ ctest_read_custom_files ----------------------- -read CTestCustom files. +Read CTestCustom files. .. code-block:: cmake ctest_read_custom_files(<directory>...) -Read all the CTestCustom.ctest or CTestCustom.cmake files from the +Read all the ``CTestCustom.ctest`` or ``CTestCustom.cmake`` files from the given directory. By default, invoking :manual:`ctest(1)` without a script will read custom
diff --git a/Help/command/ctest_run_script.rst b/Help/command/ctest_run_script.rst index 0d94eb0..734fa28 100644 --- a/Help/command/ctest_run_script.rst +++ b/Help/command/ctest_run_script.rst
@@ -1,14 +1,21 @@ ctest_run_script ---------------- -runs a :option:`ctest -S` script +Run a :option:`ctest -S` script. .. code-block:: cmake - ctest_run_script([NEW_PROCESS] script_file_name script_file_name1 - script_file_name2 ... [RETURN_VALUE var]) + ctest_run_script([NEW_PROCESS] + <script-file>... + [RETURN_VALUE <result-var>] + ) Runs a script or scripts much like if it was run from :option:`ctest -S`. -If ``NEW_PROCESS`` is specified then each script will be run in a separate -process. If ``RETURN_VALUE`` is specified the return value of the last script -run will be put into ``var``. +The options are: + +``NEW_PROCESS`` + Run each script in a separate process. + +``RETURN_VALUE <result-var>`` + Store in the ``<result-var>`` variable ``0`` for success and + non-zero on failure.
diff --git a/Help/command/ctest_sleep.rst b/Help/command/ctest_sleep.rst index 42b9768..723c2d4 100644 --- a/Help/command/ctest_sleep.rst +++ b/Help/command/ctest_sleep.rst
@@ -1,16 +1,15 @@ ctest_sleep ----------- -sleeps for some amount of time +Sleep for some amount of time. -.. code-block:: cmake - +.. signature:: ctest_sleep(<seconds>) -Sleep for given number of seconds. + Sleep for ``<seconds>`` seconds. -.. code-block:: cmake - +.. signature:: ctest_sleep(<time1> <duration> <time2>) -Sleep for t=(time1 + duration - time2) seconds if t > 0. + Sleep for ``<time1> + <duration> - <time2>`` seconds, if this sum is greater + than zero.
diff --git a/Help/command/ctest_start.rst b/Help/command/ctest_start.rst index 9c4e3dc..9184fac 100644 --- a/Help/command/ctest_start.rst +++ b/Help/command/ctest_start.rst
@@ -1,7 +1,7 @@ ctest_start ----------- -Starts the testing for a given model +Perform the :ref:`CTest Start Step` as a :ref:`Dashboard Client`. .. code-block:: cmake
diff --git a/Help/command/ctest_submit.rst b/Help/command/ctest_submit.rst index 56a47e8..aa238b0 100644 --- a/Help/command/ctest_submit.rst +++ b/Help/command/ctest_submit.rst
@@ -83,8 +83,9 @@ ``CAPTURE_CMAKE_ERROR <result-var>`` .. versionadded:: 3.13 - Store in the ``<result-var>`` variable -1 if there are any errors running - the command and prevent ctest from returning non-zero if an error occurs. + Store in the ``<result-var>`` variable ``-1`` if there are any errors running + the command and prevent :manual:`ctest(1)` from returning non-zero if an + error occurs. ``QUIET`` .. versionadded:: 3.3
diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst index c1862df..47dfe23 100644 --- a/Help/command/ctest_test.rst +++ b/Help/command/ctest_test.rst
@@ -109,8 +109,8 @@ .. versionadded:: 3.29 - The ``<level>`` may be omitted, or ``0``, to let ctest use a default - level of parallelism, or unbounded parallelism, respectively, as + The ``<level>`` may be omitted, or ``0``, to let :manual:`ctest(1)` use a + default level of parallelism, or unbounded parallelism, respectively, as documented by the :option:`ctest --parallel` option. ``RESOURCE_SPEC_FILE <file>`` @@ -170,8 +170,9 @@ ``CAPTURE_CMAKE_ERROR <result-var>`` .. versionadded:: 3.7 - Store in the ``<result-var>`` variable -1 if there are any errors running - the command and prevent ctest from returning non-zero if an error occurs. + Store in the ``<result-var>`` variable ``-1`` if there are any errors running + the command and prevent :manual:`ctest(1)` from returning non-zero if an + error occurs. ``OUTPUT_JUNIT <file>`` .. versionadded:: 3.21 @@ -182,6 +183,13 @@ file is **not** uploaded to CDash because it would be redundant with CTest's ``Test.xml`` file. +``COVERAGE_TOOL <tool>`` + .. versionadded:: 4.4 + + Specify the ``<tool>`` used for collecting coverage during the running + of the tests. See the CTest :ref:`CoverageTool <ctest-CoverageTool>` + setting for details. + ``QUIET`` .. versionadded:: 3.3 @@ -194,9 +202,9 @@ :variable:`CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE` and :variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` variables, along with their corresponding :manual:`ctest(1)` command line options -:option:`--test-output-size-passed <ctest --test-output-size-passed>`, -:option:`--test-output-size-failed <ctest --test-output-size-failed>`, and -:option:`--test-output-truncation <ctest --test-output-truncation>`. +:ctest-option:`--test-output-size-passed`, +:ctest-option:`--test-output-size-failed`, and +:ctest-option:`--test-output-truncation`. .. _`Additional Test Measurements`: @@ -213,7 +221,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/ctest_update.rst b/Help/command/ctest_update.rst index 836cdf1..c20b8ae 100644 --- a/Help/command/ctest_update.rst +++ b/Help/command/ctest_update.rst
@@ -26,14 +26,15 @@ ``CAPTURE_CMAKE_ERROR <result-var>`` .. versionadded:: 3.13 - Store in the ``<result-var>`` variable -1 if there are any errors running - the command and prevent ctest from returning non-zero if an error occurs. + Store in the ``<result-var>`` variable ``-1`` if there are any errors running + the command and prevent :manual:`ctest(1)` from returning non-zero if an + error occurs. ``QUIET`` .. versionadded:: 3.3 - Tell CTest to suppress most non-error messages that it would - have otherwise printed to the console. CTest will still report + Suppress any CTest-specific non-error messages that would have otherwise + been printed to the console. CTest will still report the new revision of the repository and any conflicting files that were found.
diff --git a/Help/command/ctest_upload.rst b/Help/command/ctest_upload.rst index 344979a..2c0f8b2 100644 --- a/Help/command/ctest_upload.rst +++ b/Help/command/ctest_upload.rst
@@ -13,14 +13,15 @@ Specify a list of files to be sent along with the build results to the dashboard server. +``CAPTURE_CMAKE_ERROR <result-var>`` + .. versionadded:: 3.7 + + Store in the ``<result-var>`` variable ``-1`` if there are any errors running + the command and prevent :manual:`ctest(1)` from returning non-zero if an + error occurs. + ``QUIET`` .. versionadded:: 3.3 Suppress any CTest-specific non-error output that would have been printed to the console otherwise. - -``CAPTURE_CMAKE_ERROR <result-var>`` - .. versionadded:: 3.7 - - Store in the ``<result-var>`` variable -1 if there are any errors running - the command and prevent ctest from returning non-zero if an error occurs.
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/discover_tests.rst b/Help/command/discover_tests.rst new file mode 100644 index 0000000..39bd192 --- /dev/null +++ b/Help/command/discover_tests.rst
@@ -0,0 +1,117 @@ +discover_tests +-------------- + +Register tests with names and properties discovered at test time by +:manual:`ctest(1)`. + +.. code-block:: cmake + + discover_tests(COMMAND <command> [<arg>...] [COMMAND_EXPAND_LISTS] + [CONFIGURATIONS <config>...] + DISCOVERY_ARGS <arg>... + DISCOVERY_MATCH <regex> + [DISCOVERY_PROPERTIES <key> <value> [<key> <value>]...] + TEST_NAME <replacement> + TEST_ARGS <replacement>... + [TEST_PROPERTIES <key> <replacement> [<key> <replacement>]...] + ) + +This command configures test discovery rather than defining a single test at +configure time. During test execution, :manual:`ctest(1)` runs the specified +discovery command, parses its output, and registers one or more tests based on +the provided regular expression and replacement strings. + +``discover_tests`` options are: + +``COMMAND`` + Specify the command-line used for test discovery. + + The command is executed by :manual:`ctest(1)` at test time (not by CMake at + configure time). With ``DISCOVERY_ARGS`` appended, it must print the list of + available tests in a format matched by ``DISCOVERY_MATCH``. + + If ``<command>`` specifies an executable target created by + :command:`add_executable`: + + * It will automatically be replaced by the location of the executable + created at build time. + + * The target's :prop_tgt:`CROSSCOMPILING_EMULATOR`, if set, will be + used to run the command on the host:: + + <emulator> <command> + + The emulator is used only when + :variable:`cross-compiling <CMAKE_CROSSCOMPILING>`. + + * The target's :prop_tgt:`TEST_LAUNCHER`, if set, will be used to launch the + command:: + + <launcher> <command> + + If the :prop_tgt:`CROSSCOMPILING_EMULATOR` is also set, both are used:: + + <launcher> <emulator> <command> + + The command may be specified using + :manual:`generator expressions <cmake-generator-expressions(7)>`. + +``COMMAND_EXPAND_LISTS`` + Lists in ``COMMAND`` arguments will be expanded, including those created with + :manual:`generator expressions <cmake-generator-expressions(7)>`. + +``CONFIGURATIONS`` + Restrict the test discovery only to the named configurations. + +``DISCOVERY_ARGS`` + Additional arguments passed to ``COMMAND`` when performing discovery. + +``DISCOVERY_MATCH`` + Regular expression used to parse each line produced by the discovery command. + Capturing groups may be referenced by ``TEST_NAME``, ``TEST_ARGS``, and + values in ``TEST_PROPERTIES`` using ``\1``, ``\2``, etc. + +``DISCOVERY_PROPERTIES`` + Specify properties for the discovery run itself. + +``TEST_NAME`` + Replacement string used to generate the test name for each discovered test. + It may reference capture groups from ``DISCOVERY_MATCH``. + +``TEST_ARGS`` + Replacement strings used to generate the arguments passed to the discovered + test. Each argument may reference capture groups from ``DISCOVERY_MATCH``. + +``TEST_PROPERTIES`` + Specify test properties to set on each discovered test. Values are + replacement strings and may reference capture groups from + ``DISCOVERY_MATCH``. + +CTest executes the discovery step to obtain the list of tests and then runs +each discovered test using the command-line produced by ``COMMAND`` together +with ``TEST_ARGS``. The pass/fail behavior of each discovered test follows +the usual CTest rules (exit code ``0`` indicates success unless inverted by +the :prop_test:`WILL_FAIL` property). Output written to stdout or stderr is +captured by :manual:`ctest(1)` and only affects the pass/fail status via the +:prop_test:`PASS_REGULAR_EXPRESSION`, :prop_test:`FAIL_REGULAR_EXPRESSION`, +or :prop_test:`SKIP_REGULAR_EXPRESSION` test properties. + +Example usage: + +.. code-block:: cmake + + discover_tests(COMMAND testDriver --exe $<TARGET_FILE:myexe> + DISCOVERY_ARGS --list-tests + DISCOVERY_MATCH "^([^,]+),([^,]+),([^,]+),(.*)$" + TEST_NAME "${PROJECT_NAME}.\\1.\\2" + TEST_ARGS --run-test "\\1.\\2" + TEST_PROPERTIES + PROCESSORS "\\3" + LABELS "\\4" + ) + +This example configures discovery by running ``testDriver --list-tests``. +For each line of output that matches ``DISCOVERY_MATCH``, a test name is +generated using ``TEST_NAME``, the per-test command-line is generated using +``TEST_ARGS``, and test properties are populated from the remaining capture +groups.
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..429be72 100644 --- a/Help/command/execute_process.rst +++ b/Help/command/execute_process.rst
@@ -22,6 +22,8 @@ [OUTPUT_STRIP_TRAILING_WHITESPACE] [ERROR_STRIP_TRAILING_WHITESPACE] [ENCODING <name>] + [ENVIRONMENT <variable=value>...] + [ENVIRONMENT_MODIFICATION <env-mod-op>...] [ECHO_OUTPUT_VARIABLE] [ECHO_ERROR_VARIABLE] [COMMAND_ERROR_IS_FATAL <ANY|LAST|NONE>]) @@ -75,7 +77,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 @@ -186,6 +189,27 @@ `UTF-8 RFC <https://datatracker.ietf.org/doc/html/rfc3629>`_ naming convention. +``ENVIRONMENT <variable=value>...`` + .. versionadded:: 4.4 + + Add environment variable definitions to the environment of the child + processes. Each entry must be of the form ``NAME=value`` and is interpreted + as setting ``NAME`` to ``value`` for the duration of the + ``execute_process()`` call. + + These entries are processed in order. If the same variable name is given + multiple times, the last value wins. + +``ENVIRONMENT_MODIFICATION <env-mod-op>...`` + .. versionadded:: 4.4 + + Apply one or more :prop_test:`ENVIRONMENT_MODIFICATION` operations to the + environment of the child processes. Each operation is applied in the given + order, and failures to parse an operation are treated as errors. + + Environment modifications are applied after ``ENVIRONMENT`` entries, if both + options are specified. + ``COMMAND_ERROR_IS_FATAL <ANY|LAST|NONE>`` .. versionadded:: 3.19
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..42b0871 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 ^^^^^^^^ @@ -43,7 +43,7 @@ file(`COPY_FILE`_ <oldname> <newname> [...]) file({`COPY`_ | `INSTALL`_} <file>... DESTINATION <dir> [...]) file(`SIZE`_ <filename> <out-var>) - file(`READ_SYMLINK`_ <linkname> <out-var>) + file(`READ_SYMLINK`_ <linkname> <out-var> [...]) file(`CREATE_LINK`_ <original> <linkname> [...]) file(`CHMOD`_ <files>... <directories>... PERMISSIONS <permissions>... [...]) file(`CHMOD_RECURSE`_ <files>... <directories>... PERMISSIONS <permissions>... [...]) @@ -577,13 +577,21 @@ pointing to a file and is readable. .. signature:: - file(READ_SYMLINK <linkname> <variable>) + file(READ_SYMLINK <linkname> <variable> [RESULT <result>]) .. versionadded:: 3.14 Query the symlink ``<linkname>`` and stores the path it points to - in the result ``<variable>``. If ``<linkname>`` does not exist - or is not a symlink, CMake issues a fatal error. + in the result ``<variable>``. + + The options are: + + ``RESULT <result>`` + .. versionadded:: 4.4 + + Capture the status of the operation in a ``<result>`` variable. The + variable is set to ``0`` on success or an error message otherwise. + If not specified, and the operation fails, a fatal error is emitted. Note that this command returns the raw symlink path and does not resolve a relative path. The following is an example of how to ensure that an @@ -606,7 +614,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 +628,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 +722,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). @@ -912,7 +927,9 @@ [FORMAT <format>] [COMPRESSION <compression> [COMPRESSION_LEVEL <compression-level>]] + [ENCODING <encoding>] [MTIME <mtime>] + [THREADS <number>] [WORKING_DIRECTORY <dir>] [VERBOSE]) :target: ARCHIVE_CREATE @@ -931,17 +948,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 +1005,64 @@ 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. + + ``ENCODING <encoding>`` + .. versionadded:: 4.4 + + Specify the pathname character encoding used in the archive. + + The ``<encoding>`` may be one of: + + ``UTF-8`` + Archive pathnames are encoded as UTF-8. + + In CMake 4.4 and below, this is the default. + See policy :policy:`CMP0213` for CMake 4.3 and below compatibility + details. + + ``OEM`` + On Windows platforms, pathnames are encoded as using the original + equipment manufacturer (OEM) code page. On non-Windows platforms, + pathnames are encoded according to the current locale. + + In CMake 4.3 and below, the ``OEM`` encoding (current locale) + was always used. + + ``UTF-16LE``, ``UTF-16BE`` + Archive pathnames are encoded as UTF-16 little-endian or big-endian. + + ``...`` + Any encoding name supported by ``iconv`` on the current platform. + On Windows, code page names may be specified. + + .. note:: + ``7zip`` archives always encode paths as ``UTF-16LE``, + so this option is silently ignored for that 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 @@ -972,6 +1078,7 @@ file(ARCHIVE_EXTRACT INPUT <archive> [DESTINATION <dir>] + [ENCODING <encoding>] [PATTERNS <pattern>...] [LIST_ONLY] [VERBOSE] @@ -990,6 +1097,41 @@ If ``DESTINATION`` is not given, the current binary directory will be used. + ``ENCODING <encoding>`` + .. versionadded:: 4.4 + + Specify the pathname character encoding used in the archive. + + The ``<encoding>`` may be one of: + + ``UTF-8`` + Archive pathnames are encoded as UTF-8. + + In CMake 4.3 and below, this is the default + if the :policy:`CMP0213` is ``NEW``. + + ``OEM`` + On Windows platforms, pathnames are encoded as using the original + equipment manufacturer (OEM) code page. On non-Windows platforms, + pathnames are encoded according to the current locale. + + In CMake 4.3 and below, the ``OEM`` encoding (current locale) + was always used. + + In CMake 4.4 and above, the ``OEM`` encoding (current locale) + is only used if the :policy:`CMP0213` is not ``NEW``. + + ``UTF-16LE``, ``UTF-16BE`` + Archive pathnames are encoded as UTF-16 little-endian or big-endian. + + ``...`` + Any encoding name supported by ``iconv`` on the current platform. + On Windows, code page names may be specified. + + .. note:: + ``7zip`` archives always encode paths as ``UTF-16LE``, + so this option is silently ignored for that format. + ``PATTERNS <pattern>...`` Extract/list only files and directories that match one of the given patterns. Wildcards are supported. If the ``PATTERNS`` option is @@ -1007,6 +1149,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 +1266,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..6433e45 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst
@@ -41,19 +41,21 @@ 1. `Parentheses`_. -2. Unary tests such as `COMMAND`_, `POLICY`_, `TARGET`_, `TEST`_, - `EXISTS`_, `IS_READABLE`_, `IS_WRITABLE`_, `IS_EXECUTABLE`_, - `IS_DIRECTORY`_, `IS_SYMLINK`_, `IS_ABSOLUTE`_, and `DEFINED`_. +2. Unary tests such as: -3. Binary tests such as `EQUAL`_, `LESS`_, `LESS_EQUAL`_, `GREATER`_, - `GREATER_EQUAL`_, `STREQUAL`_, `STRLESS`_, `STRLESS_EQUAL`_, - `STRGREATER`_, `STRGREATER_EQUAL`_, `VERSION_EQUAL`_, `VERSION_LESS`_, - `VERSION_LESS_EQUAL`_, `VERSION_GREATER`_, `VERSION_GREATER_EQUAL`_, - `PATH_EQUAL`_, `IN_LIST`_, `IS_NEWER_THAN`_, and `MATCHES`_. + * The `Existence Checks`_ :cref:`COMMAND`, :cref:`POLICY`, :cref:`TARGET`, + :cref:`TEST`, :cref:`EXISTS`, and :cref:`DEFINED`. + * The `File Operations`_ :cref:`IS_READABLE`, :cref:`IS_WRITABLE`, + :cref:`IS_EXECUTABLE`, :cref:`IS_DIRECTORY`, :cref:`IS_SYMLINK`, and + :cref:`IS_ABSOLUTE`. -4. Unary logical operator `NOT`_. +3. Binary tests such as those described in `Comparisons`_, + `Version Comparisons`_, and `Path Comparisons`_, as well as :cref:`IN_LIST` + and :cref:`IS_NEWER_THAN`. -5. Binary logical operators `AND`_ and `OR`_, from left to right, +4. Unary logical operator :cref:`NOT`. + +5. Binary logical operators :cref:`AND` and :cref:`OR`, from left to right, without any short-circuit. Basic Expressions @@ -181,7 +183,7 @@ False if the given path is an empty string. .. note:: - Prefer ``if(IS_READABLE)`` to check file readability. ``if(EXISTS)`` + Prefer :command:`if(IS_READABLE)` to check file readability. ``if(EXISTS)`` may be changed in the future to only check file existence. .. signature:: if(IS_READABLE <path-to-file-or-directory>) @@ -228,7 +230,7 @@ time stamps are exactly the same, an ``IS_NEWER_THAN`` comparison returns true, so that any dependent build operations will occur in the event of a tie. This includes the case of passing the same file name for - both file1 and file2. + both ``file1`` and ``file2``. .. signature:: if(IS_DIRECTORY <path>) @@ -262,10 +264,8 @@ :target: MATCHES True if the given string or variable's value matches the given regular - expression. See :ref:`Regex Specification` for regex format. - - .. versionadded:: 3.9 - ``()`` groups are captured in :variable:`CMAKE_MATCH_<n>` variables. + expression. See :ref:`Regex Specification` for regex format. ``()`` groups + are captured in :variable:`CMAKE_MATCH_<n>` variables. .. signature:: if(<variable|string> LESS <variable|string>) :target: LESS @@ -415,7 +415,7 @@ ... endif() - See :ref:`cmake_path(COMPARE) <Path COMPARE>` for more details. + See :command:`cmake_path(COMPARE)` for more details. Variable Expansion ^^^^^^^^^^^^^^^^^^ @@ -452,40 +452,40 @@ Automatic evaluation applies in the other cases whenever the above-documented condition syntax accepts ``<variable|string>``: -* The left hand argument to `MATCHES`_ is first checked to see if it is +* The left hand argument to :cref:`MATCHES` is first checked to see if it is a defined variable. If so, the variable's value is used, otherwise the original value is used. -* If the left hand argument to `MATCHES`_ is missing it returns false +* If the left hand argument to :cref:`MATCHES` is missing it returns false without error -* Both left and right hand arguments to `LESS`_, `GREATER`_, `EQUAL`_, - `LESS_EQUAL`_, and `GREATER_EQUAL`_, are independently tested to see if - they are defined variables. If so, their defined values are used otherwise - the original value is used. +* Both left and right hand arguments to :cref:`LESS`, :cref:`GREATER`, + :cref:`EQUAL`, :cref:`LESS_EQUAL`, and :cref:`GREATER_EQUAL` are + independently tested to see if they are defined variables. If so, their + defined values are used; otherwise the original value is used. -* Both left and right hand arguments to `STRLESS`_, `STRGREATER`_, - `STREQUAL`_, `STRLESS_EQUAL`_, and `STRGREATER_EQUAL`_ are independently - tested to see if they are defined variables. If so, their defined values are - used otherwise the original value is used. +* Both left and right hand arguments to :cref:`STRLESS`, :cref:`STRGREATER`, + :cref:`STREQUAL`, :cref:`STRLESS_EQUAL`, and :cref:`STRGREATER_EQUAL` are + independently tested to see if they are defined variables. If so, their + defined values are used; otherwise the original value is used. -* Both left and right hand arguments to `VERSION_LESS`_, - `VERSION_GREATER`_, `VERSION_EQUAL`_, `VERSION_LESS_EQUAL`_, and - `VERSION_GREATER_EQUAL`_ are independently tested to see if they are defined - variables. If so, their defined values are used otherwise the original value - is used. +* Both left and right hand arguments to :cref:`VERSION_LESS`, + :cref:`VERSION_GREATER`, :cref:`VERSION_EQUAL`, :cref:`VERSION_LESS_EQUAL`, + and :cref:`VERSION_GREATER_EQUAL` are independently tested to see if they are + defined variables. If so, their defined values are used; otherwise the + original value is used. -* The left hand argument to `IN_LIST`_ is tested to see if it is a defined - variable. If so, the variable's value is used, otherwise the original +* The left hand argument to :cref:`IN_LIST` is tested to see if it is a defined + variable. If so, the variable's value is used; otherwise the original value is used. -* The right hand argument to `NOT`_ is tested to see if it is a boolean - constant. If so, the value is used, otherwise it is assumed to be a +* The right hand argument to :cref:`NOT` is tested to see if it is a boolean + constant. If so, the value is used; otherwise it is assumed to be a variable and it is dereferenced. -* The left and right hand arguments to `AND`_ and `OR`_ are independently - tested to see if they are boolean constants. If so, they are used as - such, otherwise they are assumed to be variables and are dereferenced. +* The left and right hand arguments to :cref:`AND` and :cref:`OR` are + independently tested to see if they are boolean constants. If so, they are + used as such, otherwise they are assumed to be variables and are dereferenced. .. versionchanged:: 3.1 To prevent ambiguity, potential variable or keyword names can be
diff --git a/Help/command/include.rst b/Help/command/include.rst index 80968da..9e87db0 100644 --- a/Help/command/include.rst +++ b/Help/command/include.rst
@@ -6,7 +6,7 @@ .. code-block:: cmake include(<file|module> [OPTIONAL] [RESULT_VARIABLE <var>] - [NO_POLICY_SCOPE]) + [NO_POLICY_SCOPE] [NO_DIAGNOSTIC_SCOPE]) Loads and runs CMake code from the file given. Variable reads and writes access the scope of the caller (dynamic scoping). If ``OPTIONAL`` @@ -23,3 +23,6 @@ See the :command:`cmake_policy` command documentation for discussion of the ``NO_POLICY_SCOPE`` option. + +See the :command:`cmake_diagnostic` command documentation for discussion of the +``NO_DIAGNOSTIC_SCOPE`` option.
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/include/SUPPORTED_LANGUAGES.rst b/Help/command/include/SUPPORTED_LANGUAGES.rst index a98c07a..9e84190 100644 --- a/Help/command/include/SUPPORTED_LANGUAGES.rst +++ b/Help/command/include/SUPPORTED_LANGUAGES.rst
@@ -1,25 +1,59 @@ +The supported languages are: -Supported languages are ``C``, ``CXX`` (i.e. C++), ``CSharp`` (i.e. C#), ``CUDA``, -``OBJC`` (i.e. Objective-C), ``OBJCXX`` (i.e. Objective-C++), ``Fortran``, ``HIP``, -``ISPC``, ``Swift``, ``ASM``, ``ASM_NASM``, ``ASM_MARMASM``, ``ASM_MASM``, and ``ASM-ATT``. +``C`` +``CXX`` + C++ + +``CSharp`` .. versionadded:: 3.8 - Added ``CSharp`` and ``CUDA`` support. - .. versionadded:: 3.15 - Added ``Swift`` support. + C# +``CUDA`` + .. versionadded:: 3.8 + +``OBJC`` .. versionadded:: 3.16 - Added ``OBJC`` and ``OBJCXX`` support. - .. versionadded:: 3.18 - Added ``ISPC`` support. + Objective-C +``OBJCXX`` + .. versionadded:: 3.16 + + Objective-C++ + +``Fortran`` + +``HIP`` .. versionadded:: 3.21 - Added ``HIP`` support. +``ISPC`` + .. versionadded:: 3.18 + +``Swift`` + .. versionadded:: 3.15 + +``ASM`` + Assembly language supported by the C compiler. + + If enabling ``ASM``, list it last so that CMake can check + whether the ``C`` or ``CXX`` compiler supports assembly. + +``ASM_NASM`` + Netwide Assembler + +``ASM_MARMASM`` .. versionadded:: 3.26 - Added ``ASM_MARMASM`` support. -If enabling ``ASM``, list it last so that CMake can check whether -compilers for other languages like ``C`` work for assembly too. + Microsoft Assembler (ARM, ARM64) + +``ASM_MASM`` + Microsoft Assembler (x86, x64) + +.. FIXME(#21536): ``ASM_POASM`` + .. versionadded:: 4.4 + + Pelles C toolchain assembler. + +``ASM-ATT``
diff --git a/Help/command/install.rst b/Help/command/install.rst index 033c5c6..e69d266 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 ^^^^^^^^^^^^ @@ -59,6 +60,10 @@ ``<dir>`` should be a relative path. An absolute path is allowed, but not recommended. + .. versionadded:: 4.4 + The :diagnostic:`CMD_INSTALL_ABSOLUTE_DESTINATION` diagnostic can be + enabled to warn or error out when an absolute destination is provided. + When a relative path is given, it is interpreted relative to the value of the :variable:`CMAKE_INSTALL_PREFIX` variable. The prefix can be relocated at install time using the ``DESTDIR`` @@ -200,6 +205,8 @@ - DLLs (these go to ``RUNTIME``, see below), - on macOS when marked as ``FRAMEWORK`` (see below). + * *Module libraries* + ``RUNTIME`` Target artifacts of this kind include: @@ -242,7 +249,10 @@ File sets are defined by the :command:`target_sources(FILE_SET)` command. If the file set ``<set-name>`` exists and is ``PUBLIC`` or ``INTERFACE``, - any files in the set are installed under the destination (see below). + any files in the set of type ``HEADERS`` are installed under + the destination (see below). Other types do not have any default + destination, so ``DESTINATION`` option must be specified for each + ``FILE_SET``. The directory structure relative to the file set's base directories is preserved. For example, a file added to the file set as ``/blah/include/myproj/here.h`` with a base directory ``/blah/include`` @@ -262,12 +272,13 @@ ``DESTINATION`` is omitted, a default destination will be taken from the appropriate variable from :module:`GNUInstallDirs`, or set to a built-in default value if that variable is not defined. The same is true for file - sets, and the public and private headers associated with the installed - targets through the :prop_tgt:`PUBLIC_HEADER` and :prop_tgt:`PRIVATE_HEADER` - target properties. A destination must always be provided for module libraries, - Apple bundles and frameworks. A destination can be omitted for interface and - object libraries, but they are handled differently (see the discussion of this - topic toward the end of this section). + sets of type ``HEADERS``, and the public and private headers associated with + the installed targets through the :prop_tgt:`PUBLIC_HEADER` and + :prop_tgt:`PRIVATE_HEADER` target properties. A destination must always be + provided for module libraries, Apple bundles and frameworks. A destination + can be omitted for interface and object libraries, but they are handled + differently (see the discussion of this topic toward the end of this + section). For shared libraries on DLL platforms, if neither ``RUNTIME`` nor ``ARCHIVE`` destinations are specified, both the ``RUNTIME`` and ``ARCHIVE`` components are @@ -497,7 +508,7 @@ [CONFIGURATIONS <config>...] [COMPONENT <component>] [OPTIONAL] [EXCLUDE_FROM_ALL] - ] [...] + ]... ) The ``IMPORTED_RUNTIME_ARTIFACTS`` form specifies rules for installing the @@ -550,7 +561,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 +802,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 +829,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 +985,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 +1001,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 +1062,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 +1114,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 +1145,7 @@ [COMPONENT <component>] [NAMELINK_COMPONENT <component>] [OPTIONAL] [EXCLUDE_FROM_ALL] - ] [...] + ]... [PRE_INCLUDE_REGEXES <regex>...] [PRE_EXCLUDE_REGEXES <regex>...] [POST_INCLUDE_REGEXES <regex>...] @@ -1158,6 +1201,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 +1412,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/list.rst b/Help/command/list.rst index abae8d2..1280c40 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst
@@ -19,7 +19,7 @@ `Modification`_ list(`APPEND`_ <list> [<element>...]) - list(`FILTER`_ <list> {INCLUDE | EXCLUDE} REGEX <regex>) + list(`FILTER`_ <list> <INCLUDE|EXCLUDE> <MODE>) list(`INSERT`_ <list> <index> [<element>...]) list(`POP_BACK`_ <list> [<out-var>...]) list(`POP_FRONT`_ <list> [<out-var>...]) @@ -120,15 +120,54 @@ that empty list. .. signature:: - list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>) + list(FILTER <list> <INCLUDE|EXCLUDE> <MODE>) -.. versionadded:: 3.6 + .. versionadded:: 3.6 -Includes or removes items from the list that match the mode's pattern. -In ``REGEX`` mode, items will be matched against the given regular expression. + Includes or removes items from the list that match the mode's pattern. -For more information on regular expressions look under -:ref:`string(REGEX) <Regex Specification>`. + ``<MODE>`` must be one of the following: + + ``REGEX`` + Items will be matched against the given regular expression. + + .. code-block:: cmake + + list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>) + + For more information on regular expressions look under + :ref:`string(REGEX) <Regex Specification>`. + + ``PREDICATE`` + Specify a user-defined callable as a predicate. + + .. code-block:: cmake + + list(FILTER <list> <INCLUDE|EXCLUDE> PREDICATE <function>) + + .. versionadded:: 4.4 + + ``<function>`` is a user-defined :command:`function` that acts as a + unary predicate. The callable must accept exactly two parameters: the + input value and the name of an output variable. The callable must set the + output variable to a boolean value in the calling scope. + The output variable is interpreted using standard CMake boolean evaluation. + If the callable does not set the output variable, it is an error. + + Example: + + .. code-block:: cmake + + function(file_exists path result) + if(EXISTS "${path}") + set(${result} TRUE PARENT_SCOPE) + else() + set(${result} FALSE PARENT_SCOPE) + endif() + endfunction() + + set(candidate_files main.c missing.c utils.c) + list(FILTER candidate_files INCLUDE PREDICATE file_exists) .. signature:: list(INSERT <list> <element_index> <element> [<element> ...]) @@ -203,8 +242,7 @@ the other ones will remain the same as before the transformation. ``<ACTION>`` specifies the action to apply to the elements of the list. - The actions have exactly the same semantics as sub-commands of the - :command:`string` command. ``<ACTION>`` must be one of the following: + ``<ACTION>`` must be one of the following: :command:`APPEND <string(APPEND)>`, :command:`PREPEND <string(PREPEND)>` Append, prepend specified value to each element of the list. @@ -251,6 +289,45 @@ element instead of the beginning of each repeated search. See policy :policy:`CMP0186`. + ``APPLY`` + Invoke a user-defined callable for each element of the list. + The callable must accept exactly two parameters: the input value and the + name of an output variable. The callable must set the output variable + in the calling scope. + + .. signature:: + list(TRANSFORM <list> APPLY <function> ...) + :target: TRANSFORM_APPLY + + .. versionadded:: 4.4 + + ``<function>`` is a :command:`function` with exactly two formal parameters. + Set the output variable via + :command:`set(\<variable\> \<value\> PARENT_SCOPE) <set>`: + + .. code-block:: cmake + + function(<function> <input> <output>) + # Transform <input>, store result in ${<output>} + set(${<output>} "<result>" PARENT_SCOPE) + endfunction() + + Before each invocation, the output variable is unset in the calling scope + to prevent stale values. + + Example: + + .. code-block:: cmake + + function(make_absolute in out) + cmake_path(ABSOLUTE_PATH in BASE_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}") + set(${out} "${in}" PARENT_SCOPE) + endfunction() + + set(mylist main.c utils.c io.c) + list(TRANSFORM mylist APPLY make_absolute) + # mylist is now absolute paths relative to CMAKE_CURRENT_SOURCE_DIR + ``<SELECTOR>`` determines which elements of the list will be transformed. Only one type of selector can be specified at a time. When given, ``<SELECTOR>`` must be one of the following: @@ -278,6 +355,39 @@ list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...) + ``PREDICATE`` + Specify a user-defined callable as a predicate. + Only elements for which the callable returns a true value will be + transformed. + + .. code-block:: cmake + + list(TRANSFORM <list> <ACTION> PREDICATE <function> ...) + + .. versionadded:: 4.4 + + ``<function>`` is a user-defined :command:`function` with exactly + two formal parameters: the input value and the name of an output + variable. The callable must set the output variable to a boolean + value. Standard CMake boolean evaluation is used. + If the callable does not set the output variable, it is an error. + + Example: + + .. code-block:: cmake + + function(is_relative path result) + if(NOT IS_ABSOLUTE "${path}") + set(${result} TRUE PARENT_SCOPE) + else() + set(${result} FALSE PARENT_SCOPE) + endif() + endfunction() + + set(search_paths /usr/include src lib /opt/lib) + list(TRANSFORM search_paths PREPEND "${CMAKE_CURRENT_SOURCE_DIR}/" + PREDICATE is_relative) + Ordering ^^^^^^^^ @@ -289,6 +399,7 @@ .. signature:: list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>]) + list(SORT <list> COMPARATOR <function> [CASE <case>] [ORDER <order>]) Sorts the list in-place alphabetically. @@ -337,3 +448,47 @@ ``DESCENDING`` Sorts the list in descending order. + + Instead of the built-in ``COMPARE`` methods, a user-defined comparison + function may be used with the ``COMPARATOR`` keyword. + + .. versionadded:: 4.4 + + ``COMPARATOR`` is mutually exclusive with ``COMPARE``. The ``CASE`` + and ``ORDER`` options may still be used alongside ``COMPARATOR``: + the ``CASE`` filter is applied to both values before they are passed to + the callable, and ``ORDER DESCENDING`` reverses the comparison by + swapping the two arguments. + + The callable must accept exactly three parameters: two input values and + the name of an output variable. It must set the output variable to a + boolean value (``TRUE`` if the first value should come before the second, + ``FALSE`` otherwise) in the calling scope. + If the callable does not set the output variable, it is an error. + + The comparator must define a + `strict weak ordering <https://en.wikipedia.org/wiki/Weak_ordering#Strict_weak_orderings>`_. + In particular: + + * It must return ``FALSE`` when comparing an element to itself + (irreflexivity). + * If it returns ``TRUE`` for ``(a, b)``, it must return ``FALSE`` + for ``(b, a)`` (asymmetry). + + An error is raised if the comparator violates these requirements. + + Example: + + .. code-block:: cmake + + function(version_less a b result) + if("${a}" VERSION_LESS "${b}") + set(${result} TRUE PARENT_SCOPE) + else() + set(${result} FALSE PARENT_SCOPE) + endif() + endfunction() + + set(versions 3.1 1.2 2.0 1.10) + list(SORT versions COMPARATOR version_less) + # versions is now: 1.2;1.10;2.0;3.1
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..0646116 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. @@ -143,18 +175,17 @@ Selects which programming languages are needed to build the project. -.. include:: include/SUPPORTED_LANGUAGES.rst + .. include:: include/SUPPORTED_LANGUAGES.rst By default ``C`` and ``CXX`` are enabled if no language options are given. Specify language ``NONE``, or use the ``LANGUAGES`` keyword and list no languages, to skip enabling any languages. -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..6564ec5 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,10 @@ <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>] + `PARTIAL_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 +298,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 +556,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 +568,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 +638,49 @@ 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>] + PARTIAL_EQUAL <json-pattern> <json-actual>) + :target: JSON-PARTIAL_EQUAL + + .. versionadded:: 4.4 + + Compare two JSON values using *partial* equality. The first argument + (``<json-pattern>``) is treated as a pattern to match against the second + argument (``<json-actual>``), which is treated as the complete JSON value. + The contents of ``<json-pattern>`` and ``<json-actual>`` must be valid JSON. + + The ``<out-var>`` will be set to a true value if ``<json-pattern>`` is + contained within ``<json-actual>`` according to the rules below, or a false + value otherwise. + + Partial equality is not symmetric. In general, + ``PARTIAL_EQUAL(A, B)`` and ``PARTIAL_EQUAL(B, A)`` may produce different + results. + + Matching rules: + + * **Scalars** (null, number, string, boolean) must match exactly. + * **Objects** match if every member in ``<json-pattern>`` exists in + ``<json-actual>`` and the corresponding values also match recursively. + Extra members in ``<json-actual>`` are ignored. + * **Arrays** match if every element in ``<json-pattern>`` matches a + distinct element in ``<json-actual>`` recursively. Once an element in + ``<json-actual>`` successfully matches an element in ``<json-pattern>``, + it is consumed and cannot be reused to match any subsequent elements. + Array element order is not significant. Extra elements in + ``<json-actual>`` are ignored. + + Type differences do not match (for example, an object does not match an + array, and a string does not match a number). + +.. 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..374d828 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,19 +70,37 @@ .. code-block:: cmake target_sources(<target> - [<INTERFACE|PUBLIC|PRIVATE> + [{INTERFACE|PUBLIC|PRIVATE} [FILE_SET <set> [TYPE <type>] [BASE_DIRS <dirs>...] [FILES <files>...]]... ]...) Adds a file set to a target, or adds files to an existing file set. Targets have zero or more named file sets. Each file set has a name, a type, a scope of ``INTERFACE``, ``PUBLIC``, or ``PRIVATE``, one or more base directories, and -files within those directories. The acceptable types include: +files within those directories. + +.. versionchanged:: 4.4 + A file may only belong to at most one file set in a target. See policy + :policy:`CMP0211`. + + The acceptable types include: ``HEADERS`` Sources intended to be used via a language's ``#include`` mechanism. +``SOURCES`` + .. versionadded:: 4.4 + + Specifies sources to use when building a target and/or its dependents. + With the scope ``PRIVATE`` and ``PUBLIC``, items will populate the + :prop_fs:`SOURCES` property of ``<set>``, which are used when building the + target itself. With the scope ``PUBLIC`` and ``INTERFACE``, items will + populate the :prop_fs:`INTERFACE_SOURCES` property of ``<set>``, which are + used when building dependents. The sources specified by the + :prop_fs:`INTERFACE_SOURCES` property are propagated, transitively, to all + the dependents. + ``CXX_MODULES`` .. versionadded:: 3.28 @@ -91,7 +109,8 @@ ``INTERFACE`` scope except on ``IMPORTED`` targets. The optional default file sets are named after their type. The target may not -be a custom target or :prop_tgt:`FRAMEWORK` target. +be a custom target or, for ``HEADERS`` and ``CXX_MODULES`` types, a +:prop_tgt:`FRAMEWORK` target. Files in a ``PRIVATE`` or ``PUBLIC`` file set are marked as source files for the purposes of IDE integration. Additionally, files in ``HEADERS`` file sets @@ -100,8 +119,8 @@ :command:`install(TARGETS)` command, and exported with the :command:`install(EXPORT)` and :command:`export` commands. -Each ``target_sources(FILE_SET)`` entry starts with ``INTERFACE``, ``PUBLIC``, or -``PRIVATE`` and accepts the following arguments: +Each ``target_sources(FILE_SET)`` entry starts with ``INTERFACE``, ``PUBLIC``, +or ``PRIVATE`` and accepts the following arguments: ``FILE_SET <set>`` @@ -158,6 +177,15 @@ * :prop_tgt:`HEADER_DIRS` * :prop_tgt:`HEADER_DIRS_<NAME>` +For file sets of type ``SOURCES``: + +* :prop_tgt:`SOURCE_SETS` +* :prop_tgt:`INTERFACE_SOURCE_SETS` +* :prop_tgt:`SOURCE_SET` +* :prop_tgt:`SOURCE_SET_<NAME>` +* :prop_tgt:`SOURCE_DIRS` +* :prop_tgt:`SOURCE_DIRS_<NAME>` + For file sets of type ``CXX_MODULES``: * :prop_tgt:`CXX_MODULE_SETS`
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..3560bed 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,36 @@ 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. + +.. variable:: CPACK_ARCHIVE_ENCODING + + .. versionadded:: 4.4 + + Specify the pathname character encoding used in package archives. + + :Default: ``UTF-8`` + + See the :option:`cmake -E tar <cmake-E tar>` tool's + :option:`--cmake-tar-encoding <cmake-E_tar --cmake-tar-encoding>` flag + for supported encoding names. + + In CMake 4.3 and below, the ``OEM`` encoding (current locale) + was always used.
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..a6bc84a 100644 --- a/Help/cpack_gen/nsis.rst +++ b/Help/cpack_gen/nsis.rst
@@ -240,3 +240,18 @@ 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``. + +.. variable:: CPACK_NSIS_IGNORE_COMPONENTS_PAGE + + .. versionadded:: 4.4 + + If set, do not display the page containing the license during installation.
diff --git a/Help/cpack_gen/rpm.rst b/Help/cpack_gen/rpm.rst index 3583765..a30b481 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 @@ -553,6 +553,10 @@ set(CPACK_RPM_SPEC_MORE_DEFINE "%define __spec_install_post /bin/true") + .. versionadded:: 4.4 + If the variable is a list, its string elements will be concatenated using + ``\n`` before being substituted into the spec template. + .. variable:: CPACK_RPM_PACKAGE_DEBUG Toggle CPack RPM generator debug output.
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..050ec07 100644 --- a/Help/dev/README.rst +++ b/Help/dev/README.rst
@@ -40,11 +40,15 @@ * The `CMake Documentation Guide`_. * The `CMake Testing Guide`_. * The `CMake Experimental Features Guide`_. +* The `CMake Debugging Guide`_. +* The `CMake Diagnostics 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 +.. _`CMake Diagnostics Guide`: diagnostics.rst Maintainer Documentation ========================
diff --git a/Help/dev/ai-policy.rst b/Help/dev/ai-policy.rst new file mode 100644 index 0000000..b18a5cd --- /dev/null +++ b/Help/dev/ai-policy.rst
@@ -0,0 +1,18 @@ +AI Policy +********* + +The CMake project supports the responsible use of AI services and tools. +Contributors are welcome to use AI tools and services to help them be more +effective, subject to the following guidelines: + +* A human author must be responsible for any submission to the CMake project's + GitLab instance or forums. This includes merge requests, issues, and forum + posts. AI tools and services must not make submissions or comments without + a human author being associated with and responsible for them. + +* All merge request submissions are expected to be fully understood by the + contributing author. + +* AI tools and services are not considered authors. They should not be listed + as co-authors, and their review is not considered adequate for demonstrating + a human author's understanding or the correctness of a proposed change.
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/diagnostics.rst b/Help/dev/diagnostics.rst new file mode 100644 index 0000000..394f4d6 --- /dev/null +++ b/Help/dev/diagnostics.rst
@@ -0,0 +1,157 @@ +CMake Diagnostics Guide +*********************** + +The following is a guide on how CMake should issue diagnostics. +See documentation on `CMake Development`_ for more information. + +.. _`CMake Development`: README.rst + +TL;DR Porting Guide (from CMake < 4.4) +====================================== + +I want to write ``IssueMessage(MessageType::AUTHOR_WARNING, ...``: + Write ``IssueDiagnostic(cmDiagnostics::CMD_AUTHOR, ...`` instead. + +I want to write ``IssueMessage(MessageType::DEPRECATION_WARNING, ...``: + Write ``IssueDiagnostic(cmDiagnostics::CMD_DEPRECATED, ...`` instead. + +I want to write ``IssueMessage(MessageType::AUTHOR_ERROR, ...``: + No, you don't. Under the old system, there isn't a meaningful difference + between ``AUTHOR_WARNING`` and ``AUTHOR_ERROR``; at least, not as arguments + to ``IssueMessage``. + +I want to write ``IssueMessage(MessageType::DEPRECATION_ERROR, ...``: + See ``AUTHOR_ERROR``. + +History +======= + +Prior to CMake 4.4, CMake did not have a formal system for issuing diagnostics. +The messaging system had message types for author diagnostics and deprecation +diagnostics which conflated category and severity. Worse, although these types +*purported* to allow the caller to specify severity, this information is not +actually honored. Other diagnostics existed which did not use these types. + +More importantly, the mechanisms for managing severity differed depending on +the diagnostic. Variables to control a diagnostic might be documented, +undocumented, or non-existent. Spelling of command-line options to control +diagnostics was inconsistent, as was the ability to make diagnostics fatal. +Adding new categories required significant effort, as the logic to handle a +diagnostic was bespoke at every layer. + +CMake Diagnostic Framework +========================== + +CMake 4.4 introduced a structured framework for issuing and managing +diagnostics. The ``cmDiagnostics.h`` header enumerates all available +diagnostic categories. All code to manage diagnostics leverages either this +table or helper code generated from the same, such that it is the *only* +non-documentation location that needs to be updated to add a new diagnostic +category. The framework is also responsible for determining the severity of a +diagnostic, based on the combination of category defaults and user preferences, +and for presenting the user with a consistent set of control mechanisms. + +Numeric identifiers associated with diagnostic categories are only used +internally and are never persisted. This means that numbers can be reassigned +at any time. This also permits ensuring that numbers are consecutive, which +allows iterating over all categories using a simple ``for`` loop. (Note that +such loops will typically start from ``1``, not ``0``, as ``0`` is reserved +for the 'NONE' category which is used primarily as a virtual parent.) Where +necessary, macros provided by ``cmDiagnostics.h`` can generate code for each +diagnostic category. + +Refer to ``Help/manual/cmake-diagnostics.7.rst`` for user-facing documentation. + +Issuing Diagnostics +=================== + +Diagnostics are the CMake equivalent of compiler warnings, with categorization +providing both additional information and additional response control to users. + +Diagnostics are issued via the ``IssueDiagnostic`` method. This method is +provided on various objects, with ``cmMakefile`` being the most prominent, and +typically exists alongside an ``IssueMessage`` method. The latter is not +deprecated, and should still be used to issue messages outside of the +diagnostic categories, such as hard errors or informational messages. + +The historic ``{AUTHOR,DEPRECATION}_{WARNING,ERROR}`` message types, however, +have been removed. These are replaced by ``IssueDiagnostic`` and the +``CMD_{AUTHOR,DEPRECATED}`` diagnostic categories. Because the methods have +similar signatures, porting in many cases can be accomplished by replacing the +method name and first argument (the former message type, newly the diagnostic +category). For example, where prior versions of CMake wrote: + +.. code:: c++ + + mf->IssueMessage(MessageType::AUTHOR_WARNING, ...); + +CMake 4.4 and later should write: + +.. code:: c++ + + mf->IssueDiagnostic(cmDiagnostics::CMD_AUTHOR, ...); + +(Note that the ``"cmDiagnostics.h"`` header may need to be newly included.) + +As previously mentioned, the purported severity was ignored by ``cmMessenger``, +which instead used its own internal state to decide whether a message should +be a warning or an error. This logic overrode the severity component of the +message type as passed into the method. As a result, although the new method +does not accept a severity, this is actually consistent with the historic +behavior and does not represent any loss of functionality. + +.. note:: + + When issuing diagnostics targeted at build-system authors, please consult the + complete list of available diagnostics, as a more specific category may be + available. In some cases, it may even make sense to add a new category. + +Adding Diagnostic Categories +============================ + +Adding new diagnostic categories involves four steps. + +1. The new category must be added to ``cmDiagnostics.h``. The diagnostics + table looks like this: + + .. code:: c++ + + #define CM_FOR_EACH_DIAGNOSTIC_TABLE(ACTION, SELECT) \ + SELECT(ACTION, Warn, CMD_NONE, CMD_AUTHOR, 12) \ + SELECT(ACTION, Warn, CMD_AUTHOR, CMD_DEPRECATED, 1) \ + ... + + Add a new entry. All entries must begin with ``SELECT(ACTION,``. The + second argument is the *default* state of the diagnostic and should + typically be ``Warn``, but may be ``Ignore`` if the diagnostic should be + opt-in. Defaulting to ``SendError`` would be exceptional, and defaulting + to ``FatalError`` is not recommended under any circumstances. The third + argument is the *parent* of the diagnostic (see below). The fourth is the + actual name of the diagnostic. The fifth and final argument is the CMake + preset version corresponding to the introduction of the argument, which + should be the latest preset version as used by the version of CMake under + development. + + .. note:: + + In the event that the development version has not already introduced a + new preset version, adding a new diagnostic will additionally require + introducing a new preset version. + + Diagnostics are hierarchical and **must** be listed in order of a + depth-first search. (If you imagine the order of items in a typical tree + view which has been fully expanded, that is depth-first order.) Each + diagnostic has a direct parent. Recursive alterations to a diagnostic will + also affect all descendant diagnostics. + +2. A documentation page for the new diagnostic must be created under + ``Help/diagnostic``, and a link to the same added to the Diagnostics + manual, ``Help/manual/cmake-diagnostics.7.rst``. + +3. The new presets fields must be mentioned in the CMake presets version + history, found at the bottom of ``Help/manual/cmake-presets.7.rst``. Note + that the documentation of the fields themselves is generated. + +4. The ``Utilities/Scripts/regenerate-presets.py`` script must be run to + generate the updated presets schema and documentation. Don't forget to + review and commit the changes made by this script.
diff --git a/Help/dev/experimental.rst b/Help/dev/experimental.rst index 81ddc8c..61b77c0 100644 --- a/Help/dev/experimental.rst +++ b/Help/dev/experimental.rst
@@ -37,42 +37,27 @@ * The package name associated with specific targets may be specified using the ``CMAKE_EXPORT_FIND_PACKAGE_NAME`` variable and/or -``EXPORT_FIND_PACKAGE_NAME`` target property. + ``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 ``efaed83b-d73a-48af-999a-bd0a6172c313``. + +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..046be1e 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`` @@ -203,6 +209,9 @@ * ``<cm/map>`` : ``cm::erase_if``, ``cm::ssize`` + * ``<cm/ranges>``: + ``cm::ranges::views::keys``, ``cm::ranges::views::values`` + * ``<cm/set>`` : ``cm::erase_if``, ``cm::ssize`` @@ -238,6 +247,14 @@ * ``cm::contains``: Checks if element or key is contained in container. + * ``cm::keys`` + Extract keys from associative container or sequence container with tuple as + element + + * ``cm::values`` + Extract values from associative container or sequence container with tuple as + element + * ``<cmext/enum_set>`` * ``cm::enum_set``: @@ -245,7 +262,7 @@ * ``<cmext/iterator>``: - * ``cm::is_terator``: + * ``cm::is_iterator``: Checks if a type is an iterator type. * ``cm::is_input_iterator``: @@ -269,6 +286,12 @@ * ``<cmext/type_traits>``: + * ``cm::is_pair``: + Checks if a type is a std::pair<> type. + + * ``cm::is_tuple``: + Checks if a type is a std::tuple<> type. + * ``cm::is_container``: Checks if a type is a container type.
diff --git a/Help/diagnostic/CMD_AUTHOR.rst b/Help/diagnostic/CMD_AUTHOR.rst new file mode 100644 index 0000000..c309f31 --- /dev/null +++ b/Help/diagnostic/CMD_AUTHOR.rst
@@ -0,0 +1,16 @@ +CMD_AUTHOR +---------- + +.. diagnostic:: + :default: warn + + Warn about a build system's incorrect use of CMake, or of a CMake interface + provided by a dependency. This is the category triggered by + :command:`message(AUTHOR_WARNING)`. It is also the ancestor of many other + diagnostic categories. + + The most important aspect of this category is that it represents issues with + a project's build system which typically require alteration to the same. + This is to say that users simply trying to build a project obtained elsewhere + will typically not be interested in these warnings, except to perhaps report + them to the project's developer(s).
diff --git a/Help/diagnostic/CMD_DEPRECATED.rst b/Help/diagnostic/CMD_DEPRECATED.rst new file mode 100644 index 0000000..dfb23d5 --- /dev/null +++ b/Help/diagnostic/CMD_DEPRECATED.rst
@@ -0,0 +1,9 @@ +CMD_DEPRECATED +-------------- + +.. diagnostic:: + :default: warn + :parent: CMD_AUTHOR + + Warn about use of a deprecated function or package. This is the category + triggered by :command:`message(DEPRECATION)`.
diff --git a/Help/diagnostic/CMD_INSTALL_ABSOLUTE_DESTINATION.rst b/Help/diagnostic/CMD_INSTALL_ABSOLUTE_DESTINATION.rst new file mode 100644 index 0000000..b7c6e08 --- /dev/null +++ b/Help/diagnostic/CMD_INSTALL_ABSOLUTE_DESTINATION.rst
@@ -0,0 +1,10 @@ +CMD_INSTALL_ABSOLUTE_DESTINATION +-------------------------------- + +.. diagnostic:: + :default: ignore + :parent: CMD_AUTHOR + + Warn when an :command:`install` command specifies an absolute ``DESTINATION`` + path. Absolute destinations are typically undesirable because they prevent + the installation prefix from being overridden at install time.
diff --git a/Help/diagnostic/CMD_UNINITIALIZED.rst b/Help/diagnostic/CMD_UNINITIALIZED.rst new file mode 100644 index 0000000..8c2edc8 --- /dev/null +++ b/Help/diagnostic/CMD_UNINITIALIZED.rst
@@ -0,0 +1,7 @@ +CMD_UNINITIALIZED +----------------- + +.. diagnostic:: + :default: ignore + + Warn if an uninitialized variable is dereferenced.
diff --git a/Help/diagnostic/CMD_UNUSED_CLI.rst b/Help/diagnostic/CMD_UNUSED_CLI.rst new file mode 100644 index 0000000..718598e --- /dev/null +++ b/Help/diagnostic/CMD_UNUSED_CLI.rst
@@ -0,0 +1,12 @@ +CMD_UNUSED_CLI +-------------- + +.. diagnostic:: + :default: ignore + + Warn about variables that are declared on the command line, but not used. + + This diagnostic is issued outside of the configuration / generation phases. + Accordingly, while the action of this warning category can be queried as + usual, the :command:`cmake_diagnostic` command is unable to affect the action + of this diagnostic.
diff --git a/Help/envvar/ASM_DIALECT.rst b/Help/envvar/ASM_DIALECT.rst index 4c271fd..1c01546 100644 --- a/Help/envvar/ASM_DIALECT.rst +++ b/Help/envvar/ASM_DIALECT.rst
@@ -7,9 +7,15 @@ files. ``ASM<DIALECT>`` can be one of: * ``ASM`` + * ``ASM_NASM`` (Netwide Assembler) + * ``ASM_MASM`` (Microsoft Assembler) + * ``ASM_MARMASM`` (Microsoft ARM Assembler) + +.. FIXME(#21536): * ``ASM_POASM`` (Pelles Macro Assembler) + * ``ASM-ATT`` (Assembler AT&T) Will only be used by CMake on the first configuration to determine
diff --git a/Help/envvar/ASM_DIALECTFLAGS.rst b/Help/envvar/ASM_DIALECTFLAGS.rst index e2b48a1..578d1b9 100644 --- a/Help/envvar/ASM_DIALECTFLAGS.rst +++ b/Help/envvar/ASM_DIALECTFLAGS.rst
@@ -7,9 +7,15 @@ of an assembly language. ``ASM<DIALECT>FLAGS`` can be one of: * ``ASMFLAGS`` + * ``ASM_NASMFLAGS`` + * ``ASM_MASMFLAGS`` + * ``ASM_MARMASMFLAGS`` + +.. FIXME(#21536): * ``ASM_POASMFLAGS`` + * ``ASM-ATTFLAGS`` .. |CMAKE_LANG_FLAGS| replace:: :variable:`CMAKE_ASM<DIALECT>_FLAGS <CMAKE_<LANG>_FLAGS>`
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_DISABLE_PRECOMPILE_HEADERS.rst b/Help/envvar/CMAKE_DISABLE_PRECOMPILE_HEADERS.rst new file mode 100644 index 0000000..0a8723e --- /dev/null +++ b/Help/envvar/CMAKE_DISABLE_PRECOMPILE_HEADERS.rst
@@ -0,0 +1,11 @@ +CMAKE_DISABLE_PRECOMPILE_HEADERS +-------------------------------- + +.. versionadded:: 4.4 + +.. include:: include/ENV_VAR.rst + +The default value for the :variable:`CMAKE_DISABLE_PRECOMPILE_HEADERS` variable +when there is no explicit configuration given on the first run while creating a +new build tree. On later runs in an existing build tree the value persists in +the cache as :variable:`CMAKE_DISABLE_PRECOMPILE_HEADERS`.
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..809cf73 100644 --- a/Help/guide/ide-integration/index.rst +++ b/Help/guide/ide-integration/index.rst
@@ -40,7 +40,7 @@ user-specific counterpart, ``CMakeUserPresets.json``. This file contains information on the various configure presets that a user may want. Each preset may have a different compiler, build flags, etc. The details of this format are -explained in the :manual:`cmake(1)` manual. +explained in the :manual:`cmake-presets(7)` manual. IDE vendors are encouraged to read and evaluate this file the same way CMake does, and present the user with the presets listed in the file. Users should be @@ -71,12 +71,12 @@ of the platform to be exceeded, the IDE should instead construct a temporary cache script and pass it with the :option:`-C <cmake -C>` flag. -While reading, parsing, and evaluating the contents of ``CMakePresets.json`` is +While reading, parsing, and evaluating the contents of CMake presets files is straightforward, it is not trivial. In addition to the documentation, IDE vendors may also wish to refer to the CMake source code and test cases for a better understanding of how to implement the format. :download:`This file <../../manual/presets/schema.json>` provides a -machine-readable JSON schema for the ``CMakePresets.json`` format that IDE +machine-readable JSON schema for the CMake presets file format that IDE vendors may find useful for validation and providing editing assistance. Configuring @@ -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..7da09ed --- /dev/null +++ b/Help/guide/tutorial/Configuration and Cache Variables.rst
@@ -0,0 +1,612 @@ +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/cpp/utility/format/format>`_ + +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. + +.. note:: + On CMake 4.4 and newer, CMake can also load presets from any file specified + with :option:`cmake --presets-file`. This can be useful when reusing settings + across multiple projects, since it avoids having to duplicate them in + separate ``CMakePresets.json`` files for each project. + +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 presets 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/guide/user-interaction/index.rst b/Help/guide/user-interaction/index.rst index fe8a45a..12d6b84 100644 --- a/Help/guide/user-interaction/index.rst +++ b/Help/guide/user-interaction/index.rst
@@ -71,7 +71,7 @@ for the provider of the software, not intended for the consumer of the software. Such warnings end with "This warning is for project developers". Users may disable -such warnings by passing the :option:`-Wno-dev <cmake -Wno-dev>` +such warnings by passing the :option:`-Wno-author <cmake -Wno->` flag to :manual:`cmake(1)`. cmake-gui tool @@ -425,7 +425,7 @@ presets can set the build directory, generator, cache variables, environment variables, and other command-line options. All of these options can be overridden by the -user. The full details of the ``CMakePresets.json`` format +user. The full details of the CMake presets format are listed in the :manual:`cmake-presets(7)` manual. Using presets on the command-line
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/index.rst b/Help/index.rst index f9ffcba..fa7d199 100644 --- a/Help/index.rst +++ b/Help/index.rst
@@ -60,6 +60,7 @@ /manual/cmake-configure-log.7 /manual/cmake-cxxmodules.7 /manual/cmake-developer.7 + /manual/cmake-diagnostics.7 /manual/cmake-env-variables.7 /manual/cmake-file-api.7 /manual/cmake-generator-expressions.7
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-commands.7.rst b/Help/manual/cmake-commands.7.rst index 6f1a947..8a25b62 100644 --- a/Help/manual/cmake-commands.7.rst +++ b/Help/manual/cmake-commands.7.rst
@@ -17,6 +17,7 @@ /command/block /command/break + /command/cmake_diagnostic /command/cmake_host_system_information /command/cmake_language /command/cmake_minimum_required @@ -93,6 +94,7 @@ /command/cmake_instrumentation /command/create_test_sourcelist /command/define_property + /command/discover_tests /command/enable_language /command/enable_testing /command/export
diff --git a/Help/manual/cmake-cxxmodules.7.rst b/Help/manual/cmake-cxxmodules.7.rst index ee16e27..c9f9521 100644 --- a/Help/manual/cmake-cxxmodules.7.rst +++ b/Help/manual/cmake-cxxmodules.7.rst
@@ -5,68 +5,56 @@ .. 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. - If the target does not use at least C++ 20, it will not be scanned. - If the source file is not the language ``CXX``, it will not be scanned. -- If the :prop_sf:`CXX_SCAN_FOR_MODULES` source file property is set, its +- If the source file belongs to a file set that is not of type ``CXX_MODULES``, + and the :prop_fs:`CXX_SCAN_FOR_MODULES` file set property is set, its value will be used. +- If the :prop_sf:`CXX_SCAN_FOR_MODULES` source file property is set in the + target's directory, its value will be used. - If the :prop_tgt:`CXX_SCAN_FOR_MODULES` target property is set, its value will be used. Set the :variable:`CMAKE_CXX_SCAN_FOR_MODULES` variable to initialize this property on all targets as they are created. @@ -80,11 +68,18 @@ 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 + + .. versionadded:: 4.4 + + ``clang-cl`` version 19.1 and newer + +* GCC 14 and newer ``import std`` Support ====================== @@ -92,51 +87,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-diagnostics.7.rst b/Help/manual/cmake-diagnostics.7.rst new file mode 100644 index 0000000..de2b705 --- /dev/null +++ b/Help/manual/cmake-diagnostics.7.rst
@@ -0,0 +1,93 @@ +.. cmake-manual-description: CMake Diagnostics Reference + +cmake-diagnostics(7) +******************** + +.. only:: html + + .. contents:: + +.. _cmake-diagnostics-intro: + +Introduction +============ + +.. versionadded:: 4.4 + +CMake Diagnostics are the mechanism by which CMake categorizes and presents +certain advisory information about a project's configuration and the generation +of its build system. These diagnostics can be seen as the build system +equivalent of compiler warnings. Diagnostics provide feedback on potential +issues in several categories: + +* Issues that may impact the success of the build. + +* Issues that may impact the correctness of the build. + +* Issues that may impact the correctness of the project packaging. + +* Issues that may impact the ability of the project + to be built with newer versions of dependencies. + +* Issues that may impact the ability of the project + to be built with newer versions of CMake. + +Controlling Diagnostics +======================= + +Each diagnostic category has an associated action to be taken when that +diagnostic is triggered. Most categories will warn by default. The available +actions are described in the :command:`cmake_diagnostic` command documentation. + +CMake maintains a diagnostic state stack that is similar to the policy state. +The initial state of the stack is determined by four factors, which are, in +order of precedence: + +* The default action associated with the diagnostic. + +* The action associated with the diagnostic stored in the CMake variable cache, + which is used to persist the initial state between CMake runs. + +* The :preset:`configurePresets.warnings` and :preset:`configurePresets.errors` + fields of :manual:`CMake Presets <cmake-presets(7)>`. + +* The :option:`-W[no-][error=] <cmake -W>` command line arguments. + +.. note:: + + Because command line arguments operate both recursively and in the order + specified, some combinations of diagnostic arguments may result in later + arguments completely overwriting the action of earlier arguments. For + example, ``-Wno-child -Wparent`` will result in the ``child`` warning being + enabled, because ``-Wparent`` promotes both ``parent`` and ``child`` to at + least ``WARN`` severity. CMake presets are evaluated in order from most + ancestral to least ancestral. + +During script execution, the :command:`cmake_diagnostic` command can be used to +query or alter the state, or to perform limited stack manipulations. + +When a diagnostic is issued at configure time (or during script execution, when +CMake is running in script mode), the current diagnostic state controls the +action. Diagnostics issued at generate time, or outside of the configuration +and generation phases must make use of recorded state information. While CMake +strives to preserve this information in a way that matches the recorded state +to the state as of the CMake command which ultimately causes a diagnostic to be +issued, CMake may sometimes fall back to the state when processing of a +subdirectory completed, or even the root state. This may limit the ability of +the :command:`cmake_diagnostic` command to control such diagnostics, especially +if called from a function or included file. This is especially the case for +diagnostics that are not directly coupled to a CMake command. + +Diagnostic Categories +===================== + +The following categories are defined: + +.. toctree:: + :maxdepth: 1 + + /diagnostic/CMD_AUTHOR + /diagnostic/CMD_DEPRECATED + /diagnostic/CMD_INSTALL_ABSOLUTE_DESTINATION + /diagnostic/CMD_UNINITIALIZED + /diagnostic/CMD_UNUSED_CLI
diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index e493655..e3779c0 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 @@ -51,8 +52,10 @@ /envvar/CMAKE_CONFIG_TYPE /envvar/CMAKE_CONFIGURATION_TYPES /envvar/CMAKE_CROSSCOMPILING_EMULATOR + /envvar/CMAKE_DISABLE_PRECOMPILE_HEADERS /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 +63,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..49b348f 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: @@ -918,6 +1017,9 @@ This field was added in codemodel version 2.4. + Since codemodel version 2.11, this field additionally accounts for + ``SOURCES`` file sets. + ``fileSetDirectories`` Optional member that is present when ``type`` is ``fileSet``. The value is a list of strings with the file set's base directories (determined by @@ -976,10 +1078,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 +1112,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 +1253,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 +1300,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 +1340,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 +1366,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 +1640,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 +1683,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 +1884,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 +1928,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 +2004,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 +2137,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 +2150,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 +2235,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..51ed27e 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst
@@ -43,6 +43,12 @@ :variable:`CMAKE_CXX_COMPILER_VERSION <CMAKE_<LANG>_COMPILER_VERSION>` is less than 4.2.0. +.. note:: + + Generator expressions are supported in the values of many properties, + but not all. Check a property's documentation for explicit mention + of generator expressions before using them. + Whitespace And Quoting ====================== @@ -115,6 +121,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 +290,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 +324,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 +728,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 +964,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 +976,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 +984,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 +1056,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 +1073,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 +1116,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 +1216,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 +1226,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 +1236,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 +1244,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 +1253,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 +1269,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 +1282,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 +1817,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 +2224,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 +2761,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 +2839,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 +2925,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 +3004,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 +3086,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 +3207,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. @@ -2497,13 +3304,23 @@ Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). -.. genex:: $<TARGET_OBJECTS:tgt> +.. genex:: $<TARGET_OBJECTS:tgt[,SOURCE_FILES:source_file[;source_file]...]> .. versionadded:: 3.1 List of objects resulting from building ``tgt``. This would typically be used on :ref:`object library <Object Libraries>` targets. + Additional arguments: + + ``SOURCE_FILES:source_file[;source_file]...`` + + .. versionadded:: 4.4 + + An optional list of one or more source files for the target. Only the + object files built from those source files will be returned (but not + necessarily in the same order they were specified). + .. genex:: $<TARGET_RUNTIME_DLLS:tgt> .. versionadded:: 3.21 @@ -2558,6 +3375,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..9fe2d3c 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,94 @@ "ctest-<hash>-<timestamp>.json", "test-<hash>-<timestamp>.json", "test-<hash>-<timestamp>.json", - ] + ], + "trace": "trace/trace-<timestamp>.json" } + +.. versionadded:: 4.4 + The JSON format is described in machine-readable form by + :download:`this JSON schema </manual/instrumentation/index-v1-schema.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..2ab7290 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.3) -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.3 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,47 @@ The following policies are supported. +Policies Introduced by CMake 4.4 +-------------------------------- + +.. toctree:: + :maxdepth: 1 + + CMP0217: The MACROS directory property does not exist anymore. </policy/CMP0217> + CMP0216: Swift targets have a default project name. </policy/CMP0216> + CMP0215: Ninja generators emit Swift modules separately from compilation. </policy/CMP0215> + CMP0214: Honor CMAKE_EXE_LINKER_FLAGS for Swift executable targets. </policy/CMP0214> + CMP0213: file(ARCHIVE_{CREATE,EXTRACT}) encode archive paths as UTF-8 by default. </policy/CMP0213> + CMP0212: add_custom_command DEPENDS does not strip .exe suffixes. </policy/CMP0212> + CMP0211: A file may belong to at most one file set in a target. </policy/CMP0211> + +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..d5f7c98 100644 --- a/Help/manual/cmake-presets.7.rst +++ b/Help/manual/cmake-presets.7.rst
@@ -1,4 +1,4 @@ -.. cmake-manual-description: CMakePresets.json +.. cmake-manual-description: CMake Presets Reference cmake-presets(7) **************** @@ -16,12 +16,16 @@ for common ways to configure a project. This may be done to support CI builds, or for users who frequently use the same build. CMake supports two main files, ``CMakePresets.json`` and ``CMakeUserPresets.json``, that allow users to -specify common configure options and share them with others. CMake also -supports files included with the ``include`` field. +specify common configure options and share them with others. + +.. presets-versionadded:: 4 + + CMake also supports files included with the :preset:`include` field. See + `Includes`_ for more details. ``CMakePresets.json`` and ``CMakeUserPresets.json`` live in the project's root directory. They both have exactly the same format, and both are optional -(though at least one must be present if :option:`--preset <cmake --preset>` +(though at least one must be present if :cmake-option:`--preset` is specified). ``CMakePresets.json`` is meant to specify project-wide build details, while ``CMakeUserPresets.json`` is meant for developers to specify their own local build details. @@ -31,6 +35,13 @@ project is using Git, ``CMakePresets.json`` may be tracked, and ``CMakeUserPresets.json`` should be added to the ``.gitignore``. +.. versionadded:: 4.4 + + CMake also supports specifying a file from which to read presets via the + :cmake-option:`--presets-file` option. If this option is specified, neither + of ``CMakePresets.json`` nor ``CMakeUserPresets.json`` are required to be + present, and any presets defined in those files will be ignored/unavailable. + Format ====== @@ -39,112 +50,27 @@ .. literalinclude:: presets/example.json :language: json -Preset files specifying version ``10`` or above may include comments using the -key ``$comment`` at any level within the JSON object to provide documentation. +.. presets-versionadded:: 10 + + Presets files may include comments using the key ``$comment`` at any level + within the JSON object to provide documentation. The root object recognizes the following fields: -``$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 - autocompletion in editors that support JSON schema. It doesn't affect the - 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 - -``cmakeMinimumRequired`` - An optional object representing the minimum version of CMake needed to - build this project. This object consists of the following fields: - - ``major`` - An optional integer representing the major version. - - ``minor`` - An optional integer representing the minor version. - - ``patch`` - An optional integer representing the patch version. - -``include`` - An optional array of strings representing files to include. If the filenames - are not absolute, they are considered relative to the current file. - This is allowed in preset files specifying version ``4`` or above. - See `Includes`_ for discussion of the constraints on included files. - -``vendor`` - An optional map containing vendor-specific information. CMake does not - interpret the contents of this field except to verify that it is a map if - it does exist. However, the keys should be a vendor-specific domain name - followed by a ``/``-separated path. For example, the Example IDE 1.0 could - use ``example.com/ExampleIDE/1.0``. The value of each field can be anything - desired by the vendor, though will typically be a map. - -``configurePresets`` - An optional array of `Configure Preset`_ objects. - This is allowed in preset files specifying version ``1`` or above. - -``buildPresets`` - An optional array of `Build Preset`_ objects. - This is allowed in preset files specifying version ``2`` or above. - -``testPresets`` - An optional array of `Test Preset`_ objects. - This is allowed in preset files specifying version ``2`` or above. - -``packagePresets`` - An optional array of `Package Preset`_ objects. - This is allowed in preset files specifying version ``6`` or above. - -``workflowPresets`` - An optional array of `Workflow Preset`_ objects. - This is allowed in preset files specifying version ``6`` or above. +.. include:: presets/root-properties.rst Includes ^^^^^^^^ -``CMakePresets.json`` and ``CMakeUserPresets.json`` can include other files -with the ``include`` field in file version ``4`` and later. Files included -by these files can also include other files. If ``CMakePresets.json`` and -``CMakeUserPresets.json`` are both present, ``CMakeUserPresets.json`` -implicitly includes ``CMakePresets.json``, even with no ``include`` field, -in all versions of the format. +.. presets-versionadded:: 4 -If a preset file contains presets that inherit from presets in another file, +CMake presets files can include other files with the :preset:`include` field. +Files included in this manner can also include other files. If +``CMakePresets.json`` and ``CMakeUserPresets.json`` are both present, +``CMakeUserPresets.json`` implicitly includes ``CMakePresets.json``, even with +no :preset:`include` field, in all versions of the format. + +If a presets file contains presets that inherit from presets in another file, the file must include the other file either directly or indirectly. Include cycles are not allowed among files. If ``a.json`` includes ``b.json``, ``b.json`` cannot include ``a.json``. However, a file may be @@ -154,11 +80,18 @@ guaranteed to be provided by the project. ``CMakeUserPresets.json`` may include files from anywhere. -Starting from version ``7``, the ``include`` field supports -`macro expansion`_, but only ``$penv{}`` macro expansion. Starting from version -``9``, other macro expansions are also available, except for ``$env{}`` and -preset-specific macros, i.e., those derived from the fields inside a preset's -definition like ``presetName``. +.. presets-versionchanged:: 7 + + The :preset:`include` field supports `macro expansion`_, but only ``$penv{}`` + macro expansion. + +.. presets-versionchanged:: 9 + + The :preset:`include` field supports `macro expansion`_, except for + ``$env{}`` and preset-specific macros (i.e., those derived from the fields + inside a preset's definition like ``presetName``). + +.. _`Configure Preset`: Configure Preset ^^^^^^^^^^^^^^^^ @@ -166,988 +99,69 @@ Each entry of the ``configurePresets`` array is a JSON object that may contain the following fields: -``name`` - A required string representing the machine-friendly name of the preset. - This identifier is used in the :ref:`cmake --preset <CMake Options>` 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, - package, or workflow preset. +.. include:: presets/configurePresets-properties.rst -``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. - -``inherits`` - An optional array of strings representing the names of presets to inherit - from. This field can also be a string, which is equivalent to an array - containing one string. - - 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`` array will be - preferred. - - A preset can only inherit from another preset that is defined in the - same file or in one of the files it includes (directly or indirectly). - Presets in ``CMakePresets.json`` may not inherit from presets in - ``CMakeUserPresets.json``. - -``condition`` - An optional `Condition`_ object. This is allowed in preset files specifying - version ``3`` or above. - -``vendor`` - An optional map containing vendor-specific information. CMake does not - 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. - -``displayName`` - An optional string with a human-friendly name of the preset. - -``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. - - Note that for 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. - -``architecture``, ``toolset`` - Optional fields representing the platform and toolset, respectively, for - :manual:`generators <cmake-generators(7)>` that support them. - - See :option:`cmake -A` option for possible values for ``architecture`` - and :option:`cmake -T` for ``toolset``. - - Each may be either a string or an object with the following fields: - - ``value`` - An optional string representing the value. - - ``strategy`` - An optional string telling CMake how to handle the ``architecture`` or - ``toolset`` field. Valid values are: - - ``"set"`` - Set the respective value. This will result in an error for generators - that do not support the respective field. - - ``"external"`` - Do not set the value, even if the generator supports it. This is - useful if, for example, a preset uses the Ninja generator, and an IDE - knows how to set up the Visual C++ environment from the - ``architecture`` and ``toolset`` fields. In that case, CMake will - ignore the field, but the IDE can use them to set up the environment - before invoking CMake. - - 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"``. - -``toolchainFile`` - An optional string representing the path to the toolchain file. - This field supports `macro expansion`_. If a relative path is specified, - it is calculated relative to the build directory, and if not found, - relative to the source directory. This field takes precedence over any - :variable:`CMAKE_TOOLCHAIN_FILE` value. It is allowed in preset files - specifying version ``3`` or above. - -``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. - - 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. - -``binaryDir`` - An optional string representing the path to the output binary directory. - This field supports `macro expansion`_. If a relative path is specified, - it is calculated relative to the source directory. If ``binaryDir`` is not - specified, it must be inherited from the ``inherits`` preset (unless this - preset is ``hidden``). In version ``3`` or above, this field may be - omitted. - -``installDir`` - An optional string representing the path to the installation directory. - This field supports `macro expansion`_. If a relative path is specified, - it is calculated relative to the source directory. This is allowed in - preset files specifying version ``3`` or above. - -``cmakeExecutable`` - 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`` - An optional map of cache variables. The key is the variable name (which - may not be an empty string), and the value is either ``null``, a boolean - (which is equivalent to a value of ``"TRUE"`` or ``"FALSE"`` and a type - of ``BOOL``), a string representing the value of the variable (which - supports `macro expansion`_), or an object with the following fields: - - ``type`` - An optional string representing the type of the variable. - - ``value`` - A required string or boolean representing the value of the variable. - A boolean is equivalent to ``"TRUE"`` or ``"FALSE"``. This field - supports `macro expansion`_. - - 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. Setting a variable to ``null`` causes it to not be set, even if - a value was inherited from another preset. - -``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 - a string representing the value of the variable. 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}``). ``$penv{NAME}`` - allows one to prepend or append values to existing environment variables by - accessing only values from the parent environment. - - 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. - -``warnings`` - An optional object specifying the warnings to enable. The object may - contain the following fields: - - ``dev`` - An optional boolean. Equivalent to passing :option:`-Wdev <cmake -Wdev>` - or :option:`-Wno-dev <cmake -Wno-dev>` on the command line. This may not - be set to ``false`` if ``errors.dev`` is set to ``true``. - - ``deprecated`` - An optional boolean. Equivalent to passing - :option:`-Wdeprecated <cmake -Wdeprecated>` or - :option:`-Wno-deprecated <cmake -Wno-deprecated>` on the command line. - This may not be set to ``false`` if ``errors.deprecated`` is set to - ``true``. - - ``uninitialized`` - An optional boolean. Setting this to ``true`` is equivalent to passing - :option:`--warn-uninitialized <cmake --warn-uninitialized>` on the command - line. - - ``unusedCli`` - An optional boolean. Setting this to ``false`` is equivalent to passing - :option:`--no-warn-unused-cli <cmake --no-warn-unused-cli>` on the command - line. - - ``systemVars`` - An optional boolean. Setting this to ``true`` is equivalent to passing - :option:`--check-system-vars <cmake --check-system-vars>` on the command - line. - -``errors`` - An optional object specifying the errors to enable. The object may - contain the following fields: - - ``dev`` - An optional boolean. Equivalent to passing :option:`-Werror=dev <cmake -Werror>` - or :option:`-Wno-error=dev <cmake -Werror>` on the command line. - This may not be set to ``true`` if ``warnings.dev`` is set to ``false``. - - ``deprecated`` - An optional boolean. Equivalent to passing - :option:`-Werror=deprecated <cmake -Werror>` or - :option:`-Wno-error=deprecated <cmake -Werror>` on the command line. - This may not be set to ``true`` if ``warnings.deprecated`` is set to - ``false``. - -``debug`` - An optional object specifying debug options. The object may contain the - following fields: - - ``output`` - An optional boolean. Setting this to ``true`` is equivalent to passing - :option:`--debug-output <cmake --debug-output>` on the command line. - - ``tryCompile`` - An optional boolean. Setting this to ``true`` is equivalent to passing - :option:`--debug-trycompile <cmake --debug-trycompile>` on the command - line. - - ``find`` - An optional boolean. Setting this to ``true`` is equivalent to passing - :option:`--debug-find <cmake --debug-find>` on the command line. - -``trace`` - An optional object specifying trace options. This is allowed in preset - files specifying version ``7``. The object may contain the following fields: - - ``mode`` - An optional string that specifies the trace mode. Valid values are: - - ``on`` - Causes a trace of all calls made and from where to be printed. - Equivalent to passing :option:`--trace <cmake --trace>` on the command - line. - - ``off`` - A trace of all calls will not be printed. - - ``expand`` - Causes a trace with variables expanded of all calls made and from where - to be printed. Equivalent to passing :option:`--trace-expand <cmake --trace-expand>` - on the command line. - - ``format`` - An optional string that specifies the format output of the trace. - Valid values are: - - ``human`` - Prints each trace line in a human-readable format. - This is the default format. Equivalent to passing - :option:`--trace-format=human <cmake --trace-format>` - on the command line. - - ``json-v1`` - Prints each line as a separate JSON document. Equivalent to passing - :option:`--trace-format=json-v1 <cmake --trace-format>` - on the command line. - - ``source`` - An optional array of strings representing the paths of source files to - be traced. This field can also be a string, which is equivalent to an - array containing one string. Equivalent to passing - :option:`--trace-source <cmake --trace-source>` on the command line. - - ``redirect`` - An optional string specifying a path to a trace output file. Equivalent - to passing :option:`--trace-redirect <cmake --trace-redirect>` - on the command line. +.. _`Build Preset`: Build Preset ^^^^^^^^^^^^ +.. presets-versionadded:: 2 + Each entry of the ``buildPresets`` array is a JSON object that may contain the following fields: -``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. - 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, - package, or workflow preset. +.. include:: presets/buildPresets-properties.rst -``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 - 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`` - An optional array of strings representing the names of presets to inherit - from. This field can also be a string, which is equivalent to an array - containing one string. - - 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`` array - will be preferred. - - A preset can only inherit from another preset that is defined in the - same file or in one of the files it includes (directly or indirectly). - Presets in ``CMakePresets.json`` may not inherit from presets in - ``CMakeUserPresets.json``. - -``condition`` - An optional `Condition`_ object. This is allowed in preset files specifying - version ``3`` or above. - -``vendor`` - An optional map containing vendor-specific information. CMake does not - 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. - -``displayName`` - An optional string with a human-friendly name of the preset. - -``description`` - An optional string with a human-friendly description of the preset. - -``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 - a string representing the value of the variable. 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}``). ``$penv{NAME}`` - allows one to prepend or append values to existing environment variables by - accessing only values from the parent environment. - - 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. - - .. note:: - - For a CMake project using ExternalProject with a configuration preset - having environment variables needed in the ExternalProject, use a build - preset that inherits that configuration preset or the ExternalProject - will not have the environment variables set in the configuration preset. - Example: suppose the host defaults to one compiler (say Clang) - and the user wishes to use another compiler (say GCC). Set configuration - preset environment variables ``CC`` and ``CXX`` and use a build preset - that inherits that configuration preset. Otherwise the ExternalProject - may use a different (system default) compiler than the top-level CMake - project. - -``configurePreset`` - An optional string specifying the name of a configure preset to - 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 directory is inferred from the configure - preset, so the build will take place in the same ``binaryDir`` that the - configuration did. - -``inheritConfigureEnvironment`` - 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`` - An optional integer. Equivalent to passing - :option:`--parallel <cmake--build --parallel>` or ``-j`` on the command line. - -``targets`` - An optional string or array of strings. Equivalent to passing - :option:`--target <cmake--build --target>` or ``-t`` on the command line. - Vendors may ignore the targets property or hide build presets that - explicitly specify targets. This field supports macro expansion. - -``configuration`` - An optional string. Equivalent to passing - :option:`--config <cmake--build --config>` on the command line. - -``cleanFirst`` - An optional bool. If true, equivalent to passing - :option:`--clean-first <cmake--build --clean-first>` on the command line. - -``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: - - ``on`` - Causes package references to be resolved before attempting a build. - - ``off`` - Package references will not be resolved. Note that this may cause - errors in some build environments, such as .NET SDK style projects. - - ``only`` - Only resolve package references, but do not perform a build. - - .. note:: - - The command line parameter - :option:`--resolve-package-references <cmake--build --resolve-package-references>` - will take priority over this setting. If the command line parameter is not - provided and this setting is not specified, an environment-specific cache - 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. - -``verbose`` - An optional bool. If true, equivalent to passing - :option:`--verbose <cmake--build --verbose>` on the command line. - -``nativeToolOptions`` - An optional array of strings. Equivalent to passing options after ``--`` - on the command line. The array values support macro expansion. +.. _`Test Preset`: Test Preset ^^^^^^^^^^^ +.. presets-versionadded:: 2 + Each entry of the ``testPresets`` array is a JSON object that may contain the following fields: -``name`` - A required string representing the machine-friendly name of the preset. - This identifier is used in the :option:`ctest --preset` option. - There must not be two test presets in the union of ``CMakePresets.json`` - and ``CMakeUserPresets.json`` in the same directory with the same name. - However, a test preset may have the same name as a configure, build, - package, or workflow preset. +.. include:: presets/testPresets-properties.rst -``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 <ctest --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`` - An optional array of strings representing the names of presets to inherit - from. This field can also be a string, which is equivalent to an array - containing one string. - - 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`` array - will be preferred. - - A preset can only inherit from another preset that is defined in the - same file or in one of the files it includes (directly or indirectly). - Presets in ``CMakePresets.json`` may not inherit from presets in - ``CMakeUserPresets.json``. - -``condition`` - An optional `Condition`_ object. This is allowed in preset files specifying - version ``3`` or above. - -``vendor`` - An optional map containing vendor-specific information. CMake does not - 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. - -``displayName`` - An optional string with a human-friendly name of the preset. - -``description`` - An optional string with a human-friendly description of the preset. - -``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 - a string representing the value of the variable. 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}``). ``$penv{NAME}`` - allows one to prepend or append values to existing environment variables by - accessing only values from the parent environment. - - 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. - -``configurePreset`` - 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 directory is inferred from the configure - preset, so tests will run in the same ``binaryDir`` that the - configuration did and build did. - -``inheritConfigureEnvironment`` - 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`` - An optional string. Equivalent to passing - :option:`--build-config <ctest --build-config>` on the command line. - -``overwriteConfigurationFile`` - An optional array of configuration options to overwrite options - specified in the CTest configuration file. Equivalent to passing - :option:`--overwrite <ctest --overwrite>` for each value in the array. - The array values support macro expansion. - -``output`` - An optional object specifying output options. The object may contain the - following fields. - - ``shortProgress`` - An optional bool. If true, equivalent to passing - :option:`--progress <ctest --progress>` on the command line. - - ``verbosity`` - An optional string specifying verbosity level. Must be one of the - following: - - ``default`` - Equivalent to passing no verbosity flags on the command line. - - ``verbose`` - Equivalent to passing :option:`--verbose <ctest --verbose>` on - the command line. - - ``extra`` - Equivalent to passing :option:`--extra-verbose <ctest --extra-verbose>` - on the command line. - - ``debug`` - An optional bool. If true, equivalent to passing - :option:`--debug <ctest --debug>` on the command line. - - ``outputOnFailure`` - An optional bool. If true, equivalent to passing - :option:`--output-on-failure <ctest --output-on-failure>` on the command - line. - - ``quiet`` - An optional bool. If true, equivalent to passing - :option:`--quiet <ctest --quiet>` on the command line. - - ``outputLogFile`` - An optional string specifying a path to a log file. Equivalent to - passing :option:`--output-log <ctest --output-log>` on the command line. - This field supports macro expansion. - - ``outputJUnitFile`` - An optional string specifying a path to a JUnit file. Equivalent to - passing :option:`--output-junit <ctest --output-junit>` on the command line. - This field supports macro expansion. This is allowed in preset files - specifying version ``6`` or above. - - ``labelSummary`` - An optional bool. If false, equivalent to passing - :option:`--no-label-summary <ctest --no-label-summary>` on the command - line. - - ``subprojectSummary`` - An optional bool. If false, equivalent to passing - :option:`--no-subproject-summary <ctest --no-subproject-summary>` - on the command line. - - ``maxPassedTestOutputSize`` - An optional integer specifying the maximum output for passed tests in - bytes. Equivalent to passing - :option:`--test-output-size-passed <ctest --test-output-size-passed>` - on the command line. - - ``maxFailedTestOutputSize`` - An optional integer specifying the maximum output for failed tests in - bytes. Equivalent to passing - :option:`--test-output-size-failed <ctest --test-output-size-failed>` - on the command line. - - ``testOutputTruncation`` - An optional string specifying the test output truncation mode. Equivalent - to passing - :option:`--test-output-truncation <ctest --test-output-truncation>` on - the command line. This is allowed in preset files specifying version - ``5`` or above. - - ``maxTestNameWidth`` - An optional integer specifying the maximum width of a test name to - output. Equivalent to passing :option:`--max-width <ctest --max-width>` - on the command line. - -``filter`` - An optional object specifying how to filter the tests to run. The object - may contain the following fields. - - ``include`` - An optional object specifying which tests to include. The object may - contain the following fields. - - ``name`` - An optional string specifying a regex for test names. Equivalent to - passing :option:`--tests-regex <ctest --tests-regex>` on the command - line. This field supports macro expansion. CMake regex syntax is - described under :ref:`string(REGEX) <Regex Specification>`. - - ``label`` - An optional string specifying a regex for test labels. Equivalent to - passing :option:`--label-regex <ctest --label-regex>` on the command - line. This field supports macro expansion. - - ``useUnion`` - An optional bool. Equivalent to passing :option:`--union <ctest --union>` - on the command line. - - ``index`` - An optional object specifying tests to include by test index. The - object may contain the following fields. Can also be an optional - string specifying a file with the command line syntax for - :option:`--tests-information <ctest --tests-information>`. - If specified as a string, this field supports macro expansion. - - ``start`` - An optional integer specifying a test index to start testing at. - - ``end`` - An optional integer specifying a test index to stop testing at. - - ``stride`` - An optional integer specifying the increment. - - ``specificTests`` - An optional array of integers specifying specific test indices to - run. - - ``exclude`` - An optional object specifying which tests to exclude. The object may - contain the following fields. - - ``name`` - An optional string specifying a regex for test names. Equivalent to - passing :option:`--exclude-regex <ctest --exclude-regex>` on the - command line. This field supports macro expansion. - - ``label`` - An optional string specifying a regex for test labels. Equivalent to - passing :option:`--label-exclude <ctest --label-exclude>` on the - command line. This field supports macro expansion. - - ``fixtures`` - An optional object specifying which fixtures to exclude from adding - tests. The object may contain the following fields. - - ``any`` - An optional string specifying a regex for text fixtures to exclude - from adding any tests. Equivalent to - :option:`--fixture-exclude-any <ctest --fixture-exclude-any>` on - the command line. This field supports macro expansion. - - ``setup`` - An optional string specifying a regex for text fixtures to exclude - from adding setup tests. Equivalent to - :option:`--fixture-exclude-setup <ctest --fixture-exclude-setup>` - on the command line. This field supports macro expansion. - - ``cleanup`` - An optional string specifying a regex for text fixtures to exclude - from adding cleanup tests. Equivalent to - :option:`--fixture-exclude-cleanup <ctest --fixture-exclude-cleanup>` - on the command line. This field supports macro expansion. - -``execution`` - An optional object specifying options for test execution. The object may - contain the following fields. - - ``stopOnFailure`` - An optional bool. If true, equivalent to passing - :option:`--stop-on-failure <ctest --stop-on-failure>` on the command - line. - - ``enableFailover`` - An optional bool. If true, equivalent to passing :option:`-F <ctest -F>` - on the command line. - - ``jobs`` - An optional integer. Equivalent to passing - :option:`--parallel <ctest --parallel>` on the command line. - - ``resourceSpecFile`` - An optional string. Equivalent to passing - :option:`--resource-spec-file <ctest --resource-spec-file>` on - the command line. This field supports macro expansion. - - ``testLoad`` - An optional integer. Equivalent to passing - :option:`--test-load <ctest --test-load>` on the command line. - - ``showOnly`` - An optional string. Equivalent to passing - :option:`--show-only <ctest --show-only>` on the - command line. The string must be one of the following values: - - ``human`` - - ``json-v1`` - - ``repeat`` - An optional object specifying how to repeat tests. Equivalent to - passing :option:`--repeat <ctest --repeat>` on the command line. - The object must have the following fields. - - ``mode`` - A required string. Must be one of the following values: - - ``until-fail`` - - ``until-pass`` - - ``after-timeout`` - - ``count`` - A required integer. - - ``interactiveDebugging`` - An optional bool. If true, equivalent to passing - :option:`--interactive-debug-mode 1 <ctest --interactive-debug-mode>` - on the command line. If false, equivalent to passing - :option:`--interactive-debug-mode 0 <ctest --interactive-debug-mode>` - on the command line. - - ``scheduleRandom`` - An optional bool. If true, equivalent to passing - :option:`--schedule-random <ctest --schedule-random>` on the command - line. - - ``timeout`` - An optional integer. Equivalent to passing - :option:`--timeout <ctest --timeout>` on the command line. - - ``noTestsAction`` - 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 :option:`--no-tests=error <ctest --no-tests>` - on the command line. - - ``ignore`` - Equivalent to passing :option:`--no-tests=ignore <ctest --no-tests>` - on the command line. +.. _`Package Preset`: Package Preset ^^^^^^^^^^^^^^ -Package presets may be used in schema version ``6`` or above. Each entry of -the ``packagePresets`` array is a JSON object that may contain the following -fields: +.. presets-versionadded:: 6 -``name`` - A required string representing the machine-friendly name of the preset. - This identifier is used in the :option:`cpack --preset` option. - There must not be two package presets in the union of ``CMakePresets.json`` - and ``CMakeUserPresets.json`` in the same directory with the same name. - However, a package preset may have the same name as a configure, build, - test, or workflow preset. +Each entry of the ``packagePresets`` array is a JSON object +that may contain the following fields: -``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 <cpack --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`` - An optional array of strings representing the names of presets to inherit - from. This field can also be a string, which is equivalent to an array - containing one string. - - 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`` array - will be preferred. - - A preset can only inherit from another preset that is defined in the - same file or in one of the files it includes (directly or indirectly). - Presets in ``CMakePresets.json`` may not inherit from presets in - ``CMakeUserPresets.json``. - -``condition`` - An optional `Condition`_ object. - -``vendor`` - 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. - -``displayName`` - An optional string with a human-friendly name of the preset. - -``description`` - An optional string with a human-friendly description of the preset. - -``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 - a string representing the value of the variable. 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}``). ``$penv{NAME}`` - allows one to prepend or append values to existing environment variables by - accessing only values from the parent environment. - - 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. - -``configurePreset`` - 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 directory is inferred from the configure - preset, so packaging will run in the same ``binaryDir`` that the - configuration did and build did. - -``inheritConfigureEnvironment`` - 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`` - An optional array of strings representing generators for CPack to use. - -``configurations`` - An optional array of strings representing build configurations for CPack to - package. - -``variables`` - An optional map of variables to pass to CPack, equivalent to - :option:`-D <cpack -D>` arguments. Each key is the name of a variable, and - the value is the string to assign to that variable. - -``configFile`` - An optional string representing the config file for CPack to use. - -``output`` - An optional object specifying output options. Valid keys are: - - ``debug`` - An optional boolean specifying whether or not to print debug information. - A value of ``true`` is equivalent to passing - :option:`--debug <cpack --debug>` on the command line. - - ``verbose`` - An optional boolean specifying whether or not to print verbosely. A value - of ``true`` is equivalent to passing :option:`--verbose <cpack --verbose>` - on the command line. - -``packageName`` - An optional string representing the package name. - -``packageVersion`` - An optional string representing the package version. - -``packageDirectory`` - An optional string representing the directory in which to place the package. - -``vendorName`` - An optional string representing the vendor name. +.. include:: presets/packagePresets-properties.rst .. _`Workflow Preset`: Workflow Preset ^^^^^^^^^^^^^^^ -Workflow presets may be used in schema version ``6`` or above. Each entry of -the ``workflowPresets`` array is a JSON object that may contain the following -fields: +.. presets-versionadded:: 6 -``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 - ``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. +Each entry of the ``workflowPresets`` array is a JSON object +that may contain the following fields: -``vendor`` - 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. - -``displayName`` - An optional string with a human-friendly name of the preset. - -``description`` - An optional string with a human-friendly description of the preset. - -``steps`` - 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. Each object may contain the following fields: - - ``type`` - A required string. The first step must be ``configure``. Subsequent steps - must be either ``build``, ``test``, or ``package``. - - ``name`` - A required string representing the name of the configure, build, test, or - package preset to run as this workflow step. +.. include:: presets/workflowPresets-properties.rst Condition ^^^^^^^^^ -The ``condition`` field of a preset, allowed in preset files specifying version -``3`` or above, is used to determine whether or not the preset is enabled. For -example, this can be used to disable a preset on platforms other than Windows. -``condition`` may be either a boolean, ``null``, or an object. If it is a -boolean, the boolean indicates whether the preset is enabled or disabled. If it -is ``null``, the preset is enabled, but the ``null`` condition is not inherited -by any presets that may inherit from the preset. Sub-conditions (for example in -a ``not``, ``anyOf``, or ``allOf`` condition) may not be ``null``. If it is an -object, it has the following fields: +.. presets-versionadded:: 3 + +The ``condition`` field of a preset is used to determine whether or not the +preset is enabled. For example, this can be used to disable a preset on +platforms other than Windows. ``condition`` may be either a boolean, ``null``, +or an object. If it is a boolean, the boolean indicates whether the preset is +enabled or disabled. If it is ``null``, the preset is enabled, but the ``null`` +condition is not inherited by any presets that may inherit from the preset. +Sub-conditions (for example in a ``not``, ``anyOf``, or ``allOf`` condition) +may not be ``null``. If it is an object, it has the following fields: ``type`` A required string with one of the following values: @@ -1161,9 +175,7 @@ A required boolean which provides a constant value for the condition's evaluation. - ``"equals"`` - - ``"notEquals"`` + ``"equals"``, ``"notEquals"`` Indicates that the condition compares two strings to see if they are equal (or not equal). The condition object will have the following additional fields: @@ -1174,9 +186,7 @@ ``rhs`` Second string to compare. This field supports macro expansion. - ``"inList"`` - - ``"notInList"`` + ``"inList"``, ``"notInList"`` Indicates that the condition searches for a string in a list of strings. The condition object will have the following additional fields: @@ -1187,9 +197,7 @@ A required array of strings to search. This field supports macro expansion, and uses short-circuit evaluation. - ``"matches"`` - - ``"notMatches"`` + ``"matches"``, ``"notMatches"`` Indicates that the condition searches for a regular expression in a string. The condition object will have the following additional fields: @@ -1200,9 +208,7 @@ A required regular expression to search for. This field supports macro expansion. - ``"anyOf"`` - - ``"allOf"`` + ``"anyOf"``, ``"allOf"`` Indicates that the condition is an aggregation of zero or more nested conditions. The condition object will have the following additional fields: @@ -1222,12 +228,14 @@ ^^^^^^^^^^^^^^^ As mentioned above, some fields support macro expansion. Macros are -recognized in the form ``$<macro-namespace>{<macro-name>}``. All macros are -evaluated in the context of the preset being used, even if the macro is in a -field that was inherited from another preset. For example, if the ``Base`` -preset sets variable ``PRESET_NAME`` to ``${presetName}``, and the -``Derived`` preset inherits from ``Base``, ``PRESET_NAME`` will be set to -``Derived``. +recognized in the form ``$<macro-namespace>{<macro-name>}``. + +In general, macros are evaluated in the context of the preset being used, even +if the macro is in a field that was inherited from another preset. For example, +if the ``Base`` preset sets variable ``PRESET_NAME`` to ``${presetName}``, and +the ``Derived`` preset inherits from ``Base``, ``PRESET_NAME`` will be set to +``Derived``. The ``${fileDir}`` macro as of preset version ``12`` is an +exception to this rule. It is an error to not put a closing brace at the end of a macro name. For example, ``${sourceDir`` is invalid. A dollar sign (``$``) followed by @@ -1259,19 +267,59 @@ This is a preset-specific macro. +.. _`CMakePresets hostSystemName`: + ``${hostSystemName}`` + .. presets-versionadded:: 3 + 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. + :variable:`CMAKE_HOST_SYSTEM_NAME`. + +.. _`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. + .. presets-versionadded:: 4 + + Path to the directory containing the presets file which defines the preset + being used. + + .. presets-versionchanged:: 12 + + This macro *always* expands to the directory of the current presets file + containing the macro, regardless of the preset being used. + + For example, consider the following scenario. + + * ``/path/to/CMakePresets.json`` includes + ``/path/to/subdir/CMakePresets.json``. + * ``/path/to/subdir/CMakePresets.json`` defines preset ``Base``, which + sets variable ``MY_DIR`` to ``${fileDir}``. + * ``/path/to/CMakePresets.json`` defines preset ``Derived``, and + ``Derived`` inherits from ``Base``. + + Under preset versions ``4``-``11``, ``MY_DIR`` will be set to ``/path/to/`` + when using the ``Base`` preset, and ``/path/to/subdir/`` when using the + ``Derived`` preset. + + When ``/path/to/subdir/CMakePresets.json`` specifies version ``12`` or + above, ``MY_DIR`` will always be set to ``/path/to/subdir/``, regardless of + the preset being used. + + .. note:: + + Since the ``${fileDir}`` macro in version 12 is expanded in the context + of the current presets file, it is the version of the current file, rather + than the version of the root file containing the preset being used, which + enables this alternative behavior. ``${dollar}`` A literal dollar sign (``$``). +.. _`CMakePresets pathListSep`: + ``${pathListSep}`` + .. presets-versionadded:: 5 + Native character for separating lists of paths, such as ``:`` or ``;``. For example, by setting ``PATH`` to @@ -1279,8 +327,6 @@ expand to the underlying operating system's character used for concatenation in ``PATH``. - This is allowed in preset files specifying version ``5`` or above. - ``$env{<variable-name>}`` Environment variable with name ``<variable-name>``. The variable name may not be an empty string. If the variable is defined in the ``environment`` @@ -1314,8 +360,149 @@ 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 CMake presets files 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 :preset:`configurePresets.installDir` field was added. + * The :preset:`configurePresets.toolchainFile` field was added. + * The :preset:`configurePresets.binaryDir` field is now optional. + * The :preset:`configurePresets.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 :preset:`buildPresets.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 :preset:`testPresets.output.testOutputTruncation` field was added + to the :preset:`testPresets.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 :preset:`testPresets.output.outputJUnitFile` field was added to the + :preset:`testPresets.output` object. + + ``7`` + .. versionadded:: 3.27 + + * Changes to `Configure Presets <Configure Preset_>`_ + + * The :preset:`configurePresets.trace` field was added. + + * Changes to `Includes`_ + + * The :preset:`include` field now supports ``$penv{}`` `macro expansion`_. + + ``8`` + .. versionadded:: 3.28 + + * The :preset:`$schema` field was added to the root object. + + ``9`` + .. versionadded:: 3.30 + + * Changes to `Includes`_ + + * The :preset:`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 :preset:`configurePresets.graphviz` field was added. + + ``11`` + .. versionadded:: 4.3 + + * Changes to `Test Presets <Test Preset_>`_ + + * The :preset:`testPresets.execution.jobs` field now accepts an empty + string representing :ctest-option:`--parallel` with ``<jobs>`` omitted. + + ``12`` + .. versionadded:: 4.4 + + * Changes to `Configure Presets <Configure Preset_>`_: + + * The ``dev`` field is renamed to ``author`` in + :preset:`configurePresets.warnings` and + :preset:`configurePresets.errors`. + + * The ``uninitialized`` and ``unusedCli`` fields were added to + :preset:`configurePresets.errors`. + + * The ``installAbsoluteDestination`` field was added to + :preset:`configurePresets.warnings` and :preset:`configurePresets.errors`. + + * Changes to `Macro Expansion`_ + + * The `${fileDir} <CMakePresets fileDir_>`_ macro now always expands to + the directory of presets file containing the ``${fileDir}`` macro, + regardless of whether it is inherited by another preset in a different + directory. + + * Changes to `Test Presets <Test Preset_>`_ + + * The :preset:`testPresets.execution.testPassthroughArguments` field was + added to forward arguments to test executables. + Schema ====== :download:`This file </manual/presets/schema.json>` provides a machine-readable -JSON schema for the ``CMakePresets.json`` format. +JSON schema for the CMake presets file format.
diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index a2b88dd..aec1892 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 @@ -84,7 +84,6 @@ /prop_dir/LINK_DIRECTORIES /prop_dir/LINK_OPTIONS /prop_dir/LISTFILE_STACK - /prop_dir/MACROS /prop_dir/PARENT_DIRECTORY /prop_dir/RULE_LAUNCH_COMPILE /prop_dir/RULE_LAUNCH_CUSTOM @@ -226,6 +225,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 +256,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 +284,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 @@ -302,6 +306,7 @@ /prop_tgt/INTERFACE_LINK_OPTIONS /prop_tgt/INTERFACE_POSITION_INDEPENDENT_CODE /prop_tgt/INTERFACE_PRECOMPILE_HEADERS + /prop_tgt/INTERFACE_SOURCE_SETS /prop_tgt/INTERFACE_SOURCES /prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES /prop_tgt/INTERPROCEDURAL_OPTIMIZATION @@ -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 @@ -399,10 +405,18 @@ /prop_tgt/RUNTIME_OUTPUT_DIRECTORY_CONFIG /prop_tgt/RUNTIME_OUTPUT_NAME /prop_tgt/RUNTIME_OUTPUT_NAME_CONFIG + /prop_tgt/Rust_EDITION /prop_tgt/SKIP_BUILD_RPATH + /prop_tgt/SKIP_LINTING /prop_tgt/SOURCE_DIR + /prop_tgt/SOURCE_DIRS + /prop_tgt/SOURCE_DIRS_NAME + /prop_tgt/SOURCE_SET + /prop_tgt/SOURCE_SET_NAME + /prop_tgt/SOURCE_SETS /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 +426,9 @@ /prop_tgt/Swift_LANGUAGE_VERSION /prop_tgt/Swift_MODULE_DIRECTORY /prop_tgt/Swift_MODULE_NAME + /prop_tgt/Swift_PACKAGE_NAME + /prop_tgt/Swift_SEPARATE_MODULE_EMISSION + /prop_tgt/SYMBOLIC /prop_tgt/SYSTEM /prop_tgt/TEST_LAUNCHER /prop_tgt/TRANSITIVE_COMPILE_PROPERTIES @@ -421,10 +438,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 +517,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 @@ -514,6 +533,30 @@ /prop_tgt/XCODE_XCCONFIG /prop_tgt/XCTEST +.. _`File Set Properties`: + +Properties on File Sets +======================= + +.. toctree:: + :maxdepth: 1 + + /prop_fs/BASE_DIRS + /prop_fs/COMPILE_DEFINITIONS + /prop_fs/COMPILE_OPTIONS + /prop_fs/CXX_SCAN_FOR_MODULES + /prop_fs/JOB_POOL_COMPILE + /prop_fs/INCLUDE_DIRECTORIES + /prop_fs/INDEPENDENT_FILES + /prop_fs/INTERFACE_COMPILE_DEFINITIONS + /prop_fs/INTERFACE_COMPILE_OPTIONS + /prop_fs/INTERFACE_INCLUDE_DIRECTORIES + /prop_fs/INTERFACE_SOURCES + /prop_fs/SCOPE + /prop_fs/SKIP_LINTING + /prop_fs/SOURCES + /prop_fs/TYPE + .. _`Test Properties`: Properties on Tests @@ -573,13 +616,17 @@ /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/Rust_EMIT /prop_sf/SKIP_AUTOGEN /prop_sf/SKIP_AUTOMOC /prop_sf/SKIP_AUTORCC @@ -656,6 +703,7 @@ /prop_dir/COMPILE_DEFINITIONS_CONFIG /prop_dir/INTERPROCEDURAL_OPTIMIZATION /prop_dir/INTERPROCEDURAL_OPTIMIZATION_CONFIG + /prop_dir/MACROS /prop_dir/TEST_INCLUDE_FILE
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..71318dd 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 @@ -125,6 +142,7 @@ /variable/CMAKE_Swift_COMPILATION_MODE /variable/CMAKE_Swift_MODULE_DIRECTORY /variable/CMAKE_Swift_NUM_THREADS + /variable/CMAKE_Swift_SEPARATE_MODULE_EMISSION /variable/CMAKE_TEST_LAUNCHER /variable/CMAKE_TOOLCHAIN_FILE /variable/CMAKE_TWEAK_VERSION @@ -154,28 +172,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 +208,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 +230,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 +264,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 +335,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 +365,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 +410,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 +451,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 +485,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 +506,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 +518,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 +530,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 @@ -553,6 +578,7 @@ /variable/CMAKE_POSITION_INDEPENDENT_CODE /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG + /variable/CMAKE_Rust_EDITION /variable/CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS /variable/CMAKE_SHARED_LINKER_FLAGS /variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG @@ -560,6 +586,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 +601,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 +706,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 @@ -776,6 +806,7 @@ /variable/CTEST_SVN_UPDATE_OPTIONS /variable/CTEST_TEST_LOAD /variable/CTEST_TEST_TIMEOUT + /variable/CTEST_TEST_COVERAGE_TOOL /variable/CTEST_TLS_VERIFY /variable/CTEST_TLS_VERSION /variable/CTEST_UPDATE_COMMAND @@ -872,6 +903,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..7b7680f 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst
@@ -99,9 +99,8 @@ This chooses the kind of buildsystem to generate. See the :manual:`cmake-generators(7)` manual for documentation of all generators. Run :option:`cmake --help` to see a list of generators available locally. - Optionally use the :option:`-G <cmake -G>` option below to specify a - generator, or simply accept the default CMake chooses for the current - platform. + Optionally use the :cmake-option:`-G` option below to specify a generator, + or simply accept the default CMake chooses for the current platform. When using one of the :ref:`Command-Line Build Tool Generators` CMake expects that the environment needed by the compiler toolchain @@ -158,11 +157,11 @@ In all cases the ``<options>`` may be zero or more of the `Options`_ below. The above styles for specifying the source and build trees may be mixed. -Paths specified with :option:`-S <cmake -S>` or :option:`-B <cmake -B>` -are always classified as source or build trees, respectively. Paths -specified with plain arguments are classified based on their content -and the types of paths given earlier. If only one type of path is given, -the current working directory (cwd) is used for the other. For example: +Paths specified with :cmake-option:`-S` or :cmake-option:`-B` are always +classified as source or build trees, respectively. Paths specified with plain +arguments are classified based on their content and the types of paths given +earlier. If only one type of path is given, the current working directory +(cwd) is used for the other. For example: ============================== ============ =========== Command Line Source Dir Build Dir @@ -225,12 +224,12 @@ List non-advanced cached variables. List ``CACHE`` variables will run CMake and list all the variables from - the CMake ``CACHE`` that are not marked as ``INTERNAL`` or :prop_cache:`ADVANCED`. - This will effectively display current CMake settings, which can then be - changed with :option:`-D <cmake -D>` option. Changing some of the variables - may result in more variables being created. If ``A`` is specified, then it - will display also advanced variables. If ``H`` is specified, it will also - display help for each variable. + the CMake ``CACHE`` that are not marked as ``INTERNAL`` or + :prop_cache:`ADVANCED`. This will effectively display current CMake + settings, which can then be changed with :cmake-option:`-D` option. + Changing some of the variables may result in more variables being created. + If ``A`` is specified, then it will display also advanced variables. + If ``H`` is specified, it will also display help for each variable. .. option:: -LR[A][H] <regex> @@ -252,11 +251,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] @@ -365,7 +498,7 @@ is an entry in the given comma-separated list of case-sensitive package names. - Like :option:`--debug-find <cmake --debug-find>`, but limiting scope + Like :cmake-option:`--debug-find`, but limiting scope to the specified packages. .. option:: --debug-find-var=<var>[,...] @@ -376,7 +509,7 @@ as the result variable, where ``<var>`` is an entry in the given comma-separated list. - Like :option:`--debug-find <cmake --debug-find>`, but limiting scope + Like :cmake-option:`--debug-find`, but limiting scope to the specified variable names. .. option:: --trace @@ -389,7 +522,7 @@ Put cmake in trace mode. - Like :option:`--trace <cmake --trace>`, but with variables expanded. + Like :cmake-option:`--trace`, but with variables expanded. .. option:: --trace-format=<format> @@ -490,22 +623,23 @@ .. option:: --warn-uninitialized - Warn about uninitialized values. + .. deprecated:: 4.4 - Print a warning when an uninitialized variable is used. + Compatibility synonym for ``-Wuninitialized``. .. option:: --warn-unused-vars + .. deprecated:: 3.19 + Does nothing. In CMake versions 3.2 and below this enabled warnings about unused variables. In CMake versions 3.3 through 3.18 the option was broken. In CMake 3.19 and above the option has been removed. .. option:: --no-warn-unused-cli - Don't warn about command line options. + .. deprecated:: 4.4 - Don't find variables that are declared on the command line, but not - used. + Compatibility synonym for ``-Wno-unused-cli``. .. option:: --check-system-vars @@ -535,9 +669,8 @@ .. versionadded:: 3.18 - Used in conjunction with - :option:`--profiling-format <cmake --profiling-format>` to output to a - given path. + Used in conjunction with :cmake-option:`--profiling-format` + to output to a given path. .. option:: --profiling-format=<file> @@ -553,43 +686,75 @@ .. option:: --preset <preset>, --preset=<preset> - Reads a :manual:`preset <cmake-presets(7)>` from ``CMakePresets.json`` and - ``CMakeUserPresets.json`` files, which must be located in the same directory - as the top level ``CMakeLists.txt`` file. The preset may specify the - generator, the build directory, a list of variables, and other arguments to - pass to CMake. At least one of ``CMakePresets.json`` or - ``CMakeUserPresets.json`` must be present. + Reads a :manual:`preset <cmake-presets(7)>` from CMake presets files. + ``CMakePresets.json`` and ``CMakeUserPresets.json`` are the default files, + which must be located in the same directory as the top level + ``CMakeLists.txt`` file. A file can also be specified with + :cmake-option:`--presets-file`. + + The preset may specify the generator, the build directory, a list of + variables, and other arguments to pass to CMake. + The :manual:`CMake GUI <cmake-gui(1)>` also recognizes and supports ``CMakePresets.json`` and ``CMakeUserPresets.json`` files. For full details on these files, see :manual:`cmake-presets(7)`. The presets are read before all other command line options, although the - :option:`-S <cmake -S>` option can be used to specify the source directory + :cmake-option:`-S` option can be used to specify the source directory containing the ``CMakePresets.json`` and ``CMakeUserPresets.json`` files. - If :option:`-S <cmake -S>` is not given, the current directory is assumed to - be the top level source directory and must contain the presets files. The - options specified by the chosen preset (variables, generator, etc.) can all - be overridden by manually specifying them on the command line. For example, - 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. + If neither :cmake-option:`-S` nor :cmake-option:`--presets-file` are given, + the current working directory is assumed to be the top level source directory + and must contain ``CMakePresets.json`` and/or ``CMakeUserPresets.json``. + + The options specified by the chosen preset (variables, generator, etc.) + can all be overridden by manually specifying them on the command line. + For example, if the preset sets a variable called ``MYVAR`` to ``1``, + but the user sets it to ``2`` with a :cmake-option:`-D` argument, + the value ``2`` is preferred. + + .. versionadded:: 3.21 + The :cmake-option:`-B` option may optionally be specified with a different + binary directory than the one specified by the + :preset:`configurePresets.binaryDir` field. + + .. versionchanged:: 4.4 + If :cmake-option:`--presets-file` is specified, neither of + ``CMakePresets.json`` nor ``CMakeUserPresets.json`` are required to be + present. In prior versions, the presence of these files in the top-level + source directory (whether via :cmake-option:`-S` or the current working + directory) was strictly required. + +.. option:: --presets-file <file>, --presets-file=<file> + + .. versionadded:: 4.4 + + Reads :manual:`presets <cmake-presets(7)>` from the given ``<file>``. The + specified path may be absolute or relative to the current working directory. + If ``--presets-file`` is given, presets defined in ``CMakePresets.json`` and + ``CMakeUserPresets.json`` will be ignored. .. option:: --list-presets[=<type>] Lists the available presets of the specified ``<type>``. Valid values for ``<type>`` are ``configure``, ``build``, ``test``, ``package``, or ``all``. - If ``<type>`` is omitted, ``configure`` is assumed. The current working - directory must contain CMake preset files unless the :option:`-S <cmake -S>` - option is used to specify a different top level source directory. + If ``<type>`` is omitted, ``configure`` is assumed. + + .. versionchanged:: 4.4 + If :cmake-option:`--presets-file` is specified, the presets defined in the + given ``<file>`` will be listed. Otherwise, the top-level source directory + (whether via :cmake-option:`-S` or the current working directory) must + contain ``CMakePresets.json`` and/or ``CMakeUserPresets.json``. + In prior versions, the latter was strictly required. .. option:: --debugger - Enables interactive debugging of the CMake language. CMake exposes a debugging - interface on the pipe named by :option:`--debugger-pipe <cmake --debugger-pipe>` - that conforms to the `Debug Adapter Protocol`_ specification with the following - modifications. + Enables interactive debugging of the CMake language. CMake exposes a + debugging interface on the pipe named by :cmake-option:`--debugger-pipe` + that conforms to the `Debug Adapter Protocol`_ specification with the + following modifications. - The ``initialize`` response includes an additional field named ``cmakeVersion`` - which specifies the version of CMake being debugged. + The ``initialize`` response includes an additional field named + ``cmakeVersion`` which specifies the version of CMake being debugged. .. code-block:: json :caption: Debugger initialize response @@ -640,8 +805,8 @@ .. code-block:: shell - cmake --build <dir> [<options>] [-- <build-tool-options>] - cmake --build --preset <preset> [<options>] [-- <build-tool-options>] + cmake --build <dir> [<options>] [-- <build-tool-options>] + cmake --build [<dir>] --preset <preset> [<options>] [-- <build-tool-options>] This abstracts a native build tool's command-line interface with the following options: @@ -655,15 +820,41 @@ .. 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. + Use a build :manual:`preset <cmake-presets(7)>` to specify build options. + The project binary directory is inferred from the + :preset:`buildPresets.configurePreset` key unless a directory is specified + after ``--build``. + + .. versionadded:: 4.3 + ``cmake --build`` now supports specifying a build directory and + preset together. + + .. versionchanged:: 4.4 + ``cmake --build <dir> --preset`` no longer needs to be called from the + directory containing ``CMakePresets.json`` or ``CMakeUserPresets.json``. + If :cmake-build-option:`--presets-file` is specified, CMake will use that + file; otherwise, the presets file(s) can be inferred from the current + build directory's ``CMakeCache.txt``. + +.. option:: --presets-file <file>, --presets-file=<file> + + .. versionadded:: 4.4 + + Reads :manual:`presets <cmake-presets(7)>` from the given ``<file>``. The + specified path may be absolute or relative to the current working directory. + If ``--presets-file`` is given, presets defined in ``CMakePresets.json`` and + ``CMakeUserPresets.json`` will be ignored. .. option:: --list-presets - Lists the available build presets. The current working directory must - contain CMake preset files. + Lists the available build presets. + + .. versionchanged:: 4.4 + ``cmake --build <dir> --list-presets`` no longer needs to be called from + the directory containing ``CMakePresets.json`` or ``CMakeUserPresets.json``. + If :cmake-build-option:`--presets-file` is specified, only presets defined + in the given ``<file>`` will be listed; otherwise, the presets file(s) are + inferred from the current build directory's ``CMakeCache.txt``. .. option:: -j [<jobs>], --parallel [<jobs>] @@ -779,13 +970,36 @@ Component-based install. Only install component ``<comp>``. + .. versionadded:: 4.4 + + Supports installing more than one component: + + * ``--component <compA> <compB>`` + * ``--component <compA> --component <compB>`` + .. option:: --default-directory-permissions <permissions> Default directory install permissions. Permissions in format ``<u=rwx,g=rx,o=rx>``. .. 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 +1087,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 @@ -884,7 +1170,7 @@ A JSON object with version information. Keys are: ``string`` - The full version string as displayed by cmake :option:`--version <cmake --version>`. + The full version string as displayed by cmake :cmake-option:`--version`. ``major`` The major version number in integer form. ``minor`` @@ -945,8 +1231,8 @@ ``debugger`` .. versionadded:: 3.27 - ``true`` if the :option:`--debugger <cmake --debugger>` mode - is supported and ``false`` otherwise. + ``true`` if the :cmake-option:`--debugger` mode is supported + and ``false`` otherwise. .. option:: cat [--] <files>... @@ -969,6 +1255,10 @@ ``cat`` can now print the standard input by passing the ``-`` argument. + .. versionadded:: 4.4 + + ``cat`` will print the standard input when no arguments are passed. + .. program:: cmake-E .. option:: chdir <dir> <cmd> [<arg>...] @@ -991,11 +1281,12 @@ .. program:: cmake-E -.. option:: copy <file>... <destination>, copy -t <destination> <file>... +.. option:: copy <file>... <destination>, + copy -t <destination> <file>... Copy files to ``<destination>`` (either file or directory). If multiple files are specified, or if ``-t`` is specified, the - ``<destination>`` must be directory and it must exist. If ``-t`` is not + ``<destination>`` must be a directory and it must exist. If ``-t`` is not specified, the last argument is assumed to be the ``<destination>``. Wildcards are not supported. ``copy`` does follow symlinks. That means it does not copy symlinks, but the files or directories it point to. @@ -1006,10 +1297,13 @@ .. versionadded:: 3.26 Support for ``-t`` argument. -.. option:: copy_directory <dir>... <destination> +.. option:: copy_directory <dir>... <destination>, + copy_directory -t <destination> <dir>... - Copy content of ``<dir>...`` directories to ``<destination>`` directory. - If ``<destination>`` directory does not exist it will be created. + Copy content of ``<dir>...`` directories to a ``<destination>`` directory. + If the ``<destination>`` directory does not exist it will be created. + If ``-t`` is not specified, the last argument is assumed to be the + ``<destination>``. ``copy_directory`` does follow symlinks. .. versionadded:: 3.5 @@ -1019,27 +1313,75 @@ The command now fails when the source directory does not exist. Previously it succeeded by creating an empty destination directory. -.. option:: copy_directory_if_different <dir>... <destination> + .. versionadded:: 4.4 + Support for the ``-t`` argument. + +.. option:: copy_directory_if_different <dir>... <destination>, + copy_directory_if_different -t <destination> <dir>... .. versionadded:: 3.26 - Copy changed content of ``<dir>...`` directories to ``<destination>`` directory. - If ``<destination>`` directory does not exist it will be created. + Copy changed content of ``<dir>...`` directories to a ``<destination>`` directory. + If the ``<destination>`` directory does not exist it will be created. + If ``-t`` is not specified, the last argument is assumed to be the + ``<destination>``. ``copy_directory_if_different`` does follow symlinks. The command fails when the source directory does not exist. -.. option:: copy_if_different <file>... <destination> + .. versionadded:: 4.4 + Support for the ``-t`` argument. + +.. option:: copy_directory_if_newer <dir>... <destination>, + copy_directory_if_newer -t <destination> <dir>... + + .. versionadded:: 4.2 + + Copy content of ``<dir>...`` directories to a ``<destination>`` directory + if source files are newer than destination files (based on file timestamps). + If the ``<destination>`` directory does not exist it will be created. + If ``-t`` is not specified, the last argument is assumed to be the + ``<destination>``. + + ``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. + + .. versionadded:: 4.4 + Support for the ``-t`` argument. + +.. option:: copy_if_different <file>... <destination>, + copy_if_different -t <destination> <file>... Copy files to ``<destination>`` (either file or directory) if they have changed. - If multiple files are specified, the ``<destination>`` must be - directory and it must exist. + If multiple files are specified, or if ``-t`` is specified, + the ``<destination>`` must be a directory and it must exist. ``copy_if_different`` does follow symlinks. .. versionadded:: 3.5 Support for multiple input files. + .. versionadded:: 4.4 + Support for the ``-t`` argument. + +.. option:: copy_if_newer <file>... <destination>, + copy_if_newer -t <destination> <file>... + + .. 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, or if ``-t`` is specified, + the ``<destination>`` must be a 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. + + .. versionadded:: 4.4 + Support for the ``-t`` argument. + .. option:: create_symlink <old> <new> Create a symbolic link ``<new>`` naming ``<old>``. @@ -1133,6 +1475,9 @@ 351abe79cd3800b38cdfb25d45015a15 file1.txt 052f86c15bbde68af55c7f7b340ab639 file2.txt + .. versionchanged:: 4.3 + Passing ``-`` reads from standard input. + .. option:: sha1sum <file>... .. versionadded:: 3.10 @@ -1142,6 +1487,9 @@ 4bb7932a29e6f73c97bb9272f2bdc393122f86e0 file1.txt 1df4c8f318665f9a5f2ed38f55adadb7ef9f559c file2.txt + .. versionchanged:: 4.3 + Passing ``-`` reads from standard input. + .. option:: sha224sum <file>... .. versionadded:: 3.10 @@ -1151,6 +1499,9 @@ b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930 file1.txt 6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24 file2.txt + .. versionchanged:: 4.3 + Passing ``-`` reads from standard input. + .. option:: sha256sum <file>... .. versionadded:: 3.10 @@ -1160,6 +1511,9 @@ 76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc file1.txt 15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea file2.txt + .. versionchanged:: 4.3 + Passing ``-`` reads from standard input. + .. option:: sha384sum <file>... .. versionadded:: 3.10 @@ -1169,6 +1523,9 @@ acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434 file1.txt 668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d file2.txt + .. versionchanged:: 4.3 + Passing ``-`` reads from standard input. + .. option:: sha512sum <file>... .. versionadded:: 3.10 @@ -1178,6 +1535,9 @@ 2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89 file1.txt 7a0b54896fe5e70cca6dd643ad6f672614b189bf26f8153061c4d219474b05dad08c4e729af9f4b009f1a1a280cb625454bf587c690f4617c27e3aebdf3b7a2d file2.txt + .. versionchanged:: 4.3 + Passing ``-`` reads from standard input. + .. option:: remove [-f] <file>... .. deprecated:: 3.17 @@ -1257,6 +1617,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 +1635,7 @@ .. option:: z - Compress the resulting archive with gzip. + Compress the resulting archive with gzip (Deflate). .. option:: j @@ -1281,7 +1645,7 @@ .. versionadded:: 3.1 - Compress the resulting archive with XZ. + Compress the resulting archive with XZ (LZMA2). .. option:: --zstd @@ -1289,6 +1653,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 +1673,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 +1707,89 @@ 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-encoding=<encoding> + + .. versionadded:: 4.4 + + Specify the pathname character encoding used in the archive. + + The ``<encoding>`` may be one of: + + ``UTF-8`` + Archive pathnames are encoded as UTF-8. + + This is the default since CMake 4.4. + + ``OEM`` + On Windows platforms, pathnames are encoded as using the original + equipment manufacturer (OEM) code page. On non-Windows platforms, + pathnames are encoded according to the current locale. + + In CMake 4.3 and below, the ``OEM`` encoding (current locale) + was always used. + + ``UTF-16LE``, ``UTF-16BE`` + Archive pathnames are encoded as UTF-16 little-endian or big-endian. + + ``...`` + Any encoding name supported by ``iconv`` on the current platform. + On Windows, code page names may be specified. + + .. note:: + ``7zip`` archives always encode paths as ``UTF-16LE``, + so this option is silently ignored for that format. + + .. 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 @@ -1474,10 +1952,8 @@ .. option:: --preset <preset>, --preset=<preset> - Use a workflow preset to specify a workflow. The project binary directory - is inferred from the initial configure preset. The current working directory - must contain CMake preset files. - See :manual:`preset <cmake-presets(7)>` for more details. + Use a workflow :manual:`preset <cmake-presets(7)>` to specify a workflow. + The project binary directory is inferred from the initial configure preset. .. versionchanged:: 3.31 When following immediately after the ``--workflow`` option, @@ -1488,10 +1964,31 @@ $ cmake --workflow my-preset + .. versionchanged:: 4.4 + If :cmake-workflow-option:`--presets-file` is specified, neither of + ``CMakePresets.json`` nor ``CMakeUserPresets.json`` are required to be + present. Otherwise, they are required to be present in the top level + source directory. In prior versions, this was strictly required. + +.. option:: --presets-file <file>, --presets-file=<file> + + .. versionadded:: 4.4 + + Reads :manual:`presets <cmake-presets(7)>` from the given ``<file>``. The + specified path may be absolute or relative to the current working directory. + If ``--presets-file`` is given, presets defined in ``CMakePresets.json`` and + ``CMakeUserPresets.json`` will be ignored. + .. option:: --list-presets - Lists the available workflow presets. The current working directory must - contain CMake preset files. + Lists the available workflow presets. + + .. versionchanged:: 4.4 + If :cmake-workflow-option:`--presets-file` is specified, neither of + ``CMakePresets.json`` nor ``CMakeUserPresets.json`` are required to be + present, and only presets defined in the given ``<file>`` will be listed. + Otherwise, they are required to be present in the top level source + directory. In prior versions, this was strictly required. .. option:: --fresh
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/cpack.1.rst b/Help/manual/cpack.1.rst index d1ca268..686d153 100644 --- a/Help/manual/cpack.1.rst +++ b/Help/manual/cpack.1.rst
@@ -26,11 +26,11 @@ <cpack-generators(7)>` manual. The command ``cpack --help`` prints a list of generators supported for the target platform. Which of them are to be used can be selected through the :variable:`CPACK_GENERATOR` variable -or through the command-line option :option:`-G <cpack -G>`. +or through the command-line option :cpack-option:`-G`. The :program:`cpack` program is steered by a configuration file written in the :manual:`CMake language <cmake-language(7)>`. Unless chosen differently -through the command-line option :option:`--config <cpack --config>`, the +through the command-line option :cpack-option:`--config`, the file ``CPackConfig.cmake`` in the current directory is used. In the standard CMake workflow, the file ``CPackConfig.cmake`` is generated @@ -120,13 +120,37 @@ Override/define :variable:`CPACK_PACKAGE_VENDOR`. -.. option:: --preset <presetName> +.. option:: --preset <preset>, --preset=<preset> - Use a preset from :manual:`cmake-presets(7)`. + Use a package :manual:`preset <cmake-presets(7)>` to specify package + options. The project binary directory is inferred from the + :preset:`packagePresets.configurePreset` key. + + .. versionchanged:: 4.4 + If :cpack-option:`--presets-file` is specified, neither of + ``CMakePresets.json`` nor ``CMakeUserPresets.json`` are required to be + present. Otherwise, they are required to be present in the top level + source directory. In prior versions, this was strictly required. + +.. option:: --presets-file <file>, --presets-file=<file> + + .. versionadded:: 4.4 + + Reads :manual:`presets <cmake-presets(7)>` from the given ``<file>``. The + specified path may be absolute or relative to the current working directory. + If ``--presets-file`` is given, presets defined in ``CMakePresets.json`` and + ``CMakeUserPresets.json`` will be ignored. .. option:: --list-presets - List presets from :manual:`cmake-presets(7)`. + Lists the available package presets. + + .. versionchanged:: 4.4 + If :cpack-option:`--presets-file` is specified, neither of + ``CMakePresets.json`` nor ``CMakeUserPresets.json`` are required to be + present, and only presets defined in the given ``<file>`` will be listed. + Otherwise, they are required to be present in the top level source + directory. In prior versions, this was strictly required. .. include:: include/OPTIONS_HELP.rst
diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 3a871bb..4ab9d75 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst
@@ -11,7 +11,7 @@ .. parsed-literal:: `Run Tests`_ - ctest [<options>] [--test-dir <path-to-build>] + ctest [<options>...] [--test-dir <path-to-build>] [-- <test-args>...] `Build and Test Mode`_ ctest --build-and-test <path-to-source> <path-to-build> @@ -42,19 +42,68 @@ Run Tests ========= +:program:`ctest` runs tests defined by a ``CTestTestfile.cmake`` file, +typically in a build tree generated by :manual:`cmake(1)`: + +.. code-block:: shell + + ctest [<options>...] [--test-dir <path-to-build>] [-- <test-args>...] + +If all tests pass, the exit code is ``0``. The exit code is non-zero +in the following cases: + +* An error occurs, such as failure to process invalid arguments. + +* .. versionadded:: 4.4 + No arguments are given and no ``CTestTestfile.cmake`` exists. + +* The :ctest-option:`--no-tests=error` argument is given and no tests are + executed, e.g., when ``CTestTestfile.cmake`` defines no tests, or when the + given arguments exclude all tests. + +* At least one test fails. + +The options for running tests are: + .. program:: ctest .. option:: --preset <preset>, --preset=<preset> - Use a test preset to specify test 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. + Use a test :manual:`preset <cmake-presets(7)>` to specify test options. The + project binary directory is inferred from the + :preset:`testPresets.configurePreset` key. + + .. versionadded:: 3.30 + The :ctest-option:`--test-dir` option may be specified with a different + binary directory than the one specified by the + :preset:`testPresets.configurePreset` key. + + .. versionchanged:: 4.4 + If :ctest-option:`--presets-file` is specified, neither of + ``CMakePresets.json`` nor ``CMakeUserPresets.json`` are required to be + present. Otherwise, they are required to be present in the top level + source directory. In prior versions, this was strictly required. + +.. option:: --presets-file <file>, --presets-file=<file> + + .. versionadded:: 4.4 + + Reads :manual:`presets <cmake-presets(7)>` from the given ``<file>``. The + specified path may be absolute or relative to the current working directory. + If ``--presets-file`` is given, presets defined in ``CMakePresets.json`` and + ``CMakeUserPresets.json`` will be ignored. .. option:: --list-presets Lists the available test presets. The current working directory must contain - CMake preset files. + ``CMakePresets.json`` and/or ``CMakeUserPresets.json``. + + .. versionchanged:: 4.4 + If :ctest-option:`--presets-file` is specified, neither of + ``CMakePresets.json`` nor ``CMakeUserPresets.json`` are required to be + present, and only presets defined in the given ``<file>`` will be listed. + Otherwise, they are required to be present in the top level source + directory. In prior versions, this was strictly required. .. option:: -C <cfg>, --build-config <cfg> @@ -152,9 +201,8 @@ .. option:: --test-load <level> - While running tests in parallel (e.g. with :option:`-j <ctest -j>`), try - not to start tests when they may cause the CPU load to pass above a given - threshold. + While running tests in parallel (e.g. with :ctest-option:`-j`), try not to + start tests when they may cause the CPU load to pass above a given threshold. When :program:`ctest` is run as a `Dashboard Client`_ this sets the ``TestLoad`` option of the `CTest Test Step`_. @@ -164,10 +212,10 @@ Make CTest quiet. This option will suppress all the output. The output log file will - still be generated if the :option:`--output-log <ctest --output-log>` is - specified. Options such as :option:`--verbose <ctest --verbose>`, - :option:`--extra-verbose <ctest --extra-verbose>`, and - :option:`--debug <ctest --debug>` are ignored + still be generated if the :ctest-option:`--output-log` is specified. + Options such as :ctest-option:`--verbose`, + :ctest-option:`--extra-verbose`, and + :ctest-option:`--debug` are ignored if ``--quiet`` is specified. .. option:: -O <file>, --output-log <file> @@ -184,16 +232,16 @@ This option tells CTest to write test results to ``<file>`` in JUnit XML format. If ``<file>`` already exists, it will be overwritten. If using the - :option:`-S <ctest -S>` option to run a dashboard script, use the - ``OUTPUT_JUNIT`` keyword with the :command:`ctest_test` command instead. + :ctest-option:`-S` option to run a dashboard script, use the ``OUTPUT_JUNIT`` + keyword with the :command:`ctest_test` command instead. .. option:: -N, --show-only[=<format>] Disable actual execution of tests. This option tells CTest to list the tests that would be run but not - actually run them. Useful in conjunction with the :option:`-R <ctest -R>` - and :option:`-E <ctest -E>` options. + actually run them. Useful in conjunction with the :ctest-option:`-R` + and :ctest-option:`-E` options. .. versionadded:: 3.14 @@ -282,13 +330,11 @@ .. option:: -FS <regex>, --fixture-exclude-setup <regex> - Same as :option:`-FA <ctest -FA>` except only matching setup tests are - excluded. + Same as :ctest-option:`-FA` except only matching setup tests are excluded. .. option:: -FC <regex>, --fixture-exclude-cleanup <regex> - Same as :option:`-FA <ctest -FA>` except only matching cleanup tests are - excluded. + Same as :ctest-option:`-FA` except only matching cleanup tests are excluded. .. option:: -I [Start,End,Stride,test#,test#|Test file], --tests-information @@ -302,11 +348,11 @@ .. option:: -U, --union - Take the Union of :option:`-I <ctest -I>` and :option:`-R <ctest -R>`. + Take the Union of :ctest-option:`-I` and :ctest-option:`-R`. - When both :option:`-R <ctest -R>` and :option:`-I <ctest -I>` are specified - by default the intersection of tests are run. By specifying ``-U`` the union - of tests is run instead. + When both :ctest-option:`-R` and :ctest-option:`-I` are specified by default + the intersection of tests are run. By specifying ``-U`` the union of tests + is run instead. .. option:: --rerun-failed @@ -315,8 +361,8 @@ This option tells CTest to perform only the tests that failed during its previous run. When this option is specified, CTest ignores all other options intended to modify the list of tests to run ( - :option:`-L <ctest -L>`, :option:`-R <ctest -R>`, :option:`-E <ctest -E>`, - :option:`-LE <ctest -LE>`, :option:`-I <ctest -I>`, etc). In the event that + :ctest-option:`-L`, :ctest-option:`-R`, :ctest-option:`-E`, + :ctest-option:`-LE`, :ctest-option:`-I`, etc). In the event that CTest runs and no tests fail, subsequent calls to CTest with the ``--rerun-failed`` option will run the set of tests that most recently failed (if any). @@ -484,19 +530,56 @@ .. option:: --no-tests=<action> - Regard no tests found either as error (when ``<action>`` is set to - ``error``) or ignore it (when ``<action>`` is set to ``ignore``). + Specify behavior when no tests are executed, e.g., when + ``CTestTestfile.cmake`` defines no tests, or when the given arguments + exclude all tests. The ``<action>`` may be one of: - If no tests were found, the default behavior of CTest is to always log an - error message but to return an error code in script mode only. This option - unifies the behavior of CTest by either returning an error code if no tests - were found or by ignoring it. + ``error`` + Consider running no tests to be an error. + + This is the default when running :option:`ctest -S` scripts. + + ``ignore`` + Consider running no tests to be normal. + + This is the default when `running tests <Run Tests_>`__ via the + :program:`ctest` command line, even when running as a + `dashboard client <Dashboard Client_>`__. .. versionadded:: 3.26 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. + +.. option:: -- <test-args>... + + .. versionadded:: 4.4 + + Forward extra arguments to test executables. + + All arguments after ``--`` are appended to the end of every executed + test's command line. This is useful for passing options to test + frameworks like Google Test or doctest. For example: + + .. code-block:: shell + + ctest -R my_test -- --gtest_filter=SomeTest.Case + ctest --verbose -- --success + + All selected tests receive the same extra arguments. + Use :ctest-option:`-R` or :ctest-option:`-L` to limit + which tests are executed. + + A bare ``--`` with no following arguments is silently ignored. + View Help ========= @@ -515,17 +598,16 @@ Each individual filter is a regular expression applied to the labels attached to a test. -When :option:`-L <ctest -L>` is used, in order for a test to be included in a -test run, each regular expression must match at least one -label. Using more than one :option:`-L <ctest -L>` option means "match **all** -of these". +When :ctest-option:`-L` is used, in order for a test to be included in a test +run, each regular expression must match at least one label. Using more than +one :ctest-option:`-L` option means "match **all** of these". -The :option:`-LE <ctest -LE>` option works just like :option:`-L <ctest -L>`, +The :ctest-option:`-LE` option works just like :ctest-option:`-L`, but excludes tests rather than including them. A test is excluded if each regular expression matches at least one label. -If a test has no labels attached to it, then :option:`-L <ctest -L>` will never -include that test, and :option:`-LE <ctest -LE>` will never exclude that test. +If a test has no labels attached to it, then :ctest-option:`-L` will never +include that test, and :ctest-option:`-LE` will never exclude that test. As an example of tests with labels, consider five tests, with the following labels: @@ -685,7 +767,7 @@ .. option:: --test-command The command to run as the test step with the - :option:`--build-and-test <ctest --build-and-test>` option. + :ctest-option:`--build-and-test` option. All arguments following this keyword will be assumed to be part of the test command line, so it must be the last option given. @@ -732,8 +814,7 @@ This option tells CTest to act as a CDash client where the ``<model>`` can be ``Experimental``, ``Nightly``, and ``Continuous``. - Combining ``-M`` and :option:`-T <ctest -T>` is similar to - :option:`-D <ctest -D>`. + Combining ``-M`` and :ctest-option:`-T` is similar to :ctest-option:`-D`. .. option:: -T <action>, --test-action <action> @@ -742,8 +823,7 @@ This option tells CTest to act as a CDash client and perform some action such as ``start``, ``build``, ``test`` etc. See `Dashboard Client Steps`_ for the full list of actions. - Combining :option:`-M <ctest -M>` and ``-T`` is similar to - :option:`-D <ctest -D>`. + Combining :ctest-option:`-M` and ``-T`` is similar to :ctest-option:`-D`. .. option:: -S <script>, --script <script> @@ -759,10 +839,10 @@ Execute a dashboard for a configuration. - This option does the same operations as :option:`-S <ctest -S>` but it - will do them in a separate process. This is primarily useful in cases - where the script may modify the environment and you do not want the modified - environment to impact other :option:`-S <ctest -S>` scripts. + This option does the same operations as :ctest-option:`-S` but it will do + them in a separate process. This is primarily useful in cases where the + script may modify the environment and you do not want the modified + environment to impact other :ctest-option:`-S` scripts. .. _`Dashboard Options`: @@ -773,7 +853,7 @@ Define a variable for script mode. Pass in variable values on the command line. Use in conjunction - with :option:`-S <ctest -S>` to pass variable values to a dashboard script. + with :ctest-option:`-S` to pass variable values to a dashboard script. Parsing ``-D`` arguments as variable values is only attempted if the value following ``-D`` does not match any of the known dashboard types. @@ -1214,9 +1294,9 @@ ``DefaultCTestConfigurationType`` When the build system to be launched allows build-time selection of the configuration (e.g. ``Debug``, ``Release``), this specifies - the default configuration to be built when no :option:`-C <ctest -C>` - option is given to the :program:`ctest` command. The value will be substituted - into the value of ``MakeCommand`` to replace the literal string + the default configuration to be built when no :ctest-option:`-C` + option is given to the :program:`ctest` command. The value will be + substituted into the value of ``MakeCommand`` to replace the literal string ``${CTEST_CONFIGURATION_TYPE}`` if it appears. * `CTest Script`_ variable: :variable:`CTEST_CONFIGURATION_TYPE` @@ -1288,7 +1368,7 @@ See `Label and Subproject Summary`_. ``TestLoad`` - While running tests in parallel (e.g. with :option:`-j <ctest -j>`), + While running tests in parallel (e.g. with :ctest-option:`-j`), try not to start tests when they may cause the CPU load to pass above a given threshold. @@ -1298,13 +1378,46 @@ ``TimeOut`` The default timeout for each test if not specified by the :prop_test:`TIMEOUT` test property or the - :option:`--timeout <ctest --timeout>` flag. + :ctest-option:`--timeout` flag. * `CTest Script`_ variable: :variable:`CTEST_TEST_TIMEOUT` * :module:`CTest` module variable: ``DART_TESTING_TIMEOUT`` +.. _`ctest-CoverageTool`: + +``CoverageTool`` + .. versionadded:: 4.4 + + Specify the tool used for collecting coverage during the running + of the tests. The tool may be one of: + + ``LLVM-COV`` + This value indicates the usage of Clang's source-based code coverage + which "operates on AST and preprocessor information directly". + For more information, see the `Clang Source-based Code Coverage`_ + documentation. + + CTest will run each test with the ``LLVM_PROFILE_FILE`` environment + variable set to ``<directory>/<test-name>_<process-id>.profraw``, + where ``<directory>`` is the absolute path to the directory where + the ``CTestTestfile.cmake`` that describes the test is located. + This configures Clang Source-based Code Coverage to uniquely identify + the coverage information gathered by each test without any collisions. + + Any existing ``<directory>/<test-name>_*.profraw`` files for a test + are removed before running the test. Any existing ``LLVM_PROFILE_FILE`` + environment variable is ignored. + + If no value is specified, no work is done and nothing is added to the + environment. + + * `CTest Script`_ variable: :variable:`CTEST_TEST_COVERAGE_TOOL` + * :module:`CTest` module variable: :variable:`CTEST_TEST_COVERAGE_TOOL` + To report extra test values to CDash, see :ref:`Additional Test Measurements`. +.. _`Clang Source-based Code Coverage`: https://clang.llvm.org/docs/SourceBasedCodeCoverage.html + .. _`CTest Coverage Step`: CTest Coverage Step @@ -1664,7 +1777,7 @@ Test name. This cannot be empty. ``config`` Optional field specifying the configuration for which the test will run. - This will always match the :option:`-C <ctest -C>` option specified on the + This will always match the :ctest-option:`-C` option specified on the ``ctest`` command line. If no such option was given, this field will not be present. ``command`` @@ -1782,11 +1895,10 @@ If a dashboard script is used and ``RESOURCE_SPEC_FILE`` is not specified, the value of :variable:`CTEST_RESOURCE_SPEC_FILE` in the dashboard script is used -instead. If :option:`--resource-spec-file <ctest --resource-spec-file>`, -``RESOURCE_SPEC_FILE``, and :variable:`CTEST_RESOURCE_SPEC_FILE` in the -dashboard script are not specified, the value of -:variable:`CTEST_RESOURCE_SPEC_FILE` in the CMake build is used instead. -If none of these are specified, no resource spec file is used. +instead. If :ctest-option:`--resource-spec-file`, ``RESOURCE_SPEC_FILE``, and +:variable:`CTEST_RESOURCE_SPEC_FILE` in the dashboard script are not specified, +the value of :variable:`CTEST_RESOURCE_SPEC_FILE` in the CMake build is used +instead. If none of these are specified, no resource spec file is used. The resource specification file must be a JSON object. All examples in this document assume the following resource specification file: @@ -1983,9 +2095,9 @@ On POSIX systems, when running under the context of a `Job Server`_, CTest shares its job slots. This is independent of the :prop_test:`PROCESSORS` -test property, which still counts against CTest's :option:`-j <ctest -j>` -parallel level. CTest acquires exactly one token from the job server before -running each test, and returns it when the test finishes. +test property, which still counts against CTest's :ctest-option:`-j` parallel +level. CTest acquires exactly one token from the job server before running +each test, and returns it when the test finishes. For example, consider the ``Makefile``:
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..925c259 --- /dev/null +++ b/Help/manual/file_api/schema_target.json
@@ -0,0 +1,1946 @@ +{ + "$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" + }, + { + "$ref": "#/definitions/codemodelV2_11" + } + ], + "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", + "const": 10 + } + }, + "additionalProperties": false + }, + "codemodelVersionV2_11": { + "type": "object", + "required": [ + "major", + "minor" + ], + "properties": { + "major": { + "type": "integer", + "const": 2 + }, + "minor": { + "type": "integer", + "minimum": 11 + } + }, + "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." + }, + "fileset-typeV2_5": { + "type": "string", + "enum": [ + "HEADERS", + "CXX_MODULES" + ] + }, + "fileset-typeV2_11": { + "type": "string", + "enum": [ + "HEADERS", + "CXX_MODULES", + "SOURCES" + ] + }, + "target-typeV2_0": { + "type": "string", + "enum": [ + "EXECUTABLE", + "STATIC_LIBRARY", + "SHARED_LIBRARY", + "MODULE_LIBRARY", + "OBJECT_LIBRARY", + "INTERFACE_LIBRARY", + "UTILITY" + ] + }, + "target-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": { + "$ref": "#/definitions/fileset-typeV2_5" + }, + "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 + } + }, + "fileSetsV2_11": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "type", + "visibility", + "baseDirectories" + ], + "properties": { + "name": { + "type": "string" + }, + "type": { + "$ref": "#/definitions/fileset-typeV2_11" + }, + "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/target-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/target-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/target-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/target-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/target-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/target-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/target-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/target-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/target-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 + }, + "codemodelV2_11": { + "required": [ + "codemodelVersion", + "name", + "id", + "type", + "paths", + "sources", + "backtraceGraph" + ], + "properties": { + "codemodelVersion": { + "$ref": "#/definitions/codemodelVersionV2_11" + }, + "name": { + "$ref": "#/definitions/name" + }, + "id": { + "$ref": "#/definitions/id" + }, + "type": { + "$ref": "#/definitions/target-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_11" + }, + "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_BUILD.rst b/Help/manual/include/OPTIONS_BUILD.rst index 4d8f88e..851cb9d 100644 --- a/Help/manual/include/OPTIONS_BUILD.rst +++ b/Help/manual/include/OPTIONS_BUILD.rst
@@ -138,59 +138,34 @@ transition and not for publication of a final product. CMake will always emit a warning when the project file is anything other than ``CMakeLists.txt``. -.. option:: -Wno-dev +.. option:: -W<category> - Suppress developer warnings. + Promote the specified diagnostic category (and any children) to at least + ``WARN`` severity. Note that this has no effect on diagnostics already set to + a higher severity. - Suppress warnings that are meant for the author of the - ``CMakeLists.txt`` files. By default this will also turn off - deprecation warnings. + See the :manual:`cmake-diagnostics(7)` manual for a list of accepted values + for ``<category>``. -.. option:: -Wdev +.. option:: -Wno-<category> - Enable developer warnings. + Disable (ignore) all diagnostics of the specified category, including any + child categories. - Enable warnings that are meant for the author of the ``CMakeLists.txt`` - files. By default this will also turn on deprecation warnings. +.. option:: -Werror=<category> -.. option:: -Wdeprecated + Promote the specified diagnostic category (and any children) to at least + ``SEND_ERROR`` severity. Note that this has no effect on diagnostics already + set to a higher severity. - Enable deprecated functionality warnings. +.. option:: -Wno-error=<category> - Enable warnings for usage of deprecated functionality, that are meant - for the author of the ``CMakeLists.txt`` files. + Demote the specified diagnostic category (and any children) to at most + ``WARN`` severity. Note that this has no effect on diagnostics already + set to a lower severity. -.. option:: -Wno-deprecated +.. option:: -Wdev, -Wno-dev - Suppress deprecated functionality warnings. + .. deprecated:: 4.4 - Suppress warnings for usage of deprecated functionality, that are meant - for the author of the ``CMakeLists.txt`` files. - -.. option:: -Werror=<what> - - Treat CMake warnings as errors. ``<what>`` must be one of the following: - - ``dev`` - Make developer warnings errors. - - Make warnings that are meant for the author of the ``CMakeLists.txt`` files - errors. By default this will also turn on deprecated warnings as errors. - - ``deprecated`` - Make deprecated macro and function warnings errors. - - Make warnings for usage of deprecated macros and functions, that are meant - for the author of the ``CMakeLists.txt`` files, errors. - -.. option:: -Wno-error=<what> - - Do not treat CMake warnings as errors. ``<what>`` must be one of the following: - - ``dev`` - Make warnings that are meant for the author of the ``CMakeLists.txt`` files not - errors. By default this will also turn off deprecated warnings as errors. - - ``deprecated`` - Make warnings for usage of deprecated macros and functions, that are meant - for the author of the ``CMakeLists.txt`` files, not errors. + Compatibility synonyms for ``-Wauthor`` / ``-Wno-author``.
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/index-v1-schema.json b/Help/manual/instrumentation/index-v1-schema.json new file mode 100644 index 0000000..6b59bb6 --- /dev/null +++ b/Help/manual/instrumentation/index-v1-schema.json
@@ -0,0 +1,169 @@ +{ + "$schema": "http://json-schema.org/draft/2020-12/schema#", + "type": "object", + "required": [ + "version", + "buildDir", + "dataDir", + "hook", + "snippets" + ], + "definitions": { + "nonEmptyStringOrNull": { + "anyOf": [ + { + "type": "string", + "minLength": 1 + }, + { + "type": "null" + } + ] + }, + "positiveIntegerOrNull": { + "anyOf": [ + { + "type": "integer", + "minimum": 1 + }, + { + "type": "null" + } + ] + } + }, + "properties": { + "version": { + "type": "integer", + "description": "The data version of the index file.", + "enum": [ + 1 + ] + }, + "buildDir": { + "type": "string", + "description": "The build directory of the CMake project.", + "minLength": 1 + }, + "dataDir": { + "type": "string", + "description": "The full path to the <build>/.cmake/instrumentation/v1/data/ directory.", + "minLength": 1 + }, + "hook": { + "type": "string", + "description": "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.", + "enum": [ + "postGenerate", + "preBuild", + "postBuild", + "preCMakeBuild", + "postCMakeBuild", + "postCMakeInstall", + "postCMakeWorkflow", + "postCTest", + "manual" + ] + }, + "snippets": { + "type": "array", + "description": "Contains a list of v1 Snippet Files. This includes all snippet files generated since the previous index file was created. The file paths are relative to dataDir.", + "items": { + "type": "string", + "minLength": 1 + }, + "uniqueItems": true + }, + "trace": { + "type": "string", + "description": "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.", + "minLength": 1 + }, + "staticSystemInformation": { + "type": "object", + "description": "Specifies the static information collected about the host machine CMake is being run from. Only included when enabled by the v1 Query Files.", + "properties": { + "OSName": { + "description": "The host operating system name.", + "$ref": "#/definitions/nonEmptyStringOrNull" + }, + "OSPlatform": { + "description": "The name of the CPU CMake is running on.", + "$ref": "#/definitions/nonEmptyStringOrNull" + }, + "OSRelease": { + "description": "The OS sub-type (e.g., 'Professional' on Windows).", + "$ref": "#/definitions/nonEmptyStringOrNull" + }, + "OSVersion": { + "description": "The OS build ID.", + "$ref": "#/definitions/nonEmptyStringOrNull" + }, + "familyId": { + "description": "The processor family name.", + "$ref": "#/definitions/nonEmptyStringOrNull" + }, + "hostname": { + "description": "Hostname.", + "$ref": "#/definitions/nonEmptyStringOrNull" + }, + "is64Bits": { + "type": "boolean", + "description": "True if processor is 64 bit." + }, + "modelId": { + "description": "The processor model ID", + "$ref": "#/definitions/nonEmptyStringOrNull" + }, + "numberOfLogicalCPU": { + "description": "Number of logical cores.", + "$ref": "#/definitions/positiveIntegerOrNull" + }, + "numberOfPhysicalCPU": { + "description": "Number of physical cores.", + "$ref": "#/definitions/positiveIntegerOrNull" + }, + "processorAPICID": { + "description": "The processor APIC ID.", + "$ref": "#/definitions/nonEmptyStringOrNull" + }, + "processorCacheSize": { + "description": "The processor L1 cache size.", + "$ref": "#/definitions/positiveIntegerOrNull" + }, + "processorClockFrequency": { + "description": "The processor clock frequency.", + "anyOf": [ + { + "type": "number", + "minimum": 1 + }, + { + "type": "null" + } + ] + }, + "processorName": { + "description": "Human readable processor name.", + "$ref": "#/definitions/nonEmptyStringOrNull" + }, + "totalPhysicalMemory": { + "description": "Total physical memory in MiB", + "$ref": "#/definitions/positiveIntegerOrNull" + }, + "totalVirtualMemory": { + "description": "Total virtual memory in MiB", + "$ref": "#/definitions/positiveIntegerOrNull" + }, + "vendorID": { + "description": "The processor vendor ID.", + "$ref": "#/definitions/nonEmptyStringOrNull" + }, + "vendorString": { + "description": "The processor vendor string.", + "$ref": "#/definitions/nonEmptyStringOrNull" + } + } + } + } +}
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/architecture-properties.rst b/Help/manual/presets/architecture-properties.rst new file mode 100644 index 0000000..31182b5 --- /dev/null +++ b/Help/manual/presets/architecture-properties.rst
@@ -0,0 +1,27 @@ +.. This file was generated by Utilities/Scripts/regenerate-presets.py + from Help/manual/presets/schema.yaml. Do not edit. + +.. _`CMakePresets.configurePresets.architecture.value`: + +``value`` + An optional string representing the value. + +.. _`CMakePresets.configurePresets.architecture.strategy`: + +``strategy`` + An optional string telling CMake how to handle the field. + Valid values are: + + ``"set"`` + Set the respective value. This will result in an error for generators + that do not support the respective field. + + ``"external"`` + Do not set the value, even if the generator supports it. This is + useful if, for example, a preset uses the Ninja generator, and an IDE + knows how to set up the Visual C++ environment from the architecture + and toolset fields. In that case, CMake will ignore the field, but + the IDE can use them to set up the environment before invoking CMake. + + 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"``.
diff --git a/Help/manual/presets/buildPresets-properties.rst b/Help/manual/presets/buildPresets-properties.rst new file mode 100644 index 0000000..1256280 --- /dev/null +++ b/Help/manual/presets/buildPresets-properties.rst
@@ -0,0 +1,214 @@ +.. This file was generated by Utilities/Scripts/regenerate-presets.py + from Help/manual/presets/schema.yaml. Do not edit. + +.. _`CMakePresets.buildPresets.name`: + +``name`` + A required string representing the machine-friendly name of the + preset. This identifier is used in the + :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, package, or workflow preset. + +.. _`CMakePresets.buildPresets.hidden`: + +``hidden`` + An optional boolean specifying whether or not a preset should be + hidden. If a preset is hidden, it cannot be used in the + :cmake-build-option:`--preset` argument and does not have to have a + valid :preset:`buildPresets.configurePreset`, even from + inheritance. ``hidden`` presets are intended to be used as a base + for other presets to inherit via the + :preset:`buildPresets.inherits` field. + +.. _`CMakePresets.buildPresets.inherits`: + +``inherits`` + An optional array of strings representing the names of presets from which + to inherit. This field can also be a string, which is equivalent to an + array containing one string. + + 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`` array will be preferred. + + A preset can only inherit from another preset that is defined in the same + file or in one of the files it includes (directly or indirectly). Presets + in ``CMakePresets.json`` may not inherit from presets in + ``CMakeUserPresets.json``. + +.. _`CMakePresets.buildPresets.condition`: + +``condition`` + .. presets-versionadded:: 3 + + An optional `Condition`_ object. + +.. _`CMakePresets.buildPresets.vendor`: + +``vendor`` + 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. + +.. _`CMakePresets.buildPresets.displayName`: + +``displayName`` + An optional string with a human-friendly name of the preset. + +.. _`CMakePresets.buildPresets.description`: + +``description`` + An optional string with a human-friendly description of the preset. + +.. _`CMakePresets.buildPresets.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 a + string representing the value of the variable. 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}``). ``$penv{NAME}`` + allows one to prepend or append values to existing environment variables + by accessing only values from the parent environment. + + 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. + + .. note:: + + 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 :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. + + +.. _`CMakePresets.buildPresets.configurePreset`: + +``configurePreset`` + 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 directory is inferred from the + configure preset, so the build will take place in the same + ``binaryDir`` that the configuration did. + +.. _`CMakePresets.buildPresets.inheritConfigureEnvironment`: + +``inheritConfigureEnvironment`` + 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. + +.. _`CMakePresets.buildPresets.jobs`: + +``jobs`` + An optional integer. Equivalent to passing + :cmake-build-option:`--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 presets file. + +.. _`CMakePresets.buildPresets.targets`: + +``targets`` + An optional string or array of strings. Equivalent to passing + :cmake-build-option:`--target` or ``-t`` on the command line. + Vendors may ignore the targets property or hide build presets that + explicitly specify targets. This field supports `macro expansion`_. + +.. _`CMakePresets.buildPresets.configuration`: + +``configuration`` + An optional string. Equivalent to passing + :cmake-build-option:`--config` on the command line. + +.. _`CMakePresets.buildPresets.cleanFirst`: + +``cleanFirst`` + An optional bool. If ``true``, equivalent to passing + :cmake-build-option:`--clean-first` on the command line. + +.. _`CMakePresets.buildPresets.resolvePackageReferences`: + +``resolvePackageReferences`` + .. presets-versionadded:: 4 + + An optional string that specifies the package resolve mode. + + Package references are used to define dependencies to packages from + external package managers. Currently only NuGet in combination with + the :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. + + ``off`` + Package references will not be resolved. Note that this may cause + errors in some build environments, such as .NET SDK style + projects. + + ``only`` + Only resolve package references, but do not perform a build. + + .. note:: + + The command line parameter + :cmake-build-option:`--resolve-package-references` + will take priority over this setting. If the command line + parameter is not provided and this setting is not specified, an + environment-specific cache variable will be evaluated to decide, + if package restoration should be performed. + + 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. + +.. _`CMakePresets.buildPresets.verbose`: + +``verbose`` + An optional boolean. If ``true``, equivalent to passing + :cmake-build-option:`--verbose` on the command line. + +.. _`CMakePresets.buildPresets.nativeToolOptions`: + +``nativeToolOptions`` + An optional array of strings. Equivalent to passing options after + :cmake-build-option:`--` on the command line. The array values + support `macro expansion`_.
diff --git a/Help/manual/presets/cacheVariables-properties.rst b/Help/manual/presets/cacheVariables-properties.rst new file mode 100644 index 0000000..76e1a66 --- /dev/null +++ b/Help/manual/presets/cacheVariables-properties.rst
@@ -0,0 +1,7 @@ +.. This file was generated by Utilities/Scripts/regenerate-presets.py + from Help/manual/presets/schema.yaml. Do not edit. + +.. _`CMakePresets.configurePresets.cacheVariables.type`: + +``type`` + An optional string representing the type of the variable. It should be BOOL, FILEPATH, PATH, STRING, or INTERNAL.
diff --git a/Help/manual/presets/cmakeMinimumRequired-properties.rst b/Help/manual/presets/cmakeMinimumRequired-properties.rst new file mode 100644 index 0000000..e3ede9b --- /dev/null +++ b/Help/manual/presets/cmakeMinimumRequired-properties.rst
@@ -0,0 +1,17 @@ +.. This file was generated by Utilities/Scripts/regenerate-presets.py + from Help/manual/presets/schema.yaml. Do not edit. + +.. _`CMakePresets.cmakeMinimumRequired.major`: + +``major`` + An optional integer representing the major version. + +.. _`CMakePresets.cmakeMinimumRequired.minor`: + +``minor`` + An optional integer representing the minor version. + +.. _`CMakePresets.cmakeMinimumRequired.patch`: + +``patch`` + An optional integer representing the patch version.
diff --git a/Help/manual/presets/configurePresets-properties.rst b/Help/manual/presets/configurePresets-properties.rst new file mode 100644 index 0000000..c15874b --- /dev/null +++ b/Help/manual/presets/configurePresets-properties.rst
@@ -0,0 +1,251 @@ +.. This file was generated by Utilities/Scripts/regenerate-presets.py + from Help/manual/presets/schema.yaml. Do not edit. + +.. _`CMakePresets.configurePresets.name`: + +``name`` + A required string representing the machine-friendly name of the + preset. 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, package, or workflow preset. + +.. _`CMakePresets.configurePresets.hidden`: + +``hidden`` + An optional boolean specifying whether or not a preset should be + hidden. If a preset is hidden, it cannot be used in the + :cmake-option:`--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. + +.. _`CMakePresets.configurePresets.inherits`: + +``inherits`` + An optional array of strings representing the names of presets from which + to inherit. This field can also be a string, which is equivalent to an + array containing one string. + + 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`` array will be preferred. + + A preset can only inherit from another preset that is defined in the same + file or in one of the files it includes (directly or indirectly). Presets + in ``CMakePresets.json`` may not inherit from presets in + ``CMakeUserPresets.json``. + +.. _`CMakePresets.configurePresets.condition`: + +``condition`` + .. presets-versionadded:: 3 + + An optional `Condition`_ object. + +.. _`CMakePresets.configurePresets.vendor`: + +``vendor`` + 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. + +.. _`CMakePresets.configurePresets.displayName`: + +``displayName`` + An optional string with a human-friendly name of the preset. + +.. _`CMakePresets.configurePresets.description`: + +``description`` + An optional string with a human-friendly description of the preset. + +.. _`CMakePresets.configurePresets.generator`: + +``generator`` + An optional string representing the + :manual:`generator <cmake-generators(7)>` to use for the preset. + + .. presets-versionchanged:: 3 + + If omitted, CMake will fall back to regular generator discovery + procedure. In previous versions, if not specified, this field + must be inherited from the ``inherits`` preset (unless this + preset is ``hidden``). + + Note that for :ref:`Visual Studio generators`, unlike in the + command line :cmake-option:`-G` argument, you cannot include the + platform name in the generator name. Use the ``architecture`` + field instead. + +.. _`CMakePresets.configurePresets.architecture`: + +``architecture`` + Optional field representing the platform for + :manual:`generators <cmake-generators(7)>` that support it. + + See :option:`cmake -A` for possible values. + + ``architecture`` may be either a string or an object with the + following fields: + + .. include:: presets/architecture-properties.rst + +.. _`CMakePresets.configurePresets.toolset`: + +``toolset`` + Optional field representing the toolset for + :manual:`generators <cmake-generators(7)>` that support it. + + See :option:`cmake -T` for possible values. + + ``toolset`` may be either a string or an object with the following + fields: + + .. include:: presets/toolset-properties.rst + +.. _`CMakePresets.configurePresets.toolchainFile`: + +``toolchainFile`` + .. presets-versionadded:: 3 + + An optional string representing the path to the toolchain file. + This field supports `macro expansion`_. If a relative path is + specified, it is calculated relative to the build directory, and if + not found, relative to the source directory. This field takes + precedence over any :variable:`CMAKE_TOOLCHAIN_FILE` value. + +.. _`CMakePresets.configurePresets.graphviz`: + +``graphviz`` + .. presets-versionadded:: 10 + + 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 + :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. + +.. _`CMakePresets.configurePresets.binaryDir`: + +``binaryDir`` + An optional string representing the path to the output binary + directory. This field supports `macro expansion`_. If a relative + path is specified, it is calculated relative to the source + directory. + + .. presets-versionchanged:: 3 + + If omitted, CMake will calculate the path using regular methods. + In previous versions, if not specified, this field must be + inherited from the ``inherits`` preset (unless this preset is + ``hidden``). + +.. _`CMakePresets.configurePresets.installDir`: + +``installDir`` + .. presets-versionadded:: 3 + + 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. + +.. _`CMakePresets.configurePresets.cmakeExecutable`: + +``cmakeExecutable`` + 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. + +.. _`CMakePresets.configurePresets.cacheVariables`: + +``cacheVariables`` + An optional map of cache variables. The key is the variable name + (which may not be an empty string), and the value is either + ``null``, a boolean (which is equivalent to a value of ``"TRUE"`` + or ``"FALSE"`` and a type of ``BOOL``), a string representing the + value of the variable (which supports `macro expansion`_), or an + object with the following fields: + + ``type`` + An optional string representing the type of the variable. + + ``value`` + A required string or boolean representing the value of the + variable. A boolean is equivalent to ``"TRUE"`` or ``"FALSE"``. + This field supports `macro expansion`_. + + 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. Setting a variable to + ``null`` causes it to not be set, even if a value was inherited + from another preset. + +.. _`CMakePresets.configurePresets.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 a + string representing the value of the variable. 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}``). ``$penv{NAME}`` + allows one to prepend or append values to existing environment variables + by accessing only values from the parent environment. + + 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. + +.. _`CMakePresets.configurePresets.warnings`: + +``warnings`` + An optional object specifying the warnings to enable. + The object may contain the following fields: + + .. include:: presets/warnings-properties.rst + +.. _`CMakePresets.configurePresets.errors`: + +``errors`` + An optional object specifying the errors to enable. + The object may contain the following fields: + + .. include:: presets/errors-properties.rst + +.. _`CMakePresets.configurePresets.debug`: + +``debug`` + An optional object specifying debug options. + The object may contain the following fields: + + .. include:: presets/debug-properties.rst + +.. _`CMakePresets.configurePresets.trace`: + +``trace`` + .. presets-versionadded:: 7 + + An optional object specifying trace options. + The object may contain the following fields: + + .. include:: presets/trace-properties.rst
diff --git a/Help/manual/presets/debug-properties.rst b/Help/manual/presets/debug-properties.rst new file mode 100644 index 0000000..6c8cbde --- /dev/null +++ b/Help/manual/presets/debug-properties.rst
@@ -0,0 +1,20 @@ +.. This file was generated by Utilities/Scripts/regenerate-presets.py + from Help/manual/presets/schema.yaml. Do not edit. + +.. _`CMakePresets.configurePresets.debug.output`: + +``output`` + An optional boolean. Setting this to ``true`` is equivalent to + passing :cmake-option:`--debug-output` on the command line. + +.. _`CMakePresets.configurePresets.debug.tryCompile`: + +``tryCompile`` + An optional boolean. Setting this to ``true`` is equivalent to + passing :cmake-option:`--debug-trycompile` on the command line. + +.. _`CMakePresets.configurePresets.debug.find`: + +``find`` + An optional boolean. Setting this to ``true`` is equivalent to + passing :cmake-option:`--debug-find` on the command line.
diff --git a/Help/manual/presets/errors-properties.rst b/Help/manual/presets/errors-properties.rst new file mode 100644 index 0000000..7bf5dac --- /dev/null +++ b/Help/manual/presets/errors-properties.rst
@@ -0,0 +1,66 @@ +.. This file was generated by Utilities/Scripts/regenerate-presets.py + from Help/manual/presets/schema.yaml. Do not edit. + +.. _`CMakePresets.configurePresets.errors.author`: + +``author`` + .. presets-versionadded:: 12 + + An optional boolean. Equivalent to passing :cmake-option:`-Werror=author` or + :cmake-option:`-Wno-error=author` on the command line. + This may not be set to ``true`` if ``warnings.author`` is set to ``false``. + +.. _`CMakePresets.configurePresets.errors.deprecated`: + +``deprecated`` + An optional boolean. Equivalent to passing + :cmake-option:`-Werror=deprecated` or + :cmake-option:`-Wno-error=deprecated` + on the command line. + This may not be set to ``true`` + if ``warnings.deprecated`` is set to ``false``. + +.. _`CMakePresets.configurePresets.errors.dev`: + +``dev`` + .. presets-versionremoved:: 12 + + An optional boolean. Equivalent to passing + :cmake-option:`-Werror=dev` or + :cmake-option:`-Wno-error=dev` + on the command line. + This may not be set to ``true`` + if ``warnings.dev`` is set to ``false``. + +.. _`CMakePresets.configurePresets.errors.installAbsoluteDestination`: + +``installAbsoluteDestination`` + .. presets-versionadded:: 12 + + An optional boolean. Equivalent to passing :cmake-option:`-Werror=install-absolute-destination` or + :cmake-option:`-Wno-error=install-absolute-destination` on the command line. + This may not be set to ``true`` if ``warnings.installAbsoluteDestination`` is set to ``false``. + +.. _`CMakePresets.configurePresets.errors.uninitialized`: + +``uninitialized`` + .. presets-versionadded:: 12 + + An optional boolean. Equivalent to passing + :cmake-option:`-Werror=uninitialized` or + :cmake-option:`-Wno-error=uninitialized` + on the command line. + This may not be set to ``true`` + if ``warnings.uninitialized`` is set to ``false``. + +.. _`CMakePresets.configurePresets.errors.unusedCli`: + +``unusedCli`` + .. presets-versionadded:: 12 + + An optional boolean. Equivalent to passing + :cmake-option:`-Werror=unused-cli` or + :cmake-option:`-Wno-error=unused-cli` + on the command line. + This may not be set to ``true`` + if ``warnings.unusedCli`` is set to ``false``.
diff --git a/Help/manual/presets/exclude-properties.rst b/Help/manual/presets/exclude-properties.rst new file mode 100644 index 0000000..24775b5 --- /dev/null +++ b/Help/manual/presets/exclude-properties.rst
@@ -0,0 +1,25 @@ +.. This file was generated by Utilities/Scripts/regenerate-presets.py + from Help/manual/presets/schema.yaml. Do not edit. + +.. _`CMakePresets.testPresets.filter.exclude.name`: + +``name`` + An optional string specifying a regex for test names. + Equivalent to passing :ctest-option:`--exclude-regex` on + the command line. This field supports `macro expansion`_. + +.. _`CMakePresets.testPresets.filter.exclude.label`: + +``label`` + An optional string specifying a regex for test labels. + Equivalent to passing :ctest-option:`--label-exclude` on + the command line. This field supports `macro expansion`_. + +.. _`CMakePresets.testPresets.filter.exclude.fixtures`: + +``fixtures`` + An optional object specifying which fixtures to exclude + from adding tests. The object may contain the following + fields: + + .. include:: presets/fixtures-properties.rst
diff --git a/Help/manual/presets/execution-properties.rst b/Help/manual/presets/execution-properties.rst new file mode 100644 index 0000000..8e3d4a0 --- /dev/null +++ b/Help/manual/presets/execution-properties.rst
@@ -0,0 +1,115 @@ +.. This file was generated by Utilities/Scripts/regenerate-presets.py + from Help/manual/presets/schema.yaml. Do not edit. + +.. _`CMakePresets.testPresets.execution.stopOnFailure`: + +``stopOnFailure`` + An optional bool. If ``true``, equivalent to passing + :ctest-option:`--stop-on-failure` on the command line. + +.. _`CMakePresets.testPresets.execution.enableFailover`: + +``enableFailover`` + An optional bool. If ``true``, equivalent to passing + :ctest-option:`-F` on the command line. + +.. _`CMakePresets.testPresets.execution.jobs`: + +``jobs`` + An optional integer. Equivalent to passing + :ctest-option:`--parallel` on the command line. If the value is + ``0``, it is equivalent to unbounded parallelism. + + .. presets-versionchanged:: 11 + + 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 presets file. + +.. _`CMakePresets.testPresets.execution.resourceSpecFile`: + +``resourceSpecFile`` + An optional string. Equivalent to passing + :ctest-option:`--resource-spec-file` on the command line. This + field supports `macro expansion`_. + +.. _`CMakePresets.testPresets.execution.testLoad`: + +``testLoad`` + An optional integer. Equivalent to passing + :ctest-option:`--test-load` on the command line. + +.. _`CMakePresets.testPresets.execution.showOnly`: + +``showOnly`` + An optional string. Equivalent to passing + :ctest-option:`--show-only` on the command line. The string + must be one of the following values: + + * ``human`` + + * ``json-v1`` + +.. _`CMakePresets.testPresets.execution.repeat`: + +``repeat`` + An optional object specifying how to repeat tests. Equivalent + to passing :ctest-option:`--repeat` on the command line. + The object must have the following fields: + + .. include:: presets/repeat-properties.rst + +.. _`CMakePresets.testPresets.execution.interactiveDebugging`: + +``interactiveDebugging`` + An optional bool. If ``true``, equivalent to passing + :ctest-option:`--interactive-debug-mode 1` on the command line. + If ``false``, equivalent to passing + :ctest-option:`--interactive-debug-mode 0` on the command line. + +.. _`CMakePresets.testPresets.execution.scheduleRandom`: + +``scheduleRandom`` + An optional bool. If ``true``, equivalent to passing + :ctest-option:`--schedule-random` on the command line. + +.. _`CMakePresets.testPresets.execution.timeout`: + +``timeout`` + An optional integer. Equivalent to passing + :ctest-option:`--timeout` on the command line. + +.. _`CMakePresets.testPresets.execution.noTestsAction`: + +``noTestsAction`` + 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 :ctest-option:`--no-tests=error` + on the command line. + + ``ignore`` + Equivalent to passing :ctest-option:`--no-tests=ignore` + on the command line. + +.. _`CMakePresets.testPresets.execution.testPassthroughArguments`: + +``testPassthroughArguments`` + .. presets-versionadded:: 12 + + An optional array of strings. Each element is forwarded as an + argument to every test executable, equivalent to passing + arguments after :option:`ctest --` on the command line. + + When both preset and command-line passthrough arguments are + specified, preset arguments appear first, followed by + command-line arguments.
diff --git a/Help/manual/presets/filter-properties.rst b/Help/manual/presets/filter-properties.rst new file mode 100644 index 0000000..083e268 --- /dev/null +++ b/Help/manual/presets/filter-properties.rst
@@ -0,0 +1,18 @@ +.. This file was generated by Utilities/Scripts/regenerate-presets.py + from Help/manual/presets/schema.yaml. Do not edit. + +.. _`CMakePresets.testPresets.filter.include`: + +``include`` + An optional object specifying which tests to include. + The object may contain the following fields: + + .. include:: presets/include-properties.rst + +.. _`CMakePresets.testPresets.filter.exclude`: + +``exclude`` + An optional object specifying which tests to exclude. + The object may contain the following fields: + + .. include:: presets/exclude-properties.rst
diff --git a/Help/manual/presets/fixtures-properties.rst b/Help/manual/presets/fixtures-properties.rst new file mode 100644 index 0000000..727236a --- /dev/null +++ b/Help/manual/presets/fixtures-properties.rst
@@ -0,0 +1,27 @@ +.. This file was generated by Utilities/Scripts/regenerate-presets.py + from Help/manual/presets/schema.yaml. Do not edit. + +.. _`CMakePresets.testPresets.filter.exclude.fixtures.any`: + +``any`` + An optional string specifying a regex for text fixtures + to exclude from adding any tests. Equivalent to passing + :ctest-option:`--fixture-exclude-any` on the command + line. This field supports `macro expansion`_. + +.. _`CMakePresets.testPresets.filter.exclude.fixtures.setup`: + +``setup`` + An optional string specifying a regex for text fixtures + to exclude from adding setup tests. Equivalent to + passing :ctest-option:`--fixture-exclude-setup` on the + command line. This field supports `macro expansion`_. + +.. _`CMakePresets.testPresets.filter.exclude.fixtures.cleanup`: + +``cleanup`` + An optional string specifying a regex for text fixtures + to exclude from adding cleanup tests. Equivalent to + passing :ctest-option:`--fixture-exclude-cleanup` on + the command line. + This field supports `macro expansion`_.
diff --git a/Help/manual/presets/include-properties.rst b/Help/manual/presets/include-properties.rst new file mode 100644 index 0000000..b55c0e1 --- /dev/null +++ b/Help/manual/presets/include-properties.rst
@@ -0,0 +1,37 @@ +.. This file was generated by Utilities/Scripts/regenerate-presets.py + from Help/manual/presets/schema.yaml. Do not edit. + +.. _`CMakePresets.testPresets.filter.include.name`: + +``name`` + An optional string specifying a regex for test names. + Equivalent to passing :ctest-option:`--tests-regex` on the + command line. This field supports `macro expansion`_. + + CMake regex syntax is described under + :ref:`string(REGEX) <Regex Specification>`. + +.. _`CMakePresets.testPresets.filter.include.label`: + +``label`` + An optional string specifying a regex for test labels. + Equivalent to passing :ctest-option:`--label-regex` on the + command line. This field supports `macro expansion`_. + +.. _`CMakePresets.testPresets.filter.include.useUnion`: + +``useUnion`` + An optional bool. Equivalent to passing + :ctest-option:`--union` on the command line. + +.. _`CMakePresets.testPresets.filter.include.index`: + +``index`` + An optional object specifying tests to include by test + index. The object may contain the following fields. Can + also be an optional string specifying a file with the + command line syntax for + :ctest-option:`--tests-information`. If specified as a + string, this field supports `macro expansion`_. + + .. include:: presets/index-properties.rst
diff --git a/Help/manual/presets/index-properties.rst b/Help/manual/presets/index-properties.rst new file mode 100644 index 0000000..6bbce33 --- /dev/null +++ b/Help/manual/presets/index-properties.rst
@@ -0,0 +1,22 @@ +.. This file was generated by Utilities/Scripts/regenerate-presets.py + from Help/manual/presets/schema.yaml. Do not edit. + +.. _`CMakePresets.testPresets.filter.include.index.start`: + +``start`` + An optional integer specifying a test index at which to start testing. + +.. _`CMakePresets.testPresets.filter.include.index.end`: + +``end`` + An optional integer specifying a test index at which to stop testing. + +.. _`CMakePresets.testPresets.filter.include.index.stride`: + +``stride`` + An optional integer specifying the increment. + +.. _`CMakePresets.testPresets.filter.include.index.specificTests`: + +``specificTests`` + An optional array of integers specifying specific test indices to run.
diff --git a/Help/manual/presets/packageOutput-properties.rst b/Help/manual/presets/packageOutput-properties.rst new file mode 100644 index 0000000..d8ab6fb --- /dev/null +++ b/Help/manual/presets/packageOutput-properties.rst
@@ -0,0 +1,16 @@ +.. This file was generated by Utilities/Scripts/regenerate-presets.py + from Help/manual/presets/schema.yaml. Do not edit. + +.. _`CMakePresets.packagePresets.output.debug`: + +``debug`` + An optional boolean specifying whether or not to print debug + information. A value of ``true`` is equivalent to passing + :cpack-option:`--debug` on the command line. + +.. _`CMakePresets.packagePresets.output.verbose`: + +``verbose`` + An optional boolean specifying whether or not to print + verbosely. A value of ``true`` is equivalent to passing + :cpack-option:`--verbose` on the command line.
diff --git a/Help/manual/presets/packagePresets-properties.rst b/Help/manual/presets/packagePresets-properties.rst new file mode 100644 index 0000000..863500f --- /dev/null +++ b/Help/manual/presets/packagePresets-properties.rst
@@ -0,0 +1,175 @@ +.. This file was generated by Utilities/Scripts/regenerate-presets.py + from Help/manual/presets/schema.yaml. Do not edit. + +.. _`CMakePresets.packagePresets.name`: + +``name`` + A required string representing the machine-friendly name of the + preset. This identifier is used in the :option:`cpack --preset` + option. There must not be two package presets in the union of + ``CMakePresets.json`` and ``CMakeUserPresets.json`` in the same + directory with the same name. However, a package preset may have + the same name as a configure, build, test, or workflow preset. + +.. _`CMakePresets.packagePresets.hidden`: + +``hidden`` + An optional boolean specifying whether or not a preset should be + hidden. If a preset is hidden, it cannot be used in the + :cpack-option:`--preset` argument and does not have to have a valid + :preset:`packagePresets.configurePreset`, even from + inheritance. ``hidden`` presets are intended to be used as a base + for other presets to inherit via the + :preset:`packagePresets.inherits` field. + +.. _`CMakePresets.packagePresets.inherits`: + +``inherits`` + An optional array of strings representing the names of presets from which + to inherit. This field can also be a string, which is equivalent to an + array containing one string. + + 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`` array will be preferred. + + A preset can only inherit from another preset that is defined in the same + file or in one of the files it includes (directly or indirectly). Presets + in ``CMakePresets.json`` may not inherit from presets in + ``CMakeUserPresets.json``. + +.. _`CMakePresets.packagePresets.condition`: + +``condition`` + An optional `Condition`_ object. + +.. _`CMakePresets.packagePresets.vendor`: + +``vendor`` + 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. + +.. _`CMakePresets.packagePresets.displayName`: + +``displayName`` + An optional string with a human-friendly name of the preset. + +.. _`CMakePresets.packagePresets.description`: + +``description`` + An optional string with a human-friendly description of the preset. + +.. _`CMakePresets.packagePresets.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 a + string representing the value of the variable. 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}``). ``$penv{NAME}`` + allows one to prepend or append values to existing environment variables + by accessing only values from the parent environment. + + 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. + +.. _`CMakePresets.packagePresets.configurePreset`: + +``configurePreset`` + 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 directory is inferred from the + configure preset, so packaging will run in the same ``binaryDir`` + that the configuration did and build did. + +.. _`CMakePresets.packagePresets.inheritConfigureEnvironment`: + +``inheritConfigureEnvironment`` + 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. + +.. _`CMakePresets.packagePresets.generators`: + +``generators`` + An optional array of strings representing generators for CPack to use. + +.. _`CMakePresets.packagePresets.configurations`: + +``configurations`` + An optional array of strings representing build configurations for CPack to package. + +.. _`CMakePresets.packagePresets.variables`: + +``variables`` + An optional map of variables to pass to CPack, equivalent to + :cpack-option:`-D` arguments. Each key is the name of a variable, + and the value is the string to assign to that variable. + +.. _`CMakePresets.packagePresets.configFile`: + +``configFile`` + An optional string representing the config file for CPack to use. + +.. _`CMakePresets.packagePresets.output`: + +``output`` + An optional object specifying output options. Valid keys are: + + .. include:: presets/packageOutput-properties.rst + +.. _`CMakePresets.packagePresets.packageName`: + +``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. However, other aspects + of the package may use the value, leading to inconsistencies. A + future CMake release may address this problem, but until then, it + is recommended that this field not be used. + + +.. _`CMakePresets.packagePresets.packageVersion`: + +``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. However, other aspects + of the package may use the value, leading to inconsistencies. A + future CMake release may address this problem, but until then, it + is recommended that this field not be used. + + +.. _`CMakePresets.packagePresets.packageDirectory`: + +``packageDirectory`` + An optional string representing the directory in which to place the package. + +.. _`CMakePresets.packagePresets.vendorName`: + +``vendorName`` + An optional string representing the vendor name.
diff --git a/Help/manual/presets/repeat-properties.rst b/Help/manual/presets/repeat-properties.rst new file mode 100644 index 0000000..98800ff --- /dev/null +++ b/Help/manual/presets/repeat-properties.rst
@@ -0,0 +1,18 @@ +.. This file was generated by Utilities/Scripts/regenerate-presets.py + from Help/manual/presets/schema.yaml. Do not edit. + +.. _`CMakePresets.testPresets.execution.repeat.mode`: + +``mode`` + A required string. Must be one of the following values: + + * ``until-fail`` + + * ``until-pass`` + + * ``after-timeout`` + +.. _`CMakePresets.testPresets.execution.repeat.count`: + +``count`` + A required integer.
diff --git a/Help/manual/presets/root-properties.rst b/Help/manual/presets/root-properties.rst new file mode 100644 index 0000000..a1ccccb --- /dev/null +++ b/Help/manual/presets/root-properties.rst
@@ -0,0 +1,78 @@ +.. This file was generated by Utilities/Scripts/regenerate-presets.py + from Help/manual/presets/schema.yaml. Do not edit. + +.. _`CMakePresets.$schema`: + +``$schema`` + .. presets-versionadded:: 8 + + 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 autocompletion in editors that support JSON schema. It doesn't affect the 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. + +.. _`CMakePresets.version`: + +``version`` + 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. + +.. _`CMakePresets.cmakeMinimumRequired`: + +``cmakeMinimumRequired`` + An optional object representing the minimum version of CMake + needed to build this project. This object consists of the following + fields: + + .. include:: presets/cmakeMinimumRequired-properties.rst + +.. _`CMakePresets.include`: + +``include`` + .. presets-versionadded:: 4 + + An optional array of strings representing files to include. If the + filenames are not absolute, they are considered relative to the current + file. See `Includes`_ for discussion of the constraints on included + files. + +.. _`CMakePresets.vendor`: + +``vendor`` + An optional map containing vendor-specific information. CMake does not + interpret the contents of this field except to verify that it is a map if + it does exist. However, the keys should be a vendor-specific domain name + followed by a ``/``-separated path. For example, the Example IDE 1.0 + could use ``example.com/ExampleIDE/1.0``. The value of each field can be + anything desired by the vendor, though will typically be a map. + +.. _`CMakePresets.configurePresets`: + +``configurePresets`` + An optional array of `Configure Preset`_ objects. + +.. _`CMakePresets.buildPresets`: + +``buildPresets`` + .. presets-versionadded:: 2 + + An optional array of `Build Preset`_ objects. + +.. _`CMakePresets.testPresets`: + +``testPresets`` + .. presets-versionadded:: 2 + + An optional array of `Test Preset`_ objects. + +.. _`CMakePresets.packagePresets`: + +``packagePresets`` + .. presets-versionadded:: 6 + + An optional array of `Package Preset`_ objects. + +.. _`CMakePresets.workflowPresets`: + +``workflowPresets`` + .. presets-versionadded:: 6 + + An optional array of `Workflow Preset`_ objects.
diff --git a/Help/manual/presets/schema.json b/Help/manual/presets/schema.json index 63fbdb7..128c829 100644 --- a/Help/manual/presets/schema.json +++ b/Help/manual/presets/schema.json
@@ -1,165 +1,440 @@ { - "$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": [ { + "description": "The presets specify the generator and the build directory, and optionally an array of variables and other arguments to pass to CMake.", "properties": { "version": { - "const": 1, - "description": "A required integer representing the version of the JSON schema." + "type": "integer", + "description": "A required integer representing the version of the JSON schema.", + "const": 1 }, - "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequiredV1" }, - "vendor": { "$ref": "#/definitions/vendor" }, - "configurePresets": { "$ref": "#/definitions/configurePresetsV1" } + "cmakeMinimumRequired": { + "$ref": "#/definitions/cmakeMinimumRequired@v1..v9" + }, + "vendor": { + "$ref": "#/definitions/vendor@v1.." + }, + "configurePresets": { + "$ref": "#/definitions/configurePresets@v1..v2" + } }, + "required": [ + "version" + ], "additionalProperties": false }, { + "description": "The presets specify the generator and the build directory, and optionally an array of variables and other arguments to pass to CMake.", "properties": { "version": { - "const": 2, - "description": "A required integer representing the version of the JSON schema." + "type": "integer", + "description": "A required integer representing the version of the JSON schema.", + "const": 2 }, - "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequiredV1" }, - "vendor": { "$ref": "#/definitions/vendor" }, - "configurePresets": { "$ref": "#/definitions/configurePresetsV1" }, - "buildPresets": { "$ref": "#/definitions/buildPresetsV2" }, - "testPresets": { "$ref": "#/definitions/testPresetsV2" } + "cmakeMinimumRequired": { + "$ref": "#/definitions/cmakeMinimumRequired@v1..v9" + }, + "vendor": { + "$ref": "#/definitions/vendor@v1.." + }, + "configurePresets": { + "$ref": "#/definitions/configurePresets@v1..v2" + }, + "buildPresets": { + "$ref": "#/definitions/buildPresets@v2" + }, + "testPresets": { + "$ref": "#/definitions/testPresets@v2" + } }, + "required": [ + "version" + ], "additionalProperties": false }, { + "description": "The presets specify the generator and the build directory, and optionally an array of variables and other arguments to pass to CMake.", "properties": { "version": { - "const": 3, - "description": "A required integer representing the version of the JSON schema." + "type": "integer", + "description": "A required integer representing the version of the JSON schema.", + "const": 3 }, - "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequiredV1" }, - "vendor": { "$ref": "#/definitions/vendor" }, - "configurePresets": { "$ref": "#/definitions/configurePresetsV3" }, - "buildPresets": { "$ref": "#/definitions/buildPresetsV3" }, - "testPresets": { "$ref": "#/definitions/testPresetsV3" } + "cmakeMinimumRequired": { + "$ref": "#/definitions/cmakeMinimumRequired@v1..v9" + }, + "vendor": { + "$ref": "#/definitions/vendor@v1.." + }, + "configurePresets": { + "$ref": "#/definitions/configurePresets@v3..v6" + }, + "buildPresets": { + "$ref": "#/definitions/buildPresets@v3" + }, + "testPresets": { + "$ref": "#/definitions/testPresets@v3..v4" + } }, + "required": [ + "version" + ], "additionalProperties": false }, { + "description": "The presets specify the generator and the build directory, and optionally an array of variables and other arguments to pass to CMake.", "properties": { "version": { - "const": 4, - "description": "A required integer representing the version of the JSON schema." + "type": "integer", + "description": "A required integer representing the version of the JSON schema.", + "const": 4 }, - "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequiredV1" }, - "vendor": { "$ref": "#/definitions/vendor" }, - "configurePresets": { "$ref": "#/definitions/configurePresetsV3" }, - "buildPresets": { "$ref": "#/definitions/buildPresetsV4" }, - "testPresets": { "$ref": "#/definitions/testPresetsV3" }, - "include": { "$ref": "#/definitions/include" } + "cmakeMinimumRequired": { + "$ref": "#/definitions/cmakeMinimumRequired@v1..v9" + }, + "include": { + "$ref": "#/definitions/include@v4.." + }, + "vendor": { + "$ref": "#/definitions/vendor@v1.." + }, + "configurePresets": { + "$ref": "#/definitions/configurePresets@v3..v6" + }, + "buildPresets": { + "$ref": "#/definitions/buildPresets@v4..v9" + }, + "testPresets": { + "$ref": "#/definitions/testPresets@v3..v4" + } }, + "required": [ + "version" + ], "additionalProperties": false }, { + "description": "The presets specify the generator and the build directory, and optionally an array of variables and other arguments to pass to CMake.", "properties": { "version": { - "const": 5, - "description": "A required integer representing the version of the JSON schema." + "type": "integer", + "description": "A required integer representing the version of the JSON schema.", + "const": 5 }, - "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequiredV1" }, - "vendor": { "$ref": "#/definitions/vendor" }, - "configurePresets": { "$ref": "#/definitions/configurePresetsV3" }, - "buildPresets": { "$ref": "#/definitions/buildPresetsV4" }, - "testPresets": { "$ref": "#/definitions/testPresetsV5" }, - "include": { "$ref": "#/definitions/include" } + "cmakeMinimumRequired": { + "$ref": "#/definitions/cmakeMinimumRequired@v1..v9" + }, + "include": { + "$ref": "#/definitions/include@v4.." + }, + "vendor": { + "$ref": "#/definitions/vendor@v1.." + }, + "configurePresets": { + "$ref": "#/definitions/configurePresets@v3..v6" + }, + "buildPresets": { + "$ref": "#/definitions/buildPresets@v4..v9" + }, + "testPresets": { + "$ref": "#/definitions/testPresets@v5" + } }, + "required": [ + "version" + ], "additionalProperties": false }, { + "description": "The presets specify the generator and the build directory, and optionally an array of variables and other arguments to pass to CMake.", "properties": { "version": { - "const": 6, - "description": "A required integer representing the version of the JSON schema." + "type": "integer", + "description": "A required integer representing the version of the JSON schema.", + "const": 6 }, - "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequiredV1" }, - "vendor": { "$ref": "#/definitions/vendor" }, - "configurePresets": { "$ref": "#/definitions/configurePresetsV3" }, - "buildPresets": { "$ref": "#/definitions/buildPresetsV4" }, - "testPresets": { "$ref": "#/definitions/testPresetsV6" }, - "packagePresets": { "$ref": "#/definitions/packagePresetsV6" }, - "workflowPresets": { "$ref": "#/definitions/workflowPresetsV6" }, - "include": { "$ref": "#/definitions/include" } + "cmakeMinimumRequired": { + "$ref": "#/definitions/cmakeMinimumRequired@v1..v9" + }, + "include": { + "$ref": "#/definitions/include@v4.." + }, + "vendor": { + "$ref": "#/definitions/vendor@v1.." + }, + "configurePresets": { + "$ref": "#/definitions/configurePresets@v3..v6" + }, + "buildPresets": { + "$ref": "#/definitions/buildPresets@v4..v9" + }, + "testPresets": { + "$ref": "#/definitions/testPresets@v6..v9" + }, + "packagePresets": { + "$ref": "#/definitions/packagePresets@v6..v9" + }, + "workflowPresets": { + "$ref": "#/definitions/workflowPresets@v6..v9" + } }, + "required": [ + "version" + ], "additionalProperties": false }, { + "description": "The presets specify the generator and the build directory, and optionally an array of variables and other arguments to pass to CMake.", "properties": { "version": { - "const": 7, - "description": "A required integer representing the version of the JSON schema." + "type": "integer", + "description": "A required integer representing the version of the JSON schema.", + "const": 7 }, - "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequiredV1" }, - "vendor": { "$ref": "#/definitions/vendor" }, - "configurePresets": { "$ref": "#/definitions/configurePresetsV7" }, - "buildPresets": { "$ref": "#/definitions/buildPresetsV4" }, - "testPresets": { "$ref": "#/definitions/testPresetsV6" }, - "packagePresets": { "$ref": "#/definitions/packagePresetsV6" }, - "workflowPresets": { "$ref": "#/definitions/workflowPresetsV6" }, - "include": { "$ref": "#/definitions/include" } + "cmakeMinimumRequired": { + "$ref": "#/definitions/cmakeMinimumRequired@v1..v9" + }, + "include": { + "$ref": "#/definitions/include@v4.." + }, + "vendor": { + "$ref": "#/definitions/vendor@v1.." + }, + "configurePresets": { + "$ref": "#/definitions/configurePresets@v7..v9" + }, + "buildPresets": { + "$ref": "#/definitions/buildPresets@v4..v9" + }, + "testPresets": { + "$ref": "#/definitions/testPresets@v6..v9" + }, + "packagePresets": { + "$ref": "#/definitions/packagePresets@v6..v9" + }, + "workflowPresets": { + "$ref": "#/definitions/workflowPresets@v6..v9" + } }, + "required": [ + "version" + ], "additionalProperties": false }, { + "description": "The presets specify the generator and the build directory, and optionally an array of variables and other arguments to pass to CMake.", "properties": { - "$schema": { "$ref": "#/definitions/$schema" }, - "version": { - "const": 8, - "description": "A required integer representing the version of the JSON schema." + "$schema": { + "$ref": "#/definitions/$schema@v8.." }, - "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequiredV1" }, - "vendor": { "$ref": "#/definitions/vendor" }, - "configurePresets": { "$ref": "#/definitions/configurePresetsV7" }, - "buildPresets": { "$ref": "#/definitions/buildPresetsV4" }, - "testPresets": { "$ref": "#/definitions/testPresetsV6" }, - "packagePresets": { "$ref": "#/definitions/packagePresetsV6" }, - "workflowPresets": { "$ref": "#/definitions/workflowPresetsV6" }, - "include": { "$ref": "#/definitions/include" } + "version": { + "type": "integer", + "description": "A required integer representing the version of the JSON schema.", + "const": 8 + }, + "cmakeMinimumRequired": { + "$ref": "#/definitions/cmakeMinimumRequired@v1..v9" + }, + "include": { + "$ref": "#/definitions/include@v4.." + }, + "vendor": { + "$ref": "#/definitions/vendor@v1.." + }, + "configurePresets": { + "$ref": "#/definitions/configurePresets@v7..v9" + }, + "buildPresets": { + "$ref": "#/definitions/buildPresets@v4..v9" + }, + "testPresets": { + "$ref": "#/definitions/testPresets@v6..v9" + }, + "packagePresets": { + "$ref": "#/definitions/packagePresets@v6..v9" + }, + "workflowPresets": { + "$ref": "#/definitions/workflowPresets@v6..v9" + } }, + "required": [ + "version" + ], "additionalProperties": false }, { + "description": "The presets specify the generator and the build directory, and optionally an array of variables and other arguments to pass to CMake.", "properties": { - "$schema": { "$ref": "#/definitions/$schema" }, - "version": { - "const": 9, - "description": "A required integer representing the version of the JSON schema." + "$schema": { + "$ref": "#/definitions/$schema@v8.." }, - "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequiredV1" }, - "vendor": { "$ref": "#/definitions/vendor" }, - "configurePresets": { "$ref": "#/definitions/configurePresetsV7" }, - "buildPresets": { "$ref": "#/definitions/buildPresetsV4" }, - "testPresets": { "$ref": "#/definitions/testPresetsV6" }, - "packagePresets": { "$ref": "#/definitions/packagePresetsV6" }, - "workflowPresets": { "$ref": "#/definitions/workflowPresetsV6" }, - "include": { "$ref": "#/definitions/include" } + "version": { + "type": "integer", + "description": "A required integer representing the version of the JSON schema.", + "const": 9 + }, + "cmakeMinimumRequired": { + "$ref": "#/definitions/cmakeMinimumRequired@v1..v9" + }, + "include": { + "$ref": "#/definitions/include@v4.." + }, + "vendor": { + "$ref": "#/definitions/vendor@v1.." + }, + "configurePresets": { + "$ref": "#/definitions/configurePresets@v7..v9" + }, + "buildPresets": { + "$ref": "#/definitions/buildPresets@v4..v9" + }, + "testPresets": { + "$ref": "#/definitions/testPresets@v6..v9" + }, + "packagePresets": { + "$ref": "#/definitions/packagePresets@v6..v9" + }, + "workflowPresets": { + "$ref": "#/definitions/workflowPresets@v6..v9" + } }, + "required": [ + "version" + ], "additionalProperties": false }, { + "description": "The presets specify the generator and the build directory, and optionally an array of variables and other arguments to pass to CMake.", "properties": { - "$schema": { "$ref": "#/definitions/$schema" }, - "$comment": { "$ref": "#/definitions/$comment" }, - "version": { - "const": 10, - "description": "A required integer representing the version of the JSON schema." + "$schema": { + "$ref": "#/definitions/$schema@v8.." }, - "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequiredV10" }, - "vendor": { "$ref": "#/definitions/vendor" }, - "configurePresets": { "$ref": "#/definitions/configurePresetsV10" }, - "buildPresets": { "$ref": "#/definitions/buildPresetsV10" }, - "testPresets": { "$ref": "#/definitions/testPresetsV10" }, - "packagePresets": { "$ref": "#/definitions/packagePresetsV10" }, - "workflowPresets": { "$ref": "#/definitions/workflowPresetsV10" }, - "include": { "$ref": "#/definitions/include" } + "version": { + "type": "integer", + "description": "A required integer representing the version of the JSON schema.", + "const": 10 + }, + "cmakeMinimumRequired": { + "$ref": "#/definitions/cmakeMinimumRequired@v10.." + }, + "include": { + "$ref": "#/definitions/include@v4.." + }, + "vendor": { + "$ref": "#/definitions/vendor@v1.." + }, + "configurePresets": { + "$ref": "#/definitions/configurePresets@v10..v11" + }, + "buildPresets": { + "$ref": "#/definitions/buildPresets@v10.." + }, + "testPresets": { + "$ref": "#/definitions/testPresets@v10" + }, + "packagePresets": { + "$ref": "#/definitions/packagePresets@v10.." + }, + "workflowPresets": { + "$ref": "#/definitions/workflowPresets@v10.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } }, + "required": [ + "version" + ], + "additionalProperties": false + }, + { + "description": "The presets specify the generator and the build directory, and optionally an array of variables and other arguments to pass to CMake.", + "properties": { + "$schema": { + "$ref": "#/definitions/$schema@v8.." + }, + "version": { + "type": "integer", + "description": "A required integer representing the version of the JSON schema.", + "const": 11 + }, + "cmakeMinimumRequired": { + "$ref": "#/definitions/cmakeMinimumRequired@v10.." + }, + "include": { + "$ref": "#/definitions/include@v4.." + }, + "vendor": { + "$ref": "#/definitions/vendor@v1.." + }, + "configurePresets": { + "$ref": "#/definitions/configurePresets@v10..v11" + }, + "buildPresets": { + "$ref": "#/definitions/buildPresets@v10.." + }, + "testPresets": { + "$ref": "#/definitions/testPresets@v11" + }, + "packagePresets": { + "$ref": "#/definitions/packagePresets@v10.." + }, + "workflowPresets": { + "$ref": "#/definitions/workflowPresets@v10.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + }, + "required": [ + "version" + ], + "additionalProperties": false + }, + { + "description": "The presets specify the generator and the build directory, and optionally an array of variables and other arguments to pass to CMake.", + "properties": { + "$schema": { + "$ref": "#/definitions/$schema@v8.." + }, + "version": { + "type": "integer", + "description": "A required integer representing the version of the JSON schema.", + "const": 12 + }, + "cmakeMinimumRequired": { + "$ref": "#/definitions/cmakeMinimumRequired@v10.." + }, + "include": { + "$ref": "#/definitions/include@v4.." + }, + "vendor": { + "$ref": "#/definitions/vendor@v1.." + }, + "configurePresets": { + "$ref": "#/definitions/configurePresets@v12" + }, + "buildPresets": { + "$ref": "#/definitions/buildPresets@v10.." + }, + "testPresets": { + "$ref": "#/definitions/testPresets@v12" + }, + "packagePresets": { + "$ref": "#/definitions/packagePresets@v10.." + }, + "workflowPresets": { + "$ref": "#/definitions/workflowPresets@v10.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + }, + "required": [ + "version" + ], "additionalProperties": false } ], @@ -167,2845 +442,3588 @@ "version" ], "definitions": { - "$schema": { + "$schema@v8..": { "type": "string", - "description": "The schema against which to verify this document.", - "format": "uri-reference" + "format": "uri-reference", + "description": "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 autocompletion in editors that support JSON schema. It doesn't affect the 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." }, - "$comment": { + "cmakeMinimumRequired@v1..v9": { + "type": "object", + "description": "An optional object representing the minimum version of CMake needed to build this project.", + "unevaluatedProperties": false, + "properties": { + "major": { + "$ref": "#/definitions/cmakeMinimumRequired.major@v1.." + }, + "minor": { + "$ref": "#/definitions/cmakeMinimumRequired.minor@v1.." + }, + "patch": { + "$ref": "#/definitions/cmakeMinimumRequired.patch@v1.." + } + } + }, + "cmakeMinimumRequired@v10..": { + "type": "object", + "description": "An optional object representing the minimum version of CMake needed to build this project.", + "unevaluatedProperties": false, + "properties": { + "major": { + "$ref": "#/definitions/cmakeMinimumRequired.major@v1.." + }, + "minor": { + "$ref": "#/definitions/cmakeMinimumRequired.minor@v1.." + }, + "patch": { + "$ref": "#/definitions/cmakeMinimumRequired.patch@v1.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + } + }, + "cmakeMinimumRequired.major@v1..": { + "type": "integer", + "description": "An optional integer representing the major version." + }, + "cmakeMinimumRequired.minor@v1..": { + "type": "integer", + "description": "An optional integer representing the minor version." + }, + "cmakeMinimumRequired.patch@v1..": { + "type": "integer", + "description": "An optional integer representing the patch version." + }, + "$comment@v10..": { + "$ref": "#/definitions/comment@v10.." + }, + "comment@v10..": { "anyOf": [ { "type": "string", - "description": "The single-line comment" + "description": "A single-line comment." }, { "type": "array", - "description": "The multi-line comment", + "description": "A multi-line comment.", "minItems": 1, "items": { "type": "string", - "description": "One line of the multi-line comment" + "description": "One line of the multi-line comment." } } ] }, - "cmakeMinimumRequiredPropertiesV10": { - "type": "object", - "description": "An optional object representing the minimum version of CMake needed to build this project. Available in version 10 and higher.", - "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.", - "properties": { - "major": { - "type": "integer", - "description": "An optional integer representing the major version." - }, - "minor": { - "type": "integer", - "description": "An optional integer representing the minor version." - }, - "patch": { - "type": "integer", - "description": "An optional integer representing the patch version." - } - } - }, - "cmakeMinimumRequiredV10": { - "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" } - ], - "properties": { - "$comment": {}, - "major": {}, - "minor": {}, - "patch": {} - }, - "additionalProperties": 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" } - ], - "properties": { - "major": {}, - "minor": {}, - "patch": {} - }, - "additionalProperties": false - }, - "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, the keys should be a vendor-specific domain name followed by a /-separated path. For example, the Example IDE 1.0 could use example.com/ExampleIDE/1.0. The value of each field can be anything desired by the vendor, though will typically be a map.", - "properties": {} - }, - "configurePresetsArchitectureAsStringV1": { - "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", - "description": "An optional string representing the value." - }, - "strategy": { - "type": "string", - "description": "An optional string telling CMake how to handle the field. Valid values are: \"set\" Set the respective value. This will result in an error for generators that do not support the respective field. \"external\" Do not set the value, even if the generator supports it. This is useful if, for example, a preset uses the Ninja generator, and an IDE knows how to set up the Visual C++ environment from the architecture and toolset fields. In that case, CMake will ignore the field, but the IDE can use them to set up the environment before invoking CMake.", - "enum": [ - "set", - "external" - ] - } - } - }, - "configurePresetsArchitectureV10": { - "anyOf": [ - { "$ref": "#/definitions/configurePresetsArchitectureAsStringV1" }, - { - "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" } - ], - "properties": { - "$comment": {}, - "value": {}, - "strategy": {} - }, - "additionalProperties": false - } - ] - }, - "configurePresetsArchitectureV1": { - "anyOf": [ - { "$ref": "#/definitions/configurePresetsArchitectureAsStringV1" }, - { - "type": "object", - "description": "An optional object representing the platform for generators that support it. Available in version 1 and higher.", - "allOf": [ - { "$ref": "#/definitions/configurePresetsArchitectureAsObjectV1" } - ], - "properties": { - "value": {}, - "strategy": {} - }, - "additionalProperties": false - } - ] - }, - "configurePresetsToolsetAsStringV1": { - "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", - "description": "An optional string representing the value." - }, - "strategy": { - "type": "string", - "description": "An optional string telling CMake how to handle the field. Valid values are: \"set\" Set the respective value. This will result in an error for generators that do not support the respective field. \"external\" Do not set the value, even if the generator supports it. This is useful if, for example, a preset uses the Ninja generator, and an IDE knows how to set up the Visual C++ environment from the architecture and toolset fields. In that case, CMake will ignore the field, but the IDE can use them to set up the environment before invoking CMake.", - "enum": [ - "set", - "external" - ] - } - } - }, - "configurePresetsToolsetV10": { - "anyOf": [ - { "$ref": "#/definitions/configurePresetsToolsetAsStringV1" }, - { - "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" } - ], - "properties": { - "$comment": {}, - "value": {}, - "strategy": {} - }, - "additionalProperties": false - } - ] - }, - "configurePresetsToolsetV1": { - "anyOf": [ - { "$ref": "#/definitions/configurePresetsToolsetAsStringV1" }, - { - "type": "object", - "description": "An optional object representing the toolset for generators that support it. Available in version 1 and higher.", - "allOf": [ - { "$ref": "#/definitions/configurePresetsToolsetAsObjectV1" } - ], - "properties": { - "value": {}, - "strategy": {} - }, - "additionalProperties": false - } - ] - }, - "configurePresetsCacheVariablesAdditionalPropertiesAsNullV1": { - "type": "null", - "description": "Setting a variable to null causes it to not be set, even if a value was inherited from another preset." - }, - "configurePresetsCacheVariablesAdditionalPropertiesAsBooleanV1": { - "type": "boolean", - "description": "A boolean representing the value of the variable. Equivalent to \"TRUE\" or \"FALSE\"." - }, - "configurePresetsCacheVariablesAdditionalPropertiesAsStringV1": { - "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.", - "properties": { - "type": { - "type": "string", - "description": "An optional string representing the type of the variable. It should be BOOL, FILEPATH, PATH, STRING, or 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." - } - ] - } - } - }, - "configurePresetsCacheVariablesAdditionalPropertiesV10": { - "anyOf": [ - { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesAsNullV1" }, - { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesAsBooleanV1" }, - { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesAsStringV1" }, - { - "type": "object", - "description": "An object representing the type and value of the variable. Available in version 10 and higher.", - "allOf": [ - { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesAsObjectV10" }, - { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesAsObjectV1" } - ], - "properties": { - "$comment": {}, - "type": {}, - "value": {} - }, - "required": [ - "value" - ], - "additionalProperties": false - } - ] - }, - "configurePresetsCacheVariablesAdditionalPropertiesV1": { - "anyOf": [ - { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesAsNullV1" }, - { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesAsBooleanV1" }, - { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesAsStringV1" }, - { - "type": "object", - "description": "An object representing the type and value of the variable. Available in version 1 and higher.", - "allOf": [ - { "$ref": "#/definitions/configurePresetsCacheVariablesAdditionalPropertiesAsObjectV1" } - ], - "properties": { - "type": {}, - "value": {} - }, - "required": [ - "value" - ], - "additionalProperties": 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" } - } - }, - "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." - } - } - } - }, - "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." - } - } - } - } - } - }, - "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." - } - } - } - }, - "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": { - "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." - } - ] - }, - "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." - } - } - } - } - } - }, - "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" - ], - "additionalProperties": 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" - ], - "additionalProperties": 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" - ], - "additionalProperties": 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" } - } - } - }, - "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" - ] - } - } - } - }, - "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": { - "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": "^.+$" - } - }, - "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": { - "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": { - "type": "string", - "description": "An optional string representing an option to pass after -- on the command line." - } - } - } - } - }, - "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" - ], - "additionalProperties": 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" - ], - "additionalProperties": 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" - ], - "additionalProperties": false - } - }, - "buildPresetsV2": { - "type": "array", - "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.", - "allOf": [ - { "$ref": "#/definitions/buildPresetsItemsV2" } - ], - "items": { - "type": "object", - "properties": { - "name": {}, - "hidden": {}, - "inherits": {}, - "configurePreset": {}, - "vendor": {}, - "displayName": {}, - "description": {}, - "inheritConfigureEnvironment": {}, - "environment": {}, - "jobs": {}, - "targets": {}, - "configuration": {}, - "cleanFirst": {}, - "verbose": {}, - "nativeToolOptions": {} - }, - "required": [ - "name" - ], - "additionalProperties": false - } - }, - "testPresetsFilterIncludeIndexAsStringV2": { - "type": "string", - "description": "An optional string specifying a file with the command line syntax for --tests-information. Available in version 2 and higher." - }, - "testPresetsFilterIncludeIndexAsObjectV10": { - "type": "object", - "description": "An optional object specifying tests to include by test index. Available in version 10 and higher.", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" } - } - }, - "testPresetsFilterIncludeIndexAsObjectV2": { - "type": "object", - "description": "An optional object specifying tests to include by test index. Available in version 2 and higher.", - "properties": { - "start": { - "type": "integer", - "description": "An optional integer specifying a test index to start testing at." - }, - "end": { - "type": "integer", - "description": "An optional integer specifying a test index to stop testing at." - }, - "stride": { - "type": "integer", - "description": "An optional integer specifying the increment." - }, - "specificTests": { - "type": "array", - "description": "An optional array of integers specifying specific test indices to run.", - "items": { - "type": "integer", - "description": "An integer specifying the test to run by index." - } - } - } - }, - "testPresetsFilterIncludeIndexV10": { - "anyOf": [ - { "$ref": "#/definitions/testPresetsFilterIncludeIndexAsStringV2" }, - { - "type": "object", - "description": "An optional object specifying test preset filters. Available in version 10 and higher.", - "allOf": [ - { "$ref": "#/definitions/testPresetsFilterIncludeIndexAsObjectV10" }, - { "$ref": "#/definitions/testPresetsFilterIncludeIndexAsObjectV2" } - ], - "properties": { - "$comment": {}, - "start": {}, - "end": {}, - "stride": {}, - "specificTests": {} - }, - "additionalProperties": false - } - ] - }, - "testPresetsFilterIncludeIndexV2": { - "anyOf": [ - { "$ref": "#/definitions/testPresetsFilterIncludeIndexAsStringV2" }, - { - "type": "object", - "description": "An optional object specifying test preset filters. Available in version 2 and higher.", - "allOf": [ - { "$ref": "#/definitions/testPresetsFilterIncludeIndexAsObjectV2" } - ], - "properties": { - "start": {}, - "end": {}, - "stride": {}, - "specificTests": {} - }, - "additionalProperties": 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" } - } - } - } - } - } - }, - "execution": { - "type": "object", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" }, - "repeat": { - "type": "object", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" } - } - } - } - } - } - } - }, - "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." - } - } - } - } - } - }, - "testPresetsItemsV5": { - "type": "array", - "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 5 and higher.", - "items": { - "type": "object", - "properties": { - "output": { - "type": "object", - "description": "An optional object specifying output options.", - "properties": { - "testOutputTruncation": { - "type": "string", - "description": "An optional string specifying the test output truncation mode. Equivalent to passing --test-output-truncation on the command line. Must be one of the following values: \"tail\", \"middle\", or \"head\".", - "enum": [ - "tail", "middle", "head" - ] - } - } - } - } - } - }, - "testPresetsItemsV3": { - "type": "array", - "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 3 and higher." - }, - "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": { - "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": "^.+$" - } - }, - "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 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": { - "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" - ] - } - } - } - } - } - }, - "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" - ], - "additionalProperties": 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" - ], - "additionalProperties": 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" - ], - "additionalProperties": false - } - }, - "testPresetsV3": { - "type": "array", - "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 3 and higher.", - "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" - ], - "additionalProperties": false - } - }, - "testPresetsV2": { - "type": "array", - "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.", - "allOf": [ - { "$ref": "#/definitions/testPresetsItemsV2" } - ], - "items": { - "type": "object", - "properties": { - "name": {}, - "hidden": {}, - "inherits": {}, - "configurePreset": {}, - "vendor": {}, - "displayName": {}, - "description": {}, - "inheritConfigureEnvironment": {}, - "environment": {}, - "configuration": {}, - "overwriteConfigurationFile": {}, - "output": { - "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" - ], - "additionalProperties": 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" } - } - } - } - } - }, - "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": { - "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": "^.+$" - } - }, - "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." - }, - "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." - } - } - }, - "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." - } - } - } - }, - "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" - ], - "additionalProperties": 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" - ], - "additionalProperties": false - } - }, - "workflowPresetsItemsV10": { - "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.", - "items": { - "type": "object", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" }, - "steps": { - "type": "array", - "items": { - "type": "object", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" } - } - } - } - } - } - }, - "workflowPresetsItemsV6": { - "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.", - "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 - } - } - } - } - } - } - }, - "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 - } - } - }, - "required": [ - "name", - "steps" - ], - "additionalProperties": 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 - } - } - }, - "required": [ - "name", - "steps" - ], - "additionalProperties": 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": { - "type": { - "type": "string", - "description": "A required string specifying the type of the condition.", - "const": "const" - }, - "value": { - "type": "boolean", - "description": "A required boolean which provides a constant value for the condition's evaluation." - } - } - }, - "conditionAsObjectEqualsV10": { - "type": "object", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" } - } - }, - "conditionAsObjectEqualsV3": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "A required string specifying the type of the condition.", - "enum": [ "equals", "notEquals" ] - }, - "lhs": { - "type": "string", - "description": "First string to compare. This field supports macro expansion." - }, - "rhs": { - "type": "string", - "description": "Second string to compare. This field supports macro expansion." - } - } - }, - "conditionAsObjectInListV10": { - "type": "object", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" } - } - }, - "conditionAsObjectInListV3": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "A required string specifying the type of the condition.", - "enum": [ "inList", "notInList" ] - }, - "string": { - "type": "string", - "description": "A required string to search for. This field supports macro expansion." - }, - "list": { - "type": "array", - "description": "A required list of strings to search. This field supports macro expansion, and uses short-circuit evaluation.", - "items": { - "type": "string" - } - } - } - }, - "conditionAsObjectMatchesV10": { - "type": "object", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" } - } - }, - "conditionAsObjectMatchesV3": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "A required string specifying the type of the condition.", - "enum": [ "matches", "notMatches" ] - }, - "string": { - "type": "string", - "description": "A required string to search. This field supports macro expansion." - }, - "regex": { - "type": "string", - "description": "A required regular expression to search for. This field supports macro expansion." - } - } - }, - "conditionAsObjectAggregationV10": { - "type": "object", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" } - } - }, - "conditionAsObjectAggregationV3": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "A required string specifying the type of the condition.", - "enum": [ "anyOf", "allOf" ] - }, - "conditions": { - "type": "array", - "description": "A required array of condition objects. These conditions use short-circuit evaluation." - } - } - }, - "conditionAsObjectNotV10": { - "type": "object", - "properties": { - "$comment": { "$ref": "#/definitions/$comment" } - } - }, - "conditionAsObjectNotV3": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "A required string specifying the type of the condition.", - "const": "not" - } - } - }, - "conditionV10": { - "anyOf": [ - { "$ref": "#/definitions/conditionAsBooleanV3" }, - { - "type": "object", - "allOf": [ - { "$ref": "#/definitions/conditionAsObjectConstV10" }, - { "$ref": "#/definitions/conditionAsObjectConstV3" } - ], - "properties": { - "$comment": {}, - "type": {}, - "value": {} - }, - "required": [ - "type", - "value" - ], - "additionalProperties": false - }, - { - "type": "object", - "allOf": [ - { "$ref": "#/definitions/conditionAsObjectEqualsV10" }, - { "$ref": "#/definitions/conditionAsObjectEqualsV3" } - ], - "properties": { - "$comment": {}, - "type": {}, - "lhs": {}, - "rhs": {} - }, - "required": [ - "type", - "lhs", - "rhs" - ], - "additionalProperties": false - }, - { - "type": "object", - "allOf": [ - { "$ref": "#/definitions/conditionAsObjectInListV10" }, - { "$ref": "#/definitions/conditionAsObjectInListV3" } - ], - "properties": { - "$comment": {}, - "type": {}, - "string": {}, - "list": {} - }, - "required": [ - "type", - "string", - "list" - ], - "additionalProperties": false - }, - { - "type": "object", - "allOf": [ - { "$ref": "#/definitions/conditionAsObjectMatchesV10" }, - { "$ref": "#/definitions/conditionAsObjectMatchesV3" } - ], - "properties": { - "$comment": {}, - "type": {}, - "string": {}, - "regex": {} - }, - "required": [ - "type", - "string", - "regex" - ], - "additionalProperties": false - }, - { - "type": "object", - "allOf": [ - { "$ref": "#/definitions/conditionAsObjectAggregationV10" }, - { "$ref": "#/definitions/conditionAsObjectAggregationV3" } - ], - "properties": { - "$comment": {}, - "type": {}, - "conditions": { - "type": "array", - "items": { "$ref": "#/definitions/conditionV10" } - } - }, - "required": [ - "type", - "conditions" - ], - "additionalProperties": false - }, - { - "type": "object", - "allOf": [ - { "$ref": "#/definitions/conditionAsObjectNotV10" }, - { "$ref": "#/definitions/conditionAsObjectNotV3" } - ], - "properties": { - "$comment": {}, - "type": {}, - "condition": { "$ref": "#/definitions/conditionV10" } - }, - "required": [ - "type", - "condition" - ], - "additionalProperties": false - } - ] - }, - "conditionV3": { - "anyOf": [ - { "$ref": "#/definitions/conditionAsBooleanV3" }, - { - "type": "object", - "allOf": [ - { "$ref": "#/definitions/conditionAsObjectConstV3" } - ], - "properties": { - "type": {}, - "value": {} - }, - "required": [ - "type", - "value" - ], - "additionalProperties": false - }, - { - "type": "object", - "allOf": [ - { "$ref": "#/definitions/conditionAsObjectEqualsV3" } - ], - "properties": { - "type": {}, - "lhs": {}, - "rhs": {} - }, - "required": [ - "type", - "lhs", - "rhs" - ], - "additionalProperties": false - }, - { - "type": "object", - "allOf": [ - { "$ref": "#/definitions/conditionAsObjectInListV3" } - ], - "properties": { - "type": {}, - "string": {}, - "list": {} - }, - "required": [ - "type", - "string", - "list" - ], - "additionalProperties": false - }, - { - "type": "object", - "allOf": [ - { "$ref": "#/definitions/conditionAsObjectMatchesV3" } - ], - "properties": { - "type": {}, - "string": {}, - "regex": {} - }, - "required": [ - "type", - "string", - "regex" - ], - "additionalProperties": false - }, - { - "type": "object", - "allOf": [ - { "$ref": "#/definitions/conditionAsObjectAggregationV3" } - ], - "properties": { - "type": {}, - "conditions": { - "type": "array", - "items": { "$ref": "#/definitions/conditionV3" } - } - }, - "required": [ - "type", - "conditions" - ], - "additionalProperties": false - }, - { - "type": "object", - "allOf": [ - { "$ref": "#/definitions/conditionAsObjectNotV3" } - ], - "properties": { - "type": {}, - "condition": { "$ref": "#/definitions/conditionV3" } - }, - "required": [ - "type", - "condition" - ], - "additionalProperties": false - } - ] - }, - "topConditionAsNullV3": { - "type": "null", - "description": "Null indicates that the condition always evaluates to true and is not inherited." - }, - "topConditionV10": { - "anyOf": [ - { "$ref": "#/definitions/conditionV10" }, - { "$ref": "#/definitions/topConditionAsNullV3" } - ] - }, - "topConditionV3": { - "anyOf": [ - { "$ref": "#/definitions/conditionV3" }, - { "$ref": "#/definitions/topConditionAsNullV3" } - ] - }, - "include": { + "include@v4..": { "type": "array", "description": "An optional array of strings representing files to include. If the filenames are not absolute, they are considered relative to the current file.", "items": { "type": "string" } + }, + "vendor@v1..": { + "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, the keys should be a vendor-specific domain name followed by a /-separated path. For example, the Example IDE 1.0 could use example.com/ExampleIDE/1.0. The value of each field can be anything desired by the vendor, though will typically be a map.", + "properties": {} + }, + "configurePresets@v1..v2": { + "type": "array", + "description": "An optional array of configure preset objects.", + "items": { + "type": "object", + "description": "A configure preset object.", + "unevaluatedProperties": false, + "properties": { + "name": { + "$ref": "#/definitions/configurePresets.name@v1.." + }, + "hidden": { + "$ref": "#/definitions/configurePresets.hidden@v1.." + }, + "inherits": { + "$ref": "#/definitions/configurePresets.inherits@v1.." + }, + "vendor": { + "$ref": "#/definitions/configurePresets.vendor@v1.." + }, + "displayName": { + "$ref": "#/definitions/configurePresets.displayName@v1.." + }, + "description": { + "$ref": "#/definitions/configurePresets.description@v1.." + }, + "generator": { + "$ref": "#/definitions/configurePresets.generator@v1..v2" + }, + "architecture": { + "$ref": "#/definitions/configurePresets.architecture@v1..v9" + }, + "toolset": { + "$ref": "#/definitions/configurePresets.toolset@v1..v9" + }, + "binaryDir": { + "$ref": "#/definitions/configurePresets.binaryDir@v1..v2" + }, + "cmakeExecutable": { + "$ref": "#/definitions/configurePresets.cmakeExecutable@v1.." + }, + "cacheVariables": { + "$ref": "#/definitions/configurePresets.cacheVariables@v1..v9" + }, + "environment": { + "$ref": "#/definitions/configurePresets.environment@v1.." + }, + "warnings": { + "$ref": "#/definitions/configurePresets.warnings@v1..v9" + }, + "errors": { + "$ref": "#/definitions/configurePresets.errors@v1..v9" + }, + "debug": { + "$ref": "#/definitions/configurePresets.debug@v1..v9" + } + }, + "required": [ + "name" + ] + } + }, + "configurePresets@v3..v6": { + "type": "array", + "description": "An optional array of configure preset objects.", + "items": { + "type": "object", + "description": "A configure preset object.", + "unevaluatedProperties": false, + "properties": { + "name": { + "$ref": "#/definitions/configurePresets.name@v1.." + }, + "hidden": { + "$ref": "#/definitions/configurePresets.hidden@v1.." + }, + "inherits": { + "$ref": "#/definitions/configurePresets.inherits@v1.." + }, + "condition": { + "$ref": "#/definitions/configurePresets.condition@v3..v9" + }, + "vendor": { + "$ref": "#/definitions/configurePresets.vendor@v1.." + }, + "displayName": { + "$ref": "#/definitions/configurePresets.displayName@v1.." + }, + "description": { + "$ref": "#/definitions/configurePresets.description@v1.." + }, + "generator": { + "$ref": "#/definitions/configurePresets.generator@v3.." + }, + "architecture": { + "$ref": "#/definitions/configurePresets.architecture@v1..v9" + }, + "toolset": { + "$ref": "#/definitions/configurePresets.toolset@v1..v9" + }, + "toolchainFile": { + "$ref": "#/definitions/configurePresets.toolchainFile@v3.." + }, + "binaryDir": { + "$ref": "#/definitions/configurePresets.binaryDir@v3.." + }, + "installDir": { + "$ref": "#/definitions/configurePresets.installDir@v3.." + }, + "cmakeExecutable": { + "$ref": "#/definitions/configurePresets.cmakeExecutable@v1.." + }, + "cacheVariables": { + "$ref": "#/definitions/configurePresets.cacheVariables@v1..v9" + }, + "environment": { + "$ref": "#/definitions/configurePresets.environment@v1.." + }, + "warnings": { + "$ref": "#/definitions/configurePresets.warnings@v1..v9" + }, + "errors": { + "$ref": "#/definitions/configurePresets.errors@v1..v9" + }, + "debug": { + "$ref": "#/definitions/configurePresets.debug@v1..v9" + } + }, + "required": [ + "name" + ] + } + }, + "configurePresets@v7..v9": { + "type": "array", + "description": "An optional array of configure preset objects.", + "items": { + "type": "object", + "description": "A configure preset object.", + "unevaluatedProperties": false, + "properties": { + "name": { + "$ref": "#/definitions/configurePresets.name@v1.." + }, + "hidden": { + "$ref": "#/definitions/configurePresets.hidden@v1.." + }, + "inherits": { + "$ref": "#/definitions/configurePresets.inherits@v1.." + }, + "condition": { + "$ref": "#/definitions/configurePresets.condition@v3..v9" + }, + "vendor": { + "$ref": "#/definitions/configurePresets.vendor@v1.." + }, + "displayName": { + "$ref": "#/definitions/configurePresets.displayName@v1.." + }, + "description": { + "$ref": "#/definitions/configurePresets.description@v1.." + }, + "generator": { + "$ref": "#/definitions/configurePresets.generator@v3.." + }, + "architecture": { + "$ref": "#/definitions/configurePresets.architecture@v1..v9" + }, + "toolset": { + "$ref": "#/definitions/configurePresets.toolset@v1..v9" + }, + "toolchainFile": { + "$ref": "#/definitions/configurePresets.toolchainFile@v3.." + }, + "binaryDir": { + "$ref": "#/definitions/configurePresets.binaryDir@v3.." + }, + "installDir": { + "$ref": "#/definitions/configurePresets.installDir@v3.." + }, + "cmakeExecutable": { + "$ref": "#/definitions/configurePresets.cmakeExecutable@v1.." + }, + "cacheVariables": { + "$ref": "#/definitions/configurePresets.cacheVariables@v1..v9" + }, + "environment": { + "$ref": "#/definitions/configurePresets.environment@v1.." + }, + "warnings": { + "$ref": "#/definitions/configurePresets.warnings@v1..v9" + }, + "errors": { + "$ref": "#/definitions/configurePresets.errors@v1..v9" + }, + "debug": { + "$ref": "#/definitions/configurePresets.debug@v1..v9" + }, + "trace": { + "$ref": "#/definitions/configurePresets.trace@v7..v9" + } + }, + "required": [ + "name" + ] + } + }, + "configurePresets@v10..v11": { + "type": "array", + "description": "An optional array of configure preset objects.", + "items": { + "type": "object", + "description": "A configure preset object.", + "unevaluatedProperties": false, + "properties": { + "name": { + "$ref": "#/definitions/configurePresets.name@v1.." + }, + "hidden": { + "$ref": "#/definitions/configurePresets.hidden@v1.." + }, + "inherits": { + "$ref": "#/definitions/configurePresets.inherits@v1.." + }, + "condition": { + "$ref": "#/definitions/configurePresets.condition@v10.." + }, + "vendor": { + "$ref": "#/definitions/configurePresets.vendor@v1.." + }, + "displayName": { + "$ref": "#/definitions/configurePresets.displayName@v1.." + }, + "description": { + "$ref": "#/definitions/configurePresets.description@v1.." + }, + "generator": { + "$ref": "#/definitions/configurePresets.generator@v3.." + }, + "architecture": { + "$ref": "#/definitions/configurePresets.architecture@v10.." + }, + "toolset": { + "$ref": "#/definitions/configurePresets.toolset@v10.." + }, + "toolchainFile": { + "$ref": "#/definitions/configurePresets.toolchainFile@v3.." + }, + "graphviz": { + "$ref": "#/definitions/configurePresets.graphviz@v10.." + }, + "binaryDir": { + "$ref": "#/definitions/configurePresets.binaryDir@v3.." + }, + "installDir": { + "$ref": "#/definitions/configurePresets.installDir@v3.." + }, + "cmakeExecutable": { + "$ref": "#/definitions/configurePresets.cmakeExecutable@v1.." + }, + "cacheVariables": { + "$ref": "#/definitions/configurePresets.cacheVariables@v10.." + }, + "environment": { + "$ref": "#/definitions/configurePresets.environment@v1.." + }, + "warnings": { + "$ref": "#/definitions/configurePresets.warnings@v10..v11" + }, + "errors": { + "$ref": "#/definitions/configurePresets.errors@v10..v11" + }, + "debug": { + "$ref": "#/definitions/configurePresets.debug@v10.." + }, + "trace": { + "$ref": "#/definitions/configurePresets.trace@v10.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + }, + "required": [ + "name" + ] + } + }, + "configurePresets@v12": { + "type": "array", + "description": "An optional array of configure preset objects.", + "items": { + "type": "object", + "description": "A configure preset object.", + "unevaluatedProperties": false, + "properties": { + "name": { + "$ref": "#/definitions/configurePresets.name@v1.." + }, + "hidden": { + "$ref": "#/definitions/configurePresets.hidden@v1.." + }, + "inherits": { + "$ref": "#/definitions/configurePresets.inherits@v1.." + }, + "condition": { + "$ref": "#/definitions/configurePresets.condition@v10.." + }, + "vendor": { + "$ref": "#/definitions/configurePresets.vendor@v1.." + }, + "displayName": { + "$ref": "#/definitions/configurePresets.displayName@v1.." + }, + "description": { + "$ref": "#/definitions/configurePresets.description@v1.." + }, + "generator": { + "$ref": "#/definitions/configurePresets.generator@v3.." + }, + "architecture": { + "$ref": "#/definitions/configurePresets.architecture@v10.." + }, + "toolset": { + "$ref": "#/definitions/configurePresets.toolset@v10.." + }, + "toolchainFile": { + "$ref": "#/definitions/configurePresets.toolchainFile@v3.." + }, + "graphviz": { + "$ref": "#/definitions/configurePresets.graphviz@v10.." + }, + "binaryDir": { + "$ref": "#/definitions/configurePresets.binaryDir@v3.." + }, + "installDir": { + "$ref": "#/definitions/configurePresets.installDir@v3.." + }, + "cmakeExecutable": { + "$ref": "#/definitions/configurePresets.cmakeExecutable@v1.." + }, + "cacheVariables": { + "$ref": "#/definitions/configurePresets.cacheVariables@v10.." + }, + "environment": { + "$ref": "#/definitions/configurePresets.environment@v1.." + }, + "warnings": { + "$ref": "#/definitions/configurePresets.warnings@v12" + }, + "errors": { + "$ref": "#/definitions/configurePresets.errors@v12" + }, + "debug": { + "$ref": "#/definitions/configurePresets.debug@v10.." + }, + "trace": { + "$ref": "#/definitions/configurePresets.trace@v10.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + }, + "required": [ + "name" + ] + } + }, + "configurePresets.name@v1..": { + "type": "string", + "minLength": 1, + "description": "A required string representing the machine-friendly name of the preset. This identifier is used in the 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, package, or workflow preset." + }, + "configurePresets.hidden@v1..": { + "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." + }, + "configurePresets.inherits@v1..": { + "anyOf": [ + { + "type": "string", + "minLength": 1, + "description": "An optional string representing the name of the preset from which to inherit." + }, + { + "type": "array", + "description": "An optional array of strings representing the names of presets from which to inherit. 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", + "minLength": 1, + "description": "An optional string representing the name of the preset from which to inherit." + } + } + ] + }, + "configurePresets.condition@v3..v9": { + "anyOf": [ + { + "$ref": "#/definitions/condition@v3..v9" + }, + { + "type": "null", + "description": "Null indicates that the condition always evaluates to true and is not inherited." + } + ] + }, + "configurePresets.condition@v10..": { + "anyOf": [ + { + "$ref": "#/definitions/condition@v10.." + }, + { + "type": "null", + "description": "Null indicates that the condition always evaluates to true and is not inherited." + } + ] + }, + "configurePresets.vendor@v1..": { + "type": "object", + "minLength": 1, + "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": {} + }, + "configurePresets.displayName@v1..": { + "type": "string", + "description": "An optional string with a human-friendly name of the preset." + }, + "configurePresets.description@v1..": { + "type": "string", + "description": "An optional string with a human-friendly description of the preset." + }, + "configurePresets.generator@v1..v2": { + "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." + }, + "configurePresets.generator@v3..": { + "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." + }, + "configurePresets.architecture@v1..v9": { + "anyOf": [ + { + "type": "string", + "description": "An optional string representing the platform for generators that support it." + }, + { + "type": "object", + "description": "An optional string representing the platform for generators that support it.", + "unevaluatedProperties": false, + "properties": { + "value": { + "$ref": "#/definitions/configurePresets.architecture.value@v1.." + }, + "strategy": { + "$ref": "#/definitions/configurePresets.architecture.strategy@v1.." + } + } + } + ] + }, + "configurePresets.architecture@v10..": { + "anyOf": [ + { + "type": "string", + "description": "An optional string representing the platform for generators that support it." + }, + { + "type": "object", + "description": "An optional string representing the platform for generators that support it.", + "unevaluatedProperties": false, + "properties": { + "value": { + "$ref": "#/definitions/configurePresets.architecture.value@v1.." + }, + "strategy": { + "$ref": "#/definitions/configurePresets.architecture.strategy@v1.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + } + } + ] + }, + "configurePresets.architecture.value@v1..": { + "type": "string", + "description": "An optional string representing the value." + }, + "configurePresets.architecture.strategy@v1..": { + "type": "string", + "enum": [ + "set", + "external" + ], + "description": "An optional string telling CMake how to handle the field. Valid values are: \"set\" Set the respective value. This will result in an error for generators that do not support the respective field. \"external\" Do not set the value, even if the generator supports it. This is useful if, for example, a preset uses the Ninja generator, and an IDE knows how to set up the Visual C++ environment from the architecture and toolset fields. In that case, CMake will ignore the field, but the IDE can use them to set up the environment before invoking CMake." + }, + "configurePresets.toolset@v1..v9": { + "anyOf": [ + { + "type": "string", + "description": "An optional string representing the toolset for generators that support it." + }, + { + "type": "object", + "description": "An optional string representing the toolset for generators that support it.", + "unevaluatedProperties": false, + "properties": { + "value": { + "$ref": "#/definitions/configurePresets.toolset.value@v1.." + }, + "strategy": { + "$ref": "#/definitions/configurePresets.toolset.strategy@v1.." + } + } + } + ] + }, + "configurePresets.toolset@v10..": { + "anyOf": [ + { + "type": "string", + "description": "An optional string representing the toolset for generators that support it." + }, + { + "type": "object", + "description": "An optional string representing the toolset for generators that support it.", + "unevaluatedProperties": false, + "properties": { + "value": { + "$ref": "#/definitions/configurePresets.toolset.value@v1.." + }, + "strategy": { + "$ref": "#/definitions/configurePresets.toolset.strategy@v1.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + } + } + ] + }, + "configurePresets.toolset.value@v1..": { + "type": "string", + "description": "An optional string representing the value." + }, + "configurePresets.toolset.strategy@v1..": { + "type": "string", + "enum": [ + "set", + "external" + ], + "description": "An optional string telling CMake how to handle the field. Valid values are: \"set\" Set the respective value. This will result in an error for generators that do not support the respective field. \"external\" Do not set the value, even if the generator supports it. This is useful if, for example, a preset uses the Ninja generator, and an IDE knows how to set up the Visual C++ environment from the architecture and toolset fields. In that case, CMake will ignore the field, but the IDE can use them to set up the environment before invoking CMake." + }, + "configurePresets.toolchainFile@v3..": { + "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." + }, + "configurePresets.graphviz@v10..": { + "type": "string", + "description": "An optional string specifying the path to the graphviz dot file." + }, + "configurePresets.binaryDir@v1..v2": { + "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)." + }, + "configurePresets.binaryDir@v3..": { + "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." + }, + "configurePresets.installDir@v3..": { + "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." + }, + "configurePresets.cmakeExecutable@v1..": { + "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." + }, + "configurePresets.cacheVariables@v1..v9": { + "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.", + "propertyNames": { + "pattern": "^.+$" + }, + "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": "boolean", + "description": "A boolean representing the value of the variable. Equivalent to \"TRUE\" or \"FALSE\"" + }, + { + "type": "string", + "description": "A string representing the value of the variable (which supports macro expansion)." + }, + { + "type": "object", + "description": "An optional object representing the cache variables for generators that support it.", + "unevaluatedProperties": false, + "properties": { + "type": { + "$ref": "#/definitions/configurePresets.cacheVariables.type@v1.." + }, + "value": { + "$ref": "#/definitions/configurePresets.cacheVariables.value@v1.." + } + }, + "required": [ + "value" + ] + } + ] + } + }, + "configurePresets.cacheVariables@v10..": { + "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.", + "propertyNames": { + "pattern": "^.+$" + }, + "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": "boolean", + "description": "A boolean representing the value of the variable. Equivalent to \"TRUE\" or \"FALSE\"" + }, + { + "type": "string", + "description": "A string representing the value of the variable (which supports macro expansion)." + }, + { + "type": "object", + "description": "An optional object representing the cache variables for generators that support it.", + "unevaluatedProperties": false, + "properties": { + "type": { + "$ref": "#/definitions/configurePresets.cacheVariables.type@v1.." + }, + "value": { + "$ref": "#/definitions/configurePresets.cacheVariables.value@v1.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + }, + "required": [ + "value" + ] + } + ] + } + }, + "configurePresets.cacheVariables.type@v1..": { + "type": "string", + "enum": [ + "BOOL", + "FILEPATH", + "PATH", + "STRING", + "INTERNAL" + ], + "description": "An optional string representing the type of the variable. It should be BOOL, FILEPATH, PATH, STRING, or INTERNAL." + }, + "configurePresets.cacheVariables.value@v1..": { + "anyOf": [ + { + "type": "boolean", + "description": "A boolean representing the value of the variable. Equivalent to \"TRUE\" or \"FALSE\"." + }, + { + "type": "string", + "description": "A string representing the value of the variable (which supports macro expansion)." + } + ] + }, + "configurePresets.environment@v1..": { + "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.", + "propertyNames": { + "pattern": "^.+$" + }, + "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." + } + ] + } + }, + "configurePresets.warnings@v1..v9": { + "type": "object", + "description": "An optional object specifying the warnings to enable.", + "unevaluatedProperties": false, + "properties": { + "deprecated": { + "$ref": "#/definitions/configurePresets.warnings.deprecated@v1.." + }, + "dev": { + "$ref": "#/definitions/configurePresets.warnings.dev@v1..v11" + }, + "uninitialized": { + "$ref": "#/definitions/configurePresets.warnings.uninitialized@v1.." + }, + "unusedCli": { + "$ref": "#/definitions/configurePresets.warnings.unusedCli@v1.." + }, + "systemVars": { + "$ref": "#/definitions/configurePresets.warnings.systemVars@v1.." + } + } + }, + "configurePresets.warnings@v10..v11": { + "type": "object", + "description": "An optional object specifying the warnings to enable.", + "unevaluatedProperties": false, + "properties": { + "deprecated": { + "$ref": "#/definitions/configurePresets.warnings.deprecated@v1.." + }, + "dev": { + "$ref": "#/definitions/configurePresets.warnings.dev@v1..v11" + }, + "uninitialized": { + "$ref": "#/definitions/configurePresets.warnings.uninitialized@v1.." + }, + "unusedCli": { + "$ref": "#/definitions/configurePresets.warnings.unusedCli@v1.." + }, + "systemVars": { + "$ref": "#/definitions/configurePresets.warnings.systemVars@v1.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + } + }, + "configurePresets.warnings@v12": { + "type": "object", + "description": "An optional object specifying the warnings to enable.", + "unevaluatedProperties": false, + "properties": { + "author": { + "$ref": "#/definitions/configurePresets.warnings.author@v12" + }, + "deprecated": { + "$ref": "#/definitions/configurePresets.warnings.deprecated@v1.." + }, + "installAbsoluteDestination": { + "$ref": "#/definitions/configurePresets.warnings.installAbsoluteDestination@v12" + }, + "uninitialized": { + "$ref": "#/definitions/configurePresets.warnings.uninitialized@v1.." + }, + "unusedCli": { + "$ref": "#/definitions/configurePresets.warnings.unusedCli@v1.." + }, + "systemVars": { + "$ref": "#/definitions/configurePresets.warnings.systemVars@v1.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + } + }, + "configurePresets.warnings.author@v12": { + "type": "boolean", + "description": "An optional boolean. Equivalent to passing -Wauthor or -Wno-author on the command line. This may not be set to false if errors.author is set to true." + }, + "configurePresets.warnings.deprecated@v1..": { + "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." + }, + "configurePresets.warnings.dev@v1..v11": { + "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." + }, + "configurePresets.warnings.installAbsoluteDestination@v12": { + "type": "boolean", + "description": "An optional boolean. Equivalent to passing -Winstall-absolute-destination or -Wno-install-absolute-destination on the command line. This may not be set to false if errors.installAbsoluteDestination is set to true." + }, + "configurePresets.warnings.uninitialized@v1..": { + "type": "boolean", + "description": "An optional boolean. Equivalent to passing -Wuninitialized or -Wno-uninitialized on the command line. This may not be set to false if errors.uninitialized is set to true." + }, + "configurePresets.warnings.unusedCli@v1..": { + "type": "boolean", + "description": "An optional boolean. Equivalent to passing -Wunused-cli or -Wno-unused-cli on the command line. This may not be set to false if errors.unusedCli is set to true." + }, + "configurePresets.warnings.systemVars@v1..": { + "type": "boolean", + "description": "An optional boolean. Setting this to true is equivalent to passing --check-system-vars on the command line." + }, + "configurePresets.errors@v1..v9": { + "type": "object", + "description": "An optional object specifying the errors to enable.", + "unevaluatedProperties": false, + "properties": { + "deprecated": { + "$ref": "#/definitions/configurePresets.errors.deprecated@v1.." + }, + "dev": { + "$ref": "#/definitions/configurePresets.errors.dev@v1..v11" + } + } + }, + "configurePresets.errors@v10..v11": { + "type": "object", + "description": "An optional object specifying the errors to enable.", + "unevaluatedProperties": false, + "properties": { + "deprecated": { + "$ref": "#/definitions/configurePresets.errors.deprecated@v1.." + }, + "dev": { + "$ref": "#/definitions/configurePresets.errors.dev@v1..v11" + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + } + }, + "configurePresets.errors@v12": { + "type": "object", + "description": "An optional object specifying the errors to enable.", + "unevaluatedProperties": false, + "properties": { + "author": { + "$ref": "#/definitions/configurePresets.errors.author@v12" + }, + "deprecated": { + "$ref": "#/definitions/configurePresets.errors.deprecated@v1.." + }, + "installAbsoluteDestination": { + "$ref": "#/definitions/configurePresets.errors.installAbsoluteDestination@v12" + }, + "uninitialized": { + "$ref": "#/definitions/configurePresets.errors.uninitialized@v12" + }, + "unusedCli": { + "$ref": "#/definitions/configurePresets.errors.unusedCli@v12" + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + } + }, + "configurePresets.errors.author@v12": { + "type": "boolean", + "description": "An optional boolean. Equivalent to passing -Werror=author or -Wno-error=author on the command line. This may not be set to true if warnings.author is set to false." + }, + "configurePresets.errors.deprecated@v1..": { + "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." + }, + "configurePresets.errors.dev@v1..v11": { + "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." + }, + "configurePresets.errors.installAbsoluteDestination@v12": { + "type": "boolean", + "description": "An optional boolean. Equivalent to passing -Werror=install-absolute-destination or -Wno-error=install-absolute-destination on the command line. This may not be set to true if warnings.installAbsoluteDestination is set to false." + }, + "configurePresets.errors.uninitialized@v12": { + "type": "boolean", + "description": "An optional boolean. Equivalent to passing -Werror=uninitialized or -Wno-error=uninitialized on the command line. This may not be set to true if warnings.uninitialized is set to false." + }, + "configurePresets.errors.unusedCli@v12": { + "type": "boolean", + "description": "An optional boolean. Equivalent to passing -Werror=unused-cli or -Wno-error=unused-cli on the command line. This may not be set to true if warnings.unusedCli is set to false." + }, + "configurePresets.debug@v1..v9": { + "type": "object", + "description": "An optional object specifying debug options.", + "unevaluatedProperties": false, + "properties": { + "output": { + "$ref": "#/definitions/configurePresets.debug.output@v1.." + }, + "tryCompile": { + "$ref": "#/definitions/configurePresets.debug.tryCompile@v1.." + }, + "find": { + "$ref": "#/definitions/configurePresets.debug.find@v1.." + } + } + }, + "configurePresets.debug@v10..": { + "type": "object", + "description": "An optional object specifying debug options.", + "unevaluatedProperties": false, + "properties": { + "output": { + "$ref": "#/definitions/configurePresets.debug.output@v1.." + }, + "tryCompile": { + "$ref": "#/definitions/configurePresets.debug.tryCompile@v1.." + }, + "find": { + "$ref": "#/definitions/configurePresets.debug.find@v1.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + } + }, + "configurePresets.debug.output@v1..": { + "type": "boolean", + "description": "An optional boolean. Setting this to true is equivalent to passing --debug-output on the command line." + }, + "configurePresets.debug.tryCompile@v1..": { + "type": "boolean", + "description": "An optional boolean. Setting this to true is equivalent to passing --debug-trycompile on the command line." + }, + "configurePresets.debug.find@v1..": { + "type": "boolean", + "description": "An optional boolean. Setting this to true is equivalent to passing --debug-find on the command line." + }, + "configurePresets.trace@v7..v9": { + "type": "object", + "description": "An optional object specifying trace options.", + "unevaluatedProperties": false, + "properties": { + "mode": { + "$ref": "#/definitions/configurePresets.trace.mode@v7.." + }, + "format": { + "$ref": "#/definitions/configurePresets.trace.format@v7.." + }, + "source": { + "$ref": "#/definitions/configurePresets.trace.source@v7.." + }, + "redirect": { + "$ref": "#/definitions/configurePresets.trace.redirect@v7.." + } + } + }, + "configurePresets.trace@v10..": { + "type": "object", + "description": "An optional object specifying trace options.", + "unevaluatedProperties": false, + "properties": { + "mode": { + "$ref": "#/definitions/configurePresets.trace.mode@v7.." + }, + "format": { + "$ref": "#/definitions/configurePresets.trace.format@v7.." + }, + "source": { + "$ref": "#/definitions/configurePresets.trace.source@v7.." + }, + "redirect": { + "$ref": "#/definitions/configurePresets.trace.redirect@v7.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + } + }, + "configurePresets.trace.mode@v7..": { + "type": "string", + "enum": [ + "on", + "off", + "expand" + ], + "description": "An optional string that specifies the trace mode." + }, + "configurePresets.trace.format@v7..": { + "type": "string", + "enum": [ + "human", + "json-v1" + ], + "description": "An optional string that specifies the trace output format." + }, + "configurePresets.trace.source@v7..": { + "anyOf": [ + { + "type": "string", + "minLength": 1, + "description": "An optional string representing the path to one source file to be traced." + }, + { + "type": "array", + "description": "An optional array of strings representing the paths to source files to be traced.", + "items": { + "type": "string", + "minLength": 1, + "description": "A string representing the path to one source file to be traced." + } + } + ] + }, + "configurePresets.trace.redirect@v7..": { + "type": "string", + "description": "An optional string specifying a path to a trace output file." + }, + "buildPresets@v2": { + "type": "array", + "description": "An optional array of build preset objects.", + "items": { + "type": "object", + "description": "A build preset object.", + "unevaluatedProperties": false, + "properties": { + "name": { + "$ref": "#/definitions/buildPresets.name@v2.." + }, + "hidden": { + "$ref": "#/definitions/buildPresets.hidden@v2.." + }, + "inherits": { + "$ref": "#/definitions/buildPresets.inherits@v2.." + }, + "vendor": { + "$ref": "#/definitions/buildPresets.vendor@v2.." + }, + "displayName": { + "$ref": "#/definitions/buildPresets.displayName@v2.." + }, + "description": { + "$ref": "#/definitions/buildPresets.description@v2.." + }, + "environment": { + "$ref": "#/definitions/buildPresets.environment@v2.." + }, + "configurePreset": { + "$ref": "#/definitions/buildPresets.configurePreset@v2.." + }, + "inheritConfigureEnvironment": { + "$ref": "#/definitions/buildPresets.inheritConfigureEnvironment@v2.." + }, + "jobs": { + "$ref": "#/definitions/buildPresets.jobs@v2.." + }, + "targets": { + "$ref": "#/definitions/buildPresets.targets@v2.." + }, + "configuration": { + "$ref": "#/definitions/buildPresets.configuration@v2.." + }, + "cleanFirst": { + "$ref": "#/definitions/buildPresets.cleanFirst@v2.." + }, + "verbose": { + "$ref": "#/definitions/buildPresets.verbose@v2.." + }, + "nativeToolOptions": { + "$ref": "#/definitions/buildPresets.nativeToolOptions@v2.." + } + }, + "required": [ + "name" + ] + } + }, + "buildPresets@v3": { + "type": "array", + "description": "An optional array of build preset objects.", + "items": { + "type": "object", + "description": "A build preset object.", + "unevaluatedProperties": false, + "properties": { + "name": { + "$ref": "#/definitions/buildPresets.name@v2.." + }, + "hidden": { + "$ref": "#/definitions/buildPresets.hidden@v2.." + }, + "inherits": { + "$ref": "#/definitions/buildPresets.inherits@v2.." + }, + "condition": { + "$ref": "#/definitions/buildPresets.condition@v3..v9" + }, + "vendor": { + "$ref": "#/definitions/buildPresets.vendor@v2.." + }, + "displayName": { + "$ref": "#/definitions/buildPresets.displayName@v2.." + }, + "description": { + "$ref": "#/definitions/buildPresets.description@v2.." + }, + "environment": { + "$ref": "#/definitions/buildPresets.environment@v2.." + }, + "configurePreset": { + "$ref": "#/definitions/buildPresets.configurePreset@v2.." + }, + "inheritConfigureEnvironment": { + "$ref": "#/definitions/buildPresets.inheritConfigureEnvironment@v2.." + }, + "jobs": { + "$ref": "#/definitions/buildPresets.jobs@v2.." + }, + "targets": { + "$ref": "#/definitions/buildPresets.targets@v2.." + }, + "configuration": { + "$ref": "#/definitions/buildPresets.configuration@v2.." + }, + "cleanFirst": { + "$ref": "#/definitions/buildPresets.cleanFirst@v2.." + }, + "verbose": { + "$ref": "#/definitions/buildPresets.verbose@v2.." + }, + "nativeToolOptions": { + "$ref": "#/definitions/buildPresets.nativeToolOptions@v2.." + } + }, + "required": [ + "name" + ] + } + }, + "buildPresets@v4..v9": { + "type": "array", + "description": "An optional array of build preset objects.", + "items": { + "type": "object", + "description": "A build preset object.", + "unevaluatedProperties": false, + "properties": { + "name": { + "$ref": "#/definitions/buildPresets.name@v2.." + }, + "hidden": { + "$ref": "#/definitions/buildPresets.hidden@v2.." + }, + "inherits": { + "$ref": "#/definitions/buildPresets.inherits@v2.." + }, + "condition": { + "$ref": "#/definitions/buildPresets.condition@v3..v9" + }, + "vendor": { + "$ref": "#/definitions/buildPresets.vendor@v2.." + }, + "displayName": { + "$ref": "#/definitions/buildPresets.displayName@v2.." + }, + "description": { + "$ref": "#/definitions/buildPresets.description@v2.." + }, + "environment": { + "$ref": "#/definitions/buildPresets.environment@v2.." + }, + "configurePreset": { + "$ref": "#/definitions/buildPresets.configurePreset@v2.." + }, + "inheritConfigureEnvironment": { + "$ref": "#/definitions/buildPresets.inheritConfigureEnvironment@v2.." + }, + "jobs": { + "$ref": "#/definitions/buildPresets.jobs@v2.." + }, + "targets": { + "$ref": "#/definitions/buildPresets.targets@v2.." + }, + "configuration": { + "$ref": "#/definitions/buildPresets.configuration@v2.." + }, + "cleanFirst": { + "$ref": "#/definitions/buildPresets.cleanFirst@v2.." + }, + "resolvePackageReferences": { + "$ref": "#/definitions/buildPresets.resolvePackageReferences@v4.." + }, + "verbose": { + "$ref": "#/definitions/buildPresets.verbose@v2.." + }, + "nativeToolOptions": { + "$ref": "#/definitions/buildPresets.nativeToolOptions@v2.." + } + }, + "required": [ + "name" + ] + } + }, + "buildPresets@v10..": { + "type": "array", + "description": "An optional array of build preset objects.", + "items": { + "type": "object", + "description": "A build preset object.", + "unevaluatedProperties": false, + "properties": { + "name": { + "$ref": "#/definitions/buildPresets.name@v2.." + }, + "hidden": { + "$ref": "#/definitions/buildPresets.hidden@v2.." + }, + "inherits": { + "$ref": "#/definitions/buildPresets.inherits@v2.." + }, + "condition": { + "$ref": "#/definitions/buildPresets.condition@v10.." + }, + "vendor": { + "$ref": "#/definitions/buildPresets.vendor@v2.." + }, + "displayName": { + "$ref": "#/definitions/buildPresets.displayName@v2.." + }, + "description": { + "$ref": "#/definitions/buildPresets.description@v2.." + }, + "environment": { + "$ref": "#/definitions/buildPresets.environment@v2.." + }, + "configurePreset": { + "$ref": "#/definitions/buildPresets.configurePreset@v2.." + }, + "inheritConfigureEnvironment": { + "$ref": "#/definitions/buildPresets.inheritConfigureEnvironment@v2.." + }, + "jobs": { + "$ref": "#/definitions/buildPresets.jobs@v2.." + }, + "targets": { + "$ref": "#/definitions/buildPresets.targets@v2.." + }, + "configuration": { + "$ref": "#/definitions/buildPresets.configuration@v2.." + }, + "cleanFirst": { + "$ref": "#/definitions/buildPresets.cleanFirst@v2.." + }, + "resolvePackageReferences": { + "$ref": "#/definitions/buildPresets.resolvePackageReferences@v4.." + }, + "verbose": { + "$ref": "#/definitions/buildPresets.verbose@v2.." + }, + "nativeToolOptions": { + "$ref": "#/definitions/buildPresets.nativeToolOptions@v2.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + }, + "required": [ + "name" + ] + } + }, + "buildPresets.name@v2..": { + "type": "string", + "minLength": 1, + "description": "A required string representing the machine-friendly name of the preset. This identifier is used in the 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, package, or workflow preset." + }, + "buildPresets.hidden@v2..": { + "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." + }, + "buildPresets.inherits@v2..": { + "anyOf": [ + { + "type": "string", + "minLength": 1, + "description": "An optional string representing the name of the preset from which to inherit." + }, + { + "type": "array", + "description": "An optional array of strings representing the names of presets from which to inherit. 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", + "minLength": 1, + "description": "An optional string representing the name of the preset from which to inherit." + } + } + ] + }, + "buildPresets.condition@v3..v9": { + "anyOf": [ + { + "$ref": "#/definitions/condition@v3..v9" + }, + { + "type": "null", + "description": "Null indicates that the condition always evaluates to true and is not inherited." + } + ] + }, + "buildPresets.condition@v10..": { + "anyOf": [ + { + "$ref": "#/definitions/condition@v10.." + }, + { + "type": "null", + "description": "Null indicates that the condition always evaluates to true and is not inherited." + } + ] + }, + "buildPresets.vendor@v2..": { + "type": "object", + "minLength": 1, + "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": {} + }, + "buildPresets.displayName@v2..": { + "type": "string", + "description": "An optional string with a human-friendly name of the preset." + }, + "buildPresets.description@v2..": { + "type": "string", + "description": "An optional string with a human-friendly description of the preset." + }, + "buildPresets.environment@v2..": { + "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.", + "propertyNames": { + "pattern": "^.+$" + }, + "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." + } + ] + } + }, + "buildPresets.configurePreset@v2..": { + "type": "string", + "minLength": 1, + "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." + }, + "buildPresets.inheritConfigureEnvironment@v2..": { + "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." + }, + "buildPresets.jobs@v2..": { + "type": "integer", + "description": "An optional non-negative integer. Equivalent to passing --parallel or -j on the command line.", + "minimum": 0 + }, + "buildPresets.targets@v2..": { + "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" + } + } + ] + }, + "buildPresets.configuration@v2..": { + "type": "string", + "description": "An optional string. Equivalent to passing --config on the command line." + }, + "buildPresets.cleanFirst@v2..": { + "type": "boolean", + "description": "An optional boolean. If true, equivalent to passing --clean-first on the command line." + }, + "buildPresets.resolvePackageReferences@v4..": { + "type": "string", + "enum": [ + "on", + "off", + "only" + ], + "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)." + }, + "buildPresets.verbose@v2..": { + "type": "boolean", + "description": "An optional boolean. If true, equivalent to passing --verbose on the command line." + }, + "buildPresets.nativeToolOptions@v2..": { + "type": "array", + "description": "An optional array of strings. Equivalent to passing options after -- on the command line.", + "items": { + "type": "string" + } + }, + "testPresets@v2": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest.", + "items": { + "type": "object", + "description": "A test preset object.", + "unevaluatedProperties": false, + "properties": { + "name": { + "$ref": "#/definitions/testPresets.name@v2.." + }, + "hidden": { + "$ref": "#/definitions/testPresets.hidden@v2.." + }, + "inherits": { + "$ref": "#/definitions/testPresets.inherits@v2.." + }, + "vendor": { + "$ref": "#/definitions/testPresets.vendor@v2.." + }, + "displayName": { + "$ref": "#/definitions/testPresets.displayName@v2.." + }, + "description": { + "$ref": "#/definitions/testPresets.description@v2.." + }, + "environment": { + "$ref": "#/definitions/testPresets.environment@v2.." + }, + "configurePreset": { + "$ref": "#/definitions/testPresets.configurePreset@v2.." + }, + "inheritConfigureEnvironment": { + "$ref": "#/definitions/testPresets.inheritConfigureEnvironment@v2.." + }, + "configuration": { + "$ref": "#/definitions/testPresets.configuration@v2.." + }, + "overwriteConfigurationFile": { + "$ref": "#/definitions/testPresets.overwriteConfigurationFile@v2.." + }, + "output": { + "$ref": "#/definitions/testPresets.output@v2..v4" + }, + "filter": { + "$ref": "#/definitions/testPresets.filter@v2..v9" + }, + "execution": { + "$ref": "#/definitions/testPresets.execution@v2..v9" + } + }, + "required": [ + "name" + ] + } + }, + "testPresets@v3..v4": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest.", + "items": { + "type": "object", + "description": "A test preset object.", + "unevaluatedProperties": false, + "properties": { + "name": { + "$ref": "#/definitions/testPresets.name@v2.." + }, + "hidden": { + "$ref": "#/definitions/testPresets.hidden@v2.." + }, + "inherits": { + "$ref": "#/definitions/testPresets.inherits@v2.." + }, + "condition": { + "$ref": "#/definitions/testPresets.condition@v3..v9" + }, + "vendor": { + "$ref": "#/definitions/testPresets.vendor@v2.." + }, + "displayName": { + "$ref": "#/definitions/testPresets.displayName@v2.." + }, + "description": { + "$ref": "#/definitions/testPresets.description@v2.." + }, + "environment": { + "$ref": "#/definitions/testPresets.environment@v2.." + }, + "configurePreset": { + "$ref": "#/definitions/testPresets.configurePreset@v2.." + }, + "inheritConfigureEnvironment": { + "$ref": "#/definitions/testPresets.inheritConfigureEnvironment@v2.." + }, + "configuration": { + "$ref": "#/definitions/testPresets.configuration@v2.." + }, + "overwriteConfigurationFile": { + "$ref": "#/definitions/testPresets.overwriteConfigurationFile@v2.." + }, + "output": { + "$ref": "#/definitions/testPresets.output@v2..v4" + }, + "filter": { + "$ref": "#/definitions/testPresets.filter@v2..v9" + }, + "execution": { + "$ref": "#/definitions/testPresets.execution@v2..v9" + } + }, + "required": [ + "name" + ] + } + }, + "testPresets@v5": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest.", + "items": { + "type": "object", + "description": "A test preset object.", + "unevaluatedProperties": false, + "properties": { + "name": { + "$ref": "#/definitions/testPresets.name@v2.." + }, + "hidden": { + "$ref": "#/definitions/testPresets.hidden@v2.." + }, + "inherits": { + "$ref": "#/definitions/testPresets.inherits@v2.." + }, + "condition": { + "$ref": "#/definitions/testPresets.condition@v3..v9" + }, + "vendor": { + "$ref": "#/definitions/testPresets.vendor@v2.." + }, + "displayName": { + "$ref": "#/definitions/testPresets.displayName@v2.." + }, + "description": { + "$ref": "#/definitions/testPresets.description@v2.." + }, + "environment": { + "$ref": "#/definitions/testPresets.environment@v2.." + }, + "configurePreset": { + "$ref": "#/definitions/testPresets.configurePreset@v2.." + }, + "inheritConfigureEnvironment": { + "$ref": "#/definitions/testPresets.inheritConfigureEnvironment@v2.." + }, + "configuration": { + "$ref": "#/definitions/testPresets.configuration@v2.." + }, + "overwriteConfigurationFile": { + "$ref": "#/definitions/testPresets.overwriteConfigurationFile@v2.." + }, + "output": { + "$ref": "#/definitions/testPresets.output@v5" + }, + "filter": { + "$ref": "#/definitions/testPresets.filter@v2..v9" + }, + "execution": { + "$ref": "#/definitions/testPresets.execution@v2..v9" + } + }, + "required": [ + "name" + ] + } + }, + "testPresets@v6..v9": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest.", + "items": { + "type": "object", + "description": "A test preset object.", + "unevaluatedProperties": false, + "properties": { + "name": { + "$ref": "#/definitions/testPresets.name@v2.." + }, + "hidden": { + "$ref": "#/definitions/testPresets.hidden@v2.." + }, + "inherits": { + "$ref": "#/definitions/testPresets.inherits@v2.." + }, + "condition": { + "$ref": "#/definitions/testPresets.condition@v3..v9" + }, + "vendor": { + "$ref": "#/definitions/testPresets.vendor@v2.." + }, + "displayName": { + "$ref": "#/definitions/testPresets.displayName@v2.." + }, + "description": { + "$ref": "#/definitions/testPresets.description@v2.." + }, + "environment": { + "$ref": "#/definitions/testPresets.environment@v2.." + }, + "configurePreset": { + "$ref": "#/definitions/testPresets.configurePreset@v2.." + }, + "inheritConfigureEnvironment": { + "$ref": "#/definitions/testPresets.inheritConfigureEnvironment@v2.." + }, + "configuration": { + "$ref": "#/definitions/testPresets.configuration@v2.." + }, + "overwriteConfigurationFile": { + "$ref": "#/definitions/testPresets.overwriteConfigurationFile@v2.." + }, + "output": { + "$ref": "#/definitions/testPresets.output@v6..v9" + }, + "filter": { + "$ref": "#/definitions/testPresets.filter@v2..v9" + }, + "execution": { + "$ref": "#/definitions/testPresets.execution@v2..v9" + } + }, + "required": [ + "name" + ] + } + }, + "testPresets@v10": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest.", + "items": { + "type": "object", + "description": "A test preset object.", + "unevaluatedProperties": false, + "properties": { + "name": { + "$ref": "#/definitions/testPresets.name@v2.." + }, + "hidden": { + "$ref": "#/definitions/testPresets.hidden@v2.." + }, + "inherits": { + "$ref": "#/definitions/testPresets.inherits@v2.." + }, + "condition": { + "$ref": "#/definitions/testPresets.condition@v10.." + }, + "vendor": { + "$ref": "#/definitions/testPresets.vendor@v2.." + }, + "displayName": { + "$ref": "#/definitions/testPresets.displayName@v2.." + }, + "description": { + "$ref": "#/definitions/testPresets.description@v2.." + }, + "environment": { + "$ref": "#/definitions/testPresets.environment@v2.." + }, + "configurePreset": { + "$ref": "#/definitions/testPresets.configurePreset@v2.." + }, + "inheritConfigureEnvironment": { + "$ref": "#/definitions/testPresets.inheritConfigureEnvironment@v2.." + }, + "configuration": { + "$ref": "#/definitions/testPresets.configuration@v2.." + }, + "overwriteConfigurationFile": { + "$ref": "#/definitions/testPresets.overwriteConfigurationFile@v2.." + }, + "output": { + "$ref": "#/definitions/testPresets.output@v10.." + }, + "filter": { + "$ref": "#/definitions/testPresets.filter@v10.." + }, + "execution": { + "$ref": "#/definitions/testPresets.execution@v10" + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + }, + "required": [ + "name" + ] + } + }, + "testPresets@v11": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest.", + "items": { + "type": "object", + "description": "A test preset object.", + "unevaluatedProperties": false, + "properties": { + "name": { + "$ref": "#/definitions/testPresets.name@v2.." + }, + "hidden": { + "$ref": "#/definitions/testPresets.hidden@v2.." + }, + "inherits": { + "$ref": "#/definitions/testPresets.inherits@v2.." + }, + "condition": { + "$ref": "#/definitions/testPresets.condition@v10.." + }, + "vendor": { + "$ref": "#/definitions/testPresets.vendor@v2.." + }, + "displayName": { + "$ref": "#/definitions/testPresets.displayName@v2.." + }, + "description": { + "$ref": "#/definitions/testPresets.description@v2.." + }, + "environment": { + "$ref": "#/definitions/testPresets.environment@v2.." + }, + "configurePreset": { + "$ref": "#/definitions/testPresets.configurePreset@v2.." + }, + "inheritConfigureEnvironment": { + "$ref": "#/definitions/testPresets.inheritConfigureEnvironment@v2.." + }, + "configuration": { + "$ref": "#/definitions/testPresets.configuration@v2.." + }, + "overwriteConfigurationFile": { + "$ref": "#/definitions/testPresets.overwriteConfigurationFile@v2.." + }, + "output": { + "$ref": "#/definitions/testPresets.output@v10.." + }, + "filter": { + "$ref": "#/definitions/testPresets.filter@v10.." + }, + "execution": { + "$ref": "#/definitions/testPresets.execution@v11" + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + }, + "required": [ + "name" + ] + } + }, + "testPresets@v12": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest.", + "items": { + "type": "object", + "description": "A test preset object.", + "unevaluatedProperties": false, + "properties": { + "name": { + "$ref": "#/definitions/testPresets.name@v2.." + }, + "hidden": { + "$ref": "#/definitions/testPresets.hidden@v2.." + }, + "inherits": { + "$ref": "#/definitions/testPresets.inherits@v2.." + }, + "condition": { + "$ref": "#/definitions/testPresets.condition@v10.." + }, + "vendor": { + "$ref": "#/definitions/testPresets.vendor@v2.." + }, + "displayName": { + "$ref": "#/definitions/testPresets.displayName@v2.." + }, + "description": { + "$ref": "#/definitions/testPresets.description@v2.." + }, + "environment": { + "$ref": "#/definitions/testPresets.environment@v2.." + }, + "configurePreset": { + "$ref": "#/definitions/testPresets.configurePreset@v2.." + }, + "inheritConfigureEnvironment": { + "$ref": "#/definitions/testPresets.inheritConfigureEnvironment@v2.." + }, + "configuration": { + "$ref": "#/definitions/testPresets.configuration@v2.." + }, + "overwriteConfigurationFile": { + "$ref": "#/definitions/testPresets.overwriteConfigurationFile@v2.." + }, + "output": { + "$ref": "#/definitions/testPresets.output@v10.." + }, + "filter": { + "$ref": "#/definitions/testPresets.filter@v10.." + }, + "execution": { + "$ref": "#/definitions/testPresets.execution@v12" + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + }, + "required": [ + "name" + ] + } + }, + "testPresets.name@v2..": { + "type": "string", + "minLength": 1, + "description": "A required string representing the machine-friendly name of the preset. This identifier is used in the ctest --preset option. There must not be two test presets in the union of CMakePresets.json and CMakeUserPresets.json in the same directory with the same name. However, a test preset may have the same name as a configure, build, package, or workflow preset." + }, + "testPresets.hidden@v2..": { + "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." + }, + "testPresets.inherits@v2..": { + "anyOf": [ + { + "type": "string", + "minLength": 1, + "description": "An optional string representing the name of the preset from which to inherit." + }, + { + "type": "array", + "description": "An optional array of strings representing the names of presets from which to inherit. 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", + "minLength": 1, + "description": "An optional string representing the name of the preset from which to inherit." + } + } + ] + }, + "testPresets.condition@v3..v9": { + "anyOf": [ + { + "$ref": "#/definitions/condition@v3..v9" + }, + { + "type": "null", + "description": "Null indicates that the condition always evaluates to true and is not inherited." + } + ] + }, + "testPresets.condition@v10..": { + "anyOf": [ + { + "$ref": "#/definitions/condition@v10.." + }, + { + "type": "null", + "description": "Null indicates that the condition always evaluates to true and is not inherited." + } + ] + }, + "testPresets.vendor@v2..": { + "type": "object", + "minLength": 1, + "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": {} + }, + "testPresets.displayName@v2..": { + "type": "string", + "description": "An optional string with a human-friendly name of the preset." + }, + "testPresets.description@v2..": { + "type": "string", + "description": "An optional string with a human-friendly description of the preset." + }, + "testPresets.environment@v2..": { + "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.", + "propertyNames": { + "pattern": "^.+$" + }, + "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." + } + ] + } + }, + "testPresets.configurePreset@v2..": { + "type": "string", + "minLength": 1, + "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 directory is inferred from the configure preset." + }, + "testPresets.inheritConfigureEnvironment@v2..": { + "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." + }, + "testPresets.configuration@v2..": { + "type": "string", + "description": "An optional string. Equivalent to passing --build-config on the command line." + }, + "testPresets.overwriteConfigurationFile@v2..": { + "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 option written as a key-value pair in the form \"key=value\"." + } + }, + "testPresets.output@v2..v4": { + "type": "object", + "description": "An optional object specifying output options.", + "unevaluatedProperties": false, + "properties": { + "shortProgress": { + "$ref": "#/definitions/testPresets.output.shortProgress@v2.." + }, + "verbosity": { + "$ref": "#/definitions/testPresets.output.verbosity@v2.." + }, + "debug": { + "$ref": "#/definitions/testPresets.output.debug@v2.." + }, + "outputOnFailure": { + "$ref": "#/definitions/testPresets.output.outputOnFailure@v2.." + }, + "quiet": { + "$ref": "#/definitions/testPresets.output.quiet@v2.." + }, + "outputLogFile": { + "$ref": "#/definitions/testPresets.output.outputLogFile@v2.." + }, + "labelSummary": { + "$ref": "#/definitions/testPresets.output.labelSummary@v2.." + }, + "subprojectSummary": { + "$ref": "#/definitions/testPresets.output.subprojectSummary@v2.." + }, + "maxPassedTestOutputSize": { + "$ref": "#/definitions/testPresets.output.maxPassedTestOutputSize@v2.." + }, + "maxFailedTestOutputSize": { + "$ref": "#/definitions/testPresets.output.maxFailedTestOutputSize@v2.." + }, + "maxTestNameWidth": { + "$ref": "#/definitions/testPresets.output.maxTestNameWidth@v2.." + } + } + }, + "testPresets.output@v5": { + "type": "object", + "description": "An optional object specifying output options.", + "unevaluatedProperties": false, + "properties": { + "shortProgress": { + "$ref": "#/definitions/testPresets.output.shortProgress@v2.." + }, + "verbosity": { + "$ref": "#/definitions/testPresets.output.verbosity@v2.." + }, + "debug": { + "$ref": "#/definitions/testPresets.output.debug@v2.." + }, + "outputOnFailure": { + "$ref": "#/definitions/testPresets.output.outputOnFailure@v2.." + }, + "quiet": { + "$ref": "#/definitions/testPresets.output.quiet@v2.." + }, + "outputLogFile": { + "$ref": "#/definitions/testPresets.output.outputLogFile@v2.." + }, + "labelSummary": { + "$ref": "#/definitions/testPresets.output.labelSummary@v2.." + }, + "subprojectSummary": { + "$ref": "#/definitions/testPresets.output.subprojectSummary@v2.." + }, + "maxPassedTestOutputSize": { + "$ref": "#/definitions/testPresets.output.maxPassedTestOutputSize@v2.." + }, + "maxFailedTestOutputSize": { + "$ref": "#/definitions/testPresets.output.maxFailedTestOutputSize@v2.." + }, + "testOutputTruncation": { + "$ref": "#/definitions/testPresets.output.testOutputTruncation@v5.." + }, + "maxTestNameWidth": { + "$ref": "#/definitions/testPresets.output.maxTestNameWidth@v2.." + } + } + }, + "testPresets.output@v6..v9": { + "type": "object", + "description": "An optional object specifying output options.", + "unevaluatedProperties": false, + "properties": { + "shortProgress": { + "$ref": "#/definitions/testPresets.output.shortProgress@v2.." + }, + "verbosity": { + "$ref": "#/definitions/testPresets.output.verbosity@v2.." + }, + "debug": { + "$ref": "#/definitions/testPresets.output.debug@v2.." + }, + "outputOnFailure": { + "$ref": "#/definitions/testPresets.output.outputOnFailure@v2.." + }, + "quiet": { + "$ref": "#/definitions/testPresets.output.quiet@v2.." + }, + "outputLogFile": { + "$ref": "#/definitions/testPresets.output.outputLogFile@v2.." + }, + "outputJUnitFile": { + "$ref": "#/definitions/testPresets.output.outputJUnitFile@v6.." + }, + "labelSummary": { + "$ref": "#/definitions/testPresets.output.labelSummary@v2.." + }, + "subprojectSummary": { + "$ref": "#/definitions/testPresets.output.subprojectSummary@v2.." + }, + "maxPassedTestOutputSize": { + "$ref": "#/definitions/testPresets.output.maxPassedTestOutputSize@v2.." + }, + "maxFailedTestOutputSize": { + "$ref": "#/definitions/testPresets.output.maxFailedTestOutputSize@v2.." + }, + "testOutputTruncation": { + "$ref": "#/definitions/testPresets.output.testOutputTruncation@v5.." + }, + "maxTestNameWidth": { + "$ref": "#/definitions/testPresets.output.maxTestNameWidth@v2.." + } + } + }, + "testPresets.output@v10..": { + "type": "object", + "description": "An optional object specifying output options.", + "unevaluatedProperties": false, + "properties": { + "shortProgress": { + "$ref": "#/definitions/testPresets.output.shortProgress@v2.." + }, + "verbosity": { + "$ref": "#/definitions/testPresets.output.verbosity@v2.." + }, + "debug": { + "$ref": "#/definitions/testPresets.output.debug@v2.." + }, + "outputOnFailure": { + "$ref": "#/definitions/testPresets.output.outputOnFailure@v2.." + }, + "quiet": { + "$ref": "#/definitions/testPresets.output.quiet@v2.." + }, + "outputLogFile": { + "$ref": "#/definitions/testPresets.output.outputLogFile@v2.." + }, + "outputJUnitFile": { + "$ref": "#/definitions/testPresets.output.outputJUnitFile@v6.." + }, + "labelSummary": { + "$ref": "#/definitions/testPresets.output.labelSummary@v2.." + }, + "subprojectSummary": { + "$ref": "#/definitions/testPresets.output.subprojectSummary@v2.." + }, + "maxPassedTestOutputSize": { + "$ref": "#/definitions/testPresets.output.maxPassedTestOutputSize@v2.." + }, + "maxFailedTestOutputSize": { + "$ref": "#/definitions/testPresets.output.maxFailedTestOutputSize@v2.." + }, + "testOutputTruncation": { + "$ref": "#/definitions/testPresets.output.testOutputTruncation@v5.." + }, + "maxTestNameWidth": { + "$ref": "#/definitions/testPresets.output.maxTestNameWidth@v2.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + } + }, + "testPresets.output.shortProgress@v2..": { + "type": "boolean", + "description": "An optional boolean. If true, equivalent to passing --progress on the command line." + }, + "testPresets.output.verbosity@v2..": { + "type": "string", + "enum": [ + "default", + "verbose", + "extra" + ], + "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)." + }, + "testPresets.output.debug@v2..": { + "type": "boolean", + "description": "An optional boolean. If true, equivalent to passing --debug on the command line." + }, + "testPresets.output.outputOnFailure@v2..": { + "type": "boolean", + "description": "An optional boolean. If true, equivalent to passing --output-on-failure on the command line." + }, + "testPresets.output.quiet@v2..": { + "type": "boolean", + "description": "An optional boolean. If true, equivalent to passing --quiet on the command line." + }, + "testPresets.output.outputLogFile@v2..": { + "type": "string", + "description": "An optional string specifying a path to a log file. Equivalent to passing --output-log on the command line." + }, + "testPresets.output.outputJUnitFile@v6..": { + "type": "string", + "description": "An optional string specifying a path to a JUnit file. Equivalent to passing --output-junit on the command line." + }, + "testPresets.output.labelSummary@v2..": { + "type": "boolean", + "description": "An optional boolean. If false, equivalent to passing --no-label-summary on the command line." + }, + "testPresets.output.subprojectSummary@v2..": { + "type": "boolean", + "description": "An optional boolean. If false, equivalent to passing --no-subproject-summary on the command line." + }, + "testPresets.output.maxPassedTestOutputSize@v2..": { + "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." + }, + "testPresets.output.maxFailedTestOutputSize@v2..": { + "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." + }, + "testPresets.output.testOutputTruncation@v5..": { + "type": "string", + "enum": [ + "tail", + "middle", + "head" + ], + "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\"." + }, + "testPresets.output.maxTestNameWidth@v2..": { + "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." + }, + "testPresets.filter@v2..v9": { + "type": "object", + "description": "An optional object specifying how to filter the tests to run.", + "properties": { + "include": { + "$ref": "#/definitions/testPresets.filter.include@v2..v9" + }, + "exclude": { + "$ref": "#/definitions/testPresets.filter.exclude@v2..v9" + } + } + }, + "testPresets.filter@v10..": { + "type": "object", + "description": "An optional object specifying how to filter the tests to run.", + "properties": { + "include": { + "$ref": "#/definitions/testPresets.filter.include@v10.." + }, + "exclude": { + "$ref": "#/definitions/testPresets.filter.exclude@v10.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + } + }, + "testPresets.filter.include@v2..v9": { + "type": "object", + "description": "An optional object specifying which tests to include.", + "properties": { + "name": { + "$ref": "#/definitions/testPresets.filter.include.name@v2.." + }, + "label": { + "$ref": "#/definitions/testPresets.filter.include.label@v2.." + }, + "useUnion": { + "$ref": "#/definitions/testPresets.filter.include.useUnion@v2.." + }, + "index": { + "$ref": "#/definitions/testPresets.filter.include.index@v2..v9" + } + } + }, + "testPresets.filter.include@v10..": { + "type": "object", + "description": "An optional object specifying which tests to include.", + "properties": { + "name": { + "$ref": "#/definitions/testPresets.filter.include.name@v2.." + }, + "label": { + "$ref": "#/definitions/testPresets.filter.include.label@v2.." + }, + "useUnion": { + "$ref": "#/definitions/testPresets.filter.include.useUnion@v2.." + }, + "index": { + "$ref": "#/definitions/testPresets.filter.include.index@v10.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + } + }, + "testPresets.filter.include.name@v2..": { + "type": "string", + "description": "An optional string specifying a regex for test names. Equivalent to passing --tests-regex on the command line." + }, + "testPresets.filter.include.label@v2..": { + "type": "string", + "description": "An optional string specifying a regex for test labels. Equivalent to passing --label-regex on the command line." + }, + "testPresets.filter.include.useUnion@v2..": { + "type": "boolean", + "description": "An optional boolean. Equivalent to passing --union on the command line." + }, + "testPresets.filter.include.index@v2..v9": { + "anyOf": [ + { + "type": "string", + "description": "An optional string specifying a file with the command line syntax for --tests-information. Available in version 2 and higher." + }, + { + "type": "object", + "description": "An optional object specifying test preset filters. Available in version 2 and higher.", + "unevaluatedProperties": false, + "properties": { + "start": { + "$ref": "#/definitions/testPresets.filter.include.index.start@v2.." + }, + "end": { + "$ref": "#/definitions/testPresets.filter.include.index.end@v2.." + }, + "stride": { + "$ref": "#/definitions/testPresets.filter.include.index.stride@v2.." + }, + "specificTests": { + "$ref": "#/definitions/testPresets.filter.include.index.specificTests@v2.." + } + } + } + ] + }, + "testPresets.filter.include.index@v10..": { + "anyOf": [ + { + "type": "string", + "description": "An optional string specifying a file with the command line syntax for --tests-information. Available in version 2 and higher." + }, + { + "type": "object", + "description": "An optional object specifying test preset filters. Available in version 2 and higher.", + "unevaluatedProperties": false, + "properties": { + "start": { + "$ref": "#/definitions/testPresets.filter.include.index.start@v2.." + }, + "end": { + "$ref": "#/definitions/testPresets.filter.include.index.end@v2.." + }, + "stride": { + "$ref": "#/definitions/testPresets.filter.include.index.stride@v2.." + }, + "specificTests": { + "$ref": "#/definitions/testPresets.filter.include.index.specificTests@v2.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + } + } + ] + }, + "testPresets.filter.include.index.start@v2..": { + "type": "integer", + "description": "An optional integer specifying a test index at which to start testing." + }, + "testPresets.filter.include.index.end@v2..": { + "type": "integer", + "description": "An optional integer specifying a test index at which to stop testing." + }, + "testPresets.filter.include.index.stride@v2..": { + "type": "integer", + "description": "An optional integer specifying the increment." + }, + "testPresets.filter.include.index.specificTests@v2..": { + "type": "array", + "description": "An optional array of integers specifying specific test indices to run.", + "items": { + "type": "integer", + "description": "An integer specifying the test to run by index." + } + }, + "testPresets.filter.exclude@v2..v9": { + "type": "object", + "description": "An optional object specifying which tests to exclude.", + "properties": { + "name": { + "$ref": "#/definitions/testPresets.filter.exclude.name@v2.." + }, + "label": { + "$ref": "#/definitions/testPresets.filter.exclude.label@v2.." + }, + "fixtures": { + "$ref": "#/definitions/testPresets.filter.exclude.fixtures@v2..v9" + } + } + }, + "testPresets.filter.exclude@v10..": { + "type": "object", + "description": "An optional object specifying which tests to exclude.", + "properties": { + "name": { + "$ref": "#/definitions/testPresets.filter.exclude.name@v2.." + }, + "label": { + "$ref": "#/definitions/testPresets.filter.exclude.label@v2.." + }, + "fixtures": { + "$ref": "#/definitions/testPresets.filter.exclude.fixtures@v10.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + } + }, + "testPresets.filter.exclude.name@v2..": { + "type": "string", + "description": "An optional string specifying a regex for test names. Equivalent to passing --exclude-regex on the command line." + }, + "testPresets.filter.exclude.label@v2..": { + "type": "string", + "description": "An optional string specifying a regex for test labels. Equivalent to passing --label-exclude on the command line." + }, + "testPresets.filter.exclude.fixtures@v2..v9": { + "type": "object", + "description": "An optional object specifying which fixtures to exclude from adding tests.", + "properties": { + "any": { + "$ref": "#/definitions/testPresets.filter.exclude.fixtures.any@v2.." + }, + "setup": { + "$ref": "#/definitions/testPresets.filter.exclude.fixtures.setup@v2.." + }, + "cleanup": { + "$ref": "#/definitions/testPresets.filter.exclude.fixtures.cleanup@v2.." + } + } + }, + "testPresets.filter.exclude.fixtures@v10..": { + "type": "object", + "description": "An optional object specifying which fixtures to exclude from adding tests.", + "properties": { + "any": { + "$ref": "#/definitions/testPresets.filter.exclude.fixtures.any@v2.." + }, + "setup": { + "$ref": "#/definitions/testPresets.filter.exclude.fixtures.setup@v2.." + }, + "cleanup": { + "$ref": "#/definitions/testPresets.filter.exclude.fixtures.cleanup@v2.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + } + }, + "testPresets.filter.exclude.fixtures.any@v2..": { + "type": "string", + "description": "An optional string specifying a regex for text fixtures to exclude from adding any tests. Equivalent to passing --fixture-exclude-any on the command line." + }, + "testPresets.filter.exclude.fixtures.setup@v2..": { + "type": "string", + "description": "An optional string specifying a regex for text fixtures to exclude from adding setup tests. Equivalent to passing --fixture-exclude-setup on the command line." + }, + "testPresets.filter.exclude.fixtures.cleanup@v2..": { + "type": "string", + "description": "An optional string specifying a regex for text fixtures to exclude from adding cleanup tests. Equivalent to passing --fixture-exclude-cleanup on the command line." + }, + "testPresets.execution@v2..v9": { + "type": "object", + "description": "An optional object specifying options for test execution.", + "unevaluatedProperties": false, + "properties": { + "stopOnFailure": { + "$ref": "#/definitions/testPresets.execution.stopOnFailure@v2.." + }, + "enableFailover": { + "$ref": "#/definitions/testPresets.execution.enableFailover@v2.." + }, + "jobs": { + "$ref": "#/definitions/testPresets.execution.jobs@v2..v10" + }, + "resourceSpecFile": { + "$ref": "#/definitions/testPresets.execution.resourceSpecFile@v2.." + }, + "testLoad": { + "$ref": "#/definitions/testPresets.execution.testLoad@v2.." + }, + "showOnly": { + "$ref": "#/definitions/testPresets.execution.showOnly@v2.." + }, + "repeat": { + "$ref": "#/definitions/testPresets.execution.repeat@v2..v9" + }, + "interactiveDebugging": { + "$ref": "#/definitions/testPresets.execution.interactiveDebugging@v2.." + }, + "scheduleRandom": { + "$ref": "#/definitions/testPresets.execution.scheduleRandom@v2.." + }, + "timeout": { + "$ref": "#/definitions/testPresets.execution.timeout@v2.." + }, + "noTestsAction": { + "$ref": "#/definitions/testPresets.execution.noTestsAction@v2.." + } + } + }, + "testPresets.execution@v10": { + "type": "object", + "description": "An optional object specifying options for test execution.", + "unevaluatedProperties": false, + "properties": { + "stopOnFailure": { + "$ref": "#/definitions/testPresets.execution.stopOnFailure@v2.." + }, + "enableFailover": { + "$ref": "#/definitions/testPresets.execution.enableFailover@v2.." + }, + "jobs": { + "$ref": "#/definitions/testPresets.execution.jobs@v2..v10" + }, + "resourceSpecFile": { + "$ref": "#/definitions/testPresets.execution.resourceSpecFile@v2.." + }, + "testLoad": { + "$ref": "#/definitions/testPresets.execution.testLoad@v2.." + }, + "showOnly": { + "$ref": "#/definitions/testPresets.execution.showOnly@v2.." + }, + "repeat": { + "$ref": "#/definitions/testPresets.execution.repeat@v10.." + }, + "interactiveDebugging": { + "$ref": "#/definitions/testPresets.execution.interactiveDebugging@v2.." + }, + "scheduleRandom": { + "$ref": "#/definitions/testPresets.execution.scheduleRandom@v2.." + }, + "timeout": { + "$ref": "#/definitions/testPresets.execution.timeout@v2.." + }, + "noTestsAction": { + "$ref": "#/definitions/testPresets.execution.noTestsAction@v2.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + } + }, + "testPresets.execution@v11": { + "type": "object", + "description": "An optional object specifying options for test execution.", + "unevaluatedProperties": false, + "properties": { + "stopOnFailure": { + "$ref": "#/definitions/testPresets.execution.stopOnFailure@v2.." + }, + "enableFailover": { + "$ref": "#/definitions/testPresets.execution.enableFailover@v2.." + }, + "jobs": { + "$ref": "#/definitions/testPresets.execution.jobs@v11.." + }, + "resourceSpecFile": { + "$ref": "#/definitions/testPresets.execution.resourceSpecFile@v2.." + }, + "testLoad": { + "$ref": "#/definitions/testPresets.execution.testLoad@v2.." + }, + "showOnly": { + "$ref": "#/definitions/testPresets.execution.showOnly@v2.." + }, + "repeat": { + "$ref": "#/definitions/testPresets.execution.repeat@v10.." + }, + "interactiveDebugging": { + "$ref": "#/definitions/testPresets.execution.interactiveDebugging@v2.." + }, + "scheduleRandom": { + "$ref": "#/definitions/testPresets.execution.scheduleRandom@v2.." + }, + "timeout": { + "$ref": "#/definitions/testPresets.execution.timeout@v2.." + }, + "noTestsAction": { + "$ref": "#/definitions/testPresets.execution.noTestsAction@v2.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + } + }, + "testPresets.execution@v12": { + "type": "object", + "description": "An optional object specifying options for test execution.", + "unevaluatedProperties": false, + "properties": { + "stopOnFailure": { + "$ref": "#/definitions/testPresets.execution.stopOnFailure@v2.." + }, + "enableFailover": { + "$ref": "#/definitions/testPresets.execution.enableFailover@v2.." + }, + "jobs": { + "$ref": "#/definitions/testPresets.execution.jobs@v11.." + }, + "resourceSpecFile": { + "$ref": "#/definitions/testPresets.execution.resourceSpecFile@v2.." + }, + "testLoad": { + "$ref": "#/definitions/testPresets.execution.testLoad@v2.." + }, + "showOnly": { + "$ref": "#/definitions/testPresets.execution.showOnly@v2.." + }, + "repeat": { + "$ref": "#/definitions/testPresets.execution.repeat@v10.." + }, + "interactiveDebugging": { + "$ref": "#/definitions/testPresets.execution.interactiveDebugging@v2.." + }, + "scheduleRandom": { + "$ref": "#/definitions/testPresets.execution.scheduleRandom@v2.." + }, + "timeout": { + "$ref": "#/definitions/testPresets.execution.timeout@v2.." + }, + "noTestsAction": { + "$ref": "#/definitions/testPresets.execution.noTestsAction@v2.." + }, + "testPassthroughArguments": { + "$ref": "#/definitions/testPresets.execution.testPassthroughArguments@v12" + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + } + }, + "testPresets.execution.stopOnFailure@v2..": { + "type": "boolean", + "description": "An optional boolean. If true, equivalent to passing --stop-on-failure on the command line." + }, + "testPresets.execution.enableFailover@v2..": { + "type": "boolean", + "description": "An optional boolean. If true, equivalent to passing -F on the command line." + }, + "testPresets.execution.jobs@v2..v10": { + "minimum": 0, + "type": "integer", + "description": "An optional non-negative integer. Equivalent to passing --parallel or -j on the command line." + }, + "testPresets.execution.jobs@v11..": { + "anyOf": [ + { + "type": "integer", + "minimum": 0, + "description": "An optional non-negative integer. Equivalent to passing --parallel or -j on the command line." + }, + { + "type": "string", + "minLength": 0, + "maxLength": 0, + "description": "An optional string. Equivalent to passing --parallel or -j on the command line with the number of jobs omitted." + } + ] + }, + "testPresets.execution.resourceSpecFile@v2..": { + "type": "string", + "description": "An optional string. Equivalent to passing --resource-spec-file on the command line." + }, + "testPresets.execution.testLoad@v2..": { + "type": "integer", + "description": "An optional integer. Equivalent to passing --test-load on the command line." + }, + "testPresets.execution.showOnly@v2..": { + "type": "string", + "enum": [ + "human", + "json-v1" + ], + "description": "An optional string. Equivalent to passing --show-only on the command line. Value must be \"human\" or \"json-v1\"." + }, + "testPresets.execution.repeat@v2..v9": { + "type": "object", + "description": "An optional object specifying how to repeat tests. Equivalent to passing --repeat on the command line.", + "unevaluatedProperties": false, + "properties": { + "mode": { + "$ref": "#/definitions/testPresets.execution.repeat.mode@v2.." + }, + "count": { + "$ref": "#/definitions/testPresets.execution.repeat.count@v2.." + } + }, + "required": [ + "mode", + "count" + ] + }, + "testPresets.execution.repeat@v10..": { + "type": "object", + "description": "An optional object specifying how to repeat tests. Equivalent to passing --repeat on the command line.", + "unevaluatedProperties": false, + "properties": { + "mode": { + "$ref": "#/definitions/testPresets.execution.repeat.mode@v2.." + }, + "count": { + "$ref": "#/definitions/testPresets.execution.repeat.count@v2.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + }, + "required": [ + "mode", + "count" + ] + }, + "testPresets.execution.repeat.mode@v2..": { + "type": "string", + "enum": [ + "until-fail", + "until-pass", + "after-timeout" + ], + "description": "A required string. Must be one of the following values: \"until-fail\", \"until-pass\", or \"after-timeout\"." + }, + "testPresets.execution.repeat.count@v2..": { + "type": "integer", + "description": "A required integer." + }, + "testPresets.execution.interactiveDebugging@v2..": { + "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." + }, + "testPresets.execution.scheduleRandom@v2..": { + "type": "boolean", + "description": "An optional boolean. If true, equivalent to passing --schedule-random on the command line." + }, + "testPresets.execution.timeout@v2..": { + "type": "integer", + "description": "An optional integer. Equivalent to passing --timeout on the command line." + }, + "testPresets.execution.noTestsAction@v2..": { + "type": "string", + "enum": [ + "default", + "error", + "ignore" + ], + "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)." + }, + "testPresets.execution.testPassthroughArguments@v12": { + "type": "array", + "description": "An optional array of strings. Each element is forwarded as an argument to every test executable. Equivalent to passing arguments after -- on the ctest command line.", + "items": { + "type": "string" + } + }, + "packagePresets@v6..v9": { + "type": "array", + "description": "An optional array of package preset objects. Used to specify arguments to cpack.", + "items": { + "type": "object", + "description": "A package preset object.", + "unevaluatedProperties": false, + "properties": { + "name": { + "$ref": "#/definitions/packagePresets.name@v6.." + }, + "hidden": { + "$ref": "#/definitions/packagePresets.hidden@v6.." + }, + "inherits": { + "$ref": "#/definitions/packagePresets.inherits@v6.." + }, + "condition": { + "$ref": "#/definitions/packagePresets.condition@v6..v9" + }, + "vendor": { + "$ref": "#/definitions/packagePresets.vendor@v6.." + }, + "displayName": { + "$ref": "#/definitions/packagePresets.displayName@v6.." + }, + "description": { + "$ref": "#/definitions/packagePresets.description@v6.." + }, + "environment": { + "$ref": "#/definitions/packagePresets.environment@v6.." + }, + "configurePreset": { + "$ref": "#/definitions/packagePresets.configurePreset@v6.." + }, + "inheritConfigureEnvironment": { + "$ref": "#/definitions/packagePresets.inheritConfigureEnvironment@v6.." + }, + "generators": { + "$ref": "#/definitions/packagePresets.generators@v6.." + }, + "configurations": { + "$ref": "#/definitions/packagePresets.configurations@v6.." + }, + "variables": { + "$ref": "#/definitions/packagePresets.variables@v6.." + }, + "configFile": { + "$ref": "#/definitions/packagePresets.configFile@v6.." + }, + "output": { + "$ref": "#/definitions/packagePresets.output@v6..v9" + }, + "packageName": { + "$ref": "#/definitions/packagePresets.packageName@v6.." + }, + "packageVersion": { + "$ref": "#/definitions/packagePresets.packageVersion@v6.." + }, + "packageDirectory": { + "$ref": "#/definitions/packagePresets.packageDirectory@v6.." + }, + "vendorName": { + "$ref": "#/definitions/packagePresets.vendorName@v6.." + } + }, + "required": [ + "name" + ] + } + }, + "packagePresets@v10..": { + "type": "array", + "description": "An optional array of package preset objects. Used to specify arguments to cpack.", + "items": { + "type": "object", + "description": "A package preset object.", + "unevaluatedProperties": false, + "properties": { + "name": { + "$ref": "#/definitions/packagePresets.name@v6.." + }, + "hidden": { + "$ref": "#/definitions/packagePresets.hidden@v6.." + }, + "inherits": { + "$ref": "#/definitions/packagePresets.inherits@v6.." + }, + "condition": { + "$ref": "#/definitions/packagePresets.condition@v10.." + }, + "vendor": { + "$ref": "#/definitions/packagePresets.vendor@v6.." + }, + "displayName": { + "$ref": "#/definitions/packagePresets.displayName@v6.." + }, + "description": { + "$ref": "#/definitions/packagePresets.description@v6.." + }, + "environment": { + "$ref": "#/definitions/packagePresets.environment@v6.." + }, + "configurePreset": { + "$ref": "#/definitions/packagePresets.configurePreset@v6.." + }, + "inheritConfigureEnvironment": { + "$ref": "#/definitions/packagePresets.inheritConfigureEnvironment@v6.." + }, + "generators": { + "$ref": "#/definitions/packagePresets.generators@v6.." + }, + "configurations": { + "$ref": "#/definitions/packagePresets.configurations@v6.." + }, + "variables": { + "$ref": "#/definitions/packagePresets.variables@v6.." + }, + "configFile": { + "$ref": "#/definitions/packagePresets.configFile@v6.." + }, + "output": { + "$ref": "#/definitions/packagePresets.output@v10.." + }, + "packageName": { + "$ref": "#/definitions/packagePresets.packageName@v6.." + }, + "packageVersion": { + "$ref": "#/definitions/packagePresets.packageVersion@v6.." + }, + "packageDirectory": { + "$ref": "#/definitions/packagePresets.packageDirectory@v6.." + }, + "vendorName": { + "$ref": "#/definitions/packagePresets.vendorName@v6.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + }, + "required": [ + "name" + ] + } + }, + "packagePresets.name@v6..": { + "type": "string", + "minLength": 1, + "description": "A required string representing the machine-friendly name of the preset. This identifier is used in the cpack --preset option. There must not be two package presets in the union of CMakePresets.json and CMakeUserPresets.json in the same directory with the same name. However, a package preset may have the same name as a configure, build, test, or workflow preset." + }, + "packagePresets.hidden@v6..": { + "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." + }, + "packagePresets.inherits@v6..": { + "anyOf": [ + { + "type": "string", + "minLength": 1, + "description": "An optional string representing the name of the preset from which to inherit." + }, + { + "type": "array", + "description": "An optional array of strings representing the names of presets from which to inherit. 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", + "minLength": 1, + "description": "An optional string representing the name of the preset from which to inherit." + } + } + ] + }, + "packagePresets.condition@v6..v9": { + "anyOf": [ + { + "$ref": "#/definitions/condition@v3..v9" + }, + { + "type": "null", + "description": "Null indicates that the condition always evaluates to true and is not inherited." + } + ] + }, + "packagePresets.condition@v10..": { + "anyOf": [ + { + "$ref": "#/definitions/condition@v10.." + }, + { + "type": "null", + "description": "Null indicates that the condition always evaluates to true and is not inherited." + } + ] + }, + "packagePresets.vendor@v6..": { + "type": "object", + "minLength": 1, + "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": {} + }, + "packagePresets.displayName@v6..": { + "type": "string", + "description": "An optional string with a human-friendly name of the preset." + }, + "packagePresets.description@v6..": { + "type": "string", + "description": "An optional string with a human-friendly description of the preset." + }, + "packagePresets.environment@v6..": { + "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.", + "propertyNames": { + "pattern": "^.+$" + }, + "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." + } + ] + } + }, + "packagePresets.configurePreset@v6..": { + "type": "string", + "minLength": 1, + "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." + }, + "packagePresets.inheritConfigureEnvironment@v6..": { + "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." + }, + "packagePresets.generators@v6..": { + "type": "array", + "description": "An optional array of strings representing generators for CPack to use.", + "items": { + "type": "string", + "description": "An optional string representing the name of a CPack generator to use." + } + }, + "packagePresets.configurations@v6..": { + "type": "array", + "description": "An optional array of strings representing build configurations for CPack to package.", + "items": { + "type": "string", + "description": "An optional string representing the name of a configuration to package." + } + }, + "packagePresets.variables@v6..": { + "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.", + "propertyNames": { + "pattern": "^.+$" + }, + "properties": {}, + "additionalProperties": { + "type": "string", + "description": "An optional string representing the value of the variable." + } + }, + "packagePresets.configFile@v6..": { + "type": "string", + "description": "An optional string representing the config file for CPack to use." + }, + "packagePresets.output@v6..v9": { + "type": "object", + "description": "An optional object specifying output options.", + "unevaluatedProperties": false, + "properties": { + "debug": { + "$ref": "#/definitions/packagePresets.output.debug@v6.." + }, + "verbose": { + "$ref": "#/definitions/packagePresets.output.verbose@v6.." + } + } + }, + "packagePresets.output@v10..": { + "type": "object", + "description": "An optional object specifying output options.", + "unevaluatedProperties": false, + "properties": { + "debug": { + "$ref": "#/definitions/packagePresets.output.debug@v6.." + }, + "verbose": { + "$ref": "#/definitions/packagePresets.output.verbose@v6.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + } + }, + "packagePresets.output.debug@v6..": { + "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." + }, + "packagePresets.output.verbose@v6..": { + "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." + }, + "packagePresets.packageName@v6..": { + "type": "string", + "description": "An optional string representing the package name." + }, + "packagePresets.packageVersion@v6..": { + "type": "string", + "description": "An optional string representing the package version." + }, + "packagePresets.packageDirectory@v6..": { + "type": "string", + "description": "An optional string representing the directory in which to place the package." + }, + "packagePresets.vendorName@v6..": { + "type": "string", + "description": "An optional string representing the vendor name." + }, + "workflowPresets@v6..v9": { + "type": "array", + "description": "An optional array of workflow preset objects. Used to execute configure, build, test, and package presets in order.", + "items": { + "type": "object", + "description": "A workflow preset object.", + "unevaluatedProperties": false, + "properties": { + "name": { + "$ref": "#/definitions/workflowPresets.name@v6.." + }, + "vendor": { + "$ref": "#/definitions/workflowPresets.vendor@v6.." + }, + "displayName": { + "$ref": "#/definitions/workflowPresets.displayName@v6.." + }, + "description": { + "$ref": "#/definitions/workflowPresets.description@v6.." + }, + "steps": { + "$ref": "#/definitions/workflowPresets.steps@v6..v9" + } + }, + "required": [ + "name", + "steps" + ] + } + }, + "workflowPresets@v10..": { + "type": "array", + "description": "An optional array of workflow preset objects. Used to execute configure, build, test, and package presets in order.", + "items": { + "type": "object", + "description": "A workflow preset object.", + "unevaluatedProperties": false, + "properties": { + "name": { + "$ref": "#/definitions/workflowPresets.name@v6.." + }, + "vendor": { + "$ref": "#/definitions/workflowPresets.vendor@v6.." + }, + "displayName": { + "$ref": "#/definitions/workflowPresets.displayName@v6.." + }, + "description": { + "$ref": "#/definitions/workflowPresets.description@v6.." + }, + "steps": { + "$ref": "#/definitions/workflowPresets.steps@v10.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + }, + "required": [ + "name", + "steps" + ] + } + }, + "workflowPresets.name@v6..": { + "type": "string", + "minLength": 1, + "description": "A required string representing the machine-friendly name of the preset. This identifier is used in the cmake --workflow --preset option. 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. However, a workflow preset may have the same name as a configure, build, test, or package preset." + }, + "workflowPresets.vendor@v6..": { + "type": "object", + "minLength": 1, + "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": {} + }, + "workflowPresets.displayName@v6..": { + "type": "string", + "description": "An optional string with a human-friendly name of the preset." + }, + "workflowPresets.description@v6..": { + "type": "string", + "description": "An optional string with a human-friendly description of the preset." + }, + "workflowPresets.steps@v6..v9": { + "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", + "unevaluatedProperties": false, + "properties": { + "type": { + "$ref": "#/definitions/workflowPresets.steps.type@v6.." + }, + "name": { + "$ref": "#/definitions/workflowPresets.steps.name@v6.." + } + } + } + }, + "workflowPresets.steps@v10..": { + "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", + "unevaluatedProperties": false, + "properties": { + "type": { + "$ref": "#/definitions/workflowPresets.steps.type@v6.." + }, + "name": { + "$ref": "#/definitions/workflowPresets.steps.name@v6.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + } + } + }, + "workflowPresets.steps.type@v6..": { + "type": "string", + "enum": [ + "configure", + "build", + "test", + "package" + ], + "description": "A required string. The first step must be configure. Subsequent steps must be either build, test, or package." + }, + "workflowPresets.steps.name@v6..": { + "type": "string", + "minLength": 1, + "description": "A required string representing the name of the configure, build, test, or package preset to run as this workflow step." + }, + "condition[1].type@v3..": { + "type": "string", + "const": "const", + "description": "A required string specifying the type of the condition." + }, + "condition[1].value@v3..": { + "type": "boolean", + "description": "A required boolean which provides a constant value for the condition's evaluation." + }, + "condition[2].type@v3..": { + "type": "string", + "enum": [ + "equals", + "notEquals" + ], + "description": "A required string specifying the type of the condition." + }, + "condition[2].lhs@v3..": { + "type": "string", + "description": "First string to compare. This field supports macro expansion." + }, + "condition[2].rhs@v3..": { + "type": "string", + "description": "Second string to compare. This field supports macro expansion." + }, + "condition[3].type@v3..": { + "type": "string", + "enum": [ + "inList", + "notInList" + ], + "description": "A required string specifying the type of the condition." + }, + "condition[3].string@v3..": { + "type": "string", + "description": "A required string to search for. This field supports macro expansion." + }, + "condition[3].list@v3..": { + "type": "array", + "description": "A required array of strings to search. This field supports macro expansion, and uses short-circuit evaluation.", + "items": { + "type": "string" + } + }, + "condition[4].type@v3..": { + "type": "string", + "enum": [ + "matches", + "notMatches" + ], + "description": "A required string specifying the type of the condition." + }, + "condition[4].string@v3..": { + "type": "string", + "description": "A required string to search. This field supports macro expansion." + }, + "condition[4].regex@v3..": { + "type": "string", + "description": "A required regular expression to search for. This field supports macro expansion." + }, + "condition[5].type@v3..": { + "type": "string", + "enum": [ + "anyOf", + "allOf" + ], + "description": "A required string specifying the type of the condition." + }, + "condition[5].conditions@v3..v9": { + "type": "array", + "description": "A required array of condition objects. These conditions use short-circuit evaluation.", + "items": { + "$ref": "#/definitions/condition@v3..v9" + } + }, + "condition[5].conditions@v10..": { + "type": "array", + "description": "A required array of condition objects. These conditions use short-circuit evaluation.", + "items": { + "$ref": "#/definitions/condition@v10.." + } + }, + "condition[6].type@v3..": { + "type": "string", + "const": "not", + "description": "A required string specifying the type of the condition." + }, + "condition[6].condition@v3..v9": { + "$ref": "#/definitions/condition@v3..v9" + }, + "condition[6].condition@v10..": { + "$ref": "#/definitions/condition@v10.." + }, + "condition@v3..v9": { + "anyOf": [ + { + "type": "boolean", + "description": "A boolean which provides a constant value for the condition's evaluation." + }, + { + "type": "object", + "unevaluatedProperties": false, + "properties": { + "type": { + "$ref": "#/definitions/condition[1].type@v3.." + }, + "value": { + "$ref": "#/definitions/condition[1].value@v3.." + } + }, + "required": [ + "type", + "value" + ] + }, + { + "type": "object", + "unevaluatedProperties": false, + "properties": { + "type": { + "$ref": "#/definitions/condition[2].type@v3.." + }, + "lhs": { + "$ref": "#/definitions/condition[2].lhs@v3.." + }, + "rhs": { + "$ref": "#/definitions/condition[2].rhs@v3.." + } + }, + "required": [ + "type", + "lhs", + "rhs" + ] + }, + { + "type": "object", + "unevaluatedProperties": false, + "properties": { + "type": { + "$ref": "#/definitions/condition[3].type@v3.." + }, + "string": { + "$ref": "#/definitions/condition[3].string@v3.." + }, + "list": { + "$ref": "#/definitions/condition[3].list@v3.." + } + }, + "required": [ + "type", + "string", + "list" + ] + }, + { + "type": "object", + "unevaluatedProperties": false, + "properties": { + "type": { + "$ref": "#/definitions/condition[4].type@v3.." + }, + "string": { + "$ref": "#/definitions/condition[4].string@v3.." + }, + "regex": { + "$ref": "#/definitions/condition[4].regex@v3.." + } + }, + "required": [ + "type", + "string", + "regex" + ] + }, + { + "type": "object", + "unevaluatedProperties": false, + "properties": { + "type": { + "$ref": "#/definitions/condition[5].type@v3.." + }, + "conditions": { + "$ref": "#/definitions/condition[5].conditions@v3..v9" + } + }, + "required": [ + "type", + "conditions" + ] + }, + { + "type": "object", + "unevaluatedProperties": false, + "properties": { + "type": { + "$ref": "#/definitions/condition[6].type@v3.." + }, + "condition": { + "$ref": "#/definitions/condition[6].condition@v3..v9" + } + }, + "required": [ + "type", + "condition" + ] + } + ] + }, + "condition@v10..": { + "anyOf": [ + { + "type": "boolean", + "description": "A boolean which provides a constant value for the condition's evaluation." + }, + { + "type": "object", + "unevaluatedProperties": false, + "properties": { + "type": { + "$ref": "#/definitions/condition[1].type@v3.." + }, + "value": { + "$ref": "#/definitions/condition[1].value@v3.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + }, + "required": [ + "type", + "value" + ] + }, + { + "type": "object", + "unevaluatedProperties": false, + "properties": { + "type": { + "$ref": "#/definitions/condition[2].type@v3.." + }, + "lhs": { + "$ref": "#/definitions/condition[2].lhs@v3.." + }, + "rhs": { + "$ref": "#/definitions/condition[2].rhs@v3.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + }, + "required": [ + "type", + "lhs", + "rhs" + ] + }, + { + "type": "object", + "unevaluatedProperties": false, + "properties": { + "type": { + "$ref": "#/definitions/condition[3].type@v3.." + }, + "string": { + "$ref": "#/definitions/condition[3].string@v3.." + }, + "list": { + "$ref": "#/definitions/condition[3].list@v3.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + }, + "required": [ + "type", + "string", + "list" + ] + }, + { + "type": "object", + "unevaluatedProperties": false, + "properties": { + "type": { + "$ref": "#/definitions/condition[4].type@v3.." + }, + "string": { + "$ref": "#/definitions/condition[4].string@v3.." + }, + "regex": { + "$ref": "#/definitions/condition[4].regex@v3.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + }, + "required": [ + "type", + "string", + "regex" + ] + }, + { + "type": "object", + "unevaluatedProperties": false, + "properties": { + "type": { + "$ref": "#/definitions/condition[5].type@v3.." + }, + "conditions": { + "$ref": "#/definitions/condition[5].conditions@v10.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + }, + "required": [ + "type", + "conditions" + ] + }, + { + "type": "object", + "unevaluatedProperties": false, + "properties": { + "type": { + "$ref": "#/definitions/condition[6].type@v3.." + }, + "condition": { + "$ref": "#/definitions/condition[6].condition@v10.." + }, + "$comment": { + "$ref": "#/definitions/$comment@v10.." + } + }, + "required": [ + "type", + "condition" + ] + } + ] } } }
diff --git a/Help/manual/presets/schema.yaml b/Help/manual/presets/schema.yaml new file mode 100644 index 0000000..7650fa4 --- /dev/null +++ b/Help/manual/presets/schema.yaml
@@ -0,0 +1,2039 @@ +--- +version: 12 +types: + - id: condition + type: variant + items: + - type: boolean + description: + A boolean which provides a constant value for the condition's + evaluation. + # 'const' condition + - type: object + unevaluatedProperties: false + properties: + type: + type: string + required: true + const: const + description: + A required string specifying the type of the condition. + value: + type: boolean + required: true + description: + A required boolean which provides a constant value for the + condition's evaluation. + # 'equals', 'notEquals' condition + - type: object + unevaluatedProperties: false + properties: + type: + type: string + required: true + enum: + - equals + - notEquals + description: + A required string specifying the type of the condition. + lhs: + type: string + required: true + description: + First string to compare. This field supports macro expansion. + rhs: + type: string + required: true + description: + Second string to compare. This field supports macro expansion. + # 'inList', 'notInList' condition + - type: object + properties: + type: + type: string + required: true + enum: + - inList + - notInList + description: + A required string specifying the type of the condition. + string: + type: string + required: true + description: + A required string to search for. This field supports macro + expansion. + list: + type: array + required: true + items: + type: string + description: + A required array of strings to search. This field supports macro + expansion, and uses short-circuit evaluation. + unevaluatedProperties: false + # 'matches', 'notMatches' condition + - type: object + properties: + type: + type: string + required: true + enum: + - matches + - notMatches + description: + A required string specifying the type of the condition. + string: + type: string + required: true + description: + A required string to search. This field supports macro expansion. + regex: + type: string + required: true + description: + A required regular expression to search for. This field supports + macro expansion. + unevaluatedProperties: false + # 'anyOf', 'allOf' condition + - type: object + properties: + type: + type: string + required: true + enum: + - anyOf + - allOf + description: + A required string specifying the type of the condition. + conditions: + type: array + required: true + description: + A required array of condition objects. These conditions use + short-circuit evaluation. + items: + type: ref + target: condition + unevaluatedProperties: false + # 'not' condition + - type: object + properties: + type: + type: string + required: true + const: not + description: + A required string specifying the type of the condition. + condition: + type: ref + required: true + target: condition + unevaluatedProperties: false +definitions: + inherits: &preset-inherits + anyOf: + - type: string + minLength: 1 + description: + An optional string representing the name of the preset from which to + inherit. + - type: array + description: + An optional array of strings representing the names of presets from + which to inherit. 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 + minLength: 1 + description: + An optional string representing the name of the preset from which + to inherit. + sphinxDescription: | + An optional array of strings representing the names of presets from which + to inherit. This field can also be a string, which is equivalent to an + array containing one string. + + 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`` array will be preferred. + + A preset can only inherit from another preset that is defined in the same + file or in one of the files it includes (directly or indirectly). Presets + in ``CMakePresets.json`` may not inherit from presets in + ``CMakeUserPresets.json``. + vendor: &preset-vendor + type: object + minLength: 1 + 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. + sphinxDescription: | + 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: &preset-displayName + type: string + description: + An optional string with a human-friendly name of the preset. + description: &preset-description + type: string + description: + An optional string with a human-friendly description of the preset. + environment: &preset-environment + type: object + description: &environment-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. + sphinxDescription: &environment-sphinx-description | + 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 a + string representing the value of the variable. 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}``). ``$penv{NAME}`` + allows one to prepend or append values to existing environment variables + by accessing only values from the parent environment. + + 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: {} + propertyNames: + pattern: '^.+$' + additionalProperties: &environment-additional-properties + 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. + architecture-or-toolset: &architecture-or-toolset-properties + value: + type: string + description: An optional string representing the value. + strategy: + type: string + enum: + - set + - external + description: ' + An optional string telling CMake how to handle the field. Valid values + are: "set" Set the respective value. This will result in an error for + generators that do not support the respective field. "external" Do not + set the value, even if the generator supports it. This is useful if, + for example, a preset uses the Ninja generator, and an IDE knows how to + set up the Visual C++ environment from the architecture and toolset + fields. In that case, CMake will ignore the field, but the IDE can use + them to set up the environment before invoking CMake. + ' + sphinxDescription: | + An optional string telling CMake how to handle the field. + Valid values are: + + ``"set"`` + Set the respective value. This will result in an error for generators + that do not support the respective field. + + ``"external"`` + Do not set the value, even if the generator supports it. This is + useful if, for example, a preset uses the Ninja generator, and an IDE + knows how to set up the Visual C++ environment from the architecture + and toolset fields. In that case, CMake will ignore the field, but + the IDE can use them to set up the environment before invoking CMake. + + 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"``. + condition: &condition + since: 3 + anyOf: + - type: ref + target: condition + - type: 'null' + description: + Null indicates that the condition always evaluates to true and is not + inherited. + sphinxDescription: | + An optional `Condition`_ object. +description: + The presets specify the generator and the build directory, and optionally an + array of variables and other arguments to pass to CMake. +properties: + $schema: + since: 8 + type: string + format: uri-reference + description: + 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 autocompletion in editors that support JSON schema. It doesn't affect + the 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. + version: + type: integer + required: true + description: + A required integer representing the version of the JSON schema. + sphinxDescription: | + 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: + type: object + description: + An optional object representing the minimum version of CMake + needed to build this project. + sphinxDescription: | + An optional object representing the minimum version of CMake + needed to build this project. This object consists of the following + fields: + + .. include:: presets/cmakeMinimumRequired-properties.rst + properties: + major: + type: integer + description: An optional integer representing the major version. + minor: + type: integer + description: An optional integer representing the minor version. + patch: + type: integer + description: An optional integer representing the patch version. + unevaluatedProperties: false + include: + since: 4 + type: array + items: + type: string + description: + An optional array of strings representing files to include. If the + filenames are not absolute, they are considered relative to the current + file. + sphinxDescription: | + An optional array of strings representing files to include. If the + filenames are not absolute, they are considered relative to the current + file. See `Includes`_ for discussion of the constraints on included + files. + 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, the keys should be a vendor-specific domain name + followed by a /-separated path. For example, the Example IDE 1.0 could + use example.com/ExampleIDE/1.0. The value of each field can be anything + desired by the vendor, though will typically be a map. + sphinxDescription: | + An optional map containing vendor-specific information. CMake does not + interpret the contents of this field except to verify that it is a map if + it does exist. However, the keys should be a vendor-specific domain name + followed by a ``/``-separated path. For example, the Example IDE 1.0 + could use ``example.com/ExampleIDE/1.0``. The value of each field can be + anything desired by the vendor, though will typically be a map. + properties: {} + configurePresets: + type: array + description: + An optional array of configure preset objects. + sphinxDescription: | + An optional array of `Configure Preset`_ objects. + items: + type: object + description: + A configure preset object. + properties: + name: + type: string + required: true + minLength: 1 + description: + A required string representing the machine-friendly name of the + preset. This identifier is used in the 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, package, or workflow preset. + sphinxDescription: | + A required string representing the machine-friendly name of the + preset. 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, package, or workflow preset. + 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. + sphinxDescription: | + An optional boolean specifying whether or not a preset should be + hidden. If a preset is hidden, it cannot be used in the + :cmake-option:`--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: *preset-inherits + condition: *condition + vendor: *preset-vendor + displayName: *preset-displayName + description: *preset-description + generator: + revisions: + - until: 3 + 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. + - since: 3 + 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. + sphinxDescription: | + An optional string representing the + :manual:`generator <cmake-generators(7)>` to use for the preset. + + .. presets-versionchanged:: 3 + + If omitted, CMake will fall back to regular generator discovery + procedure. In previous versions, if not specified, this field + must be inherited from the ``inherits`` preset (unless this + preset is ``hidden``). + + Note that for :ref:`Visual Studio generators`, unlike in the + command line :cmake-option:`-G` argument, you cannot include the + platform name in the generator name. Use the ``architecture`` + field instead. + architecture: + anyOf: + - type: string + description: &architectureDescription + An optional string representing the platform for generators + that support it. + - type: object + description: *architectureDescription + properties: *architecture-or-toolset-properties + unevaluatedProperties: false + sphinxDescription: | + Optional field representing the platform for + :manual:`generators <cmake-generators(7)>` that support it. + + See :option:`cmake -A` for possible values. + + ``architecture`` may be either a string or an object with the + following fields: + + .. include:: presets/architecture-properties.rst + toolset: + anyOf: + - type: string + description: &toolsetDescription + An optional string representing the toolset for generators that + support it. + - type: object + description: *toolsetDescription + properties: *architecture-or-toolset-properties + unevaluatedProperties: false + sphinxDescription: | + Optional field representing the toolset for + :manual:`generators <cmake-generators(7)>` that support it. + + See :option:`cmake -T` for possible values. + + ``toolset`` may be either a string or an object with the following + fields: + + .. include:: presets/toolset-properties.rst + toolchainFile: + since: 3 + 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. + sphinxDescription: | + An optional string representing the path to the toolchain file. + This field supports `macro expansion`_. If a relative path is + specified, it is calculated relative to the build directory, and if + not found, relative to the source directory. This field takes + precedence over any :variable:`CMAKE_TOOLCHAIN_FILE` value. + graphviz: + since: 10 + type: string + description: + An optional string specifying the path to the graphviz dot file. + sphinxDescription: | + 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 + :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. + binaryDir: + revisions: + - until: 3 + 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). + - since: 3 + 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. + sphinxDescription: | + 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. + + .. presets-versionchanged:: 3 + + If omitted, CMake will calculate the path using regular methods. + In previous versions, if not specified, this field must be + inherited from the ``inherits`` preset (unless this preset is + ``hidden``). + installDir: + since: 3 + 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. + sphinxDescription: | + 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. + 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. + sphinxDescription: | + An optional map of cache variables. The key is the variable name + (which may not be an empty string), and the value is either + ``null``, a boolean (which is equivalent to a value of ``"TRUE"`` + or ``"FALSE"`` and a type of ``BOOL``), a string representing the + value of the variable (which supports `macro expansion`_), or an + object with the following fields: + + ``type`` + An optional string representing the type of the variable. + + ``value`` + A required string or boolean representing the value of the + variable. A boolean is equivalent to ``"TRUE"`` or ``"FALSE"``. + This field supports `macro expansion`_. + + 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. Setting a variable to + ``null`` causes it to not be set, even if a value was inherited + from another preset. + properties: {} + propertyNames: + pattern: '^.+$' + 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: boolean + description: + A boolean representing the value of the variable. Equivalent + to "TRUE" or "FALSE" + - type: string + description: + A string representing the value of the variable (which + supports macro expansion). + - type: object + description: + An optional object representing the cache variables for + generators that support it. + properties: + type: + type: string + enum: + - BOOL + - FILEPATH + - PATH + - STRING + - INTERNAL + description: + An optional string representing the type of the variable. + It should be BOOL, FILEPATH, PATH, STRING, or INTERNAL. + value: + required: true + anyOf: + - type: boolean + description: + A boolean representing the value of the variable. + Equivalent to "TRUE" or "FALSE". + - type: string + description: + A string representing the value of the variable + (which supports macro expansion). + unevaluatedProperties: false + environment: *preset-environment + warnings: + type: object + description: + An optional object specifying the warnings to enable. + sphinxDescription: | + An optional object specifying the warnings to enable. + The object may contain the following fields: + + .. include:: presets/warnings-properties.rst + properties: + # This should ONLY have diagnostics whose definitions require + # special handling (i.e. anything from preset version < 12). Others + # will be generated from cmDiagnostics.h. + 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. + sphinxDescription: | + An optional boolean. Equivalent to passing + :option:`-Wdeprecated <cmake -W>` or + :option:`-Wno-deprecated <cmake -Wno->` + on the command line. + This may not be set to ``false`` + if ``errors.deprecated`` is set to ``true``. + dev: + until: 12 + 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. + sphinxDescription: | + An optional boolean. Equivalent to passing + :option:`-Wdev <cmake -W>` or + :option:`-Wno-dev <cmake -Wno->` + on the command line. + This may not be set to ``false`` + if ``errors.dev`` is set to ``true``. + uninitialized: + type: boolean + description: + An optional boolean. Equivalent to passing -Wuninitialized or + -Wno-uninitialized on the command line. This may not be set + to false if errors.uninitialized is set to true. + sphinxDescription: | + An optional boolean. Equivalent to passing + :option:`-Wuninitialized <cmake -W>` or + :option:`-Wno-uninitialized <cmake -Wno->` + on the command line. + This may not be set to ``false`` + if ``errors.uninitialized`` is set to ``true``. + unusedCli: + type: boolean + description: + An optional boolean. Equivalent to passing -Wunused-cli or + -Wno-unused-cli on the command line. This may not be set + to false if errors.unusedCli is set to true. + sphinxDescription: | + An optional boolean. Equivalent to passing + :option:`-Wunused-cli <cmake -W>` or + :option:`-Wno-unused-cli <cmake -Wno->` + on the command line. + This may not be set to ``false`` + if ``errors.unusedCli`` is set to ``true``. + systemVars: + sort: false + type: boolean + description: + An optional boolean. Setting this to true is equivalent to + passing --check-system-vars on the command line. + sphinxDescription: | + An optional boolean. Setting this to ``true`` is equivalent to + passing :cmake-option:`--check-system-vars` on the command + line. + unevaluatedProperties: false + errors: + type: object + description: + An optional object specifying the errors to enable. + sphinxDescription: | + An optional object specifying the errors to enable. + The object may contain the following fields: + + .. include:: presets/errors-properties.rst + properties: + # This should ONLY have diagnostics whose definitions require + # special handling (i.e. anything from preset version < 12). Others + # will be generated from cmDiagnostics.h. + 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. + sphinxDescription: | + An optional boolean. Equivalent to passing + :cmake-option:`-Werror=deprecated` or + :cmake-option:`-Wno-error=deprecated` + on the command line. + This may not be set to ``true`` + if ``warnings.deprecated`` is set to ``false``. + dev: + until: 12 + 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. + sphinxDescription: | + An optional boolean. Equivalent to passing + :cmake-option:`-Werror=dev` or + :cmake-option:`-Wno-error=dev` + on the command line. + This may not be set to ``true`` + if ``warnings.dev`` is set to ``false``. + uninitialized: + since: 12 + type: boolean + description: + An optional boolean. Equivalent to passing + -Werror=uninitialized or -Wno-error=uninitialized + on the command line. This may not be set + to true if warnings.uninitialized is set to false. + sphinxDescription: | + An optional boolean. Equivalent to passing + :cmake-option:`-Werror=uninitialized` or + :cmake-option:`-Wno-error=uninitialized` + on the command line. + This may not be set to ``true`` + if ``warnings.uninitialized`` is set to ``false``. + unusedCli: + since: 12 + type: boolean + description: + An optional boolean. Equivalent to passing + -Werror=unused-cli or -Wno-error=unused-cli + on the command line. This may not be set + to true if warnings.unusedCli is set to false. + sphinxDescription: | + An optional boolean. Equivalent to passing + :cmake-option:`-Werror=unused-cli` or + :cmake-option:`-Wno-error=unused-cli` + on the command line. + This may not be set to ``true`` + if ``warnings.unusedCli`` is set to ``false``. + unevaluatedProperties: false + debug: + type: object + description: + An optional object specifying debug options. + sphinxDescription: | + An optional object specifying debug options. + The object may contain the following fields: + + .. include:: presets/debug-properties.rst + properties: + output: + type: boolean + description: + An optional boolean. Setting this to true is equivalent to + passing --debug-output on the command line. + sphinxDescription: | + An optional boolean. Setting this to ``true`` is equivalent to + passing :cmake-option:`--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. + sphinxDescription: | + An optional boolean. Setting this to ``true`` is equivalent to + passing :cmake-option:`--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. + sphinxDescription: | + An optional boolean. Setting this to ``true`` is equivalent to + passing :cmake-option:`--debug-find` on the command line. + unevaluatedProperties: false + trace: + since: 7 + type: object + description: + An optional object specifying trace options. + sphinxDescription: | + An optional object specifying trace options. + The object may contain the following fields: + + .. include:: presets/trace-properties.rst + properties: + mode: + type: string + enum: + - 'on' + - 'off' + - 'expand' + description: + An optional string that specifies the trace mode. + sphinxDescription: | + An optional string that specifies the trace mode. + Valid values are: + + ``on`` + Causes a trace of all calls made and from where to be + printed. Equivalent to passing :cmake-option:`--trace` + on the command line. + + ``off`` + A trace of all calls will not be printed. + + ``expand`` + Causes a trace with variables expanded of all calls made + and from where to be printed. Equivalent to passing + :cmake-option:`--trace-expand` on the command line. + format: + type: string + enum: + - human + - json-v1 + description: + An optional string that specifies the trace output format. + sphinxDescription: | + An optional string that specifies the format output of the + trace. Valid values are: + + ``human`` + Prints each trace line in a human-readable format. + This is the default format. Equivalent to passing + :cmake-option:`--trace-format=human` + on the command line. + + ``json-v1`` + Prints each line as a separate JSON document. Equivalent + to passing :cmake-option:`--trace-format=json-v1` + on the command line. + source: + anyOf: + - type: string + minLength: 1 + description: + An optional string representing the path to one source file + to be traced. + - type: array + description: + An optional array of strings representing the paths to source + files to be traced. + items: + type: string + minLength: 1 + description: + A string representing the path to one source file to be + traced. + sphinxDescription: | + An optional array of strings representing the paths of source + files to be traced. This field can also be a string, which is + equivalent to an array containing one string. Equivalent to + passing :cmake-option:`--trace-source` on the command line. + redirect: + type: string + description: + An optional string specifying a path to a trace output file. + sphinxDescription: | + An optional string specifying a path to a trace output file. + Equivalent to passing :cmake-option:`--trace-redirect` on the + command line. + unevaluatedProperties: false + unevaluatedProperties: false + buildPresets: + since: 2 + type: array + description: + An optional array of build preset objects. + sphinxDescription: | + An optional array of `Build Preset`_ objects. + items: + type: object + description: + A build preset object. + properties: + name: + type: string + required: true + minLength: 1 + description: + A required string representing the machine-friendly name of the + preset. This identifier is used in the 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, package, or workflow preset. + sphinxDescription: | + A required string representing the machine-friendly name of the + preset. This identifier is used in the + :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, package, or workflow preset. + 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. + sphinxDescription: | + An optional boolean specifying whether or not a preset should be + hidden. If a preset is hidden, it cannot be used in the + :cmake-build-option:`--preset` argument and does not have to have a + valid :preset:`buildPresets.configurePreset`, even from + inheritance. ``hidden`` presets are intended to be used as a base + for other presets to inherit via the + :preset:`buildPresets.inherits` field. + inherits: *preset-inherits + condition: *condition + vendor: *preset-vendor + displayName: *preset-displayName + description: *preset-description + environment: + type: object + description: *environment-description + sphinxDescription: *environment-sphinx-description + sphinxNote: | + 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 :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. + properties: {} + propertyNames: + pattern: '^.+$' + additionalProperties: *environment-additional-properties + configurePreset: + type: string + minLength: 1 + 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. + sphinxDescription: | + 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 directory is inferred from the + configure preset, so the build will take place in the same + ``binaryDir`` that the configuration did. + 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. + sphinxDescription: | + 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. + sphinxDescription: | + An optional integer. Equivalent to passing + :cmake-build-option:`--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 presets file. + 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 + items: + type: string + 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. + sphinxDescription: | + An optional string or array of strings. Equivalent to passing + :cmake-build-option:`--target` or ``-t`` on the command line. + Vendors may ignore the targets property or hide build presets that + explicitly specify targets. This field supports `macro expansion`_. + configuration: + type: string + description: + An optional string. Equivalent to passing --config on the command + line. + sphinxDescription: | + An optional string. Equivalent to passing + :cmake-build-option:`--config` on the command line. + cleanFirst: + type: boolean + description: + An optional boolean. If true, equivalent to passing --clean-first + on the command line. + sphinxDescription: | + An optional bool. If ``true``, equivalent to passing + :cmake-build-option:`--clean-first` on the command line. + resolvePackageReferences: + since: 4 + type: string + enum: + - 'on' + - 'off' + - 'only' + 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). + sphinxDescription: | + An optional string that specifies the package resolve mode. + + Package references are used to define dependencies to packages from + external package managers. Currently only NuGet in combination with + the :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. + + ``off`` + Package references will not be resolved. Note that this may cause + errors in some build environments, such as .NET SDK style + projects. + + ``only`` + Only resolve package references, but do not perform a build. + + .. note:: + + The command line parameter + :cmake-build-option:`--resolve-package-references` + will take priority over this setting. If the command line + parameter is not provided and this setting is not specified, an + environment-specific cache variable will be evaluated to decide, + if package restoration should be performed. + + 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: + type: boolean + description: + An optional boolean. If true, equivalent to passing --verbose on + the command line. + sphinxDescription: | + An optional boolean. If ``true``, equivalent to passing + :cmake-build-option:`--verbose` on the command line. + nativeToolOptions: + type: array + items: + type: string + description: + An optional array of strings. Equivalent to passing options after + -- on the command line. + sphinxDescription: | + An optional array of strings. Equivalent to passing options after + :cmake-build-option:`--` on the command line. The array values + support `macro expansion`_. + unevaluatedProperties: false + testPresets: + since: 2 + type: array + description: + An optional array of test preset objects. Used to specify arguments to + ctest. + sphinxDescription: | + An optional array of `Test Preset`_ objects. + items: + type: object + description: + A test preset object. + properties: + name: + type: string + required: true + minLength: 1 + description: + A required string representing the machine-friendly name of the + preset. This identifier is used in the ctest --preset option. There + must not be two test presets in the union of CMakePresets.json and + CMakeUserPresets.json in the same directory with the same name. + However, a test preset may have the same name as a configure, + build, package, or workflow preset. + sphinxDescription: | + A required string representing the machine-friendly name of the + preset. This identifier is used in the :option:`ctest --preset` + option. There must not be two test presets in the union of + ``CMakePresets.json`` and ``CMakeUserPresets.json`` in the same + directory with the same name. However, a test preset may have the + same name as a configure, build, package, or workflow preset. + 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. + sphinxDescription: | + An optional boolean specifying whether or not a preset should be + hidden. If a preset is hidden, it cannot be used in the + :ctest-option:`--preset` argument and does not have to have a valid + :preset:`testPresets.configurePreset`, even from + inheritance. ``hidden`` presets are intended to be used as a base + for other presets to inherit via the + :preset:`testPresets.inherits` field. + inherits: *preset-inherits + condition: *condition + vendor: *preset-vendor + displayName: *preset-displayName + description: *preset-description + environment: *preset-environment + configurePreset: + type: string + minLength: 1 + 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 directory is inferred from the + configure preset. + sphinxDescription: | + 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 directory is inferred from the + configure preset, so tests will run in the same ``binaryDir`` that + the configuration and build used. + 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. + sphinxDescription: | + 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. + sphinxDescription: | + An optional string. Equivalent to passing + :ctest-option:`--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. + sphinxDescription: | + An optional array of configuration options to overwrite options + specified in the CTest configuration file. Equivalent to passing + :ctest-option:`--overwrite` for each value in the array. The array + values support `macro expansion`_. + items: + type: string + description: + An option written as a key-value pair in the form "key=value". + output: + id: testOutput + type: object + description: + An optional object specifying output options. + sphinxDescription: | + An optional object specifying output options. + The object may contain the following fields: + + .. include:: presets/testOutput-properties.rst + properties: + shortProgress: + type: boolean + description: + An optional boolean. If true, equivalent to passing --progress + on the command line. + sphinxDescription: | + An optional bool. If ``true``, equivalent to passing + :ctest-option:`--progress` on the command line. + verbosity: + type: string + enum: + - default + - verbose + - extra + 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). + ' + sphinxDescription: | + An optional string specifying verbosity level. Must be one of + the following: + + ``default`` + Equivalent to passing no verbosity flags on the command line. + + ``verbose`` + Equivalent to passing :ctest-option:`--verbose` on the + command line. + + ``extra`` + Equivalent to passing :ctest-option:`--extra-verbose` on the + command line. + debug: + type: boolean + description: + An optional boolean. If true, equivalent to passing --debug on + the command line. + sphinxDescription: | + An optional bool. If ``true``, equivalent to passing + :ctest-option:`--debug` on the command line. + outputOnFailure: + type: boolean + description: + An optional boolean. If true, equivalent to passing + --output-on-failure on the command line. + sphinxDescription: | + An optional bool. If ``true``, equivalent to passing + :ctest-option:`--output-on-failure` on the command line. + quiet: + type: boolean + description: + An optional boolean. If true, equivalent to passing --quiet on + the command line. + sphinxDescription: | + An optional bool. If ``true``, equivalent to passing + :ctest-option:`--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. + sphinxDescription: | + An optional string specifying a path to a log file. Equivalent + to passing :ctest-option:`--output-log` on the command line. + This field supports `macro expansion`_. + outputJUnitFile: + since: 6 + type: string + description: + An optional string specifying a path to a JUnit file. + Equivalent to passing --output-junit on the command line. + sphinxDescription: | + An optional string specifying a path to a JUnit file. + Equivalent to passing :ctest-option:`--output-junit` on the + command line. This field supports `macro expansion`_. + labelSummary: + type: boolean + description: + An optional boolean. If false, equivalent to passing + --no-label-summary on the command line. + sphinxDescription: | + An optional bool. If ``false``, equivalent to passing + :ctest-option:`--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. + sphinxDescription: | + An optional bool. If ``false``, equivalent to passing + :ctest-option:`--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. + sphinxDescription: | + An optional integer specifying the maximum output for passed + tests in bytes. Equivalent to passing + :ctest-option:`--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. + sphinxDescription: | + An optional integer specifying the maximum output for failed + tests in bytes. Equivalent to passing + :ctest-option:`--test-output-size-failed` on the command line. + testOutputTruncation: + since: 5 + type: string + enum: + - tail + - middle + - head + 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". + ' + sphinxDescription: | + An optional string specifying the test output truncation mode. + Equivalent to passing :ctest-option:`--test-output-truncation` + on the command line. Must be one of the following values: + + * ``tail`` + + * ``middle`` + + * ``head`` + 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. + sphinxDescription: | + An optional integer specifying the maximum width of a test name + to output. Equivalent to passing :ctest-option:`--max-width` on + the command line. + unevaluatedProperties: false + filter: + type: object + description: + An optional object specifying how to filter the tests to run. + sphinxDescription: | + An optional object specifying how to filter the tests to run. + The object may contain the following fields: + + .. include:: presets/filter-properties.rst + properties: + include: + type: object + description: + An optional object specifying which tests to include. + sphinxDescription: | + An optional object specifying which tests to include. + The object may contain the following fields: + + .. include:: presets/include-properties.rst + properties: + name: + type: string + description: + An optional string specifying a regex for test names. + Equivalent to passing --tests-regex on the command line. + sphinxDescription: | + An optional string specifying a regex for test names. + Equivalent to passing :ctest-option:`--tests-regex` on the + command line. This field supports `macro expansion`_. + + CMake regex syntax is described under + :ref:`string(REGEX) <Regex Specification>`. + label: + type: string + description: + An optional string specifying a regex for test labels. + Equivalent to passing --label-regex on the command line. + sphinxDescription: | + An optional string specifying a regex for test labels. + Equivalent to passing :ctest-option:`--label-regex` on the + command line. This field supports `macro expansion`_. + useUnion: + type: boolean + description: + An optional boolean. Equivalent to passing --union on the + command line. + sphinxDescription: | + An optional bool. Equivalent to passing + :ctest-option:`--union` on the command line. + index: + anyOf: + - type: string + description: + An optional string specifying a file with the command + line syntax for --tests-information. Available in + version 2 and higher. + - type: object + description: + An optional object specifying test preset filters. + Available in version 2 and higher. + properties: + start: + type: integer + description: + An optional integer specifying a test index at + which to start testing. + end: + type: integer + description: + An optional integer specifying a test index at + which to stop testing. + stride: + type: integer + description: + An optional integer specifying the increment. + specificTests: + type: array + description: + An optional array of integers specifying specific + test indices to run. + items: + type: integer + description: + An integer specifying the test to run by index. + unevaluatedProperties: false + sphinxDescription: | + An optional object specifying tests to include by test + index. The object may contain the following fields. Can + also be an optional string specifying a file with the + command line syntax for + :ctest-option:`--tests-information`. If specified as a + string, this field supports `macro expansion`_. + + .. include:: presets/index-properties.rst + exclude: + type: object + description: + An optional object specifying which tests to exclude. + sphinxDescription: | + An optional object specifying which tests to exclude. + The object may contain the following fields: + + .. include:: presets/exclude-properties.rst + properties: + name: + type: string + description: + An optional string specifying a regex for test names. + Equivalent to passing --exclude-regex on the command line. + sphinxDescription: | + An optional string specifying a regex for test names. + Equivalent to passing :ctest-option:`--exclude-regex` on + the command line. This field supports `macro expansion`_. + label: + type: string + description: + An optional string specifying a regex for test labels. + Equivalent to passing --label-exclude on the command line. + sphinxDescription: | + An optional string specifying a regex for test labels. + Equivalent to passing :ctest-option:`--label-exclude` on + the command line. This field supports `macro expansion`_. + fixtures: + type: object + description: + An optional object specifying which fixtures to exclude + from adding tests. + sphinxDescription: | + An optional object specifying which fixtures to exclude + from adding tests. The object may contain the following + fields: + + .. include:: presets/fixtures-properties.rst + properties: + any: + type: string + description: + An optional string specifying a regex for text fixtures + to exclude from adding any tests. Equivalent to passing + --fixture-exclude-any on the command line. + sphinxDescription: | + An optional string specifying a regex for text fixtures + to exclude from adding any tests. Equivalent to passing + :ctest-option:`--fixture-exclude-any` on the command + line. This field supports `macro expansion`_. + setup: + type: string + description: + An optional string specifying a regex for text fixtures + to exclude from adding setup tests. Equivalent to + passing --fixture-exclude-setup on the command line. + sphinxDescription: | + An optional string specifying a regex for text fixtures + to exclude from adding setup tests. Equivalent to + passing :ctest-option:`--fixture-exclude-setup` on the + command line. This field supports `macro expansion`_. + cleanup: + type: string + description: + An optional string specifying a regex for text fixtures + to exclude from adding cleanup tests. Equivalent to + passing --fixture-exclude-cleanup on the command line. + sphinxDescription: | + An optional string specifying a regex for text fixtures + to exclude from adding cleanup tests. Equivalent to + passing :ctest-option:`--fixture-exclude-cleanup` on + the command line. + This field supports `macro expansion`_. + execution: + type: object + description: + An optional object specifying options for test execution. + sphinxDescription: | + An optional object specifying options for test execution. + The object may contain the following fields: + + .. include:: presets/execution-properties.rst + properties: + stopOnFailure: + type: boolean + description: + An optional boolean. If true, equivalent to passing + --stop-on-failure on the command line. + sphinxDescription: | + An optional bool. If ``true``, equivalent to passing + :ctest-option:`--stop-on-failure` on the command line. + enableFailover: + type: boolean + description: + An optional boolean. If true, equivalent to passing -F on the + command line. + sphinxDescription: | + An optional bool. If ``true``, equivalent to passing + :ctest-option:`-F` on the command line. + jobs: + revisions: + - until: 11 + type: integer + minimum: 0 + description: + An optional non-negative integer. Equivalent to passing + --parallel or -j on the command line. + - since: 11 + anyOf: + - type: integer + minimum: 0 + description: + An optional non-negative integer. Equivalent to passing + --parallel or -j on the command line. + - type: string + minLength: 0 + maxLength: 0 + description: + An optional string. Equivalent to passing --parallel or + -j on the command line with the number of jobs omitted. + sphinxDescription: | + An optional integer. Equivalent to passing + :ctest-option:`--parallel` on the command line. If the value is + ``0``, it is equivalent to unbounded parallelism. + + .. presets-versionchanged:: 11 + + 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 presets file. + minimum: 0 + resourceSpecFile: + type: string + description: + An optional string. Equivalent to passing --resource-spec-file + on the command line. + sphinxDescription: | + An optional string. Equivalent to passing + :ctest-option:`--resource-spec-file` on the command line. This + field supports `macro expansion`_. + testLoad: + type: integer + description: + An optional integer. Equivalent to passing --test-load on the + command line. + sphinxDescription: | + An optional integer. Equivalent to passing + :ctest-option:`--test-load` on the command line. + showOnly: + type: string + enum: + - human + - json-v1 + description: + An optional string. Equivalent to passing --show-only on the + command line. Value must be "human" or "json-v1". + sphinxDescription: | + An optional string. Equivalent to passing + :ctest-option:`--show-only` on the command line. The string + must be one of the following values: + + * ``human`` + + * ``json-v1`` + repeat: + type: object + description: + An optional object specifying how to repeat tests. Equivalent + to passing --repeat on the command line. + sphinxDescription: | + An optional object specifying how to repeat tests. Equivalent + to passing :ctest-option:`--repeat` on the command line. + The object must have the following fields: + + .. include:: presets/repeat-properties.rst + properties: + mode: + type: string + required: true + enum: + - until-fail + - until-pass + - after-timeout + description: ' + A required string. Must be one of the following values: + "until-fail", "until-pass", or "after-timeout". + ' + sphinxDescription: | + A required string. Must be one of the following values: + + * ``until-fail`` + + * ``until-pass`` + + * ``after-timeout`` + count: + type: integer + required: true + description: + A required integer. + unevaluatedProperties: false + 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. + sphinxDescription: | + An optional bool. If ``true``, equivalent to passing + :ctest-option:`--interactive-debug-mode 1` on the command line. + If ``false``, equivalent to passing + :ctest-option:`--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. + sphinxDescription: | + An optional bool. If ``true``, equivalent to passing + :ctest-option:`--schedule-random` on the command line. + timeout: + type: integer + description: + An optional integer. Equivalent to passing --timeout on the + command line. + sphinxDescription: | + An optional integer. Equivalent to passing + :ctest-option:`--timeout` on the command line. + noTestsAction: + type: string + enum: + - default + - error + - ignore + 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). + ' + sphinxDescription: | + 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 :ctest-option:`--no-tests=error` + on the command line. + + ``ignore`` + Equivalent to passing :ctest-option:`--no-tests=ignore` + on the command line. + testPassthroughArguments: + since: 12 + type: array + items: + type: string + description: + An optional array of strings. Each element is forwarded as an + argument to every test executable. Equivalent to passing + arguments after -- on the ctest command line. + sphinxDescription: | + An optional array of strings. Each element is forwarded as an + argument to every test executable, equivalent to passing + arguments after :option:`ctest --` on the command line. + + When both preset and command-line passthrough arguments are + specified, preset arguments appear first, followed by + command-line arguments. + unevaluatedProperties: false + unevaluatedProperties: false + packagePresets: + since: 6 + type: array + description: + An optional array of package preset objects. Used to specify arguments to + cpack. + sphinxDescription: | + An optional array of `Package Preset`_ objects. + items: + type: object + description: + A package preset object. + properties: + name: + type: string + required: true + minLength: 1 + description: + A required string representing the machine-friendly name of the + preset. This identifier is used in the cpack --preset option. There + must not be two package presets in the union of CMakePresets.json + and CMakeUserPresets.json in the same directory with the same name. + However, a package preset may have the same name as a configure, + build, test, or workflow preset. + sphinxDescription: | + A required string representing the machine-friendly name of the + preset. This identifier is used in the :option:`cpack --preset` + option. There must not be two package presets in the union of + ``CMakePresets.json`` and ``CMakeUserPresets.json`` in the same + directory with the same name. However, a package preset may have + the same name as a configure, build, test, or workflow preset. + 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. + sphinxDescription: | + An optional boolean specifying whether or not a preset should be + hidden. If a preset is hidden, it cannot be used in the + :cpack-option:`--preset` argument and does not have to have a valid + :preset:`packagePresets.configurePreset`, even from + inheritance. ``hidden`` presets are intended to be used as a base + for other presets to inherit via the + :preset:`packagePresets.inherits` field. + inherits: *preset-inherits + condition: *condition + vendor: *preset-vendor + displayName: *preset-displayName + description: *preset-description + environment: *preset-environment + configurePreset: + type: string + minLength: 1 + 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. + sphinxDescription: | + 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 directory is inferred from the + configure preset, so packaging will run in the same ``binaryDir`` + that the configuration did and build did. + 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. + sphinxDescription: | + 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 array of strings representing generators for CPack to + use. + items: + type: string + description: + An optional string representing the name of a CPack generator + to use. + configurations: + type: array + description: + An optional array of strings representing build configurations for + CPack to package. + items: + type: string + description: + An optional string representing the name of a configuration to + package. + 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. + sphinxDescription: | + An optional map of variables to pass to CPack, equivalent to + :cpack-option:`-D` arguments. Each key is the name of a variable, + and the value is the string to assign to that variable. + properties: {} + propertyNames: + pattern: '^.+$' + additionalProperties: + 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: + id: packageOutput + type: object + description: + An optional object specifying output options. + sphinxDescription: | + An optional object specifying output options. Valid keys are: + + .. include:: presets/packageOutput-properties.rst + 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. + sphinxDescription: | + An optional boolean specifying whether or not to print debug + information. A value of ``true`` is equivalent to passing + :cpack-option:`--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. + sphinxDescription: | + An optional boolean specifying whether or not to print + verbosely. A value of ``true`` is equivalent to passing + :cpack-option:`--verbose` on the command line. + unevaluatedProperties: false + packageName: + type: string + description: + An optional string representing the package name. + sphinxNote: &package-naming-note | + Due to problems with the implementation, this field does not affect + the name of the final package file produced. However, other aspects + of the package may use the value, leading to inconsistencies. A + future CMake release may address this problem, but until then, it + is recommended that this field not be used. + packageVersion: + type: string + description: + An optional string representing the package version. + sphinxNote: *package-naming-note + 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. + unevaluatedProperties: false + workflowPresets: + since: 6 + type: array + description: + An optional array of workflow preset objects. Used to execute configure, + build, test, and package presets in order. + sphinxDescription: | + An optional array of `Workflow Preset`_ objects. + items: + type: object + description: + A workflow preset object. + properties: + name: + type: string + required: true + minLength: 1 + description: + A required string representing the machine-friendly name of the + preset. This identifier is used in the cmake --workflow --preset + option. 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. + However, a workflow preset may have the same name as a configure, + build, test, or package preset. + sphinxDescription: | + A required string representing the machine-friendly name of the + preset. This identifier is used in the + :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. + vendor: *preset-vendor + displayName: *preset-displayName + description: *preset-description + steps: + type: array + required: true + 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. + sphinxDescription: | + 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. Each object may contain the + following fields: + + .. include:: presets/steps-properties.rst + items: + type: object + properties: + type: + type: string + enum: + - configure + - build + - test + - package + description: + A required string. The first step must be configure. + Subsequent steps must be either build, test, or package. + sphinxDescription: | + A required string. The first step must be ``configure``. + Subsequent steps must be either ``build``, ``test``, or + ``package``. + name: + type: string + minLength: 1 + description: + A required string representing the name of the configure, + build, test, or package preset to run as this workflow step. + unevaluatedProperties: false + unevaluatedProperties: false +additionalProperties: false
diff --git a/Help/manual/presets/steps-properties.rst b/Help/manual/presets/steps-properties.rst new file mode 100644 index 0000000..6da4a51 --- /dev/null +++ b/Help/manual/presets/steps-properties.rst
@@ -0,0 +1,14 @@ +.. This file was generated by Utilities/Scripts/regenerate-presets.py + from Help/manual/presets/schema.yaml. Do not edit. + +.. _`CMakePresets.workflowPresets.steps.type`: + +``type`` + A required string. The first step must be ``configure``. + Subsequent steps must be either ``build``, ``test``, or + ``package``. + +.. _`CMakePresets.workflowPresets.steps.name`: + +``name`` + A required string representing the name of the configure, build, test, or package preset to run as this workflow step.
diff --git a/Help/manual/presets/testOutput-properties.rst b/Help/manual/presets/testOutput-properties.rst new file mode 100644 index 0000000..3e5a6df --- /dev/null +++ b/Help/manual/presets/testOutput-properties.rst
@@ -0,0 +1,107 @@ +.. This file was generated by Utilities/Scripts/regenerate-presets.py + from Help/manual/presets/schema.yaml. Do not edit. + +.. _`CMakePresets.testPresets.output.shortProgress`: + +``shortProgress`` + An optional bool. If ``true``, equivalent to passing + :ctest-option:`--progress` on the command line. + +.. _`CMakePresets.testPresets.output.verbosity`: + +``verbosity`` + An optional string specifying verbosity level. Must be one of + the following: + + ``default`` + Equivalent to passing no verbosity flags on the command line. + + ``verbose`` + Equivalent to passing :ctest-option:`--verbose` on the + command line. + + ``extra`` + Equivalent to passing :ctest-option:`--extra-verbose` on the + command line. + +.. _`CMakePresets.testPresets.output.debug`: + +``debug`` + An optional bool. If ``true``, equivalent to passing + :ctest-option:`--debug` on the command line. + +.. _`CMakePresets.testPresets.output.outputOnFailure`: + +``outputOnFailure`` + An optional bool. If ``true``, equivalent to passing + :ctest-option:`--output-on-failure` on the command line. + +.. _`CMakePresets.testPresets.output.quiet`: + +``quiet`` + An optional bool. If ``true``, equivalent to passing + :ctest-option:`--quiet` on the command line. + +.. _`CMakePresets.testPresets.output.outputLogFile`: + +``outputLogFile`` + An optional string specifying a path to a log file. Equivalent + to passing :ctest-option:`--output-log` on the command line. + This field supports `macro expansion`_. + +.. _`CMakePresets.testPresets.output.outputJUnitFile`: + +``outputJUnitFile`` + .. presets-versionadded:: 6 + + An optional string specifying a path to a JUnit file. + Equivalent to passing :ctest-option:`--output-junit` on the + command line. This field supports `macro expansion`_. + +.. _`CMakePresets.testPresets.output.labelSummary`: + +``labelSummary`` + An optional bool. If ``false``, equivalent to passing + :ctest-option:`--no-label-summary` on the command line. + +.. _`CMakePresets.testPresets.output.subprojectSummary`: + +``subprojectSummary`` + An optional bool. If ``false``, equivalent to passing + :ctest-option:`--no-subproject-summary` on the command line. + +.. _`CMakePresets.testPresets.output.maxPassedTestOutputSize`: + +``maxPassedTestOutputSize`` + An optional integer specifying the maximum output for passed + tests in bytes. Equivalent to passing + :ctest-option:`--test-output-size-passed` on the command line. + +.. _`CMakePresets.testPresets.output.maxFailedTestOutputSize`: + +``maxFailedTestOutputSize`` + An optional integer specifying the maximum output for failed + tests in bytes. Equivalent to passing + :ctest-option:`--test-output-size-failed` on the command line. + +.. _`CMakePresets.testPresets.output.testOutputTruncation`: + +``testOutputTruncation`` + .. presets-versionadded:: 5 + + An optional string specifying the test output truncation mode. + Equivalent to passing :ctest-option:`--test-output-truncation` + on the command line. Must be one of the following values: + + * ``tail`` + + * ``middle`` + + * ``head`` + +.. _`CMakePresets.testPresets.output.maxTestNameWidth`: + +``maxTestNameWidth`` + An optional integer specifying the maximum width of a test name + to output. Equivalent to passing :ctest-option:`--max-width` on + the command line.
diff --git a/Help/manual/presets/testPresets-properties.rst b/Help/manual/presets/testPresets-properties.rst new file mode 100644 index 0000000..6e71ab4 --- /dev/null +++ b/Help/manual/presets/testPresets-properties.rst
@@ -0,0 +1,147 @@ +.. This file was generated by Utilities/Scripts/regenerate-presets.py + from Help/manual/presets/schema.yaml. Do not edit. + +.. _`CMakePresets.testPresets.name`: + +``name`` + A required string representing the machine-friendly name of the + preset. This identifier is used in the :option:`ctest --preset` + option. There must not be two test presets in the union of + ``CMakePresets.json`` and ``CMakeUserPresets.json`` in the same + directory with the same name. However, a test preset may have the + same name as a configure, build, package, or workflow preset. + +.. _`CMakePresets.testPresets.hidden`: + +``hidden`` + An optional boolean specifying whether or not a preset should be + hidden. If a preset is hidden, it cannot be used in the + :ctest-option:`--preset` argument and does not have to have a valid + :preset:`testPresets.configurePreset`, even from + inheritance. ``hidden`` presets are intended to be used as a base + for other presets to inherit via the + :preset:`testPresets.inherits` field. + +.. _`CMakePresets.testPresets.inherits`: + +``inherits`` + An optional array of strings representing the names of presets from which + to inherit. This field can also be a string, which is equivalent to an + array containing one string. + + 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`` array will be preferred. + + A preset can only inherit from another preset that is defined in the same + file or in one of the files it includes (directly or indirectly). Presets + in ``CMakePresets.json`` may not inherit from presets in + ``CMakeUserPresets.json``. + +.. _`CMakePresets.testPresets.condition`: + +``condition`` + .. presets-versionadded:: 3 + + An optional `Condition`_ object. + +.. _`CMakePresets.testPresets.vendor`: + +``vendor`` + 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. + +.. _`CMakePresets.testPresets.displayName`: + +``displayName`` + An optional string with a human-friendly name of the preset. + +.. _`CMakePresets.testPresets.description`: + +``description`` + An optional string with a human-friendly description of the preset. + +.. _`CMakePresets.testPresets.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 a + string representing the value of the variable. 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}``). ``$penv{NAME}`` + allows one to prepend or append values to existing environment variables + by accessing only values from the parent environment. + + 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. + +.. _`CMakePresets.testPresets.configurePreset`: + +``configurePreset`` + 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 directory is inferred from the + configure preset, so tests will run in the same ``binaryDir`` that + the configuration and build used. + +.. _`CMakePresets.testPresets.inheritConfigureEnvironment`: + +``inheritConfigureEnvironment`` + 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. + +.. _`CMakePresets.testPresets.configuration`: + +``configuration`` + An optional string. Equivalent to passing + :ctest-option:`--build-config` on the command line. + +.. _`CMakePresets.testPresets.overwriteConfigurationFile`: + +``overwriteConfigurationFile`` + An optional array of configuration options to overwrite options + specified in the CTest configuration file. Equivalent to passing + :ctest-option:`--overwrite` for each value in the array. The array + values support `macro expansion`_. + +.. _`CMakePresets.testPresets.output`: + +``output`` + An optional object specifying output options. + The object may contain the following fields: + + .. include:: presets/testOutput-properties.rst + +.. _`CMakePresets.testPresets.filter`: + +``filter`` + An optional object specifying how to filter the tests to run. + The object may contain the following fields: + + .. include:: presets/filter-properties.rst + +.. _`CMakePresets.testPresets.execution`: + +``execution`` + An optional object specifying options for test execution. + The object may contain the following fields: + + .. include:: presets/execution-properties.rst
diff --git a/Help/manual/presets/toolset-properties.rst b/Help/manual/presets/toolset-properties.rst new file mode 100644 index 0000000..1fc91ca --- /dev/null +++ b/Help/manual/presets/toolset-properties.rst
@@ -0,0 +1,27 @@ +.. This file was generated by Utilities/Scripts/regenerate-presets.py + from Help/manual/presets/schema.yaml. Do not edit. + +.. _`CMakePresets.configurePresets.toolset.value`: + +``value`` + An optional string representing the value. + +.. _`CMakePresets.configurePresets.toolset.strategy`: + +``strategy`` + An optional string telling CMake how to handle the field. + Valid values are: + + ``"set"`` + Set the respective value. This will result in an error for generators + that do not support the respective field. + + ``"external"`` + Do not set the value, even if the generator supports it. This is + useful if, for example, a preset uses the Ninja generator, and an IDE + knows how to set up the Visual C++ environment from the architecture + and toolset fields. In that case, CMake will ignore the field, but + the IDE can use them to set up the environment before invoking CMake. + + 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"``.
diff --git a/Help/manual/presets/trace-properties.rst b/Help/manual/presets/trace-properties.rst new file mode 100644 index 0000000..b7b8b94 --- /dev/null +++ b/Help/manual/presets/trace-properties.rst
@@ -0,0 +1,53 @@ +.. This file was generated by Utilities/Scripts/regenerate-presets.py + from Help/manual/presets/schema.yaml. Do not edit. + +.. _`CMakePresets.configurePresets.trace.mode`: + +``mode`` + An optional string that specifies the trace mode. + Valid values are: + + ``on`` + Causes a trace of all calls made and from where to be + printed. Equivalent to passing :cmake-option:`--trace` + on the command line. + + ``off`` + A trace of all calls will not be printed. + + ``expand`` + Causes a trace with variables expanded of all calls made + and from where to be printed. Equivalent to passing + :cmake-option:`--trace-expand` on the command line. + +.. _`CMakePresets.configurePresets.trace.format`: + +``format`` + An optional string that specifies the format output of the + trace. Valid values are: + + ``human`` + Prints each trace line in a human-readable format. + This is the default format. Equivalent to passing + :cmake-option:`--trace-format=human` + on the command line. + + ``json-v1`` + Prints each line as a separate JSON document. Equivalent + to passing :cmake-option:`--trace-format=json-v1` + on the command line. + +.. _`CMakePresets.configurePresets.trace.source`: + +``source`` + An optional array of strings representing the paths of source + files to be traced. This field can also be a string, which is + equivalent to an array containing one string. Equivalent to + passing :cmake-option:`--trace-source` on the command line. + +.. _`CMakePresets.configurePresets.trace.redirect`: + +``redirect`` + An optional string specifying a path to a trace output file. + Equivalent to passing :cmake-option:`--trace-redirect` on the + command line.
diff --git a/Help/manual/presets/warnings-properties.rst b/Help/manual/presets/warnings-properties.rst new file mode 100644 index 0000000..0a31190 --- /dev/null +++ b/Help/manual/presets/warnings-properties.rst
@@ -0,0 +1,69 @@ +.. This file was generated by Utilities/Scripts/regenerate-presets.py + from Help/manual/presets/schema.yaml. Do not edit. + +.. _`CMakePresets.configurePresets.warnings.author`: + +``author`` + .. presets-versionadded:: 12 + + An optional boolean. Equivalent to passing :option:`-Wauthor <cmake -W>` or + :option:`-Wno-author <cmake -Wno->` on the command line. + This may not be set to ``false`` if ``errors.author`` is set to ``true``. + +.. _`CMakePresets.configurePresets.warnings.deprecated`: + +``deprecated`` + An optional boolean. Equivalent to passing + :option:`-Wdeprecated <cmake -W>` or + :option:`-Wno-deprecated <cmake -Wno->` + on the command line. + This may not be set to ``false`` + if ``errors.deprecated`` is set to ``true``. + +.. _`CMakePresets.configurePresets.warnings.dev`: + +``dev`` + .. presets-versionremoved:: 12 + + An optional boolean. Equivalent to passing + :option:`-Wdev <cmake -W>` or + :option:`-Wno-dev <cmake -Wno->` + on the command line. + This may not be set to ``false`` + if ``errors.dev`` is set to ``true``. + +.. _`CMakePresets.configurePresets.warnings.installAbsoluteDestination`: + +``installAbsoluteDestination`` + .. presets-versionadded:: 12 + + An optional boolean. Equivalent to passing :option:`-Winstall-absolute-destination <cmake -W>` or + :option:`-Wno-install-absolute-destination <cmake -Wno->` on the command line. + This may not be set to ``false`` if ``errors.installAbsoluteDestination`` is set to ``true``. + +.. _`CMakePresets.configurePresets.warnings.uninitialized`: + +``uninitialized`` + An optional boolean. Equivalent to passing + :option:`-Wuninitialized <cmake -W>` or + :option:`-Wno-uninitialized <cmake -Wno->` + on the command line. + This may not be set to ``false`` + if ``errors.uninitialized`` is set to ``true``. + +.. _`CMakePresets.configurePresets.warnings.unusedCli`: + +``unusedCli`` + An optional boolean. Equivalent to passing + :option:`-Wunused-cli <cmake -W>` or + :option:`-Wno-unused-cli <cmake -Wno->` + on the command line. + This may not be set to ``false`` + if ``errors.unusedCli`` is set to ``true``. + +.. _`CMakePresets.configurePresets.warnings.systemVars`: + +``systemVars`` + An optional boolean. Setting this to ``true`` is equivalent to + passing :cmake-option:`--check-system-vars` on the command + line.
diff --git a/Help/manual/presets/workflowPresets-properties.rst b/Help/manual/presets/workflowPresets-properties.rst new file mode 100644 index 0000000..fdebe96 --- /dev/null +++ b/Help/manual/presets/workflowPresets-properties.rst
@@ -0,0 +1,44 @@ +.. This file was generated by Utilities/Scripts/regenerate-presets.py + from Help/manual/presets/schema.yaml. Do not edit. + +.. _`CMakePresets.workflowPresets.name`: + +``name`` + A required string representing the machine-friendly name of the + preset. This identifier is used in the + :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. + +.. _`CMakePresets.workflowPresets.vendor`: + +``vendor`` + 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. + +.. _`CMakePresets.workflowPresets.displayName`: + +``displayName`` + An optional string with a human-friendly name of the preset. + +.. _`CMakePresets.workflowPresets.description`: + +``description`` + An optional string with a human-friendly description of the preset. + +.. _`CMakePresets.workflowPresets.steps`: + +``steps`` + 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. Each object may contain the + following fields: + + .. include:: presets/steps-properties.rst
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/CMP0211.rst b/Help/policy/CMP0211.rst new file mode 100644 index 0000000..4ef04c8 --- /dev/null +++ b/Help/policy/CMP0211.rst
@@ -0,0 +1,22 @@ +CMP0211 +------- + +.. versionadded:: 4.4 + +A file may belong to at most one :ref:`file set <file sets>` in a target. + +In CMake 4.3 and below, it was possible to specify the same file +in multiple file sets in a target. In CMake 4.4 and above, a file +may belong to at most one file set in a target. This policy provides +compatibility for projects that have not been updated accordingly. + +The ``OLD`` behavior for this policy is to accept the same file in +multiple file sets in a target. The ``NEW`` behavior for this policy +is to accept a given file in at most one file set in a target. + +.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 4.4 +.. |WARNS_OR_DOES_NOT_WARN| replace:: + warns when a file is part of multiple file sets in a target +.. include:: include/STANDARD_ADVICE.rst + +.. include:: include/DEPRECATED.rst
diff --git a/Help/policy/CMP0212.rst b/Help/policy/CMP0212.rst new file mode 100644 index 0000000..81d7828 --- /dev/null +++ b/Help/policy/CMP0212.rst
@@ -0,0 +1,31 @@ +CMP0212 +------- + +.. versionadded:: 4.4 + +:command:`add_custom_command` ``DEPENDS`` does not strip ``.exe`` suffixes. + +When searching for dependencies specified with the ``DEPENDS`` option of +:command:`add_custom_command`, CMake 4.3 and below applied a heuristic to +remove ``.exe`` from the end of ``DEPENDS`` argument values, which created a +target-level dependency on an executable with that stripped name if such a +target exists. This allowed using the name of the target output file as an +alternative spelling when naming dependencies. However, with the emergence of +CMake's target model, specifying the output file in this way is no longer +needed, and leads to conflicts in creating target- and file-level dependencies +when targets exist with the ``.exe`` suffix in the name itself. + +The ``OLD`` behavior of this policy strips the ``.exe`` suffix from arguments +to ``DEPENDS`` when searching for target-level dependencies. The ``NEW`` +behavior does not strip the ``.exe`` suffix in its search. CMake will otherwise +proceed normally with the other dependency search heuristics as specified in +:command:`add_custom_command` ``DEPENDS``. Users are encouraged to specify the +name of the executable target if a target-level dependency is desired, or use +the :genex:`TARGET_FILE` generator expression if a file-level dependency +is desired, rather than implying the target indirectly via its output file name. + +.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 4.4 +.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn +.. include:: include/STANDARD_ADVICE.rst + +.. include:: include/DEPRECATED.rst
diff --git a/Help/policy/CMP0213.rst b/Help/policy/CMP0213.rst new file mode 100644 index 0000000..d8a8e25 --- /dev/null +++ b/Help/policy/CMP0213.rst
@@ -0,0 +1,22 @@ +CMP0213 +------- + +.. versionadded:: 4.4 + +:command:`file(ARCHIVE_CREATE)` and :command:`file(ARCHIVE_EXTRACT)` +encode archive paths as UTF-8 by default. + +CMake 4.3 and below always used the ``OEM`` (current locale) encoding for archive +paths. CMake 4.4 offer the ``ENCODING`` option, but prefer to use ``UTF-8`` +by default. This policy provides compatibility for projects that have not +been updated to specify the encoding or accept the new default. + +The ``OLD`` behavior for this policy is to use the current locale as the +default encoding, which is also known as an ``OEM`` encoding. +The ``NEW`` behavior uses ``UTF-8`` as the default encoding. + +.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 4.4 +.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn +.. include:: include/STANDARD_ADVICE.rst + +.. include:: include/DEPRECATED.rst
diff --git a/Help/policy/CMP0214.rst b/Help/policy/CMP0214.rst new file mode 100644 index 0000000..f1e6db5 --- /dev/null +++ b/Help/policy/CMP0214.rst
@@ -0,0 +1,33 @@ +CMP0214 +------- + +.. versionadded:: 4.4 + +Honor ``CMAKE_EXE_LINKER_FLAGS`` for Swift executable targets. + +CMake 3.29 introduced :policy:`CMP0157`, which provides an abstraction +for selecting the Swift compilation mode. In CMake 3.30, +:variable:`CMAKE_SHARED_LINKER_FLAGS` was accidentally honored for +Swift shared library targets when :policy:`CMP0157` is ``NEW``, but +the change went unnoticed and was not documented. The corresponding +change was not made for Swift executable targets, leaving linker flag +handling inconsistent between Swift executables and Swift shared +libraries in CMake 3.30 through 4.3. + +CMake 4.4 and above prefer to honor :variable:`CMAKE_EXE_LINKER_FLAGS` +for Swift executable targets when :policy:`CMP0157` is set to ``NEW``, +restoring consistency with Swift shared library targets. This policy +provides compatibility for projects that have not been updated to +expect ``CMAKE_EXE_LINKER_FLAGS`` to be honored for Swift executables. + +The ``OLD`` behavior for this policy is to not honor +:variable:`CMAKE_EXE_LINKER_FLAGS` for Swift executable targets. +The ``NEW`` behavior for this policy is to honor +:variable:`CMAKE_EXE_LINKER_FLAGS` for Swift executable targets +when :policy:`CMP0157` is set to ``NEW``. + +.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 4.4 +.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn +.. include:: include/STANDARD_ADVICE.rst + +.. include:: include/DEPRECATED.rst
diff --git a/Help/policy/CMP0215.rst b/Help/policy/CMP0215.rst new file mode 100644 index 0000000..7573597 --- /dev/null +++ b/Help/policy/CMP0215.rst
@@ -0,0 +1,39 @@ +CMP0215 +------- + +.. versionadded:: 4.4 + +:ref:`Ninja Generators` emit Swift modules separately from compilation. + +In CMake 4.3 and below, Swift targets built by :ref:`Ninja Generators` +emit ``.swiftmodule`` from the Swift compile edge together with object files. +Because Ninja treats a build edge as atomic, downstream Swift targets +must wait for compilation outputs to finish before they can use the module +interface. + +CMake 4.4 and above prefer to emit ``.swiftmodule`` from a dedicated +``-emit-module`` build edge so that downstream Swift targets can begin +compiling as soon as the module interface is available. This policy +provides compatibility with projects that have not been updated. + +The ``OLD`` behavior for this policy is to not emit modules separately. +The ``NEW`` behavior for this policy is to emit ``.swiftmodule`` from a +dedicated build edge for importable Swift targets by default. + +The :prop_tgt:`Swift_SEPARATE_MODULE_EMISSION` target property and +corresponding :variable:`CMAKE_Swift_SEPARATE_MODULE_EMISSION` variable +may be set to enable or disable the behavior on a per-target basis. + +.. note:: + + Separate module emission takes effect only when policy :policy:`CMP0157` + is set to ``NEW`` prior to the first :command:`project` or + :command:`enable_language` command that enables the Swift language. + The dedicated ``.swiftmodule`` edge is available only in the split + Swift build model. + +.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 4.4 +.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn +.. include:: include/STANDARD_ADVICE.rst + +.. include:: include/DEPRECATED.rst
diff --git a/Help/policy/CMP0216.rst b/Help/policy/CMP0216.rst new file mode 100644 index 0000000..814440f --- /dev/null +++ b/Help/policy/CMP0216.rst
@@ -0,0 +1,32 @@ +CMP0216 +------- + +.. versionadded:: 4.4 + +Swift targets have a default project name. + +CMake 4.3 and below did not compile Swift targets with ``-package-name``. +The package name is useful because Swift package access control makes types, +functions, and properties visible to other libraries within the same package, +but not from sources outside of the package. CMake 4.4 and above prefer to +pass ``-package-name`` by default using the :variable:`PROJECT_NAME` variable +value. This policy provides compatibility for projects that have not been +updated to expect a package name. + +.. note:: + + Package access control was added in Swift 5.8 and Xcode 15. This policy has + no effect when using an earlier version of Swift or Xcode. + +The ``OLD`` behavior for this policy is to build Swift source files without +passing a package-name. The ``NEW`` behavior for this policy is to build +Swift source files with a default package name from :variable:`PROJECT_NAME`. + +Regardless of whether this policy is set, the :prop_tgt:`Swift_PACKAGE_NAME` +target property may be set to explicitly specify or suppress a package name. + +.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 4.4 +.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn +.. include:: include/STANDARD_ADVICE.rst + +.. include:: include/DEPRECATED.rst
diff --git a/Help/policy/CMP0217.rst b/Help/policy/CMP0217.rst new file mode 100644 index 0000000..052b82c6 --- /dev/null +++ b/Help/policy/CMP0217.rst
@@ -0,0 +1,24 @@ +CMP0217 +------- + +.. versionadded:: 4.4 + +The :prop_dir:`MACROS` directory property does not exist anymore. + +In CMake 4.3 and below, the macros defined in a directory are registered in the +:prop_dir:`MACROS` directory property. However, the property does not have the +same scope as macros, so it does not represent the actual list of macros. +In CMake 4.4 and above, this property is not longer filled with the defined +macros. One may still use :command:`if(COMMAND myMacro) <if(COMMAND)>` to test +whether one exists. + +The ``OLD`` behavior for this policy is to store macros definition in the +:prop_dir:`MACROS` directory property. +The ``NEW`` behavior for this policy is to no longer manage the +:prop_dir:`MACROS` directory property. + +.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 4.4 +.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn +.. 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_dir/MACROS.rst b/Help/prop_dir/MACROS.rst index 245cc1b..7f1a7c5 100644 --- a/Help/prop_dir/MACROS.rst +++ b/Help/prop_dir/MACROS.rst
@@ -1,8 +1,4 @@ MACROS ------ -List of macro commands available in the current directory. - -This read-only property specifies the list of CMake macros currently -defined. It is intended for debugging purposes. See the :command:`macro` -command. +This directory property does not exist anymore. See policy :policy:`CMP0217`.
diff --git a/Help/prop_fs/BASE_DIRS.rst b/Help/prop_fs/BASE_DIRS.rst new file mode 100644 index 0000000..879d44d --- /dev/null +++ b/Help/prop_fs/BASE_DIRS.rst
@@ -0,0 +1,15 @@ +BASE_DIRS +--------- + +.. versionadded:: 4.4 + +List of base directories of the file set. The :command:`target_sources` command +sets or adds to the ``BASE_DIRS`` file set property and is the usual way to +manipulate it. + +Contents of ``BASE_DIRS`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +Any relative paths are considered relative to the target's source directory. No +two base directories for a file set may be sub-directories of each other. This +requirement must be met across all base directories added to a file set.
diff --git a/Help/prop_fs/COMPILE_DEFINITIONS.rst b/Help/prop_fs/COMPILE_DEFINITIONS.rst new file mode 100644 index 0000000..bc400bf --- /dev/null +++ b/Help/prop_fs/COMPILE_DEFINITIONS.rst
@@ -0,0 +1,37 @@ +COMPILE_DEFINITIONS +------------------- + +.. versionadded:: 4.4 + +Preprocessor definitions for compiling a source file. + +The ``COMPILE_DEFINITIONS`` property may be set to a semicolon-separated +list of preprocessor definitions using the syntax ``VAR`` or ``VAR=value``. +Function-style definitions are not supported. CMake will +automatically escape the value correctly for the native build system +(note that CMake language syntax may require escapes to specify some +values). + +CMake will automatically drop some definitions that are not supported +by the native build tool. :generator:`Xcode` does not support +per-configuration definitions on source files. + +.. include:: /include/COMPILE_DEFINITIONS_DISCLAIMER.rst + +Contents of ``COMPILE_DEFINITIONS`` may use :manual:`cmake-generator-expressions(7)` +with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. However, :generator:`Xcode` +does not support per-config per-source settings, so expressions +that depend on the build configuration are not allowed with that +generator. + +Related properties: + +* Use :prop_fs:`COMPILE_OPTIONS` to pass additional compile flags. +* Use :prop_fs:`INCLUDE_DIRECTORIES` to pass additional include directories. + +Related commands: + +* :command:`add_compile_definitions` for directory-wide settings +* :command:`target_compile_definitions` for target-specific settings +* :command:`set_source_files_properties` for source-specific settings
diff --git a/Help/prop_fs/COMPILE_OPTIONS.rst b/Help/prop_fs/COMPILE_OPTIONS.rst new file mode 100644 index 0000000..70614b1 --- /dev/null +++ b/Help/prop_fs/COMPILE_OPTIONS.rst
@@ -0,0 +1,36 @@ +COMPILE_OPTIONS +--------------- + +.. versionadded:: 4.4 + +List of additional options to pass to the compiler. + +This property holds a :ref:`semicolon-separated list <CMake Language Lists>` +of options and will be added to the list of compile flags when the sources of +this file set are built. The options will be added after target-wide options +and source level ones. + +Contents of ``COMPILE_OPTIONS`` may use "generator expressions" with the +syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual +for available expressions. However, :generator:`Xcode` +does not support per-config per-source settings, so expressions +that depend on the build configuration are not allowed with that +generator. + +Usage example: + +.. code-block:: cmake + + set_property(FILE_SET SOURCES TARGET foo PROPERTY + COMPILE_OPTIONS "-Wno-unused-parameter;-Wno-missing-field-initializer") + +Related properties: + +* Use :prop_fs:`COMPILE_DEFINITIONS` to pass additional preprocessor definitions. +* Use :prop_fs:`INCLUDE_DIRECTORIES` to pass additional include directories. + +Related commands: + +* :command:`add_compile_options` for directory-wide settings +* :command:`target_compile_options` for target-specific settings +* :command:`set_source_files_properties` for source-specific settings
diff --git a/Help/prop_fs/CXX_SCAN_FOR_MODULES.rst b/Help/prop_fs/CXX_SCAN_FOR_MODULES.rst new file mode 100644 index 0000000..f4c92a0 --- /dev/null +++ b/Help/prop_fs/CXX_SCAN_FOR_MODULES.rst
@@ -0,0 +1,20 @@ +CXX_SCAN_FOR_MODULES +-------------------- + +.. versionadded:: 4.4 + +``CXX_SCAN_FOR_MODULES`` is a boolean specifying whether CMake will scan the +file set's sources for C++ module dependencies. See also the +:prop_sf:`CXX_SCAN_FOR_MODULES` source file property and the +:prop_tgt:`CXX_SCAN_FOR_MODULES` target property settings. + +When this property is set ``ON``, CMake will scan the file set's sources at +build time and add module dependency information to the compile line as +necessary. When this property is set ``OFF``, CMake will not scan the sources +at build time. When this property is unset, the +:prop_sf:`CXX_SCAN_FOR_MODULES` source file property and +:prop_tgt:`CXX_SCAN_FOR_MODULES` target property are consulted, in that order. + +Note that scanning is only performed if C++20 or higher is enabled for the +target and the source uses the ``CXX`` language. Scanning for modules in +sources belonging to file sets of type ``CXX_MODULES`` is always performed.
diff --git a/Help/prop_fs/INCLUDE_DIRECTORIES.rst b/Help/prop_fs/INCLUDE_DIRECTORIES.rst new file mode 100644 index 0000000..fd940ec --- /dev/null +++ b/Help/prop_fs/INCLUDE_DIRECTORIES.rst
@@ -0,0 +1,31 @@ +INCLUDE_DIRECTORIES +------------------- + +.. versionadded:: 4.4 + +List of preprocessor include file search directories. + +This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of paths +and will be added to the list of include directories when the sources of this +file set are built. These directories will take precedence over directories +defined at target level and source level except for :generator:`Xcode` +generator due to technical limitations. + +Relative paths should not be added to this property directly. + +Contents of ``INCLUDE_DIRECTORIES`` may use "generator expressions" with +the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual +for available expressions. However, :generator:`Xcode` does not support +per-config per-source settings, so expressions that depend on the build +configuration are not allowed with that generator. + +Related properties: + +* Use :prop_fs:`COMPILE_DEFINITIONS` to pass additional preprocessor definitions. +* Use :prop_fs:`COMPILE_OPTIONS` to pass additional compile flags. + +Related commands: + +* :command:`include_directories` for directory-wide settings +* :command:`target_include_directories` for target-specific settings +* :command:`set_source_files_properties` for source-specific settings
diff --git a/Help/prop_fs/INDEPENDENT_FILES.rst b/Help/prop_fs/INDEPENDENT_FILES.rst new file mode 100644 index 0000000..8536276 --- /dev/null +++ b/Help/prop_fs/INDEPENDENT_FILES.rst
@@ -0,0 +1,33 @@ +INDEPENDENT_FILES +----------------- + +.. versionadded:: 4.4 + +``INDEPENDENT_FILES`` is a boolean specifying that any :prop_sf:`GENERATED` +sources in the file set are not necessary for the compilation of other sources +in the same target. Stated another way, these files are "independent" and their +presence is never necessary for compilation of other sources (e.g., via +``#include``). + +When this property is ``ON``, :ref:`Ninja Generators` will omit conservative +order-only dependencies that prevent a target's source files from compiling +before custom commands from the target's dependencies are finished, even if +those custom commands only produce sources independent from other sources in +the same target. +When this property is ``OFF``, :ref:`Ninja Generators` will apply conservative +order-only dependencies that prevent a target's source files from compiling +before custom commands from the target's dependencies are finished, even if +those custom commands only produce sources independent from other sources in +the same target. + +If this property is not defined, the following default will be applied: +* ``ON`` for ``CXX_MODULES`` file set type. +* ``OFF`` for all other file set types. + +In the case of the ``CXX_MODULES`` file set type, the only supported mode is +``ON``. So if the property is set to ``OFF``, it will be ignored. + +In the case of the ``HEADERS`` file set type, if the property is ``ON``, an +author warning will be emit because this mode is not supported. + +This property is effective only when the policy :policy:`CMP0154` is ``NEW``.
diff --git a/Help/prop_fs/INTERFACE_COMPILE_DEFINITIONS.rst b/Help/prop_fs/INTERFACE_COMPILE_DEFINITIONS.rst new file mode 100644 index 0000000..5c102ee --- /dev/null +++ b/Help/prop_fs/INTERFACE_COMPILE_DEFINITIONS.rst
@@ -0,0 +1,15 @@ +INTERFACE_COMPILE_DEFINITIONS +----------------------------- + +.. versionadded:: 4.4 + +.. |property_name| replace:: compile definitions +.. |command_name| replace:: :command:`set_property(FILE_SET)` +.. |PROPERTY_INTERFACE_NAME| replace:: ``INTERFACE_COMPILE_DEFINITIONS`` +.. include:: include/INTERFACE_BUILD_PROPERTY.rst + +Related properties: + +* Use :prop_fs:`INTERFACE_COMPILE_OPTIONS` to pass additional compile flags. +* Use :prop_fs:`INTERFACE_INCLUDE_DIRECTORIES` to pass additional include + directories.
diff --git a/Help/prop_fs/INTERFACE_COMPILE_OPTIONS.rst b/Help/prop_fs/INTERFACE_COMPILE_OPTIONS.rst new file mode 100644 index 0000000..cd30776 --- /dev/null +++ b/Help/prop_fs/INTERFACE_COMPILE_OPTIONS.rst
@@ -0,0 +1,16 @@ +INTERFACE_COMPILE_OPTIONS +------------------------- + +.. versionadded:: 4.4 + +.. |property_name| replace:: compile options +.. |command_name| replace:: :command:`set_property(FILE_SET)` +.. |PROPERTY_INTERFACE_NAME| replace:: ``INTERFACE_COMPILE_OPTIONS`` +.. include:: include/INTERFACE_BUILD_PROPERTY.rst + +Related properties: + +* Use :prop_fs:`INTERFACE_COMPILE_DEFINITIONS` to pass additional preprocessor + definitions. +* Use :prop_fs:`INTERFACE_INCLUDE_DIRECTORIES` to pass additional include + directories.
diff --git a/Help/prop_fs/INTERFACE_INCLUDE_DIRECTORIES.rst b/Help/prop_fs/INTERFACE_INCLUDE_DIRECTORIES.rst new file mode 100644 index 0000000..880a234 --- /dev/null +++ b/Help/prop_fs/INTERFACE_INCLUDE_DIRECTORIES.rst
@@ -0,0 +1,35 @@ +INTERFACE_INCLUDE_DIRECTORIES +----------------------------- + +.. versionadded:: 4.4 + +.. |property_name| replace:: include directories +.. |command_name| replace:: :command:`set_property(FILE_SET)` +.. |PROPERTY_INTERFACE_NAME| replace:: ``INTERFACE_INCLUDE_DIRECTORIES`` +.. include:: include/INTERFACE_BUILD_PROPERTY.rst + +Include directories usage requirements commonly differ between the build-tree +and the install-tree. The ``BUILD_INTERFACE`` and ``INSTALL_INTERFACE`` +generator expressions can be used to describe separate usage requirements +based on the usage location. Relative paths are allowed within the +``INSTALL_INTERFACE`` expression and are interpreted relative to the +installation prefix. For example: + +.. code-block:: cmake + + set_property(FILE_SET myfile_set TARGET mylib PROPERTY INTERFACE_INCLUDE_DIRECTORIES + $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib> + $<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib + ) + +Related properties: + +* Use :prop_fs:`INTERFACE_COMPILE_DEFINITIONS` to pass additional preprocessor + definitions. +* Use :prop_fs:`INTERFACE_COMPILE_OPTIONS` to pass additional compile flags. + +Creating Relocatable Packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. |INTERFACE_PROPERTY_LINK| replace:: ``INTERFACE_INCLUDE_DIRECTORIES`` +.. include:: /include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.rst
diff --git a/Help/prop_fs/INTERFACE_SOURCES.rst b/Help/prop_fs/INTERFACE_SOURCES.rst new file mode 100644 index 0000000..ca9e1c1 --- /dev/null +++ b/Help/prop_fs/INTERFACE_SOURCES.rst
@@ -0,0 +1,34 @@ +INTERFACE_SOURCES +----------------- + +.. versionadded:: 4.4 + +List of interface sources to compile into consuming targets. +The :command:`target_sources` command sets or adds to the ``INTERFACE_SOURCES`` +file set property for the file sets defined with the ``PUBLIC`` or +``INTERFACE`` keyword and is the usual way to manipulate it. + +Contents of ``INTERFACE_SOURCES`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +Each file must be in one of the base directories, or a subdirectory of one of +the base directories. + +If relative paths are specified, they are considered relative to the target's +source directory. + +The following behavior applies for the :prop_fs:`SOURCES` and +``INTERFACE_SOURCES`` file set properties, dependent on the value of the +:prop_fs:`SCOPE` file set property: + +``PRIVATE`` + Only the :prop_fs:`SOURCES` property can be set. Any change to the + ``INTERFACE_SOURCES`` property will be ignored. + +``PUBLIC`` + :prop_fs:`SOURCES` and ``INTERFACE_SOURCES`` properties will always have the + same content. + +``INTERFACE`` + Only the ``INTERFACE_SOURCES`` property can be set. Any change to the + :prop_fs:`SOURCES` property will be ignored.
diff --git a/Help/prop_fs/JOB_POOL_COMPILE.rst b/Help/prop_fs/JOB_POOL_COMPILE.rst new file mode 100644 index 0000000..b460aff --- /dev/null +++ b/Help/prop_fs/JOB_POOL_COMPILE.rst
@@ -0,0 +1,28 @@ +JOB_POOL_COMPILE +---------------- + +.. versionadded:: 4.4 + +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_sf:`JOB_POOL_COMPILE` and +:prop_tgt:`JOB_POOL_COMPILE` values for specific source files within a same +target. + +For instance: + +.. code-block:: cmake + + set_property(FILE_SET my_fileset TYPE SOURCE PROPERTY JOB_POOL_COMPILE two_jobs) + +This property is undefined by default. + +See Also +^^^^^^^^ + +* :prop_sf:`JOB_POOL_COMPILE` source file property +* :prop_tgt:`JOB_POOL_COMPILE` target property
diff --git a/Help/prop_fs/SCOPE.rst b/Help/prop_fs/SCOPE.rst new file mode 100644 index 0000000..e326e2e --- /dev/null +++ b/Help/prop_fs/SCOPE.rst
@@ -0,0 +1,10 @@ +SCOPE +----- + +.. versionadded:: 4.4 + +The scope of the file set. + +This read-only property can be used to retrieve the +:ref:`scope <Target Command Scope>` of the given file set. +It will be ``PRIVATE``, ``PUBLIC``, or ``INTERFACE``.
diff --git a/Help/prop_fs/SKIP_LINTING.rst b/Help/prop_fs/SKIP_LINTING.rst new file mode 100644 index 0000000..7c6546e --- /dev/null +++ b/Help/prop_fs/SKIP_LINTING.rst
@@ -0,0 +1,54 @@ +SKIP_LINTING +------------ + +.. versionadded:: 4.4 + +This property allows you to exclude a source files of the specific file set +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`, +: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 +file set, the mentioned linting tools will not be executed for the files of +that particular file set. If the :prop_fs:`SKIP_LINTING` file set property +is set, it takes precedence over this source-file and target-wide properties. + +This is a convenience alternative to setting the :prop_sf:`SKIP_LINTING` +source file property individually on each source. + +Example +^^^^^^^ + +Consider a C++ project that includes multiple source files, +such as ``main.cpp``, ``things.cpp``, and ``generatedBindings.cpp``. +In this example, you want to exclude the ``things.cpp`` and +``generatedBindings.cpp`` files from the linting process. To achieve this, you +can use a file set and utilize the ``SKIP_LINTING`` property with the +:command:`set_property(FILE_SET) <set_property>` command as shown below: + +.. code-block:: cmake + + add_executable(MyApp main.cpp) + target_sources(MyApp PRIVATE FILE_SET skip_lint TYPE SOURCES + FILES things.cpp generatedBindings.cpp) + + set_property(FILE_SET skip_lint TARGET MyApp PROPERTY SKIP_LINTING ON) + +In the provided code snippet, the ``SKIP_LINTING`` property is set to true +for the ``skip_lint`` file set. As a result, when the linting +tools specified by :prop_tgt:`<LANG>_CPPLINT`, :prop_tgt:`<LANG>_CLANG_TIDY`, +:prop_tgt:`<LANG>_CPPCHECK`, :prop_tgt:`<LANG>_ICSTAT` or +:prop_tgt:`<LANG>_INCLUDE_WHAT_YOU_USE` are executed, they will skip analyzing +the ``things.cpp`` and ``generatedBindings.cpp`` files. + +By using the ``SKIP_LINTING`` file set property, you can selectively exclude +specific 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_sf:`SKIP_LINTING` source file property +* :prop_tgt:`SKIP_LINTING` target property
diff --git a/Help/prop_fs/SOURCES.rst b/Help/prop_fs/SOURCES.rst new file mode 100644 index 0000000..da97c59 --- /dev/null +++ b/Help/prop_fs/SOURCES.rst
@@ -0,0 +1,32 @@ +SOURCES +------- + +.. versionadded:: 4.4 + +This specifies the list of paths to sources for the file set. +The :command:`target_sources` command sets or adds to the ``SOURCES`` file set +property for the file sets defined with the ``PRIVATE`` or ``PUBLIC`` keyword +and is the usual way to manipulate it. + +Contents of ``SOURCES`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +Each file must be in one of the base directories, or a subdirectory of one of +the base directories. If relative paths are specified, they are considered +relative to the target's source directory. + +The following behavior applies for the ``SOURCES`` and +:prop_fs:`INTERFACE_SOURCES` file set properties, dependent on the value of the +:prop_fs:`SCOPE` file set property: + +``PRIVATE`` + Only the ``SOURCES`` property can be set. Any change to + the :prop_fs:`INTERFACE_SOURCES` property will be ignored. + +``PUBLIC`` + ``SOURCES`` and :prop_fs:`INTERFACE_SOURCES` properties will always have the + same content. + +``INTERFACE`` + Only the :prop_fs:`INTERFACE_SOURCES` property can be set. Any change to + ``SOURCES`` property will be ignored.
diff --git a/Help/prop_fs/TYPE.rst b/Help/prop_fs/TYPE.rst new file mode 100644 index 0000000..83a1005 --- /dev/null +++ b/Help/prop_fs/TYPE.rst
@@ -0,0 +1,10 @@ +TYPE +---- + +.. versionadded:: 4.4 + +The type of the file set. + +This read-only property can be used to retrieve the +:ref:`type <File Sets>` of the given file set. +Possible values are ``CXX_MODULES``, ``SOURCES``, or ``HEADERS``.
diff --git a/Help/prop_fs/include/INTERFACE_BUILD_PROPERTY.rst b/Help/prop_fs/include/INTERFACE_BUILD_PROPERTY.rst new file mode 100644 index 0000000..dba863c --- /dev/null +++ b/Help/prop_fs/include/INTERFACE_BUILD_PROPERTY.rst
@@ -0,0 +1,16 @@ +List of public |property_name| requirements for a file set. + +File sets may populate this property to publish the |property_name| +required to compile the sources for the target. The |command_name| +command populates this property. + +When target dependencies are specified using :command:`target_link_libraries`, +CMake will read this property from file sets of all target dependencies to +determine the build properties of the consumer. These build properties are only +applied to the sources of the file sets. The other sources of the consumer are +unaffected. + +Contents of |PROPERTY_INTERFACE_NAME| may use "generator expressions" +with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. See the :manual:`cmake-buildsystem(7)` +-manual for more on defining buildsystem properties.
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/CXX_SCAN_FOR_MODULES.rst b/Help/prop_sf/CXX_SCAN_FOR_MODULES.rst index d10969a..318a8e2 100644 --- a/Help/prop_sf/CXX_SCAN_FOR_MODULES.rst +++ b/Help/prop_sf/CXX_SCAN_FOR_MODULES.rst
@@ -5,12 +5,14 @@ ``CXX_SCAN_FOR_MODULES`` is a boolean specifying whether CMake will scan the source for C++ module dependencies. See also the -:prop_tgt:`CXX_SCAN_FOR_MODULES` for target-wide settings. +:prop_fs:`CXX_SCAN_FOR_MODULES` file set property which, if set, +overrides the per-source settings and the +:prop_tgt:`CXX_SCAN_FOR_MODULES` target property. When this property is set ``ON``, CMake will scan the source at build time and add module dependency information to the compile line as necessary. When this property is set ``OFF``, CMake will not scan the source at build time. When -this property is unset, the :prop_tgt:`CXX_SCAN_FOR_MODULES` property is +this property is unset, the :prop_tgt:`CXX_SCAN_FOR_MODULES` target property is consulted. Note that scanning is only performed if C++20 or higher is enabled for the
diff --git a/Help/prop_sf/HEADER_FILE_ONLY.rst b/Help/prop_sf/HEADER_FILE_ONLY.rst index 71d62ae..4575fab 100644 --- a/Help/prop_sf/HEADER_FILE_ONLY.rst +++ b/Help/prop_sf/HEADER_FILE_ONLY.rst
@@ -4,7 +4,7 @@ Is this source file only a header file. A property on a source file that indicates if the source file is a -header file with no associated implementation. This is set +header file that should not be compiled into an object file. This is set automatically based on the file extension and is used by CMake to determine if certain dependency information should be computed.
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..2c9a8d4 --- /dev/null +++ b/Help/prop_sf/JOB_POOL_COMPILE.rst
@@ -0,0 +1,27 @@ +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. + +See Also +^^^^^^^^ + +* :prop_fs:`JOB_POOL_COMPILE` file set property +* :prop_tgt:`JOB_POOL_COMPILE` target property
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/Rust_EMIT.rst b/Help/prop_sf/Rust_EMIT.rst new file mode 100644 index 0000000..548a485 --- /dev/null +++ b/Help/prop_sf/Rust_EMIT.rst
@@ -0,0 +1,39 @@ +Rust_EMIT +--------- + +.. versionadded:: 4.4 + +.. note:: + Experimental. Gated by ``CMAKE_EXPERIMENTAL_RUST``. + +This property controls the type of output generated by the Rust compiler. Can +be one of several values: + +``link`` + This is the default if the property is not set. The crate will be compiled + into an `rlib` file, e.g.: ``libfile.rs.rlib`` + + .. note:: + CMake will automatically prefix the generated ``rlib`` file + with ``lib`` as the Rust compiler always requires such a + prefix for external crates. + +``obj`` + Generate a native object file, e.g.: ``file.rs.o`` + +``asm`` + Generate an assembly file, e.g.: ``file.rs.s`` + +.. note:: + The ``obj`` and ``asm`` output types are known to have the following + limitations: + + * When enabled, the Rust compiler disables multiple codegen units and + ThinLTO. Depending on the situation, this can affect the generated code, + optimizations. It also reduce the internal parallelism inside and the + compiler and can reduce the effectiveness of incremental rebuilds. + * The generated ``obj`` files cannot be used as external crates, so other + Rust code can only use C-style API from them. + * The generated ``obj`` files cannot be linked as-is with native linkers, + additional crates from the Rust toolchain needs to linked too. The actual + crates to link depend on the code and compiler options.
diff --git a/Help/prop_sf/SKIP_LINTING.rst b/Help/prop_sf/SKIP_LINTING.rst index fe0f2d4..07e5cd1 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,12 @@ 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. + +A convenient alternative, when multiple sources should be excluded from the +linting process, is to use the file set's :prop_fs:`SKIP_LINTING` property. + +See Also +^^^^^^^^ + +* :prop_fs:`SKIP_LINTING` file set property +* :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_SCAN_FOR_MODULES.rst b/Help/prop_tgt/CXX_SCAN_FOR_MODULES.rst index 791914e..d61846d 100644 --- a/Help/prop_tgt/CXX_SCAN_FOR_MODULES.rst +++ b/Help/prop_tgt/CXX_SCAN_FOR_MODULES.rst
@@ -5,7 +5,8 @@ ``CXX_SCAN_FOR_MODULES`` is a boolean specifying whether CMake will scan C++ sources in the target for module dependencies. See also the -:prop_sf:`CXX_SCAN_FOR_MODULES` for per-source settings which, if set, +:prop_sf:`CXX_SCAN_FOR_MODULES` for per-source settings and +:prop_fs:`CXX_SCAN_FOR_MODULES` for file set settings. If either is set, it overrides the target-wide settings. This property is initialized by the value of the
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/INTERFACE_SOURCE_SETS.rst b/Help/prop_tgt/INTERFACE_SOURCE_SETS.rst new file mode 100644 index 0000000..4aba928 --- /dev/null +++ b/Help/prop_tgt/INTERFACE_SOURCE_SETS.rst
@@ -0,0 +1,14 @@ +INTERFACE_SOURCE_SETS +--------------------- + +.. versionadded:: 4.4 + +Read-only list of the target's ``INTERFACE`` and ``PUBLIC`` source sets (i.e. +all file sets with the type ``SOURCES``). Files listed in these source sets +can be installed with :command:`install(TARGETS)` and exported with +:command:`install(EXPORT)` and :command:`export`. + +Source sets may be defined using the :command:`target_sources` command +``FILE_SET`` option with type ``SOURCES``. + +See also :prop_tgt:`SOURCE_SETS`.
diff --git a/Help/prop_tgt/JOB_POOL_COMPILE.rst b/Help/prop_tgt/JOB_POOL_COMPILE.rst index 5d8e940..d70b010 100644 --- a/Help/prop_tgt/JOB_POOL_COMPILE.rst +++ b/Help/prop_tgt/JOB_POOL_COMPILE.rst
@@ -15,3 +15,9 @@ This property is initialized by the value of :variable:`CMAKE_JOB_POOL_COMPILE`. + +See Also +^^^^^^^^ + +* :prop_fs:`JOB_POOL_COMPILE` file set property +* :prop_sf:`JOB_POOL_COMPILE` source file property
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/LINK_WARNING_AS_ERROR.rst b/Help/prop_tgt/LINK_WARNING_AS_ERROR.rst index c3f7566..cd812cd 100644 --- a/Help/prop_tgt/LINK_WARNING_AS_ERROR.rst +++ b/Help/prop_tgt/LINK_WARNING_AS_ERROR.rst
@@ -35,6 +35,7 @@ * ``MOLD`` * ``MSVC`` * ``Solaris`` +* ``WILD`` This property is initialized by the value of the variable :variable:`CMAKE_LINK_WARNING_AS_ERROR` if it is set when a target is
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/Rust_EDITION.rst b/Help/prop_tgt/Rust_EDITION.rst new file mode 100644 index 0000000..454b1b1 --- /dev/null +++ b/Help/prop_tgt/Rust_EDITION.rst
@@ -0,0 +1,25 @@ +Rust_EDITION +------------ + +.. versionadded:: 4.4 + +.. note:: + Experimental. Gated by ``CMAKE_EXPERIMENTAL_RUST``. + +The Rust edition required to build this target. It is initialized from the +:variable:`CMAKE_Rust_EDITION` variable if defined. Setting this property +results in adding a flag such as ``--edition=2018`` to the compile line. + +Supported values are: + +``2015`` + Rust 2015, the default edition, started with Rust 1.0. + +``2018`` + Rust 2018, available since Rust 1.31. + +``2021`` + Rust 2021, available since Rust 1.56. + +``2024`` + Rust 2024, available since Rust 1.85.
diff --git a/Help/prop_tgt/SKIP_LINTING.rst b/Help/prop_tgt/SKIP_LINTING.rst new file mode 100644 index 0000000..996c4ee --- /dev/null +++ b/Help/prop_tgt/SKIP_LINTING.rst
@@ -0,0 +1,28 @@ +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 or if the :prop_fs:`SKIP_LINTING` file set property +is set, 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 file set's :prop_fs:`SKIP_LINTING` including this +source 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_fs:`SKIP_LINTING` file set property +* :prop_sf:`SKIP_LINTING` source file property
diff --git a/Help/prop_tgt/SOURCE_DIRS.rst b/Help/prop_tgt/SOURCE_DIRS.rst new file mode 100644 index 0000000..4442aa5 --- /dev/null +++ b/Help/prop_tgt/SOURCE_DIRS.rst
@@ -0,0 +1,14 @@ +SOURCE_DIRS +----------- + +.. versionadded:: 4.4 + +Semicolon-separated list of base directories of the target's default +source set (i.e. the file set with name and type ``SOURCES``). The property +supports :manual:`generator expressions <cmake-generator-expressions(7)>`. + +This property is normally only set by :command:`target_sources(FILE_SET)` +rather than being manipulated directly. + +See :prop_tgt:`SOURCE_DIRS_<NAME>` for the list of base directories in +other source sets.
diff --git a/Help/prop_tgt/SOURCE_DIRS_NAME.rst b/Help/prop_tgt/SOURCE_DIRS_NAME.rst new file mode 100644 index 0000000..22f198f --- /dev/null +++ b/Help/prop_tgt/SOURCE_DIRS_NAME.rst
@@ -0,0 +1,15 @@ +SOURCE_DIRS_<NAME> +------------------ + +.. versionadded:: 4.4 + +Semicolon-separated list of base directories of the target's ``<NAME>`` +source set, which has the set type ``SOURCES``. The property supports +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +This property is normally only set by :command:`target_sources(FILE_SET)` +rather than being manipulated directly. + +See :prop_tgt:`SOURCE_DIRS` for the list of base directories in the +default source set. See :prop_tgt:`SOURCE_SETS` for the file set names of all +source sets.
diff --git a/Help/prop_tgt/SOURCE_SET.rst b/Help/prop_tgt/SOURCE_SET.rst new file mode 100644 index 0000000..c7f517e --- /dev/null +++ b/Help/prop_tgt/SOURCE_SET.rst
@@ -0,0 +1,15 @@ +SOURCE_SET +---------- + +.. versionadded:: 4.4 + +Semicolon-separated list of files in the target's default source set, +(i.e. the file set with name and type ``SOURCES``). If any of the paths +are relative, they are computed relative to the target's source directory. +The property supports +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +This property is normally only set by :command:`target_sources(FILE_SET)` +rather than being manipulated directly. + +See :prop_tgt:`SOURCE_SET_<NAME>` for the list of files in other source sets.
diff --git a/Help/prop_tgt/SOURCE_SETS.rst b/Help/prop_tgt/SOURCE_SETS.rst new file mode 100644 index 0000000..b6fad22 --- /dev/null +++ b/Help/prop_tgt/SOURCE_SETS.rst
@@ -0,0 +1,14 @@ +SOURCE_SETS +----------- + +.. versionadded:: 4.4 + +Read-only list of the target's ``PRIVATE`` and ``PUBLIC`` source sets (i.e. +all file sets with the type ``SOURCES``). Files listed in these file sets are +treated as source files. + +Source sets may be defined using the :command:`target_sources` command +``FILE_SET`` option with type ``SOURCES``. + +See also :prop_tgt:`SOURCE_SET_<NAME>`, :prop_tgt:`SOURCE_SET` and +:prop_tgt:`INTERFACE_SOURCE_SETS`.
diff --git a/Help/prop_tgt/SOURCE_SET_NAME.rst b/Help/prop_tgt/SOURCE_SET_NAME.rst new file mode 100644 index 0000000..9eef526 --- /dev/null +++ b/Help/prop_tgt/SOURCE_SET_NAME.rst
@@ -0,0 +1,15 @@ +SOURCE_SET_<NAME> +----------------- + +.. versionadded:: 4.4 + +Semicolon-separated list of files in the target's ``<NAME>`` source set, +which has the set type ``SOURCES``. If any of the paths are relative, +they are computed relative to the target's source directory. The property +supports :manual:`generator expressions <cmake-generator-expressions(7)>`. + +This property is normally only set by :command:`target_sources(FILE_SET)` +rather than being manipulated directly. + +See :prop_tgt:`SOURCE_SET` for the list of files in the default source set. +See :prop_tgt:`SOURCE_SETS` for the file set names of all source sets.
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/Swift_MODULE_NAME.rst b/Help/prop_tgt/Swift_MODULE_NAME.rst index d941b54..8e7ee6b 100644 --- a/Help/prop_tgt/Swift_MODULE_NAME.rst +++ b/Help/prop_tgt/Swift_MODULE_NAME.rst
@@ -4,4 +4,5 @@ .. versionadded:: 3.15 This property specifies the name of the Swift module. It is defaulted to the -name of the target. +name of the target, with hyphens replaced by underscores (hyphens are not valid +in Swift module identifiers).
diff --git a/Help/prop_tgt/Swift_PACKAGE_NAME.rst b/Help/prop_tgt/Swift_PACKAGE_NAME.rst new file mode 100644 index 0000000..539e033 --- /dev/null +++ b/Help/prop_tgt/Swift_PACKAGE_NAME.rst
@@ -0,0 +1,21 @@ +Swift_PACKAGE_NAME +------------------ + +.. versionadded:: 4.4 + +Specify the Swift package name for a target. + +This property sets the package name passed to the Swift compiler via the +``-package-name`` flag, which enables the package access control in Swift +code. + +.. note:: + + Package access control was added in Swift 5.8 and Xcode 15. This target + property has no effect when using an earlier version of Swift or Xcode. + +If the property is not set, the :variable:`PROJECT_NAME` variable is used +as the default package name. See policy :policy:`CMP0216`. + +Setting this property to the empty string will result in the target being +compiled without a package name.
diff --git a/Help/prop_tgt/Swift_SEPARATE_MODULE_EMISSION.rst b/Help/prop_tgt/Swift_SEPARATE_MODULE_EMISSION.rst new file mode 100644 index 0000000..81c61b6 --- /dev/null +++ b/Help/prop_tgt/Swift_SEPARATE_MODULE_EMISSION.rst
@@ -0,0 +1,24 @@ +Swift_SEPARATE_MODULE_EMISSION +------------------------------ + +.. versionadded:: 4.4 + +Emit Swift modules separately from compilation in the :ref:`Ninja Generators`. + +When this property is set to ``ON`` on an importable Swift target built by +:ref:`Ninja Generators`, CMake emits a separate ``-emit-module`` build edge +that produces the ``.swiftmodule`` independently of object compilation. +This allows downstream Swift targets to begin compiling as soon as the +module interface is available, rather than waiting for all upstream +compilation outputs. + +The property is initialized from the value of the +:variable:`CMAKE_Swift_SEPARATE_MODULE_EMISSION` variable, if it is set. +If this property is not set, separate module emission is enabled by default. +See policy :policy:`CMP0215`. + +.. note:: + + Separate module emission takes effect only when policy :policy:`CMP0157` + is set to ``NEW`` prior to the first :command:`project` or + :command:`enable_language` command that enables the Swift language.
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..59cd104 100644 --- a/Help/prop_tgt/VERIFY_INTERFACE_HEADER_SETS.rst +++ b/Help/prop_tgt/VERIFY_INTERFACE_HEADER_SETS.rst
@@ -3,39 +3,35 @@ .. versionadded:: 3.24 +.. versionchanged:: 4.4 + ``OBJC`` and ``OBJCXX`` languages are now supported in addition to ``C`` + and ``CXX``. + Used to verify that all headers in a target's ``PUBLIC`` and ``INTERFACE`` header sets can be included on their own. +.. versionchanged:: 4.4 + Previously, the verification target was only created when the target had + at least one matching header. Now it is always created when the property + is enabled. + 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`), an object library target named +``<target_name>_verify_interface_header_sets`` is created. This verification +target has one source file per header in the target's ``PUBLIC`` and +``INTERFACE`` header sets. Each source file only includes its associated +header file. If the target has no matching header sets, a utility target is +created instead so that the target name always exists for build system +dependencies. +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..889a207 --- /dev/null +++ b/Help/prop_tgt/VERIFY_PRIVATE_HEADER_SETS.rst
@@ -0,0 +1,44 @@ +VERIFY_PRIVATE_HEADER_SETS +-------------------------- + +.. versionadded:: 4.3 + +.. versionchanged:: 4.4 + ``OBJC`` and ``OBJCXX`` languages are now supported in addition to ``C`` + and ``CXX``. + +Used to verify that all headers in a target's ``PUBLIC`` and ``PRIVATE`` +header sets can be included on their own. + +.. versionchanged:: 4.4 + Previously, the verification target was only created when the target had + at least one matching header. Now it is always created when the property + is enabled. + +When this property is set to true, and the target is an object library, static +library, shared library, module library, interface library, or executable, an +object library target named ``<target_name>_verify_private_header_sets`` is +created. This verification target has one source file per header in the +target's ``PUBLIC`` and ``PRIVATE`` header sets. Each source file only +includes its associated header file. If the target has no matching header +sets, a utility target is created instead so that the target name always +exists for build system dependencies. + +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/VS_SOLUTION_DEPLOY.rst b/Help/prop_tgt/VS_SOLUTION_DEPLOY.rst index e56f411..6c19012 100644 --- a/Help/prop_tgt/VS_SOLUTION_DEPLOY.rst +++ b/Help/prop_tgt/VS_SOLUTION_DEPLOY.rst
@@ -11,6 +11,10 @@ :manual:`Generator expressions <cmake-generator-expressions(7)>` are supported. +.. versionadded:: 4.4 + + Targets created by :command:`add_custom_target` now honor this property. + Examples ^^^^^^^^
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..b8e8d07 --- /dev/null +++ b/Help/prop_tgt/include/VERIFY_XXX_HEADER_SETS.rst
@@ -0,0 +1,38 @@ +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. +The supported languages are ``C``, ``CXX``, ``OBJC``, and ``OBJCXX``. +If the language is not one of those four, the header file is not compiled. + +Otherwise, the language is inferred from the target's sources using the +following precedence: ``OBJCXX`` takes priority over all others; if both +``CXX`` and ``OBJC`` sources are present, the header is compiled as +``OBJCXX``; otherwise ``CXX`` takes precedence over ``OBJC``, and ``OBJC`` +takes precedence over ``C``. If no matching sources are found, the same +precedence is applied to the globally enabled languages. If no supported +language is found, 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. + +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.23.rst b/Help/release/3.23.rst index 20e43c5..ece6941 100644 --- a/Help/release/3.23.rst +++ b/Help/release/3.23.rst
@@ -19,7 +19,7 @@ which allows the files to include other files. * :manual:`cmake-presets(7)` files now support a ``${fileDir}`` macro, which - contains the directory containing the preset file. + contains the directory containing the presets file. * :manual:`cmake-presets(7)` gained support for specifying the ``resolvePackageReferences`` command line option in a build preset to control
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/dev/0-sample-topic.rst b/Help/release/dev/0-sample-topic.rst new file mode 100644 index 0000000..e4cc01e --- /dev/null +++ b/Help/release/dev/0-sample-topic.rst
@@ -0,0 +1,7 @@ +0-sample-topic +-------------- + +* This is a sample release note for the change in a topic. + Developers should add similar notes for each topic branch + making a noteworthy change. Each document should be named + and titled to match the topic name to avoid merge conflicts.
diff --git a/Help/release/dev/CMAKE_INSTALL_DEFAULT_COMPONENT_NAME-project-name-placeholder.rst b/Help/release/dev/CMAKE_INSTALL_DEFAULT_COMPONENT_NAME-project-name-placeholder.rst new file mode 100644 index 0000000..37dc626 --- /dev/null +++ b/Help/release/dev/CMAKE_INSTALL_DEFAULT_COMPONENT_NAME-project-name-placeholder.rst
@@ -0,0 +1,7 @@ +CMAKE_INSTALL_DEFAULT_COMPONENT_NAME-project-name-placeholder +------------------------------------------------------------- + +* :variable:`CMAKE_INSTALL_DEFAULT_COMPONENT_NAME` gained support for a + special ``<PROJECT_NAME>`` placeholder value. It tells each + :command:`install` invocation to take a default component name + from the current :variable:`PROJECT_NAME` variable value.
diff --git a/Help/release/dev/CPACK_RPM_SPEC_MORE_DEFINE.rst b/Help/release/dev/CPACK_RPM_SPEC_MORE_DEFINE.rst new file mode 100644 index 0000000..e2c4a0f --- /dev/null +++ b/Help/release/dev/CPACK_RPM_SPEC_MORE_DEFINE.rst
@@ -0,0 +1,4 @@ +CPACK_RPM_SPEC_MORE_DEFINE +-------------------------- + +* The :variable:`CPACK_RPM_SPEC_MORE_DEFINE` could be a list of definitions.
diff --git a/Help/release/dev/ExternalData-link-mode.rst b/Help/release/dev/ExternalData-link-mode.rst new file mode 100644 index 0000000..f341e58 --- /dev/null +++ b/Help/release/dev/ExternalData-link-mode.rst
@@ -0,0 +1,7 @@ +ExternalData-link-mode +---------------------- + +* The :module:`ExternalData` module gained an + :variable:`ExternalData_LINK_MODE` variable to select an ordered list + of file materialization modes for hard links, symbolic links, and + copies.
diff --git a/Help/release/dev/ExternalData-state-dir.rst b/Help/release/dev/ExternalData-state-dir.rst new file mode 100644 index 0000000..df61d4d --- /dev/null +++ b/Help/release/dev/ExternalData-state-dir.rst
@@ -0,0 +1,6 @@ +ExternalData-state-dir +---------------------- + +* The :module:`ExternalData` module gained an + :variable:`ExternalData_STATE_ROOT` variable to store hash records outside + :variable:`ExternalData_BINARY_ROOT`.
diff --git a/Help/release/dev/ExternalProject-git-clone-retry.rst b/Help/release/dev/ExternalProject-git-clone-retry.rst new file mode 100644 index 0000000..fafe1a6 --- /dev/null +++ b/Help/release/dev/ExternalProject-git-clone-retry.rst
@@ -0,0 +1,7 @@ +ExternalProject-git-clone-retry +------------------------------- + +* The :module:`ExternalProject` and :module:`FetchContent` modules gained + :variable:`CMAKE_EP_GIT_CLONE_RETRY_COUNT` and + :variable:`CMAKE_EP_GIT_CLONE_RETRY_DELAY` variables to control + ``git clone`` retries.
diff --git a/Help/release/dev/FILE_SET-CXX_SCAN_FOR_MODULES.rst b/Help/release/dev/FILE_SET-CXX_SCAN_FOR_MODULES.rst new file mode 100644 index 0000000..8e963d4 --- /dev/null +++ b/Help/release/dev/FILE_SET-CXX_SCAN_FOR_MODULES.rst
@@ -0,0 +1,5 @@ +FILE_SET-CXX_SCAN_FOR_MODULES +----------------------------- + +* :ref:`File sets <file sets>` learned to support the + :prop_fs:`CXX_SCAN_FOR_MODULES` property.
diff --git a/Help/release/dev/FILE_SET-INDEPENDENT_FILES.rst b/Help/release/dev/FILE_SET-INDEPENDENT_FILES.rst new file mode 100644 index 0000000..1274c68 --- /dev/null +++ b/Help/release/dev/FILE_SET-INDEPENDENT_FILES.rst
@@ -0,0 +1,5 @@ +FILE_SET-INDEPENDENT_FILES +-------------------------- + +* :ref:`File sets <file sets>` learned to support the + :prop_fs:`INDEPENDENT_FILES` property.
diff --git a/Help/release/dev/FILE_SET-JOB_POOL_COMPILE.rst b/Help/release/dev/FILE_SET-JOB_POOL_COMPILE.rst new file mode 100644 index 0000000..fe30570 --- /dev/null +++ b/Help/release/dev/FILE_SET-JOB_POOL_COMPILE.rst
@@ -0,0 +1,5 @@ +FILE_SET-JOB_POOL_COMPILE +------------------------- + +* File sets gained the support of the :prop_fs:`JOB_POOL_COMPILE` file set + property.
diff --git a/Help/release/dev/FILE_SET-SKIP_LINTING.rst b/Help/release/dev/FILE_SET-SKIP_LINTING.rst new file mode 100644 index 0000000..eeca0cd --- /dev/null +++ b/Help/release/dev/FILE_SET-SKIP_LINTING.rst
@@ -0,0 +1,5 @@ +FILE_SET-SKIP_LINTING +--------------------- + +* File sets gained the support of the :prop_fs:`SKIP_LINTING` file set + property.
diff --git a/Help/release/dev/FILE_SET-SOURCES.rst b/Help/release/dev/FILE_SET-SOURCES.rst new file mode 100644 index 0000000..feb4902 --- /dev/null +++ b/Help/release/dev/FILE_SET-SOURCES.rst
@@ -0,0 +1,4 @@ +FILE_SET-SOURCES +---------------- + +* The :ref:`file set <file sets>` gains the support of the ``SOURCES`` type.
diff --git a/Help/release/dev/FILE_SET-enforce-files-unicity.rst b/Help/release/dev/FILE_SET-enforce-files-unicity.rst new file mode 100644 index 0000000..30e4ac4 --- /dev/null +++ b/Help/release/dev/FILE_SET-enforce-files-unicity.rst
@@ -0,0 +1,5 @@ +FILE_SET-enforce-files-unicity +------------------------------ + +* A file may belong to at most one :ref:`file set <file sets>` in a target. + See policy :policy:`CMP0211`.
diff --git a/Help/release/dev/FILE_SET-new-properties.rst b/Help/release/dev/FILE_SET-new-properties.rst new file mode 100644 index 0000000..764e2cc --- /dev/null +++ b/Help/release/dev/FILE_SET-new-properties.rst
@@ -0,0 +1,6 @@ +FILE_SET-new-properties +----------------------- + +* File sets gained support for the :prop_fs:`SCOPE`, :prop_fs:`TYPE`, + :prop_fs:`BASE_DIRS`, :prop_fs:`SOURCES`, and + :prop_fs:`INTERFACE_SOURCES` file set properties.
diff --git a/Help/release/dev/FindPython-PEP803.rst b/Help/release/dev/FindPython-PEP803.rst new file mode 100644 index 0000000..a6a7116 --- /dev/null +++ b/Help/release/dev/FindPython-PEP803.rst
@@ -0,0 +1,6 @@ +FindPython-PEP803 +----------------- + +* :module:`FindPython` and :module:`FindPython3` modules gained the support of + the Stable ABI for Free Threaded Python (``SABIT``) as specified by + :pep:`803`.
diff --git a/Help/release/dev/MACROS-directory-property.rst b/Help/release/dev/MACROS-directory-property.rst new file mode 100644 index 0000000..314310b --- /dev/null +++ b/Help/release/dev/MACROS-directory-property.rst
@@ -0,0 +1,5 @@ +MACROS-directory-property +------------------------- + +* The :prop_dir:`MACROS` directory property does not exist anymore. See policy + :policy:`CMP0217`.
diff --git a/Help/release/dev/OpenWatcom-linker-id.rst b/Help/release/dev/OpenWatcom-linker-id.rst new file mode 100644 index 0000000..6bc05bd --- /dev/null +++ b/Help/release/dev/OpenWatcom-linker-id.rst
@@ -0,0 +1,5 @@ +openwatcom-linker-id +-------------------- + +* The :variable:`CMAKE_<LANG>_COMPILER_LINKER_ID` variable learned to detect + the OpenWatcom ``wlink`` linker.
diff --git a/Help/release/dev/Wild-linker.rst b/Help/release/dev/Wild-linker.rst new file mode 100644 index 0000000..5bcd8d9 --- /dev/null +++ b/Help/release/dev/Wild-linker.rst
@@ -0,0 +1,5 @@ +Wild-linker +----------- + +* CMake gains the support of the + `wild linker <https://github.com/wild-linker/wild>`_.
diff --git a/Help/release/dev/add_custom_command-DEPENDS-exe.rst b/Help/release/dev/add_custom_command-DEPENDS-exe.rst new file mode 100644 index 0000000..02bb71b --- /dev/null +++ b/Help/release/dev/add_custom_command-DEPENDS-exe.rst
@@ -0,0 +1,6 @@ +add_custom_command-DEPENDS-exe +------------------------------ + +* Names of executables given to the ``DEPENDS`` argument of + :command:`add_custom_command` no longer have ``.exe`` suffixes stripped to + establish target-level dependencies. See policy :policy:`CMP0212`.
diff --git a/Help/release/dev/always-create-all-verify-targets.rst b/Help/release/dev/always-create-all-verify-targets.rst new file mode 100644 index 0000000..a634265 --- /dev/null +++ b/Help/release/dev/always-create-all-verify-targets.rst
@@ -0,0 +1,9 @@ +always-create-all-verify-targets +--------------------------------- + +* The :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` and + :prop_tgt:`VERIFY_PRIVATE_HEADER_SETS` target properties now always + create the per-target verification target and the aggregate + ``all_verify_interface_header_sets``, ``all_verify_private_header_sets``, + and ``all_verify_header_sets`` targets when the property is enabled, + even if the target has no matching header sets.
diff --git a/Help/release/dev/clang-cl-cxxmodules.rst b/Help/release/dev/clang-cl-cxxmodules.rst new file mode 100644 index 0000000..7a3a23f --- /dev/null +++ b/Help/release/dev/clang-cl-cxxmodules.rst
@@ -0,0 +1,5 @@ +clang-cl-cxxmodules +------------------- + +* C++ 20 named modules are now supported with ``clang-cl``. + See :manual:`cmake-cxxmodules(7)`.
diff --git a/Help/release/dev/cmake-E-copy-t-flag.rst b/Help/release/dev/cmake-E-copy-t-flag.rst new file mode 100644 index 0000000..178292c --- /dev/null +++ b/Help/release/dev/cmake-E-copy-t-flag.rst
@@ -0,0 +1,10 @@ +cmake-E-copy-t-flag +------------------- + +* The :option:`cmake -E` commands + :option:`copy_if_different <cmake-E copy_if_different>`, + :option:`copy_if_newer <cmake-E copy_if_newer>`, + :option:`copy_directory <cmake-E copy_directory>`, + :option:`copy_directory_if_different <cmake-E copy_directory_if_different>`, + and :option:`copy_directory_if_newer <cmake-E copy_directory_if_newer>` + gained support for the ``-t`` argument.
diff --git a/Help/release/dev/cmake-E-tar-encoding.rst b/Help/release/dev/cmake-E-tar-encoding.rst new file mode 100644 index 0000000..30ac5f7 --- /dev/null +++ b/Help/release/dev/cmake-E-tar-encoding.rst
@@ -0,0 +1,10 @@ +cmake-E-tar-encoding +-------------------- + +* The :option:`cmake -E tar <cmake-E tar>` command-line tool gained the + :option:`--cmake-tar-encoding <cmake-E_tar --cmake-tar-encoding>` flag + to specify the pathname encoding used in archives. + +* The :cpack_gen:`CPack Archive Generator` gained the + :variable:`CPACK_ARCHIVE_ENCODING` variable to specify the pathname + encoding used in package archives.
diff --git a/Help/release/dev/cmake-build-preset-dir.rst b/Help/release/dev/cmake-build-preset-dir.rst new file mode 100644 index 0000000..4422487 --- /dev/null +++ b/Help/release/dev/cmake-build-preset-dir.rst
@@ -0,0 +1,5 @@ +cmake-build-preset-dir +---------------------- + +* :manual:`cmake(1)` now supports ``--build <dir> --preset <pre>`` + regardless of the current working directory.
diff --git a/Help/release/dev/cmake-env-pch-disable.rst b/Help/release/dev/cmake-env-pch-disable.rst new file mode 100644 index 0000000..9b74d7f --- /dev/null +++ b/Help/release/dev/cmake-env-pch-disable.rst
@@ -0,0 +1,5 @@ +cmake-env-pch-disable +--------------------- + +* The :envvar:`CMAKE_DISABLE_PRECOMPILE_HEADERS` environment variable + was added to disable precompiled headers by default.
diff --git a/Help/release/dev/cmake-install-j-no-space.rst b/Help/release/dev/cmake-install-j-no-space.rst new file mode 100644 index 0000000..e3d3411 --- /dev/null +++ b/Help/release/dev/cmake-install-j-no-space.rst
@@ -0,0 +1,5 @@ +cmake-install-j-no-space +------------------------ + +* :option:`cmake --install` now accepts ``-j<N>`` in addition to ``-j <N>`` + for specifying the number of parallel jobs.
diff --git a/Help/release/dev/cmake-install-multi-component.rst b/Help/release/dev/cmake-install-multi-component.rst new file mode 100644 index 0000000..0e3d3aa --- /dev/null +++ b/Help/release/dev/cmake-install-multi-component.rst
@@ -0,0 +1,5 @@ +cmake-install-multi-component +----------------------------- + +* The :option:`cmake --install` command now supports installing + multiple components.
diff --git a/Help/release/dev/ctest-error-exit.rst b/Help/release/dev/ctest-error-exit.rst new file mode 100644 index 0000000..1c1faad --- /dev/null +++ b/Help/release/dev/ctest-error-exit.rst
@@ -0,0 +1,5 @@ +ctest-error-exit +---------------- + +* :manual:`ctest(1)` now exits with non-zero if invoked with no + arguments and no test input file exists.
diff --git a/Help/release/dev/ctest-llvm-cov.rst b/Help/release/dev/ctest-llvm-cov.rst new file mode 100644 index 0000000..f6ca701 --- /dev/null +++ b/Help/release/dev/ctest-llvm-cov.rst
@@ -0,0 +1,6 @@ +ctest-llvm-cov +-------------- + +* :manual:`ctest(1)` gained a :ref:`CoverageTool <ctest-CoverageTool>` + option in :ref:`Dashboard Client` mode to configure tests for + coverage collection by ``llvm-cov``.
diff --git a/Help/release/dev/ctest-passthrough-args.rst b/Help/release/dev/ctest-passthrough-args.rst new file mode 100644 index 0000000..93175e4 --- /dev/null +++ b/Help/release/dev/ctest-passthrough-args.rst
@@ -0,0 +1,10 @@ +ctest-passthrough-args +---------------------- + +* :manual:`ctest(1)` gained support for forwarding extra arguments to test + executables using a :option:`-- <ctest -->` separator. + +* :manual:`cmake-presets(7)` gained support for a + ``testPassthroughArguments`` field in the + test preset ``execution`` object for + forwarding arguments to test executables via presets.
diff --git a/Help/release/dev/ctest_build_preset_option.rst b/Help/release/dev/ctest_build_preset_option.rst new file mode 100644 index 0000000..d46e6dc --- /dev/null +++ b/Help/release/dev/ctest_build_preset_option.rst
@@ -0,0 +1,5 @@ +ctest_build_preset_option +------------------------- + +* The :command:`ctest_build` command gained a ``PRESET`` option + drive the build through a build preset.
diff --git a/Help/release/dev/discover-tests.rst b/Help/release/dev/discover-tests.rst new file mode 100644 index 0000000..8af674e --- /dev/null +++ b/Help/release/dev/discover-tests.rst
@@ -0,0 +1,11 @@ +discover-tests +-------------- + +* The :command:`discover_tests` command was added to support registering tests + discovered at test time by :manual:`ctest(1)`. It runs a user-provided + discovery command, parses its output, and generates test names, arguments, + and properties from regular-expression captures. + +* Test drivers generated by the :command:`create_test_sourcelist` command now + support the `-N` option to list all tests, one per line. This is useful in + combination with the new :command:`discover_tests` command.
diff --git a/Help/release/dev/execute_process-environment.rst b/Help/release/dev/execute_process-environment.rst new file mode 100644 index 0000000..d14bc4b --- /dev/null +++ b/Help/release/dev/execute_process-environment.rst
@@ -0,0 +1,6 @@ +execute_process-environment +--------------------------- + +* The :command:`execute_process` command learned the + ``ENVIRONMENT`` and ``ENVIRONMENT_MODIFICATION`` options to run child + processes with a modified environment.
diff --git a/Help/release/dev/file-api-FILE_SET-SOURCES.rst b/Help/release/dev/file-api-FILE_SET-SOURCES.rst new file mode 100644 index 0000000..e121c65 --- /dev/null +++ b/Help/release/dev/file-api-FILE_SET-SOURCES.rst
@@ -0,0 +1,8 @@ +file-api-FILE_SET-SOURCES +------------------------- + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 object has been + updated to 2.11. +* The :manual:`cmake-file-api(7)` "codemodel" version 2 "installers" object's + optional ``fileSetType`` field gained a new ``SOURCES`` value to incorporate + the new :ref:`file set <file sets>` ``SOURCES`` type in codemodel replies.
diff --git a/Help/release/dev/file-archive-encoding.rst b/Help/release/dev/file-archive-encoding.rst new file mode 100644 index 0000000..3275c4c --- /dev/null +++ b/Help/release/dev/file-archive-encoding.rst
@@ -0,0 +1,7 @@ +file-archive-encoding +--------------------- + +* The :command:`file(ARCHIVE_CREATE)` and :command:`file(ARCHIVE_EXTRACT)` + commands accepts an ``ENCODING`` option to specify the encoding of the + archive pathnames. The default is now ``UTF-8``. + See policy :policy:`CMP0213`.
diff --git a/Help/release/dev/findcudatoolkit-sanitizer-api.rst b/Help/release/dev/findcudatoolkit-sanitizer-api.rst new file mode 100644 index 0000000..94bb55b --- /dev/null +++ b/Help/release/dev/findcudatoolkit-sanitizer-api.rst
@@ -0,0 +1,6 @@ +findcudatoolkit-sanitizer-api +----------------------------- + +* The :module:`FindCUDAToolkit` module now creates a ``CUDA::sanitizer`` + target for the :ref:`compute-sanitizer <FindCUDAToolkit_sanitizer>` + library.
diff --git a/Help/release/dev/genex-TARGET_OBJECTS-SOURCE_FILES.rst b/Help/release/dev/genex-TARGET_OBJECTS-SOURCE_FILES.rst new file mode 100644 index 0000000..623b9ad --- /dev/null +++ b/Help/release/dev/genex-TARGET_OBJECTS-SOURCE_FILES.rst
@@ -0,0 +1,7 @@ +genex-TARGET_OBJECTS-SOURCE_FILES +--------------------------------- + +* The :genex:`TARGET_OBJECTS` generator expression now has an optional + ``SOURCE_FILES:...`` argument, which can take one or more source files as + arguments, and will filter its output to only include objects built from + those source files.
diff --git a/Help/release/dev/install-absolute-dest-configure-time.rst b/Help/release/dev/install-absolute-dest-configure-time.rst new file mode 100644 index 0000000..580a46c --- /dev/null +++ b/Help/release/dev/install-absolute-dest-configure-time.rst
@@ -0,0 +1,12 @@ +install-absolute-dest-configure-time +------------------------------------- + +* CMake gained the ability to diagnose :command:`install` commands that + specify an absolute ``DESTINATION`` path via the + :diagnostic:`CMD_INSTALL_ABSOLUTE_DESTINATION` diagnostic category. + This diagnostic may be controlled with the + :option:`-Winstall-absolute-destination <cmake -W>` command-line option, + the ``installAbsoluteDestination`` field in a + :manual:`CMake Presets <cmake-presets(7)>` + :preset:`configurePresets.warnings` object, + or the :command:`cmake_diagnostic` command.
diff --git a/Help/release/dev/json-partial-equals.rst b/Help/release/dev/json-partial-equals.rst new file mode 100644 index 0000000..2149421 --- /dev/null +++ b/Help/release/dev/json-partial-equals.rst
@@ -0,0 +1,5 @@ +json-partial-equals +------------------- + +* The :command:`string(JSON ... PARTIAL_EQUAL) <string(JSON-PARTIAL_EQUAL)>` + command was added to compare two JSON values using *partial* equality.
diff --git a/Help/release/dev/list-PREDICATE.rst b/Help/release/dev/list-PREDICATE.rst new file mode 100644 index 0000000..324bd07 --- /dev/null +++ b/Help/release/dev/list-PREDICATE.rst
@@ -0,0 +1,10 @@ +list-PREDICATE +-------------- + +* The :command:`list(TRANSFORM)` command gained a new ``PREDICATE`` selector + that invokes a user-defined callable to decide which elements are + transformed. + +* The :command:`list(FILTER)` command gained a new ``PREDICATE`` mode + that invokes a user-defined callable to decide which elements are + included or excluded, complementing the existing ``REGEX`` mode.
diff --git a/Help/release/dev/list-SORT-COMPARATOR.rst b/Help/release/dev/list-SORT-COMPARATOR.rst new file mode 100644 index 0000000..61a658d --- /dev/null +++ b/Help/release/dev/list-SORT-COMPARATOR.rst
@@ -0,0 +1,6 @@ +list-SORT-COMPARATOR +-------------------- + +* The :command:`list(SORT)` command gained a new ``COMPARATOR`` keyword + that invokes a user-defined :command:`function` to compare elements, complementing + the built-in ``COMPARE`` methods.
diff --git a/Help/release/dev/list-TRANSFORM-APPLY.rst b/Help/release/dev/list-TRANSFORM-APPLY.rst new file mode 100644 index 0000000..8807669 --- /dev/null +++ b/Help/release/dev/list-TRANSFORM-APPLY.rst
@@ -0,0 +1,6 @@ +list-TRANSFORM-APPLY +-------------------- + +* The :command:`list(TRANSFORM)` command gained a new ``APPLY`` action that + invokes a user-defined :command:`function` for each element of the list, + enabling arbitrary per-element transformations.
diff --git a/Help/release/dev/nsis_ignore_components_page.rst b/Help/release/dev/nsis_ignore_components_page.rst new file mode 100644 index 0000000..f5c36e3 --- /dev/null +++ b/Help/release/dev/nsis_ignore_components_page.rst
@@ -0,0 +1,6 @@ +nsis_ignore_components_page +--------------------------- + +* The :cpack_gen:`CPack NSIS Generator` gained a new variable + :variable:`CPACK_NSIS_IGNORE_COMPONENTS_PAGE` to ignore the + component selection page in the installer.
diff --git a/Help/release/dev/presets-file-arg.rst b/Help/release/dev/presets-file-arg.rst new file mode 100644 index 0000000..7cfc969 --- /dev/null +++ b/Help/release/dev/presets-file-arg.rst
@@ -0,0 +1,11 @@ +presets-file-arg +---------------- + +* :manual:`cmake(1)`, :manual:`ctest(1)`, and :manual:`cpack(1)` gained + ``--presets-file`` arguments to support loading + :manual:`presets <cmake-presets(7)>` from the specified file instead of + ``CMakePresets.json`` and/or ``CMakeUserPresets.json``. See + :option:`cmake --presets-file`, + :option:`cmake --build --presets-file <cmake--build --presets-file>`, + :option:`cmake --workflow --presets-file <cmake--workflow --presets-file>`, + :option:`ctest --presets-file`, and :option:`cpack --presets-file` for details.
diff --git a/Help/release/dev/presets-fileDir.rst b/Help/release/dev/presets-fileDir.rst new file mode 100644 index 0000000..6ee8603 --- /dev/null +++ b/Help/release/dev/presets-fileDir.rst
@@ -0,0 +1,7 @@ +presets-fileDir +--------------- + +* :manual:`cmake-presets(7)` files now support schema version 12. The + :ref:`${fileDir} <CMakePresets fileDir>` macro now always expands to the + directory of the presets file containing the ``${fileDir}`` macro, regardless + of whether it is inherited by another preset in a different directory.
diff --git a/Help/release/dev/read-symlink-result.rst b/Help/release/dev/read-symlink-result.rst new file mode 100644 index 0000000..62386df --- /dev/null +++ b/Help/release/dev/read-symlink-result.rst
@@ -0,0 +1,5 @@ +read-symlink-result +------------------- + +* The :command:`file(READ_SYMLINK)` command gained a ``RESULT`` + option to capture errors without failing.
diff --git a/Help/release/dev/swift-ninja-separate-swiftmodule-edge.rst b/Help/release/dev/swift-ninja-separate-swiftmodule-edge.rst new file mode 100644 index 0000000..c9eb6f8 --- /dev/null +++ b/Help/release/dev/swift-ninja-separate-swiftmodule-edge.rst
@@ -0,0 +1,11 @@ +swift-ninja-separate-swiftmodule-edge +------------------------------------- + +* The :ref:`Ninja Generators` gained the + :prop_tgt:`Swift_SEPARATE_MODULE_EMISSION` target property, initialized by + the :variable:`CMAKE_Swift_SEPARATE_MODULE_EMISSION` variable, to control + whether importable Swift targets emit ``.swiftmodule`` from a dedicated + build edge. Policy :policy:`CMP0215` enables this by default. + +* The default :prop_tgt:`Swift_MODULE_NAME` now replaces hyphens with + underscores, since hyphens are not valid in Swift module identifiers.
diff --git a/Help/release/dev/swift-package-name.rst b/Help/release/dev/swift-package-name.rst new file mode 100644 index 0000000..b35d47e --- /dev/null +++ b/Help/release/dev/swift-package-name.rst
@@ -0,0 +1,8 @@ +swift-package-name +------------------ + +* Swift targets now have a package name by default. + See policy :policy:`CMP0216`. + +* The :prop_tgt:`Swift_PACKAGE_NAME` target property was added to + specify a Swift package name.
diff --git a/Help/release/dev/verify-header-sets-objc.rst b/Help/release/dev/verify-header-sets-objc.rst new file mode 100644 index 0000000..4b53e88 --- /dev/null +++ b/Help/release/dev/verify-header-sets-objc.rst
@@ -0,0 +1,6 @@ +verify-header-sets-objc +----------------------- + +* The :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` and + :prop_tgt:`VERIFY_PRIVATE_HEADER_SETS` target properties now support + ``OBJC`` and ``OBJCXX`` languages in addition to ``C`` and ``CXX``.
diff --git a/Help/release/dev/vs-deploy-utility-fix.rst b/Help/release/dev/vs-deploy-utility-fix.rst new file mode 100644 index 0000000..8dd639f --- /dev/null +++ b/Help/release/dev/vs-deploy-utility-fix.rst
@@ -0,0 +1,5 @@ +vs-deploy-utility-fix +--------------------- + +* The :prop_tgt:`VS_SOLUTION_DEPLOY` target property is now implemented + for targets created by :command:`add_custom_target`.
diff --git a/Help/release/index.rst b/Help/release/index.rst index 400e1f2..76550cb 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst
@@ -7,12 +7,16 @@ This file should include the adjacent "dev.txt" file in development versions but not in release versions. +.. include:: dev.txt + Releases ======== .. 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_ERROR_DEPRECATED.rst b/Help/variable/CMAKE_ERROR_DEPRECATED.rst index f3a6738..12aa50b 100644 --- a/Help/variable/CMAKE_ERROR_DEPRECATED.rst +++ b/Help/variable/CMAKE_ERROR_DEPRECATED.rst
@@ -1,6 +1,8 @@ CMAKE_ERROR_DEPRECATED ---------------------- +.. deprecated:: 4.4 + Whether to issue errors for deprecated functionality. If ``TRUE``, use of deprecated functionality will issue fatal errors.
diff --git a/Help/variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION.rst b/Help/variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION.rst index 38e9b7b..5ee7bf3 100644 --- a/Help/variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION.rst +++ b/Help/variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION.rst
@@ -8,3 +8,10 @@ file takes place. This variable is used by CMake-generated ``cmake_install.cmake`` scripts. If one sets this variable to ``ON`` while running the script, it may get fatal error messages from the script. + +.. versionadded:: 4.4 + + The :diagnostic:`CMD_INSTALL_ABSOLUTE_DESTINATION` diagnostic can be used to + generate errors for absolute install destinations at generate time. + +See also :variable:`CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION`.
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_DEFAULT_COMPONENT_NAME.rst b/Help/variable/CMAKE_INSTALL_DEFAULT_COMPONENT_NAME.rst index 57160f1..15ec0cd 100644 --- a/Help/variable/CMAKE_INSTALL_DEFAULT_COMPONENT_NAME.rst +++ b/Help/variable/CMAKE_INSTALL_DEFAULT_COMPONENT_NAME.rst
@@ -7,3 +7,13 @@ these files will be grouped into a default component. The name of this default install component will be taken from this variable. It defaults to ``Unspecified``. + +There is a special component name: + +``<PROJECT_NAME>`` + .. versionadded:: 4.4 + + This literal placeholder will expand to the contents of the + :variable:`PROJECT_NAME` variable when the :command:`install` command is + evaluated. If no :command:`project` command has been called it defaults to + ``Unspecified``.
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..f9fa96d 100644 --- a/Help/variable/CMAKE_INSTALL_PREFIX.rst +++ b/Help/variable/CMAKE_INSTALL_PREFIX.rst
@@ -45,3 +45,20 @@ .. 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 :preset:`configurePresets.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_COMPILER_LINKER_ID.rst b/Help/variable/CMAKE_LANG_COMPILER_LINKER_ID.rst index a57fd33..21b31c4 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_LINKER_ID.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_LINKER_ID.rst
@@ -11,6 +11,7 @@ =============================== =============================================== Value Name =============================== =============================================== +``AIX`` AIX system linker ``AppleClang`` Apple Clang ``LLD`` `LLVM LLD`_ ``GNU`` `GNU Binutils - ld linker`_ (also known as @@ -19,8 +20,9 @@ ``MSVC`` `Microsoft Visual Studio`_ ``MOLD`` `mold: A Modern Linker`_, or on Apple the `sold`_ linker -``AIX`` AIX system linker ``Solaris`` SunOS system linker +``WILD`` `wild`_ linker +``OpenWatcom`` `OpenWatcom wlink`_ linker =============================== =============================================== This variable is not guaranteed to be defined for all linkers or languages. @@ -31,3 +33,5 @@ .. _Microsoft Visual Studio: https://visualstudio.microsoft.com .. _mold\: A Modern Linker: https://github.com/rui314/mold .. _sold: https://github.com/bluewhalesystems/sold +.. _wild: https://github.com/wild-linker/wild +.. _OpenWatcom wlink: https://www.openwatcom.com/
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_Rust_EDITION.rst b/Help/variable/CMAKE_Rust_EDITION.rst new file mode 100644 index 0000000..273aea6 --- /dev/null +++ b/Help/variable/CMAKE_Rust_EDITION.rst
@@ -0,0 +1,10 @@ +CMAKE_Rust_EDITION +------------------ + +.. versionadded:: 4.4 + +.. note:: + Experimental. Gated by ``CMAKE_EXPERIMENTAL_RUST``. + +Default value for :prop_tgt:`Rust_EDITION` target property if set when a target +is created.
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..90b26ba 100644 --- a/Help/variable/CMAKE_SYSTEM_NAME.rst +++ b/Help/variable/CMAKE_SYSTEM_NAME.rst
@@ -28,79 +28,270 @@ The following is a list of possible values, each associated with corresponding operating systems or environments. -========================= ====================================================== -Value Name -========================= ====================================================== -``ADSP`` Analog Devices Audio Digital Signal Processing -``AIX`` IBM Unix operating system -``Android`` Android operating system -``ARTOS`` Operating system for microcontrollers -``BeOS`` Operating system for personal computers (discontinued) -``BlueGeneL`` Blue Gene/L static environment -``BlueGeneP-dynamic`` Blue Gene/P dynamic environment -``BlueGeneP-static`` Blue Gene/P static environment -``BlueGeneQ-dynamic`` Blue Gene/Q dynamic environment -``BlueGeneQ-static`` Blue Gene/Q static environment -``BSDOS`` BSD operating system (discontinued) -``Catamount`` Operating system for Cray XT series -``CrayLinuxEnvironment`` Cray Linux Environment -``CYGWIN`` Cygwin environment for Windows -``Darwin`` Apple stationary operating systems (macOS, OS X, etc.) -``DOS`` MS-DOS or compatible -``DragonFly`` BSD-derived operating system -``eCos`` Real-time embedded operating system -``Emscripten`` Compiler toolchain to WebAssembly -``Euros`` Real-time operating system for embedded devices -``FreeBSD`` FreeBSD operating system -``Fuchsia`` Operating system by Google based on the Zircon kernel -``Generic-ADSP`` Generic ADSP (Audio DSP) environment -``Generic-ELF`` Generic ELF (Executable and Linkable Format) environment -``Generic`` Some platforms, e.g. bare metal embedded devices -``GHS-MULTI`` Green Hills Software MULTI environment -``GNU`` GNU/Hurd-based operating system -``Haiku`` Unix operating system inspired by BeOS -``HP-UX`` Hewlett Packard Unix -``iOS`` Apple mobile phone operating system -``Linux`` All Linux-based distributions -``Midipix`` POSIX-compatible layer for Windows -``MirBSD`` MirOS BSD operating system -``MP-RAS`` MP-RAS UNIX operating system -``MSYS`` MSYS environment (MSYSTEM=MSYS) -``NetBSD`` NetBSD operating systems -``OpenBSD`` OpenBSD operating systems -``OpenVMS`` OpenVMS operating system by HP -``OS2`` OS/2 operating system -``OSF1`` Compaq Tru64 UNIX (formerly DEC OSF/1, Digital Unix) (discontinued) -``QNX`` Unix-like operating system by BlackBerry -``RISCos`` RISC OS operating system -``SCO_SV`` SCO OpenServer 5 -``SerenityOS`` Unix-like operating system -``SINIX`` SINIX operating system -``SunOS`` Oracle Solaris and all illumos operating systems -``syllable`` Syllable operating system -``Tru64`` Compaq Tru64 UNIX (formerly DEC OSF/1) operating system -``tvOS`` Apple TV operating system -``ULTRIX`` Unix operating system (discontinued) -``UNIX_SV`` SCO UnixWare (pre release 7) -``UnixWare`` SCO UnixWare 7 -``visionOS`` Apple mixed reality operating system -``WASI`` WebAssembly System Interface -``watchOS`` Apple watch operating system -``Windows`` Windows stationary operating systems -``WindowsCE`` Windows Embedded Compact -``WindowsPhone`` Windows mobile phone operating system -``WindowsStore`` Universal Windows Platform applications -``Xenix`` SCO Xenix Unix operating system (discontinued) -========================= ====================================================== +Apple Platforms +""""""""""""""" -Platform-specific notes: +``Darwin`` + Apple stationary operating systems (macOS, OS X, etc.) -* MSYS2's ``msys/cmake`` package (``/usr/bin/cmake``) works only under +``iOS`` + .. versionadded:: 3.14 + + Apple mobile phone operating system + +``tvOS`` + .. versionadded:: 3.14 + + Apple TV operating system + +``visionOS`` + .. versionadded:: 3.28 + + Apple mixed reality operating system + +``watchOS`` + .. versionadded:: 3.14 + + Apple watch operating system + +UNIX Platforms +"""""""""""""" + +``ADSP`` + Analog Devices Audio Digital Signal Processing + +``AIX`` + IBM Unix operating system + +``Android`` + .. versionadded:: 3.1 + + Android operating system + +``ARTOS`` + .. versionadded:: 3.4 + + Operating system for microcontrollers + +``BeOS`` + Operating system for personal computers (discontinued) + +``BlueGeneL`` + Blue Gene/L static environment + +``BlueGeneP-dynamic`` + Blue Gene/P dynamic environment + +``BlueGeneP-static`` + Blue Gene/P static environment + +``BlueGeneQ-dynamic`` + .. versionadded:: 3.3 + + Blue Gene/Q dynamic environment + +``BlueGeneQ-static`` + .. versionadded:: 3.3 + + Blue Gene/Q static environment + +``BSDOS`` + BSD operating system (discontinued) + +``Catamount`` + Operating system for Cray XT series + +``CrayLinuxEnvironment`` + .. versionadded:: 3.5 + + Cray Linux Environment + +``DragonFly`` + BSD-derived operating system + +``eCos`` + Real-time embedded operating system + +``Emscripten`` + .. versionadded:: 4.2 + + Compiler toolchain to WebAssembly. + +``Euros`` + .. versionadded:: 3.4 + + Real-time operating system for embedded devices + +``FreeBSD`` + FreeBSD operating system + +``Fuchsia`` + .. versionadded:: 3.8 + + Operating system by Google based on the Zircon kernel + +``Generic-ADSP`` + Generic ADSP (Audio DSP) environment + +``Generic-ELF`` + .. versionadded:: 3.23 + + Generic ELF (Executable and Linkable Format) environment + +``Generic`` + Some platforms, e.g. bare metal embedded devices + +``GHS-MULTI`` + .. versionadded:: 3.3 + + Green Hills Software MULTI environment + +``GNU`` + GNU/Hurd-based operating system + +``Haiku`` + Unix operating system inspired by BeOS + +``HP-UX`` + Hewlett Packard Unix (discontinued) + +``Linux`` + All Linux-based distributions + +``MirBSD`` + MirOS BSD operating system + +``MP-RAS`` + MP-RAS UNIX operating system + +``NetBSD`` + NetBSD operating systems + +``OHOS`` + .. versionadded:: 3.30 + + OpenHarmony family of operating systems (e.g., HarmonyOS) + + Toolchain file can set this value when targeting OpenHarmony operating + systems. + +``OpenBSD`` + OpenBSD operating systems + +``OpenVMS`` + OpenVMS operating system by HP + +``OS2`` + .. versionadded:: 3.18 + + OS/2 operating system + +``OSF1`` + Compaq Tru64 UNIX (formerly DEC OSF/1, Digital Unix) (discontinued) + +``QNX`` + Unix-like operating system by BlackBerry + +``RISCos`` + RISC OS operating system + +``SCO_SV`` + SCO OpenServer 5 + +``SerenityOS`` + .. versionadded:: 3.25 + + Unix-like operating system + +``SINIX`` + SINIX operating system + +``SunOS`` + Oracle Solaris and all illumos operating systems + +``syllable`` + Syllable operating system + +``Tru64`` + Compaq Tru64 UNIX (formerly DEC OSF/1) operating system + +``ULTRIX`` + Unix operating system (discontinued) + +``UNIX_SV`` + SCO UnixWare (pre release 7) + +``UnixWare`` + SCO UnixWare 7 + +``WASI`` + .. versionadded:: 3.31 + + WebAssembly System Interface + +``Xenix`` + SCO Xenix Unix operating system (discontinued) + +Windows Platforms +""""""""""""""""" + +``CYGWIN`` + Cygwin environment for Windows + + 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. + +``DOS`` + MS-DOS or compatible + +``Midipix`` + .. versionadded:: 3.10 + + POSIX-compatible layer for Windows + +``MSYS`` + MSYS environment (MSYSTEM=MSYS) + + MSYS2's ``msys/cmake`` package (``/usr/bin/cmake``) works only under ``MSYSTEM=MSYS`` environments, with system name ``MSYS``. Under other environments like ``MSYSTEM=MINGW64``, use another package such as ``mingw64/mingw-w64-x86_64-cmake`` (``/mingw64/bin/cmake``), which targets ``MSYSTEM=MINGW64`` with system name ``Windows``. -* 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. +``Windows`` + Windows stationary operating systems + +``WindowsCE`` + Windows Embedded Compact + +``WindowsKernelModeDriver`` + .. versionadded:: 4.1 + + Windows Kernel-Mode Driver + + When building drivers for Kernel-Mode Driver Framework on Windows, toolchain + file can set this value. See also the :variable:`CMAKE_WINDOWS_KMDF_VERSION` + variable. + +``WindowsPhone`` + .. versionadded:: 3.1 + + Windows mobile phone operating system + +``WindowsStore`` + .. versionadded:: 3.1 + + Universal Windows Platform applications + +Removed Platforms +""""""""""""""""" + +The following platforms were once supported by CMake and got removed either due +to platform's EOL, or other incompatibilities: + +``kFreeBSD`` + .. versionchanged:: 4.1 + Removed from CMake. + + FreeBSD kernel with a GNU userland
diff --git a/Help/variable/CMAKE_Swift_SEPARATE_MODULE_EMISSION.rst b/Help/variable/CMAKE_Swift_SEPARATE_MODULE_EMISSION.rst new file mode 100644 index 0000000..d5ebcb0 --- /dev/null +++ b/Help/variable/CMAKE_Swift_SEPARATE_MODULE_EMISSION.rst
@@ -0,0 +1,24 @@ +CMAKE_Swift_SEPARATE_MODULE_EMISSION +------------------------------------- + +.. versionadded:: 4.4 + +Specify whether Swift targets emit ``.swiftmodule`` from a dedicated build +edge. This variable is used to initialize the +:prop_tgt:`Swift_SEPARATE_MODULE_EMISSION` property on targets as they are +created. + +When set to ``ON``, importable Swift targets built by :ref:`Ninja Generators` +produce the ``.swiftmodule`` from a separate ``-emit-module`` build edge, +allowing downstream Swift targets to compile in parallel with upstream +object compilation. + +If this variable is not set, separate module emission is enabled by default +in targets that do not set :prop_tgt:`Swift_SEPARATE_MODULE_EMISSION`. +See policy :policy:`CMP0215`. + +.. note:: + + Separate module emission takes effect only when policy :policy:`CMP0157` + is set to ``NEW`` prior to the first :command:`project` or + :command:`enable_language` command that enables the Swift language.
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/CMAKE_WARN_DEPRECATED.rst b/Help/variable/CMAKE_WARN_DEPRECATED.rst index c7b6159..ffe24bd 100644 --- a/Help/variable/CMAKE_WARN_DEPRECATED.rst +++ b/Help/variable/CMAKE_WARN_DEPRECATED.rst
@@ -1,11 +1,13 @@ CMAKE_WARN_DEPRECATED --------------------- +.. deprecated:: 4.4 + Whether to issue warnings for deprecated functionality. If not ``FALSE``, use of deprecated functionality will issue warnings. If this variable is not set, CMake behaves as if it were set to ``TRUE``. When running :manual:`cmake(1)`, this option can be enabled with the -:option:`-Wdeprecated <cmake -Wdeprecated>` option, or disabled with the -:option:`-Wno-deprecated <cmake -Wno-deprecated>` option. +:option:`-Wdeprecated <cmake -W>` option, or disabled with the +:option:`-Wno-deprecated <cmake -Wno->` option.
diff --git a/Help/variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION.rst b/Help/variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION.rst index 81c1158..ac40b3d 100644 --- a/Help/variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION.rst +++ b/Help/variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION.rst
@@ -7,3 +7,10 @@ This variable is used by CMake-generated ``cmake_install.cmake`` scripts. If one sets this variable to ``ON`` while running the script, it may get warning messages from the script. + +.. versionadded:: 4.4 + + The :diagnostic:`CMD_INSTALL_ABSOLUTE_DESTINATION` diagnostic can be used to + generate warnings for absolute install destinations at generate time. + +See also :variable:`CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION`.
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_COVERAGE_TOOL.rst b/Help/variable/CTEST_TEST_COVERAGE_TOOL.rst new file mode 100644 index 0000000..bc94825 --- /dev/null +++ b/Help/variable/CTEST_TEST_COVERAGE_TOOL.rst
@@ -0,0 +1,7 @@ +CTEST_TEST_COVERAGE_TOOL +------------------------ + +.. versionadded:: 4.4 + +Specify the CTest :ref:`CoverageTool <ctest-CoverageTool>` setting +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/Help/variable/include/LINKER_PREDEFINED_TYPES.rst b/Help/variable/include/LINKER_PREDEFINED_TYPES.rst index 3c1b7b8..63ed955 100644 --- a/Help/variable/include/LINKER_PREDEFINED_TYPES.rst +++ b/Help/variable/include/LINKER_PREDEFINED_TYPES.rst
@@ -45,8 +45,8 @@ ``NVIDIA``, and ``Swift`` compilers. ``MOLD`` - Use the `mold linker <https://github.com/rui314/mold>`_. This type is - supported on the following platform-compiler combinations: + Use the `mold linker`_. This type is supported on the following + platform-compiler combinations: * Linux: ``GNU``, ``Clang``, ``LLVMFlang``, and ``NVIDIA`` compilers. * Apple platforms: ``Clang`` and ``AppleClang`` compilers (acts as an @@ -56,6 +56,12 @@ Use the `sold linker`_. This type is only supported on Apple platforms with ``Clang`` and ``AppleClang`` compilers. +``WILD`` + .. versionadded:: 4.4 + + Use the `wild linker`_. This type is only supported on Linux platforms + with ``Clang`` and ``GNU`` compilers. + ``APPLE_CLASSIC`` Use the Apple linker in the classic behavior (i.e. before ``Xcode 15.0``). This type is only supported on Apple platforms with ``GNU``, ``Clang``, @@ -66,4 +72,6 @@ platform with ``MSVC``, ``Clang`` with MSVC-like front-end, and ``Swift`` compilers. +.. _mold linker: https://github.com/rui314/mold .. _sold linker: https://github.com/bluewhalesystems/sold +.. _wild linker: https://github.com/wild-linker/wild
diff --git a/Help/variable/include/LINK_GROUP_PREDEFINED_FEATURES.rst b/Help/variable/include/LINK_GROUP_PREDEFINED_FEATURES.rst index 557886e..f83fefd 100644 --- a/Help/variable/include/LINK_GROUP_PREDEFINED_FEATURES.rst +++ b/Help/variable/include/LINK_GROUP_PREDEFINED_FEATURES.rst
@@ -20,3 +20,7 @@ This feature is available when using toolchains that target Linux, BSD, and SunOS. It can also be used when targeting Windows platforms if the GNU toolchain is used. + + .. versionadded:: 4.4 + ``RESCAN`` is additionally available when using toolchains targeting + Haiku.
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/CMakeASM_NASMInformation.cmake b/Modules/CMakeASM_NASMInformation.cmake index 54e5153..c60aef0 100644 --- a/Modules/CMakeASM_NASMInformation.cmake +++ b/Modules/CMakeASM_NASMInformation.cmake
@@ -8,30 +8,34 @@ if(NOT CMAKE_ASM_NASM_OBJECT_FORMAT) if(WIN32) - if(DEFINED CMAKE_C_SIZEOF_DATA_PTR AND CMAKE_C_SIZEOF_DATA_PTR EQUAL 8) + if(CMAKE_C_SIZEOF_DATA_PTR EQUAL 8 OR CMAKE_CXX_SIZEOF_DATA_PTR EQUAL 8) set(CMAKE_ASM_NASM_OBJECT_FORMAT win64) - elseif(DEFINED CMAKE_CXX_SIZEOF_DATA_PTR AND CMAKE_CXX_SIZEOF_DATA_PTR EQUAL 8) - set(CMAKE_ASM_NASM_OBJECT_FORMAT win64) + elseif(CMAKE_C_SIZEOF_DATA_PTR EQUAL 4 OR CMAKE_CXX_SIZEOF_DATA_PTR EQUAL 4) + set(CMAKE_ASM_NASM_OBJECT_FORMAT win32) elseif(CMAKE_SYSTEM_PROCESSOR STREQUAL "x86_64") set(CMAKE_ASM_NASM_OBJECT_FORMAT win64) else() set(CMAKE_ASM_NASM_OBJECT_FORMAT win32) endif() elseif(APPLE) - if(DEFINED CMAKE_C_SIZEOF_DATA_PTR AND CMAKE_C_SIZEOF_DATA_PTR EQUAL 8) + if(CMAKE_C_SIZEOF_DATA_PTR EQUAL 8 OR CMAKE_CXX_SIZEOF_DATA_PTR EQUAL 8) set(CMAKE_ASM_NASM_OBJECT_FORMAT macho64) - elseif(DEFINED CMAKE_CXX_SIZEOF_DATA_PTR AND CMAKE_CXX_SIZEOF_DATA_PTR EQUAL 8) - set(CMAKE_ASM_NASM_OBJECT_FORMAT macho64) + elseif(CMAKE_C_SIZEOF_DATA_PTR EQUAL 4 OR CMAKE_CXX_SIZEOF_DATA_PTR EQUAL 4) + set(CMAKE_ASM_NASM_OBJECT_FORMAT macho32) elseif(CMAKE_SYSTEM_PROCESSOR STREQUAL "x86_64") set(CMAKE_ASM_NASM_OBJECT_FORMAT macho64) else() set(CMAKE_ASM_NASM_OBJECT_FORMAT macho) endif() else() - if(DEFINED CMAKE_C_SIZEOF_DATA_PTR AND CMAKE_C_SIZEOF_DATA_PTR EQUAL 8) + if(CMAKE_C_SIZEOF_DATA_PTR EQUAL 8 OR CMAKE_CXX_SIZEOF_DATA_PTR EQUAL 8) set(CMAKE_ASM_NASM_OBJECT_FORMAT elf64) - elseif(DEFINED CMAKE_CXX_SIZEOF_DATA_PTR AND CMAKE_CXX_SIZEOF_DATA_PTR EQUAL 8) - set(CMAKE_ASM_NASM_OBJECT_FORMAT elf64) + elseif(CMAKE_C_SIZEOF_DATA_PTR EQUAL 4 OR CMAKE_CXX_SIZEOF_DATA_PTR EQUAL 4) + if(";${CMAKE_C_COMPILER_ARCHITECTURE_ID};${CMAKE_CXX_COMPILER_ARCHITECTURE_ID};" MATCHES ";x86_64;") + set(CMAKE_ASM_NASM_OBJECT_FORMAT elfx32) + else() + set(CMAKE_ASM_NASM_OBJECT_FORMAT elf32) + endif() elseif(CMAKE_SYSTEM_PROCESSOR STREQUAL "x86_64") set(CMAKE_ASM_NASM_OBJECT_FORMAT elf64) else() @@ -41,7 +45,7 @@ endif() if(NOT CMAKE_ASM_NASM_COMPILE_OBJECT) - set(CMAKE_ASM_NASM_COMPILE_OBJECT "<CMAKE_ASM_NASM_COMPILER> <DEFINES> <INCLUDES> <FLAGS> -f ${CMAKE_ASM_NASM_OBJECT_FORMAT} -o <OBJECT> <SOURCE>") + set(CMAKE_ASM_NASM_COMPILE_OBJECT "<CMAKE_ASM_NASM_COMPILER> <DEFINES> <INCLUDES> -f ${CMAKE_ASM_NASM_OBJECT_FORMAT} <FLAGS> -o <OBJECT> <SOURCE>") endif() if(NOT CMAKE_ASM_NASM_LINK_EXECUTABLE)
diff --git a/Modules/CMakeASM_POASMInformation.cmake b/Modules/CMakeASM_POASMInformation.cmake new file mode 100644 index 0000000..fad25a2 --- /dev/null +++ b/Modules/CMakeASM_POASMInformation.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. + +set(ASM_DIALECT "_POASM") +set(CMAKE_ASM${ASM_DIALECT}_SOURCE_FILE_EXTENSIONS asm) +include(CMakeASMInformation) +set(ASM_DIALECT)
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/CMakeCCompilerId.c.in b/Modules/CMakeCCompilerId.c.in index c79362e..165376d 100644 --- a/Modules/CMakeCCompilerId.c.in +++ b/Modules/CMakeCCompilerId.c.in
@@ -44,16 +44,17 @@ #define C_STD_17 201710L #define C_STD_23 202311L -#ifdef __STDC_VERSION__ -# define C_STD __STDC_VERSION__ +#if defined(__STDC_VERSION__) +# define C_STD __STDC_VERSION__ +#elif defined(__POCC_STDC_VERSION__) +# define C_STD __POCC_STDC_VERSION__ +#elif defined(__STDC__) || defined(__clang__) || defined(_MSC_VER) || \ + defined(__ibmxl__) || defined(__IBMC__) || defined(__RENESAS__) +# define C_STD 1 #endif -#if !defined(__STDC__) && !defined(__clang__) && !defined(__RENESAS__) -# if defined(_MSC_VER) || defined(__ibmxl__) || defined(__IBMC__) -# define C_VERSION "90" -# else -# define C_VERSION -# endif +#if !defined(C_STD) +# define C_VERSION #elif C_STD > C_STD_17 # define C_VERSION "23" #elif C_STD > C_STD_11 @@ -73,6 +74,8 @@ defined(__TI_COMPILER_VERSION__) || defined(__RENESAS__)) && \ !defined(__STRICT_ANSI__) "ON" +#elif defined(__POCC__) && defined(__POCC__EXTENSIONS) + "ON" #else "OFF" #endif
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/CMakeCXXCompilerId.cpp.in b/Modules/CMakeCXXCompilerId.cpp.in index 4d78c2a..2e08785 100644 --- a/Modules/CMakeCXXCompilerId.cpp.in +++ b/Modules/CMakeCXXCompilerId.cpp.in
@@ -63,7 +63,9 @@ # define CXX_STD __cplusplus # endif #elif defined(__NVCOMPILER) -# if __cplusplus == CXX_STD_17 && defined(__cpp_aggregate_paren_init) +# if __cplusplus > CXX_STD_20 && defined(__cpp_pp_embed) +# define CXX_STD /*CXX_STD_26*/ (CXX_STD_23 + 1) +# elif __cplusplus == CXX_STD_17 && defined(__cpp_aggregate_paren_init) # define CXX_STD CXX_STD_20 # else # define CXX_STD __cplusplus
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/CMakeCompilerIdDetection.cmake b/Modules/CMakeCompilerIdDetection.cmake index 68182b8..a8e652c 100644 --- a/Modules/CMakeCompilerIdDetection.cmake +++ b/Modules/CMakeCompilerIdDetection.cmake
@@ -74,6 +74,7 @@ list(APPEND ordered_compilers TinyCC Bruce + PellesC ) endif() list(APPEND ordered_compilers
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..fbfa52c 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() @@ -165,6 +165,10 @@ set(CMAKE_ASM${ASM_DIALECT}_COMPILER_ID_VENDOR_FLAGS_Renesas "-v") set(CMAKE_ASM${ASM_DIALECT}_COMPILER_ID_VENDOR_REGEX_Renesas "(RX Family C/C\\+\\+ Compiler)|(RL78 Family Compiler)|(RH850 Family Compiler)") + list(APPEND CMAKE_ASM${ASM_DIALECT}_COMPILER_ID_VENDORS PellesC) + set(CMAKE_ASM${ASM_DIALECT}_COMPILER_ID_VENDOR_FLAGS_PellesC ) + set(CMAKE_ASM${ASM_DIALECT}_COMPILER_ID_VENDOR_REGEX_PellesC "Pelles Macro Assembler") + include(CMakeDetermineCompilerId) set(userflags) CMAKE_DETERMINE_COMPILER_ID_VENDOR(ASM${ASM_DIALECT} "${userflags}") @@ -263,7 +267,7 @@ endif () -set(_CMAKE_PROCESSING_LANGUAGE "ASM") +set(_CMAKE_PROCESSING_LANGUAGE "ASM${ASM_DIALECT}") include(CMakeFindBinUtils) include(Compiler/${CMAKE_ASM${ASM_DIALECT}_COMPILER_ID}-FindBinUtils OPTIONAL) unset(_CMAKE_PROCESSING_LANGUAGE)
diff --git a/Modules/CMakeDetermineASM_POASMCompiler.cmake b/Modules/CMakeDetermineASM_POASMCompiler.cmake new file mode 100644 index 0000000..a46e96f --- /dev/null +++ b/Modules/CMakeDetermineASM_POASMCompiler.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. + +set(ASM_DIALECT "_POASM") +set(CMAKE_ASM${ASM_DIALECT}_COMPILER_INIT poasm) +include(CMakeDetermineASMCompiler) +unset(ASM_DIALECT)
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..8276da2 100644 --- a/Modules/CMakeDetermineCompiler.cmake +++ b/Modules/CMakeDetermineCompiler.cmake
@@ -112,7 +112,7 @@ # if compiler (and arguments) comes from cache then synchronize cache with updated CMAKE_<LANG>_COMPILER get_filename_component(_CMAKE_USER_${lang}_COMPILER_PATH "${CMAKE_${lang}_COMPILER}" PATH) if(NOT _CMAKE_USER_${lang}_COMPILER_PATH) - find_program(CMAKE_${lang}_COMPILER_WITH_PATH NAMES ${CMAKE_${lang}_COMPILER}) + find_program(CMAKE_${lang}_COMPILER_WITH_PATH NO_CACHE NAMES ${CMAKE_${lang}_COMPILER}) if(CMAKE_${lang}_COMPILER_WITH_PATH) set(CMAKE_${lang}_COMPILER ${CMAKE_${lang}_COMPILER_WITH_PATH}) get_property(_CMAKE_${lang}_COMPILER_CACHED CACHE CMAKE_${lang}_COMPILER PROPERTY TYPE) @@ -121,7 +121,6 @@ endif() unset(_CMAKE_${lang}_COMPILER_CACHED) endif() - unset(CMAKE_${lang}_COMPILER_WITH_PATH CACHE) elseif (EXISTS ${CMAKE_${lang}_COMPILER}) get_property(_CMAKE_${lang}_COMPILER_CACHED CACHE CMAKE_${lang}_COMPILER PROPERTY TYPE) if(_CMAKE_${lang}_COMPILER_CACHED) @@ -137,9 +136,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..b2092bc 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}") @@ -318,6 +324,12 @@ else() set(CMAKE_${lang}_COMPILER_FRONTEND_VARIANT "GNU") endif() + elseif("x${CMAKE_${lang}_COMPILER_ID}" STREQUAL "xIntel") + if(CMAKE_HOST_WIN32) + set(CMAKE_${lang}_COMPILER_FRONTEND_VARIANT "MSVC") + else() + set(CMAKE_${lang}_COMPILER_FRONTEND_VARIANT "GNU") + endif() elseif("x${CMAKE_${lang}_COMPILER_ID}" STREQUAL "xGNU" OR "x${CMAKE_${lang}_COMPILER_ID}" STREQUAL "xAppleClang" OR "x${CMAKE_${lang}_COMPILER_ID}" STREQUAL "xFujitsuClang" @@ -459,7 +471,7 @@ #----------------------------------------------------------------------------- # Function to write the compiler id source file. function(CMAKE_DETERMINE_COMPILER_ID_WRITE lang src) - find_file(src_in ${src}.in PATHS ${CMAKE_ROOT}/Modules ${CMAKE_MODULE_PATH} NO_DEFAULT_PATH NO_CMAKE_FIND_ROOT_PATH) + find_file(src_in ${src}.in NO_CACHE PATHS ${CMAKE_ROOT}/Modules ${CMAKE_MODULE_PATH} NO_DEFAULT_PATH NO_CMAKE_FIND_ROOT_PATH) file(READ ${src_in} ID_CONTENT_IN) compiler_id_detection(CMAKE_${lang}_COMPILER_ID_CONTENT ${lang} @@ -484,7 +496,6 @@ ) endif() - unset(src_in CACHE) string(CONFIGURE "${ID_CONTENT_IN}" ID_CONTENT_OUT @ONLY) file(WRITE ${CMAKE_${lang}_COMPILER_ID_DIR}/${src} "${ID_CONTENT_OUT}") endfunction() @@ -604,7 +615,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 +1351,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..8aeadc1 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() @@ -76,11 +76,10 @@ # if the C compiler already had a path, reuse it for searching the CXX compiler get_filename_component(_CMAKE_USER_OBJC_COMPILER_PATH "${CMAKE_OBJC_COMPILER}" PATH) if(NOT _CMAKE_USER_OBJC_COMPILER_PATH) - find_program(CMAKE_OBJC_COMPILER_WITH_PATH NAMES ${CMAKE_OBJC_COMPILER}) + find_program(CMAKE_OBJC_COMPILER_WITH_PATH NO_CACHE NAMES ${CMAKE_OBJC_COMPILER}) if(CMAKE_OBJC_COMPILER_WITH_PATH) set(CMAKE_OBJC_COMPILER ${CMAKE_OBJC_COMPILER_WITH_PATH} CACHE STRING "Objective-C compiler" FORCE) endif() - unset(CMAKE_OBJC_COMPILER_WITH_PATH CACHE) endif() endif() mark_as_advanced(CMAKE_OBJC_COMPILER)
diff --git a/Modules/CMakeDetermineOBJCXXCompiler.cmake b/Modules/CMakeDetermineOBJCXXCompiler.cmake index 8036da2..b7df4e8 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() @@ -78,11 +78,10 @@ # if the C compiler already had a path, reuse it for searching the CXX compiler get_filename_component(_CMAKE_USER_OBJCXX_COMPILER_PATH "${CMAKE_OBJCXX_COMPILER}" PATH) if(NOT _CMAKE_USER_OBJCXX_COMPILER_PATH) - find_program(CMAKE_OBJCXX_COMPILER_WITH_PATH NAMES ${CMAKE_OBJCXX_COMPILER}) + find_program(CMAKE_OBJCXX_COMPILER_WITH_PATH NO_CACHE NAMES ${CMAKE_OBJCXX_COMPILER}) if(CMAKE_OBJCXX_COMPILER_WITH_PATH) set(CMAKE_OBJCXX_COMPILER ${CMAKE_OBJCXX_COMPILER_WITH_PATH} CACHE STRING "Objective-C++ compiler" FORCE) endif() - unset(CMAKE_OBJCXX_COMPILER_WITH_PATH CACHE) endif() 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..971354f --- /dev/null +++ b/Modules/CMakeDetermineRustCompiler.cmake
@@ -0,0 +1,50 @@ +# 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 + RESULT_VARIABLE _rust_result + ) + + if(NOT _rust_result EQUAL 0 OR "${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/CMakeDetermineSystem.cmake b/Modules/CMakeDetermineSystem.cmake index dc26258..c70fea1 100644 --- a/Modules/CMakeDetermineSystem.cmake +++ b/Modules/CMakeDetermineSystem.cmake
@@ -15,19 +15,24 @@ execute_process(COMMAND ${CMAKE_UNAME} -v OUTPUT_VARIABLE _CMAKE_HOST_SYSTEM_MAJOR_VERSION OUTPUT_STRIP_TRAILING_WHITESPACE - ERROR_QUIET) + ERROR_QUIET + RESULT_VARIABLE _uname_result) execute_process(COMMAND ${CMAKE_UNAME} -r OUTPUT_VARIABLE _CMAKE_HOST_SYSTEM_MINOR_VERSION OUTPUT_STRIP_TRAILING_WHITESPACE - ERROR_QUIET) - set(CMAKE_HOST_SYSTEM_VERSION "${_CMAKE_HOST_SYSTEM_MAJOR_VERSION}.${_CMAKE_HOST_SYSTEM_MINOR_VERSION}") + ERROR_QUIET + RESULT_VARIABLE _uname_result2) + if(_uname_result EQUAL 0 AND _uname_result2 EQUAL 0) + set(CMAKE_HOST_SYSTEM_VERSION "${_CMAKE_HOST_SYSTEM_MAJOR_VERSION}.${_CMAKE_HOST_SYSTEM_MINOR_VERSION}") + endif() unset(_CMAKE_HOST_SYSTEM_MAJOR_VERSION) unset(_CMAKE_HOST_SYSTEM_MINOR_VERSION) elseif(CMAKE_HOST_SYSTEM_NAME STREQUAL "Android") execute_process(COMMAND getprop ro.build.version.sdk OUTPUT_VARIABLE CMAKE_HOST_SYSTEM_VERSION OUTPUT_STRIP_TRAILING_WHITESPACE - ERROR_QUIET) + ERROR_QUIET + RESULT_VARIABLE _uname_result) if(NOT DEFINED CMAKE_SYSTEM_VERSION) set(_ANDROID_API_LEVEL_H $ENV{PREFIX}/include/android/api-level.h) @@ -49,7 +54,8 @@ execute_process(COMMAND ${CMAKE_UNAME} -r OUTPUT_VARIABLE CMAKE_HOST_SYSTEM_VERSION OUTPUT_STRIP_TRAILING_WHITESPACE - ERROR_QUIET) + ERROR_QUIET + RESULT_VARIABLE _uname_result) endif() if(CMAKE_HOST_SYSTEM_NAME MATCHES "Linux|CYGWIN.*|MSYS.*|^GNU$|Android") execute_process(COMMAND ${CMAKE_UNAME} -m
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..3e77903 100644 --- a/Modules/CMakeFindBinUtils.cmake +++ b/Modules/CMakeFindBinUtils.cmake
@@ -34,7 +34,7 @@ if(NOT _CMAKE_USER_TOOL_PATH) # Find CMAKE_TOOL in the SEARCH_PATH directory by user-defined name. - find_program(_CMAKE_TOOL_WITH_PATH NAMES ${${CMAKE_TOOL}} HINTS ${SEARCH_PATH} NO_CMAKE_PATH NO_CMAKE_ENVIRONMENT_PATH) + find_program(_CMAKE_TOOL_WITH_PATH NO_CACHE NAMES ${${CMAKE_TOOL}} HINTS ${SEARCH_PATH} NO_CMAKE_PATH NO_CMAKE_ENVIRONMENT_PATH) if(_CMAKE_TOOL_WITH_PATH) # Overwrite CMAKE_TOOL with full path found in SEARCH_PATH. @@ -47,7 +47,6 @@ endif() endif() - unset(_CMAKE_TOOL_WITH_PATH CACHE) endif() @@ -108,6 +107,11 @@ set(_CMAKE_AR_NAMES "wlib") list(APPEND _CMAKE_TOOL_VARS LINKER AR) +elseif("x${CMAKE_${_CMAKE_PROCESSING_LANGUAGE}_COMPILER_ID}" STREQUAL "xPellesC") + set(_CMAKE_LINKER_NAMES "polink") + set(_CMAKE_AR_NAMES "polib") + list(APPEND _CMAKE_TOOL_VARS LINKER AR) + elseif("x${CMAKE_${_CMAKE_PROCESSING_LANGUAGE}_COMPILER_ID}" MATCHES "^xIAR$") # Detect the `<lang>` compiler name get_filename_component(__iar_selected_compiler "${CMAKE_${_CMAKE_PROCESSING_LANGUAGE}_COMPILER}" NAME) @@ -219,6 +223,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 +268,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() -
