Expand buildpack author concepts pages

content/docs/for-buildpack-authors/concepts/build-plan.md

@@ -3,8 +3,56 @@ title="What is the build plan?"
 weight=99
 +++
 
+A **build plan** is a `toml` file that is the output of the [detect](https://buildpacks.io/docs/for-buildpack-authors/concepts/lifecycle-phases/#phase-2-detect) phase, in which each component buildpack or image extension may express the dependencies it requires and the dependencies it provides.
+
 <!--more-->
 
-This page is a stub! The CNB project is applying to [Google Season of Docs](https://developers.google.com/season-of-docs/docs/timeline) to receive support for improving our documentation. Please check back soon.
+Before we dive into more details, let's explain the difference between three terms relevant to the concept of `build plan`.
+
+* First, the [build plan](https://github.com/buildpacks/spec/blob/main/buildpack.md#build-plan-toml) piece that is contributed by the buildpack during the `detect` phase. This piece is seen as the `build plan` from buildpack's perspective and is written to a temporary directory by the buildpack.
+
+* Second, the concatenation of all buildpacks contributions that passed `detect`, which is considered the true [build plan](https://github.com/buildpacks/spec/blob/main/platform.md#plantoml-toml) from the platform's perspective. This file usually gets written to the `<layers>` directory—unless the platform provided another path for it.
+
+* Finally, the build plan piece that is shown to the buildpack during the `build` phase that is referred to as the [buildpack plan](https://github.com/buildpacks/spec/blob/main/buildpack.md#buildpack-plan-toml). This file only contains dependencies that a buildpack is responsible for providing; however a buildpack may choose NOT to provide any of these dependencies, leaving that work for a future buildpack. The `buildpack plan` file is usually written to a temporary directory by the `lifecycle`.
+
+## Example Build Plan (toml)
+
+In order to make contributions to the `Build Plan`, a `/bin/detect` executable MUST write entries to `<plan>` in two sections: `requires` and `provides`. The generated `plan.toml` file is usually added under the `<layers>`directory.
+The `requires` and `provides` sections MAY be repeated together inside of an `or` array at the top-level.  
+Each `requires` and `provides` section MUST be a list of entries formatted as shown below:
+
+```toml
+[[provides]]
+name = "<dependency name>"
+
+[[requires]]
+name = "<dependency name>"
+
+[requires.metadata]
+# buildpack-specific data
+
+[[or]]
+
+[[or.provides]]
+name = "<dependency name>"
+
+[[or.requires]]
+name = "<dependency name>"
+
+[or.requires.metadata]
+# buildpack-specific data
+
+```  
+
+## Key Points
+
+* 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 component buildpack or an image extension that runs before it.
+* Each pairing of `requires` and `provides` sections (at the top level, or inside of an `or` array) is a potential build plan. For more details, see the [JVM buildpack](https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/use-build-plan/#example-jvm-buildpack) example.
+* A group will only pass detection if a valid build plan can be produced from the dependencies that all elements in the group require and provide.
+* The `detect` phase could fail if a buildpack requires a dependency that it does not itself provide, or is not provided by another buildpack.
+* The `detect` phase could also fail when the buildpacks order is incorrect, i.e, the buildpacks providing dependencies run `after` the buildpacks requiring them.
+* The resulting `build plan` is passed as one of the inputs to the `build` phase.
+
+## Resources
 
-If you are familiar with this content and would like to make a contribution, please feel free to open a PR :)
+For further examples and guidance on using the build plan, see the [how-to page]( https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/use-build-plan/).

content/docs/for-buildpack-authors/concepts/buildpack-group.md

@@ -1,4 +1,3 @@
-
 +++
 title="What is a buildpack group?"
 aliases=[
@@ -7,7 +6,7 @@ aliases=[
 weight=2
 +++
 
-A buildpack group is a list of individual buildpacks that are designged to work together to build an application.
+A buildpack group is a list of individual buildpacks that are designed to work together to build an application.
 
 <!--more-->
 
@@ -58,4 +57,4 @@ The [Operator's Guide][operator-guide] has more information on creating builders
 [order-resolution]: https://github.com/buildpacks/spec/blob/main/buildpack.md#order-resolution
 [operator-guide]: /docs/for-platform-operators/
 [builder]: /docs/for-platform-operators/concepts/builder/
-[composite buildpack]: /docs/for-platform-operators/concepts/composite-buildpack
+[composite buildpack]: /docs/for-buildpack-authors/concepts/composite-buildpack

content/docs/for-buildpack-authors/concepts/caching-strategies.md

@@ -1,4 +1,3 @@
-
 +++
 title="What caching strategies are available to buildpacks?"
 aliases=[
@@ -8,7 +7,7 @@ weight=4
 summary="Learn strategies for caching layers at build-time for future re-use."
 +++
 
-# Layers
+## Layers
 
 There are three types of layers that can be contributed to an image
 
@@ -18,7 +17,7 @@ There are three types of layers that can be contributed to an image
 
 In this section we look at caching each layer type.
 
-## Layer Metadata
+### Layer Metadata
 
 buildpacks ensure byte-for-byte reproducibility of layers.  File creation time is [normalized to January 1, 1980](https://medium.com/buildpacks/time-travel-with-pack-e0efd8bf05db) to ensure reproducibility.  Byte-for-byte reproducibility means previous layers can be reused.  However, we may want to invalidate previously cached layers if an important property changes, such as:
 
@@ -27,7 +26,7 @@ buildpacks ensure byte-for-byte reproducibility of layers.  File creation time i
 
 Launch layers are exported to an OCI registry.  The layer metadata is commonly used when deciding if a launch layer should be re-used.  A launch layer may be re-used on an OCI registry without downloading the layer to the machine running a build.
 
-## Caching Strategies
+### Caching Strategies
 
 Caching during the production of an application image is necessarily very flexible.  Most buildpacks that wish to contribute a layer to the application image need only to
 

content/docs/for-buildpack-authors/concepts/component-buildpack.md

@@ -3,8 +3,22 @@ title="What is a component buildpack?"
 weight=99
 +++
 
+A **component buildpack** is a buildpack containing `/bin/detect` and `/bin/build` executables and that implements the [Buildpack Interface](https://github.com/buildpacks/spec/blob/main/buildpack.md#buildpack-interface).
+
 <!--more-->
 
-This page is a stub! The CNB project is applying to [Google Season of Docs](https://developers.google.com/season-of-docs/docs/timeline) to receive support for improving our documentation. Please check back soon.
+## Key Points
+
+During the `build` phase, typical component buildpacks might perform one, or more, of the following actions:
 
-If you are familiar with this content and would like to make a contribution, please feel free to open a PR :)
+* Read the [Buildpack Plan](https://buildpacks.io/docs/for-buildpack-authors/concepts/build-plan/) in `<plan>` to determine what dependencies to provide
+* Supply the application with [dependencies](https://buildpacks.io/docs/for-buildpack-authors/concepts/layer/) for launch in `<layers>/<layer>`
+* Reuse application [dependencies](https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/re-use-layers/) from a previous image by appending `[types]` and `launch = true` to `<layers>/<layer>.toml`
+* Contribute [dependencies](https://buildpacks.io/docs/for-buildpack-authors/concepts/layer/) added in `<layers>/<layer>` to subsequent buildpacks  
+* Reuse [cached build dependencies](https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/create-layer/) from a previous build by appending `[types]`, `build = true` and `cache = true` to `<layers>/<layer>.toml`
+* Compile the application source code into object code
+* Remove application source code that is not necessary for launch
+* Supply start command in `<layers>/launch.toml`
+* Write a partial [Software Bill of Materials](https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/add-sbom/) to `<layers>/<layer>.sbom.<ext>` describing any dependencies provided in the layer
+* Write a partial [Software Bill of Materials](https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/add-sbom/) to `<layers>/launch.sbom.<ext>` describing any provided application dependencies not associated with a layer
+* Write a partial [Software Bill of Materials](https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/add-sbom/) to `<layers>/build.sbom.<ext>` describing any provided build dependencies not associated with a layer

content/docs/for-buildpack-authors/concepts/layer.md

@@ -3,8 +3,41 @@ title="What is a buildpack dependency layer?"
 weight=99
 +++
 
+`Dependency layers` are semantically meaningful layers that are contributed by one or more buildpacks during the `build` phase, one for each dependency.
+
 <!--more-->
 
-This page is a stub! The CNB project is applying to [Google Season of Docs](https://developers.google.com/season-of-docs/docs/timeline) to receive support for improving our documentation. Please check back soon.
+To better understand dependency layers and how they fit into the larger picture, it's helpful to understand the concept of an `OCI image layer`.
+
+At a high level,  an `OCI image layer` can be seen as a [filesystem changeset](https://github.com/opencontainers/image-spec/blob/main/layer.md) and some accompanying metadata. The ordering of layers is usually important for OCI images; however this is not the case for buildpack contributed layers.
+
+From a buildpack author's perspective, it is helpful to know that the directories created would be mapped to OCI image layers.That being said, the following are different types of layers created when building with buildpacks:
+
+* Base image layers ([build](https://buildpacks.io/docs/for-app-developers/concepts/base-images/build/) and [run](https://buildpacks.io/docs/for-app-developers/concepts/base-images/run/)), which are the layers that make up the underlying OS for the `build-time` container and the `runtime` container, respectively.
+* Buildpack-contributed dependency layers, which contain application dependencies, such as language runtime & libraries.
+* Application layer(s), which can be thought of as transformation of the application source code into a compiled executable. It's possible to divide an application into several layers—[slices](https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/create-slice-layers/)—in order to make updates faster.
+* Finally, CNB-contributed layers, such as the `SBOM`, the `launcher` executable, and some configuration for the `launcher`.
+
+Buildpack authors don’t usually have control over the first and last layers added above. However, an ultimate goal for most buildpack authors is keeping layers small, which creates reusable and composable layers. This reduces duplication in what buildpack authors need to maintain and minimizes data transfer to/from the `registry` when builds are rerun.
+
+![builder](/images/builder.svg)
+
+Going back to the concept of `dependency layers` and as seen in the image above, buildpacks read application source code and create dependency layers. Each buildpack can contribute a subset of an app's required dependencies, added as subdirectories under the `CNB_LAYERS_DIR` directory. These dependencies are then exported as layers in the final app image or build cache.
+
+The `build` phase runs the `/bin/build` binary of each buildpack, which outputs zero or more layers into `$(CNB_LAYERS_DIR)/<buildpack-id>` and writes metadata for each layer as `toml` files in that directory. During the `export` phase, all layers created by the buildpacks are either cached or added to the output application image.
+
+The following shows an example filesystem tree created after the `build` phase is complete:
+
+```text
+
+layers/
+├── buildpack-1-id
+│   ├── layer-1
+│   ├── layer-1.toml
+│   ├── layer-2
+│   └── layer-2.toml
+└── buildpack-2-id
+
+```
 
-If you are familiar with this content and would like to make a contribution, please feel free to open a PR :)
+> For more information about creating `dependency layers`, see [Create dependency layers](https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/create-layer/)

content/docs/for-buildpack-authors/concepts/lifecycle-phases.md

@@ -1,4 +1,3 @@
-
 +++
 title="What is the lifecycle?"
 aliases=[

content/docs/for-buildpack-authors/concepts/package.md

@@ -3,8 +3,10 @@ title="What is a buildpack package?"
 weight=99
 +++
 
+A `buildpack package` refers to the process of packaging buildpacks for distribution as OCI images or OCI-compatible `tar` files.
+
 <!--more-->
 
-This page is a stub! The CNB project is applying to [Google Season of Docs](https://developers.google.com/season-of-docs/docs/timeline) to receive support for improving our documentation. Please check back soon.
+A `buildpack package` typically encapsulates the scripts, required dependencies, and metadata needed to transform application source code into a fully operational application within a specific platform's runtime environment.
 
-If you are familiar with this content and would like to make a contribution, please feel free to open a PR :)
+For more information about packaging a buildpack, see [Package a buildpack or extension](https://buildpacks.io/docs/for-buildpack-authors/how-to/distribute-buildpacks/package-buildpack/).

content/docs/for-buildpack-authors/concepts/targets.md

@@ -1,4 +1,3 @@
-
 +++
 title="What are targets?"
 aliases=[
@@ -12,6 +11,7 @@ The concept of `targets` is used to identify compatibility between buildpacks an
 <!--more-->
 
 Target data includes:
+
 * Operating system name (e.g., "linux")
 * Architecture (e.g., "amd64", "arm64")
 * Architecture variant
@@ -25,6 +25,7 @@ Buildpacks may declare the targets they are compatible with in `buildpack.toml`.
 This information will be used by `pack` (or other platforms) and the lifecycle to avoid running buildpacks on images they aren't designed to work with.
 
 Additionally, during builds this information will be read by the lifecycle from the run image and exposed to buildpacks through `CNB_TARGET_` environment variables:
+
 * `CNB_TARGET_OS`
 * `CNB_TARGET_ARCH`
 * `CNB_TARGET_ARCH_VARIANT`

content/docs/for-buildpack-authors/how-to/write-buildpacks/use-build-plan.md

@@ -3,7 +3,7 @@ title="Use the build plan"
 weight=2
 +++
 
-The [Build Plan](https://github.com/buildpacks/spec/blob/main/buildpack.md#build-plan-toml) is a document that buildpacks can use to pass information between the `detect` and `build` phases, and between each other.
+The [Build Plan](https://buildpacks.io/docs/for-buildpack-authors/concepts/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.
 
 <!--more-->
@@ -24,25 +24,28 @@ Let's see how this works with an example.
 
 Let's walk through some possible cases a `node-engine` buildpack may consider:
 
-1.  Nothing in the app explicitly calls out that it is needed
-2.  It is explicitly referred to in some configuration file
+1. Nothing in the app explicitly calls out that it is needed
+2. 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:
-```
+
+```toml
 [[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](https://github.com/buildpacks/spec/blob/main/buildpack.md#phase-1-detection) 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:
-```
+
+```toml
 [[provides]]
 name = "node"
 
@@ -63,13 +66,15 @@ As always, the buildpack `provides` `node`. In this particular case, a version o
 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):
-```
+
+```toml
 [[requires]]
 name = "node"
 ```
 
 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:
-```
+
+```toml
 [[requires]]
 name = "node"
 version = "14.1"
@@ -90,7 +95,7 @@ A very naive implementation of the buildpack may have it write several `provides
 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:
 
-```
+```toml
 # option 1 (`jre` and `jdk`)
 [[provides]]
 name = "jre"
@@ -110,6 +115,7 @@ 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`

content/docs/for-buildpack-authors/how-to/write-buildpacks/use-exec.d.md

@@ -15,7 +15,7 @@ The [buildpacks `exec.d` interface](https://github.com/buildpacks/spec/blob/main
     * **Inputs**
         * A third open file descriptor. File descriptors are integers used by a process to uniquely identify opened files; pre-opened file descriptors are usually `0` for `stdin`, `1` for `stdout` and `2` for `stderr`. The third open file descriptor is inherited from the calling process.  
     * **Outputs**
-        * Valid TOML describing environment variables in the form of key=value pairs. These variables are added to the application's runtime environment. The content should be written to file descriptor 3 (see examples for how to do this).
+        * Valid TOML describing environment variables in the form of `key="value"` pairs. These variables are added to the application's runtime environment. The content should be written to file descriptor 3 (see examples for how to do this).
         * Exit Code: The scripts should exit with a status code of `0` to indicate success. A non-zero exit code will indicate an error and prevent the application from launching.
 
 ## Use Cases