common

Documentation

Index

• Constants
• func ResetTimestamp(path string) error
• func WriteFile(path string, contents []byte, mode os.FileMode, buildReproducibly bool) error
• type DirectorySection
• type ErrorCollector
  • func (c *ErrorCollector) Add(err error)
  • func (c *ErrorCollector) Addf(format string, args ...interface{})
• type FSEntry
• type FileSection
• type Generator
• type GroupSection
• type IntOrString
• type Package
  • func ParsePackageDefinition(input io.Reader) (*Package, []error)
  • func (pkg *Package) Build(generator Generator, printToStdout bool, buildReproducibly bool) error
  • func (pkg *Package) InstalledSizeInBytes() int
• type PackageDefinition
• type PackageRelation
• type PackageSection
• type SymlinkSection
• type UserSection
• type VersionConstraint

Constants

const (
	//FSEntryTypeRegular is the FSEntry.Type for regular files.
	FSEntryTypeRegular = iota
	//FSEntryTypeSymlink is the FSEntry.Type for symlinks.
	FSEntryTypeSymlink
	//FSEntryTypeDirectory is the FSEntry.Type for directories.
	FSEntryTypeDirectory
)

Functions

func ResetTimestamp

func ResetTimestamp(path string) error

ResetTimestamp sets the atime and mtime of the given file to 0 (i.e. 1970-01-01T00:00:00Z). This is required only when building a --reproducible package.

func WriteFile

func WriteFile(path string, contents []byte, mode os.FileMode, buildReproducibly bool) error

WriteFile acts like ioutil.WriteFile, but calls ResetTimestamp if buildReproducibly is true.

Types

type DirectorySection

type DirectorySection struct {
	Path  string
	Mode  string      //see above
	Owner interface{} //see above
	Group interface{} //see above
}

DirectorySection only needs a nice exported name for the TOML parser to produce more meaningful error messages on malformed input data.

type ErrorCollector

type ErrorCollector struct {
	Errors []error
}

ErrorCollector is a wrapper around []error that simplifies code where multiple errors can happen and need to be aggregated for collective display in an error display.

func (*ErrorCollector) Add

func (c *ErrorCollector) Add(err error)

Add adds an error to this collector. If nil is given, nothing happens, so you can safely write

ec.Add(OperationThatMightFail())

instead of

err := OperationThatMightFail()
if err != nil {
    ec.Add(err)
}

func (*ErrorCollector) Addf

func (c *ErrorCollector) Addf(format string, args ...interface{})

Addf adds an error to this collector by passing the arguments into fmt.Errorf(). If only one argument is given, it is used as error string verbatim.

type FSEntry

type FSEntry struct {
	Type    int
	Path    string
	Content string       //except directories (has content for regular files, target for symlinks)
	Mode    os.FileMode  //except symlinks
	Owner   *IntOrString //except symlinks
	Group   *IntOrString //except symlinks
}

FSEntry represents a file, directory or symlink in the package.

type FileSection

type FileSection struct {
	Path        string
	Content     string
	ContentFrom string
	Raw         bool
	Mode        string      //TOML does not support octal number literals, so we have to write: mode = "0666"
	Owner       interface{} //either string (name) or integer (ID)
	Group       interface{} //same

}

FileSection only needs a nice exported name for the TOML parser to produce more meaningful error messages on malformed input data.

type Generator

type Generator interface {
	//Validate performs additional validations on pkg that are specific to the
	//concrete generator. For example, if the package format imposes additional
	//restrictions on the format of certain fields (names, versions, etc.), they
	//should be checked here.
	//
	//If the package is valid, an empty slice is to be returned.
	Validate(pkg *Package) []error
	//Build produces the final package (usually a compressed tar file) in the
	//return argument. When it is called, all files and directories contained
	//in the package definition have already been materialized in the temporary
	//directory specified in the second argument.
	//
	//For example, if pkg contains the file
	//
	//    [[file]]
	//    name = "/etc/foo.conf"
	//    content = "xxx"
	//    mode = "0400"
	//    owner = "root"
	//    group = "root"
	//
	//Then this file has already been placed at `rootPath+"/etc/foo.conf"` with
	//the right content, ownership, and permissions. The generator usually just
	//has to write the package metadata into the temporary directory, tar the
	//directory and compress it.
	//
	//If `buildReproducibly` is true, the package must be built such that every
	//run (even across systems) produces an identical result. For example, no
	//timestamps or generator version information may be included.
	Build(pkg *Package, rootPath string, buildReproducibly bool) ([]byte, error)
	//Generate the recommended file name for this package. Distributions
	//usually have guidelines for this sort of thing. The string returned must
	//be a plain file name, not a path.
	RecommendedFileName(pkg *Package) string
}

Generator is a generic interface for the package generator implementations. One Generator exists for every target package format (e.g. pacman, dpkg, RPM) supported by holo-build.

type GroupSection

type GroupSection struct {
	Name   string `toml:"name"`
	Gid    uint32 `toml:"gid"`
	System bool   `toml:"system"`
}

GroupSection only needs a nice exported name for the TOML parser to produce more meaningful error messages on malformed input data.

type IntOrString

type IntOrString struct {
	Int uint32
	Str string
}

