From 406fdb444a7c9d293c8439d93f79c4fc10a962ba Mon Sep 17 00:00:00 2001
From: Alex Lowe <alex.lowe@canonical.com>
Date: Wed, 20 Nov 2024 08:17:22 -0500
Subject: [PATCH] feat(docs): add information about CRAFT_SHARED_CACHE (#1989)

---
 docs/howto/index.rst         |  1 +
 docs/howto/shared-cache.rst  | 78 ++++++++++++++++++++++++++++++++++++
 docs/reference/changelog.rst |  1 +
 3 files changed, 80 insertions(+)
 create mode 100644 docs/howto/shared-cache.rst

diff --git a/docs/howto/index.rst b/docs/howto/index.rst
index 46ccff52b..9bf000898 100644
--- a/docs/howto/index.rst
+++ b/docs/howto/index.rst
@@ -8,3 +8,4 @@ How-To
 
    charm-to-poetry
    charm-to-python
+   shared-cache
diff --git a/docs/howto/shared-cache.rst b/docs/howto/shared-cache.rst
new file mode 100644
index 000000000..9fe793c68
--- /dev/null
+++ b/docs/howto/shared-cache.rst
@@ -0,0 +1,78 @@
+.. _howto-shared-cache:
+
+Cache intermediate build artefacts
+==================================
+
+Because Charmcraft builds Python packages from source rather than using pre-built
+wheels, the initial builds of charms can take a while. The intermediate artefacts
+get cached, which significantly speeds up subsequent builds.
+
+When installed  as a snap, Charmcraft automatically caches these wheels in the
+``~/snap/charmcraft/common/cache`` directory. However, in some cases, it may be
+beneficial to change this directory.
+
+This can be especially useful in CI, where you may wish to specify a directory that
+gets cached between CI runs.
+
+Local usage
+-----------
+
+When packing locally, you can change where Charmcraft caches build artefacts by setting
+the ``CRAFT_SHARED_CACHE`` environment variable to the path of an existing directory to
+use instead::
+
+  mkdir -p /tmp/charmcraft
+  CRAFT_SHARED_CACHE=/tmp/charmcraft charmcraft pack
+
+On GitHub
+---------
+
+While it's recommended that you use the ``charmcraft/pack`` action from
+`craft-actions`_ where possible, the following workflow will manually pack a charm,
+caching the intermediate files:
+
+.. code-block:: yaml
+
+    name: Pack charm
+    on:
+      pull_request:
+    jobs:
+      pack:
+        runs-on: ubuntu-latest
+        steps:
+        - uses: actions/checkout@v4
+        - uses: canonical/craft-actions/charmcraft/setup
+        - uses: actions/cache@v4
+            with:
+              path: ${{ runner.temp }}
+              key: charmcraft-cache-${{ hashfiles('requirements.txt') }}
+              restore-keys: |
+                charmcraft-cache-
+        - env:
+            CRAFT_SHARED_CACHE: ${{ runner.temp }
+          run: |
+            charmcraft pack
+
+On GitLab
+---------
+
+The following example ``gitlab-ci.yml`` will install and run Charmcraft to pack your
+charm, caching the intermediate artefacts:
+
+.. code-block:: yaml
+
+    pack-charm:
+      cache:
+        - key:
+            files:
+              - requirements.txt
+          paths:
+            - .charmcraft_cache/
+      variables:
+        CRAFT_SHARED_CACHE: .charmcraft_cache/
+      script:
+        - mkdir -p .charmcraft_cache
+        - snap install charmcraft
+        - charmcraft pack
+
+.. _craft-actions: https://github.com/canonical/craft-actions
diff --git a/docs/reference/changelog.rst b/docs/reference/changelog.rst
index 20941fe6d..12cac5a82 100644
--- a/docs/reference/changelog.rst
+++ b/docs/reference/changelog.rst
@@ -375,3 +375,4 @@ page.
 .. _3.1.2: https://github.com/canonical/charmcraft/releases/tag/3.1.2
 .. _3.2.0: https://github.com/canonical/charmcraft/releases/tag/3.2.0
 .. _3.2.1: https://github.com/canonical/charmcraft/releases/tag/3.2.1
+.. _3.2.2: https://github.com/canonical/charmcraft/releases/tag/3.2.2