9.5 KiB
9.5 KiB
Development Guide
Guide for local TypeDialog development using just command orchestration.
Quick Start
# See all available commands
just --list
# Show help
just help
# Get help for specific module
just help build # Build commands
just help test # Test commands
just help dev # Development utilities
just help ci # CI/CD pipeline
just help distro # Distribution & packaging
```text
## Common Workflows
### Setup Development Environment
```bash
# 1. Clone and enter repository
git clone https://github.com/anthropics/typedialog.git
cd typedialog
# 2. Verify installation (see installation.md)
rustc --version && cargo --version && just --version
# 3. Build project
just build::default
# 4. Run tests
just test::all
# 5. Setup pre-commit hooks (optional but recommended)
./scripts/setup-pre-commit.sh
```text
**See**: [pre-commit-setup.md](pre-commit-setup.md) for automated linting before commits.
### Format & Lint Code
```bash
# Format code
just fmt
# Check formatting (without changes)
just fmt-check
# Run linter
just lint
# Auto-fix linter warnings
just lint-fix
# All checks together
just check-all
```text
### Run Tests
```bash
# All tests (default features)
just test::all
# All tests with all features
just test::all-features
# Test specific backend
just test::cli # CLI backend
just test::tui # TUI backend
just test::web # Web backend
# Test specific crate
just test::core # typedialog-core
# Integration tests
just test::integration
# Documentation tests
just test::doc
```text
### Build Project
```bash
# Build with default features
just build::default
# Build specific backend
just build::cli # CLI only
just build::tui # TUI only
just build::web # Web only
# Build all backends
just build::all-backends
# Release build (optimized)
just build::release
```text
### Watch for Changes
Watch for file changes and auto-rebuild:
```bash
just dev::watch
```text
Requires: `cargo-watch` (install with `cargo install cargo-watch`)
### Generate Documentation
```bash
# Generate docs
just dev::docs-gen
# Generate and open in browser
just dev::docs
```text
### Run Examples
See [../examples/README.md](../examples/README.md) for complete examples.
Quick examples:
```bash
# Run basic example
cargo run --example form
# Run with specific backend
cargo run -p typedialog-tui --example form_with_autocompletion
# List available examples
just test::list
```text
## Just Modules
### build - Build Recipes
Compile project for different backends and targets:
```bash
just build::default # Debug build
just build::release # Release build (optimized)
just build::cli # CLI backend only
just build::tui # TUI backend only
just build::web # Web backend only
just build::all # All variants
just build::all-backends # All backends combined
just build::full # All features
just build::check # Check compilation (no build)
```text
### test - Test Suite
Run tests with various configurations:
```bash
just test::all # All tests
just test::all-features # With all features
just test::cli # CLI tests
just test::tui # TUI tests
just test::web # Web tests
just test::core # Core library tests
just test::bins # Binary tests
just test::integration # Integration tests
just test::doc # Doc tests
just test::verbose # Tests with output
just test::list # List tests
```text
### dev - Development Tools
Format, lint, and document code:
```bash
just dev::fmt # Format code
just dev::fmt-check # Check format
just dev::lint # Lint with clippy
just dev::lint-fix # Auto-fix warnings
just dev::audit # Audit dependencies
just dev::docs-gen # Generate docs
just dev::docs # Generate and open
just dev::build # Build default
just dev::watch # Watch and rebuild
just dev::check # Check + fmt + lint
just dev::info # Show workspace info
just dev::tree # Dependency tree
```text
### ci - CI/CD Pipeline
Validation and build pipeline:
```bash
just ci::fmt-check # Format validation
just ci::lint # Linting
just ci::check # Format + lint
just ci::test-all # Test all features
just ci::test-default # Test default
just ci::test-integration # Integration tests
just ci::build-debug # Debug build
just ci::build-release # Release build
just ci::full # Complete pipeline
```text
### nickel - Nickel Schema Generation
Generate TOML forms from Nickel schemas:
```bash
just nickel::nickel-to-form SCHEMA # Generate form from schema
just nickel::nickel-preview SCHEMA # Preview without writing
just nickel::nickel-workflow SCHEMA TEMPLATE # Full workflow
just nickel::nickel-i18n SCHEMA # Extract i18n only
just nickel::nickel-roundtrip IN FORM # Roundtrip (read/write)
just nickel::help # Show Nickel recipes help
```text
### distro - Distribution & Packaging
Build, package, and release:
```bash
# Build
just distro::build-all # Debug build
just distro::build-release # Release build
# Cross-compile
just distro::cross # All targets
just distro::cross-docker TGT # Docker build
# Package
just distro::create-package # Create distribution
just distro::create-checksums # Generate checksums
just distro::package-all # Build + package
# Release
just distro::package-release # Prepare release
just distro::package-release-version V # With version
# Utilities
just distro::generate-manifest # Create manifest
just distro::list-packages # List packages
just distro::clean-distro # Clean directory
```text
## Development Workflow Examples
### Daily Development
```bash
# 1. Start watching
just dev::watch
# 2. In another terminal, work on code
# 3. Changes auto-rebuild
# 4. Run tests manually
just test::all
```text
### Adding a Feature
```bash
# 1. Create feature branch
git checkout -b feature/my-feature
# 2. Code and test
just check-all
# 3. Run full validation
just ci::full
# 4. Push and create PR
git push origin feature/my-feature
```text
### Preparing Release
```bash
# 1. Update version in Cargo.toml
nano crates/typedialog-core/Cargo.toml
# 2. Validate everything
just ci::full
# 3. Build and package
just distro::build-release
just distro::create-package
just distro::create-checksums
# 4. Prepare release
just distro::package-release
# 5. Create GitHub release (see release.md)
```text
## Examples
Complete examples organized by category:
### Basic Examples
```bash
# Run basic form
cargo run --example form
# With sections
cargo run --example form_with_sections
# With groups
cargo run --example form_with_grouped_items
```text
### Advanced Examples
```bash
# Conditional logic
cargo run --example conditional_required_demo
# Autocompletion
cargo run --example form_with_autocompletion
```text
### Backend-Specific
```bash
# CLI with autocompletion
cargo run --example autocompletion_demo
# TUI interactive form
cargo run -p typedialog-tui --example form_with_autocompletion
# Web server
cargo run -p typedialog-web -- --config config/web/dev.toml
```text
### Nickel Examples
Nickel schema parsing and generation:
```bash
# Basic Nickel schema
cargo run --example basic_nickel_schema
# Roundtrip (parse, transform, write)
cargo run --example nickel_roundtrip
# I18n extraction from Nickel
cargo run --example nickel_i18n_extraction
# Template rendering
cargo run --example nickel_template_context
```text
See [../examples/07-nickel-generation/](../examples/07-nickel-generation/) for complete guide.
See [nickel.md](nickel.md) for detailed Nickel documentation.
## Troubleshooting
### Build errors
Clear build cache and rebuild:
```bash
cargo clean
just build::default
```text
### Test failures
Run with backtrace for more details:
```bash
RUST_BACKTRACE=1 cargo test
```text
### Format check failing
Auto-fix formatting:
```bash
just fmt
```text
### "just" not found
Install or add to PATH:
```bash
cargo install just
export PATH="$HOME/.cargo/bin:$PATH"
```text
### cargo-watch not working
Install it:
```bash
cargo install cargo-watch
```text
### Port already in use (web backend)
Change port in config:
```toml
# config/web/dev.toml
[server]
port = 3001 # Instead of 3000
```text
Or override:
```bash
TYPEDIALOG_WEB_PORT=3001 cargo run -p typedialog-web
```text
## Tips & Tricks
### Faster builds
Use incremental compilation:
```bash
export CARGO_BUILD_JOBS=$(nproc)
export CARGO_INCREMENTAL=1
```text
### Parallel testing
```bash
cargo test -- --test-threads=4
```text
### Format all code quickly
```bash
just fmt && just lint-fix
```text
### Development script
Create a development startup script:
```bash
#!/bin/bash
# dev.sh
echo "Installing dependencies..."
cargo install just cargo-watch
echo "Building project..."
just build::default
echo "Running tests..."
just test::all
echo "Watching for changes..."
just dev::watch
```text
## Next Steps
- Read [build.md](build.md) for building distributions
- Read [configuration.md](configuration.md) for configuration options
- Check [../examples/README.md](../examples/README.md) for examples
- See [release.md](release.md) for release process
---
**Ready to develop!** 🚀
Questions? Check the examples or open an issue on GitHub.