From 74d65af56de8bede95da1dec4eb1afc17e743d94 Mon Sep 17 00:00:00 2001 From: AidanDelaney Date: Wed, 17 Jul 2024 18:58:19 +0000 Subject: [PATCH] expands re-use dependency layers page (#750) * expands re-use dependency layers page Signed-off-by: Hanan Younes * adds few links Signed-off-by: Hanan Younes --------- Signed-off-by: Hanan Younes --- .../how-to/write-buildpacks/index.html | 2 +- .../how-to/write-buildpacks/index.xml | 2 +- .../write-buildpacks/re-use-layers/index.html | 41 +++++++++++++++++-- index.xml | 2 +- 4 files changed, 40 insertions(+), 7 deletions(-) diff --git a/docs/for-buildpack-authors/how-to/write-buildpacks/index.html b/docs/for-buildpack-authors/how-to/write-buildpacks/index.html index a5bf87cf3..588464db6 100644 --- a/docs/for-buildpack-authors/how-to/write-buildpacks/index.html +++ b/docs/for-buildpack-authors/how-to/write-buildpacks/index.html @@ -970,7 +970,7 @@

Re-use dependency layers

-

+

The lifecycle 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.

diff --git a/docs/for-buildpack-authors/how-to/write-buildpacks/index.xml b/docs/for-buildpack-authors/how-to/write-buildpacks/index.xml index 48962d3b6..c69211ab8 100644 --- a/docs/for-buildpack-authors/how-to/write-buildpacks/index.xml +++ b/docs/for-buildpack-authors/how-to/write-buildpacks/index.xml @@ -68,7 +68,7 @@ https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/re-use-layers/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/re-use-layers/ - + <p>The <a href="https://buildpacks.io/docs/for-buildpack-authors/concepts/lifecycle-phases/">lifecycle</a> provides a mechanism for buildpacks to explicitly opt into reusing any necessary <a href="https://buildpacks.io/docs/for-buildpack-authors/concepts/layer/">dependency layers</a> from a previous build. Buildpacks may modify cached build dependencies before reusing them.</p> Specify the environment diff --git a/docs/for-buildpack-authors/how-to/write-buildpacks/re-use-layers/index.html b/docs/for-buildpack-authors/how-to/write-buildpacks/re-use-layers/index.html index 3d1eeee96..f28116192 100644 --- a/docs/for-buildpack-authors/how-to/write-buildpacks/re-use-layers/index.html +++ b/docs/for-buildpack-authors/how-to/write-buildpacks/re-use-layers/index.html @@ -8,7 +8,7 @@ - + @@ -22,7 +22,7 @@ - + @@ -897,8 +897,41 @@

Re-use dependency layers

-

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 lifecycle 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.

+

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 <app> 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 <layers>/<layer>.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.
    • +
  • <layers>/<layer>.sbom.<ext> files that were written previously.
    • +
  • <layers>/<layer>/ directories containing layer contents that have been restored from the cache.
    • +
+

A buildpack:

+
    +
  • MAY set launch = true under [types] in the restored <layers>/<layer>.toml file in order to include the layer in the final OCI image.
    • +
  • MAY modify metadata in <layers>/<layer>.toml
    • +
  • MAY modify metadata in <layers>/<layer>.sbom.<ext>
    • +
  • If the layer contents have been restored to the <layers>/<layer>/ directory +
      +
    • MAY set build = true under [types] in the restored <layers>/<layer>.toml to expose the layer to subsequent buildpacks. +
        +
      • MAY set cache = true under [types] in the restored <layers>/<layer>.toml to persist the layer to subsequent builds.
        • +
      • MAY modify the contents of <layers>/<layer>/.
        • +
      +
      • +
    +
    • +
+

If the buildpack does not set launch, build, or cache under [types] in the restored <layers>/<layer>.toml the layer SHALL be ignored.

+
+

For more information on buildpack layer caching, see the documentation on create dependency layers and buildpack layer types.

+
diff --git a/index.xml b/index.xml index 98ffe64b3..20b2c737f 100644 --- a/index.xml +++ b/index.xml @@ -684,7 +684,7 @@ https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/re-use-layers/ Mon, 01 Jan 0001 00:00:00 +0000 https://buildpacks.io/docs/for-buildpack-authors/how-to/write-buildpacks/re-use-layers/ - + <p>The <a href="https://buildpacks.io/docs/for-buildpack-authors/concepts/lifecycle-phases/">lifecycle</a> provides a mechanism for buildpacks to explicitly opt into reusing any necessary <a href="https://buildpacks.io/docs/for-buildpack-authors/concepts/layer/">dependency layers</a> from a previous build. Buildpacks may modify cached build dependencies before reusing them.</p> Specify the default launch process