From 190f2cb54f50649ac5f0db1e78ec61358b30e2e2 Mon Sep 17 00:00:00 2001 From: David Freilich Date: Mon, 15 Feb 2021 15:24:27 +0200 Subject: [PATCH 1/8] Add initial builder spec Signed-off-by: David Freilich --- .gitignore | 1 + README.md | 1 + distribution.md | 3 + extensions/builder.md | 145 ++++++++++++++++++++++++++++++++++++++++++ platform.md | 2 + 5 files changed, 152 insertions(+) create mode 100644 extensions/builder.md diff --git a/.gitignore b/.gitignore index e43b0f98..af56f610 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ .DS_Store +.idea/ 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/distribution.md b/distribution.md index 2de8d99f..a224c3dd 100644 --- a/distribution.md +++ b/distribution.md @@ -69,3 +69,6 @@ Each stack ID MUST only be present once. For a given stack, the `mixins` list MUST enumerate mixins such that no included buildpacks are missing a mixin for the stack. Fewer stack entries as well as additional mixins for a stack entry MAY be specified. + +### Builders +Buildpacks may be distributed using builders, described in the [builder extension spec](extensions/builder.md). diff --git a/extensions/builder.md b/extensions/builder.md new file mode 100644 index 00000000..06043cd3 --- /dev/null +++ b/extensions/builder.md @@ -0,0 +1,145 @@ +# Builder + +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. + +## Table of Contents + +## Required File/Directories +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: +- `/cnb/buildpacks/...//` + +## Environment Variables/Labels +A builder's environment is the build-time environment of the stack, and as such, MUST fulfill all of the [build image specifications][build-image-specs]. + +The following variables MUST be set in the builder environment (through the image config's `Env` field): + +| Env Variable | Description +|-----------------|-------------------------------------- +| `WorkingDir` | The working directory where buildpacks should default (eg: `/workspace`) +| `CNB_APP_DIR` | Application directory of the build environment (eg: `/app`) +| `CNB_LAYERS_DIR` | The directory to create and store `layers` in the build environment (eg: `/layers`) +| `CNB_PLATFORM_DIR` | The directory to create and store platform focused files in the build environment (eg: `/platform`) + +The following variables MAY be set in the builder environment (through the image config's `Env` field): + +| Env Variable | Description +|-----------------|-------------------------------------- +| `SERVICE_BINDING_ROOT` | The directory where services are bound + +The following labels MUST be set in the builder environment (through the image config's `Labels` field): + +| Env Variable | Description +|-----------------|-------------------------------------- +| `io.buildpacks.builder.api` | The Builder API this builder implements (at this point, **0.1**) +| `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 (greater than `0.9.0`) +| `io.buildpacks.lifecycle.apis` | A JSON object representing the [lifecycle APIs](#iobuildpackslifecycleapis) the lifecycle stored in the builder supports + +### `io.buildpacks.builder.metadata` +The `io.buildpacks.builder.metadata` data should look like: +```json +{ + "description": "", + "stack": { + "runImage": { + "image": "", + "mirrors": [ + "" + ] + } + }, + "buildpacks": [ + { + "id": "", + "version": "", + "homepage": "http://geocities.com/top-bp" + } + ], + "createdBy": { + "name": "", + "version": "" + } +} +``` + +### `io.buildpacks.buildpack.order` +The `io.buildpacks.buildpack.order` data MUST look like: +```json +[ + { + "group": + [ + { + "id": "", + "version": "", + "optional": "" + } + ] + } +] +``` + +### `io.buildpacks.buildpack.layers` +The `io.buildpacks.buildpack.layers` data should look like: +```json +{ + "": { + "": { + "api": "", + "order": [ + { + "group": [ + { + "id": "", + "version": "" + } + ] + } + ], + "layerDiffID": "sha256:test.nested.sha256", + "homepage": "http://geocities.com/top-bp" + } + }, + "": { + "": { + "api": "", + "stacks": [ + { + "id": "", + "mixins": [""] + } + ], + "layerDiffID": "sha256:test.bp.one.sha256", + "homepage": "http://geocities.com/cool-bp" + } + } +} +``` + +### `io.buildpacks.lifecycle.apis` +The `io.buildpacks.lifecycle.apis` data should look like: +```json +{ + "buildpack": { + "deprecated": [""], + "supported": [""] + }, + "platform": { + "deprecated": [""], + "supported": [""] + } +} +``` + +[//]: <> (Links) +[build-image-specs]: https://github.com/buildpacks/spec/blob/main/platform.md#build-image +[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..bea3384c 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 Stack build image MAY be a [valid builder](extensions/builder.md) + ### Run Image The platform MUST ensure that: From 557b34f22337214fa0459737b5e080201dd920e2 Mon Sep 17 00:00:00 2001 From: David Freilich Date: Thu, 18 Feb 2021 11:32:16 +0200 Subject: [PATCH 2/8] Update for comments Signed-off-by: David Freilich --- .gitignore | 1 - distribution.md | 2 +- extensions/builder.md | 129 +++++++++++++++++++++++++++--------------- platform.md | 2 +- 4 files changed, 84 insertions(+), 50 deletions(-) diff --git a/.gitignore b/.gitignore index af56f610..e43b0f98 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1 @@ .DS_Store -.idea/ diff --git a/distribution.md b/distribution.md index a224c3dd..5f63c8e8 100644 --- a/distribution.md +++ b/distribution.md @@ -71,4 +71,4 @@ For a given stack, the `mixins` list MUST enumerate mixins such that no included Fewer stack entries as well as additional mixins for a stack entry MAY be specified. ### Builders -Buildpacks may be distributed using builders, described in the [builder extension spec](extensions/builder.md). +Buildpacks may be distributed using builders, as described in the [builder extension spec](extensions/builder.md). diff --git a/extensions/builder.md b/extensions/builder.md index 06043cd3..6f0aa138 100644 --- a/extensions/builder.md +++ b/extensions/builder.md @@ -1,10 +1,35 @@ -# Builder +# 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) + - [File/Directories](#filedirectories) + - [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. -## Table of Contents +### Builder API Version +This document specifies Builder API version `0.1`. -## Required File/Directories +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 + +### File/Directories 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] @@ -13,81 +38,90 @@ A builder MUST have the following directories/files: In addition, every buildpack blob contained on a builder MUST be stored at the following file path: - `/cnb/buildpacks/...//` -## Environment Variables/Labels -A builder's environment is the build-time environment of the stack, and as such, MUST fulfill all of the [build image specifications][build-image-specs]. +If the buildpack ID contains a `/`, it MUST be replaced with `_` in the directory name. + +All specified files and directories are 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 variables MUST be set in the builder environment (through the image config's `Env` field): +The following environment variables MUST be set on the builder: -| Env Variable | Description -|-----------------|-------------------------------------- -| `WorkingDir` | The working directory where buildpacks should default (eg: `/workspace`) -| `CNB_APP_DIR` | Application directory of the build environment (eg: `/app`) -| `CNB_LAYERS_DIR` | The directory to create and store `layers` in the build environment (eg: `/layers`) -| `CNB_PLATFORM_DIR` | The directory to create and store platform focused files in the build environment (eg: `/platform`) +| Env Variable | Description | +| ------------------ | --------------------------------------------------------------------------------------------------- | +| `CNB_APP_DIR` | Application directory of the build environment (eg: `/workspace`) | +| `CNB_LAYERS_DIR` | The directory to create and store `layers` in the build environment (eg: `/layers`) | +| `CNB_PLATFORM_DIR` | The directory to create and store platform focused files in the build environment (eg: `/platform`) | The following variables MAY be set in the builder environment (through the image config's `Env` field): -| Env Variable | Description -|-----------------|-------------------------------------- -| `SERVICE_BINDING_ROOT` | The directory where services are bound +| Env Variable | Description | +| ---------------------- | -------------------------------------- | +| `SERVICE_BINDING_ROOT` | The directory where services are bound | + +### Labels The following labels MUST be set in the builder environment (through the image config's `Labels` field): -| Env Variable | Description -|-----------------|-------------------------------------- -| `io.buildpacks.builder.api` | The Builder API this builder implements (at this point, **0.1**) -| `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 (greater than `0.9.0`) -| `io.buildpacks.lifecycle.apis` | A JSON object representing the [lifecycle APIs](#iobuildpackslifecycleapis) the lifecycle stored in the builder supports - -### `io.buildpacks.builder.metadata` -The `io.buildpacks.builder.metadata` data should look like: +| 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": "", + "description": "", "stack": { "runImage": { - "image": "", + "image": "", "mirrors": [ - "" + "" ] } }, "buildpacks": [ { - "id": "", + "id": "", "version": "", - "homepage": "http://geocities.com/top-bp" + "homepage": "" } ], "createdBy": { - "name": "", - "version": "" + "name": "", + "version": "" } } ``` -### `io.buildpacks.buildpack.order` -The `io.buildpacks.buildpack.order` data MUST look like: +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": "", + "id": "", "version": "", - "optional": "" + "optional": false } ] } ] ``` -### `io.buildpacks.buildpack.layers` -The `io.buildpacks.buildpack.layers` data should look like: +#### `io.buildpacks.buildpack.layers` (JSON) + ```json { "": { @@ -97,14 +131,14 @@ The `io.buildpacks.buildpack.layers` data should look like: { "group": [ { - "id": "", - "version": "" + "id": "", + "version": "" } ] } ], - "layerDiffID": "sha256:test.nested.sha256", - "homepage": "http://geocities.com/top-bp" + "layerDiffID": "", + "homepage": "" } }, "": { @@ -116,15 +150,15 @@ The `io.buildpacks.buildpack.layers` data should look like: "mixins": [""] } ], - "layerDiffID": "sha256:test.bp.one.sha256", - "homepage": "http://geocities.com/cool-bp" + "layerDiffID": "", + "homepage": "" } } } ``` -### `io.buildpacks.lifecycle.apis` -The `io.buildpacks.lifecycle.apis` data should look like: +#### `io.buildpacks.lifecycle.apis` (JSON) + ```json { "buildpack": { @@ -140,6 +174,7 @@ The `io.buildpacks.lifecycle.apis` data should look like: [//]: <> (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 bea3384c..8c6ede3a 100644 --- a/platform.md +++ b/platform.md @@ -179,7 +179,7 @@ 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 Stack build image MAY be a [valid builder](extensions/builder.md) +A [builder](extensions/builder.md) MUST be an extension of a build image. ### Run Image From 7c048c863ecba6e5bdbb80dcf413a912ec23cce0 Mon Sep 17 00:00:00 2001 From: David Freilich Date: Thu, 18 Feb 2021 11:36:51 +0200 Subject: [PATCH 3/8] Capitalize ID Signed-off-by: David Freilich --- extensions/builder.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extensions/builder.md b/extensions/builder.md index 6f0aa138..85d836d2 100644 --- a/extensions/builder.md +++ b/extensions/builder.md @@ -124,7 +124,7 @@ The `createdBy` metadata is meant to contain the name and version of the tool th ```json { - "": { + "": { "": { "api": "", "order": [ From dff4ee9c7fda1b7df51865f230ae5cb5ccf10a60 Mon Sep 17 00:00:00 2001 From: David Freilich Date: Fri, 9 Apr 2021 15:40:50 +0300 Subject: [PATCH 4/8] Incorporate suggestions Signed-off-by: David Freilich --- distribution.md | 3 --- extensions/builder.md | 28 ++++++++++++++-------------- 2 files changed, 14 insertions(+), 17 deletions(-) diff --git a/distribution.md b/distribution.md index 5f63c8e8..2de8d99f 100644 --- a/distribution.md +++ b/distribution.md @@ -69,6 +69,3 @@ Each stack ID MUST only be present once. For a given stack, the `mixins` list MUST enumerate mixins such that no included buildpacks are missing a mixin for the stack. Fewer stack entries as well as additional mixins for a stack entry MAY be specified. - -### Builders -Buildpacks may be distributed using builders, as described in the [builder extension spec](extensions/builder.md). diff --git a/extensions/builder.md b/extensions/builder.md index 85d836d2..204f7f41 100644 --- a/extensions/builder.md +++ b/extensions/builder.md @@ -31,12 +31,12 @@ Builder API versions: ### File/Directories 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]. +- `/order.toml` → As defined in the [platform specification][order-toml-spec] +- `/stack.toml` → As defined in the [platform specification][stack-toml-spec] +- `/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: -- `/cnb/buildpacks/...//` +- `/buildpacks/...//` If the buildpack ID contains a `/`, it MUST be replaced with `_` in the directory name. @@ -55,10 +55,10 @@ The following environment variables MUST be set on the builder: The following variables MAY be set in the builder environment (through the image config's `Env` field): -| Env Variable | Description | -| ---------------------- | -------------------------------------- | -| `SERVICE_BINDING_ROOT` | The directory where services are bound | - +| Env Variable | Description | Default | +| ---------------------- | -------------------------------------- | ---- | +| `SERVICE_BINDING_ROOT` | The directory where services are bound | - | +| `CNB_BUILDPACKS_DIR` | The directory where CNB required files are | `/cnb` | ### Labels The following labels MUST be set in the builder environment (through the image config's `Labels` field): @@ -81,9 +81,9 @@ The following labels MUST be set in the builder environment (through the image c "description": "", "stack": { "runImage": { - "image": "", + "image": "", "mirrors": [ - "" + "" ] } }, @@ -131,8 +131,8 @@ The `createdBy` metadata is meant to contain the name and version of the tool th { "group": [ { - "id": "", - "version": "" + "id": "", + "version": "" } ] } @@ -142,7 +142,7 @@ The `createdBy` metadata is meant to contain the name and version of the tool th } }, "": { - "": { + "": { "api": "", "stacks": [ { @@ -151,7 +151,7 @@ The `createdBy` metadata is meant to contain the name and version of the tool th } ], "layerDiffID": "", - "homepage": "" + "homepage": "" } } } From 35b895077cea1f49ec9d12682e5f8613244a25d6 Mon Sep 17 00:00:00 2001 From: David Freilich Date: Wed, 14 Apr 2021 19:51:02 +0300 Subject: [PATCH 5/8] Apply suggestions from code review Signed-off-by: David Freilich Co-authored-by: Natalie Arellano --- extensions/builder.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/extensions/builder.md b/extensions/builder.md index 204f7f41..233530bf 100644 --- a/extensions/builder.md +++ b/extensions/builder.md @@ -31,12 +31,12 @@ Builder API versions: ### File/Directories A builder MUST have the following directories/files: -- `/order.toml` → As defined in the [platform specification][order-toml-spec] -- `/stack.toml` → As defined in the [platform specification][stack-toml-spec] -- `/lifecycle/` → An implementation of the lifecycle, which contains the required lifecycle binaries for [building images][lifecycle-for-build]. +- `/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: -- `/buildpacks/...//` +- `///` If the buildpack ID contains a `/`, it MUST be replaced with `_` in the directory name. From 85542a2e86339b66c4ac372d313554eaeaa31f42 Mon Sep 17 00:00:00 2001 From: David Freilich Date: Wed, 14 Apr 2021 19:51:44 +0300 Subject: [PATCH 6/8] Apply suggestions from code review Signed-off-by: David Freilich Co-authored-by: Natalie Arellano --- extensions/builder.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extensions/builder.md b/extensions/builder.md index 233530bf..36483f88 100644 --- a/extensions/builder.md +++ b/extensions/builder.md @@ -58,7 +58,7 @@ The following variables MAY be set in the builder environment (through the image | Env Variable | Description | Default | | ---------------------- | -------------------------------------- | ---- | | `SERVICE_BINDING_ROOT` | The directory where services are bound | - | -| `CNB_BUILDPACKS_DIR` | The directory where CNB required files are | `/cnb` | +| `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): From 00e3a0b6d5c07deb97664173335ad3225d0c22e8 Mon Sep 17 00:00:00 2001 From: David Freilich Date: Tue, 4 May 2021 20:46:44 +0300 Subject: [PATCH 7/8] Change File/Directories to Filesystem Signed-off-by: David Freilich --- extensions/builder.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/extensions/builder.md b/extensions/builder.md index 36483f88..db0aab5f 100644 --- a/extensions/builder.md +++ b/extensions/builder.md @@ -9,7 +9,7 @@ A [platform][platform-spec] supporting the builder extension specification SHOUL ## Table of Contents - [General Requirements](#general-requirements) - [Builder API Version](#builder-api-version) - - [File/Directories](#filedirectories) + - [Filesystem](#filesystem) - [Environment Variables](#environment-variables) - [Labels](#labels) - [Data Format](#data-format) @@ -29,7 +29,7 @@ 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 -### File/Directories +### 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] From cabe24fe1fe0a0dcf3896f86a80e042fcc5c611e Mon Sep 17 00:00:00 2001 From: David Freilich Date: Tue, 18 May 2021 22:03:55 +0300 Subject: [PATCH 8/8] Add default to env var table Signed-off-by: David Freilich --- extensions/builder.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/extensions/builder.md b/extensions/builder.md index db0aab5f..bf279102 100644 --- a/extensions/builder.md +++ b/extensions/builder.md @@ -40,20 +40,20 @@ In addition, every buildpack blob contained on a builder MUST be stored at the f If the buildpack ID contains a `/`, it MUST be replaced with `_` in the directory name. -All specified files and directories are writeable by the build environment's User. +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: +The following environment variables MUST be set on the builder (through the image config's `Env` field): -| Env Variable | Description | -| ------------------ | --------------------------------------------------------------------------------------------------- | -| `CNB_APP_DIR` | Application directory of the build environment (eg: `/workspace`) | -| `CNB_LAYERS_DIR` | The directory to create and store `layers` in the build environment (eg: `/layers`) | -| `CNB_PLATFORM_DIR` | The directory to create and store platform focused files in the build environment (eg: `/platform`) | +| 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 in the builder environment (through the image config's `Env` field): +The following variables MAY be set on the builder (through the image config's `Env` field): | Env Variable | Description | Default | | ---------------------- | -------------------------------------- | ---- |