Merge pull request #300 from buildpacks/buildpack-terminology

Add terminology section to the buildpack spec

buildpack.md

@@ -2,17 +2,6 @@
 
 This document specifies the interface between a lifecycle program and one or more buildpacks.
 
-The lifecycle program uses buildpacks to build software artifacts from source code and pack the result into an OCI image.
-
-This is accomplished in four phases:
-
-1. **Detection,** where an optimal selection of compatible buildpacks is chosen.
-2. **Analysis,** where metadata about OCI layers generated during a previous build are made available to buildpacks.
-3. **Build,** where buildpacks use that metadata to generate only the OCI layers that need to be replaced.
-4. **Export,** where the remote layers are replaced by the generated layers.
-
-The `ENTRYPOINT` of the OCI image contains logic implemented by the lifecycle that executes during the **Launch** phase.
-
 ## Table of Contents
 
 <!-- Using https://github.com/yzhang-gh/vscode-markdown to manage toc -->
@@ -75,8 +64,8 @@ The `ENTRYPOINT` of the OCI image contains logic implemented by the lifecycle th
     - [Buildpack Plan (TOML)](#buildpack-plan-toml)
     - [Layer Content Metadata (TOML)](#layer-content-metadata-toml)
     - [buildpack.toml (TOML)](#buildpacktoml-toml)
-      - [Buildpack Implementations](#buildpack-implementations)
-      - [Order Buildpacks](#order-buildpacks)
+      - [Stacks](#stacks)
+      - [Order](#order)
     - [Exec.d Output (TOML)](#execd-output-toml)
   - [Deprecations](#deprecations)
     - [`0.3`](#03)
@@ -90,15 +79,61 @@ Buildpack API versions:
  - `<major>` and `<minor>` MUST only contain numbers (unsigned 64 bit integer)
  - When `<major>` is greater than `0` increments to `<minor>` SHALL exclusively indicate additive changes
 
+## Terminology
+
+### CNB Terminology
+
+A **buildpack** is a directory containing a `buildpack.toml`. A buildpack analyzes application source code and determines the best way to build it.
+
+A **buildpack group**, or **group**, is a list of one or more buildpacks that are designed to work together - for example, a buildpack that provides `node` and a buildpack that provides `npm`.
+
+An **order** is a list of one or more groups to be tested against application source code, so that the appropriate group for a build can be determined. 
+
+A **component buildpack** is a buildpack containing `/bin/detect` and `/bin/build` executables. Component buildpacks implement the [Buildpack Interface](#buildpack-interface).
+
+A **composite buildpack** is a buildpack containing an order definition in `buildpack.toml`. Composite buildpacks do not contain `/bin/detect` or `/bin/build` executables. They MUST be [resolvable](#order-resolution) into a collection of component buildpacks.
+
+**Resolving an order** is the process by which an order (which may contain composite buildpacks) is evaluated together with application source code to produce a group of component buildpacks that can be used to build the application. This process is known as **detection**. During detection, the `/bin/detect` executable for each component buildpack is invoked.
+
+An **optional buildpack** is a buildpack (either component or composite) that, when failing detection, will be excluded from the group without causing the entire group to fail.
+
+A **build plan** is a file used during detection, in which each component buildpack may express the dependencies that it requires and the dependencies that it provides. A group of component buildpacks will only pass detection if a valid build plan can be produced from the dependencies that all component buildpacks in the group require and provide. A valid build plan is a plan where all required dependencies are provided in the necessary order, meaning that during the build phase, each component buildpack will have its required dependencies provided by a component buildpack that runs before it.
+
+A **buildpack plan** is a file unique to each component buildpack, used during the build phase to communicate the dependencies that the component buildpack is expected to provide.
+
+A **lifecycle** is software that orchestrates a build. It executes in a series of phases that each have a distinct responsibility.
+
+A **launcher** is an executable that is the `ENTRYPOINT` of the exported OCI image. It is used to start processes at runtime. Having a launcher enables multiple process types to be defined on an image, with process-specific environment variables and other functionality.
+
+**Launch** describes the process of running an application by creating a container from the exported OCI image.
+
+A **platform** is a system or software that orchestrates the lifecycle by invoking each lifecycle phase in order.
+
+A **process definition** is a description, provided by component buildpacks during the build phase, of a process to launch at runtime.
+
+An **application directory** is a directory containing application source code. Component buildpacks may make changes to the application directory during the build phase.
+
+A **layer** is a set of filesystem changes packaged according to the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/layer.md).
+
+A **layer directory** is a directory created by a component buildpack that contains build and/or runtime dependencies, and can be used to configure the build and/or runtime environment. There are three **layer types**:
+  * a **launch layer** is added as a layer in the exported OCI image; it can be re-used on the next build (the lifecycle can avoid re-uploading it) if the component buildpack that created the layer has the same requirements on the next build
+  * a **cache layer** is saved to the cache and its contents may be restored on the next build
+  * a **build layer** contains child directories with paths that are added to the environment (e.g., `PATH`, `LD_LIBRARY_PATH`, etc.) for subsequent buildpacks in the same build
+Any combination of the three layer types are valid for a particular layer directory.
+
+A **stack** is a contract, implemented by a **build image** and **run image**, that guarantees properties of the **build environment** and **app image**. The provided stack is communicated to component buildpacks through the `CNB_STACK_ID` environment variable, enabling each component buildpack to modify its behavior when executed on different stacks.
+
+A **mixin** is a named set of additions to a stack that can be used to make additive changes to the contract. Buildpacks can express their required mixins in `buildpack.toml`.
+
 ## Buildpack Interface
 
-The following specifies the interface implemented by executables in each buildpack.
-The lifecycle MUST invoke these executables as described in the Phase sections.
+The following specifies the interface implemented by component buildpacks.
+The lifecycle MUST invoke executables in component buildpacks as described in the Phase sections.
 
 ### Buildpack API Compatibility
 Given a buildpack declaring `<buildpack API Version>` in its [`buildpack.toml`](#buildpacktoml-toml), the lifecycle:
 - MUST either conform to the matching version of this specification when interfacing with the buildpack or
-- return an error to the platform if it does not support `<buildpack API Version>`
+- MUST return an error to the platform if it does not support `<buildpack API Version>`
 
 The lifecycle MAY return an error to the platform if two or more buildpacks within a group declare buildpack API versions that the lifecycle cannot support together within a single build, even if both are supported independently.
 
@@ -134,7 +169,6 @@ Executable: `/bin/detect`, Working Dir: `<app[AR]>`
 | Standard error         | Logs (warnings, errors)                     |
 | `$CNB_BUILD_PLAN_PATH` | Contributions to the the Build Plan (TOML)  |
 
-
 ###  Build
 
 Executable: `/bin/build`, Working Dir: `<app[AI]>`
@@ -297,13 +331,13 @@ At the end of each individual buildpack's build phase:
 
 ### Purpose
 
-The purpose of detection is to find an ordered group of buildpacks to use during the build phase.
+The purpose of detection is to find an ordered group of component buildpacks to use during the build phase.
 These buildpacks must be compatible with the app.
 
 ### Process
 
 **GIVEN:**
-- An ordered list of buildpack groups resolved into buildpack implementations as described in [Order Resolution](#order-resolution)
+- An ordered list of buildpack groups resolved into component buildpacks as described in [Order Resolution](#order-resolution)
 - A directory containing application source code
 
 For each buildpack in each group in order, the lifecycle MUST execute `/bin/detect`.
@@ -368,13 +402,13 @@ A buildpack's mixin requirements must be satisfied by the stack in one of the fo
 
 #### Order Resolution
 
-During detection, an order definition MUST be resolved into individual buildpack implementations.
+During detection, an order definition MUST be resolved into individual component buildpacks.
 
 The resolution process MUST follow this pattern:
 
 Where:
 - O and P are buildpack orders.
-- A through H are buildpack implementations.
+- A through H are component buildpacks.
 
 Given:
 
@@ -428,7 +462,7 @@ If a buildpack order entry within a group has the parameter `optional = true`, t
 
 ### Purpose
 
-The purpose of analysis is to restore `<layers>/<layer>.toml`, `<layers>/<layer>.sbom.<ext>`, and `<layers>/store.toml` files that buildpacks may use to optimize the build and export phases.
+The purpose of analysis is to restore `<layers>/<layer>.toml`, `<layers>/<layer>.sbom.<ext>`, and `<layers>/store.toml` files that component buildpacks may use to optimize the build and export phases.
 
 ### Process
 
@@ -457,9 +491,9 @@ After analysis, the lifecycle MUST proceed to the build phase.
 
 ### Purpose
 
-The purpose of build is to transform application source code into runnable artifacts that can be packaged into a container.
+The purpose of build is to transform application source code into runnable artifacts that can be packaged into a container image.
 
-During the build phase, typical buildpacks might:
+During the build phase, typical component buildpacks might:
 
 1. Read the Buildpack Plan in `<plan>` to determine what dependencies to provide.
 1. Provide the application with dependencies for launch in `<layers>/<layer>`.
@@ -844,7 +878,7 @@ working-dir = "<working directory>"
 paths = ["<app sub-path glob>"]
 ```
 
-The buildpack MAY specify any number of labels, processes, or slices.
+The component buildpack MAY specify any number of labels, processes, or slices.
 
 For each label, the buildpack:
 
@@ -896,7 +930,7 @@ The lifecycle MUST include all unmatched files in the app directory in any numbe
 name = "<dependency name>"
 ```
 
-For each unmet entry in the Buildpack Plan, the buildpack:
+For each unmet entry in the Buildpack Plan, the component buildpack:
 - SHOULD add an entry to `unmet`.
 
 For each entry in `unmet`:
@@ -961,7 +995,6 @@ For a given layer, the buildpack MAY specify:
 - Whether the layer is cached, intended for build, and/or intended for launch.
 - Metadata that describes the layer contents.
 
-
 ### buildpack.toml (TOML)
 This section describes the 'Buildpack descriptor'.
 
@@ -1031,9 +1064,9 @@ The `[[buildpack.licenses]]` table is optional and MAY contain a list of buildpa
 *Key: `sbom-formats = [ "<string>" ]`*
  - MUST be supported SBOM media types as described in [Software-Bill-of-Materials](#software-bill-of-materials).
 
-#### Buildpack Implementations
+#### Stacks
 
-A buildpack descriptor that specifies `stacks` MUST describe a buildpack that implements the [Buildpack Interface](#buildpack-interface).
+A buildpack descriptor may specify `stacks`.
 
 Each stack in `stacks` either:
 - MUST identify a compatible stack:
@@ -1043,9 +1076,7 @@ Each stack in `stacks` either:
    - `id` MUST be set to the special value `"*"`.
    - `mixins` MUST be empty.
 
-#### Order Buildpacks
-
-A buildpack descriptor that specifies `order` MUST be [resolvable](#order-resolution) into an ordering of buildpacks that implement the [Buildpack Interface](#buildpack-interface).
+#### Order
 
 A buildpack reference inside of a `group` MUST contain an `id` and `version`.