diff options
97 files changed, 1427 insertions, 785 deletions
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index f321d33..bfc713f 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -314,6 +314,33 @@ b:debian10-makefiles-inplace: variables: CMAKE_CI_JOB_NIGHTLY: "true" +b:debian10-extdeps: + extends: + - .debian10_extdeps + - .cmake_build_linux_standalone + - .linux_builder_tags + - .run_manually + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + +b:debian10-aarch64-extdeps: + extends: + - .debian10_aarch64_extdeps + - .cmake_build_linux_standalone + - .linux_builder_tags_aarch64 + - .run_manually + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + +b:fedora36-extdeps: + extends: + - .fedora36_extdeps + - .cmake_build_linux_standalone + - .linux_builder_tags + - .run_manually + variables: + CMAKE_CI_JOB_NIGHTLY: "true" + t:fedora36-ninja: extends: - .fedora36_ninja diff --git a/.gitlab/ci/cmake.ps1 b/.gitlab/ci/cmake.ps1 index bea3286..98aeae3 100755 --- a/.gitlab/ci/cmake.ps1 +++ b/.gitlab/ci/cmake.ps1 @@ -1,7 +1,7 @@ $erroractionpreference = "stop" -$version = "3.24.0-rc1" -$sha256sum = "8D075F5C663263713008FB77E31956C808D3A30074C3655F16EB76A0800F99D6" +$version = "3.24.1" +$sha256sum = "C1B17431A16337D517F7BA78C7067B6F143A12686CB8087F3DD32F3FA45F5AAE" $filename = "cmake-$version-windows-x86_64" $tarball = "$filename.zip" diff --git a/.gitlab/ci/cmake.sh b/.gitlab/ci/cmake.sh index 0d52e19..137da06 100755 --- a/.gitlab/ci/cmake.sh +++ b/.gitlab/ci/cmake.sh @@ -2,22 +2,22 @@ set -e -readonly version="3.24.0-rc1" +readonly version="3.24.1" case "$(uname -s)-$(uname -m)" in Linux-x86_64) shatool="sha256sum" - sha256sum="183ff011a2177d0a683e81d645d02c0ed8ff790449158522928ef069775091cc" + sha256sum="827bf068cfaa23a9fb95f990c9f8a7ed8f2caeb3af62b5c0a2fed7a8dd6dde3e" platform="linux-x86_64" ;; Linux-aarch64) shatool="sha256sum" - sha256sum="f26642d5bc503de6bf7dd2d06afb8777d5862aa44e556cdf4155fec60e534d04" + sha256sum="d50c40135df667ed659f8e4eb7cf7d53421250304f7b3e1a70af9cf3d0f2ab18" platform="linux-aarch64" ;; Darwin-*) shatool="shasum -a 256" - sha256sum="417fde30f2cf96f53eaf27b1e510924ce441f0449e53974f2156cb19d32978b9" + sha256sum="71bb8db69826d74c395a3c3bbf8b773dbe9f54a2c7331266ba70da303e9c97a1" platform="macos-universal" ;; *) diff --git a/.gitlab/ci/configure_debian10_aarch64_extdeps.cmake b/.gitlab/ci/configure_debian10_aarch64_extdeps.cmake new file mode 100644 index 0000000..8e545f5 --- /dev/null +++ b/.gitlab/ci/configure_debian10_aarch64_extdeps.cmake @@ -0,0 +1 @@ +include("${CMAKE_CURRENT_LIST_DIR}/configure_extdeps_common.cmake") diff --git a/.gitlab/ci/configure_debian10_extdeps.cmake b/.gitlab/ci/configure_debian10_extdeps.cmake new file mode 100644 index 0000000..8e545f5 --- /dev/null +++ b/.gitlab/ci/configure_debian10_extdeps.cmake @@ -0,0 +1 @@ +include("${CMAKE_CURRENT_LIST_DIR}/configure_extdeps_common.cmake") diff --git a/.gitlab/ci/configure_extdeps_common.cmake b/.gitlab/ci/configure_extdeps_common.cmake new file mode 100644 index 0000000..2c7d328 --- /dev/null +++ b/.gitlab/ci/configure_extdeps_common.cmake @@ -0,0 +1,5 @@ +set(CMAKE_USE_SYSTEM_LIBRARIES ON CACHE BOOL "") +set(CMAKE_SKIP_BOOTSTRAP_TEST ON CACHE BOOL "") +set(CMake_TEST_Qt6 OFF CACHE BOOL "") + +include("${CMAKE_CURRENT_LIST_DIR}/configure_common.cmake") diff --git a/.gitlab/ci/configure_fedora36_extdeps.cmake b/.gitlab/ci/configure_fedora36_extdeps.cmake new file mode 100644 index 0000000..8e545f5 --- /dev/null +++ b/.gitlab/ci/configure_fedora36_extdeps.cmake @@ -0,0 +1 @@ +include("${CMAKE_CURRENT_LIST_DIR}/configure_extdeps_common.cmake") diff --git a/.gitlab/ci/ctest_standalone.cmake b/.gitlab/ci/ctest_standalone.cmake index 9199693..36ba71c 100644 --- a/.gitlab/ci/ctest_standalone.cmake +++ b/.gitlab/ci/ctest_standalone.cmake @@ -3,8 +3,8 @@ cmake_minimum_required(VERSION 3.8) include("${CMAKE_CURRENT_LIST_DIR}/gitlab_ci.cmake") include("${CMAKE_CURRENT_LIST_DIR}/env_$ENV{CMAKE_CONFIGURATION}.cmake" OPTIONAL) -set(cmake_args - -C "${CMAKE_CURRENT_LIST_DIR}/configure_$ENV{CMAKE_CONFIGURATION}.cmake") +set(initial_cache "${CMAKE_CURRENT_LIST_DIR}/configure_$ENV{CMAKE_CONFIGURATION}.cmake") +set(cmake_args -C "${initial_cache}") include(ProcessorCount) ProcessorCount(nproc) @@ -25,6 +25,8 @@ ctest_update() if("$ENV{CMAKE_CI_BOOTSTRAP}") set(CTEST_CONFIGURE_COMMAND "\"${CTEST_SOURCE_DIRECTORY}/bootstrap\" --parallel=${nproc}") +elseif("$ENV{CMAKE_CONFIGURATION}" MATCHES "extdeps") + set(CTEST_CONFIGURE_COMMAND "/opt/extdeps/bin/cmake -C \"${initial_cache}\" -G \"${CTEST_CMAKE_GENERATOR}\" \"${CTEST_SOURCE_DIRECTORY}\"") endif() # Configure the project. diff --git a/.gitlab/ci/docker/debian10-aarch64/install_deps.sh b/.gitlab/ci/docker/debian10-aarch64/install_deps.sh index 3dd814d..9a98538 100755 --- a/.gitlab/ci/docker/debian10-aarch64/install_deps.sh +++ b/.gitlab/ci/docker/debian10-aarch64/install_deps.sh @@ -14,6 +14,20 @@ apt-get install -y \ curl \ git +# Install optional external build dependencies. +apt-get install -y \ + 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. apt-get install -y \ clang-6.0 \ diff --git a/.gitlab/ci/docker/debian10/install_deps.sh b/.gitlab/ci/docker/debian10/install_deps.sh index f796816..36ef508 100755 --- a/.gitlab/ci/docker/debian10/install_deps.sh +++ b/.gitlab/ci/docker/debian10/install_deps.sh @@ -14,6 +14,20 @@ apt-get install -y \ curl \ git +# Install optional external build dependencies. +apt-get install -y \ + 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. apt-get install -y \ clang-6.0 \ diff --git a/.gitlab/ci/docker/fedora36/install_deps.sh b/.gitlab/ci/docker/fedora36/install_deps.sh index b8ddfb9..141e540 100755 --- a/.gitlab/ci/docker/fedora36/install_deps.sh +++ b/.gitlab/ci/docker/fedora36/install_deps.sh @@ -17,6 +17,20 @@ dnf install --setopt=install_weak_deps=False -y \ git-core \ make +# Install optional external build dependencies. +dnf install --setopt=install_weak_deps=False -y \ + bzip2-devel \ + expat-devel \ + jsoncpp-devel \ + libarchive-devel \ + libcurl-devel \ + libuv-devel \ + libuv-devel \ + libzstd-devel \ + rhash-devel \ + xz-devel \ + zlib-devel + # Install documentation tools. dnf install --setopt=install_weak_deps=False -y \ python3-sphinx \ diff --git a/.gitlab/ci/env_debian10_aarch64_extdeps.sh b/.gitlab/ci/env_debian10_aarch64_extdeps.sh new file mode 100644 index 0000000..7076e18 --- /dev/null +++ b/.gitlab/ci/env_debian10_aarch64_extdeps.sh @@ -0,0 +1 @@ +source .gitlab/ci/env_extdeps_common.sh diff --git a/.gitlab/ci/env_debian10_extdeps.sh b/.gitlab/ci/env_debian10_extdeps.sh new file mode 100644 index 0000000..7076e18 --- /dev/null +++ b/.gitlab/ci/env_debian10_extdeps.sh @@ -0,0 +1 @@ +source .gitlab/ci/env_extdeps_common.sh diff --git a/.gitlab/ci/env_extdeps_common.sh b/.gitlab/ci/env_extdeps_common.sh new file mode 100644 index 0000000..8cabc05 --- /dev/null +++ b/.gitlab/ci/env_extdeps_common.sh @@ -0,0 +1,5 @@ +.gitlab/ci/extdeps-linux.sh + +export CMAKE_PREFIX_PATH=/opt/extdeps +export PATH=/opt/extdeps/bin:$PATH +export LD_LIBRARY_PATH=/opt/extdeps/lib diff --git a/.gitlab/ci/env_fedora36_extdeps.sh b/.gitlab/ci/env_fedora36_extdeps.sh new file mode 100644 index 0000000..7076e18 --- /dev/null +++ b/.gitlab/ci/env_fedora36_extdeps.sh @@ -0,0 +1 @@ +source .gitlab/ci/env_extdeps_common.sh diff --git a/.gitlab/ci/extdeps-linux.sh b/.gitlab/ci/extdeps-linux.sh new file mode 100755 index 0000000..f0d4c0d --- /dev/null +++ b/.gitlab/ci/extdeps-linux.sh @@ -0,0 +1,62 @@ +#!/bin/sh + +set -e + +mkdir -p /opt/extdeps/src +cd /opt/extdeps/src +export PATH=/opt/extdeps/bin:$PATH + +#---------------------------------------------------------------------------- +# cmake + +case "$(uname -s)-$(uname -m)" in + Linux-x86_64) + cmake_version="3.13.5" + cmake_sha256sum="e2fd0080a6f0fc1ec84647acdcd8e0b4019770f48d83509e6a5b0b6ea27e5864" + cmake_platform="Linux-x86_64" + ;; + Linux-aarch64) + cmake_version="3.19.8" + cmake_sha256sum="807f5afb2a560e00af9640e496d5673afefc2888bf0ed076412884a5ebb547a1" + cmake_platform="Linux-aarch64" + ;; + *) + echo "Unrecognized platform $(uname -s)-$(uname -m)" + exit 1 + ;; +esac +readonly shatool +readonly cmake_sha256sum +readonly cmake_platform + +readonly cmake_filename="cmake-$cmake_version-$cmake_platform" +readonly cmake_tarball="$cmake_filename.tar.gz" + +echo "$cmake_sha256sum $cmake_tarball" > cmake.sha256sum +curl -OL "https://github.com/Kitware/CMake/releases/download/v$cmake_version/$cmake_tarball" +sha256sum --check cmake.sha256sum +tar xzf "$cmake_tarball" -C /opt/extdeps --strip-components=1 +rm -f "$cmake_tarball" cmake.sha256sum + +#---------------------------------------------------------------------------- +# libuv + +curl -L -o libuv-1.28.0.tar.gz https://github.com/libuv/libuv/archive/refs/tags/v1.28.0.tar.gz +tar xzf libuv-1.28.0.tar.gz +cmake -S libuv-1.28.0 -B libuv-1.28.0-build \ + -DCMAKE_INSTALL_PREFIX=/opt/extdeps +cmake --build libuv-1.28.0-build --target install +rm -rf libuv-1.28.0* + +#---------------------------------------------------------------------------- +# jsoncpp + +curl -L -o jsoncpp-1.6.0.tar.gz https://github.com/open-source-parsers/jsoncpp/archive/refs/tags/1.6.0.tar.gz +tar xzf jsoncpp-1.6.0.tar.gz +cmake -S jsoncpp-1.6.0 -B jsoncpp-1.6.0-build \ + -DCMAKE_BUILD_TYPE=Release \ + -DJSONCPP_LIB_BUILD_STATIC=ON \ + -DJSONCPP_LIB_BUILD_SHARED=ON \ + -DCMAKE_INSTALL_PREFIX=/opt/extdeps +cmake --build jsoncpp-1.6.0-build --target install +rm -rf jsoncpp-1.6.0* diff --git a/.gitlab/os-linux.yml b/.gitlab/os-linux.yml index 37e5c22..765518a 100644 --- a/.gitlab/os-linux.yml +++ b/.gitlab/os-linux.yml @@ -45,7 +45,7 @@ ### Debian .debian10: - image: "kitware/cmake:ci-debian10-x86_64-2022-06-21" + image: "kitware/cmake:ci-debian10-x86_64-2022-08-17" variables: GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake ci" @@ -60,7 +60,7 @@ CMAKE_CI_NO_INSTALL: 1 .debian10_aarch64: - image: "kitware/cmake:ci-debian10-aarch64-2022-06-21" + image: "kitware/cmake:ci-debian10-aarch64-2022-08-17" variables: GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake ci" @@ -69,7 +69,7 @@ ### Fedora .fedora36: - image: "kitware/cmake:ci-fedora36-x86_64-2022-06-21" + image: "kitware/cmake:ci-fedora36-x86_64-2022-08-17" variables: GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake ci/long file name for testing purposes" @@ -137,6 +137,30 @@ CMAKE_CI_NO_INSTALL: 1 CTEST_NO_WARNINGS_ALLOWED: 1 +.debian10_extdeps: + extends: .debian10 + + variables: + CMAKE_CONFIGURATION: debian10_extdeps + CMAKE_CI_BUILD_TYPE: Release + CTEST_NO_WARNINGS_ALLOWED: 1 + +.debian10_aarch64_extdeps: + extends: .debian10_aarch64 + + variables: + CMAKE_CONFIGURATION: debian10_aarch64_extdeps + CMAKE_CI_BUILD_TYPE: Release + CTEST_NO_WARNINGS_ALLOWED: 1 + +.fedora36_extdeps: + extends: .fedora36 + + variables: + CMAKE_CONFIGURATION: fedora36_extdeps + CMAKE_CI_BUILD_TYPE: Release + CTEST_NO_WARNINGS_ALLOWED: 1 + .fedora36_ninja: extends: .fedora36 diff --git a/CMakeLists.txt b/CMakeLists.txt index 267518b..9d77dfc 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -648,7 +648,7 @@ macro (CMAKE_BUILD_UTILITIES) #--------------------------------------------------------------------- # Build jsoncpp library. if(CMAKE_USE_SYSTEM_JSONCPP) - find_package(JsonCpp 1.4.1) + find_package(JsonCpp 1.6.0) if(NOT JsonCpp_FOUND) message(FATAL_ERROR "CMAKE_USE_SYSTEM_JSONCPP is ON but a JsonCpp is not found!") diff --git a/Help/guide/tutorial/A Basic Starting Point.rst b/Help/guide/tutorial/A Basic Starting Point.rst index d57cc35..69f6748 100644 --- a/Help/guide/tutorial/A Basic Starting Point.rst +++ b/Help/guide/tutorial/A Basic Starting Point.rst @@ -1,45 +1,81 @@ Step 1: A Basic Starting Point ============================== -The most basic project is an executable built from source code files. -For simple projects, a three line ``CMakeLists.txt`` file is all that is -required. This will be the starting point for our tutorial. Create a -``CMakeLists.txt`` file in the ``Step1`` directory that looks like: - -.. code-block:: cmake - :caption: CMakeLists.txt - :name: CMakeLists.txt-start - - cmake_minimum_required(VERSION 3.10) - - # set the project name - project(Tutorial) - - # add the executable - add_executable(Tutorial tutorial.cxx) - +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. + +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. + +Also note that each step in the tutorial builds on the next. So, for example, +the starting code for ``Step2`` is the complete solution to ``Step1``. + +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 +------------- -Any project's top most ``CMakeLists.txt`` must start by specifying -a minimum CMake version using :command:`cmake_minimum_required`. This ensures -that the later CMake functions are run with a compatible version of CMake. +* ``CMakeLists.txt`` -To start a project, we use :command:`project` to set the project name. This -call is required with every project and should be called soon after -:command:`cmake_minimum_required`. +Getting Started +---------------- -Lastly, we use :command:`add_executable` to specify we want an executable -named Tutorial generated using ``tutorial.cxx`` as the source. +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. -Note that this example uses lower case commands in the ``CMakeLists.txt`` -file. Upper, lower, and mixed case commands are supported by CMake. The source -code for ``tutorial.cxx`` is provided in the ``Step1`` directory and can be -used to compute the square root of a number. +In the same directory is a ``CMakeLists.txt`` file which you will complete. +Start with ``TODO 1`` and work through ``TODO 3``. Build and Run ------------- -That's all that is needed - we can build and run our project now! First, run -the :manual:`cmake <cmake(1)>` executable or the +Once ``TODO 1`` through ``TODO 3`` have been completed, we are ready to build +and run our project! First, run the :manual:`cmake <cmake(1)>` executable or the :manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it with your chosen build tool. @@ -51,8 +87,9 @@ build directory: mkdir Step1_build -Next, navigate to the build directory and run CMake to configure the project -and generate a native build system: +Next, navigate to that build directory and run +:manual:`cmake <cmake(1)>` to configure the project and generate a native build +system: .. code-block:: console @@ -73,115 +110,351 @@ Finally, try to use the newly built ``Tutorial`` with these commands: Tutorial 10 Tutorial +Solution +-------- -Adding a Version Number and Configured Header File --------------------------------------------------- +As mentioned above, a three line ``CMakeLists.txt`` is all that we need to get +up and running. The first line is to use :command:`cmake_minimum_required` to +set the CMake version as follows: -The first feature we will add is to provide our executable and project with a -version number. While we could do this exclusively in the source code, using -``CMakeLists.txt`` provides more flexibility. +.. raw:: html -First, modify the ``CMakeLists.txt`` file to use the :command:`project` command -to set the project name and version number. + <details><summary>TODO 1: Click to show/hide answer</summary> .. literalinclude:: Step2/CMakeLists.txt - :caption: CMakeLists.txt - :name: CMakeLists.txt-project-VERSION + :caption: TODO 1: CMakeLists.txt + :name: CMakeLists.txt-cmake_minimum_required :language: cmake - :end-before: # specify the C++ standard + :end-before: # set the project name and version -Then use :command:`configure_file` to pass the version number to the source -code: +.. raw:: html -.. literalinclude:: Step2/CMakeLists.txt - :caption: CMakeLists.txt - :name: CMakeLists.txt-configure_file - :language: cmake - :start-after: # to the source code - :end-before: # add the executable + </details> -Since the configured file will be written into the binary tree, we -must add that directory to the list of paths to search for include -files. Use :command:`target_include_directories` to add the following lines to -the end of the ``CMakeLists.txt`` file: +The next step to make a basic project is to use the :command:`project` +command as follows to set the project name: + +.. raw:: html + + <details><summary>TODO 2: Click to show/hide answer</summary> + +.. code-block:: cmake + :caption: TODO 2: CMakeLists.txt + :name: CMakeLists.txt-project + + project(Tutorial) + +.. raw:: html + + </details> + +The last command to call for a basic project is +:command:`add_executable`. We call it as follows: + +.. raw:: html + + <details><summary>TODO 3: Click to show/hide answer</summary> .. literalinclude:: Step2/CMakeLists.txt - :caption: CMakeLists.txt - :name: CMakeLists.txt-target_include_directories + :caption: TODO 3: CMakeLists.txt + :name: CMakeLists.txt-add_executable :language: cmake - :start-after: # so that we will find TutorialConfig.h + :start-after: # add the executable + :end-before: # add the binary tree to the search path for include files -Using your favorite editor, create ``TutorialConfig.h.in`` in the source -directory with the following contents: +.. raw:: html -.. literalinclude:: Step2/TutorialConfig.h.in - :caption: TutorialConfig.h.in - :name: TutorialConfig.h.in - :language: c++ + </details> -When CMake configures this header file, the values for -``@Tutorial_VERSION_MAJOR@`` and ``@Tutorial_VERSION_MINOR@`` will be -replaced with the corresponding version numbers from the project. +Exercise 2 - Specifying the C++ Standard +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Next modify ``tutorial.cxx`` to include the configured header file, -``TutorialConfig.h``. +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. -Finally, let's print out the executable name and version number by updating -``tutorial.cxx`` as follows: +Goal +---- -.. literalinclude:: Step2/tutorial.cxx - :caption: tutorial.cxx - :name: tutorial.cxx-print-version - :language: c++ - :start-after: { - :end-before: // convert input to double +Add a feature that requires C++11. -Specify the C++ Standard -------------------------- +Helpful Resources +----------------- -Next let's add some C++11 features to our project by replacing ``atof`` with -``std::stod`` in ``tutorial.cxx``. At the same time, remove -``#include <cstdlib>``. +* :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: tutorial.cxx + :caption: TODO 4: tutorial.cxx :name: tutorial.cxx-cxx11 :language: c++ :start-after: // convert input to double :end-before: // calculate square root +.. 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. The easiest way to enable support for a specific C++ standard -in CMake is by using the :variable:`CMAKE_CXX_STANDARD` variable. For this -tutorial, :command:`set` the :variable:`CMAKE_CXX_STANDARD` variable in the -``CMakeLists.txt`` file to ``11`` and :variable:`CMAKE_CXX_STANDARD_REQUIRED` -to ``True``. Make sure to add the ``CMAKE_CXX_STANDARD`` declarations above the -call to ``add_executable``. +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: 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 to pass some of the CMake settings -Rebuild -------- +.. 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 +----------------- -Let's build our project again. We already created a build directory and ran -CMake, so we can skip to the build step: +* :variable:`<PROJECT-NAME>_VERSION_MAJOR` +* :variable:`<PROJECT-NAME>_VERSION_MINOR` +* :command:`configure_file` +* :command:`target_include_directories` + +Files to Edit +------------- + +* ``CMakeLists.txt`` +* ``tutorial.cxx`` + +Getting Started +--------------- + +Continue to edit files from ``Step1``. Start on ``TODO 7`` and complete through +``TODO 12``. In this exercise, we start by adding a project version number in +``CMakeLists.txt``. In that same file, use :command:`configure_file` to copy a +given input file to an output file and substitute some variable values in the +input file content. + +Next, create an input header file ``TutorialConfig.h.in`` defining version +numbers which will accept variables passed from :command:`configure_file`. + +Finally, update ``tutorial.cxx`` to print out its version number. + +Build and Run +------------- + +Let's build our project again. As before, we already created a build directory +and ran CMake so we can skip to the build step: .. code-block:: console cd Step1_build cmake --build . -Now we can try to use the newly built ``Tutorial`` with same commands as before: +Verify that the version number is now reported when running the executable +without any arguments. -.. code-block:: console +Solution +-------- - Tutorial 4294967296 - Tutorial 10 - Tutorial +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: # add the executable + +.. 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 -Check that the version number is now reported when running the executable without -any arguments. + </details> diff --git a/Help/guide/tutorial/Step1/CMakeLists.txt b/Help/guide/tutorial/Step1/CMakeLists.txt new file mode 100644 index 0000000..282951a --- /dev/null +++ b/Help/guide/tutorial/Step1/CMakeLists.txt @@ -0,0 +1,16 @@ +# TODO 1: Set the minimum required version of CMake to be 3.10 + +# TODO 2: Create a project named Tutorial + +# TODO 7: Set the project version number as 1.0 in the above project command + +# TODO 6: Set the variable CMAKE_CXX_STANDARD to 11 +# and the variable CMAKE_CXX_REQUIRED_STANDARD to True + +# TODO 8: Use configure_file to configure and copy TutorialConfig.h.in to +# TutorialConfig.h + +# TODO 3: Add an executable called Tutorial to the project +# Hint: Be sure to specify the source file as tutorial.cxx + +# TODO 9: Use target_include_directories to include ${PROJECT_BINARY_DIR} diff --git a/Help/guide/tutorial/Step1/TutorialConfig.h.in b/Help/guide/tutorial/Step1/TutorialConfig.h.in new file mode 100644 index 0000000..990bfbd --- /dev/null +++ b/Help/guide/tutorial/Step1/TutorialConfig.h.in @@ -0,0 +1,2 @@ +// 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 index 08323bf..64d0916 100644 --- a/Help/guide/tutorial/Step1/tutorial.cxx +++ b/Help/guide/tutorial/Step1/tutorial.cxx @@ -1,17 +1,22 @@ // A simple program that computes the square root of a number #include <cmath> -#include <cstdlib> +#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]) const double inputValue = atof(argv[1]); // calculate square root diff --git a/Help/manual/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt index 3868276..4220dc0 100644 --- a/Help/manual/OPTIONS_BUILD.txt +++ b/Help/manual/OPTIONS_BUILD.txt @@ -109,20 +109,6 @@ Enable warnings that are meant for the author of the ``CMakeLists.txt`` files. By default this will also turn on deprecation warnings. -.. option:: -Werror=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. - -.. option:: -Wno-error=dev - - Make developer warnings not errors. - - 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. - .. option:: -Wdeprecated Enable deprecated functionality warnings. @@ -137,16 +123,30 @@ Suppress warnings for usage of deprecated functionality, that are meant for the author of the ``CMakeLists.txt`` files. -.. option:: -Werror=deprecated +.. 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 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. - 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> -.. option:: -Wno-error=deprecated + Do not treat CMake warnings as errors. ``<what>`` must be one of the following: - Make deprecated macro and function warnings not errors. + ``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. - Make warnings for usage of deprecated macros and functions, that are meant - for the author of the ``CMakeLists.txt`` files, not errors. + ``deprecated`` + Make warnings for usage of deprecated macros and functions, that are meant + for the author of the ``CMakeLists.txt`` files, not errors. diff --git a/Help/manual/OPTIONS_HELP.txt b/Help/manual/OPTIONS_HELP.txt index 92bdf1e..78ee245 100644 --- a/Help/manual/OPTIONS_HELP.txt +++ b/Help/manual/OPTIONS_HELP.txt @@ -1,33 +1,31 @@ -.. |file| replace:: The help is printed to a named <f>ile if given. +.. |file| replace:: The output is printed to a named ``<file>`` if given. -.. option:: --help, -help, -usage, -h, -H, /? +.. option:: -version [<file>], --version [<file>], /V [<file>] - Print usage information and exit. - - Usage describes the basic command line interface and its options. + Show program name/version banner and exit. + |file| -.. option:: --version, -version, /V [<f>] +.. option:: -h, -H, --help, -help, -usage, /? - Show program name/version banner and exit. + Print usage information and exit. - If a file is specified, the version is written into it. - |file| + Usage describes the basic command line interface and its options. -.. option:: --help-full [<f>] +.. option:: --help-full [<file>] Print all help manuals and exit. All manuals are printed in a human-readable text format. |file| -.. option:: --help-manual <man> [<f>] +.. option:: --help-manual <man> [<file>] Print one help manual and exit. The specified manual is printed in a human-readable text format. |file| -.. option:: --help-manual-list [<f>] +.. option:: --help-manual-list [<file>] List help manuals available and exit. @@ -35,7 +33,7 @@ using the ``--help-manual`` option followed by a manual name. |file| -.. option:: --help-command <cmd> [<f>] +.. option:: --help-command <cmd> [<file>] Print help for one command and exit. @@ -43,7 +41,7 @@ printed in a human-readable text format. |file| -.. option:: --help-command-list [<f>] +.. option:: --help-command-list [<file>] List commands with help available and exit. @@ -51,7 +49,7 @@ using the ``--help-command`` option followed by a command name. |file| -.. option:: --help-commands [<f>] +.. option:: --help-commands [<file>] Print cmake-commands manual and exit. @@ -59,7 +57,7 @@ human-readable text format. |file| -.. option:: --help-module <mod> [<f>] +.. option:: --help-module <mod> [<file>] Print help for one module and exit. @@ -67,7 +65,7 @@ in a human-readable text format. |file| -.. option:: --help-module-list [<f>] +.. option:: --help-module-list [<file>] List modules with help available and exit. @@ -75,7 +73,7 @@ using the ``--help-module`` option followed by a module name. |file| -.. option:: --help-modules [<f>] +.. option:: --help-modules [<file>] Print cmake-modules manual and exit. @@ -83,7 +81,7 @@ text format. |file| -.. option:: --help-policy <cmp> [<f>] +.. option:: --help-policy <cmp> [<file>] Print help for one policy and exit. @@ -91,7 +89,7 @@ printed in a human-readable text format. |file| -.. option:: --help-policy-list [<f>] +.. option:: --help-policy-list [<file>] List policies with help available and exit. @@ -99,7 +97,7 @@ using the ``--help-policy`` option followed by a policy name. |file| -.. option:: --help-policies [<f>] +.. option:: --help-policies [<file>] Print cmake-policies manual and exit. @@ -107,7 +105,7 @@ human-readable text format. |file| -.. option:: --help-property <prop> [<f>] +.. option:: --help-property <prop> [<file>] Print help for one property and exit. @@ -115,7 +113,7 @@ printed in a human-readable text format. |file| -.. option:: --help-property-list [<f>] +.. option:: --help-property-list [<file>] List properties with help available and exit. @@ -123,7 +121,7 @@ using the ``--help-property`` option followed by a property name. |file| -.. option:: --help-properties [<f>] +.. option:: --help-properties [<file>] Print cmake-properties manual and exit. @@ -131,7 +129,7 @@ human-readable text format. |file| -.. option:: --help-variable <var> [<f>] +.. option:: --help-variable <var> [<file>] Print help for one variable and exit. @@ -139,7 +137,7 @@ printed in a human-readable text format. |file| -.. option:: --help-variable-list [<f>] +.. option:: --help-variable-list [<file>] List variables with help available and exit. @@ -147,7 +145,7 @@ using the ``--help-variable`` option followed by a variable name. |file| -.. option:: --help-variables [<f>] +.. option:: --help-variables [<file>] Print cmake-variables manual and exit. diff --git a/Help/manual/ccmake.1.rst b/Help/manual/ccmake.1.rst index bc411a4..cd66d51 100644 --- a/Help/manual/ccmake.1.rst +++ b/Help/manual/ccmake.1.rst @@ -8,7 +8,7 @@ Synopsis .. parsed-literal:: - ccmake [<options>] {<path-to-source> | <path-to-existing-build>} + ccmake [<options>] <path-to-source | path-to-existing-build> Description =========== diff --git a/Help/manual/cmake-gui.1.rst b/Help/manual/cmake-gui.1.rst index 493b625..dd0eeca 100644 --- a/Help/manual/cmake-gui.1.rst +++ b/Help/manual/cmake-gui.1.rst @@ -9,7 +9,7 @@ Synopsis .. parsed-literal:: cmake-gui [<options>] - cmake-gui [<options>] {<path-to-source> | <path-to-existing-build>} + cmake-gui [<options>] <path-to-source | path-to-existing-build> cmake-gui [<options>] -S <path-to-source> -B <path-to-build> cmake-gui [<options>] --browse-manual diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index 02cfa7e..16917ff 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst @@ -391,8 +391,8 @@ Variable References A *variable reference* has the form ``${<variable>}`` and is evaluated inside a `Quoted Argument`_ or an `Unquoted Argument`_. -A variable reference is replaced by the value of the variable, -or by the empty string if the variable is not set. +A variable reference is replaced by the value of the specified +variable or cache entry, or if neither is set, by the empty string. Variable references can nest and are evaluated from the inside out, e.g. ``${outer_${inner_variable}_variable}``. @@ -408,14 +408,16 @@ and how their values are set. An *environment variable reference* has the form ``$ENV{<variable>}``. See the `Environment Variables`_ section for more information. -A *cache variable reference* has the form ``$CACHE{<variable>}``. +A *cache variable reference* has the form ``$CACHE{<variable>}``, +and is replaced by the value of the specified cache entry without +checking for a normal variable of the same name. If the cache +entry does not exist, it is replaced by the empty string. See :variable:`CACHE` for more information. The :command:`if` command has a special condition syntax that allows for variable references in the short form ``<variable>`` -instead of ``${<variable>}``. -However, environment and cache variables always need to be -referenced as ``$ENV{<variable>}`` or ``$CACHE{<variable>}``. +instead of ``${<variable>}``. However, environment variables +always need to be referenced as ``$ENV{<variable>}``. Comments -------- diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst index 290c2ba..16cd54e 100644 --- a/Help/manual/cmake-presets.7.rst +++ b/Help/manual/cmake-presets.7.rst @@ -40,7 +40,6 @@ The files are a JSON document with an object as the root: The root object recognizes the following fields: ``version`` - A required integer representing the version of the JSON schema. The supported versions are: @@ -60,31 +59,25 @@ The root object recognizes the following fields: .. versionadded:: 3.24 ``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 @@ -93,17 +86,14 @@ The root object recognizes the following fields: 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. @@ -134,7 +124,6 @@ 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`` @@ -142,7 +131,6 @@ that may contain the following fields: However, a configure preset may have the same name as a build or test preset. ``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 @@ -151,7 +139,6 @@ that may contain the following fields: 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. @@ -169,12 +156,10 @@ that may contain the following fields: ``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 @@ -183,15 +168,12 @@ that may contain the following fields: 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`` @@ -203,27 +185,22 @@ that may contain the following fields: in the generator name. Use the ``architecture`` field instead. ``architecture``, ``toolset`` - Optional fields representing the platform and toolset, respectively, for generators that support them. 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 @@ -232,7 +209,6 @@ that may contain the following fields: before invoking CMake. ``toolchainFile`` - An optional string representing the path to the toolchain file. This field supports `macro expansion`_. If a relative path is specified, it is calculated relative to the build directory, and if not found, @@ -241,7 +217,6 @@ that may contain the following fields: specifying version ``3`` or above. ``binaryDir`` - An optional string representing the path to the output binary directory. This field supports `macro expansion`_. If a relative path is specified, it is calculated relative to the source directory. If ``binaryDir`` is not @@ -250,20 +225,17 @@ that may contain the following fields: 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 @@ -271,11 +243,9 @@ that may contain the following fields: 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`_. @@ -288,7 +258,6 @@ that may contain the following fields: 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 @@ -306,18 +275,15 @@ that may contain the following fields: 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. @@ -325,58 +291,50 @@ that may contain the following fields: ``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 ``-Werror=dev`` or - ``-Wno-error=dev`` on the command line. This may not be set to ``true`` - if ``warnings.dev`` is set to ``false``. + 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 ``-Werror=deprecated`` or - ``-Wno-error=deprecated`` on the command line. This may not be set to - ``true`` if ``warnings.deprecated`` is set to ``false``. + 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. @@ -387,7 +345,6 @@ 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. @@ -396,7 +353,6 @@ that may contain the following fields: However, a build preset may have the same name as a configure or test preset. ``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 @@ -405,7 +361,6 @@ that may contain the following fields: 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. @@ -423,12 +378,10 @@ that may contain the following fields: ``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 @@ -437,15 +390,12 @@ that may contain the following fields: 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 @@ -476,7 +426,6 @@ that may contain the following fields: 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 @@ -485,36 +434,30 @@ that may contain the following fields: 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 --parallel>` or ``-j`` on the command line. ``targets`` - An optional string or array of strings. Equivalent to passing :option:`--target <cmake --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 --config>` on the command line. ``cleanFirst`` - An optional bool. If true, equivalent to passing :option:`--clean-first <cmake --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. @@ -524,16 +467,13 @@ that may contain the following fields: 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:: @@ -552,12 +492,10 @@ that may contain the following fields: done from within a configure preset. ``verbose`` - An optional bool. If true, equivalent to passing :option:`--verbose <cmake --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. @@ -568,15 +506,13 @@ 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 :ref:`ctest --preset <CTest Options>` option. + 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 or build preset. ``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 @@ -585,7 +521,6 @@ that may contain the following fields: 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. @@ -603,12 +538,10 @@ that may contain the following fields: ``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 @@ -617,15 +550,12 @@ that may contain the following fields: 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 @@ -643,7 +573,6 @@ that may contain the following fields: 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 @@ -652,103 +581,85 @@ that may contain the following fields: 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. ``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 @@ -756,42 +667,34 @@ that may contain the following fields: ``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 @@ -799,99 +702,81 @@ that may contain the following fields: 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: @@ -901,13 +786,11 @@ that may contain the following fields: ``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`` @@ -917,11 +800,9 @@ that may contain the following fields: ``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 @@ -929,32 +810,26 @@ that may contain the following fields: 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. @@ -972,65 +847,53 @@ a ``not``, ``anyOf``, or ``allOf`` condition) may not be ``null``. If it is an object, it has the following fields: ``type`` - A required string with one of the following values: ``"const"`` - Indicates that the condition is constant. This is equivalent to using a boolean in place of the object. The condition object will have the following additional fields: ``value`` - A required boolean which provides a constant value for the condition's evaluation. ``"equals"`` ``"notEquals"`` - Indicates that the condition compares two strings to see if they are equal (or not equal). The condition object will have the following additional fields: ``lhs`` - First string to compare. This field supports macro expansion. ``rhs`` - Second string to compare. This field supports macro expansion. ``"inList"`` ``"notInList"`` - Indicates that the condition searches for a string in a list of strings. The condition object will have the following additional fields: ``string`` - A required string to search for. This field supports macro expansion. ``list`` - A required list of strings to search. This field supports macro expansion, and uses short-circuit evaluation. ``"matches"`` ``"notMatches"`` - Indicates that the condition searches for a regular expression in a string. The condition object will have the following additional fields: ``string`` - A required string to search. This field supports macro expansion. ``regex`` - A required regular expression to search for. This field supports macro expansion. @@ -1042,17 +905,14 @@ object, it has the following fields: conditions. The condition object will have the following additional fields: ``conditions`` - A required array of condition objects. These conditions use short-circuit evaluation. ``"not"`` - Indicates that the condition is an inversion of another condition. The condition object will have the following additional fields: ``condition`` - A required condition object. Macro Expansion @@ -1074,46 +934,37 @@ interpreted as a literal dollar sign. Recognized macros include: ``${sourceDir}`` - Path to the project source directory (i.e. the same as :variable:`CMAKE_SOURCE_DIR`). ``${sourceParentDir}`` - Path to the project source directory's parent directory. ``${sourceDirName}`` - The last filename component of ``${sourceDir}``. For example, if ``${sourceDir}`` is ``/path/to/source``, this would be ``source``. ``${presetName}`` - Name specified in the preset's ``name`` field. ``${generator}`` - Generator specified in the preset's ``generator`` field. For build and test presets, this will evaluate to the generator specified by ``configurePreset``. ``${hostSystemName}`` - The name of the host operating system. Contains the same value as :variable:`CMAKE_HOST_SYSTEM_NAME`. This is allowed in preset files specifying version ``3`` or above. ``${fileDir}`` - Path to the directory containing the preset file which contains the macro. This is allowed in preset files specifying version ``4`` or above. ``${dollar}`` - A literal dollar sign (``$``). ``${pathListSep}`` - Native character for separating lists of paths, such as ``:`` or ``;``. For example, by setting ``PATH`` to @@ -1124,7 +975,6 @@ Recognized macros include: 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`` field, that value is used instead of the value from the parent environment. @@ -1137,7 +987,6 @@ Recognized macros include: the casing of environment variable names consistent. ``$penv{<variable-name>}`` - Similar to ``$env{<variable-name>}``, except that the value only comes from the parent environment, and never from the ``environment`` field. This allows you to prepend or append values to existing environment variables. @@ -1147,7 +996,6 @@ Recognized macros include: references. ``$vendor{<macro-name>}`` - An extension point for vendors to insert their own macros. CMake will not be able to use presets which have a ``$vendor{<macro-name>}`` macro, and effectively ignores such presets. However, it will still be able to use diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst index e194df0..7fa73e7 100644 --- a/Help/manual/cmake-toolchains.7.rst +++ b/Help/manual/cmake-toolchains.7.rst @@ -96,7 +96,8 @@ Cross Compiling =============== If :manual:`cmake(1)` is invoked with the command line parameter -``--toolchain path/to/file`` or ``-DCMAKE_TOOLCHAIN_FILE=path/to/file``, the +:option:`--toolchain path/to/file <cmake --toolchain>` or +:option:`-DCMAKE_TOOLCHAIN_FILE=path/to/file <cmake -D>`, the file will be loaded early to set values for the compilers. The :variable:`CMAKE_CROSSCOMPILING` variable is set to true when CMake is cross-compiling. diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index ff6ae80..8cec9d4 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -9,8 +9,7 @@ Synopsis .. parsed-literal:: `Generate a Project Buildsystem`_ - cmake [<options>] <path-to-source> - cmake [<options>] <path-to-existing-build> + cmake [<options>] <path-to-source | path-to-existing-build> cmake [<options>] -S <path-to-source> -B <path-to-build> `Build a Project`_ @@ -23,7 +22,7 @@ Synopsis cmake --open <dir> `Run a Script`_ - cmake [{-D <var>=<value>}...] -P <cmake-script-file> + cmake [-D <var>=<value>]... -P <cmake-script-file> `Run a Command-Line Tool`_ cmake -E <command> [<options>] @@ -243,12 +242,13 @@ Options from the top of a binary tree for a CMake project it will dump additional information such as the cache, log files etc. -.. option:: --log-level=<ERROR|WARNING|NOTICE|STATUS|VERBOSE|DEBUG|TRACE> +.. option:: --log-level=<level> - Set the log level. + Set the log ``<level>``. The :command:`message` command will only output messages of the specified - log level or higher. The default log level is ``STATUS``. + log level or higher. The valid log levels are ``ERROR``, ``WARNING``, + ``NOTICE``, ``STATUS`` (default), ``VERBOSE``, ``DEBUG``, or ``TRACE``. To make a log level persist between CMake runs, set :variable:`CMAKE_MESSAGE_LOG_LEVEL` as a cache variable instead. @@ -497,10 +497,12 @@ Options a variable called ``MYVAR`` to ``1``, but the user sets it to ``2`` with a ``-D`` argument, the value ``2`` is preferred. -.. option:: --list-presets, --list-presets=<[configure | build | test | all]> +.. option:: --list-presets[=<type>] - Lists the available presets. If no option is specified only configure presets - will be listed. The current working directory must contain CMake preset files. + Lists the available presets of the specified ``<type>``. Valid values for + ``<type>`` are ``configure``, ``build``, ``test``, or ``all``. If ``<type>`` + is omitted, ``configure`` is assumed. The current working directory must + contain CMake preset files. .. _`Build Tool Mode`: @@ -535,7 +537,7 @@ following options: Lists the available build presets. The current working directory must contain CMake preset files. -.. option:: --parallel [<jobs>], -j [<jobs>] +.. option:: -j [<jobs>], --parallel [<jobs>] The maximum number of concurrent processes to use when building. If ``<jobs>`` is omitted the native build tool's default number is used. @@ -546,7 +548,7 @@ following options: Some native build tools always build in parallel. The use of ``<jobs>`` value of ``1`` can be used to limit to a single job. -.. option:: --target <tgt>..., -t <tgt>... +.. option:: -t <tgt>..., --target <tgt>... Build ``<tgt>`` instead of the default target. Multiple targets may be given, separated by spaces. @@ -560,14 +562,15 @@ following options: Build target ``clean`` first, then build. (To clean only, use :option:`--target clean <cmake --target>`.) -.. option:: --resolve-package-references=<on|off|only> +.. option:: --resolve-package-references=<value> .. versionadded:: 3.23 Resolve remote package references from external package managers (e.g. NuGet) - before build. When set to ``on`` (default), packages will be restored before - building a target. When set to ``only``, the packages will be restored, but no - build will be performed. When set to ``off``, no packages will be restored. + before build. When ``<value>`` is set to ``on`` (default), packages will be + restored before building a target. When ``<value>`` is set to ``only``, the + packages will be restored, but no build will be performed. When + ``<value>`` is set to ``off``, no packages will be restored. If the target does not define any package references, this option does nothing. @@ -669,7 +672,7 @@ Run a Script .. code-block:: shell - cmake [{-D <var>=<value>}...] -P <cmake-script-file> [-- <unparsed-options>...] + cmake [-D <var>=<value>]... -P <cmake-script-file> [-- <unparsed-options>...] .. option:: -D <var>=<value> @@ -859,11 +862,29 @@ Available commands are: Displays arguments as text but no new line. -.. option:: env [--unset=NAME ...] [NAME=VALUE ...] [--] <command> [<arg>...] +.. option:: env [<options>] [--] <command> [<arg>...] .. versionadded:: 3.1 - Run command in a modified environment. + Run command in a modified environment. Options are: + + ``NAME=VALUE`` + Replaces the current value of ``NAME`` with ``VALUE``. + + ``--unset=NAME`` + Unsets the current value of ``NAME``. + + ``--modify ENVIRONMENT_MODIFICATION`` + .. versionadded:: 3.25 + + Apply a single :prop_test:`ENVIRONMENT_MODIFICATION` operation to the + modified environment. + + The ``NAME=VALUE`` and ``--unset=NAME`` options are equivalent to + ``--modify NAME=set:VALUE`` and ``--modify NAME=unset:``, respectively. + Note that ``--modify NAME=reset:`` resets ``NAME`` to the value it had + when ``cmake`` launched (or unsets it), not to the most recent + ``NAME=VALUE`` option. .. versionadded:: 3.24 Added support for the double dash argument ``--``. Use ``--`` to stop diff --git a/Help/manual/cpack.1.rst b/Help/manual/cpack.1.rst index 4861e95..a95df8b 100644 --- a/Help/manual/cpack.1.rst +++ b/Help/manual/cpack.1.rst @@ -73,7 +73,7 @@ Options details. By default, ``CPackConfig.cmake`` in the current directory will be used. -.. option:: --verbose, -V +.. option:: -V, --verbose Run ``cpack`` with verbose output. This can be used to show more details from the package generation tools and is suitable for project developers. diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 713a98d..fe81a46 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -10,12 +10,24 @@ Synopsis .. parsed-literal:: - ctest [<options>] - ctest --build-and-test <path-to-source> <path-to-build> - --build-generator <generator> [<options>...] - [--build-options <opts>...] [--test-command <command> [<args>...]] - ctest {-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>} - [-- <dashboard-options>...] + `Run Tests`_ + ctest [<options>] + + `Build and Test Mode`_ + ctest --build-and-test <path-to-source> <path-to-build> + --build-generator <generator> [<options>...] + [--build-options <opts>...] + [--test-command <command> [<args>...]] + + `Dashboard Client`_ + ctest -D <dashboard> [-- <dashboard-options>...] + ctest -M <model> -T <action> [-- <dashboard-options>...] + ctest -S <script> [-- <dashboard-options>...] + ctest -SP <script> [-- <dashboard-options>...] + + `View Help`_ + ctest --help[-<topic>] + Description =========== @@ -25,14 +37,13 @@ CMake-generated build trees created for projects that use the :command:`enable_testing` and :command:`add_test` commands have testing support. This program will run the tests and report results. -.. _`CTest Options`: +.. _`Run Tests`: -Options -======= +Run Tests +========= .. program:: ctest - .. option:: --preset <preset>, --preset=<preset> Use a test preset to specify test options. The project binary directory @@ -76,6 +87,7 @@ Options displayed. This option will show all test output. .. option:: -VV, --extra-verbose + Enable more verbose output from tests. Test output is normally suppressed and only summary information is @@ -138,6 +150,7 @@ Options ``TestLoad`` option of the `CTest Test Step`_. .. option:: -Q, --quiet + Make CTest quiet. This option will suppress all the output. The output log file will @@ -237,73 +250,6 @@ Options Same as :option:`-FA <ctest -FA>` except only matching cleanup tests are excluded. -.. option:: -D <dashboard>, --dashboard <dashboard> - - Execute dashboard test. - - This option tells CTest to act as a CDash client and perform a - dashboard test. All tests are ``<Mode><Test>``, where ``<Mode>`` can be - ``Experimental``, ``Nightly``, and ``Continuous``, and ``<Test>`` can be - ``Start``, ``Update``, ``Configure``, ``Build``, ``Test``, - ``Coverage``, and ``Submit``. - - See `Dashboard Client`_. - -.. option:: -D <var>:<type>=<value> - - 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. - Parsing ``-D`` arguments as variable values is only attempted if the value - following ``-D`` does not match any of the known dashboard types. - -.. option:: -M <model>, --test-model <model> - - Sets the model for a dashboard. - - 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>`. - - See `Dashboard Client`_. - -.. option:: -T <action>, --test-action <action> - - Sets the dashboard action to perform. - - 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>`. - - See `Dashboard Client`_. - -.. option:: -S <script>, --script <script> - - Execute a dashboard for a configuration. - - This option tells CTest to load in a configuration script which sets - a number of parameters such as the binary and source directories. - Then CTest will do what is required to create and run a dashboard. - This option basically sets up a dashboard and then runs :option:`ctest -D` - with the appropriate options. - - See `Dashboard Client`_. - -.. option:: -SP <script>, --script-new-process <script> - - 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. - - See `Dashboard Client`_. - .. option:: -I [Start,End,Stride,test#,test#|Test file], --tests-information Run a specific number of tests by number. @@ -400,13 +346,9 @@ Options See `Label and Subproject Summary`_. -.. option:: --build-and-test - - See `Build and Test Mode`_. - .. option:: --test-dir <dir> -Specify the directory in which to look for tests. + Specify the directory in which to look for tests. .. option:: --test-output-size-passed <size> @@ -477,15 +419,22 @@ Specify the directory in which to look for tests. This option will not run any tests, it will simply print the list of all labels associated with the test set. -.. option:: --no-tests=<[error|ignore]> +.. option:: --no-tests=<action> - Regard no tests found either as error or ignore it. + Regard no tests found either as error (when ``<action>`` is set to + ``error``) or ignore it (when ``<action>`` is set to ``ignore``). 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. +View Help +========= + +To print version details or selected pages from the CMake documentation, +use one of the following options: + .. include:: OPTIONS_HELP.txt .. _`Label Matching`: @@ -595,6 +544,10 @@ be provided to use ``--build-and-test``. If ``--test-command`` is specified then that will be run after the build is complete. Other options that affect this mode include: +.. option:: --build-and-test + + Switch into the build and test mode. + .. option:: --build-target Specify a specific target to build. The option can be given multiple times @@ -682,11 +635,78 @@ application. As a dashboard client, CTest performs a sequence of steps to configure, build, and test software, and then submits the results to a `CDash`_ server. The command-line signature used to submit to `CDash`_ is:: - ctest (-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>) - [-- <dashboard-options>...] + ctest -D <dashboard> [-- <dashboard-options>...] + ctest -M <model> -T <action> [-- <dashboard-options>...] + ctest -S <script> [-- <dashboard-options>...] + ctest -SP <script> [-- <dashboard-options>...] Options for Dashboard Client include: +.. option:: -D <dashboard>, --dashboard <dashboard> + + Execute dashboard test. + + This option tells CTest to act as a CDash client and perform a + dashboard test. All tests are ``<Mode><Test>``, where ``<Mode>`` can be + ``Experimental``, ``Nightly``, and ``Continuous``, and ``<Test>`` can be + ``Start``, ``Update``, ``Configure``, ``Build``, ``Test``, + ``Coverage``, and ``Submit``. + + If ``<dashboard>`` is not one of the recognized ``<Mode><Test>`` values, + this will be treated as a variable definition instead (see the + :ref:`dashboard-options <Dashboard Options>` further below). + +.. option:: -M <model>, --test-model <model> + + Sets the model for a dashboard. + + 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>`. + +.. option:: -T <action>, --test-action <action> + + Sets the dashboard action to perform. + + 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>`. + +.. option:: -S <script>, --script <script> + + Execute a dashboard for a configuration. + + This option tells CTest to load in a configuration script which sets + a number of parameters such as the binary and source directories. + Then CTest will do what is required to create and run a dashboard. + This option basically sets up a dashboard and then runs :option:`ctest -D` + with the appropriate options. + +.. option:: -SP <script>, --script-new-process <script> + + 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. + +.. _`Dashboard Options`: + +The available ``<dashboard-options>`` are the following: + +.. option:: -D <var>:<type>=<value> + + 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. + Parsing ``-D`` arguments as variable values is only attempted if the value + following ``-D`` does not match any of the known dashboard types. + .. option:: --group <group> Specify what group you'd like to submit results to @@ -810,7 +830,7 @@ Run the ``ctest`` command with the current working directory set to the build tree and use one of these signatures:: ctest -D <mode>[<step>] - ctest -M <mode> [ -T <step> ]... + ctest -M <mode> [-T <step>]... The ``<mode>`` must be one of the above `Dashboard Client Modes`_, and each ``<step>`` must be one of the above `Dashboard Client Steps`_. diff --git a/Help/prop_test/LABELS.rst b/Help/prop_test/LABELS.rst index a06f152..d827adc 100644 --- a/Help/prop_test/LABELS.rst +++ b/Help/prop_test/LABELS.rst @@ -4,7 +4,7 @@ LABELS Specify a list of text labels associated with a test. The labels are reported in both the ``ctest`` output summary and in dashboard submissions. They can also be used to filter the set of tests to be executed (see the -``ctest -L`` and ``ctest -LE`` :ref:`CTest Options`). +:option:`ctest -L` and :option:`ctest -LE` options). See :ref:`Additional Labels` for adding labels to a test dynamically during test execution. diff --git a/Help/release/3.24.rst b/Help/release/3.24.rst index 3141255..ecf6f1c 100644 --- a/Help/release/3.24.rst +++ b/Help/release/3.24.rst @@ -317,6 +317,11 @@ Deprecated and Removed Features * The :module:`FindGLUT` module no longer provides the undocumented ``GLUT_LIBRARY`` and ``GLUT_INCLUDE_PATH`` result variables. +* The :module:`FindVulkan` module no longer silently ignores unknown + components requested by a ``find_package(Vulkan REQUIRED ...)`` call. + With the addition of support for components, requests for unknown + components now produce an error. + Other Changes ============= @@ -357,5 +362,6 @@ Changes made since CMake 3.24.0 include the following. 3.24.1 ------ -* The :prop_tgt:`COMPILE_WARNING_AS_ERROR` target property now supports the - TI compiler. +* This version 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/cmake-E-env-modify.rst b/Help/release/dev/cmake-E-env-modify.rst new file mode 100644 index 0000000..ea4a622 --- /dev/null +++ b/Help/release/dev/cmake-E-env-modify.rst @@ -0,0 +1,5 @@ +cmake-E-env-modify +------------------ + +* A new ``--modify`` flag was added to :option:`cmake -E env <cmake_E env>` to support :prop_test:`ENVIRONMENT_MODIFICATION` + operations. diff --git a/Help/variable/CMAKE_BINARY_DIR.rst b/Help/variable/CMAKE_BINARY_DIR.rst index 3b323b7..f9c7689 100644 --- a/Help/variable/CMAKE_BINARY_DIR.rst +++ b/Help/variable/CMAKE_BINARY_DIR.rst @@ -7,7 +7,7 @@ This is the full path to the top level of the current CMake build tree. For an in-source build, this would be the same as :variable:`CMAKE_SOURCE_DIR`. -When run in -P script mode, CMake sets the variables +When run in :option:`-P <cmake_P -P>` script mode, CMake sets the variables :variable:`CMAKE_BINARY_DIR`, :variable:`CMAKE_SOURCE_DIR`, :variable:`CMAKE_CURRENT_BINARY_DIR` and :variable:`CMAKE_CURRENT_SOURCE_DIR` to the current working directory. diff --git a/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst b/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst index 8fc85ee..6f82dcc 100644 --- a/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst +++ b/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst @@ -9,7 +9,7 @@ create a binary directory in the build tree, and as it is being processed this variable will be set. For in-source builds this is the current source directory being processed. -When run in -P script mode, CMake sets the variables +When run in :option:`-P <cmake_P -P>` script mode, CMake sets the variables :variable:`CMAKE_BINARY_DIR`, :variable:`CMAKE_SOURCE_DIR`, :variable:`CMAKE_CURRENT_BINARY_DIR` and :variable:`CMAKE_CURRENT_SOURCE_DIR` to the current working directory. diff --git a/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst b/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst index 1a25efc..0678f99 100644 --- a/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst +++ b/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst @@ -6,7 +6,7 @@ The path to the source directory currently being processed. This is the full path to the source directory that is currently being processed by cmake. -When run in -P script mode, CMake sets the variables +When run in :option:`-P <cmake_P -P>` script mode, CMake sets the variables :variable:`CMAKE_BINARY_DIR`, :variable:`CMAKE_SOURCE_DIR`, :variable:`CMAKE_CURRENT_BINARY_DIR` and :variable:`CMAKE_CURRENT_SOURCE_DIR` to the current working directory. diff --git a/Help/variable/CMAKE_LANG_COMPILER_ID.rst b/Help/variable/CMAKE_LANG_COMPILER_ID.rst index 6a0a1d9..f0534ba 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_ID.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_ID.rst @@ -6,43 +6,60 @@ Compiler identification string. A short string unique to the compiler vendor. Possible values include: -:: - - Absoft = Absoft Fortran (absoft.com) - ADSP = Analog VisualDSP++ (analog.com) - AppleClang = Apple Clang (apple.com) - ARMCC = ARM Compiler (arm.com) - ARMClang = ARM Compiler based on Clang (arm.com) - Bruce = Bruce C Compiler - CCur = Concurrent Fortran (ccur.com) - Clang = LLVM Clang (clang.llvm.org) - Cray = Cray Compiler (cray.com) - Embarcadero, Borland = Embarcadero (embarcadero.com) - Flang = Classic Flang Fortran Compiler (https://github.com/flang-compiler/flang) - LLVMFlang = LLVM Flang Fortran Compiler (https://github.com/llvm/llvm-project/tree/main/flang) - Fujitsu = Fujitsu HPC compiler (Trad mode) - FujitsuClang = Fujitsu HPC compiler (Clang mode) - G95 = G95 Fortran (g95.org) - GNU = GNU Compiler Collection (gcc.gnu.org) - GHS = Green Hills Software (www.ghs.com) - HP = Hewlett-Packard Compiler (hp.com) - IAR = IAR Systems (iar.com) - Intel = Intel Compiler (intel.com) - IntelLLVM = Intel LLVM-Based Compiler (intel.com) - LCC = MCST Elbrus C/C++/Fortran Compiler (mcst.ru) - MSVC = Microsoft Visual Studio (microsoft.com) - NVHPC = NVIDIA HPC SDK Compiler (nvidia.com) - NVIDIA = NVIDIA CUDA Compiler (nvidia.com) - OpenWatcom = Open Watcom (openwatcom.org) - PGI = The Portland Group (pgroup.com) - PathScale = PathScale (pathscale.com) - SDCC = Small Device C Compiler (sdcc.sourceforge.net) - SunPro = Oracle Solaris Studio (oracle.com) - TI = Texas Instruments (ti.com) - TinyCC = Tiny C Compiler (tinycc.org) - XL, VisualAge, zOS = IBM XL (ibm.com) - XLClang = IBM Clang-based XL (ibm.com) - IBMClang = IBM LLVM-based Compiler (ibm.com) +=============================== =============================================== +Value Name +=============================== =============================================== +``Absoft`` `Absoft Fortran`_ +``ADSP`` Analog VisualDSP++ +``AppleClang`` Apple Clang +``ARMCC`` ARM Compiler +``ARMClang`` ARM Compiler based on Clang +``Bruce`` Bruce C Compiler +``CCur`` Concurrent Fortran +``Clang`` `LLVM Clang`_ +``Cray`` Cray Compiler +``Embarcadero``, ``Borland`` `Embarcadero`_ +``Flang`` `Classic Flang Fortran Compiler`_ +``LLVMFlang`` `LLVM Flang Fortran Compiler`_ +``Fujitsu`` Fujitsu HPC compiler (Trad mode) +``FujitsuClang`` Fujitsu HPC compiler (Clang mode) +``G95`` `G95 Fortran`_ +``GNU`` `GNU Compiler Collection`_ +``GHS`` `Green Hills Software`_ +``HP`` Hewlett-Packard Compiler +``IAR`` IAR Systems +``Intel`` Intel Compiler +``IntelLLVM`` Intel LLVM-Based Compiler +``LCC`` MCST Elbrus C/C++/Fortran Compiler +``MSVC`` `Microsoft Visual Studio`_ +``NVHPC`` `NVIDIA HPC Compiler`_ +``NVIDIA`` `NVIDIA CUDA Compiler`_ +``OpenWatcom`` `Open Watcom`_ +``PGI`` The Portland Group +``PathScale`` PathScale +``SDCC`` `Small Device C Compiler`_ +``SunPro`` Oracle Solaris Studio +``TI`` Texas Instruments +``TinyCC`` `Tiny C Compiler`_ +``XL``, ``VisualAge``, ``zOS`` IBM XL +``XLClang`` IBM Clang-based XL +``IBMClang`` IBM LLVM-based Compiler +=============================== =============================================== This variable is not guaranteed to be defined for all compilers or languages. + +.. _Absoft Fortran: https://www.absoft.com +.. _LLVM Clang: https://clang.llvm.org +.. _Embarcadero: https://www.embarcadero.com +.. _Classic Flang Fortran Compiler: https://github.com/flang-compiler/flang +.. _LLVM Flang Fortran Compiler: https://github.com/llvm/llvm-project/tree/main/flang +.. _G95 Fortran: http://g95.sourceforge.net +.. _GNU Compiler Collection: https://gcc.gnu.org +.. _Green Hills Software: https://www.ghs.com/products/compiler.html +.. _Microsoft Visual Studio: https://visualstudio.microsoft.com +.. _NVIDIA HPC Compiler: https://developer.nvidia.com/hpc-compilers +.. _NVIDIA CUDA Compiler: https://developer.nvidia.com/cuda-llvm-compiler +.. _Open Watcom: https://open-watcom.github.io +.. _Small Device C Compiler: http://sdcc.sourceforge.net +.. _Tiny C Compiler: https://bellard.org/tcc diff --git a/Help/variable/CMAKE_SOURCE_DIR.rst b/Help/variable/CMAKE_SOURCE_DIR.rst index d1f1798..32e6e90 100644 --- a/Help/variable/CMAKE_SOURCE_DIR.rst +++ b/Help/variable/CMAKE_SOURCE_DIR.rst @@ -7,7 +7,7 @@ This is the full path to the top level of the current CMake source tree. For an in-source build, this would be the same as :variable:`CMAKE_BINARY_DIR`. -When run in ``-P`` script mode, CMake sets the variables +When run in :option:`-P <cmake_P -P>` script mode, CMake sets the variables :variable:`CMAKE_BINARY_DIR`, :variable:`CMAKE_SOURCE_DIR`, :variable:`CMAKE_CURRENT_BINARY_DIR` and :variable:`CMAKE_CURRENT_SOURCE_DIR` to the current working directory. diff --git a/Modules/CMakeDetermineCompilerId.cmake b/Modules/CMakeDetermineCompilerId.cmake index 2b19736..6b58549 100644 --- a/Modules/CMakeDetermineCompilerId.cmake +++ b/Modules/CMakeDetermineCompilerId.cmake @@ -720,7 +720,7 @@ Id flags: ${testflags} ${CMAKE_${lang}_COMPILER_ID_FLAGS_ALWAYS} OR CMAKE_${lang}_COMPILER_ID_OUTPUT MATCHES "warning #5117: Bad # preprocessor line" ) # Compilation failed. - set(MSG + string(APPEND _CMAKE_DETERMINE_COMPILER_ID_BUILD_MSG "Compiling the ${lang} compiler identification source file \"${src}\" failed. ${COMPILER_DESCRIPTION} The output was: @@ -736,7 +736,11 @@ ${CMAKE_${lang}_COMPILER_ID_OUTPUT} # Some languages may know the correct/desired set of flags and want to fail right away if they don't work. # This is currently only used by CUDA. if(__compiler_id_require_success) - message(FATAL_ERROR "${MSG}") + message(FATAL_ERROR "${_CMAKE_DETERMINE_COMPILER_ID_BUILD_MSG}") + else() + # Build up the outputs for compiler detection attempts so that users + # can see all set of flags tried, instead of just last + set(_CMAKE_DETERMINE_COMPILER_ID_BUILD_MSG "${_CMAKE_DETERMINE_COMPILER_ID_BUILD_MSG}" PARENT_SCOPE) endif() # No output files should be inspected. diff --git a/Modules/CMakeDetermineFortranCompiler.cmake b/Modules/CMakeDetermineFortranCompiler.cmake index 650c87a..087c0f6 100644 --- a/Modules/CMakeDetermineFortranCompiler.cmake +++ b/Modules/CMakeDetermineFortranCompiler.cmake @@ -44,17 +44,14 @@ else() # finally list compilers to try if(NOT CMAKE_Fortran_COMPILER_INIT) # Known compilers: - # f77/f90/f95: generic compiler names # ftn: Cray fortran compiler wrapper - # g77: GNU Fortran 77 compiler # gfortran: putative GNU Fortran 95+ compiler (in progress) - # fort77: native F77 compiler under HP-UX (and some older Crays) - # frt: Fujitsu F77 compiler + # frt: Fujitsu Fortran compiler # pathf90/pathf95/pathf2003: PathScale Fortran compiler - # pgf77/pgf90/pgf95/pgfortran: Portland Group F77/F90/F95 compilers + # pgfortran: Portland Group Fortran compilers # nvfortran: NVHPC Fotran compiler # flang: Flang Fortran compiler - # xlf/xlf90/xlf95: IBM (AIX) F77/F90/F95 compilers + # xlf: IBM (AIX) Fortran compiler # lf95: Lahey-Fujitsu F95 compiler # fl32: Microsoft Fortran 77 "PowerStation" compiler # af77: Apogee F77 compiler for Intergraph hardware running CLIX @@ -62,31 +59,20 @@ else() # fort: Compaq (now HP) Fortran 90/95 compiler for Tru64 and Linux/Alpha # ifx: Intel Fortran LLVM-based compiler # ifort: Intel Classic Fortran compiler - # ifc: Intel Fortran 95 compiler for Linux/x86 - # efc: Intel Fortran 95 compiler for IA64 # nagfor: NAG Fortran compiler # - # The order is 95 or newer compilers first, then 90, - # then 77 or older compilers, gnu is always last in the group, + # GNU is last to be searched, # so if you paid for a compiler it is picked by default. - if(CMAKE_HOST_WIN32) - set(CMAKE_Fortran_COMPILER_LIST - ifort ifx pgf95 pgfortran nvfortran lf95 fort - flang gfortran gfortran-4 g95 f90 pgf90 - pgf77 g77 f77 nag - ) - else() - set(CMAKE_Fortran_COMPILER_LIST - ftn - ifort ifc ifx efc pgf95 pgfortran nvfortran lf95 xlf95 fort - flang lfortran gfortran gfortran-4 g95 f90 pgf90 - frt pgf77 xlf g77 f77 nag - ) - endif() + set(CMAKE_Fortran_COMPILER_LIST + ftn + ifx ifort nvfortran pgfortran lf95 xlf fort + flang lfortran frt nagfor + gfortran + ) # Vendor-specific compiler names. set(_Fortran_COMPILER_NAMES_LCC lfortran gfortran) - set(_Fortran_COMPILER_NAMES_GNU gfortran gfortran-4 g95 g77) + set(_Fortran_COMPILER_NAMES_GNU gfortran) set(_Fortran_COMPILER_NAMES_Intel ifort ifc efc ifx) set(_Fortran_COMPILER_NAMES_Absoft af95 af90 af77) set(_Fortran_COMPILER_NAMES_PGI pgf95 pgfortran pgf90 pgf77) diff --git a/Modules/FindVulkan.cmake b/Modules/FindVulkan.cmake index 2f69234..3817987 100644 --- a/Modules/FindVulkan.cmake +++ b/Modules/FindVulkan.cmake @@ -222,6 +222,16 @@ environment. cmake_policy(PUSH) cmake_policy(SET CMP0057 NEW) +# Provide compatibility with a common invalid component request that +# was silently ignored prior to CMake 3.24. +if("FATAL_ERROR" IN_LIST Vulkan_FIND_COMPONENTS) + message(AUTHOR_WARNING + "Ignoring unknown component 'FATAL_ERROR'.\n" + "The find_package() command documents no such argument." + ) + list(REMOVE_ITEM Vulkan_FIND_COMPONENTS "FATAL_ERROR") +endif() + # For backward compatibility as `FindVulkan` in previous CMake versions allow to retrieve `glslc` # and `glslangValidator` without requesting the corresponding component. if(NOT glslc IN_LIST Vulkan_FIND_COMPONENTS) diff --git a/Modules/Platform/Linux-NVHPC.cmake b/Modules/Platform/Linux-NVHPC.cmake index aad17f1..602b417 100644 --- a/Modules/Platform/Linux-NVHPC.cmake +++ b/Modules/Platform/Linux-NVHPC.cmake @@ -3,13 +3,15 @@ # This module is shared by multiple languages; use include blocker. -if(__LINUX_COMPILER_NVIDIA) - return() -endif() -set(__LINUX_COMPILER_NVIDIA 1) - -include(Platform/Linux-PGI) +include_guard() macro(__linux_compiler_nvhpc lang) - __linux_compiler_pgi(${lang}) + set(CMAKE_${lang}_COMPILE_OPTIONS_PIC "-fPIC") + set(CMAKE_${lang}_COMPILE_OPTIONS_PIE "-fPIE") + set(_CMAKE_${lang}_PIE_MAY_BE_SUPPORTED_BY_LINKER YES) + set(CMAKE_${lang}_LINK_OPTIONS_PIE "-fPIE") + set(CMAKE_${lang}_LINK_OPTIONS_NO_PIE "") + set(CMAKE_SHARED_LIBRARY_${lang}_FLAGS "-fPIC") + set(CMAKE_SHARED_LIBRARY_CREATE_${lang}_FLAGS "-shared") + set(CMAKE_SHARED_LIBRARY_LINK_${lang}_FLAGS "") endmacro() diff --git a/Modules/Platform/Windows-GNU.cmake b/Modules/Platform/Windows-GNU.cmake index b464169..bf96e63 100644 --- a/Modules/Platform/Windows-GNU.cmake +++ b/Modules/Platform/Windows-GNU.cmake @@ -157,7 +157,7 @@ macro(__windows_compiler_gnu lang) endif() if(NOT CMAKE_RC_COMPILER_INIT AND NOT CMAKE_GENERATOR_RC) - set(CMAKE_RC_COMPILER_INIT ${_CMAKE_TOOLCHAIN_PREFIX}windres) + set(CMAKE_RC_COMPILER_INIT ${_CMAKE_TOOLCHAIN_PREFIX}windres windres) endif() enable_language(RC) diff --git a/Source/CMakeVersion.cmake b/Source/CMakeVersion.cmake index 260e61b..6ba211e 100644 --- a/Source/CMakeVersion.cmake +++ b/Source/CMakeVersion.cmake @@ -1,7 +1,7 @@ # CMake version number components. set(CMake_VERSION_MAJOR 3) set(CMake_VERSION_MINOR 24) -set(CMake_VERSION_PATCH 20220816) +set(CMake_VERSION_PATCH 20220819) #set(CMake_VERSION_RC 0) set(CMake_VERSION_IS_DIRTY 0) diff --git a/Source/CPack/cpack.cxx b/Source/CPack/cpack.cxx index 221f7dd..4d9a42a 100644 --- a/Source/CPack/cpack.cxx +++ b/Source/CPack/cpack.cxx @@ -50,7 +50,7 @@ const char* cmDocumentationOptions[][2] = { { "-C <Configuration>", "Specify the project configuration" }, { "-D <var>=<value>", "Set a CPack variable." }, { "--config <configFile>", "Specify the config file." }, - { "--verbose,-V", "Enable verbose output" }, + { "-V,--verbose", "Enable verbose output" }, { "--trace", "Put underlying cmake scripts in trace mode." }, { "--trace-expand", "Put underlying cmake scripts in expanded trace mode." }, { "--debug", "Enable debug output (for CPack developers)" }, diff --git a/Source/CTest/cmCTestRunTest.cxx b/Source/CTest/cmCTestRunTest.cxx index 2a2cb1c..5efe69f 100644 --- a/Source/CTest/cmCTestRunTest.cxx +++ b/Source/CTest/cmCTestRunTest.cxx @@ -8,16 +8,12 @@ #include <cstdint> #include <cstdio> #include <cstring> -#include <functional> #include <iomanip> #include <ratio> #include <sstream> #include <utility> #include <cm/memory> -#include <cm/optional> -#include <cm/string_view> -#include <cmext/string_view> #include "cmsys/RegularExpression.hxx" @@ -787,149 +783,31 @@ bool cmCTestRunTest::ForkProcess( this->TestProcess->SetTimeout(timeout); -#ifndef CMAKE_BOOTSTRAP cmSystemTools::SaveRestoreEnvironment sre; -#endif - std::ostringstream envMeasurement; + + // We split processing ENVIRONMENT and ENVIRONMENT_MODIFICATION into two + // phases to ensure that MYVAR=reset: in the latter phase resets to the + // former phase's settings, rather than to the original environment. if (environment && !environment->empty()) { - // Environment modification works on the assumption that the environment is - // actually modified here. If another strategy is used, there will need to - // be updates below in `apply_diff`. - cmSystemTools::AppendEnv(*environment); - for (auto const& var : *environment) { - envMeasurement << var << std::endl; - } + cmSystemTools::EnvDiff diff; + diff.AppendEnv(*environment); + diff.ApplyToCurrentEnv(&envMeasurement); } if (environment_modification && !environment_modification->empty()) { - std::map<std::string, cm::optional<std::string>> env_application; - -#ifdef _WIN32 - char path_sep = ';'; -#else - char path_sep = ':'; -#endif - - auto apply_diff = - [&env_application](const std::string& name, - std::function<void(std::string&)> const& apply) { - cm::optional<std::string> old_value = env_application[name]; - std::string output; - if (old_value) { - output = *old_value; - } else { - // This only works because the environment is actually modified above - // (`AppendEnv`). If CTest ever just creates an environment block - // directly, that block will need to be queried for the subprocess' - // value instead. - const char* curval = cmSystemTools::GetEnv(name); - if (curval) { - output = curval; - } - } - apply(output); - env_application[name] = output; - }; - - bool err_occurred = false; + cmSystemTools::EnvDiff diff; + bool env_ok = true; for (auto const& envmod : *environment_modification) { - // Split on `=` - auto const eq_loc = envmod.find_first_of('='); - if (eq_loc == std::string::npos) { - cmCTestLog(this->CTest, ERROR_MESSAGE, - "Error: Missing `=` after the variable name in: " - << envmod << std::endl); - err_occurred = true; - continue; - } - auto const name = envmod.substr(0, eq_loc); - - // Split value on `:` - auto const op_value_start = eq_loc + 1; - auto const colon_loc = envmod.find_first_of(':', op_value_start); - if (colon_loc == std::string::npos) { - cmCTestLog(this->CTest, ERROR_MESSAGE, - "Error: Missing `:` after the operation in: " << envmod - << std::endl); - err_occurred = true; - continue; - } - auto const op = - envmod.substr(op_value_start, colon_loc - op_value_start); - - auto const value_start = colon_loc + 1; - auto const value = envmod.substr(value_start); - - // Determine what to do with the operation. - if (op == "reset"_s) { - auto entry = env_application.find(name); - if (entry != env_application.end()) { - env_application.erase(entry); - } - } else if (op == "set"_s) { - env_application[name] = value; - } else if (op == "unset"_s) { - env_application[name] = {}; - } else if (op == "string_append"_s) { - apply_diff(name, [&value](std::string& output) { output += value; }); - } else if (op == "string_prepend"_s) { - apply_diff(name, - [&value](std::string& output) { output.insert(0, value); }); - } else if (op == "path_list_append"_s) { - apply_diff(name, [&value, path_sep](std::string& output) { - if (!output.empty()) { - output += path_sep; - } - output += value; - }); - } else if (op == "path_list_prepend"_s) { - apply_diff(name, [&value, path_sep](std::string& output) { - if (!output.empty()) { - output.insert(output.begin(), path_sep); - } - output.insert(0, value); - }); - } else if (op == "cmake_list_append"_s) { - apply_diff(name, [&value](std::string& output) { - if (!output.empty()) { - output += ';'; - } - output += value; - }); - } else if (op == "cmake_list_prepend"_s) { - apply_diff(name, [&value](std::string& output) { - if (!output.empty()) { - output.insert(output.begin(), ';'); - } - output.insert(0, value); - }); - } else { - cmCTestLog(this->CTest, ERROR_MESSAGE, - "Error: Unrecognized environment manipulation argument: " - << op << std::endl); - err_occurred = true; - continue; - } + env_ok &= diff.ParseOperation(envmod); } - if (err_occurred) { + if (!env_ok) { return false; } - for (auto const& env_apply : env_application) { - if (env_apply.second) { - auto const env_update = - cmStrCat(env_apply.first, '=', *env_apply.second); - cmSystemTools::PutEnv(env_update); - envMeasurement << env_update << std::endl; - } else { - cmSystemTools::UnsetEnv(env_apply.first.c_str()); - // Signify that this variable is being actively unset - envMeasurement << "#" << env_apply.first << "=" << std::endl; - } - } + diff.ApplyToCurrentEnv(&envMeasurement); } if (this->UseAllocatedResources) { diff --git a/Source/cmArgumentParser.cxx b/Source/cmArgumentParser.cxx index 614d00d..ad57a88 100644 --- a/Source/cmArgumentParser.cxx +++ b/Source/cmArgumentParser.cxx @@ -139,6 +139,7 @@ void Instance::Consume(std::size_t pos, cm::string_view arg) this->FinishKeyword(); this->Keyword = it->first; this->KeywordValuesSeen = 0; + this->DoneWithPositional = true; if (this->Bindings.ParsedKeyword) { this->Bindings.ParsedKeyword(*this, it->first); } @@ -158,10 +159,12 @@ void Instance::Consume(std::size_t pos, cm::string_view arg) return; } - auto const pit = this->Bindings.Positions.Find(pos); - if (pit != this->Bindings.Positions.end()) { - pit->second(*this, pos, arg); - return; + if (!this->DoneWithPositional) { + auto const pit = this->Bindings.Positions.Find(pos); + if (pit != this->Bindings.Positions.end()) { + pit->second(*this, pos, arg); + return; + } } if (this->UnparsedArguments != nullptr) { diff --git a/Source/cmArgumentParser.h b/Source/cmArgumentParser.h index ac78872..fdf54fb 100644 --- a/Source/cmArgumentParser.h +++ b/Source/cmArgumentParser.h @@ -206,6 +206,7 @@ private: std::size_t KeywordValuesSeen = 0; std::size_t KeywordValuesExpected = 0; std::function<Continue(cm::string_view)> KeywordValueFunc; + bool DoneWithPositional = false; void Consume(std::size_t pos, cm::string_view arg); void FinishKeyword(); diff --git a/Source/cmCoreTryCompile.cxx b/Source/cmCoreTryCompile.cxx index c2c3118..7b9dc2e 100644 --- a/Source/cmCoreTryCompile.cxx +++ b/Source/cmCoreTryCompile.cxx @@ -145,6 +145,10 @@ auto const TryCompileArgParser = .BIND_LANG_PROPS(HIP) .BIND_LANG_PROPS(OBJC) .BIND_LANG_PROPS(OBJCXX) + /* keep semicolon on own line */; + +auto const TryRunArgParser = + cmArgumentParser<Arguments>{ TryCompileArgParser } .Bind("COMPILE_OUTPUT_VARIABLE"_s, &Arguments::CompileOutputVariable) .Bind("RUN_OUTPUT_VARIABLE"_s, &Arguments::RunOutputVariable) .Bind("RUN_OUTPUT_STDOUT_VARIABLE"_s, &Arguments::RunOutputStdOutVariable) @@ -160,12 +164,13 @@ Arguments cmCoreTryCompile::ParseArgs( cmRange<std::vector<std::string>::const_iterator> args, bool isTryRun) { std::vector<std::string> unparsedArguments; - auto arguments = TryCompileArgParser.Parse(args, &unparsedArguments, 0); + const auto& parser = (isTryRun ? TryRunArgParser : TryCompileArgParser); + auto arguments = parser.Parse(args, &unparsedArguments, 0); if (!arguments.MaybeReportError(*(this->Makefile)) && !unparsedArguments.empty()) { std::string m = "Unknown arguments:"; for (const auto& i : unparsedArguments) { - m = cmStrCat(m, "\n ", i, "\""); + m = cmStrCat(m, "\n \"", i, "\""); } this->Makefile->IssueMessage(MessageType::AUTHOR_WARNING, m); } @@ -194,31 +199,6 @@ Arguments cmCoreTryCompile::ParseArgs( arguments.RunWorkingDirectory->empty()) { arguments.RunWorkingDirectory = cm::nullopt; } - } else { - std::string tryRunArgs; - if (arguments.CompileOutputVariable) { - tryRunArgs = cmStrCat(tryRunArgs, " COMPILE_OUTPUT_VARIABLE\n"); - } - if (arguments.RunOutputVariable) { - tryRunArgs = cmStrCat(tryRunArgs, " RUN_OUTPUT_VARIABLE\n"); - } - if (arguments.RunOutputStdOutVariable) { - tryRunArgs = cmStrCat(tryRunArgs, " RUN_OUTPUT_STDOUT_VARIABLE\n"); - } - if (arguments.RunOutputStdErrVariable) { - tryRunArgs = cmStrCat(tryRunArgs, " RUN_OUTPUT_STDERR_VARIABLE\n"); - } - if (arguments.RunWorkingDirectory) { - tryRunArgs = cmStrCat(tryRunArgs, " WORKING_DIRECTORY\n"); - } - if (arguments.RunArgs) { - tryRunArgs = cmStrCat(tryRunArgs, " ARGS\n"); - } - if (!tryRunArgs.empty()) { - this->Makefile->IssueMessage( - MessageType::AUTHOR_WARNING, - cmStrCat("Ignoring try_run arguments for try_compile:\n", tryRunArgs)); - } } return arguments; } diff --git a/Source/cmCreateTestSourceList.cxx b/Source/cmCreateTestSourceList.cxx index 2a52d1a..75c25e3 100644 --- a/Source/cmCreateTestSourceList.cxx +++ b/Source/cmCreateTestSourceList.cxx @@ -87,9 +87,7 @@ bool cmCreateTestSourceList(std::vector<std::string> const& args, func_name = cmSystemTools::GetFilenameWithoutLastExtension(*i); } cmSystemTools::ConvertToUnixSlashes(func_name); - std::replace(func_name.begin(), func_name.end(), ' ', '_'); - std::replace(func_name.begin(), func_name.end(), '/', '_'); - std::replace(func_name.begin(), func_name.end(), ':', '_'); + func_name = cmSystemTools::MakeCidentifier(func_name); bool already_declared = std::find(tests_func_name.begin(), tests_func_name.end(), func_name) != tests_func_name.end(); diff --git a/Source/cmDocumentation.cxx b/Source/cmDocumentation.cxx index 3619ade..d466a12 100644 --- a/Source/cmDocumentation.cxx +++ b/Source/cmDocumentation.cxx @@ -17,30 +17,32 @@ #include "cmVersion.h" static const char* cmDocumentationStandardOptions[][2] = { - { "--help,-help,-usage,-h,-H,/?", "Print usage information and exit." }, - { "--version,-version,/V [<f>]", "Print version number and exit." }, - { "--help-full [<f>]", "Print all help manuals and exit." }, - { "--help-manual <man> [<f>]", "Print one help manual and exit." }, - { "--help-manual-list [<f>]", "List help manuals available and exit." }, - { "--help-command <cmd> [<f>]", "Print help for one command and exit." }, - { "--help-command-list [<f>]", + { "-h,-H,--help,-help,-usage,/?", "Print usage information and exit." }, + { "--version,-version,/V [<file>]", "Print version number and exit." }, + { "--help-full [<file>]", "Print all help manuals and exit." }, + { "--help-manual <man> [<file>]", "Print one help manual and exit." }, + { "--help-manual-list [<file>]", "List help manuals available and exit." }, + { "--help-command <cmd> [<file>]", "Print help for one command and exit." }, + { "--help-command-list [<file>]", "List commands with help available and exit." }, - { "--help-commands [<f>]", "Print cmake-commands manual and exit." }, - { "--help-module <mod> [<f>]", "Print help for one module and exit." }, - { "--help-module-list [<f>]", "List modules with help available and exit." }, - { "--help-modules [<f>]", "Print cmake-modules manual and exit." }, - { "--help-policy <cmp> [<f>]", "Print help for one policy and exit." }, - { "--help-policy-list [<f>]", + { "--help-commands [<file>]", "Print cmake-commands manual and exit." }, + { "--help-module <mod> [<file>]", "Print help for one module and exit." }, + { "--help-module-list [<file>]", + "List modules with help available and exit." }, + { "--help-modules [<file>]", "Print cmake-modules manual and exit." }, + { "--help-policy <cmp> [<file>]", "Print help for one policy and exit." }, + { "--help-policy-list [<file>]", "List policies with help available and exit." }, - { "--help-policies [<f>]", "Print cmake-policies manual and exit." }, - { "--help-property <prop> [<f>]", "Print help for one property and exit." }, - { "--help-property-list [<f>]", + { "--help-policies [<file>]", "Print cmake-policies manual and exit." }, + { "--help-property <prop> [<file>]", + "Print help for one property and exit." }, + { "--help-property-list [<file>]", "List properties with help available and exit." }, - { "--help-properties [<f>]", "Print cmake-properties manual and exit." }, - { "--help-variable var [<f>]", "Print help for one variable and exit." }, - { "--help-variable-list [<f>]", + { "--help-properties [<file>]", "Print cmake-properties manual and exit." }, + { "--help-variable var [<file>]", "Print help for one variable and exit." }, + { "--help-variable-list [<file>]", "List variables with help available and exit." }, - { "--help-variables [<f>]", "Print cmake-variables manual and exit." }, + { "--help-variables [<file>]", "Print cmake-variables manual and exit." }, { nullptr, nullptr } }; diff --git a/Source/cmExportFileGenerator.cxx b/Source/cmExportFileGenerator.cxx index 23b5690..50bc78c 100644 --- a/Source/cmExportFileGenerator.cxx +++ b/Source/cmExportFileGenerator.cxx @@ -843,9 +843,16 @@ void cmExportFileGenerator::SetImportDetailProperties( suffix, target, "IMPORTED_LINK_INTERFACE_LANGUAGES", iface->Languages, properties, ImportLinkPropertyTargetNames::No); + // Export IMPORTED_LINK_DEPENDENT_LIBRARIES to help consuming linkers + // find private dependencies of shared libraries. + std::size_t oldMissingTargetsSize = this->MissingTargets.size(); this->SetImportLinkProperty( suffix, target, "IMPORTED_LINK_DEPENDENT_LIBRARIES", iface->SharedDeps, properties, ImportLinkPropertyTargetNames::Yes); + // Avoid enforcing shared library private dependencies as public package + // dependencies by ignoring missing targets added for them. + this->MissingTargets.resize(oldMissingTargetsSize); + if (iface->Multiplicity > 0) { std::string prop = cmStrCat("IMPORTED_LINK_INTERFACE_MULTIPLICITY", suffix); diff --git a/Source/cmGlobalXCodeGenerator.cxx b/Source/cmGlobalXCodeGenerator.cxx index 70a379e..7523662 100644 --- a/Source/cmGlobalXCodeGenerator.cxx +++ b/Source/cmGlobalXCodeGenerator.cxx @@ -2894,8 +2894,8 @@ void cmGlobalXCodeGenerator::CreateBuildSettings(cmGeneratorTarget* gtgt, } // Create the INSTALL_PATH attribute. - std::string install_name_dir; if (gtgt->GetType() == cmStateEnums::SHARED_LIBRARY) { + std::string install_name_dir; // Get the install_name directory for the build tree. install_name_dir = gtgt->GetInstallNameDirForBuildTree(configName); // Xcode doesn't create the correct install_name in some cases. @@ -2917,9 +2917,9 @@ void cmGlobalXCodeGenerator::CreateBuildSettings(cmGeneratorTarget* gtgt, extraLinkOptions += " -install_name "; extraLinkOptions += XCodeEscapePath(install_name); } + buildSettings->AddAttribute("INSTALL_PATH", + this->CreateString(install_name_dir)); } - buildSettings->AddAttribute("INSTALL_PATH", - this->CreateString(install_name_dir)); // Create the LD_RUNPATH_SEARCH_PATHS cmComputeLinkInformation* pcli = gtgt->GetLinkInformation(configName); diff --git a/Source/cmLocalGenerator.cxx b/Source/cmLocalGenerator.cxx index 7b823da..64f8996 100644 --- a/Source/cmLocalGenerator.cxx +++ b/Source/cmLocalGenerator.cxx @@ -2591,7 +2591,9 @@ void cmLocalGenerator::AddPchDependencies(cmGeneratorTarget* target) if (pchSource.empty() || pchHeader.empty()) { if (this->GetGlobalGenerator()->IsXcode() && !pchLangSet.empty()) { for (auto* sf : sources) { - if (pchLangSet.find(sf->GetLanguage()) == pchLangSet.end()) { + const auto sourceLanguage = sf->GetLanguage(); + if (!sourceLanguage.empty() && + pchLangSet.find(sourceLanguage) == pchLangSet.end()) { sf->SetProperty("SKIP_PRECOMPILE_HEADERS", "ON"); } } diff --git a/Source/cmQtAutoMocUic.cxx b/Source/cmQtAutoMocUic.cxx index a7125b1..8c09b56 100644 --- a/Source/cmQtAutoMocUic.cxx +++ b/Source/cmQtAutoMocUic.cxx @@ -2167,22 +2167,23 @@ void cmQtAutoMocUicT::JobCompileUicT::Process() void cmQtAutoMocUicT::JobMocsCompilationT::Process() { + std::string const& compAbs = this->MocConst().CompFileAbs; + // Compose mocs compilation file content std::string content = "// This file is autogenerated. Changes will be overwritten.\n"; if (this->MocEval().CompFiles.empty()) { // Placeholder content + cmCryptoHash hash(cmCryptoHash::AlgoSHA256); + const std::string hashedPath = hash.HashString(compAbs); + const std::string functionName = + "cmake_automoc_silence_linker_warning" + hashedPath; + content += "// No files found that require moc or the moc files are " "included\n" - "struct cmake_automoc_silence_linker_warning{\n" - " virtual ~cmake_automoc_silence_linker_warning();\n" - "};\n" - "\n" - "inline " - "cmake_automoc_silence_linker_warning::" - "~cmake_automoc_silence_linker_warning()\n" - "{}\n"; + "void " + + functionName + "() {}\n"; } else { // Valid content const bool mc = this->BaseConst().MultiConfig; @@ -2191,7 +2192,6 @@ void cmQtAutoMocUicT::JobMocsCompilationT::Process() content += cmWrap(wrapFront, this->MocEval().CompFiles, wrapBack, ""); } - std::string const& compAbs = this->MocConst().CompFileAbs; if (cmQtAutoGenerator::FileDiffers(compAbs, content)) { // Actually write mocs compilation file if (this->Log().Verbose()) { diff --git a/Source/cmSystemTools.cxx b/Source/cmSystemTools.cxx index 672cdc7..3c4e709 100644 --- a/Source/cmSystemTools.cxx +++ b/Source/cmSystemTools.cxx @@ -16,6 +16,7 @@ #include <cm/optional> #include <cmext/algorithm> +#include <cmext/string_view> #include <cm3p/uv.h> @@ -1563,6 +1564,144 @@ void cmSystemTools::AppendEnv(std::vector<std::string> const& env) } } +void cmSystemTools::EnvDiff::AppendEnv(std::vector<std::string> const& env) +{ + for (std::string const& eit : env) { + this->PutEnv(eit); + } +} + +void cmSystemTools::EnvDiff::PutEnv(const std::string& env) +{ + auto const eq_loc = env.find('='); + if (eq_loc != std::string::npos) { + std::string name = env.substr(0, eq_loc); + diff[name] = env.substr(eq_loc + 1); + } else { + this->UnPutEnv(env); + } +} + +void cmSystemTools::EnvDiff::UnPutEnv(const std::string& env) +{ + diff[env] = {}; +} + +bool cmSystemTools::EnvDiff::ParseOperation(const std::string& envmod) +{ + char path_sep = GetSystemPathlistSeparator(); + + auto apply_diff = [this](const std::string& name, + std::function<void(std::string&)> const& apply) { + cm::optional<std::string> old_value = diff[name]; + std::string output; + if (old_value) { + output = *old_value; + } else { + const char* curval = cmSystemTools::GetEnv(name); + if (curval) { + output = curval; + } + } + apply(output); + diff[name] = output; + }; + + // Split on `=` + auto const eq_loc = envmod.find_first_of('='); + if (eq_loc == std::string::npos) { + cmSystemTools::Error(cmStrCat( + "Error: Missing `=` after the variable name in: ", envmod, '\n')); + return false; + } + + auto const name = envmod.substr(0, eq_loc); + + // Split value on `:` + auto const op_value_start = eq_loc + 1; + auto const colon_loc = envmod.find_first_of(':', op_value_start); + if (colon_loc == std::string::npos) { + cmSystemTools::Error( + cmStrCat("Error: Missing `:` after the operation in: ", envmod, '\n')); + return false; + } + auto const op = envmod.substr(op_value_start, colon_loc - op_value_start); + + auto const value_start = colon_loc + 1; + auto const value = envmod.substr(value_start); + + // Determine what to do with the operation. + if (op == "reset"_s) { + auto entry = diff.find(name); + if (entry != diff.end()) { + diff.erase(entry); + } + } else if (op == "set"_s) { + diff[name] = value; + } else if (op == "unset"_s) { + diff[name] = {}; + } else if (op == "string_append"_s) { + apply_diff(name, [&value](std::string& output) { output += value; }); + } else if (op == "string_prepend"_s) { + apply_diff(name, + [&value](std::string& output) { output.insert(0, value); }); + } else if (op == "path_list_append"_s) { + apply_diff(name, [&value, path_sep](std::string& output) { + if (!output.empty()) { + output += path_sep; + } + output += value; + }); + } else if (op == "path_list_prepend"_s) { + apply_diff(name, [&value, path_sep](std::string& output) { + if (!output.empty()) { + output.insert(output.begin(), path_sep); + } + output.insert(0, value); + }); + } else if (op == "cmake_list_append"_s) { + apply_diff(name, [&value](std::string& output) { + if (!output.empty()) { + output += ';'; + } + output += value; + }); + } else if (op == "cmake_list_prepend"_s) { + apply_diff(name, [&value](std::string& output) { + if (!output.empty()) { + output.insert(output.begin(), ';'); + } + output.insert(0, value); + }); + } else { + cmSystemTools::Error(cmStrCat( + "Error: Unrecognized environment manipulation argument: ", op, '\n')); + return false; + } + + return true; +} + +void cmSystemTools::EnvDiff::ApplyToCurrentEnv(std::ostringstream* measurement) +{ + for (auto const& env_apply : diff) { + if (env_apply.second) { + auto const env_update = + cmStrCat(env_apply.first, '=', *env_apply.second); + cmSystemTools::PutEnv(env_update); + if (measurement) { + *measurement << env_update << std::endl; + } + } else { + cmSystemTools::UnsetEnv(env_apply.first.c_str()); + if (measurement) { + // Signify that this variable is being actively unset + *measurement << '#' << env_apply.first << "=\n"; + } + } + } +} + cmSystemTools::SaveRestoreEnvironment::SaveRestoreEnvironment() { this->Env = cmSystemTools::GetEnvironmentVariables(); diff --git a/Source/cmSystemTools.h b/Source/cmSystemTools.h index ec650f7..48bbe23 100644 --- a/Source/cmSystemTools.h +++ b/Source/cmSystemTools.h @@ -6,9 +6,12 @@ #include <cstddef> #include <functional> +#include <map> +#include <sstream> #include <string> #include <vector> +#include <cm/optional> #include <cm/string_view> #include "cmsys/Process.h" @@ -377,6 +380,42 @@ public: /** Append multiple variables to the current environment. */ static void AppendEnv(std::vector<std::string> const& env); + /** + * Helper class to represent an environment diff directly. This is to avoid + * repeated in-place environment modification (i.e. via setenv/putenv), which + * could be slow. + */ + class EnvDiff + { + public: + /** Append multiple variables to the current environment diff */ + void AppendEnv(std::vector<std::string> const& env); + + /** + * Add a single variable (or remove if no = sign) to the current + * environment diff. + */ + void PutEnv(const std::string& env); + + /** Remove a single variable from the current environment diff. */ + void UnPutEnv(const std::string& env); + + /** + * Apply an ENVIRONMENT_MODIFICATION operation to this diff. Returns + * false and issues an error on parse failure. + */ + bool ParseOperation(const std::string& envmod); + + /** + * Apply this diff to the actual environment, optionally writing out the + * modifications to a CTest-compatible measurement stream. + */ + void ApplyToCurrentEnv(std::ostringstream* measurement = nullptr); + + private: + std::map<std::string, cm::optional<std::string>> diff; + }; + /** Helper class to save and restore the environment. Instantiate this class as an automatic variable on the stack. Its constructor saves a copy of the current diff --git a/Source/cmakemain.cxx b/Source/cmakemain.cxx index c83508b..6f3d0eb 100644 --- a/Source/cmakemain.cxx +++ b/Source/cmakemain.cxx @@ -71,7 +71,7 @@ const char* cmDocumentationUsageNote[][2] = { const char* cmDocumentationOptions[][2] = { CMAKE_STANDARD_OPTIONS_TABLE, { "--preset <preset>,--preset=<preset>", "Specify a configure preset." }, - { "--list-presets", "List available presets." }, + { "--list-presets[=<type>]", "List available presets." }, { "-E", "CMake command mode." }, { "-L[A][H]", "List non-advanced cached variables." }, { "--fresh", @@ -83,8 +83,8 @@ const char* cmDocumentationOptions[][2] = { { "-P <file>", "Process script mode." }, { "--find-package", "Legacy pkg-config like mode. Do not use." }, { "--graphviz=<file>", - "Generate graphviz of dependencies, see " - "CMakeGraphVizOptions.cmake for more." }, + "Generate graphviz of dependencies, see CMakeGraphVizOptions.cmake for " + "more." }, { "--system-information [file]", "Dump information about this system." }, { "--log-level=<ERROR|WARNING|NOTICE|STATUS|VERBOSE|DEBUG|TRACE>", "Set the verbosity of messages from CMake files. " @@ -109,8 +109,7 @@ const char* cmDocumentationOptions[][2] = { { "--warn-uninitialized", "Warn about uninitialized values." }, { "--no-warn-unused-cli", "Don't warn about command line options." }, { "--check-system-vars", - "Find problems with variable usage in system " - "files." }, + "Find problems with variable usage in system files." }, { "--compile-no-warning-as-error", "Ignore COMPILE_WARNING_AS_ERROR property and " "CMAKE_COMPILE_WARNING_AS_ERROR variable." }, @@ -616,7 +615,7 @@ int do_build(int ac, char const* const* av) " <dir> = Project binary directory to be built.\n" " --preset <preset>, --preset=<preset>\n" " = Specify a build preset.\n" - " --list-presets\n" + " --list-presets[=<type>]\n" " = List available build presets.\n" " --parallel [<jobs>], -j [<jobs>]\n" " = Build in parallel using the given number of jobs. \n" @@ -627,14 +626,14 @@ int do_build(int ac, char const* const* av) " specifies a default parallel level when this " "option\n" " is not given.\n" - " --target <tgt>..., -t <tgt>... \n" + " -t <tgt>..., --target <tgt>...\n" " = Build <tgt> instead of default targets.\n" " --config <cfg> = For multi-configuration tools, choose <cfg>.\n" " --clean-first = Build target 'clean' first, then build.\n" " (To clean only, use --target 'clean'.)\n" " --resolve-package-references={on|only|off}\n" " = Restore/resolve package references during build.\n" - " --verbose, -v = Enable verbose output - if supported - including\n" + " -v, --verbose = Enable verbose output - if supported - including\n" " the build commands to be executed. \n" " -- = Pass remaining options to the native tool.\n" ; diff --git a/Source/cmcmd.cxx b/Source/cmcmd.cxx index b1f1bcf..00c9bda 100644 --- a/Source/cmcmd.cxx +++ b/Source/cmcmd.cxx @@ -791,6 +791,10 @@ int cmcmd::ExecuteCMakeCommand(std::vector<std::string> const& args, } if (args[1] == "env") { +#ifndef CMAKE_BOOTSTRAP + cmSystemTools::EnvDiff env; +#endif + auto ai = args.cbegin() + 2; auto ae = args.cend(); for (; ai != ae; ++ai) { @@ -803,16 +807,40 @@ int cmcmd::ExecuteCMakeCommand(std::vector<std::string> const& args, } if (cmHasLiteralPrefix(a, "--unset=")) { // Unset environment variable. +#ifdef CMAKE_BOOTSTRAP cmSystemTools::UnPutEnv(a.substr(8)); +#else + env.UnPutEnv(a.substr(8)); +#endif + } else if (a == "--modify") { +#ifdef CMAKE_BOOTSTRAP + std::cerr + << "cmake -E env: --modify not available during bootstrapping\n"; + return 1; +#else + if (++ai == ae) { + std::cerr << "cmake -E env: --modify missing a parameter\n"; + return 1; + } + std::string const& op = *ai; + if (!env.ParseOperation(op)) { + std::cerr << "cmake -E env: invalid parameter to --modify: " << op + << '\n'; + return 1; + } +#endif } else if (!a.empty() && a[0] == '-') { // Environment variable and command names cannot start in '-', // so this must be an unknown option. - std::cerr << "cmake -E env: unknown option '" << a << '\'' - << std::endl; + std::cerr << "cmake -E env: unknown option '" << a << "'\n"; return 1; } else if (a.find('=') != std::string::npos) { // Set environment variable. +#ifdef CMAKE_BOOTSTRAP cmSystemTools::PutEnv(a); +#else + env.PutEnv(a); +#endif } else { // This is the beginning of the command. break; @@ -820,10 +848,14 @@ int cmcmd::ExecuteCMakeCommand(std::vector<std::string> const& args, } if (ai == ae) { - std::cerr << "cmake -E env: no command given" << std::endl; + std::cerr << "cmake -E env: no command given\n"; return 1; } +#ifndef CMAKE_BOOTSTRAP + env.ApplyToCurrentEnv(); +#endif + // Execute command from remaining arguments. std::vector<std::string> cmd(ai, ae); int retval; diff --git a/Tests/CMakeLib/testArgumentParser.cxx b/Tests/CMakeLib/testArgumentParser.cxx index 58c0418..e044794 100644 --- a/Tests/CMakeLib/testArgumentParser.cxx +++ b/Tests/CMakeLib/testArgumentParser.cxx @@ -42,7 +42,9 @@ struct Result : public ArgumentParser::ParseResult cm::optional<std::vector<std::vector<std::string>>> Multi3; cm::optional<std::vector<std::vector<std::string>>> Multi4; + cm::optional<std::string> Pos0; cm::optional<std::string> Pos1; + cm::optional<std::string> Pos2; bool Func0_ = false; ArgumentParser::Continue Func0(cm::string_view) @@ -97,9 +99,10 @@ struct Result : public ArgumentParser::ParseResult std::initializer_list<cm::string_view> const args = { /* clang-format off */ + "pos0", // position index 0 "OPTION_1", // option + "pos2", // position index 2, ignored because after keyword // "OPTION_2", // option that is not present - "pos1", // position index 1 "STRING_1", // string arg missing value "STRING_2", "foo", "bar", // string arg + unparsed value, presence captured // "STRING_3", // string arg that is not present @@ -172,8 +175,8 @@ bool verifyResult(Result const& result, { "LIST_4"_s, " missing required value\n" }, { "FUNC_0"_s, " missing required value\n" } }; - static std::vector<std::string> const unparsed = { "bar", "ign1", "ign2", - "ign4" }; + static std::vector<std::string> const unparsed = { "pos2", "bar", "ign1", + "ign2", "ign4" }; #define ASSERT_TRUE(x) \ do { \ @@ -215,7 +218,9 @@ bool verifyResult(Result const& result, ASSERT_TRUE((*result.Multi3)[1] == barfoo); ASSERT_TRUE(!result.Multi4); - ASSERT_TRUE(result.Pos1 == "pos1"); + ASSERT_TRUE(result.Pos0 == "pos0"); + ASSERT_TRUE(!result.Pos1); + ASSERT_TRUE(!result.Pos2); ASSERT_TRUE(result.Func0_ == false); ASSERT_TRUE(result.Func1_ == "foo"); @@ -255,6 +260,9 @@ bool testArgumentParserDynamic() static_cast<ArgumentParser::ParseResult&>(result) = cmArgumentParser<void>{} + .Bind(0, result.Pos0) + .Bind(1, result.Pos1) + .Bind(2, result.Pos2) .Bind("OPTION_1"_s, result.Option1) .Bind("OPTION_2"_s, result.Option2) .Bind("STRING_1"_s, result.String1) @@ -273,7 +281,6 @@ bool testArgumentParserDynamic() .Bind("MULTI_2"_s, result.Multi2) .Bind("MULTI_3"_s, result.Multi3) .Bind("MULTI_4"_s, result.Multi4) - .Bind(1, result.Pos1) .Bind("FUNC_0"_s, [&result](cm::string_view arg) -> ArgumentParser::Continue { return result.Func0(arg); @@ -307,6 +314,9 @@ static auto const parserStaticFunc4 = }; static auto const parserStatic = // cmArgumentParser<Result>{} + .Bind(0, &Result::Pos0) + .Bind(1, &Result::Pos1) + .Bind(2, &Result::Pos2) .Bind("OPTION_1"_s, &Result::Option1) .Bind("OPTION_2"_s, &Result::Option2) .Bind("STRING_1"_s, &Result::String1) @@ -325,7 +335,6 @@ static auto const parserStatic = // .Bind("MULTI_2"_s, &Result::Multi2) .Bind("MULTI_3"_s, &Result::Multi3) .Bind("MULTI_4"_s, &Result::Multi4) - .Bind(1, &Result::Pos1) .Bind("FUNC_0"_s, &Result::Func0) .Bind("FUNC_1"_s, &Result::Func1) .Bind("FUNC_2a"_s, &Result::Func2) diff --git a/Tests/CTestCoverageCollectGCOV/test.cmake.in b/Tests/CTestCoverageCollectGCOV/test.cmake.in index a36f374..7c7a3e5 100644 --- a/Tests/CTestCoverageCollectGCOV/test.cmake.in +++ b/Tests/CTestCoverageCollectGCOV/test.cmake.in @@ -34,9 +34,10 @@ set(expected_out # then back to relative to get them in canonical form (or maybe this is a bug # in how the tarball is generated?) function(to_relative_paths real_paths paths) + file(REAL_PATH "${CTEST_BINARY_DIRECTORY}" base) foreach(file ${paths}) - file(REAL_PATH "${file}" real_path BASE_DIRECTORY "${CTEST_BINARY_DIRECTORY}") - file(RELATIVE_PATH relative_path "${CTEST_BINARY_DIRECTORY}" "${real_path}") + file(REAL_PATH "${file}" real_path BASE_DIRECTORY "${base}") + file(RELATIVE_PATH relative_path "${base}" "${real_path}") list(APPEND local_real_paths "${relative_path}") message(DEBUG "${file} -> ${real_path} -> ${relative_path}") endforeach() diff --git a/Tests/RunCMake/CMakeLists.txt b/Tests/RunCMake/CMakeLists.txt index 9549af9..2485a7e 100644 --- a/Tests/RunCMake/CMakeLists.txt +++ b/Tests/RunCMake/CMakeLists.txt @@ -301,9 +301,13 @@ if("${CMAKE_GENERATOR}" MATCHES "Unix Makefiles|Ninja") add_RunCMake_test(ExportCompileCommands) endif() add_RunCMake_test(ExcludeFromAll) +add_RunCMake_test(ExportImport) add_RunCMake_test(ExternalData) add_RunCMake_test(FeatureSummary) add_RunCMake_test(FPHSA) +if(CMAKE_USE_SYSTEM_JSONCPP) + list(APPEND FileAPI_ARGS -DJsonCpp_VERSION_STRING=${JsonCpp_VERSION_STRING}) +endif() add_RunCMake_test(FileAPI -DPython_EXECUTABLE=${Python_EXECUTABLE} -DCMAKE_CXX_COMPILER_ID=${CMAKE_CXX_COMPILER_ID}) add_RunCMake_test(FindBoost) diff --git a/Tests/RunCMake/CommandLine/E_env-equal.cmake b/Tests/RunCMake/CommandLine/E_env-equal.cmake new file mode 100644 index 0000000..3f18bb6 --- /dev/null +++ b/Tests/RunCMake/CommandLine/E_env-equal.cmake @@ -0,0 +1,15 @@ +if (NOT DEFINED ENV{TEST_ENV_EXPECTED}) + if (NOT DEFINED ENV{TEST_ENV}) + message(STATUS "TEST_ENV is correctly not set in environment") + else () + message(FATAL_ERROR "TEST_ENV is incorrectly set in environment") + endif () +else () + if (NOT DEFINED ENV{TEST_ENV}) + message(FATAL_ERROR "TEST_ENV is incorrectly not set in environment") + elseif ("$ENV{TEST_ENV}" STREQUAL "$ENV{TEST_ENV_EXPECTED}") + message(STATUS "TEST_ENV is correctly set in environment: $ENV{TEST_ENV}") + else () + message(FATAL_ERROR "TEST_ENV is incorrectly set in environment!\n\tactual: $ENV{TEST_ENV}\n\texpected: $ENV{TEST_ENV_EXPECTED}") + endif () +endif () diff --git a/Tests/RunCMake/CommandLine/E_env_modify-bad-operation-result.txt b/Tests/RunCMake/CommandLine/E_env_modify-bad-operation-result.txt new file mode 100644 index 0000000..d00491f --- /dev/null +++ b/Tests/RunCMake/CommandLine/E_env_modify-bad-operation-result.txt @@ -0,0 +1 @@ +1 diff --git a/Tests/RunCMake/CommandLine/E_env_modify-bad-operation-stderr.txt b/Tests/RunCMake/CommandLine/E_env_modify-bad-operation-stderr.txt new file mode 100644 index 0000000..ccfdeab --- /dev/null +++ b/Tests/RunCMake/CommandLine/E_env_modify-bad-operation-stderr.txt @@ -0,0 +1,3 @@ +^CMake Error: Error: Unrecognized environment manipulation argument: unknown + +cmake -E env: invalid parameter to --modify: TEST_ENV=unknown:$ diff --git a/Tests/RunCMake/CommandLine/E_env_modify-cmake_list-stdout.txt b/Tests/RunCMake/CommandLine/E_env_modify-cmake_list-stdout.txt new file mode 100644 index 0000000..ad42f56 --- /dev/null +++ b/Tests/RunCMake/CommandLine/E_env_modify-cmake_list-stdout.txt @@ -0,0 +1 @@ +^-- TEST_ENV is correctly set in environment: exp;ect;ed$ diff --git a/Tests/RunCMake/CommandLine/E_env_modify-path_list-stdout.txt b/Tests/RunCMake/CommandLine/E_env_modify-path_list-stdout.txt new file mode 100644 index 0000000..49572a3 --- /dev/null +++ b/Tests/RunCMake/CommandLine/E_env_modify-path_list-stdout.txt @@ -0,0 +1 @@ +^-- TEST_ENV is correctly set in environment: exp[;:]ect[;:]ed$ diff --git a/Tests/RunCMake/CommandLine/E_env_modify-reset-stdout.txt b/Tests/RunCMake/CommandLine/E_env_modify-reset-stdout.txt new file mode 100644 index 0000000..a60f1bf --- /dev/null +++ b/Tests/RunCMake/CommandLine/E_env_modify-reset-stdout.txt @@ -0,0 +1 @@ +^-- TEST_ENV is correctly set in environment: expected$ diff --git a/Tests/RunCMake/CommandLine/E_env_modify-reset-to-unset-stdout.txt b/Tests/RunCMake/CommandLine/E_env_modify-reset-to-unset-stdout.txt new file mode 100644 index 0000000..a1d5c01 --- /dev/null +++ b/Tests/RunCMake/CommandLine/E_env_modify-reset-to-unset-stdout.txt @@ -0,0 +1 @@ +^-- TEST_ENV is correctly not set in environment$ diff --git a/Tests/RunCMake/CommandLine/E_env_modify-set-stdout.txt b/Tests/RunCMake/CommandLine/E_env_modify-set-stdout.txt new file mode 100644 index 0000000..feff117 --- /dev/null +++ b/Tests/RunCMake/CommandLine/E_env_modify-set-stdout.txt @@ -0,0 +1 @@ +^-- TEST_ENV is correctly set in environment: 1$ diff --git a/Tests/RunCMake/CommandLine/E_env_modify-string-stdout.txt b/Tests/RunCMake/CommandLine/E_env_modify-string-stdout.txt new file mode 100644 index 0000000..a60f1bf --- /dev/null +++ b/Tests/RunCMake/CommandLine/E_env_modify-string-stdout.txt @@ -0,0 +1 @@ +^-- TEST_ENV is correctly set in environment: expected$ diff --git a/Tests/RunCMake/CommandLine/E_env_modify-unset-stdout.txt b/Tests/RunCMake/CommandLine/E_env_modify-unset-stdout.txt new file mode 100644 index 0000000..a1d5c01 --- /dev/null +++ b/Tests/RunCMake/CommandLine/E_env_modify-unset-stdout.txt @@ -0,0 +1 @@ +^-- TEST_ENV is correctly not set in environment$ diff --git a/Tests/RunCMake/CommandLine/E_env_modify-with-double-dash-result.txt b/Tests/RunCMake/CommandLine/E_env_modify-with-double-dash-result.txt new file mode 100644 index 0000000..573541a --- /dev/null +++ b/Tests/RunCMake/CommandLine/E_env_modify-with-double-dash-result.txt @@ -0,0 +1 @@ +0 diff --git a/Tests/RunCMake/CommandLine/E_env_modify-without-double-dash-result.txt b/Tests/RunCMake/CommandLine/E_env_modify-without-double-dash-result.txt new file mode 100644 index 0000000..d00491f --- /dev/null +++ b/Tests/RunCMake/CommandLine/E_env_modify-without-double-dash-result.txt @@ -0,0 +1 @@ +1 diff --git a/Tests/RunCMake/CommandLine/E_env_modify-without-double-dash-stderr.txt b/Tests/RunCMake/CommandLine/E_env_modify-without-double-dash-stderr.txt new file mode 100644 index 0000000..8d98f9d --- /dev/null +++ b/Tests/RunCMake/CommandLine/E_env_modify-without-double-dash-stderr.txt @@ -0,0 +1 @@ +.* diff --git a/Tests/RunCMake/CommandLine/RunCMakeTest.cmake b/Tests/RunCMake/CommandLine/RunCMakeTest.cmake index 39d7858..7da0f8d 100644 --- a/Tests/RunCMake/CommandLine/RunCMakeTest.cmake +++ b/Tests/RunCMake/CommandLine/RunCMakeTest.cmake @@ -744,6 +744,10 @@ run_cmake_command(E_cat-without-double-dash ${CMAKE_COMMAND} -E cat "-file-start unset(RunCMake_TEST_COMMAND_WORKING_DIRECTORY) unset(out) +# Unset environment variables that are used for testing cmake -E +unset(ENV{TEST_ENV}) +unset(ENV{TEST_ENV_EXPECTED}) + run_cmake_command(E_env-no-command0 ${CMAKE_COMMAND} -E env) run_cmake_command(E_env-no-command1 ${CMAKE_COMMAND} -E env TEST_ENV=1) run_cmake_command(E_env-bad-arg1 ${CMAKE_COMMAND} -E env -bad-arg1) @@ -758,6 +762,56 @@ file(COPY_FILE "${EXIT_CODE_EXE}" "${RunCMake_BINARY_DIR}/env=${exit_code}") run_cmake_command(E_env-with-double-dash ${CMAKE_COMMAND} -E env TEST_ENV=1 -- "${RunCMake_BINARY_DIR}/env=${exit_code}" zero_exit) run_cmake_command(E_env-without-double-dash ${CMAKE_COMMAND} -E env TEST_ENV=1 "${RunCMake_BINARY_DIR}/env=${exit_code}" zero_exit) +## Tests of env --modify +# Repeat the same tests as above +run_cmake_command(E_env_modify-set ${CMAKE_COMMAND} -E env --modify TEST_ENV=set:1 ${CMAKE_COMMAND} -P ${RunCMake_SOURCE_DIR}/E_env-set.cmake) +run_cmake_command(E_env_modify-unset ${CMAKE_COMMAND} -E env --modify TEST_ENV=set:1 ${CMAKE_COMMAND} -E env --modify TEST_ENV=unset: ${CMAKE_COMMAND} -P ${RunCMake_SOURCE_DIR}/E_env-unset.cmake) +run_cmake_command(E_env_modify-with-double-dash ${CMAKE_COMMAND} -E env --modify TEST_ENV=set:1 -- "${RunCMake_BINARY_DIR}/env=${exit_code}" zero_exit) +run_cmake_command(E_env_modify-without-double-dash ${CMAKE_COMMAND} -E env --modify TEST_ENV=set:1 "${RunCMake_BINARY_DIR}/env=${exit_code}" zero_exit) + +# Test environment modification commands +run_cmake_command(E_env_modify-reset + ${CMAKE_COMMAND} -E env TEST_ENV=expected + ${CMAKE_COMMAND} -E env TEST_ENV_EXPECTED=expected TEST_ENV=bad_value --modify TEST_ENV=reset: + ${CMAKE_COMMAND} -P ${RunCMake_SOURCE_DIR}/E_env-equal.cmake) + +run_cmake_command(E_env_modify-reset-to-unset + ${CMAKE_COMMAND} -E env --unset=TEST_ENV --unset=TEST_ENV_EXPECTED + ${CMAKE_COMMAND} -E env TEST_ENV=bad_value --modify TEST_ENV=reset: + ${CMAKE_COMMAND} -P ${RunCMake_SOURCE_DIR}/E_env-equal.cmake) + +run_cmake_command(E_env_modify-string + ${CMAKE_COMMAND} -E env TEST_ENV_EXPECTED=expected + --modify TEST_ENV=unset: + --modify TEST_ENV=string_append:ect + --modify TEST_ENV=string_prepend:exp + --modify TEST_ENV=string_append:ed + ${CMAKE_COMMAND} -P ${RunCMake_SOURCE_DIR}/E_env-equal.cmake) + +if (WIN32) + set(SEP "\\;") +else () + set(SEP ":") +endif () + +run_cmake_command(E_env_modify-path_list + ${CMAKE_COMMAND} -E env "TEST_ENV_EXPECTED=exp${SEP}ect${SEP}ed" + --modify TEST_ENV=unset: + --modify TEST_ENV=path_list_append:ect + --modify TEST_ENV=path_list_prepend:exp + --modify TEST_ENV=path_list_append:ed + ${CMAKE_COMMAND} -P ${RunCMake_SOURCE_DIR}/E_env-equal.cmake) + +run_cmake_command(E_env_modify-cmake_list + ${CMAKE_COMMAND} -E env "TEST_ENV_EXPECTED=exp\\;ect\\;ed" + --modify TEST_ENV=unset: + --modify TEST_ENV=cmake_list_append:ect + --modify TEST_ENV=cmake_list_prepend:exp + --modify TEST_ENV=cmake_list_append:ed + ${CMAKE_COMMAND} -P ${RunCMake_SOURCE_DIR}/E_env-equal.cmake) + +run_cmake_command(E_env_modify-bad-operation ${CMAKE_COMMAND} -E env --modify TEST_ENV=unknown:) + run_cmake_command(E_md5sum-dir ${CMAKE_COMMAND} -E md5sum .) run_cmake_command(E_sha1sum-dir ${CMAKE_COMMAND} -E sha1sum .) run_cmake_command(E_sha224sum-dir ${CMAKE_COMMAND} -E sha224sum .) diff --git a/Tests/RunCMake/ExportImport/CMakeLists.txt b/Tests/RunCMake/ExportImport/CMakeLists.txt new file mode 100644 index 0000000..5ff8d3e --- /dev/null +++ b/Tests/RunCMake/ExportImport/CMakeLists.txt @@ -0,0 +1,3 @@ +cmake_minimum_required(VERSION 3.23) +project(${RunCMake_TEST} NONE) +include(${RunCMake_TEST}.cmake) diff --git a/Tests/RunCMake/ExportImport/RunCMakeTest.cmake b/Tests/RunCMake/ExportImport/RunCMakeTest.cmake new file mode 100644 index 0000000..d07fca2 --- /dev/null +++ b/Tests/RunCMake/ExportImport/RunCMakeTest.cmake @@ -0,0 +1,24 @@ +cmake_minimum_required(VERSION 3.23) +include(RunCMake) + +function(run_ExportImport_test case) + set(RunCMake_TEST_BINARY_DIR ${RunCMake_BINARY_DIR}/${case}-export-build) + set(CMAKE_INSTALL_PREFIX ${RunCMake_TEST_BINARY_DIR}/root) + if (NOT RunCMake_GENERATOR_IS_MULTI_CONFIG) + set(RunCMake_TEST_OPTIONS -DCMAKE_BUILD_TYPE=Debug) + endif() + run_cmake(${case}-export) + unset(RunCMake_TEST_OPTIONS) + set(RunCMake_TEST_NO_CLEAN 1) + run_cmake_command(${case}-export-build ${CMAKE_COMMAND} --build . --config Debug) + run_cmake_command(${case}-export-install ${CMAKE_COMMAND} -DCMAKE_INSTALL_PREFIX=${CMAKE_INSTALL_PREFIX} -DBUILD_TYPE=Debug -P cmake_install.cmake) + unset(RunCMake_TEST_NO_CLEAN) + + set(RunCMake_TEST_BINARY_DIR ${RunCMake_BINARY_DIR}/${case}-import-build) + run_cmake_with_options(${case}-import + -Dfoo_DIR=${CMAKE_INSTALL_PREFIX}/lib/cmake/foo + -Dbar_DIR=${CMAKE_INSTALL_PREFIX}/lib/cmake/bar + ) +endfunction() + +run_ExportImport_test(SharedDep) diff --git a/Tests/RunCMake/ExportImport/SharedDep-export.cmake b/Tests/RunCMake/ExportImport/SharedDep-export.cmake new file mode 100644 index 0000000..2da3e47 --- /dev/null +++ b/Tests/RunCMake/ExportImport/SharedDep-export.cmake @@ -0,0 +1,13 @@ +enable_language(C) + +add_library(foo SHARED foo.c) +install(TARGETS foo EXPORT foo) +install(EXPORT foo DESTINATION lib/cmake/foo) +install(FILES foo-config.cmake.in RENAME foo-config.cmake DESTINATION lib/cmake/foo) + +add_library(bar SHARED bar.c) +target_link_libraries(bar PRIVATE foo) +# 'foo' only appears in IMPORTED_LINK_DEPENDENT_LIBRARIES, and so is not enforced on import. +install(TARGETS bar EXPORT bar) +install(EXPORT bar DESTINATION lib/cmake/bar) +install(FILES bar-config.cmake.in RENAME bar-config.cmake DESTINATION lib/cmake/bar) diff --git a/Tests/RunCMake/ExportImport/SharedDep-import.cmake b/Tests/RunCMake/ExportImport/SharedDep-import.cmake new file mode 100644 index 0000000..2e2c2f6 --- /dev/null +++ b/Tests/RunCMake/ExportImport/SharedDep-import.cmake @@ -0,0 +1 @@ +find_package(bar REQUIRED CONFIG NO_DEFAULT_PATH) diff --git a/Tests/RunCMake/ExportImport/bar-config.cmake.in b/Tests/RunCMake/ExportImport/bar-config.cmake.in new file mode 100644 index 0000000..9148046 --- /dev/null +++ b/Tests/RunCMake/ExportImport/bar-config.cmake.in @@ -0,0 +1,2 @@ +# find_dependency(foo) intentionally left out for this test case +include(${CMAKE_CURRENT_LIST_DIR}/bar.cmake) diff --git a/Tests/RunCMake/ExportImport/bar.c b/Tests/RunCMake/ExportImport/bar.c new file mode 100644 index 0000000..19adca9 --- /dev/null +++ b/Tests/RunCMake/ExportImport/bar.c @@ -0,0 +1,12 @@ +#if defined(_WIN32) +__declspec(dllimport) +#endif + int foo(void); + +#ifdef _WIN32 +__declspec(dllexport) +#endif + int bar(void) +{ + return foo(); +} diff --git a/Tests/RunCMake/ExportImport/foo-config.cmake.in b/Tests/RunCMake/ExportImport/foo-config.cmake.in new file mode 100644 index 0000000..b038138 --- /dev/null +++ b/Tests/RunCMake/ExportImport/foo-config.cmake.in @@ -0,0 +1 @@ +include(${CMAKE_CURRENT_LIST_DIR}/foo.cmake) diff --git a/Tests/RunCMake/ExportImport/foo.c b/Tests/RunCMake/ExportImport/foo.c new file mode 100644 index 0000000..8794965 --- /dev/null +++ b/Tests/RunCMake/ExportImport/foo.c @@ -0,0 +1,7 @@ +#ifdef _WIN32 +__declspec(dllexport) +#endif + int foo(void) +{ + return 0; +} diff --git a/Tests/RunCMake/FileAPI/ClientStateful-check.py b/Tests/RunCMake/FileAPI/ClientStateful-check.py index f3d20d1..28679bb 100644 --- a/Tests/RunCMake/FileAPI/ClientStateful-check.py +++ b/Tests/RunCMake/FileAPI/ClientStateful-check.py @@ -108,7 +108,11 @@ def check_query_json_empty(q): check_error_re(q, "value, object or array expected") def check_query_json_extra(q): - check_error_re(q, "Extra non-whitespace after JSON value") + if bool(os.environ.get("CMake_JSONCPP_PRE_1_7_5", "")) and is_dict(q) and sorted(q.keys()) == ["responses"]: + # jsoncpp < 1.7.5 did not diagnose extra non-whitespace characters + check_error(q["responses"], "'requests' member missing") + else: + check_error_re(q, "Extra non-whitespace after JSON value") def check_query_not_file(q): check_error_re(q, "failed to read from file") diff --git a/Tests/RunCMake/FileAPI/RunCMakeTest.cmake b/Tests/RunCMake/FileAPI/RunCMakeTest.cmake index 61dce17..961b73a 100644 --- a/Tests/RunCMake/FileAPI/RunCMakeTest.cmake +++ b/Tests/RunCMake/FileAPI/RunCMakeTest.cmake @@ -39,6 +39,10 @@ if(RunCMake_GENERATOR_IS_MULTI_CONFIG) set(RunCMake_TEST_OPTIONS "-DCMAKE_CONFIGURATION_TYPES=Debug\\;Release\\;MinSizeRel\\;RelWithDebInfo") endif() +if(JsonCpp_VERSION_STRING AND JsonCpp_VERSION_STRING VERSION_LESS 1.7.5) + set(ENV{CMake_JSONCPP_PRE_1_7_5} 1) +endif() + run_cmake(Nothing) run_cmake(Empty) run_cmake(EmptyClient) diff --git a/Tests/RunCMake/ctest_environment/ENVIRONMENT_MODIFICATION-reset-to-prop-result.txt b/Tests/RunCMake/ctest_environment/ENVIRONMENT_MODIFICATION-reset-to-prop-result.txt new file mode 100644 index 0000000..573541a --- /dev/null +++ b/Tests/RunCMake/ctest_environment/ENVIRONMENT_MODIFICATION-reset-to-prop-result.txt @@ -0,0 +1 @@ +0 diff --git a/Tests/RunCMake/ctest_environment/ENVIRONMENT_MODIFICATION-reset-to-prop-stdout.txt b/Tests/RunCMake/ctest_environment/ENVIRONMENT_MODIFICATION-reset-to-prop-stdout.txt new file mode 100644 index 0000000..a7eae05 --- /dev/null +++ b/Tests/RunCMake/ctest_environment/ENVIRONMENT_MODIFICATION-reset-to-prop-stdout.txt @@ -0,0 +1 @@ +CTEST_TEST_VAR=set-via-ENVIRONMENT-property diff --git a/Tests/RunCMake/ctest_environment/ENVIRONMENT_MODIFICATION-reset-to-prop.cmake b/Tests/RunCMake/ctest_environment/ENVIRONMENT_MODIFICATION-reset-to-prop.cmake new file mode 100644 index 0000000..51e7f2a --- /dev/null +++ b/Tests/RunCMake/ctest_environment/ENVIRONMENT_MODIFICATION-reset-to-prop.cmake @@ -0,0 +1,9 @@ +include(CTest) + +add_test(NAME cmake_environment COMMAND "${CMAKE_COMMAND}" -E environment) +set_tests_properties( + cmake_environment + PROPERTIES + ENVIRONMENT "CTEST_TEST_VAR=set-via-ENVIRONMENT-property" + ENVIRONMENT_MODIFICATION "CTEST_TEST_VAR=set:set-via-ENVIRONMENT_MODIFICATION;CTEST_TEST_VAR=reset:" +) diff --git a/Tests/RunCMake/ctest_environment/ENVIRONMENT_MODIFICATION-reset-to-system-result.txt b/Tests/RunCMake/ctest_environment/ENVIRONMENT_MODIFICATION-reset-to-system-result.txt new file mode 100644 index 0000000..573541a --- /dev/null +++ b/Tests/RunCMake/ctest_environment/ENVIRONMENT_MODIFICATION-reset-to-system-result.txt @@ -0,0 +1 @@ +0 diff --git a/Tests/RunCMake/ctest_environment/ENVIRONMENT_MODIFICATION-reset-to-system-stdout.txt b/Tests/RunCMake/ctest_environment/ENVIRONMENT_MODIFICATION-reset-to-system-stdout.txt new file mode 100644 index 0000000..beaf133 --- /dev/null +++ b/Tests/RunCMake/ctest_environment/ENVIRONMENT_MODIFICATION-reset-to-system-stdout.txt @@ -0,0 +1 @@ +CTEST_TEST_VAR=set-via-system-environment diff --git a/Tests/RunCMake/ctest_environment/ENVIRONMENT_MODIFICATION-reset-to-system.cmake b/Tests/RunCMake/ctest_environment/ENVIRONMENT_MODIFICATION-reset-to-system.cmake new file mode 100644 index 0000000..23268aa --- /dev/null +++ b/Tests/RunCMake/ctest_environment/ENVIRONMENT_MODIFICATION-reset-to-system.cmake @@ -0,0 +1,9 @@ +include(CTest) + +add_test(NAME cmake_environment COMMAND "${CMAKE_COMMAND}" -E environment) +set_tests_properties( + cmake_environment + PROPERTIES + # ENVIRONMENT "CTEST_TEST_VAR=set-via-ENVIRONMENT-property" + ENVIRONMENT_MODIFICATION "CTEST_TEST_VAR=set:set-via-ENVIRONMENT_MODIFICATION;CTEST_TEST_VAR=reset:" +) diff --git a/Tests/RunCMake/ctest_environment/RunCMakeTest.cmake b/Tests/RunCMake/ctest_environment/RunCMakeTest.cmake index 3447779..365c9e8 100644 --- a/Tests/RunCMake/ctest_environment/RunCMakeTest.cmake +++ b/Tests/RunCMake/ctest_environment/RunCMakeTest.cmake @@ -10,3 +10,7 @@ set(RunCTest_VERBOSE_FLAG "-VV") run_ctest(ENVIRONMENT_MODIFICATION-invalid-op) run_ctest(ENVIRONMENT_MODIFICATION-no-colon) run_ctest(ENVIRONMENT_MODIFICATION-no-equals) + +set(ENV{CTEST_TEST_VAR} set-via-system-environment) +run_ctest(ENVIRONMENT_MODIFICATION-reset-to-prop) +run_ctest(ENVIRONMENT_MODIFICATION-reset-to-system) diff --git a/Tests/RunCMake/try_compile/TryRunArgs-stderr.txt b/Tests/RunCMake/try_compile/TryRunArgs-stderr.txt index 717c208..2a58e71 100644 --- a/Tests/RunCMake/try_compile/TryRunArgs-stderr.txt +++ b/Tests/RunCMake/try_compile/TryRunArgs-stderr.txt @@ -1,13 +1,18 @@ ^CMake Warning \(dev\) at TryRunArgs.cmake:[0-9]+ \(try_compile\): - Ignoring try_run arguments for try_compile: - - COMPILE_OUTPUT_VARIABLE - RUN_OUTPUT_VARIABLE - RUN_OUTPUT_STDOUT_VARIABLE - RUN_OUTPUT_STDERR_VARIABLE - WORKING_DIRECTORY - ARGS + Unknown arguments: + "COMPILE_OUTPUT_VARIABLE" + "compOutputVar" + "RUN_OUTPUT_VARIABLE" + "runOutputVar" + "RUN_OUTPUT_STDOUT_VARIABLE" + "runOutputStdOutVar" + "RUN_OUTPUT_STDERR_VARIABLE" + "runOutputStdErrVar" + "WORKING_DIRECTORY" + "runWorkDir" + "ARGS" + "runArgs" Call Stack \(most recent call first\): CMakeLists.txt:[0-9]+ \(include\) This warning is for project developers. Use -Wno-dev to suppress it.$ diff --git a/Tests/TryCompile/CMakeLists.txt b/Tests/TryCompile/CMakeLists.txt index 7c6f970..dccc227 100644 --- a/Tests/TryCompile/CMakeLists.txt +++ b/Tests/TryCompile/CMakeLists.txt @@ -30,6 +30,15 @@ endmacro() # try to compile a file that should compile +try_compile(SHOULD_PASS + ${TryCompile_BINARY_DIR} + ${TryCompile_SOURCE_DIR}/pass.c + OUTPUT_VARIABLE TRY_OUT) +if(NOT SHOULD_PASS) + message(SEND_ERROR "should pass failed ${TRY_OUT}") +endif() + +# try to compile a file that should compile # also check that COPY_FILE works try_compile(SHOULD_PASS ${TryCompile_BINARY_DIR} @@ -73,24 +82,6 @@ if(SHOULD_FAIL) message(SEND_ERROR "Should fail passed ${TRY_OUT}") endif() -# try to compile a file that should compile -try_compile(SHOULD_PASS - ${TryCompile_BINARY_DIR} - ${TryCompile_SOURCE_DIR}/pass.c - OUTPUT_VARIABLE TRY_OUT) -if(NOT SHOULD_PASS) - message(SEND_ERROR "should pass failed ${TRY_OUT}") -endif() - -# try to compile a file that should not compile -try_compile(SHOULD_FAIL - ${TryCompile_BINARY_DIR} - ${TryCompile_SOURCE_DIR}/fail.c - OUTPUT_VARIABLE TRY_OUT) -if(SHOULD_FAIL) - message(SEND_ERROR "Should fail passed ${TRY_OUT}") -endif() - # try to compile two files that should compile try_compile(SHOULD_PASS ${TryCompile_BINARY_DIR} @@ -125,24 +116,6 @@ if(NOT SHOULD_PASS) endif() set(CMAKE_C_FLAGS "${_c_flags}") -if(NOT SHOULD_FAIL) - if(SHOULD_PASS) - message("All Tests passed, ignore all previous output.") - else() - message("Test failed") - endif() -else() - message("Test failed") -endif() -try_compile(CMAKE_ANSI_FOR_SCOPE - ${TryCompile_BINARY_DIR} - ${CMAKE_ROOT}/Modules/TestForAnsiForScope.cxx OUTPUT_VARIABLE OUT) -if (CMAKE_ANSI_FOR_SCOPE) - message("Compiler supports ansi for") -else() - message("Compiler does not support ansi for scope") -endif() - try_compile(CMAKE_ANSI_FOR_SCOPE ${TryCompile_BINARY_DIR} ${CMAKE_ROOT}/Modules/TestForAnsiForScope.cxx OUTPUT_VARIABLE OUT) @@ -160,6 +133,7 @@ else() message("Compiler does not support ansi for scope") endif() +# try to compile a project message("Testing try_compile project mode") try_compile(TEST_INNER ${TryCompile_BINARY_DIR}/CMakeFiles/Inner |