hpk/package-format.md

HitchHiker package format

Contents

• 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