PACKAGE SYSTEM


This document talks about the packaging system works with the kiss
package manager in detail. For information regarding the usage of
the package manager itself, see the kiss(1) manual page.

A package is formed of 4 MANDATORY files. These are,
- BUILD
- SOURCES
- CHECKSUMS
- VERSION

The package manager also reacts to the existence of these files,
- DEPENDS
- POST-INSTALL
- MESSAGE

Any other file can be added to the package directory at the discretion
of the package maintainer. Everything in the package directory will also 
be added to the package database that is located on '/var/db/kiss/installed'
These can be patches, configuration files, etc.


BUILD
-----

Typically build files are shell scripts that run commands to prepare the
source code to be installed on the target system. Even though we will be
assuming that the build file is a POSIX shell script (for portability's
sake), build files can be any executable program from binary programs to
Perl scripts.

The contents of a build script do not need to follow a certain rule for
the package manager, except for the fact that the user needs the permission
to execute the file.

An important advice is to append an '-e' to the shebang (#!/bin/sh -e) so
that the build script exits on compilation error.


SOURCES
-------

sources file is a list of files and sources that will be put to the build
directory during the build process. Those can be remote sources (such as
tarballs), git repositories, and files that reside on the package directory.

The SYNTAX is pretty simple for the sources file. Here are some example
sources files taken from the packages in the repository.

    BUSYBOX

    https://busybox.net/downloads/busybox-1.31.1.tar.bz2
    files/.config
    files/.config-suid
    files/acpid.run
    files/crond.run
    files/inittab
    files/ntpd.run
    files/syslogd.run
    files/ntp.conf
    patches/fsck-resolve-uuid.patch
    patches/modprobe-kernel-version.patch
    patches/adduser-no-setgid.patch
    patches/install-fix-chown.patch
    patches/print-unicode.patch
    patches/1-date-64-prefix.patch
    patches/2-time-64-prefix.patch
    patches/3-syscall-gettime.patch


    SINIT

    git+git://git.suckless.org/sinit#v1.1
    files/config.h
    files/reboot
    files/poweroff


    GST-PLUGINS
    https://gstreamer.freedesktop.org/src/gst-plugins-good/gst-plugins-good-1.16.2.tar.xz good
    https://gstreamer.freedesktop.org/src/gst-plugins-bad/gst-plugins-bad-1.16.2.tar.xz   bad
    https://gstreamer.freedesktop.org/src/gst-plugins-ugly/gst-plugins-ugly-1.16.2.tar.xz ugly
    https://gstreamer.freedesktop.org/src/gst-libav/gst-libav-1.16.2.tar.xz               libav


This file is read from the package manager as space seperated. Files that begin
with a '#' comment are ignored. The first value points to the location of the
source.

If it starts with a protcol url, (such as ftp:// http:// https://) it will be
downloaded with curl(1).

If the source is GIT repository, it shall be prefixed with a 'git+'. git(1) will be
used to do a shallow clone of the repository. If the commit is suffixed by a history
pointer, git will checkout the relevant revision. So,

- git+git://example.com/pub/repo#v1.2.3      will checkout the tag named 'v1.2.3'
- git+git://example.com/pub/repo#development will checkout the branch named 'development'
- git+git://example.com/pub/repo#1a314s87    will checkout the commit named '1a314s87'


Other files are assumed to be residing in the package directory. They should be
added with their paths relative to the package directory.

The optional second value marks the DESTINATION of the source. If the value is
'example', the source will be extracted to a directory named 'example'. This is
useful on cases where there are multiple sources, or where a software requires
a source to be on a specific directory, you can see the gcc package for that.


CHECKSUMS
---------

checksums file is generated by the `kiss c pkg` command. It is generated
according to the order of the sources file. That's why you shouldn't be
editing it manually. The checksums file is created with the digests of the
files using the sha256 algorithm.


VERSION
-------

The version file includes the version of the software and the release number
of the package on a space seperated format. The contents of the file should
look like below.

    1.3.2 1

The version should always match to the number of the upstream release. For
drastic changes that require a rebuild Those can be,

- update of libraries that forces the package to be relinked
- change in the build scripts that affect the output of the package

When a version bump occurs, the release should be reset to 1.


DEPENDS
-------

This is a list of dependencies that must be installed before a package build.
You can append 'make' after a dependency to mark a package is only required
during the build process of a package. Packages marked as a make dependency
can be removed after the build.


POST-INSTALL
------------

post-installs have the same requirements as the build script. They will be
run after the package is installed as root (or as the user if the user has
write permissions on KISS_ROOT).

MESSAGE
-------

This plaintext file will be outputted with 'cat(1)' after every package is ins-
talled.
