TypeDialog Logo
# Building & Distribution Guide Complete guide for building, packaging, and releasing TypeDialog. ## Overview Two main workflows: 1. **Building** - Compile binaries for your platform 2. **Distribution** - Package with configs and installers for release ## Building Binaries ### Single Platform Build Build for your current platform: ```bash # Debug build (default) just distro::build-all # Release build (optimized) just distro::build-release ``` **Output**: Binaries in `target/release/` ```bash # Check binaries ls -la target/release/typedialog* ``` ### Build by Backend Build specific backend only: ```bash just build::cli # CLI backend just build::tui # TUI backend just build::web # Web backend just build::all # All backends ``` ### Development Build Quick build for development: ```bash just build::default ``` ## Cross-Compilation Build for multiple platforms: ### Using cargo-cross Cross-compile to different targets: ```bash # All supported targets just distro::cross # Specific target just distro::cross-target x86_64-unknown-linux-gnu ``` **Supported targets:** - `x86_64-unknown-linux-gnu` - Linux x86_64 - `aarch64-unknown-linux-gnu` - Linux ARM64 - `x86_64-apple-darwin` - macOS Intel - `aarch64-apple-darwin` - macOS Apple Silicon - `x86_64-pc-windows-gnu` - Windows x86_64 **Requires:** `cargo install cross` ### Using Docker Docker-based cross-compilation: ```bash # Docker cross-compile just distro::cross-docker x86_64-unknown-linux-gnu ``` **Requires:** Docker installed **Dockerfile:** See `Dockerfile.cross` ## Creating Distribution Packages Distribution packages include binaries, configs, and installers. ### Create Package ```bash # From existing binaries just distro::create-package # With specific version just distro::create-package-version v0.1.0 ``` **Output:** `distribution/typedialog-0.1.0/` ``` typedialog-0.1.0/ ├── bin/ │ ├── typedialog # CLI binary │ ├── typedialog-tui # TUI binary │ └── typedialog-web # Web binary ├── config/ │ ├── cli/ # 3 configs: default, dev, production │ ├── tui/ # 3 configs │ └── web/ # 3 configs ├── installers/ │ ├── install.sh # Linux/macOS installer │ ├── install.ps1 # Windows installer │ └── README.md # Installation guide └── MANIFEST.json # Package metadata ``` ### Generate Checksums ```bash just distro::create-checksums ``` **Output:** `SHA256SUMS` file Verify integrity: ```bash sha256sum -c SHA256SUMS ``` ### Full Package Workflow ```bash # 1. Build release just distro::build-release # 2. Create package just distro::create-package # 3. Generate checksums just distro::create-checksums # Or all together: just distro::package-all ``` ## Distribution Structure ### Package Contents **bin/** - Compiled binaries - `typedialog` - CLI backend - `typedialog-tui` - TUI backend - `typedialog-web` - Web backend **config/** - Configuration templates - CLI configs (default, dev, production) - TUI configs (default, dev, production) - Web configs (default, dev, production) **installers/** - Installation scripts - `install.sh` - For Linux/macOS - `install.ps1` - For Windows - `README.md` - Installation guide **MANIFEST.json** - Package metadata ```json { "name": "typedialog", "version": "0.1.0", "created": "...", "binaries": [...], "configs": {...}, "installers": {...} } ``` ### Configuration Management Pre-configured settings for each backend and environment: **CLI Backend:** - `default.toml` - Standard settings - `dev.toml` - Development (debug enabled) - `production.toml` - Hardened production **TUI Backend:** - `default.toml` - Interactive settings - `dev.toml` - Development features - `production.toml` - Optimized production **Web Backend:** - `default.toml` - Standard web server - `dev.toml` - Development (hot reload) - `production.toml` - Hardened web server See [CONFIGURATION.md](CONFIGURATION.md) for details. ## Build Scripts All build automation uses bash scripts in `scripts/`: ### build_all.sh Build all workspace targets: ```bash ./scripts/build_all.sh [debug|release] ``` ### build_cross.sh Cross-compile for multiple platforms: ```bash ./scripts/build_cross.sh [target] ``` ### create_distro.sh Create distribution package: ```bash ./scripts/create_distro.sh [version] ``` ### package_release.sh Prepare release with checksums and notes: ```bash ./scripts/package_release.sh [version] ``` ## Docker Build ### Dockerfile.cross Multi-platform Docker build: ```bash # Build image for specific target docker build -f Dockerfile.cross \ --build-arg TARGET=x86_64-unknown-linux-gnu \ -t typedialog-builder:latest \ . # Run compilation docker run --rm \ -v $(pwd)/distribution:/output \ typedialog-builder:latest ``` ## Complete Release Workflow Prepare a release for GitHub: ```bash # 1. Build release binaries just distro::build-release # 2. Create distribution package just distro::create-package # 3. Generate checksums just distro::create-checksums # 4. Prepare release (with notes) just distro::package-release # 5. Verify contents just distro::list-packages # 6. Create GitHub release (see RELEASE.md) gh release create v0.1.0 \ release/typedialog-0.1.0.tar.gz \ release/SHA256SUMS \ --title "TypeDialog 0.1.0" \ --notes-file release/RELEASE_NOTES.md ``` ## Utilities ### List packages ```bash just distro::list-packages ``` ### Generate manifest ```bash just distro::generate-manifest ``` ### Clean distribution ```bash just distro::clean-distro ``` ## Troubleshooting ### Build fails Clear cache and rebuild: ```bash cargo clean just distro::build-release ``` ### Cross-compilation fails Ensure Docker is running: ```bash docker --version docker run hello-world ``` ### Missing dependencies Install required tools: ```bash cargo install cross # For cross-compilation cargo install just # For command orchestration ``` ### Checksum verification fails Regenerate checksums: ```bash just distro::create-checksums ``` ## Platform Support | Platform | Arch | Status | |----------|------|--------| | Linux (glibc) | x86_64 | ✓ Stable | | Linux (glibc) | ARM64 | ✓ Stable | | macOS | x86_64 | ✓ Stable | | macOS | ARM64 | ✓ Stable | | Windows | x86_64 | ✓ Stable | ## Performance Tips ### Faster builds ```bash # Use all CPU cores export CARGO_BUILD_JOBS=$(nproc) export CARGO_INCREMENTAL=1 # Then build just distro::build-release ``` ### Parallel testing ```bash cargo test -- --test-threads=4 ``` ## Compliance & SBOM Generation Generate Software Bill of Materials (SBOM) for supply chain transparency using [`cargo-sbom`](https://crates.io/crates/cargo-sbom). ### Regenerate SBOMs When dependencies change (new crates, version updates, Cargo.lock changes): ```bash just distro::generate-sbom ``` This regenerates: - **SBOM.spdx.json** - SPDX 2.3 standard format (ISO/IEC 5962:2021) - **SBOM.cyclonedx.json** - CycloneDX 1.4 format (ECMA standard) ### Audit Dependencies Check for known security vulnerabilities: ```bash just ci::audit ``` ### Verify SBOMs in CI Verify SBOMs are up-to-date during CI pipeline: ```bash just ci::verify-sbom ``` Included automatically in full CI run: ```bash just ci::full ``` ### SBOM Files **SBOM.spdx.json** (~350-400 KB) - SPDX 2.3 format (ISO/IEC 5962:2021) - Complete component inventory with unique identifiers - Compatible with SPDX validators, GitHub Dependabot, and osv-scanner - Generated by [cargo-sbom](https://crates.io/crates/cargo-sbom) **SBOM.cyclonedx.json** (~280-320 KB) - CycloneDX 1.4 format (ECMA standard) - Complete component inventory with Package URLs (pURL) - Compatible with vulnerability scanners and SCA tools (Dependabot, Snyk) - Generated by [cargo-sbom](https://crates.io/crates/cargo-sbom) ### Supply Chain Security All dependencies are: - Permissive or compatible licenses ✓ - Regularly audited for vulnerabilities ✓ - Tracked in version-controlled SBOMs ✓ - Included in releases ✓ --- ## Next Steps - [RELEASE.md](RELEASE.md) - Release workflow - [CONFIGURATION.md](CONFIGURATION.md) - Configuration options - [INSTALLATION.md](INSTALLATION.md) - User installation - [DEVELOPMENT.md](DEVELOPMENT.md) - Development setup --- **Build complete!** Ready for distribution.