uimage

Documentation

Overview

Package uimage creates root file systems from Go programs.

uimage will appropriately compile the Go programs, create symlinks for their names, and assemble an initramfs with additional files as specified.

Index

• func Create(l *llog.Logger, mods ...Modifier) error
• func CreateInitramfs(l *llog.Logger, opts Opts) error
• func DefaultRamfs() *cpio.Archive
• func ParseExtraFiles(l *llog.Logger, archive *initramfs.Files, extraFiles []string, lddDeps bool) error
• type Commands
  • func BinaryCmds(cmds ...string) []Commands
  • func BusyboxCmds(cmds ...string) []Commands
  • func (c Commands) TargetDir() string
• type Modifier
  • func WithBase(base initramfs.ReadOpener) Modifier
  • func WithBaseArchive(archive *cpio.Archive) Modifier
  • func WithBaseFile(path string) Modifier
  • func WithBinaryCommands(cmd ...string) Modifier
  • func WithBinaryCommandsOpts(gbOpts *golang.BuildOpts, cmd ...string) Modifier
  • func WithBusyboxBuildOpts(g *golang.BuildOpts) Modifier
  • func WithBusyboxCommands(cmd ...string) Modifier
  • func WithCPIOOutput(path string) Modifier
  • func WithCommands(buildOpts *golang.BuildOpts, b builder.Builder, cmd ...string) Modifier
  • func WithCoveredCommands(cmd ...string) Modifier
  • func WithEnv(gopts ...golang.Opt) Modifier
  • func WithExistingInit(use bool) Modifier
  • func WithFiles(file ...string) Modifier
  • func WithInit(arg0 string) Modifier
  • func WithOutput(w initramfs.WriteOpener) Modifier
  • func WithOutputDir(path string) Modifier
  • func WithReplaceEnv(env *golang.Environ) Modifier
  • func WithShell(arg0 string) Modifier
  • func WithShellBang(b bool) Modifier
  • func WithSkipLDD() Modifier
  • func WithSymlink(file string, target string) Modifier
  • func WithTempDir(dir string) Modifier
  • func WithUinit(arg0 string, args ...string) Modifier
  • func WithUinitCommand(cmd string) Modifier
• type Opts
  • func OptionsFor(mods ...Modifier) (*Opts, error)
  • func (o *Opts) AddBusyboxCommands(pkgs ...string)
  • func (o *Opts) AddCommands(c ...Commands)
  • func (o *Opts) Apply(mods ...Modifier) error
  • func (o *Opts) Create(l *llog.Logger) error

Functions

func Create

func Create(l *llog.Logger, mods ...Modifier) error

Create creates an initramfs from mods specifications.

func CreateInitramfs

func CreateInitramfs(l *llog.Logger, opts Opts) error

CreateInitramfs creates an initramfs built to opts' specifications.

func DefaultRamfs

func DefaultRamfs() *cpio.Archive

DefaultRamfs returns a cpio.Archive for the target OS. If an OS is not known it will return a reasonable u-root specific default.

func ParseExtraFiles

func ParseExtraFiles(l *llog.Logger, archive *initramfs.Files, extraFiles []string, lddDeps bool) error

ParseExtraFiles adds files from the extraFiles list to the archive.

The following formats are allowed in the extraFiles list:

• "/home/chrisko/foo:root/bar" adds the file from absolute path /home/chrisko/foo on the host at the relative root/bar in the archive.
• "/home/foo" is equivalent to "/home/foo:home/foo".

ParseExtraFiles will also add ldd-listed dependencies if lddDeps is true.

Types

type Commands

