deb

Documentation

Overview

Package deb is used to build debian binary packages (.deb), based on the debian package specification. It does not handle source, source package, or changes.

The bulk of the configuration options and functionalty are associated with PackageSpec. Refer to that section for more details.

References

https://www.debian.org/doc/debian-policy/ch-controlfields.html

https://www.debian.org/doc/manuals/debian-faq/ch-pkg_basics.en.html

Index

• func FileExists(path string) bool
• func SupportedArchitectures() []string
• type PackageSpec
  • func DefaultPackageSpec() *PackageSpec
  • func NewPackageSpecFromFile(filename string) (*PackageSpec, error)
  • func NewPackageSpecFromJSON(data []byte) (*PackageSpec, error)
  • func (p *PackageSpec) Build(target string) error
  • func (p *PackageSpec) CalculateChecksums() ([]byte, error)
  • func (p *PackageSpec) CalculateSize() (int64, error)
  • func (p *PackageSpec) CreateControlArchive(target string) error
  • func (p *PackageSpec) CreateDataArchive(target string) error
  • func (p *PackageSpec) Filename() string
  • func (p *PackageSpec) ListEtcFiles() ([]string, error)
  • func (p *PackageSpec) ListFiles(includeDirs bool) ([]string, error)
  • func (p *PackageSpec) MapControlFiles() map[string]string
  • func (p *PackageSpec) NormalizeFilename(filename string) (string, error)
  • func (p *PackageSpec) RenderControlFile() ([]byte, error)
  • func (p *PackageSpec) Validate(buildTime bool) error

Functions

func FileExists

func FileExists(path string) bool

FileExists returns true if the specified file/dir exists and we can stat it

func SupportedArchitectures

func SupportedArchitectures() []string

SupportedArchitectures lists the architectures that are accepted by the validator

Types

type PackageSpec

type PackageSpec struct {
	// Binary Debian Control File - Required fields
	Package      string `json:"package"`
	Version      string `json:"-"`
	Architecture string `json:"architecture"`
	Maintainer   string `json:"maintainer"`
	Description  string `json:"description"`

	// Optional Fields
	Depends    []string `json:"depends"`
	PreDepends []string `json:"preDepends"`
	Conflicts  []string `json:"conflicts,omitempty"`
	Breaks     []string `json:"breaks,omitempty"`
	Replaces   []string `json:"replaces,omitempty"`
	Section    string   `json:"section"`  // Defaults to "default"
	Priority   string   `json:"priority"` // Defaults to "extra"
	Homepage   string   `json:"homepage"`

	// Control Scripts
	Preinst  string `json:"preinst"`
	Postinst string `json:"postinst"`
	Prerm    string `json:"prerm"`
	Postrm   string `json:"postrm"`

	// Build time options
	AutoPath         string            `json:"autoPath"` // Defaults to "deb-pkg"
	Files            map[string]string `json:"files"`
	TempPath         string            `json:"tempPath,omitempty"`
	PreserveSymlinks bool              `json:"preserveSymlinks,omitempty"`
	UpgradeConfigs   bool              `json:"upgradeConfigs,omitempty"`

	// Derived fields
	InstalledSize int64 `json:"-"` // Kilobytes, rounded up. Derived from file sizes.
}

PackageSpec is parsed from JSON and initializes both build time parameters and the metadata inside the .deb package.

Required Fields

The following fields are required by the debian package specification:

Package is the name of your package, and typically matches the name of your main program.

Version is a debian version string. See the reference for more details. This field is not currently validated except to verify that it is specified, but if the syntax is invalid you will not be able to install the package.

Architecture is the CPU architecture your package is compiled for. If your package does not include a compiled binary you can set this to "all".

Maintainer should indicate contact information for the package, such as Chris Bednarski <chris@example.com>

Description should briefly explain what your package is used for. Only a single line is currently supported.

Optional Fields

Depends is used to specify whether your package depends on other packages. Dependencies should be specified using the following syntax

"depends": [
    "curl (>= 7.0.0)",
    "python (= 2.7.12)",
    "tree"
]

Conflicts, Breaks, and Replaces work in a very similar way. For additional information on when you should use optional fields and how to specify them, refer to the debian package specification.

Homepage should link to your package's source repository, if applicable. Otherwise link to your website.

Control Scripts

You may need to perform additional setup (or cleanup) when (un)installing a package. You can do this through the control scripts: preinst, postinst, prerm, and postrm.

These are commonly used to create users, start or stop services, or perform cleanup when a package is uninstalled.

AutoPath

