buildenv

Documentation

Index

• type BindMount
• type BuildEnv
• type BuildEnvInfo
  • func (i *BuildEnvInfo) Serialize() (data []byte, err error)
• type CreateOptions
• type EnvType
  • func (f *EnvType) Set(value string) error
  • func (f *EnvType) String() string
  • func (f *EnvType) Type() string
• type Factory
• type MockRoot
  • func OpenMockRoot(ctx opctx.Ctx, info BuildEnvInfo) (mockRoot *MockRoot, err error)
  • func (r *MockRoot) BuildRPM(ctx context.Context, srpmPath, outputDirPath string, options RPMBuildOptions) error
  • func (r *MockRoot) BuildSRPM(ctx context.Context, specPath, sourceDirPath, outputDirPath string, ...) error
  • func (r *MockRoot) CreateCmd(ctx context.Context, args []string, options RunOptions) (cmd opctx.Cmd, err error)
  • func (r *MockRoot) Destroy(ctx opctx.Ctx) (err error)
  • func (r *MockRoot) GetInfo() BuildEnvInfo
  • func (r *MockRoot) GetRunner() *mock.Runner
  • func (r *MockRoot) TryGetFailureDetails(fs opctx.FS, outputDirPath string) (details *RPMBuildLogDetails)
• type MockRootFactory
  • func NewMockRootFactory(ctx opctx.Ctx, mockConfigPath string) (*MockRootFactory, error)
  • func (f *MockRootFactory) CreateEnv(options CreateOptions) (BuildEnv, error)
  • func (f *MockRootFactory) CreateMockRoot(options CreateOptions) (*MockRoot, error)
  • func (f *MockRootFactory) CreateRPMAwareEnv(options CreateOptions) (RPMAwareBuildEnv, error)
• type RPMAwareBuildEnv
• type RPMAwareFactory
• type RPMBuildLogDetails
• type RPMBuildOptions
• type RunOptions
• type SRPMBuildOptions

Types

type BindMount

type BindMount struct {
	PathInHost     string
	PathInBuildEnv string
}

type BuildEnv

type BuildEnv interface {
	// GetInfo returns a [BuildEnvInfo] structure that contains information about the build
	// environment. This information can be used to identify the build environment and its properties.
	GetInfo() BuildEnvInfo

	// CreateCmd builds a new [exec.Cmd] for running the given command within the build environment.
	CreateCmd(ctx context.Context, args []string, options RunOptions) (cmd opctx.Cmd, err error)

	// Destroy permanently (and irreversibly) destroys the build environment, removing its files from
	// the filesystem.
	Destroy(ctx opctx.Ctx) error
}

BuildEnv defines an abstract interface for interacting with a specific instance of a build environment. A build environment is a self-contained, intentionally constructed environment that can be used to run build-related operations. A mock root instance is an example of a build environment.

type BuildEnvInfo

type BuildEnvInfo struct {
	// Name is the human-readable name moniker for the build environment.
	Name string `json:"name"`

	// UserCreated indicates whether the build environment was created on behalf of a direct user request.
	// If this is false, the build environment was created automatically as part of a larger operation.
	UserCreated bool `json:"userCreated"`

	// Type is the type of build environment. This is used to determine which technology can be used
	// to interact with the build environment.
	Type EnvType `json:"type"`

	// CreationTime is the time when the build environment was created. This can be useful for users to
	// better understanding their environments.
	CreationTime time.Time `json:"creationTime"`

	// Dir is the directory under which the build environment's files are stored.
	Dir string `json:"dir"`

	// Description optionally provides a human-readable description of the environment's purpose.
	Description string `json:"description"`
}

BuildEnvInfo is a simple data structure that contains information about a BuildEnv.

func (*BuildEnvInfo) Serialize

func (i *BuildEnvInfo) Serialize() (data []byte, err error)

type CreateOptions

type CreateOptions struct {
	// Name is the user-referenceable name of the build environment.
	Name string
	// Dir is the directory under which the build environment's files should be stored.
	Dir string
	// UserCreated indicates whether the build environment was explicitly created by the
	// user for direct use (as opposed to being created as part of a build operation).
	UserCreated bool
	// Description optionally provides a human-readable description for the purpose of
	// this environment.
	Description string
	// ConfigOpts is an optional set of key-value pairs that will be passed through to the
	// underlying build environment backend as configuration overrides (e.g., mock's --config-opts).
	ConfigOpts map[string]string
}

CreateOptions encapsulate options that may be specified at creation time of a BuildEnv. Note that there may be some environment options that are only configurable when the build environment is *run* (see: RunOptions).

type EnvType

type EnvType string

EnvType identifies the type of a build environment. This is used to determine which technology can be used to interact with the build environment.

const (
	// EnvTypeMock is the type of build environment that uses the mock technology.
	EnvTypeMock EnvType = "mock"
)

func (*EnvType) Set

func (f *EnvType) Set(value string) error

Parses the type from a string; usable by a command-line parser. Required by cobra.Command to be able to parse an EnvType from a command-line string.

func (*EnvType) String

func (f *EnvType) String() string

String returns the string representation of the build environment type.

func (*EnvType) Type

func (f *EnvType) Type() string

Returns a descriptive string usable in usage information.

type Factory

type Factory interface {
	// CreateEnv creates a new instance of a build environment (e.g., a specific mock root);
	// note that creation is decoupled from executing operations within the build environment.
	CreateEnv(options CreateOptions) (buildEnv BuildEnv, err error)
}

Factory is an abstract interface for a factory that can create new BuildEnv instances.

type MockRoot

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

MockRoot is an implementation of the BuildEnv interface that represents a mock root build environment.

func OpenMockRoot

