github.com/docker/docker@v299999999.0.0-20200612211812-aaf470eca7b5+incompatible/builder/builder.go (about)

     1  // Package builder defines interfaces for any Docker builder to implement.
     2  //
     3  // Historically, only server-side Dockerfile interpreters existed.
     4  // This package allows for other implementations of Docker builders.
     5  package builder // import "github.com/docker/docker/builder"
     6  
     7  import (
     8  	"context"
     9  	"io"
    10  
    11  	"github.com/docker/docker/api/types"
    12  	"github.com/docker/docker/api/types/backend"
    13  	"github.com/docker/docker/api/types/container"
    14  	containerpkg "github.com/docker/docker/container"
    15  	"github.com/docker/docker/image"
    16  	"github.com/docker/docker/layer"
    17  	"github.com/docker/docker/pkg/containerfs"
    18  )
    19  
    20  const (
    21  	// DefaultDockerfileName is the Default filename with Docker commands, read by docker build
    22  	DefaultDockerfileName = "Dockerfile"
    23  )
    24  
    25  // Source defines a location that can be used as a source for the ADD/COPY
    26  // instructions in the builder.
    27  type Source interface {
    28  	// Root returns root path for accessing source
    29  	Root() containerfs.ContainerFS
    30  	// Close allows to signal that the filesystem tree won't be used anymore.
    31  	// For Context implementations using a temporary directory, it is recommended to
    32  	// delete the temporary directory in Close().
    33  	Close() error
    34  	// Hash returns a checksum for a file
    35  	Hash(path string) (string, error)
    36  }
    37  
    38  // Backend abstracts calls to a Docker Daemon.
    39  type Backend interface {
    40  	ImageBackend
    41  	ExecBackend
    42  
    43  	// CommitBuildStep creates a new Docker image from the config generated by
    44  	// a build step.
    45  	CommitBuildStep(backend.CommitConfig) (image.ID, error)
    46  	// ContainerCreateWorkdir creates the workdir
    47  	ContainerCreateWorkdir(containerID string) error
    48  
    49  	CreateImage(config []byte, parent string) (Image, error)
    50  
    51  	ImageCacheBuilder
    52  }
    53  
    54  // ImageBackend are the interface methods required from an image component
    55  type ImageBackend interface {
    56  	GetImageAndReleasableLayer(ctx context.Context, refOrID string, opts backend.GetImageAndLayerOptions) (Image, ROLayer, error)
    57  }
    58  
    59  // ExecBackend contains the interface methods required for executing containers
    60  type ExecBackend interface {
    61  	// ContainerAttachRaw attaches to container.
    62  	ContainerAttachRaw(cID string, stdin io.ReadCloser, stdout, stderr io.Writer, stream bool, attached chan struct{}) error
    63  	// ContainerCreateIgnoreImagesArgsEscaped creates a new Docker container and returns potential warnings
    64  	ContainerCreateIgnoreImagesArgsEscaped(config types.ContainerCreateConfig) (container.ContainerCreateCreatedBody, error)
    65  	// ContainerRm removes a container specified by `id`.
    66  	ContainerRm(name string, config *types.ContainerRmConfig) error
    67  	// ContainerKill stops the container execution abruptly.
    68  	ContainerKill(containerID string, sig uint64) error
    69  	// ContainerStart starts a new container
    70  	ContainerStart(containerID string, hostConfig *container.HostConfig, checkpoint string, checkpointDir string) error
    71  	// ContainerWait stops processing until the given container is stopped.
    72  	ContainerWait(ctx context.Context, name string, condition containerpkg.WaitCondition) (<-chan containerpkg.StateStatus, error)
    73  }
    74  
    75  // Result is the output produced by a Builder
    76  type Result struct {
    77  	ImageID   string
    78  	FromImage Image
    79  }
    80  
    81  // ImageCacheBuilder represents a generator for stateful image cache.
    82  type ImageCacheBuilder interface {
    83  	// MakeImageCache creates a stateful image cache.
    84  	MakeImageCache(cacheFrom []string) ImageCache
    85  }
    86  
    87  // ImageCache abstracts an image cache.
    88  // (parent image, child runconfig) -> child image
    89  type ImageCache interface {
    90  	// GetCache returns a reference to a cached image whose parent equals `parent`
    91  	// and runconfig equals `cfg`. A cache miss is expected to return an empty ID and a nil error.
    92  	GetCache(parentID string, cfg *container.Config) (imageID string, err error)
    93  }
    94  
    95  // Image represents a Docker image used by the builder.
    96  type Image interface {
    97  	ImageID() string
    98  	RunConfig() *container.Config
    99  	MarshalJSON() ([]byte, error)
   100  	OperatingSystem() string
   101  }
   102  
   103  // ROLayer is a reference to image rootfs layer
   104  type ROLayer interface {
   105  	Release() error
   106  	NewRWLayer() (RWLayer, error)
   107  	DiffID() layer.DiffID
   108  }
   109  
   110  // RWLayer is active layer that can be read/modified
   111  type RWLayer interface {
   112  	Release() error
   113  	Root() containerfs.ContainerFS
   114  	Commit() (ROLayer, error)
   115  }