debian: pault.ag/go/debian/control Index | Files

package control

import "pault.ag/go/debian/control"

Parse the Debian control file format.

Index

Package Files

changes.go control.go decode.go doc.go dsc.go encode.go filehash.go index.go parse.go

func Marshal Uses

func Marshal(writer io.Writer, data interface{}) error

Marshal is a one-off interface to serialize a single object to a writer.

Most notably, this will *not* separate Paragraphs with a newline as is expected upon repeated calls, please use the Encoder streaming interface for that.

It's also worth noting that this *will* also write out elements that were Unmarshaled into a Struct without a member of that name if (and only if) the target Struct contains a `control.Paragraph` anonymous member.

This is handy if the Unmarshaler was given any `X-*` keys that were not present on your Struct.

Given a struct (or list of structs), write to the io.Writer stream in the RFC822-alike Debian control-file format

This code will attempt to unpack it into the struct based on the literal name of the key, This can be overridden by the struct tag `control:""`.

If you're dehydrating a list of strings, you have the option of defining a string to join the tokens with (`delim:", "`).

In order to Marshal a custom Struct, you are required to implement the Marshallable interface. It's highly encouraged to put this interface on the struct without a pointer receiver, so that pass-by-value works when you call Marshal.

func Unmarshal Uses

func Unmarshal(data interface{}, reader io.Reader) error

Given a struct (or list of structs), read the io.Reader RFC822-alike Debian control-file stream into the struct, unpacking keys into the struct as needed. If a list of structs is given, unpack all RFC822 Paragraphs into the structs.

This code will attempt to unpack it into the struct based on the literal name of the key, compared byte-for-byte. If this is not OK, the struct tag `control:""` can be used to define the key to use in the RFC822 stream.

If you're unpacking into a list of strings, you have the option of defining a string to split tokens on (`delim:", "`), and things to strip off each element (`strip:"\n\r\t "`).

If you're unpacking into a struct, the struct will be walked according to the rules above. If you wish to override how this writes to the nested struct, objects that implement the Unmarshallable interface will be Unmarshaled via that method call only.

Structs that contain Paragraph as an Anonymous member will have that member populated with the parsed RFC822 block, to allow access to the .Values and .Order members.

func UnpackFromParagraph Uses

func UnpackFromParagraph(para Paragraph, incoming interface{}) error

Unpack a Paragraph into a Struct, as if that data had been unpacked into that struct to begin with. The normal rules from running the Unmarshal API directly apply when unpacking a Paragraph using UnpackFromParagraph.

In most cases, the Unmarshal API should be sufficient. Use of this API is mildly discouraged.

type BestChecksums Uses

type BestChecksums struct {
    ChecksumsSha256 []SHA256FileHash `control:"Checksums-Sha256" delim:"\n" strip:"\n\r\t "`
    ChecksumsSha512 []SHA256FileHash `control:"Checksums-Sha512" delim:"\n" strip:"\n\r\t "`
}

BestChecksums can be included in a struct instead of e.g. ChecksumsSha256.

BestChecksums uses cryptographically secure checksums, so that application code does not need to worry about that.

The struct fields of BestChecksums need to be exported for the unmarshaling process but most not be used directly. Use the Checksums() accessor instead.

func (*BestChecksums) Checksums Uses

func (b *BestChecksums) Checksums() []FileHash

Checksums returns FileHashes of a cryptographically secure kind.

type BinaryIndex Uses

type BinaryIndex struct {
    Paragraph

    Package        string
    Source         string
    Version        version.Version
    InstalledSize  string `control:"Installed-Size"`
    Maintainer     string
    Architecture   dependency.Arch
    MultiArch      string `control:"Multi-Arch"`
    Description    string
    Homepage       string
    DescriptionMD5 string   `control:"Description-md5"`
    Tags           []string `delim:", "`
    Section        string
    Priority       string
    Filename       string
    Size           string
    MD5sum         string
    SHA1           string
    SHA256         string

    DebugBuildIds []string `control:"Build-Ids" delim:" "`
}

