dioxus/notes/architecture/02-CLI.md

# Dioxus CLI Architecture

The `dx` CLI is a comprehensive build tool for Dioxus applications, supporting development, building, bundling, and cross-platform deployment.

## Command Structure

Entry point: `main.rs` with async tokio runtime and `TraceController` for error handling.

### Commands Enum
- `Serve` - Watch and serve with hot-reloading
- `Build` - Full production build
- `Bundle` - Package for distribution
- `Run` - Run without hot-reload
- `Create` / `Init` - Project scaffolding
- `Check` - Lint/validate RSX
- `Translate` - Convert HTML/JSX to RSX
- `Autoformat` - Format RSX code
- `Config` - Manage Dioxus.toml
- `Doctor` - Diagnose environment
- `Components` - Component registry
- `SelfUpdate` - Update CLI
- `Tools` - Internal tools (build-assets, hotpatch)

## Platform Support

### Platform Enum
- `Web` - wasm32-unknown-unknown
- `MacOS` / `Windows` / `Linux` - Desktop webview
- `Ios` / `Android` - Mobile webview
- `Server` - SSR/fullstack server
- `Liveview` - WebSocket streaming
- `Unknown` - Auto-select

### CommandWithPlatformOverrides
Allows separate client/server args for fullstack:
```bash
dx serve @client --features web @server --features server
```

Decomposes into client BuildArgs, server BuildArgs, and shared args.

## Build System

### BuildRequest
The "plan" for a single build:
```
BuildRequest
├── workspace: Workspace metadata
├── config: DioxusConfig
├── package: Package details
├── features: Vec<String>
├── target: Triple
├── bundle: BundleFormat
├── profile: Profile
├── rustflags: Vec<String>
└── custom_linker: Option<PathBuf>
```

Responsible for:
- Writing build artifacts
- Processing assets
- Writing platform-specific metadata (Info.plist, AndroidManifest.xml)
- Platform-specific linking (Android uses dx as opaque linker, hotpatching uses custom linker)

### BuildMode Enum
- `Base { run: bool }` - Normal cargo rustc build
- `Fat` - Full build with all symbols for hot-patching
- `Thin { rustc_args, changed_files, aslr_reference, cache }` - Fast rebuild

### BuildContext
Runtime configuration with progress channel:
- `ProgressTx` for status updates
- `BuildId` enum: PRIMARY (client), SECONDARY (server)
- Helper methods: `compiling()`, `linking()`, `bindgen()`, etc.

### AppBuilder
State machine managing ongoing builds:
- Build task handle and artifacts
- App child process (stdout/stderr)
- Hot-patching state (patches, module cache, ASLR offset)
- Build metadata: stage, compiled crates, timing

## Dev Server (Serve)

### AppServer (runner.rs)
Primary orchestration:
```
AppServer
├── workspace: Workspace metadata
├── client / server: AppBuilder instances
├── watcher: File system watcher
├── file_map: Cached RSX files for hot-reload diffing
├── devserver: WebServer
└── flags: use_hotpatch_engine, automatic_rebuilds, hot_reload, etc.
```

### WebServer (server.rs)
HTTP + WebSocket server providing:
- **Hot-reload socket** - RSX and asset updates
- **Build-status socket** - Compilation progress
- **HTTP server** - Static assets (public folder, WASM)
- **Proxy support** - Fullstack backend
- **DevTools** - Connected clients with build_id, ASLR reference, PID

### Output (output.rs)
Terminal UI with ratatui:
- Build progress with crate-by-crate counts
- Asset copying progress
- Colored output, throbber animations
- Keyboard input (r=rebuild, p=pause, v=verbose)
- 100ms tick-based rendering

### File Change Handling
```
File modified → detect type
├── Rust file → diff RSX using dioxus_rsx_hotreload::diff_rsx()
│   ├── Extract changed templates
│   ├── Build HotReloadMsg
│   └── Send via WebSocket
├── Asset file → copy to bundle, signal reload
└── If can't hot-reload → queue full rebuild
```

