TypeDialog/docs/BUILD.md

<div align="center">
  <img src="../imgs/typedialog_logo_h_s.svg" alt="TypeDialog Logo" width="600" />
</div>

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