hpk/README.md

# 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
- [x] 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