Added package format description

README.md

@@ -67,7 +67,7 @@ are not exposed in the library.
 
 While the hpk source distribution will only include a command line client, provision
 is made for some nice modern features for a future graphical client. As an example,
-the `package.ron` file has an optional field to link to an
+the *package.ron* file has an optional field to link to an
 [AppStream](https://www.freedesktop.org/wiki/Distributions/AppStream/) metadata
 file, allowing for nice things such as screenshots in a mode *App Store* like
 presentation.

package-format.md

@@ -0,0 +1,118 @@
+# 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

src/lib.rs

@@ -12,5 +12,6 @@ pub use {
     package::{Dependency, Package, Specs},
     plist::*,
     repository::Repository,
+    tar,
     version::*,
 };