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 ________________________________________________________________________________ * build [1.0] * checksums [2.0] * depends [3.0] * sources [4.0] * version [5.0] * pre-remove [6.0] * post-install [7.0] * Further reading [8.0] [1.0] 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 | +------------------------------------------------------------------------------+ | | | 1 #!/bin/sh -e | | 2 | | 3 # Disable stripping (use if needed). | | 4 :> nostrip | | 5 | | 6 ./configure \ | | 7 --prefix=/usr | | 8 | | 9 make | | 10 make install | | | +------------------------------------------------------------------------------+ [2.0] 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. +------------------------------------------------------------------------------+ | | | 1 892a0875b9872acd04a9fde79b1f943075d5ea162415de3047c327df33fbaee5 | | 2 8a5b38a76b778da8d6f4236f1ea89e680daea971be6ee3a57e4e7ae99a883aa2 | | 3 SKIP | | | +------------------------------------------------------------------------------+ [3.0] 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). +------------------------------------------------------------------------------+ | | | 1 alsa-lib | | 2 meson make | | 3 | | 4 # This is a comment. | | 5 wayland | | 6 wayland-protocols make | | | +------------------------------------------------------------------------------+ [4.0] 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. +------------------------------------------------------------------------------+ | | | 1 # This is a comment. | | 2 https://www.openssl.org/source/openssl-VERSION.tar.gz | | 3 https://causal.agency/libretls/libretls-3.3.3p1.tar.gz libretls | | 4 | | 5 files/update-certdata.sh | | 6 git+https://github.com/kisslinux/kiss@dev | | | +------------------------------------------------------------------------------+ The following MARKERS can be used to substitute version information. These are replaced at runtime with their respective values. Literal MARKERS can be escaped by prepending a backslash. +------------------------------------------------------------------------------+ | | | VERSION The first field of the version file verbatim. | | RELEASE The second field of the version file verbatim. | | MAJOR The first component of VERSION split on .-_+ | | MINOR The second component of VERSION split on .-_+ | | PATCH The third component of VERSION split on .-_+ | | IDENT All other components. | | PACKAGE The name of the package. | | | +------------------------------------------------------------------------------+ [5.0] 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 1.2.11 1 | | | +------------------------------------------------------------------------------+ [6.0] 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 | +------------------------------------------------------------------------------+ | | | TODO: Example | | | +------------------------------------------------------------------------------+ [7.0] 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 | +------------------------------------------------------------------------------+ | | | 1 #!/bin/sh -e | | 2 | | 3 cat <<EOF | | 4 | | 5 The commands zcat, unpigz and gunzip were merely symbolic | | 6 links to the pigz binary. They have been removed. To gain | | 7 them back, create the symlinks (or use an alias or shell | | 8 function). | | 9 | | 10 EOF | | | +------------------------------------------------------------------------------+ [8.0] Further reading ________________________________________________________________________________ - @/package-manager - $/kisslinux/kiss