Managing ipks Howto

----

Introduction.

This article is about installing and removing applications and not
about the structure and creation of packages. For the latter see the
development section.

1. What is a feed?

A feed is a collection of .ipk files in a directory together with a
"Packages" file that contains the list of applications plus some other
info extracted from the package.

A feed is not necessary to install a package.  Individual .ipk files
can be installed as well.

The advantage of feeds is that the package managers are able to
install the dependent packages of an application, finding them
directly from the feed(s).  If you can, try to avoid to download the
whole pdaxrom feed from *.pdaxrom.org as it will help to save some
bandwidth and limit the costs of the site. You can use the original
"Packages" file even if some ipks are missing from the directory.

2. Where to install an ipkg.

When installing an application you must choose where to install it.
Typicall choices are "/" the root partition of the internal flash,
"/mnt/user/" the other partition of the internal flash, "/mnt/card"
for the SD, "/mnt/cf" for the CF...  

You must try hard to leave some
freespace on the root partition and on the /mnt/user (which is in fact
mounted as /home) partition.  Even if you install a package on your sd
card, the packager manager will create some links in the root
partition (see 7. if your links seem to have disappear, they do no
take much space but they do take some place and are required.  Even if
you have installed a package on the root partition when you run the
application it might want to save some data and or a configuration
file in the home directory so once again you will want to have some
free space.

Why do I need to format my card(s) in ext2/ext3 format? 

Some packages use features of the traditonal unix filesystems that
are not supported by the fat/fat32 file system. For instance shared
libraries in general consist in one binary file. This is not supported by fat.

Formating the card, creating partition and alternative solutions are
not discussed here.

3. using qpkg.

qpkg is the graphical package manager of pdaxrom.

3.1. Using feeds.

The first thing you need to do is to go to the settings tab and edit
the feed url.  The default url might be wrong so make sure that you
have the feed corresponding to the release you have installed.

Feed urls can be either of the form: http://feedsite.org/path/to/feed
or ftp://server.org/path/to/feed/ for distant feeds or
file:///path/to/feed for a feed on a local storage.

Besides the "official feed" you can add other feeds contributed by
users.

The second thing you need to do is to do an "update".  To do this
press the second button. An update does not install anything new on
your Zaurus,  it only dowloads the latest version of the 
"Packages" file found of the feeds you have in your list to "update"
the list of available applications.

You can then go to the "Available" tab and click in the little
checkbox to indicate the applications you want to install.

'''IMPORTANT''': Before the next step make sure that you have choosen
the place where you want your new applications to be installed.  As
mention before you should make sure to allways have some freespace on
the internal flash.  To choose the destination use the drop-down list
in the upper right corner of the qpkg window.

Finally you can press the third button, the "Apply" button to start
the installation.


3.2 Installing a .ipk file

First choose the place whre you want to install your ipk (see above).

Then Use the first button, the open button, find the .ipk files you want 
to install, click on open the package will be installed.


3.3 Removing a package.

Go to the "Installed tab" and click in the little checkbox to indicate
the applications you want to desinstall.

Then press the third button, the "Apply" button to start the desinstallation.

4. using ipkg from the command line

Note that most of the advices given in the previous sections are valid
also when you work from the command line. You might consider to read
the whole article. 


4.1 using feeds

Ipkg is a shell script similar to apt-get found in Debian Linux
distribution. Its usage is very simple.

First edit the file /etc/ipkg.conf.  The first thing to do is to check
the url of the feeds.  The format is 

 src name url

"src" is a keyword. It must be at the begining of the line (column
0). The name can be pretty much what you want without space, but 2
feeds cannot have the same name (only the second one will be taken
into account. For the url see 3.1

As with qpkg the second thing to do is to do an "update". To do this
type in a terminal.

# ipkg update 

This download the "Packages" file of the feeds so that ipkg knows
what's available.

Next you will want to check the available space to decide where you
are going to install the new package. Type in a terminal

# df -h

You are now ready to install. As an example let's say that we want to
install the package vlc on the SD card. To do this type in a terminal:

# ipkg -d /mnt/card install vlc

 For the destination given after the "-d" we could have used its name
(read more on destination below) ie

# ipkg -d sd install vlc

To see what packages are available in your feeds type:

# ipkg list | more


4.2 Install a .ipk file that is not in a feed

First decide where you want to install the package (see the previous
section). The command is the same as previous, the only difference is
that you use the full name of the file.

# ipkg -d cf install /mnt/cf/vlc_8.1-armv5tel.ipk

4.3 To remove a package

type in a terminal:

# ipkg remove vlc

you don't need to specify a destination, ipkg will search the package
for you and delete the files if found. 

4.4 Links

When a package is installed on an "external storage" ie every
destination but root, ipkg will create symbolic link of each file of
the package in the root partition so that it appears as if it has been
installed there. This creates an illusion of a big root partition.
This is probably not the most elegant solution, but it works.

(a quick note, you can create a symbolic link using the command 'ln
-s' it acts just like the commands cp except that the resulting file
is a link to the source file instead of a copy)

The creation of the links is done by the script "ipkg-link".

Normally you should not have to use this directly, but it might happen
that some links "disappear". To recreate the symbolic links of a
package say vlc use:

# ipkg-link add vlc 


4.5 More Commands

ipkg offers you more commands than the 3 (install remove links) you
can see these options by issuing:

# ipkg 2>&1 | more 

For instance if you want a compact list of the installed packages you
can type:

# ipkg status '.*' Package

If you want to see the files installed by a package (say the vlc
package):

# ipkg files vlc 

You should be able to upgrade all the installed ipk using:

# ipkg upgrade

In practice, the feeds are rarely updated and when a new release is
available you generally reflash the zaurus. 

5. files and directories used by ipkg

5.1 ipkg.conf

The main configuration file is /etc/ipkg.conf.  You can define feeds
location using:

dest name urls

you can define destination, ie mounted partitions on which you want to
install ipks using:

dest name path

you can add proxy settings 

option http-proxy http://myproxy:port 
option ftp-proxy ftp://myproxy:port
option proxy_username myname
option proxy_password mypass


5.2 usr/lib/ipkg

For each destinations ipkg creates a directory in usr/lib/ ie

/usr/lib/ipkg/
/mnt/card/usr/lib/ipkg/
...

In this directory you will find a "status" file which gather some
information on the installed packages.

You will also find a directory "info" which contains a .list file for
each package installed on the current partition. This file
contains (what a surprise) the list of the files of the corresponding 
package.

In /usr/lib/ipkg (and only there) there is also a "lists" directory
which contains the "Packages" files from your feeds.


6. troubleshooting


6.1 I modified /etc/ipkg.conf but qpkg doesn't take my changes into account

qpkg used to load its configuration options from  
 /home/root/Choices/common/Packager.conf and not from /etc/ipkg.conf.
Destinations were hardcoded.

This is be fixed in the newer version.

6.2 qpkg destroy the changes I made in /etc/ipkg.conf

qpkg used to overwrite /etc/ipkg.conf with its own options 
(from Packager.conf)

This is be fixed in the newer version.

6.3 I have done a df -h and I don't see /mnt/user

 /mnt/user does not appears here because it is a link to a
directory in the /home partition. So the space available in /mnt/user
is the space available in /home. 

6.4 I have added a destination in /etc/ipkg.conf but when I install a
new package there I get "Package nnnn not found on external storages."

Destinations used to be hard coded in ipkg-link and ipkg-uninstall and
these scripts complain when they don't find a package.
You should be fine if you create the link yourself.

Or else use a newer version of ipkg-link and ipkg-uninstall where it
is fixed.

6.5 I have added a destination but it doesn't appear in qpkg.

qpkg display only destinations that corresponds to a mounted
filesystem. This is a restriction but it also prevent from installing
a package in /mnt/cf when it is not mounted, which could easily result in a
full root partition.

As a workaround you can mount the directory like this:

mkdir mydest
mount --bind /path/mydest/ /mnt/mydest 

And then use /mnt/mydest as your new destination.