Document SYMFONY_CACHE_DIR

tucksaun · tucksaun · commit f39aa43c6bd5 · 2020-10-14T11:07:45.000+02:00
diff --git a/config.rst b/config.rst
@@ -397,17 +397,27 @@ Three hooks are available:
 * First, the **build** script runs when SymfonyCloud packages the application.
   At this time, the application source code is checked out, global
   `dependencies`_ are installed and the filesystem can be written at will but no
-  :doc:`services </services/intro>` are available. This is the best time to run
-  heavy-duty tasks that can be performed offline such as assets build or Symfony
-  container compilation.
+  :doc:`services </services/intro>` are available.
 
   .. caution::
 
-    The *build* step creates a container image that is tied to the sha1 of
-    the Git tree being built. This image is reused for all deployments and all
+    The *build* step creates a container image that is tied to the Git tree
+    content being built. This image is reused for all deployments and all
     environments, including production. This means that the build step **must**
     be environment agnostic.
 
+  This is the best time to run heavy-duty tasks that can be performed offline
+  such as assets build or Symfony container compilation. A persisted :ref:`build
+  cache directory <build_cache_dir>` is available to you for storing reusable
+  artifacts. ``/tmp`` is also writable but its content is wiped after the build.
+
+  .. note::
+
+    Build environments (the application plus the cache directory) are limited to
+    4 GB during the build step - independently of the mounted disk size that is
+    allocated for deployment. If you exceed this limit you will receive a ``No
+    space left on device error``.
+
 .. _deploy-hook:
 
 * Then, the **deploy** script runs when SymfonyCloud is deploying the
diff --git a/cookbooks/env.rst b/cookbooks/env.rst
@@ -162,6 +162,23 @@ prefixed with ``SYMFONY_*``:
 * ``SYMFONY_PROJECT_ENTROPY``: A random value created when the project is
   first created, which is then stable throughout the project’s life.
 
+The following variables exist **only** during the build. If used at runtime they
+will evaluate to an empty string like any other unset variable:
+
+.. _build_cache_dir:
+
+* ``SYMFONY_CACHE_DIR``: The absolute path to the build cache directory
+  available during the :ref:`build hook <build-hook>` execution.
+
+  This directory is persisted between builds, but is **not** deployed. It’s a
+  good place to store build artifacts, such as downloaded files, that can be
+  reused between builds.
+
+  .. note::
+
+     This directory is shared by **all** builds on **all** branches, make sure
+     your build hook accounts for that.
+
 The following variables exist **only** at runtime. If used in a build hook they
 will evaluate to an empty string like any other unset variable:
 
