Alpine Linux - User contributions [en]

Creating an Alpine package

2011-01-10T16:58:02Z

Amanison: /* Installing and configuring the alpine-sdk */

== General ==

This document assumes that you have a working [[Setting up the build environment|build environment]], or use a diskbased alpine installation.

=== The APKBUILDs ===

The ''[http://dev.alpinelinux.org/cgit/abuild/ abuild]'' script reads the ''[http://dev.alpinelinux.org/cgit/abuild/tree/sample.APKBUILD APKBUILD]'' and executes the steps needed to create a package.

=== The aports tree ===

The [http://dev.alpinelinux.org/cgit/aports aports] tree is a [http://dev.alpinelinux.org/cgit/aports/tree directory tree] with many APKBUILDs. Those files are used when building alpine from source.

== Installing and configuring the alpine-sdk ==

The alpine-sdk is a metapackage that pulls in the most essential packages used to build new packages. 
Install those packages now:

apk add alpine-sdk

This would be a good time to create a normal user account for you to work in. (You weren't going to develop as root now, were you!) To create the user:

adduser <yourusername>

To make life easier later, it's a good idea to add this user to /etc/sudoers. Append the line

<yourusername> ALL=(ALL) ALL

using the command:

visudo

Now logout of the root account, and login as <yourusername>. From here on everything can be done in a normal user account, and operations that require superuser privileges can be done with sudo.

The aports tree is in git so before we clone the aports tree we should configure git.

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

Now we can clone the aports tree.

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

Before we start creating or modifying APKBUILD files we need to setup abuild to our system/user. Edit the file 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.

sudo vi /etc/abuild.conf

We also need to prepare the location that the build process caches files when they are downloaded. By default this is /var/cache/distfiles. To create this directory and ensure that it is writeable, enter the following commands:

sudo mkdir -p /var/cache/distfiles
sudo chmod a+w /var/cache/distfiles

The last step in preparation is to configure the security keys 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

== Creating an APKBUILD file ==

=== Use a template APKBUILD ===

To create the actual APKBUILD file abuild has the option -n (new). It will simply copy an example/template 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 -c -n ''packagename''

{{Note|The 'packagename' is a parameter to the -n option so order of -c and -n matters. Further, on newer Alpine systems, 'newapkbuild' has replaced abuild with the -n switch.}}

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:
: <pre>abuild checksum</pre>
: {{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 'saveas-' to the protocol and append '/software-1.0.tar.gz' (for instance) to the end of the URI, like so:
: <pre>saveas-http://oss.example.org/?get=software&ver=1.0/software-1.0.tar.gz</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.

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

* abuild currently supports the following archive types/archive file extensions:
** .tar.gz / .tgz
** .tar.bz2
** .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 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 with the command:

abuild unpack

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

* [http://www.gentoo-portage.com Search ebuilds]
* [http://sources.gentoo.org/viewcvs.py/gentoo-x86/ Gentoo CVS]
* [http://www.archlinux.org/packages/search/ Arch Linux packages]

After the package is successfully compiled and created we should make sure it didn't link to any package that is not present in the $depends variable. We do this by using scanelf. If scanelf is not yet installed on your system you can do that by installing pax-utils.

scanelf -nR pkg

An example output of libcurl would be:

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

You can see the needed files and should be able to find out which file belongs to which package.

==== license ====

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 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 build() 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.

==== 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 (ie, 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 usefully 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.

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

==== 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 user/group to be created. For example:
<pre>
#!/bin/sh
adduser -H -s /bin/false -D 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 apk add will exit with failure.

===== $pkgname.post-install =====
This script is executed after package is installed. Can be used to generate font cache and similar.

===== $pkgname.pre-upgrade =====
Same as pre-install but is executed before upgrading an already installed package.

===== $pkgname.post-upgrade =====
Same as post-install but is executed after upgrading 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. Can be used to update font caches and restore busybox links. For example:
<pre>
#!/bin/sh
busybox --install -s
</pre>

If the package have an pre-install and post-install script the APKBUILD should have the ''install'' variable defined and the scripts should also be added to the source variable:
<pre>
...
install="$pkgname.pre-install $pkgname.post-install"
source="http://....
$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:

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

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

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. Way's to create them are:

directory compare:

diff -urp original_directory new_directory > filename.patch

file compare:

diff -up original.file new.file > filename.patch

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.

for i in "$srcdir"/*.patch; do
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:

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

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

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

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 || return 1

To disable parallel we use:

make -j1 || return 1

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 sudo when needed. If by accident the Makefile does not support DESTDIR variable it will fail to install in our build system system directories.

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

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.

abuild -r

== Commit your work ==

After you successfully build your package you can submit your APKBUILD to alpine git repository.

Update you git repo, before adding new files:

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

cd $apkbuilddir
git add APKBUILD (include any other files needed for the build; $pkgname.install...)
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:

git format-patch -1

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

An easy way to send this patch to the list is with an program called 'email'.

apk_add email

to send to the mailing list you would do:

email -a 0001...patch alpine-devel@lists.alpinelinux.org

And provide a subject and body after you execute the above cmd.

 If you doubt to which repo your package belongs to you can safely use testing.

== See Also ==
* [[APKBUILD Reference]]
* [[Development using git]]

Setting up a SSH server

2010-01-24T17:38:21Z

Amanison: /* Make it autostart */

= General =
If you need to administer a Alpine Linux box, you can install and use openssh. 
Openssh is used to provide a secure encrypted communications between you and the host where openssh is running (the ssh-server is called ''sshd'' and the ssh-client is called ''ssh'').

== Initial Setup ==
We assume you are running a ''alpine-1.8.x''. If not, please follow [http://wiki.alpinelinux.org/w/index.php?title=Installing_Alpine Installing_Alpine] on how to setup Alpine.

== Install programs ==
Installing programs in Alpine Linux is easy. 
In this case we only need to install one program:
apk_add openssh

'''''Note:''' If you want the ACF-frontend for openssh, you should install 'acf-openssh' instead (assuming that you have setup-webconf)''

== Make it autostart ==
Next time you reboot your Linux box, you would probably want your ''sshd'' to automatically start.
rc-update add sshd

You can check your boot sequence:
rc_status

== Start it up now ==
The reason we want to manually start ''sshd'' at this moment is... 
We want ''sshd'' to create some initial files that he needs. After they are created, we can permanently save them. 
Next reason is... we don't have time to wait for the box to reboot ;-)
/etc/init.d/sshd start
'''''Note:''' Don't forget to permanently save your settings by using the 'lbu ci' command when you are done.''

= Fine tuning =
The default config that comes with openssh has pretty good default values. 
But sometimes you would like to fine-tune things. We show some examples below on what you might want to do. 
'''''Note:''' You are _not_ required to follow this [[#Fine_tuning]] section. You can skip it if you want to make things easy!''

The fine-tuning is done by editing '''/etc/ssh/sshd_config''' 
"#" marks that the rest of the line should be ignored by ''sshd''. Everything right to the "#" is treated as comments.
UseDNS no # By setting this to no, you could increase speed when the client starts to connect to this ssh-server
PasswordAuthentication no # Instead you could use private/public keys to authenticate to this box (this increases security for the box)
Many other options are found in '''/etc/ssh/sshd_config'''. The describing text that comes in the same file will guide you in your fine-tuning.

= Firewalling =
As default, sshd will communicate on port ''''22'''' using protocol ''''TCP''''. 
You would need to make sure that the box where ''sshd'' is running, doesn't block your connection attempts on '''22TCP'''. 
If you still have trouble accessing your box, make sure that there is no other firewall blocking your connection.

Sometimes '''22TCP''' is blocked by some firewall that you can not control. In those cases you might want to configure '''sshd''' to communicate on some other port. 
In that case you change '''/etc/ssh/sshd_config''' to reflect your needs. 
But before you do so, you need to check so you don't use a port that already is in use. (You can check this by using the command ''''netstat -ln'''' on the box where you plan to run ''sshd'')
Port 443 # Use whatever port number that fits your needs

You need to restart ''sshd'' after you done you modifications.
/etc/init.d/sshd restart

= Save settings =
If you already haven't done so, save all your settings
lbu ci

Alpine Configuration Framework Design

2009-11-27T18:37:22Z

Amanison: /* Starting ACF */

= Alpine Configuration Framework =

The Alpine Configuration Framework (ACF) is a mvc-style application for configuring an Alpine device. The primary focus is for a web interface - ACF's main goal is to be a light-weight MVC "webmin".

== Why Haserl + Lua ==

Other competitors in the arena were Webmin, Ruby on Rails, PHP with templates.

A full webmin (Perl), RoR or PHP implementation each require several MB of installed code, and can have very slow startup times, especially when used in "cgi" mode. After evaluating many options, we found that [http://www.lua.org Lua] has the following advantages:

*It is small (typically ~200KB of compiled code)
*It compiles and runs much faster than [http://shootout.alioth.debian.org/gp4/benchmark.php?test=all&lang=lua&lang2=php PHP], [http://shootout.alioth.debian.org/gp4/benchmark.php?test=all&lang=lua&lang2=perl Perl] or [http://shootout.alioth.debian.org/gp4/benchmark.php?test=all&lang=lua&lang2=ruby Ruby]
*It provides a "normal" scripting language with [http://en.wikipedia.org/wiki/Lua_(programming_language)#Features features] similar to PHP, perl, java, awk, etc.

Haserl + Lua provides a 'good enough' toolset to build a full-featured web application.

== Why ACF is MVC ==

The MVC design pattern is used to separate presentation information from control logic. By MVC we mean:

*'''Model''' - code that reads / writes a config file, starts / stops daemons, or does other work modifying the router.
*'''View''' - code that formats data for output
*'''Controller''' - code that glues the two together

Note the lack of words like: HTML, XML, OO, AJAX, etc. The purpose of ACF's MVC is simply to separate the configuration logic from the presentation of the output.

The flow of a single transaction is:

start -> execute requested function in '''controller''', optionally reading/writing a file using functions in the '''model''' -> execute the '''view''' to format the output -> end

''Every'' transaction follows this pattern. For ACF developers, the focus should be on getting a model that does a proper job of abstracting the config file into useable entities and then building a controller that presents useable "actions" based on the model. The presentation layer should be last on the priority list.

For good background information on what ACF attempts to do, please see Terence Parr's paper "Enforcing Strict Model-View Separation in Template Engines" at [http://www.cs.usfca.edu/~parrt/papers/mvc.templates.pdf http://www.cs.usfcs.edu] or the [[Media:Mvc.templates.pdf|local copy]] of the pdf.

= Starting ACF =

The easiest way to start ACF is to run the ''setup-webconf'' script (renamed to ''setup-acf'' in Alpine beta 4 and later). This script will install mini-httpd, create a certificate, and start mini-httpd in HTTPS mode. '''WARNING - This will give anyone on the network access to your machine.''' The script will also install the two packages that are necessary for basic ACF: acf-core and acf-alpine-baselayout. To view ACF, simply browse to your machine (https://<hostname>/).

Alternately, you can manually install ACF and your web server. Once again, the two critical ACF packages are acf-core and acf-alpine-baselayout. The ACF packages will install to /usr/share/acf. You can configure your web server to give access to /usr/share/acf/www and run cgi scripts from /usr/share/acf/www/cgi-bin, and you should be able to view ACF.

If you would like to play with other ACF packages, we recommend you install the acf-apk-tools package. This package will allow you to install / delete other packages using ACF. You can then load any other acf-* packages you are interested in.

In alpine 1.8, the system includes two default users: ''alpine'' and ''foo''. 'alpine' is given ADMIN rights and 'foo' is given USER rights. The default password for both users is ''test123''. '''Replace the default users as soon as possible.''' In alpine 1.9, you will be prompted to create an initial user the first time you try to log in. (As of 1.9.1, the initial user is already created and is the root account for the system.)

[[Managing ACF|Managing Your ACF Installation]]

= ACF Developer's Guides =

#[[ACF mvc.lua reference|mvc.lua reference]] - mvc.lua is the core of ACF
#[[ACF mvc.lua example|mvc.lua example]] - build a simple (command-line) application
#[[ACF acf www-controller.lua reference|acf www-controller reference]] - ACF www application functions
#[[ACF acf www example|acf www-controller example]] - webify the above examples
#[[ACF how to write]] - Step by step howto for writing acfs
#[[ACF core principles]] - Things that are standard across the application
#[[LPOSIX]] - Documentation for the Lua Posix functions
#[[ACF Libraries]] - Document the libraries and common functions
#[[Writing ACF Views]] - Guide for writing a view
#[[Writing ACF Controllers]] - Guide for writing a controller
#[[Writing ACF Models]] - Guide for writing a model

== Other useful links ==

#[http://www.lua.org/manual/5.1/ Lua 5.1 Reference Manual]
#[http://www.lua.org/pil/ Programming in Lua (first edition)]

= ACF Layout =

ACF has support for multiple skins. Only a few skins are available. Feel free to contribute in programming css-stylesheets for ACF.

== Howto contribute ==

First download ACF using git or installing available acf's using apk_add. Easiest is if you download latest Alpine ISO, boot a box on that and then run 'setup-alpine' and 'setup-webconf -a' (renamed to ''setup-acf'' in Alpine beta 4 and later)that way you get a running environment fast and easy! Some example skins are available

*/usr/share/acf/www/skins/ice/
*/usr/share/acf/www/skins/snow/

Make a new skin-folder

mkdir /usr/share/acf/www/skins/myskin

Create a css file called as the folder.

touch /usr/share/acf/www/skins/myskin/myskin.css

Now you can start editing your myskin.css. If you have ACF running on a computer, you can browse to this ACF-page and switch to your new skin (called myskin) and see the results of your changes.

Pack your myskin-folder, containing your css-file (and images, if there is any). Send this patch to acf@lists.alpinelinux.org ''('''Note:''' Don't forget to [http://wiki.alpinelinux.org/w/index.php?title=Mailing_lists subscribe] before sending your patch)''

= ACF Packages =

Look at [http://wiki.alpinelinux.org/w/index.php?title=ACF_packages ACF packages] to see available ACF modules and their status.

Creating an Alpine package

2009-11-24T09:27:55Z

Amanison: /* pkgdesc */

== General ==

This document assumes that you have a working [[Setting up the build environment|build environment]], or use a diskbased alpine installation.

=== The APKBUILDs ===

The ''[http://dev.alpinelinux.org/cgit/abuild/ abuild]'' script reads the ''[http://dev.alpinelinux.org/cgit/abuild/tree/sample.APKBUILD APKBUILD]'' and executes the steps needed to create a package.

=== The aports tree ===

The [http://dev.alpinelinux.org/cgit/aports aports] tree is a [http://dev.alpinelinux.org/cgit/aports/tree directory tree] with many APKBUILDs. Those files are used when building alpine from source.

== Installing and configuring the alpine-sdk ==

The alpine-sdk is a metapackage that pulls in the most essential packages used to build new packages. 
Install those packages now:

apk add alpine-sdk

This would be a good time to create a normal user account for you to work in. (You weren't going to develop as root now, were you!) To create the user:

adduser <yourusername>

To make life easier later, it's a good idea to add this user to /etc/sudoers. Append the line

<yourusername> ALL=(ALL) ALL

using the command:

visudo

Now logout of the root account, and login as <yourusername>. From here on everything can be done in a normal user account, and operations that require superuser privileges can be done with sudo.

The aports tree is in git so before we clone the aports tree we should configure git.

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

Now we can clone the aports tree.

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

Before we start creating or modifying APKBUILD files we need to setup abuild to our system/user. Edit the file 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.

vi /etc/abuild.conf

The last step in preparation is to configure the security keys 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

== Creating an APKBUILD file ==

=== Use a template APKBUILD ===

To create the actual APKBUILD file abuild has the option -n (new). It will simply copy an example/template 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 -c -n ''packagename''

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

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

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 command to add their checksums to the APKBUILD file:

abuild checksum

Another thing to note is when a package is using sourceforge for hosting. If so you should specify the special mirrors link used by sf:

http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz

(or similar depending on the package).

Currently abuild supports the following archives/extensions:

*.tar.gz, *.tgz, *.tar.bz2, *.tar.lzma, *.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 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 with the command:

abuild unpack

Running configure 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 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 Archlinux (Alpine package management and build scripts are similar) or Gentoo linux ebuilds (previous versions of Alpine were based on Gentoo).

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

[http://sources.gentoo.org/viewcvs.py/gentoo-x86/ Gentoo CVS]

[http://www.archlinux.org/packages/search/ Archlinux packages]

After the package is successfully compiled and created we should make sure it didn't link to any package that is not present in the $depends variable. We do this by using scanelf. If scanelf is not yet installed on your system you can do that by installing pax-utils.

scanelf -nR pkg

An example output of libcurl would be:

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

You can see the needed files and should be able to find out which file belongs to which package.

==== license ====

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 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 build() 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.

==== url ====

Website address for the program. This is usefully 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.

Here is an example from apk_info for the OpenSSH client package

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

==== pkgver ====

A brief, one line, description of what the package does. Useful for the package management system. 

 

Example from apk_info 

openssh-client-5.1_p1-r1 - Port of OpenBSD's free SSH release - client 

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

==== pkgname ====

editme

==== 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 user/group to be created. For example:
<pre>
#!/bin/sh
adduser -H -s /bin/false -D 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 apk add will exit with failure.

===== $pkgname.post-install =====
This script is executed after package is installed. Can be used to generate font cache and similar.

===== $pkgname.pre-upgrade =====
Same as pre-install but is executed before upgrading an already installed package.

===== $pkgname.post-upgrade =====
Same as post-install but is executed after upgrading 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. Can be used to update font caches and restore busybox links. For example:
<pre>
#!/bin/sh
busybox --install -s
</pre>

If the package have an pre-install and post-install script the APKBUILD should have the ''install'' variable defined and the scripts should also be added to the source variable:
<pre>
...
install="$pkgname.pre-install $pkgname.post-install"
source="http://....
$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:

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

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

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. Way's to create them are:

directory compare:

diff -urp original_directory new_directory > filename.patch

file compare:

diff -up original.file new.file > filename.patch

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.

for i in "$srcdir"/*.patch; do
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:

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

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

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

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 || return 1

To disable parallel we use:

make -j1 || return 1

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 sudo when needed. If by accident the Makefile does not support DESTDIR variable it will fail to install in our build system system directories.

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

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.

abuild -r

== Commit your work ==

After you successfully build your package you can submit your APKBUILD to alpine git repository.

Update you git repo, before adding new files:

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

cd $apkbuilddir
git add APKBUILD (include any other files needed for the build; $pkgname.install...)
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:

git format-patch -1

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

An easy way to send this patch to the list is with an program called 'email'.

apk_add email

to send to the mailing list you would do:

email -a 0001...patch alpine-devel@lists.alpinelinux.org

And provide a subject and body after you execute the above cmd.

 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.

Creating an Alpine package

2009-11-24T09:26:35Z

Amanison: /* pkgdesc */

== General ==

This document assumes that you have a working [[Setting up the build environment|build environment]], or use a diskbased alpine installation.

=== The APKBUILDs ===

The ''[http://dev.alpinelinux.org/cgit/abuild/ abuild]'' script reads the ''[http://dev.alpinelinux.org/cgit/abuild/tree/sample.APKBUILD APKBUILD]'' and executes the steps needed to create a package.

=== The aports tree ===

The [http://dev.alpinelinux.org/cgit/aports aports] tree is a [http://dev.alpinelinux.org/cgit/aports/tree directory tree] with many APKBUILDs. Those files are used when building alpine from source.

== Installing and configuring the alpine-sdk ==

The alpine-sdk is a metapackage that pulls in the most essential packages used to build new packages. 
Install those packages now:

apk add alpine-sdk

This would be a good time to create a normal user account for you to work in. (You weren't going to develop as root now, were you!) To create the user:

adduser <yourusername>

To make life easier later, it's a good idea to add this user to /etc/sudoers. Append the line

<yourusername> ALL=(ALL) ALL

using the command:

visudo

Now logout of the root account, and login as <yourusername>. From here on everything can be done in a normal user account, and operations that require superuser privileges can be done with sudo.

The aports tree is in git so before we clone the aports tree we should configure git.

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

Now we can clone the aports tree.

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

Before we start creating or modifying APKBUILD files we need to setup abuild to our system/user. Edit the file 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.

vi /etc/abuild.conf

The last step in preparation is to configure the security keys 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

== Creating an APKBUILD file ==

=== Use a template APKBUILD ===

To create the actual APKBUILD file abuild has the option -n (new). It will simply copy an example/template 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 -c -n ''packagename''

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

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

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 command to add their checksums to the APKBUILD file:

abuild checksum

Another thing to note is when a package is using sourceforge for hosting. If so you should specify the special mirrors link used by sf:

http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz

(or similar depending on the package).

Currently abuild supports the following archives/extensions:

*.tar.gz, *.tgz, *.tar.bz2, *.tar.lzma, *.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 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 with the command:

abuild unpack

Running configure 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 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 Archlinux (Alpine package management and build scripts are similar) or Gentoo linux ebuilds (previous versions of Alpine were based on Gentoo).

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

[http://sources.gentoo.org/viewcvs.py/gentoo-x86/ Gentoo CVS]

[http://www.archlinux.org/packages/search/ Archlinux packages]

After the package is successfully compiled and created we should make sure it didn't link to any package that is not present in the $depends variable. We do this by using scanelf. If scanelf is not yet installed on your system you can do that by installing pax-utils.

scanelf -nR pkg

An example output of libcurl would be:

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

You can see the needed files and should be able to find out which file belongs to which package.

==== license ====

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 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 build() 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.

==== url ====

Website address for the program. This is usefully 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.

Here is an example from apk_info 

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

==== pkgver ====

A brief, one line, description of what the package does. Useful for the package management system. 

 

Example from apk_info 

openssh-client-5.1_p1-r1 - Port of OpenBSD's free SSH release - client 

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

==== pkgname ====

editme

==== 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 user/group to be created. For example:
<pre>
#!/bin/sh
adduser -H -s /bin/false -D 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 apk add will exit with failure.

===== $pkgname.post-install =====
This script is executed after package is installed. Can be used to generate font cache and similar.

===== $pkgname.pre-upgrade =====
Same as pre-install but is executed before upgrading an already installed package.

===== $pkgname.post-upgrade =====
Same as post-install but is executed after upgrading 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. Can be used to update font caches and restore busybox links. For example:
<pre>
#!/bin/sh
busybox --install -s
</pre>

If the package have an pre-install and post-install script the APKBUILD should have the ''install'' variable defined and the scripts should also be added to the source variable:
<pre>
...
install="$pkgname.pre-install $pkgname.post-install"
source="http://....
$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:

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

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

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. Way's to create them are:

directory compare:

diff -urp original_directory new_directory > filename.patch

file compare:

diff -up original.file new.file > filename.patch

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.

for i in "$srcdir"/*.patch; do
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:

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

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

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

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 || return 1

To disable parallel we use:

make -j1 || return 1

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 sudo when needed. If by accident the Makefile does not support DESTDIR variable it will fail to install in our build system system directories.

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

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.

abuild -r

== Commit your work ==

After you successfully build your package you can submit your APKBUILD to alpine git repository.

Update you git repo, before adding new files:

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

cd $apkbuilddir
git add APKBUILD (include any other files needed for the build; $pkgname.install...)
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:

git format-patch -1

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

An easy way to send this patch to the list is with an program called 'email'.

apk_add email

to send to the mailing list you would do:

email -a 0001...patch alpine-devel@lists.alpinelinux.org

And provide a subject and body after you execute the above cmd.

 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.

Creating an Alpine package

2009-11-24T09:25:52Z

Amanison: /* pkgdesc */

== General ==

This document assumes that you have a working [[Setting up the build environment|build environment]], or use a diskbased alpine installation.

=== The APKBUILDs ===

The ''[http://dev.alpinelinux.org/cgit/abuild/ abuild]'' script reads the ''[http://dev.alpinelinux.org/cgit/abuild/tree/sample.APKBUILD APKBUILD]'' and executes the steps needed to create a package.

=== The aports tree ===

The [http://dev.alpinelinux.org/cgit/aports aports] tree is a [http://dev.alpinelinux.org/cgit/aports/tree directory tree] with many APKBUILDs. Those files are used when building alpine from source.

== Installing and configuring the alpine-sdk ==

The alpine-sdk is a metapackage that pulls in the most essential packages used to build new packages. 
Install those packages now:

apk add alpine-sdk

This would be a good time to create a normal user account for you to work in. (You weren't going to develop as root now, were you!) To create the user:

adduser <yourusername>

To make life easier later, it's a good idea to add this user to /etc/sudoers. Append the line

<yourusername> ALL=(ALL) ALL

using the command:

visudo

Now logout of the root account, and login as <yourusername>. From here on everything can be done in a normal user account, and operations that require superuser privileges can be done with sudo.

The aports tree is in git so before we clone the aports tree we should configure git.

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

Now we can clone the aports tree.

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

Before we start creating or modifying APKBUILD files we need to setup abuild to our system/user. Edit the file 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.

vi /etc/abuild.conf

The last step in preparation is to configure the security keys 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

== Creating an APKBUILD file ==

=== Use a template APKBUILD ===

To create the actual APKBUILD file abuild has the option -n (new). It will simply copy an example/template 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 -c -n ''packagename''

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

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

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 command to add their checksums to the APKBUILD file:

abuild checksum

Another thing to note is when a package is using sourceforge for hosting. If so you should specify the special mirrors link used by sf:

http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz

(or similar depending on the package).

Currently abuild supports the following archives/extensions:

*.tar.gz, *.tgz, *.tar.bz2, *.tar.lzma, *.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 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 with the command:

abuild unpack

Running configure 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 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 Archlinux (Alpine package management and build scripts are similar) or Gentoo linux ebuilds (previous versions of Alpine were based on Gentoo).

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

[http://sources.gentoo.org/viewcvs.py/gentoo-x86/ Gentoo CVS]

[http://www.archlinux.org/packages/search/ Archlinux packages]

After the package is successfully compiled and created we should make sure it didn't link to any package that is not present in the $depends variable. We do this by using scanelf. If scanelf is not yet installed on your system you can do that by installing pax-utils.

scanelf -nR pkg

An example output of libcurl would be:

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

You can see the needed files and should be able to find out which file belongs to which package.

==== license ====

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 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 build() 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.

==== url ====

Website address for the program. This is usefully 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. 

Here is an example from apk_info 

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

==== pkgver ====

A brief, one line, description of what the package does. Useful for the package management system. 

 

Example from apk_info 

openssh-client-5.1_p1-r1 - Port of OpenBSD's free SSH release - client 

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

==== pkgname ====

editme

==== 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 user/group to be created. For example:
<pre>
#!/bin/sh
adduser -H -s /bin/false -D 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 apk add will exit with failure.

===== $pkgname.post-install =====
This script is executed after package is installed. Can be used to generate font cache and similar.

===== $pkgname.pre-upgrade =====
Same as pre-install but is executed before upgrading an already installed package.

===== $pkgname.post-upgrade =====
Same as post-install but is executed after upgrading 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. Can be used to update font caches and restore busybox links. For example:
<pre>
#!/bin/sh
busybox --install -s
</pre>

If the package have an pre-install and post-install script the APKBUILD should have the ''install'' variable defined and the scripts should also be added to the source variable:
<pre>
...
install="$pkgname.pre-install $pkgname.post-install"
source="http://....
$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:

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

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

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. Way's to create them are:

directory compare:

diff -urp original_directory new_directory > filename.patch

file compare:

diff -up original.file new.file > filename.patch

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.

for i in "$srcdir"/*.patch; do
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:

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

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

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

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 || return 1

To disable parallel we use:

make -j1 || return 1

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 sudo when needed. If by accident the Makefile does not support DESTDIR variable it will fail to install in our build system system directories.

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

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.

abuild -r

== Commit your work ==

After you successfully build your package you can submit your APKBUILD to alpine git repository.

Update you git repo, before adding new files:

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

cd $apkbuilddir
git add APKBUILD (include any other files needed for the build; $pkgname.install...)
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:

git format-patch -1

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

An easy way to send this patch to the list is with an program called 'email'.

apk_add email

to send to the mailing list you would do:

email -a 0001...patch alpine-devel@lists.alpinelinux.org

And provide a subject and body after you execute the above cmd.

 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.

Creating an Alpine package

2009-11-24T09:23:23Z

Amanison: /* license */

== General ==

This document assumes that you have a working [[Setting up the build environment|build environment]], or use a diskbased alpine installation.

=== The APKBUILDs ===

The ''[http://dev.alpinelinux.org/cgit/abuild/ abuild]'' script reads the ''[http://dev.alpinelinux.org/cgit/abuild/tree/sample.APKBUILD APKBUILD]'' and executes the steps needed to create a package.

=== The aports tree ===

The [http://dev.alpinelinux.org/cgit/aports aports] tree is a [http://dev.alpinelinux.org/cgit/aports/tree directory tree] with many APKBUILDs. Those files are used when building alpine from source.

== Installing and configuring the alpine-sdk ==

The alpine-sdk is a metapackage that pulls in the most essential packages used to build new packages. 
Install those packages now:

apk add alpine-sdk

This would be a good time to create a normal user account for you to work in. (You weren't going to develop as root now, were you!) To create the user:

adduser <yourusername>

To make life easier later, it's a good idea to add this user to /etc/sudoers. Append the line

<yourusername> ALL=(ALL) ALL

using the command:

visudo

Now logout of the root account, and login as <yourusername>. From here on everything can be done in a normal user account, and operations that require superuser privileges can be done with sudo.

The aports tree is in git so before we clone the aports tree we should configure git.

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

Now we can clone the aports tree.

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

Before we start creating or modifying APKBUILD files we need to setup abuild to our system/user. Edit the file 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.

vi /etc/abuild.conf

The last step in preparation is to configure the security keys 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

== Creating an APKBUILD file ==

=== Use a template APKBUILD ===

To create the actual APKBUILD file abuild has the option -n (new). It will simply copy an example/template 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 -c -n ''packagename''

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

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

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 command to add their checksums to the APKBUILD file:

abuild checksum

Another thing to note is when a package is using sourceforge for hosting. If so you should specify the special mirrors link used by sf:

http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz

(or similar depending on the package).

Currently abuild supports the following archives/extensions:

*.tar.gz, *.tgz, *.tar.bz2, *.tar.lzma, *.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 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 with the command:

abuild unpack

Running configure 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 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 Archlinux (Alpine package management and build scripts are similar) or Gentoo linux ebuilds (previous versions of Alpine were based on Gentoo).

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

[http://sources.gentoo.org/viewcvs.py/gentoo-x86/ Gentoo CVS]

[http://www.archlinux.org/packages/search/ Archlinux packages]

After the package is successfully compiled and created we should make sure it didn't link to any package that is not present in the $depends variable. We do this by using scanelf. If scanelf is not yet installed on your system you can do that by installing pax-utils.

scanelf -nR pkg

An example output of libcurl would be:

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

You can see the needed files and should be able to find out which file belongs to which package.

==== license ====

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 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 build() 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.

==== url ====

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

==== pkgdesc ====

editme

==== pkgver ====

A brief, one line, description of what the package does. Useful for the package management system. 

 

Example from apk_info 

openssh-client-5.1_p1-r1 - Port of OpenBSD's free SSH release - client 

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

==== pkgname ====

editme

==== 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 user/group to be created. For example:
<pre>
#!/bin/sh
adduser -H -s /bin/false -D 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 apk add will exit with failure.

===== $pkgname.post-install =====
This script is executed after package is installed. Can be used to generate font cache and similar.

===== $pkgname.pre-upgrade =====
Same as pre-install but is executed before upgrading an already installed package.

===== $pkgname.post-upgrade =====
Same as post-install but is executed after upgrading 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. Can be used to update font caches and restore busybox links. For example:
<pre>
#!/bin/sh
busybox --install -s
</pre>

If the package have an pre-install and post-install script the APKBUILD should have the ''install'' variable defined and the scripts should also be added to the source variable:
<pre>
...
install="$pkgname.pre-install $pkgname.post-install"
source="http://....
$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:

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

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

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. Way's to create them are:

directory compare:

diff -urp original_directory new_directory > filename.patch

file compare:

diff -up original.file new.file > filename.patch

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.

for i in "$srcdir"/*.patch; do
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:

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

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

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

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 || return 1

To disable parallel we use:

make -j1 || return 1

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 sudo when needed. If by accident the Makefile does not support DESTDIR variable it will fail to install in our build system system directories.

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

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.

abuild -r

== Commit your work ==

After you successfully build your package you can submit your APKBUILD to alpine git repository.

Update you git repo, before adding new files:

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

cd $apkbuilddir
git add APKBUILD (include any other files needed for the build; $pkgname.install...)
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:

git format-patch -1

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

An easy way to send this patch to the list is with an program called 'email'.

apk_add email

to send to the mailing list you would do:

email -a 0001...patch alpine-devel@lists.alpinelinux.org

And provide a subject and body after you execute the above cmd.

 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.

Creating an Alpine package

2009-11-24T09:19:35Z

Amanison: /* depends & makedepends */

== General ==

This document assumes that you have a working [[Setting up the build environment|build environment]], or use a diskbased alpine installation.

=== The APKBUILDs ===

The ''[http://dev.alpinelinux.org/cgit/abuild/ abuild]'' script reads the ''[http://dev.alpinelinux.org/cgit/abuild/tree/sample.APKBUILD APKBUILD]'' and executes the steps needed to create a package.

=== The aports tree ===

The [http://dev.alpinelinux.org/cgit/aports aports] tree is a [http://dev.alpinelinux.org/cgit/aports/tree directory tree] with many APKBUILDs. Those files are used when building alpine from source.

== Installing and configuring the alpine-sdk ==

The alpine-sdk is a metapackage that pulls in the most essential packages used to build new packages. 
Install those packages now:

apk add alpine-sdk

This would be a good time to create a normal user account for you to work in. (You weren't going to develop as root now, were you!) To create the user:

adduser <yourusername>

To make life easier later, it's a good idea to add this user to /etc/sudoers. Append the line

<yourusername> ALL=(ALL) ALL

using the command:

visudo

Now logout of the root account, and login as <yourusername>. From here on everything can be done in a normal user account, and operations that require superuser privileges can be done with sudo.

The aports tree is in git so before we clone the aports tree we should configure git.

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

Now we can clone the aports tree.

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

Before we start creating or modifying APKBUILD files we need to setup abuild to our system/user. Edit the file 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.

vi /etc/abuild.conf

The last step in preparation is to configure the security keys 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

== Creating an APKBUILD file ==

=== Use a template APKBUILD ===

To create the actual APKBUILD file abuild has the option -n (new). It will simply copy an example/template 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 -c -n ''packagename''

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

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

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 command to add their checksums to the APKBUILD file:

abuild checksum

Another thing to note is when a package is using sourceforge for hosting. If so you should specify the special mirrors link used by sf:

http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz

(or similar depending on the package).

Currently abuild supports the following archives/extensions:

*.tar.gz, *.tgz, *.tar.bz2, *.tar.lzma, *.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 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 with the command:

abuild unpack

Running configure 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 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 Archlinux (Alpine package management and build scripts are similar) or Gentoo linux ebuilds (previous versions of Alpine were based on Gentoo).

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

[http://sources.gentoo.org/viewcvs.py/gentoo-x86/ Gentoo CVS]

[http://www.archlinux.org/packages/search/ Archlinux packages]

After the package is successfully compiled and created we should make sure it didn't link to any package that is not present in the $depends variable. We do this by using scanelf. If scanelf is not yet installed on your system you can do that by installing pax-utils.

scanelf -nR pkg

An example output of libcurl would be:

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

You can see the needed files and should be able to find out which file belongs to which package.

==== license ====

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:

subpackages="$pkgname-doc"

And add a similar line to your build() function depending on the license:

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

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

==== url ====

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

==== pkgdesc ====

editme

==== pkgver ====

A brief, one line, description of what the package does. Useful for the package management system. 

 

Example from apk_info 

openssh-client-5.1_p1-r1 - Port of OpenBSD's free SSH release - client 

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

==== pkgname ====

editme

==== 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 user/group to be created. For example:
<pre>
#!/bin/sh
adduser -H -s /bin/false -D 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 apk add will exit with failure.

===== $pkgname.post-install =====
This script is executed after package is installed. Can be used to generate font cache and similar.

===== $pkgname.pre-upgrade =====
Same as pre-install but is executed before upgrading an already installed package.

===== $pkgname.post-upgrade =====
Same as post-install but is executed after upgrading 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. Can be used to update font caches and restore busybox links. For example:
<pre>
#!/bin/sh
busybox --install -s
</pre>

If the package have an pre-install and post-install script the APKBUILD should have the ''install'' variable defined and the scripts should also be added to the source variable:
<pre>
...
install="$pkgname.pre-install $pkgname.post-install"
source="http://....
$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:

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

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

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. Way's to create them are:

directory compare:

diff -urp original_directory new_directory > filename.patch

file compare:

diff -up original.file new.file > filename.patch

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.

for i in "$srcdir"/*.patch; do
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:

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

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

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

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 || return 1

To disable parallel we use:

make -j1 || return 1

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 sudo when needed. If by accident the Makefile does not support DESTDIR variable it will fail to install in our build system system directories.

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

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.

abuild -r

== Commit your work ==

After you successfully build your package you can submit your APKBUILD to alpine git repository.

Update you git repo, before adding new files:

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

cd $apkbuilddir
git add APKBUILD (include any other files needed for the build; $pkgname.install...)
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:

git format-patch -1

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

An easy way to send this patch to the list is with an program called 'email'.

apk_add email

to send to the mailing list you would do:

email -a 0001...patch alpine-devel@lists.alpinelinux.org

And provide a subject and body after you execute the above cmd.

 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.

Creating an Alpine package

2009-11-24T09:13:51Z

Amanison: /* source */

== General ==

This document assumes that you have a working [[Setting up the build environment|build environment]], or use a diskbased alpine installation.

=== The APKBUILDs ===

The ''[http://dev.alpinelinux.org/cgit/abuild/ abuild]'' script reads the ''[http://dev.alpinelinux.org/cgit/abuild/tree/sample.APKBUILD APKBUILD]'' and executes the steps needed to create a package.

=== The aports tree ===

The [http://dev.alpinelinux.org/cgit/aports aports] tree is a [http://dev.alpinelinux.org/cgit/aports/tree directory tree] with many APKBUILDs. Those files are used when building alpine from source.

== Installing and configuring the alpine-sdk ==

The alpine-sdk is a metapackage that pulls in the most essential packages used to build new packages. 
Install those packages now:

apk add alpine-sdk

This would be a good time to create a normal user account for you to work in. (You weren't going to develop as root now, were you!) To create the user:

adduser <yourusername>

To make life easier later, it's a good idea to add this user to /etc/sudoers. Append the line

<yourusername> ALL=(ALL) ALL

using the command:

visudo

Now logout of the root account, and login as <yourusername>. From here on everything can be done in a normal user account, and operations that require superuser privileges can be done with sudo.

The aports tree is in git so before we clone the aports tree we should configure git.

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

Now we can clone the aports tree.

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

Before we start creating or modifying APKBUILD files we need to setup abuild to our system/user. Edit the file 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.

vi /etc/abuild.conf

The last step in preparation is to configure the security keys 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

== Creating an APKBUILD file ==

=== Use a template APKBUILD ===

To create the actual APKBUILD file abuild has the option -n (new). It will simply copy an example/template 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 -c -n ''packagename''

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

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

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 command to add their checksums to the APKBUILD file:

abuild checksum

Another thing to note is when a package is using sourceforge for hosting. If so you should specify the special mirrors link used by sf:

http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz

(or similar depending on the package).

Currently abuild supports the following archives/extensions:

*.tar.gz, *.tgz, *.tar.bz2, *.tar.lzma, *.zip

==== depends & 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].

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:

abuild unpack

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

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

[http://sources.gentoo.org/viewcvs.py/gentoo-x86/ Gentoo CVS]

[http://www.archlinux.org/packages/search/ Archlinux packages]

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.

scanelf -nR pkg

example output of libcurl would be:

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

You can see the needed files and should be able to find out which file belongs to which package.

==== license ====

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:

subpackages="$pkgname-doc"

And add a similar line to your build() function depending on the license:

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

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

==== url ====

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

==== pkgdesc ====

editme

==== pkgver ====

A brief, one line, description of what the package does. Useful for the package management system. 

 

Example from apk_info 

openssh-client-5.1_p1-r1 - Port of OpenBSD's free SSH release - client 

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

==== pkgname ====

editme

==== 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 user/group to be created. For example:
<pre>
#!/bin/sh
adduser -H -s /bin/false -D 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 apk add will exit with failure.

===== $pkgname.post-install =====
This script is executed after package is installed. Can be used to generate font cache and similar.

===== $pkgname.pre-upgrade =====
Same as pre-install but is executed before upgrading an already installed package.

===== $pkgname.post-upgrade =====
Same as post-install but is executed after upgrading 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. Can be used to update font caches and restore busybox links. For example:
<pre>
#!/bin/sh
busybox --install -s
</pre>

If the package have an pre-install and post-install script the APKBUILD should have the ''install'' variable defined and the scripts should also be added to the source variable:
<pre>
...
install="$pkgname.pre-install $pkgname.post-install"
source="http://....
$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:

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

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

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. Way's to create them are:

directory compare:

diff -urp original_directory new_directory > filename.patch

file compare:

diff -up original.file new.file > filename.patch

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.

for i in "$srcdir"/*.patch; do
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:

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

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

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

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 || return 1

To disable parallel we use:

make -j1 || return 1

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 sudo when needed. If by accident the Makefile does not support DESTDIR variable it will fail to install in our build system system directories.

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

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.

abuild -r

== Commit your work ==

After you successfully build your package you can submit your APKBUILD to alpine git repository.

Update you git repo, before adding new files:

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

cd $apkbuilddir
git add APKBUILD (include any other files needed for the build; $pkgname.install...)
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:

git format-patch -1

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

An easy way to send this patch to the list is with an program called 'email'.

apk_add email

to send to the mailing list you would do:

email -a 0001...patch alpine-devel@lists.alpinelinux.org

And provide a subject and body after you execute the above cmd.

 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.

Creating an Alpine package

2009-11-24T09:11:18Z

Amanison: /* Modify your APKBUILD */

== General ==

This document assumes that you have a working [[Setting up the build environment|build environment]], or use a diskbased alpine installation.

=== The APKBUILDs ===

The ''[http://dev.alpinelinux.org/cgit/abuild/ abuild]'' script reads the ''[http://dev.alpinelinux.org/cgit/abuild/tree/sample.APKBUILD APKBUILD]'' and executes the steps needed to create a package.

=== The aports tree ===

The [http://dev.alpinelinux.org/cgit/aports aports] tree is a [http://dev.alpinelinux.org/cgit/aports/tree directory tree] with many APKBUILDs. Those files are used when building alpine from source.

== Installing and configuring the alpine-sdk ==

The alpine-sdk is a metapackage that pulls in the most essential packages used to build new packages. 
Install those packages now:

apk add alpine-sdk

This would be a good time to create a normal user account for you to work in. (You weren't going to develop as root now, were you!) To create the user:

adduser <yourusername>

To make life easier later, it's a good idea to add this user to /etc/sudoers. Append the line

<yourusername> ALL=(ALL) ALL

using the command:

visudo

Now logout of the root account, and login as <yourusername>. From here on everything can be done in a normal user account, and operations that require superuser privileges can be done with sudo.

The aports tree is in git so before we clone the aports tree we should configure git.

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

Now we can clone the aports tree.

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

Before we start creating or modifying APKBUILD files we need to setup abuild to our system/user. Edit the file 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.

vi /etc/abuild.conf

The last step in preparation is to configure the security keys 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

== Creating an APKBUILD file ==

=== Use a template APKBUILD ===

To create the actual APKBUILD file abuild has the option -n (new). It will simply copy an example/template 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 -c -n ''packagename''

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

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

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:

abuild checksum

Another thing to note is when a package is using sourceforge as hosting, if so you should add special mirrors link used by sf:

http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz

(or similar depending on the package).

Currently abuild support the following archives/extensions:

*.tar.gz, *.tgz, *.tar.bz2, *.tar.lzma, *.zip

==== depends & 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].

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:

abuild unpack

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

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

[http://sources.gentoo.org/viewcvs.py/gentoo-x86/ Gentoo CVS]

[http://www.archlinux.org/packages/search/ Archlinux packages]

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.

scanelf -nR pkg

example output of libcurl would be:

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

You can see the needed files and should be able to find out which file belongs to which package.

==== license ====

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:

subpackages="$pkgname-doc"

And add a similar line to your build() function depending on the license:

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

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

==== url ====

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

==== pkgdesc ====

editme

==== pkgver ====

A brief, one line, description of what the package does. Useful for the package management system. 

 

Example from apk_info 

openssh-client-5.1_p1-r1 - Port of OpenBSD's free SSH release - client 

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

==== pkgname ====

editme

==== 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 user/group to be created. For example:
<pre>
#!/bin/sh
adduser -H -s /bin/false -D 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 apk add will exit with failure.

===== $pkgname.post-install =====
This script is executed after package is installed. Can be used to generate font cache and similar.

===== $pkgname.pre-upgrade =====
Same as pre-install but is executed before upgrading an already installed package.

===== $pkgname.post-upgrade =====
Same as post-install but is executed after upgrading 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. Can be used to update font caches and restore busybox links. For example:
<pre>
#!/bin/sh
busybox --install -s
</pre>

If the package have an pre-install and post-install script the APKBUILD should have the ''install'' variable defined and the scripts should also be added to the source variable:
<pre>
...
install="$pkgname.pre-install $pkgname.post-install"
source="http://....
$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:

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

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

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. Way's to create them are:

directory compare:

diff -urp original_directory new_directory > filename.patch

file compare:

diff -up original.file new.file > filename.patch

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.

for i in "$srcdir"/*.patch; do
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:

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

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

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

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 || return 1

To disable parallel we use:

make -j1 || return 1

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 sudo when needed. If by accident the Makefile does not support DESTDIR variable it will fail to install in our build system system directories.

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

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.

abuild -r

== Commit your work ==

After you successfully build your package you can submit your APKBUILD to alpine git repository.

Update you git repo, before adding new files:

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

cd $apkbuilddir
git add APKBUILD (include any other files needed for the build; $pkgname.install...)
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:

git format-patch -1

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

An easy way to send this patch to the list is with an program called 'email'.

apk_add email

to send to the mailing list you would do:

email -a 0001...patch alpine-devel@lists.alpinelinux.org

And provide a subject and body after you execute the above cmd.

 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.

Creating an Alpine package

2009-11-06T17:58:26Z

Amanison: /* Installing and configuring the alpine-sdk */

== General ==

This document assumes that you have a working [[Setting up the build environment|build environment]], or use a diskbased alpine installation.

=== The APKBUILDs ===

The ''[http://dev.alpinelinux.org/cgit/abuild/ abuild]'' script reads the ''[http://dev.alpinelinux.org/cgit/abuild/tree/sample.APKBUILD APKBUILD]'' and executes the steps needed to create a package.

=== The aports tree ===

The [http://dev.alpinelinux.org/cgit/aports aports] tree is a [http://dev.alpinelinux.org/cgit/aports/tree directory tree] with many APKBUILDs. Those files are used when building alpine from source.

== Installing and configuring the alpine-sdk ==

The alpine-sdk is a metapackage that pulls in the most essential packages used to build new packages. 
Install those packages now:

apk add alpine-sdk

This would be a good time to create a normal user account for you to work in. (You weren't going to develop as root now, were you!) To create the user:

adduser <yourusername>

To make life easier later, it's a good idea to add this user to /etc/sudoers. Append the line

<yourusername> ALL=(ALL) ALL

using the command:

visudo

Now logout of the root account, and login as <yourusername>. From here on everything can be done in a normal user account, and operations that require superuser privileges can be done with sudo.

The aports tree is in git so before we clone the aports tree we should configure git.

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

Now we can clone the aports tree.

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

Before we start creating or modifying APKBUILD files we need to setup abuild to our system/user. Edit the file 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.

vi /etc/abuild.conf

The last step in preparation is to configure the security keys 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

== Creating an APKBUILD file ==

=== Use a template APKBUILD ===

To create the actual APKBUILD file abuild has the option -n (new). It will simply copy an example/template 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 -c -n ''packagename''

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

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 directory's 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 ====

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:

abuild checksum

Another thing to note is when a package is using sourceforge as hosting, if so you should add special mirrors link used by sf:

http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz

(or similar depending on the package).

Currently abuild support the following archives/extensions:

*.tar.gz, *.tgz, *.tar.bz2, *.tar.lzma, *.zip

==== depends & 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].

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:

abuild unpack

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

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

[http://sources.gentoo.org/viewcvs.py/gentoo-x86/ Gentoo CVS]

[http://www.archlinux.org/packages/search/ Archlinux packages]

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.

scanelf -nR pkg

example output of libcurl would be:

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

You can see the needed files and should be able to find out which file belongs to which package.

==== license ====

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:

subpackages="$pkgname-doc"

And add a similar line to your build() function depending on the license:

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

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

==== url ====

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

==== pkgdesc ====

editme

==== pkgver ====

A brief, one line, description of what the package does. Useful for the package management system. 

 

Example from apk_info 

openssh-client-5.1_p1-r1 - Port of OpenBSD's free SSH release - client 

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

==== pkgname ====

editme

==== 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 user/group to be created. For example:
<pre>
#!/bin/sh
adduser -H -s /bin/false -D 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 apk add will exit with failure.

===== $pkgname.post-install =====
This script is executed after package is installed. Can be used to generate font cache and similar.

===== $pkgname.pre-upgrade =====
Same as pre-install but is executed before upgrading an already installed package.

===== $pkgname.post-upgrade =====
Same as post-install but is executed after upgrading 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. Can be used to update font caches and restore busybox links. For example:
<pre>
#!/bin/sh
busybox --install -s
</pre>

If the package have an pre-install and post-install script the APKBUILD should have the ''install'' variable defined and the scripts should also be added to the source variable:
<pre>
...
install="$pkgname.pre-install $pkgname.post-install"
source="http://....
$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:

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

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

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. Way's to create them are:

directory compare:

diff -urp original_directory new_directory > filename.patch

file compare:

diff -up original.file new.file > filename.patch

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.

for i in "$srcdir"/*.patch; do
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:

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

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

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

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 || return 1

To disable parallel we use:

make -j1 || return 1

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 sudo when needed. If by accident the Makefile does not support DESTDIR variable it will fail to install in our build system system directories.

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

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.

abuild -r

== Commit your work ==

After you successfully build your package you can submit your APKBUILD to alpine git repository.

Update you git repo, before adding new files:

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

cd $apkbuilddir
git add APKBUILD (include any other files needed for the build; $pkgname.install...)
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:

git format-patch -1

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

An easy way to send this patch to the list is with an program called 'email'.

apk_add email

to send to the mailing list you would do:

email -a 0001...patch alpine-devel@lists.alpinelinux.org

And provide a subject and body after you execute the above cmd.

 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.

Creating an Alpine package

2009-11-06T16:34:43Z

Amanison: /* Installing and configuring the alpine-sdk */

== General ==

This document assumes that you have a working [[Setting up the build environment|build environment]], or use a diskbased alpine installation.

=== The APKBUILDs ===

The ''[http://dev.alpinelinux.org/cgit/abuild/ abuild]'' script reads the ''[http://dev.alpinelinux.org/cgit/abuild/tree/sample.APKBUILD APKBUILD]'' and executes the steps needed to create a package.

=== The aports tree ===

The [http://dev.alpinelinux.org/cgit/aports aports] tree is a [http://dev.alpinelinux.org/cgit/aports/tree directory tree] with many APKBUILDs. Those files are used when building alpine from source.

== Installing and configuring the alpine-sdk ==

The alpine-sdk is a metapackage that pulls in the most essential packages used to build new packages. 
Install those packages now:

apk add alpine-sdk

This would be a good time to create a normal user account for you to work in. (You weren't going to develop as root now, were you!) To create the user:

adduser <yourusername>

To make life easier later, it's a good idea to add this user to /etc/sudoers. Append the line

<yourusername> ALL=(ALL) ALL

using the command:

visudo

Now logout of the root account, and login as <yourusername>. From here on everything can be done in a normal user account, and operations that require superuser privileges can be done with sudo.

The aports tree is in git so before we clone the aports tree we should configure git.

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

Now we can clone the aports tree.

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

Before we start creating or modifying APKBUILD files we need to setup abuild to our system/user. Edit the file 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.

vi /etc/abuild.conf

== Getting some help ==

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

abuild -h

== Creating an APKBUILD file ==

=== Use a template APKBUILD ===

To create the actual APKBUILD file abuild has the option -n (new). It will simply copy an example/template 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 -c -n ''packagename''

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

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 directory's 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 ====

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:

abuild checksum

Another thing to note is when a package is using sourceforge as hosting, if so you should add special mirrors link used by sf:

http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz

(or similar depending on the package).

Currently abuild support the following archives/extensions:

*.tar.gz, *.tgz, *.tar.bz2, *.tar.lzma, *.zip

==== depends & 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].

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:

abuild unpack

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

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

[http://sources.gentoo.org/viewcvs.py/gentoo-x86/ Gentoo CVS]

[http://www.archlinux.org/packages/search/ Archlinux packages]

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.

scanelf -nR pkg

example output of libcurl would be:

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

You can see the needed files and should be able to find out which file belongs to which package.

==== license ====

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:

subpackages="$pkgname-doc"

And add a similar line to your build() function depending on the license:

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

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

==== url ====

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

==== pkgdesc ====

editme

==== pkgver ====

A brief, one line, description of what the package does. Useful for the package management system. 

 

Example from apk_info 

openssh-client-5.1_p1-r1 - Port of OpenBSD's free SSH release - client 

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

==== pkgname ====

editme

==== 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 user/group to be created. For example:
<pre>
#!/bin/sh
adduser -H -s /bin/false -D 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 apk add will exit with failure.

===== $pkgname.post-install =====
This script is executed after package is installed. Can be used to generate font cache and similar.

===== $pkgname.pre-upgrade =====
Same as pre-install but is executed before upgrading an already installed package.

===== $pkgname.post-upgrade =====
Same as post-install but is executed after upgrading 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. Can be used to update font caches and restore busybox links. For example:
<pre>
#!/bin/sh
busybox --install -s
</pre>

If the package have an pre-install and post-install script the APKBUILD should have the ''install'' variable defined and the scripts should also be added to the source variable:
<pre>
...
install="$pkgname.pre-install $pkgname.post-install"
source="http://....
$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:

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

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

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. Way's to create them are:

directory compare:

diff -urp original_directory new_directory > filename.patch

file compare:

diff -up original.file new.file > filename.patch

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.

for i in "$srcdir"/*.patch; do
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:

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

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

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

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 || return 1

To disable parallel we use:

make -j1 || return 1

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 sudo when needed. If by accident the Makefile does not support DESTDIR variable it will fail to install in our build system system directories.

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

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.

abuild -r

== Commit your work ==

After you successfully build your package you can submit your APKBUILD to alpine git repository.

Update you git repo, before adding new files:

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

cd $apkbuilddir
git add APKBUILD (include any other files needed for the build; $pkgname.install...)
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:

git format-patch -1

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

An easy way to send this patch to the list is with an program called 'email'.

apk_add email

to send to the mailing list you would do:

email -a 0001...patch alpine-devel@lists.alpinelinux.org

And provide a subject and body after you execute the above cmd.

 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.

Creating an Alpine package

2009-11-06T16:26:15Z

Amanison: /* Installing and configuring the alpine-sdk */

== General ==

This document assumes that you have a working [[Setting up the build environment|build environment]], or use a diskbased alpine installation.

=== The APKBUILDs ===

The ''[http://dev.alpinelinux.org/cgit/abuild/ abuild]'' script reads the ''[http://dev.alpinelinux.org/cgit/abuild/tree/sample.APKBUILD APKBUILD]'' and executes the steps needed to create a package.

=== The aports tree ===

The [http://dev.alpinelinux.org/cgit/aports aports] tree is a [http://dev.alpinelinux.org/cgit/aports/tree directory tree] with many APKBUILDs. Those files are used when building alpine from source.

== Installing and configuring the alpine-sdk ==

The alpine-sdk is a metapackage that pulls in the most essential packages used to build new packages. 
Install those packages now:

apk add alpine-sdk

This would be a good time to create a normal user account for you to work in. (You weren't going to develop as root now, were you!) To create the user:

adduser <yourusername>

To make life easier later, it's a good idea to add this user to /etc/sudoers. Append the line

<yourusername> ALL=(ALL) ALL

using the command:

visudo

Now logout of the root account, and login as <yourusername>. From here on everything can be done in a normal user account, and operations that require superuser privileges can be done with sudo.

The aports tree is in git so before we clone the aports tree we should configure git.

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

Now we can clone the aports tree.

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

Before we start create or modifying APKBUILD files we need to setup abuild to our system/user. Please edit the file abuild.conf to your liking.

vi /etc/abuild.conf

== Getting some help ==

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

abuild -h

== Creating an APKBUILD file ==

=== Use a template APKBUILD ===

To create the actual APKBUILD file abuild has the option -n (new). It will simply copy an example/template 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 -c -n ''packagename''

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

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 directory's 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 ====

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:

abuild checksum

Another thing to note is when a package is using sourceforge as hosting, if so you should add special mirrors link used by sf:

http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz

(or similar depending on the package).

Currently abuild support the following archives/extensions:

*.tar.gz, *.tgz, *.tar.bz2, *.tar.lzma, *.zip

==== depends & 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].

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:

abuild unpack

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

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

[http://sources.gentoo.org/viewcvs.py/gentoo-x86/ Gentoo CVS]

[http://www.archlinux.org/packages/search/ Archlinux packages]

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.

scanelf -nR pkg

example output of libcurl would be:

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

You can see the needed files and should be able to find out which file belongs to which package.

==== license ====

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:

subpackages="$pkgname-doc"

And add a similar line to your build() function depending on the license:

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

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

==== url ====

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

==== pkgdesc ====

editme

==== pkgver ====

A brief, one line, description of what the package does. Useful for the package management system. 

 

Example from apk_info 

openssh-client-5.1_p1-r1 - Port of OpenBSD's free SSH release - client 

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

==== pkgname ====

editme

==== 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 user/group to be created. For example:
<pre>
#!/bin/sh
adduser -H -s /bin/false -D 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 apk add will exit with failure.

===== $pkgname.post-install =====
This script is executed after package is installed. Can be used to generate font cache and similar.

===== $pkgname.pre-upgrade =====
Same as pre-install but is executed before upgrading an already installed package.

===== $pkgname.post-upgrade =====
Same as post-install but is executed after upgrading 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. Can be used to update font caches and restore busybox links. For example:
<pre>
#!/bin/sh
busybox --install -s
</pre>

If the package have an pre-install and post-install script the APKBUILD should have the ''install'' variable defined and the scripts should also be added to the source variable:
<pre>
...
install="$pkgname.pre-install $pkgname.post-install"
source="http://....
$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:

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

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

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. Way's to create them are:

directory compare:

diff -urp original_directory new_directory > filename.patch

file compare:

diff -up original.file new.file > filename.patch

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.

for i in "$srcdir"/*.patch; do
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:

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

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

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

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 || return 1

To disable parallel we use:

make -j1 || return 1

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 sudo when needed. If by accident the Makefile does not support DESTDIR variable it will fail to install in our build system system directories.

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

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.

abuild -r

== Commit your work ==

After you successfully build your package you can submit your APKBUILD to alpine git repository.

Update you git repo, before adding new files:

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

cd $apkbuilddir
git add APKBUILD (include any other files needed for the build; $pkgname.install...)
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:

git format-patch -1

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

An easy way to send this patch to the list is with an program called 'email'.

apk_add email

to send to the mailing list you would do:

email -a 0001...patch alpine-devel@lists.alpinelinux.org

And provide a subject and body after you execute the above cmd.

 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.

Creating an Alpine package

2009-10-23T18:06:40Z

Amanison: /* Installing and configuring the alpine-sdk */

== General ==

This document assumes that you have a working [[Setting up the build environment|build environment]], or use a diskbased alpine installation.

=== The APKBUILDs ===

The ''[http://dev.alpinelinux.org/cgit/abuild/ abuild]'' script reads the ''[http://dev.alpinelinux.org/cgit/abuild/tree/sample.APKBUILD APKBUILD]'' and executes the steps needed to create a package.

=== The aports tree ===

The [http://dev.alpinelinux.org/cgit/aports aports] tree is a [http://dev.alpinelinux.org/cgit/aports/tree directory tree] with many APKBUILDs. Those files are used when building alpine from source.

== Installing and configuring the alpine-sdk ==

The alpine-sdk is a metapackage that pulls in the most essential packages used to build new packages. 
To install those packages:

apk add alpine-sdk

The aports tree is in git so before we clone the aports tree we should configure git.

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

Now we can clone the aports tree.

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

Before we start create or modifying APKBUILD files we need to setup abuild to our system/user. Please edit the file abuild.conf to your likings.

vi /etc/abuild.conf

== Getting some help ==

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

abuild -h

== Creating an APKBUILD file ==

=== Use a template APKBUILD ===

To create the actual APKBUILD file abuild has the option -n (new). It will simply copy an example/template 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 -c -n ''packagename''

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

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 directory's 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 ====

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:

abuild checksum

Another thing to note is when a package is using sourceforge as hosting, if so you should add special mirrors link used by sf:

http://downloads.sourceforge.net/$pkgname/$pkgname-$pkgver.tar.gz

(or similar depending on the package).

Currently abuild support the following archives/extensions:

*.tar.gz, *.tgz, *.tar.bz2, *.tar.lzma, *.zip

==== depends & 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].

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:

abuild unpack

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

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

[http://sources.gentoo.org/viewcvs.py/gentoo-x86/ Gentoo CVS]

[http://www.archlinux.org/packages/search/ Archlinux packages]

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.

scanelf -nR pkg

example output of libcurl would be:

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

You can see the needed files and should be able to find out which file belongs to which package.

==== license ====

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:

subpackages="$pkgname-doc"

And add a similar line to your build() function depending on the license:

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

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

==== url ====

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

==== pkgdesc ====

editme

==== pkgver ====

A brief, one line, description of what the package does. Useful for the package management system. 

 

Example from apk_info 

openssh-client-5.1_p1-r1 - Port of OpenBSD's free SSH release - client 

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

==== pkgname ====

editme

==== 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 user/group to be created. For example:
<pre>
#!/bin/sh
adduser -H -s /bin/false -D 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 apk add will exit with failure.

===== $pkgname.post-install =====
This script is executed after package is installed. Can be used to generate font cache and similar.

===== $pkgname.pre-upgrade =====
Same as pre-install but is executed before upgrading an already installed package.

===== $pkgname.post-upgrade =====
Same as post-install but is executed after upgrading 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. Can be used to update font caches and restore busybox links. For example:
<pre>
#!/bin/sh
busybox --install -s
</pre>

If the package have an pre-install and post-install script the APKBUILD should have the ''install'' variable defined and the scripts should also be added to the source variable:
<pre>
...
install="$pkgname.pre-install $pkgname.post-install"
source="http://....
$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:

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

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

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. Way's to create them are:

directory compare:

diff -urp original_directory new_directory > filename.patch

file compare:

diff -up original.file new.file > filename.patch

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.

for i in "$srcdir"/*.patch; do
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:

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

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

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

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 || return 1

To disable parallel we use:

make -j1 || return 1

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 sudo when needed. If by accident the Makefile does not support DESTDIR variable it will fail to install in our build system system directories.

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

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.

abuild -r

== Commit your work ==

After you successfully build your package you can submit your APKBUILD to alpine git repository.

Update you git repo, before adding new files:

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

cd $apkbuilddir
git add APKBUILD (include any other files needed for the build; $pkgname.install...)
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:

git format-patch -1

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

An easy way to send this patch to the list is with an program called 'email'.

apk_add email

to send to the mailing list you would do:

email -a 0001...patch alpine-devel@lists.alpinelinux.org

And provide a subject and body after you execute the above cmd.

 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.