Alpine Linux - User contributions [en]

User:Sertonix/Freedom of choice

2026-01-31T21:00:43Z

Sertonix: add capsudo

This is an overview over the different available programms, etc. that can be selected from when using alpine. It is also intended as a reference what should be documented and what could be supported.

== Bootloaders ==
* See: [[Bootloaders]]
* Also: {{Pkg|systemd-boot}}

== Kernel ==
* See: [[Kernels]]

== Libc ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|musl}} || style="background:lime" | Full || Default
|-
| [https://www.gnu.org/software/libc/ glibc] || style="background:red" | None || [[Running glibc programs]]
|-
| without aka static || style="background:orange" | depends on package || Note that this only means no libc at runtime
|}
* See also: [https://gitlab.alpinelinux.org/alpine/tsc/-/issues/17 alpine-glibc]
* See also: [https://wiki.gentoo.org/wiki/Libc Gentoo Wiki]

== Initramfs ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|mkinitfs}} || style="background:lime" | Full || Default
|-
| {{Pkg|dracut}} || style="background:lime" | Full ||
|-
| {{Pkg|booster}} || style="background:lime" | Full ||
|-
| [https://github.com/illiliti/tinyramfs tinyramfs] || style="background:red" | None ||
|-
| without || style="background:red" | None || may require [[custom Kernel]], [https://kisslinux.org/install#021 kisslinux without initramfs]
|}
* See also: [[Initramfs init]]
* See also: [https://wiki.gentoo.org/wiki/Initramfs Gentoo Wiki]

== PID 1 ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| busybox init || style="background:lime" | Full || Default
|-
| {{Pkg|dinit}} || style="background:orange" | In testing || Shutdown commands are prefixed with {{ic|dinit-}}. eg {{ic|dinit-reboot}}
|-
| {{Pkg|s6-linux-init}} || style="background:orange" | Works || Requires manually running {{ic|s6-linux-init-maker}}
|-
| {{Pkg|openrc-init}} || style="background:orange" | Manual setup ||
|-
| {{Pkg|dumb-init}} || style="background:silver" | Needs testing || For containers
|-
| runit-init || style="background:silver" | Needs testing || [https://dev.alpinelinux.org/~clandmeter/other/forum.alpinelinux.org/comment/383.html#comment-383 runit-init starting OpenRC]
|-
| {{Pkg|epoch}} || style="background:silver" | Needs testing ||
|-
| systemd || style="background:red" | None || Supported by postmarketOS
|-
| custom || style="background:lime" | Full || For example in docker containers
|}
* See also: [https://wiki.gentoo.org/wiki/Init_system Gentoo Wiki]
* See also: [https://wiki.archlinux.org/title/Init Archwiki]

== Service Manager ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[OpenRC]] || style="background:lime" | Full || Default
|-
| {{Pkg|dinit}} || style="background:orange" | In testing || {{Pkg|dinit-alpine}} includes service files
|-
| {{Pkg|s6-rc}} || style="background:orange" | Works || Not integrated. For containers there is {{Pkg|s6-overlay}}
|-
| {{Pkg|runit}} || style="background:orange" | As OpenRC service ||
|-
| {{Pkg|daemontools}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|daemontools-encore}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|supervisor}} || style="background:silver" | Needs testing ||
|-
| busybox runit || style="background:red" | None || Not enabled in a busybox package
|-
| systemd || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:lime" | Full || Requires to replace {{Pkg|alpine-base}} with custom set of packages (See {{Issue|71686}})
|}
* See also: [https://wiki.gentoo.org/wiki/Init_system Gentoo Wiki]
* See also: [https://wiki.archlinux.org/title/Init Archwiki]

== System Logs ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[Syslog#busybox_syslog|busybox syslog]] || style="background:lime" | Full || Default
|-
| {{Pkg|rsyslog}} || style="background:lime" | Full ||
|-
| {{Pkg|syslog-ng}} || style="background:lime" | Full ||
|-
| {{pkg|socklog}} || style="background:silver" | Needs testing ||
|-
| [https://skarnet.org/software/s6/s6-socklog.html s6-socklog] from {{pkg|s6}} || style="background:silver" | Needs testing ||
|-
| systemd-journald || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:silver" | Needs testing ||
|}
* See also: [[Syslog]]

== [[Device Manager]] ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[mdev]] || style="background:lime" | Full || Default
|-
| [[mdevd]] || style="background:lime" | Full ||
|-
| [[eudev]] || style="background:lime" | Full ||
|-
| vdev || style="background:red" | None ||
|-
| systemd-udev || style="background:red" | None || Supported by postmarketOS
|}

== Power Managment ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[busybox acpid]] || style="background:lime" | Full || Default
|-
| {{Pkg|acpid}} || style="background:lime" | Full ||
|-
| {{Pkg|elogind}} || style="background:silver" | Needs testing ||
|-
| systemd-logind || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:lime" | Full ||
|}
* See also: [https://wiki.archlinux.org/title/Power_management Archwiki]
* See also: [https://wiki.gentoo.org/wiki/Power_management Gentoo Wiki]

== DHCP Client ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[Udhcpc|busybox udhcpc]] || style="background:lime" | Full || Default
|-
| {{Pkg|dhcpcd}} || style="background:lime" | Full ||
|-
| {{Pkg|dhclient}} || style="background:lime" | Full ||
|-
| without aka static || style="background:lime" | Full ||
|}
* See also: [[Configure Networking]]
* See also: [https://wiki.archlinux.org/title/Network_configuration#DHCP Archwiki]
* See also: [https://wiki.gentoo.org/wiki/Resolv.conf Gentoo Wiki - resolv.conf]

== Wi-Fi ==
* See: [[Wi-Fi]]
* Also supported: {{pkg|eiwd}}

== Seat/Session Managnent ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[elogind]] || style="background:lime" | Full ||
|-
| {{Pkg|seatd}} || style="background:lime" | Full || seats only
|-
| {{Pkg|turnstile}} || style="background:silver" | needs testing || session only
|-
| systemd-logind || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:lime" | Full || Not recommended with graphical enviroment
|}
* [https://wiki.gentoo.org/wiki/Seatd Gentoo Wiki - seatd]
* [https://wiki.gentoo.org/wiki/Elogind Gentoo Wiki - elogind]
* [https://wiki.archlinux.org/title/Init#logind ArchWiki - systemd-logind]
* [https://chimera-linux.org/docs/configuration/seat Chimera Linux docs]

== Login ==

{| class="wikitable"
|-
! Name !! Support !! Supports [[PAM]] !! Notes
|-
| busybox login || style="background:lime" | Full || style="background:red" | No || Default
|-
| {{Pkg|greetd}} || style="background:lime" | Full || style="background:lime" | Yes || requires greeter
|-
| {{Pkg|shadow-login}} || style="background:lime" | Full || style="background:lime" | Yes ||
|-
| {{Pkg|util-linux-login}} || style="background:lime" | Full || style="background:lime" | Yes ||
|-
| systemd-logind || style="background:red" | None || style="background:lime" | Yes || Supported by postmarketOS
|-
| without || style="background:lime" | Full || style="background:red" | No ||
|}
* See also: [https://wiki.gentoo.org/wiki/Login Gentoo Wiki]

== Shell Utils ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|busybox}} || style="background:lime" | Full || Dependency of {{pkg|alpine-base}}
|-
| {{Pkg|busybox-extras}} || style="background:lime" | Full || Some commands that are missing in the main {{Pkg|busybox}} package
|-
| {{Pkg|util-linux}} || style="background:lime" | Full ||
|-
| [[GNU_core_utilities|coreutils]] || style="background:lime" | Full ||
|-
| {{Pkg|s6-portable-utils}} || style="background:lime" | Full ||
|-
| {{Pkg|s6-linux-utils}} || style="background:lime" | Full ||
|-
| {{Pkg|toybox}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|sbase}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|ubase}} || style="background:silver" | Needs testing ||
|-
| without || style="background:red" | None || A lot of implicit dependency
|}
* See also: [https://wiki.archlinux.org/title/Core_utilities Archwiki]

== Shell ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| busybox ash || style="background:lime" | Full || Default
|-
| {{Pkg|bash}} || style="background:lime" | Full ||
|-
| {{Pkg|dash}} || style="background:lime" | Full || When used as /bin/sh this may cause breakage.
|-
| {{Pkg|yash}} || style="background:lime" | Full ||
|-
| busybox hush || style="background:red" | None ||
|-
| without || style="background:red" | None || sometimes implicit dependency
|}
* See also: [[Change default shell]]
* See proposal: [https://gitlab.alpinelinux.org/alpine/tsc/-/issues/39 replace busybox ash with another /bin/sh]
* See also: [https://wiki.archlinux.org/title/Command-line_shell Archwiki]
* See also: [https://wiki.gentoo.org/wiki/Shell Gentoo Wiki]

== SU ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{ic|su}} from {{Pkg|busybox-suid}} || style="background:lime" | Full || default, can't be removed by default ({{issue|11730}})
|-
| {{ic|su}} from {{Pkg|shadow-login}} || style="background:lime" | Full ||
|-
| {{ic|su}} from {{Pkg|util-linux-login}} || style="background:lime" | Full ||
|-
| {{Pkg|sudo}} || style="background:lime" | Full ||
|-
| {{Pkg|doas}} || style="background:lime" | Full || sudo shim using doas: {{Pkg|doas-sudo-shim}}
|-
| [https://skarnet.org/software/s6/s6-sudo.html s6-sudo] || style="background:silver" | Needs testing ||
|-
| {{Pkg|capsudo}} || style="background:orange" | In development ||
|-
| run0 || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:lime" | Full ||
|}

== SSL/TLS ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|openssl}} || style="background:lime" | Full || Default
|-
| {{Pkg|libressl}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|bearssl}} || style="background:silver" | Needs testing ||
|}
* See also: [https://gitlab.alpinelinux.org/alpine/tsc/-/issues/28 consider LibreSSL as default OpenSSL provider again]
* See also: [https://wiki.archlinux.org/title/Transport_Layer_Security Archwiki]
* See also: [https://github.com/haproxy/wiki/wiki/SSL-Libraries-Support-Status haproxy SSL Libraries Support Status]

== Cron ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|cronie}} || style="background:lime" | Full ||
|-
| {{Pkg|dcron}} || style="background:lime" | Full ||
|-
| {{Pkg|fcron}} || style="background:lime" | Full ||
|-
| vixie-cron || style="background:red" | None ||
|-
| scron || style="background:red" | None ||
|-
| systemd.timer || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:lime" | Full || {{Pkg|alpine-baselayout}} includes cron specific directories though
|}
* See also: [https://wiki.archlinux.org/title/Cron Archwiki]
* See also: [https://wiki.gentoo.org/wiki/Cron Gentoo Wiki]

== SSH ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[Setting_up_a_SSH_server#OpenSSH|openssh]] || style="background:lime" | Full ||
|-
| [[Setting_up_a_SSH_server#Dropbear|dropbear]] || style="background:lime" | Full || provide {{ic|ssh}} command {{pkg|dropbear-ssh}}
|-
| without || style="background:lime" | Full ||
|}
* See also: [https://wiki.archlinux.org/title/Secure_Shell Archwiki]
* See also: [https://wiki.gentoo.org/wiki/SSH Gentoo Wiki - OpenSSH]
* See also: [https://wiki.gentoo.org/wiki/Dropbear Gentoo Wiki - Dropbear]

== Desktop ==
* See: [[Desktop environments and Window managers]]

== See Also ==
* [[Architecture|Alpine Architecture]]
* [https://gitlab.alpinelinux.org/alpine/tsc/-/issues/55 Future of busybox]

Alpine Package Keeper

2025-12-09T22:42:55Z

Sertonix: force-broken-world is independently of disless/sys installs a bad idea. Avoid disless users from considering to use the option

{{TOC right}}
This page documents the Alpine Package Keeper(APK), the package manager in Alpine Linux. Refer to the excellent guide [https://docs.alpinelinux.org/user-handbook/0.1a/Working/apk.html Working with APK] from Alpine Linux documentation project to learn the basics quickly.

[[Software management#Graphical software manager|Graphical software managers]] can be used for certain basic package management tasks like adding/removing and upgrading packages.

Package management in RAM-based installs like [[Installation#Diskless_Mode|Diskless]] mode and [[Data Disk Mode|Data disk]] mode require [[#Package management in Diskless mode|additional step using lbu]].

== apk v3 ==


{{Pill_clickable||v3 only|green|palegreen|right|Release Notes for Alpine 3.23.0#apk-tools_v3}}
With the release of Alpine Linux [[Release Notes for Alpine 3.23.0|v3.23]], the Alpine package manager has transitioned to [https://gitlab.alpinelinux.org/alpine/apk-tools/-/releases/v3.0.0 apk-tools v3], but the index and package formats are still at v2. apk v3 targets backwards compatibility and new features are flagged on the relevant sections of this page as seen on the right side. The diff output of the documentation between V2 and V3 is [[Apk/apkv3 doc diff|available here]] for reference.

== Overview ==

The {{pkg|apk-tools}} provides '''apk''' and it supports the following operations:
{| class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|-
|style="background:black; color:white" colspan=2 align=center |Package installation and removal
|-
|[[#Add a Package|add]] || Add or modify constraints in [[#World|WORLD]] and commit changes
|-
|[[#Remove a Package|del]] || Remove constraints from [[#World|WORLD]] and commit changes
|-
|style="background:black; color:white" colspan=2 align=center |System maintenance
|-
|[[#apk fix|fix ]] || Fix, reinstall or upgrade packages without modifying [[#World|WORLD]]
|-
|[[#Update Package list|update]]|| Update repository indexes
|-
|[[#Upgrade a Running System|upgrade]]|| Install upgrades available from repositories
|-
|[[#Local Cache|cache]] || Manage the local package cache
|-
|style="background:black; color:white" colspan=2 align=center |Querying package information
|-
|[[#apk query|query]] || Query information about packages by various criteria
|-
|[[#Listing installed packages|list]] || List packages matching a pattern or other criteria
|-
|[[#apk dot|dot]] || Render dependencies as [https://graphviz.org/ graphviz] graphs
|-
|[[#apk policy|policy]]|| Show repository policy for packages
|-
|[[#Search for Packages|search]] || Search for packages by name or description
|-
|[[#Information on Packages|info]] || Give detailed information about packages or repositories
|-
|-
|style="background:black; color:white" colspan=2 align=center |Repository and package maintenance
|-
|mkndx || Create repository index (v3) file from packages
|-
|mkpkg || Create package (v3)
|-
|index || Create repository index (v2) file from packages
|-
|fetch || Download packages from repositories to a local directory
|-
|manifest|| Show checksums of package contents
|-
|extract || Extract package file contents
|-
|verify || Verify package integrity and signature
|-
|adbsign || Sign, resign or recompress v3 packages and indexes
|-
|style="background:black; color:white" colspan=2 align=center |Miscellaneous
|-
|audit|| Audit system for changes
|-
|stats || Show statistics about repositories and installations
|-
|version|| Compare package versions or perform tests on version strings
|-
|adbdump|| Dump v3 files in textual representation
|-
|adbgen || Generate v3 files from text representation
|-
|convdb || Convert v2 installed database to v3 format
|-
|convndx || Convert v2 indexes to v3 format
|-
|}

== Packages and Repositories ==
{{Main|Repositories}}
Official software packages for Alpine Linux have the extension <code>.apk</code>, and are often called "a-packs". Packages in Alpine Linux are organized into [[Repositories|'''repositories''']] and are defined in the {{Path|/etc/apk/repositories}} file. [[Apk spec#Package Format V2|apk v2]] packages are digitally signed tar.gz archives containing programs, configuration files, and dependency metadata.

=== Subpackages ===

In Alpine Linux, software packages are thinned out and split into subpackages to give more control over what features are installed and keeps the installation as small and efficient as possible.

Subpackages related to service files, documentation and shell completions are installed automatically by the package manager using '''auto-install''' rule based on [[APKBUILD_Reference#install_if|install_if]] directive. For example, if {{pkg|zsh}} is already installed, on installing any package with {{pkg|*zsh-completion*}} subpackage, apk automatically installs the associated subpackage. The {{pkg|docs}} meta package for pulling in [[Alpine_Linux:FAQ#Why_don't_I_have_man_pages_or_where_is_the_'man'_command?|all documentation]] works the same way.

Alpine Linux [https://pkgs.alpinelinux.org package database] page shows the list of available subpackages for any package.

== World ==

At {{Path|/etc/apk/world}}, apk maintains the world, that is, a list of constraints the package selection needs to fulfill. World describes the desired system state. {{Path|/etc/apk/world}} is a plaintext file with one constraint using dependency notation per line. Each line has the format: 
<code>[!]NAME{@tag}{[<>~=]version}</code>.

There can be only one line with a given package NAME in the file and except the package NAME, all the other options are optional.

* '''!''' is used for [[#Masking a specific package|masking a specific package]]
* '''@tag''' allows apk to use the [[Repositories#Tagged_repository|tagged repository]] for the named package
* '''[<>~=]version''' are used for [[#Package pinning|package pinning]].

The commands {{ic|apk add foo}} and {{ic|apk del bar}} manipulate the desired state by adding or removing packages <code>foo</code>, <code>bar</code> respectively as a dependency constraint in {{Path|/etc/apk/world}}. If the {{Path|/etc/apk/world}} is edited manually, run the command [[#apk fix|apk fix]] to apply the changes.

Every constraint listed in {{Path|/etc/apk/world}} must be solvable in order for the system to be considered correct, and no transaction may be committed that is incorrect. If apk cannot verify the correctness of the requested change, it will back out adding the constraint before attempting to change what packages are actually installed on the system. Thus apk will never [[#ERROR:_unsatisfiable_constraints|commit]] a change to the system that leaves it unbootable.

{{Warning| The option {{ic|force-broken-world}}, will delete world constraints until a solution without conflicts is found to boot. This does not allow installation of packages with unjustifiable dependencies. Using this will likely result in unexpected removal of some packages.}}

== Update Package list ==

Alpine Linux [[Repositories|'''repositories''']] change as packages are added and upgraded. To get the latest list of available packages, use the ''update'' command. This command downloads the {{Path|APKINDEX.tar.gz}} from each repository and stores it in the local cache, typically {{Path|/var/cache/apk/}}, {{Path|/var/lib/apk/}} or {{Path|/etc/apk/cache/}}. {{Cmd|# apk update}}

Adding the <code>--update-cache</code>, or for short <code>-U</code> switch to another apk command, as in <code>apk --update-cache upgrade</code> or <code>apk -U add ...</code>, the command has the same effect as first running <code>apk update</code> before the other apk command.

It is a good idea to always do an '''update''' right '''before''' doing an '''upgrade or add''' command. That way the command will install the latest available packages from the repositories.

== Add a Package ==

Use '''add''' to install packages from a [[Repositories|'''repository''']]. Any necessary dependencies are also installed. If you have multiple repositories, the '''add''' command installs the newest package. {{Cmd|<nowiki># apk add openssh
# apk add openssh openntp vim </nowiki>}}

Packages from a [[Repositories#Tagged repository|tagged repository]] can be installed by adding tags to them:{{cmd|# apk add wireguard-go@testing}}

A specific package can also be [[#Package pinning|held back or pinned]] at a specific level or version.

=== Add a local Package ===

To install a locally available apk package, for example if this device has no internet access but you can upload apk packages directly to it, use the '''--allow-untrusted''' flag: {{cmd|# apk add --allow-untrusted /path/to/file.apk}}

Note that multiple packages can be given. When installing a local package, all dependencies should also be specified. For example:

{{cmd|# apk add --allow-untrusted /var/tig-2.2-r0.apk /var/git-2.11.1-20.apk}}

== Remove a Package ==

Use '''del''' to remove a package along with dependencies that are no longer needed.{{cmd|<nowiki># apk del openssh
# apk del openssh openntp vim</nowiki>}}

== Upgrade a Running System ==
{{Seealso|Upgrading Alpine Linux to a new release branch}}
To get the latest security upgrades and bugfixes available for all the installed packages from the [[Repositories#Release_Branches|current release branch]] of a running system, always [[#Update Package list| update the packages list]] before issuing the '''upgrade''' command as shown below:{{cmd|<nowiki># apk update
# apk upgrade </nowiki>}}

Or, combining the same into one single command:{{cmd|# apk -U upgrade}}

To upgrade only ''specific'' packages, use the '''upgrade''' command and specify them: {{cmd|<nowiki># apk update
# apk upgrade busybox</nowiki>}}

When upgrading packages, the package manager may create <var>apk-new</var> files to avoid overwriting configuration files. Once the packages are updated, remember to [[#Handling apk-new files|handle such <var>apk-new<var>]] files.

Here is an example, showing the procedure on a system that has [[Repositories#Using testing repository|testing repository tagged]]:
<Pre>
# apk update
fetch <nowiki>https://dl-3.alpinelinux.org/alpine/v3.6/main/x86_64/APKINDEX.tar.gz</nowiki>
fetch <nowiki>https://dl-3.alpinelinux.org/alpine/v3.6/community/x86_64/APKINDEX.tar.gz</nowiki>
fetch <nowiki>https://dl-3.alpinelinux.org/alpine/edge/testing/x86_64/APKINDEX.tar.gz</nowiki>
v3.6.2-191-gf98d79930f <nowiki>[https://dl-3.alpinelinux.org/alpine/v3.6/main]</nowiki>
v3.6.2-190-ga5d68c47df <nowiki>[https://dl-3.alpinelinux.org/alpine/v3.6/community]</nowiki>
v3.6.0-4624-g11f1b9c8ab <nowiki>[https://dl-3.alpinelinux.org/alpine/edge/testing]</nowiki>
OK: 20118 distinct packages available

# apk upgrade
(1/2) Upgrading extra-cmake-modules@testing (5.38.0-r0 -> 5.39.0-r0)
(2/2) Upgrading extra-cmake-modules-doc@testing (5.38.0-r0 -> 5.39.0-r0)
Executing mdocml-apropos-1.14.1-r0.trigger
OK: 2635 MiB in 803 packages
</Pre>

=== Upgrading "diskless" and "data" disk mode installs ===

When upgrading packages, the kernel and firmware packages are '''not''' upgraded. Upgrading them requires [[Diskless Mode#update-kernel script|'''update-kernel''']] script.

=== Handling apk-new files ===

apk avoids overwriting configuration files in the {{path|/etc}} directory. Whenever apk installs a file there, but realizes a potentially edited one is already present, it will write its file to that filename with {{path|.apk-new}} appended. When upgrading, you see a message like below: {{Cmd|# apk upgrade
(1/2) Upgrading openrc-user-pam (0.62.2-r2 -> 0.62.2-r3)
(2/2) Upgrading openrc (0.62.2-r2 -> 0.62.2-r3)
openrc-0.62.2-r3: installing file to etc/rc.conf.apk-new
openrc-0.62.2-r3.post-upgrade: Executing script}}

You may handle these by hand, or use [[Alpine configuration management scripts#update-conf|update-conf]] utility.

* To check for changes to configurations from the new packages: {{Cmd|# update-conf -a -l}}
* Simply invoking it will present you with the difference between the two files, and offer various choices for dealing with the conflicts.{{Cmd|# update-conf}}

=== Autoupdate tool for apk ===

Alpine Linux [https://github.com/jirutka/apk-autoupdate tool for automatic updates] is available as {{pkg|apk-autoupdate}} package. It can be used with [[Cron]] to enable unattended, automatic upgrades of packages.

== Package management in Diskless mode ==

Besides using [[#Local Cache|Local Cache]], all package management tasks in [[Diskless Mode|diskless]] and [[Data Disk Mode|Data disk]] mode systems like adding, removing and [[#Upgrading "diskless" and "data" disk mode installs|upgrading]] packages requires running the command: {{Cmd|'''# [[Alpine_local_backup#Committing changes|lbu commit]]'''}}

Only when the above command is run, the changes will take effect on next reboot.

== apk query ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
The query applet is a superset of [[#Information on Packages|info]], [[#Listing installed packages|list]] and [[#Search for Packages|search]] commands to interrogate the installed database and indexes for information related to packages. The command outputs human readable format in addition to json and yaml output.

== Search for Packages ==

{{Tip|Alpine Linux provides a specialized [https://pkgs.alpinelinux.org web interface] dedicated to looking through various available packages.}}

The '''search''' command searches the repository Index files for installable packages.

The return format is '''Package'''-'''Version'''. Omit '''Version''' for ''apk add '''Package'''''

Examples:
* To list all packages available, along with their descriptions: {{cmd|$ apk search -v}}
* To list all packages are part of the ACF system: {{cmd|$ apk search -v 'acf*' }}
* To list all packages that list NTP as part of their description, use the ''-d'' or ''--description'' option: {{cmd|$ apk search -v --description 'NTP' }}
* To list all packages that provide the <code>git</code> command: {{cmd|$ apk search -v 'cmd:git'}}

== Information on Packages ==

The '''info''' command provides information on the contents of packages, their dependencies, and which files belong to a package.

For a given package, each element can be chosen (for example, ''-w'' to show just the webpage information), or all information displayed with the ''-a'' command.

Example: {{cmd|$ apk info -a zlib}}

'''zlib-1.2.5-r1 description:'''
A compression/decompression Library

'''zlib-1.2.5-r1 webpage:'''
<nowiki>https://zlib.net</nowiki>

'''zlib-1.2.5-r1 installed size:'''
94208

'''zlib-1.2.5-r1 depends on:'''
libc0.9.32

'''zlib-1.2.5-r1 is required by:'''
libcrypto1.0-1.0.0-r0
apk-tools-2.0.2-r4
openssh-client-5.4_p1-r2
openssh-5.4_p1-r2
libssl1.0-1.0.0-r0
freeswitch-1.0.6-r6
atop-1.25-r0

'''zlib-1.2.5-r1 contains:'''
lib/libz.so.1.2.5
lib/libz.so.1
lib/libz.so

'''zlib-1.2.5-r1 triggers:'''

As shown in the example you can determine
* The '''description''' of the package (''-d'' or ''--description'')
* The '''webpage''' where the application is hosted (''-w'' or ''--webpage'')
* The '''size''' the package will require once installed (in bytes) (''-s'' or ''--size'')
* What packages are required to use this one ('''depends''') (''-R'' or ''--depends'')
* What packages require this one to be installed ('''required by''') (''-r'' or ''--rdepends'')
* The '''contents''' of the package, that is, which files it installs (''-L'' or ''--contents'')
* Any '''triggers''' this package sets. (''-t'' or ''--triggers'') Listed here are directories that are watched; if a change happens to the directory, then the trigger script is run at the end of the apk add/delete. For example, doing a depmod once after installing all packages that add kernel modules.

=== Check file ownership ===

The '''info''' command is also useful to determine which package a file belongs to. For example: {{cmd|$ apk info --who-owns /sbin/lbu}}
will display
<pre>
/sbin/lbu is owned by alpine-conf-x.x-rx
</pre>

=== Check Dependencies ===

The '''info''' command specific to check package dependency and reverse dependency is explained below:

The option '''-R''' or '''--depends''' lists the dependencies of the package: {{Cmd|$ apk info --depends pipewire}}
<pre>
pipewire-1.0.6-r1 depends on:
/bin/sh
so:libc.musl-x86_64.so.1
so:libpipewire-0.3.so.0
</pre>

The option '''-r''' or '''--rdepends''' lists the reverse dependencies of the package (all other packages which depend on the package). {{Cmd|$ apk info --rdepends pipewire}}
<pre>
pipewire-1.0.6-r1 is required by:
xdg-desktop-portal-wlr-0.7.1-r0
pipewire-pulse-1.0.6-r1
</pre>

=== Listing installed packages ===

To list all installed packages, use: {{Cmd|$ apk info}}

To list all installed packages in alphabetical order, with a description of each, do:{{Cmd|$ apk -vv info|sort}}

To list packages locally installed that are not longer available in repositories, use {{Cmd|$ apk list --orphaned}}

To browse details of installed package in a "TUI" with:{{Cmd|<nowiki>$ apk list --installed -q | fzf --preview 'apk query {1}'</nowiki>}}

To list subpackages for a package, for e.g {{pkg|util-linux}}:{{Cmd|$ apk list --quiet --origin util-linux}}

The apk tool does not have a subcommand to list manually-installed packages that do not have reverse dependencies. To get this information on a traditional system that is not using [[Alpine local backup|lbu]], try this script. Note that this approach will also list core packages like alpine-base that should not be removed.

<pre>
#!/bin/sh
apk info | grep -ve '-doc$' | sort | while read pkg
do
rdep=`apk info -qr "$pkg"`
[ -z "$rdep" ] && echo $pkg
done
</pre>

== Local Cache ==
{{Seealso|Local APK cache}}
APK can keep a cache of installed packages on a local disk. HDD or [[Installation#System_Disk_Mode|sys mode]] installs don't need an apk cache, it still allows to serve packages over the network, though, e.g. to get installed by other local machines.

{{Note|For [[Diskless Mode|diskless]] installations, [[Local APK cache|local package cache]] is needed to automatically (re-)install packages when booting.}}

When newer packages are added to the cache over time, the older versions of the packages default to remain in the cache directory. The older versions of packages can be removed with the '''clean''' command. {{cmd|# apk cache clean}} Or to see what is deleted include the verbose switch: {{cmd|# apk -v cache clean}}

If packages got deleted accidentally from the cache directory, then use the '''download''' command, {{cmd|# apk cache download}}

The above two steps can be combined into one with the '''sync''' command - this cleans out old packages and downloads missing packages. {{cmd|# apk cache -v sync}}

== apk dot ==

The dot option renders package dependencies as {{pkg|graphviz}} graphs.[[File:Seatd dependencies.png|800px|center|alt=Seatd dependencies|Seatd dependencies]] Steps to use the dot option is documented below:
# Save the output of apk dot option to a dot file.{{Cmd|$ apk dot seatd > seatd_dependencies.dot}}
# Use <code>dot</code> utility from {{pkg|graphviz}} package to convert the {{Path|seatd_dependencies.dot}} file into a graphical format such as PNG, PDF, or SVG. {{Cmd|$ dot -Tpng seatd_dependencies.dot -o seatd_dependencies.png}}

== apk fix ==

If a package is specified, the '''fix''' subcommand applies repair strategies to correct errors in the installation of the specified packages. If no packages are specified, this command synchronizes all the installed packages with the [[#World|desired system state]].

== apk policy ==

To display the repository a package was installed from and will be updated from, plus any [[#Repository_pinning|tagged]] or enabled repositories where it is also offered, if any, for this architecture - its '''policy''': {{Cmd|$ apk policy ''package''}}

For example:
<pre>
$ apk policy vlc
vlc policy:
2.2.6-r1:
lib/apk/db/installed
https://dl-3.alpinelinux.org/alpine/v3.7/community
3.0.0_rc2-r1:
@edgecommunity https://dl-3.alpinelinux.org/alpine/edge/community
</pre>

== Configuration file ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
Support for config file for setting default global options has been enabled. The user defined config file {{path|/etc/config/apk}}, if present overrides the {{path|/lib/apk/config}}, intended for distribution default options. To override the default config file name, the environment variable {{ic|APK_CONFIG}} can be used.

The configuration file contains one long option per line as shown here for reference:{{Cat|/etc/config/apk|no-cache
timeout 120}}

The following aliases are available: {{ic|cache}} equals {{ic|cache yes}} and {{ic|no-cache}} equals {{ic|cache no}}.

== Transaction logs ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
All apk commands which modify the database i.e write transactions are logged to {{Path|/var/log/apk.log}}. To disable the writing of the log file, the configuration option {{ic|logfile}} in the [[#Configuration file|configuration file]] must be set as follows:{{Cat|/etc/config/apk|logfile no}}

== Advanced APK Usage ==

=== Commandline repository options ===

By default, the '''apk''' utility will use the system repositories for all operations. This behavior can be overridden by the following options:
{|
| --repositories-file REPOFILE
| Override the system repositories by specifying a repositories file.
|-
| <nowiki>-X|--repository REPO</nowiki>
| Specify a supplemental repository that will be used in addition to the system repositories. This option can be provided multiple times.
|}

{{cmd|# apk add cherokee --update-cache --repository https://dl-cdn.alpinelinux.org/alpine/edge/testing/ --allow-untrusted}}

=== Package pinning ===
{{Seealso|Repositories#Tagged repository}}

In certain cases, you may want to upgrade a system, but keep a specific package at a specific level or version by pinning a Package. It is possible to add "sticky" or versioned dependencies.

{{Warning| If you desire deterministic, repeatable package installation (such as with containerized environments) via package pinning, it is important to understand your package repo's version retention rules. Always pin to a package version that is intended for your [[Repositories#Release_Branches|release branch]]. Pinning to a version on the [[Repositories#Edge|edge]] branch may stop working after the package version is revoked from the repo.}}

For instance, to hold the ''asterisk'' package to the 1.6.2 level or lower:{{cmd|<nowiki># apk add asterisk=1.6.0.21-r0</nowiki>}}
or {{cmd|# apk add 'asterisk<1.6.1'}}

To upgrade the entire system, keeping the asterisk package at the 1.6.0 or lower level:{{cmd|# apk upgrade}}

To later upgrade to the current version, and ensure that 1.6.1 is the minimum version used. {{cmd|# apk add 'asterisk>1.6.1'}}

You can also use "fuzzy" version matching to pin the version to a major/minor release. To match any version of asterisk that starts with 1.6 (such as 1.6.0.21-r0 or 1.6.9.31-r9) use the command: {{cmd|<nowiki># apk add 'asterisk=~1.6'</nowiki>}}

==== Holding a specific package back ====
See [[#Package pinning|Package pinning]]

=== Masking a specific package ===

In case a package is pulled in yet is superfluous or unwanted, or if it were to be installed and conflict with another, one could ''mask'' it i.e. ''exclude it'' from being installed unless '''apk''' is later instructed ''explicitly'' to add it. To mask/exclude an unwanted package hypothetically called ''foo'':
{{Cmd|# apk add '!foo'}}
Beforehand, ensure that the '''''package is not installed'''''. If so, ''uninstall it first'', as otherwise, it would become an ''"orphaned package"'': installed, yet not being managed by the '''apk''' package keeper, which could cause an obfuscated problem(s) if it or its dependencies linger and later conflict with another package; it could be harder to trace the issue(s) then.

The package then appears negated in ''world'':
{{Cat|/etc/apk/world|fon
!foo
fop}}

The exclamation mark (!) is often used in logic and IT to express negation.
Be sure to '''employ the single quotes''' (') so as to avoid an unintended interpretation by the shell interpreter. Say, if the command were effected in a '''bash''' shell without using quotes, {{ic|!}} may be interpreted as 'history expansion', as opposed to 'negate installation', as intended. The single quotes enclose the package/package versions, with or with the negation, to be handed directly to the '''apk''' tool and is then not interpreted by the shell.

==== Unmasking a specific package ====

Simply install it ''explicitly'' using '''apk'''. Say:
{{Cmd|# apk add foo}}
Uninstall it afterwards, if not required.
Alternatively, delete the line in {{Path|/etc/apk/world}} where the package is negated. Be sure not to leave any spurious character.

=== Commit hooks ===

If you'd like to trigger an action or run a certain script on every commit made by apk, there's a built-in method for that. On every commit apk looks for executables located in the "/etc/apk/commit_hooks.d/" directory, and executes them both before and after the commit. To provide some way to selectively run hooks either before or after a change is commited by apk, the scripts are called with "pre-commit" or "post-commit" as argument 1.
This is an example of a hook to do different things before and after commit:

{{cmd|1=#!/bin/sh

if [ "$1" = "pre-commit" ]; then
do_something

elif [ "$1" = "post-commit" ]; then
do_something_else
fi}}

Commit hooks are $PATH-aware, so for the sake of security it's recommended to specify absolute paths to executables.

== Rosetta Stone ==

[[Comparison with other distros#Comparison chart/Rosetta Stone|Rosetta Stone]] or a Comparison chart shows how standard things related to package management are done in Alpine Linux compared to other popular distributions.

== Troubleshooting ==

=== ERROR: unable to select packages ===

This error typically indicates that the package manager cannot find a suitable package to install. On issuing a command to add a package for eg: {{ic|# apk add labwc}}, you may receive below error message:
<Pre>
ERROR: unable to select packages:
labwc (no such package):
required by: world[labwc]
</Pre>

The above error indicates {{pkg|labwc}} does not exist in the [[Repositories|repositories]] currently configured in {{Path|/etc/apk/repositories}}. Ensure that <code>community</code> repository is [[Repositories#Managing_repositories|enabled]], as by default only <code>main</code> repository is enabled. You may also want to check [https://pkgs.alpinelinux.org/packages packages database] to identify the correct package name and the [[Repositories|repository]] in which the package is available.

<Pre>
ERROR: unable to select packages:
so:libxml2.so.2 (no such package):
required by: llvm19-libs-19.1.7-r1[so:libxml2.so.2]
</Pre>

The above error message may occur in [[Edge|Edge]] branch in certain other situations, even if all the necessary [[Repositories|repositories]] are enabled. Temporary non-availability of the packages from the repositories can occur, when software packages are [https://build.alpinelinux.org/ rebuilt]. You may want to wait for some time to try again.

=== ERROR: unsatisfiable constraints ===

This error signifies a dependency conflict. It means that the package you're trying to install has dependencies that cannot be simultaneously satisfied within the current package repository.

You may want to check [https://pkgs.alpinelinux.org/packages packages database] to identify the correct package name and version and the [[Repositories|repository]] in which the package is available.

=== WARNING: This apk-tools is OLD! ===

'''apk update''', '''apk upgrade''' or '''apk add''' may report the following:
WARNING: This apk-tools is OLD! Some packages might not function properly

This may happen if you are running Alpine Linux stable version with a [[Repositories#Edge|Edge]] package(s) also installed. One resolution is to consider upgrading {{pkg|apk-tools}}. If edge/main is already [[Repositories#Tagged repository|tagged]] as ''@edgemain'' in your {{Path|/etc/apk/repositories}} file, then try: {{Cmd|# apk add --upgrade apk-tools@edgemain}}

=== ERROR: UNTRUSTED signature ===

This happens when the release version changes. You need to update the local apk keys.

If you have already updated your repositories, allow them to update without the trusted key:
{{Cmd|# apk update --allow-untrusted}}

Then install the keys upgrade:
{{Cmd|# apk fix --upgrade --allow-untrusted alpine-keys}}

Now updates and upgrades should proceed normally.

Alternative, the updated alpine-keys package may be obtained, verified, installed directly, as covered earlier, prior to a repository update.

=== ERROR: unable to select packages: breaks: world ===

{{Cmd|<nowiki># apk add vim
ERROR: unable to select packages:
vim-common-9.1.1566-r0:
breaks: world[!vim-common]
satisfies: vim-9.1.1566-r0[vim-common=9.1.1566-r0]</nowiki>}}

When issuing package management commands, the above error will arise, if the command cannot be solved without breaking the [[#World|World]]. 

=== World updated but the following packages are not removed ===

On issuing a command to remove a package for eg: {{ic|# apk del btrfs-progs}}, you may receive below error message:
<Pre>
World updated, but the following packages are not removed due to:
btrfs-progs: btrbk
</Pre>

Here, the removal of package {{Pkg|btrfs-progs}} affects another package {{Pkg|btrbk}} in the constraints file [[#World|/etc/apk/world]]. So the package {{Pkg|btrfs-progs}} will be removed from the constraints file, but not removed from the system. The {{Pkg|btrfs-progs}} will remain in the system, until the constraint i.e {{Pkg|btrbk}} which depends on {{Pkg|btrfs-progs}} is removed.

If {{ic|apk del btrbk}} is issued, the package {{Pkg|btrfs-progs}} will be automatically removed from system as the constraint {{Pkg|btrfs-progs}} does not exist in {{Path|/etc/apk/world}}.

== See also ==

* [https://git.alpinelinux.org/apk-tools/tree/doc/apk.8.scd Manual for apk(8)]
* [https://git.alpinelinux.org/apk-tools/tree/doc/apk-world.5.scd Manual for apk-world(5)]
* [https://pkgs.alpinelinux.org Official web interface for packages]
* [[Software management]]
* [https://ariadne.space/2021/04/24/why-apktools-is-different-than.html Why apk-tools is different than other package managers]
* [https://ariadne.space/2021/10/30/spelunking-through-the-apktools-dependency.html spelunking through the apk-tools dependency solver]
* [https://whynothugo.nl/journal/2023/02/18/in-praise-of-alpine-and-apk/ In praise of alpine and apk]
* [https://www.cyberciti.biz/faq/10-alpine-linux-apk-command-examples/ 10 Alpine Linux apk Command Examples]
[[Category:Package Manager]]
[[Category:System_Administration]]

Create Alpine Linux PV DomU

2025-12-09T22:32:57Z

Sertonix: /* Install the guest */ fix path of initramfs

== Obtain a copy of Alpine Linux ==

To create an Alpine Linux paravirtualized (PV) DomU you'll need an Alpine Linux iso.

Download the latest alpine-virt iso from https://alpinelinux.org/downloads/

In this example we'll use {{path|/data/}} for the download and disk images.

==Mount the ISO image ==

Next, mount the iso so you can read the kernel and initramfs:

{{cmd | mount -t iso9660 -o loop /data/alpine-virt-{{AlpineLatest}}-x86_64.iso /media/cdrom }}

Now you have the kernel in {{path|/media/cdrom/boot/vmlinuz-virt}} and initramfs in {{path|/media/cdrom/boot/initramfs-virt}}.

Alternatively you can use {{path|uniso}} or {{path|7z}} to extract the content to a temporary area.

== Create the disk image ==
Now you need to create an empty file to be used as the hard drive of the DomU (in this example we are using a 3GB disk):

{{cmd | <nowiki>dd if=/dev/zero of=/data/a1.img bs=1M count=3000</nowiki>}}

Alternatively, if an LVM volume group (e.g. vg1) with free space is available on dom0, create a logical volume for Alpine:

{{cmd | <nowiki>sudo lvcreate -n alpine -L 10g vg1</nowiki>}}

== Create a DomU config file that boots the ISO image ==
Next, create a basic DomU configuration file, so you can launch the pv guest iso (save it where you like, although the most common place is {{path|/etc/xen/}}).

{{cat | /etc/xen/a1.cfg | <nowiki># Alpine Linux PV DomU

# Kernel paths for install
kernel = "/media/cdrom/boot/vmlinuz-virt"
ramdisk = "/media/cdrom/boot/initramfs-virt"
extra="modules=loop,squashfs console=hvc0"

# Path to HDD and iso file
disk = [
'format=raw, vdev=xvda, access=w, target=/data/a1.img',
'format=raw, vdev=xvdc, access=r, devtype=cdrom, target=/data/alpine-virt-</nowiki>{{AlpineLatest}}<nowiki>-x86_64.iso'
]

# Network configuration
vif = ['bridge=br0']

# DomU settings
memory = 512
name = "alpine-a1"
vcpus = 1
maxvcpus = 1
</nowiki>}}

If using LVM, replace {{path|/data/a1.img}} with {{path|/dev/vg1/alpine}} in the disk specification.

== Install the guest ==
Now that you have the necessary files, you can start the DomU to proceed with the install:

{{cmd|xl create -f /etc/xen/a1.cfg -c}}

Log into the system with user "root" and no password.

After configuring the basic system, you will be asked where would you like to install Alpine. Choose xvda and sys.

That will create three partitions on your disk. xvda1 for {{path|/boot}}, xvda2 for swap and xvda3 for {{path|/}}

<pre>
Available disks are:
xvda (3.1 GB )
Which disk(s) would you like to use? (or '?' for help or 'none') [none] xvda
The following disk is selected:
xvda (3.1 GB )
How would you like to use it? ('sys', 'data' or '?' for help) [?] sys
WARNING: The following disk(s) will be erased:
xvda (3.1 GB )
WARNING: Erase the above disk(s) and continue? [y/N]: y
Initializing partitions on /dev/xvda...
Creating file systems...
Installing system on /dev/xvda3:

Installation is complete. Please reboot.

#
</pre>

When you reboot, the pv bootloader pvgrub, will look to {{path|/boot/grub/grub.cfg}} for its menu, so create that file first.

Mount the boot partition and create a {{path|grub/grub.cfg}} file for pvgrub. (Note that grub.cfg is for pvgrub2 which replaced pvgrub1 and its menu.lst beginning in 2013.)

{{cmd |<nowiki>mount /dev/xvda1 /mnt
mkdir /mnt/grub</nowiki>}}

Install a basic text editor like {{pkg|nano}} or {{pkg|vim}}: 
{{cmd | apk add nano}}

If using nano, enter: 
{{cmd | nano /mnt/grub/grub.cfg}}

Then add the following to create a basic grub2 configuration file:
{{cat | /mnt/grub/grub.cfg |<nowiki>menuentry 'alpine-xen' {
set root=(xen/xvda,msdos1)
linux /boot/vmlinuz-virt root=/dev/xvda3 modules=ext4 console=hvc0
initrd /boot/initramfs-virt
}</nowiki>}}

Finally, Ctrl-S to save, Ctrl-X to exit nano.

Unmount and power off.
{{cmd |umount /mnt
poweroff}}

== Adjust the domU config file to boot from fresh install ==

In your Dom0, edit your DomU config file to boot with pvgrub.

{{cat | /etc/xen/a1.cfg |<nowiki># Alpine Linux PV DomU

kernel = "/usr/lib/grub-xen/grub-x86_64-xen.bin"

# Path to HDD and iso file
disk = [
'format=raw, vdev=xvda, access=w, target=/data/a1.img'
]

# Network configuration
vif = ['bridge=br0']

# DomU settings
memory = 512
name = "alpine-a1"
vcpus = 1
maxvcpus = 1
</nowiki>}}

Make sure that grub-xenhost is installed.
{{cmd | apk add grub-xenhost}}

Remember to unmount the loopback iso image.
{{cmd | umount /media/cdrom}}

The next time you boot, you'll be presented with the grub boot menu, and your VM will boot.

== Using Legacy pvgrub ==

To use Legacy pvgrub you need to use a {{path|/boot/grub/menu.lst}} instead of {{path|/boot/grub/grub.cfg}}.

{{cat | /etc/xen/a1.cfg |<nowiki>default 0
timeout 2
title alpine-xen-pv
root (hd0,0)
kernel /boot/vmlinuz-virt root=/dev/xvda3 modules=ext4 console=hvc0
initrd /boot/initramfs-virt
</nowiki>}}

And in {{path|/etc/xen/a1.cfg}} you need to change the 'kernel' loader to
{{cat | /etc/xen/a1.cfg |<nowiki>...
kernel = "/usr/lib/xen/boot/pv-grub-x86_64.gz"
...
</nowiki>}}

== See also ==
* [https://www.linkedin.com/pulse/setting-up-alpine-linux-370-domu-vm-xenserver-72-ali-poursamadi Setting up Alpine Linux 3.7.0 as a domU VM on XenServer 7.2]

[[Category:Virtualization]]

Git

2025-10-05T13:02:52Z

Sertonix: fix broken link

This document describes how to use [https://git-scm.com git] for Alpine Linux development. If you just want to browse all the available Alpine git repositories, [https://git.alpinelinux.org git.alpinelinux.org] shows them all.

If you are new to git and need quick reference, check [[#Git Basics|Git Basics]]. For more info, refer [[#Further reading|further reading]] section.

== General git workflow ==

There are two ways to work with the Alpine git repository.
* without write access.
* with write access.

Most contributors to Alpine linux will be working [[#Forking a repository|with a forked repository]]. Only [https://docs.alpinelinux.org/governance/0.1b/Teams/developers.html Alpine Developers] have write access.

Follow this [[Creating_an_Alpine_package#Overview|overview]] to [[Creating an Alpine package|create a package]] or [[Creating patches|submit a patch]] even without write access.

=== Configure your global git config ===
{{:Include:Git configuration}}
If you want to use git with colored output use:{{Cmd|git config --global color.ui true
git config --global core.pager more}}
{{Tip|If you want to use git with proxy server:{{Cmd|git config --global http.proxy <nowiki>http://proxy_ip:proxy_port</nowiki>}}}}

=== Creating a gitlab account ===

Visit [https://gitlab.alpinelinux.org Alpine gitlab] to create a gitlab account.

=== Forking a repository ===

To [[Creating an Alpine package|create an Alpine package]] or [[Creating patches|submit a patch]] without write access to the Alpine repository, you need to fork the desired repository. [[#Creating a gitlab account|Create a gitlab account]], if not already done.

Create a fork for '''aports''' at https://gitlab.alpinelinux.org/alpine/aports. Refer [https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html#creating-a-fork Gitlab docs] if you're having problems with that.

Once created, the fork resides on the Gitlab server, until you [[#Cloning your forked repository|clone your fork]].

=== Cloning your forked repository ===

You can clone your [[#Forking a repository|forked]] repository, by replacing $USER with the nickname of your Gitlab account and $REPO in the git command: {{Cmd|$ git clone <nowiki>git@gitlab.alpinelinux.org:$USER/$REPO.git</nowiki>}}

Before you clone the '''aports''' repository, switch to the directory you want to have the {{Path|aports/}} directory. To clone your [[#Forking a repository|forked]] '''aports''' repository with only the last 3 revisions, replace $USER and issue the command: {{Cmd|$ git clone <nowiki>git@gitlab.alpinelinux.org:$USER/aports.git</nowiki> --depth 3}}

To see the full log of the trunk, use the command below: {{Cmd|git log}}

{{Tip|To update your old clone, see [[Include:Git_Basics#Rebasing_against_upstream_master|rebasing]].}}

=== Cloning aports repository ===

You can also clone the Alpine Linux aports repository instead of [[#Cloning your forked repository|forked repository]] using the command: {{Cmd|$ git clone <nowiki>git://git.alpinelinux.org/aports.git</nowiki>}}

Unless you have necessary permissions, you will not be able to push your changes back to the repository.

== Git Basics ==
{{:Include:Git Basics}}

== Quality assurance ==
{{:Development using git:Quality assurance}}

== Further reading ==
{{:Development_using_git:Documentation}}

== See also ==

* [[Creating_an_Alpine_package|Submit new packages]]
* [[Creating an Alpine package]]
* [[Package Maintainers]]
* [[Development_using_git:Developer_repositories|Developer repositories]]
* [[Development_using_git:Cgit| Using Cgit]]
* [[Gitolite]]

[[Category:Development]]
[[Category:Git]]

Include:Git configuration

2025-10-05T12:59:25Z

Sertonix: The name doesn't need to be a full name and some people might be scared when making it seem like it

Configure your name and email address in git. This name and email address will show up in all your commits: {{Cmd|$ git config --global user.name "Your Name"
$ git config --global user.email "your@email.address"}}

Using <tt>git config</tt> without <tt>--global</tt> let you configure other details for a specific git repository.

Git

2025-10-05T12:55:44Z

Sertonix: Not having write access is the standard for almost all contributors, not only new ones

This document describes how to use [https://git-scm.com git] for Alpine Linux development. If you just want to browse all the available Alpine git repositories, [https://git.alpinelinux.org git.alpinelinux.org] shows them all.

If you are new to git and need quick reference, check [[#Git Basics|Git Basics]]. For more info, refer [[#Further reading|further reading]] section.

== General git workflow ==

There are two ways to work with the Alpine git repository.
* without write access.
* with write access.

Most contributors to Alpine linux will be working [[#Submitting work without write access|without write access]]. Only [https://docs.alpinelinux.org/governance/0.1b/Teams/developers.html Alpine Developers] have write access.

Follow this [[Creating_an_Alpine_package#Overview|overview]] to [[Creating an Alpine package|create a package]] or [[Creating patches|submit a patch]] even without write access.

=== Configure your global git config ===
{{:Include:Git configuration}}
If you want to use git with colored output use:{{Cmd|git config --global color.ui true
git config --global core.pager more}}
{{Tip|If you want to use git with proxy server:{{Cmd|git config --global http.proxy <nowiki>http://proxy_ip:proxy_port</nowiki>}}}}

=== Creating a gitlab account ===

Visit [https://gitlab.alpinelinux.org Alpine gitlab] to create a gitlab account.

=== Forking a repository ===

To [[Creating an Alpine package|create an Alpine package]] or [[Creating patches|submit a patch]] without write access to the Alpine repository, you need to fork the desired repository. [[#Creating a gitlab account|Create a gitlab account]], if not already done.

Create a fork for '''aports''' at https://gitlab.alpinelinux.org/alpine/aports. Refer [https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html#creating-a-fork Gitlab docs] if you're having problems with that.

Once created, the fork resides on the Gitlab server, until you [[#Cloning your forked repository|clone your fork]].

=== Cloning your forked repository ===

You can clone your [[#Forking a repository|forked]] repository, by replacing $USER with the nickname of your Gitlab account and $REPO in the git command: {{Cmd|$ git clone <nowiki>git@gitlab.alpinelinux.org:$USER/$REPO.git</nowiki>}}

Before you clone the '''aports''' repository, switch to the directory you want to have the {{Path|aports/}} directory. To clone your [[#Forking a repository|forked]] '''aports''' repository with only the last 3 revisions, replace $USER and issue the command: {{Cmd|$ git clone <nowiki>git@gitlab.alpinelinux.org:$USER/aports.git</nowiki> --depth 3}}

To see the full log of the trunk, use the command below: {{Cmd|git log}}

{{Tip|To update your old clone, see [[Include:Git_Basics#Rebasing_against_upstream_master|rebasing]].}}

=== Cloning aports repository ===

You can also clone the Alpine Linux aports repository instead of [[#Cloning your forked repository|forked repository]] using the command: {{Cmd|$ git clone <nowiki>git://git.alpinelinux.org/aports.git</nowiki>}}

Unless you have necessary permissions, you will not be able to push your changes back to the repository.

== Git Basics ==
{{:Include:Git Basics}}

== Quality assurance ==
{{:Development using git:Quality assurance}}

== Further reading ==
{{:Development_using_git:Documentation}}

== See also ==

* [[Creating_an_Alpine_package|Submit new packages]]
* [[Creating an Alpine package]]
* [[Package Maintainers]]
* [[Development_using_git:Developer_repositories|Developer repositories]]
* [[Development_using_git:Cgit| Using Cgit]]
* [[Gitolite]]

[[Category:Development]]
[[Category:Git]]

APKBUILD examples:Rust

2025-10-05T12:51:44Z

Sertonix: use CHOST instead of CTARGET like in the latest newapkbuild

== Considerations ==

Use <code>cargo-auditable</code> to encode dependency information into binaries.

Most Rust projects use <code>cargo</code> to fetch Rust library dependencies. The current convention it to use <code>options="net"</code> fetch these during the <code>prepare()</code> phase. Use the <code>--locked</code> flag to ensure that the exact same versions of dependencies are fetched on each rebuild. If a package is missing a lockfile, include one with the aport and attempt to recommend upstream to include one.

== Examples ==

=== Basic example ===

<pre>
maintainer="Hugo Osvaldo Barrera <hugo@whynothugo.nl>"
pkgname=harper
pkgver=0.59.0
pkgrel=0
pkgdesc="Grammar checker that respects your privacy"
url="https://github.com/elijah-potter/harper"
arch="all"
license="Apache-2.0"
makedepends="cargo-auditable rust"
source="harper-$pkgver.tar.gz::https://github.com/elijah-potter/harper/archive/v$pkgver/harper-$pkgver.tar.gz"
options="net"

prepare() {
default_prepare

cargo fetch --target="$CHOST" --locked
}

build() {
cargo auditable build --release --frozen
}

check() {
cargo test --frozen
}

package() {
install -Dm755 target/release/harper-cli "$pkgdir"/usr/bin/harper-cli
install -Dm755 target/release/harper-ls "$pkgdir"/usr/bin/harper-ls
}

sha512sums="
e5be781b33ba624e2447464a51ff8c0b565a42d7bf957c2fd6655f4bf312211fcf669bbb152b62a57494f89fd7fbee7eda37bbbaf7a61c5d4c8c9684ffe687bd harper-0.48.0.tar.gz
"
</pre>

== See also ==

* [[APKBUILD examples]]
* [[Creating an Alpine package]]

[[Category:Development]] [[Category:Rust]]

Eudev

2025-09-06T17:52:05Z

Sertonix: Explicitly mention that a different device manager should be setup first

{{DISPLAYTITLE:eudev}}
[https://github.com/eudev-project/eudev eudev] is a [[Device_Manager|device manager]] that provides a drop-in replacement for systemd udev. It is therefore recommended for full blown desktop environments.

== Installation ==

The easy way to setup eudev is through the [[#Setup_script|setup script]]. Only advanced users are recommended to do [[#Manual installation|manual installation]].

=== Setup script ===
{{:Include:Setup Device Manager}}

No need for further configuration steps as the above script takes care of all necessary changes.

=== Manual installation ===

You need to install {{pkg|eudev}} itself. {{cmd|# apk add {{pkg|eudev}} {{pkg|udev-init-scripts}}}}

Proceed to [[#Configuration|Configuration]] step to configure eudev.

== Configuration ==

=== Service management ===

{{Note| If you already have a [[Device_Manager|device manager]] installed, you need to disable it before you enable eudev, to avoid conflicts during next reboot.}}

To use eudev as device manager enable the following services.

{{cmd|<nowiki># rc-update add udev sysinit
# rc-update add udev-trigger sysinit
# rc-update add udev-settle sysinit
# rc-update add udev-postmount default
</nowiki>}}

If you are not running in a [[Chroot]], you will also want to start eudev. {{Note| If you already have a [[Device_Manager|device manager]] installed, you need to stop it before you start eudev.}}

{{cmd|<nowiki># rc-service udev start
# rc-service udev-trigger start
# rc-service udev-settle start
# rc-service udev-postmount start </nowiki>}}

Whenever udev rules are changed, for the changes to take immediate effect, use the command:{{Cmd|<nowiki># udevadm control --reload-rules
# udevadm trigger</nowiki>}}

A reboot is usually necessary for the rule changes to fully take effect.

=== Predictable network interface names ===

eudev can automatically assign predictable, stable network [[Configure Networking#Interface configuration|interface names]] for all local Ethernet, WLAN and WWAN interfaces instead of the traditional interface naming scheme ("eth0", "eth1", "wlan0", ...).

If you want [https://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames/ predictable network interface names], install the {{pkg|eudev-netifnames}} package. {{cmd|# apk add {{pkg|eudev-netifnames}}}}

== Manual removal ==

{{warning|Use [[#Setup script|Setup script]] to change device manager. Manual removal of a device manager without first setting up an alternative may cause unexpected issues.}}

If you are not running in a chroot you need to stop the service first.{{cmd|<nowiki># rc-service udev stop
# rc-service udev-postmount stop</nowiki>}}

Then disable the services. {{cmd|<nowiki># rc-update delete udev sysinit
# rc-update delete udev-trigger sysinit
# rc-update delete udev-settle sysinit
# rc-update delete udev-postmount default</nowiki>}}

You might also want to uninstall the packages since they are not used anymore. {{cmd|# apk del {{pkg|eudev}} {{pkg|udev-init-scripts}}}}

== See also ==
* [[:Category:Device_Manager|Device Managers]]
* [https://wiki.gentoo.org/wiki/Eudev Gentoo wiki eudev]
* [https://wiki.archlinux.org/title/Udev Archwiki udev]
* [[Gamepad]]

[[Category:Device_Manager]]

Device Manager

2025-09-06T17:46:52Z

Sertonix: udev can be made to work without other systemd components

A device manager is a program that manages [https://en.wikipedia.org/wiki/Device_file device files] in the [https://en.wikipedia.org/wiki/Devfs /dev] directory. Permissions and changes in {{path|/dev}} are handled by it.

Alpine linux has several device managers available:
* '''[[mdev]]''' (from {{pkg|busybox}}) is the default.
* '''[[mdevd]]''' is standalone, compatible with mdev, more efficient.
* '''[[eudev]]''' is a complex, full-featured one.

'''udev''' is not available in Alpine Linux, use [[eudev]] instead which includes patches to make to work better without other systemd components.

{{:Include:Setup Device Manager}}

== Do I need a device manager? ==

'''Yes!''' Even for very specific use cases you would most likely just create a custom device manager.

== See also ==

* [[Mdev#libudev_replacement|libudev replacement]]
* [https://wiki.gentoo.org/wiki/Device_file Gentoo Wiki - Device file]

[[Category:Device Manager]]

How to make a custom ISO image with mkimage

2025-08-29T16:14:20Z

Sertonix: Trim required packages

This document explains how to build a custom ISO image using the new mkimage scripts located in [[aports]] directory.

== Prerequisites ==

First make sure we have the needed tools
{{Cmd|apk add abuild alpine-conf syslinux xorriso squashfs-tools grub}}
For efi you should add the following:
{{Cmd|apk add mtools}}

Then create signing keys
{{Cmd|abuild-keygen -a}}

Clone (or update) the [https://gitlab.alpinelinux.org/alpine/aports git repository].
{{Cmd|git clone --depth=1 https://gitlab.alpinelinux.org/alpine/aports.git}}

Make sure your /tmp is large enough. If you have the default 1GB /tmp, then create a local one with:
<pre>mkdir -pv ~/tmp
export TMPDIR=~/tmp</pre>

== Configuration ==

The mkimg scripts are shipped with pre-configured profiles.

The format is '''mkimg.$PROFILENAME.sh'''

In order to have a custom ISO, you should create your own '''mkimg.$PROFILENAME.sh''' script.

This is an example used to make a ZFS module, overlayfs (which enables r/w mode for /lib/modules), a serial console output and some other useful apks to build a simple NAS:

<pre>export PROFILENAME=nas</pre>

<pre>
cat << EOF > ~/aports/scripts/mkimg.$PROFILENAME.sh
profile_$PROFILENAME() {
profile_standard
kernel_cmdline="unionfs_size=512M console=tty0 console=ttyS0,115200"
syslinux_serial="0 115200"
kernel_addons="zfs"
apks="\$apks iscsi-scst zfs-scripts zfs zfs-utils-py
cciss_vol_status lvm2 mdadm mkinitfs mtools nfs-utils
parted rsync sfdisk syslinux util-linux xfsprogs
dosfstools ntfs-3g
"
local _k _a
for _k in \$kernel_flavors; do
apks="\$apks linux-\$_k"
for _a in \$kernel_addons; do
apks="\$apks \$_a-\$_k"
done
done
apks="\$apks linux-firmware"
}
EOF
</pre>

== Making packages available on boot ==

A package may be made available in the live system by defining the generation of an apkovl which contains a corresponding /etc/apk/world file, and adding that overlay definition to the mkimg-profile, e.g. with `apkovl="genapkovl-mkimgoverlay.sh"`

Note that to *use* your added apks, you have to install them, with {{ic|apk add}}.

The definition may be done as in the [https://github.com/alpinelinux/aports/blob/master/scripts/genapkovl-dhcp.sh genapkovl-dhcp.sh] example.
Copy the relevant parts (including the rc_add lines) into a `genapkovl-mkimgoverlay.sh` file and add the package(s) that should be installed in the live system on separate lines in the file contents for /etc/apk/world.

{{Cmd|cp ~/aports/scripts/genapkovl-dhcp.sh ~/aports/scripts/genapkovl-mkimgoverlay.sh}}

Edit the file to add:
<pre>
...
mkdir -p "$tmp"/etc/apk
makefile root:root 0644 "$tmp"/etc/apk/world <<EOF
alpine-base
<apk1-service>
<apk2-service>
EOF

...
rc_add <apk1-service> boot
rc_add <apk2-service> boot
...
</pre>

in the relevant locations.

Then edit the profile build script above and add:
<pre>
apkovl="aports/scripts/genapkovl-mkimgoverlay.sh"
</pre>

immediately after the last apks= line.

== Create the ISO ==

{{Cmd|mkimage.sh [--tag RELEASE] [--outdir OUTDIR] [--workdir WORKDIR]
[--arch ARCH] [--profile PROFILE] [--hostkeys] [--simulate]
[--repository REPO] [--extra-repository REPO] [--yaml FILE]
mkimage.sh --help

options:
--arch Specify which architecture images to build
(default: x86_64)
--hostkeys Copy system apk signing keys to created images
--outdir Specify directory for the created images
--profile Specify which profiles to build
--repository Package repository to use for the image create
--extra-repository Add repository to search packages from
--simulate Don't execute commands
--tag Build images for tag RELEASE
--workdir Specify temporary working directory (cache)
--yaml

known profiles: ali rpi uboot base minirootfs standard vanilla extended virt xen}}

{{Tip| You can use the --repository option multiple times, which is very useful when mixing local and official repositories. The --extra-repository option is there only for backward-compatibility.}}

Then create the actual ISO.
In this example we will use the edge version x86_64:
{{Cmd|sh aports/scripts/mkimage.sh --tag edge \
--outdir ~/iso \
--arch x86_64 \
--repository <nowiki>https://dl-cdn.alpinelinux.org/alpine/edge/main</nowiki> \
--profile $PROFILENAME
}}

'''Notes:'''

* If you want to make a customized installer, you need to create <code>.default_boot_services</code> which will cause <code>mkinitfs</code> to create the defaults for the live image.

* Several parts of this doc can be automated with a script, like the repository/arch/outdir settings.
Those steps are left to you and your imagination :)

== Testing your ISO image ==

[[QEMU#Live_mode|QEMU]] is useful for a quick test of your newly created ISO image.
This ISO build process has been tested to work and generate an ISO with auto-installed APKs as of Nov 20, 2023 with Alpine edge.

== See also ==

* [[How to make a custom ISO image]]

[[Category:Package Manager]]
[[Category:ISO]]

How to make a custom ISO image with mkimage

2025-08-29T16:08:39Z

Sertonix: The key doesn't need to be in /etc/apk/keys (when not using --hostkeys) anymore

This document explains how to build a custom ISO image using the new mkimage scripts located in [[aports]] directory.

== Prerequisites ==

First make sure we have the needed tools
{{Cmd|apk add alpine-sdk alpine-conf syslinux xorriso squashfs-tools grub}}
For efi you should add the following:
{{Cmd|apk add mtools dosfstools}}

Then create signing keys
{{Cmd|abuild-keygen -a}}

Clone (or update) the [https://gitlab.alpinelinux.org/alpine/aports git repository].
{{Cmd|git clone --depth=1 https://gitlab.alpinelinux.org/alpine/aports.git}}

Make sure your /tmp is large enough. If you have the default 1GB /tmp, then create a local one with:
<pre>mkdir -pv ~/tmp
export TMPDIR=~/tmp</pre>

== Configuration ==

The mkimg scripts are shipped with pre-configured profiles.

The format is '''mkimg.$PROFILENAME.sh'''

In order to have a custom ISO, you should create your own '''mkimg.$PROFILENAME.sh''' script.

This is an example used to make a ZFS module, overlayfs (which enables r/w mode for /lib/modules), a serial console output and some other useful apks to build a simple NAS:

<pre>export PROFILENAME=nas</pre>

<pre>
cat << EOF > ~/aports/scripts/mkimg.$PROFILENAME.sh
profile_$PROFILENAME() {
profile_standard
kernel_cmdline="unionfs_size=512M console=tty0 console=ttyS0,115200"
syslinux_serial="0 115200"
kernel_addons="zfs"
apks="\$apks iscsi-scst zfs-scripts zfs zfs-utils-py
cciss_vol_status lvm2 mdadm mkinitfs mtools nfs-utils
parted rsync sfdisk syslinux util-linux xfsprogs
dosfstools ntfs-3g
"
local _k _a
for _k in \$kernel_flavors; do
apks="\$apks linux-\$_k"
for _a in \$kernel_addons; do
apks="\$apks \$_a-\$_k"
done
done
apks="\$apks linux-firmware"
}
EOF
</pre>

== Making packages available on boot ==

A package may be made available in the live system by defining the generation of an apkovl which contains a corresponding /etc/apk/world file, and adding that overlay definition to the mkimg-profile, e.g. with `apkovl="genapkovl-mkimgoverlay.sh"`

Note that to *use* your added apks, you have to install them, with {{ic|apk add}}.

The definition may be done as in the [https://github.com/alpinelinux/aports/blob/master/scripts/genapkovl-dhcp.sh genapkovl-dhcp.sh] example.
Copy the relevant parts (including the rc_add lines) into a `genapkovl-mkimgoverlay.sh` file and add the package(s) that should be installed in the live system on separate lines in the file contents for /etc/apk/world.

{{Cmd|cp ~/aports/scripts/genapkovl-dhcp.sh ~/aports/scripts/genapkovl-mkimgoverlay.sh}}

Edit the file to add:
<pre>
...
mkdir -p "$tmp"/etc/apk
makefile root:root 0644 "$tmp"/etc/apk/world <<EOF
alpine-base
<apk1-service>
<apk2-service>
EOF

...
rc_add <apk1-service> boot
rc_add <apk2-service> boot
...
</pre>

in the relevant locations.

Then edit the profile build script above and add:
<pre>
apkovl="aports/scripts/genapkovl-mkimgoverlay.sh"
</pre>

immediately after the last apks= line.

== Create the ISO ==

{{Cmd|mkimage.sh [--tag RELEASE] [--outdir OUTDIR] [--workdir WORKDIR]
[--arch ARCH] [--profile PROFILE] [--hostkeys] [--simulate]
[--repository REPO] [--extra-repository REPO] [--yaml FILE]
mkimage.sh --help

options:
--arch Specify which architecture images to build
(default: x86_64)
--hostkeys Copy system apk signing keys to created images
--outdir Specify directory for the created images
--profile Specify which profiles to build
--repository Package repository to use for the image create
--extra-repository Add repository to search packages from
--simulate Don't execute commands
--tag Build images for tag RELEASE
--workdir Specify temporary working directory (cache)
--yaml

known profiles: ali rpi uboot base minirootfs standard vanilla extended virt xen}}

{{Tip| You can use the --repository option multiple times, which is very useful when mixing local and official repositories. The --extra-repository option is there only for backward-compatibility.}}

Then create the actual ISO.
In this example we will use the edge version x86_64:
{{Cmd|sh aports/scripts/mkimage.sh --tag edge \
--outdir ~/iso \
--arch x86_64 \
--repository <nowiki>https://dl-cdn.alpinelinux.org/alpine/edge/main</nowiki> \
--profile $PROFILENAME
}}

'''Notes:'''

* If you want to make a customized installer, you need to create <code>.default_boot_services</code> which will cause <code>mkinitfs</code> to create the defaults for the live image.

* Several parts of this doc can be automated with a script, like the repository/arch/outdir settings.
Those steps are left to you and your imagination :)

== Testing your ISO image ==

[[QEMU#Live_mode|QEMU]] is useful for a quick test of your newly created ISO image.
This ISO build process has been tested to work and generate an ISO with auto-installed APKs as of Nov 20, 2023 with Alpine edge.

== See also ==

* [[How to make a custom ISO image]]

[[Category:Package Manager]]
[[Category:ISO]]

How to make a custom ISO image with mkimage

2025-08-29T15:57:45Z

Sertonix: mkimage creates outdir automatically

This document explains how to build a custom ISO image using the new mkimage scripts located in [[aports]] directory.

== Prerequisites ==

First make sure we have the needed tools
{{Cmd|apk add alpine-sdk alpine-conf syslinux xorriso squashfs-tools grub}}
For efi you should add the following:
{{Cmd|apk add mtools dosfstools}}

Then create signing keys (-i installs them in /etc/apk/keys which is required for later)
{{Cmd|abuild-keygen -i -a}}

{{Tip| Make sure your public keys are placed in /etc/apk/keys/ (example: build-xxxxxxxx.rsa.pub)}}
{{Cmd|ls /etc/apk/keys/}}

Clone (or update) the [https://gitlab.alpinelinux.org/alpine/aports git repository].
{{Cmd|git clone --depth=1 https://gitlab.alpinelinux.org/alpine/aports.git}}

Make sure your /tmp is large enough. If you have the default 1GB /tmp, then create a local one with:
<pre>mkdir -pv ~/tmp
export TMPDIR=~/tmp</pre>

== Configuration ==

The mkimg scripts are shipped with pre-configured profiles.

The format is '''mkimg.$PROFILENAME.sh'''

In order to have a custom ISO, you should create your own '''mkimg.$PROFILENAME.sh''' script.

This is an example used to make a ZFS module, overlayfs (which enables r/w mode for /lib/modules), a serial console output and some other useful apks to build a simple NAS:

<pre>export PROFILENAME=nas</pre>

<pre>
cat << EOF > ~/aports/scripts/mkimg.$PROFILENAME.sh
profile_$PROFILENAME() {
profile_standard
kernel_cmdline="unionfs_size=512M console=tty0 console=ttyS0,115200"
syslinux_serial="0 115200"
kernel_addons="zfs"
apks="\$apks iscsi-scst zfs-scripts zfs zfs-utils-py
cciss_vol_status lvm2 mdadm mkinitfs mtools nfs-utils
parted rsync sfdisk syslinux util-linux xfsprogs
dosfstools ntfs-3g
"
local _k _a
for _k in \$kernel_flavors; do
apks="\$apks linux-\$_k"
for _a in \$kernel_addons; do
apks="\$apks \$_a-\$_k"
done
done
apks="\$apks linux-firmware"
}
EOF
</pre>

== Making packages available on boot ==

A package may be made available in the live system by defining the generation of an apkovl which contains a corresponding /etc/apk/world file, and adding that overlay definition to the mkimg-profile, e.g. with `apkovl="genapkovl-mkimgoverlay.sh"`

Note that to *use* your added apks, you have to install them, with {{ic|apk add}}.

The definition may be done as in the [https://github.com/alpinelinux/aports/blob/master/scripts/genapkovl-dhcp.sh genapkovl-dhcp.sh] example.
Copy the relevant parts (including the rc_add lines) into a `genapkovl-mkimgoverlay.sh` file and add the package(s) that should be installed in the live system on separate lines in the file contents for /etc/apk/world.

{{Cmd|cp ~/aports/scripts/genapkovl-dhcp.sh ~/aports/scripts/genapkovl-mkimgoverlay.sh}}

Edit the file to add:
<pre>
...
mkdir -p "$tmp"/etc/apk
makefile root:root 0644 "$tmp"/etc/apk/world <<EOF
alpine-base
<apk1-service>
<apk2-service>
EOF

...
rc_add <apk1-service> boot
rc_add <apk2-service> boot
...
</pre>

in the relevant locations.

Then edit the profile build script above and add:
<pre>
apkovl="aports/scripts/genapkovl-mkimgoverlay.sh"
</pre>

immediately after the last apks= line.

== Create the ISO ==

{{Cmd|mkimage.sh [--tag RELEASE] [--outdir OUTDIR] [--workdir WORKDIR]
[--arch ARCH] [--profile PROFILE] [--hostkeys] [--simulate]
[--repository REPO] [--extra-repository REPO] [--yaml FILE]
mkimage.sh --help

options:
--arch Specify which architecture images to build
(default: x86_64)
--hostkeys Copy system apk signing keys to created images
--outdir Specify directory for the created images
--profile Specify which profiles to build
--repository Package repository to use for the image create
--extra-repository Add repository to search packages from
--simulate Don't execute commands
--tag Build images for tag RELEASE
--workdir Specify temporary working directory (cache)
--yaml

known profiles: ali rpi uboot base minirootfs standard vanilla extended virt xen}}

{{Tip| You can use the --repository option multiple times, which is very useful when mixing local and official repositories. The --extra-repository option is there only for backward-compatibility.}}

Then create the actual ISO.
In this example we will use the edge version x86_64:
{{Cmd|sh aports/scripts/mkimage.sh --tag edge \
--outdir ~/iso \
--arch x86_64 \
--repository <nowiki>https://dl-cdn.alpinelinux.org/alpine/edge/main</nowiki> \
--profile $PROFILENAME
}}

'''Notes:'''

* If you want to make a customized installer, you need to create <code>.default_boot_services</code> which will cause <code>mkinitfs</code> to create the defaults for the live image.

* Several parts of this doc can be automated with a script, like the repository/arch/outdir settings.
Those steps are left to you and your imagination :)

== Testing your ISO image ==

[[QEMU#Live_mode|QEMU]] is useful for a quick test of your newly created ISO image.
This ISO build process has been tested to work and generate an ISO with auto-installed APKs as of Nov 20, 2023 with Alpine edge.

== See also ==

* [[How to make a custom ISO image]]

[[Category:Package Manager]]
[[Category:ISO]]

How to make a custom ISO image with mkimage

2025-08-29T15:56:40Z

Sertonix: mkimg.*.sh don't need to be marked as executable

This document explains how to build a custom ISO image using the new mkimage scripts located in [[aports]] directory.

== Prerequisites ==

First make sure we have the needed tools
{{Cmd|apk add alpine-sdk alpine-conf syslinux xorriso squashfs-tools grub}}
For efi you should add the following:
{{Cmd|apk add mtools dosfstools}}

Then create signing keys (-i installs them in /etc/apk/keys which is required for later)
{{Cmd|abuild-keygen -i -a}}

{{Tip| Make sure your public keys are placed in /etc/apk/keys/ (example: build-xxxxxxxx.rsa.pub)}}
{{Cmd|ls /etc/apk/keys/}}

Clone (or update) the [https://gitlab.alpinelinux.org/alpine/aports git repository].
{{Cmd|git clone --depth=1 https://gitlab.alpinelinux.org/alpine/aports.git}}

Make sure your /tmp is large enough. If you have the default 1GB /tmp, then create a local one with:
<pre>mkdir -pv ~/tmp
export TMPDIR=~/tmp</pre>

== Configuration ==

The mkimg scripts are shipped with pre-configured profiles.

The format is '''mkimg.$PROFILENAME.sh'''

In order to have a custom ISO, you should create your own '''mkimg.$PROFILENAME.sh''' script.

This is an example used to make a ZFS module, overlayfs (which enables r/w mode for /lib/modules), a serial console output and some other useful apks to build a simple NAS:

<pre>export PROFILENAME=nas</pre>

<pre>
cat << EOF > ~/aports/scripts/mkimg.$PROFILENAME.sh
profile_$PROFILENAME() {
profile_standard
kernel_cmdline="unionfs_size=512M console=tty0 console=ttyS0,115200"
syslinux_serial="0 115200"
kernel_addons="zfs"
apks="\$apks iscsi-scst zfs-scripts zfs zfs-utils-py
cciss_vol_status lvm2 mdadm mkinitfs mtools nfs-utils
parted rsync sfdisk syslinux util-linux xfsprogs
dosfstools ntfs-3g
"
local _k _a
for _k in \$kernel_flavors; do
apks="\$apks linux-\$_k"
for _a in \$kernel_addons; do
apks="\$apks \$_a-\$_k"
done
done
apks="\$apks linux-firmware"
}
EOF
</pre>

== Making packages available on boot ==

A package may be made available in the live system by defining the generation of an apkovl which contains a corresponding /etc/apk/world file, and adding that overlay definition to the mkimg-profile, e.g. with `apkovl="genapkovl-mkimgoverlay.sh"`

Note that to *use* your added apks, you have to install them, with {{ic|apk add}}.

The definition may be done as in the [https://github.com/alpinelinux/aports/blob/master/scripts/genapkovl-dhcp.sh genapkovl-dhcp.sh] example.
Copy the relevant parts (including the rc_add lines) into a `genapkovl-mkimgoverlay.sh` file and add the package(s) that should be installed in the live system on separate lines in the file contents for /etc/apk/world.

{{Cmd|cp ~/aports/scripts/genapkovl-dhcp.sh ~/aports/scripts/genapkovl-mkimgoverlay.sh}}

Edit the file to add:
<pre>
...
mkdir -p "$tmp"/etc/apk
makefile root:root 0644 "$tmp"/etc/apk/world <<EOF
alpine-base
<apk1-service>
<apk2-service>
EOF

...
rc_add <apk1-service> boot
rc_add <apk2-service> boot
...
</pre>

in the relevant locations.

Then edit the profile build script above and add:
<pre>
apkovl="aports/scripts/genapkovl-mkimgoverlay.sh"
</pre>

immediately after the last apks= line.

== Create the ISO ==

{{Cmd|mkimage.sh [--tag RELEASE] [--outdir OUTDIR] [--workdir WORKDIR]
[--arch ARCH] [--profile PROFILE] [--hostkeys] [--simulate]
[--repository REPO] [--extra-repository REPO] [--yaml FILE]
mkimage.sh --help

options:
--arch Specify which architecture images to build
(default: x86_64)
--hostkeys Copy system apk signing keys to created images
--outdir Specify directory for the created images
--profile Specify which profiles to build
--repository Package repository to use for the image create
--extra-repository Add repository to search packages from
--simulate Don't execute commands
--tag Build images for tag RELEASE
--workdir Specify temporary working directory (cache)
--yaml

known profiles: ali rpi uboot base minirootfs standard vanilla extended virt xen}}

{{Tip| You can use the --repository option multiple times, which is very useful when mixing local and official repositories. The --extra-repository option is there only for backward-compatibility.}}

Create an iso directory in your home dir:

{{Cmd|mkdir -p ~/iso}}

Then create the actual ISO.
In this example we will use the edge version x86_64:
{{Cmd|sh aports/scripts/mkimage.sh --tag edge \
--outdir ~/iso \
--arch x86_64 \
--repository <nowiki>https://dl-cdn.alpinelinux.org/alpine/edge/main</nowiki> \
--profile $PROFILENAME
}}

'''Notes:'''

* If you want to make a customized installer, you need to create <code>.default_boot_services</code> which will cause <code>mkinitfs</code> to create the defaults for the live image.

* Several parts of this doc can be automated with a script, like the repository/arch/outdir settings.
Those steps are left to you and your imagination :)

== Testing your ISO image ==

[[QEMU#Live_mode|QEMU]] is useful for a quick test of your newly created ISO image.
This ISO build process has been tested to work and generate an ISO with auto-installed APKs as of Nov 20, 2023 with Alpine edge.

== See also ==

* [[How to make a custom ISO image]]

[[Category:Package Manager]]
[[Category:ISO]]

How to make a custom ISO image with mkimage

2025-08-29T15:48:54Z

Sertonix: remove 'apk update' since mkimage uses it's own temporary apk cache

This document explains how to build a custom ISO image using the new mkimage scripts located in [[aports]] directory.

== Prerequisites ==

First make sure we have the needed tools
{{Cmd|apk add alpine-sdk alpine-conf syslinux xorriso squashfs-tools grub}}
For efi you should add the following:
{{Cmd|apk add mtools dosfstools}}

Then create signing keys (-i installs them in /etc/apk/keys which is required for later)
{{Cmd|abuild-keygen -i -a}}

{{Tip| Make sure your public keys are placed in /etc/apk/keys/ (example: build-xxxxxxxx.rsa.pub)}}
{{Cmd|ls /etc/apk/keys/}}

Clone (or update) the [https://gitlab.alpinelinux.org/alpine/aports git repository].
{{Cmd|git clone --depth=1 https://gitlab.alpinelinux.org/alpine/aports.git}}

Make sure your /tmp is large enough. If you have the default 1GB /tmp, then create a local one with:
<pre>mkdir -pv ~/tmp
export TMPDIR=~/tmp</pre>

== Configuration ==

The mkimg scripts are shipped with pre-configured profiles.

The format is '''mkimg.$PROFILENAME.sh'''

In order to have a custom ISO, you should create your own '''mkimg.$PROFILENAME.sh''' script.

This is an example used to make a ZFS module, overlayfs (which enables r/w mode for /lib/modules), a serial console output and some other useful apks to build a simple NAS:

<pre>export PROFILENAME=nas</pre>

<pre>
cat << EOF > ~/aports/scripts/mkimg.$PROFILENAME.sh
profile_$PROFILENAME() {
profile_standard
kernel_cmdline="unionfs_size=512M console=tty0 console=ttyS0,115200"
syslinux_serial="0 115200"
kernel_addons="zfs"
apks="\$apks iscsi-scst zfs-scripts zfs zfs-utils-py
cciss_vol_status lvm2 mdadm mkinitfs mtools nfs-utils
parted rsync sfdisk syslinux util-linux xfsprogs
dosfstools ntfs-3g
"
local _k _a
for _k in \$kernel_flavors; do
apks="\$apks linux-\$_k"
for _a in \$kernel_addons; do
apks="\$apks \$_a-\$_k"
done
done
apks="\$apks linux-firmware"
}
EOF
</pre>

Set the script as executable:
{{Cmd|chmod +x ~/aports/scripts/mkimg.$PROFILENAME.sh}}

== Making packages available on boot ==

A package may be made available in the live system by defining the generation of an apkovl which contains a corresponding /etc/apk/world file, and adding that overlay definition to the mkimg-profile, e.g. with `apkovl="genapkovl-mkimgoverlay.sh"`

Note that to *use* your added apks, you have to install them, with {{ic|apk add}}.

The definition may be done as in the [https://github.com/alpinelinux/aports/blob/master/scripts/genapkovl-dhcp.sh genapkovl-dhcp.sh] example.
Copy the relevant parts (including the rc_add lines) into a `genapkovl-mkimgoverlay.sh` file and add the package(s) that should be installed in the live system on separate lines in the file contents for /etc/apk/world.

{{Cmd|cp ~/aports/scripts/genapkovl-dhcp.sh ~/aports/scripts/genapkovl-mkimgoverlay.sh}}

Edit the file to add:
<pre>
...
mkdir -p "$tmp"/etc/apk
makefile root:root 0644 "$tmp"/etc/apk/world <<EOF
alpine-base
<apk1-service>
<apk2-service>
EOF

...
rc_add <apk1-service> boot
rc_add <apk2-service> boot
...
</pre>

in the relevant locations.

Then edit the profile build script above and add:
<pre>
apkovl="aports/scripts/genapkovl-mkimgoverlay.sh"
</pre>

immediately after the last apks= line.

== Create the ISO ==

{{Cmd|mkimage.sh [--tag RELEASE] [--outdir OUTDIR] [--workdir WORKDIR]
[--arch ARCH] [--profile PROFILE] [--hostkeys] [--simulate]
[--repository REPO] [--extra-repository REPO] [--yaml FILE]
mkimage.sh --help

options:
--arch Specify which architecture images to build
(default: x86_64)
--hostkeys Copy system apk signing keys to created images
--outdir Specify directory for the created images
--profile Specify which profiles to build
--repository Package repository to use for the image create
--extra-repository Add repository to search packages from
--simulate Don't execute commands
--tag Build images for tag RELEASE
--workdir Specify temporary working directory (cache)
--yaml

known profiles: ali rpi uboot base minirootfs standard vanilla extended virt xen}}

{{Tip| You can use the --repository option multiple times, which is very useful when mixing local and official repositories. The --extra-repository option is there only for backward-compatibility.}}

Create an iso directory in your home dir:

{{Cmd|mkdir -p ~/iso}}

Then create the actual ISO.
In this example we will use the edge version x86_64:
{{Cmd|sh aports/scripts/mkimage.sh --tag edge \
--outdir ~/iso \
--arch x86_64 \
--repository <nowiki>https://dl-cdn.alpinelinux.org/alpine/edge/main</nowiki> \
--profile $PROFILENAME
}}

'''Notes:'''

* If you want to make a customized installer, you need to create <code>.default_boot_services</code> which will cause <code>mkinitfs</code> to create the defaults for the live image.

* Several parts of this doc can be automated with a script, like the repository/arch/outdir settings.
Those steps are left to you and your imagination :)

== Testing your ISO image ==

[[QEMU#Live_mode|QEMU]] is useful for a quick test of your newly created ISO image.
This ISO build process has been tested to work and generate an ISO with auto-installed APKs as of Nov 20, 2023 with Alpine edge.

== See also ==

* [[How to make a custom ISO image]]

[[Category:Package Manager]]
[[Category:ISO]]

How to make a custom ISO image with mkimage

2025-08-29T15:47:21Z

Sertonix: remove mention of build user since no root privileges are required by mkimage

This document explains how to build a custom ISO image using the new mkimage scripts located in [[aports]] directory.

== Prerequisites ==

First make sure we have the needed tools
{{Cmd|apk add alpine-sdk alpine-conf syslinux xorriso squashfs-tools grub}}
For efi you should add the following:
{{Cmd|apk add mtools dosfstools}}

Then create signing keys (-i installs them in /etc/apk/keys which is required for later)
{{Cmd|abuild-keygen -i -a}}

{{Tip| Make sure your public keys are placed in /etc/apk/keys/ (example: build-xxxxxxxx.rsa.pub)}}
{{Cmd|ls /etc/apk/keys/}}

Clone (or update) the [https://gitlab.alpinelinux.org/alpine/aports git repository].
{{Cmd|git clone --depth=1 https://gitlab.alpinelinux.org/alpine/aports.git}}

Make sure the apk index is up to date (so apk can find the packages):
{{Cmd|doas apk update}}

Make sure your /tmp is large enough. If you have the default 1GB /tmp, then create a local one with:
<pre>mkdir -pv ~/tmp
export TMPDIR=~/tmp</pre>

== Configuration ==

The mkimg scripts are shipped with pre-configured profiles.

The format is '''mkimg.$PROFILENAME.sh'''

In order to have a custom ISO, you should create your own '''mkimg.$PROFILENAME.sh''' script.

This is an example used to make a ZFS module, overlayfs (which enables r/w mode for /lib/modules), a serial console output and some other useful apks to build a simple NAS:

<pre>export PROFILENAME=nas</pre>

<pre>
cat << EOF > ~/aports/scripts/mkimg.$PROFILENAME.sh
profile_$PROFILENAME() {
profile_standard
kernel_cmdline="unionfs_size=512M console=tty0 console=ttyS0,115200"
syslinux_serial="0 115200"
kernel_addons="zfs"
apks="\$apks iscsi-scst zfs-scripts zfs zfs-utils-py
cciss_vol_status lvm2 mdadm mkinitfs mtools nfs-utils
parted rsync sfdisk syslinux util-linux xfsprogs
dosfstools ntfs-3g
"
local _k _a
for _k in \$kernel_flavors; do
apks="\$apks linux-\$_k"
for _a in \$kernel_addons; do
apks="\$apks \$_a-\$_k"
done
done
apks="\$apks linux-firmware"
}
EOF
</pre>

Set the script as executable:
{{Cmd|chmod +x ~/aports/scripts/mkimg.$PROFILENAME.sh}}

== Making packages available on boot ==

A package may be made available in the live system by defining the generation of an apkovl which contains a corresponding /etc/apk/world file, and adding that overlay definition to the mkimg-profile, e.g. with `apkovl="genapkovl-mkimgoverlay.sh"`

Note that to *use* your added apks, you have to install them, with {{ic|apk add}}.

The definition may be done as in the [https://github.com/alpinelinux/aports/blob/master/scripts/genapkovl-dhcp.sh genapkovl-dhcp.sh] example.
Copy the relevant parts (including the rc_add lines) into a `genapkovl-mkimgoverlay.sh` file and add the package(s) that should be installed in the live system on separate lines in the file contents for /etc/apk/world.

{{Cmd|cp ~/aports/scripts/genapkovl-dhcp.sh ~/aports/scripts/genapkovl-mkimgoverlay.sh}}

Edit the file to add:
<pre>
...
mkdir -p "$tmp"/etc/apk
makefile root:root 0644 "$tmp"/etc/apk/world <<EOF
alpine-base
<apk1-service>
<apk2-service>
EOF

...
rc_add <apk1-service> boot
rc_add <apk2-service> boot
...
</pre>

in the relevant locations.

Then edit the profile build script above and add:
<pre>
apkovl="aports/scripts/genapkovl-mkimgoverlay.sh"
</pre>

immediately after the last apks= line.

== Create the ISO ==

{{Cmd|mkimage.sh [--tag RELEASE] [--outdir OUTDIR] [--workdir WORKDIR]
[--arch ARCH] [--profile PROFILE] [--hostkeys] [--simulate]
[--repository REPO] [--extra-repository REPO] [--yaml FILE]
mkimage.sh --help

options:
--arch Specify which architecture images to build
(default: x86_64)
--hostkeys Copy system apk signing keys to created images
--outdir Specify directory for the created images
--profile Specify which profiles to build
--repository Package repository to use for the image create
--extra-repository Add repository to search packages from
--simulate Don't execute commands
--tag Build images for tag RELEASE
--workdir Specify temporary working directory (cache)
--yaml

known profiles: ali rpi uboot base minirootfs standard vanilla extended virt xen}}

{{Tip| You can use the --repository option multiple times, which is very useful when mixing local and official repositories. The --extra-repository option is there only for backward-compatibility.}}

Create an iso directory in your home dir:

{{Cmd|mkdir -p ~/iso}}

Then create the actual ISO.
In this example we will use the edge version x86_64:
{{Cmd|sh aports/scripts/mkimage.sh --tag edge \
--outdir ~/iso \
--arch x86_64 \
--repository <nowiki>https://dl-cdn.alpinelinux.org/alpine/edge/main</nowiki> \
--profile $PROFILENAME
}}

'''Notes:'''

* If you want to make a customized installer, you need to create <code>.default_boot_services</code> which will cause <code>mkinitfs</code> to create the defaults for the live image.

* Several parts of this doc can be automated with a script, like the repository/arch/outdir settings.
Those steps are left to you and your imagination :)

== Testing your ISO image ==

[[QEMU#Live_mode|QEMU]] is useful for a quick test of your newly created ISO image.
This ISO build process has been tested to work and generate an ISO with auto-installed APKs as of Nov 20, 2023 with Alpine edge.

== See also ==

* [[How to make a custom ISO image]]

[[Category:Package Manager]]
[[Category:ISO]]

How to make a custom ISO image with mkimage

2025-08-29T15:43:24Z

Sertonix: remove grub-efi mention: https://gitlab.alpinelinux.org/alpine/aports/-/commit/5147450891cc9db4c2615b7c0ac4b978bd3797c8

This document explains how to build a custom ISO image using the new mkimage scripts located in [[aports]] directory.

== Prerequisites ==

First make sure we have the needed tools
{{Cmd|apk add alpine-sdk alpine-conf syslinux xorriso squashfs-tools grub doas}}
For efi you should add the following:
{{Cmd|apk add mtools dosfstools}}

Create a user (e.g. build) and add them to the abuild group:
{{Cmd|adduser build -G abuild}}

Give the user root-like permissions:
{{Cmd|vi /etc/doas.d/doas.conf}}
<pre>
permit persist :abuild
</pre>

Change to the build user:
{{Cmd|su - build}}

Then create signing keys (-i installs them in /etc/apk/keys which is required for later)
{{Cmd|abuild-keygen -i -a}}

{{Tip| Make sure your public keys are placed in /etc/apk/keys/ (example: build-xxxxxxxx.rsa.pub)}}
{{Cmd|ls /etc/apk/keys/}}

Clone (or update) the [https://gitlab.alpinelinux.org/alpine/aports git repository].
{{Cmd|git clone --depth=1 https://gitlab.alpinelinux.org/alpine/aports.git}}

Make sure the apk index is up to date (so apk can find the packages):
{{Cmd|doas apk update}}

Make sure your /tmp is large enough. If you have the default 1GB /tmp, then create a local one with:
<pre>mkdir -pv ~/tmp
export TMPDIR=~/tmp</pre>

== Configuration ==

The mkimg scripts are shipped with pre-configured profiles.

The format is '''mkimg.$PROFILENAME.sh'''

In order to have a custom ISO, you should create your own '''mkimg.$PROFILENAME.sh''' script.

This is an example used to make a ZFS module, overlayfs (which enables r/w mode for /lib/modules), a serial console output and some other useful apks to build a simple NAS:

<pre>export PROFILENAME=nas</pre>

<pre>
cat << EOF > ~/aports/scripts/mkimg.$PROFILENAME.sh
profile_$PROFILENAME() {
profile_standard
kernel_cmdline="unionfs_size=512M console=tty0 console=ttyS0,115200"
syslinux_serial="0 115200"
kernel_addons="zfs"
apks="\$apks iscsi-scst zfs-scripts zfs zfs-utils-py
cciss_vol_status lvm2 mdadm mkinitfs mtools nfs-utils
parted rsync sfdisk syslinux util-linux xfsprogs
dosfstools ntfs-3g
"
local _k _a
for _k in \$kernel_flavors; do
apks="\$apks linux-\$_k"
for _a in \$kernel_addons; do
apks="\$apks \$_a-\$_k"
done
done
apks="\$apks linux-firmware"
}
EOF
</pre>

Set the script as executable:
{{Cmd|chmod +x ~/aports/scripts/mkimg.$PROFILENAME.sh}}

== Making packages available on boot ==

A package may be made available in the live system by defining the generation of an apkovl which contains a corresponding /etc/apk/world file, and adding that overlay definition to the mkimg-profile, e.g. with `apkovl="genapkovl-mkimgoverlay.sh"`

Note that to *use* your added apks, you have to install them, with {{ic|apk add}}.

The definition may be done as in the [https://github.com/alpinelinux/aports/blob/master/scripts/genapkovl-dhcp.sh genapkovl-dhcp.sh] example.
Copy the relevant parts (including the rc_add lines) into a `genapkovl-mkimgoverlay.sh` file and add the package(s) that should be installed in the live system on separate lines in the file contents for /etc/apk/world.

{{Cmd|cp ~/aports/scripts/genapkovl-dhcp.sh ~/aports/scripts/genapkovl-mkimgoverlay.sh}}

Edit the file to add:
<pre>
...
mkdir -p "$tmp"/etc/apk
makefile root:root 0644 "$tmp"/etc/apk/world <<EOF
alpine-base
<apk1-service>
<apk2-service>
EOF

...
rc_add <apk1-service> boot
rc_add <apk2-service> boot
...
</pre>

in the relevant locations.

Then edit the profile build script above and add:
<pre>
apkovl="aports/scripts/genapkovl-mkimgoverlay.sh"
</pre>

immediately after the last apks= line.

== Create the ISO ==

{{Cmd|mkimage.sh [--tag RELEASE] [--outdir OUTDIR] [--workdir WORKDIR]
[--arch ARCH] [--profile PROFILE] [--hostkeys] [--simulate]
[--repository REPO] [--extra-repository REPO] [--yaml FILE]
mkimage.sh --help

options:
--arch Specify which architecture images to build
(default: x86_64)
--hostkeys Copy system apk signing keys to created images
--outdir Specify directory for the created images
--profile Specify which profiles to build
--repository Package repository to use for the image create
--extra-repository Add repository to search packages from
--simulate Don't execute commands
--tag Build images for tag RELEASE
--workdir Specify temporary working directory (cache)
--yaml

known profiles: ali rpi uboot base minirootfs standard vanilla extended virt xen}}

{{Tip| You can use the --repository option multiple times, which is very useful when mixing local and official repositories. The --extra-repository option is there only for backward-compatibility.}}

Create an iso directory in your home dir:

{{Cmd|mkdir -p ~/iso}}

Then create the actual ISO.
In this example we will use the edge version x86_64:
{{Cmd|sh aports/scripts/mkimage.sh --tag edge \
--outdir ~/iso \
--arch x86_64 \
--repository <nowiki>https://dl-cdn.alpinelinux.org/alpine/edge/main</nowiki> \
--profile $PROFILENAME
}}

'''Notes:'''

* If you want to make a customized installer, you need to create <code>.default_boot_services</code> which will cause <code>mkinitfs</code> to create the defaults for the live image.

* Several parts of this doc can be automated with a script, like the repository/arch/outdir settings.
Those steps are left to you and your imagination :)

== Testing your ISO image ==

[[QEMU#Live_mode|QEMU]] is useful for a quick test of your newly created ISO image.
This ISO build process has been tested to work and generate an ISO with auto-installed APKs as of Nov 20, 2023 with Alpine edge.

== See also ==

* [[How to make a custom ISO image]]

[[Category:Package Manager]]
[[Category:ISO]]

Shell management

2025-08-07T12:01:13Z

Sertonix: remove always true condition

The default shell used by Alpine Linux is the [[BusyBox]] variant of the [[BusyBox#Ash_shell|ash]] shell. This page explains how to use the default shell and various ways to change the default shell in Alpine Linux.

== Ash shell ==

Alpine Linux uses [[Busybox]] Ash shell for its default shell. It is a standard POSIX shell derived from Debian Ash variant.

One's ~/.bashrc file (or, alternatively, a different shell alias file) could be considered as a basis, say, for an {{Path|~/.ashrc}} file, reviewing it carefully for syntax/cli variants against that of Ash shell. For non-login, interactive shells refer to [[#Setting alias|Setting alias]] section.

{{Tip|Use {{pkg|checkbashisms}} script to perform basic checks for the presence of bashisms in scripts and help remove them.}}

=== Setting alias ===

For interactive non-login shells, Busybox Ash and other POSIX shells do NOT automatically read a startup file like {{Path|~/.ashrc}}. To ensure that both login and non-login interactive shells work consistently, use '''ENV''' environment variable in {{Path|~/.profile}} to refer {{Path|~/.ashrc}} file.

# Edit the {{Path|~/.profile}} as follows: {{Cat|~/.profile|<nowiki>...
export ENV="$HOME/.ashrc" </nowiki>}}
# Now aliases can be added in the startup file {{Path|~/.ashrc}} as follows: {{Cat|~/.ashrc|<nowiki># ~/.ashrc: interactive shell configuration for BusyBox Ash

# Custom Aliases
alias ls='ls --color=auto'
alias grep='grep --color=auto'

# You may want to put all your additions into a separate file like
# ~/.ash_aliases, instead of adding them here directly.

if [ -f ~/.ash_aliases ]; then
. ~/.ash_aliases
fi</nowiki>}}

== Available shells ==

Most of the popular shells are available in Alpine Linux repositories as can be seen from the below list.
{| class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|-style="background:#333333; color:#ffffff; font-size: 1.2em; text-align:center;"
|width="10%" | Name
|width="36%" | URL
|Remarks
|-
|{{Pkg|bash}}|| https://www.gnu.org/software/bash/bash.html||The GNU Bourne Again shell
|-
|{{Pkg|zsh}} || https://www.zsh.org/||Very advanced and programmable command interpreter
|-
|{{Pkg|fish}} ||https://fishshell.com/||Modern interactive commandline shell
|-
|{{pkg|dash}} ||http://gondor.apana.org.au/~herbert/dash/||Small and fast POSIX-compliant shell
|-
|{{pkg|oksh}} ||https://github.com/ibara/oksh||Portable OpenBSD ksh, based on pdksh
|-
|{{pkg|loksh}} ||https://github.com/dimkr/loksh||A Linux port of OpenBSD's ksh
|-
|{{pkg|yash}} ||https://magicant.github.io/yash||Yet another shell
|-
|{{pkg|tcsh}} ||https://github.com/tcsh-org/tcsh||extended C-shell
|-
|{{pkg|nsh}} ||https://github.com/nuta/nsh||A command-line shell like fish, but POSIX compatible
|-
|{{pkg|elvish}} ||https://elv.sh||Friendly and expressive Unix shell
|-
|{{pkg|nushell}} ||https://www.nushell.sh||A new type of shell
|-
|{{pkg|murex}} ||https://murex.rocks/||Intuitive, typed and content aware shell
|}

To install any of the above shells, say for eg: {{pkg|bash}} shell: {{Cmd|# apk add {{pkg|bash}} {{pkg|bash-completion}}}}

== Change default shell ==

There are various ways to change the default shell in Alpine Linux. You can revert back to [[#ash|ash]] shell at anytime with the same steps.

{{Note|After performing the below step, you need to log out and login again for these changes to take effect.}}

=== By hand ===

Edit {{Path|/etc/passwd}} manually using an editor of your choice. An example line for a user named <code>user</code> is: {{Cat|/etc/passwd|...
user:x:1000:1000:user:/home/user:/bin/ash
...
}}

Change {{Path|/bin/ash}} to point to the path of a shell from {{Path|/etc/shells}}. Take care to not delete/mangle the line, as it would make you unable to log in again. The <code>user</code> should be the user you are changing the default login shell for.

=== Using chsh command ===

To use {{ic|chsh}} command, install the {{pkg|shadow}} package: {{Cmd|# apk add shadow}}
And use chsh: {{Cmd|# chsh username}}
Now enter the path for the shell you want to use (e.g {{Path|/bin/zsh}})
and press {{Key|Enter}} to confirm this change. The shell should exist in {{Path|/etc/shells}}.

== See also ==

* [https://linux.die.net/man/1/dash dash Manual]
* [https://git.busybox.net/busybox/tree/shell/README Ash README]
* [https://git.busybox.net/busybox/tree/shell Ash source code]
* [https://pubs.opengroup.org/onlinepubs/9799919799/ POSIX standard]
* [https://stackoverflow.com/questions/38024160/how-to-get-etc-profile-to-run-automatically-in-alpine-docker/38025686#38025686 stackoverflow on ash shell]

[[Category:Shell]]
[[Category:System Administration]]

User:Sertonix/Freedom of choice

2025-07-22T16:21:10Z

Sertonix: remove suckless tools (they weren't supported anyways)

This is an overview over the different available programms, etc. that can be selected from when using alpine. It is also intended as a reference what should be documented and what could be supported.

== Bootloaders ==
* See: [[Bootloaders]]
* Also: {{Pkg|systemd-boot}}

== Kernel ==
* See: [[Kernels]]

== Libc ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|musl}} || style="background:lime" | Full || Default
|-
| [https://www.gnu.org/software/libc/ glibc] || style="background:red" | None || [[Running glibc programs]]
|-
| without aka static || style="background:orange" | depends on package || Note that this only means no libc at runtime
|}
* See also: [https://gitlab.alpinelinux.org/alpine/tsc/-/issues/17 alpine-glibc]
* See also: [https://wiki.gentoo.org/wiki/Libc Gentoo Wiki]

== Initramfs ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|mkinitfs}} || style="background:lime" | Full || Default
|-
| {{Pkg|dracut}} || style="background:lime" | Full ||
|-
| {{Pkg|booster}} || style="background:lime" | Full ||
|-
| [https://github.com/illiliti/tinyramfs tinyramfs] || style="background:red" | None ||
|-
| without || style="background:red" | None || may require [[custom Kernel]], [https://kisslinux.org/install#021 kisslinux without initramfs]
|}
* See also: [[Initramfs init]]
* See also: [https://wiki.gentoo.org/wiki/Initramfs Gentoo Wiki]

== PID 1 ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| busybox init || style="background:lime" | Full || Default
|-
| {{Pkg|dinit}} || style="background:orange" | In testing || Shutdown commands are prefixed with {{ic|dinit-}}. eg {{ic|dinit-reboot}}
|-
| {{Pkg|s6-linux-init}} || style="background:orange" | Works || Requires manually running {{ic|s6-linux-init-maker}}
|-
| {{Pkg|openrc-init}} || style="background:orange" | Manual setup ||
|-
| {{Pkg|dumb-init}} || style="background:silver" | Needs testing || For containers
|-
| runit-init || style="background:silver" | Needs testing || [https://dev.alpinelinux.org/~clandmeter/other/forum.alpinelinux.org/comment/383.html#comment-383 runit-init starting OpenRC]
|-
| {{Pkg|epoch}} || style="background:silver" | Needs testing ||
|-
| systemd || style="background:red" | None || Supported by postmarketOS
|-
| custom || style="background:lime" | Full || For example in docker containers
|}
* See also: [https://wiki.gentoo.org/wiki/Init_system Gentoo Wiki]
* See also: [https://wiki.archlinux.org/title/Init Archwiki]

== Service Manager ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[OpenRC]] || style="background:lime" | Full || Default
|-
| {{Pkg|dinit}} || style="background:orange" | In testing || {{Pkg|dinit-alpine}} includes service files
|-
| {{Pkg|s6-rc}} || style="background:orange" | Works || Not integrated. For containers there is {{Pkg|s6-overlay}}
|-
| {{Pkg|runit}} || style="background:orange" | As OpenRC service ||
|-
| {{Pkg|daemontools}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|daemontools-encore}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|supervisor}} || style="background:silver" | Needs testing ||
|-
| busybox runit || style="background:red" | None || Not enabled in a busybox package
|-
| systemd || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:lime" | Full || Requires to replace {{Pkg|alpine-base}} with custom set of packages (See {{Issue|71686}})
|}
* See also: [https://wiki.gentoo.org/wiki/Init_system Gentoo Wiki]
* See also: [https://wiki.archlinux.org/title/Init Archwiki]

== System Logs ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[Syslog#busybox_syslog|busybox syslog]] || style="background:lime" | Full || Default
|-
| {{Pkg|rsyslog}} || style="background:lime" | Full ||
|-
| {{Pkg|syslog-ng}} || style="background:lime" | Full ||
|-
| {{pkg|socklog}} || style="background:silver" | Needs testing ||
|-
| [https://skarnet.org/software/s6/s6-socklog.html s6-socklog] from {{pkg|s6}} || style="background:silver" | Needs testing ||
|-
| systemd-journald || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:silver" | Needs testing ||
|}
* See also: [[Syslog]]

== [[Device Manager]] ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[mdev]] || style="background:lime" | Full || Default
|-
| [[mdevd]] || style="background:lime" | Full ||
|-
| [[eudev]] || style="background:lime" | Full ||
|-
| vdev || style="background:red" | None ||
|-
| systemd-udev || style="background:red" | None || Supported by postmarketOS
|}

== Power Managment ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[busybox acpid]] || style="background:lime" | Full || Default
|-
| {{Pkg|acpid}} || style="background:lime" | Full ||
|-
| {{Pkg|elogind}} || style="background:silver" | Needs testing ||
|-
| systemd-logind || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:lime" | Full ||
|}
* See also: [https://wiki.archlinux.org/title/Power_management Archwiki]
* See also: [https://wiki.gentoo.org/wiki/Power_management Gentoo Wiki]

== DHCP Client ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[Udhcpc|busybox udhcpc]] || style="background:lime" | Full || Default
|-
| {{Pkg|dhcpcd}} || style="background:lime" | Full ||
|-
| {{Pkg|dhclient}} || style="background:lime" | Full ||
|-
| without aka static || style="background:lime" | Full ||
|}
* See also: [[Configure Networking]]
* See also: [https://wiki.archlinux.org/title/Network_configuration#DHCP Archwiki]
* See also: [https://wiki.gentoo.org/wiki/Resolv.conf Gentoo Wiki - resolv.conf]

== Wi-Fi ==
* See: [[Wi-Fi]]
* Also supported: {{pkg|eiwd}}

== Seat/Session Managnent ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[elogind]] || style="background:lime" | Full ||
|-
| {{Pkg|seatd}} || style="background:lime" | Full || seats only
|-
| {{Pkg|turnstile}} || style="background:silver" | needs testing || session only
|-
| systemd-logind || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:lime" | Full || Not recommended with graphical enviroment
|}
* [https://wiki.gentoo.org/wiki/Seatd Gentoo Wiki - seatd]
* [https://wiki.gentoo.org/wiki/Elogind Gentoo Wiki - elogind]
* [https://wiki.archlinux.org/title/Init#logind ArchWiki - systemd-logind]
* [https://chimera-linux.org/docs/configuration/seat Chimera Linux docs]

== Login ==

{| class="wikitable"
|-
! Name !! Support !! Supports [[PAM]] !! Notes
|-
| busybox login || style="background:lime" | Full || style="background:red" | No || Default
|-
| {{Pkg|greetd}} || style="background:lime" | Full || style="background:lime" | Yes || requires greeter
|-
| {{Pkg|shadow-login}} || style="background:lime" | Full || style="background:lime" | Yes ||
|-
| {{Pkg|util-linux-login}} || style="background:lime" | Full || style="background:lime" | Yes ||
|-
| systemd-logind || style="background:red" | None || style="background:lime" | Yes || Supported by postmarketOS
|-
| without || style="background:lime" | Full || style="background:red" | No ||
|}
* See also: [https://wiki.gentoo.org/wiki/Login Gentoo Wiki]

== Shell Utils ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|busybox}} || style="background:lime" | Full || Dependency of {{pkg|alpine-base}}
|-
| {{Pkg|busybox-extras}} || style="background:lime" | Full || Some commands that are missing in the main {{Pkg|busybox}} package
|-
| {{Pkg|util-linux}} || style="background:lime" | Full ||
|-
| [[GNU_core_utilities|coreutils]] || style="background:lime" | Full ||
|-
| {{Pkg|s6-portable-utils}} || style="background:lime" | Full ||
|-
| {{Pkg|s6-linux-utils}} || style="background:lime" | Full ||
|-
| {{Pkg|toybox}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|sbase}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|ubase}} || style="background:silver" | Needs testing ||
|-
| without || style="background:red" | None || A lot of implicit dependency
|}
* See also: [https://wiki.archlinux.org/title/Core_utilities Archwiki]

== Shell ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| busybox ash || style="background:lime" | Full || Default
|-
| {{Pkg|bash}} || style="background:lime" | Full ||
|-
| {{Pkg|dash}} || style="background:lime" | Full || When used as /bin/sh this may cause breakage.
|-
| {{Pkg|yash}} || style="background:lime" | Full ||
|-
| busybox hush || style="background:red" | None ||
|-
| without || style="background:red" | None || sometimes implicit dependency
|}
* See also: [[Change default shell]]
* See proposal: [https://gitlab.alpinelinux.org/alpine/tsc/-/issues/39 replace busybox ash with another /bin/sh]
* See also: [https://wiki.archlinux.org/title/Command-line_shell Archwiki]
* See also: [https://wiki.gentoo.org/wiki/Shell Gentoo Wiki]

== SU ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{ic|su}} from {{Pkg|busybox-suid}} || style="background:lime" | Full || default, can't be removed by default ({{issue|11730}})
|-
| {{ic|su}} from {{Pkg|shadow-login}} || style="background:lime" | Full ||
|-
| {{ic|su}} from {{Pkg|util-linux-login}} || style="background:lime" | Full ||
|-
| {{Pkg|sudo}} || style="background:lime" | Full ||
|-
| {{Pkg|doas}} || style="background:lime" | Full || sudo shim using doas: {{Pkg|doas-sudo-shim}}
|-
| [https://skarnet.org/software/s6/s6-sudo.html s6-sudo] || style="background:silver" | Needs testing ||
|-
| without || style="background:lime" | Full ||
|}

== SSL/TLS ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|openssl}} || style="background:lime" | Full || Default
|-
| {{Pkg|libressl}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|bearssl}} || style="background:silver" | Needs testing ||
|}
* See also: [https://gitlab.alpinelinux.org/alpine/tsc/-/issues/28 consider LibreSSL as default OpenSSL provider again]
* See also: [https://wiki.archlinux.org/title/Transport_Layer_Security Archwiki]
* See also: [https://github.com/haproxy/wiki/wiki/SSL-Libraries-Support-Status haproxy SSL Libraries Support Status]

== Cron ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|cronie}} || style="background:lime" | Full ||
|-
| {{Pkg|dcron}} || style="background:lime" | Full ||
|-
| {{Pkg|fcron}} || style="background:lime" | Full ||
|-
| vixie-cron || style="background:red" | None ||
|-
| scron || style="background:red" | None ||
|-
| systemd.timer || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:lime" | Full || {{Pkg|alpine-baselayout}} includes cron specific directories though
|}
* See also: [https://wiki.archlinux.org/title/Cron Archwiki]
* See also: [https://wiki.gentoo.org/wiki/Cron Gentoo Wiki]

== SSH ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[Setting_up_a_SSH_server#OpenSSH|openssh]] || style="background:lime" | Full ||
|-
| [[Setting_up_a_SSH_server#Dropbear|dropbear]] || style="background:lime" | Full || provide {{ic|ssh}} command {{pkg|dropbear-ssh}}
|-
| without || style="background:lime" | Full ||
|}
* See also: [https://wiki.archlinux.org/title/Secure_Shell Archwiki]
* See also: [https://wiki.gentoo.org/wiki/SSH Gentoo Wiki - OpenSSH]
* See also: [https://wiki.gentoo.org/wiki/Dropbear Gentoo Wiki - Dropbear]

== Desktop ==
* See: [[Desktop environments and Window managers]]

== See Also ==
* [[Architecture|Alpine Architecture]]
* [https://gitlab.alpinelinux.org/alpine/tsc/-/issues/55 Future of busybox]

User:Sertonix/Freedom of choice

2025-07-22T16:20:01Z

Sertonix: systemd-boot is now packaged

This is an overview over the different available programms, etc. that can be selected from when using alpine. It is also intended as a reference what should be documented and what could be supported.

== Bootloaders ==
* See: [[Bootloaders]]
* Also: {{Pkg|systemd-boot}}

== Kernel ==
* See: [[Kernels]]

== Libc ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|musl}} || style="background:lime" | Full || Default
|-
| [https://www.gnu.org/software/libc/ glibc] || style="background:red" | None || [[Running glibc programs]]
|-
| without aka static || style="background:orange" | depends on package || Note that this only means no libc at runtime
|}
* See also: [https://gitlab.alpinelinux.org/alpine/tsc/-/issues/17 alpine-glibc]
* See also: [https://wiki.gentoo.org/wiki/Libc Gentoo Wiki]

== Initramfs ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|mkinitfs}} || style="background:lime" | Full || Default
|-
| {{Pkg|dracut}} || style="background:lime" | Full ||
|-
| {{Pkg|booster}} || style="background:lime" | Full ||
|-
| [https://github.com/illiliti/tinyramfs tinyramfs] || style="background:red" | None ||
|-
| without || style="background:red" | None || may require [[custom Kernel]], [https://kisslinux.org/install#021 kisslinux without initramfs]
|}
* See also: [[Initramfs init]]
* See also: [https://wiki.gentoo.org/wiki/Initramfs Gentoo Wiki]

== PID 1 ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| busybox init || style="background:lime" | Full || Default
|-
| {{Pkg|dinit}} || style="background:orange" | In testing || Shutdown commands are prefixed with {{ic|dinit-}}. eg {{ic|dinit-reboot}}
|-
| {{Pkg|s6-linux-init}} || style="background:orange" | Works || Requires manually running {{ic|s6-linux-init-maker}}
|-
| {{Pkg|openrc-init}} || style="background:orange" | Manual setup ||
|-
| {{Pkg|dumb-init}} || style="background:silver" | Needs testing || For containers
|-
| runit-init || style="background:silver" | Needs testing || [https://dev.alpinelinux.org/~clandmeter/other/forum.alpinelinux.org/comment/383.html#comment-383 runit-init starting OpenRC]
|-
| {{Pkg|epoch}} || style="background:silver" | Needs testing ||
|-
| [https://core.suckless.org/sinit/ sinit] || style="background:red" | None ||
|-
| systemd || style="background:red" | None || Supported by postmarketOS
|-
| custom || style="background:lime" | Full || For example in docker containers
|}
* See also: [https://wiki.gentoo.org/wiki/Init_system Gentoo Wiki]
* See also: [https://wiki.archlinux.org/title/Init Archwiki]

== Service Manager ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[OpenRC]] || style="background:lime" | Full || Default
|-
| {{Pkg|dinit}} || style="background:orange" | In testing || {{Pkg|dinit-alpine}} includes service files
|-
| {{Pkg|s6-rc}} || style="background:orange" | Works || Not integrated. For containers there is {{Pkg|s6-overlay}}
|-
| {{Pkg|runit}} || style="background:orange" | As OpenRC service ||
|-
| {{Pkg|daemontools}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|daemontools-encore}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|supervisor}} || style="background:silver" | Needs testing ||
|-
| busybox runit || style="background:red" | None || Not enabled in a busybox package
|-
| [https://core.suckless.org/svc/ svc] || style="background:red" | None ||
|-
| systemd || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:lime" | Full || Requires to replace {{Pkg|alpine-base}} with custom set of packages (See {{Issue|71686}})
|}
* See also: [https://wiki.gentoo.org/wiki/Init_system Gentoo Wiki]
* See also: [https://wiki.archlinux.org/title/Init Archwiki]

== System Logs ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[Syslog#busybox_syslog|busybox syslog]] || style="background:lime" | Full || Default
|-
| {{Pkg|rsyslog}} || style="background:lime" | Full ||
|-
| {{Pkg|syslog-ng}} || style="background:lime" | Full ||
|-
| {{pkg|socklog}} || style="background:silver" | Needs testing ||
|-
| [https://skarnet.org/software/s6/s6-socklog.html s6-socklog] from {{pkg|s6}} || style="background:silver" | Needs testing ||
|-
| systemd-journald || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:silver" | Needs testing ||
|}
* See also: [[Syslog]]

== [[Device Manager]] ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[mdev]] || style="background:lime" | Full || Default
|-
| [[mdevd]] || style="background:lime" | Full ||
|-
| [[eudev]] || style="background:lime" | Full ||
|-
| [https://core.suckless.org/smdev/ smdev] || style="background:red" | None ||
|-
| vdev || style="background:red" | None ||
|-
| systemd-udev || style="background:red" | None || Supported by postmarketOS
|}

== Power Managment ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[busybox acpid]] || style="background:lime" | Full || Default
|-
| {{Pkg|acpid}} || style="background:lime" | Full ||
|-
| {{Pkg|elogind}} || style="background:silver" | Needs testing ||
|-
| systemd-logind || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:lime" | Full ||
|}
* See also: [https://wiki.archlinux.org/title/Power_management Archwiki]
* See also: [https://wiki.gentoo.org/wiki/Power_management Gentoo Wiki]

== DHCP Client ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[Udhcpc|busybox udhcpc]] || style="background:lime" | Full || Default
|-
| {{Pkg|dhcpcd}} || style="background:lime" | Full ||
|-
| {{Pkg|dhclient}} || style="background:lime" | Full ||
|-
| [https://core.suckless.org/sdhcp/ sdhcp] || style="background:red" | None ||
|-
| without aka static || style="background:lime" | Full ||
|}
* See also: [[Configure Networking]]
* See also: [https://wiki.archlinux.org/title/Network_configuration#DHCP Archwiki]
* See also: [https://wiki.gentoo.org/wiki/Resolv.conf Gentoo Wiki - resolv.conf]

== Wi-Fi ==
* See: [[Wi-Fi]]
* Also supported: {{pkg|eiwd}}

== Seat/Session Managnent ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[elogind]] || style="background:lime" | Full ||
|-
| {{Pkg|seatd}} || style="background:lime" | Full || seats only
|-
| {{Pkg|turnstile}} || style="background:silver" | needs testing || session only
|-
| systemd-logind || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:lime" | Full || Not recommended with graphical enviroment
|}
* [https://wiki.gentoo.org/wiki/Seatd Gentoo Wiki - seatd]
* [https://wiki.gentoo.org/wiki/Elogind Gentoo Wiki - elogind]
* [https://wiki.archlinux.org/title/Init#logind ArchWiki - systemd-logind]
* [https://chimera-linux.org/docs/configuration/seat Chimera Linux docs]

== Login ==

{| class="wikitable"
|-
! Name !! Support !! Supports [[PAM]] !! Notes
|-
| busybox login || style="background:lime" | Full || style="background:red" | No || Default
|-
| {{Pkg|greetd}} || style="background:lime" | Full || style="background:lime" | Yes || requires greeter
|-
| {{Pkg|shadow-login}} || style="background:lime" | Full || style="background:lime" | Yes ||
|-
| {{Pkg|util-linux-login}} || style="background:lime" | Full || style="background:lime" | Yes ||
|-
| systemd-logind || style="background:red" | None || style="background:lime" | Yes || Supported by postmarketOS
|-
| without || style="background:lime" | Full || style="background:red" | No ||
|}
* See also: [https://wiki.gentoo.org/wiki/Login Gentoo Wiki]

== Shell Utils ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|busybox}} || style="background:lime" | Full || Dependency of {{pkg|alpine-base}}
|-
| {{Pkg|busybox-extras}} || style="background:lime" | Full || Some commands that are missing in the main {{Pkg|busybox}} package
|-
| {{Pkg|util-linux}} || style="background:lime" | Full ||
|-
| [[GNU_core_utilities|coreutils]] || style="background:lime" | Full ||
|-
| {{Pkg|s6-portable-utils}} || style="background:lime" | Full ||
|-
| {{Pkg|s6-linux-utils}} || style="background:lime" | Full ||
|-
| {{Pkg|toybox}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|sbase}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|ubase}} || style="background:silver" | Needs testing ||
|-
| without || style="background:red" | None || A lot of implicit dependency
|}
* See also: [https://wiki.archlinux.org/title/Core_utilities Archwiki]

== Shell ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| busybox ash || style="background:lime" | Full || Default
|-
| {{Pkg|bash}} || style="background:lime" | Full ||
|-
| {{Pkg|dash}} || style="background:lime" | Full || When used as /bin/sh this may cause breakage.
|-
| {{Pkg|yash}} || style="background:lime" | Full ||
|-
| busybox hush || style="background:red" | None ||
|-
| without || style="background:red" | None || sometimes implicit dependency
|}
* See also: [[Change default shell]]
* See proposal: [https://gitlab.alpinelinux.org/alpine/tsc/-/issues/39 replace busybox ash with another /bin/sh]
* See also: [https://wiki.archlinux.org/title/Command-line_shell Archwiki]
* See also: [https://wiki.gentoo.org/wiki/Shell Gentoo Wiki]

== SU ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{ic|su}} from {{Pkg|busybox-suid}} || style="background:lime" | Full || default, can't be removed by default ({{issue|11730}})
|-
| {{ic|su}} from {{Pkg|shadow-login}} || style="background:lime" | Full ||
|-
| {{ic|su}} from {{Pkg|util-linux-login}} || style="background:lime" | Full ||
|-
| {{Pkg|sudo}} || style="background:lime" | Full ||
|-
| {{Pkg|doas}} || style="background:lime" | Full || sudo shim using doas: {{Pkg|doas-sudo-shim}}
|-
| [https://skarnet.org/software/s6/s6-sudo.html s6-sudo] || style="background:silver" | Needs testing ||
|-
| without || style="background:lime" | Full ||
|}

== SSL/TLS ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|openssl}} || style="background:lime" | Full || Default
|-
| {{Pkg|libressl}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|bearssl}} || style="background:silver" | Needs testing ||
|}
* See also: [https://gitlab.alpinelinux.org/alpine/tsc/-/issues/28 consider LibreSSL as default OpenSSL provider again]
* See also: [https://wiki.archlinux.org/title/Transport_Layer_Security Archwiki]
* See also: [https://github.com/haproxy/wiki/wiki/SSL-Libraries-Support-Status haproxy SSL Libraries Support Status]

== Cron ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|cronie}} || style="background:lime" | Full ||
|-
| {{Pkg|dcron}} || style="background:lime" | Full ||
|-
| {{Pkg|fcron}} || style="background:lime" | Full ||
|-
| vixie-cron || style="background:red" | None ||
|-
| scron || style="background:red" | None ||
|-
| systemd.timer || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:lime" | Full || {{Pkg|alpine-baselayout}} includes cron specific directories though
|}
* See also: [https://wiki.archlinux.org/title/Cron Archwiki]
* See also: [https://wiki.gentoo.org/wiki/Cron Gentoo Wiki]

== SSH ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[Setting_up_a_SSH_server#OpenSSH|openssh]] || style="background:lime" | Full ||
|-
| [[Setting_up_a_SSH_server#Dropbear|dropbear]] || style="background:lime" | Full || provide {{ic|ssh}} command {{pkg|dropbear-ssh}}
|-
| without || style="background:lime" | Full ||
|}
* See also: [https://wiki.archlinux.org/title/Secure_Shell Archwiki]
* See also: [https://wiki.gentoo.org/wiki/SSH Gentoo Wiki - OpenSSH]
* See also: [https://wiki.gentoo.org/wiki/Dropbear Gentoo Wiki - Dropbear]

== Desktop ==
* See: [[Desktop environments and Window managers]]

== See Also ==
* [[Architecture|Alpine Architecture]]
* [https://gitlab.alpinelinux.org/alpine/tsc/-/issues/55 Future of busybox]

APKBUILD Reference

2025-03-10T12:54:21Z

Sertonix: /* User-defined variables */ fix sonameprefix example

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[Abuild and Helpers|abuild]] tool.

See [[aports]] for details on Alpine's official ports repository.

This page is intended to serve as a reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

In description text:
* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented <code>like this</code>.

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}
{{Note|All arbitrary variable and function names should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (for example, ''_luaversions'').}}

These variables are all well documented in <code>man 5 APKBUILD</code> ([https://gitlab.alpinelinux.org/alpine/abuild/-/blob/master/APKBUILD.5.scd man page source]).

== User-defined variables ==
The following variables should be defined by the user:
==== maintainer ====
: Name and email address of the maintainer of the package.
: A well-formatted example is <code>maintainer="John Snow <john_snow@thewall.net>"</code>

==== arch ====
: Package architecture(s) to build for. Can be one or several seperated by whitespace of: '''[[x86]], [[x86_64]], [[armv7]], [[armhf]], [[aarch64]], [[ppc64le]], [[s390x]], [[riscv64]], all''', or '''noarch''', where '''all''' means all architectures, and '''noarch''' means it's architecture-independent (e.g., a pure-python package). Architectures can be negated using the ! character to exclude them from the list of supported architectures. E.g. '''arch="all !ppc64le"''' means that the package is allowed to be built on all architectures but the ppc64le architecture.
: {{Tip|To determine if your APKBUILD can use '''noarch''': First specify '''all''' and then build the package by executing <code>abuild -r</code>. Watch the output towards the end for warnings saying that '''noarch''' can be used. If the main package and all subpackages, if you have any subpackages, give a warning saying that '''noarch''' can be used, then you can use '''noarch'''.}}

==== depends ====
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here. To specify a conflicting package, add the package name prefixed with a '!'.

==== depends_dev ====
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.

: {{Note|From ncopa on IRC: To find out if you need to add a package to depends_dev have a look at *requires* in usr/lib/pkgconfig/*.pc. With libtool it gets more complicated, but we should delete the .la files. Also check if there are any /usr/bin/*-configure #!/bin/bash #!/usr/bin/perl or Python. Sometimes scripts or similar are generated at build time (i.e autoconf automake) then you normally don't need add those to depends_dev. You can also just add all -dev makedepends to depends_dev but it will slow the build process a little bit (more build dependencies).}}

==== depends_doc ====
: Run-time dependency package(s) for the '''$pkgname-doc''' subpackage.

==== depends_openrc ====
: Run-time dependency package(s) for the '''$pkgname-openrc''' subpackage.

==== depends_libs ====
: Run-time dependency package(s) for the '''$pkgname-libs''' subpackage.

==== depends_static ====
: Run-time dependency package(s) for the '''$pkgname-static''' subpackage.

==== checkdepends ====
: Dependencies that are only required during the check phase, they are only installed if the check option is enabled

==== giturl ====
:Git repository from which <code>abuild checkout</code> checks out. You can checkout a specific branch in git by adding <code>-b $branch</code>.
==== install ====
: There are 6 different types of install scripts. Install scripts are named '''$pkgname.action''', where '''action''' can be: '''pre-install, post-install, pre-upgrade, post-upgrade, pre-deinstall''', or '''post-deinstall'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.
<blockquote>{{Note|Always use <code>/bin/sh</code> for the command-line interpreter on the [https://en.wikipedia.org/wiki/Shebang_%28Unix%29 shebang line] of your install scripts.}}</blockquote>

The following are the different types of install scripts in detail:

===== $pkgname.pre-install =====
: This script is executed ''before installing'' the package. Typical use is when the package needs a group and a user to be created. For example:
<blockquote><pre>
#!/bin/sh

addgroup -S clamav 2>/dev/null
adduser -S -D -H -h /var/lib/clamav -s /sbin/nologin -G clamav -g clamav clamav 2>/dev/null

exit 0
</pre>
{{Note|If the script exits with a failure (e.g., if the user already exists), the package will not be installed and <code>apk</code> will exit with failure, hence the <code>exit 0</code> at the end.}}</blockquote>

===== $pkgname.post-install =====
: This script is executed ''after installing'' the package.

===== $pkgname.pre-upgrade =====
: This script is executed ''before upgrading/downgrading/reinstalling'' the package. Note that exiting with failure will not cause apk to exit with failure, but will mark the package as broken.

===== $pkgname.post-upgrade =====
: This script is executed ''after upgrading/downgrading/reinstalling'' the package.

===== $pkgname.pre-deinstall =====
: This script is executed ''before uninstalling'' the package.
: {{Note|If the script exits with failure, <code>apk</code> will not uninstall the package.}}

===== $pkgname.post-deinstall =====
: This script is executed ''after uninstalling'' the package.

==== install_if ====
:install_if can be used when a package needs to be installed when some packages are already installed or are in the dependency tree. It works in reverse to the ''recommends'' feature, that other package managers provide.

: Typically this is used in a subpackage that should provide files which make sense with another package. For example:
<blockquote><pre>
...
subpackages="$pkgname-bash-completion:bashcomp:noarch"
...
bashcomp() {
pkgdesc="Bash completions for $pkgname"
install_if="$pkgname=$pkgver-r$pkgrel bash-completion"

install -Dm644 "$builddir"/doc/bash_completion/aria2c \
"$subpkgdir"/usr/share/bash-completion/completions/_aria2c
}
</pre>
From the aria2c APKBUILD. Note that the custom bashcomp() function is only necessary, because the files are not in /usr/share/bash-completion.
</blockquote>

:In general, install_if should only be used with '''at least one versioned constraint'''. Otherwise, a package that was implicitly installed by install_if and then removed from the binary repositories, will not get purged with <code>apk upgrade</code>. [https://gitlab.alpinelinux.org/alpine/apk-tools/-/issues/10720#note_121298]

==== license ====
: License(s) for the package, for example <code>GPL-3.0-or-later</code>, <code>BSD-2-Clause</code> or <code>MIT</code> [[Creating_an_Alpine_package#license|(details)]].

==== makedepends ====
: Build-time dependency package(s). For cross compiling support, split it into <code>makedepends_build</code> (native system) and <code>makedepends_host</code> (foreign system).

==== sha256sums/sha512sums ====
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated and updated by executing <code>abuild checksum</code> and should be the last item in the APKBUILD.

New packages should use only sha512sums. Support for md5sums and sha1sums was dropped.

==== options ====
: Build-time options for the package.

: {| class="wikitable"
! Option
! Description
|-
| <code>!archcheck</code>
| Do not try to verify that the architecture of the binary files is the same architecture as abuild should build for. One example where it makes sense to set this are packages with firmware files, that get executed on another CPU (such as WiFi firmware).
|-
| <code>!check</code>
| Do not try to run the <code>check()</code> function. Please always add a short comment after the <code>!check</code> about why it's disabled. [https://github.com/alpinelinux/aports/pull/2322#discussion_r142545300] Creating a very simple check function, that calls <code>program --version</code> is worse than disabling tests completely because it gives the false impression that the package is thoroughly tested with the testsuite from upstream. [https://github.com/alpinelinux/aports/pull/7326#discussion_r278797457]
|-
| <code>checkroot</code>
| Specifies that the package's test suite will be run in ''fakeroot''. This is necessary for some test suites which fail when run as non-root.
|-
| <code>net</code>
| Allows network access when run in ''rootbld''.
|-
| <code>!strip</code>
| Avoid stripping symbols from binaries.
|-
| <code>suid</code>
| Allow [https://en.wikipedia.org/wiki/Setuid setuid] binaries.
|-
| <code>!tracedeps</code>
| Do not automatically find dependencies (e.g. by using <code>ldd</code> to find dynamic libraries, which the resulting binary links against).
|-
| <code>chmod-clean</code>
| Make all files writable in the src/ directory. Useful for packages that make files read-only in the process of building packages (go modules).
|-
| <code>toolchain</code>
| Don't warn when g++ is in makedepends
|-
| <code>!dbg</code>
| Don't create debugging subpackage
|-
| <code>ldpath-recursive</code>
| Scan directories recursively when creating .so providers
|-
| <code>!spdx</code>
| Do not check if the license= field has a SPDX compliant license
|-
| <code>textrels</code>
| Don't error out when text relocations are found
|-
| <code>charset.alias</code>
| Don't error out if /usr/lib/charset.alias is found
|-
| <code>libtool</code>
| Don't delete libtool .la files
|-
| <code>!fhs</code>
| Don't enforce checks on path that follow the FHS
|}

==== pkgdesc ====
: A brief, one-line description of what the package does.

: Here's an example from the OpenSSH client package:
: <pre>pkgdesc="Port of OpenBSD's free SSH release - client"</pre>
==== pkggroups ====
: System group(s) to be created during build-time. System group(s) should also be created in the '''[[APKBUILD Reference#.24pkgname.pre-install|$pkgname.pre-install]]''' script, so that the system group(s) are also created prior to package installation for run-time use.
==== pkgname ====
: The name of the package. All letters should be lowercase.
: {{Note|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py3-''. Search aports for other common prefixes.}}

==== pkgrel ====
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
==== pkgusers ====
: System user(s) to be created during build-time. System user(s) should also be created in the '''[[APKBUILD Reference#.24pkgname.pre-install|$pkgname.pre-install]]''' script, so that the system user(s) are also created prior to package installation for run-time use.
==== pkgver ====
: The version of the software being packaged. Format for valid versions: <code>{digit}{.digit}...{letter}{_suf{#}}...{-r#}</code> [https://git.alpinelinux.org/cgit/apk-tools/tree/src/version.c#n17]
: A Suffix <code>suf</code> in the above format can be one of the following to indicate that the release is ''less recent'' than the version without the suffix: <code>alpha</code>, <code>beta</code>, <code>pre</code>, <code>rc</code> [https://git.alpinelinux.org/cgit/apk-tools/tree/src/version.c#n75]
: These are for indicating ''more recent'' releases: <code>cvs</code>, <code>svn</code>, <code>git</code>, <code>hg</code>, <code>p</code> [https://git.alpinelinux.org/cgit/apk-tools/tree/src/version.c#n76]
: All other suffices are invalid. To package a specific git commit, the date of the commit gets appended to the latest release, e.g. <code>1.0.0_git20180204</code>.

==== provides ====
: List of package names (and optionally version info) this package provides.

: If package with a version is provided (provides='foo=1.2') apk will consider it as an alternate name and it will automatically consider the package for installation by the alternate name, and conflict with other packages having the same name, or provides.

: If version is not provided (provides='foo'), apk will consider it as virtual package name. Several package with same non-versioned provides can be installed simultaneously. However, none of them will be installed by default when requested by the virtual name - instead, error message is given and user is asked to choose which package providing the virtual name should be installed.
==== provider_priority ====
: A numeric value which is used by apk-tools to break ties when choosing a virtual package to satisfy a dependency. Higher values have higher priority. The primary use case is to specify the primary package that satisfies a virtual (provider).
==== replaces ====
: Allow this package to be installed at the same time as the listed packages, even if they have conflicting files. The files from this package will override ("take over") the conflicting files.

: This can be used to override config files with "policy packages" [https://gitlab.alpinelinux.org/alpine/apk-tools/-/commit/89d003f8c2e5a92655ee778f7bfa5c0e85ddbed4].

: Another use case is renaming packages (or moving files from one package to another): "replaces" will avoid the file conflict error that apk reports if it happens to install the new package before uninstalling the old package [https://gitlab.alpinelinux.org/alpine/apk-tools/-/issues/10724#note_132872].

: A common misconception is that "replaces" is used to replace packages (like in [https://wiki.archlinux.org/index.php/PKGBUILD#replaces PKGBUILD]). This is not the case, it is only for solving file conflicts. To let apk consider installing one package instead of another one, refer to [[#provides|provides]] (with the version).

==== replaces_priority ====
: The priority of the replaces. If multiple packages replace files of each other, then the package with the highest ''replaces_priority'' will win.

==== source ====
: The source variable is not only used to list the remote source files to fetch, it is also used to list the local files that abuild will need in order to build the apk. Examples of such local files include: init.d files, conf.d files, install files (see [[APKBUILD Reference#install|install variable]]), patches, and all other necessary files.

: Here are few things to note:

:* When you are finished adding local and/or remote files to ''source'', you can execute the following command to add their checksums to the APKBUILD file:
:: {{Cmd|abuild checksum}}
:: {{Note|When later updating the content of ''source'', or updating a file that is listed in ''source'', you must also update their checksums again with the same command.}}

:* When the remote file is hosted at SourceForge, it's best to specify the special mirrors link used by SourceForge:
:: <pre>http://downloads.sourceforge.net/software/software-$pkgver.tar.gz</pre>
:: (or similar depending on the package).

:* You can set target filename (eg 'save as...') by prefixing the URI with ''filename::''. This is useful when the remote filename is not specified in the URI (ie, does not end in '/software-1.0.tar.gz'), such as:
:: <pre>http://oss.example.org/?get=software&ver=1.0</pre>
:: or when the filename is braindead, like githubs' download tags:
:: <pre>https://github.com/software/software/archive/v$pkgver.tar.gz</pre>
:: The above two examples needs a target filename prefix:
:: <pre>$pkgname-$pkgver.tar.gz::http://oss.example.org/?get=software&ver=$pkgver</pre>
:: and:
:: <pre>$pkgname-$pkgver.tar.gz::https://github.com/software/software/archive/v$pkgver.tar.gz</pre>

:* abuild currently supports the following protocols for remote file retrieval:
:** http
:** https
:** ftp

:* abuild currently supports the following archive types/archive file extensions:
:** .tar (only in Alpine >= 2.5)
:** .tar.gz / .tgz
:** .tar.bz2
:** .tar.lz (only in Alpine >=3.7)
:** .tar.lzma
:** .tar.xz
:** .zip

:* <code>source</code> should only include variables that change often like <code>pkgver</code> or a commit ID. CI will warn you if you include <code>pkgname</code> in source. Other variables like for example <code>_pkgname</code> or <code>_pyname</code> do not belong in <code>source</code> either.

==== subpackages ====
: Subpackages built from this APKBUILD. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

: The split function can be specified in 1 of 3 different methods:
:# subpkgname:'''splitfunc'''
:# $pkgname-'''splitfunc'''
:# '''splitfunc'''

: {{Note|Split function names '''cannot''' use hyphens; use the first method above if the subpackage name contains a hyphen (-) character, like this: ''subpkg-name:subpkg_name'', where <code>subpkg-name</code> is the name of the '''subpackage''' and <code>subpkg_name</code> is the name of the '''subpackage's split function'''.}}

: {{Tip|For more information, see the [[APKBUILD_examples:Subpackages|Subpackages example]].}}

==== triggers ====
: Apk-tools can "monitor" directories and execute a trigger if any package installed/uninstalled any file in the monitored dir. The triggers are always executed after the apk action (install, uninstall, upgrade).

: The triggers are specified in the format: ''scriptname''=''pathlist'' where ''scriptname'' is the (sub)package name + .trigger suffix and pathlist is : separated list of the dirs to monitor.

: The '''triggers''' variable must include the triggers for subpackages too if they have any.

: It is possible to use wildcards (*) in the dir list.

==== url ====
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

==== langdir ====
: Path to where the language files are located for the '''-lang''' subpackage, defaults to '''/usr/share/locale'''

==== pcprefix ====
: Prefix all provides derived from parsing pkg-config Requires: with the value in this variable, example: ''''pcprefix="foo:"''' will produce '''pc:foo:bar'''

==== sonameprefix ====
: Prefix all provides derived from parsing shared objects with the value in this variable, example: '''sonameprefix="foo:"''' will produce '''so:foo:bar.so.X'''

= Functions =
{{Note|All functions that are not ''prepare()'', ''build()'', ''check()'' and ''package()'' should consider the current working directory as undefined, and should therefore use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

sanitycheck() -> clean()-> fetch() -> verify() -> unpack() -> prepare() -> mkusers() -> build() -> check() -> package() -> subpackages() -> language packs -> apk -> cleanup()

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden, but it is strongly discouraged on code review for some functions:

==== fetch() ====
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
==== unpack() ====
: unpack() will call default_unpack().

: [https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L403 default_unpack()] unpacks .tar, .tgz, .tar.gz, .tar.lz (only available in Alpine >=3.7), .tar.bz2, .tar.lzma, .tar.xz, and .zip archives from a symlink in ''$srcdir'' associated with ''$SRCDEST'' (or distfiles folder) resulting in an unpacked folder in ''$srcdir''.

==== dev() ====
: Subpackage function for the '''$pkgname-dev''' package is used to collect developer files and folders for use in other packages in the compilation process nothing more. Without specifying a custom ''dev()'' function, abuild will call its internal ''dev()'' function, which in turn calls default_dev().

: ''[https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L1605 default_dev()]'' will move any ''include'' folder and folders containing ''*.[acho]'' (static archive, c source, c header file, object file), ''*.prl'' file extension patterns in ''"$pkgdir"/{lib,usr}'' to ''"$subpkgdir"/{lib,usr}'' recursively; and ''*.so'' files from ''"$pkgdir"/{lib,usr/lib}'' to ''"$subpkgdir"/{lib,usr/lib}''. It will also scan and move ''usr/{include,lib/{pkgconfig,cmake,qt*/mkspecs},share/{aclocal,gettext,vala/vapi,gir-[0-9]*,qt*/mkspecs},bin/*-config}}'' developer only folders in ''$pkgdir'' and transfer them to ''$subpkgdir''.

: In general, default_dev() will support packages that share pkg-config, C programming language API, shared and static libraries, Autotools, gettext, Vala programming language bindings, Python GObject introspection, a provided custom pkg-config like command (*-config), Qt, and CMake. If you have packages that have C++, other languages, other build system, etc; you need to manually move those developer files only if they are to be used in other packages.

: '''Important''': For default_dev() to be called as in no dev(), you need to explicitly add subpackages="$pkgname-dev".

==== doc() ====
: Subpackage function for the '''$pkgname-doc''' package whose job is only to collect documentation folders from $pkgdir nothing more. Without specifying a custom ''doc()'' function, abuild will call its internal ''doc()'' function, which in turn calls default_doc().

: ''[https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L1519 default_doc()]'' will move ''"$pkgdir"/usr/share/{doc,man,info,html,sgml,licenses,gtk-doc,ri,help}'' to ''$subpkgdir''.

: Overriding this function is strongly discouraged. Packaging docs should be done in the package() function while letting abuild automatically collect the doc folders.

: '''Important''': For default_doc() to be called as in no doc(), you need to explicitly add subpackages="$pkgname-doc".

==== openrc() ====
: Subpackage function for the '''$pkgname-openrc''' package whose job is to collect OpenRC service files that are in /etc/init.d and /etc/conf.d.

: ''[https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L1661 default_openrc()]'' will move ''"$pkgdir"/etc/{conf,init}.d'' to ''$subpkgdir''.

: Overriding this function is strongly discouraged. Packaging OpenRC service definitions should be in the package() function while letting abuild automatically collect the openrc folders.

: '''Important''': for default_openrc() to be called as in no openrc(), you need to explicitly add subpackages="$pkgname-openrc".

==== static() ====
: Subpackage function for the '''$pkgname-static''' package whose job is to collect static libraries that are stored in /lib and /usr/lib.

: ''[https://github.com/alpinelinux/abuild/blob/v3.4.0_rc4/abuild.in#L1748 default_static()]'' will move all static libraries (files ending with .a) from ''"$pkgdir"/lib'' and ''"$pkgdir"/usr/lib'' to their equivalents in ''$subpkgdir''.

: Overriding this function is strongly discouraged. Packaging static libraries should be done in the package() function while letting abuild automatically collect the static libraries.

: '''Important''': for default_static() to be called as in no static(), you need to explicitly add subpackages="$pkgname-static".

==== snapshot() ====
: '''Optional'''. For live APKBUILDs or those with a _cvs, _svn, _git, _hg in their version number, you should create a snapshot function only if there is no download link to an archive file (.zip, .tar.gz, ...) to the commit/hash/tag. The purpose of the snapshot function is to create an archive of the source code so that the package source code is deterministic, and it doesn't waste time to fetch the source code but bypasses the download step after snapshotting. Those that download the source code from a git repository will follow head or the latest change to the source code. It is better to archive the source code as a zip / tar.gz / tar.bz2 up to the commit or the tag which you are trying to build a package. If it is not deterministic or not every part of the code frozen in time for every dependency and the main project, then the patches will fail or the package may fail to compile when you revisit the package months or years to backport a patch.

: The default [https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L2310 snapshot()] function has variables associated with it:
:* $disturl - the base-url of the place to autoupload the snapshot
:* $svnurl - Subversion repository
:* $giturl - Git repository

: The default snapshot() can only support one repository. It is better to override it if there are multiple repositories involved in your package. CVS, Mercurial (hg), and alternative version control systems must override the default snapshot().

: See [[APKBUILD_examples:Git_checkout]] to how to use it with git. It takes 2-3 general steps. Clone the repository; check it out at a specific revision/commit or tag; then you use an archiver to dump it in the ''$SRCDEST'' variable which points to the distfiles folder and the base path to the full path to the archive that you want to create. You do this for every internal dependency that the package pulls.

: After you have created your snapshot function, you use <code>abuild snapshot</code> to run it.

: The archives produced by the snapshot will be saved in ''/var/cache/distfiles'' or whatever you set for ''$SRCDEST''. You may need to create symlinks to the archive if the archive is not saved to the Alpine server.

: After you snapshot it, you need to produce the checksums with <code>abuild checksum</code> to use it in the APKBUILD creation process.

: This feature is available since Alpine >=2.6.

==== default_prepare() ====

: Before build preparation it handles set of patches inside <code>$srcdir</code> and prints failed ones.

== User-defined functions ==
The following functions should be defined by the user:

==== prepare() ====
: {{note|Please adjust old APKBUILDs, which still have a ''prepare()'' function that does the same as the ''default_prepare()'' when you edit them anyway.}}
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. When you don't specify a custom ''prepare()'', the built-in ''default_prepare()'' from abuild will be used. It applies patches already (always prepare them in the <code>-p1</code> format), so '''usually it makes sense to not create a custom ''prepare()'' function at all!''' If you do create one, call ''default_prepare()'' inside it:

: Before default_prepare gets called, you can define ''patch_args'' to supply the argument to the patch command in global scope then throw away prepare() so it is unnecessary to use the old template code floating around to patch. patch_args and autopatching is only available in Alpine >=3.4. See [[Creating_an_Alpine_package#Patches]] to fix the patch that uses a different patch level (-pX).

<pre>
prepare() {
default_prepare
# your custom code here
}
</pre>

==== build() ====
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, the function should be removed.

: To enable or disable CFLAGS, CXXFLAGS, CMake with option, or configure option per arch, use the CARCH variable:
<pre>
local cmakeoptions=
case "$CARCH" in
aarch64*|arm*|ppc64le|x86|s390x) cmakeoptions="$cmakeoptions -DWITH_OPENMP=OFF" ;;
x86_64) cmakeoptions="$cmakeoptions -DWITH_OPENMP=ON" ;;
*) msg "Unable to determine architecture from (CARCH=$CARCH)" ; return 1 ;;
esac
</pre>
: The block can be used in other parts of the APKBUILD even in global.

==== check() ====
: '''Required if functionality exists.''' This function is called right after the build stage. It should check that the packaged thing is actually working, typically by running (integration) tests, if provided by upstream. If there’s no (easy) way how to test the package, you can declare that it does not want to use ''check()'' by adding "!check" into the ''options'' variable (<code>options="!check"</code>).

: default_check() does nothing. You need to manually explicitly call the unit tests or test suite yourself. When you run the test, the program should return with an exit code of 0, indicating the tests were a success. Unit tests or test suites will do feature tests, per function correctness check, fuzz testing, benchmarks.

: A package may also require additional testing frameworks packages that are external dependencies. You should add those to the ''checkdepends='' in Alpine >=3.6 or ''makedepends='' for older for backporters. If the testing framework is not available, you need to create a package for it. If it requires a specific version of a testing framework, consider making it an internal dependency or a new package with a package name containing the major and minor version number like the python packages.

: Generally speaking, you should define the check functions for libraries, large programs like web browsers, or compilers and interpreters, cryptographic/security/anonymity stuff, mission critical stuff, PCI compliance/money/accounting software, server software with a lot of stakeholders or consumers. Soon for the new policy change will have virtually '''all packages with testing capabilities be required to have a working and defined check() function'''.

: There are times when the unit tests do not work, just because the test itself is broken, new unimplemented feature, external factors not taken into consideration, unbundling path differences, breakage caused by ccache, missing test dependency or version mismatch dependency as in python2 vs python3, test scripts only work for particular language implementation like only supporting python2 but not python3 having used the 2to3 conversion script. If a unit test is known not to work, you may need to patch it to omit that test or fix it; but, certain tests should not be disabled if it is important. You may need to alter the references to uncompiled internal dependencies to work with the external dependencies instead. For ccache, you can either disable it or remove it from the PATH environmental variable before running tests.

{{Note|Tests for graphical applications and toolkits might work on a X11 user setup but will fail on the server unless run with xvfb-run.}}

: If you don't add the ''check()'' and the ''options='', this is what you will see:

>>> WARNING: py-webtest*: APKBUILD does not run any tests!
Alpine policy will soon require that packages have any relevant testsuites run during the build process.
To fix, either define a check() function, or declare !check in $options to indicate the package does not have a testsuite.

: If you do not do a check or disable it, you must state there is no testsuite in comment form (#) next to options="!check" for the code reviewers.

: To run test suite with autotools do:

make check

: To run the test suite with python setuptools:

python2 setup.py test
python3 setup.py test

: For python it should be '''test''' not check. Check for python setuptools will check the packaging metadata fields[https://docs.python.org/3/distutils/examples.html#checking-a-package] only but not run the unit tests. There should be verbose output also. The dependencies for the tests are found in test_require in the setup.py.

: If it says <code>Ran 0 tests in 0.000s</code> that is not acceptable. check() will say it was good but it is not actually correct. It needs to run the test suite with an alternative method like <code>tox -e py27,py36</code> if you see a tox.ini file.

: You want to do it for each implementation to ensure that the API calls are correct per implementation but ncopa said it was just fine with python3.

: If there is a circular dependency for the checkdepends=, you need to disable the check and put the reason next to <code>options="!check"</code> that there is a circular dependency. You should disable it for the package that package that is least important or least security risk. The other solution is to make the conflicting dependency an internal dependency but making sure that it doesn't pull it at check time. This way they can both preform tests properly.

==== package() ====
: '''Required.''' This is the packaging stage. Here, the built application and support files should be installed into '''$pkgdir'''. If this is a metapackage, this function can contain a single line: <code>mkdir -p "$pkgdir"</code>

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Special Operators =

== $pkgname~$pkgver ==

Specifies a required <code>$pkgver</code> for [[apk]] to satisfy the <code>$pkgname</code> requirement. <code>~</code> ignores revisions of the package version. For example <code>superd~0.6</code> in <code>$depends</code> will ensure superd with package version 0.6 is installed as a run-time dependency for the package.

== $pkgname>=$pkgver ==

Specifies the installed package version must be greater than or equal to <code>$pkgver</code> for [[apk]] to satisfy the <code>$pkgname</code> requirement.

= Examples =
The [[APKBUILD examples]] page will assist you in understanding how to create an APKBUILD.

= Version =

This document assumes abuild for Alpine Edge. For older releases of abuild, some of these features may not be available if you are using an older release. A link to the implementation is linked for researchers and backporters.

For more information see [[APKBUILD_versions]].

[[Category:Development]]

APKBUILD Reference

2025-03-10T11:30:20Z

Sertonix: /* md5sums/sha256sums/sha512sums */ support for md5sums/sha1sums was dropped

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[Abuild and Helpers|abuild]] tool.

See [[aports]] for details on Alpine's official ports repository.

This page is intended to serve as a reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

In description text:
* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented <code>like this</code>.

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}
{{Note|All arbitrary variable and function names should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (for example, ''_luaversions'').}}

These variables are all well documented in <code>man 5 APKBUILD</code> ([https://gitlab.alpinelinux.org/alpine/abuild/-/blob/master/APKBUILD.5.scd man page source]).

== User-defined variables ==
The following variables should be defined by the user:
==== maintainer ====
: Name and email address of the maintainer of the package.
: A well-formatted example is <code>maintainer="John Snow <john_snow@thewall.net>"</code>

==== arch ====
: Package architecture(s) to build for. Can be one or several seperated by whitespace of: '''[[x86]], [[x86_64]], [[armv7]], [[armhf]], [[aarch64]], [[ppc64le]], [[s390x]], [[riscv64]], all''', or '''noarch''', where '''all''' means all architectures, and '''noarch''' means it's architecture-independent (e.g., a pure-python package). Architectures can be negated using the ! character to exclude them from the list of supported architectures. E.g. '''arch="all !ppc64le"''' means that the package is allowed to be built on all architectures but the ppc64le architecture.
: {{Tip|To determine if your APKBUILD can use '''noarch''': First specify '''all''' and then build the package by executing <code>abuild -r</code>. Watch the output towards the end for warnings saying that '''noarch''' can be used. If the main package and all subpackages, if you have any subpackages, give a warning saying that '''noarch''' can be used, then you can use '''noarch'''.}}

==== depends ====
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here. To specify a conflicting package, add the package name prefixed with a '!'.

==== depends_dev ====
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.

: {{Note|From ncopa on IRC: To find out if you need to add a package to depends_dev have a look at *requires* in usr/lib/pkgconfig/*.pc. With libtool it gets more complicated, but we should delete the .la files. Also check if there are any /usr/bin/*-configure #!/bin/bash #!/usr/bin/perl or Python. Sometimes scripts or similar are generated at build time (i.e autoconf automake) then you normally don't need add those to depends_dev. You can also just add all -dev makedepends to depends_dev but it will slow the build process a little bit (more build dependencies).}}

==== depends_doc ====
: Run-time dependency package(s) for the '''$pkgname-doc''' subpackage.

==== depends_openrc ====
: Run-time dependency package(s) for the '''$pkgname-openrc''' subpackage.

==== depends_libs ====
: Run-time dependency package(s) for the '''$pkgname-libs''' subpackage.

==== depends_static ====
: Run-time dependency package(s) for the '''$pkgname-static''' subpackage.

==== checkdepends ====
: Dependencies that are only required during the check phase, they are only installed if the check option is enabled

==== giturl ====
:Git repository from which <code>abuild checkout</code> checks out. You can checkout a specific branch in git by adding <code>-b $branch</code>.
==== install ====
: There are 6 different types of install scripts. Install scripts are named '''$pkgname.action''', where '''action''' can be: '''pre-install, post-install, pre-upgrade, post-upgrade, pre-deinstall''', or '''post-deinstall'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.
<blockquote>{{Note|Always use <code>/bin/sh</code> for the command-line interpreter on the [https://en.wikipedia.org/wiki/Shebang_%28Unix%29 shebang line] of your install scripts.}}</blockquote>

The following are the different types of install scripts in detail:

===== $pkgname.pre-install =====
: This script is executed ''before installing'' the package. Typical use is when the package needs a group and a user to be created. For example:
<blockquote><pre>
#!/bin/sh

addgroup -S clamav 2>/dev/null
adduser -S -D -H -h /var/lib/clamav -s /sbin/nologin -G clamav -g clamav clamav 2>/dev/null

exit 0
</pre>
{{Note|If the script exits with a failure (e.g., if the user already exists), the package will not be installed and <code>apk</code> will exit with failure, hence the <code>exit 0</code> at the end.}}</blockquote>

===== $pkgname.post-install =====
: This script is executed ''after installing'' the package.

===== $pkgname.pre-upgrade =====
: This script is executed ''before upgrading/downgrading/reinstalling'' the package. Note that exiting with failure will not cause apk to exit with failure, but will mark the package as broken.

===== $pkgname.post-upgrade =====
: This script is executed ''after upgrading/downgrading/reinstalling'' the package.

===== $pkgname.pre-deinstall =====
: This script is executed ''before uninstalling'' the package.
: {{Note|If the script exits with failure, <code>apk</code> will not uninstall the package.}}

===== $pkgname.post-deinstall =====
: This script is executed ''after uninstalling'' the package.

==== install_if ====
:install_if can be used when a package needs to be installed when some packages are already installed or are in the dependency tree. It works in reverse to the ''recommends'' feature, that other package managers provide.

: Typically this is used in a subpackage that should provide files which make sense with another package. For example:
<blockquote><pre>
...
subpackages="$pkgname-bash-completion:bashcomp:noarch"
...
bashcomp() {
pkgdesc="Bash completions for $pkgname"
install_if="$pkgname=$pkgver-r$pkgrel bash-completion"

install -Dm644 "$builddir"/doc/bash_completion/aria2c \
"$subpkgdir"/usr/share/bash-completion/completions/_aria2c
}
</pre>
From the aria2c APKBUILD. Note that the custom bashcomp() function is only necessary, because the files are not in /usr/share/bash-completion.
</blockquote>

:In general, install_if should only be used with '''at least one versioned constraint'''. Otherwise, a package that was implicitly installed by install_if and then removed from the binary repositories, will not get purged with <code>apk upgrade</code>. [https://gitlab.alpinelinux.org/alpine/apk-tools/-/issues/10720#note_121298]

==== license ====
: License(s) for the package, for example <code>GPL-3.0-or-later</code>, <code>BSD-2-Clause</code> or <code>MIT</code> [[Creating_an_Alpine_package#license|(details)]].

==== makedepends ====
: Build-time dependency package(s). For cross compiling support, split it into <code>makedepends_build</code> (native system) and <code>makedepends_host</code> (foreign system).

==== sha256sums/sha512sums ====
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated and updated by executing <code>abuild checksum</code> and should be the last item in the APKBUILD.

New packages should use only sha512sums. Support for md5sums and sha1sums was dropped.

==== options ====
: Build-time options for the package.

: {| class="wikitable"
! Option
! Description
|-
| <code>!archcheck</code>
| Do not try to verify that the architecture of the binary files is the same architecture as abuild should build for. One example where it makes sense to set this are packages with firmware files, that get executed on another CPU (such as WiFi firmware).
|-
| <code>!check</code>
| Do not try to run the <code>check()</code> function. Please always add a short comment after the <code>!check</code> about why it's disabled. [https://github.com/alpinelinux/aports/pull/2322#discussion_r142545300] Creating a very simple check function, that calls <code>program --version</code> is worse than disabling tests completely because it gives the false impression that the package is thoroughly tested with the testsuite from upstream. [https://github.com/alpinelinux/aports/pull/7326#discussion_r278797457]
|-
| <code>checkroot</code>
| Specifies that the package's test suite will be run in ''fakeroot''. This is necessary for some test suites which fail when run as non-root.
|-
| <code>net</code>
| Allows network access when run in ''rootbld''.
|-
| <code>!strip</code>
| Avoid stripping symbols from binaries.
|-
| <code>suid</code>
| Allow [https://en.wikipedia.org/wiki/Setuid setuid] binaries.
|-
| <code>!tracedeps</code>
| Do not automatically find dependencies (e.g. by using <code>ldd</code> to find dynamic libraries, which the resulting binary links against).
|-
| <code>chmod-clean</code>
| Make all files writable in the src/ directory. Useful for packages that make files read-only in the process of building packages (go modules).
|-
| <code>toolchain</code>
| Don't warn when g++ is in makedepends
|-
| <code>!dbg</code>
| Don't create debugging subpackage
|-
| <code>ldpath-recursive</code>
| Scan directories recursively when creating .so providers
|-
| <code>!spdx</code>
| Do not check if the license= field has a SPDX compliant license
|-
| <code>textrels</code>
| Don't error out when text relocations are found
|-
| <code>charset.alias</code>
| Don't error out if /usr/lib/charset.alias is found
|-
| <code>libtool</code>
| Don't delete libtool .la files
|-
| <code>!fhs</code>
| Don't enforce checks on path that follow the FHS
|}

==== pkgdesc ====
: A brief, one-line description of what the package does.

: Here's an example from the OpenSSH client package:
: <pre>pkgdesc="Port of OpenBSD's free SSH release - client"</pre>
==== pkggroups ====
: System group(s) to be created during build-time. System group(s) should also be created in the '''[[APKBUILD Reference#.24pkgname.pre-install|$pkgname.pre-install]]''' script, so that the system group(s) are also created prior to package installation for run-time use.
==== pkgname ====
: The name of the package. All letters should be lowercase.
: {{Note|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py3-''. Search aports for other common prefixes.}}

==== pkgrel ====
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
==== pkgusers ====
: System user(s) to be created during build-time. System user(s) should also be created in the '''[[APKBUILD Reference#.24pkgname.pre-install|$pkgname.pre-install]]''' script, so that the system user(s) are also created prior to package installation for run-time use.
==== pkgver ====
: The version of the software being packaged. Format for valid versions: <code>{digit}{.digit}...{letter}{_suf{#}}...{-r#}</code> [https://git.alpinelinux.org/cgit/apk-tools/tree/src/version.c#n17]
: A Suffix <code>suf</code> in the above format can be one of the following to indicate that the release is ''less recent'' than the version without the suffix: <code>alpha</code>, <code>beta</code>, <code>pre</code>, <code>rc</code> [https://git.alpinelinux.org/cgit/apk-tools/tree/src/version.c#n75]
: These are for indicating ''more recent'' releases: <code>cvs</code>, <code>svn</code>, <code>git</code>, <code>hg</code>, <code>p</code> [https://git.alpinelinux.org/cgit/apk-tools/tree/src/version.c#n76]
: All other suffices are invalid. To package a specific git commit, the date of the commit gets appended to the latest release, e.g. <code>1.0.0_git20180204</code>.

==== provides ====
: List of package names (and optionally version info) this package provides.

: If package with a version is provided (provides='foo=1.2') apk will consider it as an alternate name and it will automatically consider the package for installation by the alternate name, and conflict with other packages having the same name, or provides.

: If version is not provided (provides='foo'), apk will consider it as virtual package name. Several package with same non-versioned provides can be installed simultaneously. However, none of them will be installed by default when requested by the virtual name - instead, error message is given and user is asked to choose which package providing the virtual name should be installed.
==== provider_priority ====
: A numeric value which is used by apk-tools to break ties when choosing a virtual package to satisfy a dependency. Higher values have higher priority. The primary use case is to specify the primary package that satisfies a virtual (provider).
==== replaces ====
: Allow this package to be installed at the same time as the listed packages, even if they have conflicting files. The files from this package will override ("take over") the conflicting files.

: This can be used to override config files with "policy packages" [https://gitlab.alpinelinux.org/alpine/apk-tools/-/commit/89d003f8c2e5a92655ee778f7bfa5c0e85ddbed4].

: Another use case is renaming packages (or moving files from one package to another): "replaces" will avoid the file conflict error that apk reports if it happens to install the new package before uninstalling the old package [https://gitlab.alpinelinux.org/alpine/apk-tools/-/issues/10724#note_132872].

: A common misconception is that "replaces" is used to replace packages (like in [https://wiki.archlinux.org/index.php/PKGBUILD#replaces PKGBUILD]). This is not the case, it is only for solving file conflicts. To let apk consider installing one package instead of another one, refer to [[#provides|provides]] (with the version).

==== replaces_priority ====
: The priority of the replaces. If multiple packages replace files of each other, then the package with the highest ''replaces_priority'' will win.

==== source ====
: The source variable is not only used to list the remote source files to fetch, it is also used to list the local files that abuild will need in order to build the apk. Examples of such local files include: init.d files, conf.d files, install files (see [[APKBUILD Reference#install|install variable]]), patches, and all other necessary files.

: Here are few things to note:

:* When you are finished adding local and/or remote files to ''source'', you can execute the following command to add their checksums to the APKBUILD file:
:: {{Cmd|abuild checksum}}
:: {{Note|When later updating the content of ''source'', or updating a file that is listed in ''source'', you must also update their checksums again with the same command.}}

:* When the remote file is hosted at SourceForge, it's best to specify the special mirrors link used by SourceForge:
:: <pre>http://downloads.sourceforge.net/software/software-$pkgver.tar.gz</pre>
:: (or similar depending on the package).

:* You can set target filename (eg 'save as...') by prefixing the URI with ''filename::''. This is useful when the remote filename is not specified in the URI (ie, does not end in '/software-1.0.tar.gz'), such as:
:: <pre>http://oss.example.org/?get=software&ver=1.0</pre>
:: or when the filename is braindead, like githubs' download tags:
:: <pre>https://github.com/software/software/archive/v$pkgver.tar.gz</pre>
:: The above two examples needs a target filename prefix:
:: <pre>$pkgname-$pkgver.tar.gz::http://oss.example.org/?get=software&ver=$pkgver</pre>
:: and:
:: <pre>$pkgname-$pkgver.tar.gz::https://github.com/software/software/archive/v$pkgver.tar.gz</pre>

:* abuild currently supports the following protocols for remote file retrieval:
:** http
:** https
:** ftp

:* abuild currently supports the following archive types/archive file extensions:
:** .tar (only in Alpine >= 2.5)
:** .tar.gz / .tgz
:** .tar.bz2
:** .tar.lz (only in Alpine >=3.7)
:** .tar.lzma
:** .tar.xz
:** .zip

:* <code>source</code> should only include variables that change often like <code>pkgver</code> or a commit ID. CI will warn you if you include <code>pkgname</code> in source. Other variables like for example <code>_pkgname</code> or <code>_pyname</code> do not belong in <code>source</code> either.

==== subpackages ====
: Subpackages built from this APKBUILD. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

: The split function can be specified in 1 of 3 different methods:
:# subpkgname:'''splitfunc'''
:# $pkgname-'''splitfunc'''
:# '''splitfunc'''

: {{Note|Split function names '''cannot''' use hyphens; use the first method above if the subpackage name contains a hyphen (-) character, like this: ''subpkg-name:subpkg_name'', where <code>subpkg-name</code> is the name of the '''subpackage''' and <code>subpkg_name</code> is the name of the '''subpackage's split function'''.}}

: {{Tip|For more information, see the [[APKBUILD_examples:Subpackages|Subpackages example]].}}

==== triggers ====
: Apk-tools can "monitor" directories and execute a trigger if any package installed/uninstalled any file in the monitored dir. The triggers are always executed after the apk action (install, uninstall, upgrade).

: The triggers are specified in the format: ''scriptname''=''pathlist'' where ''scriptname'' is the (sub)package name + .trigger suffix and pathlist is : separated list of the dirs to monitor.

: The '''triggers''' variable must include the triggers for subpackages too if they have any.

: It is possible to use wildcards (*) in the dir list.

==== url ====
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

==== langdir ====
: Path to where the language files are located for the '''-lang''' subpackage, defaults to '''/usr/share/locale'''

==== pcprefix ====
: Prefix all provides derived from parsing pkg-config Requires: with the value in this variable, example: ''''pcprefix="foo:"''' will produce '''pc:foo:bar'''

==== sonameprefix ====
: Prefix all provides derived from parsing shared objects with the value in this variable, example: '''sonameprefix="foo"''' will produce '''so:foo:bar.so.X'''

= Functions =
{{Note|All functions that are not ''prepare()'', ''build()'', ''check()'' and ''package()'' should consider the current working directory as undefined, and should therefore use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

sanitycheck() -> clean()-> fetch() -> verify() -> unpack() -> prepare() -> mkusers() -> build() -> check() -> package() -> subpackages() -> language packs -> apk -> cleanup()

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden, but it is strongly discouraged on code review for some functions:

==== fetch() ====
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
==== unpack() ====
: unpack() will call default_unpack().

: [https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L403 default_unpack()] unpacks .tar, .tgz, .tar.gz, .tar.lz (only available in Alpine >=3.7), .tar.bz2, .tar.lzma, .tar.xz, and .zip archives from a symlink in ''$srcdir'' associated with ''$SRCDEST'' (or distfiles folder) resulting in an unpacked folder in ''$srcdir''.

==== dev() ====
: Subpackage function for the '''$pkgname-dev''' package is used to collect developer files and folders for use in other packages in the compilation process nothing more. Without specifying a custom ''dev()'' function, abuild will call its internal ''dev()'' function, which in turn calls default_dev().

: ''[https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L1605 default_dev()]'' will move any ''include'' folder and folders containing ''*.[acho]'' (static archive, c source, c header file, object file), ''*.prl'' file extension patterns in ''"$pkgdir"/{lib,usr}'' to ''"$subpkgdir"/{lib,usr}'' recursively; and ''*.so'' files from ''"$pkgdir"/{lib,usr/lib}'' to ''"$subpkgdir"/{lib,usr/lib}''. It will also scan and move ''usr/{include,lib/{pkgconfig,cmake,qt*/mkspecs},share/{aclocal,gettext,vala/vapi,gir-[0-9]*,qt*/mkspecs},bin/*-config}}'' developer only folders in ''$pkgdir'' and transfer them to ''$subpkgdir''.

: In general, default_dev() will support packages that share pkg-config, C programming language API, shared and static libraries, Autotools, gettext, Vala programming language bindings, Python GObject introspection, a provided custom pkg-config like command (*-config), Qt, and CMake. If you have packages that have C++, other languages, other build system, etc; you need to manually move those developer files only if they are to be used in other packages.

: '''Important''': For default_dev() to be called as in no dev(), you need to explicitly add subpackages="$pkgname-dev".

==== doc() ====
: Subpackage function for the '''$pkgname-doc''' package whose job is only to collect documentation folders from $pkgdir nothing more. Without specifying a custom ''doc()'' function, abuild will call its internal ''doc()'' function, which in turn calls default_doc().

: ''[https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L1519 default_doc()]'' will move ''"$pkgdir"/usr/share/{doc,man,info,html,sgml,licenses,gtk-doc,ri,help}'' to ''$subpkgdir''.

: Overriding this function is strongly discouraged. Packaging docs should be done in the package() function while letting abuild automatically collect the doc folders.

: '''Important''': For default_doc() to be called as in no doc(), you need to explicitly add subpackages="$pkgname-doc".

==== openrc() ====
: Subpackage function for the '''$pkgname-openrc''' package whose job is to collect OpenRC service files that are in /etc/init.d and /etc/conf.d.

: ''[https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L1661 default_openrc()]'' will move ''"$pkgdir"/etc/{conf,init}.d'' to ''$subpkgdir''.

: Overriding this function is strongly discouraged. Packaging OpenRC service definitions should be in the package() function while letting abuild automatically collect the openrc folders.

: '''Important''': for default_openrc() to be called as in no openrc(), you need to explicitly add subpackages="$pkgname-openrc".

==== static() ====
: Subpackage function for the '''$pkgname-static''' package whose job is to collect static libraries that are stored in /lib and /usr/lib.

: ''[https://github.com/alpinelinux/abuild/blob/v3.4.0_rc4/abuild.in#L1748 default_static()]'' will move all static libraries (files ending with .a) from ''"$pkgdir"/lib'' and ''"$pkgdir"/usr/lib'' to their equivalents in ''$subpkgdir''.

: Overriding this function is strongly discouraged. Packaging static libraries should be done in the package() function while letting abuild automatically collect the static libraries.

: '''Important''': for default_static() to be called as in no static(), you need to explicitly add subpackages="$pkgname-static".

==== snapshot() ====
: '''Optional'''. For live APKBUILDs or those with a _cvs, _svn, _git, _hg in their version number, you should create a snapshot function only if there is no download link to an archive file (.zip, .tar.gz, ...) to the commit/hash/tag. The purpose of the snapshot function is to create an archive of the source code so that the package source code is deterministic, and it doesn't waste time to fetch the source code but bypasses the download step after snapshotting. Those that download the source code from a git repository will follow head or the latest change to the source code. It is better to archive the source code as a zip / tar.gz / tar.bz2 up to the commit or the tag which you are trying to build a package. If it is not deterministic or not every part of the code frozen in time for every dependency and the main project, then the patches will fail or the package may fail to compile when you revisit the package months or years to backport a patch.

: The default [https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L2310 snapshot()] function has variables associated with it:
:* $disturl - the base-url of the place to autoupload the snapshot
:* $svnurl - Subversion repository
:* $giturl - Git repository

: The default snapshot() can only support one repository. It is better to override it if there are multiple repositories involved in your package. CVS, Mercurial (hg), and alternative version control systems must override the default snapshot().

: See [[APKBUILD_examples:Git_checkout]] to how to use it with git. It takes 2-3 general steps. Clone the repository; check it out at a specific revision/commit or tag; then you use an archiver to dump it in the ''$SRCDEST'' variable which points to the distfiles folder and the base path to the full path to the archive that you want to create. You do this for every internal dependency that the package pulls.

: After you have created your snapshot function, you use <code>abuild snapshot</code> to run it.

: The archives produced by the snapshot will be saved in ''/var/cache/distfiles'' or whatever you set for ''$SRCDEST''. You may need to create symlinks to the archive if the archive is not saved to the Alpine server.

: After you snapshot it, you need to produce the checksums with <code>abuild checksum</code> to use it in the APKBUILD creation process.

: This feature is available since Alpine >=2.6.

==== default_prepare() ====

: Before build preparation it handles set of patches inside <code>$srcdir</code> and prints failed ones.

== User-defined functions ==
The following functions should be defined by the user:

==== prepare() ====
: {{note|Please adjust old APKBUILDs, which still have a ''prepare()'' function that does the same as the ''default_prepare()'' when you edit them anyway.}}
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. When you don't specify a custom ''prepare()'', the built-in ''default_prepare()'' from abuild will be used. It applies patches already (always prepare them in the <code>-p1</code> format), so '''usually it makes sense to not create a custom ''prepare()'' function at all!''' If you do create one, call ''default_prepare()'' inside it:

: Before default_prepare gets called, you can define ''patch_args'' to supply the argument to the patch command in global scope then throw away prepare() so it is unnecessary to use the old template code floating around to patch. patch_args and autopatching is only available in Alpine >=3.4. See [[Creating_an_Alpine_package#Patches]] to fix the patch that uses a different patch level (-pX).

<pre>
prepare() {
default_prepare
# your custom code here
}
</pre>

==== build() ====
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, the function should be removed.

: To enable or disable CFLAGS, CXXFLAGS, CMake with option, or configure option per arch, use the CARCH variable:
<pre>
local cmakeoptions=
case "$CARCH" in
aarch64*|arm*|ppc64le|x86|s390x) cmakeoptions="$cmakeoptions -DWITH_OPENMP=OFF" ;;
x86_64) cmakeoptions="$cmakeoptions -DWITH_OPENMP=ON" ;;
*) msg "Unable to determine architecture from (CARCH=$CARCH)" ; return 1 ;;
esac
</pre>
: The block can be used in other parts of the APKBUILD even in global.

==== check() ====
: '''Required if functionality exists.''' This function is called right after the build stage. It should check that the packaged thing is actually working, typically by running (integration) tests, if provided by upstream. If there’s no (easy) way how to test the package, you can declare that it does not want to use ''check()'' by adding "!check" into the ''options'' variable (<code>options="!check"</code>).

: default_check() does nothing. You need to manually explicitly call the unit tests or test suite yourself. When you run the test, the program should return with an exit code of 0, indicating the tests were a success. Unit tests or test suites will do feature tests, per function correctness check, fuzz testing, benchmarks.

: A package may also require additional testing frameworks packages that are external dependencies. You should add those to the ''checkdepends='' in Alpine >=3.6 or ''makedepends='' for older for backporters. If the testing framework is not available, you need to create a package for it. If it requires a specific version of a testing framework, consider making it an internal dependency or a new package with a package name containing the major and minor version number like the python packages.

: Generally speaking, you should define the check functions for libraries, large programs like web browsers, or compilers and interpreters, cryptographic/security/anonymity stuff, mission critical stuff, PCI compliance/money/accounting software, server software with a lot of stakeholders or consumers. Soon for the new policy change will have virtually '''all packages with testing capabilities be required to have a working and defined check() function'''.

: There are times when the unit tests do not work, just because the test itself is broken, new unimplemented feature, external factors not taken into consideration, unbundling path differences, breakage caused by ccache, missing test dependency or version mismatch dependency as in python2 vs python3, test scripts only work for particular language implementation like only supporting python2 but not python3 having used the 2to3 conversion script. If a unit test is known not to work, you may need to patch it to omit that test or fix it; but, certain tests should not be disabled if it is important. You may need to alter the references to uncompiled internal dependencies to work with the external dependencies instead. For ccache, you can either disable it or remove it from the PATH environmental variable before running tests.

{{Note|Tests for graphical applications and toolkits might work on a X11 user setup but will fail on the server unless run with xvfb-run.}}

: If you don't add the ''check()'' and the ''options='', this is what you will see:

>>> WARNING: py-webtest*: APKBUILD does not run any tests!
Alpine policy will soon require that packages have any relevant testsuites run during the build process.
To fix, either define a check() function, or declare !check in $options to indicate the package does not have a testsuite.

: If you do not do a check or disable it, you must state there is no testsuite in comment form (#) next to options="!check" for the code reviewers.

: To run test suite with autotools do:

make check

: To run the test suite with python setuptools:

python2 setup.py test
python3 setup.py test

: For python it should be '''test''' not check. Check for python setuptools will check the packaging metadata fields[https://docs.python.org/3/distutils/examples.html#checking-a-package] only but not run the unit tests. There should be verbose output also. The dependencies for the tests are found in test_require in the setup.py.

: If it says <code>Ran 0 tests in 0.000s</code> that is not acceptable. check() will say it was good but it is not actually correct. It needs to run the test suite with an alternative method like <code>tox -e py27,py36</code> if you see a tox.ini file.

: You want to do it for each implementation to ensure that the API calls are correct per implementation but ncopa said it was just fine with python3.

: If there is a circular dependency for the checkdepends=, you need to disable the check and put the reason next to <code>options="!check"</code> that there is a circular dependency. You should disable it for the package that package that is least important or least security risk. The other solution is to make the conflicting dependency an internal dependency but making sure that it doesn't pull it at check time. This way they can both preform tests properly.

==== package() ====
: '''Required.''' This is the packaging stage. Here, the built application and support files should be installed into '''$pkgdir'''. If this is a metapackage, this function can contain a single line: <code>mkdir -p "$pkgdir"</code>

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Special Operators =

== $pkgname~$pkgver ==

Specifies a required <code>$pkgver</code> for [[apk]] to satisfy the <code>$pkgname</code> requirement. <code>~</code> ignores revisions of the package version. For example <code>superd~0.6</code> in <code>$depends</code> will ensure superd with package version 0.6 is installed as a run-time dependency for the package.

== $pkgname>=$pkgver ==

Specifies the installed package version must be greater than or equal to <code>$pkgver</code> for [[apk]] to satisfy the <code>$pkgname</code> requirement.

= Examples =
The [[APKBUILD examples]] page will assist you in understanding how to create an APKBUILD.

= Version =

This document assumes abuild for Alpine Edge. For older releases of abuild, some of these features may not be available if you are using an older release. A link to the implementation is linked for researchers and backporters.

For more information see [[APKBUILD_versions]].

[[Category:Development]]

APKBUILD Reference

2025-03-10T11:23:24Z

Sertonix: /* $pkgname.pre-install */ use -h in adduser example

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[Abuild and Helpers|abuild]] tool.

See [[aports]] for details on Alpine's official ports repository.

This page is intended to serve as a reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

In description text:
* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented <code>like this</code>.

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}
{{Note|All arbitrary variable and function names should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (for example, ''_luaversions'').}}

These variables are all well documented in <code>man 5 APKBUILD</code> ([https://gitlab.alpinelinux.org/alpine/abuild/-/blob/master/APKBUILD.5.scd man page source]).

== User-defined variables ==
The following variables should be defined by the user:
==== maintainer ====
: Name and email address of the maintainer of the package.
: A well-formatted example is <code>maintainer="John Snow <john_snow@thewall.net>"</code>

==== arch ====
: Package architecture(s) to build for. Can be one or several seperated by whitespace of: '''[[x86]], [[x86_64]], [[armv7]], [[armhf]], [[aarch64]], [[ppc64le]], [[s390x]], [[riscv64]], all''', or '''noarch''', where '''all''' means all architectures, and '''noarch''' means it's architecture-independent (e.g., a pure-python package). Architectures can be negated using the ! character to exclude them from the list of supported architectures. E.g. '''arch="all !ppc64le"''' means that the package is allowed to be built on all architectures but the ppc64le architecture.
: {{Tip|To determine if your APKBUILD can use '''noarch''': First specify '''all''' and then build the package by executing <code>abuild -r</code>. Watch the output towards the end for warnings saying that '''noarch''' can be used. If the main package and all subpackages, if you have any subpackages, give a warning saying that '''noarch''' can be used, then you can use '''noarch'''.}}

==== depends ====
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here. To specify a conflicting package, add the package name prefixed with a '!'.

==== depends_dev ====
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.

: {{Note|From ncopa on IRC: To find out if you need to add a package to depends_dev have a look at *requires* in usr/lib/pkgconfig/*.pc. With libtool it gets more complicated, but we should delete the .la files. Also check if there are any /usr/bin/*-configure #!/bin/bash #!/usr/bin/perl or Python. Sometimes scripts or similar are generated at build time (i.e autoconf automake) then you normally don't need add those to depends_dev. You can also just add all -dev makedepends to depends_dev but it will slow the build process a little bit (more build dependencies).}}

==== depends_doc ====
: Run-time dependency package(s) for the '''$pkgname-doc''' subpackage.

==== depends_openrc ====
: Run-time dependency package(s) for the '''$pkgname-openrc''' subpackage.

==== depends_libs ====
: Run-time dependency package(s) for the '''$pkgname-libs''' subpackage.

==== depends_static ====
: Run-time dependency package(s) for the '''$pkgname-static''' subpackage.

==== checkdepends ====
: Dependencies that are only required during the check phase, they are only installed if the check option is enabled

==== giturl ====
:Git repository from which <code>abuild checkout</code> checks out. You can checkout a specific branch in git by adding <code>-b $branch</code>.
==== install ====
: There are 6 different types of install scripts. Install scripts are named '''$pkgname.action''', where '''action''' can be: '''pre-install, post-install, pre-upgrade, post-upgrade, pre-deinstall''', or '''post-deinstall'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.
<blockquote>{{Note|Always use <code>/bin/sh</code> for the command-line interpreter on the [https://en.wikipedia.org/wiki/Shebang_%28Unix%29 shebang line] of your install scripts.}}</blockquote>

The following are the different types of install scripts in detail:

===== $pkgname.pre-install =====
: This script is executed ''before installing'' the package. Typical use is when the package needs a group and a user to be created. For example:
<blockquote><pre>
#!/bin/sh

addgroup -S clamav 2>/dev/null
adduser -S -D -H -h /var/lib/clamav -s /sbin/nologin -G clamav -g clamav clamav 2>/dev/null

exit 0
</pre>
{{Note|If the script exits with a failure (e.g., if the user already exists), the package will not be installed and <code>apk</code> will exit with failure, hence the <code>exit 0</code> at the end.}}</blockquote>

===== $pkgname.post-install =====
: This script is executed ''after installing'' the package.

===== $pkgname.pre-upgrade =====
: This script is executed ''before upgrading/downgrading/reinstalling'' the package. Note that exiting with failure will not cause apk to exit with failure, but will mark the package as broken.

===== $pkgname.post-upgrade =====
: This script is executed ''after upgrading/downgrading/reinstalling'' the package.

===== $pkgname.pre-deinstall =====
: This script is executed ''before uninstalling'' the package.
: {{Note|If the script exits with failure, <code>apk</code> will not uninstall the package.}}

===== $pkgname.post-deinstall =====
: This script is executed ''after uninstalling'' the package.

==== install_if ====
:install_if can be used when a package needs to be installed when some packages are already installed or are in the dependency tree. It works in reverse to the ''recommends'' feature, that other package managers provide.

: Typically this is used in a subpackage that should provide files which make sense with another package. For example:
<blockquote><pre>
...
subpackages="$pkgname-bash-completion:bashcomp:noarch"
...
bashcomp() {
pkgdesc="Bash completions for $pkgname"
install_if="$pkgname=$pkgver-r$pkgrel bash-completion"

install -Dm644 "$builddir"/doc/bash_completion/aria2c \
"$subpkgdir"/usr/share/bash-completion/completions/_aria2c
}
</pre>
From the aria2c APKBUILD. Note that the custom bashcomp() function is only necessary, because the files are not in /usr/share/bash-completion.
</blockquote>

:In general, install_if should only be used with '''at least one versioned constraint'''. Otherwise, a package that was implicitly installed by install_if and then removed from the binary repositories, will not get purged with <code>apk upgrade</code>. [https://gitlab.alpinelinux.org/alpine/apk-tools/-/issues/10720#note_121298]

==== license ====
: License(s) for the package, for example <code>GPL-3.0-or-later</code>, <code>BSD-2-Clause</code> or <code>MIT</code> [[Creating_an_Alpine_package#license|(details)]].

==== makedepends ====
: Build-time dependency package(s). For cross compiling support, split it into <code>makedepends_build</code> (native system) and <code>makedepends_host</code> (foreign system).

==== md5sums/sha256sums/sha512sums ====
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated and updated by executing <code>abuild checksum</code> and should be the last item in the APKBUILD.

New packages should use only sha512sums.

==== options ====
: Build-time options for the package.

: {| class="wikitable"
! Option
! Description
|-
| <code>!archcheck</code>
| Do not try to verify that the architecture of the binary files is the same architecture as abuild should build for. One example where it makes sense to set this are packages with firmware files, that get executed on another CPU (such as WiFi firmware).
|-
| <code>!check</code>
| Do not try to run the <code>check()</code> function. Please always add a short comment after the <code>!check</code> about why it's disabled. [https://github.com/alpinelinux/aports/pull/2322#discussion_r142545300] Creating a very simple check function, that calls <code>program --version</code> is worse than disabling tests completely because it gives the false impression that the package is thoroughly tested with the testsuite from upstream. [https://github.com/alpinelinux/aports/pull/7326#discussion_r278797457]
|-
| <code>checkroot</code>
| Specifies that the package's test suite will be run in ''fakeroot''. This is necessary for some test suites which fail when run as non-root.
|-
| <code>net</code>
| Allows network access when run in ''rootbld''.
|-
| <code>!strip</code>
| Avoid stripping symbols from binaries.
|-
| <code>suid</code>
| Allow [https://en.wikipedia.org/wiki/Setuid setuid] binaries.
|-
| <code>!tracedeps</code>
| Do not automatically find dependencies (e.g. by using <code>ldd</code> to find dynamic libraries, which the resulting binary links against).
|-
| <code>chmod-clean</code>
| Make all files writable in the src/ directory. Useful for packages that make files read-only in the process of building packages (go modules).
|-
| <code>toolchain</code>
| Don't warn when g++ is in makedepends
|-
| <code>!dbg</code>
| Don't create debugging subpackage
|-
| <code>ldpath-recursive</code>
| Scan directories recursively when creating .so providers
|-
| <code>!spdx</code>
| Do not check if the license= field has a SPDX compliant license
|-
| <code>textrels</code>
| Don't error out when text relocations are found
|-
| <code>charset.alias</code>
| Don't error out if /usr/lib/charset.alias is found
|-
| <code>libtool</code>
| Don't delete libtool .la files
|-
| <code>!fhs</code>
| Don't enforce checks on path that follow the FHS
|}

==== pkgdesc ====
: A brief, one-line description of what the package does.

: Here's an example from the OpenSSH client package:
: <pre>pkgdesc="Port of OpenBSD's free SSH release - client"</pre>
==== pkggroups ====
: System group(s) to be created during build-time. System group(s) should also be created in the '''[[APKBUILD Reference#.24pkgname.pre-install|$pkgname.pre-install]]''' script, so that the system group(s) are also created prior to package installation for run-time use.
==== pkgname ====
: The name of the package. All letters should be lowercase.
: {{Note|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py3-''. Search aports for other common prefixes.}}

==== pkgrel ====
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
==== pkgusers ====
: System user(s) to be created during build-time. System user(s) should also be created in the '''[[APKBUILD Reference#.24pkgname.pre-install|$pkgname.pre-install]]''' script, so that the system user(s) are also created prior to package installation for run-time use.
==== pkgver ====
: The version of the software being packaged. Format for valid versions: <code>{digit}{.digit}...{letter}{_suf{#}}...{-r#}</code> [https://git.alpinelinux.org/cgit/apk-tools/tree/src/version.c#n17]
: A Suffix <code>suf</code> in the above format can be one of the following to indicate that the release is ''less recent'' than the version without the suffix: <code>alpha</code>, <code>beta</code>, <code>pre</code>, <code>rc</code> [https://git.alpinelinux.org/cgit/apk-tools/tree/src/version.c#n75]
: These are for indicating ''more recent'' releases: <code>cvs</code>, <code>svn</code>, <code>git</code>, <code>hg</code>, <code>p</code> [https://git.alpinelinux.org/cgit/apk-tools/tree/src/version.c#n76]
: All other suffices are invalid. To package a specific git commit, the date of the commit gets appended to the latest release, e.g. <code>1.0.0_git20180204</code>.

==== provides ====
: List of package names (and optionally version info) this package provides.

: If package with a version is provided (provides='foo=1.2') apk will consider it as an alternate name and it will automatically consider the package for installation by the alternate name, and conflict with other packages having the same name, or provides.

: If version is not provided (provides='foo'), apk will consider it as virtual package name. Several package with same non-versioned provides can be installed simultaneously. However, none of them will be installed by default when requested by the virtual name - instead, error message is given and user is asked to choose which package providing the virtual name should be installed.
==== provider_priority ====
: A numeric value which is used by apk-tools to break ties when choosing a virtual package to satisfy a dependency. Higher values have higher priority. The primary use case is to specify the primary package that satisfies a virtual (provider).
==== replaces ====
: Allow this package to be installed at the same time as the listed packages, even if they have conflicting files. The files from this package will override ("take over") the conflicting files.

: This can be used to override config files with "policy packages" [https://gitlab.alpinelinux.org/alpine/apk-tools/-/commit/89d003f8c2e5a92655ee778f7bfa5c0e85ddbed4].

: Another use case is renaming packages (or moving files from one package to another): "replaces" will avoid the file conflict error that apk reports if it happens to install the new package before uninstalling the old package [https://gitlab.alpinelinux.org/alpine/apk-tools/-/issues/10724#note_132872].

: A common misconception is that "replaces" is used to replace packages (like in [https://wiki.archlinux.org/index.php/PKGBUILD#replaces PKGBUILD]). This is not the case, it is only for solving file conflicts. To let apk consider installing one package instead of another one, refer to [[#provides|provides]] (with the version).

==== replaces_priority ====
: The priority of the replaces. If multiple packages replace files of each other, then the package with the highest ''replaces_priority'' will win.

==== source ====
: The source variable is not only used to list the remote source files to fetch, it is also used to list the local files that abuild will need in order to build the apk. Examples of such local files include: init.d files, conf.d files, install files (see [[APKBUILD Reference#install|install variable]]), patches, and all other necessary files.

: Here are few things to note:

:* When you are finished adding local and/or remote files to ''source'', you can execute the following command to add their checksums to the APKBUILD file:
:: {{Cmd|abuild checksum}}
:: {{Note|When later updating the content of ''source'', or updating a file that is listed in ''source'', you must also update their checksums again with the same command.}}

:* When the remote file is hosted at SourceForge, it's best to specify the special mirrors link used by SourceForge:
:: <pre>http://downloads.sourceforge.net/software/software-$pkgver.tar.gz</pre>
:: (or similar depending on the package).

:* You can set target filename (eg 'save as...') by prefixing the URI with ''filename::''. This is useful when the remote filename is not specified in the URI (ie, does not end in '/software-1.0.tar.gz'), such as:
:: <pre>http://oss.example.org/?get=software&ver=1.0</pre>
:: or when the filename is braindead, like githubs' download tags:
:: <pre>https://github.com/software/software/archive/v$pkgver.tar.gz</pre>
:: The above two examples needs a target filename prefix:
:: <pre>$pkgname-$pkgver.tar.gz::http://oss.example.org/?get=software&ver=$pkgver</pre>
:: and:
:: <pre>$pkgname-$pkgver.tar.gz::https://github.com/software/software/archive/v$pkgver.tar.gz</pre>

:* abuild currently supports the following protocols for remote file retrieval:
:** http
:** https
:** ftp

:* abuild currently supports the following archive types/archive file extensions:
:** .tar (only in Alpine >= 2.5)
:** .tar.gz / .tgz
:** .tar.bz2
:** .tar.lz (only in Alpine >=3.7)
:** .tar.lzma
:** .tar.xz
:** .zip

:* <code>source</code> should only include variables that change often like <code>pkgver</code> or a commit ID. CI will warn you if you include <code>pkgname</code> in source. Other variables like for example <code>_pkgname</code> or <code>_pyname</code> do not belong in <code>source</code> either.

==== subpackages ====
: Subpackages built from this APKBUILD. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

: The split function can be specified in 1 of 3 different methods:
:# subpkgname:'''splitfunc'''
:# $pkgname-'''splitfunc'''
:# '''splitfunc'''

: {{Note|Split function names '''cannot''' use hyphens; use the first method above if the subpackage name contains a hyphen (-) character, like this: ''subpkg-name:subpkg_name'', where <code>subpkg-name</code> is the name of the '''subpackage''' and <code>subpkg_name</code> is the name of the '''subpackage's split function'''.}}

: {{Tip|For more information, see the [[APKBUILD_examples:Subpackages|Subpackages example]].}}

==== triggers ====
: Apk-tools can "monitor" directories and execute a trigger if any package installed/uninstalled any file in the monitored dir. The triggers are always executed after the apk action (install, uninstall, upgrade).

: The triggers are specified in the format: ''scriptname''=''pathlist'' where ''scriptname'' is the (sub)package name + .trigger suffix and pathlist is : separated list of the dirs to monitor.

: The '''triggers''' variable must include the triggers for subpackages too if they have any.

: It is possible to use wildcards (*) in the dir list.

==== url ====
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

==== langdir ====
: Path to where the language files are located for the '''-lang''' subpackage, defaults to '''/usr/share/locale'''

==== pcprefix ====
: Prefix all provides derived from parsing pkg-config Requires: with the value in this variable, example: ''''pcprefix="foo:"''' will produce '''pc:foo:bar'''

==== sonameprefix ====
: Prefix all provides derived from parsing shared objects with the value in this variable, example: '''sonameprefix="foo"''' will produce '''so:foo:bar.so.X'''

= Functions =
{{Note|All functions that are not ''prepare()'', ''build()'', ''check()'' and ''package()'' should consider the current working directory as undefined, and should therefore use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

sanitycheck() -> clean()-> fetch() -> verify() -> unpack() -> prepare() -> mkusers() -> build() -> check() -> package() -> subpackages() -> language packs -> apk -> cleanup()

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden, but it is strongly discouraged on code review for some functions:

==== fetch() ====
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
==== unpack() ====
: unpack() will call default_unpack().

: [https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L403 default_unpack()] unpacks .tar, .tgz, .tar.gz, .tar.lz (only available in Alpine >=3.7), .tar.bz2, .tar.lzma, .tar.xz, and .zip archives from a symlink in ''$srcdir'' associated with ''$SRCDEST'' (or distfiles folder) resulting in an unpacked folder in ''$srcdir''.

==== dev() ====
: Subpackage function for the '''$pkgname-dev''' package is used to collect developer files and folders for use in other packages in the compilation process nothing more. Without specifying a custom ''dev()'' function, abuild will call its internal ''dev()'' function, which in turn calls default_dev().

: ''[https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L1605 default_dev()]'' will move any ''include'' folder and folders containing ''*.[acho]'' (static archive, c source, c header file, object file), ''*.prl'' file extension patterns in ''"$pkgdir"/{lib,usr}'' to ''"$subpkgdir"/{lib,usr}'' recursively; and ''*.so'' files from ''"$pkgdir"/{lib,usr/lib}'' to ''"$subpkgdir"/{lib,usr/lib}''. It will also scan and move ''usr/{include,lib/{pkgconfig,cmake,qt*/mkspecs},share/{aclocal,gettext,vala/vapi,gir-[0-9]*,qt*/mkspecs},bin/*-config}}'' developer only folders in ''$pkgdir'' and transfer them to ''$subpkgdir''.

: In general, default_dev() will support packages that share pkg-config, C programming language API, shared and static libraries, Autotools, gettext, Vala programming language bindings, Python GObject introspection, a provided custom pkg-config like command (*-config), Qt, and CMake. If you have packages that have C++, other languages, other build system, etc; you need to manually move those developer files only if they are to be used in other packages.

: '''Important''': For default_dev() to be called as in no dev(), you need to explicitly add subpackages="$pkgname-dev".

==== doc() ====
: Subpackage function for the '''$pkgname-doc''' package whose job is only to collect documentation folders from $pkgdir nothing more. Without specifying a custom ''doc()'' function, abuild will call its internal ''doc()'' function, which in turn calls default_doc().

: ''[https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L1519 default_doc()]'' will move ''"$pkgdir"/usr/share/{doc,man,info,html,sgml,licenses,gtk-doc,ri,help}'' to ''$subpkgdir''.

: Overriding this function is strongly discouraged. Packaging docs should be done in the package() function while letting abuild automatically collect the doc folders.

: '''Important''': For default_doc() to be called as in no doc(), you need to explicitly add subpackages="$pkgname-doc".

==== openrc() ====
: Subpackage function for the '''$pkgname-openrc''' package whose job is to collect OpenRC service files that are in /etc/init.d and /etc/conf.d.

: ''[https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L1661 default_openrc()]'' will move ''"$pkgdir"/etc/{conf,init}.d'' to ''$subpkgdir''.

: Overriding this function is strongly discouraged. Packaging OpenRC service definitions should be in the package() function while letting abuild automatically collect the openrc folders.

: '''Important''': for default_openrc() to be called as in no openrc(), you need to explicitly add subpackages="$pkgname-openrc".

==== static() ====
: Subpackage function for the '''$pkgname-static''' package whose job is to collect static libraries that are stored in /lib and /usr/lib.

: ''[https://github.com/alpinelinux/abuild/blob/v3.4.0_rc4/abuild.in#L1748 default_static()]'' will move all static libraries (files ending with .a) from ''"$pkgdir"/lib'' and ''"$pkgdir"/usr/lib'' to their equivalents in ''$subpkgdir''.

: Overriding this function is strongly discouraged. Packaging static libraries should be done in the package() function while letting abuild automatically collect the static libraries.

: '''Important''': for default_static() to be called as in no static(), you need to explicitly add subpackages="$pkgname-static".

==== snapshot() ====
: '''Optional'''. For live APKBUILDs or those with a _cvs, _svn, _git, _hg in their version number, you should create a snapshot function only if there is no download link to an archive file (.zip, .tar.gz, ...) to the commit/hash/tag. The purpose of the snapshot function is to create an archive of the source code so that the package source code is deterministic, and it doesn't waste time to fetch the source code but bypasses the download step after snapshotting. Those that download the source code from a git repository will follow head or the latest change to the source code. It is better to archive the source code as a zip / tar.gz / tar.bz2 up to the commit or the tag which you are trying to build a package. If it is not deterministic or not every part of the code frozen in time for every dependency and the main project, then the patches will fail or the package may fail to compile when you revisit the package months or years to backport a patch.

: The default [https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L2310 snapshot()] function has variables associated with it:
:* $disturl - the base-url of the place to autoupload the snapshot
:* $svnurl - Subversion repository
:* $giturl - Git repository

: The default snapshot() can only support one repository. It is better to override it if there are multiple repositories involved in your package. CVS, Mercurial (hg), and alternative version control systems must override the default snapshot().

: See [[APKBUILD_examples:Git_checkout]] to how to use it with git. It takes 2-3 general steps. Clone the repository; check it out at a specific revision/commit or tag; then you use an archiver to dump it in the ''$SRCDEST'' variable which points to the distfiles folder and the base path to the full path to the archive that you want to create. You do this for every internal dependency that the package pulls.

: After you have created your snapshot function, you use <code>abuild snapshot</code> to run it.

: The archives produced by the snapshot will be saved in ''/var/cache/distfiles'' or whatever you set for ''$SRCDEST''. You may need to create symlinks to the archive if the archive is not saved to the Alpine server.

: After you snapshot it, you need to produce the checksums with <code>abuild checksum</code> to use it in the APKBUILD creation process.

: This feature is available since Alpine >=2.6.

==== default_prepare() ====

: Before build preparation it handles set of patches inside <code>$srcdir</code> and prints failed ones.

== User-defined functions ==
The following functions should be defined by the user:

==== prepare() ====
: {{note|Please adjust old APKBUILDs, which still have a ''prepare()'' function that does the same as the ''default_prepare()'' when you edit them anyway.}}
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. When you don't specify a custom ''prepare()'', the built-in ''default_prepare()'' from abuild will be used. It applies patches already (always prepare them in the <code>-p1</code> format), so '''usually it makes sense to not create a custom ''prepare()'' function at all!''' If you do create one, call ''default_prepare()'' inside it:

: Before default_prepare gets called, you can define ''patch_args'' to supply the argument to the patch command in global scope then throw away prepare() so it is unnecessary to use the old template code floating around to patch. patch_args and autopatching is only available in Alpine >=3.4. See [[Creating_an_Alpine_package#Patches]] to fix the patch that uses a different patch level (-pX).

<pre>
prepare() {
default_prepare
# your custom code here
}
</pre>

==== build() ====
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, the function should be removed.

: To enable or disable CFLAGS, CXXFLAGS, CMake with option, or configure option per arch, use the CARCH variable:
<pre>
local cmakeoptions=
case "$CARCH" in
aarch64*|arm*|ppc64le|x86|s390x) cmakeoptions="$cmakeoptions -DWITH_OPENMP=OFF" ;;
x86_64) cmakeoptions="$cmakeoptions -DWITH_OPENMP=ON" ;;
*) msg "Unable to determine architecture from (CARCH=$CARCH)" ; return 1 ;;
esac
</pre>
: The block can be used in other parts of the APKBUILD even in global.

==== check() ====
: '''Required if functionality exists.''' This function is called right after the build stage. It should check that the packaged thing is actually working, typically by running (integration) tests, if provided by upstream. If there’s no (easy) way how to test the package, you can declare that it does not want to use ''check()'' by adding "!check" into the ''options'' variable (<code>options="!check"</code>).

: default_check() does nothing. You need to manually explicitly call the unit tests or test suite yourself. When you run the test, the program should return with an exit code of 0, indicating the tests were a success. Unit tests or test suites will do feature tests, per function correctness check, fuzz testing, benchmarks.

: A package may also require additional testing frameworks packages that are external dependencies. You should add those to the ''checkdepends='' in Alpine >=3.6 or ''makedepends='' for older for backporters. If the testing framework is not available, you need to create a package for it. If it requires a specific version of a testing framework, consider making it an internal dependency or a new package with a package name containing the major and minor version number like the python packages.

: Generally speaking, you should define the check functions for libraries, large programs like web browsers, or compilers and interpreters, cryptographic/security/anonymity stuff, mission critical stuff, PCI compliance/money/accounting software, server software with a lot of stakeholders or consumers. Soon for the new policy change will have virtually '''all packages with testing capabilities be required to have a working and defined check() function'''.

: There are times when the unit tests do not work, just because the test itself is broken, new unimplemented feature, external factors not taken into consideration, unbundling path differences, breakage caused by ccache, missing test dependency or version mismatch dependency as in python2 vs python3, test scripts only work for particular language implementation like only supporting python2 but not python3 having used the 2to3 conversion script. If a unit test is known not to work, you may need to patch it to omit that test or fix it; but, certain tests should not be disabled if it is important. You may need to alter the references to uncompiled internal dependencies to work with the external dependencies instead. For ccache, you can either disable it or remove it from the PATH environmental variable before running tests.

{{Note|Tests for graphical applications and toolkits might work on a X11 user setup but will fail on the server unless run with xvfb-run.}}

: If you don't add the ''check()'' and the ''options='', this is what you will see:

>>> WARNING: py-webtest*: APKBUILD does not run any tests!
Alpine policy will soon require that packages have any relevant testsuites run during the build process.
To fix, either define a check() function, or declare !check in $options to indicate the package does not have a testsuite.

: If you do not do a check or disable it, you must state there is no testsuite in comment form (#) next to options="!check" for the code reviewers.

: To run test suite with autotools do:

make check

: To run the test suite with python setuptools:

python2 setup.py test
python3 setup.py test

: For python it should be '''test''' not check. Check for python setuptools will check the packaging metadata fields[https://docs.python.org/3/distutils/examples.html#checking-a-package] only but not run the unit tests. There should be verbose output also. The dependencies for the tests are found in test_require in the setup.py.

: If it says <code>Ran 0 tests in 0.000s</code> that is not acceptable. check() will say it was good but it is not actually correct. It needs to run the test suite with an alternative method like <code>tox -e py27,py36</code> if you see a tox.ini file.

: You want to do it for each implementation to ensure that the API calls are correct per implementation but ncopa said it was just fine with python3.

: If there is a circular dependency for the checkdepends=, you need to disable the check and put the reason next to <code>options="!check"</code> that there is a circular dependency. You should disable it for the package that package that is least important or least security risk. The other solution is to make the conflicting dependency an internal dependency but making sure that it doesn't pull it at check time. This way they can both preform tests properly.

==== package() ====
: '''Required.''' This is the packaging stage. Here, the built application and support files should be installed into '''$pkgdir'''. If this is a metapackage, this function can contain a single line: <code>mkdir -p "$pkgdir"</code>

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Special Operators =

== $pkgname~$pkgver ==

Specifies a required <code>$pkgver</code> for [[apk]] to satisfy the <code>$pkgname</code> requirement. <code>~</code> ignores revisions of the package version. For example <code>superd~0.6</code> in <code>$depends</code> will ensure superd with package version 0.6 is installed as a run-time dependency for the package.

== $pkgname>=$pkgver ==

Specifies the installed package version must be greater than or equal to <code>$pkgver</code> for [[apk]] to satisfy the <code>$pkgname</code> requirement.

= Examples =
The [[APKBUILD examples]] page will assist you in understanding how to create an APKBUILD.

= Version =

This document assumes abuild for Alpine Edge. For older releases of abuild, some of these features may not be available if you are using an older release. A link to the implementation is linked for researchers and backporters.

For more information see [[APKBUILD_versions]].

[[Category:Development]]

APKBUILD Reference

2025-03-10T10:47:37Z

Sertonix: remove build() function instead of using return 0

APKBUILDs are the scripts that are created in order to build Alpine packages using the [[Abuild and Helpers|abuild]] tool.

See [[aports]] for details on Alpine's official ports repository.

This page is intended to serve as a reference for creating APKBUILDs; if this is your first time creating a package for Alpine Linux, please see [[Creating an Alpine package]].

= Legend =
The following notes will assist you in understanding this document.

In description text:
* If a variable is not prefixed with a ''$'', it will be represented by italics (i.e., ''srcdir'' ).
* Functions will also be represented by italics, but will also end with a pair of parentheses (i.e., ''build()'' ).
* Shell commands will be represented <code>like this</code>.

= Variables =
{{Note|Variables that contain a path (e.g. ''$srcdir'' and ''$pkgdir'') should always be quoted using double quotes (i.e., ''"$srcdir"''). This is done to prevent things from breaking, should the user have the APKBUILD in a directory path that contains spaces.}}
{{Note|All arbitrary variable and function names should be prefixed with an underscore character ( _ ) to avoid name clashes with the internals of abuild (for example, ''_luaversions'').}}

These variables are all well documented in <code>man 5 APKBUILD</code> ([https://gitlab.alpinelinux.org/alpine/abuild/-/blob/master/APKBUILD.5.scd man page source]).

== User-defined variables ==
The following variables should be defined by the user:
==== maintainer ====
: Name and email address of the maintainer of the package.
: A well-formatted example is <code>maintainer="John Snow <john_snow@thewall.net>"</code>

==== arch ====
: Package architecture(s) to build for. Can be one or several seperated by whitespace of: '''[[x86]], [[x86_64]], [[armv7]], [[armhf]], [[aarch64]], [[ppc64le]], [[s390x]], [[riscv64]], all''', or '''noarch''', where '''all''' means all architectures, and '''noarch''' means it's architecture-independent (e.g., a pure-python package). Architectures can be negated using the ! character to exclude them from the list of supported architectures. E.g. '''arch="all !ppc64le"''' means that the package is allowed to be built on all architectures but the ppc64le architecture.
: {{Tip|To determine if your APKBUILD can use '''noarch''': First specify '''all''' and then build the package by executing <code>abuild -r</code>. Watch the output towards the end for warnings saying that '''noarch''' can be used. If the main package and all subpackages, if you have any subpackages, give a warning saying that '''noarch''' can be used, then you can use '''noarch'''.}}

==== depends ====
: Run-time dependency package(s) that are not shared-object dependencies. Shared objects dependencies are auto-detected and should not be specified here. To specify a conflicting package, add the package name prefixed with a '!'.

==== depends_dev ====
: Run-time dependency package(s) for the '''$pkgname-dev''' subpackage.

: {{Note|From ncopa on IRC: To find out if you need to add a package to depends_dev have a look at *requires* in usr/lib/pkgconfig/*.pc. With libtool it gets more complicated, but we should delete the .la files. Also check if there are any /usr/bin/*-configure #!/bin/bash #!/usr/bin/perl or Python. Sometimes scripts or similar are generated at build time (i.e autoconf automake) then you normally don't need add those to depends_dev. You can also just add all -dev makedepends to depends_dev but it will slow the build process a little bit (more build dependencies).}}

==== depends_doc ====
: Run-time dependency package(s) for the '''$pkgname-doc''' subpackage.

==== depends_openrc ====
: Run-time dependency package(s) for the '''$pkgname-openrc''' subpackage.

==== depends_libs ====
: Run-time dependency package(s) for the '''$pkgname-libs''' subpackage.

==== depends_static ====
: Run-time dependency package(s) for the '''$pkgname-static''' subpackage.

==== checkdepends ====
: Dependencies that are only required during the check phase, they are only installed if the check option is enabled

==== giturl ====
:Git repository from which <code>abuild checkout</code> checks out. You can checkout a specific branch in git by adding <code>-b $branch</code>.
==== install ====
: There are 6 different types of install scripts. Install scripts are named '''$pkgname.action''', where '''action''' can be: '''pre-install, post-install, pre-upgrade, post-upgrade, pre-deinstall''', or '''post-deinstall'''. For example, if ''pkgname'' is set to '''mypackage''' and ''install'' is set to '''$pkgname.post-install''', then a script named '''mypackage.post-install''' must exist along-side the APKBUILD.
<blockquote>{{Note|Always use <code>/bin/sh</code> for the command-line interpreter on the [https://en.wikipedia.org/wiki/Shebang_%28Unix%29 shebang line] of your install scripts.}}</blockquote>

The following are the different types of install scripts in detail:

===== $pkgname.pre-install =====
: This script is executed ''before installing'' the package. Typical use is when the package needs a group and a user to be created. For example:
<blockquote><pre>
#!/bin/sh

addgroup -S clamav 2>/dev/null
adduser -S -D -H -s /sbin/nologin -G clamav -g clamav clamav 2>/dev/null

exit 0
</pre>
{{Note|If the script exits with a failure (e.g., if the user already exists), the package will not be installed and <code>apk</code> will exit with failure, hence the <code>exit 0</code> at the end.}}</blockquote>

===== $pkgname.post-install =====
: This script is executed ''after installing'' the package.

===== $pkgname.pre-upgrade =====
: This script is executed ''before upgrading/downgrading/reinstalling'' the package. Note that exiting with failure will not cause apk to exit with failure, but will mark the package as broken.

===== $pkgname.post-upgrade =====
: This script is executed ''after upgrading/downgrading/reinstalling'' the package.

===== $pkgname.pre-deinstall =====
: This script is executed ''before uninstalling'' the package.
: {{Note|If the script exits with failure, <code>apk</code> will not uninstall the package.}}

===== $pkgname.post-deinstall =====
: This script is executed ''after uninstalling'' the package.

==== install_if ====
:install_if can be used when a package needs to be installed when some packages are already installed or are in the dependency tree. It works in reverse to the ''recommends'' feature, that other package managers provide.

: Typically this is used in a subpackage that should provide files which make sense with another package. For example:
<blockquote><pre>
...
subpackages="$pkgname-bash-completion:bashcomp:noarch"
...
bashcomp() {
pkgdesc="Bash completions for $pkgname"
install_if="$pkgname=$pkgver-r$pkgrel bash-completion"

install -Dm644 "$builddir"/doc/bash_completion/aria2c \
"$subpkgdir"/usr/share/bash-completion/completions/_aria2c
}
</pre>
From the aria2c APKBUILD. Note that the custom bashcomp() function is only necessary, because the files are not in /usr/share/bash-completion.
</blockquote>

:In general, install_if should only be used with '''at least one versioned constraint'''. Otherwise, a package that was implicitly installed by install_if and then removed from the binary repositories, will not get purged with <code>apk upgrade</code>. [https://gitlab.alpinelinux.org/alpine/apk-tools/-/issues/10720#note_121298]

==== license ====
: License(s) for the package, for example <code>GPL-3.0-or-later</code>, <code>BSD-2-Clause</code> or <code>MIT</code> [[Creating_an_Alpine_package#license|(details)]].

==== makedepends ====
: Build-time dependency package(s). For cross compiling support, split it into <code>makedepends_build</code> (native system) and <code>makedepends_host</code> (foreign system).

==== md5sums/sha256sums/sha512sums ====
: Checksums for the files/URLs listed in ''source''. The checksums are normally generated and updated by executing <code>abuild checksum</code> and should be the last item in the APKBUILD.

New packages should use only sha512sums.

==== options ====
: Build-time options for the package.

: {| class="wikitable"
! Option
! Description
|-
| <code>!archcheck</code>
| Do not try to verify that the architecture of the binary files is the same architecture as abuild should build for. One example where it makes sense to set this are packages with firmware files, that get executed on another CPU (such as WiFi firmware).
|-
| <code>!check</code>
| Do not try to run the <code>check()</code> function. Please always add a short comment after the <code>!check</code> about why it's disabled. [https://github.com/alpinelinux/aports/pull/2322#discussion_r142545300] Creating a very simple check function, that calls <code>program --version</code> is worse than disabling tests completely because it gives the false impression that the package is thoroughly tested with the testsuite from upstream. [https://github.com/alpinelinux/aports/pull/7326#discussion_r278797457]
|-
| <code>checkroot</code>
| Specifies that the package's test suite will be run in ''fakeroot''. This is necessary for some test suites which fail when run as non-root.
|-
| <code>net</code>
| Allows network access when run in ''rootbld''.
|-
| <code>!strip</code>
| Avoid stripping symbols from binaries.
|-
| <code>suid</code>
| Allow [https://en.wikipedia.org/wiki/Setuid setuid] binaries.
|-
| <code>!tracedeps</code>
| Do not automatically find dependencies (e.g. by using <code>ldd</code> to find dynamic libraries, which the resulting binary links against).
|-
| <code>chmod-clean</code>
| Make all files writable in the src/ directory. Useful for packages that make files read-only in the process of building packages (go modules).
|-
| <code>toolchain</code>
| Don't warn when g++ is in makedepends
|-
| <code>!dbg</code>
| Don't create debugging subpackage
|-
| <code>ldpath-recursive</code>
| Scan directories recursively when creating .so providers
|-
| <code>!spdx</code>
| Do not check if the license= field has a SPDX compliant license
|-
| <code>textrels</code>
| Don't error out when text relocations are found
|-
| <code>charset.alias</code>
| Don't error out if /usr/lib/charset.alias is found
|-
| <code>libtool</code>
| Don't delete libtool .la files
|-
| <code>!fhs</code>
| Don't enforce checks on path that follow the FHS
|}

==== pkgdesc ====
: A brief, one-line description of what the package does.

: Here's an example from the OpenSSH client package:
: <pre>pkgdesc="Port of OpenBSD's free SSH release - client"</pre>
==== pkggroups ====
: System group(s) to be created during build-time. System group(s) should also be created in the '''[[APKBUILD Reference#.24pkgname.pre-install|$pkgname.pre-install]]''' script, so that the system group(s) are also created prior to package installation for run-time use.
==== pkgname ====
: The name of the package. All letters should be lowercase.
: {{Note|When creating an APKBUILD of a module or library for another package, we use some common package prefixes, such as: ''lua-'', ''perl-'', ''php-'', and ''py3-''. Search aports for other common prefixes.}}

==== pkgrel ====
: Alpine package release number. Starts at 0 (zero). Always increment ''pkgrel'' when making updates to an aport; reset ''pkgrel'' to 0 (zero) when incrementing ''pkgver''.
==== pkgusers ====
: System user(s) to be created during build-time. System user(s) should also be created in the '''[[APKBUILD Reference#.24pkgname.pre-install|$pkgname.pre-install]]''' script, so that the system user(s) are also created prior to package installation for run-time use.
==== pkgver ====
: The version of the software being packaged. Format for valid versions: <code>{digit}{.digit}...{letter}{_suf{#}}...{-r#}</code> [https://git.alpinelinux.org/cgit/apk-tools/tree/src/version.c#n17]
: A Suffix <code>suf</code> in the above format can be one of the following to indicate that the release is ''less recent'' than the version without the suffix: <code>alpha</code>, <code>beta</code>, <code>pre</code>, <code>rc</code> [https://git.alpinelinux.org/cgit/apk-tools/tree/src/version.c#n75]
: These are for indicating ''more recent'' releases: <code>cvs</code>, <code>svn</code>, <code>git</code>, <code>hg</code>, <code>p</code> [https://git.alpinelinux.org/cgit/apk-tools/tree/src/version.c#n76]
: All other suffices are invalid. To package a specific git commit, the date of the commit gets appended to the latest release, e.g. <code>1.0.0_git20180204</code>.

==== provides ====
: List of package names (and optionally version info) this package provides.

: If package with a version is provided (provides='foo=1.2') apk will consider it as an alternate name and it will automatically consider the package for installation by the alternate name, and conflict with other packages having the same name, or provides.

: If version is not provided (provides='foo'), apk will consider it as virtual package name. Several package with same non-versioned provides can be installed simultaneously. However, none of them will be installed by default when requested by the virtual name - instead, error message is given and user is asked to choose which package providing the virtual name should be installed.
==== provider_priority ====
: A numeric value which is used by apk-tools to break ties when choosing a virtual package to satisfy a dependency. Higher values have higher priority. The primary use case is to specify the primary package that satisfies a virtual (provider).
==== replaces ====
: Allow this package to be installed at the same time as the listed packages, even if they have conflicting files. The files from this package will override ("take over") the conflicting files.

: This can be used to override config files with "policy packages" [https://gitlab.alpinelinux.org/alpine/apk-tools/-/commit/89d003f8c2e5a92655ee778f7bfa5c0e85ddbed4].

: Another use case is renaming packages (or moving files from one package to another): "replaces" will avoid the file conflict error that apk reports if it happens to install the new package before uninstalling the old package [https://gitlab.alpinelinux.org/alpine/apk-tools/-/issues/10724#note_132872].

: A common misconception is that "replaces" is used to replace packages (like in [https://wiki.archlinux.org/index.php/PKGBUILD#replaces PKGBUILD]). This is not the case, it is only for solving file conflicts. To let apk consider installing one package instead of another one, refer to [[#provides|provides]] (with the version).

==== replaces_priority ====
: The priority of the replaces. If multiple packages replace files of each other, then the package with the highest ''replaces_priority'' will win.

==== source ====
: The source variable is not only used to list the remote source files to fetch, it is also used to list the local files that abuild will need in order to build the apk. Examples of such local files include: init.d files, conf.d files, install files (see [[APKBUILD Reference#install|install variable]]), patches, and all other necessary files.

: Here are few things to note:

:* When you are finished adding local and/or remote files to ''source'', you can execute the following command to add their checksums to the APKBUILD file:
:: {{Cmd|abuild checksum}}
:: {{Note|When later updating the content of ''source'', or updating a file that is listed in ''source'', you must also update their checksums again with the same command.}}

:* When the remote file is hosted at SourceForge, it's best to specify the special mirrors link used by SourceForge:
:: <pre>http://downloads.sourceforge.net/software/software-$pkgver.tar.gz</pre>
:: (or similar depending on the package).

:* You can set target filename (eg 'save as...') by prefixing the URI with ''filename::''. This is useful when the remote filename is not specified in the URI (ie, does not end in '/software-1.0.tar.gz'), such as:
:: <pre>http://oss.example.org/?get=software&ver=1.0</pre>
:: or when the filename is braindead, like githubs' download tags:
:: <pre>https://github.com/software/software/archive/v$pkgver.tar.gz</pre>
:: The above two examples needs a target filename prefix:
:: <pre>$pkgname-$pkgver.tar.gz::http://oss.example.org/?get=software&ver=$pkgver</pre>
:: and:
:: <pre>$pkgname-$pkgver.tar.gz::https://github.com/software/software/archive/v$pkgver.tar.gz</pre>

:* abuild currently supports the following protocols for remote file retrieval:
:** http
:** https
:** ftp

:* abuild currently supports the following archive types/archive file extensions:
:** .tar (only in Alpine >= 2.5)
:** .tar.gz / .tgz
:** .tar.bz2
:** .tar.lz (only in Alpine >=3.7)
:** .tar.lzma
:** .tar.xz
:** .zip

:* <code>source</code> should only include variables that change often like <code>pkgver</code> or a commit ID. CI will warn you if you include <code>pkgname</code> in source. Other variables like for example <code>_pkgname</code> or <code>_pyname</code> do not belong in <code>source</code> either.

==== subpackages ====
: Subpackages built from this APKBUILD. abuild will parse this variable and try to find a subpackage split function. The split function must ''move'' files that do not belong in the main package, from ''$pkgdir'' to ''$subpkgdir''. Files and directories can also be ''copied'' from ''$startdir'' and ''$srcdir'' to ''$subpkgdir''.

: The split function can be specified in 1 of 3 different methods:
:# subpkgname:'''splitfunc'''
:# $pkgname-'''splitfunc'''
:# '''splitfunc'''

: {{Note|Split function names '''cannot''' use hyphens; use the first method above if the subpackage name contains a hyphen (-) character, like this: ''subpkg-name:subpkg_name'', where <code>subpkg-name</code> is the name of the '''subpackage''' and <code>subpkg_name</code> is the name of the '''subpackage's split function'''.}}

: {{Tip|For more information, see the [[APKBUILD_examples:Subpackages|Subpackages example]].}}

==== triggers ====
: Apk-tools can "monitor" directories and execute a trigger if any package installed/uninstalled any file in the monitored dir. The triggers are always executed after the apk action (install, uninstall, upgrade).

: The triggers are specified in the format: ''scriptname''=''pathlist'' where ''scriptname'' is the (sub)package name + .trigger suffix and pathlist is : separated list of the dirs to monitor.

: The '''triggers''' variable must include the triggers for subpackages too if they have any.

: It is possible to use wildcards (*) in the dir list.

==== url ====
: The homepage for the package. This is to help users find upstream documentation and other information regarding the package.

==== langdir ====
: Path to where the language files are located for the '''-lang''' subpackage, defaults to '''/usr/share/locale'''

==== pcprefix ====
: Prefix all provides derived from parsing pkg-config Requires: with the value in this variable, example: ''''pcprefix="foo:"''' will produce '''pc:foo:bar'''

==== sonameprefix ====
: Prefix all provides derived from parsing shared objects with the value in this variable, example: '''sonameprefix="foo"''' will produce '''so:foo:bar.so.X'''

= Functions =
{{Note|All functions that are not ''prepare()'', ''build()'', ''check()'' and ''package()'' should consider the current working directory as undefined, and should therefore use the [[APKBUILD Reference#abuild-defined_variables|abuild-defined directory variables]] to their advantage.}}

sanitycheck() -> clean()-> fetch() -> verify() -> unpack() -> prepare() -> mkusers() -> build() -> check() -> package() -> subpackages() -> language packs -> apk -> cleanup()

== abuild-defined functions ==
The following functions are provided by abuild and can be overridden, but it is strongly discouraged on code review for some functions:

==== fetch() ====
: Downloads remote sources listed in ''source'' to ''SRCDEST'' (''SRCDEST'' is configured in ''/etc/abuild.conf'') and creates symlinks in ''$srcdir''.
==== unpack() ====
: unpack() will call default_unpack().

: [https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L403 default_unpack()] unpacks .tar, .tgz, .tar.gz, .tar.lz (only available in Alpine >=3.7), .tar.bz2, .tar.lzma, .tar.xz, and .zip archives from a symlink in ''$srcdir'' associated with ''$SRCDEST'' (or distfiles folder) resulting in an unpacked folder in ''$srcdir''.

==== dev() ====
: Subpackage function for the '''$pkgname-dev''' package is used to collect developer files and folders for use in other packages in the compilation process nothing more. Without specifying a custom ''dev()'' function, abuild will call its internal ''dev()'' function, which in turn calls default_dev().

: ''[https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L1605 default_dev()]'' will move any ''include'' folder and folders containing ''*.[acho]'' (static archive, c source, c header file, object file), ''*.prl'' file extension patterns in ''"$pkgdir"/{lib,usr}'' to ''"$subpkgdir"/{lib,usr}'' recursively; and ''*.so'' files from ''"$pkgdir"/{lib,usr/lib}'' to ''"$subpkgdir"/{lib,usr/lib}''. It will also scan and move ''usr/{include,lib/{pkgconfig,cmake,qt*/mkspecs},share/{aclocal,gettext,vala/vapi,gir-[0-9]*,qt*/mkspecs},bin/*-config}}'' developer only folders in ''$pkgdir'' and transfer them to ''$subpkgdir''.

: In general, default_dev() will support packages that share pkg-config, C programming language API, shared and static libraries, Autotools, gettext, Vala programming language bindings, Python GObject introspection, a provided custom pkg-config like command (*-config), Qt, and CMake. If you have packages that have C++, other languages, other build system, etc; you need to manually move those developer files only if they are to be used in other packages.

: '''Important''': For default_dev() to be called as in no dev(), you need to explicitly add subpackages="$pkgname-dev".

==== doc() ====
: Subpackage function for the '''$pkgname-doc''' package whose job is only to collect documentation folders from $pkgdir nothing more. Without specifying a custom ''doc()'' function, abuild will call its internal ''doc()'' function, which in turn calls default_doc().

: ''[https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L1519 default_doc()]'' will move ''"$pkgdir"/usr/share/{doc,man,info,html,sgml,licenses,gtk-doc,ri,help}'' to ''$subpkgdir''.

: Overriding this function is strongly discouraged. Packaging docs should be done in the package() function while letting abuild automatically collect the doc folders.

: '''Important''': For default_doc() to be called as in no doc(), you need to explicitly add subpackages="$pkgname-doc".

==== openrc() ====
: Subpackage function for the '''$pkgname-openrc''' package whose job is to collect OpenRC service files that are in /etc/init.d and /etc/conf.d.

: ''[https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L1661 default_openrc()]'' will move ''"$pkgdir"/etc/{conf,init}.d'' to ''$subpkgdir''.

: Overriding this function is strongly discouraged. Packaging OpenRC service definitions should be in the package() function while letting abuild automatically collect the openrc folders.

: '''Important''': for default_openrc() to be called as in no openrc(), you need to explicitly add subpackages="$pkgname-openrc".

==== static() ====
: Subpackage function for the '''$pkgname-static''' package whose job is to collect static libraries that are stored in /lib and /usr/lib.

: ''[https://github.com/alpinelinux/abuild/blob/v3.4.0_rc4/abuild.in#L1748 default_static()]'' will move all static libraries (files ending with .a) from ''"$pkgdir"/lib'' and ''"$pkgdir"/usr/lib'' to their equivalents in ''$subpkgdir''.

: Overriding this function is strongly discouraged. Packaging static libraries should be done in the package() function while letting abuild automatically collect the static libraries.

: '''Important''': for default_static() to be called as in no static(), you need to explicitly add subpackages="$pkgname-static".

==== snapshot() ====
: '''Optional'''. For live APKBUILDs or those with a _cvs, _svn, _git, _hg in their version number, you should create a snapshot function only if there is no download link to an archive file (.zip, .tar.gz, ...) to the commit/hash/tag. The purpose of the snapshot function is to create an archive of the source code so that the package source code is deterministic, and it doesn't waste time to fetch the source code but bypasses the download step after snapshotting. Those that download the source code from a git repository will follow head or the latest change to the source code. It is better to archive the source code as a zip / tar.gz / tar.bz2 up to the commit or the tag which you are trying to build a package. If it is not deterministic or not every part of the code frozen in time for every dependency and the main project, then the patches will fail or the package may fail to compile when you revisit the package months or years to backport a patch.

: The default [https://github.com/alpinelinux/abuild/blob/v3.1.0/abuild.in#L2310 snapshot()] function has variables associated with it:
:* $disturl - the base-url of the place to autoupload the snapshot
:* $svnurl - Subversion repository
:* $giturl - Git repository

: The default snapshot() can only support one repository. It is better to override it if there are multiple repositories involved in your package. CVS, Mercurial (hg), and alternative version control systems must override the default snapshot().

: See [[APKBUILD_examples:Git_checkout]] to how to use it with git. It takes 2-3 general steps. Clone the repository; check it out at a specific revision/commit or tag; then you use an archiver to dump it in the ''$SRCDEST'' variable which points to the distfiles folder and the base path to the full path to the archive that you want to create. You do this for every internal dependency that the package pulls.

: After you have created your snapshot function, you use <code>abuild snapshot</code> to run it.

: The archives produced by the snapshot will be saved in ''/var/cache/distfiles'' or whatever you set for ''$SRCDEST''. You may need to create symlinks to the archive if the archive is not saved to the Alpine server.

: After you snapshot it, you need to produce the checksums with <code>abuild checksum</code> to use it in the APKBUILD creation process.

: This feature is available since Alpine >=2.6.

==== default_prepare() ====

: Before build preparation it handles set of patches inside <code>$srcdir</code> and prints failed ones.

== User-defined functions ==
The following functions should be defined by the user:

==== prepare() ====
: {{note|Please adjust old APKBUILDs, which still have a ''prepare()'' function that does the same as the ''default_prepare()'' when you edit them anyway.}}
: '''''Optional''.''' Used for build preparation: patches, etc, should be applied here. When you don't specify a custom ''prepare()'', the built-in ''default_prepare()'' from abuild will be used. It applies patches already (always prepare them in the <code>-p1</code> format), so '''usually it makes sense to not create a custom ''prepare()'' function at all!''' If you do create one, call ''default_prepare()'' inside it:

: Before default_prepare gets called, you can define ''patch_args'' to supply the argument to the patch command in global scope then throw away prepare() so it is unnecessary to use the old template code floating around to patch. patch_args and autopatching is only available in Alpine >=3.4. See [[Creating_an_Alpine_package#Patches]] to fix the patch that uses a different patch level (-pX).

<pre>
prepare() {
default_prepare
# your custom code here
}
</pre>

==== build() ====
: '''Required.''' This is the compilation stage. This function will be called as the current user (unless the ''package()'' function is missing - for compatibility reasons). If no compilation is needed, the function should be removed.

: To enable or disable CFLAGS, CXXFLAGS, CMake with option, or configure option per arch, use the CARCH variable:
<pre>
local cmakeoptions=
case "$CARCH" in
aarch64*|arm*|ppc64le|x86|s390x) cmakeoptions="$cmakeoptions -DWITH_OPENMP=OFF" ;;
x86_64) cmakeoptions="$cmakeoptions -DWITH_OPENMP=ON" ;;
*) msg "Unable to determine architecture from (CARCH=$CARCH)" ; return 1 ;;
esac
</pre>
: The block can be used in other parts of the APKBUILD even in global.

==== check() ====
: '''Required if functionality exists.''' This function is called right after the build stage. It should check that the packaged thing is actually working, typically by running (integration) tests, if provided by upstream. If there’s no (easy) way how to test the package, you can declare that it does not want to use ''check()'' by adding "!check" into the ''options'' variable (<code>options="!check"</code>).

: default_check() does nothing. You need to manually explicitly call the unit tests or test suite yourself. When you run the test, the program should return with an exit code of 0, indicating the tests were a success. Unit tests or test suites will do feature tests, per function correctness check, fuzz testing, benchmarks.

: A package may also require additional testing frameworks packages that are external dependencies. You should add those to the ''checkdepends='' in Alpine >=3.6 or ''makedepends='' for older for backporters. If the testing framework is not available, you need to create a package for it. If it requires a specific version of a testing framework, consider making it an internal dependency or a new package with a package name containing the major and minor version number like the python packages.

: Generally speaking, you should define the check functions for libraries, large programs like web browsers, or compilers and interpreters, cryptographic/security/anonymity stuff, mission critical stuff, PCI compliance/money/accounting software, server software with a lot of stakeholders or consumers. Soon for the new policy change will have virtually '''all packages with testing capabilities be required to have a working and defined check() function'''.

: There are times when the unit tests do not work, just because the test itself is broken, new unimplemented feature, external factors not taken into consideration, unbundling path differences, breakage caused by ccache, missing test dependency or version mismatch dependency as in python2 vs python3, test scripts only work for particular language implementation like only supporting python2 but not python3 having used the 2to3 conversion script. If a unit test is known not to work, you may need to patch it to omit that test or fix it; but, certain tests should not be disabled if it is important. You may need to alter the references to uncompiled internal dependencies to work with the external dependencies instead. For ccache, you can either disable it or remove it from the PATH environmental variable before running tests.

{{Note|Tests for graphical applications and toolkits might work on a X11 user setup but will fail on the server unless run with xvfb-run.}}

: If you don't add the ''check()'' and the ''options='', this is what you will see:

>>> WARNING: py-webtest*: APKBUILD does not run any tests!
Alpine policy will soon require that packages have any relevant testsuites run during the build process.
To fix, either define a check() function, or declare !check in $options to indicate the package does not have a testsuite.

: If you do not do a check or disable it, you must state there is no testsuite in comment form (#) next to options="!check" for the code reviewers.

: To run test suite with autotools do:

make check

: To run the test suite with python setuptools:

python2 setup.py test
python3 setup.py test

: For python it should be '''test''' not check. Check for python setuptools will check the packaging metadata fields[https://docs.python.org/3/distutils/examples.html#checking-a-package] only but not run the unit tests. There should be verbose output also. The dependencies for the tests are found in test_require in the setup.py.

: If it says <code>Ran 0 tests in 0.000s</code> that is not acceptable. check() will say it was good but it is not actually correct. It needs to run the test suite with an alternative method like <code>tox -e py27,py36</code> if you see a tox.ini file.

: You want to do it for each implementation to ensure that the API calls are correct per implementation but ncopa said it was just fine with python3.

: If there is a circular dependency for the checkdepends=, you need to disable the check and put the reason next to <code>options="!check"</code> that there is a circular dependency. You should disable it for the package that package that is least important or least security risk. The other solution is to make the conflicting dependency an internal dependency but making sure that it doesn't pull it at check time. This way they can both preform tests properly.

==== package() ====
: '''Required.''' This is the packaging stage. Here, the built application and support files should be installed into '''$pkgdir'''. If this is a metapackage, this function can contain a single line: <code>mkdir -p "$pkgdir"</code>

{{Note|Building in fakeroot will reduce performance for parallel builds dramatically. It is for this reason that we split the build and package process into two separate functions.}}

= Special Operators =

== $pkgname~$pkgver ==

Specifies a required <code>$pkgver</code> for [[apk]] to satisfy the <code>$pkgname</code> requirement. <code>~</code> ignores revisions of the package version. For example <code>superd~0.6</code> in <code>$depends</code> will ensure superd with package version 0.6 is installed as a run-time dependency for the package.

== $pkgname>=$pkgver ==

Specifies the installed package version must be greater than or equal to <code>$pkgver</code> for [[apk]] to satisfy the <code>$pkgname</code> requirement.

= Examples =
The [[APKBUILD examples]] page will assist you in understanding how to create an APKBUILD.

= Version =

This document assumes abuild for Alpine Edge. For older releases of abuild, some of these features may not be available if you are using an older release. A link to the implementation is linked for researchers and backporters.

For more information see [[APKBUILD_versions]].

[[Category:Development]]

Alpine Linux:Listings

2024-10-26T18:21:34Z

Sertonix: Update link to Alpine Suck

{{TOC right}}

{{Draft}}

== Alpine Linux Dedicated Pages ==

These are official and unofficial '''Alpine Linux''' pages around the web.

===Social Media Pages===

* [https://twitter.com/alpinelinux Twitter]
* [https://fosstodon.org/@alpinelinux Mastodon (on fosstodon.org)]
* [https://br.linkedin.com/groups/Alpine-Linux-6648617 LinkedIn Group]
* [https://old.reddit.com/r/alpinelinux /r/alpinelinux on Reddit]

===Other Pages===

* [https://en.wikipedia.org/wiki/Alpine_Linux Wikipedia article]
* [https://distrowatch.com/table.php?distribution=alpine Distrowatch entry]
* [https://openhub.net/p/aports Black Duck Open Hub] (aports statistics)
* [http://iso.linuxquestions.org/alpine-linux/ Linux Questions ISO links]
* [https://web.archive.org/web/20171125113042/https://blog.xenproject.org/2013/03/04/alpine-linux-and-xen/ Xen.org article] about Xen and Alpine Linux.
* [https://github.com/alpinelinux/ GitHub organization]
* [https://stackoverflow.com/questions/tagged/alpine Alpine Linux tag on StackOverflow]

== Reviews and other Articles ==

* [https://distrowatch.com/weekly.php?issue=20230403#alpine Alpine Linux 3.17.2 Review] by Jesse Smith for DistroWatch (published 2023-04-03 [https://web.archive.org/web/20230809174002/https://distrowatch.com/weekly.php?issue=20230403#alpine:~:text=Feature%20Story%20(by%20Jesse%20Smith) archive])
* [https://whynothugo.nl/journal/2023/02/18/in-praise-of-alpine-and-apk/ In praise of Alpine and apk] by Hugo Barrera (published 2023-02-18)
** See also [https://sr.ht/~bt/alpine-suck/ Alpine Suck] Desktop installer for Alpine Linux based on the suckless philosophy
* [https://drewdevault.com/2021/05/06/Praise-for-Alpine-Linux.html In praise of Alpine Linux] by Drew DeVault (published 2021-05-06)
* [https://archive.is/F4ZSa Alpine Linux 2 Review] by LinuxBSDos (published 2010-08-23)
* [https://linuxlandit.blogspot.com/2010/08/alpine-linux-is-community-developed.html Alpine Linux is a community developed operating system [...]] by Linuxlandit & The Conqueror Penguin (published 2010-08-22)

== YouTube Videos ==

* [https://www.youtube.com/watch?v=YNYtJ3jyMRs Installing Alpine Linux as a Desktop OS by Trafotin]

== Lists that include Alpine ==

* [https://en.wikipedia.org/wiki/Lightweight_Linux_distribution Lightweight Linux Distributions]
* [https://en.wikipedia.org/wiki/List_of_Linux_distributions_that_run_from_RAM Distributions that run from RAM]
* [https://en.wikipedia.org/wiki/List_of_router_or_firewall_distributions Router or Firewall Distributions]
* [https://en.wikipedia.org/wiki/Security-focused_operating_system#Alpine_Linux Security-focused Distributions]
* [https://en.wikipedia.org/wiki/PaX#Distributions_that_use_PaX Distributions that use PaX]

== Hosting Providers ==

* [https://www.gigatux.com/distro/alpine_linux_vps GigaTux]
* [https://linode.com Linode]
* [https://vpsfree.cz/ vpsFree.cz]

User:Sertonix/Freedom of choice

2024-10-08T22:42:03Z

Sertonix: update status of openrc-init

This is an overview over the different available programms, etc. that can be selected from when using alpine. It is also intended as a reference what should be documented and what could be supported.

== Bootloaders ==
* See: [[Bootloaders]]
* Not supported: <code>systemd-boot</code> ([https://pkgs.postmarketos.org/packages?name=systemd-boot PostmarketOS does])

== Kernel ==
* See: [[Kernels]]

== Libc ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|musl}} || style="background:lime" | Full || Default
|-
| [https://www.gnu.org/software/libc/ glibc] || style="background:red" | None || [[Running glibc programs]]
|-
| without aka static || style="background:orange" | depends on package || Note that this only means no libc at runtime
|}
* See also: [https://gitlab.alpinelinux.org/alpine/tsc/-/issues/17 alpine-glibc]
* See also: [https://wiki.gentoo.org/wiki/Libc Gentoo Wiki]

== Initramfs ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|mkinitfs}} || style="background:lime" | Full || Default
|-
| {{Pkg|dracut}} || style="background:lime" | Full ||
|-
| {{Pkg|booster}} || style="background:lime" | Full ||
|-
| [https://github.com/illiliti/tinyramfs tinyramfs] || style="background:red" | None ||
|-
| without || style="background:red" | None || may require [[custom Kernel]], [https://kisslinux.org/install#021 kisslinux without initramfs]
|}
* See also: [[Initramfs init]]
* See also: [https://wiki.gentoo.org/wiki/Initramfs Gentoo Wiki]

== PID 1 ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| busybox init || style="background:lime" | Full || Default
|-
| {{Pkg|dinit}} || style="background:orange" | In testing || Shutdown commands are prefixed with {{ic|dinit-}}. eg {{ic|dinit-reboot}}
|-
| {{Pkg|s6-linux-init}} || style="background:orange" | Works || Requires manually running {{ic|s6-linux-init-maker}}
|-
| {{Pkg|openrc-init}} || style="background:orange" | Manual setup ||
|-
| {{Pkg|dumb-init}} || style="background:silver" | Needs testing || For containers
|-
| runit-init || style="background:silver" | Needs testing || [https://dev.alpinelinux.org/~clandmeter/other/forum.alpinelinux.org/comment/383.html#comment-383 runit-init starting OpenRC]
|-
| {{Pkg|epoch}} || style="background:silver" | Needs testing ||
|-
| [https://core.suckless.org/sinit/ sinit] || style="background:red" | None ||
|-
| systemd || style="background:red" | None || Supported by postmarketOS
|-
| custom || style="background:lime" | Full || For example in docker containers
|}
* See also: [https://wiki.gentoo.org/wiki/Init_system Gentoo Wiki]
* See also: [https://wiki.archlinux.org/title/Init Archwiki]

== Service Manager ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[OpenRC]] || style="background:lime" | Full || Default
|-
| {{Pkg|dinit}} || style="background:orange" | In testing || {{Pkg|dinit-alpine}} includes service files
|-
| {{Pkg|s6-rc}} || style="background:orange" | Works || Not integrated. For containers there is {{Pkg|s6-overlay}}
|-
| {{Pkg|runit}} || style="background:orange" | As OpenRC service ||
|-
| {{Pkg|daemontools}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|daemontools-encore}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|supervisor}} || style="background:silver" | Needs testing ||
|-
| busybox runit || style="background:red" | None || Not enabled in a busybox package
|-
| [https://core.suckless.org/svc/ svc] || style="background:red" | None ||
|-
| systemd || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:lime" | Full || Requires to replace {{Pkg|alpine-base}} with custom set of packages (See {{Issue|71686}})
|}
* See also: [https://wiki.gentoo.org/wiki/Init_system Gentoo Wiki]
* See also: [https://wiki.archlinux.org/title/Init Archwiki]

== System Logs ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[Syslog#busybox_syslog|busybox syslog]] || style="background:lime" | Full || Default
|-
| {{Pkg|rsyslog}} || style="background:lime" | Full ||
|-
| {{Pkg|syslog-ng}} || style="background:lime" | Full ||
|-
| {{pkg|socklog}} || style="background:silver" | Needs testing ||
|-
| [https://skarnet.org/software/s6/s6-socklog.html s6-socklog] from {{pkg|s6}} || style="background:silver" | Needs testing ||
|-
| systemd-journald || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:silver" | Needs testing ||
|}
* See also: [[Syslog]]

== [[Device Manager]] ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[mdev]] || style="background:lime" | Full || Default
|-
| [[mdevd]] || style="background:lime" | Full ||
|-
| [[eudev]] || style="background:lime" | Full ||
|-
| [https://core.suckless.org/smdev/ smdev] || style="background:red" | None ||
|-
| vdev || style="background:red" | None ||
|-
| systemd-udev || style="background:red" | None || Supported by postmarketOS
|}

== Power Managment ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[busybox acpid]] || style="background:lime" | Full || Default
|-
| {{Pkg|acpid}} || style="background:lime" | Full ||
|-
| {{Pkg|elogind}} || style="background:silver" | Needs testing ||
|-
| systemd-logind || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:lime" | Full ||
|}
* See also: [https://wiki.archlinux.org/title/Power_management Archwiki]
* See also: [https://wiki.gentoo.org/wiki/Power_management Gentoo Wiki]

== DHCP Client ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[Udhcpc|busybox udhcpc]] || style="background:lime" | Full || Default
|-
| {{Pkg|dhcpcd}} || style="background:lime" | Full ||
|-
| {{Pkg|dhclient}} || style="background:lime" | Full ||
|-
| [https://core.suckless.org/sdhcp/ sdhcp] || style="background:red" | None ||
|-
| without aka static || style="background:lime" | Full ||
|}
* See also: [[Configure Networking]]
* See also: [https://wiki.archlinux.org/title/Network_configuration#DHCP Archwiki]
* See also: [https://wiki.gentoo.org/wiki/Resolv.conf Gentoo Wiki - resolv.conf]

== Wi-Fi ==
* See: [[Wi-Fi]]
* Also supported: {{pkg|eiwd}}

== Seat/Session Managnent ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[elogind]] || style="background:lime" | Full ||
|-
| {{Pkg|seatd}} || style="background:lime" | Full || seats only
|-
| {{Pkg|turnstile}} || style="background:silver" | needs testing || session only
|-
| systemd-logind || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:lime" | Full || Not recommended with graphical enviroment
|}
* [https://wiki.gentoo.org/wiki/Seatd Gentoo Wiki - seatd]
* [https://wiki.gentoo.org/wiki/Elogind Gentoo Wiki - elogind]
* [https://wiki.archlinux.org/title/Init#logind ArchWiki - systemd-logind]
* [https://chimera-linux.org/docs/configuration/seat Chimera Linux docs]

== Login ==

{| class="wikitable"
|-
! Name !! Support !! Supports [[PAM]] !! Notes
|-
| busybox login || style="background:lime" | Full || style="background:red" | No || Default
|-
| {{Pkg|greetd}} || style="background:lime" | Full || style="background:lime" | Yes || requires greeter
|-
| {{Pkg|shadow-login}} || style="background:lime" | Full || style="background:lime" | Yes ||
|-
| {{Pkg|util-linux-login}} || style="background:lime" | Full || style="background:lime" | Yes ||
|-
| systemd-logind || style="background:red" | None || style="background:lime" | Yes || Supported by postmarketOS
|-
| without || style="background:lime" | Full || style="background:red" | No ||
|}
* See also: [https://wiki.gentoo.org/wiki/Login Gentoo Wiki]

== Shell Utils ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|busybox}} || style="background:lime" | Full || Dependency of {{pkg|alpine-base}}
|-
| {{Pkg|busybox-extras}} || style="background:lime" | Full || Some commands that are missing in the main {{Pkg|busybox}} package
|-
| {{Pkg|util-linux}} || style="background:lime" | Full ||
|-
| [[GNU_core_utilities|coreutils]] || style="background:lime" | Full ||
|-
| {{Pkg|s6-portable-utils}} || style="background:lime" | Full ||
|-
| {{Pkg|s6-linux-utils}} || style="background:lime" | Full ||
|-
| {{Pkg|toybox}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|sbase}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|ubase}} || style="background:silver" | Needs testing ||
|-
| without || style="background:red" | None || A lot of implicit dependency
|}
* See also: [https://wiki.archlinux.org/title/Core_utilities Archwiki]

== Shell ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| busybox ash || style="background:lime" | Full || Default
|-
| {{Pkg|bash}} || style="background:lime" | Full ||
|-
| {{Pkg|dash}} || style="background:lime" | Full || When used as /bin/sh this may cause breakage.
|-
| {{Pkg|yash}} || style="background:lime" | Full ||
|-
| busybox hush || style="background:red" | None ||
|-
| without || style="background:red" | None || sometimes implicit dependency
|}
* See also: [[Change default shell]]
* See proposal: [https://gitlab.alpinelinux.org/alpine/tsc/-/issues/39 replace busybox ash with another /bin/sh]
* See also: [https://wiki.archlinux.org/title/Command-line_shell Archwiki]
* See also: [https://wiki.gentoo.org/wiki/Shell Gentoo Wiki]

== SU ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{ic|su}} from {{Pkg|busybox-suid}} || style="background:lime" | Full || default, can't be removed by default ({{issue|11730}})
|-
| {{ic|su}} from {{Pkg|shadow-login}} || style="background:lime" | Full ||
|-
| {{ic|su}} from {{Pkg|util-linux-login}} || style="background:lime" | Full ||
|-
| {{Pkg|sudo}} || style="background:lime" | Full ||
|-
| {{Pkg|doas}} || style="background:lime" | Full || sudo shim using doas: {{Pkg|doas-sudo-shim}}
|-
| [https://skarnet.org/software/s6/s6-sudo.html s6-sudo] || style="background:silver" | Needs testing ||
|-
| without || style="background:lime" | Full ||
|}

== SSL/TLS ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|openssl}} || style="background:lime" | Full || Default
|-
| {{Pkg|libressl}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|bearssl}} || style="background:silver" | Needs testing ||
|}
* See also: [https://gitlab.alpinelinux.org/alpine/tsc/-/issues/28 consider LibreSSL as default OpenSSL provider again]
* See also: [https://wiki.archlinux.org/title/Transport_Layer_Security Archwiki]
* See also: [https://github.com/haproxy/wiki/wiki/SSL-Libraries-Support-Status haproxy SSL Libraries Support Status]

== Cron ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|cronie}} || style="background:lime" | Full ||
|-
| {{Pkg|dcron}} || style="background:lime" | Full ||
|-
| {{Pkg|fcron}} || style="background:lime" | Full ||
|-
| vixie-cron || style="background:red" | None ||
|-
| scron || style="background:red" | None ||
|-
| systemd.timer || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:lime" | Full || {{Pkg|alpine-baselayout}} includes cron specific directories though
|}
* See also: [https://wiki.archlinux.org/title/Cron Archwiki]
* See also: [https://wiki.gentoo.org/wiki/Cron Gentoo Wiki]

== SSH ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[Setting_up_a_SSH_server#OpenSSH|openssh]] || style="background:lime" | Full ||
|-
| [[Setting_up_a_SSH_server#Dropbear|dropbear]] || style="background:lime" | Full || provide {{ic|ssh}} command {{pkg|dropbear-ssh}}
|-
| without || style="background:lime" | Full ||
|}
* See also: [https://wiki.archlinux.org/title/Secure_Shell Archwiki]
* See also: [https://wiki.gentoo.org/wiki/SSH Gentoo Wiki - OpenSSH]
* See also: [https://wiki.gentoo.org/wiki/Dropbear Gentoo Wiki - Dropbear]

== Desktop ==
* See: [[Desktop environments and Window managers]]

== See Also ==
* [[Architecture|Alpine Architecture]]
* [https://gitlab.alpinelinux.org/alpine/tsc/-/issues/55 Future of busybox]

User:Sertonix/Freedom of choice

2024-09-28T22:12:21Z

Sertonix: a few updates

This is an overview over the different available programms, etc. that can be selected from when using alpine. It is also intended as a reference what should be documented and what could be supported.

== Bootloaders ==
* See: [[Bootloaders]]
* Not supported: <code>systemd-boot</code> ([https://pkgs.postmarketos.org/packages?name=systemd-boot PostmarketOS does])

== Kernel ==
* See: [[Kernels]]

== Libc ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|musl}} || style="background:lime" | Full || Default
|-
| [https://www.gnu.org/software/libc/ glibc] || style="background:red" | None || [[Running glibc programs]]
|-
| without aka static || style="background:orange" | depends on package || Note that this only means no libc at runtime
|}
* See also: [https://gitlab.alpinelinux.org/alpine/tsc/-/issues/17 alpine-glibc]
* See also: [https://wiki.gentoo.org/wiki/Libc Gentoo Wiki]

== Initramfs ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|mkinitfs}} || style="background:lime" | Full || Default
|-
| {{Pkg|dracut}} || style="background:lime" | Full ||
|-
| {{Pkg|booster}} || style="background:lime" | Full ||
|-
| [https://github.com/illiliti/tinyramfs tinyramfs] || style="background:red" | None ||
|-
| without || style="background:red" | None || may require [[custom Kernel]], [https://kisslinux.org/install#021 kisslinux without initramfs]
|}
* See also: [[Initramfs init]]
* See also: [https://wiki.gentoo.org/wiki/Initramfs Gentoo Wiki]

== PID 1 ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| busybox init || style="background:lime" | Full || Default
|-
| {{Pkg|dinit}} || style="background:orange" | In testing || Shutdown commands are prefixed with {{ic|dinit-}}. eg {{ic|dinit-reboot}}
|-
| {{Pkg|s6-linux-init}} || style="background:orange" | Works || Requires manually running {{ic|s6-linux-init-maker}}
|-
| {{Pkg|dumb-init}} || style="background:silver" | Needs testing || For containers
|-
| runit-init || style="background:silver" | Needs testing || [https://dev.alpinelinux.org/~clandmeter/other/forum.alpinelinux.org/comment/383.html#comment-383 runit-init starting OpenRC]
|-
| {{Pkg|epoch}} || style="background:silver" | Needs testing ||
|-
| openrc-init || style="background:red" | None || Is excluded from the {{pkg|openrc}} package
|-
| [https://core.suckless.org/sinit/ sinit] || style="background:red" | None ||
|-
| systemd || style="background:red" | None || Supported by postmarketOS
|-
| custom || style="background:lime" | Full || For example in docker containers
|}
* See also: [https://wiki.gentoo.org/wiki/Init_system Gentoo Wiki]
* See also: [https://wiki.archlinux.org/title/Init Archwiki]

== Service Manager ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[OpenRC]] || style="background:lime" | Full || Default
|-
| {{Pkg|dinit}} || style="background:orange" | In testing || {{Pkg|dinit-alpine}} includes service files
|-
| {{Pkg|s6-rc}} || style="background:orange" | Works || Not integrated. For containers there is {{Pkg|s6-overlay}}
|-
| {{Pkg|runit}} || style="background:orange" | As OpenRC service ||
|-
| {{Pkg|daemontools}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|daemontools-encore}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|supervisor}} || style="background:silver" | Needs testing ||
|-
| busybox runit || style="background:red" | None || Not enabled in a busybox package
|-
| [https://core.suckless.org/svc/ svc] || style="background:red" | None ||
|-
| systemd || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:lime" | Full || Requires to replace {{Pkg|alpine-base}} with custom set of packages (See {{Issue|71686}})
|}
* See also: [https://wiki.gentoo.org/wiki/Init_system Gentoo Wiki]
* See also: [https://wiki.archlinux.org/title/Init Archwiki]

== System Logs ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[Syslog#busybox_syslog|busybox syslog]] || style="background:lime" | Full || Default
|-
| {{Pkg|rsyslog}} || style="background:lime" | Full ||
|-
| {{Pkg|syslog-ng}} || style="background:lime" | Full ||
|-
| {{pkg|socklog}} || style="background:silver" | Needs testing ||
|-
| [https://skarnet.org/software/s6/s6-socklog.html s6-socklog] from {{pkg|s6}} || style="background:silver" | Needs testing ||
|-
| systemd-journald || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:silver" | Needs testing ||
|}
* See also: [[Syslog]]

== [[Device Manager]] ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[mdev]] || style="background:lime" | Full || Default
|-
| [[mdevd]] || style="background:lime" | Full ||
|-
| [[eudev]] || style="background:lime" | Full ||
|-
| [https://core.suckless.org/smdev/ smdev] || style="background:red" | None ||
|-
| vdev || style="background:red" | None ||
|-
| systemd-udev || style="background:red" | None || Supported by postmarketOS
|}

== Power Managment ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[busybox acpid]] || style="background:lime" | Full || Default
|-
| {{Pkg|acpid}} || style="background:lime" | Full ||
|-
| {{Pkg|elogind}} || style="background:silver" | Needs testing ||
|-
| systemd-logind || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:lime" | Full ||
|}
* See also: [https://wiki.archlinux.org/title/Power_management Archwiki]
* See also: [https://wiki.gentoo.org/wiki/Power_management Gentoo Wiki]

== DHCP Client ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[Udhcpc|busybox udhcpc]] || style="background:lime" | Full || Default
|-
| {{Pkg|dhcpcd}} || style="background:lime" | Full ||
|-
| {{Pkg|dhclient}} || style="background:lime" | Full ||
|-
| [https://core.suckless.org/sdhcp/ sdhcp] || style="background:red" | None ||
|-
| without aka static || style="background:lime" | Full ||
|}
* See also: [[Configure Networking]]
* See also: [https://wiki.archlinux.org/title/Network_configuration#DHCP Archwiki]
* See also: [https://wiki.gentoo.org/wiki/Resolv.conf Gentoo Wiki - resolv.conf]

== Wi-Fi ==
* See: [[Wi-Fi]]
* Also supported: {{pkg|eiwd}}

== Seat/Session Managnent ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[elogind]] || style="background:lime" | Full ||
|-
| {{Pkg|seatd}} || style="background:lime" | Full || seats only
|-
| {{Pkg|turnstile}} || style="background:silver" | needs testing || session only
|-
| systemd-logind || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:lime" | Full || Not recommended with graphical enviroment
|}
* [https://wiki.gentoo.org/wiki/Seatd Gentoo Wiki - seatd]
* [https://wiki.gentoo.org/wiki/Elogind Gentoo Wiki - elogind]
* [https://wiki.archlinux.org/title/Init#logind ArchWiki - systemd-logind]
* [https://chimera-linux.org/docs/configuration/seat Chimera Linux docs]

== Login ==

{| class="wikitable"
|-
! Name !! Support !! Supports [[PAM]] !! Notes
|-
| busybox login || style="background:lime" | Full || style="background:red" | No || Default
|-
| {{Pkg|greetd}} || style="background:lime" | Full || style="background:lime" | Yes || requires greeter
|-
| {{Pkg|shadow-login}} || style="background:lime" | Full || style="background:lime" | Yes ||
|-
| {{Pkg|util-linux-login}} || style="background:lime" | Full || style="background:lime" | Yes ||
|-
| systemd-logind || style="background:red" | None || style="background:lime" | Yes || Supported by postmarketOS
|-
| without || style="background:lime" | Full || style="background:red" | No ||
|}
* See also: [https://wiki.gentoo.org/wiki/Login Gentoo Wiki]

== Shell Utils ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|busybox}} || style="background:lime" | Full || Dependency of {{pkg|alpine-base}}
|-
| {{Pkg|busybox-extras}} || style="background:lime" | Full || Some commands that are missing in the main {{Pkg|busybox}} package
|-
| {{Pkg|util-linux}} || style="background:lime" | Full ||
|-
| [[GNU_core_utilities|coreutils]] || style="background:lime" | Full ||
|-
| {{Pkg|s6-portable-utils}} || style="background:lime" | Full ||
|-
| {{Pkg|s6-linux-utils}} || style="background:lime" | Full ||
|-
| {{Pkg|toybox}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|sbase}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|ubase}} || style="background:silver" | Needs testing ||
|-
| without || style="background:red" | None || A lot of implicit dependency
|}
* See also: [https://wiki.archlinux.org/title/Core_utilities Archwiki]

== Shell ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| busybox ash || style="background:lime" | Full || Default
|-
| {{Pkg|bash}} || style="background:lime" | Full ||
|-
| {{Pkg|dash}} || style="background:lime" | Full || When used as /bin/sh this may cause breakage.
|-
| {{Pkg|yash}} || style="background:lime" | Full ||
|-
| busybox hush || style="background:red" | None ||
|-
| without || style="background:red" | None || sometimes implicit dependency
|}
* See also: [[Change default shell]]
* See proposal: [https://gitlab.alpinelinux.org/alpine/tsc/-/issues/39 replace busybox ash with another /bin/sh]
* See also: [https://wiki.archlinux.org/title/Command-line_shell Archwiki]
* See also: [https://wiki.gentoo.org/wiki/Shell Gentoo Wiki]

== SU ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{ic|su}} from {{Pkg|busybox-suid}} || style="background:lime" | Full || default, can't be removed by default ({{issue|11730}})
|-
| {{ic|su}} from {{Pkg|shadow-login}} || style="background:lime" | Full ||
|-
| {{ic|su}} from {{Pkg|util-linux-login}} || style="background:lime" | Full ||
|-
| {{Pkg|sudo}} || style="background:lime" | Full ||
|-
| {{Pkg|doas}} || style="background:lime" | Full || sudo shim using doas: {{Pkg|doas-sudo-shim}}
|-
| [https://skarnet.org/software/s6/s6-sudo.html s6-sudo] || style="background:silver" | Needs testing ||
|-
| without || style="background:lime" | Full ||
|}

== SSL/TLS ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|openssl}} || style="background:lime" | Full || Default
|-
| {{Pkg|libressl}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|bearssl}} || style="background:silver" | Needs testing ||
|}
* See also: [https://gitlab.alpinelinux.org/alpine/tsc/-/issues/28 consider LibreSSL as default OpenSSL provider again]
* See also: [https://wiki.archlinux.org/title/Transport_Layer_Security Archwiki]
* See also: [https://github.com/haproxy/wiki/wiki/SSL-Libraries-Support-Status haproxy SSL Libraries Support Status]

== Cron ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|cronie}} || style="background:lime" | Full ||
|-
| {{Pkg|dcron}} || style="background:lime" | Full ||
|-
| {{Pkg|fcron}} || style="background:lime" | Full ||
|-
| vixie-cron || style="background:red" | None ||
|-
| scron || style="background:red" | None ||
|-
| systemd.timer || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:lime" | Full || {{Pkg|alpine-baselayout}} includes cron specific directories though
|}
* See also: [https://wiki.archlinux.org/title/Cron Archwiki]
* See also: [https://wiki.gentoo.org/wiki/Cron Gentoo Wiki]

== SSH ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[Setting_up_a_SSH_server#OpenSSH|openssh]] || style="background:lime" | Full ||
|-
| [[Setting_up_a_SSH_server#Dropbear|dropbear]] || style="background:lime" | Full || provide {{ic|ssh}} command {{pkg|dropbear-ssh}}
|-
| without || style="background:lime" | Full ||
|}
* See also: [https://wiki.archlinux.org/title/Secure_Shell Archwiki]
* See also: [https://wiki.gentoo.org/wiki/SSH Gentoo Wiki - OpenSSH]
* See also: [https://wiki.gentoo.org/wiki/Dropbear Gentoo Wiki - Dropbear]

== Desktop ==
* See: [[Desktop environments and Window managers]]

== See Also ==
* [[Architecture|Alpine Architecture]]
* [https://gitlab.alpinelinux.org/alpine/tsc/-/issues/55 Future of busybox]

GCC

2024-06-22T17:11:31Z

Sertonix: Remove deprecated libc-dev

[https://gcc.gnu.org/ GCC], which stands for GNU Compiler Collection, is a free, open-source compiler system produced by the [https://gnu.org/ GNU Project].

== Installation ==

The quickest way to get started with GCC on Alpine Linux is by issuing the following command:
{{cmd|# apk add {{pkg|build-base}}}}

{{pkg|build-base}} is a meta-package that will install the {{pkg|gcc}}, {{pkg|musl-dev}} and {{pkg|binutils}} packages (amongst others).

For a smaller install you may install just {{pkg|gcc}} but will also need at least {{pkg|musl-dev}}.

[[Category:Development]]

User:Sertonix/Freedom of choice

2024-06-04T12:27:03Z

Sertonix: add note about dinit shutdown commands

This is an overview over the different available programms, etc. that can be selected from when using alpine. It is also intended as a reference what should be documented and what could be supported.

== Bootloaders ==
* See: [[Bootloaders]]
* Not supported: <code>systemd-boot</code> ([https://gitlab.com/postmarketOS/pmaports/-/tree/master/main/systemd-boot PostmarketOS does])

== Kernel ==
* See: [[Kernels]]

== Libc ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|musl}} || style="background:lime" | Full || Default
|-
| [https://www.gnu.org/software/libc/ glibc] || style="background:red" | None || [[Running glibc programs]]
|-
| without aka static || style="background:orange" | depends on package || Note that this only means no libc at runtime
|}
* See also: [https://gitlab.alpinelinux.org/alpine/tsc/-/issues/17 alpine-glibc]
* See also: [https://wiki.gentoo.org/wiki/Libc Gentoo Wiki]

== Initramfs ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|mkinitfs}} || style="background:lime" | Full || Default
|-
| {{Pkg|dracut}} || style="background:lime" | Full ||
|-
| {{Pkg|booster}} || style="background:lime" | Full ||
|-
| [https://github.com/illiliti/tinyramfs tinyramfs] || style="background:red" | None ||
|-
| without || style="background:red" | None || may require [[custom Kernel]], [https://kisslinux.org/install#021 kisslinux without initramfs]
|}
* See also: [[Initramfs init]]
* See also: [https://wiki.gentoo.org/wiki/Initramfs Gentoo Wiki]

== PID 1 ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| busybox init || style="background:lime" | Full || Default
|-
| {{Pkg|dinit}} || style="background:orange" | In testing || Shutdown commands are prefixed with {{ic|dinit-}}. eg {{ic|dinit-reboot}}
|-
| {{Pkg|s6-linux-init}} || style="background:orange" | Works || Not integrated
|-
| {{Pkg|dumb-init}} || style="background:silver" | Needs testing || For containers
|-
| runit-init || style="background:silver" | Needs testing || [https://dev.alpinelinux.org/~clandmeter/other/forum.alpinelinux.org/comment/383.html#comment-383 runit-init starting OpenRC]
|-
| {{Pkg|epoch}} || style="background:silver" | Needs testing ||
|-
| openrc-init || style="background:red" | None || Is excluded from the {{pkg|openrc}} package
|-
| [https://core.suckless.org/sinit/ sinit] || style="background:red" | None ||
|-
| [https://ewontfix.com/14/ Felker init] || style="background:red" | None ||
|-
| systemd || style="background:red" | None || Supported by postmarketOS
|}
* See also: [https://wiki.gentoo.org/wiki/Init_system Gentoo Wiki]
* See also: [https://wiki.archlinux.org/title/Init Archwiki]

== Service Manager ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[OpenRC]] || style="background:lime" | Full || Default
|-
| {{Pkg|dinit}} || style="background:orange" | In testing || {{Pkg|dinit-alpine}} includes service files
|-
| {{Pkg|s6-rc}} || style="background:orange" | Works || Not integrated
|-
| {{Pkg|runit}} || style="background:orange" | As OpenRC service ||
|-
| {{Pkg|daemontools}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|daemontools-encore}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|supervisor}} || style="background:silver" | Needs testing ||
|-
| busybox runit || style="background:red" | None || Not enabled in a busybox package
|-
| [https://core.suckless.org/svc/ svc] || style="background:red" | None ||
|-
| systemd || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:red" | None ||
|}
* See also: [https://wiki.gentoo.org/wiki/Init_system Gentoo Wiki]
* See also: [https://wiki.archlinux.org/title/Init Archwiki]

== System Logs ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[Syslog#busybox_syslog|busybox syslog]] || style="background:lime" | Full || Default
|-
| {{Pkg|rsyslog}} || style="background:lime" | Full ||
|-
| {{Pkg|syslog-ng}} || style="background:lime" | Full ||
|-
| {{pkg|socklog}} || style="background:silver" | Needs testing ||
|-
| [https://skarnet.org/software/s6/s6-socklog.html s6-socklog] from {{pkg|s6}} || style="background:silver" | Needs testing ||
|-
| systemd-journald || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:silver" | Needs testing ||
|}
* See also: [[Syslog]]

== [[Device Manager]] ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[mdev]] || style="background:lime" | Full || Default
|-
| [[mdevd]] || style="background:lime" | Full ||
|-
| [[eudev]] || style="background:lime" | Full ||
|-
| [https://core.suckless.org/smdev/ smdev] || style="background:red" | None ||
|-
| vdev || style="background:red" | None ||
|-
| systemd-udev || style="background:red" | None || Supported by postmarketOS
|}

== Power Managment ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[busybox acpid]] || style="background:lime" | Full || Default
|-
| {{Pkg|acpid}} || style="background:lime" | Full ||
|-
| {{Pkg|elogind}} || style="background:silver" | Needs testing ||
|-
| systemd-logind || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:lime" | Full ||
|}
* See also: [https://wiki.archlinux.org/title/Power_management Archwiki]
* See also: [https://wiki.gentoo.org/wiki/Power_management Gentoo Wiki]

== DHCP Client ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[Udhcpc|busybox udhcpc]] || style="background:lime" | Full || Default
|-
| {{Pkg|dhcpcd}} || style="background:lime" | Full ||
|-
| {{Pkg|dhclient}} || style="background:lime" | Full ||
|-
| [https://core.suckless.org/sdhcp/ sdhcp] || style="background:red" | None ||
|-
| without aka static || style="background:lime" | Full ||
|}
* See also: [[Configure Networking]]
* See also: [https://wiki.archlinux.org/title/Network_configuration#DHCP Archwiki]
* See also: [https://wiki.gentoo.org/wiki/Resolv.conf Gentoo Wiki - resolv.conf]

== Wi-Fi ==
* See: [[Wi-Fi]]
* Also supported: {{pkg|eiwd}}

== Seat/Session Managnent ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[elogind]] || style="background:lime" | Full ||
|-
| {{Pkg|seatd}} || style="background:lime" | Full || seats only
|-
| {{Pkg|turnstile}} || style="background:silver" | needs testing || session only
|-
| systemd-logind || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:lime" | Full || Not recommended with graphical enviroment
|}
* [https://wiki.gentoo.org/wiki/Seatd Gentoo Wiki - seatd]
* [https://wiki.gentoo.org/wiki/Elogind Gentoo Wiki - elogind]
* [https://wiki.archlinux.org/title/Init#logind ArchWiki - systemd-logind]
* [https://chimera-linux.org/docs/configuration/seat Chimera Linux docs]

== Login ==

{| class="wikitable"
|-
! Name !! Support !! Supports [[PAM]] !! Notes
|-
| busybox login || style="background:lime" | Full || style="background:red" | No || Default
|-
| {{Pkg|greetd}} || style="background:lime" | Full || style="background:lime" | Yes || requires greeter
|-
| {{Pkg|shadow-login}} || style="background:lime" | Full || style="background:lime" | Yes ||
|-
| {{Pkg|util-linux-login}} || style="background:lime" | Full || style="background:lime" | Yes ||
|-
| systemd-logind || style="background:red" | None || style="background:lime" | Yes || Supported by postmarketOS
|-
| without || style="background:lime" | Full || style="background:red" | No ||
|}
* See also: [https://wiki.gentoo.org/wiki/Login Gentoo Wiki]

== Shell Utils ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|busybox}} || style="background:lime" | Full || Dependency of {{pkg|alpine-base}}
|-
| {{Pkg|busybox-extras}} || style="background:lime" | Full || Some commands that are missing in the busybox package
|-
| {{Pkg|util-linux}} || style="background:lime" | Full ||
|-
| [[GNU_core_utilities|coreutils]] || style="background:lime" | Full ||
|-
| {{Pkg|s6-portable-utils}} || style="background:lime" | Full ||
|-
| {{Pkg|s6-linux-utils}} || style="background:lime" | Full ||
|-
| {{Pkg|toybox}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|sbase}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|ubase}} || style="background:silver" | Needs testing ||
|-
| without || style="background:red" | None || A lot of implicit dependency
|}
* See also: [https://wiki.archlinux.org/title/Core_utilities Archwiki]

== Shell ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| busybox ash || style="background:lime" | Full || Default
|-
| {{Pkg|bash}} || style="background:lime" | Full ||
|-
| {{Pkg|dash}} || style="background:lime" | Full ||
|-
| {{Pkg|yash}} || style="background:lime" | Full ||
|-
| busybox hush || style="background:red" | None ||
|-
| without || style="background:red" | None || sometimes implicit dependency
|}
* See also: [[Change default shell]]
* See proposal: [https://gitlab.alpinelinux.org/alpine/tsc/-/issues/39 replace busybox ash with another /bin/sh]
* See also: [https://wiki.archlinux.org/title/Command-line_shell Archwiki]
* See also: [https://wiki.gentoo.org/wiki/Shell Gentoo Wiki]

== SU ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| su from {{Pkg|busybox-suid}} || style="background:lime" | Full || default, can't be removed by default ({{issue|11730}})
|-
| su from {{Pkg|shadow-login}} || style="background:lime" | Full ||
|-
| su from {{Pkg|util-linux-login}} || style="background:lime" | Full ||
|-
| {{Pkg|sudo}} || style="background:lime" | Full ||
|-
| {{Pkg|doas}} || style="background:lime" | Full || sudo shim using doas: {{Pkg|doas-sudo-shim}}
|-
| [https://skarnet.org/software/s6/s6-sudo.html s6-sudo] || style="background:silver" | Needs testing ||
|-
| without || style="background:silver" | Needs testing ||
|}

== SSL/TLS ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|openssl}} || style="background:lime" | Full || Default
|-
| {{Pkg|libressl}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|bearssl}} || style="background:silver" | Needs testing ||
|}
* See also: [https://gitlab.alpinelinux.org/alpine/tsc/-/issues/28 consider LibreSSL as default OpenSSL provider again]
* See also: [https://wiki.archlinux.org/title/Transport_Layer_Security Archwiki]
* See also: [https://github.com/haproxy/wiki/wiki/SSL-Libraries-Support-Status haproxy SSL Libraries Support Status]

== Cron ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|cronie}} || style="background:lime" | Full ||
|-
| {{Pkg|dcron}} || style="background:lime" | Full ||
|-
| {{Pkg|fcron}} || style="background:lime" | Full ||
|-
| vixie-cron || style="background:red" | None ||
|-
| scron || style="background:red" | None ||
|-
| systemd.timer || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:lime" | Full || alpine-baselayout includes cron specific directories though
|}
* See also: [https://wiki.archlinux.org/title/Cron Archwiki]
* See also: [https://wiki.gentoo.org/wiki/Cron Gentoo Wiki]

== SSH ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[Setting_up_a_SSH_server#OpenSSH|openssh]] || style="background:lime" | Full ||
|-
| [[Setting_up_a_SSH_server#Dropbear|dropbear]] || style="background:lime" | Full || provide ssh command {{pkg|dropbear-ssh}}
|-
| without || style="background:lime" | Full ||
|}
* See also: [https://wiki.archlinux.org/title/Secure_Shell Archwiki]
* See also: [https://wiki.gentoo.org/wiki/SSH Gentoo Wiki - OpenSSH]
* See also: [https://wiki.gentoo.org/wiki/Dropbear Gentoo Wiki - Dropbear]

== Desktop ==
* See: [[Desktop environments and Window managers]]

== See Also ==
* [[Architecture|Alpine Architecture]]
* [https://gitlab.alpinelinux.org/alpine/tsc/-/issues/55 Future of busybox]

User:Sertonix/Freedom of choice

2024-06-04T12:20:30Z

Sertonix: Add notes that postmarketOS supports systemd

This is an overview over the different available programms, etc. that can be selected from when using alpine. It is also intended as a reference what should be documented and what could be supported.

== Bootloaders ==
* See: [[Bootloaders]]
* Not supported: <code>systemd-boot</code> ([https://gitlab.com/postmarketOS/pmaports/-/tree/master/main/systemd-boot PostmarketOS does])

== Kernel ==
* See: [[Kernels]]

== Libc ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|musl}} || style="background:lime" | Full || Default
|-
| [https://www.gnu.org/software/libc/ glibc] || style="background:red" | None || [[Running glibc programs]]
|-
| without aka static || style="background:orange" | depends on package || Note that this only means no libc at runtime
|}
* See also: [https://gitlab.alpinelinux.org/alpine/tsc/-/issues/17 alpine-glibc]
* See also: [https://wiki.gentoo.org/wiki/Libc Gentoo Wiki]

== Initramfs ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|mkinitfs}} || style="background:lime" | Full || Default
|-
| {{Pkg|dracut}} || style="background:lime" | Full ||
|-
| {{Pkg|booster}} || style="background:lime" | Full ||
|-
| [https://github.com/illiliti/tinyramfs tinyramfs] || style="background:red" | None ||
|-
| without || style="background:red" | None || may require [[custom Kernel]], [https://kisslinux.org/install#021 kisslinux without initramfs]
|}
* See also: [[Initramfs init]]
* See also: [https://wiki.gentoo.org/wiki/Initramfs Gentoo Wiki]

== PID 1 ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| busybox init || style="background:lime" | Full || Default
|-
| {{Pkg|dinit}} || style="background:orange" | In testing ||
|-
| {{Pkg|s6-linux-init}} || style="background:orange" | Works || Not integrated
|-
| {{Pkg|dumb-init}} || style="background:silver" | Needs testing || For containers
|-
| runit-init || style="background:silver" | Needs testing || [https://dev.alpinelinux.org/~clandmeter/other/forum.alpinelinux.org/comment/383.html#comment-383 runit-init starting OpenRC]
|-
| {{Pkg|epoch}} || style="background:silver" | Needs testing ||
|-
| openrc-init || style="background:red" | None || Is excluded from the {{pkg|openrc}} package
|-
| [https://core.suckless.org/sinit/ sinit] || style="background:red" | None ||
|-
| [https://ewontfix.com/14/ Felker init] || style="background:red" | None ||
|-
| systemd || style="background:red" | None || Supported by postmarketOS
|}
* See also: [https://wiki.gentoo.org/wiki/Init_system Gentoo Wiki]
* See also: [https://wiki.archlinux.org/title/Init Archwiki]

== Service Manager ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[OpenRC]] || style="background:lime" | Full || Default
|-
| {{Pkg|dinit}} || style="background:orange" | In testing || {{Pkg|dinit-alpine}} includes service files
|-
| {{Pkg|s6-rc}} || style="background:orange" | Works || Not integrated
|-
| {{Pkg|runit}} || style="background:orange" | As OpenRC service ||
|-
| {{Pkg|daemontools}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|daemontools-encore}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|supervisor}} || style="background:silver" | Needs testing ||
|-
| busybox runit || style="background:red" | None || Not enabled in a busybox package
|-
| [https://core.suckless.org/svc/ svc] || style="background:red" | None ||
|-
| systemd || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:red" | None ||
|}
* See also: [https://wiki.gentoo.org/wiki/Init_system Gentoo Wiki]
* See also: [https://wiki.archlinux.org/title/Init Archwiki]

== System Logs ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[Syslog#busybox_syslog|busybox syslog]] || style="background:lime" | Full || Default
|-
| {{Pkg|rsyslog}} || style="background:lime" | Full ||
|-
| {{Pkg|syslog-ng}} || style="background:lime" | Full ||
|-
| {{pkg|socklog}} || style="background:silver" | Needs testing ||
|-
| [https://skarnet.org/software/s6/s6-socklog.html s6-socklog] from {{pkg|s6}} || style="background:silver" | Needs testing ||
|-
| systemd-journald || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:silver" | Needs testing ||
|}
* See also: [[Syslog]]

== [[Device Manager]] ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[mdev]] || style="background:lime" | Full || Default
|-
| [[mdevd]] || style="background:lime" | Full ||
|-
| [[eudev]] || style="background:lime" | Full ||
|-
| [https://core.suckless.org/smdev/ smdev] || style="background:red" | None ||
|-
| vdev || style="background:red" | None ||
|-
| systemd-udev || style="background:red" | None || Supported by postmarketOS
|}

== Power Managment ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[busybox acpid]] || style="background:lime" | Full || Default
|-
| {{Pkg|acpid}} || style="background:lime" | Full ||
|-
| {{Pkg|elogind}} || style="background:silver" | Needs testing ||
|-
| systemd-logind || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:lime" | Full ||
|}
* See also: [https://wiki.archlinux.org/title/Power_management Archwiki]
* See also: [https://wiki.gentoo.org/wiki/Power_management Gentoo Wiki]

== DHCP Client ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[Udhcpc|busybox udhcpc]] || style="background:lime" | Full || Default
|-
| {{Pkg|dhcpcd}} || style="background:lime" | Full ||
|-
| {{Pkg|dhclient}} || style="background:lime" | Full ||
|-
| [https://core.suckless.org/sdhcp/ sdhcp] || style="background:red" | None ||
|-
| without aka static || style="background:lime" | Full ||
|}
* See also: [[Configure Networking]]
* See also: [https://wiki.archlinux.org/title/Network_configuration#DHCP Archwiki]
* See also: [https://wiki.gentoo.org/wiki/Resolv.conf Gentoo Wiki - resolv.conf]

== Wi-Fi ==
* See: [[Wi-Fi]]
* Also supported: {{pkg|eiwd}}

== Seat/Session Managnent ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[elogind]] || style="background:lime" | Full ||
|-
| {{Pkg|seatd}} || style="background:lime" | Full || seats only
|-
| {{Pkg|turnstile}} || style="background:silver" | needs testing || session only
|-
| systemd-logind || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:lime" | Full || Not recommended with graphical enviroment
|}
* [https://wiki.gentoo.org/wiki/Seatd Gentoo Wiki - seatd]
* [https://wiki.gentoo.org/wiki/Elogind Gentoo Wiki - elogind]
* [https://wiki.archlinux.org/title/Init#logind ArchWiki - systemd-logind]
* [https://chimera-linux.org/docs/configuration/seat Chimera Linux docs]

== Login ==

{| class="wikitable"
|-
! Name !! Support !! Supports [[PAM]] !! Notes
|-
| busybox login || style="background:lime" | Full || style="background:red" | No || Default
|-
| {{Pkg|greetd}} || style="background:lime" | Full || style="background:lime" | Yes || requires greeter
|-
| {{Pkg|shadow-login}} || style="background:lime" | Full || style="background:lime" | Yes ||
|-
| {{Pkg|util-linux-login}} || style="background:lime" | Full || style="background:lime" | Yes ||
|-
| systemd-logind || style="background:red" | None || style="background:lime" | Yes || Supported by postmarketOS
|-
| without || style="background:lime" | Full || style="background:red" | No ||
|}
* See also: [https://wiki.gentoo.org/wiki/Login Gentoo Wiki]

== Shell Utils ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|busybox}} || style="background:lime" | Full || Dependency of {{pkg|alpine-base}}
|-
| {{Pkg|busybox-extras}} || style="background:lime" | Full || Some commands that are missing in the busybox package
|-
| {{Pkg|util-linux}} || style="background:lime" | Full ||
|-
| [[GNU_core_utilities|coreutils]] || style="background:lime" | Full ||
|-
| {{Pkg|s6-portable-utils}} || style="background:lime" | Full ||
|-
| {{Pkg|s6-linux-utils}} || style="background:lime" | Full ||
|-
| {{Pkg|toybox}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|sbase}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|ubase}} || style="background:silver" | Needs testing ||
|-
| without || style="background:red" | None || A lot of implicit dependency
|}
* See also: [https://wiki.archlinux.org/title/Core_utilities Archwiki]

== Shell ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| busybox ash || style="background:lime" | Full || Default
|-
| {{Pkg|bash}} || style="background:lime" | Full ||
|-
| {{Pkg|dash}} || style="background:lime" | Full ||
|-
| {{Pkg|yash}} || style="background:lime" | Full ||
|-
| busybox hush || style="background:red" | None ||
|-
| without || style="background:red" | None || sometimes implicit dependency
|}
* See also: [[Change default shell]]
* See proposal: [https://gitlab.alpinelinux.org/alpine/tsc/-/issues/39 replace busybox ash with another /bin/sh]
* See also: [https://wiki.archlinux.org/title/Command-line_shell Archwiki]
* See also: [https://wiki.gentoo.org/wiki/Shell Gentoo Wiki]

== SU ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| su from {{Pkg|busybox-suid}} || style="background:lime" | Full || default, can't be removed by default ({{issue|11730}})
|-
| su from {{Pkg|shadow-login}} || style="background:lime" | Full ||
|-
| su from {{Pkg|util-linux-login}} || style="background:lime" | Full ||
|-
| {{Pkg|sudo}} || style="background:lime" | Full ||
|-
| {{Pkg|doas}} || style="background:lime" | Full || sudo shim using doas: {{Pkg|doas-sudo-shim}}
|-
| [https://skarnet.org/software/s6/s6-sudo.html s6-sudo] || style="background:silver" | Needs testing ||
|-
| without || style="background:silver" | Needs testing ||
|}

== SSL/TLS ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|openssl}} || style="background:lime" | Full || Default
|-
| {{Pkg|libressl}} || style="background:silver" | Needs testing ||
|-
| {{Pkg|bearssl}} || style="background:silver" | Needs testing ||
|}
* See also: [https://gitlab.alpinelinux.org/alpine/tsc/-/issues/28 consider LibreSSL as default OpenSSL provider again]
* See also: [https://wiki.archlinux.org/title/Transport_Layer_Security Archwiki]
* See also: [https://github.com/haproxy/wiki/wiki/SSL-Libraries-Support-Status haproxy SSL Libraries Support Status]

== Cron ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| {{Pkg|cronie}} || style="background:lime" | Full ||
|-
| {{Pkg|dcron}} || style="background:lime" | Full ||
|-
| {{Pkg|fcron}} || style="background:lime" | Full ||
|-
| vixie-cron || style="background:red" | None ||
|-
| scron || style="background:red" | None ||
|-
| systemd.timer || style="background:red" | None || Supported by postmarketOS
|-
| without || style="background:lime" | Full || alpine-baselayout includes cron specific directories though
|}
* See also: [https://wiki.archlinux.org/title/Cron Archwiki]
* See also: [https://wiki.gentoo.org/wiki/Cron Gentoo Wiki]

== SSH ==

{| class="wikitable"
|-
! Name !! Support !! Notes
|-
| [[Setting_up_a_SSH_server#OpenSSH|openssh]] || style="background:lime" | Full ||
|-
| [[Setting_up_a_SSH_server#Dropbear|dropbear]] || style="background:lime" | Full || provide ssh command {{pkg|dropbear-ssh}}
|-
| without || style="background:lime" | Full ||
|}
* See also: [https://wiki.archlinux.org/title/Secure_Shell Archwiki]
* See also: [https://wiki.gentoo.org/wiki/SSH Gentoo Wiki - OpenSSH]
* See also: [https://wiki.gentoo.org/wiki/Dropbear Gentoo Wiki - Dropbear]

== Desktop ==
* See: [[Desktop environments and Window managers]]

== See Also ==
* [[Architecture|Alpine Architecture]]
* [https://gitlab.alpinelinux.org/alpine/tsc/-/issues/55 Future of busybox]

Sway

2024-03-06T21:43:26Z

Sertonix: /* Install greetd (optional) */ link to greetd pahe

[https://swaywm.org Sway] is a tiling [[Wayland]] compositor and a drop-in replacement for the i3 window manager for X11. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.

== Installation ==
=== Add a normal user ===

Use <code>setup-user</code> to add a non-system normal user for running Sway.

=== Set up eudev ===

[[eudev]] is recommended and required for. Without it, sway cannot connect to input devices.

setup-devd udev

=== Install Graphics Drivers ===

Graphics drivers:

* [[Intel Video]]
* [[Radeon Video]]
* [[Nvidia Video]]

=== Setting up a seat manager ===

Wayland compositors need raw access to input and output devices. This is mediated by a [[seat manager]]. Using either [[seatd]] or [[elogind]] is supported. Using both may lead to conflicts.

==== Install seatd ====

See [[Seatd]].

==== Install elogind ====

See [[Elogind]].

===== Elogind and swayidle =====

<code>swayidle</code> has integration with <code>elogind</code> and can handle <code>before-sleep</code> events.

If using <code>swayidle before-sleep</code>, there will be a race condition, so that when you resume the computer from suspend, the screen shows the contents of the unlocked screen for a second before showing the actual lock screen. This can be a privacy concern.

To solve this issue, do the following:

Create this file <code>/etc/elogind/system-sleep/10-swaylock.sh</code>, then add the following script to this file:

#!/bin/sh
if [ "${1}" == "pre" ]; then
touch /tmp/swaylock-sleep
sleep 1
fi

Then set it to executable.

Later, once sway is installed, add the following line to sway config:

# in ~/.config/sway/config
exec touch /tmp/swaylock-sleep && inotifyd swaylock /tmp/swaylock-sleep

With this line, the screen will be promptly locked before suspend-to-RAM starts.

=== Install greetd (optional) ===

{{Box YELLOW|Note:|This content is tangential, and should be moved into the '[[greetd]]' page}}

apk add greetd greetd-gtkgreet cage
rc-update add greetd
adduser greetd seat

In <code>/etc/greetd/config.toml</code>, set

<pre>
[default_session]

command = "cage -s -- gtkgreet"
</pre>

To use a graphical greeter with seatd add <code>rc_need=seatd</code> to <code>/etc/conf.d/greetd</code>.

In <code>/etc/greetd/environments</code>, set
<pre>
# Launch Sway with a D-Bus server available, use:
dbus-run-session -- sway
</pre>

D-Bus is required for PipeWire and screensharing in Firefox and Chromium. Running with <code>dbus-run-session</code> is a convenience wrapper that will explicitly export the path of the session bus.

=== Install fonts ===

Install DejaVu fonts, which has good Unicode coverage:

apk add font-dejavu

=== Install Sway ===

apk add sway \
xwayland \ # if you need xserver
foot \ # default terminal emulator. Modify $term in config for a different one.
wmenu \ # default wayland native menu for choosing program and screensharing monitor
swaylock swaylockd \ # lockscreen tool
grim \ # screenshot tool
wl-clipboard \ # clipboard management
i3status \ # simple status bar
swayidle # idle management (DPMS) daemon

For complimentary software alternatives, see [https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway the relevant page from sway's wiki] or [https://wiki.gentoo.org/wiki/List_of_software_for_Wayland this list at Gentoo Wiki.]

== Configuration ==

Copy default sway configuration to <code>~/.config</code>:

# as normal user
mkdir -p ~/.config/sway
cp /etc/sway/config ~/.config/sway/

Read through it to learn the default keybindings.
Sway configuration is mostly backwards-compatible with that of [[I3wm|i3]] and if you are looking for a solution for a specific issue, you may also try checking if it hasn't been provided for i3WM.

For additional information, start at <code>man 5 sway</code> and read the [https://github.com/swaywm/sway/wiki upstream wiki].

== PipeWire and enable screensharing ==

For audio playback, either PipeWire or PulseAudio work fine. The compositor has no involvement in audio playback.

For screen sharing, applications are split into two categories:

* Those which use the native wayland protocol, </code>wlr-screencopy</code>
* Those which use the API from Flatpak's <code>xdg-desktop-portal</code> (this portal is also used by native non-Flatpak applications).

Applications in the first group require not additional setup. Applications in the second group (which includes Firefox and Chromium) require setting up pipewire, wireplumber and xdg portals:

{{Todo|Move this content into [[PipeWire]].}}

apk add pipewire pipewire-pulse pipewire-tools
apk add wireplumber
apk add xdg-desktop-portal xdg-desktop-portal-wlr

Launch PipeWire with Sway. Use your service manager of choice, or add the following to sway config:

exec /usr/libexec/pipewire-launcher

If your are using automatic D-Bus activation, you also need to set DBus variables for the portal and screensharing features to work:

exec dbus-update-activation-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=sway

{{Box YELLOW|Unclear:|The following paragraph is unclear and needs further work}}

Replace dmenu (depends on X server) with bemenu (Wayland native) for launching programs and selecting which screen to share in Firefox/Chromium:

set $menu bemenu-run | xargs swaymsg exec

== Screen lock and suspend-to-RAM ==

=== Without elogind ===

Consider using {{Pkg|powerctl}}.

=== With elogind ===

Putting the system to sleep with elogind requires elevated privileges or additional configuration.

For details on configuring <code>doas</code> with <code>elogind</code>, see [[Elogind#Doas]]

To put the system to sleep after 600 seconds, use:

exec swayidle -w timeout 600 'doas /bin/loginctl suspend'

loginctl suspend command will trigger the screenlock, as mentioned in the section [[#Install elogind (optional)|Install elogind (optional)]] above.

Do not lock the screen if program is running in full screen:

for_window [app_id="^.*"] inhibit_idle fullscreen

== Brightness control ==

Controlling display backlight requires either the proper udev rules, or using some form of privilege escalation.

{{Pkg|brightnessctl}} is a reliable alternative, although its default udev rules require too wide permissions (see {{Issue|15409}}). You may need your own rules, or configure doas to allow running it as an unprivileged user.

Optionally enable brightnessctl service to restore brightness settings on reboot:

rc-update add brightnessctl

== Output scaling for high resolution displays ==

Without further configuration, program interfaces might be too small to use on high resolution displays.

Sway supports the per-display configuration of

* fractional (e.g., 1.5x), and
* integer scaling (e.g., 2x)

However, fractional scaling is discouraged due to both the performance impact and the blurry output it produces. In this case, where 1x scaling is too small and 2x scaling is too large, program-specific GTK/QT based scaling is recommended. See below.

To enable Sway scaling, the user can first preview different scaling factors with <code>wdisplays</code> package. Note the output name (eDP-1, LVDS-1) and try apply scaling factors such as 1 and 2. To make changes permanent, add

<pre>
output <name> scale <factor>
</pre>

to ~/.config/sway/config.

To use toolkit scaling, use
{{Cmd|# for GTK-based programs such as firefox and emacs:
export GDK_DPI_SCALE{{=}}2

<nowiki>#</nowiki> for QT-based programs
export QT_WAYLAND_FORCE_DPI{{=}}"physical"
<nowiki>#</nowiki> or if still too small, use a custom DPI
export QT_WAYLAND_FORCE_DPI{{=}}192 # 2x scaling
export QT_QPA_PLATFORM{{=}}"wayland-egl"
}}

== Screenshots ==
A simple tool that works well under Wayland is Grimshot. Example keybindings:
<pre>
bindsym Print exec grimshot copy area
bindsym Shift+Print exec grimshot copy screen
bindsym Control+Print exec grimshot save area ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
bindsym Control+Shift+Print exec grimshot save screen ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
</pre>

See [https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway the sway wiki's article] for a list of screenshot tools.

== Tweaks ==

=== Make clipboard content persistent ===
By default the clipboard content does not persist after terminating the program: you copy some text from Firefox and then exit Firefox, the copied text is also lost.

Install clipman from testing repo and add the following to sway config:

<pre>
exec wl-paste --type text/plain --watch clipman store --histpath="~/.local/state/clipman-primary.json"
bindsym $mod+h exec clipman pick --tool wofi --histpath="~/.local/state/clipman-primary.json"
</pre>

=== Firefox picture-in-picture mode/floating windows ===
Add this to your sway config file (modify the numeric values to suit your needs and your display):
<pre>
for_window [app_id="firefox" title="^Picture-in-Picture$"] floating enable, move position 877 450, sticky enable, border none
</pre>

=== Start with NumLock enabled ===
Add this to your sway config file:
<code>input type:keyboard xkb_numlock enabled</code>

=== Change mouse cursor theme and size ===
Add to your sway config:

seat seat0 xcursor_theme my_cursor_theme my_cursor_size

For example, set a mouse cursor, using GNOME Adwaita theme:

seat seat0 xcursor_theme Adwaita 16

You can inspect their values with <code>echo $XCURSOR_SIZE</code> and <code>echo $XCURSOR_THEME</code>. If reloading your config does not result in change, try logging out and in.

{{Note|Wayland allows for client-side cursors. It is possible that applications do not evaluate the values of <code>$XCURSOR_SIZE</code> and <code>$XCURSOR_THEME</code>.}}

=== Custom keyboard layout ===

To use custom keyboard layout, just use
<pre>
input type:keyboard {
xkb_file /path/to/my/custom/layout
}
</pre>

=== Changing default application fonts ===

See [[Fontconfig]]

== Troubleshooting ==

If you encounter any issues, try running <code>sway -Vc /etc/sway/config</code>. It will run sway with the default config file and set the output to be more verbose. It is generally a good idea to track your config files with git (when and if at all you use a remote repository for them, keep it private for security reasons).

=== Flatpaks ===
{{main|Flatpak}}
Due to their sandboxing, flatpaks require the use of a portal frontend (xdg-desktop-portal) and backends (such as xdg-desktop-portal-wlr, xdg-desktop-portal-gtk, xdg-desktop-portal-gnome) that implement the methods. When in doubt, install multiple backends. For more information on backends, see [https://github.com/flatpak/xdg-desktop-portal/#using-portals flatpak's page on the subject]. In addition to the steps under the "Firefox Screensharing" section, it may also be necessary to launch additional backends in your Sway config file. Otherwise, you may run into GDBus errors as your flatpak fails to interface with the portal. This can cause issues such as with opening your file directories from a flatpak application.

After installing different backends, you might need to add the relevant backends to your sway config file similarly to in the "Firefox Screensharing" section above. For example, an autostart section of your sway config file may include:
<pre>
exec /usr/libexec/xdg-desktop-portal-gtk
exec /usr/libexec/xdg-desktop-portal-wlr
exec /usr/libexec/xdg-desktop-portal-gnome
</pre>

This is only needed if they are not started automatically via other means.

=== Firefox (Flatpak) and/or GTK apps ===
==== Disappearing cursor ====
You may need to get an icon pack and possibly a theme from [https://www.pling.com/browse?cat=107&ord=latest Pling store] and set <code>GTK_THEME</code> environmental variable. Alternatively you can install a theme for all users (search [https://pkgs.alpinelinux.org/ Alpine Linux Packages] for ''*-icon-theme'') using <code>apk add</code>.

==== Missing file picker/cannot download ====

Go to ''about:config'' and set <code>widget.use-xdg-desktop-portal.file-picker</code> to 0.

=== Failing to start under certain graphics cards/multiple wlroots stacked windows spawning upon start ===
As of Dec 31 2022, [https://developer.nvidia.com/docs/drive/drive-os/latest/linux/sdk/common/topics/window_system_stub/Gnome-WaylandDesktopShellSupport136.html Nvidia still doesn't fully support Wayland]. Therefore, the possible solutions are as outlined in the link, or setting your WLR_BACKENDS environmental variables to <code>drm,libinput</code> or <code>x11</code> (add libinput here as well if you cannot use your mouse and keyboard after starting Sway). The latter also works for AMD/ATI cards ('''make sure to install libinput first''').

=== Sway socket not detected ===

See [[Sway#Installation|Installation]] for instructions on how to set this environmental variable. This issue may occur with terminal multiplexers, such as [[tmux]]

== See Also ==
* [https://wiki.archlinux.org/title/Sway Archwiki]
* [https://wiki.gentoo.org/wiki/Sway Gentoo Wiki]
* [https://wiki.postmarketos.org/wiki/Sway PostmarketOS Wiki]

[[Category:Desktop]]
[[Category:Window Managers]]
[[Category:Wayland]]

Sway

2024-03-06T21:42:03Z

Sertonix: /* Setting up a seat manager */ link to 'seat manager' page and more

[https://swaywm.org Sway] is a tiling [[Wayland]] compositor and a drop-in replacement for the i3 window manager for X11. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.

== Installation ==
=== Add a normal user ===

Use <code>setup-user</code> to add a non-system normal user for running Sway.

=== Set up eudev ===

[[eudev]] is recommended and required for. Without it, sway cannot connect to input devices.

setup-devd udev

=== Install Graphics Drivers ===

Graphics drivers:

* [[Intel Video]]
* [[Radeon Video]]
* [[Nvidia Video]]

=== Setting up a seat manager ===

Wayland compositors need raw access to input and output devices. This is mediated by a [[seat manager]]. Using either [[seatd]] or [[elogind]] is supported. Using both may lead to conflicts.

==== Install seatd ====

See [[Seatd]].

==== Install elogind ====

See [[Elogind]].

===== Elogind and swayidle =====

<code>swayidle</code> has integration with <code>elogind</code> and can handle <code>before-sleep</code> events.

If using <code>swayidle before-sleep</code>, there will be a race condition, so that when you resume the computer from suspend, the screen shows the contents of the unlocked screen for a second before showing the actual lock screen. This can be a privacy concern.

To solve this issue, do the following:

Create this file <code>/etc/elogind/system-sleep/10-swaylock.sh</code>, then add the following script to this file:

#!/bin/sh
if [ "${1}" == "pre" ]; then
touch /tmp/swaylock-sleep
sleep 1
fi

Then set it to executable.

Later, once sway is installed, add the following line to sway config:

# in ~/.config/sway/config
exec touch /tmp/swaylock-sleep && inotifyd swaylock /tmp/swaylock-sleep

With this line, the screen will be promptly locked before suspend-to-RAM starts.

=== Install greetd (optional) ===

{{Box YELLOW|Note:|This content is tangential, and should be moved into the 'greetd' page}}

apk add greetd greetd-gtkgreet cage
rc-update add greetd
adduser greetd seat

In <code>/etc/greetd/config.toml</code>, set

<pre>
[default_session]

command = "cage -s -- gtkgreet"
</pre>

To use a graphical greeter with seatd add <code>rc_need=seatd</code> to <code>/etc/conf.d/greetd</code>.

In <code>/etc/greetd/environments</code>, set
<pre>
# Launch Sway with a D-Bus server available, use:
dbus-run-session -- sway
</pre>

D-Bus is required for PipeWire and screensharing in Firefox and Chromium. Running with <code>dbus-run-session</code> is a convenience wrapper that will explicitly export the path of the session bus.

=== Install fonts ===

Install DejaVu fonts, which has good Unicode coverage:

apk add font-dejavu

=== Install Sway ===

apk add sway \
xwayland \ # if you need xserver
foot \ # default terminal emulator. Modify $term in config for a different one.
wmenu \ # default wayland native menu for choosing program and screensharing monitor
swaylock swaylockd \ # lockscreen tool
grim \ # screenshot tool
wl-clipboard \ # clipboard management
i3status \ # simple status bar
swayidle # idle management (DPMS) daemon

For complimentary software alternatives, see [https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway the relevant page from sway's wiki] or [https://wiki.gentoo.org/wiki/List_of_software_for_Wayland this list at Gentoo Wiki.]

== Configuration ==

Copy default sway configuration to <code>~/.config</code>:

# as normal user
mkdir -p ~/.config/sway
cp /etc/sway/config ~/.config/sway/

Read through it to learn the default keybindings.
Sway configuration is mostly backwards-compatible with that of [[I3wm|i3]] and if you are looking for a solution for a specific issue, you may also try checking if it hasn't been provided for i3WM.

For additional information, start at <code>man 5 sway</code> and read the [https://github.com/swaywm/sway/wiki upstream wiki].

== PipeWire and enable screensharing ==

For audio playback, either PipeWire or PulseAudio work fine. The compositor has no involvement in audio playback.

For screen sharing, applications are split into two categories:

* Those which use the native wayland protocol, </code>wlr-screencopy</code>
* Those which use the API from Flatpak's <code>xdg-desktop-portal</code> (this portal is also used by native non-Flatpak applications).

Applications in the first group require not additional setup. Applications in the second group (which includes Firefox and Chromium) require setting up pipewire, wireplumber and xdg portals:

{{Todo|Move this content into [[PipeWire]].}}

apk add pipewire pipewire-pulse pipewire-tools
apk add wireplumber
apk add xdg-desktop-portal xdg-desktop-portal-wlr

Launch PipeWire with Sway. Use your service manager of choice, or add the following to sway config:

exec /usr/libexec/pipewire-launcher

If your are using automatic D-Bus activation, you also need to set DBus variables for the portal and screensharing features to work:

exec dbus-update-activation-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=sway

{{Box YELLOW|Unclear:|The following paragraph is unclear and needs further work}}

Replace dmenu (depends on X server) with bemenu (Wayland native) for launching programs and selecting which screen to share in Firefox/Chromium:

set $menu bemenu-run | xargs swaymsg exec

== Screen lock and suspend-to-RAM ==

=== Without elogind ===

Consider using {{Pkg|powerctl}}.

=== With elogind ===

Putting the system to sleep with elogind requires elevated privileges or additional configuration.

For details on configuring <code>doas</code> with <code>elogind</code>, see [[Elogind#Doas]]

To put the system to sleep after 600 seconds, use:

exec swayidle -w timeout 600 'doas /bin/loginctl suspend'

loginctl suspend command will trigger the screenlock, as mentioned in the section [[#Install elogind (optional)|Install elogind (optional)]] above.

Do not lock the screen if program is running in full screen:

for_window [app_id="^.*"] inhibit_idle fullscreen

== Brightness control ==

Controlling display backlight requires either the proper udev rules, or using some form of privilege escalation.

{{Pkg|brightnessctl}} is a reliable alternative, although its default udev rules require too wide permissions (see {{Issue|15409}}). You may need your own rules, or configure doas to allow running it as an unprivileged user.

Optionally enable brightnessctl service to restore brightness settings on reboot:

rc-update add brightnessctl

== Output scaling for high resolution displays ==

Without further configuration, program interfaces might be too small to use on high resolution displays.

Sway supports the per-display configuration of

* fractional (e.g., 1.5x), and
* integer scaling (e.g., 2x)

However, fractional scaling is discouraged due to both the performance impact and the blurry output it produces. In this case, where 1x scaling is too small and 2x scaling is too large, program-specific GTK/QT based scaling is recommended. See below.

To enable Sway scaling, the user can first preview different scaling factors with <code>wdisplays</code> package. Note the output name (eDP-1, LVDS-1) and try apply scaling factors such as 1 and 2. To make changes permanent, add

<pre>
output <name> scale <factor>
</pre>

to ~/.config/sway/config.

To use toolkit scaling, use
{{Cmd|# for GTK-based programs such as firefox and emacs:
export GDK_DPI_SCALE{{=}}2

<nowiki>#</nowiki> for QT-based programs
export QT_WAYLAND_FORCE_DPI{{=}}"physical"
<nowiki>#</nowiki> or if still too small, use a custom DPI
export QT_WAYLAND_FORCE_DPI{{=}}192 # 2x scaling
export QT_QPA_PLATFORM{{=}}"wayland-egl"
}}

== Screenshots ==
A simple tool that works well under Wayland is Grimshot. Example keybindings:
<pre>
bindsym Print exec grimshot copy area
bindsym Shift+Print exec grimshot copy screen
bindsym Control+Print exec grimshot save area ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
bindsym Control+Shift+Print exec grimshot save screen ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
</pre>

See [https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway the sway wiki's article] for a list of screenshot tools.

== Tweaks ==

=== Make clipboard content persistent ===
By default the clipboard content does not persist after terminating the program: you copy some text from Firefox and then exit Firefox, the copied text is also lost.

Install clipman from testing repo and add the following to sway config:

<pre>
exec wl-paste --type text/plain --watch clipman store --histpath="~/.local/state/clipman-primary.json"
bindsym $mod+h exec clipman pick --tool wofi --histpath="~/.local/state/clipman-primary.json"
</pre>

=== Firefox picture-in-picture mode/floating windows ===
Add this to your sway config file (modify the numeric values to suit your needs and your display):
<pre>
for_window [app_id="firefox" title="^Picture-in-Picture$"] floating enable, move position 877 450, sticky enable, border none
</pre>

=== Start with NumLock enabled ===
Add this to your sway config file:
<code>input type:keyboard xkb_numlock enabled</code>

=== Change mouse cursor theme and size ===
Add to your sway config:

seat seat0 xcursor_theme my_cursor_theme my_cursor_size

For example, set a mouse cursor, using GNOME Adwaita theme:

seat seat0 xcursor_theme Adwaita 16

You can inspect their values with <code>echo $XCURSOR_SIZE</code> and <code>echo $XCURSOR_THEME</code>. If reloading your config does not result in change, try logging out and in.

{{Note|Wayland allows for client-side cursors. It is possible that applications do not evaluate the values of <code>$XCURSOR_SIZE</code> and <code>$XCURSOR_THEME</code>.}}

=== Custom keyboard layout ===

To use custom keyboard layout, just use
<pre>
input type:keyboard {
xkb_file /path/to/my/custom/layout
}
</pre>

=== Changing default application fonts ===

See [[Fontconfig]]

== Troubleshooting ==

If you encounter any issues, try running <code>sway -Vc /etc/sway/config</code>. It will run sway with the default config file and set the output to be more verbose. It is generally a good idea to track your config files with git (when and if at all you use a remote repository for them, keep it private for security reasons).

=== Flatpaks ===
{{main|Flatpak}}
Due to their sandboxing, flatpaks require the use of a portal frontend (xdg-desktop-portal) and backends (such as xdg-desktop-portal-wlr, xdg-desktop-portal-gtk, xdg-desktop-portal-gnome) that implement the methods. When in doubt, install multiple backends. For more information on backends, see [https://github.com/flatpak/xdg-desktop-portal/#using-portals flatpak's page on the subject]. In addition to the steps under the "Firefox Screensharing" section, it may also be necessary to launch additional backends in your Sway config file. Otherwise, you may run into GDBus errors as your flatpak fails to interface with the portal. This can cause issues such as with opening your file directories from a flatpak application.

After installing different backends, you might need to add the relevant backends to your sway config file similarly to in the "Firefox Screensharing" section above. For example, an autostart section of your sway config file may include:
<pre>
exec /usr/libexec/xdg-desktop-portal-gtk
exec /usr/libexec/xdg-desktop-portal-wlr
exec /usr/libexec/xdg-desktop-portal-gnome
</pre>

This is only needed if they are not started automatically via other means.

=== Firefox (Flatpak) and/or GTK apps ===
==== Disappearing cursor ====
You may need to get an icon pack and possibly a theme from [https://www.pling.com/browse?cat=107&ord=latest Pling store] and set <code>GTK_THEME</code> environmental variable. Alternatively you can install a theme for all users (search [https://pkgs.alpinelinux.org/ Alpine Linux Packages] for ''*-icon-theme'') using <code>apk add</code>.

==== Missing file picker/cannot download ====

Go to ''about:config'' and set <code>widget.use-xdg-desktop-portal.file-picker</code> to 0.

=== Failing to start under certain graphics cards/multiple wlroots stacked windows spawning upon start ===
As of Dec 31 2022, [https://developer.nvidia.com/docs/drive/drive-os/latest/linux/sdk/common/topics/window_system_stub/Gnome-WaylandDesktopShellSupport136.html Nvidia still doesn't fully support Wayland]. Therefore, the possible solutions are as outlined in the link, or setting your WLR_BACKENDS environmental variables to <code>drm,libinput</code> or <code>x11</code> (add libinput here as well if you cannot use your mouse and keyboard after starting Sway). The latter also works for AMD/ATI cards ('''make sure to install libinput first''').

=== Sway socket not detected ===

See [[Sway#Installation|Installation]] for instructions on how to set this environmental variable. This issue may occur with terminal multiplexers, such as [[tmux]]

== See Also ==
* [https://wiki.archlinux.org/title/Sway Archwiki]
* [https://wiki.gentoo.org/wiki/Sway Gentoo Wiki]
* [https://wiki.postmarketos.org/wiki/Sway PostmarketOS Wiki]

[[Category:Desktop]]
[[Category:Window Managers]]
[[Category:Wayland]]

Desktop environments and Window managers

2024-03-06T21:31:12Z

Sertonix: fix link to display manager category

{{TOC right}}

'''Alpine Linux''' has no official desktop. Older versions used Xfce, but now all GUI and graphical interfaces are optional. many are available and are attempted to be listed below:

== Desktop Environments ==

See also: [[:Category:Desktop Environments|Desktop Environments Category]]

* [[Xfce]]
* [[LXQt]]
* [[KDE|KDE Plasma]]
* [[GNOME]]
* [[MATE]]

== Window Managers ==

See also: [[:Category:Window Managers|Window Managers Category]]

=== [https://en.wikipedia.org/wiki/Stacking_window_manager Stacking (floating) window managers] ===

* X11:
** [[Openbox]]

* Wayland:
** Weston
** [[LabWC]]
** [[Wayfire]]

=== [https://en.wikipedia.org/wiki/Tiling_window_manager Tiling (dynamic) window managers] ===

* X11:
** bspwm
** herbstluftwm
** [[twm]]
** [[dwm]]
** [[I3wm|i3]]
** [[AwesomeWM|Awesome Window Manager]]
** Ratpoison (Available in Edge branch under the testing repository)
** spectrwm (Available in Edge Branch under the testing repository)
** Qtile (Available in Edge Branch under the testing repository)

* Wayland:
** [[Sway]]
** [[River]]
** Cagebreak
** dwl (Available in Edge Branch under the testing repository)
** Qtile (Available in Edge Branch under the testing repository)

=== Other Window Managers ===

* Wayland
** Cage - Wayland Compositor for running single app on fullscreen mode (kiosk)

== See Also ==
* [[Installation]]
* [[Installation#Post-Installation|Post Installation]]
* [[Seat_manager#Input_and_video_groups|Input and video groups]]
* [[Fonts]]
* [[Wayland]]
* [[:Category:Display Managers]]
* [https://wiki.archlinux.org/title/Desktop_environment Desktop environment - Archwiki]
* [https://wiki.gentoo.org/wiki/Desktop_environment Desktop environment - Gentoo Wiki]

[[Category:Desktop]]
[[Category:Newbie]]

Desktop environments and Window managers

2024-03-06T21:30:53Z

Sertonix: fix input/video group suggestion

{{TOC right}}

'''Alpine Linux''' has no official desktop. Older versions used Xfce, but now all GUI and graphical interfaces are optional. many are available and are attempted to be listed below:

== Desktop Environments ==

See also: [[:Category:Desktop Environments|Desktop Environments Category]]

* [[Xfce]]
* [[LXQt]]
* [[KDE|KDE Plasma]]
* [[GNOME]]
* [[MATE]]

== Window Managers ==

See also: [[:Category:Window Managers|Window Managers Category]]

=== [https://en.wikipedia.org/wiki/Stacking_window_manager Stacking (floating) window managers] ===

* X11:
** [[Openbox]]

* Wayland:
** Weston
** [[LabWC]]
** [[Wayfire]]

=== [https://en.wikipedia.org/wiki/Tiling_window_manager Tiling (dynamic) window managers] ===

* X11:
** bspwm
** herbstluftwm
** [[twm]]
** [[dwm]]
** [[I3wm|i3]]
** [[AwesomeWM|Awesome Window Manager]]
** Ratpoison (Available in Edge branch under the testing repository)
** spectrwm (Available in Edge Branch under the testing repository)
** Qtile (Available in Edge Branch under the testing repository)

* Wayland:
** [[Sway]]
** [[River]]
** Cagebreak
** dwl (Available in Edge Branch under the testing repository)
** Qtile (Available in Edge Branch under the testing repository)

=== Other Window Managers ===

* Wayland
** Cage - Wayland Compositor for running single app on fullscreen mode (kiosk)

== See Also ==
* [[Installation]]
* [[Installation#Post-Installation|Post Installation]]
* [[Seat_manager#Input_and_video_groups|Input and video groups]]
* [[Fonts]]
* [[Wayland]]
* [[Category:Display Managers]]
* [https://wiki.archlinux.org/title/Desktop_environment Desktop environment - Archwiki]
* [https://wiki.gentoo.org/wiki/Desktop_environment Desktop environment - Gentoo Wiki]

[[Category:Desktop]]
[[Category:Newbie]]

Category:Seat manager

2024-03-06T21:26:25Z

Sertonix: add to desktop category

#REDIRECT [[Seat_manager]]

[[Category:Desktop]]

Seat manager

2024-03-06T21:25:54Z

Sertonix: add desktop category

{{todo|This article needs verification for X11 based setups}}

A seat manager dictates access to input and output devices like keyboard and monitor.

On alpine linux 2 seat managers are available:
* [[seatd]]: a minimal seat management daemon
* [[elogind]]: from systemd extracted login manager

== Input and video groups ==
Some instructions mention the need for the <code>input</code> and <code>video</code> groups. This is in most cases not correct and insecure! The seat manager already provides the necessary permissions.

Due to issue {{issue|15409}} there is currently 1 exception: If you aren't using elogind and need [[PipeWire#Device_access|PipeWire]] to access a webcam you need the <code>video</code> group.

== See Also ==
* [https://man.sr.ht/~kennylevinsen/seatd/#what-is-a-seat seatd: what is a seat]
* [https://docs.voidlinux.org/config/session-management.html void docs: Session and Seat Management]

[[Category:Desktop]]

Seatd

2024-03-06T21:24:38Z

Sertonix: link to seat manager article

Seatd is a [[seat manager]] and provides user sessions (mostly compositors) with access to input and output devices.

See [https://man.sr.ht/~kennylevinsen/seatd/ the seatd documentation] for further details.

When using [[elogind]], seatd is not required and viceversa.

= Installation =

{{Cmd|apk add {{Pkg|seatd}} # install seatd
rc-update add seatd # configure it to auto-start
service seatd start # start it now
adduser $USER seat # allow current user to access seatd
}}

If you are already logged in as a <code>$USER</code>, you will need to relogin.

[[Category:Desktop]]
[[Category:Seat_manager]]

Category:Seat manager

2024-03-06T21:24:05Z

Sertonix: redirect to "Seat manager" page

#REDIRECT [[Seat_manager]]

Seat manager

2024-03-06T21:23:30Z

Sertonix: initial instructions

Desktop environments and Window managers

2024-03-06T21:00:29Z

Sertonix: link to wayland article

{{TOC right}}

{{Tip|Be sure to add your user to <code>input</code> and <code>video</code> groups.}}

'''Alpine Linux''' has no official desktop. Older versions used Xfce, but now all GUI and graphical interfaces are optional. many are available and are attempted to be listed below:

== Desktop Environments ==

See also: [[:Category:Desktop Environments|Desktop Environments Category]]

* [[Xfce]]
* [[LXQt]]
* [[KDE|KDE Plasma]]
* [[GNOME]]
* [[MATE]]

== Window Managers ==

See also: [[:Category:Window Managers|Window Managers Category]]

=== [https://en.wikipedia.org/wiki/Stacking_window_manager Stacking (floating) window managers] ===

* X11:
** [[Openbox]]

* Wayland:
** Weston
** [[LabWC]]
** [[Wayfire]]

=== [https://en.wikipedia.org/wiki/Tiling_window_manager Tiling (dynamic) window managers] ===

* X11:
** bspwm
** herbstluftwm
** [[twm]]
** [[dwm]]
** [[I3wm|i3]]
** [[AwesomeWM|Awesome Window Manager]]
** Ratpoison (Available in Edge branch under the testing repository)
** spectrwm (Available in Edge Branch under the testing repository)
** Qtile (Available in Edge Branch under the testing repository)

* Wayland:
** [[Sway]]
** [[River]]
** Cagebreak
** dwl (Available in Edge Branch under the testing repository)
** Qtile (Available in Edge Branch under the testing repository)

=== Other Window Managers ===

* Wayland
** Cage - Wayland Compositor for running single app on fullscreen mode (kiosk)

== See Also ==
* [[Installation]]
* [[Installation#Post-Installation|Post Installation]]
* [[Fonts]]
* [[Wayland]]
* [[Category:Display Managers]]
* [https://wiki.archlinux.org/title/Desktop_environment Desktop environment - Archwiki]
* [https://wiki.gentoo.org/wiki/Desktop_environment Desktop environment - Gentoo Wiki]

[[Category:Desktop]]
[[Category:Newbie]]

Seatd

2024-03-06T20:49:01Z

Sertonix: add seat manager category

Seatd is a seat manager and provides user sessions (mostly compositors) with access to input and output devices.

See [https://man.sr.ht/~kennylevinsen/seatd/ the seatd documentation] for further details.

When using [[elogind]], seatd is not required and viceversa.

= Installation =

{{Cmd|apk add {{Pkg|seatd}} # install seatd
rc-update add seatd # configure it to auto-start
service seatd start # start it now
adduser $USER seat # allow current user to access seatd
}}

If you are already logged in as a <code>$USER</code>, you will need to relogin.

[[Category:Desktop]]
[[Category:Seat_manager]]

Elogind

2024-03-06T20:48:59Z

Sertonix: add seat manager category

[https://github.com/elogind/elogind '''elogind'''] is a login manager and provides support for

* setting up necessary permissions for the desktop environment or window manager
* handling poweroff, reboot, suspend and hibernate via '''loginctl''' command

== Installation ==

{{Cmd|# apk add {{Pkg|elogind}}
<nowiki>#</nowiki> rc-update add elogind
<nowiki>#</nowiki> rc-service elogind start}}
Polkit is used for authentication. Without it some things may not function. You need to install and configure [[D-Bus#Installation|D-Bus]] to use polkit.
{{Cmd|# apk add {{Pkg|polkit-elogind}}
<nowiki>#</nowiki> rc-update add polkit
<nowiki>#</nowiki> rc-service polkit start}}

Set up a [[PAM]] login.

== Hibernating ==

For {{Cmd|# loginctl hibernate}} to work, you must have a swap partition. Check {{Cmd|# lsblk}} for a partition with the mountpoint [SWAP].

<pre>
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS
nvme0n1 259:0 0 953.9G 0 disk
├─nvme0n1p1 259:1 0 200M 0 part /boot
├─nvme0n1p2 259:2 0 100G 0 part /
├─nvme0n1p3 259:3 0 805G 0 part /home
└─nvme0n1p4 259:4 0 48.7G 0 part [SWAP]
</pre>

Remember also to add a kernel parameter to resume, ie in {{Path|/etc/default/grub}} :

{{Cat|/etc/default/grub|<nowiki>...
GRUB_CMDLINE_LINUX_DEFAULT="modules=sd-mod,usb-storage,ext4,nvme quiet rootfstype=ext4 resume=/dev/nvme0n1p4"
</nowiki>}}

Note the "resume=" flag with the same partition that was marked as [SWAP].

== Configuration ==

=== logind.conf ===

Edit {{Path|/etc/elogind/logind.conf}} to configure handling of power events, such as suspending the computer when power button is pressed:

{{cat|/etc/elogind/logind.conf|...
[Login]
HandlePowerKey{{=}}suspend
...}}

=== Working with Desktop Environments ===

If using a Window Manager or Desktop Environment, such as [[Sway]], the user must ensure that login session is correctly configured. When correctly configured, the <code>loginctl</code> command should output the following:

'''Using [[Sway]] and [[SDDM]]'''

~'''$''' loginctl

SESSION UID USER SEAT TTY
c1 105 sddm seat0
c2 1000 User seat0 tty8

2 sessions listed.


If the output is <code>No session available.</code>, such as in the case of launching Sway from tty, suspend and many other functionality will not work. The user then must configure a display manager such as {{Pkg|greetd}}, [[SDDM]] or {{Pkg|lightdm|LightDM}}.

== Doas ==

Doas is used to grant permissions for suspend-to-RAM and brightness control with brightnessctl:

apk add doas brightnessctl
# optionally, allow $USER root access with password
adduser $USER wheel

In <code>/etc/doas.conf</code>, set

permit :wheel
permit nopass $USER as root cmd /bin/loginctl
permit nopass $USER as root cmd /usr/bin/brightnessctl

After setting the above, suspend-to-RAM can be triggered by running

/bin/loginctl suspend

(use full path to executable) and brightness can be adjusted by running

/usr/bin/brightnessctl set 100

== See also ==
* [https://wiki.gentoo.org/wiki/Elogind elogind - Gentoo Wiki]
* [https://wiki.gentoo.org/wiki/Polkit polkit - Gentoo Wiki]
* [https://wiki.archlinux.org/title/Polkit polkit - ArchWiki]

[[Category:Desktop]]
[[Category:Seat_manager]]

Seatd

2024-03-06T20:28:01Z

Sertonix: add to desktop category

Seatd

2024-03-06T20:26:46Z

Sertonix: link to elogind article

Sway

2024-03-06T20:25:09Z

Sertonix: add overall install heading

[https://swaywm.org Sway] is a tiling [[Wayland]] compositor and a drop-in replacement for the i3 window manager for X11. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.

== Installation ==
=== Add a normal user ===

Use <code>setup-user</code> to add a non-system normal user for running Sway.

=== Set up eudev ===

[[eudev]] is recommended and required for. Without it, sway cannot connect to input devices.

setup-devd udev

=== Install Graphics Drivers ===

Graphics drivers:

* [[Intel Video]]
* [[Radeon Video]]
* [[Nvidia Video]]

=== Setting up a seat manager ===

Wayland compositors need raw access to input and output devices. This is mediated by a [https://man.sr.ht/~kennylevinsen/seatd/ seat manager]. Using either seatd or elogind is supported. Using both may lead to conflicts.

==== Install seatd ====

See [[Seatd]].

==== Install elogind ====

See [[Elogind]].

===== Elogind and swayidle =====

<code>swayidle</code> has integration with <code>elogind</code> and can handle <code>before-sleep</code> events.

If using <code>swayidle before-sleep</code>, there will be a race condition, so that when you resume the computer from suspend, the screen shows the contents of the unlocked screen for a second before showing the actual lock screen. This can be a privacy concern.

To solve this issue, do the following:

Create this file <code>/etc/elogind/system-sleep/10-swaylock.sh</code>, then add the following script to this file:

#!/bin/sh
if [ "${1}" == "pre" ]; then
touch /tmp/swaylock-sleep
sleep 1
fi

Then set it to executable.

Later, once sway is installed, add the following line to sway config:

# in ~/.config/sway/config
exec touch /tmp/swaylock-sleep && inotifyd swaylock /tmp/swaylock-sleep

With this line, the screen will be promptly locked before suspend-to-RAM starts.

=== Install greetd (optional) ===

{{Box YELLOW|Note:|This content is tangential, and should be moved into the 'greetd' page}}

apk add greetd greetd-gtkgreet cage
rc-update add greetd
adduser greetd seat

In <code>/etc/greetd/config.toml</code>, set

<pre>
[default_session]

command = "cage -s -- gtkgreet"
</pre>

To use a graphical greeter with seatd add <code>rc_need=seatd</code> to <code>/etc/conf.d/greetd</code>.

In <code>/etc/greetd/environments</code>, set
<pre>
# Launch Sway with a D-Bus server available, use:
dbus-run-session -- sway
</pre>

D-Bus is required for PipeWire and screensharing in Firefox and Chromium. Running with <code>dbus-run-session</code> is a convenience wrapper that will explicitly export the path of the session bus.

=== Install fonts ===

Install DejaVu fonts, which has good Unicode coverage:

apk add font-dejavu

=== Install Sway ===

apk add sway \
xwayland \ # if you need xserver
foot \ # default terminal emulator. Modify $term in config for a different one.
wmenu \ # default wayland native menu for choosing program and screensharing monitor
swaylock swaylockd \ # lockscreen tool
grim \ # screenshot tool
wl-clipboard \ # clipboard management
i3status \ # simple status bar
swayidle # idle management (DPMS) daemon

For complimentary software alternatives, see [https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway the relevant page from sway's wiki] or [https://wiki.gentoo.org/wiki/List_of_software_for_Wayland this list at Gentoo Wiki.]

== Configuration ==

Copy default sway configuration to <code>~/.config</code>:

# as normal user
mkdir -p ~/.config/sway
cp /etc/sway/config ~/.config/sway/

Read through it to learn the default keybindings.
Sway configuration is mostly backwards-compatible with that of [[I3wm|i3]] and if you are looking for a solution for a specific issue, you may also try checking if it hasn't been provided for i3WM.

For additional information, start at <code>man 5 sway</code> and read the [https://github.com/swaywm/sway/wiki upstream wiki].

== PipeWire and enable screensharing ==

For audio playback, either PipeWire or PulseAudio work fine. The compositor has no involvement in audio playback.

For screen sharing, applications are split into two categories:

* Those which use the native wayland protocol, </code>wlr-screencopy</code>
* Those which use the API from Flatpak's <code>xdg-desktop-portal</code> (this portal is also used by native non-Flatpak applications).

Applications in the first group require not additional setup. Applications in the second group (which includes Firefox and Chromium) require setting up pipewire, wireplumber and xdg portals:

{{Todo|Move this content into [[PipeWire]].}}

apk add pipewire pipewire-pulse pipewire-tools
apk add wireplumber
apk add xdg-desktop-portal xdg-desktop-portal-wlr

Launch PipeWire with Sway. Use your service manager of choice, or add the following to sway config:

exec /usr/libexec/pipewire-launcher

If your are using automatic D-Bus activation, you also need to set DBus variables for the portal and screensharing features to work:

exec dbus-update-activation-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=sway

{{Box YELLOW|Unclear:|The following paragraph is unclear and needs further work}}

Replace dmenu (depends on X server) with bemenu (Wayland native) for launching programs and selecting which screen to share in Firefox/Chromium:

set $menu bemenu-run | xargs swaymsg exec

== Screen lock and suspend-to-RAM ==

=== Without elogind ===

Consider using {{Pkg|powerctl}}.

=== With elogind ===

Putting the system to sleep with elogind requires elevated privileges or additional configuration.

For details on configuring <code>doas</code> with <code>elogind</code>, see [[Elogind#Doas]]

To put the system to sleep after 600 seconds, use:

exec swayidle -w timeout 600 'doas /bin/loginctl suspend'

loginctl suspend command will trigger the screenlock, as mentioned in the section [[#Install elogind (optional)|Install elogind (optional)]] above.

Do not lock the screen if program is running in full screen:

for_window [app_id="^.*"] inhibit_idle fullscreen

== Brightness control ==

Controlling display backlight requires either the proper udev rules, or using some form of privilege escalation.

{{Pkg|brightnessctl}} is a reliable alternative, although its default udev rules require too wide permissions (see {{Issue|15409}}). You may need your own rules, or configure doas to allow running it as an unprivileged user.

Optionally enable brightnessctl service to restore brightness settings on reboot:

rc-update add brightnessctl

== Output scaling for high resolution displays ==

Without further configuration, program interfaces might be too small to use on high resolution displays.

Sway supports the per-display configuration of

* fractional (e.g., 1.5x), and
* integer scaling (e.g., 2x)

However, fractional scaling is discouraged due to both the performance impact and the blurry output it produces. In this case, where 1x scaling is too small and 2x scaling is too large, program-specific GTK/QT based scaling is recommended. See below.

To enable Sway scaling, the user can first preview different scaling factors with <code>wdisplays</code> package. Note the output name (eDP-1, LVDS-1) and try apply scaling factors such as 1 and 2. To make changes permanent, add

<pre>
output <name> scale <factor>
</pre>

to ~/.config/sway/config.

To use toolkit scaling, use
{{Cmd|# for GTK-based programs such as firefox and emacs:
export GDK_DPI_SCALE{{=}}2

<nowiki>#</nowiki> for QT-based programs
export QT_WAYLAND_FORCE_DPI{{=}}"physical"
<nowiki>#</nowiki> or if still too small, use a custom DPI
export QT_WAYLAND_FORCE_DPI{{=}}192 # 2x scaling
export QT_QPA_PLATFORM{{=}}"wayland-egl"
}}

== Screenshots ==
A simple tool that works well under Wayland is Grimshot. Example keybindings:
<pre>
bindsym Print exec grimshot copy area
bindsym Shift+Print exec grimshot copy screen
bindsym Control+Print exec grimshot save area ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
bindsym Control+Shift+Print exec grimshot save screen ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
</pre>

See [https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway the sway wiki's article] for a list of screenshot tools.

== Tweaks ==

=== Make clipboard content persistent ===
By default the clipboard content does not persist after terminating the program: you copy some text from Firefox and then exit Firefox, the copied text is also lost.

Install clipman from testing repo and add the following to sway config:

<pre>
exec wl-paste --type text/plain --watch clipman store --histpath="~/.local/state/clipman-primary.json"
bindsym $mod+h exec clipman pick --tool wofi --histpath="~/.local/state/clipman-primary.json"
</pre>

=== Firefox picture-in-picture mode/floating windows ===
Add this to your sway config file (modify the numeric values to suit your needs and your display):
<pre>
for_window [app_id="firefox" title="^Picture-in-Picture$"] floating enable, move position 877 450, sticky enable, border none
</pre>

=== Start with NumLock enabled ===
Add this to your sway config file:
<code>input type:keyboard xkb_numlock enabled</code>

=== Change mouse cursor theme and size ===
Add to your sway config:

seat seat0 xcursor_theme my_cursor_theme my_cursor_size

For example, set a mouse cursor, using GNOME Adwaita theme:

seat seat0 xcursor_theme Adwaita 16

You can inspect their values with <code>echo $XCURSOR_SIZE</code> and <code>echo $XCURSOR_THEME</code>. If reloading your config does not result in change, try logging out and in.

{{Note|Wayland allows for client-side cursors. It is possible that applications do not evaluate the values of <code>$XCURSOR_SIZE</code> and <code>$XCURSOR_THEME</code>.}}

=== Custom keyboard layout ===

To use custom keyboard layout, just use
<pre>
input type:keyboard {
xkb_file /path/to/my/custom/layout
}
</pre>

=== Changing default application fonts ===

See [[Fontconfig]]

== Troubleshooting ==

If you encounter any issues, try running <code>sway -Vc /etc/sway/config</code>. It will run sway with the default config file and set the output to be more verbose. It is generally a good idea to track your config files with git (when and if at all you use a remote repository for them, keep it private for security reasons).

=== Flatpaks ===
{{main|Flatpak}}
Due to their sandboxing, flatpaks require the use of a portal frontend (xdg-desktop-portal) and backends (such as xdg-desktop-portal-wlr, xdg-desktop-portal-gtk, xdg-desktop-portal-gnome) that implement the methods. When in doubt, install multiple backends. For more information on backends, see [https://github.com/flatpak/xdg-desktop-portal/#using-portals flatpak's page on the subject]. In addition to the steps under the "Firefox Screensharing" section, it may also be necessary to launch additional backends in your Sway config file. Otherwise, you may run into GDBus errors as your flatpak fails to interface with the portal. This can cause issues such as with opening your file directories from a flatpak application.

After installing different backends, you might need to add the relevant backends to your sway config file similarly to in the "Firefox Screensharing" section above. For example, an autostart section of your sway config file may include:
<pre>
exec /usr/libexec/xdg-desktop-portal-gtk
exec /usr/libexec/xdg-desktop-portal-wlr
exec /usr/libexec/xdg-desktop-portal-gnome
</pre>

This is only needed if they are not started automatically via other means.

=== Firefox (Flatpak) and/or GTK apps ===
==== Disappearing cursor ====
You may need to get an icon pack and possibly a theme from [https://www.pling.com/browse?cat=107&ord=latest Pling store] and set <code>GTK_THEME</code> environmental variable. Alternatively you can install a theme for all users (search [https://pkgs.alpinelinux.org/ Alpine Linux Packages] for ''*-icon-theme'') using <code>apk add</code>.

==== Missing file picker/cannot download ====

Go to ''about:config'' and set <code>widget.use-xdg-desktop-portal.file-picker</code> to 0.

=== Failing to start under certain graphics cards/multiple wlroots stacked windows spawning upon start ===
As of Dec 31 2022, [https://developer.nvidia.com/docs/drive/drive-os/latest/linux/sdk/common/topics/window_system_stub/Gnome-WaylandDesktopShellSupport136.html Nvidia still doesn't fully support Wayland]. Therefore, the possible solutions are as outlined in the link, or setting your WLR_BACKENDS environmental variables to <code>drm,libinput</code> or <code>x11</code> (add libinput here as well if you cannot use your mouse and keyboard after starting Sway). The latter also works for AMD/ATI cards ('''make sure to install libinput first''').

=== Sway socket not detected ===

See [[Sway#Installation|Installation]] for instructions on how to set this environmental variable. This issue may occur with terminal multiplexers, such as [[tmux]]

== See Also ==
* [https://wiki.archlinux.org/title/Sway Archwiki]
* [https://wiki.gentoo.org/wiki/Sway Gentoo Wiki]
* [https://wiki.postmarketos.org/wiki/Sway PostmarketOS Wiki]

[[Category:Desktop]]
[[Category:Window Managers]]
[[Category:Wayland]]

Sway

2024-03-06T20:18:52Z

Sertonix: add links to introduction

[https://swaywm.org Sway] is a tiling [[Wayland]] compositor and a drop-in replacement for the i3 window manager for X11. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.

== Add a normal user ==

Use <code>setup-user</code> to add a non-system normal user for running Sway.

== Set up eudev ==

[[eudev]] is recommended and required for. Without it, sway cannot connect to input devices.

setup-devd udev

== Install Graphics Drivers ==

Graphics drivers:

* [[Intel Video]]
* [[Radeon Video]]
* [[Nvidia Video]]

== Setting up a seat manager ==

Wayland compositors need raw access to input and output devices. This is mediated by a [https://man.sr.ht/~kennylevinsen/seatd/ seat manager]. Using either seatd or elogind is supported. Using both may lead to conflicts.

=== Install seatd ===

See [[Seatd]].

=== Install elogind ===

See [[Elogind]].

==== Elogind and swayidle ====

<code>swayidle</code> has integration with <code>elogind</code> and can handle <code>before-sleep</code> events.

If using <code>swayidle before-sleep</code>, there will be a race condition, so that when you resume the computer from suspend, the screen shows the contents of the unlocked screen for a second before showing the actual lock screen. This can be a privacy concern.

To solve this issue, do the following:

Create this file <code>/etc/elogind/system-sleep/10-swaylock.sh</code>, then add the following script to this file:

#!/bin/sh
if [ "${1}" == "pre" ]; then
touch /tmp/swaylock-sleep
sleep 1
fi

Then set it to executable.

Later, once sway is installed, add the following line to sway config:

# in ~/.config/sway/config
exec touch /tmp/swaylock-sleep && inotifyd swaylock /tmp/swaylock-sleep

With this line, the screen will be promptly locked before suspend-to-RAM starts.

== Install greetd (optional) ==

{{Box YELLOW|Note:|This content is tangential, and should be moved into the 'greetd' page}}

apk add greetd greetd-gtkgreet cage
rc-update add greetd
adduser greetd seat

In <code>/etc/greetd/config.toml</code>, set

<pre>
[default_session]

command = "cage -s -- gtkgreet"
</pre>

To use a graphical greeter with seatd add <code>rc_need=seatd</code> to <code>/etc/conf.d/greetd</code>.

In <code>/etc/greetd/environments</code>, set
<pre>
# Launch Sway with a D-Bus server available, use:
dbus-run-session -- sway
</pre>

D-Bus is required for PipeWire and screensharing in Firefox and Chromium. Running with <code>dbus-run-session</code> is a convenience wrapper that will explicitly export the path of the session bus.

== Install fonts ==

Install DejaVu fonts, which has good Unicode coverage:

apk add font-dejavu

== Install Sway ==

apk add sway \
xwayland \ # if you need xserver
foot \ # default terminal emulator. Modify $term in config for a different one.
wmenu \ # default wayland native menu for choosing program and screensharing monitor
swaylock swaylockd \ # lockscreen tool
grim \ # screenshot tool
wl-clipboard \ # clipboard management
i3status \ # simple status bar
swayidle # idle management (DPMS) daemon

For complimentary software alternatives, see [https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway the relevant page from sway's wiki] or [https://wiki.gentoo.org/wiki/List_of_software_for_Wayland this list at Gentoo Wiki.]

== Configuration ==

Copy default sway configuration to <code>~/.config</code>:

# as normal user
mkdir -p ~/.config/sway
cp /etc/sway/config ~/.config/sway/

Read through it to learn the default keybindings.
Sway configuration is mostly backwards-compatible with that of [[I3wm|i3]] and if you are looking for a solution for a specific issue, you may also try checking if it hasn't been provided for i3WM.

For additional information, start at <code>man 5 sway</code> and read the [https://github.com/swaywm/sway/wiki upstream wiki].

== PipeWire and enable screensharing ==

For audio playback, either PipeWire or PulseAudio work fine. The compositor has no involvement in audio playback.

For screen sharing, applications are split into two categories:

* Those which use the native wayland protocol, </code>wlr-screencopy</code>
* Those which use the API from Flatpak's <code>xdg-desktop-portal</code> (this portal is also used by native non-Flatpak applications).

Applications in the first group require not additional setup. Applications in the second group (which includes Firefox and Chromium) require setting up pipewire, wireplumber and xdg portals:

{{Todo|Move this content into [[PipeWire]].}}

apk add pipewire pipewire-pulse pipewire-tools
apk add wireplumber
apk add xdg-desktop-portal xdg-desktop-portal-wlr

Launch PipeWire with Sway. Use your service manager of choice, or add the following to sway config:

exec /usr/libexec/pipewire-launcher

If your are using automatic D-Bus activation, you also need to set DBus variables for the portal and screensharing features to work:

exec dbus-update-activation-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=sway

{{Box YELLOW|Unclear:|The following paragraph is unclear and needs further work}}

Replace dmenu (depends on X server) with bemenu (Wayland native) for launching programs and selecting which screen to share in Firefox/Chromium:

set $menu bemenu-run | xargs swaymsg exec

== Screen lock and suspend-to-RAM ==

=== Without elogind ===

Consider using {{Pkg|powerctl}}.

=== With elogind ===

Putting the system to sleep with elogind requires elevated privileges or additional configuration.

For details on configuring <code>doas</code> with <code>elogind</code>, see [[Elogind#Doas]]

To put the system to sleep after 600 seconds, use:

exec swayidle -w timeout 600 'doas /bin/loginctl suspend'

loginctl suspend command will trigger the screenlock, as mentioned in the section [[#Install elogind (optional)|Install elogind (optional)]] above.

Do not lock the screen if program is running in full screen:

for_window [app_id="^.*"] inhibit_idle fullscreen

== Brightness control ==

Controlling display backlight requires either the proper udev rules, or using some form of privilege escalation.

{{Pkg|brightnessctl}} is a reliable alternative, although its default udev rules require too wide permissions (see {{Issue|15409}}). You may need your own rules, or configure doas to allow running it as an unprivileged user.

Optionally enable brightnessctl service to restore brightness settings on reboot:

rc-update add brightnessctl

== Output scaling for high resolution displays ==

Without further configuration, program interfaces might be too small to use on high resolution displays.

Sway supports the per-display configuration of

* fractional (e.g., 1.5x), and
* integer scaling (e.g., 2x)

However, fractional scaling is discouraged due to both the performance impact and the blurry output it produces. In this case, where 1x scaling is too small and 2x scaling is too large, program-specific GTK/QT based scaling is recommended. See below.

To enable Sway scaling, the user can first preview different scaling factors with <code>wdisplays</code> package. Note the output name (eDP-1, LVDS-1) and try apply scaling factors such as 1 and 2. To make changes permanent, add

<pre>
output <name> scale <factor>
</pre>

to ~/.config/sway/config.

To use toolkit scaling, use
{{Cmd|# for GTK-based programs such as firefox and emacs:
export GDK_DPI_SCALE{{=}}2

<nowiki>#</nowiki> for QT-based programs
export QT_WAYLAND_FORCE_DPI{{=}}"physical"
<nowiki>#</nowiki> or if still too small, use a custom DPI
export QT_WAYLAND_FORCE_DPI{{=}}192 # 2x scaling
export QT_QPA_PLATFORM{{=}}"wayland-egl"
}}

== Screenshots ==
A simple tool that works well under Wayland is Grimshot. Example keybindings:
<pre>
bindsym Print exec grimshot copy area
bindsym Shift+Print exec grimshot copy screen
bindsym Control+Print exec grimshot save area ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
bindsym Control+Shift+Print exec grimshot save screen ~/Pictures/$(date +%d-%m-%Y-%H-%M-%S).png
</pre>

See [https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway the sway wiki's article] for a list of screenshot tools.

== Tweaks ==

=== Make clipboard content persistent ===
By default the clipboard content does not persist after terminating the program: you copy some text from Firefox and then exit Firefox, the copied text is also lost.

Install clipman from testing repo and add the following to sway config:

<pre>
exec wl-paste --type text/plain --watch clipman store --histpath="~/.local/state/clipman-primary.json"
bindsym $mod+h exec clipman pick --tool wofi --histpath="~/.local/state/clipman-primary.json"
</pre>

=== Firefox picture-in-picture mode/floating windows ===
Add this to your sway config file (modify the numeric values to suit your needs and your display):
<pre>
for_window [app_id="firefox" title="^Picture-in-Picture$"] floating enable, move position 877 450, sticky enable, border none
</pre>

=== Start with NumLock enabled ===
Add this to your sway config file:
<code>input type:keyboard xkb_numlock enabled</code>

=== Change mouse cursor theme and size ===
Add to your sway config:

seat seat0 xcursor_theme my_cursor_theme my_cursor_size

For example, set a mouse cursor, using GNOME Adwaita theme:

seat seat0 xcursor_theme Adwaita 16

You can inspect their values with <code>echo $XCURSOR_SIZE</code> and <code>echo $XCURSOR_THEME</code>. If reloading your config does not result in change, try logging out and in.

{{Note|Wayland allows for client-side cursors. It is possible that applications do not evaluate the values of <code>$XCURSOR_SIZE</code> and <code>$XCURSOR_THEME</code>.}}

=== Custom keyboard layout ===

To use custom keyboard layout, just use
<pre>
input type:keyboard {
xkb_file /path/to/my/custom/layout
}
</pre>

=== Changing default application fonts ===

See [[Fontconfig]]

== Troubleshooting ==

If you encounter any issues, try running <code>sway -Vc /etc/sway/config</code>. It will run sway with the default config file and set the output to be more verbose. It is generally a good idea to track your config files with git (when and if at all you use a remote repository for them, keep it private for security reasons).

=== Flatpaks ===
{{main|Flatpak}}
Due to their sandboxing, flatpaks require the use of a portal frontend (xdg-desktop-portal) and backends (such as xdg-desktop-portal-wlr, xdg-desktop-portal-gtk, xdg-desktop-portal-gnome) that implement the methods. When in doubt, install multiple backends. For more information on backends, see [https://github.com/flatpak/xdg-desktop-portal/#using-portals flatpak's page on the subject]. In addition to the steps under the "Firefox Screensharing" section, it may also be necessary to launch additional backends in your Sway config file. Otherwise, you may run into GDBus errors as your flatpak fails to interface with the portal. This can cause issues such as with opening your file directories from a flatpak application.

After installing different backends, you might need to add the relevant backends to your sway config file similarly to in the "Firefox Screensharing" section above. For example, an autostart section of your sway config file may include:
<pre>
exec /usr/libexec/xdg-desktop-portal-gtk
exec /usr/libexec/xdg-desktop-portal-wlr
exec /usr/libexec/xdg-desktop-portal-gnome
</pre>

This is only needed if they are not started automatically via other means.

=== Firefox (Flatpak) and/or GTK apps ===
==== Disappearing cursor ====
You may need to get an icon pack and possibly a theme from [https://www.pling.com/browse?cat=107&ord=latest Pling store] and set <code>GTK_THEME</code> environmental variable. Alternatively you can install a theme for all users (search [https://pkgs.alpinelinux.org/ Alpine Linux Packages] for ''*-icon-theme'') using <code>apk add</code>.

==== Missing file picker/cannot download ====

Go to ''about:config'' and set <code>widget.use-xdg-desktop-portal.file-picker</code> to 0.

=== Failing to start under certain graphics cards/multiple wlroots stacked windows spawning upon start ===
As of Dec 31 2022, [https://developer.nvidia.com/docs/drive/drive-os/latest/linux/sdk/common/topics/window_system_stub/Gnome-WaylandDesktopShellSupport136.html Nvidia still doesn't fully support Wayland]. Therefore, the possible solutions are as outlined in the link, or setting your WLR_BACKENDS environmental variables to <code>drm,libinput</code> or <code>x11</code> (add libinput here as well if you cannot use your mouse and keyboard after starting Sway). The latter also works for AMD/ATI cards ('''make sure to install libinput first''').

=== Sway socket not detected ===

See [[Sway#Installation|Installation]] for instructions on how to set this environmental variable. This issue may occur with terminal multiplexers, such as [[tmux]]

== See Also ==
* [https://wiki.archlinux.org/title/Sway Archwiki]
* [https://wiki.gentoo.org/wiki/Sway Gentoo Wiki]
* [https://wiki.postmarketos.org/wiki/Sway PostmarketOS Wiki]

[[Category:Desktop]]
[[Category:Window Managers]]
[[Category:Wayland]]

Software management

2024-03-06T20:15:38Z

Sertonix: space between # and command

If you want to run [https://www.gnu.org/software/libc/ glibc] programs in Alpine Linux, there are a few ways of doing so. You can install the [https://git.adelielinux.org/adelie/gcompat gcompat] compatibility layer, you can install glibc alongside [https://musl.libc.org/ musl] (manually, as it isn't packaged), or you could do it the easy way and use either Flatpak (the easiest), containers or a chroot. 

Because there are different use cases, this is just a slight overview about what's possible and what's sensible. 

= Your options =

== gcompat ==

gcompat is the go-to compatibility layer for Alpine users.

{{cmd|apk add {{pkg|gcompat}}}}

After that you run your binaries as normal.

== Flatpak ==

Flatpak is by far the easiest method of running any graphical glibc program on Alpine.
Firstly install it.

{{cmd|apk add {{pkg|flatpak}}}}

Then you can run any Flatpak application:

{{cmd|flatpak run <flatpak name>}}

It is recommended to enable [https://flathub.org Flathub] using its instructions [https://flatpak.org/setup/Alpine/ here], as most glibc programs you might need will be packaged there.

You can then install applications from it, for example:

{{cmd|flatpak install com.valvesoftware.Steam}}

== Chroot ==

An option that's easier to generalize to other glibc applications is installing a glibc-based distribution into a chroot. You can then either chroot into it, or use a symlink and some configuration to make its glibc (and associated libraries) usable from Alpine.

After setting up a chroot using any of the methods described below, the loader can be set up in Alpine like so (these instructions are for a Debian chroot in /var/chroots/debian, on x86_64, but can be adapted to other systems by using the appropriate paths):

{{cmd|mkdir -p /lib64
ln -s /var/chroots/debian/lib/x86_64-linux-gnu/ld-2.33.so /lib64
printf '/var/chroots/debian/lib/x86_64-linux-gnu\n/var/chroots/debian/usr/lib/x86_64-linux-gnu\n' > /etc/ld.so.conf
/var/chroots/debian/sbin/ldconfig}}

=== Gentoo Linux ===

Select a stage3 from [https://www.gentoo.org/downloads/ here] and portage latest from [https://www.gentoo.org/downloads/mirrors/ here] at gentoo/snapshots/portage-latest.tar.xz.

First,

{{cmd|doas apk add {{pkg|xz}}}}

Enter the chroot:
{{cmd|mkdir ~/chroot
cd ~/chroot
tar -xvf stage3-*.tar.xz
tar -xvf portage-latest.tar.xz
mv portage usr
doas mount --bind /dev dev
doas mount --bind /sys sys
doas mount -t proc proc proc
cp /etc/resolv.conf etc
doas chroot . /bin/bash}}

And voilà, you have your working Gentoo chroot! 

You can now take a look at [https://wiki.gentoo.org/wiki/Handbook:Main_Page Gentoo's Handbook] to find out how you can configure and install your system, or simply extract/copy the program you need to run in your chroot enviroment and execute it.

Here is a wrapper script that is similar to <code>arch-chroot</code> when you frequently reuse this chroot:

Also, create an account with the same user name as host current user to the chroot or make changes to the userspec option to chroot line.

{{Cat|gentoo-chroot.sh|<nowiki>!/bin/bash
CHROOT_PATH="/home/$USER/chroot"
cd $CHROOT_PATH
mount | grep $CHROOT_PATH/dev || doas mount --bind /dev dev
mount | grep $CHROOT_PATH/sys || doas mount --bind /sys sys
mount | grep $CHROOT_PATH/proc || doas mount -t proc proc proc
cp /etc/resolv.conf etc
doas chroot --userspec=$USER:users . /bin/bash
echo "You must manually unmount $CHROOT_PATH/dev, $CHROOT_PATH/sys, $CHROOT_PATH/proc."
</nowiki>
}}

Do at <code>chmod +x gentoo-chroot.sh</code> to get it to work.

=== Arch Linux ===

Either use '''pacstrap''' (included with the arch-install-scripts package) or an Arch bootstrap image:

{{cmd|doas apk add {{pkg|arch-install-scripts}}
mkdir ~/chroot && cd ~/chroot
curl -O https://mirrors.edge.kernel.org/archlinux/iso/latest/archlinux-bootstrap-x86_64.tar.gz
doas tar xzf archlinux-bootstrap-x86_64.tar.gz && rm archlinux-bootstrap-x86_64.tar.gz
doas sed -i '/evowise/s/^#//' root.x86_64/etc/pacman.d/mirrorlist
doas sed -i '/CheckSpace/s/^/#/' root.x86_64/etc/pacman.conf
doas arch-chroot root.x86_64
[chroot]# pacman-key --init
[chroot]# pacman-key --populate archlinux}}

Once that is done, update the system and install the desired package(s) (denoted by ''"foo"'' in this example):

{{cmd|[chroot]# pacman -Syu ''foo''}}

=== Debian ===
{{todo|gresec referencs need to be cleanly removed from this section.}}
Use the provided debootstrap package to create the Debian chroot. <code>--arch</code> is optional, depending of your needs.

On the '''linux-grsec''' kernel, you will need to relax chroot limitations:

sudo apk add debootstrap
for i in /proc/sys/kernel/grsecurity/chroot_*; do echo 0 | sudo tee $i; done
mkdir ~/chroot
sudo debootstrap --arch=i386 wheezy ~/chroot https://deb.debian.org/debian/
for i in /proc/sys/kernel/grsecurity/chroot_*; do echo 1 | sudo tee $i; done
sudo chroot ~/chroot /bin/bash

You can now use <code>apt-get</code> to install needed packages.

== Containers ==

It's also possible to use Docker or Podman containers with a helper like Distrobox. This allows using graphical programs easily and doesn't require root privileges once set up.

{{cmd|# apk add {{pkg|distrobox}}}}

=== Distrobox + Podman ===

{{cmd|# apk add {{pkg|podman}}}}

Then set up rootless Podman, following [[Podman|these steps]].
You'll need to mount your root as shared for Distrobox to function.

Fill in {{path|/etc/local.d/mount-rshared.start}} like so:

{{cmd|#!/bin/sh
mount --make-rshared /}}

Mark it as executable.

{{cmd|# chmod +x /etc/local.d/mount-rshared.start}}

Then autostart its service.

{{cmd|# rc-update add local default
# rc-service local start}}

Finally you can create a container using your chosen image.

{{cmd|$ distrobox create --image debian --name debian
$ distrobox enter debian}}

It may also be necessary to allow X authorization for GUI programs to work.

{{cmd|$ xhost +si:localuser:$USER}}

== Chroot + Bubblewrap ==

It's also possible to use a Debian system chroot with Bubblewrap. This allows running programs without root.

{{cmd|# apk add bubblewrap debootstrap
# mkdir -p /var/chroots/debian
# debootstrap --arch amd64 stable /var/chroots/debian/ https://deb.debian.org/debian}}

Finally we can make an alias for bwrap.

{{cmd|$ alias glibc{{=}}"LANG{{=}}en_US.UTF-8 bwrap --bind /var/chroots/debian / --dev-bind /dev /dev --proc /proc --bind /sys /sys --bind /run /run --bind /home /home --ro-bind /etc/resolv.conf /etc/resolv.conf --ro-bind /etc/passwd /etc/passwd --ro-bind /etc/group /etc/group"}}

To run programs that use X11/Xorg you can use:
{{cmd|$ alias glibcX11{{=}}"LANG{{=}}en_US.UTF-8 bwrap --bind /var/chroots/debian / --dev-bind /dev /dev --proc /proc --bind /sys /sys --bind /run /run --bind /home /home --ro-bind /etc/resolv.conf /etc/resolv.conf --ro-bind /etc/passwd /etc/passwd --ro-bind /etc/group /etc/group --bind /tmp/.X11-unix/X0 /tmp/.X11-unix/X0 --setenv DISPLAY :0"}}

In this case you might need to use xhost to allow local connections, e.g.:
{{cmd|# xhost + local:}}

Now we can invoke glibc-built binaries like so:
{{cmd|$ glibc ./binary}} or {{cmd|$ glibcX11 ./binary}}

For updating the Chroot or installing dependencies we can mount it and then login as root:
{{cmd|# mount --bind /dev /var/chroots/debian/dev
# mount --bind /proc /var/chroots/debian/proc
# chroot /var/chroots/debian /bin/bash
# apt update && apt upgrade}}

After installing what you might want to umount the binds for dev and proc to avoid issues.
{{cmd|# umount /var/chroots/debian/dev}}
{{cmd|# umount /var/chroots/debian/proc}}

[[Category:Development]]
[[Category:Installation]]

Steam

2024-03-02T18:26:07Z

Sertonix: Links Sway article

[https://store.steampowered.com/about/ Steam] is a popular game distribution platform by Valve.

{{Note|Steam for Linux only supports Ubuntu LTS. Thus, do not turn to Valve for support for issues with Steam on Alpine Linux.}}

== Installation ==

Steam requires glibc to run, and thus doesn't straight up run on Alpine Linux.
To work around this problem, we'll use [https://wiki.alpinelinux.org/wiki/Flatpak Flatpak].
Make sure you have the Flathub repository installed.

{{Note| commands prefixed with # are run as root, commands prefixed with $ are run as a regular user}}

# apk add {{pkg|flatpak|arch=x86_64}}
$ flatpak --user remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
$ flatpak --user install com.valvesoftware.Steam

After installation Steam can be started using it's .desktop file or on the command line:

$ flatpak run com.valvesoftware.Steam

== Troubleshooting ==

=== My controllers aren't detected ===

By default Steam doesn't have permission to read your controllers.
This can be fixed by installing an [[udev]] rule from the official Steam package, but the udev rules are also available as an Alpine package.

# apk add {{pkg|steam-devices|arch=x86_64}}

=== SteamVR won't launch ===

Out of the box SteamVR might not be able to launch and give you various errors. Steam tries to fix this itself by setting the right capabilities on the SteamVR binary, but this doesn't work in the Flatpak. Instead we'll have do it manually.

# setcap CAP_SYS_NICE+ep ~/.var/app/com.valvesoftware.Steam/data/Steam/steamapps/common/SteamVR/bin/linux64/vrcompositor-launcher

Then restart Steam.

There is an issue for this [https://github.com/flathub/com.valvesoftware.Steam/issues/636#issuecomment-779763326 on the Flathub repository].

=== Steam - Error: OpenGL GLX extension not supported by display ===

Add the Mesa gallium driver and reboot your system.

# apk add {{pkg|mesa-dri-gallium|arch=x86_64}}

=== eventfd: Too many open files ===

Due to a low amount of allowed open file descriptors, Proton games may crash shortly after launching. This can be worked around by disabling esync but many games will perform measurably worse without it. Instead, user limits should be increased. In order to do this, you will need [[PAM]] and a PAM enabled login.

Add the following to <code>/etc/security/limits.conf</code>:
@users hard nofile 524288

{{Note|Although you should already belong to the users group, you can run <code>groups</code> to check.}}

Reboot and run <code>ulimit -Hn</code> to verify the new limits are applied.

=== dbus-launch: no such file or directory ===

Set up [[D-Bus|dbus]] for your session.

=== Steam games launched via Proton crash before creating a window ===

Instead of just using the in-Steam menu to install and select a Proton version, try installing the flatpak community build for Proton onto your system. There are several versions, depending on your desired stability, and the experimental version available in Flathub is called "com.valvesoftware.Steam.CompatibilityTool.Proton-Exp". After you install your chosen version, go into Steam to specify compatibility tool for a game as usual. The installed community build will now be an option. Select that and try launching the game again.

As your last resort, you can try installing [https://github.com/GloriousEggroll/proton-ge-custom proton-ge-custom], but please note that in order for this to be even detected by Steam, you will need to install Steam via Nix due to high level of isolation that Flatpaks utilize. This can however come at the expense of your [https://tosdr.org/en/service/180 privacy].

=== Steam spams dmesg with x86/split lock detection entries ===

Add the below line to {{path|/etc/sysctl.conf}}:
kernel.split_lock_mitigate = 0

=== Steam hangs on start with a steamwebhelper popup ===

If this happens and your <pre>cat ~/.var/app/com.valvesoftware.Steam/.local/share/Steam/logs/steamwebhelper.log</pre> says that you are missing X server or $Display, it means your DISPLAY is not present in the activation environment. For more information please see https://github.com/ValveSoftware/steam-for-linux/issues/10554

[[Sway]]: go into your sway config file and add DISPLAY to the following line, then restart:
<pre>exec dbus-activation-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=sway</pre>
For more information about this line, please see the Alpine Wiki's entry on Sway

Hyprland: add an exec-once to the configuration file at ~/.config/hypr/hyprland to set DISPLAY. Similarly to Sway you may already have a line that sets other variables. If so, add DISPLAY to the line. The line should look similar to this:

<pre>exec-once = dbus-update-activation-environment DISPLAY</pre>

Greetd

2024-02-29T14:42:11Z

Sertonix: may need to add greetd to the seat group

{{DISPLAYTITLE:greetd}}

[https://git.sr.ht/~kennylevinsen/greetd greetd] is a minimal and flexible login manager daemon that makes no assumptions about what you want to launch.

This article focuses on alpine specific instructions. It is recommended to read the [https://man.sr.ht/~kennylevinsen/greetd/ greetd wiki] first.

== Installation ==

greetd needs to be combined with a greeter. You can find a list of available greeters here: {{pkg|greetd-*}}. Install the main package and the greeter you selected:

{{cmd|# apk add {{pkg|greetd}} <greeter>}}

You need to [[#Configuration|configure]] greetd before you can start it.

Enable and start greetd:
{{cmd|<nowiki># rc-update add greetd
# rc-service greetd start</nowiki>}}

== Configuration ==

Some graphical greeters (like gtkgreet) require <code>seatd</code> or [[elogind]]. Add <code>rc_need=seatd</code> or <code>rc_need=elogind</code> to {{path|/etc/conf.d/greetd}}.
When you use <code>seatd</code> with a graphical greeter it needs the <code>seatd</code> group:
{{cmd|# adduser greetd seat}}

For text based greeters you want to make sure that <code>vt</code> is set to <code>7</code> in {{path|/etc/greetd/config.toml}}. (This will be the default in alpine 3.20)

You might want to start a [[D-Bus#D-Bus_session|D-Bus session]] when the greetd session is started.

== See Also ==
* [https://man.sr.ht/~kennylevinsen/greetd/ greetd wiki]
* [https://wiki.archlinux.org/title/Greetd Arch wiki]

PAM

2024-02-29T14:26:27Z

Sertonix: link greetd page

To use PAM, the {{Pkg|linux-pam}} package itself must be installed as well as something for logging into the system that supports PAM. The <code>login</code> bundled with <code>busybox</code> does not support PAM. Instead, one of the following may be used:

* [[greetd]] plus any greeter
* <code>login(1)</code> provided by {{Pkg|shadow-login}}
* <code>login(1)</code> provided by {{Pkg|util-linux-login}}

{{warning|Login without PAM will still be possible. See {{issue|11730}}}}

== ulimit ==

<code>ulimit</code> permissions can be changed via <code>/etc/security/limits.conf</code>. These will only apply if a PAM-compatible tool is used for logging in (as indicated above).

== See Also ==

* [https://wiki.gentoo.org/wiki/PAM PAM on the Gentoo Wiki]
* [https://wiki.archlinux.org/title/PAM PAM on the ArchLinux Wiki]

[[Category:Kernel]]
[[Category:Authentication]]

Greetd

2024-02-29T14:24:46Z

Sertonix: finish sentence

{{DISPLAYTITLE:greetd}}

[https://git.sr.ht/~kennylevinsen/greetd greetd] is a minimal and flexible login manager daemon that makes no assumptions about what you want to launch.

This article focuses on alpine specific instructions. It is recommended to read the [https://man.sr.ht/~kennylevinsen/greetd/ greetd wiki] first.

== Installation ==

greetd needs to be combined with a greeter. You can find a list of available greeters here: {{pkg|greetd-*}}. Install the main package and the greeter you selected:

{{cmd|# apk add {{pkg|greetd}} <greeter>}}

You need to [[#Configuration|configure]] greetd before you can start it.

Enable and start greetd:
{{cmd|<nowiki># rc-update add greetd
# rc-service greetd start</nowiki>}}

== Configuration ==

Some graphical greeters (like gtkgreet) require <code>seatd</code> or [[elogind]]. Add <code>rc_need=seatd</code> or <code>rc_need=elogind</code> to {{path|/etc/conf.d/greetd}}.

For text based greeters you want to make sure that <code>vt</code> is set to <code>7</code> in {{path|/etc/greetd/config.toml}}. (This will be the default in alpine 3.20)

You might want to start a [[D-Bus#D-Bus_session|D-Bus session]] when the greetd session is started.

== See Also ==
* [https://man.sr.ht/~kennylevinsen/greetd/ greetd wiki]
* [https://wiki.archlinux.org/title/Greetd Arch wiki]