In order to package the CERN libraries in an acceptable way, it was necessary
to make a large number of changes to the installation.  Most of these changes
should be transparent to the user, but they are nevertheless noted here.

If you are compiling code and linking it against CERN libraries on a 64-bit
platform, please see also the file README.64-bit in this directory.

For more information, you may also wish to read the CERNLIB on Debian
web pages at http://people.debian.org/~kmccarty/cernlib/ .

CONTENTS

0) Turning on syntax highlighting in Vim
1) Package layout
2) Using shared libraries
3) Meeting the Filesystem Hierarchy Standard
4) Mixing Debian and CERN versions of CERNLIB
5) Removal of non-free code


0) Turning on syntax highlighting in Vim

The cernlib-base package ships syntax highlighting files for KUIPC and
PAW macro (kumacs) files, but it is not turned on by default.  For it to
be made usable, the "vim-addon-manager" package should be installed.
To turn on the syntax highlighting as a normal user, run

	vim-addons install cernlib-base

To turn it on by default for ALL users, as root run

	vim-addons -w install cernlib-base


1) Package layout

To install parts of CERNLIB, you may use one or more of these metapackages:

cernlib-core       - CERNLIB main programs and libraries
cernlib-core-dev   - CERNLIB development headers, tools and static libraries
cernlib-montecarlo - CERNLIB Monte Carlo libraries (both shared and static)
cernlib            - All of the above plus Geant 3.21
cernlib-extras     - A few extra programs not of interest to most people

or for finer-grained installation, see the list below of CERNLIB systems and
the corresponding Debian packages in which they are included.

SYSTEM or program	Debian Package
-----------------	--------------
COMIS			libpawlib2-gfortran, libpawlib2-dev
CSPACK			libpacklib1-gfortran, libpacklib1-dev
 |_ pawserv, zserv	pawserv
 \_ zftp		zftp
DZDOC			libgraflib1-gfortran, libgraflib1-dev
 \_ dzeX11, dzedit	dzedit
EPIO			libpacklib1-gfortran, libpacklib1-dev
FATMEN			libpacklib1-gfortran, libpacklib1-dev
 \_ fatmen, fatsrv, ...	[Not currently packaged]
FFREAD			libpacklib1-gfortran, libpacklib1-dev
GEANT			libgeant321-2-gfortran, libgeant321-2-dev,
                          geant321, geant321-data, geant321-doc
HBOOK			libpacklib1-gfortran, libpacklib1-dev
HEPDB			libpacklib1-gfortran, libpacklib1-dev
 \_ hepdb, cdbackup, ...[Not currently packaged]
HIGZ			libgrafx11-1-gfortran, libgrafx11-1-dev
HPLOT			libgraflib1-gfortran, libgraflib1-dev
KAPACK			libpacklib1-gfortran, libpacklib1-dev
KERNLIB			libkernlib1-gfortran, libkernlib1-dev
KUIP			libpacklib1-gfortran, libpacklib1-dev,
 |                        libpacklib-lesstif1-gfortran [*],
 |			  libpacklib-lesstif1-dev [*]
 |_ kuesvr		libpacklib1-gfortran, libpacklib1-dev
 |_ kuipc		kuipc
 \_ kxterm		kxterm
MATHLIB			libmathlib2-gfortran, libmathlib2-dev
MINUIT			libpacklib1-gfortran, libpacklib1-dev
             /		libcojets2-gfortran, libeurodec1-gfortran,
	    |		  libherwig59-2-gfortran, libisajet758-3-gfortran,
Monte Carlo |             libpdflib804-2-gfortran, libphotos202-1-gfortran,
	    |		  libphtools2-gfortran, montecarlo-data
             \            (and -dev packages)
NYPATCHY		nypatchy
PAW			libpawlib2-gfortran, libpawlib2-dev,
 |			  libpawlib-lesstif3-gfortran [**],
 |                        libpawlib-lesstif3-dev [**]
 \_ PAW, Paw++		paw, paw++, paw-common, paw-demos
