From 8fcdb8b063f3d531ea161f561707468930ac16e1 Mon Sep 17 00:00:00 2001 From: Dylan Araps Date: Fri, 16 Jul 2021 18:56:24 +0300 Subject: [PATCH] kiss: move docs from website. Website can now import kisslinux/kiss as a submodule locked to the latest tag. Will make keeping documentation in sync easier. --- doc/package-manager.txt | 740 ++++++++++++++++++++++++++++++++++++++++ doc/package-system.txt | 327 ++++++++++++++++++ 2 files changed, 1067 insertions(+) create mode 100644 doc/package-manager.txt create mode 100644 doc/package-system.txt diff --git a/doc/package-manager.txt b/doc/package-manager.txt new file mode 100644 index 0000000..025473f --- /dev/null +++ b/doc/package-manager.txt @@ -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 | + | | + +--------------------------------------------------------------------------+ diff --git a/doc/package-system.txt b/doc/package-system.txt new file mode 100644 index 0000000..d4f2e32 --- /dev/null +++ b/doc/package-system.txt @@ -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" | +| | ++------------------------------------------------------------------------------+ + +