diff --git a/README.md b/README.md index 72b12665..cc60caae 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,7 @@ When the specification refers to a path in the context of an OCI layer tar (e.g. - [Bindings Extension Specification](extensions/bindings.md) - [Buildpack Registry Extension Specification](extensions/buildpack-registry.md) - [Project Descriptor Extension Specification](extensions/project-descriptor.md) +- [Builder Extension Specification](extensions/builder.md) ## API Versions diff --git a/extensions/builder.md b/extensions/builder.md new file mode 100644 index 00000000..bf279102 --- /dev/null +++ b/extensions/builder.md @@ -0,0 +1,180 @@ +# Builder Specification + +This document specified the artifact format for a builder. + +A builder is an OCI image that provides a distributable build environment. + +A [platform][platform-spec] supporting the builder extension specification SHOULD allow users to configure the build environment with a provided builder. + +## Table of Contents +- [General Requirements](#general-requirements) + - [Builder API Version](#builder-api-version) + - [Filesystem](#filesystem) + - [Environment Variables](#environment-variables) + - [Labels](#labels) +- [Data Format](#data-format) + - [Labels](#labels-1) + - [`io.buildpacks.builder.metadata` (JSON)](#iobuildpacksbuildermetadata-json) + - [`io.buildpacks.buildpack.order` (JSON)](#iobuildpacksbuildpackorder-json) + - [`io.buildpacks.buildpack.layers` (JSON)](#iobuildpacksbuildpacklayers-json) + - [`io.buildpacks.lifecycle.apis` (JSON)](#iobuildpackslifecycleapis-json) + +## General Requirements +A **builder** is an image that MUST contain an implementation of the lifecycle, and build-time environment, and MAY contain buildpacks. Platforms SHOULD use builders to ease the build process. + +### Builder API Version +This document specifies Builder API version `0.1`. + +Builder API versions: +- MUST be in form `.` or ``, where `` is equivalent to `.0` +- When `` is greater than `0` increments to `` SHALL exclusively indicate additive changes + +### Filesystem +A builder MUST have the following directories/files: +- `/cnb/order.toml` → As defined in the [platform specification][order-toml-spec] +- `/cnb/stack.toml` → As defined in the [platform specification][stack-toml-spec] +- `/cnb/lifecycle/` → An implementation of the lifecycle, which contains the required lifecycle binaries for [building images][lifecycle-for-build]. + +In addition, every buildpack blob contained on a builder MUST be stored at the following file path: +- `///` + +If the buildpack ID contains a `/`, it MUST be replaced with `_` in the directory name. + +The `CNB_APP_DIR` and `CNB_LAYERS_DIR` MUST be writeable by the build environment's User. + +### Environment Variables +A builder MUST be an extension of a build-image, and MUST retain all specified environment variables and labels set on the original build image, as specified in the [platform specifications][build-image-specs]. + +The following environment variables MUST be set on the builder (through the image config's `Env` field): + +| Env Variable | Description | Default | +| ------------------ | ----------------------------------------------------------------------------------| ---- | +| `CNB_APP_DIR` | Application directory of the build environment | `/workspace` | +| `CNB_LAYERS_DIR` | The directory to create and store `layers` in the build environment | `/layers` | +| `CNB_PLATFORM_DIR` | The directory to create and store platform focused files in the build environment | `/platform` | + +The following variables MAY be set on the builder (through the image config's `Env` field): + +| Env Variable | Description | Default | +| ---------------------- | -------------------------------------- | ---- | +| `SERVICE_BINDING_ROOT` | The directory where services are bound | - | +| `CNB_BUILDPACKS_DIR` | The directory where buildpacks are located | `/cnb/buildpacks` | + +### Labels +The following labels MUST be set in the builder environment (through the image config's `Labels` field): + +| Label | Description | +| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | +| `io.buildpacks.builder.api` | The [Builder API Version](#builder-api-version) this builder implements | +| `io.buildpacks.builder.metadata` | A JSON object representing [Builder Metadata](#iobuildpacksbuildermetadata) | +| `io.buildpacks.buildpack.order` | A JSON object representing the [order of the buildpacks stored on the builder](#iobuildpacksbuildpackorder) | +| `io.buildpacks.buildpack.layers` | A JSON object representing the [buildpack layers](#iobuildpacksbuildpacklayers) | +| `io.buildpacks.lifecycle.version` | A string, representing the version of the lifecycle stored in the builder | +| `io.buildpacks.lifecycle.apis` | A JSON object representing the [lifecycle APIs](#iobuildpackslifecycleapis) the lifecycle stored in the builder supports | + +## Data Format +### Labels +#### `io.buildpacks.builder.metadata` (JSON) + +```json +{ + "description": "", + "stack": { + "runImage": { + "image": "", + "mirrors": [ + "" + ] + } + }, + "buildpacks": [ + { + "id": "", + "version": "", + "homepage": "" + } + ], + "createdBy": { + "name": "", + "version": "" + } +} +``` + +The `createdBy` metadata is meant to contain the name and version of the tool that created the builder. + +#### `io.buildpacks.buildpack.order` (JSON) + +```json +[ + { + "group": + [ + { + "id": "", + "version": "", + "optional": false + } + ] + } +] +``` + +#### `io.buildpacks.buildpack.layers` (JSON) + +```json +{ + "": { + "": { + "api": "", + "order": [ + { + "group": [ + { + "id": "", + "version": "" + } + ] + } + ], + "layerDiffID": "", + "homepage": "" + } + }, + "": { + "": { + "api": "", + "stacks": [ + { + "id": "", + "mixins": [""] + } + ], + "layerDiffID": "", + "homepage": "" + } + } +} +``` + +#### `io.buildpacks.lifecycle.apis` (JSON) + +```json +{ + "buildpack": { + "deprecated": [""], + "supported": [""] + }, + "platform": { + "deprecated": [""], + "supported": [""] + } +} +``` + +[//]: <> (Links) +[build-image-specs]: https://github.com/buildpacks/spec/blob/main/platform.md#build-image +[platform-spec]: https://github.com/buildpacks/spec/blob/main/platform.md +[order-toml-spec]: https://github.com/buildpacks/spec/blob/main/platform.md#ordertoml-toml +[stack-toml-spec]: https://github.com/buildpacks/spec/blob/main/platform.md#stacktoml-toml +[lifecycle-for-build]: https://github.com/buildpacks/spec/blob/main/platform.md#build diff --git a/platform.md b/platform.md index 7482958c..8c6ede3a 100644 --- a/platform.md +++ b/platform.md @@ -179,6 +179,8 @@ The platform SHOULD ensure that: - The image config's `Label` field has the label `io.buildpacks.stack.description` set to the description of the stack. - The image config's `Label` field has the label `io.buildpacks.stack.metadata` set to additional metadata related to the stack. +A [builder](extensions/builder.md) MUST be an extension of a build image. + ### Run Image The platform MUST ensure that: