lifecycle

README

Lifecycle

A reference implementation of Buildpack API v3.

Commands

Build

• detector - chooses buildpacks (via /bin/detect)
• analyzer - restores launch layer metadata from the previous build
• builder - executes buildpacks (via /bin/build)
• exporter - remotely patches images with new layers (via rebase & append)
• launcher - invokes choice of process

Develop

• detector - chooses buildpacks (via /bin/detect)
• developer - executes buildpacks (via /bin/develop)
• launcher - invokes choice of process

Cache

• restorer - restores cache
• cacher - updates cache

Rebase

• rebaser - remotely patches images with new base image

Notes

Cache implementations (restorer and cacher) are intended to be interchangeable and platform-specific. A platform may choose not to deduplicate cache layers.

Development

To test, build, and package binaries into an archive, simply run:

$ make all

This will create an archive at out/lifecycle-<LIFECYCLE_VERSION>+linux.x86-64.tgz.

By default, LIFECYCLE_VERSION is 0.0.0. It can be changed by prepending LIFECYCLE_VERSION=<some version> to the make command. For example:

$ LIFECYCLE_VERSION=1.2.3 make all

Steps can also be run individually as shown below.

Test

Formats, vets, and tests the code.

$ make test

Build

Builds binaries to out/lifecycle/.

$ make build

To clean the out/ directory, run make clean.

Package

Creates an archive at out/lifecycle-<LIFECYCLE_VERSION>+linux.x86-64.tgz, using the contents of the out/lifecycle/ directory, for the given (or default) LIFECYCLE_VERSION.

$ make package

Documentation

Index

• Constants
• Variables
• func NewCachingImage(image imgutil.Image, cache *cache.VolumeCache) imgutil.Image
• func SetupCredHelpers(dockerPath string, refs ...string) error
• func TruncateSha(sha string) string
• func WriteTOML(path string, data interface{}) error
• type Analyzer
  • func (a *Analyzer) Analyze(image imgutil.Image) (metadata.AnalyzedMetadata, error)
• type BOMEntry
• type BuildEnv
• type BuildMetadata
• type BuildPlan
• type BuildPlanEntry
• type Builder
  • func (b *Builder) Build() (*BuildMetadata, error)
• type Buildpack
  • func (bp Buildpack) String() string
• type BuildpackGroup
  • func ReadGroup(path string) (BuildpackGroup, error)
  • func (bg BuildpackGroup) Detect(c *DetectConfig) (BuildpackGroup, BuildPlan, error)
• type BuildpackOrder
  • func ReadOrder(path string) (BuildpackOrder, error)
  • func (bo BuildpackOrder) Detect(c *DetectConfig) (BuildpackGroup, BuildPlan, error)
• type Cache
• type Cacher
  • func (c *Cacher) Cache(layersDir string, cacheStore Cache) error
• type DetectConfig
• type Env
  • func (p *Env) AddEnvDir(envDir string) error
  • func (p *Env) AddRootDir(baseDir string) error
  • func (p *Env) List() []string
  • func (p *Env) WithPlatform(platformDir string) (out []string, err error)
• type Exporter
  • func (e *Exporter) Export(layersDir, appDir string, workingImage imgutil.Image, runImageRef string, ...) error
• type LaunchTOML
• type Launcher
  • func (l *Launcher) Launch(self string, cmd []string) error
• type LauncherConfig
• type Logger
• type MultiError
  • func (me *MultiError) Error() string
• type Process
• type Provide
• type Rebaser
  • func (r *Rebaser) Rebase(workingImage imgutil.Image, newBaseImage imgutil.Image, ...) error
• type Require
• type Restorer
  • func (r *Restorer) Restore(cache Cache) error

Constants

const (
	CodeDetectPass = 0
	CodeDetectFail = 100
)

Variables

var ErrFail = errors.New("no buildpacks participating")

var POSIXBuildEnv = map[string][]string{
	"bin": {
		"PATH",
	},
	"lib": {
		"LD_LIBRARY_PATH",
		"LIBRARY_PATH",
	},
	"include": {
		"CPATH",
	},
	"pkgconfig": {
		"PKG_CONFIG_PATH",
	},
}

var POSIXLaunchEnv = map[string][]string{
	"bin": {"PATH"},
	"lib": {"LD_LIBRARY_PATH"},
}

Functions

func NewCachingImage

func NewCachingImage(image imgutil.Image, cache *cache.VolumeCache) imgutil.Image

func SetupCredHelpers

func SetupCredHelpers(dockerPath string, refs ...string) error

func TruncateSha

func TruncateSha(sha string) string

func WriteTOML

func WriteTOML(path string, data interface{}) error

Types

type Analyzer

type Analyzer struct {
	AnalyzedPath string
	AppDir       string
	Buildpacks   []Buildpack
	GID, UID     int
	LayersDir    string
	Logger       Logger
	SkipLayers   bool
}

func (*Analyzer) Analyze

func (a *Analyzer) Analyze(image imgutil.Image) (metadata.AnalyzedMetadata, error)

type BOMEntry

type BOMEntry struct {
	Require
	Buildpack Buildpack `toml:"buildpack" json:"buildpack"`
}

type BuildEnv

type BuildEnv interface {
	AddRootDir(baseDir string) error
	AddEnvDir(envDir string) error
	WithPlatform(platformDir string) ([]string, error)
	List() []string
}

type BuildMetadata

type BuildMetadata struct {
	Processes  []Process   `toml:"processes"`
	Buildpacks []Buildpack `toml:"buildpacks"`
	BOM        []BOMEntry  `toml:"bom"`
}