func OpenMockRoot(ctx opctx.Ctx, info BuildEnvInfo) (mockRoot *MockRoot, err error)

OpenMockRoot opens an existing mock root build environment.

func (*MockRoot) BuildRPM

func (r *MockRoot) BuildRPM(ctx context.Context, srpmPath, outputDirPath string, options RPMBuildOptions) error

BuildRPM uses this build environment to build binary RPM packages from the provided SRPM package.

func (*MockRoot) BuildSRPM

func (r *MockRoot) BuildSRPM(
	ctx context.Context, specPath, sourceDirPath, outputDirPath string, options SRPMBuildOptions,
) error

BuildSRPM uses this build environment to build a source RPM package.

func (*MockRoot) CreateCmd

func (r *MockRoot) CreateCmd(ctx context.Context, args []string, options RunOptions) (
	cmd opctx.Cmd, err error,
)

CreateCmd builds a new opctx.Cmd for running the given command within the build environment.

func (*MockRoot) Destroy

func (r *MockRoot) Destroy(ctx opctx.Ctx) (err error)

Destroy permanently (and irreversibly) destroys the build environment, removing its files from the filesystem.

func (*MockRoot) GetInfo

func (r *MockRoot) GetInfo() BuildEnvInfo

func (*MockRoot) GetRunner

func (r *MockRoot) GetRunner() *mock.Runner

GetRunner returns the mock.Runner that may be used to run commands within this mock root build environment.

func (*MockRoot) TryGetFailureDetails

func (r *MockRoot) TryGetFailureDetails(fs opctx.FS, outputDirPath string) (details *RPMBuildLogDetails)

TryGetFailureDetails makes a best-effort attempt to extract details from build logs that may be relevant to understanding the cause of a build failure. This is intended to be called after a build failure to glean any insights we can from logs about why the failure might have occurred.

type MockRootFactory

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

MockRootFactory is an implementation of Factory that can create new MockRoot instances of build environments.

func NewMockRootFactory

func NewMockRootFactory(ctx opctx.Ctx, mockConfigPath string) (*MockRootFactory, error)

NewMockRootFactory creates a new instance of [mockRootFactory] with the given config file.

func (*MockRootFactory) CreateEnv

func (f *MockRootFactory) CreateEnv(options CreateOptions) (BuildEnv, error)

CreateEnv creates a new instance of a build environment (e.g., a specific mock root).

func (*MockRootFactory) CreateMockRoot

func (f *MockRootFactory) CreateMockRoot(options CreateOptions) (*MockRoot, error)

CreateMockRoot creates a new instance of a mock root. Unlike [CreateEnv], this method returns a MockRoot directly for callers that specifically want to interact with our concrete type.

func (*MockRootFactory) CreateRPMAwareEnv

func (f *MockRootFactory) CreateRPMAwareEnv(options CreateOptions) (RPMAwareBuildEnv, error)

CreateRPMAwareEnv creates a new instance of an RPM-aware build environment (e.g., a specific mock root).

type RPMAwareBuildEnv

type RPMAwareBuildEnv interface {
	BuildEnv

	// BuildSRPM uses this build environment to build a source RPM package.
	BuildSRPM(ctx context.Context, specPath, sourceDirPath, outputDirPath string, options SRPMBuildOptions) error

	// BuildRPM uses this build environment to build binary RPM packages from the provided SRPM package.
	BuildRPM(ctx context.Context, srpmPath, outputDirPath string, options RPMBuildOptions) error

	// TryGetFailureDetails makes a best-effort attempt to extract details from build logs that may be
	// relevant to understanding the cause of a build failure. This is intended to be called after a build
	// failure to glean any insights we can from logs about why the failure might have occurred.
	TryGetFailureDetails(fs opctx.FS, outputDirPath string) (details *RPMBuildLogDetails)
}

RPMAwareBuildEnv is an interface that extends the BuildEnv interface for the subset of build environments that provide native support RPM build operations.

type RPMAwareFactory

type RPMAwareFactory interface {
	// CreateEnv creates a new instance of a build environment (e.g., a specific mock root);
	// note that creation is decoupled from executing operations within the build environment.
	CreateRPMAwareEnv(options CreateOptions) (buildEnv RPMAwareBuildEnv, err error)
}

RPMAwareFactory is an abstract interface for a factory that can create new RPMAwareBuildEnv instances.

type RPMBuildLogDetails

type RPMBuildLogDetails = mock.BuildLogDetails

RPMBuildLogDetails encapsulates details extracted from RPM build logs that may be relevant to understanding the cause of a build failure.

type RPMBuildOptions

type RPMBuildOptions = mock.RPMBuildOptions

RPMBuildOptions encapsulates options that may be specified when building binary RPM packages using an RPMAwareBuildEnv.

type RunOptions

type RunOptions struct {
	// EnableNetworking indicates whether the build environment should allow networking operations.
	// If set to false, the build environment will be entirely isolated from the network.
	EnableNetworking bool

	// Interactive indicates whether the command should be run interactively. If set to true, the
	// command will be run in an interactive terminal, allowing the user to interact with it via
	// stdin.
	Interactive bool

	// BindMounts is a list of bind mounts that should be created for the build environment, allowing
	// mapping of host paths into the build environment.
	BindMounts []BindMount
}

RunOptions encapsulate options that may be specified at runtime when executing an operation within an created instance of a BuildEnv. Note that there may be some environment options that are only configurable when the build environment is *created* (see: CreateOptions).

type SRPMBuildOptions

type SRPMBuildOptions = mock.SRPMBuildOptions

SRPMBuildOptions encapsulates options that may be specified when building source RPM packages using an RPMAwareBuildEnv.