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

   INSTALLATION - BASIC

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
   Makefile.inc.  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.)

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

   INSTALLATION - ADVANCED OPTIONS

1) If you want to set various compilation options, the following two options
   are available.

1.1) You can use command-line arguments to the configure script for
     finer grain control of the installation. A full description of
     the options is given by running "configure --help". Here additional
     clarification is provided.
     --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-optdebug : turns on debugging flags but allow optimization.
     --lcg=PLATFORM : allows you to specify the platform assumed for
         compilation, which also affects the assumed location of the
         libraries below; default is x86_64-slc5-gcc43-opt while other
         supported values for name include slc4_ia32_gcc34,
         slc4_amd64_gcc34 and slc3_ia32_gcc323 (deprecated).
     --prefix=DIR : absolute path to a directory where the "bin",
         "lib", "include", and "share" directories will be copied, by
         a "gmake install" command subsequent to the "gmake" one.
         Note that the files in the current working directory are
         kept.
     --prefix-COMPONENT=DIR : finer grain control over where the "bin",
         "lib", "include", and "share" directories are copied for
         installation.
     --arch=ARCH : sets the architecture to be used. The two options
         are either "Darwin" for OS X, or "Linux" for other *nix
         platforms. The architecture is used to set automatically the
         "--cxx-shared", "--cxx-soname", and "--lib-suffix" flags but
         otherwise has no effect.
     --cxx=COMPILER : the compiler to be used. Currently PYTHIA 8 has
         been successfully compiled with GCC and LLVM
         (i.e. CLANG). Most systems will by default have "g++" aliased
         or linked to the appropriate compiler for your program.
     --cxx-common="FLAGS" : the flags that are passed for all
         compilation statements. This is equivalent to the GNU
         configuration variable CXXFLAGS, which is not supported here.
     --cxx-shared="FLAGS" : the flags that are passed when building
         shared dynamic libraries.
     --cxx-soname="FLAGS" : these flags are passed to the linker when
         setting the shared library names. Normally this should not
         need to be changed.
     --lib-suffix=SUF : the shared library suffix to use. This only
         effects the name of "lib/libpythia8.SUF". Typically for *nix
         systems this is ".so" and for OS X this is ".dylib". Note
         that all plugin libraries, including the Python interface,
         are always built with the ".so" suffix.
     --obj-common="FLAGS" : add a common compiler flag to object 
         compilation only (ie. .o files and not linking).

1.2) All of the options listed above are formatted into
     "Makefile.inc", which is also copied to
     "examples/Makefile.inc" whenever "gmake" is run and
     a change has been made. The "Makefile.inc" file can be simply
     modified to change any of these options after "configure" is
     run. Each option corresponds to a variable in this file as
     follows: "--option-foo-bar" is translated to "OPTION_FOO_BAR".

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

3) 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.

3.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/share/Pythia8/xmldoc
     while in other shells it could be
       export PYTHIA8DATA=/home/myname/pythia81xx/share/Pythia8/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.

3.2) You can provide the path as argument to the Pythia constructor in
     your main program, e.g.
       Pythia pythia("/home/myname/pythia81xx/share/Pythia8/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
   $PREFIX/share/Pythia8/xmldoc directory, where $PREFIX is defined by
   the --prefix configuration flag. By default, this is just the top
   level directory of the PYTHIA distribution. This final option is
   what is typically used when you run the examples/mainNN programs.

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

   INSTALLATION - EXTERNAL PACKAGES

1) PYTHIA 8 is designed to run out-of-the-box without any external
   package dependencies. However, a variety of interfaces to external
   packages is available. The building and linking to external
   interfaces can be controlled via the same two options as the
   advanced installation options.

