packit

README

packit

Package packit provides primitives for implementing a Cloud Native Buildpack according to the specification: https://github.com/buildpacks/spec/blob/main/buildpack.md.

Buildpack Interface

According to the CNB specification, the buildpack interface is composed of both a detect and build phase. Each of these phases has a corresponding set of packit primitives enable developers to easily implement a buildpack.

Detect Phase

The purpose of the detect phase is for buildpacks to declare dependencies that are provided or required for the buildpack to execute. Implementing the detect phase can be achieved by calling the Detect function and providing a DetectFunc callback to be invoked during that phase. Below is an example of a simple detect phase that provides the "yarn" dependency and requires the "node" dependency.

package main

import (
	"encoding/json"
	"os"
	"path/filepath"

	"github.com/paketo-buildpacks/packit"
)

func main() {
	// The detect phase provides yarn and requires node. When requiring node,
	// a version specified in the package.json file is included to indicate
	// what versions of node are acceptable to the buildpack.

	packit.Detect(func(context packit.DetectContext) (packit.DetectResult, error) {

		// The DetectContext includes a WorkingDir field that specifies the
		// location of the application source code. This field can be combined with
		// other paths to find and inspect files included in the application source
		// code that is provided to the buildpack.
		file, err := os.Open(filepath.Join(context.WorkingDir, "package.json"))
		if err != nil {
			return packit.DetectResult{}, err
		}

		// The package.json file includes a declaration of what versions of node
		// are acceptable. For example:
		//   {
		//     "engines": {
		//       "node": ">=0.10.3 <0.12"
		//     }
		//   }
		var config struct {
			Engines struct {
				Node string `json:"node"`
			} `json:"engines"`
		}

		err = json.NewDecoder(file).Decode(&config)
		if err != nil {
			return packit.DetectResult{}, err
		}

		// Once the package.json file has been parsed, the detect phase can return
		// a result that indicates the provision of yarn and the requirement of
		// node. As can be seen below, the BuildPlanRequirement may also include
		// optional metadata information to such as the source of the version
		// information for a given requirement.
		return packit.DetectResult{
			Plan: packit.BuildPlan{
				Provides: []packit.BuildPlanProvision{
					{Name: "yarn"},
				},
				Requires: []packit.BuildPlanRequirement{
					{
						Name:    "node",
						Version: config.Engines.Node,
						Metadata: map[string]string{
							"version-source": "package.json",
						},
					},
				},
			},
		}, nil
	})
}

Build Phase

The purpose of the build phase is to perform the operation of providing whatever dependencies were declared in the detect phase for the given application code. Implementing the build phase can be achieved by calling the Build function and providing a BuildFunc callback to be invoked during that phase. Below is an example that adds "yarn" as a dependency to the application source code.

package main

import "github.com/paketo-buildpacks/packit"

func main() {
	// The build phase includes the yarn cli in a new layer that is made
	// available for subsequent buildpacks during their build phase as well as to
	// the start command during launch.

	packit.Build(func(context packit.BuildContext) (packit.BuildResult, error) {

		// The BuildContext includes a BuildpackPlan with entries that specify a
		// requirement on a dependency provided by the buildpack. This example
		// simply chooses the first entry, but more intelligent resolution
		// processes can and likely shoud be used in real implementations.
		entry := context.Plan.Entries[0]

		// The BuildContext also provides a mechanism whereby a layer can be
		// created to store the results of a given portion of the build process.
		// This example creates a layer called "yarn" that will hold the yarn cli.
		layer, err := context.Layers.Get("yarn")
		if err != nil {
			return packit.BuildResult{}, err
		}

		layer.Build = true
		layer.Launch = true

		// At this point we are performing the process of installing the yarn cli.
		// As those details are not important to the explanation of the packit API,
		// they are omitted here.
		err = InstallYarn(entry.Version, layer.Path)
		if err != nil {
			return packit.BuildResult{}, err
		}

		// After the installation of the yarn cli, a BuildResult can be returned
		// that included details of the executed BuildpackPlan, the Layers to
		// provide back to the lifecycle, and the Processes to execute at launch.
		return packit.BuildResult{
			Layers: []packit.Layer{
				layer,
			},
			Processes: []packit.Process{
				{
					Type:    "web",
					Command: "yarn start",
				},
			},
		}, nil
	})
}

// InstallYarn executes the process of installing the yarn cli.
func InstallYarn(version, path string) error {
	// Implemention omitted.
	return nil
}

