Merge topic 'fetchcontent-CMAKE-vars-passthrough'

1851aa49be FetchContent: Pass through networking-related CMAKE_... variables
96937438b7 Help: Clean up how TLS and NETRC variables are discussed
2a82bd85b6 Help: Add documentation for CMAKE_TLS_CAINFO

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !6589

Help/command/file.rst

@@ -1073,7 +1073,7 @@ Options to both ``DOWNLOAD`` and ``UPLOAD`` are:
   .. versionadded:: 3.11
 
   Specify whether the .netrc file is to be used for operation.  If this
-  option is not specified, the value of the ``CMAKE_NETRC`` variable
+  option is not specified, the value of the :variable:`CMAKE_NETRC` variable
   will be used instead.
   Valid levels are:
 
@@ -1092,29 +1092,28 @@ Options to both ``DOWNLOAD`` and ``UPLOAD`` are:
 
   Specify an alternative .netrc file to the one in your home directory,
   if the ``NETRC`` level is ``OPTIONAL`` or ``REQUIRED``. If this option
-  is not specified, the value of the ``CMAKE_NETRC_FILE`` variable will
+  is not specified, the value of the :variable:`CMAKE_NETRC_FILE` variable will
   be used instead.
 
-If neither ``NETRC`` option is given CMake will check variables
-``CMAKE_NETRC`` and ``CMAKE_NETRC_FILE``, respectively.
-
 ``TLS_VERIFY <ON|OFF>``
   Specify whether to verify the server certificate for ``https://`` URLs.
-  The default is to *not* verify.
+  The default is to *not* verify. If this option is not specified, the value
+  of the :variable:`CMAKE_TLS_VERIFY` variable will be used instead.
 
   .. versionadded:: 3.18
     Added support to ``file(UPLOAD)``.
 
 ``TLS_CAINFO <file>``
-  Specify a custom Certificate Authority file for ``https://`` URLs.
+  Specify a custom Certificate Authority file for ``https://`` URLs. If this
+  option is not specified, the value of the :variable:`CMAKE_TLS_CAINFO`
+  variable will be used instead.
 
   .. versionadded:: 3.18
     Added support to ``file(UPLOAD)``.
 
 For ``https://`` URLs CMake must be built with OpenSSL support.  ``TLS/SSL``
 certificates are not checked by default.  Set ``TLS_VERIFY`` to ``ON`` to
-check certificates. If neither ``TLS`` option is given CMake will check
+check certificates.
-variables :variable:`CMAKE_TLS_VERIFY` and ``CMAKE_TLS_CAINFO``, respectively.
 
 Additional options to ``DOWNLOAD`` are:
 

Help/manual/cmake-variables.7.rst

@@ -247,6 +247,7 @@ Variables that Change Behavior
    /variable/CMAKE_SYSTEM_LIBRARY_PATH
    /variable/CMAKE_SYSTEM_PREFIX_PATH
    /variable/CMAKE_SYSTEM_PROGRAM_PATH
+   /variable/CMAKE_TLS_CAINFO
    /variable/CMAKE_TLS_VERIFY
    /variable/CMAKE_USER_MAKE_RULES_OVERRIDE
    /variable/CMAKE_WARN_DEPRECATED

Help/release/dev/fetchcontent-CMAKE-vars-passthrough.rst

@@ -0,0 +1,8 @@
+fetchcontent-CMAKE-vars-passthrough.rst
+---------------------------------------
+
+* The :module:`FetchContent` module now passes through the
+  :variable:`CMAKE_TLS_VERIFY`, :variable:`CMAKE_TLS_CAINFO`,
+  :variable:`CMAKE_NETRC` and :variable:`CMAKE_NETRC_FILE` variables (when
+  defined) to the underlying :module:`ExternalProject` sub-build.
+  Previously, those variables were silently ignored by :module:`FetchContent`.

Help/variable/CMAKE_NETRC.rst

@@ -3,9 +3,11 @@ CMAKE_NETRC
 
 .. versionadded:: 3.11
 
-This variable is used to initialize the ``NETRC`` option for
+This variable is used to initialize the ``NETRC`` option for the
-:command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands and the
+:command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands.
-module :module:`ExternalProject`. See those commands for additional
+See those commands for additional information.
-information.
+
+This variable is also used by the :module:`ExternalProject` and
+:module:`FetchContent` modules for internal calls to :command:`file(DOWNLOAD)`.
 
 The local option takes precedence over this variable.

