flox-builds

# Flox Build System Guide

## Build System Overview

Flox supports two build modes, each with its own strengths:

**Manifest builds** enable you to define your build steps in your manifest and reuse your existing build scripts and toolchains. Flox manifests are declarative artifacts, expressed in TOML.

Manifest builds:
- Make it easy to get started, requiring few if any changes to your existing workflows
- Can run inside a sandbox (using `sandbox = "pure"`) for reproducible builds
- Are best for getting going fast with existing projects

**Nix expression builds** guarantee build-time reproducibility because they're both isolated and purely functional. Their learning curve is steeper because they require proficiency with the Nix language.

Nix expression builds:
- Are isolated by default. The Nix sandbox seals the build off from the host system, so no state leak ins
- Are functional. A Nix build is defined as a pure function of its declared inputs

You can mix both approaches in the same project, but package names must be unique.

## Core Commands

```bash
flox build                      # Build all targets
flox build app docs             # Build specific targets
flox build -d /path/to/project  # Build in another directory
flox build -v                   # Verbose output
flox build .#hello              # Build specific Nix expression
```

## Development vs Runtime: The Two-Environment Pattern

A common workflow involves **two separate environments**:

### Development Environment (Build-Time)
Contains source code, build tools, and build definitions:
```toml
# project-dev/.flox/env/manifest.toml (in git with source code)
[install]
gcc.pkg-path = "gcc13"
make.pkg-path = "make"
python.pkg-path = "python311Full"
uv.pkg-path = "uv"

[build.myapp]
command = '''
  make build
  mkdir -p $out/bin
  cp build/myapp $out/bin/
'''
version = "1.0.0"
```

**Workflow:**
```bash
cd project-dev
flox activate
flox build myapp
flox publish -o myorg myapp
```

### Runtime Environment (Co