Optional Software Packages - Building Packages yourself

From ReelBox Maniacs

For your convenience, there are some helper programs available to build a package: ipkg-utils. Download them first and have a look, what you have got then. For the next step we are giong to use the ipklg-build script, which creates a package so everything is prepared for uploading it to a feed. We are going to describe the procedure of package building in an example first. At the end of this article, you will find an explanation of the command line usage of ipkg-build.

[edit] Examplary Package Build

You may build your package easily using the ipkg-build shell script. There are some steps to be done to be able to build a package. We will discuss these while developing a simple examplary package named hello-world.

[edit] Creating a directory structure

The fist step to package creation is to setup a directory structure. We want to go the hello-world.sh tool to the opt/bin directory of the target system. It will read some configuration data from opt/etc. At the same level topmost of this directory, we have to create a directory named CONTROL. To keep things for this package together, we setup all this in a directory named hello-word-package.

- hello-world-package -+- opt -+- bin
                       |       |
                       |       +- etc
                       |
                       +- CONTROL

hello-world.sh is a small shell script. The only thing it does, is displaying a message on your OSD. Part of this message it reads from a configuration file:

The confgiguration data are just for showing some of the concept later in this document. If you have any configuration which may be changed by the user, you may want to follow this example.

[edit] Defining some Metadata

Now we have a look at the CONTROL directory. We have to create a file named control there with lines of the form Field: value. Some metadata are to be defined in this file. Required fields are Package, Version, Architecture, Maintainer, Section, Priority and Description. Optional fields include Depends and others. Please have a look at Metadata definitions to understand the meaning of each of the fields and the specific requirements at ReelBox-Maniacs.Org.

[edit] Making ipkg aware of Configuration Files

Because our package has a configuration files, we create the 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.

[edit] Preparing Install and Uninstall Scripts

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 have to 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 preinst, postinst, prerm, and postrm scripts are all the same for our example. They have to be individual files, though. Softlinking doesn't work.

Make sure, the scripts are executable! 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. The root of the package installation is set via ipkg-cl command line option -d <dest_name> or --dest <dest_name>. The value of <dest_name> has to match to an entry in ipkg.conf accordingly.

[edit] Directory Listing of all Preparations

Now everything is prepared to create a package. The directory structure looks like this:

- hello-world-package -+- opt -+- bin --- hello-world.sh
                       |       |
                       |       +- etc --- hello-world.conf
                       |
                       +- CONTROL --- conffiles
                                      control
                                      postinst
                                      postrm
                                      preinst
                                      prerm

hello-world-package/:
total 8
drwxr-xr-x  2 root root 4096 Mar 18 20:38 CONTROL
drwxr-xr-x  4 root root 4096 Mar 18 20:37 opt

hello-world-package/CONTROL:
total 24
-rw-r--r--  1 root root  26 Mar 18 20:38 conffiles
-rw-r--r--  1 root root 616 Mar 18 15:56 control
-rwxr-xr-x  1 root root  86 Mar 18 16:36 postinst
-rwxr-xr-x  1 root root  86 Mar 18 16:36 postrm
-rwxr-xr-x  1 root root  86 Mar 18 16:36 preinst
-rwxr-xr-x  1 root root  86 Mar 18 16:37 prerm

hello-world-package/opt:
total 8
drwxr-xr-x  2 root root 4096 Mar 18 20:37 bin
drwxr-xr-x  2 root root 4096 Mar 18 20:38 etc

hello-world-package/opt/bin:
total 4
-rwxr-xr-x  1 root root 71 Mar 18 16:36 hello-world.sh

hello-world-package/opt/etc:
total 4
-rw-r--r--  1 root root 23 Mar 18 20:38 hello-world.conf

[edit] Building the Package

To create the package, fire up ipkg-build now.

Packaged contents of hello-world-package/ into hello-world_0.0.1-rbm1_i586.ipk

total 8
-rw-r--r--  1 root root 1182 Mar 18 20:52 hello-world_0.0.1-rbm1_i586.ipk
drwxr-xr-x  4 root root 4096 Mar 18 20:50 hello-world-package

The package is now ready to be uploaded to a feed. At ReelBox-maniacs.Org we run a subversion server to check in packages.

[edit] ipkg-build usage

The command line of ipkg-build generally is:

• <pkg_directory> is mandantory. This is the directory containing the CONTROL directory and the directory structure of your choice for the target system.
• -c is optional and causes the package to be build as a tar file. As of version 050831, ipkg-build creates ar files on default. At ReelBox-Maniacs.Org we think it to be kind of strange to put some tar files into an ar file. So we always use the -c option while building packages.
• <destination_directory> is optional and defaults to the current directory. You may want to give another destination here.
• -o owner is optional. If you are not running ipkg-build as root, then provide the -g root and -o root options.
• -g group is optional. If you are not running ipkg-build as root, then provide the -g root and -o root options.
• -C is non functional in the original script. What they tought to use it for is:
  • Files containing a ~ (tilde) in its name, are deleted before the package is built normally (there's a message being displayed while deleting). If you want to keep them and let these files find their way into your package, you should be able to do so using the -C option. To make it work correctly, use the folling patch on ipkg-build:

The ipkg-build script peforms several sanity checks on the package directory and should guide you through any problems.