Help/variable/CMAKE_NETRC_FILE.rst

@@ -3,9 +3,11 @@ CMAKE_NETRC_FILE
 
 .. versionadded:: 3.11
 
-This variable is used to initialize the ``NETRC_FILE`` option for
+This variable is used to initialize the ``NETRC_FILE`` option for the
-:command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands and the
+:command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands.
-module :module:`ExternalProject`. See those commands for additional
+See those commands for additional information.
-information.
+
+This variable is also used by the :module:`ExternalProject` and
+:module:`FetchContent` modules for internal calls to :command:`file(DOWNLOAD)`.
 
 The local option takes precedence over this variable.

Help/variable/CMAKE_TLS_CAINFO.rst

@@ -0,0 +1,9 @@
+CMAKE_TLS_CAINFO
+----------------
+
+Specify the default value for the :command:`file(DOWNLOAD)` and
+:command:`file(UPLOAD)` commands' ``TLS_CAINFO`` options.
+It is unset by default.
+
+This variable is also used by the :module:`ExternalProject` and
+:module:`FetchContent` modules for internal calls to :command:`file(DOWNLOAD)`.

Help/variable/CMAKE_TLS_VERIFY.rst

@@ -5,8 +5,8 @@ Specify the default value for the :command:`file(DOWNLOAD)` and
 :command:`file(UPLOAD)` commands' ``TLS_VERIFY`` options.
 If not set, the default is *off*.
 
-This setting is also used by the :module:`ExternalProject` module
+This variable is also used by the :module:`ExternalProject` and
-for internal calls to :command:`file(DOWNLOAD)`.
+:module:`FetchContent` modules for internal calls to :command:`file(DOWNLOAD)`.
 
 TLS verification can help provide confidence that one is connecting
 to the desired server.  When downloading known content, one should

Modules/ExternalProject.cmake

@@ -224,14 +224,14 @@ External Project Definition
       ``TLS_CAINFO <file>``
         Specify a custom certificate authority file to use if ``TLS_VERIFY``
         is enabled. If this option is not specified, the value of the
-        ``CMAKE_TLS_CAINFO`` variable will be used instead (see
+        :variable:`CMAKE_TLS_CAINFO` variable will be used instead (see
         :command:`file(DOWNLOAD)`)
 
       ``NETRC <level>``
         .. versionadded:: 3.11
 
         Specify whether the ``.netrc`` file is to be used for operation.
-        If this option is not specified, the value of the ``CMAKE_NETRC``
+        If this option is not specified, the value of the :variable:`CMAKE_NETRC`
         variable will be used instead (see :command:`file(DOWNLOAD)`)
         Valid levels are:
 
@@ -251,8 +251,8 @@ External Project Definition
 
         Specify an alternative ``.netrc`` file to the one in your home directory
         if the ``NETRC`` level is ``OPTIONAL`` or ``REQUIRED``. If this option
-        is not specified, the value of the ``CMAKE_NETRC_FILE`` variable will
+        is not specified, the value of the :variable:`CMAKE_NETRC_FILE` variable
-        be used instead (see :command:`file(DOWNLOAD)`)
+        will be used instead (see :command:`file(DOWNLOAD)`)
 
       .. versionadded:: 3.1
         Added support for `tbz2`, `.tar.xz`, `.txz`, and `.7z` extensions.

Modules/FetchContent.cmake

@@ -162,6 +162,13 @@ Commands
     This may be needed for things like password prompts or real-time display
     of command progress.
 
+  .. versionadded:: 3.22
+    The :variable:`CMAKE_TLS_VERIFY`, :variable:`CMAKE_TLS_CAINFO`,
+    :variable:`CMAKE_NETRC` and :variable:`CMAKE_NETRC_FILE` variables now
+    provide the defaults for their corresponding content options, just like
+    they do for :command:`ExternalProject_Add`. Previously, these variables
+    were ignored by the ``FetchContent`` module.
+
 .. command:: FetchContent_MakeAvailable
 
   .. versionadded:: 3.14
@@ -1016,18 +1023,29 @@ ExternalProject_Add_Step(${contentName}-populate copyfile
     unset(subCMakeOpts)
   endif()
 
-  if(DEFINED CMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY)
+  set(__FETCHCONTENT_CACHED_INFO "")
-    list(APPEND subCMakeOpts
+  set(__passthrough_vars
-      "-DCMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY=${CMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY}")
+    CMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY
-  endif()
+    CMAKE_TLS_VERIFY
+    CMAKE_TLS_CAINFO
+    CMAKE_NETRC
+    CMAKE_NETRC_FILE
+  )
+  foreach(var IN LISTS __passthrough_vars)
+    if(DEFINED ${var})
+      # Embed directly in the generated CMakeLists.txt file to avoid making
+      # the cmake command line excessively long. It also makes debugging and
+      # testing easier.
+      string(APPEND __FETCHCONTENT_CACHED_INFO "set(${var} [==[${${var}}]==])\n")
+    endif()
+  endforeach()
 
   # Avoid using if(... IN_LIST ...) so we don't have to alter policy settings
-  set(__FETCHCONTENT_CACHED_INFO "")
   list(FIND ARG_UNPARSED_ARGUMENTS GIT_REPOSITORY indexResult)
   if(indexResult GREATER_EQUAL 0)
     find_package(Git QUIET)
-    set(__FETCHCONTENT_CACHED_INFO
+    string(APPEND __FETCHCONTENT_CACHED_INFO "
-"# Pass through things we've already detected in the main project to avoid
+# Pass through things we've already detected in the main project to avoid
 # paying the cost of redetecting them again in ExternalProject_Add()
 set(GIT_EXECUTABLE [==[${GIT_EXECUTABLE}]==])
 set(GIT_VERSION_STRING [==[${GIT_VERSION_STRING}]==])

Tests/RunCMake/FetchContent/RunCMakeTest.cmake

@@ -9,6 +9,7 @@ run_cmake(DownloadTwice)
 run_cmake(DownloadFile)
 run_cmake(SameGenerator)
 run_cmake(VarDefinitions)
+run_cmake(VarPassthroughs)
 run_cmake(GetProperties)
 run_cmake(UsesTerminalOverride)
 run_cmake(MakeAvailable)

Tests/RunCMake/FetchContent/VarPassthroughs.cmake

@@ -0,0 +1,38 @@
+include(FetchContent)
+
+set(CMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY AAAA)
+set(CMAKE_TLS_VERIFY BBBB)
+set(CMAKE_TLS_CAINFO CCCC)
+set(CMAKE_NETRC DDDD)
+set(CMAKE_NETRC_FILE EEEE)
+
+FetchContent_Declare(PassThrough
+  DOWNLOAD_COMMAND ${CMAKE_COMMAND} -E echo "Download command executed"
+)
+FetchContent_Populate(PassThrough)
+
+set(gen_file ${FETCHCONTENT_BASE_DIR}/passthrough-subbuild/CMakeLists.txt)
+if(NOT EXISTS ${gen_file})
+  message(FATAL_ERROR "File does not exist: ${gen_file}")
+endif()
+file(READ ${gen_file} contents)
+
+if(NOT contents MATCHES "CMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY \\[==\\[AAAA\\]==\\]")
+  message(FATAL_ERROR "Missing CMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY")
+endif()
+
+if(NOT contents MATCHES "CMAKE_TLS_VERIFY \\[==\\[BBBB\\]==\\]")
+  message(FATAL_ERROR "Missing CMAKE_TLS_VERIFY")
+endif()
+
+if(NOT contents MATCHES "CMAKE_TLS_CAINFO \\[==\\[CCCC\\]==\\]")
+  message(FATAL_ERROR "Missing CMAKE_TLS_CAINFO")
+endif()
+
+if(NOT contents MATCHES "CMAKE_NETRC \\[==\\[DDDD\\]==\\]")
+  message(FATAL_ERROR "Missing CMAKE_NETRC")
+endif()
+
+if(NOT contents MATCHES "CMAKE_NETRC_FILE \\[==\\[EEEE\\]==\\]")
+  message(FATAL_ERROR "Missing CMAKE_NETRC_FILE")
+endif()