🔨 ZSHAND Build System¶
The build system converts
.zshsource into.zwcbytecode bundles, chooses loading mode at startup, and provides profiling and benchmarking. The compilation engine iszprimein core/06_engine.zsh.
Most used commands
Rebuild: zr or zprime — compile all directories. Full bundle: zfull or zprime --full — one cache file (framework + user). Selective: zrecompile user after config-only changes. Profile: ZSHAND_PROFILE_BUNDLE=1 exec zsh — see PERFORMANCE.
See also: Performance (profiling, targets) · Architecture (loading strategies) · Auto-Full Mode (single-bundle fast path)
How It Works¶
The build system implements a hybrid compilation approach. In production, source files from each framework directory are concatenated into a single .zsh file and compiled to .zwc bytecode via zcompile. At startup, Zsh loads these bytecode bundles instead of parsing raw source — resulting in 3–5x faster loading per directory. In development mode, individual files are loaded directly so changes take effect immediately without recompilation.
The compilation engine lives in core/06_engine.zsh as the zprime function, which calls into the build/ scripts to do the actual work.
Loading Modes¶
The framework supports five loading strategies, selected automatically or via environment variables.
Auto-Full (ZSHAND_AUTO_FULL=1) is the recommended production mode. It compiles the entire framework plus user config into a single bundle at $ZSHAND_CACHE_DIR/zshand-full.zwc. On first run, compilation takes ~200–500ms. On subsequent runs, the fast path loads the bundle directly in ~42ms, skipping all build function loading.
Manual Full (ZSHAND_USE_MONOLITHIC=1) loads a pre-compiled full bundle from cache. You must run zfull before enabling this mode.
Hybrid (default) loads per-directory bundles from .compiled/ subdirectories. Each directory has its own *-all.zwc file. This is the balanced mode — faster than individual loading but slower than a single full bundle.
Individual (ZSHAND_DEV_MODE=1, or .dev file exists, or uncommitted git changes detected) loads every .zsh file separately. Slower (~180ms) but changes take effect immediately. Debug output is available with ZSHAND_DEBUG=1.
Profile (ZSHAND_PROFILE_BUNDLE=1) loads an instrumented bundle that records per-file timing data to $ZSHAND_CACHE_DIR/profile-timing.log.
Script Reference¶
Compilation Scripts¶
| Script | Function | Purpose |
|---|---|---|
compile_single_directory.zsh | _zshand_compile_single_directory | Compile one directory into .compiled/*-all.zwc |
compile_all_directories.zsh | _zshand_compile_all_directories | Compile all framework directories (used by zprime) |
compile_monolithic.zsh | _zshand_compile_monolithic | Build framework-only monolithic bundle |
compile_full_bundle.zsh | _zshand_compile_full_bundle | Build framework + user config full bundle |
compile_zshrc.zsh | — | Compile zshrc.zsh to bytecode |
compile_profile_bundle.zsh | — | Build instrumented profile bundle |
check_needs_rebuild_directory.zsh | _zshand_check_needs_rebuild_directory | Check if any source is newer than bundle |
Loading Scripts¶
| Script | Function | Purpose |
|---|---|---|
load_directory.zsh | _zshand_load_directory | Smart loader: bundle in prod, individual in dev |
load_compiled_bundles.zsh | _zshand_load_compiled_bundles | Load all directory bundles in order |
load_individual_directory.zsh | _zshand_load_individual_directory | Load all .zsh files individually |
detect_dev_mode.zsh | _zshand_detect_dev_mode | Auto-detect dev vs production mode |
Profiling & Benchmarking Scripts¶
| Script | Purpose |
|---|---|
benchmark_loading.zsh | Compare per-directory production vs dev loading times |
benchmark_monolithic.zsh | Time monolithic .zwc startup over N iterations |
profile_startup_detailed.zsh | Micro-profiling for operations >5ms |
profile_hooks.zsh | Time individual hook loading |
profile_time_all_widgets.zsh | Time widget registration |
profile_bundle_report.zsh | Generate report from profile timing data |
Optimization Scripts¶
| Script | Purpose |
|---|---|
optimize_startup.zsh | Contains optimized component versions |
activate_optimizations.zsh | Apply performance optimizations (--all) |
verify_optimizations.zsh | Verify optimizations are active |
CLI Commands¶
| Command | What It Does |
|---|---|
zr | Standard rebuild — compiles all directories via zprime |
zrebuild | Syntax-check all files, clean bytecode, recompile |
zrecompile user\|framework\|both | Selective recompilation by scope |
zfull | Build full bundle (framework + user) |
zmono | Build monolithic bundle (framework only) |
zfresh | Delete cache, recompile, restart shell |
zr-deps | Update .zshand-deps dependency manifests |
Performance¶
| Metric | Value |
|---|---|
| Full bundle startup | ~42ms |
| Hybrid per-directory startup | ~80ms |
| Individual file startup (dev) | ~180ms |
| Initial compilation | ~2–3s |
| Incremental compilation | ~200–500ms |
| CI regression threshold | +10ms fail |
🔗 Related Documents¶
| Document | Purpose |
|---|---|
| ⚡ Auto-Full Mode | Zero-config full bundle (recommended production) |
| ⚡ Performance | Profiling, benchmarks, optimization |
| 📚 Lib | Rebuild helpers and dependency manifests |
| 🏗️ Architecture | Loading strategies and bundle types |
| ⚙️ Core | Engine and zprime context |
| 📚 Documentation Index | Full doc nav |
| 📚 Documentation Index | Full doc nav |