hpk/package-format.md

# HitchHiker package format
Contents
========
- [Archive Format](#archive_format)
- [File Layout](#file_layout)
- [package.ron](#package.ron)

## Archive Format
HitchHiker package archives are [zstd](https://facebook.github.io/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).
```Sh
.
├── 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](https://en.wikipedia.org/wiki/KISS_principle) 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*
```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](https://www.freedesktop.org/wiki/Distributions/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.