bundleinstall

README

bundle-install

gcr.io/paketo-buildpacks/bundle-install

A Cloud Native Buildpack to install gems from a Gemfile

This will be providing gems.

Documentation

Index

• Constants
• func Build(entries EntryResolver, installProcess InstallProcess, ...) packit.BuildFunc
• func Detect(gemfileParser, rubyVersionFileParser VersionParser, logger scribe.Emitter) packit.DetectFunc
• type BuildPlanMetadata
• type BundleInstallProcess
  • func NewBundleInstallProcess(executable Executable, logger scribe.Emitter, versionResolver VersionResolver, ...) BundleInstallProcess
  • func (ip BundleInstallProcess) Execute(workingDir, layerPath string, config map[string]string, keepBuildFiles bool) error
  • func (ip BundleInstallProcess) ShouldRun(metadata map[string]interface{}, workingDir string) (bool, string, string, error)
• type Calculator
• type EntryResolver
• type Environment
  • func ParseEnvironment(environ []string) (Environment, error)
• type Executable
• type GemfileParser
  • func NewGemfileParser() GemfileParser
  • func (p GemfileParser) ParseVersion(path string) (string, error)
• type InstallProcess
• type RubyVersionFileParser
  • func NewRubyVersionFileParser() RubyVersionFileParser
  • func (p RubyVersionFileParser) ParseVersion(path string) (string, error)
• type RubyVersionResolver
  • func NewRubyVersionResolver(executable Executable) RubyVersionResolver
  • func (r RubyVersionResolver) CompareMajorMinor(cachedVersion, newVersion string) (bool, error)
  • func (r RubyVersionResolver) Lookup() (string, error)
• type SBOMGenerator
• type VersionParser
• type VersionResolver

Constants

const (
	// GemsDependency is the name of the dependency provided by the buildpack in
	// its build plan entries.
	GemsDependency = "gems"

	// BundlerDependency is the name of a dependency required by the buildpack in
	// its build plan entries.
	BundlerDependency = "bundler"

	// MRIDependency is the name of a dependency required by the buildpack in its
	// build plan entries.
	MRIDependency = "mri"

	// LayerNameBuildGems is the name of the layer that is used to store gems
	// that are available during the build phase.
	LayerNameBuildGems = "build-gems"

	// LayerNameLaunchGems is the name of the layer that is used to store gems
	// that are available during the launch phase.
	LayerNameLaunchGems = "launch-gems"
)

Functions

func Build

func Build(
	entries EntryResolver,
	installProcess InstallProcess,
	sbomGenerator SBOMGenerator,
	logger scribe.Emitter,
	clock chronos.Clock,
	environment Environment,
) packit.BuildFunc

Build will return a packit.BuildFunc that will be invoked during the build phase of the buildpack lifecycle.

Build will execute the installation process to install gems that can be used in the build or launch phases of the buildpack lifecycle. Specifically, Build will provide different sets of gems as discrete layers depending upon their requirement in either the build or launch phase.

If gems are required during the build phase, Build will ensure that all gems, including those in the "development" and "test" groups are installed into a layer that is made available during the remainder of the build phase.

If gems are required during the launch phase, Build will ensure that only those gems that are not in the "development" or "test" groups are installed into a layer that is made available during the launch phase.

If gems are required during both the build and launch phases, Build will provide both of the above layers with their sets of gems. These layers operate mutually exclusively as only one is available in each of the build or launch phase.

To improve performance when installing gems for use in both the build and launch phases, Build will copy the contents of the build layer into the launch layer before executing the launch layer installation process. This will result in the launch layer installation process performing an effective "no-op" as all of the gems that it requires should already be copied into the layer. The launch layer installation process will however perform a "bundle clean" to remove any extra gems, including those from the "development" and "test" groups that may have been copied from the build layer.

Finally, upon completing the installation process, Build will remove any local bundler configuration files such that the Bundler CLI will only follow configuration from the global location, which will be configured to point to a file that is maintained in each of the build and launch layers respectively.

func Detect

func Detect(gemfileParser, rubyVersionFileParser VersionParser, logger scribe.Emitter) packit.DetectFunc

Detect will return a packit.DetectFunc that will be invoked during the detect phase of the buildpack lifecycle.

Detect will return a positive result if the application source code contains a Gemfile.

The buildplan entries for a positive detection include providing the "gems" dependency, and requiring the "bundler" and "mri" dependencies. If the Gemfile contains a specified Ruby version, the "mri" build plan entry will include a specific Ruby version contraint.

Types

type BuildPlanMetadata

type BuildPlanMetadata struct {
	Version       string `toml:"version"`
	VersionSource string `toml:"version-source,omitempty"`
	Build         bool   `toml:"build"`
	Launch        bool   `toml:"launch"`
}

BuildPlanMetadata declares the set of metadata included in buildplan requirements.