The BinaryIndex struct represents the exported APT Binary package index file, as seen on Debian (and Debian derived) mirrors, as well as the cached version in /var/lib/apt/lists/.

This can be used to examine Binary packages contained in the Archive, to examine things like Built-Using, Depends, Tags or Binary packages present on an Architecture.

func ParseBinaryIndex Uses

func ParseBinaryIndex(reader *bufio.Reader) (ret []BinaryIndex, err error)

Given a reader, parse out a list of BinaryIndex structs.

func (*BinaryIndex) GetBreaks Uses

func (index *BinaryIndex) GetBreaks() dependency.Dependency

Parse the Depends Breaks relation on this package.

func (*BinaryIndex) GetBuiltUsing Uses

func (index *BinaryIndex) GetBuiltUsing() dependency.Dependency

Parse the Built-Depends relation on this package.

func (*BinaryIndex) GetDepends Uses

func (index *BinaryIndex) GetDepends() dependency.Dependency

Parse the Depends Dependency relation on this package.

func (*BinaryIndex) GetPreDepends Uses

func (index *BinaryIndex) GetPreDepends() dependency.Dependency

Parse the Depends Pre-Depends relation on this package.

func (*BinaryIndex) GetReplaces Uses

func (index *BinaryIndex) GetReplaces() dependency.Dependency

Parse the Depends Replaces relation on this package.

func (*BinaryIndex) GetSuggests Uses

func (index *BinaryIndex) GetSuggests() dependency.Dependency

Parse the Depends Suggests relation on this package.

func (*BinaryIndex) SourcePackage Uses

func (index *BinaryIndex) SourcePackage() string

SourcePackage returns the Debian source package name from which this binary Package was built, coping with the special cases Source == Package (skipped for efficiency) and binNMUs (Source contains version number).

type BinaryParagraph Uses

type BinaryParagraph struct {
    Paragraph
    Architectures []dependency.Arch `control:"Architecture"`
    Package       string
    Priority      string
    Section       string
    Essential     bool
    Description   string

    Depends    dependency.Dependency
    Recommends dependency.Dependency
    Suggests   dependency.Dependency
    Enhances   dependency.Dependency
    PreDepends dependency.Dependency `control:"Pre-Depends"`

    Breaks    dependency.Dependency
    Conflicts dependency.Dependency
    Replaces  dependency.Dependency

    BuiltUsing dependency.Dependency `control:"Built-Using"`
}

Encapsulation for a debian/control Binary control entry. This contains information that will be eventually put lovingly into the .deb file after it's built on a given Arch.

type Changes Uses

type Changes struct {
    Paragraph

    Filename string

    Format          string
    Source          string
    Binaries        []string          `control:"Binary" delim:" "`
    Architectures   []dependency.Arch `control:"Architecture"`
    Version         version.Version
    Origin          string
    Distribution    string
    Urgency         string
    Maintainer      string
    ChangedBy       string `control:"Changed-By"`
    Closes          []string
    Changes         string
    ChecksumsSha1   []SHA1FileHash            `control:"Checksums-Sha1" delim:"\n" strip:"\n\r\t "`
    ChecksumsSha256 []SHA256FileHash          `control:"Checksums-Sha256" delim:"\n" strip:"\n\r\t "`
    Files           []FileListChangesFileHash `control:"Files" delim:"\n" strip:"\n\r\t "`
}

The Changes struct is the default encapsulation of the Debian .changes package filetype.This struct contains an anonymous member of type Paragraph, allowing you to use the standard .Values and .Order of the Paragraph type.

The .changes files are used by the Debian archive maintenance software to process updates to packages. They consist of a single paragraph, possibly surrounded by a PGP signature. That paragraph contains information from the debian/control file and other data about the source package gathered via debian/changelog and debian/rules.

func ParseChanges Uses

func ParseChanges(reader *bufio.Reader, path string) (*Changes, error)

Given a bufio.Reader, consume the Reader, and return a Changes object for use. The "path" argument is used to set Changes.Filename, which is used by Changes.GetDSC, Changes.Remove, Changes.Move and Changes.Copy to figure out where all the files on the filesystem are. This value can be set to something invalid if you're not using those functions.