type Commands struct {
	// Builder is the Go compiler mode.
	Builder builder.Builder

	// Packages are the Go commands to include (compiled or otherwise) and
	// add to the archive.
	//
	// Currently allowed formats:
	//
	//   - package imports; e.g. github.com/u-root/u-root/cmds/ls
	//   - globs of package imports; e.g. github.com/u-root/u-root/cmds/*
	//   - paths to package directories; e.g. $GOPATH/src/github.com/u-root/u-root/cmds/ls
	//   - globs of paths to package directories; e.g. ./cmds/*
	//
	// Directories may be relative or absolute, with or without globs.
	// Globs are resolved using filepath.Glob.
	Packages []string

	// BinaryDir is the directory in which the resulting binaries are
	// placed inside the initramfs.
	//
	// BinaryDir may be empty, in which case Builder.DefaultBinaryDir()
	// will be used.
	BinaryDir string

	// Build options for building go binaries. Ultimate this holds all the
	// args that end up being passed to `go build`.
	BuildOpts *golang.BuildOpts
}

Commands specifies a list of Golang packages to build with a builder, e.g. in busybox mode, source mode, or binary mode.

See Builder for an explanation of build modes.

func BinaryCmds

func BinaryCmds(cmds ...string) []Commands

BinaryCmds returns a list of Commands with cmds built as a busybox.

func BusyboxCmds

func BusyboxCmds(cmds ...string) []Commands

BusyboxCmds returns a list of Commands with cmds built as a busybox.

func (Commands) TargetDir

func (c Commands) TargetDir() string

TargetDir returns the initramfs binary directory for these Commands.

type Modifier

type Modifier func(*Opts) error

Modifier modifies uimage options.

func WithBase

func WithBase(base initramfs.ReadOpener) Modifier

WithBase is an existing initramfs to include in the resulting initramfs.

func WithBaseArchive

func WithBaseArchive(archive *cpio.Archive) Modifier

WithBaseArchive is an existing initramfs to include in the resulting initramfs.

func WithBaseFile

func WithBaseFile(path string) Modifier

WithBaseFile is an existing initramfs read from a CPIO file at the given path to include in the resulting initramfs.

func WithBinaryCommands

func WithBinaryCommands(cmd ...string) Modifier

WithBinaryCommands adds Go commands to compile as individual binaries and add to the archive.

Allowed formats for cmd are documented in WithCommands.

func WithBinaryCommandsOpts

func WithBinaryCommandsOpts(gbOpts *golang.BuildOpts, cmd ...string) Modifier

WithBinaryCommandsOpts adds Go commands to compile as individual binaries and add to the archive.

Allowed formats for cmd are documented in WithCommands.

func WithBusyboxBuildOpts

func WithBusyboxBuildOpts(g *golang.BuildOpts) Modifier

WithBusyboxBuildOpts directs the busybox builder to use the given build opts.

Overrides any previously defined build options.

func WithBusyboxCommands

func WithBusyboxCommands(cmd ...string) Modifier

WithBusyboxCommands adds Go commands to compile in a busybox and add to the archive.

If there were already busybox commands added to the archive, the given cmd will be merged with them.

Allowed formats for cmd are documented in WithCommands.

func WithCPIOOutput

func WithCPIOOutput(path string) Modifier

WithCPIOOutput sets the archive output file to be a CPIO created at the given path.

func WithCommands

func WithCommands(buildOpts *golang.BuildOpts, b builder.Builder, cmd ...string) Modifier

WithCommands adds Go commands to compile and add to the archive.

b is the method of building -- as a busybox or a binary.

Currently allowed formats for cmd:

