diff --git a/devops/devops.rst b/devops/devops.rst index 402030ec9428..974de6c019cb 100644 --- a/devops/devops.rst +++ b/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 diff --git a/devops/download_cache.rst b/devops/download_cache.rst new file mode 100644 index 000000000000..622753a93fb6 --- /dev/null +++ b/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` 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()` or :ref:`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` 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. diff --git a/reference/config_files/global_conf.rst b/reference/config_files/global_conf.rst index 9377b959a38b..8d290ff783b3 100644 --- a/reference/config_files/global_conf.rst +++ b/reference/config_files/global_conf.rst @@ -469,6 +469,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 ` dedicated section for more information. .. code-block:: text :caption: *global.conf* diff --git a/reference/tools/apple/xcodebuild.rst b/reference/tools/apple/xcodebuild.rst index 132035571c81..ef8a64ef1b78 100644 --- a/reference/tools/apple/xcodebuild.rst +++ b/reference/tools/apple/xcodebuild.rst @@ -33,6 +33,10 @@ Reference .. automethod:: XcodeBuild.build +.. automethod:: XcodeBuild.build_workspace + +.. automethod:: XcodeBuild.discover_workspace_schemes + The ``XcodeBuild.build()`` method internally implements a call to ``xcodebuild`` like: .. code:: bash