diff --git a/README.md b/README.md index 4c2b824a..025ab99e 100644 --- a/README.md +++ b/README.md @@ -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` diff --git a/buildpack.md b/buildpack.md index dcdc5f6a..38cfef17 100644 --- a/buildpack.md +++ b/buildpack.md @@ -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) @@ -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 `.` or ``, where `` is equivalent to `.0` @@ -117,58 +116,64 @@ The lifecycle MAY return an error to the platform if two or more buildpacks with ### Detection -Executable: `/bin/detect `, Working Dir: `` +Executable: `/bin/detect`, Working Dir: `` -| Input | Description -|-------------------|---------------------------------------------- -| `$0` | Absolute path of `/bin/detect` executable -| `/env/` | User-provided environment variables for build -| `/#` | 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) -| `` | 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 `, Working Dir: `` - -| Input | Description -|-------------------|---------------------------------------------- -| `$0` | Absolute path of `/bin/build` executable -| `` | Relevant [Buildpack Plan entries](#buildpack-plan-toml) from detection (TOML) -| `/env/` | User-provided environment variables for build -| `/#` | Platform-specific extensions - -| Output | Description -|------------------------------------------|-------------------------------------- -| [exit status] | Success (0) or failure (1+) -| Standard output | Logs (info) -| Standard error | Logs (warnings, errors) -| `/launch.toml` | App metadata (see [launch.toml](#launchtoml-toml)) -| `/launch.sbom.` | Launch Software Bill of Materials (see [Software-Bill-of-Materials](#bill-of-materials)) -| `/build.toml` | Build metadata (see [build.toml](#buildtoml-toml)) -| `/build.sbom.` | Build Software Bill of Materials (see [Software-Bill-of-Materials](#bill-of-materials)) -| `/store.toml` | Persistent metadata (see [store.toml](#storetoml-toml)) -| `/.toml` | Layer metadata (see [Layer Content Metadata](#layer-content-metadata-toml)) -| `/.sbom.` | Layer Software Bill of Materials (see [Software-Bill-of-Materials](#bill-of-materials)) -| `//bin/` | Binaries for launch and/or subsequent buildpacks -| `//lib/` | Shared libraries for launch and/or subsequent buildpacks -| `//profile.d/` | Scripts sourced by Bash before launch -| `//profile.d//` | Scripts sourced by Bash before launch for a particular process type -| `//exec.d/` | Executables that provide env vars via the [Exec.d Interface](#execd) before launch -| `//exec.d//` | Executables that provide env vars for a particular process type via the [Exec.d Interface](#execd) before launch -| `//include/` | C/C++ headers for subsequent buildpacks -| `//pkgconfig/` | Search path for pkg-config for subsequent buildpacks -| `//env/` | Env vars for launch and/or subsequent buildpacks -| `//env.launch/` | Env vars for launch (after `env`, before `profile.d`) -| `//env.launch//` | Env vars for launch (after `env`, before `profile.d`) for the launched process -| `//env.build/` | Env vars for subsequent buildpacks (after `env`) -| `//*` | Other content for launch and/or subsequent buildpacks +Executable: `/bin/build`, Working Dir: `` + +| 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.` | 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.` | 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/.toml` | Layer metadata (see [Layer Content Metadata](#layer-content-metadata-toml)) | +| `$CNB_LAYERS_DIR/.sbom.` | Layer Software Bill of Materials (see [Software-Bill-of-Materials](#software-bill-of-materials)) | +| `$CNB_LAYERS_DIR//bin/` | Binaries for launch and/or subsequent buildpacks | +| `$CNB_LAYERS_DIR//lib/` | Shared libraries for launch and/or subsequent buildpacks | +| `$CNB_LAYERS_DIR//profile.d/` | Scripts sourced by Bash before launch | +| `$CNB_LAYERS_DIR//profile.d//` | Scripts sourced by Bash before launch for a particular process type | +| `$CNB_LAYERS_DIR//exec.d/` | Executables that provide env vars via the [Exec.d Interface](#execd) before launch | +| `$CNB_LAYERS_DIR//exec.d//` | Executables that provide env vars for a particular process type via the [Exec.d Interface](#execd) before launch | +| `$CNB_LAYERS_DIR//include/` | C/C++ headers for subsequent buildpacks | +| `$CNB_LAYERS_DIR//pkgconfig/` | Search path for pkg-config for subsequent buildpacks | +| `$CNB_LAYERS_DIR//env/` | Env vars for launch and/or subsequent buildpacks | +| `$CNB_LAYERS_DIR//env.launch/` | Env vars for launch (after `env`, before `profile.d`) | +| `$CNB_LAYERS_DIR//env.launch//` | Env vars for launch (after `env`, before `profile.d`) for the launched process | +| `$CNB_LAYERS_DIR//env.build/` | Env vars for subsequent buildpacks (after `env`) | +| `$CNB_LAYERS_DIR//*` | Other content for launch and/or subsequent buildpacks | ### Exec.d @@ -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 `//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 `//exec.d` directory in the launch environment, with working directory ``, 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 `//exec.d/` 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 `//exec.d/` directory in the launch environment, with working directory ``, 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 ``, to 1. source each file in each `//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. @@ -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)`/.profile` or [‡](README.md#windows-only)`/.profile.bat` if it is present. +1. The lifecycle MUST set the working directory for the start command to ``, or to `` if `` is not specified. -3. If using an execution strategy involving a shell, the lifecycle MUST source [†](README.md#linux-only)`/.profile` or [‡](README.md#windows-only)`/.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. @@ -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. @@ -901,6 +895,7 @@ command = "" args = [""] direct = false default = false +working-dir = "" [[slices]] paths = [""] @@ -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). @@ -1060,7 +1056,7 @@ Buildpack authors MUST choose a globally unique ID, for example: "io.buildpacks. *Key: `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:** @@ -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 = "" + +[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 = "" + +[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.