build

Documentation

Overview

Copyright 2023 Chainguard, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright 2023 Chainguard, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

• Variables
• type Assertion
  • func RequireGroupFile(optional bool) Assertion
  • func RequirePasswdFile(optional bool) Assertion
• type Context
  • func New(workDir string, opts ...Option) (*Context, error)
  • func (bc *Context) BuildImage() (fs.FS, error)
  • func (bc *Context) BuildLayer() (string, error)
  • func (bc *Context) BuildPackageList() (toInstall []*repository.RepositoryPackage, conflicts []string, err error)
  • func (bc *Context) BuildTarball() (string, error)
  • func (bc *Context) GenerateImageSBOM(arch types.Architecture, img coci.SignedImage) error
  • func (bc *Context) GenerateIndexSBOM(indexDigest name.Digest, imgs map[types.Architecture]coci.SignedImage) error
  • func (bc *Context) GenerateSBOM() error
  • func (bc *Context) ImageLayoutToLayer() (string, error)
  • func (bc *Context) Logger() *logrus.Entry
  • func (bc *Context) Refresh() error
  • func (bc *Context) SetImplementation(i buildImplementation)
  • func (bc *Context) Summarize()
• type Option
  • func WithAnnotations(annotations map[string]string) Option
  • func WithArch(arch types.Architecture) Option
  • func WithAssertions(a ...Assertion) Option
  • func WithBuildDate(s string) Option
  • func WithBuildOptions(buildOptions []string) Option
  • func WithConfig(configFile string) Option
  • func WithDebugLogging(enable bool) Option
  • func WithDockerMediatypes(useDockerMediaTypes bool) Option
  • func WithExtraKeys(keys []string) Option
  • func WithExtraRepos(repos []string) Option
  • func WithImageConfiguration(ic types.ImageConfiguration) Option
  • func WithLocal(local bool) Option
  • func WithPackageVersionTag(pvt string) Option
  • func WithPackageVersionTagPrefix(packageVersionTagPrefix string) Option
  • func WithPackageVersionTagStem(packageVersionTagStem bool) Option
  • func WithSBOM(path string) Option
  • func WithSBOMFormats(formats []string) Option
  • func WithStageTags(stageTags string) Option
  • func WithTagSuffix(tagSuffix string) Option
  • func WithTags(tags ...string) Option
  • func WithTarball(path string) Option
  • func WithVCS(enable bool) Option
• type PathMutator

Variables

var ErrOSReleaseAlreadyPresent = errors.New("already present")

ErrOSReleaseAlreadyPresent indicates /etc/os-release is already present.

Types

type Assertion

type Assertion func(*Context) error

func RequireGroupFile

func RequireGroupFile(optional bool) Assertion

func RequirePasswdFile

func RequirePasswdFile(optional bool) Assertion

type Context

type Context struct {

	// ImageConfiguration instructions to use for the build, normally from an apko.yaml file, but can be set directly.
	ImageConfiguration types.ImageConfiguration
	// ImageConfigFile path to the config file used, if any, to load the ImageConfiguration
	ImageConfigFile string

	Assertions []Assertion
	Options    options.Options
	// contains filtered or unexported fields
}

Context contains all of the information necessary to build an OCI image. Includes the configurationfor the build, the path to the config file, the executor for root jails and architecture emulation, the s6 supervisor to add to the image, build options, and the `buildImplementation`, which handles the actual build.

func New

func New(workDir string, opts ...Option) (*Context, error)

New creates a build context. The SOURCE_DATE_EPOCH env variable is supported and will overwrite the provided timestamp if present.

func (*Context) BuildImage

func (bc *Context) BuildImage() (fs.FS, error)

func (*Context) BuildLayer

func (bc *Context) BuildLayer() (string, error)

BuildLayer given the context set up, including build configuration and working directory, lays out all of the packages in the working directory, sets up the necessary user accounts and groups, and sets everything up in the directory. Then packages it all up into a standard OCI image layer tar.gz file.

func (*Context) BuildPackageList

func (bc *Context) BuildPackageList() (toInstall []*repository.RepositoryPackage, conflicts []string, err error)

