source: trunk/environments/g4py/00README

$Id: 00README,v 1.12 2009/11/20 03:36:51 kmura Exp $
==========================================================================
Geant4Py

  Geant4Py is a set of python modules for using Geant4.

==========================================================================

URL
---
http://www-geant4.kek.jp/projects/Geant4Py/


System Requirements:
-------------------
Python
  - only 2.x is tested.

Geant4
  - 8.0 or later
  - should be built in "GLOBAL" and "SHARED" libraries.
  - All header files should be collected into $(G4INSTALL)/include
    by "make includes"

CLHEP
  - 1.9.1.1 or later
  - should be built in shared library.
  - Building shared objects is supported since version 1.9.

(Optional)
ROOT

Before Starting:
----------------
In dafault situation, Geant4 creates and uses "granular static libraries".
But, the Python interface requires "GLOBAL SHARED library".
If you donot build your Geant4 libraries in global shared mode, 
you have to recreate your instance additionally.

In "tools" directory, you can find some ways to handle both "glanular static"
and "global shared" environments. Please take a look.


How to Install:
---------------
There is a configuraton script for building the package.

# ./configure --help
`configure' configures Geant4Py to adapt to many kinds of systems.

Usage:  ./configure SYSTEM [OPTION]... [VAR=VALUE]...

SYSTEM: System type (see Supported Arhitectures)

Options:
  -h, --help                Display this help and exit

Installation directories:
  --prefix=PREFIX           Installation prefix  [./]
  --libdir=DIR              Python modules dir [PREFIX/lib]

Fine tuning of the library path:
  --with-g4-incdir=DIR      Geant4 header dir [$G4INCLUDE]
  --with-g4-libdir=DIR      Geant4 library dir [$G4LIB/$G4SYSTEM]
  --with-clhep-incdir=DIR   CLHEP header dir [$CLHEP_INCLUDE_DIR]
  --with-clhep-libdir=DIR   CLHEP library dir [$CLHEP_LIB_DIR]
  --with-clhep-lib=LIB      library name of libCLHEP.so [CLHEP|$CLHEP_LIB]

  --with-python-incdir=DIR  Python header dir [/usr/include/python(2.#)],
                            (location of pyconfig.h)
  --with-python-libdir=DIR  Python library dir [/usr/lib(64)]

  --with-boost-incdir=DIR   BOOST-C++ header dir [/usr/include],
                            (location of boost/)
  --with-boost-libdir=DIR   BOOST-C++ library dir [/usr/lib]
  --with-boost-python-lib=LIB library name of libboost_python.so [boost_python]

  --with-package-dir=DIR    Geant4 Package dir

  --with-extra-dir=DIR      Install path for extra packages [/usr/local]

  --with-xercesc-incdir=DIR Xerces-C header dir [/usr/include]
  --with-xercesc-libdir=DIR Xerces-C library dir [/usr/lib(64)]

Enable/disable options: prefix with either --enable- or --disable-
  openglx      OpenGLX support    [auto]
  openglxm     OpenGLXm support   [disable, $G4VIS_USE_OPENGLXM]
  raytracerx   RayTracerX support [disable, $G4VIS_USE_RAYTRACERX]

Supported Architectures:
  linux           for Linux gcc 3.x and 4.x (32bit)
  linux64         for Linux gcc 3.x and 4.x (64bit, alias to linuxx8664gcc)
  linuxx8664gcc   for AMD Opteron and Intel EM64T Linux gcc 3.x and 4.x
  macosx          for MacOSX with gcc (Tiger/Leopard and Xcode)

You can specify all parameters adopting your environment.

For example,
# ./configure linux64  (miserable)
  --with-g4-incdir=/opt/heplib/Geant4/geant4.8.1/include 
  --with-g4-libdir=/opt/heplib/Geant4/geant4.8.1/slib/Linux-g++ 
  --with-clhep-incdir=/opt/heplib/CLHEP/2.0.2.2/include 
  --with-clhep-libdir=/opt/heplib/CLHEP/2.0.2.2/lib 
  --with-clhep-lib=CLHEP-2.0.2.2

# ./configure linux64  (smart)
  --with-package-dir=/opt/heplib/Geant4/packages/9.1.2

# ./confugre linux64 (intelligent or haphazard ?)

The configuration script will create config/config.gmk, which describes 
your envrionment.

After executing the configure script, then 

# make
# make install

That's all!

How to Use:
-----------
Some environment variables are required at run time.

* PYTHONPATH
Python module search directories, given by a colon-separated list 
of directories. 
Practically, $(INSTALL_PATH)/lib is ok.

* LD_LIBRARY_PATH
Additional shared library path to be searched.

Some libraries paths are already specified via "-rpath" linker option, 
so these paths do not have to be added to "LD_LIBRARY_PATH".
 * Geant4
 * CLHEP
 * boost-python library
 * $(INSTALL_PATH)/lib
 * $(G4PY_EXLIB_LIBDIR) specified in a module makefile.


You can import Geant4Py modules in Python just like

>>> import Geant4

Notes:
-----
1) >> IMPORTANT <<
All users' libraries should be build in SHARED libaries.

2) Development Environment:
OS:             SuSE Linux 11.1 (x86-64)
g++ :           4.3.2
Python:         2.6
CLHEP:          2.0.4.4
ROOT:           5.20/00

3) Tested environment:
  Linux 32/64-bit
  SuSE 11.2 11.1 
  SL4.5 SL5.4
  Ubuntu 8.0.4
  MacOSX 10.5 (Leopard) 10.6 (Snow Leopard)

Have A Fun!!

Koichi Murakami <Koichi.Murakami@kek.jp>