PROJECT: Merlin
====================================================================

DESCRIPTION: 
------------

This directory contains the Merlin sources and all resources required to build a Merlin installation.  Structure and build procedures are described below.

STRUCTURE:
----------

  merlin
    |
    +-- activation
        +- api                   activation API interfaces and classes
        +- spi                   activation SPI interfaces and classes
        +- impl                  activation implementation
    +-- composition              
        +- api                   composition API
        +- spi                   composition SPI
        +- impl                  composition framework implementation
    +-- extension                
        +-- spi                  jar management SPI interfaces and classes
        +-- impl                 jar management implementation
    +-- kernel                   
        +- bootstrap             kernel bootstrap
        +- spi                   kernel interfaces
        +- impl                  kernel implementation
        +- plugin                kernel plugin for Maven
        +- unit                  abstract merlin unit test framework
    +-- platform                 
        +- src                   resources used to build a merlin installation
        +- tutorials             several merlin tutorials
        +- xdocs                 site documentation src 
    +-- target                   
        +- merlin                the generated installation (see 
                                 build procedure detailed below)
        +- docs                  generate site documentation


BUILD PROCEDURE:
----------------

The Merlin project requires the Maven project management tool. 
The avalon:install goal builds a Merlin installation directory under the 
default /target/merlin.

  $ maven avalon:install

Following the creation of an installation you need to declare the environment 
variable MERLIN_HOME with a value corresponding to the directory in which you
choose to deploy the merlin system.  Please also make sure that you include
MERLIN_HOME/bin in your PATH environment variable.  You can then move the merlin
directory to MERLIN_HOME following which the Merlin command line utilities 
should function properly.  You can confirm this (on NT) by opening a new DOS 
window and invoking the following command:

  $ merlin -version

Support for the installation and execution of Merlin as an NT process is 
now included in the package (refer bin directory) - special thanks to Leif
for helping to set this up.  When updating an existing installation, the 
maven goal avalon:update invokes the classic avalon:install and updates your 
local merlin repository.  This is often convinient if you are frequently  
updating the merlin core.

For additional information please check the documentation and also use the 
Avalon Users list (subscription details in the doc).  The avalon:site goal 
aggregates the sources from across the main Merlin sub-projects to build a 
consolidated project presentation. The goal should be invoked from the 
root merlin cvs directory.

  $ maven avalon:site

Finally, a note concerning product status. 

The client contract concerns the interaction between a component 
and the Merlin containment system.  This deals with the description
of deployment directives (such as <container>, <component>), standard 
names for context entries, standard attribute names, etc. At this level
the Merlin platform has been very stable and functioning reliably in 
production applications.  And changes in this area will be dealt with 
a very high sensitivity to end-user impact and best-effort will be 
applied to ensure backward compatibility.

Product APIs and implementations are evolving and no gaurantees are 
provided concerning backward compatability at this time. Refactoring and
class renaming is ongoing under the 3.3 with the objective of establishing
a stable 3.4 release.  This aspect should only be of concern to developers
engaged in the embedding of Merlin within another application.

SJM 15 January 2004