Run

Buildpacks can be created with a single entrypoint executable using the packit.Run function. Here, you can combine both the Detect and Build phases and run will ensure that the correct phase is called when the matching executable is called by the Cloud Native Buildpack Lifecycle. Below is an example that combines a simple detect and build into a single main program.

package main

import "github.com/paketo-buildpacks/packit"

func main() {
	detect := func(context packit.DetectContext) (packit.DetectResult, error) {
		return packit.DetectResult{}, nil
	}

	build := func(context packit.BuildContext) (packit.BuildResult, error) {
		return packit.BuildResult{
			Processes: []packit.Process{
				{
					Type:    "web",
					Command: `while true; do nc -l -p $PORT -c 'echo -e "HTTP/1.1 200 OK\n\n Hello, world!\n"'; done`,
				},
			},
		}, nil
	}

	packit.Run(detect, build)
}

Summary

These examples show the very basics of what a buildpack implementation using packit might entail. For more details, please consult the documentation of the types and functions declared herein.

Sub Packages

• cargo

• chronos: Package chronos provides clock functionality that can be useful when developing and testing Cloud Native Buildpacks.

• draft: Package draft provides a mechanism for combining Buildpack Plan entries for a dependency into an single entry. The entry has layer metadata that meets all of the entries' specifications. Its version constraint is based on a user-provided prioritized list of version sources. Useful during the build phase. See the CNB Buildpacks specification for context.

• fakes

• fs: Package fs provides a set of filesystem helpers that can be useful when developing Cloud Native Buildpacks.

• matchers

• pexec: Package pexec provides a mechanism for invoking a program executable with a varying set of arguments.

• postal: Package postal provides a service for resolving and installing dependencies for a buildpack.

• scribe

• vacation: Package vacation provides a set of functions that enable input stream decompression logic from several popular decompression formats.

jam CLI

The packit library comes with a command-line tool called jam that can be used to create buildpack tarball artifacts. The jam name is simply a play on the idea of "packaging" or "packing" a buildpack.

The jam executable can be installed by downloading the latest version from the Releases page. Once downloaded, buildpacks can be created from a source repository using the pack command like this:

jam pack \
  --buildpack ./buildpack.toml \
  --stack io.paketo.stacks.tiny \
  --version 1.2.3 \
  --offline \
  --output ./buildpack.tgz

---

Readme created from Go doc with goreadme

Documentation

Overview

Package packit provides primitives for implementing a Cloud Native Buildpack according to the specification: https://github.com/buildpacks/spec/blob/main/buildpack.md.

Buildpack Interface

According to the specification, the buildpack interface is composed of both a detect and build phase. Each of these phases has a corresponding set of packit primitives enable developers to easily implement a buildpack.

Detect Phase

The purpose of the detect phase is for buildpacks to declare dependencies that are provided or required for the buildpack to execute. Implementing the detect phase can be achieved by calling the Detect function and providing a DetectFunc callback to be invoked during that phase. Below is an example of a simple detect phase that provides the "yarn" dependency and requires the "node" dependency.

package main

import (
	"encoding/json"
	"os"
	"path/filepath"

	"github.com/paketo-buildpacks/packit"
)

func main() {
	// The detect phase provides yarn and requires node. When requiring node,
	// a version specified in the package.json file is included to indicate
	// what versions of node are acceptable to the buildpack.

	packit.Detect(func(context packit.DetectContext) (packit.DetectResult, error) {

		// The DetectContext includes a WorkingDir field that specifies the
		// location of the application source code. This field can be combined with
		// other paths to find and inspect files included in the application source
		// code that is provided to the buildpack.
		file, err := os.Open(filepath.Join(context.WorkingDir, "package.json"))
		if err != nil {
			return packit.DetectResult{}, err
		}

		// The package.json file includes a declaration of what versions of node
		// are acceptable. For example:
		//   {
		//     "engines": {
		//       "node": ">=0.10.3 <0.12"
		//     }
		//   }
		var config struct {
			Engines struct {
				Node string `json:"node"`
			} `json:"engines"`
		}

		err = json.NewDecoder(file).Decode(&config)
		if err != nil {
			return packit.DetectResult{}, err
		}

		// Once the package.json file has been parsed, the detect phase can return
		// a result that indicates the provision of yarn and the requirement of
		// node. As can be seen below, the BuildPlanRequirement may also include
		// optional metadata information to such as the source of the version
		// information for a given requirement.
		return packit.DetectResult{
			Plan: packit.BuildPlan{
				Provides: []packit.BuildPlanProvision{
					{Name: "yarn"},
				},
				Requires: []packit.BuildPlanRequirement{
					{
						Name:    "node",
						Version: config.Engines.Node,
						Metadata: map[string]string{
							"version-source": "package.json",
						},
					},
				},
			},
		}, nil
	})
}

