************************************************************************ 
*
* Marlin is a C++ software framework for ILC software.
* It uses the LCIO data model and can be used for
* all tasks that involve processing of LCIO files, e.g. reconstruction
* and analysis.
*
*
* F. Gaede, DESY
* J. Engels, DESY
* $Id: README,v 1.19 2008-06-24 13:46:48 engels Exp $
************************************************************************


The idea is that every computing task is implemented as a processor (module) that analyzes 
data in an LCEvent and creates additional output collections that are added to the event.
The framework allows to define the processors (and their order) that are executed at runtime in a 
simple steering file.
Via the steering file you can also define named parameters (string, float, int - single and arrays)
for every processor as well as for the global scope.
By using the framework users don't have to write any code that deals with the IO they simply 
write processors with defined callbacks, i.e. init(), processRunHeader(), processEvent(), end().


  +++++++++++++ (NEW since v00-09-08) ++++++++++++++++

    CMake is now the new default build tool for Marlin - it simplifies the build process
    and creates shared libraries by default. 
    This makes it easier to include external packages through a plugin mechanism,
    in particular only the package that has changed needs to be recompiled and no 
    relinking is necessary.
    
  ++++++++++++++++++++++++++++++++++++++++++++++++++++


    Instructions for building Marlin with CMake:
    -------------------------------------------

    . path_to_ilcsoft_installation/v01-XX/init_ilcsoft.sh

    mkdir build
    cd build

    cmake -C $ILCSOFT/ILCSoft.cmake ..
    
    make install


    Loading plugins/processors dynamically ( at run time ):
    -------------------------------------------------------
    
    It is possible to load plugins dynamically @ run-time into Marlin
    by setting the colon-separated environment variable MARLIN_DLL to
    a list of plugins:
    
    Take mymarlin as an example:
    
    cd ./examples/mymarlin
    mkdir build ; cd build
    cmake -C $ILCSOFT/ILCSoft.cmake ..
    make install

    export MARLIN_DLL="$PWD/lib/libmymarlin.so"
    Marlin -x

    If you have 2 or more libs you should separate them with a ':'
    $ export MARLIN_DLL="/path1/lib1.so:/path2/lib2.so"
    

    Create a new Marlin Plugin / Processor:
    ---------------------------------------
    
    ./examples/mymarlin can be used as a template for a new Marlin plugin

    simply copy the whole directory:

    cp -r $MARLIN/examples/mymarlin MyFastJetClustering (or whatever your processor should be called...)

    renaming the files source files, e.g.

    mv include/MyProcessor.h include/ChooseAReasonableNameForThisClass.h
    mv src/MyProcessor.cc src/ChooseAReasonableNameForThisClass.cc

    change in CMakeLists.txt:

        * PROJECT( MyFastJetClusteringProcessor )
    
        * if needed check DEPENDENCIES for additional required / optional packages


    compile your new plugin as described above for the mymarlin example under
    "Loading plugins/processors dynamically"



    For more information on CMake for the ILCSoftware, check:
    http://ilcsoft.desy.de/portal/general_documentation/index_eng.html

    CMake's official website:
    http://www.cmake.org


  ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++



    To develop your own processors and create applications:
    -------------------------------------------------------

  - Inherit from Processor and overwrite the needed methods (init(), processRunHeader(), 
  processEvent(), end()).

  - provide default constructor that initializes the Processor with a type name (typically the class name)
    and one globale instance of your class, e.g. 

     TestProcessor aTestProcessor ;
     TestProcessor::TestProcessor() : Processor("TestProcessor") {}

     this makes your processor known to Marlin.


  - Create the steering file:

    old ascii format (DEPRECATED: use XML format):
    -----------------
    * start from test.steer and add sections for every needed processor (use ./bin/MyMarlinApp -l 
      to get example sections for all known processors)
    * Add your processor(s) to the variable ActiveProcessors with a unique name.
    * Add a section with the processor parameters to the steering file (identified by the unique name)
    * Don't forget the parameter ProcessorType (typically the class name)
 
    -> run: './bin/MyMarlinApp test.steer'


  +++ (NEW since v00-09) +++

    new XML format:
    ---------------
    * create an example steering file with ./bin/MyMarlinApp -x > test.xml
    * edit the <execute/> section by adding processors as needed (use the names 
      defined in the corresponding <processor/> tag.  

    -> run: './bin/MyMarlinApp test.xml'

    * XML files provide a mechanism to group processors and to define conditions for the 
      execution of the processors (see API doc of class XMLParser for details)     

  ++++++++++++++++++++++++++

If you are updating from an older version please also read the ./doc/release.notes and the latest version
of the API doc !