• package imports; e.g. github.com/u-root/u-root/cmds/ls
• globs of package imports; e.g. github.com/u-root/u-root/cmds/*
• paths to package directories; e.g. $GOPATH/src/github.com/u-root/u-root/cmds/ls
• globs of paths to package directories; e.g. ./cmds/*

Directories may be relative or absolute, with or without globs. Globs are resolved using filepath.Glob.

func WithCoveredCommands

func WithCoveredCommands(cmd ...string) Modifier

WithCoveredCommands adds Go commands to compile as individual binaries with -cover and -covermode=atomic for integration test coverage.

Allowed formats for cmd are documented in WithCommands.

func WithEnv

func WithEnv(gopts ...golang.Opt) Modifier

WithEnv alters the Go build environment (e.g. build tags, GOARCH, GOOS env vars).

func WithExistingInit

func WithExistingInit(use bool) Modifier

WithExistingInit sets whether an existing init from BaseArchive should remain the init.

If not, it will be renamed inito.

func WithFiles

func WithFiles(file ...string) Modifier

WithFiles adds files to the archive.

Shared library dependencies will automatically also be added to the archive using ldd, unless WithSkipLDD is set.

The following formats are allowed in the list:

• "/home/chrisko/foo:root/bar" adds the file from absolute path /home/chrisko/foo on the host at the relative root/bar in the archive.
• "/home/foo" is equivalent to "/home/foo:home/foo".
• "uroot_test.go" is equivalent to "uroot_test.go:uroot_test.go".

func WithInit

func WithInit(arg0 string) Modifier

WithInit sets the name of a command to link /init to.

This can be an absolute path or the name of a command included in Commands.

func WithOutput

func WithOutput(w initramfs.WriteOpener) Modifier

WithOutput sets the archive output file.

func WithOutputDir

func WithOutputDir(path string) Modifier

WithOutputDir sets the archive output to be in the given directory.

func WithReplaceEnv

func WithReplaceEnv(env *golang.Environ) Modifier

WithReplaceEnv replaces the Go build environment.

func WithShell

func WithShell(arg0 string) Modifier

WithShell sets the default shell to start after init, which is a symlink from /bin/sh.

This can be an absolute path or the name of a command included in Commands.

func WithShellBang

func WithShellBang(b bool) Modifier

WithShellBang directs the busybox builder to use #! instead of symlinks.

func WithSkipLDD

func WithSkipLDD() Modifier

WithSkipLDD sets SkipLDD to true. If true, initramfs creation skips using ldd to pick up dependencies from the local file system when resolving ExtraFiles.

Useful if you have all deps revision controlled and wish to ensure builds are repeatable, and/or if the local machine's binaries use instructions unavailable on the emulated CPU.

If you turn this on but do not manually list all deps, affected binaries will misbehave.

func WithSymlink

func WithSymlink(file string, target string) Modifier

WithSymlink adds a symlink to the archive.

Target can be the name of a command. If not, it will be created as given.

func WithTempDir

func WithTempDir(dir string) Modifier

WithTempDir sets a temporary directory to use for building commands.

func WithUinit

func WithUinit(arg0 string, args ...string) Modifier

WithUinit is command to link to /bin/uinit with args.

This can be an absolute path or the name of a command included in Commands.

The u-root init will always attempt to fork/exec a uinit program, and append arguments from both the kernel command-line (uroot.uinitargs) as well as those specified in cmd.

func WithUinitCommand

func WithUinitCommand(cmd string) Modifier

WithUinitCommand is command to link to /bin/uinit with args.

cmd will be tokenized by a very basic shlex.Split.

This can be an absolute path or the name of a command included in Commands.

The u-root init will always attempt to fork/exec a uinit program, and append arguments from both the kernel command-line (uroot.uinitargs) as well as those specified in cmd.

If this is empty, no uinit symlink will be created, but a user may still specify a command called uinit or include a /bin/uinit file.

type Opts

type Opts struct {
	// Env is the Golang build environment (GOOS, GOARCH, etc).
	//
	// If nil, golang.Default is used.
	Env *golang.Environ

	// Commands specify packages to build using a specific builder.
	//
	// E.g. the following will build 'ls' and 'ip' in busybox mode, but
	// 'cd' and 'cat' as separate binaries. 'cd', 'cat', 'bb', and symlinks
	// from 'ls' and 'ip' will be added to the final initramfs.
	//
	//   []Commands{
	//     Commands{
	//       Builder: builder.Busybox,
	//       Packages: []string{
	//         "github.com/u-root/u-root/cmds/ls",
	//         "github.com/u-root/u-root/cmds/ip",
	//       },
	//     },
	//     Commands{
	//       Builder: builder.Binary,
	//       Packages: []string{
	//         "github.com/u-root/u-root/cmds/cd",
	//         "github.com/u-root/u-root/cmds/cat",
	//       },
	//     },
	//   }
	Commands []Commands

	// UrootSource is the filesystem path to the locally checked out
	// u-root source tree. This is needed to resolve templates or
	// import paths of u-root commands.
	UrootSource string

	// TempDir is a temporary directory for builders to store files in.
	TempDir string

	// ExtraFiles are files to add to the archive in addition to the Go
	// packages.
	//
	// Shared library dependencies will automatically also be added to the
	// archive using ldd, unless SkipLDD (below) is true.
	//
	// The following formats are allowed in the list:
	//
	//   - "/home/chrisko/foo:root/bar" adds the file from absolute path
	//     /home/chrisko/foo on the host at the relative root/bar in the
	//     archive.
	//   - "/home/foo" is equivalent to "/home/foo:home/foo".
	ExtraFiles []string

	// Symlinks to create in the archive. File path in archive -> target
	//
	// Target can be the name of a command. If not, it will be created as given.
	Symlinks map[string]string

	// If true, do not use ldd to pick up dependencies from local machine for
	// ExtraFiles. Useful if you have all deps revision controlled and wish to
	// ensure builds are repeatable, and/or if the local machine's binaries use
	// instructions unavailable on the emulated cpu.
	//
	// If you turn this on but do not manually list all deps, affected binaries
	// will misbehave.
	SkipLDD bool

	// OutputFile is the archive output file.
	OutputFile initramfs.WriteOpener

	// BaseArchive is an existing initramfs to include in the resulting
	// initramfs.
	BaseArchive initramfs.ReadOpener

	// UseExistingInit determines whether the existing init from
	// BaseArchive should be used.
	//
	// If this is false, the "init" from BaseArchive will be renamed to
	// "inito" (init-original).
	UseExistingInit bool

	// InitCmd is the name of a command to link /init to.
	//
	// This can be an absolute path or the name of a command included in
	// Commands.
	//
	// If this is empty, no init symlink will be created, but a user may
	// still specify a command called init or include an /init file.
	InitCmd string

	// UinitCmd is the name of a command to link /bin/uinit to.
	//
	// This can be an absolute path or the name of a command included in
	// Commands.
	//
	// The u-root init will always attempt to fork/exec a uinit program,
	// and append arguments from both the kernel command-line
	// (uroot.uinitargs) as well as specified in UinitArgs.
	//
	// If this is empty, no uinit symlink will be created, but a user may
	// still specify a command called uinit or include a /bin/uinit file.
	UinitCmd string

	// UinitArgs are the arguments passed to /bin/uinit.
	UinitArgs []string

	// DefaultShell is the default shell to start after init.
	//
	// This can be an absolute path or the name of a command included in
	// Commands.
	//
	// This must be specified to have a default shell.
	DefaultShell string
}

Opts are the arguments to CreateInitramfs.

Opts contains everything that influences initramfs creation such as the Go build environment.

func OptionsFor

func OptionsFor(mods ...Modifier) (*Opts, error)

OptionsFor will creates Opts from the given modifiers.

func (*Opts) AddBusyboxCommands

func (o *Opts) AddBusyboxCommands(pkgs ...string)

AddBusyboxCommands adds Go commands to the busybox build.

func (*Opts) AddCommands

func (o *Opts) AddCommands(c ...Commands)

AddCommands adds commands to the build.

func (*Opts) Apply

func (o *Opts) Apply(mods ...Modifier) error

Apply modifies o with the given modifiers.

func (*Opts) Create

func (o *Opts) Create(l *llog.Logger) error

Create creates an initramfs from the given options o.