diff --git a/doc/explanation/tour/engine.rst b/doc/explanation/tour/engine.rst index b4dca0b9d1f..163314b6e01 100644 --- a/doc/explanation/tour/engine.rst +++ b/doc/explanation/tour/engine.rst @@ -12,4 +12,4 @@ different frontend and CLI. In the context of Dune, the engine keeps track of the various directories and the rules in them and is able to build files using them. In addition, it takes care of the various caches that Dune uses, such as the one present in the -``_build`` directory, the :doc:`shared cache `, etc. +``_build`` directory, the :doc:`shared cache `, etc. diff --git a/doc/caching.rst b/doc/reference/caches.rst similarity index 65% rename from doc/caching.rst rename to doc/reference/caches.rst index 9278e10a4e6..ae907cf5d2f 100644 --- a/doc/caching.rst +++ b/doc/reference/caches.rst @@ -1,15 +1,43 @@ -********** -Dune Cache -********** +Dune Caches +=========== -.. TODO(diataxis) This is reference material with some explanation. +Dune implements several different caches: -Dune implements a cache of build results that is shared across different -workspaces. Before executing a build rule, Dune looks it up in the shared -cache, and if it finds a matching entry, Dune skips the rule's execution and -restores the results in the current build directory. This can greatly speed up -builds when different workspaces share code, as well as when switching branches -or simply undoing some changes within the same workspace. +- The build cache contains build artifacts that are shared across different + workspaces. This is the main cache, interacted with via the ``dune cache`` + command. +- The toolchains cache contains the compiler (and compiler variants) when they + can't be installed like regular packages, due to them not being relocatable. +- The revision store is a git repository containing all revisions fetched via + git. + +Their location is as follows: + ++------------------+----------------+------------------------------------+-----------------------------------+ +| Name | Default status | Default location on Unix | Alternate location (has priority) | ++==================+================+====================================+===================================+ +| Build cache | Enabled | ``XDG_CACHE_HOME/dune/db`` | ``DUNE_CACHE_ROOT/db`` | ++------------------+----------------+------------------------------------+-----------------------------------+ +| Toolchains cache | Enabled | ``XDG_CACHE_HOME/dune/toolchains`` | ``DUNE_CACHE_ROOT/toolchains`` | ++------------------+----------------+------------------------------------+-----------------------------------+ +| Revision store | Enabled | ``XDG_CACHE_HOME/dune/git-repo`` | ``DUNE_CACHE_ROOT/git-repo`` | ++------------------+----------------+------------------------------------+-----------------------------------+ + +.. note:: + + On Windows, you can replace ``XDG_CACHE_HOME`` by ``%LOCALAPPDATA%\Microsoft\Windows\Temporary Internet Files`` + + +.. TODO(diataxis) Above is reference material, below is explanation. + +How Caching Works +================= + +Before executing a build rule, Dune hashes the rule and looks up that hash in +the shared cache, and if it finds a matching entry, Dune skips the rule's +execution and restores the results in the current build directory. This can +greatly speed up builds when different workspaces share code, as well as when +switching branches or simply undoing some changes within the same workspace. Configuration @@ -108,4 +136,4 @@ Some build rules are inherently not reproducible because they involve running non-deterministic commands that, for example, depend on the current time or download files from the Internet. To prevent Dune from caching such rules, mark them as non-reproducible by using ``(deps (universe))``. Please see -:doc:`concepts/dependency-spec`. +:doc:`/concepts/dependency-spec` for more details. diff --git a/doc/reference/index.rst b/doc/reference/index.rst index 2d0db3a5bd8..de2136e1c8b 100644 --- a/doc/reference/index.rst +++ b/doc/reference/index.rst @@ -66,7 +66,7 @@ These documents specify the various features and languages present in Dune. cli ../dune-libs - ../caching + caches .. grid-item::