# HOWTO add (or remove) a package database

## Background

These are web pages that introduce the package system in Puppy 5.x:
http://puppylinux.com/woof/ppm.htm
http://puppylinux.com/woof/pkg-db-format.htm
There are two local files that you need to know about:
/root/.packages/DISTRO_PET_REPOS
/root/.packages/DISTRO_COMPAT_REPOS

## DISTRO_COMPAT_REPOS

What you will see in this file are two variables named PKG_DOCS_DISTRO_COMPAT and REPOS_DISTRO_COMPAT.

### PKG_DOCS_DISTRO_COMPAT

This consists of a series of entries that are separated by a space-character. Here is an example of one entry:

    slackware.cs.utah.edu|http://slackware.cs.utah.edu/pub/slackware/slackware-${DISTRO_COMPAT_VERSION}/PACKAGES.TXT|Packages-slackware-${DISTRO_COMPAT_VERSION}-official

The variable DISTRO_COMPAT_VERSION is defined in this file:
/etc/DISTRO_SPECS
An example would be Puppy built from Slackware version 12.2, so the above example resolves to:

    slackware.cs.utah.edu|http://slackware.cs.utah.edu/pub/slackware/slackware-12.2/PACKAGES.TXT|Packages-slackware-12.2-official

The entry has three fields, separated by a vertical-bar character:
1st: This is the URL used for testing that the site is responding.
2nd: The full URI of the repository packages database file.
3rd: The name of the database file after it has been downloaded and converted to a standardised format.
You must only add another repository which has packages of the same "compatible distro" that was used to build Puppy, that is, one of Slackware, Debian, Ubuntu or Arch. The DISTRO_BINARY_COMPAT variable in /etc/DISTRO_SPECS defines this.
So, when Puppy downloads the database file, in the above example 'PACKAGES.TXT', it must be in the database format used by the compatible distro. Puppy will expect it to be in that format to be able to convert it to the standadised format used in Puppy.

### REPOS_DISTRO_COMPAT

This variable has the same format, entries separated by space-character, fields in each entry separated by the vertical-bar. Here is an example:

    slackware.cs.utah.edu|http://slackware.cs.utah.edu/pub/slackware/slackware-${DISTRO_COMPAT_VERSION}|Packages-slackware-${DISTRO_COMPAT_VERSION}-official

...it looks like before, but in this case the full URI is to where the actual packages are kept. Note that individual packages may be in subdirectories but this information is in the package database.
If the repository is mirrored, no problem, additional entries can be made, all with the same 3rd field, for example here is the complete definition of REPOS_DISTRO_COMPAT (it's a bit long, so I've put in new-lines for each entry):

    slackware.cs.utah.edu|http://slackware.cs.utah.edu/pub/slackware/slackware-${DISTRO_COMPAT_VERSION}|Packages-slackware-${DISTRO_COMPAT_VERSION}-official
    slackware.mirrors.tds.net|http://slackware.mirrors.tds.net/pub/slackware/slackware-${DISTRO_COMPAT_VERSION}|Packages-slackware-${DISTRO_COMPAT_VERSION}-official
    ftp.gwdg.de|http://ftp.gwdg.de/pub/linux/slackware/slackware-${DISTRO_COMPAT_VERSION}|Packages-slackware-${DISTRO_COMPAT_VERSION}-official
    ftp.isu.edu.tw|http://ftp.isu.edu.tw/pub/Linux/Slackware/slackware-${DISTRO_COMPAT_VERSION}|Packages-slackware-${DISTRO_COMPAT_VERSION}-official
    repository.slacky.eu|http://repository.slacky.eu/slackware-${DISTRO_COMPAT_VERSION}|Packages-slackware-${DISTRO_COMPAT_VERSION}-slacky

On the other hand, one download site may have more than one "repository". What I mean by that is best shown by example. This is the REPOS_DISTRO_COMPAT variable for the Ubunt-compatible build of Puppy:

    ftp.filearena.net|http://ftp.filearena.net/pub/ubuntu|Packages-ubuntu-${DISTRO_COMPAT_VERSION}-*
    mirror.anl.gov|http://mirror.anl.gov/pub/ubuntu|Packages-ubuntu-${DISTRO_COMPAT_VERSION}-*
    mirrors.kernel.org|http://mirrors.kernel.org/ubuntu|Packages-ubuntu-${DISTRO_COMPAT_VERSION}-*
    archive.ubuntu.com|http://archive.ubuntu.com/ubuntu|Packages-ubuntu-${DISTRO_COMPAT_VERSION}-*

There are actually three different repositories on each site that Puppy can download from, 'main', 'universe' and 'multiverse'. Puppy has a database file for each, for example for the 'Intrepid' release of Ubuntu: 'Packages-ubuntu-intrepid-main', 'Packages-ubuntu-intrepid-universe' and 'Packages-ubuntu-intrepid-multiverse'. Accordingly, the PKG_DOCS_DISTRO_COMPAT variable has this:

    archive.ubuntu.com|http://archive.ubuntu.com/ubuntu/dists/intrepid/main/binary-i386/Packages.bz2|Packages-ubuntu-${DISTRO_COMPAT_VERSION}-main
    archive.ubuntu.com|http://archive.ubuntu.com/ubuntu/dists/intrepid/universe/binary-i386/Packages.bz2|Packages-ubuntu-${DISTRO_COMPAT_VERSION}-universe
    archive.ubuntu.com|http://archive.ubuntu.com/ubuntu/dists/intrepid/multiverse/binary-i386/Packages.bz2|Packages-ubuntu-${DISTRO_COMPAT_VERSION}-multiverse

