From 7eaa25ef548ada0fb8d74b855b78aff678f4683a Mon Sep 17 00:00:00 2001 From: Dylan Araps Date: Thu, 22 Jul 2021 10:14:24 +0300 Subject: [PATCH] doc: update package-manager.txt --- doc/package-manager.txt | 277 +++++++++++++++++++--------------------- 1 file changed, 128 insertions(+), 149 deletions(-) diff --git a/doc/package-manager.txt b/doc/package-manager.txt index 537ab80..9a5a620 100644 --- a/doc/package-manager.txt +++ b/doc/package-manager.txt @@ -1,21 +1,20 @@ KISS PACKAGE MANAGER ________________________________________________________________________________ -The KISS package manager is a self-contained POSIX shell script which is written -in a highly portable way. It should run anywhere with a POSIX shell and POSIX -compliant core utilities. +The KISS package manager is a small, self-contained POSIX shell script with an +emphasis on portability. Source: $/kisslinux/kiss -Index +[0.0] Index ________________________________________________________________________________ -- Usage [1.0] -- Dependencies [2.0] -- Configuration [3.0] -- Package Manager Hooks [4.0] -- Package Manager Extensions [5.0] +* Usage [1.0] +* Dependencies [2.0] +* Configuration [3.0] +* Package Manager Hooks [4.0] +* Package Manager Extensions [5.0] [1.0] Usage @@ -25,17 +24,17 @@ ________________________________________________________________________________ | kiss | +------------------------------------------------------------------------------+ | | -| -> kiss [a|b|c|d|i|l|r|s|u|v] [pkg]... | -| -> alternatives List and swap to alternatives | -| -> build Build a package | -| -> checksum Generate checksums | -| -> download Pre-download all sources | -| -> install Install a package | -| -> list List installed packages | -| -> remove Remove a package | -| -> search Search for a package | -| -> update Update the system | -| -> version Package manager version | +| -> 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 | | | +------------------------------------------------------------------------------+ @@ -43,137 +42,113 @@ ________________________________________________________________________________ [2.0] Dependencies ________________________________________________________________________________ -+----------------------+--------------------------------------------+----------+ -| Dependency | Reason for use | Required | -+----------------------+--------------------------------------------+----------| -| POSIX utilities | Used throughout | Yes | -| git | Remote repositories and git sources | Yes [1] | -| curl | Source downloads | Yes | -| gnupg1 or gnupg2 | Repository signing | No | -| sha256sum | Checksums | Yes [2] | -| tar | Sources, packages, etc | Yes [3] | -| unzip | Zip sources (very rare) | No | -| | | | -|----------------------+--------------------------------------------+----------| -| Compression | | | -|----------------------+--------------------------------------------+----------| -| gzip, bzip2, xz | Tarball compression | Yes [4] | -| zstd, lzma, lzip | Tarball compression | No | -| | | | -|----------------------+--------------------------------------------+----------| -| Privileges | | | -|----------------------+--------------------------------------------+----------| -| su, sudo, doas, ssu | Privilege escalation | No [5] | -| | | | -|----------------------+--------------------------------------------+----------| -| Binutils | | | -|----------------------+--------------------------------------------+----------| -| ldd | Dependency Fixer | No [6] | -| readelf | Dependency Fixer (better edition) | No [6] | -| strip | Binary Stripping | No [6] | -| | | | -+----------------------+--------------------------------------------+----------+ ++-----------------------+-------------------------------------------+----------+ +| 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 - sha256sum is listed above, the package manager also supports sha256, shasum, - digest and openssl as fallbacks. + 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). + 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. - 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. + Portability should not be a concern. - Tested tar implementations include: busybox, toybox, sbase, GNU and - libarchive (though all tar implementations should work in theory). + Tested tar implementations include: busybox, toybox, sbase, OpenBSD, GNU + and libarchive (though all tar implementations should work in theory). -[4] These three compression methods are required as pretty much every package - source uses them as the tarball compression method. +[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. - The other compression methods are optional as no package sources (in the - official repositories) make use of them. +[5] A privilege escalation utility is only needed when installing packages to + a directory owned by another user (user -> root) or (root -> user). -[5] A privilege escalation utility is only needed when using the package - manager as a normal user for system-wide package installation. - - Installation to a user-writable directory does not require root access. - - Root usage of the package manager (chroot usage for example) does not - require these utilities. - -[6] If these are missing, binary stripping and/or the dependency fixer will - simply be disabled. - - Regarding 'strip'; It has a POSIX specification, though the spec doesn't - contain any arguments whatsoever. - - This makes our usage of 'strip' non-POSIX. That being said, our usage is - compatible with most 'strip' implementations (binutils, elfutils, - elftoolchain, llvm, etc). +[6] If missing, binary stripping and/or the dependency fixer will be disabled. [3.0] Configuration ________________________________________________________________________________ -The package manager has no configuration files and no changes need to be made to +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. I -believe this to be the best configuration method for the problem at hand. -Environment variables can be set system-wide, per-user, conditionally, for a -single invocation and so on. +The package manager can be configured via the use of environment variables. -+-----------------+------------------------------------------------------------+ -| Variable | Description | -+-----------------+------------------------------------------------------------+ -| | | -| 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. | -| | | -| KISS_COMPRESS | Compression method to use for built package tarballs | -| | (defaults to 'gz'). Valid: bz2, gz, 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. | -| | (defaults to 'readelf') Valid: readelf(s), ldd | -| | | -| KISS_FORCE | Force installation/removal of package by bypassing | -| | dependency checks, etc. Set to '1' to enable. | -| | | -| KISS_HOOK | Hook into the package manager. A colon separated list of | -| | absolute paths to executable files. See [6.0] | -| | | -| 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 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. | -| | | -+-----------------+------------------------------------------------------------+ ++----------------+-------------------------------------------------------------+ +| 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 @@ -184,7 +159,7 @@ places inside the utility. Hooks allow the user to modify behavior, add new features or conditionally do things on a per-package basis. - [6.1] Usage + [4.1] Usage ____________________________________________________________________________ This setting is controlled by the '$KISS_HOOK' environment variable which @@ -197,7 +172,7 @@ features or conditionally do things on a per-package basis. +--------------------------------------------------------------------------+ - [6.2] List of hooks + [4.2] List of hooks ____________________________________________________________________________ Each hook is executed in the order it appears in KISS_HOOK and is given its @@ -206,14 +181,18 @@ features or conditionally do things on a per-package basis. +---------------+--------+----------+--------------------+-----------------+ | hook | arg1 | arg2 | arg3 | arg4 | +---------------+--------+----------+--------------------+-----------------+ - | post-build | Type | Package | DESTDIR | | + | | | | | | + | 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] | | | | queue-status | Type | Package | Number in queue | Total in queue | | | | | | | @@ -239,23 +218,23 @@ 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 | +| -> 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 | | | +------------------------------------------------------------------------------+