SIGMA			libpawlib2-gfortran, libpawlib2-dev
ZBOOK			libpacklib1-gfortran, libpacklib1-dev
ZEBRA			libpacklib1-gfortran, libpacklib1-dev

[*] libpacklib-lesstif1* contains the library libpacklib-lesstif, which is the
graphical interface component of packlib's KUIP subsystem.  This has been split
out into a separate library for Debian so that the packlib packages need not
depend on X and Lesstif libraries.

[**] libpawlib-lesstif3* contains portions of Pawlib that depend upon the
Lesstif library.  The remainder of Pawlib is found in libpawlib2*, whose GUI
depends only on the basic X11 libraries.

Static libraries and header files for development are available from the
CERNLIB development packages: For each lib*-gfortran package there exists a
corresponding lib*-dev package, e.g., libpacklib1-dev.  You will need to
install the appropriate development packages in order to compile programs
that link against CERNLIB libraries.

The "-gfortran" suffix on the runtime library packages indicates that they are
now compiled with gfortran.  You will need to build your own code with gfortran
in order to link it against these packages.

See also the README.Debian files for specific packages.


2) Using shared libraries

The default installation of CERNLIB creates only static libraries on Linux,
resulting in unnecessary code bloat and redundancy.  The Debian packages of
CERNLIB have been altered to use shared libraries.  In some cases this may
cause unexpected compilation failure of user programs linking against them,
since the linker is more strict about what it will accept in DLLs than in
static code.  Please file a bug report on the appropriate library package in
any such case.

Since the CERNLIB libraries were not written with the intent of having them be
shared, some of them may have bugs when linked against dynamically, especially
on 64-bit architectures.  In particular, see the README.Debian file for the
libpawlib2-dev package and the file README.64-bit in this directory.
So when linking your own programs against CERN libraries, you may want to use
the -static compiler flag.  (The 'cernlib' script in the cernlib-base-dev
package will currently do this for you automatically unless you give cernlib
the -dy or -safe flag.)

Because of the problems with making the CERN libraries shared on 64-bit
platforms, the paw and paw++ packages available on those platforms have been
statically linked against CERN libraries.


3) Meeting the Filesystem Hierarchy Standard

The upstream authors of CERNLIB have the CERN libraries and programs install
into a particular base directory $CERN_ROOT, usually /cern/<version> (where
<version> is either a year or one of {old,pro,dev}).  Below that are the
subdirectories bin, lib, and shlib (among others).  For the Debian packaging,
in order to comply with Debian policy and the FHS, everything has been moved.
(The FHS specification may be found in the debian-policy package if you are
interested.)

The programs in $CERN_ROOT/bin have been placed into /usr/bin and /usr/sbin;
static libraries in $CERN_ROOT/lib and shared libraries (which upstream does
not generate) have been put into /usr/lib; data files in $CERN_ROOT/lib have
been moved to /usr/share/<packagename>; header files have been moved to
/usr/include or a subdirectory thereof; documentation has been moved to
/usr/share/doc/<packagename>.  CERNLIB programs have been altered for Debian to
accommodate these changes, when necessary.

Some third-party programs that use CERNLIB may rely on the environment
variables $CERN, $CERN_LEVEL, etc.  For compatibility with the file layout in
Debian packages, you may set these (in .bashrc or .tcshrc, for instance) to
have the following values:

	bash, sh, zsh, ksh, etc.	csh, tcsh
	------------------------	---------
	export CERN=/usr		setenv CERN /usr
	export CERN_LEVEL=.		setenv CERN_LEVEL .
	export CERN_ROOT=/usr		setenv CERN_ROOT /usr


If a third-party piece of software is particularly poorly written and even this
does not help, you may try running the script

	/usr/share/doc/cernlib-base/examples/install-cernlib-dirs.sh

as root.  This script will violate the FHS by creating a top-level /cern
directory and putting symlinks in it that point to the appropriate places in
the file hierarchy (for instance, /cern/2006deb/lib -> /usr/lib).  If you do
not already have existing directories or symlinks named /cern/dev, /cern/pro,
/cern/old, or /cern/2006, the script will also create them as symlinks pointing
to /cern/2006deb, for compatibility.  You may then, for instance, set the
above environment variables as

	CERN=/cern
	CERN_LEVEL=2006
	CERN_ROOT="$CERN/$CERN_LEVEL"

It is possible to run the script while already having another version of
CERNLIB installed under /cern/<whatever>, as long as "whatever" is not
"2006deb".  However, I make ABSOLUTELY NO GUARANTEES OR WARRANTY about the
safety of running the script; use it AT YOUR OWN RISK.  It is quite possible
that there are corner cases I haven't thought of that will cause it to
overwrite existing data.

Once the script has been run, you may notice dead symlinks in the directory
/cern/2006deb/include.  This is to be expected if you have not installed every
single cernlib -dev package.  (If the script pruned dead symlinks, you might
run it, then later install another -dev package and find that the symlink to
the headers of that package did not exist.)

If you want to put the cern directory skeleton somewhere other than /cern
(for instance, /opt/cern), give it an optional argument specifying the desired
target: e.g., to create /opt/cern, run

	./install-cernlib-dirs.sh /opt

[In this example and the rest of this section, we assume your current working
directory is /usr/share/doc/cernlib-base/examples.]

If you have run the script and later decide you want to undo its effects, you
may run it with the --uninstall argument:

	./install-cernlib-dirs.sh --uninstall

To uninstall cern directories from a location other than /cern, give an
optional directory argument.  Thus, to uninstall /opt/cern, run

	./install-cernlib-dirs.sh --uninstall /opt

Note that the uninstall routine will not remove any directories above "cern"
that the install routine created.  That is, if /opt did not originally exist,
the above command will nevertheless not remove it. 

Should you wish to create or uninstall a skeleton CERNLIB directory with a
value of $CERN_LEVEL other than 2006, you may request a specific value
with the --year flag.  For instance, to uninstall a skeleton /cern directory
that was originally created with CERN_LEVEL 2005, you could run

	./install-cernlib-dirs.sh --year 2005 --uninstall

Again, I make ABSOLUTELY NO GUARANTEES OR WARRANTY about the safety of running
the script in any manner.  It is quite possible that there are corner cases I
haven't thought of that will cause it to delete existing data.


4) Mixing Debian and CERN versions of CERNLIB

You can still use Debian's cernlib script (see the man page for cernlib(1) in
the cernlib-base-dev package) to link libraries from an upstream version of 
CERNLIB.  Assuming that you have a non-Debian CERNLIB installation in
/opt/cern/2006 for instance, you would first define $CERN appropriately:
	export CERN=/opt/cern
then call the cernlib script with the appropriate version number:
	gfortran -o myprogram myprogram.F `cernlib -v 2006 library1 library2`
I have not tested this, so file a bug if there are problems.

You should be aware that the version of the kuesvr "edit server" binary
provided by Debian has command-line flags that are incompatible with those of
the version provided by CERN.  It was necessary to introduce this
incompatibility for security reasons.  For this reason, and in conformance with
Debian Policy, Debian's kuesvr is installed in /usr/lib/libpacklib1/, outside
of $PATH, where only Debian's version of libpacklib can find it.  If you have
the libpacklib1-gfortran package installed, see "man 1 kuesvr" for more
information.


5) Removal of non-free code

Unfortunately not all of CERNLIB is under the same license.  Although CERN has
put CERNLIB under the GPL, some pieces of source code still state that they are
licensed by other entities.  Much non-free code, code with ambiguous licensing,
and GPL-incompatible code has been replaced or removed from the upstream
source in order to permit CERNLIB packages to be in the main Debian archive.
The copyright file in this directory and the README.Debian files for individual
packages (particularly, the montecarlo-base package) are more specific.  A
complete list of removed files may be found in the file

	/usr/share/doc/cernlib-base/deadpool.txt
	
(or in the source package, in cernlib-<version>/debian/deadpool.txt).

-- Kevin McCarty <kmccarty@debian.org>, Wed,  8 Aug 2007