# forge

Client / Employer: Open Source / Personal | Category: Personal Project | Year: 2026 | Status: Active

Declarative, TOML-driven build orchestrator — one forge.toml describes any program's setup and `forge build` executes it with topological dependency ordering and parallel steps.

Tags: Go, Build Orchestration, Automation

## Overview

forge is a declarative, TOML-driven build orchestrator written in Go. One forge.toml describes any program's setup — apt packages, source fetch and compile, prebuilt binaries, shell commands, and verification — as a list of components, each carrying an ordered list of operations. `forge build` executes it with topological dependency ordering and parallel steps.

## The Problem

Container projects conventionally rely on a setup.sh plus a tree of numbered shell scripts to install and configure software. That pattern is fragile, hard to reason about, and impossible to validate before running. Each script hand-rolls apt installs, source compilation, file placement, and verification with no structure, no dependency ordering, and no way to know whether the environment is ready until something fails at runtime.

## The Solution

forge replaces that with a single declarative manifest. A forge.toml lists components, each with an ordered ops list where the order of the ops is the build lifecycle. Operations cover apt package management (split into build and runtime with structured version conditions), source fetch and compile across multiple build strategies, prebuilt binary install, user creation, file and directory operations, code generation, verification, and raw shell as a last resort. `forge build` resolves the dependency graph, runs independent steps in parallel, and caches results with artifact restore so rebuilds are fast and deterministic. A validate command checks a manifest without executing it.

## Key Outcomes

- **Declarative Manifests:** One forge.toml describes any program's setup as components with ordered operation lists — no numbered shell scripts.
- **Topological Ordering:** Resolves the dependency graph and runs independent steps in parallel for fast, deterministic builds.
- **Polymorphic Install:** Handles apt packages, source fetch and compile, and prebuilt binaries through a single install operation.
- **Structured Conditions:** Apt packages split into build and runtime with structured version conditions instead of shell string hacks.
- **Build Cache:** Automatic caching with artifact restore — a hit is trusted only if the step's outputs still exist.
- **Validation First:** A validate command checks a manifest without executing it, catching errors before they reach the build.

## Project Summary

forge is a declarative, TOML-driven build orchestrator in Go. One forge.toml describes any program's setup as components with ordered operations, and `forge build` executes it with topological dependency ordering and parallel steps — replacing the setup.sh plus numbered-shell-script pattern. Available at github.com/supanadit/forge.

## Key Features

- Go Language
- TOML-Driven Build Orchestration
- Declarative Components
- Ordered Operation Lists
- Topological Dependency Ordering
- Parallel Build Steps
- Apt Package Management
- Source Fetch & Compile
- Prebuilt Binary Install
- Structured Version Conditions
- Build Cache with Artifact Restore
- Dry-Run Execution Planning
- Manifest Validation
- Clean Architecture

## Link

https://github.com/supanadit/forge