Buildpack API

This specification defines the interface between a buildpack and the environment that runs it. This API will be used by buildpack authors.

A buildpack must contain three files:

  • buildpack.toml
  • bin/detect
  • bin/build

The two files in bin/ must be executable. They can be shell scripts written in a language like Bash or they can be executables compiled from a language like Go.

bin/detect

Usage

bin/detect PLATFORM_DIR BUILD_PLAN

Summary

This entrypoint is used to determine if a buildpack should run against a given codebase. It will often check for the existence of a particular file or some configuration indicating what kind of application has been provided. It accepts two positional arguments:

  • PLATFORM_DIR - a directory containing platform provided configuration, such as environment variables.
  • BUILD_PLAN - a string containing the Build Plan.

In addition, the working directory is defined as the location of the codebase the buildpack will execute against.

The executable must return an exit code of 0 if the codebase can be serviced by this buildpack. If the exit code is 0, the script must print a human-readable name to stdout.

Example

This is a simple example of a buildpack that detects a Python application by checking for the presence of a requirements.txt file:

#!/bin/sh

if [ -f requirements.txt ]; then
  echo "Python Buildpack"
  exit 0
else
  exit 1
fi

bin/build

Usage

bin/build LAYERS_DIR PLATFORM_DIR BUILD_PLAN

This entrypoint transforms a codebase. It will often resolve dependencies, install binary packages, and compile code. It accepts three positional arguments:

  • LAYERS_DIR - a directory that may contain subdirectories representing each layer created by the buildpack in the final image or build cache.
  • PLATFORM_DIR - a directory containing platform provided configuration, such as environment variables.
  • BUILD_PLAN - a string containing the Build Plan.

In addition, the working directory is defined as the location of the codebase this buildpack will execute against.

All changes to the codebase in the working directory will be included in the final image, along with any launch layers created in the LAYERS_DIR.

Layers

Each directory created by the buildpack under the LAYERS_DIR can be used for any of the following purposes:

  • Launch - the directory will be included in the run image as a single layer
  • Cache - the directory will be included in the cache
  • Build - the directory will be accessible by subsequent buildpacks

A buildpack defines how a layer will by used by creating a <layer>.toml with a name matching the directory it describes in the LAYERS_DIR. For example, a buildpack might create a $LAYERS_DIR/python directory and a $LAYERS_DIR/python.toml with the following contents:

launch = true
cache = true
build = true

In this example, the python directory will be included in the run image, cached for future builds, and will be accessible to subsequent buildpacks.

Example

This is a simple example of a buildpack that runs Python’s pip package manager to resolve dependencies:

#!/bin/sh

LAYERS_DIR="$1"

PIP_LAYER="$LAYERS_DIR/pip"
mkdir -p "$PIP_LAYER/modules" "$PIP_LAYER/env"

pip install -r requirements.txt -t "$PIP_LAYER/modules" \
  --install-option="--install-scripts=$PIP_LAYER/bin" \
  --exists-action=w --disable-pip-version-check --no-cache-dir

echo "launch = true" > "$PIP_LAYER.toml"

buildpack.toml

A buildpack must contain a buildpack.toml file in its root directory. This descriptor file must contain a buildpack.id that is a globally unique identifier.

The buildpack.toml has an api value that indicates the implemented Buildpack API. The format should be <major>.<minor> or <major>, where <major> is equivalent to <major>.0. With a pre-stable Buildpack API version, in that <major> equals 0, minors must be equal. If <major> is greater than 0, <minor> must be less than or equal to Buildpack API <minor>. Major versions must always be equal. The current Buildpack API version is 0.2.

Example

api = "0.2"

[buildpack]
id = "example.com/python"
version = "1.0"

[[stacks]]
id = "io.buildpacks.stacks.bionic"

Further Reading

You can read the complete Buildpack API specification on Github.