kiss/doc/package-manager.txt

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.

Source: $/kisslinux/kiss


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 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                                  |
|                                                                              |
+------------------------------------------------------------------------------+


[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]   |
|                      |                                            |          |
+----------------------+--------------------------------------------+----------+

[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.

[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, 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.

    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 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).


[3.0] Configuration
________________________________________________________________________________

The package manager has no configuration files 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.

+-----------------+------------------------------------------------------------+
|        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.                                   |
|                 |                                                            |
+-----------------+------------------------------------------------------------+


[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.


    [6.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         |
    |                                                                          |
    +--------------------------------------------------------------------------+


    [6.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            |
    +---------------+--------+----------+--------------------+-----------------+
    | post-build    | Type   | Package  | DESTDIR            |                 |
    | post-install  | Type   | Package  | Installed database |                 |
    | post-package  | Type   | Package  | Tarball            |                 |
    | 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-update    | Type   | [7]      |                    |                 |
    | 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'.


[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                       |
|                                                                              |
+------------------------------------------------------------------------------+