commit 1a1b704fac9e18c8af6c74231eaa9252cb96c7df
parent 377236dfea5fd70d71ec3cf84900e19c918b1bad
Author: Kiëd Llaentenn <kiedtl@tilde.team>
Date: Sun, 15 Jun 2025 14:20:39 -0400
kiss: add package-system/
Diffstat:
1 file changed, 170 insertions(+), 0 deletions(-)
diff --git a/wiki/kiss/package-system/index.md b/wiki/kiss/package-system/index.md
@@ -0,0 +1,170 @@
+# KISS Package System
+
+Packages are comprised of a directory and the series of files contained within.
+The name of the package is derived from its directory name. The files which
+comprise the system are as follows.
+
+ +------------------+----------+------------+----------+-------------+----------+
+ | File | Language | Executable | Comments | Blank lines | Required |
+ +------------------+----------+------------+----------+-------------+----------+
+ | | | | | | |
+ | build | Any | Yes [2] | N/A | N/A | Yes |
+ | checksums | DSL [3] | No | No | No | No [1] |
+ | depends | DSL [3] | No | Yes | Yes | No |
+ | sources | DSL [3] | No | Yes | Yes | No |
+ | version | DSL [3] | No | [4] | [4] | Yes |
+ | | | | | | |
+ | pre-remove | Any | Yes [2] | N/A | N/A | No |
+ | post-install | Any | Yes [2] | N/A | N/A | No |
+ | | | | | | |
+ +------------------+----------+------------+----------+-------------+----------+
+
+Unless stated otherwise, all files marked DSL are a grid of cells split into
+rows by newline and columns by whitespace.
+
+- [1] The checksums file is only required if the sources file contains sources
+ which exist as files on disk (directories, git repositories need not apply).
+- [2] The only requirement is that the file be executable. The file itself can
+ be written in any programming language.
+- [3] The file's format is a domain specific language with its own rules.
+ <https://en.wikipedia.org/wiki/Domain-specific_language>
+- [4] Tooling should only read the first line of the version file. Any lines
+ following should be ignored (allowing one to store arbitrary information).
+
+
+## [%[0.0]] Index
+
+* [1.0](#1.0) File: `build`
+* [2.0](#2.0) File: `checksums`
+* [3.0](#3.0) File: `depends`
+* [4.0](#4.0) File: `sources`
+* [5.0](#5.0) File: `version`
+* [6.0](#6.0) File: `pre-remove`
+* [7.0](#7.0) File: `post-install`
+* [8.0](#8.0) Further reading
+
+
+## [%[1.0]] File: `build`
+
+The build file is executed in the directory containing the package's extracted
+sources. Unlike other distributions, a 'cd' is not needed as sources have their
+top-level directory components stripped away.
+
+The build file is given two arguments. The destination directory (where
+artifacts should be installed) and the first field of the package's version
+file (verbatim).
+
+The build file is given a modified environment containing `DESTDIR`,
+`KISS_ROOT`, `GOPATH` and generic defaults for toolchain variables (if unset by
+the user). The toolchain defaults are as follows: `AR=ar, CC=cc, CXX=c++,
+NM=nm, RANLIB=ranlib`.
+
+Example shell-based build file:
+
+ #!/bin/sh -e
+
+ # Disable stripping (use if needed).
+ :> nostrip
+
+ ./configure \
+ --prefix=/usr
+
+ make
+ make install
+
+
+## [%[2.0]] File: `checksums`
+
+The checksums file is generated by the package manager (`kiss c pkg`) and is
+derived from files listed in the package's sources file. Directories and Git
+repositories are excluded.
+
+Checksum verification can be disabled for a source by replacing its checksum
+with `SKIP` in the checksums file. The package manager will notify you when
+this occurs.
+
+ 892a0875b9872acd04a9fde79b1f943075d5ea162415de3047c327df33fbaee5
+ 8a5b38a76b778da8d6f4236f1ea89e680daea971be6ee3a57e4e7ae99a883aa2
+ SKIP
+
+
+## [%[3.0]] File: `depends`
+
+The depends file contains the package's dependencies listed one per line in
+alphabetical order. Duplicate entries are not supported. The second optional
+field denotes the dependency type (unset for runtime, `make` for compile-time).
+
+ alsa-lib
+ meson make
+
+ # This is a comment.
+ wayland
+ wayland-protocols make
+
+
+## [%[4.0]] File: `sources`
+
+The sources file contains the package's sources one per line. A valid source is
+a URL to a file, relative path, absolute path or Git repository. The optional
+second field denotes the relative destination directory.
+
+Git repositories must be prefixed with `git+`. An optional suffix is supported to
+checkout a specific branch (`@BRANCH`) or commit (`#COMMIT`). All clones are shallow
+where supported by the remote server. If no suffix is used, master is cloned.
+
+ # This is a comment.
+ https://www.openssl.org/source/openssl-1.2.3.tar.gz
+ https://causal.agency/libretls/libretls-3.3.3p1.tar.gz libretls
+
+ files/update-certdata.sh
+ git+https://github.com/kisslinux/kiss@dev
+
+## [%[5.0]] File: `version`
+
+The version file is a single line split into two mandatory fields. The first
+field is the package's version and the second field the version of the
+repository files themselves.
+
+If the package follows its upstream release schedule, the first field should
+match the upstream version number. If the source is a Git repository, the
+version should be set to `git`. If a specific git commit is used, the version
+number should match accordingly.
+
+ 1.2.11 1
+
+
+## [%[6.0]] File: `pre-remove`
+
+The pre-remove file is executed before removal of the package. This file should
+be used to perform any required pre-removal steps or to display notices.
+
+Example shell-based pre-remove file (from `community/mdev-usb`):
+
+ #!/bin/sh
+
+ delgroup usb
+
+
+## [%[7.0]] File: `post-install`
+
+The post-install file is executed after installation of the package. This file
+should be used to perform any required post-install steps or to display notices.
+
+Example shell-based post-install file:
+
+ #!/bin/sh -e
+
+ cat <<EOF
+
+ The commands zcat, unpigz and gunzip were merely symbolic
+ links to the pigz binary. They have been removed. To gain
+ them back, create the symlinks (or use an alias or shell
+ function).
+
+ EOF
+
+
+## [%[8.0]] Further reading
+
+- [kiss/package-manager](/kiss/package-manager)
+- [kiss source](https://codeberg.org/kiss-community/kiss)
