libqatapult

README

libQatapult 🚀

Launching QEMU instances in style.

libQatapult provides an interface for specifying, launching and observing QEMU based virtual machines in a programmatic and declarative way from Go code.

Documentation

Index

• Constants
• type Config
• type Description
  • func NewDescription(conf *Config) (d *Description, err error)
  • func (d Description) CmdLine() []string
  • func (d Description) Files() []*os.File
• type Device
• type DeviceGroup
  • func NewDeviceGroup(devices ...Device) *DeviceGroup
  • func (g *DeviceGroup) GetCliArgs() (out []string, err error)
  • func (g *DeviceGroup) GetFiles() []File
• type File
• type FilesProvider
• type LocalFileOptFn
  • func WithMode(mode int) LocalFileOptFn
  • func WithPerm(perm fs.FileMode) LocalFileOptFn
• type OsFile
  • func NewLocalFile(p string, opts ...LocalFileOptFn) (*OsFile, error)
  • func NewMemoryFile(name string) (out *OsFile, err error)
  • func NewOsFile(f *os.File) *OsFile
  • func NewRemoteFile(url string) (*OsFile, error)
  • func (f *OsFile) GetHandle() *os.File
  • func (f *OsFile) GetIndex() int
  • func (f *OsFile) GetPath() string
  • func (f *OsFile) SetIndex(i int)
• type VM
  • func Yeet(ctx context.Context, c *Config, opts ...YeetOption) (*VM, error)
  • func YeetDescription(ctx context.Context, d *Description, opts ...YeetOption) (*VM, error)
  • func (v *VM) Done() <-chan struct{}
  • func (v *VM) Error() error
  • func (v *VM) Kill() error
  • func (v *VM) Stop() error
• type YeetOption
  • func YeetWithStdPipes(i io.Reader, o io.Writer, e io.Writer) YeetOption

Constants

const FdOffset = 3

Types

type Config

type Config struct {
	// Emulator describes how to invoke the emulator.  This is a
	// slice where the first element of the slice describes the
	// path to the executable of the emulator executable and all
	// other slice elements following the first element are passed
	// to the emulator executable as arguments.
	Emulator []string

	// Environment describes the environment that will be passed
	// to the emulator binary. The semantics of the Env field
	// in exec.Cmd apply here.
	Environment []string

	// KeepDefaults tells qatapult to launch QEMU keeping
	// their default configuration.
	KeepDefaults bool

	// KeepUserConfig tells qatapult to launch QEMU keeping
	// their user-provided config files.
	KeepUserConfig bool

	// DontUseEnv prevents qatapult from checking for an
	// environment provided qemu binary configuration.
	DontUseEnv bool

	// Devices are devices to expose to the QEMU Guest.
	Devices *DeviceGroup
}

type Description

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

Description describes VM arguments from a Config.

func NewDescription

func NewDescription(conf *Config) (d *Description, err error)

NewDescription creates a new Description from the provided Config.

func (Description) CmdLine

func (d Description) CmdLine() []string

func (Description) Files

func (d Description) Files() []*os.File

type Device

type Device interface {
	// GetCliArgs returns arguments to be passed to the QEMU
	// command line for this device.
	GetCliArgs() ([]string, error)
}

type DeviceGroup

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

DeviceGroup groups individual devices together.

func NewDeviceGroup

func NewDeviceGroup(devices ...Device) *DeviceGroup

func (*DeviceGroup) GetCliArgs

func (g *DeviceGroup) GetCliArgs() (out []string, err error)

func (*DeviceGroup) GetFiles

func (g *DeviceGroup) GetFiles() []File

type File

type File interface {
	GetIndex() int
	SetIndex(i int)
	GetPath() string
	GetHandle() *os.File
}

type FilesProvider

type FilesProvider interface {
	Device

	// GetFiles provides any files needed by the given device to
	// function properly.
	GetFiles() []File
}

type LocalFileOptFn

type LocalFileOptFn func(opts *localFileOpts)

func WithMode

func WithMode(mode int) LocalFileOptFn

func WithPerm

func WithPerm(perm fs.FileMode) LocalFileOptFn

type OsFile

type OsFile struct {
	*os.File
	// contains filtered or unexported fields
}

func NewLocalFile

func NewLocalFile(p string, opts ...LocalFileOptFn) (*OsFile, error)

func NewMemoryFile

func NewMemoryFile(name string) (out *OsFile, err error)

func NewOsFile

func NewOsFile(f *os.File) *OsFile

func NewRemoteFile

func NewRemoteFile(url string) (*OsFile, error)

func (*OsFile) GetHandle

func (f *OsFile) GetHandle() *os.File

func (*OsFile) GetIndex

func (f *OsFile) GetIndex() int

func (*OsFile) GetPath

func (f *OsFile) GetPath() string

func (*OsFile) SetIndex

func (f *OsFile) SetIndex(i int)

type VM

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

VM represents a running QEMU virtual machine that was launched with Yeet.

func Yeet

func Yeet(ctx context.Context, c *Config, opts ...YeetOption) (*VM, error)

Yeet yeets a VM instance, in style, by launching QEMU with a Description constructed from the given Config.

func YeetDescription

func YeetDescription(ctx context.Context, d *Description, opts ...YeetOption) (*VM, error)

YeetDescription yeets a VM instance, in style, by launching QEMU with the given Description.

func (*VM) Done

func (v *VM) Done() <-chan struct{}

func (*VM) Error

func (v *VM) Error() error

func (*VM) Kill

func (v *VM) Kill() error

func (*VM) Stop

func (v *VM) Stop() error

type YeetOption

type YeetOption func(cmd *exec.Cmd)

func YeetWithStdPipes

func YeetWithStdPipes(i io.Reader, o io.Writer, e io.Writer) YeetOption

YeetWithStdPipes specifies the std pipes to be used in the given VM.