earthbuild

EarthBuild

This is a community fork of Earthly!

This community fork is endorsed and supported by earthly. We're actively working on migrating things like the website and the CI to community versions.

Contributions welcome!

If you're interested in understanding why the community fork is happening, this issue has a relevant discussion.

It's like Docker for builds

🔁 Repeatable Builds - Write builds once, and run them anywhere – on your laptop, remote, and in any CI.

❤️ Super Simple - Instantly recognizable syntax – like Dockerfile and Makefile had a baby.

🛠 Compatible with Every Language, Framework, and Build Tool - If it runs on Linux, it runs on EarthBuild.

🏘 Great for Monorepos and Polyrepos - Organize your build logic however makes the most sense for your project.

💨 Fast Builds - Build caching and parallel execution makes builds fast automatically.

♻️ Reuse, Don't Repeat - Never write the same code in multiple builds again.

🌎 EarthBuild is a versatile, approachable CI/CD framework that runs every pipeline inside containers, giving you repeatable builds that you write once and run anywhere. It has a super simple, instantly recognizable syntax that is easy to write and understand – like Dockerfile and Makefile had a baby. And it leverages and augments popular build tools instead of replacing them, so you don't have to rewrite all your builds no matter what languages you use.

Table of Contents

• Why use EarthBuild?
• Where Does EarthBuild Fit?
• How Does It Work?
• Installation
• Quick Start
• Features
• FAQ
• Contributing
• Licensing

Why Use EarthBuild?

🔁 Repeatable Builds

EarthBuild runs all builds in containers, making them self-contained, isolated, repeatable, and portable. This allows for faster iteration on build scripts and easier debugging when something goes wrong – no more git commit -m "try again". When you write a build, you know it will execute correctly no matter where it runs – your laptop, a colleague's laptop, or any CI. You don't have to configure language-specific tooling, install additional dependencies, or complicate your build scripts to ensure they are compatible with different OSs. EarthBuild gives you consistent, repeatable builds regardless of where they run.

❤️ Super Simple

EarthBuild's syntax is easy to write and understand. Most engineers can read an Earthfile instantly, without prior knowledge of EarthBuild. We combined some of the best ideas from Dockerfiles and Makefiles into one specification – like Dockerfile and Makefile had a baby.

🛠 Compatible with Every Language, Framework, and Build Tool

EarthBuild works with the compilers and build tools you use. If it runs on Linux, it runs on EarthBuild. And you don't have to rewrite your existing builds or replace your package.json, go.mod, build.gradle, or Cargo.toml files. You can use EarthBuild as a wrapper around your existing tooling and still get EarthBuild's repeatable builds, parallel execution, and build caching.

🏘 Great for Monorepos and Polyrepos

EarthBuild is great for both monorepos and polyrepos. You can split your build logic across multiple Earthfiles, placing some deeper inside the directory structure or even in other repositories. Referencing targets from other Earthfiles is easy regardless of where they are stored. So you can organize your build logic however makes the most sense for your project.

💨 Fast Builds

EarthBuild automatically executes build targets in parallel and makes maximum use of cache. This makes builds fast. EarthBuild also has powerful shared caching capabilities that speed up builds frequently run across a team or in sandboxed environments, such as remote BuildKits, GitHub Actions, or your CI.

If your build has multiple steps, EarthBuild will:

1. Build a directed acyclic graph (DAG).
2. Isolate execution of each step.
3. Run independent steps in parallel.
4. Cache results for future use.

♻️ Reuse, Don't Repeat

Never have to write the same code in multiple builds again. With EarthBuild, you can reuse targets, artifacts, and images across multiple Earthfiles, even ones in other repositories, in a single line. EarthBuild is cache-aware, based on the individual hashes of each file, and has shared caching capabilities. So you can create a vast and efficient build hierarchy that only executes the minimum required steps.

Where Does EarthBuild Fit?

EarthBuild is meant to be used both on your development machine and in CI. It runs on top of your CI/CD platform (such as Jenkins, Circle CI, GitHub Actions, and GitLab CI/CD). EarthBuild provides the benefits of a modern build automation system wherever it runs – such as caching and parallelism. It is a glue layer between language-specific build tooling (like maven, gradle, npm, pip, go build) and CI, working like a wrapper around your build tooling and build logic that isolates build execution from the environments they run in.

How Does It Work?

In short: containers, layer caching, and complex build graphs!

EarthBuild executes builds in containers, where execution is isolated. The dependencies of the build are explicitly specified in the build definition, thus making the build self-sufficient.

We use a target-based system to help users break up complex builds into reusable parts. Nothing is shared between targets other than clearly declared dependencies. Nothing shared means no unexpected race conditions. In fact, the build is executed in parallel whenever possible, without any need for the user to take care of any locking or unexpected environment interactions.

ℹ️ Note Earthfiles might seem very similar to Dockerfile multi-stage builds. In fact, the same technology is used underneath. However, a key difference is that EarthBuild is designed to be a general-purpose build system, not just a Docker image specification. Read more about how EarthBuild is different from Dockerfiles.

Installation

See installation instructions.

To build from source, check the contributing page.

Quick Start

Here are some resources to get you started with EarthBuild

