add initial manpages

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.

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.