INSTALL

Installation of ROOT from source
================================

Contents:
=========

   1.    Getting the source
   2.    Getting ready to build
   3.    Choosing the installation method
   3.1.  Environment driven build
   3.2.  Fixed locations build
   4.    Installation Location
   5.    Makefile targets
   6.    Installing optional add-on libraries
   7.    Information on third party software
   7.1.  Posix Thread usage
   7.2.  OpenGL library
   7.3.  SHIFT managed tape I/O
   7.4.  ZEBRA file conversion tools
   7.5.  MySQL client
   7.6.  PostGreSQL Client
   7.7.  SapDB Client
   7.8.  Pythia Event Generators
   7.9.  Venus Event Generators
   7.10. Secure Remote Password (SRP) Authentication
   7.11. AFS Authentication
   7.12. Kerberos Authentication
   7.13. Globus Authentication
   7.14. SSH Authentication

1. Getting the source:
======================

To install ROOT from source you first have to get the tar file
containing the source. This tar file can be found in the usual
ROOT download area (ftp://root.cern.ch/root). The files are named
root-<version>.source.tar.gz.

Here's a short summary:

1) Get access to the FTP area (substitute any FTP client and appropriate
   email address below):

     prompt% ftp root.cern.ch
     User: anonymous
     Password: <your-email-address>

2) Go to the directory, and prepare for binary transfer of files:

     ftp> cd /root
     ftp> bin

3) Get the sources tar-ball (substitute the appropriate version
   number), and exit FTP client:

     ftp> get root-<version>.source.tar.gz
     ftp> bye

4) Unpack the distribution:

     prompt% gzip -dc root-<version>.source.tar.gz | tar -xf -

An alternative approach is to use our public GIT repository to get
the latest version.

     git clone http://root.cern.ch/git/root.git

The release specific tag can be obtained using for example:

     cd root
     git checkout -b v6-04-14 v6-04-14



2. Getting ready to build:
==========================

Building ROOT requires to have CMake in your system. This can be
downloaded from http://cmake.org
You may want to compile features into ROOT, which depends on third
party libraries. Make sure you meet all demands for additional
features before trying to enable them (see below).

The prerequisites neded for the different platforms are documented at 

  https://root.cern.ch/build-prerequisites


3. Choosing the installation method:
====================================

There are two main methods of installing ROOT from source.
  - 'location independent' is advised for a personal installation of ROOT
  - 'fix location' for a system wide installation. 
  
Both require to set the CMAKE_INSTALL_PREFIX variable at configuration time. 
The 'fix location' requires in addition to set the 'gnuinstall' option at configuration. 


3.1. Environment driven build:
------------------------------

You want to install in a generic directory, depending on environment
variables ROOTSYS, LD_LIBRARY_PATH, and PATH.

   1) Get the sources of the latest ROOT (see above)

   2) Type the build commands:
        mkdir <builddir>
        cd <builddir>
        cmake ../root
        cmake --build .  [ or simply "make -j<N>" on Unix systems ] 

   3) Add bin/ to PATH and lib/ to LD_LIBRARY_PATH. For the sh shell family do:
        . bin/thisroot.sh

      and for the csh shell family do:
        source bin/thisroot.csh

   4) try running root:
        root

3.2. Fixed locations build:
---------------------------

You want to install ROOT in a fixed location, not depending on
ROOTSYS. Typically you want to do this when installing in a location
like `/usr/local/bin' or even `/usr/bin'. This allows you, and all
others on your system, to run ROOT without having to setup ROOTSYS and
special PATH and LD_LIBRARY_PATH variables.

It's _strongly_ recommended to enable version numbers in sonames (if
possible) using this method (see 'soversion' option below). Also,
using the 'rpath' option to "cmake" you can set the load
path to the ROOT libraries on the applications. However, this is not
recommended if you have some other way (like /etc/ld.so.conf) of
making the dynamic loader aware of where you installed the ROOT
libraries.

   1) Get the sources of latest ROOT (see above)

   2) Now type the build commands:
        mkdir <builddir>
        cd <builddir>
        cmake ../root -DCMAKE_INSTALL_PREFIX=<prefix> -Dgnuinstall=ON 
        cmake --build .                  [ or simply "make -j<N>" on Unix systems ]
        cmake --build . --target install [ or simply "make install" on Unix systems ]
         
   3) Update the ldconfig cache by doing:
        ldconfig

   4) try running root:
        root