func ParseChangesFile Uses

func ParseChangesFile(path string) (ret *Changes, err error)

Given a path on the filesystem, Parse the file off the disk and return a pointer to a brand new Changes struct, unless error is set to a value other than nil.

func (*Changes) AbsFiles Uses

func (changes *Changes) AbsFiles() []FileListChangesFileHash

Return a list of FileListChangesFileHash entries from the `changes.Files` entry, with the exception that each `Filename` will be joined to the root directory of the Changes file.

func (*Changes) Copy Uses

func (changes *Changes) Copy(dest string) error

Copy the .changes file and all referenced files to the directory listed by the dest argument. This function will error out if the dest argument is not a directory, or if there is an IO operation in transfer.

This function will always move .changes last, making it suitable to be used to move something into an incoming directory with an inotify hook. This will also mutate Changes.Filename to match the new location.

func (*Changes) GetDSC Uses

func (changes *Changes) GetDSC() (*DSC, error)

Return a DSC struct for the DSC listed in the .changes file. This requires Changes.Filename to be correctly set, and for the .dsc file to exist in the correct place next to the .changes.

This function may also return an error if the given .changes does not include the .dsc (binary-only upload)

func (*Changes) Move Uses

func (changes *Changes) Move(dest string) error

Move the .changes file and all referenced files to the directory listed by the dest argument. This function will error out if the dest argument is not a directory, or if there is an IO operation in transfer.

This function will always move .changes last, making it suitable to be used to move something into an incoming directory with an inotify hook. This will also mutate Changes.Filename to match the new location.

func (*Changes) Remove Uses

func (changes *Changes) Remove() error

Remove the .changes file and any associated files. This function will always remove the .changes last, in the event there are filesystem i/o errors on removing associated files.

type Control Uses

type Control struct {
    Filename string

    Source   SourceParagraph
    Binaries []BinaryParagraph
}

Encapsulation for a debian/control file, which is a series of RFC2822-like blocks, starting with a Source control paragraph, and then a series of Binary control paragraphs.

The debian/control file contains the most vital (and version-independent) information about the source package and about the binary packages it creates.

The first paragraph of the control file contains information about the source package in general. The subsequent sets each describe a binary package that the source tree builds.

func ParseControl Uses

func ParseControl(reader *bufio.Reader, path string) (*Control, error)

Given a bufio.Reader, consume the Reader, and return a Control object for use.

func ParseControlFile Uses

func ParseControlFile(path string) (ret *Control, err error)

Given a path on the filesystem, Parse the file off the disk and return a pointer to a brand new Control struct, unless error is set to a value other than nil.

type DSC Uses

type DSC struct {
    Paragraph

    Filename string

    Format           string
    Source           string
    Binaries         []string          `control:"Binary" delim:","`
    Architectures    []dependency.Arch `control:"Architecture"`
    Version          version.Version
    Origin           string
    Maintainer       string
    Uploaders        []string
    Homepage         string
    StandardsVersion string `control:"Standards-Version"`

    BuildDepends      dependency.Dependency `control:"Build-Depends"`
    BuildDependsArch  dependency.Dependency `control:"Build-Depends-Arch"`
    BuildDependsIndep dependency.Dependency `control:"Build-Depends-Indep"`

    ChecksumsSha1   []SHA1FileHash   `control:"Checksums-Sha1" delim:"\n" strip:"\n\r\t "`
    ChecksumsSha256 []SHA256FileHash `control:"Checksums-Sha256" delim:"\n" strip:"\n\r\t "`
    Files           []MD5FileHash    `control:"Files" delim:"\n" strip:"\n\r\t "`
}

A DSC is the encapsulation of a Debian .dsc control file. This contains information about the source package, and is general handy.

The Debian source control file is generated by dpkg-source when it builds the source archive, from other files in the source package. When unpacking, it is checked against the files and directories in the other parts of the source package.

func OrderDSCForBuild Uses

