From 311df4c349ae77dc6533833b244903b923881344 Mon Sep 17 00:00:00 2001 From: Nathan Fisher Date: Fri, 24 Mar 2023 18:12:30 -0400 Subject: [PATCH] Added README --- README.md | 88 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..83605ca --- /dev/null +++ b/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