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
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.
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
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.)
29 ----------------------------------------------------------------------
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
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 You must use version 2.06 (or later). If the path does not
65 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.
68 --enable-gzip : enable support for gzipped LHE file reading
69 --with-boost=path see GZIP SUPPORT section below for
70 --with-zlib=path further details
71 There also are a few environment variables that you can set to
72 force the configuration process or add flags:
73 USRCXXFLAGS : to add flags. Use this variable to add -fPIC to the
74 compilation flags for the static libraries
75 USRLDFLAGSSHARED : to add flags to the shared library build command
76 USRSHAREDSUFFIX : to force shared libraries suffix to be like this
77 (default on MacOSX is dylib).
79 1.2) If you want to use the external HepMC from some different location,
80 or it is more convenient to put the paths directly into the script,
81 then you have to edit the "configure" file by hand before you run
82 it. Search in the "configure" file for
84 and provide the paths where you have the respective libraries
85 installed on your local platform.
87 Information on the selected paths is stored in the files config.mk,
88 examples/config.sh and examples/config.csh when you run "./configure".
90 1.3) The CC and FC global environment variables can be set to specify
91 the C++ and Fortran 77/90 compilers, otherwise set in
92 <code>configure</code> and <code>examples/configure</code>.
94 2) If you want to change the version of HepMC, you have to
95 rerun the script "configure" with relevant options, then type "make"
96 to recompile the library hepmcinterface. If you tried already to run
97 examples with previous versions, pay attention to the environment
98 variable LD_LIBRARY_PATH (see README in examples).
100 Hints on how to install HepMC from scratch can be found in the
101 separate README.HepMC file.
103 3) If you have two CPUs or cores on your computer then using the -j2
104 option on make/gmake may speed up compilation.
106 4) Necessary data are automatically loaded when you use the default
107 PYTHIA installation directory structure and run the main programs in
108 the examples subdirectory. However, in the general case, you must
109 provide the path to the .xml files, originally stored in the xmldoc
110 directory, where default settings and particle data are found. This
111 can be done in two ways.
113 4.1) You can set the environment variable PYTHIA8DATA to contain the
114 location of the xmldoc directory. In the csh and tcsh shells this
116 setenv PYTHIA8DATA /home/myname/pythia81xx/xmldoc
117 while in other shells it could be
118 export PYTHIA8DATA=/home/myname/pythia81xx/xmldoc
119 where xx is the subversion number.
120 Recall that environment variables set locally are only defined in
121 the current instance of the shell. The above lines should go into
122 your .cshrc and .bashrc files, respectively, if you want a more
123 permanent assignment.
125 4.2) You can provide the path as argument to the Pythia constructor in
126 your main program, e.g.
127 Pythia pythia("/home/myname/pythia81xx/xmldoc");
128 where again xx is the subversion number.
130 When PYTHIA8DATA is set it takes precedence, else the path in the
131 constructor is used, else one defaults to the ../xmldoc directory.
133 ----------------------------------------------------------------------
135 GZIP SUPPORT (experimental)
137 The '--enable-gzip' options turns on support for the reading of
138 gzipped LHE files. It relies upon Boost and zlib to function, and
139 the locations of these must be set with the '--with-boost=boost_path'
140 and '--with-zlib=zlib_path' options. Specifically, it requires (note
141 that .so should be replaced with .dylib for Mac OS X):
142 boost_path/include/boost/iostreams/ (with the appropriate files
144 boost_path/lib/libboost_iostreams.so (or boost_path/lib64/...)
147 Note that when compiling a final PYTHIA executable, these libraries
148 must also be included, e.g.:
149 -Lboost_path/lib -lboost_iostreams -Lzlib_path -lz
150 This is done automatically for the examples in the 'examples' and
151 'rootexamples' directories when gzip support is enabled.
153 When running the executable, if the Boost and zlib libraries are
154 in a non-standard directory, the LD_LIBRARY_PATH (DYLD_LIBRARY_PATH
155 for Mac OS X) must be set to include these directories, e.g. in a
157 export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:boost_path/lib:zlib_path
159 Gzip support currently switches off the '-Wshadow' compiler option
160 to avoid the possibility of a large number of warning messages.
162 ----------------------------------------------------------------------
166 The Makefile.msc file is intended for use on Win32/NMAKE systems with
167 the Microsoft Visual C/C++ compiler. This alternative installation
168 is not the development platform, however, and therefore not as well
169 tested. Not all parts of the above installation procedure are the same,
170 so some experimentation may be required. A few suggestions are found
171 in the the separate README.Win32 file.
173 ----------------------------------------------------------------------
177 To learn more about the current program:
179 A) A brief self-contained introduction is found in the
180 htmldoc/pythia8100.pdf file.
182 B) Details can be found by opening a web browser on the
183 htmldoc/Welcome.html file, and then navigating among the pages
186 ----------------------------------------------------------------------