diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/functions.txt | 92 | ||||
| -rw-r--r-- | doc/package-system.txt | 160 |
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. |