• 🏁 Getting started guide
• 👀 Examples
• Go
• JavaScript
• Python
• Java
• Rust
• TypeScript (Node)
• C++
• C
• dotnet (C#)
• Ruby
• Scala
• Elixir
• COBOL
• Monorepo
• Multirepo
• Multiplatform Builds
• Integration Tests
• 🔍 Explore EarthBuild's own build
• ✔️ Best practices

See also the full documentation.

Reference pages

• 📑 Earthfile reference
• #️⃣ EarthBuild command reference
• ⚙️ Configuration reference

A simple example (for Go)

# Earthfile
VERSION 0.8
FROM golang:1.15-alpine3.13
RUN apk --no-cache add git
WORKDIR /go-example

all:
  BUILD +lint
  BUILD +docker

build:
  COPY main.go .
  RUN go build -o build/go-example main.go
  SAVE ARTIFACT build/go-example AS LOCAL build/go-example

lint:
  RUN go get golang.org/x/lint/golint
  COPY main.go .
  RUN golint -set_exit_status ./...

docker:
  COPY +build/go-example .
  ENTRYPOINT ["/go-example/go-example"]
  SAVE IMAGE go-example:latest

// main.go
package main

import "fmt"

func main() {
  fmt.Println("hello world")
}

Invoke the build using earth +all.

Examples for other languages are available in the examples dir.

Features

⛓ Parallelization that just works

Whenever possible, EarthBuild automatically executes targets in parallel.

💾 Caching that works the same as Docker builds

🛠 Multi-platform support

Build for multiple platforms in parallel.

VERSION 0.8
all:
    BUILD \
        --platform=linux/amd64 \
        --platform=linux/arm64 \
        --platform=linux/arm/v7 \
        --platform=linux/arm/v6 \
        +build

build:
    FROM alpine:3.18
    CMD ["uname", "-m"]
    SAVE IMAGE multiplatform-image

🤲 Build tools that work everywhere

No need to ask your team to install protoc, a specific version of Python, Java 1.6, or the .NET Core ecosystem. Install once in your Earthfile, and it works for everyone. Or even better, you can just make use of the rich Docker Hub ecosystem.

VERSION 0.8
FROM golang:1.15-alpine3.13
WORKDIR /proto-example

proto:
  FROM namely/protoc-all:1.29_4
  COPY api.proto /defs
  RUN --entrypoint -- -f api.proto -l go
  SAVE ARTIFACT ./gen/pb-go /pb AS LOCAL pb

build:
  COPY go.mod go.sum .
  RUN go mod download
  COPY +proto/pb pb
  COPY main.go ./
  RUN go build -o build/proto-example main.go
  SAVE ARTIFACT build/proto-example

See full example code.

📦 Modern import system

EarthBuild can be used to reference and build targets from other directories or even other repositories. For example, if we wanted to build an example target from a repository, we could issue

# Try it yourself! No need to clone.
earthbuild github.com/earthbuild/earthbuild/examples/go:main+docker
# Run the resulting image.
docker run --rm earthbuild/examples:go

🔨 Reference other targets using +

Use + to reference other targets and create complex build inter-dependencies.

Examples

• Same directory (same Earthfile)

  BUILD +some-target
  FROM +some-target
  COPY +some-target/my-artifact ./
  

• Other directories

  BUILD ./some/local/path+some-target
  FROM ./some/local/path+some-target
  COPY ./some/local/path+some-target/my-artifact ./
  

• Other repositories

  BUILD github.com/someone/someproject:v1.2.3+some-target
  FROM github.com/someone/someproject:v1.2.3+some-target
  COPY github.com/someone/someproject:v1.2.3+some-target/my-artifact ./
  

🔑 Secrets support built-in

Secrets are never stored within an image's layers and they are only available to the commands that need them.

earth set /user/github/token 'shhh...'

release:
  RUN --push --secret GITHUB_TOKEN=user/github/token github-release upload file.bin

FAQ

How is EarthBuild different from Dockerfiles?

Dockerfiles were designed for specifying the make-up of Docker images and that's where Dockerfiles stop. EarthBuild takes some key principles of Dockerfiles (like layer caching) but expands on the use cases. For example, EarthBuild can output regular artifacts, run unit and integration tests, and create several Docker images at a time - all outside the scope of Dockerfiles.

It is possible to use Dockerfiles in combination with other technologies (e.g., Makefiles or bash files) to solve such use cases. However, these combinations are difficult to parallelize, challenging to scale across repositories as they lack a robust import system, and often vary in style from one team to another. EarthBuild does not have these limitations as it was designed as a general-purpose build system.

For example, EarthBuild introduces a richer target, artifact, and image referencing system, allowing for better reuse in complex builds spanning a single large repository or multiple repositories. Because Dockerfiles are only meant to describe one image at a time, such features are outside the scope of applicability of Dockerfiles.

How do I know if a command is a classic Dockerfile command or an EarthBuild command?

Check out the Earthfile reference doc page. It has all the commands there and specifies which commands are the same as Dockerfile commands and which are new.

Can EarthBuild build Dockerfiles?

Yes! You can use the command FROM DOCKERFILE to inherit the commands in an existing Dockerfile.

build:
  FROM DOCKERFILE .
  SAVE IMAGE some-image:latest

You may also optionally port your Dockerfiles to EarthBuild entirely. Translating Dockerfiles to Earthfiles is usually a matter of copy-pasting and making minor adjustments. See the getting started page for some Earthfile examples.

How is EarthBuild different from Bazel?

Bazel is a build tool developed by Google to optimize the speed, correctness, and reproducibility of their internal monorepo codebase. The main difference between Bazel and EarthBuild is that Bazel is a build system, whereas EarthBuild is a general-purpose CI/CD framework. For a more in-depth explanation see our FAQ.

Contributing

• Please report bugs as GitHub issues.
• Join us on Slack!
• Questions via GitHub issues are welcome!
• PRs welcome! But please give a heads-up in a GitHub issue before starting work. If there is no GitHub issue for what you want to do, please create one.
• To build from source, check the contributing page.

Licensing

EarthBuild is licensed under the Mozilla Public License Version 2.0. See LICENSE.