1.1) Command-line arguments can be passed to "configure" using the
     arguments that begin with "--with". When an external package
     interface is enabled, "configure" takes the following steps.
     a) It looks for the necessary binaries, headers, and libraries
        that are needed for the external package. If no paths for the
        package have been defined it looks along the default paths for
        the system. If a configure script for the package is
        available, "configure" attempts to use the script to find the
        necessary files. If it can not find the necessary files, it
        disables the external package and issues a warning as to why.
     b) It looks for any external packages that this package might
        require, and enables them if needed. It then checks to see if
        these packages fulfill a). If not, it disables both packages.
     If any "--with-PACKAGE" option is passed to "configure" it will
     attempt to enable the package. For example, "--with-lhapdf6" will
     enable LHAPDF6, while "--with-lhapdf6-lib=/lib/foo" will also
     enable LHAPDF6. The available "--with" arguments are
     described by "./configure --help", but further details are given
     here.
     --with-PACKAGE=[DIR] : enables a package, and if "DIR" is
         provided, then looks for the package at this root path. For
         example, if the command "--with-lhapdf6=/foo/bar" is passed,
         then "configure" will look for the library LHAPDF along the
         path "/foo/bar/lib" and the LHAPDF headers along the path
         "/foo/bar/include".
     --with-PACKAGE-bin=DIR : specifies where to look for the package
         binaries, and will ignore the root path from
         "--with-PACKAGE=DIR" and the default system paths. This can
         be used for non-standard installations of packages, where the
         "bin", "lib", and "include" directories are scattered across
         the system. In the example "--with-lhapdf6=/foo
         --with-lhapdf6-bin=/foo/bar" the "configure" script will look
         for libraries and headers on the paths "/foo/lib" and
         "/foo/include", but the binaries on the path "/foo/bar" and
         not "/foo/bin".
     --with-PACKAGE-lib=DIR : same as above for bin, but now for
         libraries.
     --with-PACKAGE-include=DIR : same as above for bin, but now for
          headers.
     --with-PACKAGE-config=CFG  : for packages that provide a configure
         script, "CFG" specifies the configure script to use. For
         example, PYTHON is by default set with the configuration
         script "python-config". However, to use Python 3, "CFG" could
         be set to "python3-config".
     --with-PACKAGE-version=VER : is used when the "--lcg=PLATFORM"
         option is specified, and will cause "configure" to look for
         version "VER" of the package in the default LCG location.

1.2) All of the options above can also be set in "Makefile.inc" after
     "configure" has been run. For each package the variable
     "PACKAGE_USE" sets whether the package is used ("true" is used,
     while "false" is not). The variables "PACKAGE_BIN",
     "PACKAGE_INCLUDE", and "PACKAGE_LIB" then specify what paths are
     used when building, for the binaries, headers, and libraries,
     respectively.

2) A variety of external packages can be enabled, with details given here.
   EVTGEN) An external particle decayer designed specifically for B-decays,
       https://evtgen.hepforge.org/.
   FASTJET3) The industry standard package to build jets,
       http://fastjet.fr/. An interface to FastJet is provided in the
       "include/Pythia8Plugins/FastJet3.h" header and a variety of
       examples in "examples" link against the FastJet libraries.
   HEPMC2) An interface to the HepMC event record, version 2:
       http://lcgapp.cern.ch/project/simu/HepMC/. The interface
       between PYTHIA 8 and HepMC is provided via the
       "include/Pythia8Plugins/HepMC2.h" header.
   HEPMC3) An interface to the HepMC event record, version 3:
       https://hepmc.web.cern.ch/hepmc/. The interface
       between PYTHIA 8 and HepMC is provided via the
       "include/Pythia8Plugins/HepMC3.h" header.
   LHAPDF6) The modern C++ version of LHAPDF,
       http://lhapdf.hepforge.org/. Because PDF sets are an integral
       part of PYTHIA 8, the LHAPDF interface is handled differently
       than for the other external packages. If LHAPDF5 support is
       enabled, then the shared library "lib/pythia8lhapdf5.so" is
       built (even for OS X systems because this library is not used
       for linking). This library is NOT linked with PYTHIA, but
       rather is dynamically loaded at runtime. Consequently, PYTHIA
       is no longer linked against LHAPDF, but rather attempts to load
       it at runtime if an LHAPDF set is requested. Note that the
       plugin library "pythia8lhapdf5.so" must exist along the current
       library load path. This can be set by the environment variable
       "LD_LIBRARY_PATH" or at compile time using the "--Wl,-rpath"
       linker flag. Versions earlier than 6.2 require BOOST and are
       not supported.
   POWHEG) Next-to-leading order matrix element generators,
       http://powhegbox.mib.infn.it, available for a number of
       processes. These MEs are written in FORTRAN, but a plugin-style
       interface is provided for PYTHIA. To link against these MEs,
       they must be build both as binaries and libraries. See
       "examples/main33.cc" for more details on how to modify the
       POWHEGBOX make structure accordingly.
   RIVET) A toolkit for comparing MC and data,
        https://rivet.hepforge.org/, used in "examples/main93.cc" and
       "examples/main111.cc". The RIVET package requires FASTJET3,
       HEPMC2, and YODA.
   ROOT) The ROOT HEP package used for data analysis and
       visualization, http://root.cern.ch. This package is only used
       for the "examples/main9[1,2].cc" examples and is optional for
       "examples/main93.cc".
   GZIP) Support for the reading of gzipped LHE files. It relies upon
       zlib to function. The "--with-gzip=PATH" provides the location
       for "zlib.h" and "libz.[so,dylib]". Note that when compiling a
       final PYTHIA executable, the zlib library must also be
       included, e.g.: "-lz". This is done automatically for the
       examples in "examples/" when GZIP support is enabled.
   PYTHON) Provides a Python interface to Pythia. To build this interface,
       the Python system header "Python.h" must be
       available. Typically this can be found under
       "/usr/include/pythonX.Y". If "python-config" is available, the
       location of this header is determined automatically, otherwise
       the user will typically need to explicitly set the include path
       with "--with-python-include=/usr/include/pythonX.Y" or
       something similar. The interface works both with Python 2 and
       3.
    MG5MES) Matrix elements automatically generated by MadGraph5 that are
       interfaced to both the Dire and Vincia parton showers.
    OPENMP) Enable multi-processing via the OpenMP libraries. Used in some
       examples.
    MPICH) Enable multi-threading support via the MPICH implementation of
       MPI. Needed for HDF5 Les Houches event reader.
    HDF5) High-performance data management libraries and file format used for
       reading HDF5 Les Houches files. 
    HighFive) HighFive headers, also needed for reading HDF5 Les Houches
       files. Currently, v2.2 is supported and is available at
       https://github.com/BlueBrain/HighFive/tree/v2.2. This can be
       downloaded on most platforms as:
         curl -OL https://github.com/BlueBrain/HighFive/archive/v2.2.zip \
           && unzip v2.2.zip && mv HighFive-2.2/include/highfive . \
           && rm -r HighFive-2.2/ && rm v2.2.zip
    
