root/main/tags/r1-2-5/DESIGN

( THIS IS REALLY REALLY OUT OF DATE, AND SHOULD BE DELETED )


Notes on newnew design

Root names never ever represent an actual release, only an
interface. If your package depends on a particular release that didn't
change the interface, tough, you'll have to do it manually.

Let's take libpng as an example:

0) run makeinstaller

1) require @libpng.org/libpng/3

2) Check local database, what skeleton version does
@libpng.org/libpng/3 need? It's not in the local database. Go resolve
it from the network.

3) Network says you need @libpng.org/libpng/skeleton.1

4) Do we have this file? Yes, we do, so bundle that into the .package
and continue

5) User runs package

6) skeleton.1 retrives the interface number from the argument to
require, and then scans for the libpng.so.$IV file, where IV is the
variable containing the interface version, in this case 3 (that's an
internal skeleton implementation detail).

7) The check fails, we only have v2 installed. Resolve
@libpng.org/libpng/3

8) The network resolves this to
http://libpng.org/packages/libpng3.package

9) Download and install........


Now let's try with GTK:

1) makeinstaller

2) require @gtk.org/gtk#2.2

3) OK. What skeleton does this require? @gtk.org/gtk/skeleton.2 - we
already have it locally in /var/packages/@gtk.org/gtk/skeleton.2

4) Bundle the skeleton into the .package

5) user installs package

6) The skeleton is called to check if gtk2.2 is present (extracted
from the root name) It's not, so we need to upgrade the system (let's
pretend gtk2.0 is present, installed via the distros packaging
system).

7) Resolve @gtk.org/gtk#2.2

8) In the meantime, 2.4 has come out. GTK2.4 also implements the 2.2
ABI, so in fact it resolves to say
http://gtk.org/packages/gtk-x11-2.4.package: the fact that we're not
downloading 2.2 is irrelevant.

9) WAIT! We don't necessarily want to use autopackage to upgrade gtk,
there may be a distro provided update for it too. If the network comes
back with an apt repository that provides it, we can use that to
upgrade it.


How is the network mirrored locally? We need to know this for now,
because we have no network!

/var/packages/@gnome.org/libxml/2.0
/var/packages/@gnome.org/libxml/2.0.1
/var/packages/@gnome.org/libxml/2.0.2
/var/packages/@gnome.org/libxml/2.1.0

noooooooooo! too many directories! They'd all contain the same file,
with the same contents! Better:

/var/packages/@gnome.org/libxml/2.x


New versioning design
---------------------

Skeletons represent a package as a whole. It doesn't matter how many
times that package has broken interface/ABI compatability, it has one
skeleton. Skeletons actually represent *interfaces*, not packages
themselves. That's a very important distinction. When you depend upon
another piece of software, there is an implicit contract between your
package and the other package. They presumably interact in some way,
otherwise you wouldn't depend on them.

The concept of IC, or interface compatability is an important one. A
package may keep the same interface for ever, or it may break it in
unpredictable ways. Other packages have uniform version numbering
systems that allow you to tell if you will be compatable with it by
examining the number.

There are two ways to identify when an interface changes. The first is
the version number of the underlying package. Some programs/libraries
use GTK/libtool versioning, whereby the major version number indicates
the interface version. The 1.x series has one set of interfaces, 2.x
has another and so on.

However, that doesn't work for all things. Sometimes, packages don't
use libtool versioning, or the interface is basically stable and won't
ever change. For instance Nautilus scripts have a very simple
interface that will probably remain constant for as long as the
feature exists and Netscape plugins have kept the same interface across
multiple major versions.

So, to deal with cases like these, we have interface serial
numbers. For packages where you can't determine the interface from
examining the version number, you can pass the skeleton an interface
number, and the skeleton will map version numbers to interface
numbers.

New function call:

require --matches 2.x @gtk.org/gtk       : this specifies that any version of GTK in the 2.x series will work, ie it was linked with gtk2.0
require --between 2.2 3.0 @gtk.org/gtk   : any version between 2.2 and 3.0 will work (but not including 3.0).
                                           This means it depends on a feature of 2.2
require --interface 1 @gnome.org/scripts : Only interface serial number 1 will work. If later on an extended interface is added (2), then
                                           the package supports both 1 and 2, but you can only ever depend upon a specific number, not a range

These have shortened forms:

require -m 2.x @gtk.org/gtk
require -b 2.2 3.0 @gtk.org/gtk
require -i 1 @gnome.org/scripts


New dependancy design
---------------------

Autopackage comes with a library of package skeletons. These are sets of tests associated
with a root name, that are triggered by the require function in the install script. For
instance, @gnome.org/libxml/2.0 is the rootname for libxml version 2. As part of
autopackage, a module is provided that can test for the presence of this package by
probing for its actual component parts, as opposed to querying for its presence in a
database. When makeinstaller creates the .package file, the scripts are scanned for the
require function and the necessary tests are automatically included. The require command
therefore does the following things:

- Flags a package skeleton to be included in the .package file,
  so it can later be used when the install scripts are run to check
  for the presence of the required "package", which can be a
  library/file/set of files/correct output of xxx-info
  program/whatever and then finally be used to verify the package if
  something goes blooey with it.

- When the script is run, it uses the package skeleton to test for the
  package presence, and to auto-download the package if it's not
  there.

- It adds a dependancy to the required package. This takes the form of
  dual symlinks between the two package-info directories. Integration
  with RPM/DPKG??? not sure if it will always be possible. These
  dependancy symlinks can later be used to verify and repair the
  package.

So if I have package "genst.package" which requires libxml and dialog
0.9, the genst.package will include 2 package skeletons: for
@gnome.org/libxml/2.0 and @advancedresearch.org/dialog/0.9

The package skeleton is a file that includes a test for it's
presence, and instructions for how to retrieve or upgrade it if
necessary. A big part of the success of autopackage will depend on the
quality and abundance of the package skeletons. They will probably be
included in a directory that can be automatically updated by CVS from
the main autopackage servers. The package skeleton can also contain a
description of what the package is, so the user can see what they are
downloading, and perhaps other metadata.