IntOrString is used for FsEntry.Owner and FSEntry.Group that can be either int or string.

type Package

type Package struct {
	//Name is the package name.
	Name string
	//Version is the version for the package contents. While many package
	//formats are more or less liberal about the format of version strings,
	//holo-build requires versions to adhere to the Semantic Version format
	//(semver.org). Build metadata is not supported, while as an extension, we
	//support an arbitrary number of segments in the initial
	//"MAJOR.MINOR.PATCH" part.
	Version string
	//Release is a counter that can be increased when the same version of one
	//hologram needs to be rebuilt. The default value is 1.
	Release uint
	//Epoch is a counter that can be increased when the version of a newer
	//package is smaller than the previous version, thus breaking normal
	//version comparison logic. This is usually only necessary when changing to
	//a different version numbering scheme. The default value is 0, which
	//usually results in the epoch not being shown in the combined version
	//string at all.
	Epoch uint
	//Description is the optional package description.
	Description string
	//Author contains the package's author's name and mail address in the form
	//"Firstname Lastname <email.address@server.tld>", if this information is
	//available.
	Author string
	//Requires contains a list of other packages that are required dependencies
	//for this package and thus must be installed together with this package.
	//This is called "Depends" by some package managers.
	Requires []PackageRelation
	//Provides contains a list of packages that this package provides features
	//of (or virtual packages whose capabilities it implements).
	Provides []PackageRelation
	//Conflicts contains a list of other packages that cannot be installed at
	//the same time as this package.
	Conflicts []PackageRelation
	//Replaces contains a list of obsolete packages that are replaced by this
	//package. Upon performing a system upgrade, the obsolete packages will be
	//automatically replaced by this package.
	Replaces []PackageRelation
	//SetupScript contains a shell script that is executed when the package is
	//installed or upgraded.
	SetupScript string
	//CleanupScript contains a shell script that is executed when the package is
	//installed or upgraded.
	CleanupScript string
	//Entries lists the files and directories contained within this package.
	FSEntries []FSEntry
}

Package contains all information about a single package. This representation will be passed into the generator backends.

func ParsePackageDefinition

func ParsePackageDefinition(input io.Reader) (*Package, []error)

ParsePackageDefinition parses a package definition from the given input. The operation is successful if the returned []error is nil or empty.

func (*Package) Build

func (pkg *Package) Build(generator Generator, printToStdout bool, buildReproducibly bool) error

Build builds the package using the given Generator.

func (*Package) InstalledSizeInBytes

func (pkg *Package) InstalledSizeInBytes() int

InstalledSizeInBytes approximates the apparent size of the given directory and everything in it, as calculated by `du -s --apparent-size`, but in a filesystem-independent way.

type PackageDefinition

type PackageDefinition struct {
	Package   PackageSection
	File      []FileSection
	Directory []DirectorySection
	Symlink   []SymlinkSection
	User      []UserSection  //see common/entities.go
	Group     []GroupSection //see common/entities.go
}

PackageDefinition only needs a nice exported name for the TOML parser to produce more meaningful error messages on malformed input data.

type PackageRelation

type PackageRelation struct {
	RelatedPackage string
	Constraints    []VersionConstraint
}

PackageRelation declares a relation to another package. For the related package, any number of version constraints may be given. For example, the following snippet makes a Package require any version of package "foo", and at least version 2.1.2 (but less than version 3.0) of package "bar".

pkg.Requires := []PackageRelation{
    PackageRelation { "foo", nil },
    PackageRelation { "bar", []VersionConstraint{
        VersionConstraint { ">=", "2.1.2" },
        VersionConstraint { "<",  "3.0"   },
    }
}

type PackageSection

type PackageSection struct {
	Name           string
	Version        string
	Release        uint
	Epoch          uint
	Description    string
	Author         string
	Requires       []string
	Provides       []string
	Conflicts      []string
	Replaces       []string
	SetupScript    string
	CleanupScript  string
	DefinitionFile string //see compileEntityDefinitions
}

PackageSection only needs a nice exported name for the TOML parser to produce more meaningful error messages on malformed input data.

type SymlinkSection

type SymlinkSection struct {
	Path   string
	Target string
}

SymlinkSection only needs a nice exported name for the TOML parser to produce more meaningful error messages on malformed input data.

type UserSection

type UserSection struct {
	Name    string   `toml:"name"`
	Comment string   `toml:"comment"`
	UID     uint32   `toml:"uid"`
	System  bool     `toml:"system"`
	Home    string   `toml:"home"`
	Group   string   `toml:"group"`
	Groups  []string `toml:"groups"`
	Shell   string   `toml:"shell"`
}

UserSection only needs a nice exported name for the TOML parser to produce more meaningful error messages on malformed input data.

type VersionConstraint

type VersionConstraint struct {
	//Relation is one of "<", "<=", "=", ">=" or ">".
	Relation string
	//Version is the version on the right side of the Relation, e.g. "1.2.3-1"
	//or "2:20151024-1.1".  This field is not structured further in this level
	//since the acceptable version format may depend on the package generator
	//used.
	Version string
}

VersionConstraint is used by the PackageRelation struct to specify version constraints for a related package.