Build Phase

The purpose of the build phase is to perform the operation of providing whatever dependencies were declared in the detect phase for the given application code. Implementing the build phase can be achieved by calling the Build function and providing a BuildFunc callback to be invoked during that phase. Below is an example that adds "yarn" as a dependency to the application source code.

package main

import "github.com/paketo-buildpacks/packit"

func main() {
	// The build phase includes the yarn cli in a new layer that is made
	// available for subsequent buildpacks during their build phase as well as to
	// the start command during launch.

	packit.Build(func(context packit.BuildContext) (packit.BuildResult, error) {

		// The BuildContext includes a BuildpackPlan with entries that specify a
		// requirement on a dependency provided by the buildpack. This example
		// simply chooses the first entry, but more intelligent resolution
		// processes can and likely shoud be used in real implementations.
		entry := context.Plan.Entries[0]

		// The BuildContext also provides a mechanism whereby a layer can be
		// created to store the results of a given portion of the build process.
		// This example creates a layer called "yarn" that will hold the yarn cli.
		layer, err := context.Layers.Get("yarn")
		if err != nil {
			return packit.BuildResult{}, err
		}
		layer.Build = true
		layer.Launch = true

		// At this point we are performing the process of installing the yarn cli.
		// As those details are not important to the explanation of the packit API,
		// they are omitted here.
		err = InstallYarn(entry.Version, layer.Path)
		if err != nil {
			return packit.BuildResult{}, err
		}

		// After the installation of the yarn cli, a BuildResult can be returned
		// that included details of the executed BuildpackPlan, the Layers to
		// provide back to the lifecycle, and the Processes to execute at launch.
		return packit.BuildResult{
			Layers: []packit.Layer{
				layer,
			},
			Processes: []packit.Process{
				{
					Type:    "web",
					Command: "yarn start",
				},
			},
		}, nil
	})
}

// InstallYarn executes the process of installing the yarn cli.
func InstallYarn(version, path string) error {
	// Implemention omitted.
	return nil
}

Run

Buildpacks can be created with a single entrypoint executable using the packit.Run function. Here, you can combine both the Detect and Build phases and run will ensure that the correct phase is called when the matching executable is called by the Cloud Native Buildpack Lifecycle. Below is an example that combines a simple detect and build into a single main program.

package main

import "github.com/paketo-buildpacks/packit"

func main() {
	detect := func(context packit.DetectContext) (packit.DetectResult, error) {
		return packit.DetectResult{}, nil
	}

	build := func(context packit.BuildContext) (packit.BuildResult, error) {
		return packit.BuildResult{
			Processes: []packit.Process{
				{
					Type:    "web",
					Command: `while true; do nc -l -p $PORT -c 'echo -e "HTTP/1.1 200 OK\n\n Hello, world!\n"'; done`,
				},
			},
		}, nil
	}

	packit.Run(detect, build)
}

Summary

These examples show the very basics of what a buildpack implementation using packit might entail. For more details, please consult the documentation of the types and functions declared herein.

Index

• Variables
• func Build(f BuildFunc, options ...Option)
• func Detect(f DetectFunc, options ...Option)
• func Run(detect DetectFunc, build BuildFunc, options ...Option)
• type BOMEntry
• type BuildContext
• type BuildFunc
• type BuildMetadata
• type BuildPlan
• type BuildPlanProvision
• type BuildPlanRequirement
• type BuildResult
• type BuildpackInfo
• type BuildpackPlan
• type BuildpackPlanEntry
• type DetectContext
• type DetectFunc
• type DetectResult
• type Environment
  • func (e Environment) Append(name, value, delim string)
  • func (e Environment) Default(name, value string)
  • func (e Environment) Override(name, value string)
  • func (e Environment) Prepend(name, value, delim string)
• type EnvironmentWriter
• type ExitHandler
• type LaunchMetadata
• type Layer
  • func (l Layer) Reset() (Layer, error)
• type Layers
  • func (l Layers) Get(name string) (Layer, error)
