Added README

README.md

@@ -0,0 +1,88 @@
+# hpk
+Contents
+========
+* [Introduction](#introduction)
+* [Package Format](#package_format)
+* [Design](#design)
+* [Status](#status)
+
+## Introduction
+*Hpk* (HitchHiker Package Keeper) is a package manager designed for
+[HitchHiker Linux](https://hitchhiker-linux.org) and written in modern and safe
+Rust. It has been designed from the ground up to have a flexible and easy to
+understand interface, have high performance and have a logical scope in regards
+to managing the files on your system.
+
+## Package Format
+Packages to be managed by *hpk* are [zstd](https://facebook.github.io/zstd/)
+compressed Unix tar archives. The archive is intended to be extracted directly
+onto the target filesystem and so does not have a root directory. Looking inside
+a package archive will show a tree similar to the following.
+```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
+```
+The file *package.ron* contains all required metadata about the package in
+[ron](https://github.com/ron-rs/ron) format (Rusty Object Notation). Config files
+are installed with the extension *.new* if the file already exists, and are renamed
+with that extension removed if the package is being installed for the first time
+and no config file exists. This is in accordance with the KISS principle, and
+configuration is left to the system administrator rather than the package manager
+attempting to do so itself. A more thorough description can be read at
+[package-format.md](package-format.md).
+
+## Design
+Every attempt is made to make the package manager performant, including things
+such as:
+- parallel processing of files during package creation
+- file data is read into memory once during package creation. That data is
+  re-used for tasks such as generating checksums and tar file nodes, as opposed
+  to calling external programs which would have to open each file multiple times.
+- similarly, since hpk imlements reading and writing tar archives, during extraction
+  each file is read into memory, the data is checked against the recorded checksum,
+  and then written to disk rather then requiring separate steps
+
+All of the main data structures and functionality are implemented as a library,
+allowing for creation of alternate frontends to be written in the future. The vast
+majority of the data is exported rather than having secret, private API's that
+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
+[AppStream](https://www.freedesktop.org/wiki/Distributions/AppStream/) metadata
+file, allowing for nice things such as screenshots in a mode *App Store* like
+presentation.
+
+## Status
+Currently, *hpk* is in an early stage of development and is not ready for use.
+Perusing the cli options will show much of the intended functionality.
+
+### What's already working
+- [x] initializing a package specs file on the command line
+- [ ] creating a package archive from a directory of files
+- [ ] installing local packages
+- [ ] installing remote packages
+- [ ] resolving dependencies
+- [ ] removing packages
+- [ ] upgrading to newer package versions
+- [ ] searching repositories for available packages
+- [ ] listing installed packages