1 files changed, 206 insertions, 0 deletions
diff --git a/modules/Working/pages/apk.adoc b/modules/Working/pages/apk.adoc
new file mode 100644
@@ -0,0 +1,206 @@
+= Working with the Alpine Package Keeper (`apk`)
+// MAINT: apk-tools - whole page
+`apk` is the Alpine Package Keeper - the distribution's package manager.
+It is used to manage the packages (software and otherwise) of the system.
+It is the primary method for installing additional software, and is available in the `apk-tools` package.
+== Normal Usage
+=== Repositories and Mirrors
+// MAINT: repositories and versions
+`apk` fetches information about available packages, as well as the packages themselves from various mirrors, which contain various repositories.
+Sometimes, those terms are used interchangeably.
+Here is a summary of relevant definitions:
+Mirror:: A website that hosts repositories.
+Release:: A collection of snapshots of various repositories.
+Repository:: A category of packages, tied together by some attribute.
+Currently, three repositories exist:
+main:: Officially supported packages that are reasonable to expect to be in a basic system. Support cycles are 2 years long.
+community:: Packages from testing that have been tested. Support cycles are 6 months long.
+testing:: New, broken, or outdated packages that need testing. No support for this repository is implied. It is not present in release snapshots.
+// MAINT: versioning scheme, edge
+// TODO: verify
+Releases are versioned using a versioning scheme somewhat reminiscent of semantic versioning.
+However, one special release exists called "edge" - this is a "rolling" release.
+"Edge" is not officially supported - if you choose to run it, you are on your own.
+"Edge" is also the only release that contains the "testing" repository.
+Repositories are configurable in the `/etc/apk/repositories` file.
+Each line corresponds to a repository.
+The format is as follows:
+// MAINT: dl-cdn.alpinelinux.org
+# comments look like so. valid examples below
+@testing http://dl-cdn.alpinelinux.org/alpine/edge/testing <2>
+<1> In this case, `http://` is the protocol, `dl-cdn.alpinelinux.org/alpine` is the path, `edge` is the release and `main` is the repository.
+<2> In this case, `@testing` is the tag. More on this in <<_installing_packages>>.
+<3> In this case, the repository is a personal one, available on the filesystem of the machine.
+NOTE: This example uses the `http://` protocol. `ftp://` and `https://` protocols are also supported.
+// TODO: xref to installation part that's relevant
+NOTE: This file should already have been been partially populated when you installed alpine.
+=== Searching for Packages
+// MAINT: apk-search and pkgs.alpinelinux.org
+In order to know what package to install, one must be able to find packages.
+Alpine has a specialized https://pkgs.alpinelinux.org[web interface] dedicated to looking through various available packages.
+However, `apk` also provides a built-in searching mechanism.
+You invoke it by using the `apk search` subcommand.
+// TODO: link to APKINDEX developer page
+You can potentially search for anything in the package index, which, among other things, includes provided binaries and libraries).
+Further, globbing is supported.
+As such, here are a few examples of searching:
+apk search libsqlite3.so <1>
+apk search consul <2>
+apk search -e vim <3>
+apk search -e so:libsqlite3.so.* <4>
+<1> You can search for partial library names.
+<2> You can also search for binary names.
+<3> You can exclude partial matches using `-e`.
+<4> You can specify that what you're searching for is a library using the `so:` prefix (or the `cmd:` prefix for commands, and `pc:` prefix for pkg-config files) - it will work with `-e` (in fact, the prefix is required for this use-case if `-e` is used).
+=== Installing Packages
+// MAINT: apk-add
+Once you know what package you want to install, you must know how to do that.
+Apk's `add` command is more strict than the `search` command - wildcards are not available, for instance.
+// TODO: gotchas, already asked in #a-docs
+However, the `cmd:`, `so:` and `pc:` prefixes are still available.
+While the `so:` prefix is still available for `apk add`, it is recommended that you avoid using it.
+This is because the provided library SONAME version can increase (for example, `libmpack.so.0` may get updated, and become `libmpack.so.1`), in which case this will *not* update libmpack next time you run `apk upgrade`, and will instead fail.
+This is because `so:libmpack.so.0` directly refers to that specific version of the library, and is typically used by packages, rather than users directly.
+While the `cmd:` and `pc:` prefix is still available for `apk add`, you should know that it does not guarantee getting you the exact package you are looking for.
+Multiple packages can contain the same executable command or pkg-config definition, but only one will be selected - not necessarily the one you want.
+Here are a few examples of adding packages:
+apk add busybox-extras <1>
+apk add bash zsh <2>
+apk add cmd:bash cmd:zsh <3>
+apk add so:libmpack.so.0 <4>
+apk add pc:msgpack <5>
+<1> You must specify the exact package name.
+<2> You may add multiple packages at once.
+<3> This should be equivalent to the previous example, but specifies the command you are interested in.
+<4> It is possible, but discouraged, to specify specific desired libraries.
+<5> Finally, it is possible to specify pkg-config dependencies.
+NOTE: If `apk add` finds multiple matching packages (for example multiple `cmd:` matches), it will select the one with the highest version number.
+=== Upgrading Packages
+// MAINT: apk-update, apk-upgrade
+Updating the system using apk is very simple.
+One need only run `apk upgrade`.
+Technically, this is two steps: `apk update`, followed by `apk upgrade` proper.
+The first step will download an updated package index from the repositories, while the second step will update all packages in <<_world>>, as well as their dependencies.
+// MAINT: update-conf
+`apk` will avoid overwriting files you may have changed.
+These will usually be in the `/etc` directory.
+Whenever `apk` wants to install a file, but realizes a potentially edited one is already present, it will write its file to that filename with `.apk-new` appended.
+You may handle these by hand, but a utility called `update-conf` exists.
+Simply invoking it normally with present you with the difference between the two files, and offer various choices for dealing with the conflicts.
+NOTE: `apk update` is only ran once your cache is invalidated, which by default happens every 4 hours.
+=== Querying Package Information
+// MAINT: apk-info
+In some cases, it may be useful to inspect packages or files to see various details.
+For this use, the `info` subcommand exists.
+It may be used on any package, installed or not, though the information on the latter will be more limited.
+It may also be used with specific flags on files.
+By default, `info` will list the package description, webpage and installed size.
+// TODO: link manual for apk(1)
+// MAINT: apk-info: `apk info -h` output
+For more details (such as a list of flags the subcommand supports), you can use the `apk info -h` output's "Info options" section or see the manual page.
+=== Removing Packages
+// MAINT: apk-del
+Often, it is desirable to remove a package.
+This can be done using the `del` subcommand, with a base syntax that is identical to the `add` subcommand.
+NOTE: If you added a package using the `cmd:`, `so:` or `pc:` virtual, you must specify the same virtual to remove them.
+NOTE: Removing a package will automatically remove all of its dependencies that are otherwise not used.
+// MAINT: apk-del: apk del -r
+The `del` subcommand also supports the `-r` flag, which will remove all packages that depend on the package being removed as well, rather than error out due to the package being needed.
+Many package managers have specific features to "clean up".
+A common one is `apt`, which has an `autoremove` subcommand.
+Apk does this by default when removing packages.
+It is also possible to clear out the apk cache, assuming it is enabled.
+You can do this using `apk cache clean`.
+== Advanced Usage
+The packages you want to have explicitly installed are listed in the "world file", available in `/etc/apk/world`.
+It is safe to edit it by hand.
+If you've edited it by hand, you may run `apk add` with no arguments to bring the package selection to a consistent state.
+NOTE: Virtuals like `cmd:`, `so:` and `pc:` will appear as such in your world file - this is why using `so:` is discouraged - the soname might get bumped!
+// MAINT: apk-add -t
+While `cmd:`, `so:` and `pc:` packages are automatically created virtuals, you can create your own as well.
+These allow for quick removal of purpose-specific packages.
+See the following examples for details:
+apk add a b c -t abc <1>
+apk del abc <2>
+apk add a b c --virtual abc <3>
+<1> This will add the packages "a", "b" and "c" as the dependencies of a virtual package "abc".
+<2> This will remove "abc" and all of its components ("a", "b" and "c"), unless they are required elsewhere.
+<3> This is equivalent to the first example.
+=== Swapping Repositories
+When alpine has a new release, the repository path will change.
+Assuming you are going forward in time (e.g from `3.8` to `3.9`), you can simply edit `/etc/apk/repositories` and run `apk upgrade --available`.
+Downgrading packages/versions is currently not supported.
+While it is technically possible, you are on your own.
+CAUTION: This is why it is not recommended to use edge repositories, unless you know what you're doing, or are tagging all those packages.