Add README file

Signed-off-by: David Oberhollenzer <>
David Oberhollenzer 2019-03-09 13:51:33 +01:00
parent 1a84276bf6
commit 88f4dd00d7
1 changed files with 129 additions and 0 deletions

129 Normal file
View File

@ -0,0 +1,129 @@
# About
This package contains the source code of a small archiving tool with support
for dependency management, aka a package manager, developed for the Pygos
build system.
Building this package produces a program called `pkg` that can:
* take a package description file and a set of input files and pack them to
a compressed archive.
* dump the contents and meta data of such an archive for inspection.
* install an archive and all its dependencies recursively, in topological
order, to a specified root directory.
* generate file listings from archives in formats suitable for `mksquashfs`
* work out a build order for source packages given information on what source
packages provide what binary packages and what binary packages they need in
order to build.
* produce pretty dependency graphs.
## License
The source code in this package is provided under the OpenBSD flavored ISC
license. So you can practically do as you wish, as long as you retain the
original copyright notice. The software is provided "as is" (as usual) with
no warranty whatsoever (e.g. it might actually do what it was designed for,
but it could just as well set your carpet on fire).
The sub directory `m4` contains third party macro files used by the build
system which may be subject to their own, respective licenses.
## Package File Format
A writeup on the package file format can be found in
The format is currrently not finalized and will be frozen with the 1.0 release
of this package.
The `pkg` utility has an extensive built in help that can be accessed through
`pkg help` or `pkg help <command>`.
# Usage Example
An example package could be created from the following description file,
named `foobar.desc`:
requires coreutils libfrob basefiles
toc-compressor zlib
data-compressor lzma
In order to be installed, the package requires the other packages `coreutils`,
`libfrob` and `basefiles` to already be installed beforehand.
For whatever reason, we specify that the table of contents should be compressed
with zlib and the data with lzma, instead of using the built in default
In addition to the description file, we most likely also need want to include
some files in the package, so we create a file listing `foobar.files`:
# this is a comment, outlining commentary syntax and explaining
# that we create a bunch of directories with permission bits 755,
# owned by the user root
dir bin 0755 0 0
dir dev 0755 0 0
dir home 0755 0 0
# this directory is owned by a different user and group
dir home/goliath 0750 1000 1000
# create a symlink named /root that points to /home/goliath
slink root 0777 0 0 /home/goliath
# create a file /home/goliath/ from the input file
# stored relative to the foobar.files
file home/goliath/ 0644 1000 1000
# create a file named /bin/foobar. Since we omit the input file path,
# assume the file ./bin/foobar also exists relative to foobar.files
file bin/foobar 0755 0 0
# create a character device with permissions 600, owned by 0:0,
# device number major 5, minor 1
nod dev/console 0600 0 0 c 5 1
Running the following command:
pkg pack -d foobar.desc -l foobar.files -r ./repodir
Creates a file `./repodir/foobar.pkg` from the package description and file
listing. Note that the files in the listing are the only things that actually
have to exist anywhere in the real file system to create the archive.
Lets say, we want to install `foobar` and all its dependencies recursively
into a staging root directory. Running the following command is sufficient:
pkg install -r ./rootfs -R ./repodir foobar
This installs `foobar.pkg` inside `./repodir`. Since `foobar` depends on
`coreutils`, `libfrob` and `basefiles`, the archive files `coreutils.pkg`,
`libfrob.pkg` and `basefiles.pkg` are also read from `./repodir` and
installed to `./rootfs`. The same way, all transitive dependencies are
installed recursively.
Assuming we are not running as root, the above command will tell us that it
cannot create device nodes while installing and it has trouble changing
permission/ownership on some file.
So instead, we could run the following command, to keep ownership of the user
that ran the command, use default permissions and not create device files:
pkg install -omD -r ./rootfs -R ./repodir foobar
For more information on possible options, simply run `pkg help install`.
Now lets assume we want to pack the staging root directory into a squashfs
file system.
The `mksquashfs` command is a bit silly in regards to managing user IDs of
files, but has half-assed support for what it calls "pseudo files" that let
us set arbitrary user IDs, permissions and create device files, even as a
regular user.
So we run the following command to generate a squashfs pseudo file for the
installed packages:
pkg install -l sqfs -r ./rootfs -R ./repodir foobar > pseudo.txt