feat: AGENTS.md and architecture guides for agents!
This commit is contained in:
Jonathan Kelley committed
1 parent
2ee8ecd477
commit
638c02e15a
12 files changed
+3324
No files matched your search
@@ -0,0 +1,264 @@
|
||||
# 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
|
||||
Reference in new issue
Block a user