bonsai/kiss
3
0
Fork 0
forked from kiss-community/kiss
Code Issues 2 Pull Requests Projects Releases Activity

doc: update package-manager.txt

Browse Source
This commit is contained in:
Dylan Araps 2021-07-22 10:14:24 +03:00
parent 0ad76a03df
commit 7eaa25ef54
No known key found for this signature in database
GPG Key ID: 13295DAC2CF13B5C
1 changed files with 128 additions and 149 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

141
doc/package-manager.txt
View File

@ -1,21 +1,20 @@
KISS PACKAGE MANAGER KISS PACKAGE MANAGER
________________________________________________________________________________ ________________________________________________________________________________
The KISS package manager is a self-contained POSIX shell script which is written The KISS package manager is a small, self-contained POSIX shell script with an
in a highly portable way. It should run anywhere with a POSIX shell and POSIX emphasis on portability.
compliant core utilities.
Source: $/kisslinux/kiss Source: $/kisslinux/kiss
Index [0.0] Index
________________________________________________________________________________ ________________________________________________________________________________
- Usage [1.0] * Usage [1.0]
- Dependencies [2.0] * Dependencies [2.0]
- Configuration [3.0] * Configuration [3.0]
- Package Manager Hooks [4.0] * Package Manager Hooks [4.0]
- Package Manager Extensions [5.0] * Package Manager Extensions [5.0]
[1.0] Usage [1.0] Usage
@ -26,14 +25,14 @@ ________________________________________________________________________________
+------------------------------------------------------------------------------+ +------------------------------------------------------------------------------+
| | | |
| -> kiss [a|b|c|d|i|l|r|s|u|v] [pkg]... | | -> kiss [a|b|c|d|i|l|r|s|u|v] [pkg]... |
| -> alternatives List and swap to alternatives | | -> alternatives List and swap alternatives |
| -> build Build a package | | -> build Build packages |
| -> checksum Generate checksums | | -> checksum Generate checksums |
| -> download Pre-download all sources | | -> download Download sources |
| -> install Install a package | | -> install Install packages |
| -> list List installed packages | | -> list List installed packages |
| -> remove Remove a package | | -> remove Remove packages |
| -> search Search for a package | | -> search Search for packages |
| -> update Update the system | | -> update Update the system |
| -> version Package manager version | | -> version Package manager version |
| | | |
@ -43,120 +42,96 @@ ________________________________________________________________________________
[2.0] Dependencies [2.0] Dependencies
________________________________________________________________________________ ________________________________________________________________________________
+----------------------+--------------------------------------------+----------+ +-----------------------+-------------------------------------------+----------+
| Dependency | Reason for use | Required | | Dependency | Reason for use | Required |
+----------------------+--------------------------------------------+----------| +-----------------------+-------------------------------------------+----------|
| POSIX utilities | Used throughout | Yes | | | | |
| POSIX utilities | N/A | Yes |
| git | Remote repositories and git sources | Yes [1] | | git | Remote repositories and git sources | Yes [1] |
| curl | Source downloads | Yes | | curl | Source downloads | Yes |
| gnupg1 or gnupg2 | Repository signing | No | | gnupg1 or gnupg2 | Repository signing | No |
| sha256sum | Checksums | Yes [2] | | openssl | Checksums | Yes [2] |
| tar | Sources, packages, etc | Yes [3] | | tar | Sources, packages, etc | Yes [3] |
| unzip | Zip sources (very rare) | No | | gzip, bzip2, xz, zstd | Tarball compression | Yes [4] |
| | | |
|----------------------+--------------------------------------------+----------|
| Compression | | |
|----------------------+--------------------------------------------+----------|
| gzip, bzip2, xz | Tarball compression | Yes [4] |
| zstd, lzma, lzip | Tarball compression | No |
| | | |
|----------------------+--------------------------------------------+----------|
| Privileges | | |
|----------------------+--------------------------------------------+----------|
| su, sudo, doas, ssu | Privilege escalation | No [5] | | su, sudo, doas, ssu | Privilege escalation | No [5] |
| | | |
|----------------------+--------------------------------------------+----------|
| Binutils | | |
|----------------------+--------------------------------------------+----------|
| ldd | Dependency Fixer | No [6] | | ldd | Dependency Fixer | No [6] |
| readelf | Dependency Fixer (better edition) | No [6] | | readelf | Dependency Fixer (better edition) | No [6] |
| strip | Binary Stripping | No [6] | | strip | Binary Stripping | No [6] |
| | | | | | | |
+----------------------+--------------------------------------------+----------+ +-----------------------+-------------------------------------------+----------+
[1] Git is also required for contribution to the distribution itself. Strictly [1] Git is also required for contribution to the distribution itself. Strictly
speaking, nothing forces you to use git. Remote repositories and git based speaking, nothing forces you to use git. Remote repositories and git based
sources will simply become unusable. sources will simply become unusable.
[2] There is no standard utility for the generation of sha256 checksums. While [2] There is no standard utility for the generation of sha256 checksums. While
sha256sum is listed above, the package manager also supports sha256, shasum, openssl is listed above, the package manager also supports sha256sum,
digest and openssl as fallbacks. sha256, shasum, and digest as fallbacks.
[3] The tar command has no standard! The POSIX equivalent is "pax" though this [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 Portability should not be a concern.
any more basic than it is now. Portability should not be a concern.
Tested tar implementations include: busybox, toybox, sbase, GNU and Tested tar implementations include: busybox, toybox, sbase, OpenBSD, GNU
libarchive (though all tar implementations should work in theory). and libarchive (though all tar implementations should work in theory).
[4] These three compression methods are required as pretty much every package [4] The first three compression methods are required as 99% of package sources
source uses them as the tarball compression method. 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 [5] A privilege escalation utility is only needed when installing packages to
official repositories) make use of them. a directory owned by another user (user -> root) or (root -> user).
[5] A privilege escalation utility is only needed when using the package [6] If missing, binary stripping and/or the dependency fixer will be disabled.
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).
[3.0] Configuration [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 the system prior to its use. While there is no configuration file, this does not
mean that there is no possibility for configuration. mean that there is no possibility for configuration.
The package manager can be configured via the use of environment variables. I The package manager can be configured via the use of environment variables.
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.
+-----------------+------------------------------------------------------------+ +----------------+-------------------------------------------------------------+
| Variable | Description | | 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 | | KISS_CHOICE | Set to '0' to disable the alternatives system and error on |
| | any detected file conflicts. | | | any detected file conflicts. |
| | | | | |
| KISS_COLOR | Enable/Disable colors. Set to '0' to disable colors. | | 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 | | KISS_COMPRESS | Compression method to use for built package tarballs. |
| | (defaults to 'gz'). Valid: bz2, gz, lzma, lz, xz, zst | | | Valid: gz (default), bz2, lzma, lz, xz, zst. |
| | | | | |
| KISS_DEBUG | Keep temporary directories around for debugging purposes. | | KISS_DEBUG | Keep temporary directories around for debugging purposes. |
| | Set to '1' to enable. | | | Set to '1' to enable. |
| | | | | |
| KISS_ELF | Which 'readelf' command to use. | | KISS_ELF | Which readelf command to use. |
| | (defaults to 'readelf') Valid: readelf(s), ldd | | | Valid: readelf (default), readelf-*, ldd. |
| | | | | |
| KISS_FORCE | Force installation/removal of package by bypassing | | KISS_FORCE | Force installation/removal of packages by bypassing |
| | dependency checks, etc. Set to '1' to enable. | | | 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 | | KISS_HOOK | Hook into the package manager. A colon separated list of |
| | absolute paths to executable files. See [6.0] | | | absolute paths to executable files. |
| | | | | |
| KISS_KEEPLOG | Keep build logs around for successful builds and not just | | KISS_KEEPLOG | Keep build logs around for successful builds and not just |
| | failing ones. Set to '1' to enable. | | | failing ones. Set to '1' to enable. |
| | | | | |
| KISS_PATH | List of repositories. This works exactly like '$PATH' | | KISS_PATH | List of repositories. This works exactly like '$PATH' |
| | (a colon separated list of paths). | | | (a colon separated list of absolute paths). |
| | | | | |
| KISS_PROMPT | Skip all prompts. Set to '0' to say 'yes' to all prompts | | KISS_PROMPT | Skip all prompts. Set to '0' to say 'yes' to all prompts |
| | from the package manager. | | | from the package manager. |
@ -173,7 +148,7 @@ single invocation and so on.
| KISS_TMPDIR | Temporary directory for builds. Can be set to a tmpfs so | | KISS_TMPDIR | Temporary directory for builds. Can be set to a tmpfs so |
| | builds happen in memory. | | | builds happen in memory. |
| | | | | |
+-----------------+------------------------------------------------------------+ +----------------+-------------------------------------------------------------+
[4.0] Package Manager Hooks [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. 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 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 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 | | 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-install | Type | Package | Installed database | |
| post-package | Type | Package | Tarball | | | post-package | Type | Package | Tarball | |
| post-source | Type | Package | Verbatim source | Resolved source |
| post-update | Type | [7] | | | | post-update | Type | [7] | | |
| pre-build | Type | Package | Build directory | | | pre-build | Type | Package | Build directory | |
| pre-extract | Type | Package | DESTDIR | | | pre-extract | Type | Package | DESTDIR | |
| pre-install | Type | Package | Extracted package | | | pre-install | Type | Package | Extracted package | |
| pre-remove | Type | Package | Installed database | | | pre-remove | Type | Package | Installed database | |
| pre-source | Type | Package | Verbatim source | Resolved source |
| pre-update | Type | [7] | | | | pre-update | Type | [7] | | |
| queue-status | Type | Package | Number in queue | Total in queue | | queue-status | Type | Package | Number in queue | Total in queue |
| | | | | | | | | | | |