root for Debian
---------------

Abstract:
=========
This document outlines the contents, design, and considerations that
went into making the ROOT packages for Debian and Redhat.  First part
is of general interest, while the second part is for people who'd like
to know the full story (needed if you want to build the packages your
self or do fixes).

Introduction:
=============
These are the Debian GNU/Linux and Redhat packages of ROOT, the
analysis frame work written in C++.

Meta package: 

* root-system           This will install the core of ROOT, plus some
                        of the most useful packages.  Note, this works
                        best on Debian as Debian has a higher level of
                        granularity than Red Hat when it comes to
                        dependencies. 

The core packages are:

* libroot               Basic ROOT libraries
* libroot-dev           The header files for the ROOT libraries
* root-system-common	Common files for ROOT
* root-system-bin       The interactive interface and utilities
* root-system-doc       Examples and tutorials

A few `server' packages are available 

* root-system-rootd     Remote fileserver 
* root-system-proofd    PROOF environment
* root-system-xrootd	Extendend ROOT Remote File server

A few `extension' packages 

* libroot-clarens       Grid-Enabled Web Services
* libroot-clarens-dev   Development files for libroot-clarens
* libroot-mlp	        Multi-Layer-Perceptron Neural Net (**)
* libroot-mlp-dev       Development files for libroot-mlp
* libroot-minuit        Fitting algorithm for ROOT (**)
* libroot-minuit-dev    Development files for libroot-minuit
* libroot-python        Python interface to ROOT
* libroot-python-dev    Development files for libroot-python
* libroot-ruby          Ruby interface to ROOT
* libroot-ruby-dev      Development files for libroot-ruby

Further more, there's a number of plugin packages.  Which exactly are
built depends on your system. 

* root-plugin-alien     AliEN interface (*,***)
* root-plugin-asimage   AfterStep image manipulation plugin
* root-plugin-castor    Interface to CASTOR managed tape robots (***)
* root-plugin-chirp     Access files via the Chirp protocol (***)
* root-plugin-dcache    Access to files data via a dCache server (***)
* root-plugin-fumuli    Alternative fitting algorithm for ROOT (**)
* root-plugin-globus    Authentication and authorisation against Globus(*,***)
* root-plugin-gl        OpenGL support using Mesa (or XFree)
* root-plugin-hbook     Conversion tools from HBOOK to ROOT files
* root-plugin-ldap      Interface to LDAP 
* root-plugin-mysql     MySQL client for ROOT
* root-plugin-netx      Client for XRootd server (**)
* root-plugin-oracle    Oracle client for ROOT (***)
* root-plugin-peac      Proof Enabled Analysis Center plugin
* root-plugin-pqsql     PostGreSQL client for ROOT
* root-plugin-proof     PROOF Client (**)
* root-plugin-pythia5   Wrapper for Pythia event generator (version 5) (***)
* root-plugin-pythia6   Wrapper for Pythia event generator (version 6) (***)
* root-plugin-qt        ROOT GUIs using QT
* root-plugin-quadp     Quadratic Programming plugin 
* root-plugin-maxdb     MaxDB/SapDB client for ROOT
* root-plugin-venus     Wrapper for Venus event generator  (***)
* root-plugin-xml       XML plugin for ROOT

