Document cache layer locations and make CI smarter

Author: ctrueden

.github/workflows/build.yml

@@ -1,3 +1,20 @@
+# Appose CI Build
+#
+# Caching Strategy:
+# 1. Maven dependencies (via setup-java cache: 'maven')
+# 2. Appose environments and tool binaries (~/.local/share/appose)
+#    - Includes pixi, uv, and micromamba executables
+#    - Includes built environments
+# 3. Pixi package cache (~/.cache/rattler on Linux, ~/Library/Caches/rattler on macOS)
+# 4. UV package cache (~/.cache/uv on Linux, ~/Library/Caches/uv on macOS)
+# 5. Micromamba package cache (~/micromamba/pkgs and ~/.conda/pkgs)
+#
+# Cache keys are based on:
+# - pom.xml hash (dependencies change)
+# - Builder source files (tool versions change)
+#
+# This prevents redundant downloads of ~100MB+ tool binaries and packages on every CI run.
+
 name: build
 
 on:
@@ -34,14 +51,45 @@ jobs:
         with:
           python-version: '3.10'
 
-      - name: Cache Appose environments
+      - name: Cache Appose environments and tools
         id: cache-appose
         uses: actions/cache@v4
         with:
           path: ~/.local/share/appose
-          key: ${{ runner.os }}-build-appose-${{ hashFiles('*') }}
+          key: ${{ runner.os }}-appose-${{ hashFiles('pom.xml') }}-${{ hashFiles('src/main/java/org/apposed/appose/builder/Pixi.java', 'src/main/java/org/apposed/appose/builder/Uv.java', 'src/main/java/org/apposed/appose/builder/Mamba.java') }}
+          restore-keys: |
+            ${{ runner.os }}-appose-${{ hashFiles('pom.xml') }}-
+            ${{ runner.os }}-appose-
+
+      - name: Cache Pixi packages (Rattler cache)
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/rattler
+            ~/Library/Caches/rattler
+          key: ${{ runner.os }}-pixi-pkgs-${{ hashFiles('pom.xml') }}
+          restore-keys: |
+            ${{ runner.os }}-pixi-pkgs-
+
+      - name: Cache UV packages
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/uv
+            ~/Library/Caches/uv
+          key: ${{ runner.os }}-uv-pkgs-${{ hashFiles('pom.xml') }}
+          restore-keys: |
+            ${{ runner.os }}-uv-pkgs-
+
+      - name: Cache Micromamba packages
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/micromamba/pkgs
+            ~/.conda/pkgs
+          key: ${{ runner.os }}-mamba-pkgs-${{ hashFiles('pom.xml') }}
           restore-keys: |
-            ${{ runner.os }}-build-appose-
+            ${{ runner.os }}-mamba-pkgs-
 
       - name: Set up CI environment
         run: .github/setup.sh

README.md

@@ -141,6 +141,67 @@ try (Service python = env.python()) {
 Of course, the above examples could have been done all in one language. But
 hopefully they hint at the possibilities of easy cross-language integration.
 
+## Caching and disk usage
+
+Appose uses multiple layers of caching to improve performance and reduce
+redundant downloads. Understanding these cache locations can help you manage
+disk usage and troubleshoot environment issues.
+
+### Appose environment cache
+
+**Location:** `~/.local/share/appose/` (customizable via `appose.envs-dir` system property)
+
+This directory contains:
+- **Tool binaries:** Pixi, UV, and Micromamba executables downloaded by Appose
+  - `.pixi/bin/pixi` (v0.39.5)
+  - `.uv/bin/uv` (v0.5.25)
+  - `.mamba/bin/micromamba` (latest)
+- **Built environments:** Each named environment created via `build(envName)`
+
+### Package manager caches
+
+Each package manager maintains its own cache for downloaded packages:
+
+**Pixi** (uses Rattler cache):
+- Linux: `~/.cache/rattler`
+- macOS: `~/Library/Caches/rattler`
+- Windows: `%LOCALAPPDATA%\rattler\Cache`
+- Environment variable: `PIXI_CACHE_DIR` or `RATTLER_CACHE_DIR`
+
+**UV**:
+- Linux: `~/.cache/uv`
+- macOS: `~/Library/Caches/uv`
+- Windows: `%LOCALAPPDATA%\uv\Cache`
+- Environment variable: `UV_CACHE_DIR`
+- Check location: `uv cache dir`
+
+**Micromamba**:
+- Default: `~/micromamba/pkgs/` (micromamba's default root prefix)
+- Alternative: `~/.conda/pkgs/` (if conda was installed previously)
+- Customizable via: `micromamba config append pkgs_dirs /path/to/cache`
+- Environment variable: `MAMBA_ROOT_PREFIX` (changes the entire root, including `pkgs/` subdirectory)
+
+### Clearing caches
+
+To free up disk space, you can clear individual caches:
+
+```bash
+# Clear UV cache
+uv cache clean
+
+# Clear Pixi/Rattler cache
+pixi clean cache --yes
+
+# Clear Micromamba cache
+micromamba clean --all --yes
+
+# Remove all Appose environments and tools (nuclear option)
+rm -rf ~/.local/share/appose
+```
+
+**Note:** Package manager caches are shared across projects and significantly
+speed up subsequent environment creation. Only clear them if disk space is critical.
+
 ## Issue tracker
 
 All implementations of Appose use the same issue tracker: