[u/mrichter/AliRoot.git] / PYTHIA8 / pythia8145 / README


   BASIC INSTALLATION

1) Once you have unpacked your tarball into a new (sub)directory,
   the first step is to run the "configure" script. If you accept the 
   default compiler options, and plan to run PYTHIA 8 standalone, you 
   only have to type "./configure". This will create the file config.mk. 
   Actually, running this script by hand is optional since "make" will 
   run "configure" anyway, but possible errors in the paths will be 
   less clearly visible.

2) Type "gmake" or "make". This will create an archive library. 
   On Linux systems gmake and make are usually equivalent. For others, 
   in case of doubt, use gmake. This applies below as well.

3) The library should now be ready for use. To study some examples,
   go to the "examples" subdirectory. The README file in that 
   subdirectory contain further instructions how executables can 
   be built and run.
    
4) At any time, typing "gmake clean" will remove all files related to
   the library compilation, including the library itself, but it will
   not reset the configure selections. With "gmake distclean" additionally
   the configure selection is reset, and many other temporary files are
   removed. Output files you may have created during your test runs are
   not affected. (A "gmake clean" is also available in the examples 
   subdirectory, see the README there.) 

----------------------------------------------------------------------

   ADVANCED INSTALLATION

1) If you want to set various compilation options, or prepare the 
   linking to the HepMC external library then the "configure" script 
   will have to do more work. There are two different ways to 
   accomplish this.

1.1)  You can use command-line arguments to set up the desired library 
     links. The possible options are:
     --help : prints a brief summary of the options described here.
     --enable-debug : turns on debugging flags and turns off optimization.
         (This makes program execution much slower. If you later want to 
         switch optimization back on you have to rerun configure without
         this option, since default is to allow optimization.)
     --enable-shared : turns on shared-library creation,
         in addition to the archive libraries always built.
     --enable-64bits : turns on 64 bits compilation flag
         (is automatic on many 64-bit installations, but just in case).
     --lcgplatform=name : allows you to specify the platform assumed for
         compilation, which also affects the assumed location of the 
         libraries below; default is slc4_ia32_gcc34 while other supported
         values for name include slc4_amd64_gcc34 and slc3_ia32_gcc323
         (deprecated). 
     --with-hepmc=path : the path to your local copy of the HepMC library.
         Please note that HepMC version 1 is no more supported. If the path
         does not contain the version number you will be warned about it.    
     --with-hepmcversion=v : a simpler alternative to the above, valid 
         if you are using the CERN AFS LCG external area. See the HepMC
         WEB site for the information about the versions currently
         "in production"
     There also are a few environment variables that you can set to 
     force the configuration process or add flags:
     USRCXXFLAGS : to add flags. Use this variable to add -fPIC to the 
         compilation flags for the static libraries
     USRLDFLAGSSHARED : to add flags to the shared library build command
     USRSHAREDSUFFIX : to force shared libraries suffix to be like this 
         (default on MacOSX is dylib).

1.2) If you want to use the external HepMC from some different location, 
     or it is more convenient to put the paths directly into the script,
     then you have to edit the "configure" file by hand before you run 
     it. Search in the "configure" file for
       HEPMCLOCATION
     and provide the paths where you have the respective libraries
     installed on your local platform.

   Information on the selected paths is stored in the files config.mk,
   examples/config.sh and examples/config.csh when you run "./configure".

2) If you want to change the version of HepMC, you have to
   rerun the script "configure" with relevant options, then type "make" 
   to recompile the library hepmcinterface. If you tried already to run 
   examples with previous versions, pay attention to the environment 
   variable LD_LIBRARY_PATH (see README in examples).

   Hints on how to install HepMC from scratch can be found in the
   separate README.HepMC file.

3) If you have two CPUs or cores on your computer then using the -j2 
   option on make/gmake may speed up compilation.

4) Necessary data are automatically loaded when you use the default 
   PYTHIA installation directory structure and run the main programs in 
   the examples subdirectory. However, in the general case, you must 
   provide the path to the .xml files, originally stored in the xmldoc 
   directory, where default settings and particle data are found. This 
   can be done in two ways.

4.1) You can set the environment variable PYTHIA8DATA to contain the 
     location of the xmldoc directory. In the csh and tcsh shells this 
     could e.g. be
       setenv PYTHIA8DATA /home/myname/pythia81xx/xmldoc
     while in other shells it could be
       export PYTHIA8DATA=/home/myname/pythia81xx/xmldoc
     where xx is the subversion number.
     Recall that environment variables set locally are only defined in 
     the current instance of the shell. The above lines should go into 
     your .cshrc and .bashrc files, respectively, if you want a more 
     permanent assignment.

4.2) You can provide the path as argument to the Pythia constructor in 
     your main program, e.g.
       Pythia pythia("/home/myname/pythia81xx/xmldoc");
     where again xx is the subversion number.

   When PYTHIA8DATA is set it takes precedence, else the path in the 
   constructor is used, else one defaults to the ../xmldoc directory.