func OrderDSCForBuild(dscs []DSC, arch dependency.Arch) ([]DSC, error)

Given a bunch of DSC objects, sort the packages topologically by build order by looking at the relationship between the Build-Depends field.

func ParseDsc Uses

func ParseDsc(reader *bufio.Reader, path string) (*DSC, error)

Given a bufio.Reader, consume the Reader, and return a DSC object for use.

func ParseDscFile Uses

func ParseDscFile(path string) (ret *DSC, err error)

Given a path on the filesystem, Parse the file off the disk and return a pointer to a brand new DSC struct, unless error is set to a value other than nil.

func (*DSC) AbsFiles Uses

func (d *DSC) AbsFiles() []MD5FileHash

Return a list of MD5FileHash entries from the `dsc.Files` entry, with the exception that each `Filename` will be joined to the root directory of the DSC file.

func (*DSC) Copy Uses

func (d *DSC) Copy(dest string) error

Copy the .dsc file and all referenced files to the directory listed by the dest argument. This function will error out if the dest argument is not a directory, or if there is an IO operation in transfer.

This function will always move .dsc last, making it suitable to be used to move something into an incoming directory with an inotify hook. This will also mutate DSC.Filename to match the new location.

func (*DSC) DebianSource Uses

func (d *DSC) DebianSource() (string, error)

Return the name of the Debian source. This is assumed to be the first file that contains ".debian." in its name.

func (*DSC) HasArchAll Uses

func (d *DSC) HasArchAll() bool

Check to see if this .dsc contains any arch:all binary packages along with any arch dependent packages.

func (*DSC) Maintainers Uses

func (d *DSC) Maintainers() []string

Return a list of all entities that are responsible for the package's well being. The 0th element is always the package's Maintainer, with any Uploaders following.

func (*DSC) Move Uses

func (d *DSC) Move(dest string) error

Move the .dsc file and all referenced files to the directory listed by the dest argument. This function will error out if the dest argument is not a directory, or if there is an IO operation in transfer.

This function will always move .dsc last, making it suitable to be used to move something into an incoming directory with an inotify hook. This will also mutate DSC.Filename to match the new location.

func (*DSC) Remove Uses

func (d *DSC) Remove() error

Remove the .dsc file and any associated files. This function will always remove the .dsc last, in the event there are filesystem i/o errors on removing associated files.

type Decoder Uses

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

func NewDecoder Uses

func NewDecoder(reader io.Reader, keyring *openpgp.EntityList) (*Decoder, error)

func (*Decoder) Decode Uses

func (d *Decoder) Decode(into interface{}) error

func (*Decoder) Signer Uses

func (d *Decoder) Signer() *openpgp.Entity

type Encoder Uses

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

Encoder is a struct that allows for the streaming Encoding of data back out to an `io.Writer`. Most notably, this will separate subsequent `Encode` calls of a Struct with a newline.

It's also worth noting that this *will* also write out elements that were Unmarshaled into a Struct without a member of that name if (and only if) the target Struct contains a `control.Paragraph` anonymous member.

This is handy if the Unmarshaler was given any `X-*` keys that were not present on your Struct.

Given a struct (or list of structs), write to the io.Writer stream in the RFC822-alike Debian control-file format

This code will attempt to unpack it into the struct based on the literal name of the key, This can be overridden by the struct tag `control:""`.

If you're dehydrating a list of strings, you have the option of defining a string to join the tokens with (`delim:", "`).

In order to Marshal a custom Struct, you are required to implement the Marshallable interface. It's highly encouraged to put this interface on the struct without a pointer receiver, so that pass-by-value works when you call Marshal.

func NewEncoder Uses

func NewEncoder(writer io.Writer) (*Encoder, error)

Create a new Encoder, which is configured to write to the given `io.Writer`.

func (*Encoder) Encode Uses

func (e *Encoder) Encode(incoming interface{}) error

Take a Struct, Encode it into a Paragraph, and write that out to the io.Writer set up when the Encoder was configured.

type FileHash Uses

