Merge branch 'main' into feature/windows-2004

Author: jromero

content/docs/reference/spec/buildpack-api.md

@@ -22,23 +22,24 @@ can be executables compiled from a language like Go.
 ### Usage
 
 ```
-bin/detect PLATFORM_DIR BUILD_PLAN
+bin/detect
 ```
 
 ### Summary
 
 This entrypoint is used to determine if a buildpack should
 run against a given codebase. It will often check for the existence of a particular
 file or some configuration indicating what kind of application has been provided.
-It accepts two positional arguments:
+Two environment variables identify important file system paths:
 
-* `PLATFORM_DIR` - a directory containing platform provided configuration, such as environment variables.
-* `BUILD_PLAN` - a path to a file containing the [Build Plan](#build-plan).
+* `CNB_PLATFORM_DIR` - a directory containing platform provided configuration, such as environment variables.
+* `CNB_BUILD_PLAN_PATH` - a path to a file containing the [Build Plan](#build-plan).
 
 In addition, the working directory is defined as the location of the codebase
 the buildpack will execute against.
 
-The executable must return an exit code of `0` if the codebase can be serviced by this buildpack.
+The executable must return an exit code of `0` if the codebase can be serviced by this buildpack, and `100` if it cannot.
+Other exit codes indicate an error during detection.
 
 ### Example
 
@@ -52,7 +53,7 @@ if [ -f requirements.txt ]; then
   echo "Python Buildpack"
   exit 0
 else
-  exit 1
+  exit 100
 fi
 ```
 
@@ -61,35 +62,35 @@ fi
 ### Usage
 
 ```
-bin/build LAYERS_DIR PLATFORM_DIR BUILD_PLAN
+bin/build
 ```
 
 This entrypoint transforms a codebase.
 It will often resolve dependencies, install binary packages, and compile code.
-It accepts three positional arguments:
+Three environment variables identify important file system paths:
 
-* `LAYERS_DIR` - a directory that may contain subdirectories representing each layer created by the buildpack in the final image or build cache.
-* `PLATFORM_DIR` - a directory containing platform provided configuration, such as environment variables.
-* `BUILD_PLAN` - a path to a file containing the [Build Plan](#build-plan).
+* `CNB_LAYERS_DIR` - a directory that may contain subdirectories representing each layer created by the buildpack in the final image or build cache.
+* `CNB_PLATFORM_DIR` - a directory containing platform provided configuration, such as environment variables.
+* `CNB_BP_PLAN_PATH` - a path to a file containing the [Build Plan](#build-plan).
 
 In addition, the working directory is defined as the location of the codebase
 this buildpack will execute against.
 
 All changes to the codebase in the working directory will be included in the final
-image, along with any launch layers created in the `LAYERS_DIR`.
+image, along with any launch layers created in the `CNB_LAYERS_DIR`.
 
 #### Layers
 
-Each directory created by the buildpack under the `LAYERS_DIR` can be used for any
+Each directory created by the buildpack under the `CNB_LAYERS_DIR` can be used for any
 of the following purposes:
 
 * Launch - the directory will be included in the run image as a single layer
 * Cache - the directory will be included in the cache
 * Build - the directory will be accessible by subsequent buildpacks
 
 A buildpack defines how a layer will by used by creating a `<layer>.toml` with
-a name matching the directory it describes in the `LAYERS_DIR`. For example, a
-buildpack might create a `$LAYERS_DIR/python` directory and a `$LAYERS_DIR/python.toml`
+a name matching the directory it describes in the `CNB_LAYERS_DIR`. For example, a
+buildpack might create a `$CNB_LAYERS_DIR/python` directory and a `$CNB_LAYERS_DIR/python.toml`
 with the following contents:
 
 ```
@@ -109,9 +110,7 @@ to resolve dependencies:
 ```
 #!/bin/sh
 
-LAYERS_DIR="$1"
-
-PIP_LAYER="$LAYERS_DIR/pip"
+PIP_LAYER="$CNB_LAYERS_DIR/pip"
 mkdir -p "$PIP_LAYER/modules" "$PIP_LAYER/env"
 
 pip install -r requirements.txt -t "$PIP_LAYER/modules" \
@@ -129,7 +128,7 @@ A buildpack must contain a `buildpack.toml` file in its root directory.
 ### Example
 
 ```
-api = "0.7"
+api = "0.8"
 
 [buildpack]
 id = "example.com/python"
@@ -142,7 +141,7 @@ id = "io.buildpacks.stacks.bionic"
 ### Schema
 
 The schema is as follows:
-- **`api`** _(string, required, current: `0.7`)_\
+- **`api`** _(string, required, current: `0.8`)_\
     The Buildpack API version the buildpack adheres to. Used to ensure [compatibility](#api-compatibility) against
     the [lifecycle][lifecycle].
 
@@ -268,7 +267,7 @@ The NPM buildpack could write the following to the build plan, if the buildpack
 name = "node"
 ```
 
-If, looking in the `package.json` file, the NPM buildpack see a specific version of `node` requested in the [engines](https://docs.npmjs.com/files/package.json#engines) field (e.g. `14.1`), it may write the following to the build plan:
+If, looking in the `package.json` file, the NPM buildpack sees a specific version of `node` requested in the [engines](https://docs.npmjs.com/files/package.json#engines) field (e.g. `14.1`), it may write the following to the build plan:
 ```
 [[requires]]
 name = "node"

content/docs/reference/spec/migration/buildpack-api-0.7-0.8.md

@@ -0,0 +1,52 @@
++++
+title="Buildpack API 0.7 -> 0.8"
++++
+
+<!--more-->
+
+This guide is most relevant to buildpack authors.
+
+See the [spec release](https://github.com/buildpacks/spec/releases/tag/buildpack%2Fv0.8) for buildpack API 0.8 for the full list of changes and further details.
+
+### Process-Specific Working Directory
+
+Buildpacks may specify the working directory for a process by setting the `working-dir` field on the process in [`launch.toml`](https://github.com/buildpacks/spec/blob/buildpack/0.8/buildpack.md#launchtoml-toml).
+
+Prior to this, all processes ran from the app directory (`CNB_APP_DIR`).
+Running a process from a different directory typically involved running a shell to execute a `cd` command and then start the process, like:
+
+```
+[[processes]]
+command = "bash"
+args = ["-c", "cd <working-dir> && <start-process>"]
+```
+
+Buildpacks can now specify the process directly with a specific working directory, like:
+
+```
+[[processes]]
+command = "<start-process>"
+working-dir = "<working-dir>"
+```
+
+For details, see [RFC 81](https://github.com/buildpacks/rfcs/blob/main/text/0081-process-specific-working-directory.md).
+
+### Deprecate Positional Args to `build` and `detect` Executables
+
+The positional arguments to the `detect` and `build` executables are deprecated.
+Lifecycle now accepts 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.
+
+For details, see [RFC 100](https://github.com/buildpacks/rfcs/blob/main/text/0100-buildpack-input-vars.md).

content/docs/reference/spec/migration/platform-api-0.8-0.9.md

@@ -0,0 +1,27 @@
++++
+title="Platform API 0.8 -> 0.9"
++++
+
+<!--more-->
+
+This guide is most relevant to platform operators.
+
+See the [spec release](https://github.com/buildpacks/spec/releases/tag/platform%2Fv0.9) for platform API 0.9 for the full list of changes and further details.
+
+## Platform Operator
+
+### Legacy BOM information removed from `io.buildpacks.build.metadata` label
+
+Legacy BOM information is removed from the `io.buildpacks.build.metadata` label and `<layers>/config/metadata.toml`. Buildpacks may still output BOM information in the legacy format, and it can now be found in `<layers>/sbom/launch/sbom.legacy.json` (for runtime dependencies) or `<layers>/sbom/build/sbom.legacy.json` (for build time dependencies). Note that `<layers>/sbom/build/sbom.legacy.json` is not exported in the application image, and must be copied from the build container before it exits.
+
+### Configurable image create time
+
+Platforms can set `SOURCE_DATE_EPOCH` in the exporter's environment to configure the create time of the exported application image. For example, platforms can set `SOURCE_DATE_EPOCH=$(date +%s)` to give images a meaningful create time instead of the current hard coded value of January 1, 1980. Note that changing the create time for an image will change its digest, affecting build reproducibility. For more information on build reproducibility, see our [blog post](https://medium.com/buildpacks/time-travel-with-pack-e0efd8bf05db).
+
+### New analyzer flags
+
+The analyze phase accepts a `-launch-cache` flag, improving performance when restoring the SBOM layer from the previous image in a Docker daemon. This should save several seconds of build time when using a Docker daemon and the untrusted builder workflow. Additionally, the analyzer accepts a `-skip-layers` flag to completely skip SBOM layer restoration instead of merely omitting SBOM files from buildpack layer directories when skipping the `restore` phase.
+
+### Process-specific working directory
+
+As of Buildpack API 0.8, buildpacks can specify the working directory for a process. If a working directory has been specified, this information will be included in the `io.buildpacks.build.metadata` label so that platforms can display this information to end users.