Handhelds.org - Open source for handheld devices



ipkg - the Itsy Package Management System

iPKG is a very lightweight package management system. It was designed for Linux installations with severe storage limitations such as handheld computers. iPKG is more than just an embedded Linux flash image builder, (although it does that fairly well). It also allows for dynamic installation/removal of packages on a running system.

note: see BuildingIpkgs for details on creating your own ipkg files.

iPKG is itsy in several ways:


See the IpkgTodo page


ipkg 0.99

ipkg 0.9 adds the following features

Where can I get it?

iPKG has been incorporated into the FamiliarDistribution for the Compaq iPAQ.

How about the source?

Older versions of ipkg are all shell scripts, so you've got the source if you've got one of those ;-) Recent versions, however, are compiled executables. But seriously, look at handhelds.org CVS (instructions at http://www.handhelds.org/sources.html ) and checkout the familiar/dist/ipkg module. The sh subdirectory contains the scripts used on the iPAQ. The util subdirectory contains scripts that are useful if you want to build a .ipk, use ipkg on a machine to create custom images, or maintain a repository of .ipk packages. All these scripts need documentation.

iPKG is available from CVS: checkout familiar/dist/ipkg from the HandheldsCvsRepository.

Snapshot tarballs are also available at http://www.handhelds.org/download/packages/ipkg/

How do I use it?

The ipkg program has many different sub-commands, (provided by the first command-line argument in a manner similar to cvs).

Here is a current snapshot of the available commands:

 usage: ipkg [options...] sub-command [arguments...]
 where sub-command is one of:

 Package Manipulation:
 update                         Update list of available packages
 upgrade                        Upgrade all installed packages to 
                                latest version
 install <pkg>                  Download and install <pkg> 
                                (and dependencies)
 install <file.ipk>             Install package <file.ipk>
 configure [<pkg>]              Configure unpacked packages
 remove <pkg>                   Remove package <pkg>
 flag <flags> <pkg> ...         Flag package(s) <pkg>
                                (<flag>=hold|noprune|user|ok|installed|unpacked (one per invocation))

 Informational Commands:
 list                           List available packages and descriptions
 files <pkg>                    List all files belonging to <pkg>
 search <file>                  Search for a package providing <file>
 info [pkg [<field>]]           Display all/some info fields for <pkg> or all
 status [pkg [<field>]]        Display all/some status fields for <pkg> or all
 download <pkg>                 Download <pkg> to current directory.
 compare_versions <v1> <op> <v2> (compare versions using <= < > >= = << >>)
 print_architecture             prints the architecture.
 whatdepends [-A] [pkgname|pat]+
 whatdependsrec [-A] [pkgname|pat]+
 whatprovides [-A] [pkgname|pat]+
 whatconflicts [-A] [pkgname|pat]+
 whatreplaces [-A] [pkgname|pat]+

 -A                             Query all packages with whatdepends,
                                whatprovides, whatreplaces, whatconflicts
 -V <level>                     Set verbosity level to <level>. If no value is
 --verbosity <level>            provided increase verbosity by one. Verbosity levels:
                                        0 errors only
                                        1 normal messages (default)
                                        2 informative messages
                                        3 debug output
 -f <conf_file>                 Use <conf_file> as the ipkg configuration file
 -conf <conf_file>              Default configuration file location
                                is /etc/ipkg.conf
 -d <dest_name>                 Use <dest_name> as the the root directory for
 -dest <dest_name>              package installation, removal, upgrading.
                                <dest_name> should be a defined dest name 
                                from the configuration file, (but can also
                                be a directory name in a pinch).
 -o <offline_root>              Use <offline_root> as the root directory for
 -offline <offline_root>        offline installation of packages.
 -verbose_wget                  more wget messages

 Force Options (use when ipkg is too smart for its own good):
 -force-depends                 Make dependency checks warnings instead of 
                                errors and install/remove package in spite of
                                failed dependences
 -force-defaults                Use default options for questions asked by
                                ipkg. (no prompts). Note that this will not
                                prevent package installation scripts from
 -force-reinstall               Allow ipkg to reinstall a package.
 -force-overwrite               Allow ipkg to overwrite files from another
                                package during an install.
 -force_space                   Install even if there does not seem to be
                                enough space.
 -noaction                      No action -- test only
 -nodeps                        Do not follow dependences
 -recursive                     Allow ipkg to remove package and all that
                                depend on it.
 -test                          No action -- test only
 -t                             Specify tmp-dir.
 --tmp-dir                      Specify tmp-dir.


 Install the ftp program:
 ipkg install ftp

 Install from an url (ipkg version >=0.9):
 ipkg install http://url/to/some/package.ipk

 Perform a limited local "ipkgfind" (assuming you've already run ipkg update):
 ipkg list|grep searchstring

Configuration Files

The /etc/ipkg.conf file controls the server from which ipkg-update and ipkg-get will pull package information and packages. As of Familiar v0.7 (ipkg 0.99.87) the configuration files are as follows:


Why a new packaging system?

I really like Debian and Debian/arm is a great distribution, but it doesn't fit well, (yet! see http://www.emdebian.org), on a system like a base iPAQ for several reasons:

That said, I didn't want to invent a new packaging system. Debian is well-maintained and it represents an enormous amount of maintainer effort that I do not want to duplicate. I want to be able to easily use any/all of Debian/arm. So iPKG tries to be like Debian, as much as possible. In fact, the philosophy in the development has been something like, "Do it like Debian unless there is a strong reason not to". The majority of the packages in the current repository come more or less straight out of Debian/arm unstable, (with documentation removed). I hope to automate this process of making .ipk packages from .debs, (and I would even like ipkg to be able to point straight at Debian/arm).

So how is it different than Debian?

First, I've written all the control programs from scratch. I looked at the dpkg source and decided that it would be easier to build up something new from scratch rather than to trim that beast down. Currently the ipkg programs are implemented as shell scripts and are still very limited compared to their Debian counterparts. Both of these facts will change as I build up ipkg. The idea is to adhere to Debian policy as much as possible without incurring a large space penalty. I wouldn't mind getting ipkg to the point where it could be a reasonable replacement for dpkg in a full Debian system, (as long as ipkg remains lighter). Another take on this would be to trim dpkg down, this is already being done with udpkg which is being dewveloped for Debian boot-floppies, (see http://www.debianplanet.org/debianplanet/article.php?sid=124). I should learn more about udpkg.

Second, the collection of packages making up the ipkg repository have a finer granularity than standard Debian packages. The Debian boot-floppies developers are doing something similar with udebs, (see debianplanet URL above). I'd like to coordinate these efforts, and eventually migrate this fine level of granularity into Debian proper.

What is the .ipk format?

In keeping with the "Just like Debian" philosphy laid out above, I first made the .ipk format equivalent to .deb, (but renamed to avoid frustration and confusion). However, I recently changed it to be a tar.gz file rather than an ar archive so that ar would not have to be installed to use ipkg. (But with 0.99 we changed it back because gzipping compressed data is a waste of CPU and battery).

So, a .ipk file is an archive (either tar or gzipped tar) containing 3 members:

If you wish to view a .ipk file using WinZip, you can rename it (or copy it) as ....ipk.tar.gz, and then carefully open the contents.

Can I make my own .ipk packages?

Yes, please do. See BuildingIpkgs.

Can I submit my .ipk packages?

Yes, see http://handhelds.org/contributing.html

Can I maintain my own feed of .ipk packages?

Yes. See MaintainingIpkgFeeds.

Is there a list of known feeds?

See IpkgFeeds (and list your feeds there)

Is there an index of feeds and packages?

See http://ipkgfind.handhelds.org/

Any bugs?

Bugs are plentiful. Here is an incomplete list:

What's on the iPKG TODO list?

This is sorted more or less in the order I intend to tackle things:

Feature Requests


If It All Goes Pear Shaped

If ipkg stops working then: (from Carl Worth):

putting the following near the top of the script:

When It Still Won't Work

Working around (a presumably non-working) ipkg: (from critta):

#Get ready.
mkdir /tmp/newipk
cd /tmp/newipk

#Retrieve libipkg
wget -O libipkg.ipk http://familiar.handhelds.org/familiar/feeds/unstable/packages/armv4l/libipkg_0.99.117_arm.ipk

#Unpack the ipk wrapper.
ar -x libipkg.ipk

#In general, when manually installing an ipk, you 
#should probably check the contents of control.tar.gz.
#For the version used as an example, there are no 
#scripts that had to be run for the library portion,
#but there's always the possibility this will change.
#If there are scripts (preinst or postinst), be sure
#you know the appropriate actions to take before and 
#after the next step.

#Unroll the tarball in the root directory.
tar -zxvC / -f data.tar.gz

#Clean up - this isn't strictly necessary, but if 
#you are checking out the files as you extract them 
#(as you probably should) this makes the things 
#easier. Type this command carefully. 
rm -R /tmp/newipk/*

#Now, get the latest ipkg.ipk. (If you skipped the above 
#steps because you are installing an older version, do 
#the initial "Get Ready" mkdir and cd commands first).
wget -O ipkg.ipk http://familiar.handhelds.org/familiar/feeds/unstable/packages/armv4l/ipkg_0.99.117_arm.ipk

#Unpack the ipk wrapper.
ar -x ipkg.ipk

#Check the control file.
tar zxvf control.tar.gz

#Look for scripts such as preinst and postinst. I will
#only cover the postinst here, but if a preinst exists
#you should probably run that before unpacking the tarball
#(i.e. ./preinst)
ls -l

#When upgrading from a version older than 0.99.110 
#[Not sure of version this changed], you will likely have 
#to remove the ipkg executable because it is not included
#in the data.tar (it becomes a link to ipkg-cl instead 
#during postinst). If this file is already a link, just 
#leave it alone [I think - you might have to run the prerm
#for the current version first].
rm /usr/bin/ipkg

#Unroll the tarball.
tar -zxvC / -f data.tar.gz

#Run the postinst script. If you get an error regarding
#linking on this step, be sure you removed the original
#binary ipkg and then try again.

#To cleanup the temporary files, you can reboot or:
cd /
rm -R /tmp/newipk

#Check your version
ipkg --version

Hopefully it matches what you downloaded :)

- Chris Thompson (critta), Carl Worth, Jonathan Chetwynd.

- Previous content by ColinMarquardt (stale items removed)

- CarlWorth, JameyHicks