type BundleInstallProcess

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

BundleInstallProcess performs the "bundle install" build process.

func NewBundleInstallProcess

func NewBundleInstallProcess(executable Executable, logger scribe.Emitter, versionResolver VersionResolver, calculator Calculator) BundleInstallProcess

NewBundleInstallProcess initializes an instance of BundleInstallProcess.

func (BundleInstallProcess) Execute

func (ip BundleInstallProcess) Execute(workingDir, layerPath string, config map[string]string, keepBuildFiles bool) error

Execute will configure and install a set of gems into a layer location using the Bundler CLI.

First, to configure the Bundler environment, Execute will copy the local Bundler configuration, if any, into the target layer path. The configuration file created in the layer will become the defacto configuration file by setting `BUNDLE_USER_CONFIG` in the local environment while executing the subsequent Bundle CLI commands. The configuration will then be modifed with any settings specific to the invocation of Execute. These configurations will override any settings previously applied in the local Bundle configuration.

Once fully configured, Execute will run "bundle install" as a child process. During the execution of the "bundle install" process, Execute will have configured the command to use any locally vendored cache, enabling offline execution.

func (BundleInstallProcess) ShouldRun

func (ip BundleInstallProcess) ShouldRun(metadata map[string]interface{}, workingDir string) (bool, string, string, error)

ShouldRun will return true if it is determined that the BundleInstallProcess be executed during the build phase.

The criteria for determining that the install process should be executed is if the major or minor version of Ruby has changed, or if the contents of the Gemfile or Gemfile.lock have changed.

In addition to reporting if the install process should execute, this method will return the current version of Ruby and the checksum of the Gemfile and Gemfile.lock contents.

type Calculator

type Calculator interface {
	Sum(paths ...string) (string, error)
}

Calculator defines the interface for calculating a checksum of the given set of file paths.

type EntryResolver

type EntryResolver interface {
	MergeLayerTypes(string, []packit.BuildpackPlanEntry) (launch, build bool)
}

EntryResolver defines the interface for determining what phases of the lifecycle will require gems.

type Environment

type Environment struct {
	KeepGemExtensionBuildFiles bool
}

func ParseEnvironment

func ParseEnvironment(environ []string) (Environment, error)

type Executable

type Executable interface {
	Execute(pexec.Execution) error
}

Executable defines the interface for executing an external process.

type GemfileParser

type GemfileParser struct{}

GemfileParser parses the Gemfile to determine the version of Ruby used by the application.

func NewGemfileParser

func NewGemfileParser() GemfileParser

NewGemfileParser initializes an instance of GemfileParser.

func (GemfileParser) ParseVersion

func (p GemfileParser) ParseVersion(path string) (string, error)

ParseVersion scans the Gemfile for a Ruby version specification.

type InstallProcess

type InstallProcess interface {
	ShouldRun(metadata map[string]interface{}, workingDir string) (should bool, checksum string, rubyVersion string, err error)
	Execute(workingDir, layerPath string, config map[string]string, keepBuildFiles bool) error
}

InstallProcess defines the interface for executing the "bundle install" build process.

type RubyVersionFileParser

type RubyVersionFileParser struct{}

RubyVersionFileParser parses the .ruby-version file to determine the version of Ruby used by the application.

func NewRubyVersionFileParser

func NewRubyVersionFileParser() RubyVersionFileParser

NewGemfileParser initializes an instance of RubyVersionFileParser.

func (RubyVersionFileParser) ParseVersion

func (p RubyVersionFileParser) ParseVersion(path string) (string, error)

ParseVersion scans the .ruby-version file for a Ruby version specification.

type RubyVersionResolver

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

RubyVersionResolver identifies and compares versions of Ruby used in the build environment.

func NewRubyVersionResolver

func NewRubyVersionResolver(executable Executable) RubyVersionResolver

NewRubyVersionResolver initializes an instance of RubyVersionResolver.

func (RubyVersionResolver) CompareMajorMinor

func (r RubyVersionResolver) CompareMajorMinor(cachedVersion, newVersion string) (bool, error)

CompareMajorMinor returns true if the current major or minor version of Ruby has changed from the cached version.

func (RubyVersionResolver) Lookup

func (r RubyVersionResolver) Lookup() (string, error)

Lookup returns the version of Ruby installed in the build environment.

type SBOMGenerator

type SBOMGenerator interface {
	Generate(dir string) (sbom.SBOM, error)
}

type VersionParser

type VersionParser interface {
	ParseVersion(path string) (version string, err error)
}

VersionParser defines the interface for parsing the version of Ruby used by the application.

type VersionResolver

type VersionResolver interface {
	Lookup() (version string, err error)
	CompareMajorMinor(left string, right string) (bool, error)
}

VersionResolver defines the interface for looking up and comparing the versions of Ruby installed in the environment.