type FileHash struct {
    // cb136f28a8c971d4299cc68e8fdad93a8ca7daf3 1131 dput-ng_1.9.dsc
    Algorithm string
    Hash      string
    Size      int64
    Filename  string
    ByHash    string
}

A FileHash is an entry as found in the Files, Checksum-Sha1, and Checksum-Sha256 entry for the .dsc or .changes files.

func FileHashFromHasher Uses

func FileHashFromHasher(path string, hasher hashio.Hasher) FileHash

func (*FileHash) ByHashPath Uses

func (c *FileHash) ByHashPath(path string) string

ByHashPath returns the corresponding /by-hash/<algorithm>/<hash> path. This function must only be used if the release supports AcquireByHash.

func (*FileHash) Verifier Uses

func (c *FileHash) Verifier() (io.WriteCloser, error)

Verifier returns an io.WriteCloser which verifies the hash of the data being written to it and fails Close() upon hash mismatch.

Example:

verifier := fh.Verifier()
r = io.TeeReader(r, verifier)
if _, err := io.Copy(f, r); err != nil {
    return err
}
if err := verifier.Close(); err != nil {
    return err
}

type FileHashes Uses

type FileHashes []FileHash

type FileListChangesFileHash Uses

type FileListChangesFileHash struct {
    FileHash

    Component string
    Priority  string
}

func (*FileListChangesFileHash) UnmarshalControl Uses

func (c *FileListChangesFileHash) UnmarshalControl(data string) error

type MD5FileHash Uses

type MD5FileHash struct{ FileHash }

func (MD5FileHash) MarshalControl Uses

func (c MD5FileHash) MarshalControl() (string, error)

func (*MD5FileHash) UnmarshalControl Uses

func (c *MD5FileHash) UnmarshalControl(data string) error

type Marshallable Uses

type Marshallable interface {
    MarshalControl() (string, error)
}

The Marshallable interface defines the interface that Marshal will use to do custom dehydration of the Struct back into the Debian 822 format.

type Paragraph Uses

type Paragraph struct {
    Values map[string]string
    Order  []string
}

A Paragraph is a block of RFC2822-like key value pairs. This struct contains two methods to fetch values, a Map called Values, and a Slice called Order, which maintains the ordering as defined in the RFC2822-like block

func ConvertToParagraph Uses

func ConvertToParagraph(incoming interface{}) (*Paragraph, error)

Given a Struct, convert that Struct back into a control.Paragraph. This is not exactly useful as part of the external API, but may be useful in some funny circumstances where you need to treat a Struct you Unmarshaled into as a control.Paragraph again.

In most cases, the Marshal API should be sufficient. Use of this API is mildly discouraged.

func (*Paragraph) Set Uses

func (p *Paragraph) Set(key, value string)

func (*Paragraph) Update Uses

func (p *Paragraph) Update(other Paragraph) Paragraph

func (*Paragraph) WriteTo Uses

func (p *Paragraph) WriteTo(out io.Writer) error

type ParagraphReader Uses

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

Wrapper to allow iteration on a set of Paragraphs without consuming them all into memory at one time. This is also the level in which data is signed, so information such as the entity that signed these documents can be read by calling the `.Signer` method on this struct. The next unread Paragraph can be returned by calling the `.Next` method on this struct.

func NewParagraphReader Uses

func NewParagraphReader(reader io.Reader, keyring *openpgp.EntityList) (*ParagraphReader, error)

Create a new ParagraphReader from the given `io.Reader`, and `keyring`. if `keyring` is set to `nil`, this will result in all OpenPGP signature checking being disabled. *including* that the contents match!

Also keep in mind, `reader` may be consumed 100% in memory due to the underlying OpenPGP API being hella fiddly.

func (*ParagraphReader) All Uses

func (p *ParagraphReader) All() ([]Paragraph, error)

func (*ParagraphReader) Next Uses

func (p *ParagraphReader) Next() (*Paragraph, error)

Consume the io.Reader and return the next parsed Paragraph, modulo garbage lines causing us to return an error.

func (*ParagraphReader) Signer Uses

func (p *ParagraphReader) Signer() *openpgp.Entity