### serve_all() Main Loop
Uses `tokio::select!` to multiplex:
- Builder updates (compilation, process output)
- WebServer events (connections, messages)
- Output (TUI updates, input)
- TraceController (panic handling)
- File watcher (filesystem changes)

## Asset Processing

### Pipeline (build/assets.rs)
1. **Manganis Integration** - Extract `__ASSETS__` symbols from binary
2. **Asset Hashing** - Compute hashes for cache-busting
3. **Two Format Support** - Legacy (0.7.0-0.7.1) and New (0.7.2+) serialization
4. **Platform Paths** - Assets relative to executable; Android uses "asset root"

### Processing by Type
- **Images**: Resize, convert format (Avif, WebP), optimize
- **CSS/JS**: Minify, hash-suffix naming
- **Folders**: Recursive copy
- **Unknown**: Direct copy with optional hash

## Bundling

### Bundle System
Platform-specific packaging:
- **Web/Server**: No special bundling, outputs to web/ directory
- **Desktop**: Uses tauri-bundler (dmg, msi, appimage)
- **iOS**: App bundle format with codesigning warnings
- **Android**: Runs `gradle bundleRelease` for AAB

### BundleConfig
```
BundleConfig
├── identifier: String
├── publisher: String
├── icon: Vec<PathBuf>
├── resources: Vec<PathBuf>
├── deb / macos / windows / android: Platform-specific
```

## Hot-Patching

### HotpatchModuleCache
Caches compiled dependency symbols:
- Symbol table with function/data info
- Pre-computed for Fat builds
- Reused in Thin builds for fast linking

### Patch Creation Flow
1. Compile app with Fat mode (all symbols)
2. On change: compile Thin (small, fast)
3. Analyze binary diff → create JumpTable
4. Apply patches to running executable
5. If patch fails → fall back to full rebuild

### Platform Implementations
- `create_windows_jump_table()` - x86/x64 jump stubs
- `create_native_jump_table()` - macOS/Linux function overrides
- `create_wasm_jump_table()` - WASM indirect call table updates

## Configuration

### DioxusConfig (Dioxus.toml)
```toml
[application]
asset_dir = "assets"
out_dir = "dist"
tailwind_input/output = "..."
ios_info_plist = "Info.plist"
android_manifest = "AndroidManifest.xml"

[web]
app.title = "My App"
https.enabled = true
pre_compress = false

[bundle]
identifier = "com.example.app"
publisher = "Company"
```

### Resolution Order
1. Default values
2. Dioxus.toml in project root
3. CLI argument overrides
4. Environment variables

## Workspace

### Workspace Struct (Singleton)
```
Workspace
├── krates: Krates (cargo metadata, dependency graph)
├── settings: CliSettings (user settings ~/.config/dioxus/)
├── sysroot: Rust target sysroot
├── rustc_version: Version
├── wasm_opt: Optional path
├── cargo_toml: Parsed Cargo.toml
└── android_tools: Optional NDK/SDK
```

Lazy-loaded via `Workspace::current()` with tokio Mutex.

## Extension Points

### Adding New Bundlers
1. New variant in `BundleFormat` enum
2. New variant in `Renderer` enum
3. New config struct (e.g., `MyPlatformSettings`)
4. Implementation in `Bundle::bundle()`
5. Asset directory structure definition
6. Linking strategy if needed

### Adding New Commands
1. New variant in `Commands` enum
2. New command module in `cli/`
3. Register in `TraceController::main()` match
4. Optional `StructuredOutput` variant for results

### Customizing Build Hooks
- Pre/post-build scripts in Dioxus.toml
- Custom linker integration
- Asset transformation pipeline

## Key Patterns

### Channel-Based Progress
```
Build Task → BuilderUpdate Channel → AppBuilder → ServeUpdate → Output TUI
```
Decouples build process from UI for real-time updates.

### Lazy Workspace Loading
Single workspace load with tokio Mutex, shows spinner if cargo-metadata takes >1 second.

### Renderer/Bundle Inference
1. Explicit flags: `--web`, `--webview`, `--native`
2. Platform aliases: `--ios`, `--android`, `--desktop`
3. Feature detection from Cargo.toml
4. Default: Infer from target triple