Documentation

Introduction

Terrabuild is born from the frustration of using other monorepos build systems:

Some require strong involvement and require a dedicated team
Some have blurry relationship with apps
Some have impacts on dependencies and how to manage them

Terrabuild does not try to change your build tools. Terrabuild just leverages them to enforce consitent and fast build workflows. In fact, Terrabuild barely knows the projects but files and dependencies. It only cares about the build graph and if something shall be rebuilt or not.

Terrabuild is voluntary limited and aims at replicating DSC for infrastructure (Desired State Configuration) to build systems. This is why Terrabuild uses an HCL inspired syntax (disclaimer, it’s not pure HCL) to describe how the build shall be done and what to expect - threading cache and reuse capabilities within the graph.

ℹ️

Terrabuild is free and available at GitHub and can be used locally or in CI.

You will need an account Insights if you want to leverage caching capabilities.

Terrabuild as a build tool

Terrabuild is a build system designed for monorepos. It aims at being easier, far less intrusive than alternatives and without lock-in.

Terrabuild only builds what’s required thanks to heavy caching. It uses a familiar HCL inspired syntax (but not strict HCL) and puts a strong emphasis on using same tools for local development or CI/CD.

Terrabuild creates a graph (more specifically a DAG) based on the provided configurations and performs a miminal rebuild. Terrabuild also provide graph optimizations to make build faster so you can focus on features instead of plumbing.

In order to verify if something needs to be rebuilt, Terrabuild create a hash for each nodes of the graph (basically, that’s a Merkle tree) based on following informations:

project
target
commands, variables and containers used for a target
hash of project files
hash of project dependencies

Terrabuild checks the cache using the hash as the key:

if the key exists, build outputs are recovered and no build is required
otherwise target execution is triggered and dependents are built in turn

Check Quick Start for a basic workflow. You can also check Terrabuild Playground if you want to deep dive without further ado.

Terrabuild as a deployment tool

But it’s not only a build tool: it’s also a release tool. Terrabuild - through configurations - is able to manage both configurations (debug and release for example) and also target environments (development, integration, production…).

Deploying is a matter of creating the right deployment targets for chosen environment.

Caching and build optimizations

Terrabuild is able to leverage a build cache to avoid building project if nothing has changed. To use this feature, you will need to create an account on Insights and a space to hold your artifacts securely.

Features

familiar HCL inspired syntax - no YAML, no XML.
Minimal (re)build - Terrabuild computes what has changed, and triggers a build for only what has changed. If connected to Insights, cache is leveraged and build will be even faster.
Parallel execution - Terrabuild run tasks in parallel while respecting task dependencies.
Barely no changes required - Terrabuild uses standard tools to build your apps. Devs can continue to use the tools/IDE they love without replicating changes to the build system. No duplicated source of truth.
Extensible - Terrabuild is built with F#, extensions can be designed in F# as well to add new capabilities. Terrabuild promotes the usage of docker images to build apps and isolate your build environment. This also enforces reproductibility of your builds and configuration discrepancies.
Local reproducible builds - Local or CI builds are the same when isolation is enforced: adopt a workflow and build anywhere.