Skip to content

Commit

Permalink
Merge pull request #302 from buildpacks/buildpack/0.8
Browse files Browse the repository at this point in the history 
Finalize Buildpack API 0.8
  • Loading branch information
@hone
hone committed Apr 6, 2022
2 parents edac0f7 + 33e6b7f commit 1153938
Show file tree
Hide file tree
Showing 2 changed files with 135 additions and 69 deletions.
2 changes: 1 addition & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,6 @@ When the specification refers to a path in the context of an OCI layer tar (e.g.

These documents currently specify:

- Buildpack API: `0.7`
- Buildpack API: `0.8`
- Distribution API: `0.3`
- Platform API: `0.9`
202 changes: 134 additions & 68 deletions buildpack.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,6 @@ The `ENTRYPOINT` of the OCI image contains logic implemented by the lifecycle th
- [Process](#process-4)
- [Environment](#environment)
- [Provided by the Lifecycle](#provided-by-the-lifecycle)
- [Buildpack Specific Variables](#buildpack-specific-variables)
- [Layer Paths](#layer-paths)
- [Provided by the Platform](#provided-by-the-platform)
- [Provided by the Buildpacks](#provided-by-the-buildpacks)
Expand Down Expand Up @@ -84,7 +83,7 @@ The `ENTRYPOINT` of the OCI image contains logic implemented by the lifecycle th
- [Build Plan (TOML) `requires.version` Key](#build-plan-toml-requiresversion-key)

## Buildpack API Version
This document specifies Buildpack API version `0.7`
This document specifies Buildpack API version `0.8`

Buildpack API versions:
- MUST be in form `<major>.<minor>` or `<major>`, where `<major>` is equivalent to `<major>.0`
Expand Down Expand Up @@ -117,58 +116,64 @@ The lifecycle MAY return an error to the platform if two or more buildpacks with

### Detection

Executable: `/bin/detect <platform[AR]> <plan[E]>`, Working Dir: `<app[AR]>`
Executable: `/bin/detect`, Working Dir: `<app[AR]>`

| Input | Description
|-------------------|----------------------------------------------
| `$0` | Absolute path of `/bin/detect` executable
| `<platform>/env/` | User-provided environment variables for build
| `<platform>/#` | Platform-specific extensions
| Input | Attributes | Description |
|--------------------------|------------|-----------------------------------------------|
| `$0` | | Absolute path of `/bin/detect` executable |
| `$CNB_BUILD_PLAN_PATH` | E | Absolute path of the build plan |
| `$CNB_BUILDPACK_DIR` | ER | Absolute path of the buildpack root directory |
| `$CNB_PLATFORM_DIR` | AR | Absolute path of the platform directory |
| `$CNB_PLATFORM_DIR/env/` | AR | User-provided environment variables for build |
| `$CNB_PLATFORM_DIR/#` | AR | Platform-specific extensions |

| Output | Description
|--------------------|----------------------------------------------
| [exit status] | Pass (0), fail (100), or error (1-99, 101+)
| Standard output | Logs (info)
| Standard error | Logs (warnings, errors)
| `<plan>` | Contributions to the the Build Plan (TOML)
| Output | Description |
|------------------------|---------------------------------------------|
| [exit status] | Pass (0), fail (100), or error (1-99, 101+) |
| Standard output | Logs (info) |
| Standard error | Logs (warnings, errors) |
| `$CNB_BUILD_PLAN_PATH` | Contributions to the the Build Plan (TOML) |


### Build

Executable: `/bin/build <layers[EIC]> <platform[AR]> <plan[ER]>`, Working Dir: `<app[AI]>`

| Input | Description
|-------------------|----------------------------------------------
| `$0` | Absolute path of `/bin/build` executable
| `<plan>` | Relevant [Buildpack Plan entries](#buildpack-plan-toml) from detection (TOML)
| `<platform>/env/` | User-provided environment variables for build
| `<platform>/#` | Platform-specific extensions

| Output | Description
|------------------------------------------|--------------------------------------
| [exit status] | Success (0) or failure (1+)
| Standard output | Logs (info)
| Standard error | Logs (warnings, errors)
| `<layers>/launch.toml` | App metadata (see [launch.toml](#launchtoml-toml))
| `<layers>/launch.sbom.<ext>` | Launch Software Bill of Materials (see [Software-Bill-of-Materials](#bill-of-materials))
| `<layers>/build.toml` | Build metadata (see [build.toml](#buildtoml-toml))
| `<layers>/build.sbom.<ext>` | Build Software Bill of Materials (see [Software-Bill-of-Materials](#bill-of-materials))
| `<layers>/store.toml` | Persistent metadata (see [store.toml](#storetoml-toml))
| `<layers>/<layer>.toml` | Layer metadata (see [Layer Content Metadata](#layer-content-metadata-toml))
| `<layers>/<layer>.sbom.<ext>` | Layer Software Bill of Materials (see [Software-Bill-of-Materials](#bill-of-materials))
| `<layers>/<layer>/bin/` | Binaries for launch and/or subsequent buildpacks
| `<layers>/<layer>/lib/` | Shared libraries for launch and/or subsequent buildpacks
| `<layers>/<layer>/profile.d/` | Scripts sourced by Bash before launch
| `<layers>/<layer>/profile.d/<process>/` | Scripts sourced by Bash before launch for a particular process type
| `<layers>/<layer>/exec.d/` | Executables that provide env vars via the [Exec.d Interface](#execd) before launch
| `<layers>/<layer>/exec.d/<process>/` | Executables that provide env vars for a particular process type via the [Exec.d Interface](#execd) before launch
| `<layers>/<layer>/include/` | C/C++ headers for subsequent buildpacks
| `<layers>/<layer>/pkgconfig/` | Search path for pkg-config for subsequent buildpacks
| `<layers>/<layer>/env/` | Env vars for launch and/or subsequent buildpacks
| `<layers>/<layer>/env.launch/` | Env vars for launch (after `env`, before `profile.d`)
| `<layers>/<layer>/env.launch/<process>/` | Env vars for launch (after `env`, before `profile.d`) for the launched process
| `<layers>/<layer>/env.build/` | Env vars for subsequent buildpacks (after `env`)
| `<layers>/<layer>/*` | Other content for launch and/or subsequent buildpacks
Executable: `/bin/build`, Working Dir: `<app[AI]>`

| Input | Attributes | Description |
|--------------------------|------------|-------------------------------------------------------------------------------|
| `$0` | | Absolute path of `/bin/build` executable |
| `$CNB_LAYERS_DIR` | EIC | Absolute path of the buildpack layers directory |
| `$CNB_BP_PLAN_PATH` | ER | Relevant [Buildpack Plan entries](#buildpack-plan-toml) from detection (TOML) |
| `$CNB_BUILDPACK_DIR` | ER | Absolute path of the buildpack root directory |
| `$CNB_PLATFORM_DIR` | AR | Absolute path of the platform directory |
| `$CNB_PLATFORM_DIR/env/` | AR | User-provided environment variables for build |
| `$CNB_PLATFORM_DIR/#` | AR | Platform-specific extensions |

| Output | Description |
|-------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
| [exit status] | Success (0) or failure (1+) |
| Standard output | Logs (info) |
| Standard error | Logs (warnings, errors) |
| `$CNB_LAYERS_DIR/launch.toml` | App metadata (see [launch.toml](#launchtoml-toml)) |
| `$CNB_LAYERS_DIR/launch.sbom.<ext>` | Launch Software Bill of Materials (see [Software-Bill-of-Materials](#software-bill-of-materials)) |
| `$CNB_LAYERS_DIR/build.toml` | Build metadata (see [build.toml](#buildtoml-toml)) |
| `$CNB_LAYERS_DIR/build.sbom.<ext>` | Build Software Bill of Materials (see [Software-Bill-of-Materials](#software-bill-of-materials)) |
| `$CNB_LAYERS_DIR/store.toml` | Persistent metadata (see [store.toml](#storetoml-toml)) |
| `$CNB_LAYERS_DIR/<layer>.toml` | Layer metadata (see [Layer Content Metadata](#layer-content-metadata-toml)) |
| `$CNB_LAYERS_DIR/<layer>.sbom.<ext>` | Layer Software Bill of Materials (see [Software-Bill-of-Materials](#software-bill-of-materials)) |
| `$CNB_LAYERS_DIR/<layer>/bin/` | Binaries for launch and/or subsequent buildpacks |
| `$CNB_LAYERS_DIR/<layer>/lib/` | Shared libraries for launch and/or subsequent buildpacks |
| `$CNB_LAYERS_DIR/<layer>/profile.d/` | Scripts sourced by Bash before launch |
| `$CNB_LAYERS_DIR/<layer>/profile.d/<process>/` | Scripts sourced by Bash before launch for a particular process type |
| `$CNB_LAYERS_DIR/<layer>/exec.d/` | Executables that provide env vars via the [Exec.d Interface](#execd) before launch |
| `$CNB_LAYERS_DIR/<layer>/exec.d/<process>/` | Executables that provide env vars for a particular process type via the [Exec.d Interface](#execd) before launch |
| `$CNB_LAYERS_DIR/<layer>/include/` | C/C++ headers for subsequent buildpacks |
| `$CNB_LAYERS_DIR/<layer>/pkgconfig/` | Search path for pkg-config for subsequent buildpacks |
| `$CNB_LAYERS_DIR/<layer>/env/` | Env vars for launch and/or subsequent buildpacks |
| `$CNB_LAYERS_DIR/<layer>/env.launch/` | Env vars for launch (after `env`, before `profile.d`) |
| `$CNB_LAYERS_DIR/<layer>/env.launch/<process>/` | Env vars for launch (after `env`, before `profile.d`) for the launched process |
| `$CNB_LAYERS_DIR/<layer>/env.build/` | Env vars for subsequent buildpacks (after `env`) |
| `$CNB_LAYERS_DIR/<layer>/*` | Other content for launch and/or subsequent buildpacks |

### Exec.d

Expand Down Expand Up @@ -704,17 +709,17 @@ Given the start command and execution strategy,

1. The lifecycle MUST set all buildpack-provided launch environment variables as described in the [Environment](#environment) section.

2. The lifecycle MUST
1. [execute](#execd) each file in each `<layers>/<layer>/exec.d` directory in the launch environment and set the [returned variables](#execd-output-toml) in the launch environment before continuing,
1. The lifecycle MUST
1. [execute](#execd) each file in each `<layers>/<layer>/exec.d` directory in the launch environment, with working directory `<app>`, and set the [returned variables](#execd-output-toml) in the launch environment before continuing,
1. Firstly, in order of `/bin/build` execution used to construct the OCI image.
2. Secondly, in alphabetically ascending order by layer directory name.
3. Thirdly, in alphabetically ascending order by file name.
2. [execute](#execd) each file in each `<layers>/<layer>/exec.d/<process>` directory in the launch environment and set the [returned variables](#execd-output-toml) in the launch environment before continuing,
2. [execute](#execd) each file in each `<layers>/<layer>/exec.d/<process>` directory in the launch environment, with working directory `<app>`, and set the [returned variables](#execd-output-toml) in the launch environment before continuing,
1. Firstly, in order of `/bin/build` execution used to construct the OCI image.
2. Secondly, in alphabetically ascending order by layer directory name.
3. Thirdly, in alphabetically ascending order by file name.

3. If using an execution strategy involving a shell, the lifecycle MUST use a single shell process to
1. If using an execution strategy involving a shell, the lifecycle MUST use a single shell process, with working directory `<app>`, to
1. source each file in each `<layers>/<layer>/profile.d` directory,
1. Firstly, in order of `/bin/build` execution used to construct the OCI image.
2. Secondly, in alphabetically ascending order by layer directory name.
Expand All @@ -725,10 +730,9 @@ Given the start command and execution strategy,
3. Thirdly, in alphabetically ascending order by file name.
3. source [†](README.md#linux-only)`<app>/.profile` or [‡](README.md#windows-only)`<app>/.profile.bat` if it is present.

1. The lifecycle MUST set the working directory for the start command to `<working-dir>`, or to `<app>` if `<working-dir>` is not specified.

3. If using an execution strategy involving a shell, the lifecycle MUST source [†](README.md#linux-only)`<app>/.profile` or [‡](README.md#windows-only)`<app>/.profile.bat` if it is present.

4. The lifecycle MUST invoke the start command with the decided execution strategy.
1. The lifecycle MUST invoke the start command with the decided execution strategy.

[†](README.md#linux-only)When executing a process using any execution strategy, the lifecycle SHOULD replace the lifecycle process in memory without forking it.

Expand All @@ -740,16 +744,6 @@ Given the start command and execution strategy,

### Provided by the Lifecycle

#### Buildpack Specific Variables

The following environment variables MUST be set by the lifecycle in each buildpack's execution environment.

These variables MAY differ between buildpacks.

| Env Variable | Description | Detect | Build | Launch
|---------------------|--------------------------------------|--------|-------|--------
| `CNB_BUILDPACK_DIR` | The root of the buildpack source | [x] | [x] |

#### Layer Paths

The following layer path environment variables MUST be set by the lifecycle during the build and launch phases in order to make buildpack dependencies accessible.
Expand Down Expand Up @@ -901,6 +895,7 @@ command = "<command>"
args = ["<arguments>"]
direct = false
default = false
working-dir = "<working directory>"

[[slices]]
paths = ["<app sub-path glob>"]
Expand Down Expand Up @@ -928,6 +923,7 @@ For each process, the buildpack:
- MAY specify an `args` list to be passed directly to the specified executable.
- MAY specify a `direct` boolean that bypasses the shell.
- MAY specify a `default` boolean that indicates that the process type should be selected as the [buildpack-provided default](https://github.com/buildpacks/spec/blob/main/platform.md#outputs-4) during the export phase.
- MAY specify a `working-dir` for the process. The `working-dir` defaults to the application directory if not specified.

An individual buildpack may only specify one process type with `default = true`. The lifecycle MUST select, from all buildpack-provided process types, the last process type with `default = true` as the buildpack-provided default. If multiple buildpacks define processes of the same type, the lifecycle MUST use the last process type definition ordered by buildpack execution for the combined process list (a non-default process type definition may override a default process type definition, leaving the app image with no default).

Expand Down Expand Up @@ -1060,7 +1056,7 @@ Buildpack authors MUST choose a globally unique ID, for example: "io.buildpacks.

*Key: `id = "<buildpack ID>"`*
- MUST only contain numbers, letters, and the characters `.`, `/`, and `-`.
- MUST NOT be `config` or `app`.
- MUST NOT be `config`, `app`, or `sbom`.
- MUST NOT be identical to any other buildpack ID when using a case-insensitive comparison.

**The buildpack version:**
Expand Down Expand Up @@ -1124,9 +1120,79 @@ Each `key`:
## Deprecations
This section describes all the features that are deprecated.

### `0.3`

#### Build Plan (TOML) `requires.version` Key
### Positional Arguments to `detect` and `build` Executables

_Deprecated in Buildpack API 0.8._

The positional arguments to the `detect` and `build` executables are deprecated.
The lifecycle provides these values as environment variables.

To upgrade, buildpack authors SHOULD use the following environment variables:

For `detect`:

- `CNB_PLATFORM_DIR` replaces the first positional argument.
- `CNB_BUILD_PLAN_PATH` replaces the second positional argument.

For `build`:

* `CNB_LAYERS_DIR` replaces the first positional argument.
* `CNB_PLATFORM_DIR` replaces the second positional argument.
* `CNB_BP_PLAN_PATH` replaces the third positional argument.

### launch.toml (TOML) `bom` Array

_Deprecated in Buildpack API 0.7._

The `bom` array is deprecated.

```toml
[[bom]]
name = "<dependency name>"

[bom.metadata]
# arbitrary metadata describing the dependency
```

If the `bom` array is used, the buildpack:
- SHOULD add a bill-of-materials entry to the `bom` array describing each dependency contributed to the app image, where:
- `name` is REQUIRED.
- `metadata` MAY contain additional data describing the dependency.

The buildpack MAY add `bom` describing the contents of the app dir, even if they were not contributed by the buildpack.

When the build is complete, a legacy Bill of Materials (BOM) describing the app image MAY be generated for auditing purposes.

If generated, this legacy BOM MUST contain all `bom` entries in each `launch.toml` at the end of each `/bin/build` execution, in adherence with the process and data format outlined in the [Platform Interface Specification](platform.md) for legacy BOM formats.

### build.toml (TOML) `bom` Array

_Deprecated in Buildpack API 0.7._

The `bom` array is deprecated.

```toml
[[bom]]
name = "<dependency name>"

[bom.metadata]
# arbitrary metadata describing the dependency
```

If the `bom` array is used, the buildpack:
- SHOULD add a bill-of-materials entry to the `bom` array describing each dependency contributed to the build environment, where:
- `name` is REQUIRED.
- `metadata` MAY contain additional data describing the dependency.

When the build is complete, a legacy build BOM describing the build container MAY be generated for auditing purposes.

If generated, this legacy build BOM MUST contain all `bom` entries in each `build.toml` at the end of each `/bin/build` execution, in adherence with the process and data format outlined in the [Platform Interface Specification](platform.md) for legacy BOM formats.


### Build Plan (TOML) `requires.version` Key

_Deprecated in Buildpack API 0.3._

The `requires.version` and `or.requires.version` keys are deprecated.

Expand Down

0 comments on commit 1153938

Please sign in to comment.