Let me -*- Outline -*- what ASDF-WORLD is about.

* What is it?

ASDF World is a library adds version controllable ASDF registries by
Ravenpack, Gabor Melis.

It's under the MIT licence. See COPYING.

* Why?

In ASDF a collection of systems is defined implicitly by
the *CENTRAL-REGISTRY* and the *SYSTEM-DEFINITION-SEARCH-FUNCTIONS*.
Sharing these kind of collections is not possible.

ASDF-WORLD aims to provide a simple, portable way to group a number of
asdf systems into a `world' much like the symlinks in a systems/
directory do.

* What is a world?

Not much. It has an INSTALL-LOCATION which is used by asdf-install
when installing into this world. And it knows how to map canonicalized
system names to the pathnames of the system definition files and lends
its knowledge to ASDF via ASDF:*SYSTEM-DEFINITION-SEARCH-FUNCTIONS*.

How it is persisted on disk tells all:

  (:INSTALL-LOCATION ((:UP "site") NIL NIL) :SYSTEM-MAP
   (("cl-utilities" ((:UP "site" "cl-utilities-1.2.4") "cl-utilities" "asd"))
    ("fsvd" ((:UP :UP :UP :UP "own" "fsvd") "fsvd" "asd"))
    ("salza" ((:UP "site" "salza-0.7.4") "salza" "asd"))))

The representation of pathnames is basically:

  (list (rest (pathname-directory pathname))
        (pathname-name pathname)
        (pathname-type pathname))

which should be good enough for relative pathnames. Since our aim is
to be able to share worlds with others - possibly through a version
control system - absolute pathnames don't make much sense anyway.

The pathnames in this representation are relative to the world file.

* How does it work?

Let's create an empty world:

  (create-world "/home/mega/bigproject/worlds/my.world"
                :install-location "/home/mega/bigproject/site/")

Note that INSTALL-LOCATION is made relative to the world file so it is
in effect "../site/" in this case.

WORLD objects are persisted in a very simple manner

  (:INSTALL-LOCATION ((:UP "site") NIL NIL) :SYSTEM-MAP
   (("cl-utilities" ((:UP "site" "cl-utilities-1.2.4") "cl-utilities" "asd"))
    ("fsvd" ((:UP :UP :UP :UP "own" "fsvd") "fsvd" "asd"))
    ("salza" ((:UP "site" "salza-0.7.4") "salza" "asd"))))

In the *WORLD* points to a file in which a WORLD object is saved. ASDF
is given a search function that looks into


  (defun search-world (system)
    (when (and *world* (probe-file *world*))
      (world-system-pathname system)))

  (pushnew 'search-world asdf:*system-definition-search-functions*)

Read example.lisp for more.
