Merge pull request #53 from buildpack/dist-spec-rfc

Distribution Specification

README.md

@@ -22,4 +22,5 @@ An implementation is compliant if it satisfies all the MUST, MUST NOT, REQUIRED,
 ## Sections
 
 - [Buildpack Interface Specification](buildpack.md)
-- [Platform Interface Specification](platform.md)
+- [Platform Interface Specification](platform.md)
+- [Distribution Specification](distribution.md)

buildpack.md

@@ -42,14 +42,12 @@ This is accomplished in two phases:
 10. [Security Considerations](#security-considerations)
     1. [Assumptions of Trust](#assumptions-of-trust)
     2. [Requirements](#requirements)
-11. [Artifact Format](#artifact-format)
-    1. [Buildpack Package](#buildpack-package)
-12. [Data Format](#data-format)
-    1. [buildpack.toml (TOML)](#buildpack.toml-toml)
-    2. [launch.toml (TOML)](#launch.toml-toml)
-    4. [Build Plan (TOML)](#build-plan-toml)
-    5. [Bill-of-Materials (TOML)](#bill-of-materials-toml)
-    6. [Layer Content Metadata (TOML)](#layer-content-metadata-toml)
+11. [Data Format](#data-format)
+    1. [launch.toml (TOML)](#launch.toml-toml)
+    2. [Build Plan (TOML)](#build-plan-toml)
+    3. [Buildpack Plan (TOML)](#buildpack-plan-toml)
+    4. [Bill-of-Materials (TOML)](#bill-of-materials-toml)
+    5. [Layer Content Metadata (TOML)](#layer-content-metadata-toml)
 
 ## Buildpack Interface
 
@@ -93,7 +91,7 @@ Executable: `/bin/build <layers[EIC]> <platform[AR]> <plan[E]>`, Working Dir: `<
 | Input             | Description
 |-------------------|----------------------------------------------
 | `$0`              | Absolute path of `/bin/build` executable
-| `<plan>`          | Relevant Build Plan entries from detection (TOML)
+| `<plan>`          | Relevant [Buildpack Plan entries](#buildpack-plan-toml) from detection (TOML)
 | `<platform>/env/` | User-provided environment variables for build
 | `<platform>/#`    | Platform-specific extensions
 
@@ -102,7 +100,7 @@ Executable: `/bin/build <layers[EIC]> <platform[AR]> <plan[E]>`, Working Dir: `<
 | [exit status]                  | Success (0) or failure (1+)
 | `/dev/stdout`                  | Logs (info)
 | `/dev/stderr`                  | Logs (warnings, errors)
-| `<plan>`                       | Refinements to the Build Plan (TOML)
+| `<plan>`                       | Refinements to the [Buildpack Plan]((#buildpack-plan-toml)) (TOML)
 | `<layers>/launch.toml`         | App metadata (see [launch.toml](#launch.toml-toml))
 | `<layers>/store.toml`          | Persistent metadata (see [store.toml](#store.toml-toml))
 | `<layers>/<layer>.toml`        | Layer metadata (see [Layer Content Metadata](#layer-content-metadata-toml))
@@ -123,7 +121,7 @@ Executable: `/bin/develop <layers[EC]> <platform[AR]> <plan[E]>`, Working Dir: `
 | Input             | Description
 |-------------------|----------------------------------------------
 | `$0`              | Absolute path of `/bin/detect` executable
-| `<plan>`          | Build plan from detection (TOML)
+| `<plan>`          | Relevant [Buildpack Plan entries](#buildpack-plan-toml) from detection (TOML)
 | `<platform>/env/` | User-provided environment variables for build
 | `<platform>/#`    | Platform-specific extensions
 
@@ -132,7 +130,7 @@ Executable: `/bin/develop <layers[EC]> <platform[AR]> <plan[E]>`, Working Dir: `
 | [exit status]                  | Success (0) or failure (1+)
 | `/dev/stdout`                  | Logs (info)
 | `/dev/stderr`                  | Logs (warnings, errors)
-| `<plan>`                       | Refinements to the Build Plan (TOML)
+| `<plan>`                       | Refinements to the [Buildpack Plan]((#buildpack-plan-toml)) (TOML)
 | `<layers>/launch.toml`         | App metadata (see [launch.toml](#launch.toml-toml))
 | `<layers>/store.toml`          | Persistent metadata (see [store.toml](#store.toml-toml))
 | `<layers>/<layer>.toml`        | Layer metadata (see [Layer Content Metadata](#layer-content-metadata-toml))
@@ -218,7 +216,7 @@ These buildpacks must be compatible with the app.
 ### Process
 
 **GIVEN:**
-- An ordered list of ordered buildpack groups and
+- An ordered list of buildpack groups resolved into buildpack implementations as described in the [Distribution Specification](distribution.md) and
 - A directory containing application source code,
 
 For each buildpack in each group in order, the lifecycle MUST execute `/bin/detect`.
@@ -313,13 +311,13 @@ The purpose of build is to transform application source code into runnable artif
 
 During the build phase, typical buildpacks might:
 
-1. Read the Build Plan in `<plan>` to determine what dependencies to provide.
+1. Read the Buildpack Plan in `<plan>` to determine what dependencies to provide.
 2. Provide the application with dependencies for launch in `<layers>/<layer>`.
 3. Provide subsequent buildpacks with dependencies in `<layers>/<layer>`.
 4. Compile the application source code into object code.
 5. Remove application source code that is not necessary for launch.
 6. Provide start command in `<layers>/launch.toml`.
-7. Refine the Build Plan in `<plan>` with more exact metadata.
+7. Refine the Buildpack Plan in `<plan>` with more exact metadata.
 
 The purpose of separate `<layers>/<layer>` directories is to:
 
@@ -338,7 +336,7 @@ This is achieved by:
 **GIVEN:**
 - The final ordered group of buildpacks determined during the detection phase,
 - A directory containing application source code,
-- The Build Plan,
+- The Buildpack Plan,
 - Any `<layers>/<layer>.toml` files placed on the filesystem during the analysis phase,
 - Any locally cached `<layers>/<layer>` directories, and
 - Bash version 3 or greater, if needed,
@@ -365,10 +363,10 @@ Correspondingly, each `/bin/build` executable:
 
 - MAY read or write to the `<app>` directory.
 - MAY read the build environment as described in the [Environment](#environment) section.
-- MAY read the Build Plan.
-- MAY augment the Build Plan with more refined metadata.
-- MAY remove entries with duplicate names in the Build Plan to refine the metadata.
-- MAY remove all entries of the same name from the Build Plan to defer those entries to subsequent `/bin/build` executables.
+- MAY read the Buildpack Plan.
+- MAY augment the Buildpack Plan with more refined metadata.
+- MAY remove entries with duplicate names in the Buildpack Plan to refine the metadata.
+- MAY remove all entries of the same name from the Buildpack Plan to defer those entries to subsequent `/bin/build` executables.
 - MAY log output from the build process to `stdout`.
 - MAY emit error, warning, or debug messages to `stderr`.
 - MAY write a list of possible commands for launch to `<layers>/launch.toml`.
@@ -381,7 +379,7 @@ Correspondingly, each `/bin/build` executable:
 - MAY name any new `<layers>/<layer>` directories without restrictions except those imposed by the filesystem.
 - SHOULD NOT use the `<app>` directory to store provided dependencies.
 
-#### Build Plan Entry Refinements
+#### Buildpack Plan Entry Refinements
 
 A buildpack MAY refine entries in `<plan>` by replacing any entries of the same name with a single entry of that name.
 The single entry MAY include additional metadata that could not be determined during the detection phase.
@@ -548,7 +546,7 @@ The purpose of development setup is to create a containerized environment for de
 
 During the development setup phase, typical buildpacks might:
 
-1. Read the Build Plan to determine what dependencies to provide.
+1. Read the Buildpack Plan to determine what dependencies to provide.
 2. Provide dependencies in `<layers>/<layer>` for development commands and for subsequent buildpacks.
 3. Provide a command to start a development server in `<layers>/launch.toml`.
 4. Provide a command to run a test suite in `<layers>/launch.toml`.
@@ -558,7 +556,7 @@ During the development setup phase, typical buildpacks might:
 **GIVEN:**
 - The final ordered group of buildpacks determined during the detection phase,
 - A directory containing application source code,
-- A Build Plan processed by previous `/bin/detect` and `/bin/develop` executions,
+- The Buildpack Plan,
 - The most recent local cached `<layers>/<layer>/` directories from a development setup of a version of the application source code, and
 - Bash version 3 or greater,
 
@@ -585,10 +583,10 @@ Correspondingly, each `/bin/develop` executable:
 - MAY read from the app directory.
 - MAY write files to the app directory in an idempotent manner.
 - MAY read the build environment as described in the [Environment](#environment) section.
-- MAY read the Build Plan.
-- MAY augment the Build Plan with more refined metadata.
-- MAY remove entries with duplicate names in the Build Plan to refine the metadata.
-- MAY remove all entries of the same name from the Build Plan to defer those entries to subsequent `/bin/develop` executables.
+- MAY read the Buildpack Plan.
+- MAY augment the Buildpack Plan with more refined metadata.
+- MAY remove entries with duplicate names in the Buildpack Plan to refine the metadata.
+- MAY remove all entries of the same name from the Buildpack Plan to defer those entries to subsequent `/bin/develop` executables.
 - MAY log output from the build process to `stdout`.
 - MAY emit error, warning, or debug messages to `stderr`.
 - MAY write a list of possible commands for launch to `<layers>/launch.toml`.
@@ -601,7 +599,7 @@ Correspondingly, each `/bin/develop` executable:
 - SHOULD NOT use the `<app>` directory to store provided dependencies.
 - SHOULD NOT specify any slices within `launch.toml`, as they are only used to generate OCI image layers.
 
-#### Build Plan Entry Refinements
+#### Buildpack Plan Entry Refinements
 
 A buildpack MAY refine entries in `<plan>` by replacing any entries of the same name with a single entry of that name.
 The single entry MAY include additional metadata that could not be determined during the detection phase.
@@ -635,7 +633,9 @@ To decide what layer operations are appropriate, the buildpack should consider:
 
 ### Provided by the Lifecycle
 
-The following environment variables MUST be set by the lifecycle during the build and launch phases in order to make buildpack dependencies accessible.
+#### 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.
 
 During the build phase, each variable designated for build MUST contain absolute paths of all previous buildpacks’ `<layers>/<layer>/` directories that are designated for build.
 
@@ -754,54 +754,6 @@ Prohibited:
 The lifecycle MUST be implemented so that the detection and build phases do not have access to OCI image store credentials used in the analysis and export phases.
 The lifecycle SHOULD be implemented so that each phase may run in a different container.
 
-## Artifact Format
-
-### Buildpack Package
-
-Buildpacks SHOULD be packaged as gzip-compressed tarballs with extension `.tgz`.
-
-Buildpacks MUST:
-- Contain `/buildpack.toml` and `/bin/detect`.
-- Contain one or both of `/bin/build` and `/bin/develop`.
-
-## Data Format
-
-### buildpack.toml (TOML)
-
-```toml
-[buildpack]
-id = "<buildpack ID>"
-name = "<buildpack name>"
-version = "<buildpack version>"
-
-[[stacks]]
-id = "<stack ID>"
-mixins = ["<mixin name>"]
-build-images = ["<build image tag>"]
-run-images = ["<run image tag>"]
-
-[metadata]
-# buildpack-specific data
-```
-
-Buildpack authors MUST choose a globally unique ID, for example: "io.buildpacks.ruby".
-
-The buildpack ID:
-- MUST only contain numbers, letters, and the characters `.`, `/`, and `-`.
-- MUST NOT be `config` or `app`.
-- MUST NOT be identical to any other buildpack ID when using a case-insensitive comparison.
-
-The buildpack version:
-- MUST NOT be `latest`.
-
-Stack authors MUST choose a globally unique ID, for example: "io.buildpacks.mystack".
-
-The stack ID:
-- MUST only contain numbers, letters, and the characters `.`, `/`, and `-`.
-- MUST NOT be identical to any other stack ID when using a case-insensitive comparison.
-
-The stack `build-images` and `run-images` are suggested sources of images for platforms that are unaware of the stack ID. Buildpack authors MUST ensure that these images include all mixins specified in `mixins`.
-
 ### launch.toml (TOML)
 
 ```toml
@@ -876,6 +828,17 @@ version = "<dependency version>"
 
 ```
 
+### Buildpack Plan (TOML)
+
+```toml
+[[entries]]
+name = "<dependency name>"
+version = "<dependency version>"
+
+[entries.metadata]
+# buildpack-specific data
+```
+
 ### Bill-of-Materials (TOML)
 
 ```toml
@@ -886,7 +849,6 @@ version = "<dependency version>"
 [[entries.buildpacks]]
 id = "<buildpack ID>"
 version = "<buildpack version>"
-optional = false
 
 [entries.metadata]
 # buildpack-specific data