119 lines
4.1 KiB
Markdown
119 lines
4.1 KiB
Markdown
# 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
|
|
├── 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](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
|
|
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),
|
|
),
|
|
]),
|
|
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
|