func (*Context) BuildTarball

func (bc *Context) BuildTarball() (string, error)

BuildTarball calls the underlying implementation's BuildTarball which takes the fully populated working directory and saves it to an OCI image layer tar.gz file.

func (*Context) GenerateImageSBOM

func (bc *Context) GenerateImageSBOM(arch types.Architecture, img coci.SignedImage) error

func (*Context) GenerateIndexSBOM

func (bc *Context) GenerateIndexSBOM(indexDigest name.Digest, imgs map[types.Architecture]coci.SignedImage) error

func (*Context) GenerateSBOM

func (bc *Context) GenerateSBOM() error

func (*Context) ImageLayoutToLayer

func (bc *Context) ImageLayoutToLayer() (string, error)

ImageLayoutToLayer given an already built-out image in an fs from BuildImage(), create an OCI image layer tgz.

func (*Context) Logger

func (bc *Context) Logger() *logrus.Entry

func (*Context) Refresh

func (bc *Context) Refresh() error

Refresh initializes the build process by calling the underlying implementation's Refresh(), which includes getting the chroot/proot jailed process executor (and possibly architecture emulator), sets those on the Context, and returns.

func (*Context) SetImplementation

func (bc *Context) SetImplementation(i buildImplementation)

func (*Context) Summarize

func (bc *Context) Summarize()

type Option

type Option func(*Context) error

Option is an option for the build context.

func WithAnnotations

func WithAnnotations(annotations map[string]string) Option

WithAnnotations parses and populates the annotations in the ImageConfiguration

func WithArch

func WithArch(arch types.Architecture) Option

WithArch sets the architecture for the build context.

func WithAssertions

func WithAssertions(a ...Assertion) Option

WithAssertions adds assertions to validate the result of this build context. Assertions are checked in parallel at the end of the build process.

func WithBuildDate

func WithBuildDate(s string) Option

WithBuildDate sets the timestamps for the build context. The string is parsed according to RFC3339. An empty string is a special case and will default to the unix epoch.

func WithBuildOptions

func WithBuildOptions(buildOptions []string) Option

WithBuildOptions applies configured patches which have been requested to the ImageConfiguration.

func WithConfig

func WithConfig(configFile string) Option

WithConfig sets the image configuration for the build context. The image configuration is parsed from given config file.

func WithDebugLogging

func WithDebugLogging(enable bool) Option

WithDebugLogging sets the debug log level for the build context.

func WithDockerMediatypes

func WithDockerMediatypes(useDockerMediaTypes bool) Option

WithDockerMediatypes determine whether to use Docker mediatypes for the build context.

func WithExtraKeys

func WithExtraKeys(keys []string) Option

func WithExtraRepos

func WithExtraRepos(repos []string) Option

func WithImageConfiguration

func WithImageConfiguration(ic types.ImageConfiguration) Option

WithImageConfiguration sets the ImageConfiguration object to use when building.

func WithLocal

func WithLocal(local bool) Option

WithLocal sets whether to publish image to local Docker daemon.

func WithPackageVersionTag

func WithPackageVersionTag(pvt string) Option

func WithPackageVersionTagPrefix

func WithPackageVersionTagPrefix(packageVersionTagPrefix string) Option

func WithPackageVersionTagStem

func WithPackageVersionTagStem(packageVersionTagStem bool) Option

func WithSBOM

func WithSBOM(path string) Option

func WithSBOMFormats

func WithSBOMFormats(formats []string) Option

func WithStageTags

func WithStageTags(stageTags string) Option

WithStageTags prevents tagging, and innstead writes all tags to the filename provided.

func WithTagSuffix

func WithTagSuffix(tagSuffix string) Option

WithTagSuffix sets a tag suffix to use, e.g. `-glibc`.

func WithTags

func WithTags(tags ...string) Option

WithTags sets the tags for the build context.

func WithTarball

func WithTarball(path string) Option

WithTarball sets the output path of the layer tarball.

func WithVCS

func WithVCS(enable bool) Option

WithVCS enables VCS URL probing for the build context.

type PathMutator

type PathMutator func(apkfs.FullFS, *options.Options, types.PathMutation) error