• type Option
  • func WithArgs(args []string) Option
  • func WithExitHandler(exitHandler ExitHandler) Option
• type OptionConfig
• type Platform
• type Process
• type Slice
• type TOMLWriter
• type UnmetEntry

Variables

var Fail = internal.Fail

Fail is a sentinal value that can be used to indicate a failure to detect during the detect phase. Fail implements the Error interface and should be returned as the error value in the DetectFunc signature. Fail also supports a modifier function, WithMessage, that allows the caller to set a custom failure message. The WithMessage function supports a fmt.Printf-like format string and variadic arguments to build a message, eg: packit.Fail.WithMessage("failed: %w", err).

Functions

func Build

func Build(f BuildFunc, options ...Option)

Build is an implementation of the build phase according to the Cloud Native Buildpacks specification. Calling this function with a BuildFunc will perform the build phase process.

func Detect

func Detect(f DetectFunc, options ...Option)

Detect is an implementation of the detect phase according to the Cloud Native Buildpacks specification. Calling this function with a DetectFunc will perform the detect phase process.

func Run

func Run(detect DetectFunc, build BuildFunc, options ...Option)

Run combines the invocation of both build and detect into a single entry point. Calling Run from an executable with a name matching "build" or "detect" will result in the matching DetectFunc or BuildFunc being called.

Types

type BOMEntry

type BOMEntry struct {
	// Name represents the name of the entry.
	Name string `toml:"name"`

	// Metadata is the metadata of the entry.  Optional.
	Metadata map[string]interface{} `toml:"metadata,omitempty"`
}

BOMEntry contains a bill of materials entry.

type BuildContext

type BuildContext struct {
	// BuildpackInfo includes the details of the buildpack parsed from the
	// buildpack.toml included in the buildpack contents.
	BuildpackInfo BuildpackInfo

	// CNBPath is the absolute path location of the buildpack contents.
	// This path is useful for finding the buildpack.toml or any other
	// files included in the buildpack.
	CNBPath string

	// Platform includes the platform context according to the specification:
	// https://github.com/buildpacks/spec/blob/main/buildpack.md#build
	Platform Platform

	// Layers provides access to layers managed by the buildpack. It can be used
	// to create new layers or retrieve cached layers from previous builds.
	Layers Layers

	// Plan includes the BuildpackPlan provided by the lifecycle as specified in
	// the specification:
	// https://github.com/buildpacks/spec/blob/main/buildpack.md#buildpack-plan-toml.
	Plan BuildpackPlan

	// Stack is the value of the chosen stack. This value is populated from the
	// $CNB_STACK_ID environment variable.
	Stack string

	// WorkingDir is the location of the application source code as provided by
	// the lifecycle.
	WorkingDir string
}

BuildContext provides the contextual details that are made available by the buildpack lifecycle during the build phase. This context is populated by the Build function and passed to BuildFunc during execution.

type BuildFunc

type BuildFunc func(BuildContext) (BuildResult, error)

BuildFunc is the definition of a callback that can be invoked when the Build function is executed. Buildpack authors should implement a BuildFunc that performs the specific build phase operations for a buildpack.

type BuildMetadata

type BuildMetadata struct {
	// BOM is the Bill-of-Material entries containing information about the
	// dependencies provided to the build environment.
	BOM []BOMEntry `toml:"bom"`

	// Unmet is a list of unmet entries from the build process that it was unable
	// to provide.
	Unmet []UnmetEntry `toml:"unmet"`
}

BuildMetadata represents the build metadata details persisted in the build.toml file according to the buildpack lifecycle specification: https://github.com/buildpacks/spec/blob/main/buildpack.md#buildtoml-toml.

type BuildPlan

type BuildPlan struct {
	// Provides is a list of BuildPlanProvisions that are provided by this
	// buildpack.
	Provides []BuildPlanProvision `toml:"provides"`

	// Requires is a list of BuildPlanRequirements that are required by this
	// buildpack.
	Requires []BuildPlanRequirement `toml:"requires"`

	// Or is a list of additional BuildPlans that may be selected by the
	// lifecycle
	Or []BuildPlan `toml:"or,omitempty"`
}

BuildPlan is a representation of the Build Plan as specified in the specification: https://github.com/buildpacks/spec/blob/main/buildpack.md#build-plan-toml. The BuildPlan allows buildpacks to indicate what dependencies they provide or require.

type BuildPlanProvision

