docs: create dedicated documentation page for the download cache - #4470
Open
anushkagupta200615-jpg wants to merge 2 commits into
Open
docs: create dedicated documentation page for the download cache#4470anushkagupta200615-jpg wants to merge 2 commits into
anushkagupta200615-jpg wants to merge 2 commits into
Conversation
memsharded
requested changes
Jun 22, 2026
memsharded
left a comment
memsharded
left a comment
Member
There was a problem hiding this comment.
Many thanks for your contribution @anushkagupta200615-jpg
Overall it is looking good.
Please check the tools.files.download:download_cache issue, if this was generated with AI, please double check the output, this could be an hallucination or a confusion with Conan 1.
Also, there is a failure in the build:
/home/jenkins/workspace/conan_docs_PR-4470/devops/download_cache.rst:23:undefined label: 'conan_tools_files_download'
| - ``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. |
Member
There was a problem hiding this comment.
This doesn't seem correct, this doesn't exist. The conf is core.sources:download_cache and it doesn't default to core.download:download_cache.
| 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. |
Member
There was a problem hiding this comment.
Suggested change
| 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. | |
| 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 download 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. |
|
|
||
| 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. |
Member
There was a problem hiding this comment.
Suggested change
| The download cache is concurrency safe. Multiple concurrent Conan processes can share the same download cache folder simultaneously. | |
| The download cache is concurrency safe. Multiple concurrent Conan processes can share the same download cache folder simultaneously. The synchronization uses system file locks, so distributed synchronization is not guaranteed. |
| 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. |
Member
There was a problem hiding this comment.
Suggested change
| - 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. | |
| - 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. This feature uses the download cache functionality to store the downloaded sources, defaulting to a folder inside the Conan packages cache, but it can be also explicitly defined with the ``core.sources:download_cache`` configuration. |
Member
There was a problem hiding this comment.
This seems already in develop2, please rebase from develop2 branch, this should dissapear.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This PR addresses issue #4200 by adding explicit documentation for the Conan 2 download cache feature.
Previously, information regarding the download cache was only partially covered under the "backup sources" section and briefly mentioned in
global_conf.rst. This PR introduces a dedicated page in the DevOps section (devops/download_cache.rst) to provide clear and central documentation.Changes included:
download_cache.rst: Explains the download cache feature, how it operates, and how to configure it (core.download:download_cacheandtools.files.download:download_cache).devops.rst: Registered the new documentation under the DevOps table of contents.global_conf.rst: Added a cross-reference link in thecore.download:download_cacheentry that points users directly to the new dedicated page for complete context.Resolves #4200