An HTML form of this documentation can be found online at
  http://sergiant.web.cern.ch/sergiant/NA62FW/html/analysis.html

Requirements
------------

This framework need Geant4, ROOT and NA62MC to be compiled and has been tested
with the following versions :
    gcc 4.6.3 | 4.1.2
    Geant4.9.5p03
    ROOT 5.34.04 | 5.34.05
    NA62MC rev_245, rev_255, rev_263

Take care of compiling each of these with the same version of gcc.
Although only tested with these versions, it's most likely to work without 
problem on any other versions

Before starting to work with the framework, you should set the NA62MCSOURCE 
environment variable to point to the directory where you keep your sources 
of NA62MC. 

Glossary
--------
NA62Analysis is divided into two distinct directory trees
  o [FWDir] Framework directory: Contains NA62Analysis itself (what you get from svn).
    You should never have the need to work in this directory.
  o [UserDir] User directory: Work directory that contains your own work (your analyzers, configurations, executables, ...)

Installation
------------

  o Extract the sources from the svn repository
      svn co svn co svn+ssh://svn.cern.ch/reps/na62fw/trunk/NA62Analysis

  o Make sure the NA62MCSOURCE environment variable points to the directory 
    containing NA62MC

  o Setup the environment
      source scripts/env.[c]sh

  o Prepare your user directory[UserDir] by issuing
      ./NA62AnalysisBuilder.py prepare PathToUserDir
    Your user directory[UserDir] can be anywhere except in the same directory than 
    this framework. It should ideally be kept separate to avoid overwriting 
    any of your work when updating the framework. If any update is needed 
    inside your	user directory, the NA62AnalysisBuilder.py tool will take 
    care of it automatically.

  o Go inside your user directory[UserDir], check that scripts/env.[c]sh is correct.

  o The framework is now installed. After sourcing the scripts/env.[c]sh script 
    the framework directory[FWDir] is added to the PATH.
    You should be able to run the framework from your user directory[UserDir] without 
    ever going back to the framework directory[FWDir]. 
    All the python scripts are also directly available from your user directory.

Clean rebuild
-------------	

If you change NA62MC or NA62Reconstruction, you should rebuild the framework.

  o Go in your user directory[UserDir] and setup the environment
      source scripts/env.[c]sh

  o Clean the current build
      NA62AnalysisBuilder.py cleanAll

  o The libraries will be recompiled next time you will try to build and 
    executable with
      NA62AnalysisBuilder.py build configFileName

Update
------

To update the framework, just go inside the framework directory[FWDir] and issue
  svn update

The next time you try to build an executable with
  NA62AnalysisBuilder.py configFileName
the libraries will be recompiled and eventual changes in your user directory[UserDir] 
will be safely done automatically. In case of problem you will see a warning 
message and inform you on the appropriate actions to manually solve the problem.

In case of compilation problem you can try a complete clean rebuild of the 
framework. See the 'Clean rebuild' section.

QuickStart
----------

  o NA62AnalysisBuilder.py help
        will print the help of the NA62AnalysisBuilder.py script

  o NA62AnalysisBuilder.py available
        will print the list of available Analyzers

  o NA62AnalysisBuilder.py cleanUser
        will remove all files generated by the build in the user directory[UserDir]

  o NA62AnalysisBuilder.py cleanFW
        will remove all files generated by the build in the FW directory[FWDir]

  o NA62AnalysisBuilder.py cleanAll
        will remove all files generated by the build in the FW directory[FWDir] and user directory[UserDir]

  o NA62AnalysisBuilder.py new AnalyzerName
        will create a new analyzer with name AnalyzerName in the user directory[UserDir]
        Alternatively AnalyzerName can be replaced by the following syntax: 
        	AnalyzerName(InputType TreeName, ...)
        This will already include the correct persistency headers, request the input tree and 
        retrieve the input events.
        Example: Creating an analyzer named toto using as input the GigaTracker MonteCarlo and 
        LKr and Spectrometer RECO
        	NA62AnalysisBuilder.py new "toto(MC GigaTracker, Reco LKr, Reco Spectrometer)"

  o NA62AnalysisBuilder.py rename oldName newName
        will rename a user analyzer

  o NA62AnalysisBuilder.py build configFileName [-j/--jobs JOBS] [-d/--debug] [--c++11] [--full-warning]
        will build the FW using the configuration file configFileName

  o NA62AnalysisBuilder.py prepare path [-j/--jobs JOBS] [-d/--debug] [--c++11] [--full-warning]
        will prepare a user directory at the specified path

  o NA62AnalysisBuilder.py examples
        will build the libraries for examples and import the configuration 
        files in user directory[UserDir]
  
The prepare and build commands have some flags that can be used to enable some features:
  o -d/--debug : activate the debug flag -g in the compiler for producing debugging information
  o --no-c++11 : disable c++11 support in the framework. C++11 support is automatically enabled for compilers supporting the feature.
  o --full-warning : activate all the warning flags during compilation
  o -j/--jobs : number of processors to use while building (make -j option)

To get help from the script: 
    NA62AnalysisBuilder.py -h 
Or for help on a specific command: 
    NA62AnalysisBuilder.py commandName -h
     

If you want to write a new analyzer on MC simulation or reconstruction coming from NA62MC or NA62Analysis:
  o Go in your user directory[UserDir] and setup the environment
      source scripts/env.[c]sh

  o Create a new analyzer with
      NA62AnalysisBuilder.py new analyzer-Name

  o Write your analyzer. The header and source files are
      PathToUserDir/Analyzer/include/analyzer-Name.hh
      PathToUserDir/Analyzer/src/analyzer-Name.cc
    In [UserDir] there is also a preformatted runtime configuration file

If you want to run the program with a set of analyzers
  o Go in you user directory (PathToUserDir) and setup the environment
      source scripts/env.[c]sh

  o Create a config file containing the following line:
      exec = name-Of-Executable-To-Generate
      analyzers = List-Of-Analyzers-You-Want-To-Run-Separated-By-White-Spaces
      libs = List-Of-Additional-Libraries-To-Link-With
      libsdirs = List-Of-Additional-Directories-To-Search-For-Libraries
      incdirs = List-Of-Additional-Directories-To-Search-For-Include-Files
      
      If one of the analyzers specified in the list does not exist, a prompt will propose you
      to create it. For this reason, the syntax 
      	AnalyzerName(InputType TreeName, ...)
      is valid in the config file as well.

  o Compile in the user directory with
      NA62AnalysisBuilder.py build configFileName

  o Run with
      ./yourExecutableName (-i path | -l/--list path) [options]

      Allowed options:
       -h/--help            : Display this help
       -v [level]           : Verbosity level.
                              Possible values: kNo, kUser, kNormal, kDebug or 0,1,2,3;
                              Default=kNo; If level not specified: kNormal
       -g                   : Graphical mode. Starts a ROOT application for display.
                              Do not automatically exit at the end of the processing, Ctrl-C to exit.
       -n/--nevt int        : Maximum number of events to process.
       -o/--output path     : Path to output ROOT file. Will be overwritten if already exists.
       -p/--params string   : List of parameters to pass to analyzers.
                              The format of the string is 
                              "analyzerName:param=val;param=val&analyzerName:param=val&..."
       --histo              : Read histograms only and bypass TTree reading.
       --start int          : Index of the first event to process.
                              Event index starts at 0.
       --config path        : Path to a configuration file containing analyzers parameters.
       --reffile path       : Path to a ROOT file containing reference plots.
       --ignore             : Ignore non-existing trees and continue processing.
       --logtofile path     : Write the log output to the specified file instead of standard output.

     Mutually exclusive options groups:
      Group1:
        -i path             : Path to an input ROOT file.
      Group2:
        -l/--list path      : Path to a text file containing a list of paths to input ROOT files.
                              One file per line.
        -B/--nfiles int     : Maximum number of files to process from the list.

The runtime configuration file will advantageously replace long list of command line parameters 
(with -p). The format of the configuration file is the following:
    [[analyzer-Name]]
    Parameter1 = value1
    Parameter2 = value2
    
    [[analyzer-Name2]]
    ...
    ...
    ...

The following parameters exist by default for all analyzers:
  o Verbose (default=kNo, possible kNo, kUser, kNormal, kDebug)
  o AutoUpdate (takes a list of plots names. They will be drawn on screen during processing
  	and refreshed at regular interval)
  o UpdateInterval (default=10, refresh interval for AutoUpdate plots in number of events)

Settings file
-------------

A settings file is used to customize the behavior of NA62Analysis. The file can be found in your user directory [UserDir]
under the name .settingsna62. The file currently contains a global section affecting the whole software, with the 
following options:
  o UseColors: If set to true NA62Analysis can use colors in the standard and error output.
  o ProcessOutputNewLine: NA62Analysis regularly outputs the number of events already read. If set to true this output
    is printed on a new line every time. If set to false, a carriage return is used instead of a new line and the line
    is replaced.
  o SkippedName: Name for the output file containing the list of skipped input files. The file is named SkippedName.skipped


Troubleshooting
---------------

  o If you are experiencing strange problems with compilation and linking, first try a
      NA62AnalysisBuilder.py cleanAll
    before trying to recompile the framework. Problems sometimes happens after changing 
    version of ROOT, NA62MC, ... or when some framework libraries were not recompiled 
    automatically after modifications in the code.