Ports: Add documentation :^)

This documents and explains how ports work and what variables, functions
and options are available for `package.sh` scripts.

1 files changed, 285 insertions, 8 deletions

diff --git a/Ports/README.md b/Ports/README.md
index 7c7af58bd0..4fe649727a 100644
--- a/Ports/README.md
+++ b/Ports/README.md
@@ -1,15 +1,292 @@
-# What's this?
+# Ports for SerenityOS
+
+## What's this?
 
 Serenity has software patched to run on it.
 These shell scripts will allow you to build that sort of software, easily.
-For example, if you want to install SDL2, simply run its package.sh script.
-Note that you should have already built Serenity, and be in a Serenity build environment.
+Note that you must have already built Serenity, and be in a Serenity build
+environment.
+
+## Using ports scripts
+
+Each port has a script called `package.sh` which defines a name and version,
+its dependencies, the required files that will be downloaded as well as
+configuration/compilation options, and some other things (see
+[Writing ports scripts](#writing-ports-scripts) for details).
+
+To install a certain port, `cd` into its directory and run `./package.sh`
+
+Installed ports are being tracked in `Ports/packages.db` (a simple text file).
+
+Not giving an option is equivalent to `installdepends`, `fetch`, `patch`,
+`configure`, `build` and `install`, in that order. This is recommended for a
+regular install.
+
+### Options
+
+The following options are available:
+
+#### `fetch`
+
+By default, download, verify, and extract the port's [`files`](#files).
+
+#### `patch`
+
+Apply the port's patches (`patches/*.patch`). A file `.foo_applied` is created
+in [`workdir`](#workdir) upon success to ensure a certain patch is only
+applied once.
+
+#### `configure`
+
+By default, run the port's [`configscript`](#configscript) (usually
+`configure`) with [`configopts`](#configopts).
+
+#### `build`
+
+By default, run `make` with the port's [`makeopts`](#makeopts).
+
+#### `install`
+
+By default, run `make install` with the port's [`installopts`](#installopts).
+
+#### `installdepends`
+
+Install all ports from the port's [`depends`](#depends) list.
+
+#### `clean`
+
+By default, remove all `.out` files from the port's [`workdir`](#workdir).
+
+#### `clean_dist`
+
+By default, remove everything that's been downloaded from the port's
+[`files`](#files) list.
+
+#### `clean_all`
+
+By default, [`clean`](#clean) and [`clean_dist`](#clean_dist) combined.
+
+#### `uninstall`
+
+Remove the port's files from the Serenity build directory, if it has a `plist`
+file.
+
+#### `--auto`
+
+Same as no option, but mark the port as having been installed automatically.
+This is used for dependencies.
+
+## Writing ports scripts
+
+The `package.sh` file is a simple Bash script that's required for each port.
+Patches and other files are optional. The most basic version of such a port
+script simply defines some well-known variables and looks like this:
+
+```bash
+#!/usr/bin/env -S bash ../.port_include.sh
+
+port="foo"
+version="1.2.3"
+workdir="foo-${version}"
+useconfigure="true"
+files="https://example.com/foo-${version}.tar.gz foo-${version}.tar.gz"
+depends="bar baz"
+```
+
+The script in the shebang, [`.port_include.sh`](./.port_include.sh), is where
+all the magic happens.
+
+### Variables
+
+The following variables have special functionality:
+
+#### `auth_import_key`
+
+PGP key to import (from `keyserver.ubuntu.com`) when [`auth_type`](#auth_type)
+is `sig`.
+
+#### `auth_opts`
+
+Options passed to `gpg --verify` when [`auth_type`](#auth_type) is `sig`.
+
+Usually used like this:
+
+```bash
+auth_opts="foo-${version}.tar.xz.asc foo-${version}.tar.xz"
+```
+
+#### `auth_type`
+
+The type of file validation to use, can be one of:
+
+- `md5`: Use MD5 hashes defined in [`files`](#files)
+- `sha256`: Use SHA256 hashes defined in [`files`](#files)
+- `sha1`: Use SHA1 hashes defined in [`files`](#files)
+- `sig`: Use PGP signatures (see [`auth_opts`](#auth_opts))
+
+Defaults to `md5`, most ports use `sig` though as `.asc` files are widely
+available.
+
+#### `configopts`
+
+Options passed to the port's [`configscript`](#configscript) in the default
+`configure` function.
+
+`--host=i686-pc-serenity` is always passed, override the `configure` function
+if that's undesirable.
+
+#### `configscript`
+
+Name of the script that will be run in the default `configure` function when
+[`useconfigure`](#useconfigure) is `true.`
+
+Defaults to `configure`.
+
+#### `depends`
+
+A space-separated list of other SerenityOS ports the port depends on and which
+will be installed during the `installdepends` step.
+
+#### `files`
+
+A list of external files required by the port, one per line. The format of each
+line is as follows:
+
+```text
+URL NAME HASH
+```
+
+Where `URL` is the URL from where the file will be downloaded (using `curl`),
+`NAME` is the output name of the downloaded file, and `HASH` is an optional
+MD5, SHA1, or SHA256 hash that will be used for verification when
+[`auth_type`](#auth_type) is set to either of those hash functions.
+
+For example:
+
+```bash
+files="https://example.com/foo-${version}.tar.xz foo-${version}.tar.xz
+https://example.com/foo-${version}.tar.xz.asc foo-${version}.tar.xz.asc"
+```
+
+If a file is a compressed tar archive, a gzip compressed file or a zip
+compressed file, it will be extracted.
+
+If a file is an `.asc` file (PGP signature) it will be imported into `gpg`'s
+keyring and can later be used for verification using [`auth_opts`](#auth_opts).
+
+#### `installopts`
+
+Options passed to `make install` in the default `install` function.
+
+`DESTDIR="$SERENITY_ROOT"/Build/Root` is always passed, override the `install`
+function if that's undesirable.
+
+#### `makeopts`
+
+Options passed to `make` in the default `build` function.
+
+Defaults to `-j$(nproc)`.
+
+#### `patchlevel`
+
+The value for `patch`'s `-p` / `--strip` option, see `man patch` for details.
+
+Defaults to `1`.
+
+#### `port`
+
+The "package name" of the port, usually the same as the directory this script
+is placed in.
+
+#### `prefix`
+
+The location of the ports directory, only used for the `package.db` file for
+now. Don't override this in ports contributed to Serenity.
+
+Defaults to `$SERENITY_ROOT/Ports`.
+
+#### `useconfigure`
+
+The `configure` step will run `pre_configure` and `configure` when this is set
+to `true`, and simply skip them otherwise.
+
+Defaults to `false`.
+
+#### `version`
+
+The version of the port. Written to `package.db`, and usually used with
+variable interpolation in [`files`](#files) where the version is part of the
+filename.
+
+#### `workdir`
+
+The working directory used for executing other commands via `run` as well as
+cleanup. Usually the directory name of the upacked source archive.
+
+Defaults to `$port-$version`.
+
+### Functions
+
+The various steps of the port installation process are split into individual
+Bash functions, some of which can be overridden to provide custom behaviour,
+like this:
+
+```bash
+build() {
+    run mybuildtool --foo --bar
+}
+```
+
+The following can be overridden, the names should be self-explanatory as they
+mostly match the [available options](#options):
+
+- `post_fetch`
+- `pre_configure`
+- `configure`.
+- `build`
+- `install`
+- `post_install`
+- `clean`
+- `clean_dist`
+- `clean_all`
+
+A few (non-overridable) util functions are available as well:
+
+#### `run`
+
+Log the command and run it in the port's [`workdir`](#workdir).
+
+#### `run_nocd`
+
+Log the command and run it in the current working directory
+(i.e. `Ports/$port`).
+
+#### `run_replace_in_file`
+
+Replace something in a file (using a Perl regular expression), like this:
+
+```bash
+run_replace_in_file "s/define FOO 1/undef FOO/" config.h
+```
+
+## How do I contribute?
 
-# Using ports scripts
+You can either:
 
-To do everything, just run the script: `./package.sh`
-To do a single step, you can specify it: `./package.sh build`
+- Add new ports - just get the software to build and add the necessary patches
+  and `package.sh` script
+- Update an existing port: bumping its version, getting functionality to work
+  that wasn't available so far etc. Make sure to update the patches
+  accordingly.
 
-# How do I contribute?
+Some videos of Andreas adding new ports can be found on YouTube, they might
+help you understand how this usually works:
 
-Port software, and add new scripts to build it of course :)
+- [OS hacking: Porting the Bash shell](https://www.youtube.com/watch?v=QNK8vK-nkkg)
+  (2019-05-20)
+- [OS hacking: Porting DOOM to Serenity](https://www.youtube.com/watch?v=a0P_bB6wjhY)
+  (2019-09-09)
+- [OS hacking: Let's port git to SerenityOS!](https://www.youtube.com/watch?v=1-7VQwWo2Tg)
+  (2020-02-19)
+- [OS hacking: Fixing a resize bug with the vim port](https://www.youtube.com/watch?v=d4uVnawzHdQ)
+  (2020-06-03)