| CMP0168 |
| ------- |
| |
| .. versionadded:: 3.30 |
| |
| The :module:`FetchContent` module implements steps directly instead of through |
| a sub-build. |
| |
| CMake 3.29 and below implement FetchContent as a separate sub-build. |
| This required configuring that separate project and using a build tool. |
| This approach can be very slow with some generators and operating systems. |
| CMake 3.30 and above prefer to implement the download, update, and patch |
| steps directly as part of the main project. |
| |
| The ``NEW`` behavior has the following characteristics: |
| |
| * No sub-build is used. All operations are implemented directly from the |
| main project's CMake configure step. When running in CMake script mode, |
| no build tool needs to be available. |
| * Generator expressions and GNU Make variables of the form ``$(SOMEVAR)`` are |
| not supported. They should not be used in any argument to |
| :command:`FetchContent_Declare` or :command:`FetchContent_Populate`. |
| * All ``LOG_...`` and ``USES_TERMINAL_...`` options, the ``QUIET`` option, and |
| the :variable:`FETCHCONTENT_QUIET` variable are ignored. |
| :module:`FetchContent` output is always part of the main project's configure |
| output. This also means it now respects the message logging level (see |
| :variable:`CMAKE_MESSAGE_LOG_LEVEL` and |
| :option:`--log-level <cmake --log-level>`). The default message log level |
| should be comparable to using ``QUIET`` with the ``OLD`` policy setting, |
| except that warnings will now be shown. |
| * The ``PREFIX``, ``TMP_DIR``, ``STAMP_DIR``, ``LOG_DIR``, and ``DOWNLOAD_DIR`` |
| options and their associated directory properties are ignored. The |
| :module:`FetchContent` module controls those locations internally. |
| |
| The ``OLD`` behavior has the following characteristics: |
| |
| * A sub-build is always used to implement the download, update, and patch |
| steps. A build tool must be available, even when using |
| :command:`FetchContent_Populate` in CMake script mode. |
| * Generator expressions and GNU Make variables of the form ``$(SOMEVAR)`` can |
| be used, although such use is almost always inappropriate. They are evaluated |
| in the sub-build, so they do not see any information from the main build. |
| * All logging, terminal control, and directory options related to the download, |
| update, or patch steps are supported. |
| * If the ``QUIET`` option is used, or the :variable:`FETCHCONTENT_QUIET` |
| variable is set to true, warnings will not be shown in the output. |
| |
| There's a reasonably good chance that users can set the |
| :variable:`CMAKE_POLICY_DEFAULT_CMP0168 <CMAKE_POLICY_DEFAULT_CMP<NNNN>>` |
| variable to ``NEW`` to globally switch to the ``NEW`` behavior while waiting |
| for the project and its dependencies to be updated use the ``NEW`` policy |
| setting by default. Projects don't typically make use of the features that the |
| ``NEW`` behavior no longer supports, and even those projects that do will often |
| still work fine when those options are ignored. Before setting this behavior |
| globally, check whether any :command:`FetchContent_Declare` or |
| :command:`FetchContent_Populate` calls use the ignored options in a way that |
| would change observable behavior, other than putting temporary or |
| internally-generated files in different locations. |
| |
| .. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.30 |
| .. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn |
| .. include:: STANDARD_ADVICE.txt |
| |
| .. include:: DEPRECATED.txt |