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

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 dev. 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-<LIFECYCLE_VERSION>+linux.x86-64/ for the given (or default) LIFECYCLE_VERSION.

$ 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-<LIFECYCLE_VERSION>+linux.x86-64/ 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 WriteTOML(path string, data interface{}) error
• type Analyzer
  • func (a *Analyzer) Analyze(image imgutil.Image) (metadata.AnalyzedMetadata, error)
• type BuildEnv
• type BuildMetadata
• type Builder
  • func (b *Builder) Build() (*BuildMetadata, error)
• type Buildpack
  • func (bp *Buildpack) Detect(c *DetectConfig, in io.Reader, out io.Writer) int
  • func (bp *Buildpack) EscapedID() string
• type BuildpackGroup
  • func (bg *BuildpackGroup) Detect(c *DetectConfig) (plan []byte, group *BuildpackGroup, ok bool)
  • func (g *BuildpackGroup) Write(path string) error
• type BuildpackMap
  • func NewBuildpackMap(dir string) (BuildpackMap, error)
  • func (m BuildpackMap) ReadGroup(path string) (*BuildpackGroup, error)
  • func (m BuildpackMap) ReadOrder(orderPath string) (BuildpackOrder, error)
• type BuildpackOrder
  • func (bo BuildpackOrder) Detect(c *DetectConfig) (plan []byte, group *BuildpackGroup)
• 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
• type Exporter
  • func (e *Exporter) Export(layersDir, appDir string, workingImage imgutil.Image, ...) error
• type LaunchTOML
• type Launcher
  • func (l *Launcher) Launch(executable, startCommand string) error
• type MultiError
  • func (me *MultiError) Error() string
• type Plan
• type Process
• type Restorer
  • func (r *Restorer) Restore(cache Cache) error

Constants

const (
	CodeDetectPass = iota
	CodeDetectError
	CodeDetectFail = 100
)

Variables

var POSIXBuildEnv = map[string][]string{
	"bin": {
		"PATH",
	},
	"lib": {
		"LD_LIBRARY_PATH",
		"LIBRARY_PATH",
	},
	"include": {
		"CPATH",
		"C_INCLUDE_PATH",
		"CPLUS_INCLUDE_PATH",
		"OBJC_INCLUDE_PATH",
	},
	"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 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
	Out, Err     *log.Logger
	SkipLayers   bool
}

func (*Analyzer) Analyze

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

type BuildEnv

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

type BuildMetadata

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

type Builder

type Builder struct {
	PlatformDir string
	LayersDir   string
	AppDir      string
	Env         BuildEnv
	Buildpacks  []*Buildpack
	Plan        Plan
	Out, Err    io.Writer
}

func (*Builder) Build

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

type Buildpack

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

func (*Buildpack) Detect

func (bp *Buildpack) Detect(c *DetectConfig, in io.Reader, out io.Writer) int

func (*Buildpack) EscapedID

func (bp *Buildpack) EscapedID() string

type BuildpackGroup

type BuildpackGroup struct {
	Buildpacks []*Buildpack `toml:"buildpacks"`
}

func (*BuildpackGroup) Detect

func (bg *BuildpackGroup) Detect(c *DetectConfig) (plan []byte, group *BuildpackGroup, ok bool)

func (*BuildpackGroup) Write

func (g *BuildpackGroup) Write(path string) error

type BuildpackMap

type BuildpackMap map[string]*Buildpack

func NewBuildpackMap

func NewBuildpackMap(dir string) (BuildpackMap, error)

func (BuildpackMap) ReadGroup

func (m BuildpackMap) ReadGroup(path string) (*BuildpackGroup, error)

func (BuildpackMap) ReadOrder

func (m BuildpackMap) ReadOrder(orderPath string) (BuildpackOrder, error)

type BuildpackOrder

type BuildpackOrder []BuildpackGroup

func (BuildpackOrder) Detect

func (bo BuildpackOrder) Detect(c *DetectConfig) (plan []byte, group *BuildpackGroup)

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
	Out, Err     *log.Logger
	UID, GID     int
}

func (*Cacher) Cache

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

type DetectConfig

type DetectConfig struct {
	AppDir      string
	PlatformDir string
	Out, Err    *log.Logger
}

type Env

type Env struct {
	Getenv  func(key string) string
	Setenv  func(key, value 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

type Exporter

type Exporter struct {
	Buildpacks   []*Buildpack
	ArtifactsDir string
	In           []byte
	Out, Err     *log.Logger
	UID, GID     int
}

func (*Exporter) Export

func (e *Exporter) Export(
	layersDir,
	appDir string,
	workingImage imgutil.Image,
	origMetadata metadata.AppImageMetadata,
	additionalNames []string,
	launcher string,
	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         []string
	Env                BuildEnv
	Exec               func(argv0 string, argv []string, envv []string) error
}

func (*Launcher) Launch

func (l *Launcher) Launch(executable, startCommand string) error

type MultiError

type MultiError struct {
	Errors []error
}

func (*MultiError) Error

func (me *MultiError) Error() string

type Plan

type Plan map[string]map[string]interface{}

type Process

type Process struct {
	Type    string `toml:"type"`
	Command string `toml:"command"`
}

type Restorer

type Restorer struct {
	LayersDir  string
	Buildpacks []*Buildpack
	Out, Err   *log.Logger
	UID        int
	GID        int
}

func (*Restorer) Restore

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