Return the Entity (if one exists) that signed this set of Paragraphs.

type SHA1FileHash Uses

type SHA1FileHash struct{ FileHash }

func (SHA1FileHash) MarshalControl Uses

func (c SHA1FileHash) MarshalControl() (string, error)

func (*SHA1FileHash) UnmarshalControl Uses

func (c *SHA1FileHash) UnmarshalControl(data string) error

type SHA256FileHash Uses

type SHA256FileHash struct{ FileHash }

func (SHA256FileHash) MarshalControl Uses

func (c SHA256FileHash) MarshalControl() (string, error)

func (*SHA256FileHash) UnmarshalControl Uses

func (c *SHA256FileHash) UnmarshalControl(data string) error

type SHA512FileHash Uses

type SHA512FileHash struct{ FileHash }

func (SHA512FileHash) MarshalControl Uses

func (c SHA512FileHash) MarshalControl() (string, error)

func (*SHA512FileHash) UnmarshalControl Uses

func (c *SHA512FileHash) UnmarshalControl(data string) error

type SourceIndex Uses

type SourceIndex struct {
    Paragraph

    Package  string
    Binaries []string `control:"Binary" delim:","`

    Version    version.Version
    Maintainer string
    Uploaders  string `delim:","`

    Architecture []dependency.Arch

    StandardsVersion string
    Format           string
    Files            []string `delim:"\n"`
    VcsBrowser       string   `control:"Vcs-Browser"`
    VcsGit           string   `control:"Vcs-Git"`
    VcsSvn           string   `control:"Vcs-Svn"`
    VcsBzr           string   `control:"Vcs-Bzr"`
    Homepage         string
    Directory        string
    Priority         string
    Section          string
}

The SourceIndex struct represents the exported APT Source index file, as seen on Debian (and Debian derived) mirrors, as well as the cached version in /var/lib/apt/lists/.

This can be used to examine Source packages, to examine things like Binary packages built by Source packages, who maintains a package, or where to find the VCS repo for that package.

func ParseSourceIndex Uses

func ParseSourceIndex(reader *bufio.Reader) (ret []SourceIndex, err error)

Given a reader, parse out a list of SourceIndex structs.

func (*SourceIndex) GetBuildDepends Uses

func (index *SourceIndex) GetBuildDepends() dependency.Dependency

Parse the Depends Build-Depends relation on this package.

func (*SourceIndex) GetBuildDependsArch Uses

func (index *SourceIndex) GetBuildDependsArch() dependency.Dependency

Parse the Depends Build-Depends-Arch relation on this package.

func (*SourceIndex) GetBuildDependsIndep Uses

func (index *SourceIndex) GetBuildDependsIndep() dependency.Dependency

Parse the Depends Build-Depends-Indep relation on this package.

type SourceParagraph Uses

type SourceParagraph struct {
    Paragraph

    Maintainer  string
    Uploaders   []string `delim:","`
    Source      string
    Priority    string
    Section     string
    Description string

    BuildDepends        dependency.Dependency `control:"Build-Depends"`
    BuildDependsIndep   dependency.Dependency `control:"Build-Depends-Indep"`
    BuildConflicts      dependency.Dependency `control:"Build-Conflicts"`
    BuildConflictsIndep dependency.Dependency `control:"Build-Conflicts-Indep"`
}

Encapsulation for a debian/control Source entry. This contains information that will wind up in the .dsc and friends. Really quite fun!

func (*SourceParagraph) Maintainers Uses

func (s *SourceParagraph) Maintainers() []string

Return a list of all entities that are responsible for the package's well being. The 0th element is always the package's Maintainer, with any Uploaders following.

type Unmarshallable Uses

type Unmarshallable interface {
    UnmarshalControl(data string) error
}

The Unmarshallable interface defines the interface that Unmarshal will use to do custom unpacks into Structs.

The argument passed in will be a string that contains the value of the RFC822 key this object relates to.

Package control imports 24 packages (graph) and is imported by 22 packages. Updated 2019-01-15. Refresh now. Tools for package owners.