...that is, it specifies all three databases.

## DISTRO_PET_REPOS

Adding another repository of .pet packages is probably the most likely requirement of a Puppy user. Chances are, when you upgrade to the latest version of Puppy the package manager will be accessing the most appropriate repositories. But, you might want to make an addition right now, or especially so if you are a Puppy-developer.

### PKG_DOCS_PET_REPOS

It is really the same as described above. File DISTRO_PET_REPOS has variable PKG_DOCS_PET_REPOS and here is it's current contents:

    ibiblio.org|http://distro.ibiblio.org//puppylinux/Packages-puppy-woof-official|Packages-puppy-woof-official
    ibiblio.org|http://distro.ibiblio.org//puppylinux/Packages-puppy-4-official|Packages-puppy-4-official
    ibiblio.org|http://distro.ibiblio.org//puppylinux/Packages-puppy-3-official|Packages-puppy-3-official
    ibiblio.org|http://distro.ibiblio.org//puppylinux/Packages-puppy-2-official|Packages-puppy-2-official

Note that the database filename on the site is the same as that after it is downloaded. This is because the PET database file on the site is supposed to already be in the "standardised format". Puppy from version 2.0 up to and including version 4.x has kept package database information in a file /root/.packages/packages.txt, but this is different from the new standardised format -- note though, the Woof build system has a script for converting old 'packages.txt' files into the new format.
So, say you have a repository of .pet packages. Let's say at http://johhny.org/petrepo. What you will have to do is create a database file, say 'Packages-puppy-4-johhny' -- the naming convention is that the second field 'puppy' identifies this as a Puppy .pet repo, the third field '4' identifies what version of Puppy these packages are compiled on/for, while the last field is a unique identification of the repository.
So, add an entry to variable PKG_DOCS_PET_REPOS:

    johhny.org|http://johhny.org/petrepo|Packages-puppy-4-johhny

### PET_REPOS

This is another variable in file DISTRO_PET_REPOS. Here are the current contents:

    ibiblio.org|http://distro.ibiblio.org//puppylinux|Packages-puppy-*-official
    ftp.nluug.nl|http://ftp.nluug.nl/ftp/pub/os/Linux/distr/puppylinux|Packages-puppy-*-official
    ftp.linux.hr|ftp://ftp.linux.hr/puppylinux|Packages-puppy-*-official
    ftp.vcu.edu|ftp://ftp.vcu.edu/pub/gnu+linux/puppylinux|Packages-puppy-*-official
    ftp.tu-chemnitz.de|ftp://ftp.tu-chemnitz.de/.SAN0/pub/linux/sunsite.unc-mirror/distributions/puppylinux|Packages-puppy-*-official
    ftp.ussg.iu.edu|ftp://ftp.ussg.iu.edu/linux/puppylinux|Packages-puppy-*-official
    ftp.lug.udel.edu|ftp://ftp.lug.udel.edu/pub/puppylinux|Packages-puppy-*-official
    ftp.sh.cvut.cz|ftp://ftp.sh.cvut.cz/storage/1/puppy|Packages-puppy-*-official

...notice the '*' wildcard. This is because all of the pet package repositories are at the same sites.
For our hypothetical example, add this line:

    johhny.org|http://johhny.org/petrepo|Packages-puppy-4-johhny

...note again, the .pet packages may be in subdirectories below 'petrepo' and this is defined in the database file.
What the above line is saying is that for any of the packages dclared in 'Packages-puppy-4-johhny', you will find them at http://johhny.org/petrepo.

## Summary

If you add the two entries as shown in the above example, and create a database file 'Packages-puppy-4-johhny' at the website, that's it, you're ready to go.
Click the 'Configure package manager' button in the main GUI window, then click 'Update now', the package manager will download the 'Packages-puppy-4-johhny' and add it to the others and the packages will then display in the main GUI window.
On the other hand, if you want to remove any repository, remove the entries in the variables (the reverse of that above procedure) and delete the 'Packages-*' file.
A final point about the example package database file 'Packages-puppy-4-johhny'. A repository could have mixed .pet packages, that have been compiled in different versions of Puppy. In such a situation, you could create separate 'Packages-*' files for each group. Alternatively, the package database does have extra fields for each package entry that can declare what environment the package was compiled in, for example 'ubuntu|intrepid|puppy' means that this package was compiled in a Puppy that was built from Ubuntu Intrepid packages. I have such a mixed bunch of packages at my ibiblio site, in directory 'pet_packages-woof', and the package database file is 'Packages-puppy-woof-official' -- the 'woof' field is not one of the Puppy release numbers. The Puppy Package Manager is able to sift through such a mixed database and offer only the appropriate packages for installation.
Regards,
Barry Kauler
October 2009