=====================================================
_The PLaneT Module Repository Interaction Collection_
=====================================================

--------------
_Using PLaneT_
--------------

The PLaneT system is a method for automatically sharing code packages,
both as libraries and as full applications, that gives every user of a
PLaneT client the illusion of having a local copy of every code
package on the server, but is parsimonious in its transmission. It
consists of a centralized server that holds all packages and
individual clients that hold some portion of the archive
locally. Maintenance of that archive should be transparent, and is the
complete responsibility of the PLaneT client. This library provides
both a client and a server; most users will only ever need to use the
client.

The PLaneT client receives user requests (i.e., the (require (planet
...)) forms) and loads the appropriate modules in response. In the
course of handling these requests it may download new code packages
from the PLaneT server.

The structure of user PLaneT invocations is listed below.

PLANET-REQUEST ::= (planet FILE-NAME PKG-SPEC [PATH ...]) 
FILE-NAME      ::= string
PKG-SPEC       ::= string | (FILE-PATH ... PKG-NAME) | (FILE-PATH ... PKG-NAME VER-SPEC)
VER-SPEC       ::= Nat | (Nat MINOR) 
MINOR          ::= Nat       ; the specified revision or above
                 | (Nat Nat) ; a revision between the two specified numbers (inclusive)
                 | (= Nat)   ; exactly the revision specified
                 | (+ Nat)   ; the specified revision or above
                 | (- Nat)   ; the specified revision or below
FILE-PATH      ::= string
PKG-NAME       ::= string
OWNER-NAME     ::= string
PATH           ::= string

All strings must be legal filename strings.

When encountered, a planet-request is interpreted as requiring the
given file name from the given logical package, specified by the
client's host language (automatically deduced by the client), the
package spec and the collection specification, if given. If no
VER-SPEC is provided, the most recent version is assumed. If no
owner-name/path ... clause is provided, the default package is
assumed.

_config.ss: client configuration_

This file provides several parameters useful for configuring how
PLaneT works. 

Parameters:

> PLANET-SERVER-NAME: parameter[string]

The name of the PLaneT server to which the client should connect if it
needs to fetch a package. The default value for this parameter is
"planet.plt-scheme.org".

> PLANET-SERVER-PORT: parameter[Nat]

The port on the server the client should connect to. The default value
for this parameter is 10000.

> PLANET-DIR: parameter[directory]

The root PLaneT directory. Default is the directory in which config.ss
is found.

> CACHE-DIR: parameter[directory]

The root of the PLaneT client's cache directory. The default is the
"planet-cache" subdirectory of the root PLaneT directory.

> LINKAGE-FILE: parameter[file]

The file to use as the first place PLaneT looks to determine how a
particular PLaneT dependence in a file should be satisfied. The
contents of this file are used to ensure that no "magic upgrades"
occur after a package is installed. The default is the file "LINKAGE"
in the root PLaneT directory.

> LOG-FILE: parameter[file or #f]

If #f, indicates that no logging should take place. Otherwise
specifies the file into which logging should be written. The default
is the file "INSTALL-LOG" in the root PLaneT directory.


Note that while these parameters can be useful to modify
programmatically, PLaneT code runs at module-expansion time and so
most user programs cannot set them until PLaneT has already
run. Therefore to meaningfully change these settings it is best to
manually edit the config.ss file.

_util.ss: utility functions_

The functions in this module support examination of the pieces of
PLaneT. They are meant primarily to support debugging and to allow
easier development of higher-level package-management tools.

_current-cache-contents_ : -> ((string ((string ((nat (nat ...)) ...)) ...)) ...)

Returns a listing of all package names and versions installed in the
local cache.

_current-linkage_: -> ((filename (package-name nat nat) ...) ...)

Gives the current linkage table.

_make-planet-archive_: directory [file] -> file

Makes a .plt archive file suitable for PLaneT whose contents are all
files in the given directory and returns that file's name.  If the
optional filename argument is provided, that filename will be used as
the output file's name.


_Distributing Packages with PLaneT_
-----------------------------------

To put a package on PLaneT, or release an upgrade to an
already-existing package:

1. PREPARE A DIRECTORY

Make sure that all source files, documentation, etc. that you want to
be a part of the package are in a single directory and its
subdirectories. Furthermore make sure that nothing else, e.g. unneeded
backup files, is in that directory (with the exception that the
subdirectories and files CVS creates are allowed).

For instance, in the following directory tree, my-app/ is set up
appropriately:

home/
  ...
  jacob/
  ...
    my-app/
      doc.txt
      my-app.ss
      graphic-for-my-app.png
      private/
         implementation.ss

2. CREATE INFO.SS AND DOC.TXT FILES [OPTIONAL]

If you put a file named info.ss in your package's root directory, the
PLaneT system will look in it for descriptive metadata about your
package. The PLaneT system looks for two names in that file:

The _'blurb field_

If present, the blurb field should contain a list of xexprs that
PLaneT will use as a short description of your project. This field
is also used by the Help Desk.

The _'primary-file field_

If present, the primary-file field should be a string corresponding to
the name (without path) of the main Scheme source file of your
package. PLaneT will direct casual users of your library to require
this file.

In addition, PLaneT uses the setup-plt installer to install packages
on client machines, so all the fields it looks for can be included. In
particular, adding a name field indicates that the Scheme files in the
package should be compiled during installation; it is probably a good
idea to add it.

An example info.ss file looks like this:

(module info (lib "infotab.ss" "setup")
  (define name "My Application")
  (define blurb
    (list "My application runs 60% faster on 20% less peanut "
	  "butter. It even shows a fancy graphic!"))
  (define primary-file "my-app.ss"))


See the PLT mzc: MzScheme Compiler Manual, chapter 7 for more
information on info.ss files.

The other special file PLaneT looks for in the root directory of your
package is doc.txt. Its contents should be documentation for your
package. Its contents will be available as a link on your package's
listing on the PLaneT web page.

3. BUILD A .PLT FILE

Run the function make-planet-archive from the util.ss module in the 
planet collection with the name of the directory you've prepared as
its argument: 

> (make-planet-archive "/home/jacob/my-app/")

This function will build a packaged version of your directory and
return the path to that package. The path will always be a file named
X.plt, where X is the name of the directory you gave to
make-planet-archive, located in that same directory.

Alternately, you can build your own .plt file using any method that
produces them (see the documentation for the Setup PLT collection for
details). The PLT file you create must be set to install in
user-specified directory rather than in the collects directory or the
user add-ons directory.

4. SUBMIT THE PACKAGE

E-mail the .plt file you built to jacobm+planet@plt-scheme.org If the
package is an upgrade to a prior package, then tell me so and tell me
whether or not this package is backwards-compatible with the package
it's upgrading. There's no particular format for this message; the
system isn't automated yet so I'll just be reading these and
processing them by hand.

Once I've added your package to the repository, I'll e-mail you
back and tell you the require-line users will need to type in to get
it.

WARNING: 

It's very important that packages you say are backwards-compatible
with the prior version, at a minimum contain all the same modules and
provide all the same names the prior version did. If you do not,
programs that use your package will break on some systems.