4.1 KiB

Raw Blame History

HitchHiker package format

Archive Format
File Layout
package.ron

Archive Format

HitchHiker package archives are zstd compressed Unix Tar archives. If at some future date a better compression algorithm becomes available than zstd it will be used instead, accompanied by a major version bump.

File Layout

There is no top level directory in a package archive. Files intended to go into /etc will be placed in etc in the archive (with no leading slash).

.
├── package.ron
├── etc
│   └── hpk
│       └── conf.ron.new
└── usr
    ├── bin
    │   └── hpk
    └── share
        ├── doc
        │   └── hpk
        │       ├── package-format.md
        │       └── README.md
        └── man
            ├── man1
            │   └── hpk.1
            └── man8
                └── hpk-package-format.8

11 directories, 7 files

Files inside of etc and var are expected to be configurable by the system administrator or may change at runtime, respectively, and so are not overwritten by default. Instead, when an archive is extracted onto the filesystem those files will have the extension .new. If this is the first time the package has been installed, or if a correspoding file does not exist on the filesystem, it will instead be extracted without the .new extension. This is a design decision made in the early planning stages of the package manager, following the KISS principle. It is believed that once a user has become proficient in managing their own system then it is bad practice for the package manager to attempt to edit config files, set services to start at boot or other related tasks.

The file package.ron contains all of the required metadata about a package, such as a list of files to be installed, their checksums, runtime dependencies etc.

package.ron

An example package.ron

Package(
    name: "foo",
    version: SemVer(
        major: 1,
        minor: 42,
        patch: 0,
    ),
    release: 1,
    description: "Select your Bars",
    long_description: "Foo is to bar as baz is to FizzBuzz",
    appstream_data: Some("https://example.com/pub/appstream/com.example.foo.appstream.xml"),
    plist: Plist(
        entries: [
        File(
            path: "usr/bin/foo",
            sha256sum: "7afe880d2ac5d5e5f29685045b366fe50a3266ba73dcad4127d4ac38b3fb11c2",
            mode: 493,
            size: 803024,
        ),
        Directory(
            path: "usr",
            mode: 493,
        ),
        Directory(
            path: "usr/bin",
            mode: 493,
        ),
    ]),
    size: 803024,
    dependencies: ["bar", "baz"],
    users: Some([
        User(
            name: "foo",
            uid: Some(42),
        ),
    ]),
    groups: Some([
        Group(
            name: "foo",
            gid: Some(42),
        ),
    ]),
    post_install: Some("bar -u baz")
)

Descriptions of the fields

name: the name of the package minus any version information
version: the version of the package, one of:
- semver (maj.min.patch)
- Git revision and date in the format git_{short_hash}.{YYYYMMDD}
- a single number, such as the version scheme used by eg Firefox and Chrome
release: the release number, in case the package must be re-packaged to correct bugs
description: a short, single line description of the package
long_description: a more verbose descrition, generally a paragraph in length
appstream_data: an optional link to an AppStream metadata file about the package
plist: the list of files, directories and symlinks installed by the package
size: the total size in bytes of all included files
users: an optional list of users which will be created on the system if they do not already exist
groups: an optional list of groups which will be created on the system if they do not already exist
post_install: an optional Posix shell script (minus shebang line) to be run after installing the package

4.1 KiB Raw Blame History