kiss-community
/
kiss
mirror of https://codeberg.org/kiss-community/kiss
1
0
Fork 1
Code Issues Wiki

kiss: remove docs

This commit is contained in:
Dylan Araps 2021-08-26 20:01:08 +03:00
parent 88b5989da4
commit 6eb382f400
No known key found for this signature in database
GPG Key ID: 13295DAC2CF13B5C
2 changed files with 0 additions and 471 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

245
doc/package-manager.txt
View File

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

226
doc/package-system.txt
View File

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