Alpine Linux - User contributions [en]

Alpine Linux:Contribute

2022-12-14T13:59:46Z

Chereskata: /* Contribute quality */

[[Image:kuser.png|left|link=]]
__NOTOC__
There are many ways that ''you'' can contribute. Whether you are a normal user, a geek, or a hardcore developer, the one and most important thing you can do is to actually '''use''' Alpine Linux.

The list below explains some of the ways that you can contribute.

= Contribute quality =
* Submit '''[https://gitlab.alpinelinux.org/alpine/aports/issues bug reports]'''.
* Suggest new '''[https://gitlab.alpinelinux.org/alpine features/ideas]''' (Previously: '''[[Project:Ideas|features/ideas]]''' and '''[[FAQ#Can_you_build_an_apk_package_for_....3F|packages]]''')
* Submit new '''[[Creating_an_Alpine_package|packages]]''' that you've created, or '''[[Development using git|patches]]''' to existing packages. For more information about developing on Alpine Linux, read our [[Developer Documentation]].
* Check the coverage of the [https://release-monitoring.org/ Anitya] release monitoring database for your favourite packages, and add new mappings as needed.
* Submit '''[[Special:NewFiles|artwork]]''' (icons, backgrounds, logos)
* Correct '''spelling and grammar''' mistakes in the documentation
* Help '''[[Project:Wiki_maintenance|maintain]]''' the wiki

= Contribute documentation =
* Help write good '''[[Tutorials_and_Howtos|documentation]]'''
* '''Translate''' the documentation (and program texts) into another language
* '''Proofread''' existing documentation, follow the examples, and make corrections
* Create diagrams, '''screenshots''', and graphics for the documentation
* Develop style, formatting, spelling, and grammar conventions for documenters
* Expand the '''[[Glossary]]''' of technical terms (so non-geeks can understand)
* Convert documentation into more formats

= Contribute support =
* '''Answer questions''' on the wiki, [[mailing lists]], [[IRC]] channels and [http://stackoverflow.com/questions/tagged/alpine StackOverflow]
* Contribute to (or start) an online support group
* Post a tutorial or other to https://asciinema.org
* Write '''HOWTOs''' and post them in the [[Tutorials and Howtos]] or your own blog

= Contribute projects =
* [[Wishlist]]

= Contribute publicity =
{{Tip|As Alpine Linux gets more popular, there will be more people wanting to contribute.}}
* '''[[Project:Listings|Link to]]''' the Alpine Linux web site
* Write '''reviews'''
* Convince people to choose Open Source products when possible
* Write about new ways of using an Open Source application

= Contribute appreciation =
* Be '''polite''' when reporting bugs or asking for new features; after all, the developers have no obligation to do it
* '''Express''' your appreciation to developers (through [[Mailing_lists|e-mail]], [https://gitlab.alpinelinux.org/alpine/aports/issues bug reports], and [[Alpine Linux:IRC|IRC]])
* Send the programmers post cards
* Give the project or [[Alpine_Linux:Developers|a developer a donation/gift]] (some have wish lists for this)
* Contribute to [https://www.patreon.com/musl musl libc development].

Alpine Linux:FAQ

2022-12-14T13:57:11Z

Chereskata: /* How can I contribute? */

[[Image:filetypes.svg|64px|left|link=]]
This is a list of '''frequently asked questions''' about Alpine Linux. 
If your question is not answered on this page, use the search box above to find work in progress pages not linked here, or in case of no answer, edit this page and write down your question.
{{Tip| Prepare your question. Think it through. Make it simple and understandable.}}

=General=

Alpine Linux is used heavily in containers (e.g. Docker images) on servers, so many of its main packages are focused on server services.

== Where to start? ==

The [[Installation]] page and the [[Installation#Post-Installation|Post Installation]] section on that page, provide a basic orientation.

A broader overview may be found on the official [https://alpinelinux.org/about About] page and at the [[Alpine Linux:Overview|wiki overview]].

Please note that testing is safer on your own virtual machine or on a public [https://distrotest.net/AlpineLinux/ DistroTest.net].

== I have found a bug, where can I report it? ==

You can report it on the [https://gitlab.alpinelinux.org/groups/alpine/-/issues bugtracker], but search it first to see if the issue has already been reported.

== Are there any details about the releases available? ==
Yes, please check the [https://alpinelinux.org/releases/ releases] page.

== How can I contribute? ==
You can contribute by:
* Using the software and giving [https://gitlab.alpinelinux.org/groups/alpine/-/issues feedback].
* Documenting your [https://www.alpinelinux.org Alpine Linux] experiences on this [[Main_Page|wiki]].
* Flag packages as outdated in the [https://pkgs.alpinelinux.org/packages package database], or even better enable release monitoring in [https://release-monitoring.org/ Anitya] for them.
* In many other ways.
Please visit [[Contribute|Contribute page]] to read more about this topic.

== Why don't I have man pages or where is the 'man' command? ==
The <code>man</code> command and '''man pages''' are not installed by default.

Install the <code>man</code> command:
{{cmd|# apk add mandoc}}
Install basic manual pages. {{pkg|man-pages}} package provides the system's ''core'' manual pages:
{{cmd|# apk add man-pages}}
Install the <code>apropos</code> command to search in '''man pages''':
{{cmd|# apk add mandoc-apropos}}
Once installed, add documentation for the package where you need it. For example, say you installed {{pkg|nftables}} and you now require its '''man pages''':
{{cmd|# apk add nftables-doc}}
To always install the documentation companion package add the {{pkg|docs}} meta package. Keep in mind not all packages have a corresponding documentation package and even when it has one it may not include '''man pages''':
{{cmd|# apk add docs}}

== What is the difference between edge and stable releases? ==
Stable releases are just what they sound like: initially a point-in-time snapshot of the package archives, but then maintained with bugfixes only in order to keep a stable environment.

[[Repositories#Edge|Edge]] is more of a rolling-release, with the latest and greatest packages available in the online repositories. 
Occasionally, snapshot ISO images of the then-current state of [[Repositories#Edge|edge]] are made and are available for download. 
Typically these are made when there are major kernel upgrades or package upgrades that require initramfs rebuilds.

== What architectures does Alpine support? ==
As Alpine uses the Linux kernel, it supports:
* '''aarch64''': The 64-bit only ARM execution state of the ARMv8 device machines.
* '''armhf''': The newer ARM hard-float for newer, more powerful 32-bit devices alongside 64-bit
* '''armv7''': The 32-bit only ARM execution state of the ARMv7 devices machines.
* '''s390x''': For the Super powered IBM mainframes, especially IBM Z and IBM LinuxONE servers.
* '''ppc64le''': For 64-bit PowerPC devices with pure little-endian mode, mostly for POWER8 and POWER9
* '''x86''': (i386, PC 32bit) and x86_64 (i686, PC 64bit and amd64)
* '''x86_64''': The popular AMD64 compatible 64-bit x86 based machines, i386 is not recommended for newer/latest hardware.

'''Please check [https://alpinelinux.org/downloads Download] page for media availability on each one''' and check [https://alpinelinux.org/releases/ Release Branches] page for latest.

== What kinds of release of Alpine Linux are available? ==
Please check the [https://alpinelinux.org/releases/ Release Branches] page for more information.

=Setup=

== What is the difference between ''sys'', ''data'', and ''diskless'' when running <code>setup-alpine</code> or <code>setup-disk</code>? ==

'''sys:''' This mode is a traditional disk install. The following partitions will be created on the disk: ''/boot/'', ''/'' (filesystem root) and ''swap''.
This mode may be used for development boxes, desktops, virtual servers, etc.

'''data:''' This mode uses your disk(s) for data storage, not for the operating system. Runs from the media and only a ''/var/'' is created on disk. The system itself will run from a ''tmpfs'' (RAM). Use this mode if you only want to use the disk(s) for data, like ''mailspool'', ''databases'', ''logs'', etc.

'''diskless:''' No disks are to be used. [[Alpine local backup]] may still be used in this mode.

These modes are explained further on the [[Installation#Installation_Overview|'''Installation''']] page.

== How do I upgrade Alpine? ==

To upgrade to a new stable release or edge:
<code>apk upgrade --available</code>

==Why don't my cron jobs run?==

Start service ''crond'' and add it to runlevel:

: {{cmd|rc-service crond start && rc-update add crond}}

After that the cron daemon is started automatically on system boot and executes the scripts placed in the folders under ''/etc/periodic/'' - there are folders for ''15min'', ''hourly'', ''daily'', ''weekly'' and ''monthly'' scripts.

To check whether your scripts are likely to run, use the ''run-parts'' command, for example:

: {{cmd|run-parts --test /etc/periodic/15min}}

This command will tell you what should run but will not actually execute the scripts.

If the results of the test are not as expected, check the following:

* Make sure the script is executable - if unsure, issue the command {{cmd|chmod a+x /etc/periodic/[path/scriptname]}}
* Make sure the first line of your script is <code>#!/bin/sh</code>
* Do not use periods on your script file names - this stops them from working; for example: {{Path|/etc/periodic/daily/myscript}} will run, but {{Path|/etc/periodic/daily/myscript.sh}} won't.

= Time and timezones =

== How do I set the local timezone? ==

If you wish to edit the ''timezone'' (TZ) after installation, run the [[Alpine_setup_scripts#setup-timezone|setup-timezone]] script.

= Packages =

== Can you build an apk package for ...? ==
Yes, we probably can. 
Please create a [https://gitlab.alpinelinux.org/alpine/aports/issues/new issue] in the [https://gitlab.alpinelinux.org bugtracker]. Prefix it with "feat" in the title and include a short description (one-line), a URL for the home page, and a URL for the source package.

== How can I build my own package? ==
Please see the [[Creating an Alpine package]] page.

== What does "required by: world[$pkgname]" mean? ==

It means that the package you try to install does not exist in the repositories you have configured.

Maybe you forgot to add community, testing or unmaintained to ''/etc/apk/repositories''?

Or is the package in a [[Alpine_Linux_package_management#Repository_pinning|pinned repository]] and you forgot to suffix the package with the repo tag? Example:

{{cmd|apk add experimental-package@testing}}

== How can I find out if a certain package exists in Alpine? ==

If you want to only search repositories you have configured in /etc/apk/repositories, then <code>apk search $pkgname</code> should get you sorted. If you want to search all repositories have a look at the [https://pkgs.alpinelinux.org/ online pkg oracle]

== WARNING: Ignoring APKINDEX.xxxx.tar.gz ==
If you get <code>WARNING: Ignoring APKINDEX.xxxx.tar.gz: No such file or directory</code> while running [[Alpine_Linux_package_management|package related tools]], check your {{Path|/etc/apk/repositories}} file.

To check the content of the repositories file
{{Cmd|cat /etc/apk/repositories}}

or
{{Cmd|setup-apkrepos}}

= Dynamic DNS =
== How do I schedule a regular dynamic DNS update? ==
You'll want to install the {{pkg|ez-ipupdate}} package:
{{cmd|apk add ez-ipupdate}}

After that, create a new file at {{path|/etc/ez-ipupdate.conf}} with contents similar to:
service-type=dyndns
user=myusername:mypassword
interface=eth1
host=myhostname.dyndns.org

Make the new ip cache directory:
{{cmd|mkdir /var/cache/ez-ipupdate
lbu add /var/cache/ez-ipupdate}}

Then schedule a new cron job with this command:
{{cmd|echo >> /var/log/ez-ipupdate && \ /bin/date >> /var/log/ez-ipupdate && \ ez-ipupdate --config-file /etc/ez-ipupdate.conf -f -F /var/run/ez-ipupdate.pid \ --cache-file /var/cache/ez-ipupdate/ipcache --quiet >> /var/log/ez-ipupdate 2>&1}}

Don't forget to backup your settings!
{{cmd|lbu ci}}

= Terminal =

== How to enable/fix colors for git? ==

The problem is not in git itself or terminal, but in the <tt>less</tt> command.
Busybox’s <tt>less</tt> doesn’t support <tt>-r</tt> (<tt>--raw-control-chars</tt>) and <tt>-R</tt> (<tt>--RAW-CONTROL-CHARS</tt>) options.

The simplest (yet not ideal) solution is to install GNU less:

{{cmd|apk add less}}

== Fix lacking lsusb / lspci output ==

If you launch <code>lsusb</code> or <code>lspci</code> on a minimal installation, there's no device descriptions.
This can be fixed with installing '''usbutils''' or '''pciutils''' packages respectively.

= Old questions, no longer frequently asked =

== Alpine freezes during boot from Compact Flash, how can I fix? ==
Most Compact Flash card readers do not support proper DMA. 
You should append '''nodma''' to the ''append'' line in {{path|syslinux.cfg}}.

== How do I remove the CDROM? ==
Since the modloop loopback device is on CDROM you cannot just run <code>eject</code>. You need to unmount the modloop first. 
Unmounting both the modloop and the CDROM in one step can be done by executing:
{{Cmd|/etc/init.d/modloop stop}}

Then it's possible to eject the CDROM:
{{Cmd|eject}}

== How can I install a custom firmware in a diskless system? ==

The modules and firmware are both special images which are mounted as read-only. 
To fix this issue you can copy the firmware directory to your writeable media (cf/usb) and copy your custom firmware to it. 
After reboot Alpine should automatically use the directory on your local storage instead of the loopback device.

== How do I play my .ogg/.mp3 files? ==
First, the sound card should be recognized (you must have {{path|/dev/snd/*****}} files)

{{pkg|sox}}, {{pkg|mpg123}}, etc all use the oss sound driver, while Alpine uses ALSA drivers. 
So you need to load the snd-pcm-oss compatibility module. 
While you're at it, you might need {{pkg|aumix}} to turn up the sound volume
{{cmd|echo snd-pcm-oss >> /etc/modules
modprobe snd-pcm-oss
apk_add aumix sox
aumix (set volume settings)
play really_cool_song.mp3}}

== OpenNTPD reports an error with "adjtime" ==
Your log contains something like:
reply from 85.214.86.126: offset 865033148.784255 delay 0.055466, next query 32s
reply from 202.150.212.24: offset 865033148.779314 delay 0.400771, next query 3s
adjusting local clock by 865033148.779835s
adjtime failed: Invalid argument

{{pkg|openntpd}} is supposed to make small adjustments in the time without causing time jumps. 
If the adjustment is too big then something is clearly wrong and ntpd gives up. (its actually adjtime(3) that has a limit on how big adjustments are allowed)

You can make ntpd set the time at startup by adding ''-s'' option to ntpd. This is done by setting '''NTPD_OPTS="-s"''' in {{path|/etc/conf.d/ntpd}}.

== Using a cron job to keep the time in sync ==
Add the following to {{path|/etc/periodic/daily}} (or use another folder under the {{path|/etc/periodic}} heirarchy if you want to run the script more/less frequently)

Example: file called {{path|do-ntp}}
<pre>
#!/bin/sh
ntpd -d -q -n -p uk.pool.ntp.org</pre>

This queries the uk time server pool - you can modify this to suit your localisation, or just use ''pool.ntp.org''. More info here: [http://www.pool.ntp.org/zone/@ http://www.pool.ntp.org/zone/@]

== Windows clients reports an error when trying to sync ==
{{pkg|openntpd}} needs to run for a while before it is satisfied it is in sync.
Until then it will set a flag "clock not synchronized" and Windows will report an error while trying to sync with your {{pkg|openntpd}} server.

Only thing to do is wait, do something else for 15-20mins and then check.

[[Category:Newbie]]

Package Maintainers

2022-12-14T13:46:02Z

Chereskata:

{{Draft}}

* You can be maintainer without having commit access. Committers can do commits and maintainers can send patches to committers. Any committers can apply patches from maintainers. (This is similar to what FreeBSD does)
* The maintainer is responsible for the the package and is expected to:
** fix bugs in package
** keep it updated. This includes follow upstream announcement list, RSS feed etc and provide updates to Alpine Linux in timely fashion.
*** it seems easier for maintainers to add their packages [https://release-monitoring.org/ Anitya] for automated release monitoring
* Committers and others should confirm with the maintainer before making any changes of the package.

[[Category:Development]] [[Category:Package Manager]]

Creating an Alpine package

2022-12-14T13:43:13Z

Chereskata:

{{TOC right}}

== Requirements ==

To build a package for Alpine Linux you need an Alpine Linux installation. Check the [[Installation]] page to see all available installation options.

== Setup your system and account ==
{{:Include:Setup_your_system_and_account_for_building_packages}}

== Getting some help ==

It might be wise to start by checking what the [[Abuild|abuild]] program can/cannot do.

{{Cmd|abuild -h}}

For real help, you can also go on OFTC's #alpine-devel on IRC.

A reference for APKBUILD files is available as [[APKBUILD Reference]] wiki page or a man page in the 'abuild-doc' package:

{{Cmd|man APKBUILD}}

== Creating an APKBUILD file ==

=== Use a template APKBUILD ===

To create the actual APKBUILD file {{Pkg|newapkbuild}} can serve you a template to start with. It will create a directory with the given package name, place an example/template APKBUILD file to the given directory, and fill some variables if those are provided. Please check the [[Package_policies| package policies]] page about naming details.

If you doubt to which repository your package belongs to you can safely use '''testing'''. Building package in your aports/testing directory is not mandatory but this way the package is already at the right place.

{{:Include:Newapkbuild}}

{{Note|On older Alpine systems, abuild -c -n ''packagename'' was the way to create APKBUILD files. The 'packagename' was a parameter to the -n option so order of -c and -n matters. }}

[[Abuild_and_Helpers#apkbuild-cpan|apkbuild-cpan]] simplifies the creation of perl packages from CPAN and [[Abuild_and_Helpers#apkbuild-pypi|apkbuild-pypi]] ease the generation of APKBUILD files for python packages from PyPi.

If you are creating a daemon package which needs initd scripts you can add the -c making it:

{{Cmd|newapkbuild -c ''packagename''}}

This will copy the sample initd and confd files to the build directory. 
A third file sample.install file will be copied as well (we will discuss this later on).

=== Modify your APKBUILD ===
Edit APKBUILD and fill in the needed info (especially pkgname, pkgver, pkgdesc, url, license, depends and source).

If you are going to use any of the variables for directories like $pkgdir, always make sure they are double quoted like:

"$pkgdir"/somedir

This will prevent issues with spaces/special characters in the future.

{{Note|If you like syntax highlighting we suggest you to install vim. We have setup vim to recognize the APKBUILD file as a bash scripts so its easier to read them.}}

=== APKBUILD variables/functions ===

==== 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 [[Creating an Alpine package#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/$pkgname/$pkgname-$pkgver.tar.gz</pre>
: (or similar depending on the package).

* 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>
: You must prepend '${pkgname}-${pkgver}.tar.gz::' to the protocol, like so:
: <pre>source="${pkgname}-${pkgver}.tar.gz::http://oss.example.org/?get=software&ver=1.0"</pre>
: This causes the file to be saved as ''software-1.0.tar.gz'' where abuild can use it, instead of ''?get=software&ver=1.0'', where abuild cannot use it.

* Some projects didn't provide a release tarball. Beware that some git services (gitweg, cgit, …?) doesn’t provide ''stable'' tarballs, so when you point source to an tarball like <tt>http://repo.or.cz/w/gitstats.git/snapshot/ad7efbb9399e60cee6cb217c6b47e604174a8093.tar.gz</tt>, then you will run into issues because the checksum changes when downloading on the build system. This is not a problem on GitHub, GitLab and other decent services provides, they provide ''stable'' tarballs.

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



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

==== depends & makedepends ====

Depends are the actual running dependencies that a package would need when it is running. Makedepends are only needed when you are building a package. If you set a package in depends, you do not need to add it to makedepends as well. The best way to find out what the depends and makedepends of a package are is to [http://en.wikipedia.org/wiki/Rtfm RTFM].

No kidding, lots of important information can be found in the package INSTALL and README files (or the likes). Another good way is the run <code>./configure --help</code> from the source directory to see which options are needed for configure to finish without errors. If you do not yet have a source directory you can create one with the command:

{{Cmd|abuild unpack}}

Running <code>configure</code> will also show you how you can disable a specific option for this package. For instance, a good example is "--disable-nls" which will disable native language support and thus does not depend on gettext (libiconv, glib, ...).

Alpine likes to keep things small, so we try to disable as much as possible without losing too many features. The exact disable/enable options are decided by the package builder but please try to follow Alpine's design concept as much as possible.

An easy way of quickly finding out the build info for a package is to check Arch Linux (Alpine package management and build scripts are similar) or Gentoo Linux ebuilds (previous versions of Alpine were based on Gentoo).

* [https://gitweb.gentoo.org/repo/gentoo.git/tree/ Gentoo Ebuilds]
* [http://www.archlinux.org/packages/search/ Arch Linux packages] [https://aur.archlinux.org/ Arch Linux User Repository]

==== license ====

The '''license''' tag must reflect the license of the source code. Please check the source tarball for COPYING, LICENSE, or other files with names that indicates that it contains licensing information. Beside the license file most developer include headers in the source code files with licensing details.

If the license is on the [https://spdx.org/licenses/ SPDX License List] or [https://spdx.org/licenses/exceptions-index.html SPDX License Exceptions], use the identifier specified by SPDX.

If a package has a special/custom license or is not listed as [https://opensource.org/licenses/alphabetical OSI approved], use the identifier "custom". We additionally need to provide the license file with the release. Because we want to save space and don't like to have licenses all over our system we have decided to include the license in the doc subpackage. Please follow the following guidelines to add a proper license. Locate the license file inside the source package. Add the doc subpackage to the $subpackages variable as follows:

subpackages="$pkgname-doc"

Add a similar line to the following to your package() function, depending on the license description file:

install -Dm644 COPYING "$pkgdir"/usr/share/licenses/$pkgname/COPYING

If you follow these steps then abuild will automatically add the license to the package-doc apk for you.

{{Warning|It is not acceptable to package software with "unknown" license! If you can't find the license of the source code, please contact the author and ask them to specify the license. }}

==== arch ====

The package architecture(s) to build for. This can be one of: ''x86, x86_64, all,'' or ''noarch'', where ''all'' means all architectures, and ''noarch'' means it's architecture-independent (e.g., a pure-python package).
{{Tip|To determine if your APKBUILD can use ''noarch'', build the package for your architecture and then run "scanelf -R pkg" from the directory that the APKBUILD resides in, in order to scan for ELF files in the ''./pkg'' directory. If you do NOT get output from this, then ''noarch'' can be used.}}

==== url ====

Website address for the program. This is useful later on when either finding documentation or other information about the package.

==== pkgdesc ====

A brief, one line, description of what the package does. Useful for the package management system. It should start with a capital letter and does '''not''' end with a period.

Here is an example from apk_info for the OpenSSH client package:

pkgdesc="Port of OpenBSD's free SSH release - client"

==== pkgver ====

Provide the release number of the package you are building.

==== pkgrel ====

The $pkgrel versioning is made so that if you change something in your APKBUILD file without changing the actual $pkgver, you can increment pkgrel so apk tools will detect it as an update. For instance, if you forget to add a dependency, you can add it afterward and you can +1 pkgver so apk finds this update and adds the missing dependency. When there's an upstream version change, we reset the pkgrel to 0.

==== pkgname ====

The base name of the package you are creating. For Freeswitch 1.0.6, you would use "freeswitch"

==== install ====

There are 6 different kinds of install scripts. Each script is called with the $pkgname.''<action>'' where ''<action>'' is one of the following:

<dl>
<dt>$pkgname.pre-install
<dd>This script is executed before package is installed. Typical use is when package needs a group and a user to be created. For example:
<pre>
#!/bin/sh

addgroup -S clamav 2>/dev/null
adduser -S -D -H -s /bin/false -G clamav -g clamav clamav 2>/dev/null

exit 0
</pre>
Note the ''exit 0'' at the end. If the script exits with failure (if the user already exist), the package will not be installed and <code>apk add</code> will exit with failure.

<dt>$pkgname.post-install
<dd>This script is executed after the package is installed.

<dt>$pkgname.pre-upgrade
<dd>Same as pre-install but is executed before upgrading/downgrading/reinstalling an already installed package. Note that exiting with failure will not cause apk to exit with failure, but will mark the package as broken.

<dt>$pkgname.post-upgrade
<dd>Same as post-install but is executed after upgrading/downgrading/reinstalling an already installed package.

<dt>$pkgname.pre-deinstall
<dd>This script is executed before uninstalling a package. If script exits with failure apk will not uninstall the package.

<dt>$pkgname.post-deinstall
<dd>This script is executed after a package have been uninstalled. For example, can be used to restore busybox links:
<pre>
#!/bin/sh
busybox --install -s
</pre>

</dl>

If the package has a pre-install and post-install script the APKBUILD should have the ''install'' variable defined:
<pre>
...
install="$pkgname.pre-install $pkgname.post-install"

...
</pre>

==== subpackages ====

$subpackages are made to split up the normal "make install" into separate packages. The most common subpackages we use are doc and dev. Because we like to keep our target system small we move documentation and development files (only needed when building packages) into separate packages. To use the specific program a user only need to install the base apk without package-doc or package-dev, but if he wants to read the manual he will need to install package-doc.

The easiest way to find out if you need to use -dev and -doc is to first build the package without these options set and wait until the build finishes. When its finished you should have a pkg directory which is the fake root directory. Inside this directory you will see the structure as how it would be installed in / on the target system.

To see if you need the -dev package you can run the following cmd:

{{Cmd|find pkg/usr/ -name '*.[acho]' -o -name '*.la'}}

If this returns any files you need to include the -dev package.

 To see if you need the -doc package you can run the following cmd:

{{Cmd|find pkg/usr/share -name doc -o -name man -o -name info -o -name html -o -name sgml -o -name licenses}}

If this returns any directories you need to include the -doc package.

===== Custom subpackages =====

Some software additionally has non-essential files that do not qualify as either documentation or development content. These files should be placed in their own, specialized subpackage(s). Some packages include large test suites which are only needed in specific circumstances or binaries which have depends which we prefer not to install. To handle those we create our own package/function. In the APKBUILD below the build() function we create another function:

test() {
mkdir -p "$subpkgdir"/usr
mv "$pkgdir"/usr/package-test "$subpkgdir"/usr/
# or amove usr/package-test
}

We also need to add the package info to $subpackages variable:

subpackages="$pkgname-doc $pkgname-dev $pkgname-test"

After we finish building the package you should see another apk called packagename-test.apk which includes the files which we moved to the $subpkgdir dir.

The above mentioned variables can also be used in our custom function. If we want for instance to build the test() function with perl support we would add:

depends="perl"
makedepends="perl-dev"

If we would install the base package it would not install perl, but if we install the package-test package it would.

==== Patches ====

Please make sure you always submit human readable patches. Ways to create them are:

directory compare:

{{Cmd|diff -Nurp original_directory new_directory > filename.patch}}

file compare:

{{Cmd|diff -up original.file new.file > filename.patch}}

If a patch contains a completely new file but not *.rej or *.orig file, you need to add -N option to diff, but you may need to add exclusions with <code>--exclude PATTERN</code> so that you do not inadvertently add files. You may need to manually delete unwanted files inside the patch file.

Because multiple patches can patch the same file, they can change the offsets required by subsequent patches. To make sure we always patch in a specific way, we should number the patches as follows:

10-patch1.patch 20-patch2.patch 30-patch3.patch

This way we are always sure that patch 1 is applied first, and if we want to add additional patches between them we can use appropriate indexes (e.g. 11, 12, 21, 22).

Add the names of the patch files to the ''source'' variable. If you haven't declared a custom ''prepare'' function, no further action is necessary. Otherwise, be sure to call ''default_prepare'' in your ''prepare'' function. For example:

prepare() {
default_prepare

# do your stuff
}

Note: Some older packages contain a ''for'' loop in the ''prepare'' function to apply patches. This is not needed anymore, as patches are handled by ''default_prepare''.

In Alpine >=3.4 you can define patch_args to supply the patch level. This only works if all the patches have the same patch level. If there are a lot of patches from different sources, there is a good chance that you may need to edit them, as discussed below.

To automatically patch the package (available only in Alpine >=3.4) if it uses a patch level (-pX) other than the default (-p1), you need to carefully modify the patch. First, you'll need a text editor that does not automatically convert between Windows and Unix new lines (or, disable this feature) so that it preserves the old code. The next thing you'll need to do is modify the paths on "+++" and "---" lines in the .patch file. You can begin the path with a/ and b/ like shown below. Next, you need to adjust the paths so that the relative base path is from inside $builddir. Anything to the left of $builddir, including $builddir itself, needs to be removed from the path. So, if $builddir is /home/USER/aports/community/chromium/src/chromium-65, you need to erase it on the "+++" and "---" lines. Inside the chromium-65 folder you can see a src folder that has 3rdparty as a descendant. If a patch originally has a deeper patch level, you may need to fill in the missing portion of the path. For example, use the <code>find . -name "Assertions.cpp"</code> command to find the full path to the file relative to the base.

{{Cat|example.patch|<nowiki>
Author: John Doe <johndoe@mail.com>
URL: http://.....
Summary: Fixes musl compatibility
----
--- a/src/3rdparty/chromium/third_party/WebKit/Source/wtf/Assertions.cpp.orig
+++ b/src/3rdparty/chromium/third_party/WebKit/Source/wtf/Assertions.cpp
@@ -142,7 +142,7 @@
};

FrameToNameScope::FrameToNameScope(void* addr) : m_name(0), m_cxaDemangled(0) {
-#if OS(MACOSX) || (OS(LINUX) && !defined(__UCLIBC__))
+#if OS(MACOSX) || (OS(LINUX) && defined(__GLIBC__))
Dl_info info;
if (!dladdr(addr, &info) || !info.dli_sname)
return;
</nowiki>}}

Portions of the patch may be outdated, removed completely as in the source code file completely removed, or moved or renamed files. You need to delete that section of the patch or find where that section of code changed and re-diff it.

It is good etiquette to give credit at the top and the location of where you originally found them with notes.

Excluding patches with global variable resembling patch_opts is not available on Alpine. To exclude patches you need to create your own custom prepare().

If you have a monolithic patch where there are a bunch of patches in one big patch, you could use filterdiff which is available in the patchutils package.

Just do something like:

<pre>
makedepends="patchutils"

prepare() {
...
cd "$builddir"
filterdiff -x '*drivers/video/logo*' "$srcdir"/original.patch > "$builddir"/modified.patch
patch -p1 -i "$builddir"/modified.patch
}
</pre>

You need to put the wildcard pattern in single quotes for it to work.

==== Configure options ====

Alpine has some default configure options we set by default. We use /usr for prefix to make sure everything is installed with /usr in front of it. If you notice that anything is installed in the wrong directory please run {{Cmd|./configure --help}} and see if you can set the correct location.

We are not covering the depend switches here we have discussed this already in the depend section.

==== Make options ====

If you notice weird problems when compiling or installing the package with make/make install you could try to disable [http://www.gnu.org/software/make/manual/make.html#Parallel parallel] building/installing. A normal make line would be:

make

To disable parallel we use:

make -j1

We can use the same for make install.

Because we do not want to install the package in our build environment but we want to install it in a fake root directory we need to tell 'make install' to use another destination directory instead of '/'. We do this by setting a variable when we execute make install as followed:

make DESTDIR="$pkgdir" install

Please note that some Makefiles do not support this variable and will always install software in '/'. To make sure you do not mess up your build system NEVER run your build system as root but always use a custom user and doas when needed. If by accident the Makefile does not support DESTDIR variable it will fail to install in our build system system directories.

==== builddir ====
If you used <tt>newapkbuild</tt> to create your APKBUILD file, you must specify the path to your unpacked sources. Inside the sections during the prepare/build/install process ''builddir'' is used. Most of the time a combination of ''$srcdir'' and ''$pkgname-$pkgver'' will work. When not, check the /src directory or the source tarball for the right string. Especially when you are working with automatically generated tarballs (like from github and gitorious), this needs to be adjusted.

builddir="$srcdir"/$pkgname-$pkgver

==== Additional files ====

If you want/need to install additional files not mentioned above you can use the following cmd (this is an example of a conf file):

install -Dm644 doc/$pkgname.conf "$pkgdir"/etc/$pkgname.conf

== Build the package ==

If you did not already create the checksums as mentioned above you can do so now:

{{Cmd|cd $pkgname
abuild checksum}}

It's about time we build our package. Because a build system should never have all the package installed to prevent linking to packages we don't want it to link we use a abuild recursively with the '''-r''' switch. It will install all dependencies from your repository and builds it, afterwards it will uninstall all those depending packages again.

{{Cmd|abuild -r}}

See also [[Abuild_and_Helpers|Abuild and Helpers]].

== Testing the package locally ==

When it completes, your package will be found in a subfolder of <code>~/packages</code>. You may want to test it on your machine but only if the package is not a critical system package like musl or apk-tools package. To avoid borking your system (as in making it impossible to use <code>apk add</code> or to restore back the system and the compiler toolchain) for a critical system package, you should test on a chroot first before using it live.

The best way to test a package locally is to modify your <code>/etc/apk/repositories</code> so that it includes the indexes to your locally built packages - the directories that contain <code>ARCH/APKINDEX.tar.gz</code>. For example the <code>/etc/apk/repositories</code> below includes locally built packages in testing, community and main. To use this example change <code>USER</code> to your login name.

{{Cat|/etc/apk/repositories|/home/USER/packages/testing/
/home/USER/packages/main/
/home/USER/packages/community/
https://dl-cdn.alpinelinux.org/alpine/edge/main
https://dl-cdn.alpinelinux.org/alpine/edge/community
https://dl-cdn.alpinelinux.org/alpine/edge/testing
}}

If you prefer to test a package without changing any other configuration you can use the <code>-X, --repository</code> option to <code>apk</code>:

{{Cmd|doas apk add --repository /home/USER/packages/testing $pkgname}}

== Code review ==

To successfully have your package pass through code reviewers (as of Feb 18, 2018 are nmeum and jirutka on GitHub) and possible increased acceptance, the following conventions need to be followed:

# Custom global variables should be prefixed with underscore (_).
# Compact code as in merged commands, removed unused variables, removal of functions that do the same thing that are automatically handled by abuild.
# Versioning is done properly. For details see [[APKBUILD_Reference#pkgver]].
# Licensing is done properly. Remove unnecessary copying of licensing that is already OSI approved.
# Naming conventions rules for unofficial variables as in _gitrev is preferred over commit.
# Indent with tabs not spaces.
# Removal of explicit return 1. (They are still found the old APKBUILD files if you are learning but are now strongly discouraged.)
# Disabling check() requires either (1) a comment (#) stating next to options="!check" that there is no test suite/unit tests or (2) functioning working check() function.
# Explicit call to subpackages="$pkgname-doc" must be used instead of explicit gzip man page compression.
# Ideally, lines should be no more than 80 columns wide

Additionally, make sure to run the linter on your package:
{{Cmd|doas apk add atools
apkbuild-lint APKBUILD}}

For more information see [[Development using git:Quality assurance]] and [[Package_policies]].

== Commit your work ==

After you successfully build your package and properly followed the conventions and requirements in the code review section, you can submit your APKBUILD to Alpine's git repository.

Update your git repo, before adding new files:

{{Cmd|cd $aportsdir
git pull}}

This should pull all the changes made by others into your local git repo.

When you think you are ready you can add your files to git:

NOTE: when using our Gitlab instance, you can create MR's for each package. Please squash all commits related to the same package into a single one per MR.

{{Cmd|cd $aportsdir
git add testing/$pkgdir (include any other files needed for the build; $pkgname.install...)
git commit}}

Use the following commit message template for new aports (without the comments):

{{Cat|template|testing/$pkgname: new aport # this will be the subject line
# a blank line
$url # project homepage
$pkgdesc # one line description}}

Or you could add the following and <code>chmod +x ports/.git/hooks/prepare-commit-msg</code> to automatically generate commit message which the default aports/.githooks/ does not:

{{Cat|aports/.git/hooks/prepare-commit-msg|<nowiki>#!/bin/sh
case "$2,$3" in
,|template,)
if git diff-index --diff-filter=A --name-only --cached HEAD \
| grep -q '/APKBUILD$'; then
meta() { git diff --staged | grep "^+$1" | sed 's/.*="\?//;s/"$//';}
printf 'testing/%s: new aport\n\n%s\n%s\n' "$(meta pkgname)" \
"$(meta url)" "$(meta pkgdesc)" "$(cat $1)" > "$1"
else
printf '%s\n\n%s' `git diff-index --name-only --cached HEAD \
| sed -n 's/\/APKBUILD$//p;q'` "$(cat $1)" > "$1"
fi;;
esac</nowiki>}}

Now your changes are only available locally in your repository.

Because you do not have push rights to the Alpine aports repository you need to create a merge request to [https://gitlab.alpinelinux.org/alpine/aports Alpine's GitLab instance].

Alternatively you can also create a diff (patch) of the changes you made and send this patch to the
[https://lists.alpinelinux.org/~alpine/aports alpine-aports mailinglist].

To create a diff patch:

{{Cmd|git format-patch HEAD^}}

or if you have sprunge, you can create a link to your patch for convenience

{{Cmd|git format-patch HEAD^ --stdout <nowiki>|</nowiki> sprunge}}

== Send a patch ==

[[Creating_patches#Only_the_last_commit_with_.27git_send-email.27|git send-email]] will do that for you.

== Automated flagging of outdated ports ==
Consider adding your port to [https://release-monitoring.org/ Anitya], so it will be flagged as outdated
as soon as a new stable version is released by upstream.

== See Also ==
* [[APKBUILD Reference]]
* [[APKBUILD examples]]
* [[Development using git]]
* [[Development using git:Quality assurance]]

[[category: Package Manager]]