guile/README-PACKAGING

-*-text-*-
Guile Packaging Guide
Copyright (C) 2002,2004 Free Software Foundation, Inc.

   Permission is granted to anyone to make or distribute verbatim copies
   of this document as received, in any medium, provided that the
   copyright notice and permission notice are preserved,
   and that the distributor grants the recipient permission
   for further redistribution as permitted by this notice.

   Permission is granted to distribute modified versions
   of this document, or of portions of it,
   under the above conditions, provided also that they
   carry prominent notices stating who last changed them,
   and that any new or changed statements about the activities
   of the Free Software Foundation are approved by the Foundation.


This guide will eventually include comprehensive recommendations for
packaging Guile.  Since the guide is still being developed, if you're
planning to package guile for a distribution, say via .debs, .rpms,
etc., please ask questions on the Guile development list at
guile-devel@gnu.org.  Packaging Guile in a way that makes future
system upgrades go smoothly and allows multiple major versions of
Guile to coexist peacefully can be tricky.  Some initial care in this
regard can save a lot of work later on.

Below is an initial set of issues that are important to consider, and
again, you're always welcome to consult guile-devel.  We should be
able to help with any issues that haven't made it here yet.

Libraries:
----------

  Under most packaging systems, it can be very important to package
  each shared library in a separate package.  However, Guile follows
  some conventions that make it's requirements somewhat different.  In
  order to explain the situaion, we'll first give a brief explanation
  of the general issue, followed by a description of how Guile
  differs.

  For most projects providing shared libraries, it can be important to
  place each library in a separate package and to put the the
  library's major version number in the name of the package.  For
  example, rather than libguile.deb or libguile.rpm, you might have
  libguile9.deb or libguile9.rpm.  This makes it possible for you or
  someone else to provide a libguile10 package later that can
  peacefully coexist with libguile9.  This means that applications
  that were compiled against libguile9 can continue to function even
  when some new version of Guile providing libguile10 is installed.

  If you put more than one library in a package, say libfoo.so.10 and
  libbar.so.10, and then in the next release, the upstream developers
  increment libfoo to libfoo.so.11, but leave libbar alone, then you
  have a problem.  Your next library package will conflict with the
  previous one because both will contain libbar.so.10 (presuming that
  your packaging system considers duplicate files an error).  This
  means that the old and new library packages cannot be installed
  simultaneously, and of course, if the new library package is
  installed, and the old one is removed, any software that was linked
  against libbar.so.10 will now be broken until it is recompiled.  On
  the other hand, if libfoo and libbar had been in separate packages,
  there would have been no problem.

  However, Guile is somewhat unusual because it promises to increment
  all of the major versions of all of its shared libraries with the
  start of every new stable series (i.e. at release 1.6.0, 1.8.0,
  etc.) and Guile also promises that there will be no backward
  incompatibilities for libraries released during a stable series
  (i.e. when going from 1.6.X to 1.6.Y).  This means that unlike many
  other projects, it is actually safe to place all of Guile's shared
  libraries in one package.  For example, Debian places all of the
  shared libraries in a guile-1.6-libs package.

Executables:
------------

  It is suggested that the executables be versioned somehow so that
  more than one version of guile can be installed at the same time.
  This is something that we may eventually address more fully
  upstream, but for now, you may want to name the executables
  according to the version and then provide some way for symlinks to
  be installed from /usr/bin/guile, etc. that point to the actual
  executables. i.e.:

    /usr/bin/guile -> /usr/bin/guile-1.6
    etc.

  Debian, for example would handle these symlinks via the
  update-alternatives mechanism so that the local admin would be able
  to control which version of Guile was the default.

  Of course for this to be a really solid approach, we should be
  naming things this way upstream and should either use the versioned
  names in scripts, i.e. #!/usr/bin/guile-1.6, or have some other way
  to make sure the script gets the version of guile it needs.