----------------------------------------------------------------------

   COMPILING PROGRAMS AGAINST PYTHIA 8

Generally compiling programs against the PYTHIA 8 libraries requires
that the PYTHIA 8 header and library directories be specified via the
usual -I and -L compiler flags, and that at least the -lpythia8 option
be provided to link against the PYTHIA 8 library.

Extra compiler flags will be needed if you are making use of PYTHIA 8's
external package features. To make this simpler,
and so that an identical compilation recipe can be used with different
builds of PYTHIA (e.g. for inclusion in shared Makefiles), a pythia8-config
script is installed into PREFIX_BIN/bin by the "make install" build
target. A typical usage of this script is as follows:

g++ myprog.cc -o myprog `pythia8-config --cppflags --libs`

The --cppflags option to this script makes pythia8-config write out
the necessary -I flags corresponding to the installed headers, and
--libs adds the required -L and -l flags.

The pythia8-config script may also be used at runtime to generate the
data directory environment variable if needed, e.g.:

PYTHIA8DATA=`pythia8-config --xmldoc` ./myprog

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

   FOR WINDOWS USERS

PYTHIA 8 is primarily intended to be run in a Unix-based environment,
such as Linux or Mac OS X. Unfortunately it is not currently supported
for Windows platforms. If you want to experiment, and do not have the
knowledge to set everything up from scratch yourself, we are aware of
three possible approaches to take.

1) Install Linux in a Virtual Machine (VM) on your Windows system,
and then work within this virtual environment as on any regular
Linux platform. You could e.g. download the VirtualBox
    https://www.virtualbox.org/
and install either Ubuntu or CernVM (Scientific Linux)
    http://cernvm.cern.ch/
on it. Make sure your installation includes the g++ compiler.

2) Install the Cygwin package, intended to allow Linux apps to run
under Windows, see
    https://www.cygwin.com/
Be sure to install the Dev tools, which appears in the list of options
to include, but won't be installed by default. Then put the Pythia
folder in the Cygwin/home directory, and compile and work with it
as usual. (The include/Pythia8Plugins/execinfo.h file provides dummy
versions of methods needed for proper compilation.)

3) The nuget.org website
    http://www.nuget.org/packages/Pythia8/
contains pre-built PYTHIA packages ready to be used under Windows
Visual Studio.

We take no responsibility for either of these solutions.
Also note that linking with other libraries may involve further
problems, in particular for the dynamic loading of LHAPDF.

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

   LEARN MORE

To learn more about the current program:

A) A brief self-contained introduction is found in the
   share/Pythia8/pdfdoc/pythia8200.pdf file.

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

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