4. Installation Location:
=========================

By default, the system will be installed depending on the ROOTSYS
environment variable. In that case the whole package will live under
the directory ROOTSYS points to.

Using the fixed location mode (section 3.2), the default 'CMAKE_INSTALL_PREFIX'
path is '/usr/local', which will result in the ROOT files to be
installed in '/usr/local/bin', `/usr/local/lib', etc. You can specify
an installation prefix other than `/usr/local' by giving `cmake'
the option `-DCMAKE_INSTALL_PREFIX=PATH'. For more detailed location specifications
see http://root.cern.ch/building-root#variables.

Here's the complete list:

* prefix (/usr/local)
  Installation prefix. This will prefix any installation directory not
  explicitly specified.
* bindir (<prefix>/bin)
  This is where the ROOT applications (root, cint, rootcint, etc.)
  will be installed.
* libdir (<prefix>/lib/root)
  Library installation directory. All the class libraries of ROOT will
  be installed into this directory. You should make your dynamic
  linker aware of this directory. On Linux - and some other Un*ces -
  this directory can be added to /etc/ld.so.conf and ldconfig should
  be run afterward (you need to be root - the user - to do
  this). Please note, that this directory should probably not be
  something like /usr/lib or /usr/local/lib, since you'll most likely
  get a name clash with ROOT libraries and other libraries
  (e.g. libMatrix.so); rather use something like /usr/local/lib/root
* incdir (<prefix>/include/root)
  Header installation directory. All the header (declaration) files
  for the ROOT classes will be installed into this directory. This
  should be parallel to libdir, for consistency.
* etcdir (<prefix>/etc/root)
  Configuration files installation directory. The system-wide
  system.rootrc and root.mimes will be installed into this directory.
* mandir (<prefix>/share/man/man1)
  Installation directory for the ROOT man(1) pages. This should be
  somewhere searched by man(1). On most Un*x you can set the search
  path for man(1) via environment variable MANPATH. On some systems, a
  special configuration file /etc/manpath.config exist and should be
  used. See also man(1) - type man man in the prompt - on your
  system.
* datadir (<prefix>/share/root)
  Top-level data installation directory. Under this directory, various
  data files needed by ROOT will be installed, either in
  subdirectories, or directly.
* proofdir (<datadir>/proof)
  PROOF utilities directory. Various PROOF utility scripts as well as
  example configurations are installed into this directory.
* macrodir (<datadir>/macros)
  Macro installation directory. Macros - properly called scripts -
  provided by the ROOT system are installed into this directory. ROOT
  - the application -  will always search this directory for scripts.
* cintincdir (<datadir>/cint)
  CINT data directory. In this directory, the CINT runtime headers
  will be installed, both the standard headers, as well as
  pre-processed once.
* iconpath (<datadir>/icons)
  Icon installation directory. The icons used by the TBrowser and other
  classes will be installed into this directory. The user can specify
  additional directories in using the "--with-sysicondir" option.
* srcdir (<datadir>/src)
  Sources installation directory. Currently not used!
* docdir (<prefix>/doc/root)
  Documentation, like the LICENCE, README, etc. files will be
  installed into this directory.
* testdir (<docdir>/test)
  The test applications and libraries will be installed here.
* tutdir (<docdir>/tutorial)
  All the tutorials will be installed in this directory.


5. Makefile targets:
====================

The availble Makefile top level targets are shown by doing 

    make help


6. Installing optional add-on libraries:
========================================

You can also specify additional features and external linking using
command line options -D<option>=ON in the cmake command.

See the full list of available options described at http://root.cern.ch/building-root#options


7. Information on third party software:
=======================================

The optional add-ons are not necessary for the proper functioning of
ROOT but we advice you to at least get the True Type fonts since they
hugely increase the appearance of text on the screen.


7.1. Posix Thread usage:
------------------------
To build the library providing thread support you need to have the
library libpthread.{a,so} and header files installed. This is usually
the case for any Un*x OS. For architecture "linux" thread support
will always be build.


7.2. OpenGL library:
--------------------
On how to get an open source version of OpenGL see:

   http://www.mesa3d.org

For prebuilt versions see:

   ftp://root.cern.ch/root/opengl/

Most Linux distributions come with a Mesa package, providing the
needed headers and libraries. Also, the OpenGL libraries are already
in XFree86 version 4 or above.


7.3. SHIFT managed tape I/O:
----------------------------
To build the library providing CERN RFIO (remote I/O) support you need
to get the "libshift.a" library from CERN. You can get pre-build
libraries from

  http://root.cern.ch/root/shift

or you can download the full source from

  http://savannah.cern.ch/files/?group=castor

7.4. ZEBRA file conversion tools:
---------------------------------
To build the HBOOK and Geant3 conversion programs `h2root' and
`g2root' you need the CERNLIB components "libpacklib.{a,so}" and
"libkernlib.{a,so}" from CERN. You can get it from

  ftp://asisftp.cern.ch/cernlib


7.5. MySQL client:
------------------
To build the MySQL interface library you need to install MySQL first. See:

   http://www.mysql.com/


7.6. PostGreSQL Client:
-----------------------
To build the PostGreSQL interface you need to install PostGreSQL
first. See

   http://www.postgresql.org


7.7.  SapDB Client:
-------------------
To build the SapDB interface you need to install the SapDB calling
interface first, which can be found in the rpm sapdb-callif-xxxx. See

   http://www.sapdb.org


7.8. Pythia Event Generators:
-----------------------------
To build the event generator interfaces for Pythia and Pythia6, you
first have to get the pythia libraries. You can get pre-build
libraries from:

   ftp://root.cern.ch/root/pythia/

or you can download the source from the same directory. The original
sources can be found via Lunds FTP server.

More information is available from:

   http://www.thep.lu.se/~torbjorn/Pythia.html


7.9. Venus Event Generators:
----------------------------
To build the event generator interface for Venus, you need to have the
Venus libraries.  The sources can be downloaded from

    ftp://root.cern.ch/root/venus/

7.10. Secure Remote Password (SRP) Authentication:
--------------------------------------------------
To build the strong authentication module used by rootd and proofd,
you first have to install the SRP (Secure Remote Password)
system. See:

   http://srp.stanford.edu/

Please note, that the library "libsrp-dev" as distributed by Standford
is not enough to build the two utility program in the srputil
directory of the ROOT source tree.


7.11. AFS Authentication:
-------------------------
To build rootd and proofd with support for AFS authentication, you
first have to install AFS client libraries system. There are a few AFS
distributions available.

* OpenAFS
  IBMs OpenSource AFS distribution - see

    http://www.openafs.org

* Transarc AFS
  IBMs commercial AFS ditribution - see

    http://www.transarc.ibm.com/Support/afs


7.12. Kerberos Authentication:
------------------------------
To build the Kerberos authentication module used by rootd and proofd,
you first have to install Kerberos V on your machine. See:

   http://web.mit.edu/kerberos/www/

for details and downloads.
If the installation directory is different from the standard ones
(typically /usr/kerberos) the --with-krb5=<krb5_dir> flag must be
used to tell configure where to look for Kerberos. Alternatrively
the --with-krb5-incdir and --with-krb5-libdir can be specified
individually.


7.13. Globus Authentication:
----------------------------
To build the Globus authentication module used by rootd and proofd,
you first have to make sure that the Globus Tool Kit is installed
on the machine. See:

   http://www.globus.org/

for details and downloads.
Globus Tool Kit is available only for a subset of Unix platforms.
The variable GLOBUS_LOCATION should be defined as the directory
containing Globus lib, include and bin. For compilation purposes
you can pass this directory to the configure script with the option
--with-globus-dir=<globus_dir>. An experimental path is available
for versions 2.2.3 and 2.2.4 of the Globus Tool Kit to fix a small
bug preventing full functionallity of the root implementation; this
is activated by setting --with-globus-patch-dir=<globus_src_dir>
where <globus_src_dir> is the globus tool kit source,

7.14. SSH Authentication:
-------------------------
There is no need to build special modules for SSH authentication.