type BuildPlanProvision struct {
	// Name is the identifier whereby buildpacks can coordinate that a dependency
	// is provided or required.
	Name string `toml:"name"`
}

BuildPlanProvision is a representation of a dependency that can be provided by a buildpack.

type BuildPlanRequirement

type BuildPlanRequirement struct {
	// Name is the identifier whereby buildpacks can coordinate that a dependency
	// is provided or required.
	Name string `toml:"name"`

	// Metadata is an unspecified field allowing buildpacks to communicate extra
	// details about their requirement. Examples of this type of metadata might
	// include details about what source was used to decide the version
	// constraint for a requirement.
	Metadata interface{} `toml:"metadata"`
}

type BuildResult

type BuildResult struct {
	// Plan is the set of refinements to the Buildpack Plan that were performed
	// during the build phase.
	//
	// Deprecated: Use LaunchMetadata or BuildMetadata instead. For more information
	// see https://buildpacks.io/docs/reference/spec/migration/buildpack-api-0.4-0.5/
	Plan BuildpackPlan

	// Layers is a list of layers that will be persisted by the lifecycle at the
	// end of the build phase. Layers not included in this list will not be made
	// available to the lifecycle.
	Layers []Layer

	// Launch is the metadata that will be persisted as launch.toml according to
	// the buildpack lifecycle specification:
	// https://github.com/buildpacks/spec/blob/main/buildpack.md#launchtoml-toml
	Launch LaunchMetadata

	// Build is the metadata that will be persisted as build.toml according to
	// the buildpack lifecycle specification:
	// https://github.com/buildpacks/spec/blob/main/buildpack.md#buildtoml-toml
	Build BuildMetadata
}

BuildResult allows buildpack authors to indicate the result of the build phase for a given buildpack. This result, returned in a BuildFunc callback, will be parsed and persisted by the Build function and returned to the lifecycle at the end of the build phase execution.

type BuildpackInfo

type BuildpackInfo struct {
	// ID is the identifier specified in the `buildpack.id` field of the buildpack.toml.
	ID string `toml:"id"`

	// Name is the identifier specified in the `buildpack.name` field of the buildpack.toml.
	Name string `toml:"name"`

	// Version is the identifier specified in the `buildpack.version` field of the buildpack.toml.
	Version string `toml:"version"`
}

BuildpackInfo is a representation of the basic information for a buildpack provided in its buildpack.toml file as described in the specification: https://github.com/buildpacks/spec/blob/main/buildpack.md#buildpacktoml-toml.

type BuildpackPlan

type BuildpackPlan struct {
	// Entries is a list of BuildpackPlanEntry fields that are declared in the
	// buildpack plan TOML file.
	Entries []BuildpackPlanEntry `toml:"entries"`
}

BuildpackPlan is a representation of the buildpack plan provided by the lifecycle and defined in the specification: https://github.com/buildpacks/spec/blob/main/buildpack.md#buildpack-plan-toml. It is also used to return a set of refinements to the plan at the end of the build phase.

type BuildpackPlanEntry

type BuildpackPlanEntry struct {
	// Name is the name of the dependency the the buildpack should provide.
	Name string `toml:"name"`

	// Metadata is an unspecified field allowing buildpacks to communicate extra
	// details about their requirement. Examples of this type of metadata might
	// include details about what source was used to decide the version
	// constraint for a requirement.
	Metadata map[string]interface{} `toml:"metadata"`
}

BuildpackPlanEntry is a representation of a single buildpack plan entry specified by the lifecycle.

type DetectContext

type DetectContext struct {
	// WorkingDir is the location of the application source code as provided by
	// the lifecycle.
	WorkingDir string

	// CNBPath is the absolute path location of the buildpack contents.
	// This path is useful for finding the buildpack.toml or any other
	// files included in the buildpack.
	CNBPath string

	// Platform includes the platform context according to the specification:
	// https://github.com/buildpacks/spec/blob/main/buildpack.md#detection
	Platform Platform

	// BuildpackInfo includes the details of the buildpack parsed from the
	// buildpack.toml included in the buildpack contents.
	BuildpackInfo BuildpackInfo

	// Stack is the value of the chosen stack. This value is populated from the
	// $CNB_STACK_ID environment variable.
	Stack string
}

DetectContext provides the contextual details that are made available by the buildpack lifecycle during the detect phase. This context is populated by the Detect function and passed to the DetectFunc during execution.

type DetectFunc

