dpkg/doc/dselect-methods.txt

From ian Sun May 14 18:21:53 +0100 1995
To: Debian developers list <debian-devel@pixar.com>
Subject: dselect installation method scripts

Below is a (somewhat amended) repost of the posting I made a little
while ago about the interface between dselect and the installation
scripts it can run to extract packages.

Carl Streeter has some hard disk scripts that look fairly good (I
haven't tested them).  Anyone else looking to write such scripts
should see his code (Carl, can you upload them please ?).

Howevever, there are a few points to note:
 * Each set of scripts can support several `options' as they're called
- this saves having different code for the CD-ROM, hard disk, &c
methods.
 * You have to supply a /usr/[local]/lib/dpkg/methods/<method>/names
file listing the options - see below.

dselect *will* look in /usr/local/lib/dpkg/methods as well as
/usr/lib.  Put your scripts there until you send them to me for
inclusion in dpkg.

Details if the installation method handling is below, and in
method-scripts.txt; an example `test' method that just shows you how
to write a `names' file and how dselect reacts is available as:

ab2022c57a1198838034c5f87ea501b1  dselect-example-test-method.tar
-rw-rw-r--   1 ian      ian         10240 May 14 18:19 dselect-example-test-method.tar

NB that the code in dselect to select and call installation scripts is
ALPHA !

Ian.

Each `installation method' will have three scripts:

 * Setup installation parameters.
 * Update list of available packages.
 * Unpack.

Which set of scripts is to be used is selectable by the user, from the
`[S]etup' menu option.  Basically, the user hits `Setup', gets
presented with a menu of choices and picks one.

This (a) sets that `choice' to be the default installation method and
(b) runs the `setup' script for that choice.

The setup script should prompt the user for parameters like the site
to NFS-mount or FTP from, the directory to use, or the directory or
filesystem where the .deb files can be found, or the tape or floppy
device to install from.  It should store the responses under
/var/lib/dpkg/methods - see below.

The update script should obtain a list of available packages if
possible (this is the Packages file from the FTP sites), and copy it
to /var/lib/dpkg/available.  Be careful not to overwrite the available
file if something goes wrong - I'd suggest copying to `available.new'
and renaming.  If no available list is available :-) it should print a
message saying so.

The unpack script should feed all the available .deb files to
  dpkg --unpack --no-also-select
(the --auto option may also be useful here).  In the future there will
be a mechanism to allow (for example) a floppy-based installation
scheme to tell the user which packages are still to be processed; in
the meantime you should just keep going until the user says `stop'.

If any of these scripts needs to display a message for the user, it
should wait for the user to hit `return' before exiting so that
dselect doesn't immediately rewrite the screen.

If a script gives a non-zero exit status dselect will print a message
about it and prompt the user for an acknowledgement.  If it exits with
a zero exit status then dselect will immediately go back into curses
and any message that the script printed just before exiting will not
be visible.

The scripts will be kept in /usr/lib/dpkg/methods/.  Each method
should have a directory under methods, containing:
  `names'  - a list of `user-visible options', see below.
  `setup', `update', `unpack'  - executable programs.
  `desc.<option>' - description file.

A method may provide several options on the `main menu' with different
behaviour.  For example, there might be a generic get-packages-by-FTP
method which might provide entries in the main menu for installation
directly from one of the Debian mirror sites as well as for
installation from a user-specified site.

The `setup', `update' and `unpack' will be invoked with three
arguments.

The first argument is the directory with the dpkg status information,
usually /var/lib/dpkg.  They should $1/methods/<method-name> to store
their data (remember that the user can give a --admindir option to
dselect).

The second and third argument are the name of the method and the
option within that method, respectively.  This information is provided
by dselect (from the user's choice of installation option).

`names' will be formatted as a list of lines, each containing:
 <sequence> <option> <summary>

<sequence> is a two-digit number that will be used much like rc.d
prefixes to control the order in the main menu.  If in doubt use 50.

<option> is a name which will be passed to `setup', `update' and
`unpack' as their third argument (see above).

<summary> is the menu entry string.

Each option may have an extended description in `desc.<option>'.  This
should be formatted like a Description: field entry *shifted one
character to the left*.

/var/lib/dpkg/methods will exist, and a method may use a
/var/lib/dpkg/methods/<method> directory or file (or <method>.* files)
to store its state.

<method> and <option> must follow the rules for C identifiers.

-- Ian Jackson 14th May 1995