Learn how to publish your buildpack to the Buildpack Registry.
+ Learn how to package your buildpack or extension for distribution.
Learn how to package your buildpack or extension for distribution.
+ Learn how to publish your buildpack to the Buildpack Registry.
Migrate
@@ -794,14 +812,17 @@
-
Configuration
@@ -854,6 +875,32 @@ Write buildpacks
+
+ To write a buildpack, we follow the Buildpack Specification,
+which defines the contract between buildpacks and the lifecycle.
+
+
+
+
+
+ The Build Plan is a document that buildpacks can use to pass information between the detect and build phases, and between each other.
+The build plan is passed (by the lifecycle) as a parameter to the detect and build binaries of each buildpack.
+
+
+
+
+
+ Each directory created by the buildpack under the CNB_LAYERS_DIR can be used as a layer in the final app image or build cache.
+
+
+
+
One of the benefits of buildpacks is that they are multi-process - an image can have multiple entrypoints for each operational mode.
@@ -889,15 +936,6 @@ This page is a stub! The CNB project is applying to Google Season of Docs to receive support for improving our documentation. Please check back soon.
-If you are familiar with this content and would like to make a contribution, please feel free to open a PR :)
-
-
-
-
This page is a stub! The CNB project is applying to Google Season of Docs to receive support for improving our documentation. Please check back soon.
If you are familiar with this content and would like to make a contribution, please feel free to open a PR :)
@@ -935,15 +973,6 @@ This page is a stub! The CNB project is applying to Google Season of Docs to receive support for improving our documentation. Please check back soon.
-If you are familiar with this content and would like to make a contribution, please feel free to open a PR :)
-
-
-
- This page is a stub! The CNB project is applying to Google Season of Docs to receive support for improving our documentation. Please check back soon.
-If you are familiar with this content and would like to make a contribution, please feel free to open a PR :)
+ The Build Plan is a document that buildpacks can use to pass information between the detect and build phases, and between each other.
+The build plan is passed (by the lifecycle) as a parameter to the detect and build binaries of each buildpack.
+During the detect phase, each buildpack may write something it requires or provides (or both) into the Build Plan.
+A buildpack can require or provide multiple dependencies, and even multiple groupings of dependencies (using or lists).
+Additionally, multiple buildpacks may require or provide the same dependency.
+For detailed information, consult the spec.
+The lifecycle uses the Build Plan to determine whether a particular list of buildpacks can work together,
+by seeing whether all dependencies required can be provided by that list.
+Later, during the build phase, each buildpack may read the Buildpack Plan (a condensed version of the Build Plan, composed by the lifecycle) to determine what it should do.
+Let’s see how this works with an example.
+Example: node-engine buildpack
+Let’s walk through some possible cases a node-engine buildpack may consider:
+
+- Nothing in the app explicitly calls out that it is needed
+- It is explicitly referred to in some configuration file
+
+We will also consider what an NPM and a JVM buildpack may do.
+Scenario 1: No Explicit Request
+A node-engine buildpack is always happy to provide the node dependency. The build plan it will write may look something like:
+
[[provides]]
+name = "node"
+
+NOTE: If this was the only buildpack running, this would fail the detect phase. In order to pass, every provides must be matched up with a requires, whether in the same buildpack or in another buildpack.
+See the spec for particulars on how ordering buildpacks can adjust detection results.
+
+Scenario 2: One Version Requested
+During the detect phase, the node-engine buildpack sees in one configuration file (e.g. a .nvmrc file in the app directory) that node v10.x is explicitly requested by the application. Seeing that, it may write the below text to the build plan:
+[[provides]]
+name = "node"
+
+[[requires]]
+name = "node"
+version = "10.x"
+
+[requires.metadata]
+version-source = ".nvmrc"
+
As always, the buildpack provides node. In this particular case, a version of node (10.x) is being requested in a configuration file (.nvmrc). The buildpack chooses to add an additional piece of metadata (version-source), so that it can understand where that request came from.
+NPM Buildpack
+NPM is the default package manager for node. A NPM Buildpack may ensure that all the packages for the application are present (by running npm install), and perhaps cache those packages as well, to optimize future builds.
+NPM is typically distributed together with node. As a result, a NPM buildpack may require node, but not want to provide it, trusting that the node-engine buildpack will be in charge of providing node.
+The NPM buildpack could write the following to the build plan, if the buildpack sees that npm is necessary (e.g., it sees a package.json file in the app directory):
+[[requires]]
+name = "node"
+
If, looking in the package.json file, the NPM buildpack sees a specific version of node requested in the engines field (e.g. 14.1), it may write the following to the build plan:
+[[requires]]
+name = "node"
+version = "14.1"
+
+[requires.metadata]
+version-source = "package.json"
+
+NOTE: As above, if this was the only buildpack running, this would fail the detect phase. In order to pass, every provides must be matched up with a requires, whether in the same buildpack or in another buildpack.
+See the spec for particulars on how ordering buildpacks can adjust detection results.
+
+However, if the NPM Buildpack was run together with the Node Engine buildpack (which provides node), the lifecycle will see that all requirements are fulfilled, and select that group as the correct set of buildpacks.
+Example: JVM buildpack
+Java is distributed in two formats - the jdk (Java Development Kit), which allows for compilation and running of Java programs, and the jre (Java Runtime Environment, which allows for running compiled Java programs).
+A very naive implementation of the buildpack may have it write several provides options to the build plan, detailing everything that it can provide,
+while later buildpacks would figure out based on the application which options it requires, and would require those.
+In this particular case, we can use the or operator to present different possible build plans the buildpack can follow:
+# option 1 (`jre` and `jdk`)
+[[provides]]
+name = "jre"
+
+[[provides]]
+name = "jdk"
+
+# option 2 (or just `jdk`)
+[[or]]
+[[or.provides]]
+name = "jdk"
+
+# option 3 (or just `jre`)
+[[or]]
+[[or.provides]]
+name = "jre"
+
The buildpack gives three options to the lifecycle:
+
+- It can provide a standalone
jre
+- It can provide a standalone
jdk
+- It can provide both the
jdk and jre
+
+As with the other buildpacks, this alone will not be sufficient for the lifecycle. However, other buildpacks that follow may require certain things.
+For example, another buildpack may look into the application and, seeing that it is a Java executable, require the jre in order to run it.
+When the lifecycle analyzes the results of the detect phase, it will see that there is a buildpack which provides jre, and a buildpack that requires jre,
+and will therefore conclude that those options represent a valid set of buildpacks.
diff --git a/docs/for-buildpack-authors/how-to/write-buildpacks/use-exec.d/index.html b/docs/for-buildpack-authors/how-to/write-buildpacks/use-exec.d/index.html
index 87c0deacb..00cef22c3 100644
--- a/docs/for-buildpack-authors/how-to/write-buildpacks/use-exec.d/index.html
+++ b/docs/for-buildpack-authors/how-to/write-buildpacks/use-exec.d/index.html
@@ -301,6 +301,14 @@
Migrate
@@ -796,14 +814,17 @@
-
Configuration
@@ -835,12 +856,12 @@
- Report Issue
- Edit
@@ -848,11 +869,11 @@
-
What are image extensions?
+ What is an image extension?
- Image extensions generate Dockerfiles that can be used to extend base images for buildpacks builds.
-Why Dockerfiles?
+ An image extension is software that generates Dockerfiles that can be used to extend base images for buildpacks builds.
+Why image extensions?
Buildpacks can do a lot, but there are some things buildpacks can’t do. They can’t install operating system packages,
for example. Why not?
Buildpacks do not run as the root user and cannot make arbitrary changes to the filesystem. This enhances security,
@@ -861,24 +882,17 @@
Why Dockerfiles?
possible.
This has been a longstanding source of discussion within the CNB project:
how can we preserve the benefits of buildpacks while enabling more powerful capabilities?
-Buildpacks and Dockerfiles can work together
+Buildpacks and Dockerfiles can work together
Buildpacks are often presented as an alternative to Dockerfiles, but we think buildpacks and Dockerfiles can work
together.
Buildpacks are optimized for creating layers that are efficient and logically mapped to the dependencies that they
provide. By contrast, Dockerfiles are the most-used and best-understood mechanism for constructing base images and
installing OS-level dependencies for containers.
The CNB Dockerfiles feature allows Dockerfiles to “provide” dependencies that buildpacks “require” through a
-shared build plan, by introducing the concept of image extensions.
-What are image extensions?
+shared build plan, by introducing the concept of image extensions.
+What do they look like?
Image extensions are buildpack-like components that use a restricted Dockerfile syntax to expand base images. Their
purpose is to generate Dockerfiles that can be used to extend the builder or run images prior to buildpacks builds.
-Like buildpacks, extensions participate in the detect phase - analyzing application source code to determine if they
-are needed. During detect, extensions can contribute to
-the build plan - recording dependencies that they are able to "
-provide" (though unlike buildpacks, they can’t “require” anything).
-If the provided order contains extensions, the output of detect will be a group of image extensions and a group of
-buildpacks that together produce a valid build plan. Image extensions only generate Dockerfiles - they don’t create
-layers or participate in the build phase.
An image extension could be defined with the following directory:
.
├── extension.toml <- similar to a buildpack buildpack.toml
@@ -886,53 +900,27 @@ What are image extensions?
│ ├── detect <- similar to a buildpack ./bin/detect
│ ├── generate <- similar to a buildpack ./bin/build
-- The
extension.toml describes the extension, containing information such as its name, ID, and version.
-./bin/detect is invoked during the detect phase. It analyzes application source code to determine if the extension
+- The
extension.toml provides metadata about the extension, containing information such as its name, ID, and version.
+./bin/detect performs detect. It analyzes application source code to determine if the extension
is needed and contributes build plan entries../bin/generate is invoked during the generate phase (a new lifecycle phase that happens after detect). It
+./bin/generate performs generate (a new lifecycle phase that happens after detect). It
outputs either or both of build.Dockerfile or run.Dockerfile for extending the builder or run image.
+How do they work?
+Each image extension has two jobs to do
+Detect
+The extension determines if it is needed or not.
+Like buildpacks, extensions participate in the detect phase - analyzing application source code to determine if they
+are needed. During detect, extensions can contribute to
+the build plan - recording dependencies that they are able to "
+provide" (though unlike buildpacks, they can’t “require” anything).
+If the provided order contains extensions, the output of detect will be a group of image extensions and a group of
+buildpacks that together produce a valid build plan. Image extensions only generate Dockerfiles - they don’t create
+layers or participate in the build phase.
+Generate
+The extension outputs Dockerfiles that can be used to extend either or both of the build-time base image and the runtime base image.
For more information and to see a build in action,
see authoring an image extension.
-
-Platforms may wish to use image extensions if they wish to provide the flexibility of modifying base images dynamically
-at build time.
-Risks
-Image extensions are considered experimental and susceptible to change in future API versions. However, image extension
-should be used with great care. Platform operators should be mindful that:
-
-- Dockerfiles are very powerful - in fact, you can do anything with a Dockerfile! Introducing image extensions into your
-CNB builds can eliminate the security and compatibility guarantees that buildpacks provide.
-- When Dockerfiles are used to switch the run image from that defined on the provided builder, the resulting run image
-may not have all the mixins required by buildpacks that detected. Platforms may wish to optionally re-validate mixins
-prior to
build when using extensions.
-
-Putting it all together
-The ordering of lifecycle phases looks like the following:
-
-analyzedetect - after standard detection, detect will also run extensions’ ./bin/generate; output Dockerfiles are
-written to a volumerestoreextend - applies one or more build.Dockerfiles to the builder imageextend - applies one or more run.Dockerfiles to the run image (could run in parallel with builder image extension)buildexport
-For more information, consult the migration guide.
-
-Supported:
-
-- pack cli (prefer version
0.30.0 and above)
-
-Needs support:
-
-Your feedback is appreciated! As the feature evolves, we want to hear from you - what’s going well, what’s challenging,
-and anything else you’d like to see. Please reach out in Slack (#buildpacks channel)
-or GitHub.
@@ -942,12 +930,12 @@
- Report Issue
- Edit
diff --git a/docs/for-platform-operators/concepts/index.html b/docs/for-platform-operators/concepts/index.html
index d46e68701..1d8a48ad1 100644
--- a/docs/for-platform-operators/concepts/index.html
+++ b/docs/for-platform-operators/concepts/index.html
@@ -299,6 +299,14 @@
Migrate
@@ -796,14 +814,17 @@
-
Configuration
@@ -851,424 +872,17 @@
Buildpack API
- This specification defines the interface between a buildpack and the environment that runs it.
-This API will be used by buildpack authors.
-A buildpack must contain three files:
-
-buildpack.tomlbin/detectbin/build
-The two files in bin/ must be executable. They can be shell scripts written in a language like Bash or they
-can be executables compiled from a language like Go.
-bin/detect
-Usage
-
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.
-Two environment variables identify important file system paths:
-
-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.
-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, and 100 if it cannot.
-Other exit codes indicate an error during detection.
-Example
-This is a simple example of a buildpack that detects a Python application by
-checking for the presence of a requirements.txt file:
-#!/bin/sh
-
-if [ -f requirements.txt ]; then
- echo "Python Buildpack"
- exit 0
-else
- exit 100
-fi
-
bin/build
-Usage
-bin/build
-
This entrypoint transforms a codebase.
-It will often resolve dependencies, install binary packages, and compile code.
-Three environment variables identify important file system paths:
-
-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.
-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 CNB_LAYERS_DIR.
-Layers
-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 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:
-launch = true
-cache = true
-build = true
-
In this example, the python directory will be included in the run image,
-cached for future builds, and will be accessible to subsequent buildpacks.
-Example
-This is a simple example of a buildpack that runs Python’s pip package manager
-to resolve dependencies:
-#!/bin/sh
-
-PIP_LAYER="$CNB_LAYERS_DIR/pip"
-mkdir -p "$PIP_LAYER/modules" "$PIP_LAYER/env"
-
-pip install -r requirements.txt -t "$PIP_LAYER/modules" \
- --install-option="--install-scripts=$PIP_LAYER/bin" \
- --exists-action=w --disable-pip-version-check --no-cache-dir
-
-echo "launch = true" > "$PIP_LAYER.toml"
-
buildpack.toml
-A buildpack must contain a buildpack.toml file in its root directory.
-Example
-api = "0.10"
-
-[buildpack]
-id = "example.com/python"
-version = "1.0"
-
-# Targets the buildpack will work with
-[[targets]]
-os = "linux"
-
-# Stacks (deprecated) the buildpack will work with
-[[stacks]]
-id = "io.buildpacks.stacks.jammy"
-
Schema
-The schema is as follows:
-
--
-
api (string, required, current: 0.10)
-The Buildpack API version the buildpack adheres to. Used to ensure compatibility against
-the lifecycle.
-
-Not to be confused with Cloud Foundry or Heroku buildpack versions. This version pertains to the interface
-between the buildpack and the lifecycle of Cloud Native Buildpacks.
-
-
--
-
buildpack (required)
-Information about the buildpack.
-
--
-
id (string, required)
-A globally unique identifier.
-
--
-
version (string, required)
-The version of the buildpack.
-
--
-
name (string, required)
-Human readable name.
-
--
-
clear-env (boolean, optional, default: false)
-Clears user-defined environment variables when true on executions of bin/detect and bin/build.
-
--
-
homepage (string, optional)
-Buildpack homepage.
-
--
-
description (string, optional)
-A short description of the buildpack.
-
--
-
keywords (string(s), optional)
-Keywords to help locate the buildpack. These can be useful if publishing to the Buildpack Registry.
-
--
-
sbom-formats (string(s), optional)
-SBOM formats output by the buildpack. Supported values are the following media types: application/vnd.cyclonedx+json, application/spdx+json, and application/vnd.syft+json.
-
--
-
licenses (list, optional)
-A list of licenses pertaining to the buildpack.
-
--
-
type (string, optional)
-The type of the license. This may use the SPDX 2.1 license expression, but it is not limited to identifiers in the SPDX Licenses List. If the buildpack is using a nonstandard license, then the uri key may be specified in lieu of or in addition to type to point to the license.
-
--
-
uri (string, optional)
-A URL or path to the license.
-
-
-
-
-
--
-
targets (list, optional)
-A list of targets supported by the buildpack.
-When no targets are specified, the os/arch will be inferred from the contents of the ./bin directory
-(./bin/build implies linux/amd64 and ./bin/build.bat implies windows/amd64).
-For each target, all fields are optional (though at least one should be provided).
-Cannot be used in conjunction with order list.
-
--
-
os (string, optional)
-The supported operating system name.
-
--
-
arch (string, optional)
-The supported architecture.
-
--
-
variant (string, optional)
-The supported architecture variant.
-
--
-
targets.distros (optional)
-A list of supported distributions for the given operating system, architecture, and architecture variant.
-
--
-
name (string, optional)
-The supported operating system distribution name.
-
--
-
version (string, optional)
-The supported operating system distribution version.
-
-
-
-
-
--
-
stacks (list, deprecated, optional)
-A list of stacks supported by the buildpack.
-Cannot be used in conjunction with order list.
-
--
-
id (string, required)
-The id of the supported stack.
-
--
-
mixins (string list, required)
-A list of mixins required on the stack images.
-
-
-
--
-
order (list, optional)
-A list of buildpack groups for the purpose of creating a meta-buildpack. This list determines the
-order in which groups of buildpacks will be tested during detection. If omitted, targets or stacks list must be present.
-Cannot be used in conjunction with targets or stacks list.
-
-
--
-
metadata (any, optional)
-Arbitrary data for buildpack.
-
-
-Build Plan
-The Build Plan is a document the buildpacks can use to pass information between the detect and build phases. The build plan is passed (by the lifecycle) as a parameter to the detect and build binaries of the buildpack.
-
-- During the
detect phase, the buildpack(s) may write something it requires or provides (or both) into the Build Plan.
-- During the
build phase, the buildpack(s) may read the Buildpack Plan (a condensed version of the Build Plan, composed by the lifecycle) to determine what it should do, and refine the Buildpack Plan with more exact metadata (eg: what version dependency it requires).
-
-A buildpack can require or provide multiple dependencies, and even multiple groupings of dependencies (using or lists). Additionally, multiple buildpacks may require or provide the same dependency.
-The lifecycle uses the Build Plan as one element in deciding whether or not a particular list of buildpacks is appropriate, by seeing whether all dependencies required can be provided by that list.
-Example
-Let’s walk through some possible cases a node-engine buildpack may consider:
-
-- Nothing in the app explicitly calls out that it is needed
-- It is explicitly referred to in some configuration file
-
-We will also consider what a NPM and a JVM buildpack may do.
-1. No Explicit Request
-A node-engine buildpack is always happy to provide the node dependency. The build plan it will write may look something like:
-[[provides]]
-name = "node"
-
-NOTE: If this was the only buildpack running, this would fail the detect phase. In order to pass, every provides must be matched up with a requires, whether in the same buildpack or in another buildpack. See the spec for particulars on how ordering buildpacks can adjust detection results.
-
-2. One Version Requested
-During the detect phase, the node-engine buildpack sees in one configuration file (e.g. a .nvmrc file in the app directory) that node v10.x is explicitly requested by the application. Seeing that, it may write the below text to the build plan:
-[[provides]]
-name = "node"
-
-[[requires]]
-name = "node"
-version = "10.x"
-
-[requires.metadata]
-version-source = ".nvmrc"
-
As always, the buildpack provides node. In this particular case, a version of node (10.x) is being requested in a configuration file (.nvmrc). The buildpack chooses to add an additional piece of metadata (version-source), so that it can understand where that request came from.
-NPM Buildpack
-NPM is the default package manager for node. A NPM Buildpack may ensure that all the packages for the application are present (by running npm install), and perhaps cache those packages as well, to optimize future builds.
-NPM is typically distributed together with node. As a result, a NPM buildpack may require node, but not want to provide it, trusting that the node-engine buildpack will be in charge of providing node.
-The NPM buildpack could write the following to the build plan, if the buildpack sees that npm is necessary (e.g., it sees a package.json file in the app directory):
-[[requires]]
-name = "node"
-
If, looking in the package.json file, the NPM buildpack sees a specific version of node requested in the engines field (e.g. 14.1), it may write the following to the build plan:
-[[requires]]
-name = "node"
-version = "14.1"
-
-[requires.metadata]
-version-source = "package.json"
-
-NOTE: As above, if this was the only buildpack running, this would fail the detect phase. In order to pass, every provides must be matched up with a requires, whether in the same buildpack or in another buildpack. See the spec for particulars on how ordering buildpacks can adjust detection results.
-
-However, if the NPM Buildpack was run together with the Node Engine buildpack (which provides node), the lifecycle will see that all requirements are fulfilled, and select that group as the correct set of buildpacks.
-Possible JVM Buildpack
-Java is distributed in two formats - the jdk (Java Development Kit), which allows for compilation and running of Java programs, and the jre (Java Runtime Environment, which allows for running compiled Java programs). A very naive implementation of the buildpack may have it write several provides options to the build plan, detailing everything that it can provide, while later buildpacks would figure out based on the application which options it requires, and would require those. In this particular case, we can use the or operator to present different possible build plans the buildpack can follow:
-# option 1 (`jre` and `jdk`)
-[[provides]]
-name = "jre"
-
-[[provides]]
-name = "jdk"
-
-# option 2 (or just `jdk`)
-[[or]]
-[[or.provides]]
-name = "jdk"
-
-# option 3 (or just `jre`)
-[[or]]
-[[or.provides]]
-name = "jre"
-
The buildpack gives three options to the lifecycle:
-
-- It can provide a standalone
jre
-- It can provide a standalone
jdk
-- It can provide both the
jdk and jre
-
-As with the other buildpacks, this alone will not be sufficient for the lifecycle. However, other buildpacks that follow may require certain things. For example, another buildpack may look into the application and, seeing that it is a Java executable, require the jre in order to run it. When the lifecycle analyzes the results of the detect phase, it will see that there is a buildpack which provides jre, and a buildpack that requires jre, and will therefore conclude that those options represent a valid set of buildpacks.
-Schema
-
--
-
provides (list, optional)
-A list of dependencies which the buildpack provides.
-
-name (string, required)
-The name of the provided dependency.
-
--
-
requires (list, optional)
-A list of dependencies which the buildpack requires.
-
--
-
name (string, required)
-The name of the required dependency.
-
--
-
version (string, optional)
-The version of the dependency required.
-
--
-
metadata (object, optional)
-Any additional key-value metadata you wish to store.
-
-
-
--
-
or (array, optional)
-A list of alternate requirements which the buildpack provides/requires. Each or array must contain a valid Build Plan (with provides and requires)
-
-
-For more information, see the Build Plan section of the spec.
+ The Buildpack API specifies the interface between a lifecycle program and one or more buildpacks.
API Compatibility
-Given the buildpack and lifecycle both declare a Buildpack API version in format:
-<major>.<minor>
-Then a buildpack and a lifecycle are considered compatible if all the following conditions are true:
-
-- If versions are pre-release, where
<major> is 0, then <minor>s must match.
-- If versions are stable, where
<major> is greater than 0, then <minor> of the buildpack must be less than
-or equal to that of the lifecycle.
-<major>s must always match.
-
-For example,
-
-
-
-| Buildpack implements Buildpack API |
-Lifecycle implements Buildpack API |
-Compatible? |
-
-
-
-
-0.2 |
-0.2 |
-yes |
-
-
-1.1 |
-1.1 |
-yes |
-
-
-1.2 |
-1.3 |
-yes |
-
-
-0.2 |
-0.3 |
-no |
-
-
-0.3 |
-0.2 |
-no |
-
-
-1.3 |
-1.2 |
-no |
-
-
-1.3 |
-2.3 |
-no |
-
-
-2.3 |
-1.3 |
-no |
-
-
-
+A buildpack only ever implements one Buildpack API version at a time.
+The implemented Buildpack API version can be found in the buildpack.toml file in the buildpack’s root directory,
+or in a label on a buildpack package.
+A lifecycle may (and usually does) support more than one Buildpack API version at a time.
+The supported Buildpack API version(s) can be found in the lifecycle.toml file in a lifecycle tarball,
+or in a label on the lifecycle image.
+A lifecycle “supports” a buildpack if they both declare support for the same Buildpack API version in format: <major>.<minor>.
+Two buildpacks of different Buildpack API versions can participate in the same build,
+provided they are both supported by the lifecycle.
Further Reading
You can read the complete Buildpack API specification on Github.
diff --git a/docs/reference/spec/distribution-api/index.html b/docs/reference/spec/distribution-api/index.html
index 7afc89111..b453e8142 100644
--- a/docs/reference/spec/distribution-api/index.html
+++ b/docs/reference/spec/distribution-api/index.html
@@ -301,6 +301,14 @@