type DetectFunc func(DetectContext) (DetectResult, error)

DetectFunc is the definition of a callback that can be invoked when the Detect function is executed. Buildpack authors should implement a DetectFunc that performs the specific detect phase operations for a buildpack.

type DetectResult

type DetectResult struct {
	// Plan is the set of Build Plan provisions and requirements that are
	// detected during the detect phase of the lifecycle.
	Plan BuildPlan
}

DetectResult allows buildpack authors to indicate the result of the detect phase for a given buildpack. This result, returned in a DetectFunc callback, will be parsed and persisted by the Detect function and returned to the lifecycle at the end of the detect phase execution.

type Environment

type Environment map[string]string

Environment provides a key-value store for declaring environment variables.

func (Environment) Append

func (e Environment) Append(name, value, delim string)

Append adds a key-value pair to the environment as an appended value according to the specification: https://github.com/buildpacks/spec/blob/main/buildpack.md#append.

func (Environment) Default

func (e Environment) Default(name, value string)

Default adds a key-value pair to the environment as a default value according to the specification: https://github.com/buildpacks/spec/blob/main/buildpack.md#default.

func (Environment) Override

func (e Environment) Override(name, value string)

Override adds a key-value pair to the environment as an overridden value according to the specification: https://github.com/buildpacks/spec/blob/main/buildpack.md#override.

func (Environment) Prepend

func (e Environment) Prepend(name, value, delim string)

Prepend adds a key-value pair to the environment as a prepended value according to the specification: https://github.com/buildpacks/spec/blob/main/buildpack.md#prepend.

type EnvironmentWriter

type EnvironmentWriter interface {
	Write(dir string, env map[string]string) error
}

EnvironmentWriter serves as the interface for types that can write an Environment to a directory on disk according to the specification: https://github.com/buildpacks/spec/blob/main/buildpack.md#provided-by-the-buildpacks.

type ExitHandler

type ExitHandler interface {
	Error(error)
}

ExitHandler serves as the interface for types that can handle an error during the Detect or Build functions. ExitHandlers are responsible for translating error values into exit codes according the specification: https://github.com/buildpacks/spec/blob/main/buildpack.md#detection and https://github.com/buildpacks/spec/blob/main/buildpack.md#build.

type LaunchMetadata

type LaunchMetadata struct {
	// Processes is a list of processes that will be returned to the lifecycle to
	// be executed during the launch phase.
	Processes []Process

	// Slices is a list of slices that will be returned to the lifecycle to be
	// exported as separate layers during the export phase.
	Slices []Slice

	// Labels is a map of key-value pairs that will be returned to the lifecycle to be
	// added as config label on the image metadata. Keys must be unique.
	Labels map[string]string

	// BOM is the Bill-of-Material entries containing information about the
	// dependencies provided to the launch environment.
	BOM []BOMEntry
}

LaunchMetadata represents the launch metadata details persisted in the launch.toml file according to the buildpack lifecycle specification: https://github.com/buildpacks/spec/blob/main/buildpack.md#launchtoml-toml.

type Layer

type Layer struct {
	// Path is the absolute location of the layer on disk.
	Path string `toml:"-"`

	// Name is the descriptive name of the layer.
	Name string `toml:"-"`

	// Build indicates whether the layer is available to subsequent buildpacks
	// during their build phase according to the specification:
	// https://github.com/buildpacks/spec/blob/main/buildpack.md#build-layers.
	Build bool `toml:"build"`

	// Launch indicates whether the layer is exported into the application image
	// and made available during the launch phase according to the specification:
	// https://github.com/buildpacks/spec/blob/main/buildpack.md#launch-layers.
	Launch bool `toml:"launch"`

	// Cache indicates whether the layer is persisted and made available to
	// subsequent builds of the same application according to the specification:
	// https://github.com/buildpacks/spec/blob/main/buildpack.md#launch-layers
	// and
	// https://github.com/buildpacks/spec/blob/main/buildpack.md#build-layers.
	Cache bool `toml:"cache"`

	// SharedEnv is the set of environment variables attached to the layer and
	// made available during both the build and launch phases according to the
	// specification:
	// https://github.com/buildpacks/spec/blob/main/buildpack.md#provided-by-the-buildpacks.
	SharedEnv Environment `toml:"-"`

	// BuildEnv is the set of environment variables attached to the layer and
	// made available during the build phase according to the specification:
	// https://github.com/buildpacks/spec/blob/main/buildpack.md#provided-by-the-buildpacks.
	BuildEnv Environment `toml:"-"`

	// LaunchEnv is the set of environment variables attached to the layer and
	// made available during the launch phase according to the specification:
	// https://github.com/buildpacks/spec/blob/main/buildpack.md#provided-by-the-buildpacks.
	LaunchEnv Environment `toml:"-"`

	// ProcessLaunchEnv is a map of environment variables attached to the layer and
	// made available to specified proccesses in the launch phase accoring to the specification:
	// https://github.com/buildpacks/spec/blob/main/buildpack.md#provided-by-the-buildpacks
	ProcessLaunchEnv map[string]Environment `toml:"-"`

	// Metadata is an unspecified field allowing buildpacks to communicate extra
	// details about the layer. Examples of this type of metadata might include
	// details about what versions of software are included in the layer such
	// that subsequent builds can inspect that metadata and choose to reuse the
	// layer if suitable. The Metadata field ultimately fills the metadata field
	// of the Layer Content Metadata TOML file according to the specification:
	// https://github.com/buildpacks/spec/blob/main/buildpack.md#layer-content-metadata-toml.
	Metadata map[string]interface{} `toml:"metadata"`
}

