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
├── appdata.xml
├── postinstall.sh
├── 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

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 [required]

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),
        ),
    ]),
)

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

appdata.xml [optional]

This is an appstream metadata file used primarily by software stores or graphical package managers. If the source distribution includes this file, it should be included in the package. If the source distribution does not contain this file, then it can be omitted or an appropriate file generated at the packager's discretion.

postinstall.sh [optional]

This is a POSIX shell compatible script to be run in order to finish installation. Heavy use of this capability is discouraged. If the desired action could be provided by hooks [see src/hooks/mod.rs] then please file a bug report to request the feature be added.

Scripts will be run with the environment variable HPK_ROOT set to the root under which the package is to be installed. Post install scripts must respect this environment variable and treat paths accordingly, so as to allow hpk to install packages into a chroot which may or may not be binary compatible with the host.