Merge branch 'master' of https://git.cern.ch/reps/AliRoot
[u/mrichter/AliRoot.git] / PYTHIA8 / pythia8170 / README
1
2    BASIC INSTALLATION
3
4 1) Once you have unpacked your tarball into a new (sub)directory,
5    the first step is to run the "configure" script. If you accept the 
6    default compiler options, and plan to run PYTHIA 8 standalone, you 
7    only have to type "./configure". This will create the file config.mk. 
8    Actually, running this script by hand is optional since "make" will 
9    run "configure" anyway, but possible errors in the paths will be 
10    less clearly visible.
11
12 2) Type "gmake" or "make". This will create an archive library. 
13    On Linux systems gmake and make are usually equivalent. For others, 
14    in case of doubt, use gmake. This applies below as well.
15
16 3) The library should now be ready for use. To study some examples,
17    go to the "examples" subdirectory. The README file in that 
18    subdirectory contain further instructions how executables can 
19    be built and run.
20     
21 4) At any time, typing "gmake clean" will remove all files related to
22    the library compilation, including the library itself, but it will
23    not reset the configure selections. With "gmake distclean" additionally
24    the configure selection is reset, and many other temporary files are
25    removed. Output files you may have created during your test runs are
26    not affected. (A "gmake clean" is also available in the examples 
27    subdirectory, see the README there.) 
28
29 ----------------------------------------------------------------------
30
31    ADVANCED INSTALLATION
32
33 1) If you want to set various compilation options, or prepare the 
34    linking to the HepMC external library then the "configure" script 
35    will have to do more work. There are two different ways to 
36    accomplish this.
37
38 1.1)  You can use command-line arguments to set up the desired library 
39      links. The possible options are:
40      --help : prints a brief summary of the options described here.
41      --enable-debug : turns on debugging flags and turns off optimization.
42          (This makes program execution much slower. If you later want to 
43          switch optimization back on you have to rerun configure without
44          this option, since default is to allow optimization.)
45      --enable-shared : turns on shared-library creation,
46          in addition to the archive libraries always built.
47      --enable-64bits : turns on 64 bits compilation flag
48          (is automatic on many 64-bit installations, but just in case).
49      --lcgplatform=name : allows you to specify the platform assumed for
50          compilation, which also affects the assumed location of the 
51          libraries below; default is x86_64-slc5-gcc43-opt while other 
52          supported values for name include slc4_ia32_gcc34, 
53          slc4_amd64_gcc34 and slc3_ia32_gcc323 (deprecated). 
54      --installdir=name : absolute path to a directory where the compiled
55          library and header file directories will be copied, by a 
56          "gmake install" command subsequent to the "gmake" one. 
57          Note that the files in the current working directory are kept. 
58      --prefix=name : equivalent alternative to --installdir=name.
59      --datadir=name : absolute path to a directory where the xmldoc
60          data directory will be copied, by a "gmake install" command 
61          subsequent to the "gmake" one. Defaults to the same as 
62          --installdir=name if not set separately.
63      --with-hepmc=path : the path to your local copy of the HepMC library.
64          Please note that HepMC version 1 is no more supported. If the path
65          does not contain the version number you will be warned about it.    
66      --with-hepmcversion=v : a simpler alternative to the above, valid 
67          if you are using the CERN AFS LCG external area. See the HepMC
68          web site for the information about the versions currently
69          "in production"
70      --enable-gzip     : enable support for gzipped LHE file reading
71      --with-boost=path   see GZIP SUPPORT section below for
72      --with-zlib=path    further details
73      There also are a few environment variables that you can set to 
74      force the configuration process or add flags:
75      USRCXXFLAGS : to add flags. Use this variable to add -fPIC to the 
76          compilation flags for the static libraries
77      USRLDFLAGSSHARED : to add flags to the shared library build command
78      USRSHAREDSUFFIX : to force shared libraries suffix to be like this 
79          (default on MacOSX is dylib).
80
81 1.2) If you want to use the external HepMC from some different location, 
82      or it is more convenient to put the paths directly into the script,
83      then you have to edit the "configure" file by hand before you run 
84      it. Search in the "configure" file for
85        HEPMCLOCATION
86      and provide the paths where you have the respective libraries
87      installed on your local platform.
88
89    Information on the selected paths is stored in the files config.mk,
90    examples/config.sh and examples/config.csh when you run "./configure".
91
92 2) If you want to change the version of HepMC, you have to
93    rerun the script "configure" with relevant options, then type "make" 
94    to recompile the library hepmcinterface. If you tried already to run 
95    examples with previous versions, pay attention to the environment 
96    variable LD_LIBRARY_PATH (see README in examples).
97
98    Hints on how to install HepMC from scratch can be found in the
99    separate README.HepMC file.
100
101 3) If you have two CPUs or cores on your computer then using the -j2 
102    option on make/gmake may speed up compilation.
103
104 4) Necessary data are automatically loaded when you use the default 
105    PYTHIA installation directory structure and run the main programs in 
106    the examples subdirectory. However, in the general case, you must 
107    provide the path to the .xml files, originally stored in the xmldoc 
108    directory, where default settings and particle data are found. This 
109    can be done in two ways.
110
111 4.1) You can set the environment variable PYTHIA8DATA to contain the 
112      location of the xmldoc directory. In the csh and tcsh shells this 
113      could e.g. be
114        setenv PYTHIA8DATA /home/myname/pythia81xx/xmldoc
115      while in other shells it could be
116        export PYTHIA8DATA=/home/myname/pythia81xx/xmldoc
117      where xx is the subversion number.
118      Recall that environment variables set locally are only defined in 
119      the current instance of the shell. The above lines should go into 
120      your .cshrc and .bashrc files, respectively, if you want a more 
121      permanent assignment.
122
123 4.2) You can provide the path as argument to the Pythia constructor in 
124      your main program, e.g.
125        Pythia pythia("/home/myname/pythia81xx/xmldoc");
126      where again xx is the subversion number.
127
128    When PYTHIA8DATA is set it takes precedence, else the path in the 
129    constructor is used, else one defaults to the ../xmldoc directory.
130
131 ----------------------------------------------------------------------
132
133    GZIP SUPPORT (experimental)
134
135 The '--enable-gzip' options turns on support for the reading of
136 gzipped LHE files. It relies upon Boost and zlib to function, and
137 the locations of these must be set with the '--with-boost=boost_path'
138 and '--with-zlib=zlib_path' options. Specifically, it requires (note
139 that .so should be replaced with .dylib for Mac OS X):
140   boost_path/include/boost/iostreams/ (with the appropriate files
141                                        in this directory)
142   boost_path/lib/libboost_iostreams.so (or boost_path/lib64/...)
143   zlib_path/libz.so
144
145 Note that when compiling a final PYTHIA executable, these libraries
146 must also be included, e.g.:
147   -Lboost_path/lib -lboost_iostreams -Lzlib_path -lz
148 This is done automatically for the examples in the 'examples' and
149 'rootexamples' directories when gzip support is enabled.
150
151 When running the executable, if the Boost and zlib libraries are
152 in a non-standard directory, the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH
153 for Mac OS X) must be set to include these directories, e.g. in a 
154 bash-type shell:
155   export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:boost_path/lib:zlib_path
156
157 Gzip support currently switches off the '-Wshadow' compiler option
158 to avoid the possibility of a large number of warning messages.
159
160 ----------------------------------------------------------------------
161
162    FOR WINDOWS USERS
163
164 The Makefile.msc file is intended for use on Win32/NMAKE systems with 
165 the  Microsoft Visual C/C++ compiler. This alternative installation
166 is not the development platform, however, and therefore not as well 
167 tested. Not all parts of the above installation procedure are the same,
168 so some experimentation may be required. A few suggestions are found 
169 in the the separate README.Win32 file.    
170
171 ----------------------------------------------------------------------
172
173    LEARN MORE
174
175 To learn more about the current program:
176
177 A) A brief self-contained introduction is found in the 
178    htmldoc/pythia8100.pdf file.
179
180 B) Details can be found by opening a web browser on the 
181    htmldoc/Welcome.html file, and then navigating among the pages 
182    in the index there.   
183
184 ----------------------------------------------------------------------