add initial manpages

This commit is contained in:
phoebos 2022-12-23 04:53:29 +00:00
parent d240830906
commit 86bbd66497
No known key found for this signature in database
2 changed files with 329 additions and 0 deletions

182
doc/kiss.1 Normal file
View File

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

147
doc/kiss.5 Normal file
View File

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