9.4 KiB
9.4 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
Common Workflows
Setup Development Environment
# 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
See: pre-commit-setup.md for automated linting before commits.
Format & Lint Code
# 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
Run Tests
# 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
Build Project
# 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
Watch for Changes
Watch for file changes and auto-rebuild:
just dev::watch
Requires: cargo-watch (install with cargo install cargo-watch)
Generate Documentation
# Generate docs
just dev::docs-gen
# Generate and open in browser
just dev::docs
Run Examples
See ../examples/README.md for complete examples.
Quick examples:
# 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
Just Modules
build - Build Recipes
Compile project for different backends and targets:
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)
test - Test Suite
Run tests with various configurations:
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
dev - Development Tools
Format, lint, and document code:
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
ci - CI/CD Pipeline
Validation and build pipeline:
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
nickel - Nickel Schema Generation
Generate TOML forms from Nickel schemas:
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
distro - Distribution & Packaging
Build, package, and release:
# 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
Development Workflow Examples
Daily Development
# 1. Start watching
just dev::watch
# 2. In another terminal, work on code
# 3. Changes auto-rebuild
# 4. Run tests manually
just test::all
Adding a Feature
# 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
Preparing Release
# 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)
Examples
Complete examples organized by category:
Basic Examples
# Run basic form
cargo run --example form
# With sections
cargo run --example form_with_sections
# With groups
cargo run --example form_with_grouped_items
Advanced Examples
# Conditional logic
cargo run --example conditional_required_demo
# Autocompletion
cargo run --example form_with_autocompletion
Backend-Specific
# 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
Nickel Examples
Nickel schema parsing and generation:
# 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
See ../examples/07-nickel-generation/ for complete guide. See nickel.md for detailed Nickel documentation.
Troubleshooting
Build errors
Clear build cache and rebuild:
cargo clean
just build::default
Test failures
Run with backtrace for more details:
RUST_BACKTRACE=1 cargo test
Format check failing
Auto-fix formatting:
just fmt
"just" not found
Install or add to PATH:
cargo install just
export PATH="$HOME/.cargo/bin:$PATH"
cargo-watch not working
Install it:
cargo install cargo-watch
Port already in use (web backend)
Change port in config:
# config/web/dev.toml
[server]
port = 3001 # Instead of 3000
Or override:
TYPEDIALOG_WEB_PORT=3001 cargo run -p typedialog-web
Tips & Tricks
Faster builds
Use incremental compilation:
export CARGO_BUILD_JOBS=$(nproc)
export CARGO_INCREMENTAL=1
Parallel testing
cargo test -- --test-threads=4
Format all code quickly
just fmt && just lint-fix
Development script
Create a development startup script:
#!/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
Next Steps
- Read build.md for building distributions
- Read configuration.md for configuration options
- Check ../examples/README.md for examples
- See release.md for release process
Ready to develop! 🚀
Questions? Check the examples or open an issue on GitHub.