TypeDialog/docs/BUILD.md

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:

# Debug build (default)
just distro::build-all

# Release build (optimized)
just distro::build-release

Output: Binaries in target/release/

# Check binaries
ls -la target/release/typedialog*

Build by Backend

Build specific backend only:

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:

just build::default

Cross-Compilation

Build for multiple platforms:

Using cargo-cross

Cross-compile to different targets:

# 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:

# 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

# 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

just distro::create-checksums

Output: SHA256SUMS file

Verify integrity:

sha256sum -c SHA256SUMS

Full Package Workflow

# 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

{
  "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 for details.

Build Scripts

All build automation uses bash scripts in scripts/:

build_all.sh

Build all workspace targets:

./scripts/build_all.sh [debug|release]

build_cross.sh

Cross-compile for multiple platforms:

./scripts/build_cross.sh [target]

create_distro.sh

Create distribution package:

./scripts/create_distro.sh [version]

package_release.sh

Prepare release with checksums and notes:

./scripts/package_release.sh [version]

Docker Build

Dockerfile.cross

Multi-platform Docker build:

# 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:

# 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

just distro::list-packages

Generate manifest

just distro::generate-manifest

Clean distribution

just distro::clean-distro

Troubleshooting

Build fails

Clear cache and rebuild:

cargo clean
just distro::build-release

Cross-compilation fails

Ensure Docker is running:

docker --version
docker run hello-world

Missing dependencies

Install required tools:

cargo install cross     # For cross-compilation
cargo install just      # For command orchestration

Checksum verification fails

Regenerate checksums:

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

# Use all CPU cores
export CARGO_BUILD_JOBS=$(nproc)
export CARGO_INCREMENTAL=1

# Then build
just distro::build-release

Parallel testing

cargo test -- --test-threads=4

Compliance & SBOM Generation

Generate Software Bill of Materials (SBOM) for supply chain transparency.

Regenerate SBOMs

When dependencies change (new crates, version updates, Cargo.lock changes):

just distro::generate-sbom

This regenerates:

• LICENSE.md - Dependency attribution and licenses
• SBOM.spdx.json - SPDX 2.3 standard format
• SBOM.cyclonedx.json - CycloneDX 1.4 format

Audit Dependencies

Check for known security vulnerabilities:

just ci::audit

Verify SBOMs in CI

Verify SBOMs are up-to-date during CI pipeline:

just ci::verify-sbom

Included automatically in full CI run:

just ci::full

SBOM Files

LICENSE.md (7.4 KB)

• Lists all dependencies with their licenses
• Organized by license type
• Compliance summary

SBOM.spdx.json (139 KB)

• SPDX 2.3 format (ISO/IEC 5962:2021)
• 287 components with unique identifiers
• Compatible with SPDX validators and GitHub Dependabot

SBOM.cyclonedx.json (90 KB)

• CycloneDX 1.4 format (modern standard)
• 286 components with package URLs
• Compatible with vulnerability scanners and SCA tools

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 workflow
• CONFIGURATION.md - Configuration options
• INSTALLATION.md - User installation
• DEVELOPMENT.md - Development setup

---

Build complete! Ready for distribution.