Layer provides a representation of a layer managed by a buildpack as described by the specification: https://github.com/buildpacks/spec/blob/main/buildpack.md#layers.

func (Layer) Reset

func (l Layer) Reset() (Layer, error)

Reset clears the state of a layer such that the layer can be replaced with new content and metadata. It clears all environment variables, and removes the content of the layer directory on disk.

type Layers

type Layers struct {
	// Path is the absolute location of the set of layers managed by a buildpack
	// on disk.
	Path string
}

Layers represents the set of layers managed by a buildpack.

func (Layers) Get

func (l Layers) Get(name string) (Layer, error)

Get will either create a new layer with the given name and layer types. If a layer already exists on disk, then the layer metadata will be retrieved from disk and returned instead.

type Option

type Option func(config OptionConfig) OptionConfig

Option declares a function signature that can be used to define optional modifications to the behavior of the Detect and Build functions.

func WithArgs

func WithArgs(args []string) Option

WithArgs is an Option that overrides the value of os.Args for a given invocation of Build or Detect.

func WithExitHandler

func WithExitHandler(exitHandler ExitHandler) Option

WithExitHandler is an Option that overrides the ExitHandler for a given invocation of Build or Detect.

type OptionConfig

type OptionConfig struct {
	// contains filtered or unexported fields
}

OptionConfig is the set of configurable options for the Build and Detect functions.

type Platform

type Platform struct {
	// Path provides the location of the platform directory on the filesystem.
	// This location can be used to find platform extensions like service
	// bindings.
	Path string
}

Platform contains the context of the buildpack platform including its location on the filesystem.

type Process

type Process struct {
	// Type is an identifier to describe the type of process to be executed, eg.
	// "web".
	Type string `toml:"type"`

	// Command is the start command to be executed at launch.
	Command string `toml:"command"`

	// Args is a list of arguments to be passed to the command at launch.
	Args []string `toml:"args"`

	// Direct indicates whether the process should bypass the shell when invoked.
	Direct bool `toml:"direct"`
}

Process represents a process to be run during the launch phase as described in the specification: https://github.com/buildpacks/spec/blob/main/buildpack.md#launch. The fields of the process are describe in the specification of the launch.toml file: https://github.com/buildpacks/spec/blob/main/buildpack.md#launchtoml-toml.

type Slice

type Slice struct {
	Paths []string `toml:"paths"`
}

Slice represents a layer of the working directory to be exported during the export phase. These slices help to optimize data transfer for files that are commonly shared across applications. Slices are described in the layers section of the buildpack spec: https://github.com/buildpacks/spec/blob/main/buildpack.md#layers. The slice fields are described in the specification of the launch.toml file: https://github.com/buildpacks/spec/blob/main/buildpack.md#launchtoml-toml.

type TOMLWriter

type TOMLWriter interface {
	Write(path string, value interface{}) error
}

TOMLWriter serves as the interface for types that can handle the writing of TOML files. TOMLWriters take a path to a file location on disk and a datastructure to marshal.

type UnmetEntry

type UnmetEntry struct {
	// Name represents the name of the entry.
	Name string `toml:"name"`
}

UnmetEntry contains the name of an unmet dependency from the build process