----------------------------------------------------------------------

   FOR WINDOWS USERS

The Makefile.msc file is intended for use on Win32/NMAKE systems with 
the  Microsoft Visual C/C++ compiler. This alternative installation
is not the development platform, however, and therefore not as well 
tested. Not all parts of the above installation procedure are the same,
so some experimentation may be required. A few suggestions are found 
in the the separate README.Win32 file.    

----------------------------------------------------------------------

   LEARN MORE

To learn more about the current program:

A) A brief self-contained introduction is found in the 
   htmldoc/pythia8100.pdf file.

B) Details can be found by opening a web browser on the 
   htmldoc/Welcome.html file, and then navigating among the pages 
   in the index there.   

----------------------------------------------------------------------
Commit	Line	Data
9419eeef	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 slc4_ia32_gcc34 while other supported
	52	values for name include slc4_amd64_gcc34 and slc3_ia32_gcc323
	53	(deprecated).
	54	--with-hepmc=path : the path to your local copy of the HepMC library.
	55	Please note that HepMC version 1 is no more supported. If the path
	56	does not contain the version number you will be warned about it.
	57	--with-hepmcversion=v : a simpler alternative to the above, valid
	58	if you are using the CERN AFS LCG external area. See the HepMC
	59	WEB site for the information about the versions currently
	60	"in production"
	61	There also are a few environment variables that you can set to
	62	force the configuration process or add flags:
	63	USRCXXFLAGS : to add flags. Use this variable to add -fPIC to the
	64	compilation flags for the static libraries
65	USRLDFLAGSSHARED : to add flags to the shared library build command
66	USRSHAREDSUFFIX : to force shared libraries suffix to be like this
67	(default on MacOSX is dylib).
68
69	1.2) If you want to use the external HepMC from some different location,
70	or it is more convenient to put the paths directly into the script,
71	then you have to edit the "configure" file by hand before you run
72	it. Search in the "configure" file for
73	HEPMCLOCATION
74	and provide the paths where you have the respective libraries
75	installed on your local platform.
76
77	Information on the selected paths is stored in the files config.mk,
78	examples/config.sh and examples/config.csh when you run "./configure".
79
80	2) If you want to change the version of HepMC, you have to
81	rerun the script "configure" with relevant options, then type "make"
82	to recompile the library hepmcinterface. If you tried already to run
83	examples with previous versions, pay attention to the environment
84	variable LD_LIBRARY_PATH (see README in examples).
85
86	Hints on how to install HepMC from scratch can be found in the
87	separate README.HepMC file.
88
89	3) If you have two CPUs or cores on your computer then using the -j2
90	option on make/gmake may speed up compilation.
91
92	4) Necessary data are automatically loaded when you use the default
93	PYTHIA installation directory structure and run the main programs in
94	the examples subdirectory. However, in the general case, you must
95	provide the path to the .xml files, originally stored in the xmldoc
96	directory, where default settings and particle data are found. This
97	can be done in two ways.
98
99	4.1) You can set the environment variable PYTHIA8DATA to contain the
100	location of the xmldoc directory. In the csh and tcsh shells this
101	could e.g. be
102	setenv PYTHIA8DATA /home/myname/pythia81xx/xmldoc
103	while in other shells it could be
104	export PYTHIA8DATA=/home/myname/pythia81xx/xmldoc
105	where xx is the subversion number.
106	Recall that environment variables set locally are only defined in
107	the current instance of the shell. The above lines should go into
108	your .cshrc and .bashrc files, respectively, if you want a more
109	permanent assignment.
110
111	4.2) You can provide the path as argument to the Pythia constructor in
112	your main program, e.g.
113	Pythia pythia("/home/myname/pythia81xx/xmldoc");
114	where again xx is the subversion number.
115
116	When PYTHIA8DATA is set it takes precedence, else the path in the
117	constructor is used, else one defaults to the ../xmldoc directory.
118
119	----------------------------------------------------------------------
120
121	FOR WINDOWS USERS
122
123	The Makefile.msc file is intended for use on Win32/NMAKE systems with
124	the Microsoft Visual C/C++ compiler. This alternative installation
125	is not the development platform, however, and therefore not as well
126	tested. Not all parts of the above installation procedure are the same,
127	so some experimentation may be required. A few suggestions are found
128	in the the separate README.Win32 file.
129
130	----------------------------------------------------------------------
131
132	LEARN MORE
133
134	To learn more about the current program:
135
136	A) A brief self-contained introduction is found in the
137	htmldoc/pythia8100.pdf file.
138
139	B) Details can be found by opening a web browser on the
140	htmldoc/Welcome.html file, and then navigating among the pages
141	in the index there.
142
143	----------------------------------------------------------------------