image-oci: add layer caching for multi-layer OCI builds

Add layer caching to speed up multi-layer OCI image rebuilds. When
enabled, pre-installed package layers are cached to disk and restored
on subsequent builds, avoiding repeated package installation.

New variables:
- OCI_LAYER_CACHE: Enable/disable caching (default "1")
- OCI_LAYER_CACHE_DIR: Cache location (default ${TOPDIR}/oci-layer-cache/${MACHINE})

Cache key is computed from:
- Layer name and type
- Sorted package list
- Package versions from PKGDATA_DIR
- MACHINE and TUNE_PKGARCH

Cache automatically invalidates when:
- Package versions change
- Layer definition changes
- Architecture changes

Benefits:
- First build: ~10-30s per layer (cache miss, packages installed)
- Subsequent builds: ~1s per layer (cache hit, files copied)
- Shared across recipes with identical layer definitions

Build log shows cache status:
  NOTE: OCI Cache HIT: Layer 'base' (be88c180f651416b)
  NOTE: OCI: Pre-installed packages for 3 layers (cache: 3 hits, 0 misses)

Also adds comprehensive pytest suite for multi-layer OCI functionality
including tests for 1/2/3 layer modes and cache behavior.

Signed-off-by: Bruce Ashfield <bruce.ashfield@gmail.com>

1 files changed, 64 insertions, 0 deletions

diff --git a/docs/container-bundling.md b/docs/container-bundling.md
index a695a5b8..745622b5 100644
--- a/docs/container-bundling.md
+++ b/docs/container-bundling.md
@@ -193,6 +193,70 @@ OCI_LAYERS = "\
 "
 ```
 
+### Layer Caching
+
+Multi-layer builds cache pre-installed package layers for faster rebuilds.
+Installing packages requires configuring the package manager, resolving
+dependencies, and running post-install scripts - this is slow. Caching
+saves the fully-installed layer rootfs after the first build so subsequent
+builds can skip package installation entirely.
+
+#### Configuration
+
+    # Enabled by default
+    OCI_LAYER_CACHE ?= "1"
+    OCI_LAYER_CACHE_DIR ?= "${TOPDIR}/oci-layer-cache/${MACHINE}"
+
+#### Cache Key Components
+
+The cache key is a SHA256 hash of:
+
+| Component | Why It Matters |
+|-----------|----------------|
+| Layer name | Different layers cached separately |
+| Layer type | `packages` vs `directories` vs `files` |
+| Package list (sorted) | Adding/removing packages invalidates cache |
+| Package versions | Upgrading a package invalidates cache |
+| MACHINE, TUNE_PKGARCH | Architecture-specific packages |
+
+#### Advantages
+
+**Faster rebuilds**: Subsequent builds restore cached layers in ~1 second
+instead of ~10-30 seconds per layer for package installation.
+
+**Efficient development**: When only your app layer changes, base and
+dependency layers are restored from cache:
+
+    OCI_LAYERS = "\
+        base:packages:base-files+busybox \      # Cached - stable
+        deps:packages:python3+python3-pip \     # Cached - stable
+        app:packages:myapp \                    # Rebuilt - changes often
+    "
+
+**Automatic invalidation**: Cache invalidates when packages change version,
+layers are modified, or architecture changes. No manual clearing needed.
+
+**Shared across recipes**: Cache stored in `${TOPDIR}/oci-layer-cache/` so
+recipes with identical layers share the same cached content.
+
+#### Build Log Example
+
+    # First build - cache misses
+    NOTE: OCI Cache MISS: Layer 'base' (base:base-files=3.0.14 ...)
+    NOTE: OCI Cache: Saving layer 'base' to cache (be88c180f651416b)
+    NOTE: OCI: Pre-installed packages for 3 layers (cache: 0 hits, 3 misses)
+
+    # Second build - cache hits
+    NOTE: OCI Cache HIT: Layer 'base' (be88c180f651416b)
+    NOTE: OCI: Pre-installed packages for 3 layers (cache: 3 hits, 0 misses)
+
+#### When to Disable
+
+Disable caching with `OCI_LAYER_CACHE = "0"` if you:
+- Suspect cache corruption
+- Need fully reproducible builds with no local state
+- Are debugging package installation issues
+
 ### OCI_IMAGE_CMD vs OCI_IMAGE_ENTRYPOINT
 
     # CMD (default) - replaced when user passes arguments