diff options
| -rw-r--r-- | modules/Working/pages/apk.adoc | 206 |
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 index 0000000..67cd450 --- /dev/null +++ b/modules/Working/pages/apk.adoc @@ -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: + +[horizontal] +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 +[source] +---- +[@tag] [protocol][/path][/release]/repository +# comments look like so. valid examples below +http://dl-cdn.alpinelinux.org/alpine/edge/main <1> +@testing http://dl-cdn.alpinelinux.org/alpine/edge/testing <2> +/var/apk/my-packages <3> +---- +<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: + +[source,sh] +---- +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. + +[WARNING] +==== +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. +==== + +[WARNING] +==== +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: + +[source,sh] +---- +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. + +=== Cleanup + +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 + +=== World + +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! + +=== Virtuals +// 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: +[source,sh] +---- +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`. + +[NOTE] +==== +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. |