BuildingIpkgs

Building ipkgs

Here's a short and incomplete guide to building packages for the Ipkg package management system:

Before you start, make sure you have the latest ipkg-utils. As of May, 2004, they're available at ftp://ftp.handhelds.org/packages/ipkg-utils

Create the directory structure and files as you want them appear on the installed system.
Create a directory named CONTROL at the top-level of this directory structure.
Inside CONTROL create a file named "control" with lines of the form "Field: value". Required fields are Package, Version, Architecture, Maintainer, Section, Priority and Description. Optional fields include Depends. The meaning of each of the fields will be given later in this document.
If your package has any configuration files, then create a file CONTROL/conffiles which lists the absolute path of each configuration file, (as it will appear on the installed system), one per line. This will prevent the package management system from automatically overwriting configuration changes when the user upgrades the package.
If needed your package may include some scripts that will be invoked by the package maintenance system. There are four possible times a script will be run: just before your package is installed, just after your package is installed, just before the package is removed, and just after the package is removed. These scripts are named preinst, postinst, prerm, and postrm and should be located in the CONTROL directory. The scripts should return 0 on success, (a non-zero return value from preinst will prevent your package from being installed -- this can be useful in rare situations). The scripts can assume a tty is available so they may prompt the user. Note that the variable PKG_ROOT is set to the root of the package installation and can be used to refer to the packages contents in their installed locations.
Now simply run:
```
 ipkg-build directory [destination_directory]
```
where directory is the directory you have created. The destination_directory is optional and defaults to the current directory. The ipkg-build script peforms several sanity checks on the package directory and should guide you through any problems.

If you are not running ipkg-build as root, then provide the -g and -o options:

ipkg-build -o root -g root directory  [destination_directory]

Here is an example control file which you may use as a template:

Package: foo
Priority: optional
Version: 0.0
Architecture: arm
Maintainer: Familiar User <user@somehost.net>
Depends: libc6, grep
Description: foo is the ever-present example program -- it does everything
 foo is not a real package. This is simply an example that you
 may modify if you wish.
 .
 When you modify this example, be sure to change the Package, Version,
 Maintainer, Depends, and Description fields.

The meaning of the various fields in CONTROL/control is as follows:

Package is the name of the package and should match the regular expression [a-z0-9.+-]\+
Version should have at least one digit and should match "[a-zA-Z0-9.+]*". Version may also contain an optional trailing revision matching "-fam[0-9]\+". This revision should be incremented each time the package changes but the version does not, (ie. a packaging tweak). It may be reset, (or simply omitted), each time the version is incremented.
Architecture should specify the architecture for which the package is compiled. Valid values for Familiar currently include "arm" and "all".
Maintainer should be the name and email address of the person responsible for maintianing the package, (not necessarily the author of the program).
Description should be a short, (less than 80 characters) description of the program. It may also include a long description on subsequent lines, (each indented by a single space character). Blank lines in the long description may be indicated by a line consisting of a space character followed by a period, ie " ."
Priority should be one of: required, standard, important, optional, or extra. Most programs should use optional.
Section can be one of the following: admin, base, comm, editors, extras, graphics, libs, misc, net, text, web, x11.
Depends indicates packages which must also be installed in order for this package to work. The pacakages should be listed on a single line, separated by commas.

Also, if your package provides a user-level program, then you should add a menu entry for that program. The top-level menu entries are defined at http://familiar.handhelds.org/policy/menu.html while instructions for adding a menu entry to a program can be found at http://www.handhelds.org/~nelson/menu/

Note (ArBor): There are special actions for BuildingIpkgsFor5600

You can also build an ipkg package from the source tarball using ipkg-buildpackage. This is very similar to dpkg-buildpackage from Debian.

unpack the source tarball.
cd to the source distribution, change whatever you need to make the package compile and work on the ipaq.
create a directory 'ipkg'
put all files which go to the 'CONTROL' directory of the root of the installed package into ipkg.
the version (Version field in control) should match the version of the source tarball, optionally with a digit (eg. -1) appended.
additionally, put a file there called 'rules' which is a shell script accepting arguments 'build', 'install' and 'clean'. It can be a Makefile starting with the line
```
#!/usr/bin/make -f
```

the build target does things like ./configure and make.
the install target installs to a temporary directory (make DESTDIR=/tmp/package) and removes unnecessary items (eg. man pages)
clean cleans

You will find an example rules file in the CVS repository of ipkg.

If you need to change file ownerships when installing, you should run this with fakeroot (1) or as root.

If all went well, you will find a diff file and an *.ipk file in the directory above. If you distribute the ipkg file, you should make the diff available as well, so that others can learn from it, or build packages themselves if something has changed.

JukkaSantala adds:

As of sometime now, an extra header titled "Section:" is required on ipkg control files. Valid values are admin, base, comm, editors, extras, games, graphics, kernel, libs, misc, net, text, web and x11. In addition, to do this work on another machine, you should check out the scripts at familiar/dist/ipkg on the handhelds.org CVS with CVSROOT :pserver:anoncvs@anoncvs.handhelds.org:/cvs and password anoncvs

Gonz adds:

A common mistake is to depend on a specific version of a single package. This leads to users which are unable to install the ipk, because they have a newer version of either the package itself or a package which provides this pkg. A well known example is not beeing able to install some qpe packages which need qpe-base(1.5.0).

quoted from irc:

 kergoth    spiralman: the problem is.. some packages still fail because 
            said packages Depends on qpe-base(1.5.0) specifically
 spiralman  oh, thats a bitch...
 kergoth    spiralman: and we could not and should not be able to Provide a 
            specific version.. because we obviously are not that version.
 kergoth    spiralman: really, said packages are broken and should Depend 
            on qpe-base (1.5.0+) or something similar

MikEw: see also SteveRedler's section on building .ipk files.

Handhelds.org - Open source for handheld devices

Building ipkgs