OOC Package Tool: Repositories

[Michael van Acken <acken@vanacken.do.uunet.de>]

Last week's topic was hierarchical module names and packages.  To
implement them in a useful way, I need to know how to store modules
(source, symbol file, object file, documentation, etc.) on the disk.
At the moment file handling for OOC is handled through directory lists
and wildcards.  This is fine for small systems, but it quickly gets
convoluted with more than a handful of modules distributed over
several directories, and it doesn't scale at all.  I want to see a
better structured approach in OOC, as a complete replacement of the
current implementation.


Let's coin the term "repository" to mean a subtree of the file system
containing a number of modules and associated files.  A repository can
contain 
  
  a) source files (Foo.Mod)
  b) symbol files (Foo.Sym)
  c) object files (Foo.o, or Foo.so, or Foo.[chdo] for oo2c)
  d) library files (libfoo.so and Foo.Lib)
  e) package data (installed packages, versions, dependences, etc)
  f) documentation

Variants a) to c) are module related, while d) and e) group a number
of modules into a larger entity.

A library is nothing but a shared library as used on systems with
linked programs (as opposed to systems with dynamically loaded
modules).  A package is a unit of distribution (i.e., a ".tar.gz"
file).

To simplify things I lay down this relationship: module <= library <=
package.  That is, a library contains modules, and a package contains
libraries and modules.  A module appears in a most one library, and a
library belongs to at most one package.


A repository can contain contain all of the file types mentioned
above, or only a part of them, depending on how the modules in it are
used.  I see these options:

  a) source only repository: useful to give access to other
  developers, in particular in connection with some revision control
  system 

  b) library repository: contains only the files necessary to use the
  modules, usually together with their documentation; safes space when
  using foreign code (=packages) without any need to access it at the
  source level

  c) development repository: contains all "work in progress" files,
  and the source files are expected to change often, in contrast to
  the static variants above


Repositories can be created for different purposes:

  a) WWW repository: a server to distribute module source code without
  using coarser grained packages

  b) cache repository: necessary for a) to make slower access
  acceptable

  c) system wide repository: the library installed with an OOC
  compiler on a single host or file system

  d) user repository: add on packages installed by a user without
  writing access to the system wide repository

  e) project repository: the "work in progress" area used for
  development 

The last three variations are currently emulated by the compiler's
initialization file.  The first two are only idle speculation for now.


The files available to the compiler (or the system) are the union of
all repositories that are listed in the user's configuration.  This
listing also defines the priorities between the repositories, if a
file is in more than one repository.

With a repository, the placement of files is fixed.  The files for a
module `foo.bar.zap' can be found at these places:

  source file  : <rep-root>/src/foo/bar/zap.Mod
  symbol file  : <rep-root>/sym/foo/bar/zap.Sym
  object files : <rep-root>/obj/foo/bar/zap.*
  documentation: <rep-root>/doc/foo/bar/zap.html

A package `zap.hod' installs its own documentation in the file
<rep-root>/_pkg/zap/hod.html'.  In the simplest case this is just a
list of links to the documentation of the package's modules.
Likewise, the documentation of a module is its HTMLized interface if
nothing else is available.  Symbol information for a shared library
can be found in <rep-root>/lib/<lib>.Lib, the shared library itself is
usually placed in a system-dependant directory.

The package's meta information is put into `<rep-root>/pkg/zap-hod.pkg'. 
It contains 

  o the dependence list of the package, 
  o a list of optional base packages,
  o the list of packages against which the package was build,
  o the actual versions of the base packages,
  o the list of PRAGMA and OPTION variables defined by the package, and
  o whatever else may be useful.

Unlike a module (or a library), a package can carry with it variables.
In the current implementation they are defined in the OPTIONS and
PRAGMAS section of the configuration file.  Putting this information
into a package specific file offers the possibility to install a
binary package (like distributed by Debian, _not_ the packages I am
talking about here) into a system simply by dropping the necessary
files into a repository.


As usual, this is just a first draft.  Please comment.

-- mva