From 6eb382f400435c08f4adc8330e81c712528e0cd7 Mon Sep 17 00:00:00 2001 From: Dylan Araps Date: Thu, 26 Aug 2021 20:01:08 +0300 Subject: [PATCH] kiss: remove docs --- doc/package-manager.txt | 245 ---------------------------------------- doc/package-system.txt | 226 ------------------------------------ 2 files changed, 471 deletions(-) delete mode 100644 doc/package-manager.txt delete mode 100644 doc/package-system.txt diff --git a/doc/package-manager.txt b/doc/package-manager.txt deleted file mode 100644 index e44f856..0000000 --- a/doc/package-manager.txt +++ /dev/null @@ -1,245 +0,0 @@ -KISS PACKAGE MANAGER -________________________________________________________________________________ - -The KISS package manager is a small, self-contained POSIX shell script with an -emphasis on portability. - -Source: $/kisslinux/kiss - - -[0.0] Index -________________________________________________________________________________ - -* Usage [1.0] -* Dependencies [2.0] -* Configuration [3.0] -* Package Manager Hooks [4.0] -* Package Manager Extensions [5.0] - - -[1.0] Usage -________________________________________________________________________________ - -+------------------------------------------------------------------------------+ -| kiss | -+------------------------------------------------------------------------------+ -| | -| -> kiss [a|b|c|d|i|l|r|s|u|v] [pkg]... | -| -> alternatives List and swap alternatives | -| -> build Build packages | -| -> checksum Generate checksums | -| -> download Download sources | -| -> install Install packages | -| -> list List installed packages | -| -> remove Remove packages | -| -> search Search for packages | -| -> update Update the system | -| -> version Package manager version | -| | -+------------------------------------------------------------------------------+ - - -[2.0] Dependencies -________________________________________________________________________________ - -+-----------------------+-------------------------------------------+----------+ -| Dependency | Reason for use | Required | -+-----------------------+-------------------------------------------+----------| -| | | | -| POSIX utilities | N/A | Yes | -| git | Remote repositories and git sources | Yes [1] | -| curl | Source downloads | Yes | -| gnupg1 or gnupg2 | Repository signing | No | -| openssl | Checksums | Yes [2] | -| tar | Sources, packages, etc | Yes [3] | -| gzip, bzip2, xz, zstd | Tarball compression | Yes [4] | -| su, sudo, doas, ssu | Privilege escalation | No [5] | -| ldd | Dependency Fixer | No [6] | -| readelf | Dependency Fixer (better edition) | No [6] | -| strip | Binary Stripping | No [6] | -| | | | -+-----------------------+-------------------------------------------+----------+ - -[1] Git is also required for contribution to the distribution itself. Strictly - speaking, nothing forces you to use git. Remote repositories and git based - sources will simply become unusable. - -[2] There is no standard utility for the generation of sha256 checksums. While - openssl is listed above, the package manager also supports sha256sum, - sha256, shasum, and digest as fallbacks. - -[3] The tar command has no standard! The POSIX equivalent is "pax" though this - has its own issues (-s is unclear about links). Our usage of tar is merely, - cf, xf and tf. Our usage of tar cannot become any more basic than it is now. - - Portability should not be a concern. - - Tested tar implementations include: busybox, toybox, sbase, OpenBSD, GNU - and libarchive (though all tar implementations should work in theory). - -[4] The first three compression methods are required as 99% of package sources - use them as the tarball compression method. Nothing as of yet uses zstd in - the official repositories. - -[5] A privilege escalation utility is only needed when installing packages to - a directory owned by another user (user -> root) or (root -> user). - -[6] If missing, binary stripping and/or the dependency fixer will be disabled. - - -[3.0] Configuration -________________________________________________________________________________ - -The package manager has no configuration file and no changes need to be made to -the system prior to its use. While there is no configuration file, this does not -mean that there is no possibility for configuration. - -The package manager can be configured via the use of environment variables. - -+----------------+-------------------------------------------------------------+ -| Variable | Description | -+----------------+-------------------------------------------------------------+ -| | | -| KISS_CHK | Which utility to use when checksumming sources. | -| | Valid: openssl, sha256sum, sha256, shasum, digest. | -| | | -| KISS_CHOICE | Set to '0' to disable the alternatives system and error on | -| | any detected file conflicts. | -| | | -| KISS_COLOR | Enable/Disable colors. Set to '0' to disable colors. | -| | Color is otherwise disabled when output is not a terminal. | -| | | -| KISS_COMPRESS | Compression method to use for built package tarballs. | -| | Valid: gz (default), bz2, lzma, lz, xz, zst. | -| | | -| KISS_DEBUG | Keep temporary directories around for debugging purposes. | -| | Set to '1' to enable. | -| | | -| KISS_ELF | Which readelf command to use. | -| | Valid: readelf (default), readelf-*, ldd. | -| | | -| KISS_FORCE | Force installation/removal of packages by bypassing | -| | dependency checks, etc. Set to '1' to enable. | -| | | -| KISS_GET | Which utility to use when downloading sources. | -| | Valid: aria2c, axel, curl, wget, wget2. | -| | | -| KISS_HOOK | Hook into the package manager. A colon separated list of | -| | absolute paths to executable files. | -| | | -| KISS_KEEPLOG | Keep build logs around for successful builds and not just | -| | failing ones. Set to '1' to enable. | -| | | -| KISS_PATH | List of repositories. This works exactly like '$PATH' | -| | (a colon separated list of absolute paths). | -| | | -| KISS_PROMPT | Skip all prompts. Set to '0' to say 'yes' to all prompts | -| | from the package manager. | -| | | -| KISS_ROOT | Where installed packages will go. Can be used to install | -| | packages to somewhere other than '/'. | -| | | -| KISS_STRIP | Enable/Disable package stripping globally. | -| | Set to '0' to disable. | -| | | -| KISS_SU | Force usage of a different sudo tool. | -| | NOTE: Tool must support sudo-like arguments. | -| | | -| KISS_TMPDIR | Temporary directory for builds. Can be set to a tmpfs so | -| | builds happen in memory. | -| | | -+----------------+-------------------------------------------------------------+ - - -[4.0] Package Manager Hooks -________________________________________________________________________________ - -KISS' package manager is extensible via hooks which fire at various different -places inside the utility. Hooks allow the user to modify behavior, add new -features or conditionally do things on a per-package basis. - - - [4.1] Usage - ____________________________________________________________________________ - - This setting is controlled by the '$KISS_HOOK' environment variable which - takes a colon separated list of absolute file paths to executables. - - +--------------------------------------------------------------------------+ - | | - | export KISS_HOOK=$HOME/.local/bin/kiss-hook:/path/to/other/hook | - | | - +--------------------------------------------------------------------------+ - - - [4.2] List of hooks - ____________________________________________________________________________ - - Each hook is executed in the order it appears in KISS_HOOK and is given its - own environment/arguments accordingly. The hooks are documented as follows. - - +---------------+--------+----------+--------------------+-----------------+ - | hook | arg1 | arg2 | arg3 | arg4 | - +---------------+--------+----------+--------------------+-----------------+ - | | | | | | - | build-fail | type | package | Build directory | | - | post-build | type | package | DESTDIR | | - | post-install | Type | Package | Installed database | | - | post-package | Type | Package | Tarball | | - | post-source | Type | Package | Verbatim source | Resolved source | - | post-update | Type | [7] | | | - | pre-build | Type | Package | Build directory | | - | pre-extract | Type | Package | DESTDIR | | - | pre-install | Type | Package | Extracted package | | - | pre-remove | Type | Package | Installed database | | - | pre-source | Type | Package | Verbatim source | Resolved source | - | pre-update | Type | [7] [8] | | | - | queue-status | Type | Package | Number in queue | Total in queue | - | | | | | | - +---------------+--------+----------+--------------------+-----------------+ - - [7] The -update hooks start in the current repository. In other words, you - can operate on the repository directly or grab the value from '$PWD'. - - [8] The second argument of pre-update is '0' if the current user owns the - repository and '1' if they do not. In the latter case, privilege - escalation is required to preserve ownership. - - -[5.0] Package Manager Extensions -________________________________________________________________________________ - -Anything in the user's '$PATH' which matches the glob 'kiss-*' will be directly -usable via the package manager. For example, 'kiss-size' is also usable as -'kiss size' (and even 'kiss si') (the shortest available alias). - -The detected 'kiss-*' utilities will appear in the package manager's help-ext -output with the second line in the script acting as a doc-string. - -Example help output: - -+------------------------------------------------------------------------------+ -| kiss help-ext | -+------------------------------------------------------------------------------+ -| | -| -> Installed extensions (kiss-* in $PATH) | -| -> chroot Enter a kiss chroot | -| -> depends Display a package's dependencies | -| -> export Installed package to tarball | -| -> fork Fork a package into the current directory | -| -> help Read KISS documentation | -| -> link Link a repo file to another repo | -| -> maintainer Find the maintainer of a package | -| -> manifest Display all files owned by a package | -| -> new Create a boilerplate package | -| -> orphans List orphaned packages | -| -> outdated Check repository packages for updates | -| -> owns Check which package owns a file | -| -> preferred Lists the owners of all files with conflicts | -| -> revdepends Packages which depend on package | -| -> repo-orphans List packages which aren't present in any repository | -| -> size Show the size on disk for a package | -| | -+------------------------------------------------------------------------------+ - - diff --git a/doc/package-system.txt b/doc/package-system.txt deleted file mode 100644 index 09104f4..0000000 --- a/doc/package-system.txt +++ /dev/null @@ -1,226 +0,0 @@ -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 -