add docs

FossilOrigin-Name: 373987d3050854074cb0f9b6dd4b24c867214f3862ed6161f94799d5ac325d86

2 files changed, 252 insertions, 0 deletions

diff --git a/doc/functions.txt b/doc/functions.txt
new file mode 100644
index 0000000..965c778
--- /dev/null
+++ b/doc/functions.txt
@@ -0,0 +1,92 @@
+FUNCTIONS
+
+This is a document for example functions to ensure portability
+across different systems. These are mere examples as we currently
+depend on non POSIX utilities on packages. These dependencies will
+be removed as we go forward.
+
+I don't want to turn the functions in here into a library because
+these are really simple, and I believe that the build scripts sho-
+uld be self-contained. What's the point of creating portable func-
+tions if the functions themselves depend on a library file to be
+installed on a system?
+
+These obviously have their own limitations, but not every limitation
+has to be solved in a single function. Use your imagination, non-
+standard flags/commands may save you some keypresses, but they are
+not standard, because you can already do these with your brain and
+a few more keypresses.
+
+SED -i
+------
+
+The -i function isn't portable across systems, and isn't defined
+by POSIX. But it isn't too valuable as it can be replaced with a
+simple function. I present you sed_i. This function only depends
+on the fact that the file name is the last argument.
+
+
+    sed_i() {
+        # This makes sure that we store the last argument on
+        # a file variable.
+        for file; do :; done
+
+        # Run the arguments against sed, and redirect output
+        # to a temporary file simply named '_'.
+        sed "$@" > _
+        # Instead of moving we cat into the file. This way we
+        # do not have to worry about preserving permissions of
+        # the file
+        cat _ > "$file"; rm -f _
+    }
+
+In build scripts with multiple 'sed -i' usage, such a function
+can be defined for and used. If only it is used a single time,
+defining such a function is quite unnecessary. In such a case
+prefer doing it manually. Assume the file is named 'file.h' and
+we are calling 's/this/that/g'.
+
+
+    sed 's/this/that/g' file.h >_
+    cat _ > file.h; rm -f _
+
+
+INSTALL -D,-t
+-------------
+
+'install' does not have a standard. Options such as '-D' and '-t',
+even though they are the most used, do not exist on every impleme-
+ntation. Avoid using these flags where possible. You can prefer us-
+ing functions such as these. The first function is similar to '-t'
+flag, where you can install multiple files to a given target. The
+second function is similar to the usage without the '-t' flag, a
+single file where it will be named as the argument.
+
+
+    kinstall_t() {
+         # usage: kinstall_t 755 /usr/bin file1 file2 file3
+         mod=$1 dir=$2; mkdir -p "$dir"
+         shift 2
+         for file; do
+             ! [ -d "$dir/$file" ] || {
+                 printf '%s\n' "Error: $dir/$file is a directory >&2"
+                 return 1
+             }
+             cp "$file" "$dir"
+             chmod "$mod" "$dir/$file"
+         done
+    }
+
+
+    kinstall() {
+        # usage: kinstall 755 /usr/bin/file filename
+        mod=$1 target=$2; mkdir -p "${target%/*}"
+        shift 2
+        ! [ -d "$target" ] || {
+            printf '%s\n' "Error: $target is a directory" >&2
+            return 1
+        }
+        cp "$file" "$target"
+        chmod "$mod" "$target"
+    }
+
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.