From 86bbd66497af3bc3794508ea8d88638960c9efd2 Mon Sep 17 00:00:00 2001 From: phoebos Date: Fri, 23 Dec 2022 04:53:29 +0000 Subject: [PATCH] add initial manpages --- doc/kiss.1 | 182 +++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/kiss.5 | 147 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 329 insertions(+) create mode 100644 doc/kiss.1 create mode 100644 doc/kiss.5 diff --git a/doc/kiss.1 b/doc/kiss.1 new file mode 100644 index 0000000..97fd386 --- /dev/null +++ b/doc/kiss.1 @@ -0,0 +1,182 @@ +.Dd December 23, 2022 +.Dt KISS 1 +.Os +.Sh NAME +.Nm kiss +.Nd package manager +.Sh SYNOPSIS +.Nm +.Op Ar a|b|c|d|H|i|l|p|r|s|u|U|v +.Op Ar pkg... +.Sh DESCRIPTION +.Nm +is a tiny, self-contained package manager written in POSIX-compliant shell +script. +It is written with portability in mind. +.Pp +Running +.Nm +without any arguments prints help output. +Every action can be written as the full name or aliased by the first letter: +.Bl -tag -width Ds +.It Ar a|alternatives +List and swap package alternatives +.It Ar b|build +Build packages +.It Ar c|checksum +Generate checksums +.It Ar d|download +Download sources +.It Ar H|help-ext +List all installed extensions (see +.Sx Extensions ) . +.It Ar i|install +Install packages +.It Ar l|list +List installed packages +.It Ar p|preferred +List the owners of all files with alternatives +.It Ar r|remove +Remove packages +.It Ar s|search +Search for packages +.It Ar u|update +Update the repositories +.It Ar U|upgrade +Update the system +.It Ar v|version +Print package manager version +.El +.Ss Extensions +Anything in the user's +.Ev $PATH +which matches the glob +.Ql kiss-* +will be directly usable via the package manager. +The shortest available alias may also be used for each extension. +The second line in the script acts as a one-line doc string. +The default extensions are: +.Bl -tag -width Ds +.It Ar chroot +Enter a kiss chroot +.It Ar depends +Display a package's dependencies +.It Ar fork +Copy a package's repository files into the current directory +.It Ar help +Read KISS documentation +.It Ar link +Link a repository file to another repository +.It Ar maintainer +Find the maintainer of a package +.It Ar manifest +Display all files owned by a package +.It Ar new +Create a boilerplate package +.It Ar orphans +List orphaned packages +.It Ar outdated +Check repository for outdated packages +.It Ar owns +Check which package owns a file +.It Ar revdepends +Display packages which depend on package +.It Ar size +Show the size on disk for a package +.El +.Sh ENVIRONMENT +.Bl -tag -width Ds +.It Ev KISS_CHK +The utility to use for SHA256 checksums. +.Pp +Valid: openssl, sha256, sha256sum, shasum, digest. +Default is the first available in that order. +.It Ev KISS_CHOICE +Set to +.Ql 0 +to disable the alternatives system and error on any detected file +conflicts. +.It Ev KISS_COLOR +Set to +.Ql 0 +to disable colorful output; otherwise colors are disabled when the +utput is not a terminal. +.It Ev KISS_COMPRESS +Compression method to use for built package tarballs. +.Pp +Valid: gz (default), bz2, lzma, lz, xz, zst. +.It Ev KISS_DEBUG +Set to +.Ql 1 +to avoid deleting temporary directories after building packages, for +debugging. +.It Ev KISS_ELF +Which readelf command to use. +.Pp +Valid: readelf (default), *-readelf, ldd. +.It Ev KISS_FORCE +Set to +.Ql 1 +to bypass dependency checks and force building/installation/removal +of packages. +.It Ev KISS_GET +Which utility to use when downloading sources. +.Pp +Valid: aria2c, axel, curl, wget, wget2. +Default is the first available in that order. +.It Ev KISS_HOOK +A colon-separated list of absolute paths to executable files which are run as +hooks. +.It Ev KISS_KEEPLOG +Set to +.Ql 1 +to keep build logs for successful builds as well as failing ones. +.It Ev KISS_PATH +A colon-separated list of paths to repositories, directories which contain +packages. +Repositories earlier in the list have a higher priority in the case of a package +being found in multiple repos. +.It Ev KISS_PID +Used to determine the exact name of temporary directories, can be specified for +debugging. +.It Ev KISS_PROMPT +Set to +.Ql 0 +to say +.Dq yes +and skip all prompts from the package manager. +.It Ev KISS_ROOT +Where installed packages will go. +Can be used to install packages to somewhere other than +.Pa / . +.It Ev KISS_STRIP +Set to +.Ql 0 +to disable stripping package binaries and libraries globally. +.It Ev KISS_SU +Privilege escalation utility to use. +.Pp +Valid: ssu, sudo, doas, su, or any other tool compatible with sudo-like +arguments. +.It Ev KISS_TMPDIR +Temporary directory used for builds. +Can be set to a tmpfs (often +.Pa /tmp +for example) so that builds happen in memory +and are faster. +.El +.Sh FILES +.Nm +does not use any configuration files. +Files used in packages are documented in +.Xr kiss 5 . +.Sh EXIT STATUS +.Ex -std +.Sh SEE ALSO +.Xr kiss 5 , +.Lk https://kisslinux.org/wiki/package-manager +.Sh AUTHORS +.Nm +was created by +.An Dylan Araps +and the community. diff --git a/doc/kiss.5 b/doc/kiss.5 new file mode 100644 index 0000000..16f038f --- /dev/null +++ b/doc/kiss.5 @@ -0,0 +1,147 @@ +.Dd December 23, 2022 +.Dt KISS 5 +.Os +.Sh NAME +.Nm kiss +.Nd package format +.Sh DESCRIPTION +KISS 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: +.TS +center box tab(|); +lb|lb +l|l. +File | Required +_ +build | yes +checksums | no +depends | no +sources | no +version | yes + +pre-remove | no +post-install | no +.TE +.Ss build +The +.Pa build +file is executed in the directory containing the package's extracted +sources. +Unlike other distributions, a +.Ic cd +is not needed as sources have their top-level directory components stripped +away. +.Pp +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). +.Pp +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: +.Bd -literal -offset indent +AR=ar +CC=cc +CXX=c++ +NM=nm +RANLIB=ranlib +RUSTFLAGS="--remap-path-prefix=$PWD=. $RUSTFLAGS" +GOFLAGS="-trimpath -modcacherw $GOFLAGS" +.Ed +.Ss checksums +The +.Pa checksums +file is generated by the package manager +.Ql ( kiss c pkg ) +and is derived from files listed in the package's +.Pa sources +file. +Directories and git repositories do not require checksums. +.Pp +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. +.Ss depends +The +.Pa 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, +.Dq make +for compile-time). +Lines beginning with +.Ql # +are comments. +.Ss sources +The +.Pa 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. +Lines beginning with +.Ql # +are comments. +.Pp +Git repositories must be prefixed with +.Ql git+ . +An optional suffix is supported to checkout a specific branch +.Ql ( @BRANCH ) +or commit +.Ql ( #COMMIT ) . +All clones are shallow where supported by the remote server. +If no suffix is used, master is cloned. +.Pp +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. +.TS +center box tab(|); +l|l. +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. +.TE +.Ss version +The +.Pa 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. +.Pp +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 +.Ql git . +If a specific git commit is used, the version number should match accordingly. +.Ss pre-remove +The +.Pa 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. +.Ss post-install +The +.Pa 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. +.Sh SEE ALSO +.Xr kiss 1 , +.Lk https://kisslinux.org/wiki/package-system +.Sh HISTORY +Originally, SHA256 was used as the checksum algorithm. +In September 2022, the checksums were switched to use BLAKE3 for speed +improvements. +.Sh AUTHORS +.Nm +was created by +.An Dylan Araps +and the community.