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.

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.