docs: create dedicated documentation page for the download cache

devops/devops.rst

@@ -17,6 +17,7 @@ If you plan to use Conan in production in your project, team, or organization, t
    using_conancenter
    devops_local_recipes_index
    backup_sources/sources_backup
+   download_cache
    metadata
    versioning/versioning
    save_restore

devops/download_cache.rst

@@ -0,0 +1,40 @@
+.. _devops_download_cache:
+
+Download Cache
+==============
+
+The Conan download cache is a feature intended to cache downloaded artifacts and recipe files, avoiding recurrent downloads of the same files. This is especially useful in Continuous Integration (CI) environments where multiple jobs might require downloading the same packages, or for developers that switch environments frequently.
+
+Configuration
+-------------
+
+The download cache is enabled by setting the ``core.download:download_cache`` configuration in the :ref:`global.conf<reference_config_files_global_conf>` file. 
+
+.. code-block:: text
+   :caption: global.conf
+
+   core.download:download_cache = /path/to/download_cache
+
+This configuration points to an absolute path to a folder where the Conan packages and downloaded files will be stored *compressed* as they come from the remote server.
+
+Conan has two configuration variables related to the download cache:
+
+- ``core.download:download_cache``: To cache Conan artifacts (like ``conan_package.tgz`` and ``conan_export.tgz``) downloads.
+- ``tools.files.download:download_cache``: To cache user downloads performed via the :ref:`download()<conan_tools_files_download>` or :ref:`get()<conan_tools_files_get>` tools in recipes.
+
+By default, ``tools.files.download:download_cache`` defaults to the value of ``core.download:download_cache``. Thus, it is only necessary to define ``core.download:download_cache`` to enable caching for both Conan packages and user recipe downloads. If a different location is desired for user downloads, ``tools.files.download:download_cache`` can be explicitly set.
+
+Usage
+-----
+
+Once enabled, every time Conan needs to download a package artifact or a user file, it will first check if the file is present in the cache folder. If it is, it will be copied from the cache to the Conan cache or recipe folder, avoiding the network request. If it is not, it will be downloaded from the remote server and a copy will be stored in the download cache folder.
+
+The download cache is concurrency safe. Multiple concurrent Conan processes can share the same download cache folder simultaneously.
+
+Download cache vs Backup sources
+--------------------------------
+
+While both the download cache and the :ref:`backup sources<conan_backup_sources>` features deal with caching downloaded files, they serve different purposes:
+
+- The **download cache** is a local filesystem cache. Its main purpose is to speed up operations and save bandwidth by keeping a local compressed copy of the downloaded files. It is volatile and can be safely cleared at any time.
+- The **backup sources** feature is designed to upload third-party source files (like ``.tar.gz`` from GitHub releases) to your own infrastructure (like an Artifactory server) to ensure traceability and reproducibility in case the original URLs go down.

reference/config_files/global_conf.rst

@@ -423,6 +423,7 @@ core.download:download_cache
 
 Absolute path to a folder where the Conan packages will be stored *compressed*.
 This is useful to avoid recurrent downloads of the same packages, especially in CI.
+Please check the :ref:`download cache <devops_download_cache>` dedicated section for more information.
 
 .. code-block:: text
     :caption: *global.conf*

reference/config_files/profiles.rst

@@ -504,8 +504,8 @@ In this case, whatever version of ``cmake`` declared in recipes, will be replace
 
    * This section should be added to the profile whose context is the one that requires the tool, i.e., if the
      tool is required in the host context, then it should be added to the host profile, so that the requirement
-     itself can be replaced.
-
+     itself can be replaced. For example, if a ``zlib`` recipe in the host context has a ``tool_requires("cmake/xxx")``, a ``replace_tool_requires`` in the **host profile** will replace it.
+   * If what you want to replace are transitive dependencies of the tools that live inside ``tool_requires`` packages, those live in the **build context**. To replace them, you must add the replacements to the **build profile**. Both ``[replace_requires]`` and ``[replace_tool_requires]`` in the build profile will affect the build context in the same way, replacing ``requires`` and ``tool_requires`` of the tools themselves.
 
 .. _reference_config_files_profiles_platform_requires: