bonsai/kiss
3
0
Fork 0
forked from kiss-community/kiss
Code Issues 2 Pull Requests Projects Releases Activity

kiss: move docs from website.

Browse Source 
Website can now import kisslinux/kiss as a submodule locked to
the latest tag. Will make keeping documentation in sync easier.
This commit is contained in:
Dylan Araps 2021-07-16 18:56:24 +03:00
parent 09d670d47e
commit 8fcdb8b063
No known key found for this signature in database
GPG Key ID: 13295DAC2CF13B5C
2 changed files with 1067 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

740
doc/package-manager.txt Normal file
View File

@ -0,0 +1,740 @@
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 in anywhere with a POSIX shell and
POSIX compliant coreutils.
The package manager is merely an implementation of the package format, its
requirements and some added sugar on top.
Source: $/kisslinux/kiss
[0.0] Index
________________________________________________________________________________
- Usage [1.0]
- Dependencies [2.0]
- Interesting Features [3.0]
- Runtime dependency detector built around 'ldd' [3.1]
- Fully dynamic (and automatic) alternatives system [3.2]
- 3-way handshake for files in /etc/ [3.3]
- Configuration [4.0]
- Repositories [5.0]
- What is a repository? [5.1]
- Enabling a remote repository [5.2]
- Preventing a package from receiving updates [5.3]
- Package fallbacks [5.4]
- Bypassing KISS_PATH [5.5]
- Package Manager Hooks [6.0]
- Usage [6.1]
- Removing unneeded files from packages [6.2]
- Drop into a subshell on build fail [6.3]
- Package Manager Extensions [7.0]
- Tips and Tricks [8.0]
- Swap grep implementations for a major speed up [8.1]
[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
________________________________________________________________________________
POSIX utilities are used where appropriate _and_ where they exist to solve a
particular problem. Utilities of which there is only a single and cross-platform
implementation are considered "portable" (git, curl, etc)
If a dependency can be made optional, it will be made so. Dependencies are also
kept to a minimum (though we must also remain realistic).
+----------------------+--------------------------------------------+----------+
| 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] |
| 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
and openssl as fallbacks.
[3] The tar command has no standard! This came as a shock. The POSIX equivalent
is "pax" though this isn't in wide use (at least on Linux).
Our usage of tar is merely, cf, xf and tf. A patch is applied to sbase's
tar so that it supports "dashless" arguments (as all others do). Our usage
of tar cannot become any more basic than it is now. Portability should no
longer 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.
If a compression method has 1-3 uses (hasn't yet happened), the compression
method will simply become a 'make' dependency of the package until usage
increases to a "normality".
[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 these 'strip' implementations.
strips: binutils, elfutils, elftoolchain, llvm, etc.
[3.0] Interesting Features
________________________________________________________________________________
[3.1] Runtime dependency detector built around 'ldd'
____________________________________________________________________________
Dynamic dependencies brought in by build systems (which are missing from the
package's dependency list) are fixed on-the-fly by checking which libraries
link to the package's files.
This prevents an incomplete dependency list from causing system breakage as
the package manager is able to complete the list.
A lot of packages make use of this "implicit" to "explicit" dependency list
"conversion" to provide optional dependencies.
Example output:
+--------------------------------------------------------------------------+
| |
| -> libXmu Checking for missing dependencies |
| --- /home/dylan/conf/cache/kiss/build-4477/d |
| depends |
| @@ -1,3 +1,8 @@ |
| +libX11 |
| +libXau |
| libXext |
| libXt |
| +libxcb |
| xorg-util-macros make |
| |
+--------------------------------------------------------------------------+
[3.2] Fully dynamic (and automatic) alternatives system
____________________________________________________________________________
Any file conflicts between two packages automatically become choices in the
alternatives system.
This allows one to swap providers of files without needing to explicitly
tell the package manager that two packages conflict, provide the same
utilities, etc.
In other words, no changes need to be made to packages. In fact, nothing
needs to be done at all. It's entirely automatic.
+--------------------------------------------------------------------------+
| List available alternatives ('a' is an alias to 'alternatives'). |
+--------------------------------------------------------------------------+
| |
| $ kiss a |
| gnugrep /usr/bin/grep |
| ncurses /usr/bin/clear |
| |
+--------------------------------------------------------------------------+
| Swap to GNU grep. |
+--------------------------------------------------------------------------+
| |
| $ kiss a gnugrep /usr/bin/grep |
| -> Swapping '/usr/bin/grep' from busybox to gnugrep |
| |
+--------------------------------------------------------------------------+
| Swap back to busybox grep. |
+--------------------------------------------------------------------------+
| |
| $ kiss a busybox /usr/bin/grep |
| -> Swapping '/usr/bin/grep' from gnugrep to busybox |
| |
+--------------------------------------------------------------------------+
| Swap to all alternatives for a given package (sbase for example). |
+--------------------------------------------------------------------------+
| |
| $ kiss a | grep ^sbase | kiss a - |
| -> Swapping '/usr/bin/cat' from busybox to sbase |
| -> Swapping '/usr/bin/cut' from busybox to sbase |
| -> Swapping '/usr/bin/yes' from busybox to sbase |
| ...Many more lines of output... |
| |
+--------------------------------------------------------------------------+
The above command works as the output of the alternatives listing is
directly usable as input to 'kiss a'.
[3.3] 3-way handshake for files in /etc/
____________________________________________________________________________
Files in /etc/ are handled differently to those elsewhere on the system. A
reinstallation or update to a package will not always overwrite these files.
Instead, a 3-way handshake happens during installation to determine how the
new /etc/ file should be handled.
If the user has made modifications to the file and those modifications
differ to the to-be-installed package's file, the file is installed with the
suffix '.new'
If the user hasn't touched the file, it will be automatically overwritten by
the package manager as it will contain updated/new contents..
If the user has touched the file but the file has not changed between
package versions, it will simply be skipped over.
+--------------------------------------------------------------------------+
| Example (with sha256 checksums truncated to fit). |
+--------------------------------------------------------------------------+
| |
| -> opendoas Doing 3-way handshake for etc/doas.conf |
| Previous: 1656eee66c235cb717f9f8f35aa9c3587bb768d7fe etc/doas.conf |
| System: 4a51871b3190fa74726ea2b12ffafb96f40c172b68 etc/doas.conf |
| New: 1656eee66c235cb717f9f8f35aa9c3587bb768d7fe etc/doas.conf |
| -> Skipping etc/doas.conf |
| |
+--------------------------------------------------------------------------+
[4.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 (where realistic). Environment
variables can be set system-wide, per-user, conditionally, for a single
invocation, etc, etc.
They require little to no extra code in the package manager to support them.
+-----------------+------------------------------------------------------------+
| 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. |
| | Valid: su, sudo, doas, ssu |
| | |
| KISS_TMPDIR | Temporary directory for builds. Can be set to a tmpfs so |
| | builds happen in memory. |
| | |
+-----------------+------------------------------------------------------------+
There are also a myriad of "3rd-party" environment variables which control GCC,
Make, CMake, etc. These aren't used by the package manager. They're used by the
tools called by the package's build script.
+-----------------+------------------------------------------------------------+
| Variable | Description |
+-----------------+------------------------------------------------------------+
| XDG_CACHE_HOME | Cache directory location. |
| | |
| CC | C compiler. |
| CXX | C++ compiler. |
| AR | Archive tool. |
| NM | Symbol tool. |
| RANLIB | Index tool. |
| | |
| CFLAGS | C compiler flags. |
| CXXFLAGS | C++ compiler flags. |
| LDFLAGS | Linker flags. |
| MAKEFLAGS | Make flags. |
| SAMUFLAGS | Samurai flags. |
| RUSTFLAGS | Rust compiler flags. |
| | |
| CMAKE_GENERATOR | 'Unix Makefiles' or 'Ninja'. |
| | |
+-----------------+------------------------------------------------------------+
[5.0] Repositories
________________________________________________________________________________
Repository management in KISS is very simple. Repositories are configurable via
an environment variable. This environment variable can be set system-wide,
per-user, conditionally (via a script or program), for a single invocation, etc.
The environment variable is called '$KISS_PATH' and is functionally identical to
the '$PATH' variable. A colon separated list of paths in other words.
+------------------------------------------------------------------------------+
| Example KISS_PATH |
+------------------------------------------------------------------------------+
| |
| $ KISS_PATH=/var/db/kiss/repo/core:/var/db/kiss/repo/extra |
| |
+------------------------------------------------------------------------------+
In the above example, two repositories are enabled (Core and Extra). The package
manager will search this list for packages in the order it is written.
Repositories can live anywhere on the system. In your '$HOME' directory,
somewhere system-wide in '/', etc. The only requirement is that a full path be
used.
[5.1] What is a repository?
____________________________________________________________________________
A KISS repository is simply a directory of directories. The quickest way to
get started is as follows.
+--------------------------------------------------------------------------+
| 1. Create the repository |
+--------------------------------------------------------------------------+
| |
| $ mkdir -p repo |
| $ cd repo |
| |
+--------------------------------------------------------------------------+
| 2. Let's 'fork' a few packages into our new repository. |
+--------------------------------------------------------------------------+
| |
| $ kiss fork curl |
| $ kiss fork xz |
| $ kiss fork zlib |
| |
+--------------------------------------------------------------------------+
This is now a fully usable repository and it can be added to your KISS_PATH.
[5.2] Enabling a remote repository
____________________________________________________________________________
Let's assume that our KISS_PATH matches the above example (Core and Extra).
+--------------------------------------------------------------------------+
| 1. Clone the repository |
+--------------------------------------------------------------------------+
| |
| # This can live anywhere on the system. |
| $ git clone https://example.com/repo |
| |
+--------------------------------------------------------------------------+
| 2. Enable the repository |
+--------------------------------------------------------------------------+
| |
| $ export KISS_PATH=$KISS_PATH:/path/to/repo |
| |
+--------------------------------------------------------------------------+
[5.3] Preventing a package from receiving updates
____________________________________________________________________________
Preventing a package from receiving updates can be accomplished in a myriad
of different ways. The easiest method is to leverage a user repository.
+--------------------------------------------------------------------------+
| 1. Create a new repository |
+--------------------------------------------------------------------------+
| |
| $ mkdir -p no_updates |
| $ cd no_updates |
| |
+--------------------------------------------------------------------------+
| 2. Copy the package to the new repository |
+--------------------------------------------------------------------------+
| |
| $ cp -r /var/db/kiss/installed/PKG_NAME /path/to/no_updates |
| |
+--------------------------------------------------------------------------+
| 3. Add the new repository to the /START/ of your KISS_PATH |
+--------------------------------------------------------------------------+
| |
| $ export KISS_PATH=/path/to/no_updates:$KISS_PATH |
| |
+--------------------------------------------------------------------------+
The package manager will search KISS_PATH in order. It will see that the
no_updates repository provides PKG_NAME and the version matches that which
is installed. No updates will again happen for the package.
[5.4] Package fallbacks
____________________________________________________________________________
If you would like to package something in your own repository but would
like the package manager to prefer other repositories before yours, simply
add your repository to the end of KISS_PATH.
The moment that your package is available elsewhere, the package manager
will prefer the new location to yours. The list is searched (in order) and
the first match is picked.
[5.5] Bypassing KISS_PATH
____________________________________________________________________________
There is a special case where one can bypass the regular KISS_PATH for a
single invocation of the package manager. This has been called "CRUX-like
usage" by users.
+--------------------------------------------------------------------------+
| |
| $ cd /path/to/myrepo/firefox |
| $ kiss b |
| |
+--------------------------------------------------------------------------+
As seen above, various package manager commands will work without arguments,
so long as you are in a package's repository directory. This will prepend
the current directory to '$KISS_PATH' _only_ for this invocation.
[6.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.
This setting is controlled by the '$KISS_HOOK' environment variable which takes
the full path to a POSIX shell script as its value.
Example:
+------------------------------------------------------------------------------+
| |
| export KISS_HOOK=$HOME/.local/bin/kiss-hook:/path/to/other/hook |
| |
+------------------------------------------------------------------------------+
[6.1] Usage
____________________________________________________________________________
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 | arguments |
+--------------+-----------------------------------------------------------+
| build-fail | hook_type pkg_name build_directory |
| post-build | hook_type pkg_name DESTDIR |
| post-install | hook_type pkg_name installed_database |
| post-package | hook_type pkg_name tarball |
| post-update | hook_type |
| pre-build | hook_type pkg_name build_directory |
| pre-extract | hook_type pkg_name DESTDIR |
| pre-install | hook_type pkg_name extract_directory |
| pre-remove | hook_type pkg_name installed_database |
| pre-update | hook_type |
| | |
+--------------------------------------------------------------------------+
build-fail
________________________________________________________________________
arg1: build-fail
arg2: package name
arg3: build directory
post-build
________________________________________________________________________
arg1: post-build
arg2: package name
arg3: DESTDIR
post-install
________________________________________________________________________
arg1: post-install
arg2: package name
arg3: installed database (/var/db/kiss/installed/pkg_name)
post-package
________________________________________________________________________
arg1: post-package
arg2: package name
arg3: path to tarball
post-update
________________________________________________________________________
arg1: post-update
env: PWD is set to the current repository.
pre-build
________________________________________________________________________
arg1: pre-build
arg2: build directory
pre-extract
________________________________________________________________________
arg1: pre-extract
arg2: DESTDIR
pre-install
________________________________________________________________________
arg1: pre-install
arg2: extraction directory
pre-remove
________________________________________________________________________
arg1: pre-remove
arg2: installed database (/var/db/kiss/installed/pkg_name)
pre-update
________________________________________________________________________
arg1: pre-update
env: PWD is set to the current repository.
[6.2] Removing unneeded files from packages
____________________________________________________________________________
Packages can contain files which you will have no use for. A simple hook can
be defined to remove them from packages.
NOTE: This is the default 'KISS_HOOK' script. If defining your own, be sure
to include this if you would like to continue to remove these files.
+--------------------------------------------------------------------------+
| |
| case $1 in |
| post-build) |
| # Ensure that '$3' is set. |
| : "${3:?DESTDIR is unset}" |
| |
| rm -rf "$3/usr/share/gettext" \ |
| "$3/usr/share/polkit-1" \ |
| "$3/usr/share/locale" \ |
| "$3/usr/share/info" \ |
| "$3/usr/lib/charset.alias" |
| ;; |
| esac |
| |
+--------------------------------------------------------------------------+
[6.3] Drop into a subshell on build fail
____________________________________________________________________________
Handy for debugging.
+--------------------------------------------------------------------------+
| |
| case $1 in |
| build-fail) |
| log "$2" "Dropped into subshell" |
| sh >/dev/tty |
| ;; |
| esac |
| |
+--------------------------------------------------------------------------+
[7.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 output
with the second line in the script acting as a doc-string.
Example help output:
+--------------------------------------------------------------------------+
| kiss extensions |
+--------------------------------------------------------------------------+
| |
| -> Installed extensions (kiss-* in $PATH) |
| -> chbuild Create/destroy temporary chroots |
| -> chroot Enter a kiss chroot |
| -> depends Display a package's dependencies |
| -> export Installed package to tarball |
| -> fork Fork a package into the current dir |
| -> 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 |
| -> revdepends Packages which depend on package |
| -> size Show the size on disk for a package |
| |
+--------------------------------------------------------------------------+
These are in effect, optional utilities which interact with the package system
in one way or another. My hope behind them is to act as an example as to how
easy it is to interface with the plain-text and "static" package system.
Example utility:
+------------------------------------------------------------------------------+
| kiss-depends (kiss depends, kiss de) |
+------------------------------------------------------------------------------+
| |
| #!/bin/sh -ef |
| # Display a package's dependencies |
| |
| # Ignore shellcheck as we want the warning's behavior. |
| # shellcheck disable=2015 |
| [ "$1" ] && kiss l "${1:-null}" >/dev/null || { |
| printf 'usage: kiss-depends [pkg]\n' |
| exit 1 |
| } |
| |
| cat "$KISS_ROOT/var/db/kiss/installed/$1/depends" 2>/dev/null |
| |
+------------------------------------------------------------------------------+
[8.0] Tips and Tricks
________________________________________________________________________________
A lot of the package manager's features are hard to discover or otherwise
non-obvious to its users. This section will document these features, how to use
them and the benefits they bring.
[8.1] Swap grep implementations for a major speed up.
____________________________________________________________________________
The default grep implementation in KISS is busybox grep. This version of
grep works very well and supports a large number of features. The one issue
is that it is painfully slow when compared to other popular implementations.
A fairly major speedup can be attained by swapping to a different grep via
the alternatives system. The fastest grep implementation around is GNU grep
which is available in the official repositories as 'gnugrep'.
+--------------------------------------------------------------------------+
| 1. Install GNU grep |
+--------------------------------------------------------------------------+
| |
| $ kiss b gnugrep |
| |
+--------------------------------------------------------------------------+
| 2. Swap to GNU grep |
+--------------------------------------------------------------------------+
| |
| $ kiss a gnugrep /usr/bin/grep |
| |
+--------------------------------------------------------------------------+

327
doc/package-system.txt Normal file
View File

@ -0,0 +1,327 @@
KISS PACKAGE SYSTEM
________________________________________________________________________________
The distribution employs a package system based around the concept of easily
parseable plain-text files (with fields separated by lines and spaces).
This format allows effortless interface using any programming language or just
basic UNIX utilities and tools.
[0.0] Index
________________________________________________________________________________
- Directory Structure [1.0]
- build [2.0]
- depends [3.0]
- sources [4.0]
- version [5.0]
- pre-remove [6.0]
- post-install [7.0]
- patches/* [8.0]
- files/* [9.0]
[1.0] Directory Structure
________________________________________________________________________________
+------------------------------------------------------------------------------+
| |
| zlib/ # Package name. |
| - build # Build script (chmod +x). |
| - sources # Remote and local sources. |
| - version # Package version. |
| |
| |
| # Optional files. |
| |
| - depends # Dependencies (usually required). |
| - pre-remove # Pre-remove script (chmod +x). |
| - post-install # Post-install script (chmod +x). |
| - patches/* # Directory to store patches. |
| - files/* # Directory to store misc files. |
| |
+------------------------------------------------------------------------------+
[2.0] build
________________________________________________________________________________
The build file should contain all of the steps necessary to patch, configure,
make and install ('make install' in this context) the package. The file is
language agnostic and the only requirement is that it be executable.
On execution the script will start in the directory of the package's source
(no need to cd anywhere).
The script is also given arguments (equivalent to 'script arg arg'). The first
argument contains the path where the script should install the compiled files.
The second argument contains the package's version.
Everything in the mentioned path is added to the package tarball and later
installed to the system.
+------------------------------------------------------------------------------+
| build |
+------------------------------------------------------------------------------+
| |
| #!/bin/sh -e |
| |
| # Disable stripping (add this only if needed). |
| :> nostrip |
| |
| ./configure \ |
| --prefix=/usr |
| |
| make |
| make DESTDIR="$1" install |
| |
+------------------------------------------------------------------------------+
[3.0] depends
________________________________________________________________________________
The depends file should contain any other packages the package depends on to
function correctly. Each dependency should be listed one per line.
A second and optional field allows for the distinction between a compile time
dependency and a run time one. The value of this field should be set to 'make'
for compile time dependencies and left blank for runtime dependencies.
The depends file can be omitted entirely if the package has no dependencies.
+------------------------------------------------------------------------------+
| depends |
+------------------------------------------------------------------------------+
| |
| # Comments are supported. |
| |
| # Perl is needed at compile time. |
| perl make |
| |
| # zlib is needed at runtime. |
| zlib |
| |
+------------------------------------------------------------------------------+
[4.0] sources
________________________________________________________________________________
The sources file should contain all remote and local files needed by the
package during the build. This includes the source, patches and any other
miscellaneous files which may be needed.
Each source should be listed one per line. An optional second field specifies
an extraction directory (relative to the build directory).
Sources which pull from a git repository use a special syntax. An additional
prefix 'git+' should be added with an optional suffix #hash or @branch).
Adding a suffix of '?no-extract' to the source URL will prevent the package
manager from automatically extracting the source (if a tarball or zip).
Sources also support MARKERS which are replaced with the version information
as defined in the version file at runtime.
+------------------------------------------------------------------------------+
| sources |
+------------------------------------------------------------------------------+
| |
| https://example.com/dhcpcd-8.0.2.tar.xz |
| files/dhcpcd.run |
| |
+------------------------------------------------------------------------------+
+------------------------------------------------------------------------------+
| sources (usage with second field) |
+------------------------------------------------------------------------------+
| |
| https://example.com/gcc-9.1.0.tar.xz gcc |
| https://example.com/gmp-6.1.2.tar.xz gcc/gmp |
| https://example.com/mpfr-4.0.2.tar.xz gcc/mpfr |
| https://example.com/mpc-1.1.0.tar.gz gcc/mpc |
| |
+------------------------------------------------------------------------------+
+------------------------------------------------------------------------------+
| sources (usage with Git) |
+------------------------------------------------------------------------------+
| |
| git+https://github.com/dylanaraps/eiwd |
| |
| # Grabbing a specific branch. |
| git+https://github.com/dylanaraps/eiwd@branch |
| |
| # Grabbing a specific commit. |
| git+https://github.com/dylanaraps/eiwd#commit |
| |
+------------------------------------------------------------------------------+
+------------------------------------------------------------------------------+
| sources (usage with MARKERS) |
+------------------------------------------------------------------------------+
| |
| 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 of VERSION. |
| PKG The name of the package. |
| |
+------------------------------------------------------------------------------+
| |
| https://example.com/dhcpcd-VERSION.tar.xz |
| https://example.com/pub/gnome/sources/atk/MAJOR.MINOR/atk-VERSION.tar.xz |
| |
+------------------------------------------------------------------------------+
+------------------------------------------------------------------------------+
| sources (usage with automatic source extraction disabled) |
+------------------------------------------------------------------------------+
| |
| https://example.com/zlib-1.2.0.tar.xz?no-extract |
| |
+------------------------------------------------------------------------------+
[5.0] version
________________________________________________________________________________
The version file should contain a single line with two fields. All other lines
will be ignored.
The first field should contain the software's upstream version and the second
field should contain the version number of the repository files themselves.
If the package is using a git source to pull down the latest commit, the
version should be simply set to 'git'.
+------------------------------------------------------------------------------+
| version |
+------------------------------------------------------------------------------+
| |
| 1.2.3 1 |
| |
+------------------------------------------------------------------------------+
+------------------------------------------------------------------------------+
| version (Git) |
+------------------------------------------------------------------------------+
| |
| git 1 |
| |
+------------------------------------------------------------------------------+
[6.0] pre-remove
________________________________________________________________________________
The pre-remove file should contain anything that needs run prior to the
removal of the package. The file is language agnostic and the only requirement
is that it be executable.
+------------------------------------------------------------------------------+
| pre-remove |
+------------------------------------------------------------------------------+
| |
| #!/bin/sh -e |
| |
| printf 'No one has used this yet!\n' |
| printf 'I have no example!\n' |
| |
+------------------------------------------------------------------------------+
[7.0] post-install
________________________________________________________________________________
The post-install file should contain anything that needs to be run after a
package installation to properly setup the software. The file is language
agnostic and the only requirement is that it be executable.
+------------------------------------------------------------------------------+
| post-install |
+------------------------------------------------------------------------------+
| |
| #!/bin/sh -e |
| |
| fc-cache -vf |
| |
+------------------------------------------------------------------------------+
[8.0] patches/*
________________________________________________________________________________
The patches directory should contain any patches the software needs.
In the `sources` file patches are referred to by using a relative path
(patches/musl.patch). The package manager does not automatically apply patches.
This must be done in the build script of the package.
The build script has direct access to the patches in its current working
directory ('patch -p1 < example.patch' works directly).
+------------------------------------------------------------------------------+
| sources (usage with patches) |
+------------------------------------------------------------------------------+
| |
| https://example.com/rxvt-unicode-9.22.tar.bz2 |
| patches/gentables.patch |
| patches/rxvt-unicode-kerning.patch |
| |
+------------------------------------------------------------------------------+
| build (usage with patches) |
+------------------------------------------------------------------------------+
| |
| #!/bin/sh -e |
| |
| patch -p1 < rxvt-unicode-kerning.patch |
| patch -p1 < gentables.patch |
| |
| ./configure \ |
| --prefix=/usr |
| |
| make |
| make DESTDIR="$1" install |
| |
+------------------------------------------------------------------------------+
[9.0] files/*
________________________________________________________________________________
The files/ directory should contain any miscellaneous files the software needs.
In the sources file, files are referred to by using a relative path
(files/busybox.config).
The build script has direct access to the files in its current working
directory ('cat example_file' works directly).
+------------------------------------------------------------------------------+
| sources (usage with local files) |
+------------------------------------------------------------------------------+
| |
| https://example.com/kiss-1.0.0.tar.gz |
| files/kiss_path.sh |
| |
+------------------------------------------------------------------------------+
| build (usage with local files) |
+------------------------------------------------------------------------------+
| |
| #!/bin/sh -e |
| |
| install -D kiss "$1/usr/bin/kiss" |
| |
| # Accessible directly in '$PWD'. |
| install -D kiss_path.sh "$1/etc/kiss_path.sh" |
| |
+------------------------------------------------------------------------------+