zr - Framework Rebuild Tool¶

zr [options]
```bash

### Options

- No options: Full rebuild of all directories
- `--quiet`, `-q`: Silent operation, minimal output
- `--help`, `-h`: Show help message

## Examples

### Basic Usage

```bash
# Full framework rebuild - compiles all .zsh files into .zwc bytecode
# This is the most common usage after making any framework changes
zr

# Quiet rebuild - suppresses progress messages and compilation details
# Useful for automated scripts or when you don't need verbose output
zr --quiet
```bash

### After Configuration Changes

```bash
# Edit a function using the framework editor
# This opens your function in $EDITOR for modification
ze my-function

# After saving changes, rebuild the framework to compile the updated function
# This ensures your changes take effect in new shell sessions
zr

# Test the changes by starting a new shell session
# The compiled bytecode will load much faster than source files
exec zsh
```bash

### Development Workflow

```bash
# When developing framework features, rebuild frequently
# Edit core configuration
ze core/config

# Rebuild after each significant change
zr

# For rapid iteration, you can combine edit and rebuild
ze functions/my-feature && zr
```bash

### Troubleshooting Compilation

```bash
# If you suspect compilation issues, run with verbose output
# (zr doesn't have a verbose flag, but errors will be shown)

# Check if specific directories compiled successfully
ls -la core/.compiled/
ls -la functions/.compiled/

# Validate syntax before rebuilding
zsh -n core/config.zsh
zsh -n functions/my-function.zsh
```bash

### Development Workflow

```bash
# Make changes
edit core/some-file.zsh

# Quick rebuild and test
zr --quiet && exec zsh
```bash

## What It Does

1. **Sets permissions** - Ensures all `bin/` scripts are executable
2. **Compiles directories** - Converts `.zsh` files to `.zwc` bytecode:
   - `core/` → `core/.compiled/core-all.zwc`
   - `functions/` → `functions/.compiled/functions-all.zwc`
   - And so on for all framework directories
3. **Updates PATH** - Ensures `bin/` directory is in `$PATH`
4. **Validates compilation** - Reports any syntax errors

## Performance Impact

- **Without compilation**: Scripts parse and compile on every load
  (~50-100ms per directory)
- **With compilation**: Pre-compiled bytecode loads instantly (~5-10ms per directory)
- **Improvement**: 5-10x faster startup, especially noticeable with many functions

## Troubleshooting

### Compilation Fails

**Symptom:** `zr` shows "zcompile failed" with a file path

**Cause:** Syntax error in the specified `.zsh` file

**Fix:**

```bash
# Check syntax of the problematic file
zsh -n path/to/file.zsh

# Edit and fix the error
ze file

# Try rebuild again
zr
```bash

### Permission Denied

**Symptom:** "Permission denied" when running `zr`

**Cause:** `bin/zr` is not executable

**Fix:**

```bash
chmod +x bin/zr
./bin/zr  # Use full path
```bash

### No Effect After Rebuild

**Symptom:** Changes not visible after `zr`

**Cause:** Shell hasn't reloaded the compiled bundles

**Fix:**

```bash
# Reload current shell
exec zsh

# Or open new terminal
```bash

## Configuration

`zr` doesn't use configuration files but respects these environment variables:

- `ZSHAND_DEBUG=1` - Show detailed compilation progress
- `ZSHAND_QUIET=1` - Suppress all output (same as `--quiet`)

## Dependencies

- **Required:** `zsh`, `zcompile` (built into zsh)
- **Optional:** None

## Integration

### With Editors

```bash
# ze/zd automatically suggest running zr after edits
ze core/config
# [edit file]
# "Run zr to rebuild? [Y/n]"

# Manual workflow
zd functions && zr
```bash

### With Development

```bash
# Quick edit-rebuild-test cycle
ze functions/utils && zr --quiet && exec zsh

# Full development rebuild
zupdate  # Includes zr + additional maintenance
```bash

### With Deployment

```bash
# In deployment scripts
#!/bin/bash
cd /path/to/zshand
./bin/zr --quiet
```bash

## Technical Details

### Compilation Process

1. **Source collection**: Gathers all `.zsh` files in each directory
2. **Concatenation**: Combines files into single source file (`.zsh`)
3. **Syntax validation**: Runs `zsh -n` on concatenated source
4. **Bytecode generation**: `zcompile` creates optimized `.zwc` file
5. **Atomic replacement**: New bundle replaces old atomically

### Directory Order

Compiled in dependency order:

1. `startup` - Early initialization
2. `shared_functions` - Common utilities
3. `core` - Framework core
4. `functions` - User functions
5. `widgets` - ZLE widgets
6. `hooks` - Zsh hooks
7. `private_functions` - Private user functions

### Error Handling

- Continues compiling other directories if one fails
- Reports all errors at the end
- Returns non-zero exit code if any compilation failed
- Preserves partial compilations (successful directories remain compiled)

## Gotchas

### Compilation Fails Silently

**Problem:** `zr` appears to run successfully but scripts don't work faster.

**Cause:** Syntax errors in `.zsh` files prevent compilation.

**Solution:** Check for error messages in output. Fix syntax errors before
recompiling. Use `zsh -n file.zsh` to validate syntax.

### Permissions Issues

**Problem:** "Permission denied" errors during compilation.

**Cause:** Framework directories not writable or script permissions incorrect.

**Solution:** Ensure you're running as the file owner or with appropriate
permissions. `zr` will attempt to fix script permissions automatically.

### Mixed File Types

**Problem:** Some files compile, others don't.

**Cause:** Directory contains non-Zsh files (.sh, .bash, etc.).

**Solution:** `zr` only compiles `.zsh` files. Other shell scripts remain
as source files. This is normal behavior.

### PATH Not Updated

**Problem:** Compiled scripts not found after rebuild.

**Cause:** `bin/` directory not in `$PATH`.

**Solution:** `zr` attempts to add it automatically. If it fails, manually
add `/path/to/zshand/bin` to your PATH.

### Large Directories Slow

**Problem:** Compilation takes unusually long.

**Cause:** Very large framework directories or many files.

**Solution:** This is normal for large codebases. Compilation time scales
with file count. Consider splitting very large directories.

## See Also

- **[zupdate](zupdate.md)** - Full system maintenance (includes zr)
- **[zr-dir](zr-dir.md)** - Rebuild single directory
- **[ze](ze.md)** - Edit with automatic rebuild suggestion
- **[zd](zd.md)** - Edit with automatic rebuild suggestion
- **[Framework Architecture](../../README.md)** - How compilation works