(*)   Note that these packages have not been tested. 
(**)  These packages can always be build, as they do not depend on
      external packages.   As such, they can be considered part of an 
      extended `base' system. 
(***) These packages are not distributed by Debian for license, and 
      availability reasons. 

The packages are structured like this, to allow maximum modularity and
flexibility for the user.

The `root-plugin-<plugin>' contain proper plug-ins, and should not
be linked to by the developer.  For example `root-plugin-minuit'
contain `libMinuit'.  This library is automatically loaded when one
starts fitting data if the proper `TEnv' value is set in `.rootrc'.
However, `libFumili' from `root-plugin-fumili' could also be loaded if
so specified in `.rootrc'. The point here is, that the developer
should not use `TMinuit' or similar directly in their code.  Instead
they should use the proper virtual interface (e.g., `TVirtualFitter'),
and leave the decision of which concrete implementation to use to the
user.   

The `libroot-<extension>' packages contain proper extensions, which
the developer can link to explicitly, or load dynamically via ROOT.
Hence, these packages comes in pairs - a run-time shared library
package, and a development package. 

The latest Debian GNU/Linux packages should be available from [1], and
a back catalogue as well as latest build should be available from the
ROOT web-site [2].

[1] deb http://mirror.phy.bnl.gov/debian-root unstable main contrib
[2] http://root.cern.ch

Original Sources:
=================
The packaging scripts for both Debian GNU/Linux and Redhat - those
normally found in "<source dir>/debian" or as a separate "spec" file -
are a part of the of the ROOT source tree, hence no patches has been
applied to build the packages.  In fact, the ROOT team maintainer and
the maintainers of the packages has worked closely together on making
ROOT packages for Debian GNU/Linux and Redhat as easy as possible.
This cooperate work has made many improvements to both the packages,
as well as for the ROOT system itself.

The sources for ROOT are available via anonymous CVS from

    Repository:   :pserver:cvs@root.cern.ch:/user/cvs
    Password:     cvs

For more availability of ROOT, including other OSs then Linux - IBM
AIX, HP Unix, Digital Unix on Alpha, FreeBSD, Windows, and many others
- please refer to [1].

[1] http://root.cern.ch

Parallel Redhat and Debian GNU/Linux Packages:
==============================================
These packages was developed in parallel on both Debian GNU/Linux and
Redhat, so that a coherent outlook could be maintained over the two
Linux distributions.

Documentation, Mailing list and Questions:
==========================================
No documentation package is made.  This is because the documentation
is vast and not particularly manageable in a package.  Instead, please
refer to the ROOT web-site [1].  There you'll find reference pages for
every class in ROOT [2], as well as a printable Users guide
[3]. There's a mailing list for ROOT issues at [4], and an archive is
available via the main ROOT web page [5].

Do not mail directly to the maintainer with questions on ROOT.
Instead mail questions to [5] - The maintainer is on that list and
will happily answer questions in that forum.

[1] http://root.cern.ch
[2] http://root.cern.ch/root/htmldoc/ClassIndex.html
[3] http://root.cern.ch/root/UsersGuide.html
[4] mailto:roottalk@cern.ch
[5] http://root.cern.ch/root/AboutRootTalk.html


Pure CINT and ROOT's CINT:
==========================
To facilitate a parallel installation of a Pure CINT on a Debian
GNU/Linux system, the `root-system-bin' package exploits the
"alternatives" feature of dpkg.  Since most ROOT users never use the
Pure CINT programs "cint" and "makecint" is is reasonably safe to have
a Pure CINT installation next to ROOT.  A Debian GNU/Linux package of
CINT is being maintained by Richard B. Kreckel.

The pure CINT packages have not been in Debian for some time now.
However, the alternatives are still used, as the pure CINT packages
might get resurrected at some point in the future. 

I (Christian Holm) know of no such system on Redhat so no attempt to
provide a similar mechanism has been tried.  If anyone should know
about such a system, please let us know.

Building the Package:
=====================
The basic process of building the RPM and Debian packages is given in
README/INSTALL; here we'll go into the details.

Basic configuration:
--------------------
The source tree is configured with

  ./configure \
		--prefix=<prefix>				\
		--etcdir=<etcdir> 				\
		--enable-table					\
		--enable-shared 				\
		--enable-soversion				\
		--disable-afs 					\
		--disable-srp 					\
		--with-sys-iconpath=/usr/share/pixmaps		\
		--with-ttf-fontdir=/usr/share/fonts/truetype

* 3rd party libraries:
  The packages will use third-party shared libraries when ever
  possible.  This is noted in the below items.

* TrueType Font Support:
  Note, that if you want to have system wide TrueType Font support,
  you can install the fonts into the directory

    @prefix@/share/fonts/truetype

  It's possible for individual users to override this path, using the
  lines

    # Path where to look for TrueType fonts
    Unix.*.Root.UseTTFonts:     true
    Unix.*.Root.TTFontPath:     <ttffontdir>

  in thier "~/.rootrc", where <ttffontdir> is the path to the TrueType
  Fonts.

  The currently supported TrueType Fonts in ROOT are:

      #   Descriptive name            file
    -----------------------------------------------
      1 : times-medium-i-normal       timesi.ttf
      2 : times-bold-r-normal         timesbd.ttf
      3 : times-bold-i-normal         timesi.ttf
      4 : helvetica-medium-r-normal   arial.ttf
      5 : helvetica-medium-o-normal   ariali.ttf
      6 : helvetica-bold-r-normal     arialbd.ttf
      7 : helvetica-bold-o-normal     arialbi.ttf
      8 : courier-medium-r-normal     cour.ttf
      9 : courier-medium-o-normal     couri.ttf
     10 : courier-bold-r-normal       courbd.ttf
     11 : courier-bold-o-normal       courbi.ttf
     12 : symbol-medium-r-normal      symbol.ttf
     13 : times-medium-r-normal       times.ttf
     14 :                             wingding.ttf

  Please note, that these fonts are copyright of Microsoft, under
  a restrictive license.  In a nut shell, this license prohibits
  the maintainer from including them in the packages, since it will
  violate other license issues, and make ROOT less close to being
  OpenSource.  

  The ROOT sources has been patched to allow using FreeFont files
  instead of the MS Core fonts.  The package `ttf-root-installer' (in
  contrib) downloads the MS Core fonts from the ROOT web-site in case
  these are wanted.

* Version number in soname:
  Debian GNU/Linux (indirectly) mandates that any shared library shall
  have the major version number the soname, so that the packaging
  system ("dpkg"/"apt") may resolve conflicts, dependencies, etc.
  Hence, the ROOT libraries are build with the major version number in
  the`soname.  Redhat does not have such a strict policy, but it is
  generally a good idea to set version numbers in sonames (the shared
  library's internal identifier) so that the runtime environment may
  resolve conflicts etc. cleanly.


3rd Party libraries:
====================
Below is listed the 3rd party interfaces possible which are not
normally build on a Debian or Red Hat system.  Most have rather
restrictive licenses which prohibits redistribution of modified
sources, thereby rendering them non-free (in the meaning of
`free-speech'). 
 
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://castor.web.cern.ch/castor/

The full sources may contain the `debian' directory. 

Chirp File access:
------------------
This allows transparent access to files via Condor file access
protocol chirp.    It requires libraries from 

  http://www.cs.wisc.edu/condor/chirp

There are no known Debian packages of this software. 

DCache file access:
-------------------
Provides transparent access to files stored in a DCache file archive.
This need client libraries from 

  $ cvs -d :pserver:cvs@cvs.dcache.org:/cvs login
  Logging in to :pserver:cvs@cvs.dcache.org:2401/cvs
  CVS password: (password is 'cvs')
  $ cvs -d :pserver:cvs@cvs.dcache.org:/cvs co .

Note, there are no known packages of his software. 

Oracle database access:
-----------------------
Provides transparent access to Oracle data bases.  This need the
client interface library from 

  http://www.oracle.com/

There are RPMs of this client (you need oracle-instantclient-devel and
oracle-instantclient-core) and these can be used on Debian via
`alien'. 

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

Note, that one Debian you can use Kevin McCarty's
`montecarlo-installer-data' package to make the packages `pythia6',
`pythia6-dev', `pythia5', and `pythia5-dev'. 

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/

There's no official or semi official package of this code, but the
sources (from the above web-site) can easily be turned into a binary
package.   However, this redistribution is painfully in conflict with
the license given by the upstream author Klaus Werner: 

  Copyright K. Werner, Nantes 1995.

  Copyright reserved in all countries of the world.  The program may
  not be reproduced by any method without prior consent of the author 
  (K. Werner).

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'
sub-directory.   There are no known packages of this code. 

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 fonctionallity 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 directory. 

There exists experimental packages of this software. 


Adding a new package:
=====================
From time to time, ROOT accepts new `modules' or plugins, in the ROOT
source tree.   Here's a description of how to make a new package that 
contains that new module.   Let's assume that the new plugin is called
`foo', and that the source code is in `foo/{src,inc}'.  

1: Open `configure' and add the line 

     test "x$enable_foo"  = "xyes"   && pkglist="$pkglist root-plugin-foo"
     
   Near where it says `Debian or Red Hat Package list'

2: Create the file `root-plugin-foo.control' in
   `build/package/common/'.  This file is really a Debian GNU/Linux
   control file snippet (the RPM stuff get information from there), so
   anything that's valid in a Debian control file is valid there too.  
   The file should look something like 

     Package: root-plugin-foo
     Architecture: any
     Depends: ${shlibs:Depends}, ${misc:Depends}
     Enhances: libroot
     Description: Foo plugin for ROOT
      This package contains the Foo plug-in for ROOT. This package
      provide a plug-in to ... in ROOT
      .
      ROOT web-site: http://root.cern.ch
      Foo web-site: http://www.foo.org 

   Please note, that the file _must_ end in 2 (two) newlines.  Also,
   blank lines (except for the final two lines) are not allowed.  In
   stead put a `.' in 2nd column, as shown above. 

3: If the plugin requires some development files (libraries and
   headers) to be available on the system, find out which Debian and
   RedHat packages these are in.  Suppose you need the library
   `libfoo' and the header `foo.h', then try 

     dpkg -S libfoo.so foo.h                       # Debian
     rpm -qf /usr/lib/libfoo.so /usr/include/foo.h # RedHat

  Then edit the file `build/package/lib/makebuilddepend.sh'
  accordingly.  Suppose libfoo.so and foo.h is in the Debian package
  libfoo-dev and RedHat package foo-devel, add the two lines 

    *foo)    echo -n ", foo-devel" ;; 
    
  and 

    *foo)    echo -n ", libfoo-dev" ;; 

   at the appropriate places in that shell script. 

4: That should be it for most packages.   However, if your plugin
   needs some extra files that is not listed in the variables 
   `ALLLIBS', `ALLHDRS', or `ALLEXECS' in the `foo/Module.mk' file,
   then you need to add the file
   `build/package/common/root-plugin-foo.install.in'.   Suppose the
   package needs the files `/etc/root/system.foorc' and
   `/usr/share/root/foo/Init.C', then the file should contain lines
   like 

     @sysconfdir@/root/system.foorc 
     @prefix@/share/root/foo/Init.C 

   Also, if your plugin needs special stuff to be done before and/or
   after installation and/or removal, you need to add the appropriate
   shell script snippets in one or more of the following pairs of
   files in `build/package/'

     debian/root-plugin-foo.preinst.in  and rpm/root-plugin-foo.pre
     debian/root-plugin-foo.postinst.in and rpm/root-plugin-foo.post
     debian/root-plugin-foo.prerm.in    and rpm/root-plugin-foo.preun
     debian/root-plugin-foo.postrm.in   and rpm/root-plugin-foo.postun

  Please look in the existing files for more information. 


Package Bugs, etc.:
===================
If you didn't get the packages from the official repositories, please
do not use the regular Debian bug tracking system.  Instead, please
send bug reports to the Debian GNU/Linux package maintainer
<cholm@nbi.dk> and possibly also the ROOT mailing list
<roottalk@cern.ch>. 

Experimental Packages:
======================
Packages downloaded from the 'experimental' distribution are snapshots
of the development versions of ROOT.  As such, there's no guaranty
that the Application Binary Interface (ABI) or Application Programming
Interface (API) is stable or backward compatible.   Therefor, use
these packages at your own risk.  You may have to recompile code that
uses ROOT even if the major and minor version numbers have not
changed.  

Development snapshots are numbered like <N>.<2 * M + 1>.<PP> (that is,
have odd minor version) while production releases are numbered like
<N>.<2 * M>.00. 

Thanks:
=======

* Many MANY thanks to the ROOT team - Rene Brun <Rene.Brun@cern.ch>
  and Fons Rademakers <Fons.Rademakers@cern.ch> - for a great piece
  of software.  Especially thanks to Fons Rademakers for putting up
  with a lot of emails from me (Christian Holm) during the initial
  development.  

* Many thanks to Masaharu Goto <gotom@hanno.jp> for CINT, inspiring
  correspondence, advice, and patience (loads of emails from me).

* Also many thanks to all the contributors of ROOT, for making it
  great.

* Anders Waananen <waananen@nbi.dk> for putting the initial Red Hat
  packages together, many suggestions and inspirrational talks.

* Thanks to Richard B. Kreckel the CINT Debian GNU/Linux package
  maintainer, for inspirring correspondence, advice, and great
  cooperation.

* Boris (?) <boris@mogwitz.eu> for porting to mips

* James Ferrando <ferrando@mail.desy.de> for the i386
  `sarge' (stable) builds. 

* Dirk Van Hertem <dirk.vanhertem@ieee.org> for porting to hppa

* John Kehayias <John.Kehayias@bnl.gov> for the amd64 `sid' (unstable)
   builds. 

* Frederic Lehobey <Frederic.Lehobey@free.fr> for linux-sparc64,
  linux-powerpc, and gnu-kfreebsd-i386 testing and builds. 

* Frank Lichtenheld <djpig@debian.org> for help on porting to sparc.

* Kevin McCarty <kmccarty@Princeton.edu> for his many suggestions,
  testing, and sponsorship, as well as some amd64 builds. 

* Daniele Nicolodi <daniele@grinta.net> for powerpc testing and builds
  on Ubuntu.

* Charles Plessy <charles-debian-nospam@plessy.org> for powerpc64
  testing and builds. 

* Thiemo Seufer <ths@networkno.de> for help on MIPS - his huge 
  expertise on the architecture was quite instructive. 

* Brett Viren <bv@bnl.gov> for hosting the repository as well as doing
  alpha and beta  testing of the Debian GNU/Linux packages.

* Ricardo Yanez <Ricardo.Yanez@calel.org> for suggestions, testing and
  stable i386 builds. 


 -- Christian Holm Christensen <cholm@nbi.dk>, Mon, 21 Feb 2005 16:28:37 +0100

Local Variables:
  mode: text
End: 