The Build method is designed to automatically fill in most of the build configuration based on files it finds on the filesystem. If AutoPath is set to a non-empty value it will be scanned for pre/post/inst/rm scripts as well as configuration files and binaries to be automatically included in the .deb.

To disable the automatic behavior set AutoPath to an empty string or dash "-". Whether or not AutoPath is used you may supplement the list of files to be included by specifying the Files field.

Build Time Options

TempPath controls where intermediate files are written during the build. This defaults to the system temp directory (usually /tmp).

UpgradeConfigs causes a package upgrade to replace all of the config files. By default files under /etc are left as-is when upgrading a package so you can keep changes made to your config files, but if you want to upgrade the config files themselves you will need to set UpgradeConfigs to true.

PreserveSymlinks writes symlinks to the archive. By default the contents of the file the symlink is pointing to is copied into the .deb package.

Derived Fields

InstalledSize is calculated based on the total size of your files and control scripts. You should not specify this yourself.

For details on how to use pre/post/inst/rm and various .deb-specific fields please refere to the debian package specification:

https://www.debian.org/doc/debian-policy/ch-controlfields.html

https://www.debian.org/doc/manuals/debian-faq/ch-pkg_basics.en.html

func DefaultPackageSpec

func DefaultPackageSpec() *PackageSpec

DefaultPackageSpec includes default values for package specifications. This simplifies configuration so a user need only specify required fields to build

func NewPackageSpecFromFile

func NewPackageSpecFromFile(filename string) (*PackageSpec, error)

NewPackageSpecFromFile creates a PackageSpec from a JSON file

func NewPackageSpecFromJSON

func NewPackageSpecFromJSON(data []byte) (*PackageSpec, error)

NewPackageSpecFromJSON creates a PackageSpec from JSON data

func (*PackageSpec) Build

func (p *PackageSpec) Build(target string) error

Build creates a .deb file in the target directory. The name is defived from Filename() so you can find it with:

path.Join(target, PackageSpec.Filename())

func (*PackageSpec) CalculateChecksums

func (p *PackageSpec) CalculateChecksums() ([]byte, error)

CalculateChecksums produces the contents of the md5sums file with the following format:

checksum  file1
checksum  file2

All files returned by ListFiles() are included

func (*PackageSpec) CalculateSize

func (p *PackageSpec) CalculateSize() (int64, error)

CalculateSize returns the size in Kilobytes of all files in the package.

func (*PackageSpec) CreateControlArchive

func (p *PackageSpec) CreateControlArchive(target string) error

CreateControlArchive creates the control.tar.gz part of the .deb package This includes:

conffiles
md5sums
control
pre/post/inst/rm scripts (if any)

You must pass in a file handle that is open for writing.

func (*PackageSpec) CreateDataArchive

func (p *PackageSpec) CreateDataArchive(target string) error

CreateDataArchive creates

func (*PackageSpec) Filename

func (p *PackageSpec) Filename() string

Filename derives the standard debian filename as package-version-arch.deb based on the data specified in PackageSpec.

func (*PackageSpec) ListEtcFiles

func (p *PackageSpec) ListEtcFiles() ([]string, error)

ListEtcFiles lists all of the configuration files that are packaged under /etc in the archive so they can be added to conffiles. These will be normalized to include a leading /

func (*PackageSpec) ListFiles

func (p *PackageSpec) ListFiles(includeDirs bool) ([]string, error)

ListFiles returns a list of files that will be included in the archive, identified by their source paths.

These files will later be written into the archive using a path derived via NormalizeFilename().

func (*PackageSpec) MapControlFiles

func (p *PackageSpec) MapControlFiles() map[string]string

MapControlFiles returns a list of optional control scripts including pre/post/inst/rm that are used in this package.

func (*PackageSpec) NormalizeFilename

func (p *PackageSpec) NormalizeFilename(filename string) (string, error)

NormalizeFilename converts a local filename into a target archive filename by either using the PackageSpec.Files map or by stripping the AutoPath prefix from the file path. For example, deb-pkg/etc/blah will become ./etc/blah and a file mapped from config to /etc/config will become ./etc/config in the archive

func (*PackageSpec) RenderControlFile

func (p *PackageSpec) RenderControlFile() ([]byte, error)

RenderControlFile creates a debian control file for this package.

func (*PackageSpec) Validate

func (p *PackageSpec) Validate(buildTime bool) error

Validate checks the syntax of various text fields in PackageSpec to verify that they conform to the debian package specification. Errors from this call should be passed to the user so they can fix errors in their config file.