From dab2facfa07aecbce7d585ecaa2094d5ced09671 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Wed, 15 Dec 2021 12:16:30 -0500 Subject: [PATCH 01/15] Fixes link to SBOM section in buildpack spec Signed-off-by: Natalie Arellano --- buildpack.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/buildpack.md b/buildpack.md index dcdc5f6a..f4d91157 100644 --- a/buildpack.md +++ b/buildpack.md @@ -150,12 +150,12 @@ Executable: `/bin/build `, Working Dir: ` | 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)) +| `/launch.sbom.` | Launch Software Bill of Materials (see [Software-Bill-of-Materials](#software-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)) +| `/build.sbom.` | Build Software Bill of Materials (see [Software-Bill-of-Materials](#software-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)) +| `/.sbom.` | Layer Software Bill of Materials (see [Software-Bill-of-Materials](#software-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 From 90dcd478d516d4a119f4d392d83cc2a38cf09058 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Wed, 15 Dec 2021 12:22:16 -0500 Subject: [PATCH 02/15] Add sbom as a reserved buildpack ID Signed-off-by: Natalie Arellano --- buildpack.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buildpack.md b/buildpack.md index dcdc5f6a..2b893a6a 100644 --- a/buildpack.md +++ b/buildpack.md @@ -1060,7 +1060,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:** From d965c9ca31260d45e74673837b121eef30a48d34 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 18 Jan 2022 16:54:49 -0500 Subject: [PATCH 03/15] Add deprecation path for buildpacks using the legacy BOM format. Signed-off-by: Natalie Arellano --- buildpack.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/buildpack.md b/buildpack.md index 6d5dd000..d7f2ead1 100644 --- a/buildpack.md +++ b/buildpack.md @@ -1124,6 +1124,52 @@ Each `key`: ## Deprecations This section describes all the features that are deprecated. +### `0.7` + +#### launch.toml (TOML) `bom` Array + +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 + +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. + ### `0.3` #### Build Plan (TOML) `requires.version` Key From b1c7fe155f5e7983aed261bfb5576a9b4e5a6cc5 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Thu, 27 Jan 2022 11:30:25 -0500 Subject: [PATCH 04/15] Process specific working directory Signed-off-by: Natalie Arellano --- buildpack.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/buildpack.md b/buildpack.md index d7f2ead1..b21b61a8 100644 --- a/buildpack.md +++ b/buildpack.md @@ -704,7 +704,9 @@ 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 +2. The lifecycle MUST set the working directory for the process to `working-directory`, or to the application directory if `working-directory` is not specified. + +3. 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. Firstly, in order of `/bin/build` execution used to construct the OCI image. 2. Secondly, in alphabetically ascending order by layer directory name. @@ -714,7 +716,7 @@ Given the start command and execution strategy, 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 +4. If using an execution strategy involving a shell, the lifecycle MUST use a single shell process 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. @@ -726,9 +728,9 @@ Given the start command and execution strategy, 3. source [†](README.md#linux-only)`/.profile` or [‡](README.md#windows-only)`/.profile.bat` if it is present. -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. +5. 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. +6. 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. @@ -901,6 +903,7 @@ command = "" args = [""] direct = false default = false +working-directory = "" [[slices]] paths = [""] @@ -928,6 +931,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-directory` for the process. The `working-directory` 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). From 270ca0461962e58d5bcd966a98bf3a86b1271fd3 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Fri, 11 Feb 2022 10:45:57 -0500 Subject: [PATCH 05/15] Reorder things and clarify the working directory for exec.d and profile.d Signed-off-by: Natalie Arellano --- buildpack.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/buildpack.md b/buildpack.md index b21b61a8..45867114 100644 --- a/buildpack.md +++ b/buildpack.md @@ -704,9 +704,7 @@ 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 set the working directory for the process to `working-directory`, or to the application directory if `working-directory` is not specified. - -3. The lifecycle MUST +1. 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. Firstly, in order of `/bin/build` execution used to construct the OCI image. 2. Secondly, in alphabetically ascending order by layer directory name. @@ -716,7 +714,9 @@ Given the start command and execution strategy, 2. Secondly, in alphabetically ascending order by layer directory name. 3. Thirdly, in alphabetically ascending order by file name. -4. If using an execution strategy involving a shell, the lifecycle MUST use a single shell process to +The working directory for all executed files SHALL be ``. + +1. If using an execution strategy involving a shell, the lifecycle MUST use a single shell process 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. @@ -727,10 +727,11 @@ 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. +The working directory for all sourced files SHALL be ``. -5. 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. +1. The lifecycle MUST set the working directory for the start command to `working-directory`, or to `` if `working-directory` is not specified. -6. 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. From e06c670cf3ed89e0fbf0b8e7e3ddb5fe27dd0edf Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Thu, 24 Feb 2022 16:19:02 -0500 Subject: [PATCH 06/15] Apply suggestions from code review Signed-off-by: Natalie Arellano Co-authored-by: Emily Casey --- buildpack.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/buildpack.md b/buildpack.md index 45867114..9e2ca5ae 100644 --- a/buildpack.md +++ b/buildpack.md @@ -705,7 +705,7 @@ 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. 1. 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. [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. @@ -716,7 +716,7 @@ Given the start command and execution strategy, The working directory for all executed files SHALL be ``. -1. 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. @@ -729,7 +729,7 @@ The working directory for all executed files SHALL be ``. The working directory for all sourced files SHALL be ``. -1. The lifecycle MUST set the working directory for the start command to `working-directory`, or to `` if `working-directory` is not specified. +1. The lifecycle MUST set the working directory for the start command to ``, or to `` if `` is not specified. 1. The lifecycle MUST invoke the start command with the decided execution strategy. From 0ecb2fe3054b1b2063b172377015c4e5d6d260e6 Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Thu, 24 Feb 2022 16:23:08 -0500 Subject: [PATCH 07/15] Remove standalone lines, and add one more line Signed-off-by: Natalie Arellano --- buildpack.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/buildpack.md b/buildpack.md index 9e2ca5ae..b2757976 100644 --- a/buildpack.md +++ b/buildpack.md @@ -709,14 +709,12 @@ Given the start command and execution strategy, 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. -The working directory for all executed files SHALL be ``. - -1. If using an execution strategy involving a shell, the lifecycle MUST use a single shell process with working directory `` 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. @@ -727,8 +725,6 @@ The working directory for all executed files SHALL be ``. 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. -The working directory for all sourced files SHALL be ``. - 1. The lifecycle MUST set the working directory for the start command to ``, or to `` if `` is not specified. 1. The lifecycle MUST invoke the start command with the decided execution strategy. From e3ba9c3b7a5c702a68c8df4a7b5e9ab373e8cf9c Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Wed, 2 Mar 2022 18:04:54 -0500 Subject: [PATCH 08/15] Change working-directory to working-dir Signed-off-by: Natalie Arellano --- buildpack.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/buildpack.md b/buildpack.md index b2757976..9f8b6e72 100644 --- a/buildpack.md +++ b/buildpack.md @@ -725,7 +725,7 @@ 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. +1. The lifecycle MUST set the working directory for the start command to ``, or to `` if `` is not specified. 1. The lifecycle MUST invoke the start command with the decided execution strategy. @@ -900,7 +900,7 @@ command = "" args = [""] direct = false default = false -working-directory = "" +working-dir = "" [[slices]] paths = [""] @@ -928,7 +928,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-directory` for the process. The `working-directory` defaults to the application directory if not specified. +- 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). From 3883a60d68fdc2faa443916b478489088939d48a Mon Sep 17 00:00:00 2001 From: Mikey Boldt Date: Wed, 2 Mar 2022 22:41:07 -0600 Subject: [PATCH 09/15] Deprecate positional args to `build` and `detect` and add env vars Per RFC 100: https://github.com/buildpacks/rfcs/blob/main/text/0100-buildpack-input-vars.md Fixes #294. Signed-off-by: Mikey Boldt --- buildpack.md | 82 +++++++++++++++++++++++++++++++++++----------------- 1 file changed, 55 insertions(+), 27 deletions(-) diff --git a/buildpack.md b/buildpack.md index d7f2ead1..03d15c27 100644 --- a/buildpack.md +++ b/buildpack.md @@ -84,7 +84,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` @@ -119,56 +119,64 @@ The lifecycle MAY return an error to the platform if two or more buildpacks with Executable: `/bin/detect `, Working Dir: `` +Note: the positional arguments to `/bin/detect` are deprecated, and buildpack authors SHOULD use the corresponding environment variables. + | Input | Description |-------------------|---------------------------------------------- | `$0` | Absolute path of `/bin/detect` executable -| `/env/` | User-provided environment variables for build -| `/#` | Platform-specific extensions +| `$CNB_BUILD_PLAN_PATH` | Absolute path of the build plan +| `$CNB_PLATFORM_DIR` | Absolute path of the platform directory +| `$CNB_PLATFORM_DIR/env/` | User-provided environment variables for build +| `$CNB_PLATFORM_DIR/#` | 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) +| `$CNB_BUILD_PLAN_PATH` | Contributions to the the Build Plan (TOML) ### Build Executable: `/bin/build `, Working Dir: `` +Note: the positional arguments to `/bin/detect` are deprecated, and buildpack authors SHOULD use the corresponding environment variables. + | 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 +| `$CNB_LAYERS_DIR` | Absolute path of the buildpack layers directory +| `$CNB_BP_PLAN_PATH` | Relevant [Buildpack Plan entries](#buildpack-plan-toml) from detection (TOML) +| `$CNB_PLATFORM_DIR` | Absolute path of the platform directory +| `$CNB_PLATFORM_DIR/env/` | User-provided environment variables for build +| `$CNB_PLATFORM_DIR/#` | 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](#software-bill-of-materials)) -| `/build.toml` | Build metadata (see [build.toml](#buildtoml-toml)) -| `/build.sbom.` | Build Software Bill of Materials (see [Software-Bill-of-Materials](#software-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](#software-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 +| `$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 @@ -1213,3 +1221,23 @@ name = "" [entries.metadata] version = "" ``` + +### `0.8` + +#### Positional Arguments to `detect` and `build` Executables + +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. From 78f9907ba358bfc2ca597fd3083f37d3c2d97648 Mon Sep 17 00:00:00 2001 From: Mikey Boldt Date: Wed, 2 Mar 2022 22:55:10 -0600 Subject: [PATCH 10/15] Whitespace Signed-off-by: Mikey Boldt --- buildpack.md | 96 ++++++++++++++++++++++++++-------------------------- 1 file changed, 48 insertions(+), 48 deletions(-) diff --git a/buildpack.md b/buildpack.md index 03d15c27..0557bc3f 100644 --- a/buildpack.md +++ b/buildpack.md @@ -121,20 +121,20 @@ Executable: `/bin/detect `, Working Dir: `` Note: the positional arguments to `/bin/detect` are deprecated, and buildpack authors SHOULD use the corresponding environment variables. -| Input | Description -|-------------------|---------------------------------------------- -| `$0` | Absolute path of `/bin/detect` executable -| `$CNB_BUILD_PLAN_PATH` | Absolute path of the build plan -| `$CNB_PLATFORM_DIR` | Absolute path of the platform directory -| `$CNB_PLATFORM_DIR/env/` | User-provided environment variables for build -| `$CNB_PLATFORM_DIR/#` | 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) -| `$CNB_BUILD_PLAN_PATH` | Contributions to the the Build Plan (TOML) +| Input | Description | +|--------------------------|-----------------------------------------------| +| `$0` | Absolute path of `/bin/detect` executable | +| `$CNB_BUILD_PLAN_PATH` | Absolute path of the build plan | +| `$CNB_PLATFORM_DIR` | Absolute path of the platform directory | +| `$CNB_PLATFORM_DIR/env/` | User-provided environment variables for build | +| `$CNB_PLATFORM_DIR/#` | 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) | +| `$CNB_BUILD_PLAN_PATH` | Contributions to the the Build Plan (TOML) | ### Build @@ -143,40 +143,40 @@ Executable: `/bin/build `, Working Dir: ` Note: the positional arguments to `/bin/detect` are deprecated, and buildpack authors SHOULD use the corresponding environment variables. -| Input | Description -|-------------------|---------------------------------------------- -| `$0` | Absolute path of `/bin/build` executable -| `$CNB_LAYERS_DIR` | Absolute path of the buildpack layers directory -| `$CNB_BP_PLAN_PATH` | Relevant [Buildpack Plan entries](#buildpack-plan-toml) from detection (TOML) -| `$CNB_PLATFORM_DIR` | Absolute path of the platform directory -| `$CNB_PLATFORM_DIR/env/` | User-provided environment variables for build -| `$CNB_PLATFORM_DIR/#` | 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 +| Input | Description | +|--------------------------|-------------------------------------------------------------------------------| +| `$0` | Absolute path of `/bin/build` executable | +| `$CNB_LAYERS_DIR` | Absolute path of the buildpack layers directory | +| `$CNB_BP_PLAN_PATH` | Relevant [Buildpack Plan entries](#buildpack-plan-toml) from detection (TOML) | +| `$CNB_PLATFORM_DIR` | Absolute path of the platform directory | +| `$CNB_PLATFORM_DIR/env/` | User-provided environment variables for build | +| `$CNB_PLATFORM_DIR/#` | 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 From 296bb6189391470bc18f33ffedb79cdc1b27ec1a Mon Sep 17 00:00:00 2001 From: Mikey Boldt Date: Wed, 2 Mar 2022 22:57:35 -0600 Subject: [PATCH 11/15] Add attributes of `build` and `detect` input env vars Signed-off-by: Mikey Boldt --- buildpack.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/buildpack.md b/buildpack.md index 0557bc3f..62305d43 100644 --- a/buildpack.md +++ b/buildpack.md @@ -121,13 +121,13 @@ Executable: `/bin/detect `, Working Dir: `` Note: the positional arguments to `/bin/detect` are deprecated, and buildpack authors SHOULD use the corresponding environment variables. -| Input | Description | -|--------------------------|-----------------------------------------------| -| `$0` | Absolute path of `/bin/detect` executable | -| `$CNB_BUILD_PLAN_PATH` | Absolute path of the build plan | -| `$CNB_PLATFORM_DIR` | Absolute path of the platform directory | -| `$CNB_PLATFORM_DIR/env/` | User-provided environment variables for build | -| `$CNB_PLATFORM_DIR/#` | 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_PLATFORM_DIR` | AR | Absolute path of the platform directory | +| `$CNB_PLATFORM_DIR/env/` | | User-provided environment variables for build | +| `$CNB_PLATFORM_DIR/#` | | Platform-specific extensions | | Output | Description | |------------------------|---------------------------------------------| @@ -143,14 +143,14 @@ Executable: `/bin/build `, Working Dir: ` Note: the positional arguments to `/bin/detect` are deprecated, and buildpack authors SHOULD use the corresponding environment variables. -| Input | Description | -|--------------------------|-------------------------------------------------------------------------------| -| `$0` | Absolute path of `/bin/build` executable | -| `$CNB_LAYERS_DIR` | Absolute path of the buildpack layers directory | -| `$CNB_BP_PLAN_PATH` | Relevant [Buildpack Plan entries](#buildpack-plan-toml) from detection (TOML) | -| `$CNB_PLATFORM_DIR` | Absolute path of the platform directory | -| `$CNB_PLATFORM_DIR/env/` | User-provided environment variables for build | -| `$CNB_PLATFORM_DIR/#` | Platform-specific extensions | +| 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_PLATFORM_DIR` | AR | Absolute path of the platform directory | +| `$CNB_PLATFORM_DIR/env/` | | User-provided environment variables for build | +| `$CNB_PLATFORM_DIR/#` | | Platform-specific extensions | | Output | Description | |-------------------------------------------------|------------------------------------------------------------------------------------------------------------------| From 16d0b14d6b5ba033ac49f6d53a5f35bde52f0546 Mon Sep 17 00:00:00 2001 From: Mikey Boldt Date: Thu, 17 Mar 2022 12:40:20 -0500 Subject: [PATCH 12/15] Remove deprecated positional args from main body Signed-off-by: Mikey Boldt --- buildpack.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/buildpack.md b/buildpack.md index 62305d43..c27d060e 100644 --- a/buildpack.md +++ b/buildpack.md @@ -117,9 +117,7 @@ The lifecycle MAY return an error to the platform if two or more buildpacks with ### Detection -Executable: `/bin/detect `, Working Dir: `` - -Note: the positional arguments to `/bin/detect` are deprecated, and buildpack authors SHOULD use the corresponding environment variables. +Executable: `/bin/detect`, Working Dir: `` | Input | Attributes | Description | |--------------------------|------------|-----------------------------------------------| @@ -139,9 +137,7 @@ Note: the positional arguments to `/bin/detect` are deprecated, and buildpack au ### Build -Executable: `/bin/build `, Working Dir: `` - -Note: the positional arguments to `/bin/detect` are deprecated, and buildpack authors SHOULD use the corresponding environment variables. +Executable: `/bin/build`, Working Dir: `` | Input | Attributes | Description | |--------------------------|------------|-------------------------------------------------------------------------------| From 80c933311b2fd62874e55c1d5839720d78ef9f94 Mon Sep 17 00:00:00 2001 From: Mikey Boldt Date: Wed, 23 Mar 2022 16:17:28 -0500 Subject: [PATCH 13/15] Restructure Deprecations section - Remove API version headings. - Add "Deprecated in Buildpack API X.Y" to each item. - Order the list of deprecations newest-on-top. Signed-off-by: Mikey Boldt --- buildpack.md | 54 ++++++++++++++++++++++++++++------------------------ 1 file changed, 29 insertions(+), 25 deletions(-) diff --git a/buildpack.md b/buildpack.md index c27d060e..e2e0e987 100644 --- a/buildpack.md +++ b/buildpack.md @@ -1128,9 +1128,30 @@ Each `key`: ## Deprecations This section describes all the features that are deprecated. -### `0.7` -#### launch.toml (TOML) `bom` Array +### 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. @@ -1153,7 +1174,9 @@ When the build is complete, a legacy Bill of Materials (BOM) describing the app 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 +### build.toml (TOML) `bom` Array + +_Deprecated in Buildpack API 0.7._ The `bom` array is deprecated. @@ -1174,9 +1197,10 @@ When the build is complete, a legacy build BOM describing the build container MA 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. -### `0.3` -#### Build Plan (TOML) `requires.version` Key +### Build Plan (TOML) `requires.version` Key + +_Deprecated in Buildpack API 0.3._ The `requires.version` and `or.requires.version` keys are deprecated. @@ -1217,23 +1241,3 @@ name = "" [entries.metadata] version = "" ``` - -### `0.8` - -#### Positional Arguments to `detect` and `build` Executables - -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. From 4db387c7b00aec9d69e66903c0a8ff4c6955d43c Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Tue, 5 Apr 2022 12:52:19 -0400 Subject: [PATCH 14/15] List CNB_BUILDPACK_DIR with other lifecycle provided variables Signed-off-by: Natalie Arellano --- buildpack.md | 21 ++++++--------------- 1 file changed, 6 insertions(+), 15 deletions(-) diff --git a/buildpack.md b/buildpack.md index ee4e08b0..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) @@ -123,9 +122,10 @@ Executable: `/bin/detect`, Working Dir: `` |--------------------------|------------|-----------------------------------------------| | `$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/` | | User-provided environment variables for build | -| `$CNB_PLATFORM_DIR/#` | | Platform-specific extensions | +| `$CNB_PLATFORM_DIR/env/` | AR | User-provided environment variables for build | +| `$CNB_PLATFORM_DIR/#` | AR | Platform-specific extensions | | Output | Description | |------------------------|---------------------------------------------| @@ -144,9 +144,10 @@ Executable: `/bin/build`, Working Dir: `` | `$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/` | | User-provided environment variables for build | -| `$CNB_PLATFORM_DIR/#` | | Platform-specific extensions | +| `$CNB_PLATFORM_DIR/env/` | AR | User-provided environment variables for build | +| `$CNB_PLATFORM_DIR/#` | AR | Platform-specific extensions | | Output | Description | |-------------------------------------------------|------------------------------------------------------------------------------------------------------------------| @@ -743,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. From 1f9f3534c3d6f6d5acfdc30ef9656923585a32bb Mon Sep 17 00:00:00 2001 From: Natalie Arellano Date: Wed, 6 Apr 2022 13:47:25 -0400 Subject: [PATCH 15/15] Bump buildpack api version in README Signed-off-by: Natalie Arellano --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index bfc4f265..99603b25 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.8` \ No newline at end of file