Skip to content

Commit e054ef0

Browse files
committed
docs(build): explain why AI Models and SEA don't use directory caching
Expand Pattern 3 documentation to clearly explain why directory caching is not used for AI Models and SEA builds. **Added explanations:** AI Models: - Single-pass conversion (PyTorch → ONNX → Quantize) - No incremental compilation (can't resume partway) - Temp files deleted immediately - 10-15 min build time (not worth cache overhead) SEA: - Just JS bundling + injection (~30 seconds total) - Uses pre-built Node.js (no compilation) - Cache download > rebuild time **Added decision criteria:** When directory caching IS valuable: - Slow compilation (>5 minutes) - Can fail partway through - Reusable intermediate state - Resume faster than rebuild When directory caching is NOT valuable: - No compilation (scripts/bundling) - Already fast (<1 minute) - No reusable intermediate state - Cache overhead > time saved This clarifies why the unified strategy uses different caching approaches for different build types.
1 parent e991ee7 commit e054ef0

File tree

1 file changed

+28
-0
lines changed

1 file changed

+28
-0
lines changed

docs/build/caching-strategy.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,34 @@ Does the build compile C/C++?
114114
- Intermediate state doesn't speed up rebuilds
115115
- Simple caching is sufficient
116116
117+
**Why no directory cache?**
118+
119+
**AI Models:**
120+
- Single-pass conversion process (PyTorch → ONNX → Quantize)
121+
- No incremental compilation (can't resume partway)
122+
- Intermediate files are temporary and immediately deleted
123+
- If conversion fails, must restart from beginning anyway
124+
- Total time: ~10-15 minutes (not long enough to justify cache overhead)
125+
126+
**SEA (Single Executable Application):**
127+
- Just bundling JavaScript + injecting into pre-built Node.js binary
128+
- Total time: ~30 seconds (already very fast)
129+
- Uses pre-built Node.js from pkg cache (no compilation)
130+
- JavaScript bundling regenerates instantly (~10 seconds)
131+
- Cache download time would exceed rebuild time
132+
133+
**When directory caching is valuable:**
134+
- ✅ Compilation is slow (>5 minutes)
135+
- ✅ Builds can fail partway through long compilation
136+
- ✅ Intermediate state is reusable (compiled objects, CMake cache)
137+
- ✅ Resuming from cache is faster than rebuilding
138+
139+
**When directory caching is NOT valuable:**
140+
- ❌ No compilation (just scripting, bundling, copying)
141+
- ❌ Builds are already fast (<1 minute)
142+
- ❌ No reusable intermediate state (temp files, single-pass operations)
143+
- ❌ Cache overhead exceeds time saved
144+
117145
## Cache Key Strategy
118146
119147
All caches use **content-based hashing** for invalidation:

0 commit comments

Comments
 (0)