type BuildPlan

type BuildPlan struct {
	Entries []BuildPlanEntry `toml:"entries"`
}

type BuildPlanEntry

type BuildPlanEntry struct {
	Providers []Buildpack `toml:"providers"`
	Requires  []Require   `toml:"requires"`
}

type Builder

type Builder struct {
	AppDir        string
	LayersDir     string
	PlatformDir   string
	BuildpacksDir string
	Env           BuildEnv
	Group         BuildpackGroup
	Plan          BuildPlan
	Out, Err      *log.Logger
}

func (*Builder) Build

func (b *Builder) Build() (*BuildMetadata, error)

type Buildpack

type Buildpack struct {
	ID       string `toml:"id" json:"id"`
	Version  string `toml:"version" json:"version"`
	Optional bool   `toml:"optional,omitempty" json:"optional,omitempty"`
}

func (Buildpack) String

func (bp Buildpack) String() string

type BuildpackGroup

type BuildpackGroup struct {
	Group []Buildpack `toml:"group"`
}

func ReadGroup

func ReadGroup(path string) (BuildpackGroup, error)

func (BuildpackGroup) Detect

func (bg BuildpackGroup) Detect(c *DetectConfig) (BuildpackGroup, BuildPlan, error)

type BuildpackOrder

type BuildpackOrder []BuildpackGroup

func ReadOrder

func ReadOrder(path string) (BuildpackOrder, error)

func (BuildpackOrder) Detect

func (bo BuildpackOrder) Detect(c *DetectConfig) (BuildpackGroup, BuildPlan, error)

type Cache

type Cache interface {
	Name() string
	SetMetadata(metadata cache.Metadata) error
	RetrieveMetadata() (cache.Metadata, error)
	AddLayerFile(sha string, tarPath string) error
	ReuseLayer(sha string) error
	RetrieveLayer(sha string) (io.ReadCloser, error)
	Commit() error
}

type Cacher

type Cacher struct {
	ArtifactsDir string
	Buildpacks   []Buildpack
	Logger       Logger
	UID, GID     int
}

func (*Cacher) Cache

func (c *Cacher) Cache(layersDir string, cacheStore Cache) error

type DetectConfig

type DetectConfig struct {
	FullEnv       []string
	ClearEnv      []string
	AppDir        string
	PlatformDir   string
	BuildpacksDir string
	Logger        Logger
	// contains filtered or unexported fields
}

type Env

type Env struct {
	LookupEnv func(key string) (string, bool)
	Getenv    func(key string) string
	Setenv    func(key, value string) error
	Unsetenv  func(key string) error
	Environ   func() []string
	Map       map[string][]string
}

func (*Env) AddEnvDir

func (p *Env) AddEnvDir(envDir string) error

func (*Env) AddRootDir

func (p *Env) AddRootDir(baseDir string) error

func (*Env) List

func (p *Env) List() []string

func (*Env) WithPlatform

func (p *Env) WithPlatform(platformDir string) (out []string, err error)

type Exporter

type Exporter struct {
	Buildpacks   []Buildpack
	ArtifactsDir string
	In           []byte
	Logger       Logger
	UID, GID     int
}

func (*Exporter) Export

func (e *Exporter) Export(
	layersDir,
	appDir string,
	workingImage imgutil.Image,
	runImageRef string,
	origMetadata metadata.LayersMetadata,
	additionalNames []string,
	launcherConfig LauncherConfig,
	stack metadata.StackMetadata,
) error

type LaunchTOML

type LaunchTOML struct {
	Processes []Process `toml:"processes"`
}

type Launcher

type Launcher struct {
	DefaultProcessType string
	LayersDir          string
	AppDir             string
	Processes          []Process
	Buildpacks         []Buildpack
	Env                BuildEnv
	Exec               func(argv0 string, argv []string, envv []string) error
}

func (*Launcher) Launch

func (l *Launcher) Launch(self string, cmd []string) error

type LauncherConfig

type LauncherConfig struct {
	Path     string
	Metadata metadata.LauncherMetadata
}

type Logger

type Logger interface {
	Debug(msg string)
	Debugf(fmt string, v ...interface{})

	Info(msg string)
	Infof(fmt string, v ...interface{})

	Warn(msg string)
	Warnf(fmt string, v ...interface{})

	Error(msg string)
	Errorf(fmt string, v ...interface{})
}

type MultiError

type MultiError struct {
	Errors []error
}

func (*MultiError) Error

func (me *MultiError) Error() string

type Process

type Process struct {
	Type    string   `toml:"type"`
	Command string   `toml:"command"`
	Args    []string `toml:"args"`
	Direct  bool     `toml:"direct"`
}

type Provide

type Provide struct {
	Name string `toml:"name"`
}

type Rebaser

type Rebaser struct {
	Logger Logger
}

func (*Rebaser) Rebase

func (r *Rebaser) Rebase(
	workingImage imgutil.Image,
	newBaseImage imgutil.Image,
	additionalNames []string,
) error

type Require

type Require struct {
	Name     string                 `toml:"name" json:"name"`
	Version  string                 `toml:"version" json:"version"`
	Metadata map[string]interface{} `toml:"metadata" json:"metadata"`
}

type Restorer

type Restorer struct {
	LayersDir  string
	Buildpacks []Buildpack
	Logger     Logger
	UID        int
	GID        int
}

func (*Restorer) Restore

func (r *Restorer) Restore(cache Cache) error