11. Build and handle your own ipkg packages

This documentation is based on wiki/BuildingIpkgs. So if you want to have the actual information, check that page.

This chapter describes the basics and includes an example, which is used to prepare your first usefull ipkg including the network setup for your ipaq based on the familiar task-bootstrap. This includes the integration of a xircom2ps kernel module, which is necessary to get my network up.

11.1 Requirements

Grab ipkg-tools.tgz from ftp://lorien.handhelds.org/pub/linux/feeds/demo/.

see also Download.

11.2 Installation

Unpack it using tar xvfz ipkg-tools.tgz. The tarball contains the programs "ipkg", "ipkg-build", "ipkg-make-index" and "ipkg-make-kernel_packages".

What we need first is only "ipkg-build". As this program (as well as ipkg itself") is a shell-script, it should run on all platforms supporting /bin/sh.

Copy the "ipkg-build" into e.g /usr/local/sbin and make sure your PATH points to that dir.

Thats all installation for the moment.

11.3 Package building

This section describes howto build a package in theory. The next section will present a very helpfull example package. Everything described below may be happen below a directory called my-first-example. Follow the steps described below.

1. Create the directory structure and files as you want them appear on the installed system.
2. Create a directory named CONTROL at the top-level of this directory structure.
3. Inside CONTROL create a file named "control" with lines of the form "Field: value". Required fields are Package, Version, Architecture, Maintainer, and Description. Optional fields include Priority, Section, and Depends.
   • Package is the name of the package
   • Version should have at least one digit 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 packages should be listed on a single line, separated by commas.
4. 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.
5. 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.

Enter the topdir of your "my-first-example"-dir and 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.

The ipkg build process from source (using ./configure, make, ...) is described on wiki/BuildingIpkgs.

This allows you to install source tarballs directly to the ipaq. As this is unusual at the moment, check the above mentioned page.

11.4 Package example : netup

As I install the ipaq frequently including the bootloader and the task-bootstrap, I run also frequently into the same problems getting the network up. To make this easier, I decided to use my own "netup" ipkg to install the required stuff.

This section describes how to do this. You can get my netup and use it as a template.

check Download.

The following listing shows all files included.

        netup
        netup/etc
        netup/etc/hosts
        netup/etc/hosts.equiv
        netup/etc/pcmcia
        netup/etc/pcmcia/network.opts
        netup/etc/ipkg.conf
        netup/etc/resolv.conf
        netup/root
        netup/root/xirc2ps-modules-2.4.7-rmk3-np1-devfs_hh12_arm.ipk
        netup/CONTROL
        netup/CONTROL/control
        netup/CONTROL/postinst
        

As you see, there are some user specific files under /etc as well as in /root the required module xirc2ps-modules..., which will be installed using the postinst shell script. The module is necessary to get the network up, as I have a xircom pcmcia network adapter.

The next paragraph shows the control file.

        Package: netup
        Version: 1.1
        Priority: important
        Architecture: arm
        Maintainer: Werner Schulte - werner@schulte-ac.de
        Description: ipaq postinstallation for werner after
         task-bootstrap load (new installation)
        

You can download netup.tar.gz from this page as an example. Just fill in the required info and use for your network setup.