🔨 ZSHAND Build System¶

The build system converts .zsh source files into optimized .zwc bytecode bundles, manages development vs production loading modes, and provides profiling and benchmarking tools.

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