add docs

FossilOrigin-Name: 373987d3050854074cb0f9b6dd4b24c867214f3862ed6161f94799d5ac325d86

1 files changed, 160 insertions, 0 deletions

diff --git a/doc/package-system.txt b/doc/package-system.txt
new file mode 100644
index 0000000..764bab9
--- /dev/null
+++ b/doc/package-system.txt
@@ -0,0 +1,160 @@
+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.