Debian treatment for Yorick add-on packages
-------------------------------------------

1 What are Yorick add-on packages?

2 How to install add-on packages under Debian?
 2.1 Using pkg_mngr.i
 2.2 Compiling from source
 2.3 Adjusting your paths

3 Technical details
 3.1 What does Debian do with add-on packages?
 3.2 Why?
 3.3 How?

4 Bugs
 4.1 ERROR (*main*) autoload variable must be nil initially
 4.2 GISTPATH

1) What are Yorick add-on packages?
-----------------------------------

The Yorick core package is intentionally simple. It has very few external
dependencies and contains only the functionalities needed in most setups.

Add-on packages exist for a variety of more specific problems, ranging from
fairly general purpose file format support (e.g. jpeg support in the yorick-z
package) to very specialized software (e.g. modelling of the adaptive optics
systems used in modern telescopes in the yorick-yao package).

Some of these add-ons are purely interpreted libraries, others contain
compiled code (and are then called plug-ins).

There are basically three ways of installing add-ons:
  - some are available as Debian packages installable through e.g. apt-get
    (there names always start in yorick-);
  - more can be downloaded and installed using Yorick's own package manager
    pkg_mngr.i (as of writing, the only Debian platform supported is i386, ppc
    coming soon);
  - even more can be downloaded from the Internet as source code that you have
    to compile and install yourself.

We will describe the last two methods below, as the first is straightforward.

2) How to install add-on packages under Debian?
-----------------------------------------------

 2.1 using pkg_mngr.i
 --------------------

This method currently works only for GNU/Linux on i386 as well as MacOS on PPC
and MS Windows on i386.

To install packages using the pkg_mngr, simply install the Debian package
`curl' and issue the following at the Yorick prompt:

//install system-wide under /usr/local/lib/yorick:
// you must be root or in the `staff' group

 #include "pkg_mngr.i";  // you then get a message that a special Debian
                         // configuration has been loaded
 pkg_sync;               // synchronize the package list with the repository
 pkg_list;               // lists available packages
 pkg_install,"pkg_name"; // replace pkg_name by the actual name

//install at the user level or at another location:

 #include "pkg_mngr.i";  // you then get a message that a special Debian
                         // configuration has been loaded
 pkg_setup;              // reconfigure the pkg_mngr: you would normally
                         // accept all defaults except for `PKG_Y_HOME'. 
                         // Follow the instructions on screen.
 pkg_sync;               // synchronize the package list with the repository
 pkg_list;               // lists available packages
 pkg_install,"pkg_name"; // replace pkg_name by the actual name



 2.2 Compiling from source
 -------------------------

First make sure you installed the yorick-dev package.

Packages usually come with instructions on how to install them, which for
simpler packages boils down to:

 yorick -batch make.i # sometimes a more complicated configure step
 make
 make install

Under Debian, you can specify the variables DEST_Y_SITE and DEST_Y_HOME (and
DEST_Y_BINDIR if you are building an executable) in this last `make install'
step to install at a custom place. For instance:

# system-wide, recommended place (/usr/local/lib/yorick):
 make DEST_Y_SITE=/usr/local/lib/yorick \
      DEST_Y_HOME=/usr/local/lib/yorick \
      install

# per-user, canonical place (~/.yorick):
 make DEST_Y_SITE=~/.yorick \
      DEST_Y_HOME=~/.yorick \
      install

See /usr/lib/yorick/Makepkg for details.


 2.3 adjusting your paths
 ------------------------

You must make sure Yorick is able to find the files you install. The Debian
default configuration includes a full package tree in /usr/local/lib/yorick,
so if you install packages there, you have nothing special to do (see
/etc/yorick/20usrlocal.i).

On the other hand, if you install in another place (say, ~/.yorick), you must
add the following lines in a startup file (e.g. ~/.yorick/custom.i or any .i
file in ~/.yorick/i-start):

 require, "pathfun.i";
 add_y_home,"~/.yorick/";

pkg_setup will offer to do it for you.


3) Technical details
--------------------

 3.1 What does Debian do with add-on packages?
 ---------------------------------------------

It is recommended not to mix packages installed through these various means
in the same directory. The following is advisable:

  - packages installed using Debian's apt-get are installed in the main Yorick
    tree (/usr/lib/yorick/);
  - packages installed system-wide using Yorick's pkg_mngr or compiled manually
    are installed in a local tree (/usr/local/lib/yorick/);
  - additionally, users can install packages in their home directory.

 3.2 Why?
 --------

Apt is not aware of packages installed through the pkg_mngr. On the other hand,
the pkg_mngr is aware of packages installed through apt, but not that they have
been installed through apt. So you could easily install a package with apt and
remove it with the pkg_mngr, leaving your system in an inconsistent
state.

Another useful example: in the future, it is possible (and, actually, likely)
that the main Yorick package for Debian will change significantly, e.g. that
the main directory will be relocated. Debian packages for add-ons will be
updated accordingly, but packages installed using the pkg_mngr will be left
behind. Even worse, if the main directory is split rather than relocated, then
packages installed using the pkg_mngr will end-up half installed.

In a word, separating the apt space and the pkg_mngr/local space will save the
sysadmins from almost certain future hassle.


 3.3 How?
 --------

First of all, the local tree must be taken into account into the various paths
of Yorick. This is achieved through the file /etc/yorick/20usrlocal.i .

The second part is to get pkg_mngr to install files under
/usr/local/lib/yorick/. The Debian package provides a file
/etc/yorick/packages/pkg_setup.i which performs the basic configuration of the
pkg_mngr. This file also reads /usr/local/lib/yorick/packages/pkg_setup.i if
it exists. /etc/yorick/packages/pkg_setup.i is pointed to by a link in
Y_HOME/packages, that pkg_mngr.i reads when it is first loaded, unless the
variable PKG_SETUP is set.

There are copies of these two files in /usr/share/doc/yorick/examples/ .


4) Bugs
-------

 4.1) ERROR (*main*) autoload variable must be nil initially
 -----------------------------------------------------------

This error is due to the autoload() function and happens when the same package
is installed twice, for instance both system-wide and per-user.

More precisely, upon Yorick startup, if a package is installed twice in your
path, you will get an error such as:

 ERROR (*main*) autoload variable must be nil initially
 WARNING detailed line number information unavailable
 now at pc= 1 (of 17), failed at pc= 11
   LINE: 1  FILE: ~/.yorick/i-start/mypkg-auto.i
  To enter debug mode, type <RETURN> now (then dbexit to get out)

Check all your i-start directories (/usr/lib/yorick/i-start/,
/usr/local/lib/yorick/i-start/, ~/.yorick/i-start/) for files with the same
name (in this case, "mypkg-auto.i"). If you find several of them, ask yourself
whether you need both copies of the package (presumably called "mypkg" in this
example). If not, simply deinstall one of the instances of the package.

If yes, then you can have the error disappear by doing the following:
  - write down all the .i files that are referred to by calls such as
      autoload, "file.i", var1, var2....;
    in this file "mypkg-auto.i";
  - for each one of them, write a line like 
      autoload, "file.i";
    without variable specification once near the top of the file
    ~/.yorick/i-start/mypkg-auto.i .

This issue is being thought in depth by upstream.


 -- Thibaut Paumard <paumard@users.sourceforge.net>  Sat, 28 Nov 2009 20:44:19 +0100

