From 6dd6a10a2dd2c874ed3c2e90570b5861f5758767 Mon Sep 17 00:00:00 2001 From: Hanan Younes Date: Wed, 17 Jul 2024 00:38:18 -0400 Subject: [PATCH 1/2] expands re-use dependency layers page Signed-off-by: Hanan Younes --- .../how-to/write-buildpacks/re-use-layers.md | 29 +++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/content/docs/for-buildpack-authors/how-to/write-buildpacks/re-use-layers.md b/content/docs/for-buildpack-authors/how-to/write-buildpacks/re-use-layers.md index 1cd37363b..68c5637b7 100644 --- a/content/docs/for-buildpack-authors/how-to/write-buildpacks/re-use-layers.md +++ b/content/docs/for-buildpack-authors/how-to/write-buildpacks/re-use-layers.md @@ -3,8 +3,33 @@ title="Re-use dependency layers" weight=99 +++ +The [lifecycle](https://buildpacks.io/docs/for-buildpack-authors/concepts/lifecycle-phases/) provides a mechanism for buildpacks to explicitly opt into reusing any necessary dependency layers from a previous build. Buildpacks may modify cached build dependencies before reusing them. + -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 usually reads metadata about layers it created during a previous build to ensure only changed layers are updated. For buildpack authors, this can aid in improving build performance by avoiding re-uploading unchanged layers and restoring any previously-cached dependencies. + +To decide whether layer reuse is appropriate, a buildpack should consider: + +* Whether files in the `` directory have changed since the layer was created. +* Whether the environment has changed since the layer was created. +* Whether the buildpack version has changed since the layer was created. +* Whether new application dependency versions have been made available since the layer was created. + +At the start of the `build` phase a buildpack MAY find: + +* Partial `/.toml` files describing layers from the previous builds. The restored `Layer Content Metadata` SHALL NOT contain `launch`, `build`, or `cache` booleans even if those values were set on a previous build. +* `/.sbom.` files that were written previously. +* `//` directories containing layer contents that have been restored from the cache. + +A buildpack: + +* MAY set `launch = true` under `[types]` in the restored `/.toml` file in order to include the layer in the final OCI image. +* MAY modify `metadata` in `/.toml` +* MAY modify `metadata` in `/.sbom.` +* **If** the layer contents have been restored to the `//` directory + * MAY set `build = true` under `[types]` in the restored `/.toml` to expose the layer to subsequent buildpacks. + * MAY set `cache = true` under `[types]` in the restored `/.toml` to persist the layer to subsequent builds. + * MAY modify the contents of `//`. -If you are familiar with this content and would like to make a contribution, please feel free to open a PR :) +If the buildpack does not set `launch`, `build`, or `cache` under `[types]` in the restored `/.toml` the layer SHALL be ignored. From 85cdab06e2826c5a908b72a09bbb2ea9f9df891e Mon Sep 17 00:00:00 2001 From: Hanan Younes Date: Wed, 17 Jul 2024 00:51:09 -0400 Subject: [PATCH 2/2] adds few links Signed-off-by: Hanan Younes --- .../how-to/write-buildpacks/re-use-layers.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/docs/for-buildpack-authors/how-to/write-buildpacks/re-use-layers.md b/content/docs/for-buildpack-authors/how-to/write-buildpacks/re-use-layers.md index 68c5637b7..8b0daaf42 100644 --- a/content/docs/for-buildpack-authors/how-to/write-buildpacks/re-use-layers.md +++ b/content/docs/for-buildpack-authors/how-to/write-buildpacks/re-use-layers.md @@ -3,7 +3,7 @@ title="Re-use dependency layers" weight=99 +++ -The [lifecycle](https://buildpacks.io/docs/for-buildpack-authors/concepts/lifecycle-phases/) provides a mechanism for buildpacks to explicitly opt into reusing any necessary dependency layers from a previous build. Buildpacks may modify cached build dependencies before reusing them. +The [lifecycle](https://buildpacks.io/docs/for-buildpack-authors/concepts/lifecycle-phases/) provides a mechanism for buildpacks to explicitly opt into reusing any necessary [dependency layers](https://buildpacks.io/docs/for-buildpack-authors/concepts/layer/) from a previous build. Buildpacks may modify cached build dependencies before reusing them. @@ -33,3 +33,5 @@ A buildpack: * MAY modify the contents of `//`. If the buildpack does not set `launch`, `build`, or `cache` under `[types]` in the restored `/.toml` the layer SHALL be ignored. + +>For more information on buildpack layer caching, see the documentation on [create dependency layers](https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/create-layer/) and [buildpack layer types](https://buildpacks.io/docs/for-buildpack-authors/concepts/caching-strategies/).