Creating an Alpine package: Difference between revisions

From Alpine Linux
No edit summary
(→‎license: Add list of known licenses that require copyright notice to be included)
 
(237 intermediate revisions by 58 users not shown)
Line 1: Line 1:
DRAFT
{{TOC right}}
== Overview ==


This document assumes that you have a working [[Setting up the build environment 1.9|build environment]], or use a diskbased alpine installation.  
This is a brief list of the steps to add a new package. Details are below, but a NB can miss a few steps.


=== The APKBUILDs  ===
# Create an account on https://gitlab.alpinelinux.org
# [[Abuild_and_Helpers#Setting_up_the_build_environment|Setup the build environment for aports]].
# Fork the [https://gitlab.alpinelinux.org/alpine/aports aports repository].
# Clone your new fork.
# Set git pull.rebase=true, set your username and email.
# Create and switch to a new branch (don't use master).
# Add a new directory under testing that is your new package name.
# Add your APKBUILD file.
# Run abuild checksum
# Make sure you run the apkbuild-lint and aport -r and there are no warnings.
# Commit your APKBUILD with the commit message: 'testing/packagename: new aport'
# Push your changes to your fork on https://gitlab.alpinelinux.org/alpine.
# Create a merge request.


The ''[http://dev.alpinelinux.org/cgit/cgit.cgi/abuild abuild]'' script reads the ''[http://dev.alpinelinux.org/cgit/cgit.cgi/abuild//tree/APKBUILD.proto APKBUILD]'' and executes the steps needed to create a package.  
Please see the rest of this wiki for details on the steps above.


=== The aports tree  ===
== Requirements ==


The [http://dev.alpinelinux.org/cgit/cgit.cgi/aports aports] tree is a [http://dev.alpinelinux.org/cgit/cgit.cgi/aports/tree directory tree] with many APKBUILDs. Those files are used when building alpine from source.  
To build a package for Alpine Linux you need an Alpine Linux installation. Check the [[Installation]] page to see all available installation options.


== Installing and configuring the alpine-sdk ==
== Setup your system and account ==
{{:Setup_your_system_and_account_for_building_packages}}


The alpine-sdk is a metapackage that pulls in the most essinsial packages used to build new packages. To install those packages:
== Getting some help ==


'''NOTE''': if you used the [[Setting up the build environment 1.9|build environment]] howto, you already have alpine-sdk installed.  
It might be wise to start by checking what the [[Abuild and Helpers|abuild]] program can/cannot do.


apk add alpine-sdk
{{Cmd|abuild -h}}


The aports tree is in git so before we can clone the aports tree we need to install and configure git. We need to tell git our name and email.  
For real help, you can also go on #alpine-devel on [[IRC]].


  git config --global user.name "Your Full Name"
A reference for APKBUILD files is available as [[APKBUILD Reference]] wiki page or a man page in the 'abuild-doc' package:
  git config --global user.email "your@email.address"


Now we can clone the aports tree.
{{Cmd|man APKBUILD}}


  git clone git://dev.alpinelinux.org/aports


Before we are going to create APKBUILD files we need to setup abuild to our system/user. Please edit the file /etc/abuild.conf to your likings.
== Creating an APKBUILD file ==
 
=== Use a template APKBUILD ===


== Creating an APKBUILD file ==
The newapkbuild tool, which is installed as part of the {{Pkg|abuild}} package, can create you a new APKBUILD 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.


=== General info  ===
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.


APKBUILD files are read by the abuild program mentioned above. To see what abuilld can/cannot do you can execute:  
{{:Abuild and Helpers}}


abuild -h
{{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. }}


To create the actual APKBUILD file abuild has the option -n (new). It will simply copy an example APKBUILD file to the given directory and fill some variables. If you are create a daemon package which needs initd scripts you can add the -c making it:
[[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.


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


'''NOTE''': The ''packagename'' is a parameter to the -n option so order of -c and -n matters.
{{Cmd|newapkbuild -c ''packagename''}}


<br> 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).  
This will copy the sample initd and confd files to the build directory.<BR>
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).  
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 directory's like $pkgdir always make sure they are double quoted like:  
If you are going to use any of the variables for directories like $pkgdir, always make sure they are double quoted like:  


  "$pkgdir"/somedir
  "$pkgdir"/somedir
Line 54: Line 70:
This will prevent issues with spaces/special characters in the future.  
This will prevent issues with spaces/special characters in the future.  


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.  
{{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  ===
=== APKBUILD variables/functions  ===
Line 60: Line 76:
==== source  ====
==== source  ====


Source is not only the link from which abuild will fetch the source, it should also hold all files abuild needs to build the apk. This could mean initd file, confd file, install file, patches or any other file needed. When you are finished adding them you can execute the following cmd to add checksum's to the APKBUILD file:  
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:


abuild checksum
* 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.}}


Another thing to note is when a package is using sourceforge as hosting, if so you should add special mirrors link used by sf:  
* 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).


http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz  
* 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.


(or similar depending on the package).  
* 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>https://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.


Currently abuild support the following archives/extensions:  
* abuild currently supports the following protocols for remote file retrieval:
** http
** https
** ftp


  *.tar.gz, *.tgz, *.tar.bz2, *.tar.lzma, *.zip
<!--: {{Note|If the you want to download from https, you need GNU wget installed on your system.}}-->
   
* 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 &amp; makedepends  ====
==== depends &amp; makedepends  ====


Depends are the actual running dependencies which a package would need when you are using it. 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 anymore. The best way to find out what depends and makedepeds are of a package is to [http://en.wikipedia.org/wiki/Rtfm RTFM].  
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 [https://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:


No kidding, lots of important information can be found it the package INSTALL and README file (or the likes). Another good way is the run ./configure --help from the source directory to see which options are needed for configure to finish without errors. If you do not yet have a src directory you can create one by doing:
{{Cmd|abuild unpack}}


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, ...).


It will also show you how you can disable a specific option for this package. A good example is for instance "--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.


Alpine likes to keep things small, so we try to disable as much as possible without loosing to many features. The exact disable/enable options are decided the package builder but please try to follow Alpines 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).


An easy way of quickly finding out build info of a package is to check Archlinux (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]
* [https://archlinux.org/packages/?q=search Arch Linux packages] [https://aur.archlinux.org/ Arch Linux User Repository]


[http://www.gentoo-portage.com Search ebuilds]
==== license  ====


[http://sources.gentoo.org/viewcvs.py/gentoo-x86/ Gentoo CVS]
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.


[http://www.archlinux.org/packages/search/ Archlinux packages]  
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.


After the package is successfully compiled and created we should make sure it didn't link to any package which is not present in the $depends variable. We do this be using scanelf. If scanelf is not yet installed on your system you can do that by installing pax-utils.
Note that some licenses have additional requirements that should be adhered to. The <code>MIT</code> license for example has the requirement:


scanelf -nR pkg
<blockquote>
The above copyright notice and this permission notice (including the next paragraph) shall be included in all copies or substantial portions of the Software.
</blockquote>


example output of libcurl would be:
This means that we need to include the license as shipped with the project.


ET_DYN libssl.so.0.9.8,libcrypto.so.0.9.8,libz.so.1,libc.so.0,ld-uClibc.so.0 pkg/usr/lib/libcurl.so.4.1.1
Known licenses that require this:


You can see the needed files and should be able to find out which file belongs to which package.
* <code>MIT</code>
* <code>ISC</code>


==== license ====
If a package has a special/custom license or is not listed as [https://opensource.org/licenses/alphabetical OSI approved], use the identifier "custom". In that case we need to provide the license file with the package as well.


If a package has a special/custom license we need to provide it 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 into the doc subpackage. Please follow the following guideline to add a proper license. Locate the license file inside the source package. Add to $subpackages variable the following:  
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"
  subpackages="$pkgname-doc"


And add a similar line to your build() function depending on the license:  
Add a similar line to the following to your package() function, depending on the license description file:  
 
{{Cmd|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. }}


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


If you follow these steps then abuild will automaticly add the license to the package-doc apk for you.  
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  ====
==== url  ====


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


==== pkgdesc  ====
==== pkgdesc  ====


editme
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  ====
==== pkgver  ====


editme
Provide the release number of the package you are building.


==== pkgrel  ====
==== pkgrel  ====


The $pkgrel versioning is made so if you change something to your APKBUILD file without changing the actual $pkgver you can higer 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 add the missing dependency.  
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  ====
==== pkgname  ====


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


==== install  ====
==== install  ====


The install file is a script which will be execute by apk-tools when you are install,deinstall,update a package. An example of using it is when you need to add a user/group to the system. The install file will only be run on the actual install so it will only add the user and group to the target system and not to the build system when we are building it. Another good example is displaying a message to the user when installing a package.
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


Please remember, commands specified in the build() function in APKBUILD will be run on both build system and target system.  
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.


Please check the sample install file for syntax.  
<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  ====
Line 152: Line 245:
To see if you need the -dev package you can run the following cmd:  
To see if you need the -dev package you can run the following cmd:  


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


If this returns any files you need to include the -dev package.  
If this returns any files you need to include the -dev package.  
Line 158: Line 251:
<br> To see if you need the -doc package you can run the following cmd:  
<br> To see if you need the -doc package you can run the following cmd:  


find pkg/usr/share -name doc -o -name man -o -name info -o -name html -o -name sgml -o -name licenses
{{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.  
If this returns any directories you need to include the -doc package.  
Line 164: Line 257:
===== Custom subpackages  =====
===== Custom subpackages  =====


Some applications will have except doc and dev files other non needed at run time files which we want to separate away from the base package. 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:  
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() {
  test() {
         mkdir -p "$subpkgdir"/usr
         mkdir -p "$subpkgdir"/usr
         mv "$pkgdir"/usr/package-test "$subpkgdir"/usr/
         mv "$pkgdir"/usr/package-test "$subpkgdir"/usr/
        # or amove usr/package-test
  }
  }
   
   
Line 187: Line 281:
==== Patches  ====
==== Patches  ====


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


directory compare:  
directory compare:  


diff -urp original_directory new_directory &gt; filename.patch
{{Cmd|diff -Nurp original_directory new_directory &gt; filename.patch}}


file compare:  
file compare:  


diff -up original.file new.file &gt; filename.patch
{{Cmd|diff -up original.file new.file &gt; 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 are going to use multiple patches for a single package, the preferred way to handle those is a loop and numbering the patches.  
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.


for i in "$srcdir"/*.patch; do
Just do something like:
        msg "Applying ${i}"
        patch -p0 -i $i || return 1
done


Because multiple patches can patch the same file, we could create offset for the next patch. To make sure we always patch in a specified way we should number the patches as followed:
<pre>
makedepends="patchutils"


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


This way we are always sure patch 1 is first and if we want to add additional patches between them we can use 11,12,21,22...  
You need to put the wildcard pattern in single quotes for it to work.


==== Configure options  ====
==== Configure options  ====


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


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


==== Make options  ====
==== 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:  
If you notice weird problems when compiling or installing the package with make/make install you could try to disable [https://www.gnu.org/software/make/manual/make.html#Parallel parallel] building/installing. A normal make line would be:  


make || return 1
{{Cmd|make}}


To disable parallel we use:  
To disable parallel we use:  


make -j1 || return 1
{{Cmd|make -j1}}


We can use the same for make install.  
We can use the same for make install.  
Line 230: Line 375:
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:  
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
{{Cmd|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.


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 customer user and sudo when needed. If by accident the Makefile does not support DESTDIR variable it will fail to install in our build system system directories.
<pre>
builddir="$srcdir"/$pkgname-$pkgver
</pre>


==== Additional files  ====
==== Additional files  ====
Line 238: Line 390:
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):  
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
{{Cmd|install -Dm644 doc/$pkgname.conf "$pkgdir"/etc/$pkgname.conf}}


== Build the package  ==
== Build the package  ==
Line 244: Line 396:
If you did not already create the checksums as mentioned above you can do so now:  
If you did not already create the checksums as mentioned above you can do so now:  


cd $pkgname
{{Cmd|cd $pkgname
abuild checksum
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]].


Its about time we build our package. Because a build system should never have all the package installed to prevent linking to packages we dont want it to link we use a abuild recursively with the -r switch. It will install all dependency's from your repository and builds it, afterwards it will uninstall all those depending packages again. You could also use the -R switch which would build your package including the dependency packages.
== Testing the package locally ==


  abuild -r
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]].
Also check out [https://gitlab.alpinelinux.org/alpine/aports/-/blob/master/COMMITSTYLE.md?ref_type=heads aports/COMMITSTYLE.md] and [https://gitlab.alpinelinux.org/alpine/aports/-/blob/master/CODINGSTYLE.md?ref_type=heads aports/CODINGSTYLE.md]


== Commit your work  ==
== Commit your work  ==


After you successfully build your package you can submit your APKBUILD to alpine git repository.  
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):


Update you git repo, before adding new files:
{{Cat|template|testing/$pkgname: new aport  # this will be the subject line
                              # a blank line
$url                          # project homepage
$pkgdesc                      # one line description}}


cd $aportsdir
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:
git pull


This should pull all the changes made by others into you local git repo. When you think you are ready you can add your files to git:
{{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>}}


cd $apkbuilddir
Now your changes are only available locally in your repository.
git add APKBUILD
git commit


Now your changes are only available locally in your repo. Because you do not have push rights to the alpine repo you need to create diff (patch) of the changes you made:  
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].


  git format-patch -1
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].


Where -1 sets how many commits you want to go back (mostly this is 1). This should create a patch called 0001......patch.
To create a diff patch:


An easy way to send this patch to the list is with an program called 'email'.
{{Cmd|git format-patch HEAD^}}


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


to send to the mailing list you would do:
{{Cmd|git format-patch HEAD^ --stdout <nowiki>|</nowiki> sprunge}}


email -a 0001...patch alpine-devel@lists.alpinelinux.org
== 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.


And provide a subject and body after you execute the above cmd.
== See Also ==
* [[APKBUILD Reference]]
* [[APKBUILD examples]]
* [[Development using git]]
* [[Development using git:Quality assurance]]


<br> If you doubt to which repo your package belongs to you can safely use extra. If you are not sure your package works at all you need to use testing.
[[category: Package Manager]]

Latest revision as of 05:33, 30 September 2024

Overview

This is a brief list of the steps to add a new package. Details are below, but a NB can miss a few steps.

  1. Create an account on https://gitlab.alpinelinux.org
  2. Setup the build environment for aports.
  3. Fork the aports repository.
  4. Clone your new fork.
  5. Set git pull.rebase=true, set your username and email.
  6. Create and switch to a new branch (don't use master).
  7. Add a new directory under testing that is your new package name.
  8. Add your APKBUILD file.
  9. Run abuild checksum
  10. Make sure you run the apkbuild-lint and aport -r and there are no warnings.
  11. Commit your APKBUILD with the commit message: 'testing/packagename: new aport'
  12. Push your changes to your fork on https://gitlab.alpinelinux.org/alpine.
  13. Create a merge request.

Please see the rest of this wiki for details on the steps above.

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

The alpine-sdk is a metapackage that pulls in the most essential packages used to build new packages. Also install and configure a way to elevate privileges, such as sudo or doas, and an editor, such as vi, nano, micro.

# apk add alpine-sdk

This would be a good time to create a normal user account for you to work in. To make life easier later, it's a good idea to add this user to the wheel group; operations that require superuser privileges can now be done with sudo or doas.

The aports tree is in git so before we clone it, let's configure git.

$ git config --global user.name "Your Full Name" $ git config --global user.email "your@email.address"

Read carefully Development using git to grasp basic Git operations and how to configure for sending email patches.

Now we can clone the aports tree.

$ git clone https://gitlab.alpinelinux.org/alpine/aports

Before we start creating or modifying APKBUILD files, we need to setup abuild for our system and user. Edit the file /etc/abuild.conf to your requirements.

Most of the defaults can be left alone, unless you are developing for a custom platform, in which case the comments in the file should guide you. The one field to edit is PACKAGER, so that you can get credit (or blame) for packages you create.

To use 'abuild -r' command to install dependency packages automatically (and other 'abuild' commands that require it).

# addgroup <yourusername> abuild

Note: Remember to logout and login again for the group change to have effect.

The last step is to configure the security keys with the abuild-keygen script for abuild with the command:

# abuild-keygen -a -i

Getting some help

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

abuild -h

For real help, you can also go on #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:

man APKBUILD


Creating an APKBUILD file

Use a template APKBUILD

The newapkbuild tool, which is installed as part of the abuild package, can create you a new APKBUILD 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 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.

The abuild package provides scripts necessary for creating packages for Alpine Linux. It implements functionality for building packages as well as additional commands and options for package maintenance.

For package development and maintenance, it is recommended to install the alpine-sdk, which will install abuild in addition to other relevant tools.

apk add alpine-sdk

The git repository always contains the latest version of the scripts, example-files, and makefiles.

Building packages

Prerequisites

In order to use abuild:

Basic usage

If you just want to build a package from an APKBUILD file, only two command are needed. Both commands operate on an APKBUILD file in the current directory, so you should cd into the directory before running them.

  • abuild checksum: updates the checksums for source files.
  • abuild -r: builds the package.

The manual page (available via man abuild) describes all options and commands for abuild.

Building in a chroot

Install package abuild-rootbld:

apk add abuild-rootbld

You may now build your packages from source in an unprivileged sandbox based on bubblewrap with the command:

abuild rootbld

rootbld assumes your APKBUILD file is in the ~/aports whose structure like aports or you need to set environment variable APORTSDIR to current directory. If the build process needs network access there has to bet set the net option in APKBUILD.

Note that using rootbld inside a docker container requires additional configuration.


Bumping a package version

The tool abump is a utility to bump pkgver in APKBUILD files if the package gets an update to a newer upstream release. abump will update the package's pkgver, rebuild it and create a new commit with the resulting changes.

The manual page (available via man abump) describes all options for abump.

Updating a package release

If you want to bump or reset the pkgrel value of your APKBUILD or test your APKBUILD files, apkgrel can assist you.

apkgrel -a|-h|-s NUM|-t|-z [-f] FILE...

apkgrel options

  • -a Add 1 to current pkgrel
  • -f Force, even if given files are not in proper format
  • -h Show this help
  • -s Set pkgrel to NUM
  • -t Only verify that files are in proper format
  • -z Set pkgrel to 0

Generating new APKBUILDs

newapkbuild

To create the actual APKBUILD file 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 in the given directory, and fill some variables if those are provided.

The manual page (available via man newapkbuild) describes all options for newapkbuild.

apkbuild-cpan

The Comprehensive Perl Archive Network (CPAN) provides a large collection of perl software and documentation. apkbuild-cpan helps with the creation of APKBUILD for perl modules from CPAN.

apkbuild-cpan [create <Module::Name> | check | recreate | update | upgrade]

This command is provided by the apkbuild-cpan package.

apkbuild-pypi

The Python Package Index (PyPi) is a repository of software and libraries for the Python programming language. apkbuild-pypi helps with the creation of APKBUILD for python package hosted at PyPI.

apkbuild-pypi [create <package> | check | recreate | update | upgrade

This command is provided by the apkbuild-pypi package.

Signing packages and indexes

abuild-sign

abuild-sign is for signing indexes.

abuild-sign [-hq] [-k PRIVKEY] [-p PUBKEY] INDEXFILE...

abuild-sign options

  • -h Show this help
  • -k The private key to use for signing
  • -p The name of public key. apk add will look for /etc/apk/keys/PUBKEY

abuild-tar

apkbuild-tar [--hash[=<algorithm>]] [--cut]

apkbuild-tar options

  • --hash[=sha1|md5] Read tar archive from stdin, precalculate hash for regular entries and output tar archive on stdout
  • --cut Remove the end of file tar record

buildrepo

buildrepo creates a local package repository for you.

buildrepo [-a APORTSDIR] [-d REPODIR] [-hp] [-l LOGPREFIX ] [-r DEPREPO] REPOSITORY...

buildrepo options

  • -a Set the aports base dir to APORTSDIR instead of $HOME/aports
  • -d Set destination repository base dir to REPODIR instead of $HOME/packages
  • -h Show this help and exit
  • -l Send build to logfile, prefixed by LOGPREFIX
  • -p Purge obsolete packages from REPODIR after build
  • -r Dependencies are found in DEPREPO


Setting up the build environment

abuild-keygen

For abuild a public/private rsa key pair is needed. abuild-keygen does the generation of those keys for you.

abuild-keygen -a -i

abuild-keygen options

  • -a Set PACKAGER_PRIVKEY=<generated key> in abuild.conf
  • -i Install public key into /etc/apk/keys using sudo
  • -h Show this help
  • -n Non-interactive. Use defaults
  • -q Quiet mode


Creating keys manually

In older versions of Alpine, we had to manually create keys for signing packages and indexes. This explains how. Nowadays you can just use abuild-keygen.

Since the public key needs to be unique for each developer, the email address should be used as name for the public key.

Create the private key:

openssl genrsa -out emailaddress.priv 2048

Tip: Append -aes256 if you want it encrypted, but then you'll need to enter the password for every package you sign

Create the public key:

openssl rsa -in emailaddress.priv -pubout -out /etc/apk/keys/emailaddress

The public key should be distributed and installed into /etc/apk/keys on the alpine box that will install the packages. The private key, when created by abuild, is installed into ~/.abuild/$something.rsa. This basically means that the main developer's public keys should be in /etc/apk/keys on all Alpine boxes.


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.

apkbuild-cpan simplifies the creation of perl packages from CPAN and 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:

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 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:

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:
http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz
(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:
http://oss.example.org/?get=software&ver=1.0
You must prepend '${pkgname}-${pkgver}.tar.gz::' to the protocol, like so:
source="${pkgname}-${pkgver}.tar.gz::http://oss.example.org/?get=software&ver=1.0"
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 https://repo.or.cz/w/gitstats.git/snapshot/ad7efbb9399e60cee6cb217c6b47e604174a8093.tar.gz, 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 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 ./configure --help 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:

abuild unpack

Running configure 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).

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 SPDX License List or SPDX License Exceptions, use the identifier specified by SPDX.

Note that some licenses have additional requirements that should be adhered to. The MIT license for example has the requirement:

The above copyright notice and this permission notice (including the next paragraph) shall be included in all copies or substantial portions of the Software.

This means that we need to include the license as shipped with the project.

Known licenses that require this:

  • MIT
  • ISC

If a package has a special/custom license or is not listed as OSI approved, use the identifier "custom". In that case we need to provide the license file with the package as well.

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:

$pkgname.pre-install
This script is executed before package is installed. Typical use is when package needs a group and a user to be created. For example:
#!/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

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 apk add will exit with failure.

$pkgname.post-install
This script is executed after the package is installed.
$pkgname.pre-upgrade
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.
$pkgname.post-upgrade
Same as post-install but is executed after upgrading/downgrading/reinstalling an already installed package.
$pkgname.pre-deinstall
This script is executed before uninstalling a package. If script exits with failure apk will not uninstall the package.
$pkgname.post-deinstall
This script is executed after a package have been uninstalled. For example, can be used to restore busybox links:
#!/bin/sh
busybox --install -s

If the package has a pre-install and post-install script the APKBUILD should have the install variable defined:

...
install="$pkgname.pre-install $pkgname.post-install"

...

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:

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:

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:

diff -Nurp original_directory new_directory > filename.patch

file compare:

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 --exclude PATTERN 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 find . -name "Assertions.cpp" command to find the full path to the file relative to the base.

Contents of example.patch

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;

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:

makedepends="patchutils"

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

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

./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 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 newapkbuild 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:

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.

abuild -r

See also Abuild and Helpers.

Testing the package locally

When it completes, your package will be found in a subfolder of ~/packages. 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 apk add 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 /etc/apk/repositories so that it includes the indexes to your locally built packages - the directories that contain ARCH/APKINDEX.tar.gz. For example the /etc/apk/repositories below includes locally built packages in testing, community and main. To use this example change USER to your login name.

Contents of /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 -X, --repository option to apk:

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:

  1. Custom global variables should be prefixed with underscore (_).
  2. Compact code as in merged commands, removed unused variables, removal of functions that do the same thing that are automatically handled by abuild.
  3. Versioning is done properly. For details see APKBUILD_Reference#pkgver.
  4. Licensing is done properly. Remove unnecessary copying of licensing that is already OSI approved.
  5. Naming conventions rules for unofficial variables as in _gitrev is preferred over commit.
  6. Indent with tabs not spaces.
  7. Removal of explicit return 1. (They are still found the old APKBUILD files if you are learning but are now strongly discouraged.)
  8. 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.
  9. Explicit call to subpackages="$pkgname-doc" must be used instead of explicit gzip man page compression.
  10. Ideally, lines should be no more than 80 columns wide

Additionally, make sure to run the linter on your package:

doas apk add atools apkbuild-lint APKBUILD

For more information see Development using git:Quality assurance and Package_policies. Also check out aports/COMMITSTYLE.md and aports/CODINGSTYLE.md

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:

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.

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):

Contents of 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 chmod +x ports/.git/hooks/prepare-commit-msg to automatically generate commit message which the default aports/.githooks/ does not:

Contents of aports/.git/hooks/prepare-commit-msg

#!/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

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 Alpine's GitLab instance.

Alternatively you can also create a diff (patch) of the changes you made and send this patch to the alpine-aports mailinglist.

To create a diff patch:

git format-patch HEAD^

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

git format-patch HEAD^ --stdout | sprunge

Automated flagging of outdated ports

Consider adding your port to Anitya, so it will be flagged as outdated as soon as a new stable version is released by upstream.

See Also