Bake is a containerized build system. You define tasks and their dependencies in a bakefile, and Bake runs them in a Dockerized environment based on an image of your choosing. Bake supports local and remote caching to avoid repeating work.
Running tasks in containers helps with reproducibility. If a Bake task works on your machine, it'll work on your teammate's machine too. You don't have to worry about ensuring everyone has the same versions of all the tools and dependencies.
Here are some reasons to use Bake on top of vanilla Docker:
Bake has no knowledge of specific programming languages or frameworks. You might use Bake with another build system like Bazel or Buck to perform language-specific build tasks.
Let's create a simple bakefile. Create a file named bake.yml with the following contents:
yaml
image: ubuntu
tasks:
greet: echo 'Hello, World!'
Now run bake. You should see something like the following:
sh
$ bake
[INFO] The following tasks will be executed in the order given: `greet`.
[INFO] Pulling image `ubuntu`...
<...>
[INFO] Running task `greet`...
[INFO] echo 'Hello, World!'
Hello, World!
[INFO] Successfully executed 1 task.
Let's make the greeting more fun with a program called cowsay. We'll add a task to install cowsay, and we'll change the greet task to depend on it:
yaml
image: ubuntu
tasks:
cowsay: |
apt-get update
apt-get install --yes cowsay
greet:
dependencies:
- cowsay
command: /usr/games/cowsay 'Hello, World!'
Run bake again and you will see:
``sh
[INFO] The following tasks will be executed in the order given:cowsayandgreet.
[INFO] Running taskcowsay...
[INFO] apt-get update
apt-get install -y cowsay
<...>
[INFO] Running taskgreet`...
[INFO] /usr/games/cowsay 'Hello, World!'
< Hello, World! >
\ ^__^
\ (oo)\_______
(__)\ )\/\
||----w |
|| ||
[INFO] Successfully executed 2 tasks. ```
Now that's better!
Here's a more realistic example. Suppose you want to compile and run a simple C program. Create a file called main.c:
```c
int main(void) { printf("Hello, World!\n"); } ```
Update bake.yml to compile and run the program:
yaml
image: ubuntu
tasks:
gcc: |
apt-get update
apt-get install -y gcc
build:
dependencies:
- gcc
paths:
- main.c
command: gcc main.c
run:
dependencies:
- build
command: ./a.out
Notice the paths array in the build task. Here we are copying a single file into the container, but we could instead copy the entire working directory with .. By default, the files will be copied into a directory called /scratch in the container. The commands will be run in that directory as well.
Now if you run bake, you'll see this:
sh
$ bake
[INFO] The following tasks will be executed in the order given: `gcc`, `build`, and `run`.
[INFO] Running task `gcc`...
[INFO] apt-get update
apt-get install -y gcc
<...>
[INFO] Running task `build`...
[INFO] gcc main.c
[INFO] Running task `run`...
[INFO] ./a.out
Hello, World!
[INFO] Successfully executed 3 tasks.
Given a set of tasks to run, Bake computes a topological sort of the dependency DAG to determine in what order to run the tasks. Because Docker does not support combining two images into one, Bake does not run tasks in parallel and must instead determine a sequential execution schedule. You are free to use parallelism within individual tasks, of course.
The topological sort of an arbitrary DAG is not necessarily unique. Bake uses depth-first search, traversing children in lexicographical order. This algorithm is deterministic and invariant to the order in which tasks and dependencies are listed, so reordering will not invalidate the cache. Furthermore, bake foo bar and bake bar foo are guaranteed to produce identical schedules.
Bake builds a Docker image for each task and uses it for the next task in the schedule. Each image is tagged with a cache key that incorporates the shell command, the contents of the files copied into the container, and other inputs. If local caching is enabled, these Docker images remain on disk for subsequent executions. If remote caching is enabled, the images will be synchronized with a remote Docker registry.
If a task is marked as non-cacheable, the Docker images for that task and any subsequent tasks in the schedule will not be persisted or uploaded.
A bakefile is a YAML file (typically named bake.yml) that defines tasks and their dependencies. The schema contains three top-level keys:
yaml
image: <Docker image name>
default: <name of default task to run (default behavior: run all tasks)>
tasks: <map from task name to task>
Tasks have the following schema and defaults:
yaml
dependencies: [] # Names of dependencies
cache: true # Whether a task can be cached
environment: {} # Map from environment variable to optional default
paths: [] # Paths to copy into the container
location: /scratch # Path in the container for running this task
user: root # Name of the user in the container for running this task
command: null # Shell command to run in the container
For convenience, a task can be a string rather than an object. The resulting task uses that string as its command, with the other fields set to their defaults. So the following two bakefiles are equivalent:
yaml
image: alpine
tasks:
greet: echo 'Hello, World!'
yaml
image: alpine
tasks:
greet:
command: echo 'Hello, World!'
The bakefile for Bake itself is a comprehensive real-world example.
Bake supports local and remote caching. By default, only local caching is enabled. Remote caching requires that the Docker Engine is logged into a Docker registry (e.g., via docker login).
The caching behavior can be customized with a configuration file. The default location of the configuration file depends on the operating system:
~/Library/Preferences/bake/bake.yml.~/.config/bake/bake.yml unless overridden by the XDG_CONFIG_HOME environment variable.The configuration file has the following schema and defaults:
yaml
docker_repo: bake # Docker repository
read_local_cache: true # Whether Bake should read from local cache
write_local_cache: true # Whether Bake should write to local cache
read_remote_cache: false # Whether Bake should read from remote cache
write_remote_cache: false # Whether Bake should write to remote cache
A typical configuration for a continuous integration (CI) environment will enable all forms of caching, whereas for local development you may want to set write_remote_cache: false to avoid waiting for remote cache writes.
Each of these options can be overridden via command-line options (see below).
Run bake with no arguments to execute the default task, or all the tasks if the bakefile doesn't define a default. You can also execute specific tasks and their dependencies:
sh
bake task1 task2 task3...
Here are all the supported command-line options:
```sh USAGE: bake [OPTIONS] [TASKS]...
OPTIONS:
-c, --config-file
-f, --file <PATH>
Sets the path to the bakefile
-h, --help
Prints help information
--read-local-cache <BOOL>
Sets whether local cache reading is enabled
--read-remote-cache <BOOL>
Sets whether remote cache reading is enabled
-r, --repo <REPO>
Sets the Docker repository
-s, --shell
Drops you into a shell after the tasks are complete
-v, --version
Prints version information
--write-local-cache <BOOL>
Sets whether local cache writing is enabled
--write-remote-cache <BOOL>
Sets whether remote cache writing is enabled
```
If you are running macOS or a GNU-based Linux on an x86-64 CPU, you can install Bake with this command:
sh
curl https://raw.githubusercontent.com/stepchowfun/bake/master/install.sh -LSfs | sh
The same command can be used to update Bake to the latest version.
The installation script supports the following environment variables:
VERSION=x.y.z (defaults to the latest version)PREFIX=/path/to/install (defaults to /usr/local/bin)For example, the following will install Bake into the current directory:
sh
curl https://raw.githubusercontent.com/stepchowfun/bake/master/install.sh -LSfs | PREFIX=. sh
The inspiration for Bake came from a similar tool used at Airbnb for CI jobs.